@lumeweb/pinner 0.0.1 → 0.1.0

package/dist/cjs/types/upload.d.cts

@@ -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.cts.map

package/dist/cjs/upload/base-upload.cjs

@@ -0,0 +1,135 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_normalize = require('./normalize.cjs');
+const require_env = require('../utils/env.cjs');
+const require_stream = require('../utils/stream.cjs');
+const require_constants = require('./constants.cjs');
+let _uppy_core = require("@uppy/core");
+_uppy_core = require_rolldown_runtime.__toESM(_uppy_core);
+let p_defer = require("p-defer");
+p_defer = require_rolldown_runtime.__toESM(p_defer);
+
+//#region src/upload/base-upload.ts
+var BaseUploadHandler = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	async upload(input, options) {
+		const normalized = require_normalize.normalizeUploadInput(input, options);
+		const uppy = new _uppy_core.default();
+		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 } = (0, p_defer.default)();
+		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 (require_env.isNodeEnvironment()) return this.#normalizeDataForNode(data);
+		return this.#normalizeDataForBrowser(data);
+	}
+	async #normalizeDataForBrowser(data) {
+		if (this.getUploadSource() === require_constants.UPLOAD_SOURCE_TUS) {
+			if (data instanceof ReadableStream) {
+				const { streamToBlobViaResponse } = await Promise.resolve().then(() => require("../utils/stream.cjs"));
+				return streamToBlobViaResponse(data);
+			}
+			return data;
+		}
+		return data;
+	}
+	async #normalizeDataForNode(data) {
+		if (this.getUploadSource() === require_constants.UPLOAD_SOURCE_XHR) return data;
+		if (data instanceof File) return await require_stream.readableStreamToNodeStream(require_stream.fileToReadableStream(data));
+		if (data instanceof ReadableStream) return await require_stream.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() === require_constants.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
+exports.BaseUploadHandler = BaseUploadHandler;
+//# sourceMappingURL=base-upload.cjs.map

package/dist/cjs/upload/base-upload.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-upload.cjs","names":["normalizeUploadInput","Uppy","#setupUppyHandlers","#addFileToUppy","#startUpload","#createUploadOperation","#extractErrorMessage","#normalizeData","isNodeEnvironment","#normalizeDataForNode","#normalizeDataForBrowser","UPLOAD_SOURCE_TUS","UPLOAD_SOURCE_XHR","readableStreamToNodeStream","fileToReadableStream"],"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/cjs/upload/builder.cjs

