feat: add pinStatus api

src/client.ts

@@ -6,7 +6,7 @@ import {
     MetadataResult,
 } from "./options/download.js";
 
-import { addUrlQuery, ensureUrl } from "./utils/url.js";
+import {addUrlQuery, ensureUrl} from "./utils/url.js";
 
 import {
     CustomRegistryOptions,
@@ -14,16 +14,16 @@ import {
     DEFAULT_PUBLISH_ENTRY_OPTIONS,
     DEFAULT_SUBSCRIBE_ENTRY_OPTIONS,
 } from "./options/registry.js";
-import { CustomClientOptions, optionsToConfig } from "./utils/options.js";
+import {CustomClientOptions, optionsToConfig} from "./utils/options.js";
-import { throwValidationError } from "./utils/validation.js";
+import {throwValidationError} from "./utils/validation.js";
 import {
     AccountPinsResponse,
-  BasicUploadResponse,
+    BasicUploadResponse, deleteS5DeleteCid,
     getS5AccountPins,
     getS5BlobCid,
     getS5DownloadCid,
-  getS5MetadataCid,
+    getS5MetadataCid, getS5PinCidStatus,
-  getS5Registry,
+    getS5Registry, postS5PinCid,
     postS5Registry,
     postS5Upload,
     postS5UploadDirectory,
@@ -31,11 +31,11 @@ import {
     PostS5UploadResult,
 } from "./generated/index.js";
 import path from "path";
-import { customInstance } from "./axios.js";
+import {customInstance} from "./axios.js";
-import { ensureBytes, equalBytes } from "@noble/curves/abstract/utils";
+import {ensureBytes, equalBytes} from "@noble/curves/abstract/utils";
-import { concatBytes } from "@noble/hashes/utils";
+import {concatBytes} from "@noble/hashes/utils";
-import { CID_HASH_TYPES } from "@lumeweb/libs5";
+import {CID_HASH_TYPES} from "@lumeweb/libs5";
-import { buildRequestUrl } from "./request.js";
+import {buildRequestUrl} from "./request.js";
 import WS from "isomorphic-ws";
 import {
     CID,
@@ -50,8 +50,8 @@ import {
     signRegistryEntry,
     verifyRegistryEntry,
 } from "@lumeweb/libs5/lib/service/registry.js";
-import { Buffer } from "buffer";
+import {Buffer} from "buffer";
-import { AxiosError } from "axios";
+import {AxiosError} from "axios";
 import {
     CustomUploadOptions,
     DEFAULT_UPLOAD_OPTIONS,
@@ -64,11 +64,12 @@ import {
     Upload,
     UploadOptions,
 } from "tus-js-client";
-import { ensureFileObjectConsistency } from "./utils/file.js";
+import {ensureFileObjectConsistency} from "./utils/file.js";
 import defer from "p-defer";
-import { Multihash } from "@lumeweb/libs5/lib/multihash.js";
+import {Multihash} from "@lumeweb/libs5/lib/multihash.js";
-import { blake3 } from "@noble/hashes/blake3";
+import {blake3} from "@noble/hashes/blake3";
-import { base64urlDecode, base64urlEncode } from "./utils/encoding.js";
+import {base64urlDecode, base64urlEncode} from "./utils/encoding.js";
+import {CustomPinOptions, DEFAULT_PIN_OPTIONS} from "#options/pin.js";
 
 export class S5Error extends Error {
     public statusCode: number;
@@ -173,7 +174,7 @@ export class S5Client {
         cid: string,
         customOptions: CustomDownloadOptions = {},
     ): Promise<string> {
-    const opt = { ...this.clientOptions, customOptions };
+        const opt = {...this.clientOptions, customOptions};
         return addUrlQuery(path.join(this.portalUrl, cid), {
             auth_token: opt.apiKey,
         });
@@ -200,7 +201,7 @@ export class S5Client {
 
         const response = await getS5MetadataCid(cid, config);
 
-    return { metadata: response };
+        return {metadata: response};
     }
 
     /**
@@ -491,7 +492,7 @@ export class S5Client {
     ): Promise<UploadResult> {
         const response = await this.uploadSmallFileRequest(file, customOptions);
 
-    return { cid: CID.decode(<string>response.cid) };
+        return {cid: CID.decode(<string>response.cid)};
     }
 
     /* istanbul ignore next */
@@ -588,7 +589,7 @@ export class S5Client {
             customOptions,
         );
 
-    return { cid: CID.decode(<string>response.cid) };
+        return {cid: CID.decode(<string>response.cid)};
     }
 
     /**
@@ -639,7 +640,7 @@ export class S5Client {
     ): Promise<UploadResult> {
         const response = await this.uploadWebappRequest(directory, customOptions);
 
-    return { cid: CID.decode(<string>response.cid) };
+        return {cid: CID.decode(<string>response.cid)};
     }
 
     /**
@@ -704,7 +705,7 @@ export class S5Client {
                         return;
                     }
 
-          p.resolve({ cid });
+                    p.resolve({cid});
                 },
                 onError: (error: Error | DetailedError) => {
                     // Return error body rather than entire error.
@@ -727,4 +728,34 @@ export class S5Client {
 
         return p.promise;
     }
+
+    public async pin(cid: string, customOptions: CustomPinOptions = {}) {
+        const config = optionsToConfig(
+            this,
+            DEFAULT_PIN_OPTIONS,
+            customOptions,
+        );
+
+        await postS5PinCid(cid, config);
+    }
+
+    public async unpin(cid: string, customOptions: CustomPinOptions = {}) {
+        const config = optionsToConfig(
+            this,
+            DEFAULT_PIN_OPTIONS,
+            customOptions,
+        );
+
+        await deleteS5DeleteCid(cid, config);
+    }
+
+    public async pinStatus(cid: string, customOptions: CustomPinOptions = {}) {
+        const config = optionsToConfig(
+            this,
+            DEFAULT_PIN_OPTIONS,
+            customOptions,
+        );
+
+        return await getS5PinCidStatus(cid, config);
+    }
 }

src/options/pin.ts

@@ -0,0 +1,8 @@
+import {CustomClientOptions} from "#utils/options.js";
+import {ResponseType} from "axios";
+
+export type CustomPinOptions = CustomClientOptions & {
+
+};
+
+export const DEFAULT_PIN_OPTIONS = {};

swagger.yaml

@@ -679,6 +679,24 @@ paths:
             responses:
                 '204':
                     description: File pinned
+    /s5/pin/{cid}/status:
+        get:
+            summary: Retrieve pin status
+            tags:
+                - pin
+            parameters:
+                - name: cid
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                '200':
+                    description: Pin status
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/AccountPinStatusResponse'
     /s5/delete/{cid}:
         delete:
             summary: Delete a file. This will only unpin it from the account, and potentially delete it later if there are no more global pins.
@@ -923,6 +941,16 @@ components:
                     type: string
                 mime_type:
                     type: string
+        AccountPinStatusResponse:
+            type: object
+            required:
+                - status
+                - progress
+            properties:
+                status:
+                    type: string
+                progress:
+                    type: number
         RegistryQueryResponse:
             type: object
             properties: