@lumeweb/pinner 0.0.1 → 0.1.1

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

@@ -0,0 +1,78 @@
+import { CID } from "multiformats/cid";
+import { Status } from "@ipfs-shipyard/pinning-service-client";
+
+//#region src/types/pin.d.ts
+
+/**
+ * Options that can be passed to abort async operations
+ */
+interface AbortOptions {
+  signal?: AbortSignal;
+}
+/**
+ * Allows passing extra options accepted by the remote pinning service
+ */
+interface RemoteAddOptions extends AbortOptions {
+  name?: string;
+  metadata?: Record<string, string>;
+  origins?: string[];
+}
+/**
+ * Allows passing extra options accepted by the remote pinning service
+ */
+interface RemoteLsOptions extends AbortOptions {
+  name?: string;
+  status?: Status[];
+  limit?: number;
+  cursor?: string;
+}
+/**
+ * Includes extra metadata supported by the remote pinning service
+ */
+interface RemotePin {
+  cid: CID;
+  name?: string;
+  status: Status;
+  created: Date;
+  size?: number;
+  metadata?: Record<string, string>;
+}
+/**
+ * Extends the Pins interface with remote pinning-specific arguments and return
+ * types (e.g. metadata as `Record<string, string>` and pins with an added
+ * `.status` property)
+ */
+interface RemotePins {
+  /**
+   * Pin a block in the blockstore. It will not be deleted
+   * when garbage collection is run.
+   */
+  add(cid: CID, options?: RemoteAddOptions): AsyncGenerator<CID, void, undefined>;
+  /**
+   * List all blocks that have been pinned.
+   */
+  ls(options?: RemoteLsOptions): AsyncGenerator<RemotePin, void, undefined>;
+  /**
+   * Return true if the passed CID is pinned
+   */
+  isPinned(cid: CID, options?: AbortOptions): Promise<boolean>;
+  /**
+   * Return pin details
+   */
+  get(cid: CID, options?: AbortOptions): Promise<RemotePin>;
+  /**
+   * Update pin metadata
+   */
+  setMetadata(cid: CID, metadata: Record<string, string> | undefined, options?: AbortOptions): Promise<void>;
+  /**
+   * Remove a pin. The block may be deleted when garbage collection is run.
+   */
+  rm(cid: CID, options?: AbortOptions): AsyncGenerator<CID, void, undefined>;
+  /**
+   * Remove a pin by request ID. The block may be deleted when garbage collection is run.
+   */
+  rmByRequestId(requestId: string, options?: AbortOptions): Promise<void>;
+}
+//#endregion
+export { AbortOptions, RemoteAddOptions, RemoteLsOptions, RemotePin, RemotePins };
+//# sourceMappingURL=pin.d.ts.map

package/dist/esm/types/type-guards.d.ts

@@ -0,0 +1,15 @@
+import { PinnerError } from "../errors/index.js";
+
+//#region src/types/type-guards.d.ts
+
+/**
+ * Check if error is retryable.
+ */
+declare function isRetryable(error: PinnerError): boolean;
+/**
+ * Check if error is authentication-related.
+ */
+declare function isAuthenticationError(error: PinnerError): boolean;
+//#endregion
+export { isAuthenticationError, isRetryable };
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/esm/types/type-guards.js

@@ -0,0 +1,19 @@
+import { PinnerError } from "../errors/index.js";
+
+//#region src/types/type-guards.ts
+/**
+* Check if error is retryable.
+*/
+function isRetryable(error) {
+	return error.retryable;
+}
+/**
+* Check if error is authentication-related.
+*/
+function isAuthenticationError(error) {
+	return error instanceof PinnerError && error.code === "AUTHENTICATION_ERROR";
+}
+
+//#endregion
+export { isAuthenticationError, isRetryable };
+//# sourceMappingURL=type-guards.js.map