@@ -0,0 +1,174 @@
+const require_json = require('../encoder/json.cjs');
+const require_base64 = require('../encoder/base64.cjs');
+const require_url = require('../encoder/url.cjs');
+const require_csv = require('../encoder/csv.cjs');
+const require_text = require('../encoder/text.cjs');
+require('../encoder/index.cjs');
+const require_validation = require('../utils/validation.cjs');
+
+//#region src/upload/builder.ts
+/**
+* Base upload builder with common name/keyvalues functionality.
+*/
+var BaseUploadBuilder = class {
+	_name;
+	_keyvalues;
+	_waitForOperation;
+	_operationPollingOptions;
+	constructor(pinner) {
+		this.pinner = pinner;
+	}
+	name(name) {
+		this._name = name;
+		return this;
+	}
+	keyvalues(kv) {
+		this._keyvalues = kv;
+		return this;
+	}
+	waitForOperation(wait = true) {
+		this._waitForOperation = wait;
+		return this;
+	}
+	operationPollingOptions(options) {
+		this._operationPollingOptions = options;
+		return this;
+	}
+	buildOptions() {
+		const options = {};
+		if (this._name !== void 0) options.name = this._name;
+		if (this._keyvalues !== void 0) options.keyvalues = this._keyvalues;
+		if (this._waitForOperation !== void 0) options.waitForOperation = this._waitForOperation;
+		if (this._operationPollingOptions !== void 0) options.operationPollingOptions = this._operationPollingOptions;
+		return options;
+	}
+};
+/**
+* File upload builder.
+*/
+var FileUploadBuilder = class extends BaseUploadBuilder {
+	constructor(pinner, file) {
+		super(pinner);
+		this.file = file;
+	}
+	async pin() {
+		return this.pinner.upload(this.file, this.buildOptions());
+	}
+};
+/**
+* Encoded upload builder - handles JSON, Base64, and URL uploads using encoders.
+*/
+var EncodedUploadBuilder = class extends BaseUploadBuilder {
+	constructor(pinner, encoderFn) {
+		super(pinner);
+		this.encoderFn = encoderFn;
+	}
+	async pin() {
+		const encoded = await this.encoderFn(this._name, this._keyvalues);
+		return this.pinner.upload(encoded.file, encoded.options);
+	}
+};
+/**
+* Raw CAR upload builder - handles raw CAR file uploads without preprocessing.
+*/
+var RawUploadBuilder = class extends BaseUploadBuilder {
+	constructor(pinner, carInput) {
+		super(pinner);
+		this.carInput = carInput;
+	}
+	async pin() {
+		return this.pinner.uploadCar(this.carInput, this.buildOptions());
+	}
+};
+/**
+* Pinner upload builder namespace.
+* Provides fluent API for file, JSON, Base64, and URL uploads.
+*/
+var UploadBuilderNamespace = class {
+	constructor(pinner) {
+		this.pinner = pinner;
+	}
+	/**
+	* Upload a file.
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	file(file) {
+		return new FileUploadBuilder(this.pinner, file);
+	}
+	/**
+	* Upload JSON data (encoded as JSON file).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	json(data) {
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => require_json.jsonToFile(data, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Upload Base64 encoded content (decoded and uploaded as file).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	base64(base64String) {
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => require_base64.base64ToFile(base64String, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Upload content from a URL (fetched and uploaded as file).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	url(urlString) {
+		require_validation.validateUrl(urlString);
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => require_url.urlToFile(urlString, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Upload CSV data (string, array of objects, or array of arrays).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	csv(data) {
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => require_csv.csvToFile(data, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Upload raw CAR data without preprocessing.
+	* Useful for passthrough of pre-generated CAR files.
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	raw(carInput) {
+		return new RawUploadBuilder(this.pinner, carInput);
+	}
+	/**
+	* Upload text content (encoded as text file).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	text(textData) {
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => require_text.textToFile(textData, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Alias for text() - upload text content.
+	*/
+	get content() {
+		return (textData) => this.text(textData);
+	}
+};
+/**
+* Create a Pinner upload builder namespace.
+*/
+function createUploadBuilderNamespace(pinner) {
+	return new UploadBuilderNamespace(pinner);
+}
+
+//#endregion
+exports.UploadBuilderNamespace = UploadBuilderNamespace;
+exports.createUploadBuilderNamespace = createUploadBuilderNamespace;
+//# sourceMappingURL=builder.cjs.map

