@lumeweb/pinner 0.1.12 → 0.1.14

package/dist/esm/pinner.d.ts

@@ -14,6 +14,11 @@ declare class Pinner {
   private _ipns;
   private _websites;
   private _upload?;
+  private readonly auth;
+  /**
+   * Create a new Pinner SDK instance.
+   * @param config SDK configuration object
+   */
   constructor(config: PinnerConfig);
   /**
    * Access the remote pins interface.
@@ -37,6 +42,8 @@ declare class Pinner {
   /**
    * Upload a file and wait for completion.
    * Convenience method for simple use cases where controls aren't needed.
+   * @param file The file to upload
+   * @param options Upload configuration
    */
   uploadAndWait(file: File, options?: UploadOptions): Promise<UploadResult>;
   /**
@@ -48,39 +55,54 @@ declare class Pinner {
   waitForOperation(input: number | UploadResult, options?: OperationPollingOptions): Promise<UploadResult>;
   /**
    * Upload a directory to IPFS.
+   * @param files Array of files to upload as a directory
+   * @param options Upload configuration
    */
   uploadDirectory(files: File[], options?: UploadOptions): Promise<UploadOperation>;
   /**
    * Upload a CAR file without preprocessing.
    * This is useful for passthrough of pre-generated CAR files.
+   * @param file CAR file or stream to upload
+   * @param options Upload configuration
    */
   uploadCar(file: File | ReadableStream<Uint8Array>, options?: UploadOptions): Promise<UploadOperation>;
   /**
    * Pin existing content by CID.
+   * @param cid CID of content to pin (string or CID object)
+   * @param options Remote add options
    */
   pinByHash(cid: string | CID, options?: RemoteAddOptions): Promise<AsyncGenerator<CID, void, undefined>>;
   /**
    * List pinned content.
+   * @param options List filtering options
    */
   listPins(options?: RemoteLsOptions): Promise<RemotePin[]>;
   /**
    * Get pin status.
+   * @param cid CID of the pinned content to check
    */
   getPinStatus(cid: string | CID): Promise<RemotePin>;
   /**
    * Check if content is pinned.
+   * @param cid CID to check
    */
   isPinned(cid: string | CID): Promise<boolean>;
   /**
    * Update pin metadata.
+   * @param cid CID of the pin
+   * @param metadata Key-value metadata to set
    */
   setPinMetadata(cid: string | CID, metadata: Record<string, string> | undefined): Promise<void>;
   /**
    * Remove a pin. The block may be deleted when garbage collection is run.
+   * @param cid CID to unpin
+   * @param options Abort options
    */
   unpin(cid: string | CID, options?: AbortOptions): Promise<void>;
   /**
    * Remove a pin by request ID. The block may be deleted when garbage collection is run.
+   * @param requestId The request ID to remove
+   * @param options Abort options
    */
   unpinByRequestId(requestId: string, options?: AbortOptions): Promise<void>;
   /**

package/dist/esm/pinner.js

@@ -5,6 +5,7 @@ import { PinClient } from "./pin/client.js";
 import "./pin/index.js";
 import { IpnsClient } from "./api/ipns.js";
 import { WebsitesClient } from "./api/websites.js";
+import { JwtAuthManager } from "./auth/manager.js";
 import { CID } from "multiformats/cid";
 
 //#region src/pinner.ts
@@ -14,11 +15,17 @@ var Pinner = class {
 	_ipns;
 	_websites;
 	_upload;
+	auth;
+	/**
+	* Create a new Pinner SDK instance.
+	* @param config SDK configuration object
+	*/
 	constructor(config) {
-		this.uploadManager = new UploadManager(config);
-		this._pins = new PinClient(config);
-		this._ipns = new IpnsClient(config);
-		this._websites = new WebsitesClient(config);
+		this.auth = new JwtAuthManager(config.jwt);
+		this.uploadManager = new UploadManager(config, this.auth);
+		this._pins = new PinClient(config, this.auth);
+		this._ipns = new IpnsClient(config, this.auth);
+		this._websites = new WebsitesClient(config, this.auth);
 	}
 	/**
 	* Access the remote pins interface.
@@ -60,6 +67,8 @@ var Pinner = class {
 	/**
 	* Upload a file and wait for completion.
 	* Convenience method for simple use cases where controls aren't needed.
+	* @param file The file to upload
+	* @param options Upload configuration
 	*/
 	async uploadAndWait(file, options) {
 		return (await this.upload(file, options)).result;
@@ -75,6 +84,8 @@ var Pinner = class {
 	}
 	/**
 	* Upload a directory to IPFS.
+	* @param files Array of files to upload as a directory
+	* @param options Upload configuration
 	*/
 	async uploadDirectory(files, options) {
 		return this.uploadManager.uploadDirectory(files, options);
@@ -82,12 +93,16 @@ var Pinner = class {
 	/**
 	* Upload a CAR file without preprocessing.
 	* This is useful for passthrough of pre-generated CAR files.
+	* @param file CAR file or stream to upload
+	* @param options Upload configuration
 	*/
 	async uploadCar(file, options) {
 		return this.uploadManager.uploadCar(file, options);
 	}
 	/**
 	* Pin existing content by CID.
+	* @param cid CID of content to pin (string or CID object)
+	* @param options Remote add options
 	*/
 	async pinByHash(cid, options) {
 		const cidObj = typeof cid === "string" ? CID.parse(cid) : cid;
@@ -95,6 +110,7 @@ var Pinner = class {
 	}
 	/**
 	* List pinned content.
+	* @param options List filtering options
 	*/
 	async listPins(options) {
 		const pins = [];
@@ -103,6 +119,7 @@ var Pinner = class {
 	}
 	/**
 	* Get pin status.
+	* @param cid CID of the pinned content to check
 	*/
 	async getPinStatus(cid) {
 		const cidObj = typeof cid === "string" ? CID.parse(cid) : cid;
@@ -110,6 +127,7 @@ var Pinner = class {
 	}
 	/**
 	* Check if content is pinned.
+	* @param cid CID to check
 	*/
 	async isPinned(cid) {
 		const cidObj = typeof cid === "string" ? CID.parse(cid) : cid;
@@ -117,6 +135,8 @@ var Pinner = class {
 	}
 	/**
 	* Update pin metadata.
+	* @param cid CID of the pin
+	* @param metadata Key-value metadata to set
 	*/
 	async setPinMetadata(cid, metadata) {
 		const cidObj = typeof cid === "string" ? CID.parse(cid) : cid;
@@ -124,6 +144,8 @@ var Pinner = class {
 	}
 	/**
 	* Remove a pin. The block may be deleted when garbage collection is run.
+	* @param cid CID to unpin
+	* @param options Abort options
 	*/
 	async unpin(cid, options) {
 		const cidObj = typeof cid === "string" ? CID.parse(cid) : cid;
@@ -132,6 +154,8 @@ var Pinner = class {
 	}
 	/**
 	* Remove a pin by request ID. The block may be deleted when garbage collection is run.
+	* @param requestId The request ID to remove
+	* @param options Abort options
 	*/
 	async unpinByRequestId(requestId, options) {
 		return this.pins.rmByRequestId(requestId, options);

package/dist/esm/pinner.js.map

@@ -1 +1 @@
-{"version":3,"file":"pinner.js","names":[],"sources":["../../src/pinner.ts"],"sourcesContent":["import type { PinnerConfig } from \"./config\";\nimport { UploadManager } from \"./upload\";\nimport { PinClient } from \"./pin\";\nimport { IpnsClient } from \"./api/ipns\";\nimport { WebsitesClient } from \"./api/websites\";\nimport type { UploadMethodAndBuilder } from \"@/upload/builder\";\nimport { createUploadBuilderNamespace } from \"@/upload/builder\";\nimport type {\n  UploadOperation,\n  UploadOptions,\n  UploadResult,\n} from \"@/types/upload\";\nimport type { OperationPollingOptions } from \"@lumeweb/portal-sdk\";\nimport type {\n  AbortOptions,\n  RemoteAddOptions,\n  RemoteLsOptions,\n  RemotePin,\n  RemotePins,\n} from \"@/types/pin\";\nimport { CID } from \"multiformats/cid\";\n\nexport class Pinner {\n  private uploadManager: UploadManager;\n  private _pins: RemotePins;\n  private _ipns: IpnsClient;\n  private _websites: WebsitesClient;\n  private _upload?: UploadMethodAndBuilder;\n\n  constructor(config: PinnerConfig) {\n    this.uploadManager = new UploadManager(config);\n    this._pins = new PinClient(config);\n    this._ipns = new IpnsClient(config);\n    this._websites = new WebsitesClient(config);\n  }\n\n  /**\n   * Access the remote pins interface.\n   */\n  get pins(): RemotePins {\n    return this._pins;\n  }\n\n  /**\n   * Access the IPNS interface for key management and publishing.\n   */\n  get ipns(): IpnsClient {\n    return this._ipns;\n  }\n\n  /**\n   * Access the websites interface for website configuration and management.\n   */\n  get websites(): WebsitesClient {\n    return this._websites;\n  }\n\n  /**\n   * Upload interface that works as both a method and a builder namespace.\n   *\n   * As a method: upload(file, options) -> UploadOperation\n   * As a property: upload.file(), upload.json(), etc. -> Builder\n   */\n  get upload(): UploadMethodAndBuilder {\n    if (!this._upload) {\n      const builderNamespace = createUploadBuilderNamespace(this);\n      const uploadMethod = async (\n        file: File,\n        options?: UploadOptions,\n      ): Promise<UploadOperation> => {\n        return this.uploadManager.upload(file, options);\n      };\n\n      this._upload = new Proxy(uploadMethod, {\n        get(target, prop) {\n          if (prop in builderNamespace) {\n            return Reflect.get(builderNamespace, prop);\n          }\n          return Reflect.get(target, prop);\n        },\n      }) as UploadMethodAndBuilder;\n    }\n    return this._upload;\n  }\n\n  /**\n   * Upload a file and wait for completion.\n   * Convenience method for simple use cases where controls aren't needed.\n   */\n  async uploadAndWait(\n    file: File,\n    options?: UploadOptions,\n  ): Promise<UploadResult> {\n    const operation = await this.upload(file, options);\n    return operation.result;\n  }\n\n  /**\n   * Wait for an operation to complete or reach a settled state.\n   * @param input Either an operation ID (number) or an UploadResult\n   * @param options Polling options (interval, timeout, settledStates)\n   * @returns UploadResult with operation status merged in\n   */\n  async waitForOperation(\n    input: number | UploadResult,\n    options?: OperationPollingOptions,\n  ): Promise<UploadResult> {\n    return this.uploadManager.waitForOperation(input, options);\n  }\n\n  /**\n   * Upload a directory to IPFS.\n   */\n  async uploadDirectory(\n    files: File[],\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    return this.uploadManager.uploadDirectory(files, options);\n  }\n\n  /**\n   * Upload a CAR file without preprocessing.\n   * This is useful for passthrough of pre-generated CAR files.\n   */\n  async uploadCar(\n    file: File | ReadableStream<Uint8Array>,\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    return this.uploadManager.uploadCar(file, options);\n  }\n\n  /**\n   * Pin existing content by CID.\n   */\n  async pinByHash(\n    cid: string | CID,\n    options?: RemoteAddOptions,\n  ): Promise<AsyncGenerator<CID, void, undefined>> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.add(cidObj, options);\n  }\n\n  /**\n   * List pinned content.\n   */\n  async listPins(options?: RemoteLsOptions): Promise<RemotePin[]> {\n    const pins: RemotePin[] = [];\n    for await (const pin of this.pins.ls(options)) {\n      pins.push(pin);\n    }\n    return pins;\n  }\n\n  /**\n   * Get pin status.\n   */\n  async getPinStatus(cid: string | CID): Promise<RemotePin> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.get(cidObj);\n  }\n\n  /**\n   * Check if content is pinned.\n   */\n  async isPinned(cid: string | CID): Promise<boolean> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.isPinned(cidObj);\n  }\n\n  /**\n   * Update pin metadata.\n   */\n  async setPinMetadata(\n    cid: string | CID,\n    metadata: Record<string, string> | undefined,\n  ): Promise<void> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.setMetadata(cidObj, metadata);\n  }\n\n  /**\n   * Remove a pin. The block may be deleted when garbage collection is run.\n   */\n  async unpin(cid: string | CID, options?: AbortOptions): Promise<void> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    const generator = this.pins.rm(cidObj, options);\n    for await (const _ of generator) {\n      // Consume the generator to complete the unpin operation\n    }\n  }\n\n  /**\n   * Remove a pin by request ID. The block may be deleted when garbage collection is run.\n   */\n  async unpinByRequestId(requestId: string, options?: AbortOptions): Promise<void> {\n    return this.pins.rmByRequestId(requestId, options);\n  }\n\n  /**\n   * Destroy the client and cleanup resources.\n   */\n  destroy(): void {\n    this.uploadManager.destroy();\n  }\n}\n"],"mappings":";;;;;;;;;;AAsBA,IAAa,SAAb,MAAoB;CAClB,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CAER,YAAY,QAAsB;AAChC,OAAK,gBAAgB,IAAI,cAAc,OAAO;AAC9C,OAAK,QAAQ,IAAI,UAAU,OAAO;AAClC,OAAK,QAAQ,IAAI,WAAW,OAAO;AACnC,OAAK,YAAY,IAAI,eAAe,OAAO;;;;;CAM7C,IAAI,OAAmB;AACrB,SAAO,KAAK;;;;;CAMd,IAAI,OAAmB;AACrB,SAAO,KAAK;;;;;CAMd,IAAI,WAA2B;AAC7B,SAAO,KAAK;;;;;;;;CASd,IAAI,SAAiC;AACnC,MAAI,CAAC,KAAK,SAAS;GACjB,MAAM,mBAAmB,6BAA6B,KAAK;GAC3D,MAAM,eAAe,OACnB,MACA,YAC6B;AAC7B,WAAO,KAAK,cAAc,OAAO,MAAM,QAAQ;;AAGjD,QAAK,UAAU,IAAI,MAAM,cAAc,EACrC,IAAI,QAAQ,MAAM;AAChB,QAAI,QAAQ,iBACV,QAAO,QAAQ,IAAI,kBAAkB,KAAK;AAE5C,WAAO,QAAQ,IAAI,QAAQ,KAAK;MAEnC,CAAC;;AAEJ,SAAO,KAAK;;;;;;CAOd,MAAM,cACJ,MACA,SACuB;AAEvB,UAAO,MADiB,KAAK,OAAO,MAAM,QAAQ,EACjC;;;;;;;;CASnB,MAAM,iBACJ,OACA,SACuB;AACvB,SAAO,KAAK,cAAc,iBAAiB,OAAO,QAAQ;;;;;CAM5D,MAAM,gBACJ,OACA,SAC0B;AAC1B,SAAO,KAAK,cAAc,gBAAgB,OAAO,QAAQ;;;;;;CAO3D,MAAM,UACJ,MACA,SAC0B;AAC1B,SAAO,KAAK,cAAc,UAAU,MAAM,QAAQ;;;;;CAMpD,MAAM,UACJ,KACA,SAC+C;EAC/C,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,IAAI,QAAQ,QAAQ;;;;;CAMvC,MAAM,SAAS,SAAiD;EAC9D,MAAM,OAAoB,EAAE;AAC5B,aAAW,MAAM,OAAO,KAAK,KAAK,GAAG,QAAQ,CAC3C,MAAK,KAAK,IAAI;AAEhB,SAAO;;;;;CAMT,MAAM,aAAa,KAAuC;EACxD,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,IAAI,OAAO;;;;;CAM9B,MAAM,SAAS,KAAqC;EAClD,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,SAAS,OAAO;;;;;CAMnC,MAAM,eACJ,KACA,UACe;EACf,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,YAAY,QAAQ,SAAS;;;;;CAMhD,MAAM,MAAM,KAAmB,SAAuC;EACpE,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;EAC1D,MAAM,YAAY,KAAK,KAAK,GAAG,QAAQ,QAAQ;AAC/C,aAAW,MAAM,KAAK;;;;;CAQxB,MAAM,iBAAiB,WAAmB,SAAuC;AAC/E,SAAO,KAAK,KAAK,cAAc,WAAW,QAAQ;;;;;CAMpD,UAAgB;AACd,OAAK,cAAc,SAAS"}
+{"version":3,"file":"pinner.js","names":[],"sources":["../../src/pinner.ts"],"sourcesContent":["import type { PinnerConfig } from \"./config\";\nimport { UploadManager } from \"./upload\";\nimport { PinClient } from \"./pin\";\nimport { IpnsClient } from \"./api/ipns\";\nimport { WebsitesClient } from \"./api/websites\";\nimport { JwtAuthManager, type AuthManager } from \"@/auth\";\nimport type { UploadMethodAndBuilder } from \"@/upload/builder\";\nimport { createUploadBuilderNamespace } from \"@/upload/builder\";\nimport type {\n  UploadOperation,\n  UploadOptions,\n  UploadResult,\n} from \"@/types/upload\";\nimport type { OperationPollingOptions } from \"@lumeweb/portal-sdk\";\nimport type {\n  AbortOptions,\n  RemoteAddOptions,\n  RemoteLsOptions,\n  RemotePin,\n  RemotePins,\n} from \"@/types/pin\";\nimport { CID } from \"multiformats/cid\";\n\nexport class Pinner {\n  private uploadManager: UploadManager;\n  private _pins: RemotePins;\n  private _ipns: IpnsClient;\n  private _websites: WebsitesClient;\n  private _upload?: UploadMethodAndBuilder;\n  private readonly auth: AuthManager;\n\n  /**\n   * Create a new Pinner SDK instance.\n   * @param config SDK configuration object\n   */\n  constructor(config: PinnerConfig) {\n    this.auth = new JwtAuthManager(config.jwt);\n    this.uploadManager = new UploadManager(config, this.auth);\n    this._pins = new PinClient(config, this.auth);\n    this._ipns = new IpnsClient(config, this.auth);\n    this._websites = new WebsitesClient(config, this.auth);\n  }\n\n  /**\n   * Access the remote pins interface.\n   */\n  get pins(): RemotePins {\n    return this._pins;\n  }\n\n  /**\n   * Access the IPNS interface for key management and publishing.\n   */\n  get ipns(): IpnsClient {\n    return this._ipns;\n  }\n\n  /**\n   * Access the websites interface for website configuration and management.\n   */\n  get websites(): WebsitesClient {\n    return this._websites;\n  }\n\n  /**\n   * Upload interface that works as both a method and a builder namespace.\n   *\n   * As a method: upload(file, options) -> UploadOperation\n   * As a property: upload.file(), upload.json(), etc. -> Builder\n   */\n  get upload(): UploadMethodAndBuilder {\n    if (!this._upload) {\n      const builderNamespace = createUploadBuilderNamespace(this);\n      const uploadMethod = async (\n        file: File,\n        options?: UploadOptions,\n      ): Promise<UploadOperation> => {\n        return this.uploadManager.upload(file, options);\n      };\n\n      this._upload = new Proxy(uploadMethod, {\n        get(target, prop) {\n          if (prop in builderNamespace) {\n            return Reflect.get(builderNamespace, prop);\n          }\n          return Reflect.get(target, prop);\n        },\n      }) as UploadMethodAndBuilder;\n    }\n    return this._upload;\n  }\n\n  /**\n   * Upload a file and wait for completion.\n   * Convenience method for simple use cases where controls aren't needed.\n   * @param file The file to upload\n   * @param options Upload configuration\n   */\n  async uploadAndWait(\n    file: File,\n    options?: UploadOptions,\n  ): Promise<UploadResult> {\n    const operation = await this.upload(file, options);\n    return operation.result;\n  }\n\n  /**\n   * Wait for an operation to complete or reach a settled state.\n   * @param input Either an operation ID (number) or an UploadResult\n   * @param options Polling options (interval, timeout, settledStates)\n   * @returns UploadResult with operation status merged in\n   */\n  async waitForOperation(\n    input: number | UploadResult,\n    options?: OperationPollingOptions,\n  ): Promise<UploadResult> {\n    return this.uploadManager.waitForOperation(input, options);\n  }\n\n  /**\n   * Upload a directory to IPFS.\n   * @param files Array of files to upload as a directory\n   * @param options Upload configuration\n   */\n  async uploadDirectory(\n    files: File[],\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    return this.uploadManager.uploadDirectory(files, options);\n  }\n\n  /**\n   * Upload a CAR file without preprocessing.\n   * This is useful for passthrough of pre-generated CAR files.\n   * @param file CAR file or stream to upload\n   * @param options Upload configuration\n   */\n  async uploadCar(\n    file: File | ReadableStream<Uint8Array>,\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    return this.uploadManager.uploadCar(file, options);\n  }\n\n  /**\n   * Pin existing content by CID.\n   * @param cid CID of content to pin (string or CID object)\n   * @param options Remote add options\n   */\n  async pinByHash(\n    cid: string | CID,\n    options?: RemoteAddOptions,\n  ): Promise<AsyncGenerator<CID, void, undefined>> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.add(cidObj, options);\n  }\n\n  /**\n   * List pinned content.\n   * @param options List filtering options\n   */\n  async listPins(options?: RemoteLsOptions): Promise<RemotePin[]> {\n    const pins: RemotePin[] = [];\n    for await (const pin of this.pins.ls(options)) {\n      pins.push(pin);\n    }\n    return pins;\n  }\n\n  /**\n   * Get pin status.\n   * @param cid CID of the pinned content to check\n   */\n  async getPinStatus(cid: string | CID): Promise<RemotePin> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.get(cidObj);\n  }\n\n  /**\n   * Check if content is pinned.\n   * @param cid CID to check\n   */\n  async isPinned(cid: string | CID): Promise<boolean> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.isPinned(cidObj);\n  }\n\n  /**\n   * Update pin metadata.\n   * @param cid CID of the pin\n   * @param metadata Key-value metadata to set\n   */\n  async setPinMetadata(\n    cid: string | CID,\n    metadata: Record<string, string> | undefined,\n  ): Promise<void> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    return this.pins.setMetadata(cidObj, metadata);\n  }\n\n  /**\n   * Remove a pin. The block may be deleted when garbage collection is run.\n   * @param cid CID to unpin\n   * @param options Abort options\n   */\n  async unpin(cid: string | CID, options?: AbortOptions): Promise<void> {\n    const cidObj = typeof cid === \"string\" ? CID.parse(cid) : cid;\n    const generator = this.pins.rm(cidObj, options);\n    for await (const _ of generator) {\n      // Consume the generator to complete the unpin operation\n    }\n  }\n\n  /**\n   * Remove a pin by request ID. The block may be deleted when garbage collection is run.\n   * @param requestId The request ID to remove\n   * @param options Abort options\n   */\n  async unpinByRequestId(requestId: string, options?: AbortOptions): Promise<void> {\n    return this.pins.rmByRequestId(requestId, options);\n  }\n\n  /**\n   * Destroy the client and cleanup resources.\n   */\n  destroy(): void {\n    this.uploadManager.destroy();\n  }\n}\n"],"mappings":";;;;;;;;;;;AAuBA,IAAa,SAAb,MAAoB;CAClB,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAiB;;;;;CAMjB,YAAY,QAAsB;AAChC,OAAK,OAAO,IAAI,eAAe,OAAO,IAAI;AAC1C,OAAK,gBAAgB,IAAI,cAAc,QAAQ,KAAK,KAAK;AACzD,OAAK,QAAQ,IAAI,UAAU,QAAQ,KAAK,KAAK;AAC7C,OAAK,QAAQ,IAAI,WAAW,QAAQ,KAAK,KAAK;AAC9C,OAAK,YAAY,IAAI,eAAe,QAAQ,KAAK,KAAK;;;;;CAMxD,IAAI,OAAmB;AACrB,SAAO,KAAK;;;;;CAMd,IAAI,OAAmB;AACrB,SAAO,KAAK;;;;;CAMd,IAAI,WAA2B;AAC7B,SAAO,KAAK;;;;;;;;CASd,IAAI,SAAiC;AACnC,MAAI,CAAC,KAAK,SAAS;GACjB,MAAM,mBAAmB,6BAA6B,KAAK;GAC3D,MAAM,eAAe,OACnB,MACA,YAC6B;AAC7B,WAAO,KAAK,cAAc,OAAO,MAAM,QAAQ;;AAGjD,QAAK,UAAU,IAAI,MAAM,cAAc,EACrC,IAAI,QAAQ,MAAM;AAChB,QAAI,QAAQ,iBACV,QAAO,QAAQ,IAAI,kBAAkB,KAAK;AAE5C,WAAO,QAAQ,IAAI,QAAQ,KAAK;MAEnC,CAAC;;AAEJ,SAAO,KAAK;;;;;;;;CASd,MAAM,cACJ,MACA,SACuB;AAEvB,UAAO,MADiB,KAAK,OAAO,MAAM,QAAQ,EACjC;;;;;;;;CASnB,MAAM,iBACJ,OACA,SACuB;AACvB,SAAO,KAAK,cAAc,iBAAiB,OAAO,QAAQ;;;;;;;CAQ5D,MAAM,gBACJ,OACA,SAC0B;AAC1B,SAAO,KAAK,cAAc,gBAAgB,OAAO,QAAQ;;;;;;;;CAS3D,MAAM,UACJ,MACA,SAC0B;AAC1B,SAAO,KAAK,cAAc,UAAU,MAAM,QAAQ;;;;;;;CAQpD,MAAM,UACJ,KACA,SAC+C;EAC/C,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,IAAI,QAAQ,QAAQ;;;;;;CAOvC,MAAM,SAAS,SAAiD;EAC9D,MAAM,OAAoB,EAAE;AAC5B,aAAW,MAAM,OAAO,KAAK,KAAK,GAAG,QAAQ,CAC3C,MAAK,KAAK,IAAI;AAEhB,SAAO;;;;;;CAOT,MAAM,aAAa,KAAuC;EACxD,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,IAAI,OAAO;;;;;;CAO9B,MAAM,SAAS,KAAqC;EAClD,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,SAAS,OAAO;;;;;;;CAQnC,MAAM,eACJ,KACA,UACe;EACf,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;AAC1D,SAAO,KAAK,KAAK,YAAY,QAAQ,SAAS;;;;;;;CAQhD,MAAM,MAAM,KAAmB,SAAuC;EACpE,MAAM,SAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,GAAG;EAC1D,MAAM,YAAY,KAAK,KAAK,GAAG,QAAQ,QAAQ;AAC/C,aAAW,MAAM,KAAK;;;;;;;CAUxB,MAAM,iBAAiB,WAAmB,SAAuC;AAC/E,SAAO,KAAK,KAAK,cAAc,WAAW,QAAQ;;;;;CAMpD,UAAgB;AACd,OAAK,cAAc,SAAS"}

package/dist/esm/types/pin.d.ts

@@ -6,34 +6,76 @@ import { Status } from "@ipfs-shipyard/pinning-service-client";
  * Options that can be passed to abort async operations
  */
 interface AbortOptions {
+  /**
+   * AbortSignal to cancel the operation
+   */
   signal?: AbortSignal;
 }
 /**
  * Allows passing extra options accepted by the remote pinning service
  */
 interface RemoteAddOptions extends AbortOptions {
+  /**
+   * Name for the pin or filter
+   */
   name?: string;
+  /**
+   * Key-value metadata to attach to the pin
+   */
   metadata?: Record<string, string>;
+  /**
+   * Origin addresses for the pinned content
+   */
   origins?: string[];
 }
 /**
  * Allows passing extra options accepted by the remote pinning service
  */
 interface RemoteLsOptions extends AbortOptions {
+  /**
+   * Name for the pin or filter
+   */
   name?: string;
+  /**
+   * Current status (queued, pinning, pinned, failed)
+   */
   status?: Status[];
+  /**
+   * Maximum number of results per page
+   */
   limit?: number;
+  /**
+   * Pagination cursor for listing results
+   */
   cursor?: string;
 }
 /**
  * Includes extra metadata supported by the remote pinning service
  */
 interface RemotePin {
+  /**
+   * IPFS Content Identifier
+   */
   cid: CID;
+  /**
+   * Name for the pin or filter
+   */
   name?: string;
+  /**
+   * Current status (queued, pinning, pinned, failed)
+   */
   status: Status;
+  /**
+   * ISO timestamp of creation
+   */
   created: Date;
+  /**
+   * Size in bytes
+   */
   size?: number;
+  /**
+   * Key-value metadata to attach to the pin
+   */
   metadata?: Record<string, string>;
 }
 /**

package/dist/esm/upload/base-upload.js

@@ -9,8 +9,10 @@ import defer from "p-defer";
 //#region src/upload/base-upload.ts
 var BaseUploadHandler = class {
 	config;
-	constructor(config) {
+	auth;
+	constructor(config, auth) {
 		this.config = config;
+		this.auth = auth;
 	}
 	async upload(input, options) {
 		const normalized = normalizeUploadInput(input, options);

package/dist/esm/upload/base-upload.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-upload.js","names":["#setupUppyHandlers","#addFileToUppy","#startUpload","#createUploadOperation","#extractErrorMessage","#normalizeData","#normalizeDataForNode","#normalizeDataForBrowser"],"sources":["../../../src/upload/base-upload.ts"],"sourcesContent":["import Uppy from \"@uppy/core\";\nimport { default as defer } from \"p-defer\";\nimport type { Readable } from \"stream\";\n\nimport type { PinnerConfig } from \"../config\";\nimport type {\n  UploadInput,\n  UploadOperation,\n  UploadOptions,\n  UploadProgress,\n  UploadResult,\n} from \"@/types/upload\";\nimport { UploadResultSymbol } from \"@/types/upload\";\nimport type { PostUploadResponse } from \"@/api/generated/schemas\";\nimport { normalizeUploadInput, type UploadInputObject } from \"./normalize\";\nimport {\n  fileToReadableStream,\n  readableStreamToNodeStream,\n} from \"@/utils/stream\";\nimport { isNodeEnvironment } from \"@/utils/env\";\nimport { UPLOAD_SOURCE_TUS, UPLOAD_SOURCE_XHR } from \"./constants\";\n\n// Node.js Readable stream with size property for Uppy compatibility\ntype NodeStreamWithSize = Readable & { size: number | null };\n\nexport abstract class BaseUploadHandler {\n  protected config: Required<PinnerConfig>;\n\n  constructor(config: PinnerConfig) {\n    this.config = config as Required<PinnerConfig>;\n  }\n\n  async upload(\n    input: UploadInput | UploadInputObject,\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    const normalized = normalizeUploadInput(input, options);\n    const uppy = new Uppy();\n    const { fileId, resultPromise, progress } = this.#setupUppyHandlers(\n      uppy,\n      normalized,\n      options,\n    );\n\n    await this.#addFileToUppy(uppy, normalized, normalized.size);\n    this.#startUpload(uppy, options);\n\n    return this.#createUploadOperation(uppy, fileId, resultPromise, progress);\n  }\n\n  #setupUppyHandlers(\n    uppy: Uppy,\n    normalized: { size: number },\n    options?: UploadOptions,\n  ): {\n    fileId: string | null;\n    resultPromise: Promise<UploadResult>;\n    progress: UploadProgress;\n  } {\n    let fileId: string | null = null;\n    let hasRejected = false;\n\n    const progress: UploadProgress = {\n      percentage: 0,\n      bytesUploaded: 0,\n      bytesTotal: normalized.size,\n    };\n\n    const {\n      promise: resultPromise,\n      resolve: resolveResult,\n      reject: rejectResult,\n    } = defer<UploadResult>();\n\n    const handleError = (error: Error) => {\n      if (hasRejected) return;\n      hasRejected = true;\n      options?.onError?.(error);\n      rejectResult(error);\n    };\n\n    this.configurePlugin(uppy);\n\n    uppy.on(\"progress\", (progressBytes) => {\n      progress.bytesUploaded = progressBytes;\n      progress.percentage = (progressBytes / progress.bytesTotal) * 100;\n      options?.onProgress?.(progress);\n    });\n\n    uppy.on(\"upload-success\", (_file, result) => {\n      if (hasRejected) return;\n      const uploadResult = this.parseResult(result);\n      options?.onComplete?.(uploadResult);\n      resolveResult(uploadResult);\n    });\n\n    uppy.on(\"error\", (error) => {\n      handleError(new Error(this.#extractErrorMessage(error)));\n    });\n\n    uppy.on(\"file-added\", (file) => {\n      fileId = file.id;\n    });\n\n    return { fileId, resultPromise, progress };\n  }\n\n  #extractErrorMessage(error: unknown): string {\n    let errorMessage = \"Upload fainormalizeDataled\";\n\n    if (!error) return errorMessage;\n\n    if (typeof error === \"string\") {\n      errorMessage = error;\n    } else if (error instanceof Error) {\n      errorMessage = error.message;\n    } else if ((error as any).message) {\n      errorMessage = (error as any).message;\n    } else if (\n      (error as any).toString &&\n      typeof (error as any).toString === \"function\"\n    ) {\n      errorMessage = (error as any).toString();\n    }\n\n    // Try to extract error from response (XHRUpload/TusPlugin)\n    const errorObj = error as any;\n    if (errorObj?.xhr?.response) {\n      try {\n        const response =\n          typeof errorObj.xhr.response === \"string\"\n            ? JSON.parse(errorObj.xhr.response)\n            : errorObj.xhr.response;\n        if (response.error) {\n          errorMessage = response.error;\n        } else if (response.message) {\n          errorMessage = response.message;\n        }\n      } catch {\n        // If parsing fails, use the original error message\n      }\n    }\n\n    return errorMessage;\n  }\n\n  async #normalizeData(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<File | ReadableStream<Uint8Array> | NodeStreamWithSize | Blob> {\n    if (isNodeEnvironment()) {\n      return this.#normalizeDataForNode(data);\n    }\n    return this.#normalizeDataForBrowser(data);\n  }\n\n  async #normalizeDataForBrowser(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<File | Blob | ReadableStream<Uint8Array>> {\n    // TUS plugin requires File, Blob, or Reader in browser\n    if (this.getUploadSource() === UPLOAD_SOURCE_TUS) {\n      if (data instanceof ReadableStream) {\n        const { streamToBlobViaResponse } = await import(\"@/utils/stream\");\n        return streamToBlobViaResponse(data);\n      }\n      return data;\n    }\n\n    // XHRUpload handles File/Blob directly\n    return data;\n  }\n\n  async #normalizeDataForNode(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<NodeStreamWithSize | File | Blob | ReadableStream<Uint8Array>> {\n    // XHRUpload with formData: true requires Blob/File for FormData.append()\n    // Do not convert to Node.js stream for XHRUpload\n    if (this.getUploadSource() === UPLOAD_SOURCE_XHR) {\n      return data;\n    }\n\n    // Convert File to ReadableStream without loading entire blob into memory\n    if (data instanceof File) {\n      const stream = fileToReadableStream(data);\n      // Convert to Node.js stream for tus-js-client\n      const nodeStream = await readableStreamToNodeStream(stream);\n      return nodeStream as NodeStreamWithSize;\n    }\n\n    // In Node.js, convert ReadableStream to Node.js stream.Readable for tus-js-client's NodeFileReader\n    if (data instanceof ReadableStream) {\n      const nodeStream = await readableStreamToNodeStream(data);\n      // Add size property to satisfy Uppy's type requirements\n      return nodeStream as NodeStreamWithSize;\n    }\n\n    return data;\n  }\n\n  async #addFileToUppy(\n    uppy: Uppy,\n    normalized: {\n      data: File | ReadableStream<Uint8Array>;\n      name: string;\n      type: string;\n    },\n    size?: number,\n  ): Promise<void> {\n    const fileData = await this.#normalizeData(normalized.data);\n    const fileOptions = {\n      source: this.getUploadSource(),\n      name: normalized.name,\n      type: normalized.type,\n      data: fileData as any,\n    };\n\n    // Add file to Uppy first\n    // Note: Uppy accepts any data type as it defers to the drivers\n    const fileId = uppy.addFile(fileOptions);\n\n    // Set TUS upload size if provided\n    // In Node.js, streams need explicit size for tus-js-client\n    // In browser, Uppy's TUS plugin may not derive size from Blob automatically\n    if (\n      this.getUploadSource() === UPLOAD_SOURCE_TUS &&\n      size !== undefined &&\n      size > 0\n    ) {\n      uppy.setFileState(fileId, {\n        tus: { uploadSize: size },\n      });\n    }\n  }\n\n  #startUpload(uppy: Uppy, options?: UploadOptions): void {\n    uppy.upload().catch((error) => {\n      options?.onError?.(new Error(this.#extractErrorMessage(error)));\n    });\n  }\n\n  #createUploadOperation(\n    uppy: Uppy,\n    fileId: string | null,\n    resultPromise: Promise<UploadResult>,\n    progress: UploadProgress,\n  ): UploadOperation {\n    return {\n      cancel: () => {\n        uppy.cancelAll();\n      },\n      pause: () => {\n        if (fileId) {\n          uppy.pauseResume(fileId);\n        }\n      },\n      resume: () => {\n        if (fileId) {\n          uppy.pauseResume(fileId);\n        }\n      },\n      result: resultPromise,\n      progress: Object.freeze({ ...progress }),\n    };\n  }\n\n  destroy(): void {\n    // No-op since each upload creates its own Uppy instance\n  }\n\n  protected abstract configurePlugin(uppy: Uppy): void;\n  protected abstract parseResult(result: unknown): UploadResult;\n  protected abstract getUploadSource(): string;\n\n  protected mapUploadResponse(\n    body: unknown,\n    uploadId: string,\n    overrides?: Partial<UploadResult>,\n  ): UploadResult {\n    if (body && typeof body === \"object\" && \"CID\" in body) {\n      const { CID } = body as PostUploadResponse;\n      return {\n        id: uploadId,\n        cid: CID,\n        name: \"\",\n        size: 0,\n        mimeType: \"\",\n        createdAt: new Date(),\n        numberOfFiles: 1,\n        [UploadResultSymbol]: true,\n        ...overrides,\n      };\n    }\n\n    return {\n      id: uploadId,\n      name: \"\",\n      size: 0,\n      mimeType: \"\",\n      createdAt: new Date(),\n      numberOfFiles: 1,\n      [UploadResultSymbol]: true,\n      ...overrides,\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"base-upload.js","names":["#setupUppyHandlers","#addFileToUppy","#startUpload","#createUploadOperation","#extractErrorMessage","#normalizeData","#normalizeDataForNode","#normalizeDataForBrowser"],"sources":["../../../src/upload/base-upload.ts"],"sourcesContent":["import Uppy from \"@uppy/core\";\nimport { default as defer } from \"p-defer\";\nimport type { Readable } from \"stream\";\n\nimport type { PinnerConfig } from \"../config\";\nimport type { AuthManager } from \"@/auth\";\nimport type {\n  UploadInput,\n  UploadOperation,\n  UploadOptions,\n  UploadProgress,\n  UploadResult,\n} from \"@/types/upload\";\nimport { UploadResultSymbol } from \"@/types/upload\";\nimport type { PostUploadResponse } from \"@/api/generated/schemas\";\nimport { normalizeUploadInput, type UploadInputObject } from \"./normalize\";\nimport {\n  fileToReadableStream,\n  readableStreamToNodeStream,\n} from \"@/utils/stream\";\nimport { isNodeEnvironment } from \"@/utils/env\";\nimport { UPLOAD_SOURCE_TUS, UPLOAD_SOURCE_XHR } from \"./constants\";\n\n// Node.js Readable stream with size property for Uppy compatibility\ntype NodeStreamWithSize = Readable & { size: number | null };\n\nexport abstract class BaseUploadHandler {\n  protected config: Required<PinnerConfig>;\n  protected readonly auth: AuthManager;\n\n  constructor(config: PinnerConfig, auth: AuthManager) {\n    this.config = config as Required<PinnerConfig>;\n    this.auth = auth;\n  }\n\n  async upload(\n    input: UploadInput | UploadInputObject,\n    options?: UploadOptions,\n  ): Promise<UploadOperation> {\n    const normalized = normalizeUploadInput(input, options);\n    const uppy = new Uppy();\n    const { fileId, resultPromise, progress } = this.#setupUppyHandlers(\n      uppy,\n      normalized,\n      options,\n    );\n\n    await this.#addFileToUppy(uppy, normalized, normalized.size);\n    this.#startUpload(uppy, options);\n\n    return this.#createUploadOperation(uppy, fileId, resultPromise, progress);\n  }\n\n  #setupUppyHandlers(\n    uppy: Uppy,\n    normalized: { size: number },\n    options?: UploadOptions,\n  ): {\n    fileId: string | null;\n    resultPromise: Promise<UploadResult>;\n    progress: UploadProgress;\n  } {\n    let fileId: string | null = null;\n    let hasRejected = false;\n\n    const progress: UploadProgress = {\n      percentage: 0,\n      bytesUploaded: 0,\n      bytesTotal: normalized.size,\n    };\n\n    const {\n      promise: resultPromise,\n      resolve: resolveResult,\n      reject: rejectResult,\n    } = defer<UploadResult>();\n\n    const handleError = (error: Error) => {\n      if (hasRejected) return;\n      hasRejected = true;\n      options?.onError?.(error);\n      rejectResult(error);\n    };\n\n    this.configurePlugin(uppy);\n\n    uppy.on(\"progress\", (progressBytes) => {\n      progress.bytesUploaded = progressBytes;\n      progress.percentage = (progressBytes / progress.bytesTotal) * 100;\n      options?.onProgress?.(progress);\n    });\n\n    uppy.on(\"upload-success\", (_file, result) => {\n      if (hasRejected) return;\n      const uploadResult = this.parseResult(result);\n      options?.onComplete?.(uploadResult);\n      resolveResult(uploadResult);\n    });\n\n    uppy.on(\"error\", (error) => {\n      handleError(new Error(this.#extractErrorMessage(error)));\n    });\n\n    uppy.on(\"file-added\", (file) => {\n      fileId = file.id;\n    });\n\n    return { fileId, resultPromise, progress };\n  }\n\n  #extractErrorMessage(error: unknown): string {\n    let errorMessage = \"Upload fainormalizeDataled\";\n\n    if (!error) return errorMessage;\n\n    if (typeof error === \"string\") {\n      errorMessage = error;\n    } else if (error instanceof Error) {\n      errorMessage = error.message;\n    } else if ((error as any).message) {\n      errorMessage = (error as any).message;\n    } else if (\n      (error as any).toString &&\n      typeof (error as any).toString === \"function\"\n    ) {\n      errorMessage = (error as any).toString();\n    }\n\n    // Try to extract error from response (XHRUpload/TusPlugin)\n    const errorObj = error as any;\n    if (errorObj?.xhr?.response) {\n      try {\n        const response =\n          typeof errorObj.xhr.response === \"string\"\n            ? JSON.parse(errorObj.xhr.response)\n            : errorObj.xhr.response;\n        if (response.error) {\n          errorMessage = response.error;\n        } else if (response.message) {\n          errorMessage = response.message;\n        }\n      } catch {\n        // If parsing fails, use the original error message\n      }\n    }\n\n    return errorMessage;\n  }\n\n  async #normalizeData(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<File | ReadableStream<Uint8Array> | NodeStreamWithSize | Blob> {\n    if (isNodeEnvironment()) {\n      return this.#normalizeDataForNode(data);\n    }\n    return this.#normalizeDataForBrowser(data);\n  }\n\n  async #normalizeDataForBrowser(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<File | Blob | ReadableStream<Uint8Array>> {\n    // TUS plugin requires File, Blob, or Reader in browser\n    if (this.getUploadSource() === UPLOAD_SOURCE_TUS) {\n      if (data instanceof ReadableStream) {\n        const { streamToBlobViaResponse } = await import(\"@/utils/stream\");\n        return streamToBlobViaResponse(data);\n      }\n      return data;\n    }\n\n    // XHRUpload handles File/Blob directly\n    return data;\n  }\n\n  async #normalizeDataForNode(\n    data: File | ReadableStream<Uint8Array>,\n  ): Promise<NodeStreamWithSize | File | Blob | ReadableStream<Uint8Array>> {\n    // XHRUpload with formData: true requires Blob/File for FormData.append()\n    // Do not convert to Node.js stream for XHRUpload\n    if (this.getUploadSource() === UPLOAD_SOURCE_XHR) {\n      return data;\n    }\n\n    // Convert File to ReadableStream without loading entire blob into memory\n    if (data instanceof File) {\n      const stream = fileToReadableStream(data);\n      // Convert to Node.js stream for tus-js-client\n      const nodeStream = await readableStreamToNodeStream(stream);\n      return nodeStream as NodeStreamWithSize;\n    }\n\n    // In Node.js, convert ReadableStream to Node.js stream.Readable for tus-js-client's NodeFileReader\n    if (data instanceof ReadableStream) {\n      const nodeStream = await readableStreamToNodeStream(data);\n      // Add size property to satisfy Uppy's type requirements\n      return nodeStream as NodeStreamWithSize;\n    }\n\n    return data;\n  }\n\n  async #addFileToUppy(\n    uppy: Uppy,\n    normalized: {\n      /**\n       * List of file manager items\n       */\n      data: File | ReadableStream<Uint8Array>;\n      /**\n       * Name for the pin or filter\n       */\n      name: string;\n      /**\n       * MIME type or content type\n       */\n      type: string;\n    },\n    size?: number,\n  ): Promise<void> {\n    const fileData = await this.#normalizeData(normalized.data);\n    const fileOptions = {\n      source: this.getUploadSource(),\n      name: normalized.name,\n      type: normalized.type,\n      data: fileData as any,\n    };\n\n    // Add file to Uppy first\n    // Note: Uppy accepts any data type as it defers to the drivers\n    const fileId = uppy.addFile(fileOptions);\n\n    // Set TUS upload size if provided\n    // In Node.js, streams need explicit size for tus-js-client\n    // In browser, Uppy's TUS plugin may not derive size from Blob automatically\n    if (\n      this.getUploadSource() === UPLOAD_SOURCE_TUS &&\n      size !== undefined &&\n      size > 0\n    ) {\n      uppy.setFileState(fileId, {\n        tus: { uploadSize: size },\n      });\n    }\n  }\n\n  #startUpload(uppy: Uppy, options?: UploadOptions): void {\n    uppy.upload().catch((error) => {\n      options?.onError?.(new Error(this.#extractErrorMessage(error)));\n    });\n  }\n\n  #createUploadOperation(\n    uppy: Uppy,\n    fileId: string | null,\n    resultPromise: Promise<UploadResult>,\n    progress: UploadProgress,\n  ): UploadOperation {\n    return {\n      cancel: () => {\n        uppy.cancelAll();\n      },\n      pause: () => {\n        if (fileId) {\n          uppy.pauseResume(fileId);\n        }\n      },\n      resume: () => {\n        if (fileId) {\n          uppy.pauseResume(fileId);\n        }\n      },\n      result: resultPromise,\n      progress: Object.freeze({ ...progress }),\n    };\n  }\n\n  destroy(): void {\n    // No-op since each upload creates its own Uppy instance\n  }\n\n  protected abstract configurePlugin(uppy: Uppy): void;\n  protected abstract parseResult(result: unknown): UploadResult;\n  protected abstract getUploadSource(): string;\n\n  protected mapUploadResponse(\n    body: unknown,\n    uploadId: string,\n    overrides?: Partial<UploadResult>,\n  ): UploadResult {\n    if (body && typeof body === \"object\" && \"CID\" in body) {\n      const { CID } = body as PostUploadResponse;\n      return {\n        id: uploadId,\n        cid: CID,\n        name: \"\",\n        size: 0,\n        mimeType: \"\",\n        createdAt: new Date(),\n        numberOfFiles: 1,\n        [UploadResultSymbol]: true,\n        ...overrides,\n      };\n    }\n\n    return {\n      id: uploadId,\n      name: \"\",\n      size: 0,\n      mimeType: \"\",\n      createdAt: new Date(),\n      numberOfFiles: 1,\n      [UploadResultSymbol]: true,\n      ...overrides,\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/esm/upload/builder.d.ts

@@ -55,5 +55,5 @@ declare class UploadBuilderNamespace {
  */
 type UploadMethodAndBuilder = ((file: File, options?: UploadOptions) => Promise<UploadOperation>) & UploadBuilderNamespace;
 //#endregion
-export { UploadMethodAndBuilder };
+export { UploadBuilderNamespace, UploadMethodAndBuilder };
 //# sourceMappingURL=builder.d.ts.map

package/dist/esm/upload/car.d.ts

@@ -2,13 +2,31 @@ import { Datastore } from "interface-datastore";
 
 //#region src/upload/car.d.ts
 interface CarPreprocessOptions {
+  /**
+   * Name for the pin or filter
+   */
   name?: string;
+  /**
+   * Progress callback for preprocessing
+   */
   onProgress?: (percentage: number) => void;
+  /**
+   * AbortSignal to cancel the operation
+   */
   signal?: AbortSignal;
 }
 interface CarPreprocessResult {
+  /**
+   * Preprocessed CAR data as a readable stream
+   */
   carStream: ReadableStream<Uint8Array>;
+  /**
+   * Root CID of the CAR file
+   */
   rootCid: string;
+  /**
+   * Size in bytes
+   */
   size: bigint;
 }
 declare function preprocessToCar(input: File | ReadableStream<Uint8Array> | File[], options?: CarPreprocessOptions): Promise<CarPreprocessResult>;

package/dist/esm/upload/car.js.map

@@ -1 +1 @@
-{"version":3,"file":"car.js","names":["createUnstorageDatastore"],"sources":["../../../src/upload/car.ts"],"sourcesContent":["import { car } from \"@helia/car\";\nimport { createHeliaHTTP } from \"@helia/http\";\nimport { unixfs } from \"@helia/unixfs\";\nimport {\n  createBlockstore,\n  createDatastore as createUnstorageDatastore,\n} from \"@/blockstore\";\nimport type { CID } from \"multiformats/cid\";\nimport { CarReader } from \"@ipld/car\";\nimport type { Datastore } from \"interface-datastore\";\n\nimport {\n  asyncGeneratorToReadableStream,\n  calculateStreamSize,\n  readableStreamToAsyncIterable,\n  streamToBlob,\n} from \"@/utils/stream\";\nimport { FILE_EXTENSION_CAR, MIME_TYPE_CAR } from \"@/types/mime-types\";\n\nexport interface CarPreprocessOptions {\n  name?: string;\n  onProgress?: (percentage: number) => void;\n  signal?: AbortSignal;\n}\n\nexport interface CarPreprocessResult {\n  carStream: ReadableStream<Uint8Array>;\n  rootCid: string;\n  size: bigint;\n}\n\nexport interface CarConfig {\n  /**\n   * Custom datastore instance for Helia.\n   * If provided, this datastore will be used directly without creating one from storage.\n   * Highest priority - takes precedence over storage and datastoreName.\n   */\n  datastore?: Datastore;\n\n  /**\n   * Custom base name for Helia storage.\n   * Passed as the `base` option to both blockstore and datastore storage instances.\n   * Only used when datastore is not provided.\n   * @default \"pinner-helia-data\"\n   */\n  datastoreName?: string;\n}\n\nlet helia: any = null;\nlet blockstore: any = null;\nlet datastore: any = null;\nlet config: CarConfig = {};\n\nexport function configureCar(carConfig: CarConfig) {\n  config = carConfig;\n}\n\nasync function getHelia() {\n  if (helia) return helia;\n\n  const BlockstoreClass = createBlockstore();\n  const DatastoreClass = createUnstorageDatastore();\n\n  blockstore = new BlockstoreClass({\n    prefix: \"pinner-helia-blocks\",\n    base: config.datastoreName,\n  });\n  datastore =\n    config.datastore ||\n    new DatastoreClass({\n      prefix: \"pinner-helia-data\",\n      base: config.datastoreName,\n    });\n\n  helia = await createHeliaHTTP({\n    blockstore,\n    datastore,\n  });\n\n  return helia;\n}\n\nasync function cleanupHelia() {\n  if (datastore?.close) {\n    await datastore.close();\n  }\n  helia = null;\n  blockstore = null;\n  datastore = null;\n}\n\nasync function* fileSource(\n  files: File[],\n  onProgress?: (percentage: number) => void,\n  signal?: AbortSignal,\n): AsyncGenerator<{\n  content: AsyncIterable<Uint8Array> | undefined;\n  path: string;\n}> {\n  const seenDirs = new Set<string>();\n  let totalBytes = 0n;\n  let processedBytes = 0n;\n\n  for (const file of files) {\n    totalBytes += BigInt(file.size);\n  }\n\n  for (const file of files) {\n    if (signal?.aborted) {\n      throw new Error(\"Aborted\");\n    }\n\n    const fullPath = (file as any).webkitRelativePath ?? file.name;\n\n    if (fullPath.includes(\"/.\")) {\n      continue;\n    }\n\n    const parts = fullPath.split(\"/\").filter((part: string) => part.length > 0);\n\n    for (let i = 1; i < parts.length; i++) {\n      if (signal?.aborted) {\n        throw new Error(\"Aborted\");\n      }\n\n      const dirPath = parts.slice(0, i).join(\"/\");\n\n      if (!seenDirs.has(dirPath)) {\n        seenDirs.add(dirPath);\n        yield {\n          content: (async function* () {})(),\n          path: dirPath,\n        };\n      }\n    }\n\n    yield {\n      content: readableStreamToAsyncIterable(file.stream()),\n      path: fullPath,\n    };\n\n    if (onProgress && totalBytes > 0n) {\n      processedBytes += BigInt(file.size);\n      const progressPercent = Number((processedBytes * 100n) / totalBytes);\n      onProgress(progressPercent);\n    }\n  }\n}\n\nexport async function preprocessToCar(\n  input: File | ReadableStream<Uint8Array> | File[],\n  options?: CarPreprocessOptions,\n): Promise<CarPreprocessResult> {\n  let files: File[];\n\n  if (input instanceof ReadableStream) {\n    const [streamForSize, streamForFile] = input.tee();\n    const size = await calculateStreamSize(streamForSize, options?.signal);\n    const streamBlob = await streamToBlob(\n      streamForFile,\n      \"application/octet-stream\",\n    );\n    files = [\n      new File([streamBlob], options?.name || \"upload\", {\n        type: streamBlob.type,\n      }),\n    ];\n  } else if (Array.isArray(input)) {\n    files = input;\n  } else {\n    files = [input];\n  }\n\n  // wrapWithDirectory must be true for directory uploads (File[] input) so the\n  // last addAll yield is the root directory CID, not a child file/subdirectory.\n  // Single files don't need wrapping. Matches Go SDK wrapInDir behavior.\n  const wrapWithDirectory = Array.isArray(input);\n\n  const heliaInstance = await getHelia();\n  const fs = unixfs(heliaInstance);\n  const c = car(heliaInstance);\n\n  let rootCid: CID | undefined;\n  let blocksCount = 0n;\n\n  const src = fileSource(files, options?.onProgress, options?.signal);\n\n  let hasFiles = false;\n  for await (const result of fs.addAll(src, {\n    cidVersion: 1,\n    rawLeaves: false,\n    wrapWithDirectory,\n    signal: options?.signal,\n    onProgress(event) {\n      if (event.type === \"blocks:put:blockstore:put\") {\n        blocksCount++;\n      }\n    },\n  })) {\n    if (options?.signal?.aborted) {\n      throw new Error(\"Aborted\");\n    }\n    rootCid = result.cid;\n    hasFiles = true;\n  }\n\n  if (!hasFiles || !rootCid) {\n    throw new Error(\"No files to process\");\n  }\n\n  // c.export() now returns an async generator directly (was renamed from 'stream')\n  const carAsyncGenerator = c.export(rootCid!, { signal: options?.signal });\n  const carStream = asyncGeneratorToReadableStream(carAsyncGenerator);\n\n  // Use stream tee to create two identical streams - one for size calculation, one for processing\n  const [streamForSize, streamForProcessing] = carStream.tee();\n\n  const size = await calculateStreamSize(streamForSize, options?.signal);\n\n  return {\n    carStream: streamForProcessing,\n    rootCid: rootCid!.toString(),\n    size,\n  };\n}\n\nexport async function isCarFile(file: File): Promise<boolean> {\n  if (file.type !== MIME_TYPE_CAR && !file.name.endsWith(FILE_EXTENSION_CAR)) {\n    return false;\n  }\n\n  try {\n    const iterable = readableStreamToAsyncIterable(file.stream());\n    const reader = await CarReader.fromIterable(iterable);\n    const roots = await reader.getRoots();\n    return roots.length > 0;\n  } catch {\n    return false;\n  }\n}\n\nexport async function destroyCarPreprocessor() {\n  await cleanupHelia();\n}\n"],"mappings":"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"}
+{"version":3,"file":"car.js","names":["createUnstorageDatastore"],"sources":["../../../src/upload/car.ts"],"sourcesContent":["import { car } from \"@helia/car\";\nimport { createHeliaHTTP } from \"@helia/http\";\nimport { unixfs } from \"@helia/unixfs\";\nimport {\n  createBlockstore,\n  createDatastore as createUnstorageDatastore,\n} from \"@/blockstore\";\nimport type { CID } from \"multiformats/cid\";\nimport { CarReader } from \"@ipld/car\";\nimport type { Datastore } from \"interface-datastore\";\n\nimport {\n  asyncGeneratorToReadableStream,\n  calculateStreamSize,\n  readableStreamToAsyncIterable,\n  streamToBlob,\n} from \"@/utils/stream\";\nimport { FILE_EXTENSION_CAR, MIME_TYPE_CAR } from \"@/types/mime-types\";\n\nexport interface CarPreprocessOptions {\n  /**\n   * Name for the pin or filter\n   */\n  name?: string;\n  /**\n   * Progress callback for preprocessing\n   */\n  onProgress?: (percentage: number) => void;\n  /**\n   * AbortSignal to cancel the operation\n   */\n  signal?: AbortSignal;\n}\n\nexport interface CarPreprocessResult {\n  /**\n   * Preprocessed CAR data as a readable stream\n   */\n  carStream: ReadableStream<Uint8Array>;\n  /**\n   * Root CID of the CAR file\n   */\n  rootCid: string;\n  /**\n   * Size in bytes\n   */\n  size: bigint;\n}\n\nexport interface CarConfig {\n  /**\n   * Custom datastore instance for Helia.\n   * If provided, this datastore will be used directly without creating one from storage.\n   * Highest priority - takes precedence over storage and datastoreName.\n   */\n  datastore?: Datastore;\n\n  /**\n   * Custom base name for Helia storage.\n   * Passed as the `base` option to both blockstore and datastore storage instances.\n   * Only used when datastore is not provided.\n   * @default \"pinner-helia-data\"\n   */\n  datastoreName?: string;\n}\n\nlet helia: any = null;\nlet blockstore: any = null;\nlet datastore: any = null;\nlet config: CarConfig = {};\n\nexport function configureCar(carConfig: CarConfig) {\n  config = carConfig;\n}\n\nasync function getHelia() {\n  if (helia) return helia;\n\n  const BlockstoreClass = createBlockstore();\n  const DatastoreClass = createUnstorageDatastore();\n\n  blockstore = new BlockstoreClass({\n    prefix: \"pinner-helia-blocks\",\n    base: config.datastoreName,\n  });\n  datastore =\n    config.datastore ||\n    new DatastoreClass({\n      prefix: \"pinner-helia-data\",\n      base: config.datastoreName,\n    });\n\n  helia = await createHeliaHTTP({\n    blockstore,\n    datastore,\n  });\n\n  return helia;\n}\n\nasync function cleanupHelia() {\n  if (datastore?.close) {\n    await datastore.close();\n  }\n  helia = null;\n  blockstore = null;\n  datastore = null;\n}\n\nasync function* fileSource(\n  files: File[],\n  onProgress?: (percentage: number) => void,\n  signal?: AbortSignal,\n): AsyncGenerator<{\n  content: AsyncIterable<Uint8Array> | undefined;\n  /**\n   * File path within the pin\n   */\n  path: string;\n}> {\n  const seenDirs = new Set<string>();\n  let totalBytes = 0n;\n  let processedBytes = 0n;\n\n  for (const file of files) {\n    totalBytes += BigInt(file.size);\n  }\n\n  for (const file of files) {\n    if (signal?.aborted) {\n      throw new Error(\"Aborted\");\n    }\n\n    const fullPath = (file as any).webkitRelativePath ?? file.name;\n\n    if (fullPath.includes(\"/.\")) {\n      continue;\n    }\n\n    const parts = fullPath.split(\"/\").filter((part: string) => part.length > 0);\n\n    for (let i = 1; i < parts.length; i++) {\n      if (signal?.aborted) {\n        throw new Error(\"Aborted\");\n      }\n\n      const dirPath = parts.slice(0, i).join(\"/\");\n\n      if (!seenDirs.has(dirPath)) {\n        seenDirs.add(dirPath);\n        yield {\n          content: (async function* () {})(),\n          path: dirPath,\n        };\n      }\n    }\n\n    yield {\n      content: readableStreamToAsyncIterable(file.stream()),\n      path: fullPath,\n    };\n\n    if (onProgress && totalBytes > 0n) {\n      processedBytes += BigInt(file.size);\n      const progressPercent = Number((processedBytes * 100n) / totalBytes);\n      onProgress(progressPercent);\n    }\n  }\n}\n\nexport async function preprocessToCar(\n  input: File | ReadableStream<Uint8Array> | File[],\n  options?: CarPreprocessOptions,\n): Promise<CarPreprocessResult> {\n  let files: File[];\n\n  if (input instanceof ReadableStream) {\n    const [streamForSize, streamForFile] = input.tee();\n    const size = await calculateStreamSize(streamForSize, options?.signal);\n    const streamBlob = await streamToBlob(\n      streamForFile,\n      \"application/octet-stream\",\n    );\n    files = [\n      new File([streamBlob], options?.name || \"upload\", {\n        type: streamBlob.type,\n      }),\n    ];\n  } else if (Array.isArray(input)) {\n    files = input;\n  } else {\n    files = [input];\n  }\n\n  // wrapWithDirectory must be true for directory uploads (File[] input) so the\n  // last addAll yield is the root directory CID, not a child file/subdirectory.\n  // Single files don't need wrapping. Matches Go SDK wrapInDir behavior.\n  const wrapWithDirectory = Array.isArray(input);\n\n  const heliaInstance = await getHelia();\n  const fs = unixfs(heliaInstance);\n  const c = car(heliaInstance);\n\n  let rootCid: CID | undefined;\n  let blocksCount = 0n;\n\n  const src = fileSource(files, options?.onProgress, options?.signal);\n\n  let hasFiles = false;\n  for await (const result of fs.addAll(src, {\n    cidVersion: 1,\n    rawLeaves: false,\n    wrapWithDirectory,\n    signal: options?.signal,\n    onProgress(event) {\n      if (event.type === \"blocks:put:blockstore:put\") {\n        blocksCount++;\n      }\n    },\n  })) {\n    if (options?.signal?.aborted) {\n      throw new Error(\"Aborted\");\n    }\n    rootCid = result.cid;\n    hasFiles = true;\n  }\n\n  if (!hasFiles || !rootCid) {\n    throw new Error(\"No files to process\");\n  }\n\n  // c.export() now returns an async generator directly (was renamed from 'stream')\n  const carAsyncGenerator = c.export(rootCid!, { signal: options?.signal });\n  const carStream = asyncGeneratorToReadableStream(carAsyncGenerator);\n\n  // Use stream tee to create two identical streams - one for size calculation, one for processing\n  const [streamForSize, streamForProcessing] = carStream.tee();\n\n  const size = await calculateStreamSize(streamForSize, options?.signal);\n\n  return {\n    carStream: streamForProcessing,\n    rootCid: rootCid!.toString(),\n    size,\n  };\n}\n\nexport async function isCarFile(file: File): Promise<boolean> {\n  if (file.type !== MIME_TYPE_CAR && !file.name.endsWith(FILE_EXTENSION_CAR)) {\n    return false;\n  }\n\n  try {\n    const iterable = readableStreamToAsyncIterable(file.stream());\n    const reader = await CarReader.fromIterable(iterable);\n    const roots = await reader.getRoots();\n    return roots.length > 0;\n  } catch {\n    return false;\n  }\n}\n\nexport async function destroyCarPreprocessor() {\n  await cleanupHelia();\n}\n"],"mappings":"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"}

package/dist/esm/upload/manager.d.ts

@@ -1,20 +1,46 @@
 import { PinnerConfig } from "../config.js";
+import { AuthManager } from "../auth/manager.js";
 import { UploadInput, UploadOperation, UploadOptions, UploadResult } from "../types/upload.js";
 import { OperationPollingOptions } from "@lumeweb/portal-sdk";
 
 //#region src/upload/manager.d.ts
+/**
+ * Handles file uploads via XHR or TUS protocol based on file size.
+ */
 declare class UploadManager {
   #private;
   private config;
+  private readonly auth;
   private xhrHandler;
   private tusHandler;
   private portalSdk;
   private uploadLimit;
   private limitFetched;
-  constructor(config: PinnerConfig);
+  /**
+   * Create a new UploadManager.
+   * @param config SDK configuration
+   * @param auth AuthManager for authentication
+   */
+  constructor(config: PinnerConfig, auth: AuthManager);
+  /**
+   * Fetch the upload size limit from the API. Falls back to 100 MB on failure.
+   */
   fetchUploadLimit(): Promise<number>;
+  /**
+   * Get the cached upload size limit (in bytes). Call fetchUploadLimit() first.
+   */
   getUploadLimit(): number;
+  /**
+   * Upload a file or stream to IPFS.
+   * @param input File, stream, or upload object
+   * @param options Upload configuration
+   */
   upload(input: UploadInput, options?: UploadOptions): Promise<UploadOperation>;
+  /**
+   * Upload a CAR file or stream directly without preprocessing.
+   * @param input CAR file or stream
+   * @param options Upload configuration
+   */
   uploadCar(input: File | ReadableStream<Uint8Array>, options?: UploadOptions): Promise<UploadOperation>;
   /**
    * Wait for an operation to complete or reach a settled state.
@@ -28,6 +54,11 @@ declare class UploadManager {
    * @returns UploadResult with operation status merged in
    */
   waitForOperation(input: number | UploadResult, options?: OperationPollingOptions): Promise<UploadResult>;
+  /**
+   * Upload an array of files as an IPFS directory.
+   * @param files Files to upload
+   * @param options Upload configuration
+   */
   uploadDirectory(files: File[], options?: UploadOptions): Promise<UploadOperation>;
   destroy(): void;
 }

package/dist/esm/upload/manager.js

@@ -10,23 +10,37 @@ import { AccountError, OPERATION_STATUS, Sdk, poll } from "@lumeweb/portal-sdk";
 import { createEqFilter } from "@lumeweb/query-builder";
 
 //#region src/upload/manager.ts
+/**
+* Handles file uploads via XHR or TUS protocol based on file size.
+*/
 var UploadManager = class {
 	config;
+	auth;
 	xhrHandler;
 	tusHandler;
 	portalSdk;
 	uploadLimit = TUS_SIZE_THRESHOLD;
 	limitFetched = false;
-	constructor(config) {
+	/**
+	* Create a new UploadManager.
+	* @param config SDK configuration
+	* @param auth AuthManager for authentication
+	*/
+	constructor(config, auth) {
 		this.config = config;
-		this.xhrHandler = new XHRUploadHandler(config);
-		this.tusHandler = new TUSUploadHandler(config);
+		this.auth = auth;
+		this.xhrHandler = new XHRUploadHandler(config, auth);
+		this.tusHandler = new TUSUploadHandler(config, auth);
 		this.portalSdk = new Sdk(config.endpoint || "https://ipfs.pinner.xyz");
+		this.portalSdk.setAuthToken(auth.getAuthToken());
 		configureCar({
 			datastoreName: config.datastoreName,
 			datastore: config.datastore
 		});
 	}
+	/**
+	* Fetch the upload size limit from the API. Falls back to 100 MB on failure.
+	*/
 	async fetchUploadLimit() {
 		if (this.limitFetched) return this.uploadLimit;
 		try {
@@ -38,13 +52,26 @@ var UploadManager = class {
 		this.limitFetched = true;
 		return this.uploadLimit;
 	}
+	/**
+	* Get the cached upload size limit (in bytes). Call fetchUploadLimit() first.
+	*/
 	getUploadLimit() {
 		return this.uploadLimit;
 	}
+	/**
+	* Upload a file or stream to IPFS.
+	* @param input File, stream, or upload object
+	* @param options Upload configuration
+	*/
 	async upload(input, options) {
 		this.#validateInput(input, options);
 		return this.#uploadInput(input, options);
 	}
+	/**
+	* Upload a CAR file or stream directly without preprocessing.
+	* @param input CAR file or stream
+	* @param options Upload configuration
+	*/
 	async uploadCar(input, options) {
 		this.#validateInput(input, options);
 		return this.#uploadCarFile(input, options);
@@ -140,7 +167,7 @@ var UploadManager = class {
 		const uploadId = uploadResult.id;
 		if (!uploadId) throw new Error("No upload ID available to poll for upload result");
 		const fetchUrl = `${this.config.endpoint || "https://ipfs.pinner.xyz"}/api/upload/result/${encodeURIComponent(uploadId)}`;
-		const headers = { Authorization: `Bearer ${this.config.jwt}` };
+		const headers = this.auth.getAuthHeaders();
 		const result = await poll(async () => {
 			const response = await fetch(fetchUrl, { headers });
 			if (response.status === 404) return {
@@ -173,6 +200,11 @@ var UploadManager = class {
 			if (options?.size !== void 0 && options.size === 0) throw new EmptyFileError("Cannot upload empty stream");
 		}
 	}
+	/**
+	* Upload an array of files as an IPFS directory.
+	* @param files Files to upload
+	* @param options Upload configuration
+	*/
 	async uploadDirectory(files, options) {
 		const carResult = await preprocessToCar(files, {
 			onProgress: options?.onProgress ? (p) => options.onProgress({