package/dist/esm/types/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","names":[],"sources":["../../../src/types/type-guards.ts"],"sourcesContent":["import { PinnerError } from \"../errors\";\n\n/**\n * Check if error is retryable.\n */\nexport function isRetryable(error: PinnerError): boolean {\n  return error.retryable;\n}\n\n/**\n * Check if error is authentication-related.\n */\nexport function isAuthenticationError(error: PinnerError): boolean {\n  return error instanceof PinnerError && error.code === \"AUTHENTICATION_ERROR\";\n}\n"],"mappings":";;;;;;AAKA,SAAgB,YAAY,OAA6B;AACvD,QAAO,MAAM;;;;;AAMf,SAAgB,sBAAsB,OAA6B;AACjE,QAAO,iBAAiB,eAAe,MAAM,SAAS"}

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

@@ -0,0 +1,189 @@
+import { OperationPollingOptions } from "@lumeweb/portal-sdk";
+
+//#region src/types/upload.d.ts
+
+/**
+ * Symbol used to brand UploadResult for type checking
+ */
+declare const UploadResultSymbol: unique symbol;
+interface UploadResult {
+  /**
+   * Unique identifier for this upload operation.
+   */
+  id: string;
+  /**
+   * IPFS Content Identifier for the uploaded content.
+   */
+  cid: string;
+  /**
+   * User-provided or auto-generated name for the content.
+   */
+  name: string;
+  /**
+   * Total size in bytes.
+   */
+  size: number;
+  /**
+   * MIME type of the content.
+   */
+  mimeType: string;
+  /**
+   * ISO timestamp when content was created.
+   */
+  createdAt: Date;
+  /**
+   * Number of files (1 for single file, N for directory).
+   */
+  numberOfFiles: number;
+  /**
+   * Custom key-value metadata.
+   */
+  keyvalues?: Record<string, string>;
+  /**
+   * Whether this upload is a directory.
+   */
+  isDirectory?: boolean;
+  /**
+   * Whether this upload is already a valid CAR file.
+   * If true, the upload system will skip CAR preprocessing and upload the file as-is.
+   * Useful for passthrough of pre-generated CAR files.
+   */
+  isCarFile?: boolean;
+  /**
+   * Portal operation ID for tracking the pinning operation.
+   * Can be used with waitForOperation() to wait for the operation to complete.
+   */
+  operationId?: number;
+  /**
+   * Symbol brand for type checking - used to identify UploadResult objects
+   */
+  [UploadResultSymbol]?: true;
+}
+type UploadInput = File | ReadableStream<Uint8Array>;
+interface UploadOptions {
+  /**
+   * Name for the uploaded content.
+   */
+  name?: string;
+  /**
+   * Custom key-value metadata.
+   */
+  keyvalues?: Record<string, string>;
+  /**
+   * Progress callback invoked during upload.
+   */
+  onProgress?: (progress: UploadProgress) => void;
+  /**
+   * Callback invoked when upload completes successfully.
+   */
+  onComplete?: (result: UploadResult) => void;
+  /**
+   * Callback invoked when upload fails.
+   */
+  onError?: (error: Error) => void;
+  /**
+   * AbortSignal for cancellation.
+   */
+  signal?: AbortSignal;
+  /**
+   * Optional size override for the upload input.
+   * Useful for ReadableStream inputs where size detection is difficult.
+   */
+  size?: number;
+  /**
+   * Whether this upload is a directory.
+   */
+  isDirectory?: boolean;
+  /**
+   * Whether this upload is already a valid CAR file.
+   * If true, the upload system will skip CAR preprocessing and upload the file as-is.
+   * Useful for passthrough of pre-generated CAR files.
+   */
+  isCarFile?: boolean;
+  /**
+   * Whether to wait for the pinning operation to complete/fail.
+   * When true, the upload will block until the operation reaches a settled state
+   * (completed, failed, or error). Default is false (upload only).
+   */
+  waitForOperation?: boolean;
+  /**
+   * Polling options for waiting on operation completion.
+   * Only used when waitForOperation is true.
+   */
+  operationPollingOptions?: OperationPollingOptions;
+}
+interface UploadProgress {
+  /**
+   * Percentage complete (0-100).
+   */
+  percentage: number;
+  /**
+   * Number of bytes uploaded.
+   */
+  bytesUploaded: number;
+  /**
+   * Total bytes to upload.
+   */
+  bytesTotal: number;
+  /**
+   * Upload speed in bytes per second.
+   */
+  speed?: number;
+  /**
+   * Estimated time remaining in seconds.
+   */
+  eta?: number;
+}
+interface UploadOperation {
+  /**
+   * Cancel the ongoing upload.
+   */
+  cancel(): void;
+  /**
+   * Pause the upload (TUS only).
+   */
+  pause(): void;
+  /**
+   * Resume a paused upload (TUS only).
+   */
+  resume(): void;
+  /**
+   * Promise that resolves when upload completes.
+   */
+  result: Promise<UploadResult>;
+  /**
+   * Current progress.
+   */
+  progress: Readonly<UploadProgress>;
+}
+/**
+ * Builder interface for Pinner upload API.
+ * Supports chaining name/keyvalues and returns UploadOperation with controls.
+ */
+interface PinnerUploadBuilder {
+  /**
+   * Set the name for the upload.
+   */
+  name(name: string): this;
+  /**
+   * Set custom key-value metadata.
+   */
+  keyvalues(kv: Record<string, string>): this;
+  /**
+   * Whether to wait for the pinning operation to complete/fail.
+   * When true, the upload will block until the operation reaches a settled state.
+   */
+  waitForOperation(wait: boolean): this;
+  /**
+   * Set polling options for waiting on operation completion.
+   * Only used when waitForOperation is true.
+   */
+  operationPollingOptions(options: OperationPollingOptions): this;
+  /**
+   * Start the upload and return UploadOperation with controls.
+   */
+  pin(): Promise<UploadOperation>;
+}
+//#endregion
+export { PinnerUploadBuilder, UploadInput, UploadOperation, UploadOptions, UploadProgress, UploadResult };
+//# sourceMappingURL=upload.d.ts.map