package/dist/cjs/upload/builder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.cjs","names":["jsonToFile","base64ToFile","urlToFile","csvToFile","textToFile"],"sources":["../../../src/upload/builder.ts"],"sourcesContent":["import type { Pinner } from \"@/pinner\";\nimport type {\n  PinnerUploadBuilder,\n  UploadOperation,\n  UploadOptions,\n} from \"@/types/upload\";\nimport type { OperationPollingOptions } from \"@lumeweb/portal-sdk\";\nimport {\n  base64ToFile,\n  csvToFile,\n  jsonToFile,\n  textToFile,\n  urlToFile,\n} from \"@/encoder\";\nimport { validateUrl } from \"@/utils/validation\";\n\n/**\n * Base upload builder with common name/keyvalues functionality.\n */\nabstract class BaseUploadBuilder implements PinnerUploadBuilder {\n  protected _name?: string;\n  protected _keyvalues?: Record<string, string>;\n  protected _waitForOperation?: boolean;\n  protected _operationPollingOptions?: OperationPollingOptions;\n\n  constructor(protected pinner: Pinner) {}\n\n  name(name: string): this {\n    this._name = name;\n    return this;\n  }\n\n  keyvalues(kv: Record<string, string>): this {\n    this._keyvalues = kv;\n    return this;\n  }\n\n  waitForOperation(wait: boolean = true): this {\n    this._waitForOperation = wait;\n    return this;\n  }\n\n  operationPollingOptions(options: OperationPollingOptions): this {\n    this._operationPollingOptions = options;\n    return this;\n  }\n\n  abstract pin(): Promise<UploadOperation>;\n\n  protected buildOptions(): UploadOptions {\n    const options: UploadOptions = {};\n    if (this._name !== undefined) {\n      options.name = this._name;\n    }\n    if (this._keyvalues !== undefined) {\n      options.keyvalues = this._keyvalues;\n    }\n    if (this._waitForOperation !== undefined) {\n      options.waitForOperation = this._waitForOperation;\n    }\n    if (this._operationPollingOptions !== undefined) {\n      options.operationPollingOptions = this._operationPollingOptions;\n    }\n    return options;\n  }\n}\n\n/**\n * File upload builder.\n */\nclass FileUploadBuilder extends BaseUploadBuilder {\n  constructor(\n    pinner: Pinner,\n    private file: File,\n  ) {\n    super(pinner);\n  }\n\n  async pin(): Promise<UploadOperation> {\n    return this.pinner.upload(this.file, this.buildOptions());\n  }\n}\n\n/**\n * Encoded upload builder - handles JSON, Base64, and URL uploads using encoders.\n */\nclass EncodedUploadBuilder extends BaseUploadBuilder {\n  constructor(\n    pinner: Pinner,\n    private encoderFn: (\n      name?: string,\n      keyvalues?: Record<string, string>,\n    ) => Promise<{ file: File; options: UploadOptions }>,\n  ) {\n    super(pinner);\n  }\n\n  async pin(): Promise<UploadOperation> {\n    const encoded = await this.encoderFn(this._name, this._keyvalues);\n    return this.pinner.upload(encoded.file, encoded.options);\n  }\n}\n\n/**\n * Raw CAR upload builder - handles raw CAR file uploads without preprocessing.\n */\nclass RawUploadBuilder extends BaseUploadBuilder {\n  constructor(\n    pinner: Pinner,\n    private carInput: File | ReadableStream<Uint8Array>,\n  ) {\n    super(pinner);\n  }\n\n  async pin(): Promise<UploadOperation> {\n    return this.pinner.uploadCar(this.carInput, this.buildOptions());\n  }\n}\n\n/**\n * Pinner upload builder namespace.\n * Provides fluent API for file, JSON, Base64, and URL uploads.\n */\nexport class UploadBuilderNamespace {\n  constructor(private pinner: Pinner) {}\n\n  /**\n   * Upload a file.\n   * Returns a builder for chaining name/keyvalues.\n   */\n  file(file: File): PinnerUploadBuilder {\n    return new FileUploadBuilder(this.pinner, file);\n  }\n\n  /**\n   * Upload JSON data (encoded as JSON file).\n   * Returns a builder for chaining name/keyvalues.\n   */\n  json(data: object): PinnerUploadBuilder {\n    return new EncodedUploadBuilder(this.pinner, (name, keyvalues) =>\n      jsonToFile(data, { name, keyvalues }),\n    );\n  }\n\n  /**\n   * Upload Base64 encoded content (decoded and uploaded as file).\n   * Returns a builder for chaining name/keyvalues.\n   */\n  base64(base64String: string): PinnerUploadBuilder {\n    return new EncodedUploadBuilder(this.pinner, (name, keyvalues) =>\n      base64ToFile(base64String, { name, keyvalues }),\n    );\n  }\n\n  /**\n   * Upload content from a URL (fetched and uploaded as file).\n   * Returns a builder for chaining name/keyvalues.\n   */\n  url(urlString: string): PinnerUploadBuilder {\n    // Validate URL to prevent SSRF attacks\n    validateUrl(urlString);\n\n    return new EncodedUploadBuilder(this.pinner, (name, keyvalues) =>\n      urlToFile(urlString, { name, keyvalues }),\n    );\n  }\n\n  /**\n   * Upload CSV data (string, array of objects, or array of arrays).\n   * Returns a builder for chaining name/keyvalues.\n   */\n  csv(data: string | object[] | any[][]): PinnerUploadBuilder {\n    return new EncodedUploadBuilder(this.pinner, (name, keyvalues) =>\n      csvToFile(data, { name, keyvalues }),\n    );\n  }\n\n  /**\n   * Upload raw CAR data without preprocessing.\n   * Useful for passthrough of pre-generated CAR files.\n   * Returns a builder for chaining name/keyvalues.\n   */\n  raw(carInput: File | ReadableStream<Uint8Array>): PinnerUploadBuilder {\n    return new RawUploadBuilder(this.pinner, carInput);\n  }\n\n  /**\n   * Upload text content (encoded as text file).\n   * Returns a builder for chaining name/keyvalues.\n   */\n  text(textData: string): PinnerUploadBuilder {\n    return new EncodedUploadBuilder(this.pinner, (name, keyvalues) =>\n      textToFile(textData, { name, keyvalues }),\n    );\n  }\n\n  /**\n   * Alias for text() - upload text content.\n   */\n  get content(): (textData: string) => PinnerUploadBuilder {\n    return (textData: string) => this.text(textData);\n  }\n}\n\n/**\n * Create a Pinner upload builder namespace.\n */\nexport function createUploadBuilderNamespace(\n  pinner: Pinner,\n): UploadBuilderNamespace {\n  return new UploadBuilderNamespace(pinner);\n}\n\n/**\n * Combined interface for upload that works as both a method and a builder namespace.\n */\nexport type UploadMethodAndBuilder = ((\n  file: File,\n  options?: UploadOptions,\n) => Promise<UploadOperation>) &\n  UploadBuilderNamespace;\n\n/**\n * Export PinnerUploadBuilder for external use.\n */\nexport type { PinnerUploadBuilder };\n"],"mappings":";;;;;;;;;;;;AAmBA,IAAe,oBAAf,MAAgE;CAC9D,AAAU;CACV,AAAU;CACV,AAAU;CACV,AAAU;CAEV,YAAY,AAAU,QAAgB;EAAhB;;CAEtB,KAAK,MAAoB;AACvB,OAAK,QAAQ;AACb,SAAO;;CAGT,UAAU,IAAkC;AAC1C,OAAK,aAAa;AAClB,SAAO;;CAGT,iBAAiB,OAAgB,MAAY;AAC3C,OAAK,oBAAoB;AACzB,SAAO;;CAGT,wBAAwB,SAAwC;AAC9D,OAAK,2BAA2B;AAChC,SAAO;;CAKT,AAAU,eAA8B;EACtC,MAAM,UAAyB,EAAE;AACjC,MAAI,KAAK,UAAU,OACjB,SAAQ,OAAO,KAAK;AAEtB,MAAI,KAAK,eAAe,OACtB,SAAQ,YAAY,KAAK;AAE3B,MAAI,KAAK,sBAAsB,OAC7B,SAAQ,mBAAmB,KAAK;AAElC,MAAI,KAAK,6BAA6B,OACpC,SAAQ,0BAA0B,KAAK;AAEzC,SAAO;;;;;;AAOX,IAAM,oBAAN,cAAgC,kBAAkB;CAChD,YACE,QACA,AAAQ,MACR;AACA,QAAM,OAAO;EAFL;;CAKV,MAAM,MAAgC;AACpC,SAAO,KAAK,OAAO,OAAO,KAAK,MAAM,KAAK,cAAc,CAAC;;;;;;AAO7D,IAAM,uBAAN,cAAmC,kBAAkB;CACnD,YACE,QACA,AAAQ,WAIR;AACA,QAAM,OAAO;EALL;;CAQV,MAAM,MAAgC;EACpC,MAAM,UAAU,MAAM,KAAK,UAAU,KAAK,OAAO,KAAK,WAAW;AACjE,SAAO,KAAK,OAAO,OAAO,QAAQ,MAAM,QAAQ,QAAQ;;;;;;AAO5D,IAAM,mBAAN,cAA+B,kBAAkB;CAC/C,YACE,QACA,AAAQ,UACR;AACA,QAAM,OAAO;EAFL;;CAKV,MAAM,MAAgC;AACpC,SAAO,KAAK,OAAO,UAAU,KAAK,UAAU,KAAK,cAAc,CAAC;;;;;;;AAQpE,IAAa,yBAAb,MAAoC;CAClC,YAAY,AAAQ,QAAgB;EAAhB;;;;;;CAMpB,KAAK,MAAiC;AACpC,SAAO,IAAI,kBAAkB,KAAK,QAAQ,KAAK;;;;;;CAOjD,KAAK,MAAmC;AACtC,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClDA,wBAAW,MAAM;GAAE;GAAM;GAAW,CAAC,CACtC;;;;;;CAOH,OAAO,cAA2C;AAChD,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClDC,4BAAa,cAAc;GAAE;GAAM;GAAW,CAAC,CAChD;;;;;;CAOH,IAAI,WAAwC;AAE1C,iCAAY,UAAU;AAEtB,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClDC,sBAAU,WAAW;GAAE;GAAM;GAAW,CAAC,CAC1C;;;;;;CAOH,IAAI,MAAwD;AAC1D,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClDC,sBAAU,MAAM;GAAE;GAAM;GAAW,CAAC,CACrC;;;;;;;CAQH,IAAI,UAAkE;AACpE,SAAO,IAAI,iBAAiB,KAAK,QAAQ,SAAS;;;;;;CAOpD,KAAK,UAAuC;AAC1C,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClDC,wBAAW,UAAU;GAAE;GAAM;GAAW,CAAC,CAC1C;;;;;CAMH,IAAI,UAAqD;AACvD,UAAQ,aAAqB,KAAK,KAAK,SAAS;;;;;;AAOpD,SAAgB,6BACd,QACwB;AACxB,QAAO,IAAI,uBAAuB,OAAO"}

package/dist/cjs/upload/builder.d.cts

@@ -0,0 +1,60 @@
+import { PinnerUploadBuilder, UploadOperation, UploadOptions } from "../types/upload.cjs";
+import { Pinner } from "../pinner.cjs";
+
+//#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.cts.map