package/dist/esm/types/upload.js

@@ -0,0 +1,16 @@
+//#region src/types/upload.ts
+/**
+* Symbol used to brand UploadResult for type checking
+*/
+const UploadResultSymbol = Symbol("UploadResult");
+/**
+* Type guard to check if a value is an UploadResult
+* Uses the UploadResultSymbol for reliable type checking
+*/
+function isUploadResult(value) {
+	return typeof value === "object" && value !== null && UploadResultSymbol in value && value[UploadResultSymbol] === true;
+}
+
+//#endregion
+export { UploadResultSymbol, isUploadResult };
+//# sourceMappingURL=upload.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","names":[],"sources":["../../../src/types/upload.ts"],"sourcesContent":["import type { OperationPollingOptions } from \"@lumeweb/portal-sdk\";\n\n/**\n * Symbol used to brand UploadResult for type checking\n */\nexport const UploadResultSymbol = Symbol(\"UploadResult\");\n\nexport interface UploadResult {\n  /**\n   * Unique identifier for this upload operation.\n   */\n  id: string;\n\n  /**\n   * IPFS Content Identifier for the uploaded content.\n   */\n  cid: string;\n\n  /**\n   * User-provided or auto-generated name for the content.\n   */\n  name: string;\n\n  /**\n   * Total size in bytes.\n   */\n  size: number;\n\n  /**\n   * MIME type of the content.\n   */\n  mimeType: string;\n\n  /**\n   * ISO timestamp when content was created.\n   */\n  createdAt: Date;\n\n  /**\n   * Number of files (1 for single file, N for directory).\n   */\n  numberOfFiles: number;\n\n  /**\n   * Custom key-value metadata.\n   */\n  keyvalues?: Record<string, string>;\n\n  /**\n   * Whether this upload is a directory.\n   */\n  isDirectory?: boolean;\n\n  /**\n   * Whether this upload is already a valid CAR file.\n   * If true, the upload system will skip CAR preprocessing and upload the file as-is.\n   * Useful for passthrough of pre-generated CAR files.\n   */\n  isCarFile?: boolean;\n\n  /**\n   * Portal operation ID for tracking the pinning operation.\n   * Can be used with waitForOperation() to wait for the operation to complete.\n   */\n  operationId?: number;\n\n  /**\n   * Symbol brand for type checking - used to identify UploadResult objects\n   */\n  [UploadResultSymbol]?: true;\n}\n\nexport type UploadInput = File | ReadableStream<Uint8Array>;\n\n/**\n * Type guard to check if a value is an UploadResult\n * Uses the UploadResultSymbol for reliable type checking\n */\nexport function isUploadResult(value: unknown): value is UploadResult {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    UploadResultSymbol in value &&\n    value[UploadResultSymbol] === true\n  );\n}\n\nexport interface UploadOptions {\n  /**\n   * Name for the uploaded content.\n   */\n  name?: string;\n\n  /**\n   * Custom key-value metadata.\n   */\n  keyvalues?: Record<string, string>;\n\n  /**\n   * Progress callback invoked during upload.\n   */\n  onProgress?: (progress: UploadProgress) => void;\n\n  /**\n   * Callback invoked when upload completes successfully.\n   */\n  onComplete?: (result: UploadResult) => void;\n\n  /**\n   * Callback invoked when upload fails.\n   */\n  onError?: (error: Error) => void;\n\n  /**\n   * AbortSignal for cancellation.\n   */\n  signal?: AbortSignal;\n\n  /**\n   * Optional size override for the upload input.\n   * Useful for ReadableStream inputs where size detection is difficult.\n   */\n  size?: number;\n\n  /**\n   * Whether this upload is a directory.\n   */\n  isDirectory?: boolean;\n\n  /**\n   * Whether this upload is already a valid CAR file.\n   * If true, the upload system will skip CAR preprocessing and upload the file as-is.\n   * Useful for passthrough of pre-generated CAR files.\n   */\n  isCarFile?: boolean;\n\n  /**\n   * Whether to wait for the pinning operation to complete/fail.\n   * When true, the upload will block until the operation reaches a settled state\n   * (completed, failed, or error). Default is false (upload only).\n   */\n  waitForOperation?: boolean;\n\n  /**\n   * Polling options for waiting on operation completion.\n   * Only used when waitForOperation is true.\n   */\n  operationPollingOptions?: OperationPollingOptions;\n}\n\nexport interface UploadProgress {\n  /**\n   * Percentage complete (0-100).\n   */\n  percentage: number;\n\n  /**\n   * Number of bytes uploaded.\n   */\n  bytesUploaded: number;\n\n  /**\n   * Total bytes to upload.\n   */\n  bytesTotal: number;\n\n  /**\n   * Upload speed in bytes per second.\n   */\n  speed?: number;\n\n  /**\n   * Estimated time remaining in seconds.\n   */\n  eta?: number;\n}\n\nexport interface UploadOperation {\n  /**\n   * Cancel the ongoing upload.\n   */\n  cancel(): void;\n\n  /**\n   * Pause the upload (TUS only).\n   */\n  pause(): void;\n\n  /**\n   * Resume a paused upload (TUS only).\n   */\n  resume(): void;\n\n  /**\n   * Promise that resolves when upload completes.\n   */\n  result: Promise<UploadResult>;\n\n  /**\n   * Current progress.\n   */\n  progress: Readonly<UploadProgress>;\n}\n\n/**\n * Builder interface for Pinner upload API.\n * Supports chaining name/keyvalues and returns UploadOperation with controls.\n */\nexport interface PinnerUploadBuilder {\n  /**\n   * Set the name for the upload.\n   */\n  name(name: string): this;\n\n  /**\n   * Set custom key-value metadata.\n   */\n  keyvalues(kv: Record<string, string>): this;\n\n  /**\n   * Whether to wait for the pinning operation to complete/fail.\n   * When true, the upload will block until the operation reaches a settled state.\n   */\n  waitForOperation(wait: boolean): this;\n\n  /**\n   * Set polling options for waiting on operation completion.\n   * Only used when waitForOperation is true.\n   */\n  operationPollingOptions(options: OperationPollingOptions): this;\n\n  /**\n   * Start the upload and return UploadOperation with controls.\n   */\n  pin(): Promise<UploadOperation>;\n}\n"],"mappings":";;;;AAKA,MAAa,qBAAqB,OAAO,eAAe;;;;;AAyExD,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACV,sBAAsB,SACtB,MAAM,wBAAwB"}

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

@@ -0,0 +1,132 @@
+import { normalizeUploadInput } from "./normalize.js";
+import { isNodeEnvironment } from "../utils/env.js";
+import { fileToReadableStream, readableStreamToNodeStream } from "../utils/stream.js";
+import { UPLOAD_SOURCE_TUS, UPLOAD_SOURCE_XHR } from "./constants.js";
+import Uppy from "@uppy/core";
+import defer from "p-defer";
+
+//#region src/upload/base-upload.ts
+var BaseUploadHandler = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	async upload(input, options) {
+		const normalized = normalizeUploadInput(input, options);
+		const uppy = new Uppy();
+		const { fileId, resultPromise, progress } = this.#setupUppyHandlers(uppy, normalized, options);
+		await this.#addFileToUppy(uppy, normalized, normalized.size);
+		this.#startUpload(uppy, options);
+		return this.#createUploadOperation(uppy, fileId, resultPromise, progress);
+	}
+	#setupUppyHandlers(uppy, normalized, options) {
+		let fileId = null;
+		let hasRejected = false;
+		const progress = {
+			percentage: 0,
+			bytesUploaded: 0,
+			bytesTotal: normalized.size
+		};
+		const { promise: resultPromise, resolve: resolveResult, reject: rejectResult } = defer();
+		const handleError = (error) => {
+			if (hasRejected) return;
+			hasRejected = true;
+			options?.onError?.(error);
+			rejectResult(error);
+		};
+		this.configurePlugin(uppy);
+		uppy.on("progress", (progressBytes) => {
+			progress.bytesUploaded = progressBytes;
+			progress.percentage = progressBytes / progress.bytesTotal * 100;
+			options?.onProgress?.(progress);
+		});
+		uppy.on("upload-success", (_file, result) => {
+			if (hasRejected) return;
+			const uploadResult = this.parseResult(result);
+			options?.onComplete?.(uploadResult);
+			resolveResult(uploadResult);
+		});
+		uppy.on("error", (error) => {
+			handleError(new Error(this.#extractErrorMessage(error)));
+		});
+		uppy.on("file-added", (file) => {
+			fileId = file.id;
+		});
+		return {
+			fileId,
+			resultPromise,
+			progress
+		};
+	}
+	#extractErrorMessage(error) {
+		let errorMessage = "Upload fainormalizeDataled";
+		if (!error) return errorMessage;
+		if (typeof error === "string") errorMessage = error;
+		else if (error instanceof Error) errorMessage = error.message;
+		else if (error.message) errorMessage = error.message;
+		else if (error.toString && typeof error.toString === "function") errorMessage = error.toString();
+		const errorObj = error;
+		if (errorObj?.xhr?.response) try {
+			const response = typeof errorObj.xhr.response === "string" ? JSON.parse(errorObj.xhr.response) : errorObj.xhr.response;
+			if (response.error) errorMessage = response.error;
+			else if (response.message) errorMessage = response.message;
+		} catch {}
+		return errorMessage;
+	}
+	async #normalizeData(data) {
+		if (isNodeEnvironment()) return this.#normalizeDataForNode(data);
+		return this.#normalizeDataForBrowser(data);
+	}
+	async #normalizeDataForBrowser(data) {
+		if (this.getUploadSource() === UPLOAD_SOURCE_TUS) {
+			if (data instanceof ReadableStream) {
+				const { streamToBlobViaResponse } = await import("../utils/stream.js");
+				return streamToBlobViaResponse(data);
+			}
+			return data;
+		}
+		return data;
+	}
+	async #normalizeDataForNode(data) {
+		if (this.getUploadSource() === UPLOAD_SOURCE_XHR) return data;
+		if (data instanceof File) return await readableStreamToNodeStream(fileToReadableStream(data));
+		if (data instanceof ReadableStream) return await readableStreamToNodeStream(data);
+		return data;
+	}
+	async #addFileToUppy(uppy, normalized, size) {
+		const fileData = await this.#normalizeData(normalized.data);
+		const fileOptions = {
+			source: this.getUploadSource(),
+			name: normalized.name,
+			type: normalized.type,
+			data: fileData
+		};
+		const fileId = uppy.addFile(fileOptions);
+		if (this.getUploadSource() === UPLOAD_SOURCE_TUS && size !== void 0 && size > 0) uppy.setFileState(fileId, { tus: { uploadSize: size } });
+	}
+	#startUpload(uppy, options) {
+		uppy.upload().catch((error) => {
+			options?.onError?.(new Error(this.#extractErrorMessage(error)));
+		});
+	}
+	#createUploadOperation(uppy, fileId, resultPromise, progress) {
+		return {
+			cancel: () => {
+				uppy.cancelAll();
+			},
+			pause: () => {
+				if (fileId) uppy.pauseResume(fileId);
+			},
+			resume: () => {
+				if (fileId) uppy.pauseResume(fileId);
+			},
+			result: resultPromise,
+			progress: Object.freeze({ ...progress })
+		};
+	}
+	destroy() {}
+};
+
+//#endregion
+export { BaseUploadHandler };
+//# sourceMappingURL=base-upload.js.map

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

@@ -0,0 +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 { 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"],"mappings":"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"}

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

@@ -0,0 +1,60 @@
+import { PinnerUploadBuilder, UploadOperation, UploadOptions } from "../types/upload.js";
+import { Pinner } from "../pinner.js";
+
+//#region src/upload/builder.d.ts
+
+/**
+ * Pinner upload builder namespace.
+ * Provides fluent API for file, JSON, Base64, and URL uploads.
+ */
+declare class UploadBuilderNamespace {
+  private pinner;
+  constructor(pinner: Pinner);
+  /**
+   * Upload a file.
+   * Returns a builder for chaining name/keyvalues.
+   */
+  file(file: File): PinnerUploadBuilder;
+  /**
+   * Upload JSON data (encoded as JSON file).
+   * Returns a builder for chaining name/keyvalues.
+   */
+  json(data: object): PinnerUploadBuilder;
+  /**
+   * Upload Base64 encoded content (decoded and uploaded as file).
+   * Returns a builder for chaining name/keyvalues.
+   */
+  base64(base64String: string): PinnerUploadBuilder;
+  /**
+   * Upload content from a URL (fetched and uploaded as file).
+   * Returns a builder for chaining name/keyvalues.
+   */
+  url(urlString: string): PinnerUploadBuilder;
+  /**
+   * Upload CSV data (string, array of objects, or array of arrays).
+   * Returns a builder for chaining name/keyvalues.
+   */
+  csv(data: string | object[] | any[][]): PinnerUploadBuilder;
+  /**
+   * Upload raw CAR data without preprocessing.
+   * Useful for passthrough of pre-generated CAR files.
+   * Returns a builder for chaining name/keyvalues.
+   */
+  raw(carInput: File | ReadableStream<Uint8Array>): PinnerUploadBuilder;
+  /**
+   * Upload text content (encoded as text file).
+   * Returns a builder for chaining name/keyvalues.
+   */
+  text(textData: string): PinnerUploadBuilder;
+  /**
+   * Alias for text() - upload text content.
+   */
+  get content(): (textData: string) => PinnerUploadBuilder;
+}
+/**
+ * Combined interface for upload that works as both a method and a builder namespace.
+ */
+type UploadMethodAndBuilder = ((file: File, options?: UploadOptions) => Promise<UploadOperation>) & UploadBuilderNamespace;
+//#endregion
+export { UploadMethodAndBuilder };
+//# sourceMappingURL=builder.d.ts.map