@lumeweb/pinner 0.0.1 → 0.1.0

package/dist/esm/upload/builder.js

@@ -0,0 +1,173 @@
+import { jsonToFile } from "../encoder/json.js";
+import { base64ToFile } from "../encoder/base64.js";
+import { urlToFile } from "../encoder/url.js";
+import { csvToFile } from "../encoder/csv.js";
+import { textToFile } from "../encoder/text.js";
+import "../encoder/index.js";
+import { validateUrl } from "../utils/validation.js";
+
+//#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) => 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) => base64ToFile(base64String, {
+			name,
+			keyvalues
+		}));
+	}
+	/**
+	* Upload content from a URL (fetched and uploaded as file).
+	* Returns a builder for chaining name/keyvalues.
+	*/
+	url(urlString) {
+		validateUrl(urlString);
+		return new EncodedUploadBuilder(this.pinner, (name, keyvalues) => 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) => 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) => 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
+export { UploadBuilderNamespace, createUploadBuilderNamespace };
+//# sourceMappingURL=builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","names":[],"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,cAClD,WAAW,MAAM;GAAE;GAAM;GAAW,CAAC,CACtC;;;;;;CAOH,OAAO,cAA2C;AAChD,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClD,aAAa,cAAc;GAAE;GAAM;GAAW,CAAC,CAChD;;;;;;CAOH,IAAI,WAAwC;AAE1C,cAAY,UAAU;AAEtB,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClD,UAAU,WAAW;GAAE;GAAM;GAAW,CAAC,CAC1C;;;;;;CAOH,IAAI,MAAwD;AAC1D,SAAO,IAAI,qBAAqB,KAAK,SAAS,MAAM,cAClD,UAAU,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,cAClD,WAAW,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/esm/upload/car.d.ts

@@ -0,0 +1,19 @@
+import { Datastore } from "interface-datastore";
+
+//#region src/upload/car.d.ts
+interface CarPreprocessOptions {
+  name?: string;
+  onProgress?: (percentage: number) => void;
+  signal?: AbortSignal;
+}
+interface CarPreprocessResult {
+  carStream: ReadableStream<Uint8Array>;
+  rootCid: string;
+  size: bigint;
+}
+declare function preprocessToCar(input: File | ReadableStream<Uint8Array> | File[], options?: CarPreprocessOptions): Promise<CarPreprocessResult>;
+declare function isCarFile(file: File): Promise<boolean>;
+declare function destroyCarPreprocessor(): Promise<void>;
+//#endregion
+export { CarPreprocessOptions, CarPreprocessResult, destroyCarPreprocessor, isCarFile, preprocessToCar };
+//# sourceMappingURL=car.d.ts.map

package/dist/esm/upload/car.js

@@ -0,0 +1,125 @@
+import { FILE_EXTENSION_CAR, MIME_TYPE_CAR } from "../types/mime-types.js";
+import { asyncGeneratorToReadableStream, calculateStreamSize, readableStreamToAsyncIterable, streamToBlob } from "../utils/stream.js";
+import { createBlockstore, createDatastore } from "../blockstore/unstorage.js";
+import "../blockstore/index.js";
+import { car } from "@helia/car";
+import { createHeliaHTTP } from "@helia/http";
+import { unixfs } from "@helia/unixfs";
+import { CarReader } from "@ipld/car";
+
+//#region src/upload/car.ts
+let helia = null;
+let blockstore = null;
+let datastore = null;
+let config = {};
+function configureCar(carConfig) {
+	config = carConfig;
+}
+async function getHelia() {
+	if (helia) return helia;
+	const BlockstoreClass = createBlockstore();
+	const DatastoreClass = createDatastore();
+	blockstore = new BlockstoreClass({
+		prefix: "pinner-helia-blocks",
+		base: config.datastoreName
+	});
+	datastore = config.datastore || new DatastoreClass({
+		prefix: "pinner-helia-data",
+		base: config.datastoreName
+	});
+	helia = await createHeliaHTTP({
+		blockstore,
+		datastore
+	});
+	return helia;
+}
+async function cleanupHelia() {
+	if (datastore?.close) await datastore.close();
+	helia = null;
+	blockstore = null;
+	datastore = null;
+}
+async function* fileSource(files, onProgress, signal) {
+	const seenDirs = /* @__PURE__ */ new Set();
+	let totalBytes = 0n;
+	let processedBytes = 0n;
+	for (const file of files) totalBytes += BigInt(file.size);
+	for (const file of files) {
+		if (signal?.aborted) throw new Error("Aborted");
+		const fullPath = file.webkitRelativePath ?? file.name;
+		if (fullPath.includes("/.")) continue;
+		const parts = fullPath.split("/").filter((part) => part.length > 0);
+		for (let i = 1; i < parts.length; i++) {
+			if (signal?.aborted) throw new Error("Aborted");
+			const dirPath = parts.slice(0, i).join("/");
+			if (!seenDirs.has(dirPath)) {
+				seenDirs.add(dirPath);
+				yield {
+					content: (async function* () {})(),
+					path: dirPath
+				};
+			}
+		}
+		yield {
+			content: readableStreamToAsyncIterable(file.stream()),
+			path: fullPath
+		};
+		if (onProgress && totalBytes > 0n) {
+			processedBytes += BigInt(file.size);
+			onProgress(Number(processedBytes * 100n / totalBytes));
+		}
+	}
+}
+async function preprocessToCar(input, options) {
+	let files;
+	if (input instanceof ReadableStream) {
+		const [streamForSize$1, streamForFile] = input.tee();
+		await calculateStreamSize(streamForSize$1, options?.signal);
+		const streamBlob = await streamToBlob(streamForFile, "application/octet-stream");
+		files = [new File([streamBlob], options?.name || "upload", { type: streamBlob.type })];
+	} else if (Array.isArray(input)) files = input;
+	else files = [input];
+	const heliaInstance = await getHelia();
+	const fs = unixfs(heliaInstance);
+	const c = car(heliaInstance);
+	let rootCid;
+	let blocksCount = 0n;
+	const src = fileSource(files, options?.onProgress, options?.signal);
+	let hasFiles = false;
+	for await (const result of fs.addAll(src, {
+		cidVersion: 1,
+		rawLeaves: false,
+		signal: options?.signal,
+		onProgress(event) {
+			if (event.type === "blocks:put:blockstore:put") blocksCount++;
+		}
+	})) {
+		if (options?.signal?.aborted) throw new Error("Aborted");
+		rootCid = result.cid;
+		hasFiles = true;
+	}
+	if (!hasFiles || !rootCid) throw new Error("No files to process");
+	const [streamForSize, streamForProcessing] = asyncGeneratorToReadableStream(c.export(rootCid, { signal: options?.signal })).tee();
+	const size = await calculateStreamSize(streamForSize, options?.signal);
+	return {
+		carStream: streamForProcessing,
+		rootCid: rootCid.toString(),
+		size
+	};
+}
+async function isCarFile(file) {
+	if (file.type !== MIME_TYPE_CAR && !file.name.endsWith(FILE_EXTENSION_CAR)) return false;
+	try {
+		const iterable = readableStreamToAsyncIterable(file.stream());
+		return (await (await CarReader.fromIterable(iterable)).getRoots()).length > 0;
+	} catch {
+		return false;
+	}
+}
+async function destroyCarPreprocessor() {
+	await cleanupHelia();
+}
+
+//#endregion
+export { configureCar, destroyCarPreprocessor, isCarFile, preprocessToCar };
+//# sourceMappingURL=car.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"car.js","names":["createUnstorageDatastore","streamForSize"],"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  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    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":";;;;;;;;;;AAgDA,IAAI,QAAa;AACjB,IAAI,aAAkB;AACtB,IAAI,YAAiB;AACrB,IAAI,SAAoB,EAAE;AAE1B,SAAgB,aAAa,WAAsB;AACjD,UAAS;;AAGX,eAAe,WAAW;AACxB,KAAI,MAAO,QAAO;CAElB,MAAM,kBAAkB,kBAAkB;CAC1C,MAAM,iBAAiBA,iBAA0B;AAEjD,cAAa,IAAI,gBAAgB;EAC/B,QAAQ;EACR,MAAM,OAAO;EACd,CAAC;AACF,aACE,OAAO,aACP,IAAI,eAAe;EACjB,QAAQ;EACR,MAAM,OAAO;EACd,CAAC;AAEJ,SAAQ,MAAM,gBAAgB;EAC5B;EACA;EACD,CAAC;AAEF,QAAO;;AAGT,eAAe,eAAe;AAC5B,KAAI,WAAW,MACb,OAAM,UAAU,OAAO;AAEzB,SAAQ;AACR,cAAa;AACb,aAAY;;AAGd,gBAAgB,WACd,OACA,YACA,QAIC;CACD,MAAM,2BAAW,IAAI,KAAa;CAClC,IAAI,aAAa;CACjB,IAAI,iBAAiB;AAErB,MAAK,MAAM,QAAQ,MACjB,eAAc,OAAO,KAAK,KAAK;AAGjC,MAAK,MAAM,QAAQ,OAAO;AACxB,MAAI,QAAQ,QACV,OAAM,IAAI,MAAM,UAAU;EAG5B,MAAM,WAAY,KAAa,sBAAsB,KAAK;AAE1D,MAAI,SAAS,SAAS,KAAK,CACzB;EAGF,MAAM,QAAQ,SAAS,MAAM,IAAI,CAAC,QAAQ,SAAiB,KAAK,SAAS,EAAE;AAE3E,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,OAAI,QAAQ,QACV,OAAM,IAAI,MAAM,UAAU;GAG5B,MAAM,UAAU,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI;AAE3C,OAAI,CAAC,SAAS,IAAI,QAAQ,EAAE;AAC1B,aAAS,IAAI,QAAQ;AACrB,UAAM;KACJ,UAAU,mBAAmB,KAAK;KAClC,MAAM;KACP;;;AAIL,QAAM;GACJ,SAAS,8BAA8B,KAAK,QAAQ,CAAC;GACrD,MAAM;GACP;AAED,MAAI,cAAc,aAAa,IAAI;AACjC,qBAAkB,OAAO,KAAK,KAAK;AAEnC,cADwB,OAAQ,iBAAiB,OAAQ,WAAW,CACzC;;;;AAKjC,eAAsB,gBACpB,OACA,SAC8B;CAC9B,IAAI;AAEJ,KAAI,iBAAiB,gBAAgB;EACnC,MAAM,CAACC,iBAAe,iBAAiB,MAAM,KAAK;AACrC,QAAM,oBAAoBA,iBAAe,SAAS,OAAO;EACtE,MAAM,aAAa,MAAM,aACvB,eACA,2BACD;AACD,UAAQ,CACN,IAAI,KAAK,CAAC,WAAW,EAAE,SAAS,QAAQ,UAAU,EAChD,MAAM,WAAW,MAClB,CAAC,CACH;YACQ,MAAM,QAAQ,MAAM,CAC7B,SAAQ;KAER,SAAQ,CAAC,MAAM;CAGjB,MAAM,gBAAgB,MAAM,UAAU;CACtC,MAAM,KAAK,OAAO,cAAc;CAChC,MAAM,IAAI,IAAI,cAAc;CAE5B,IAAI;CACJ,IAAI,cAAc;CAElB,MAAM,MAAM,WAAW,OAAO,SAAS,YAAY,SAAS,OAAO;CAEnE,IAAI,WAAW;AACf,YAAW,MAAM,UAAU,GAAG,OAAO,KAAK;EACxC,YAAY;EACZ,WAAW;EACX,QAAQ,SAAS;EACjB,WAAW,OAAO;AAChB,OAAI,MAAM,SAAS,4BACjB;;EAGL,CAAC,EAAE;AACF,MAAI,SAAS,QAAQ,QACnB,OAAM,IAAI,MAAM,UAAU;AAE5B,YAAU,OAAO;AACjB,aAAW;;AAGb,KAAI,CAAC,YAAY,CAAC,QAChB,OAAM,IAAI,MAAM,sBAAsB;CAQxC,MAAM,CAAC,eAAe,uBAHJ,+BADQ,EAAE,OAAO,SAAU,EAAE,QAAQ,SAAS,QAAQ,CAAC,CACN,CAGZ,KAAK;CAE5D,MAAM,OAAO,MAAM,oBAAoB,eAAe,SAAS,OAAO;AAEtE,QAAO;EACL,WAAW;EACX,SAAS,QAAS,UAAU;EAC5B;EACD;;AAGH,eAAsB,UAAU,MAA8B;AAC5D,KAAI,KAAK,SAAS,iBAAiB,CAAC,KAAK,KAAK,SAAS,mBAAmB,CACxE,QAAO;AAGT,KAAI;EACF,MAAM,WAAW,8BAA8B,KAAK,QAAQ,CAAC;AAG7D,UADc,OADC,MAAM,UAAU,aAAa,SAAS,EAC1B,UAAU,EACxB,SAAS;SAChB;AACN,SAAO;;;AAIX,eAAsB,yBAAyB;AAC7C,OAAM,cAAc"}

package/dist/esm/upload/constants.js

@@ -0,0 +1,7 @@
+//#region src/upload/constants.ts
+const UPLOAD_SOURCE_XHR = "xhr-upload";
+const UPLOAD_SOURCE_TUS = "tus-upload";
+
+//#endregion
+export { UPLOAD_SOURCE_TUS, UPLOAD_SOURCE_XHR };
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../../src/upload/constants.ts"],"sourcesContent":["export const UPLOAD_SOURCE_XHR = \"xhr-upload\" as const;\nexport const UPLOAD_SOURCE_TUS = \"tus-upload\" as const;\n"],"mappings":";AAAA,MAAa,oBAAoB;AACjC,MAAa,oBAAoB"}

package/dist/esm/upload/index.js

@@ -0,0 +1,8 @@
+import { UploadResultSymbol, isUploadResult } from "../types/upload.js";
+import { normalizeUploadInput } from "./normalize.js";
+import { BaseUploadHandler } from "./base-upload.js";
+import { XHRUploadHandler } from "./xhr-upload.js";
+import { TUSUploadHandler } from "./tus-upload.js";
+import { configureCar, destroyCarPreprocessor, isCarFile, preprocessToCar } from "./car.js";
+import { UploadManager } from "./manager.js";
+import { UploadBuilderNamespace, createUploadBuilderNamespace } from "./builder.js";

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

@@ -0,0 +1,35 @@
+import { PinnerConfig } from "../config.js";
+import { UploadInput, UploadOperation, UploadOptions, UploadResult } from "../types/upload.js";
+import { OperationPollingOptions } from "@lumeweb/portal-sdk";
+
+//#region src/upload/manager.d.ts
+declare class UploadManager {
+  #private;
+  private xhrHandler;
+  private tusHandler;
+  private portalSdk;
+  private uploadLimit;
+  private limitFetched;
+  constructor(config: PinnerConfig);
+  fetchUploadLimit(): Promise<number>;
+  getUploadLimit(): number;
+  upload(input: UploadInput, options?: UploadOptions): Promise<UploadOperation>;
+  uploadCar(input: File | ReadableStream<Uint8Array>, options?: UploadOptions): Promise<UploadOperation>;
+  /**
+   * Wait for an operation to complete or reach a settled state.
+   *
+   * Handles two scenarios:
+   * 1. If an operationId is provided (in UploadResult), uses it directly
+   * 2. If only CID is available, lists operations filtered by CID and polls the first result
+   *
+   * @param input Either an operation ID (number) or an UploadResult
+   * @param options Polling options (interval, timeout, settledStates)
+   * @returns UploadResult with operation status merged in
+   */
+  waitForOperation(input: number | UploadResult, options?: OperationPollingOptions): Promise<UploadResult>;
+  uploadDirectory(files: File[], options?: UploadOptions): Promise<UploadOperation>;
+  destroy(): void;
+}
+//#endregion
+export { UploadManager };
+//# sourceMappingURL=manager.d.ts.map

package/dist/esm/upload/manager.js

@@ -0,0 +1,248 @@
+import { isUploadResult } from "../types/upload.js";
+import { FILE_EXTENSION_CAR, MIME_TYPE_CAR, MIME_TYPE_OCTET_STREAM } from "../types/mime-types.js";
+import { calculateStreamSize, streamToBlob } from "../utils/stream.js";
+import { XHRUploadHandler } from "./xhr-upload.js";
+import { TUSUploadHandler } from "./tus-upload.js";
+import { DEFAULT_ENDPOINT, TUS_SIZE_THRESHOLD } from "../types/constants.js";
+import { configureCar, destroyCarPreprocessor, isCarFile, preprocessToCar } from "./car.js";
+import { EmptyFileError } from "../errors/index.js";
+import { OPERATION_STATUS, Sdk } from "@lumeweb/portal-sdk";
+import { createEqFilter } from "@lumeweb/query-builder";
+
+//#region src/upload/manager.ts
+var UploadManager = class {
+	xhrHandler;
+	tusHandler;
+	portalSdk;
+	uploadLimit = TUS_SIZE_THRESHOLD;
+	limitFetched = false;
+	constructor(config) {
+		this.xhrHandler = new XHRUploadHandler(config);
+		this.tusHandler = new TUSUploadHandler(config);
+		this.portalSdk = new Sdk(config.endpoint || DEFAULT_ENDPOINT);
+		configureCar({
+			datastoreName: config.datastoreName,
+			datastore: config.datastore
+		});
+	}
+	async fetchUploadLimit() {
+		if (this.limitFetched) return this.uploadLimit;
+		try {
+			const result = await this.portalSdk.account().uploadLimit();
+			if (result.success && result.data?.limit) this.uploadLimit = result.data.limit;
+		} catch {
+			this.uploadLimit = TUS_SIZE_THRESHOLD;
+		}
+		this.limitFetched = true;
+		return this.uploadLimit;
+	}
+	getUploadLimit() {
+		return this.uploadLimit;
+	}
+	async upload(input, options) {
+		this.#validateInput(input, options);
+		return this.#uploadInput(input, options);
+	}
+	async uploadCar(input, options) {
+		this.#validateInput(input, options);
+		return this.#uploadCarFile(input, options);
+	}
+	/**
+	* Wait for an operation to complete or reach a settled state.
+	*
+	* Handles two scenarios:
+	* 1. If an operationId is provided (in UploadResult), uses it directly
+	* 2. If only CID is available, lists operations filtered by CID and polls the first result
+	*
+	* @param input Either an operation ID (number) or an UploadResult
+	* @param options Polling options (interval, timeout, settledStates)
+	* @returns UploadResult with operation status merged in
+	*/
+	async waitForOperation(input, options) {
+		if (isUploadResult(input) && input.operationId) {
+			const result = await this.portalSdk.account().waitForOperation(input.operationId, options);
+			if (!result.success) throw new Error(result.error?.message || `Operation ${input.operationId} failed`);
+			const operation = result.data;
+			if (!operation.cid) throw new Error(`Operation ${input.operationId} completed without CID`);
+			if (operation.status?.toLowerCase() === OPERATION_STATUS.FAILED || operation.status?.toLowerCase() === OPERATION_STATUS.ERROR) throw new Error(`Operation ${input.operationId} failed: ${operation.error || operation.status_message || "Unknown error"}`);
+			return {
+				...input,
+				cid: operation.cid,
+				operationId: operation.id
+			};
+		}
+		if (isUploadResult(input) && input.cid) return await this.#waitForOperationByCid(input, options);
+		const operationId = typeof input === "number" ? input : void 0;
+		if (operationId) {
+			const result = await this.portalSdk.account().waitForOperation(operationId, options);
+			if (!result.success) throw new Error(result.error?.message || `Operation ${operationId} failed`);
+			const operation = result.data;
+			if (!operation.cid) throw new Error(`Operation ${operationId} completed without CID`);
+			if (operation.status?.toLowerCase() === OPERATION_STATUS.FAILED || operation.status?.toLowerCase() === OPERATION_STATUS.ERROR) throw new Error(`Operation ${operationId} failed: ${operation.error || operation.status_message || "Unknown error"}`);
+			return {
+				id: operationId.toString(),
+				cid: operation.cid,
+				name: operation.operation_display_name || "Unknown",
+				size: 0,
+				mimeType: "",
+				createdAt: new Date(operation.started_at),
+				numberOfFiles: 1,
+				operationId: operation.id
+			};
+		}
+		throw new Error("No operation ID or CID provided, cannot wait for operation");
+	}
+	/**
+	* Wait for an operation by CID.
+	*
+	* This is used when we have a CID from an upload but no operation ID.
+	* We list operations filtered by CID to find the operation ID,
+	* then use the SDK's waitForOperation for polling.
+	*
+	* @param uploadResult UploadResult with CID
+	* @param options Polling options (interval, timeout, settledStates)
+	* @returns UploadResult with operation status merged in
+	*/
+	async #waitForOperationByCid(uploadResult, options) {
+		const params = {
+			filters: [createEqFilter("cid", uploadResult.cid)],
+			pagination: {
+				start: 0,
+				end: 1
+			}
+		};
+		const result = await this.portalSdk.account().listOperations(params);
+		if (!result.success) throw new Error(`Failed to find operation with CID ${uploadResult.cid}`);
+		const operation = result.data.data?.[0];
+		if (!operation) throw new Error(`Failed to find operation with CID ${uploadResult.cid}`);
+		const operationId = operation.id;
+		const waitResult = await this.portalSdk.account().waitForOperation(operationId, options);
+		if (!waitResult.success) throw new Error(waitResult.error?.message || `Operation ${operationId} failed`);
+		const finalOperation = waitResult.data;
+		if (!finalOperation.cid) throw new Error(`Operation ${operationId} completed without CID`);
+		if (finalOperation.status?.toLowerCase() === OPERATION_STATUS.FAILED || finalOperation.status?.toLowerCase() === OPERATION_STATUS.ERROR) throw new Error(`Operation ${operationId} failed: ${finalOperation.error || finalOperation.status_message || "Unknown error"}`);
+		return {
+			...uploadResult,
+			cid: finalOperation.cid,
+			operationId: finalOperation.id
+		};
+	}
+	#validateInput(input, options) {
+		if (input instanceof File) {
+			if (input.size === 0) throw new EmptyFileError(`Cannot upload empty file: ${input.name}`);
+		} else if (input instanceof ReadableStream) {
+			if (options?.size !== void 0 && options.size === 0) throw new EmptyFileError("Cannot upload empty stream");
+		}
+	}
+	async uploadDirectory(files, options) {
+		const carResult = await preprocessToCar(files, {
+			onProgress: options?.onProgress ? (p) => options.onProgress({
+				percentage: p,
+				bytesUploaded: 0,
+				bytesTotal: 0
+			}) : void 0,
+			signal: options?.signal
+		});
+		const operation = await this.#uploadCarResult(carResult, options?.name || "directory", options);
+		if (options?.waitForOperation && operation.result) {
+			const uploadResult = await operation.result;
+			operation.result = this.waitForOperation({
+				...uploadResult,
+				isDirectory: true,
+				numberOfFiles: files.length
+			}, options.operationPollingOptions);
+		}
+		return operation;
+	}
+	async #uploadInput(input, options) {
+		if (await this.#isCarFileUpload(input, options)) return this.#uploadCarFile(input, options);
+		const limit = await this.fetchUploadLimit();
+		if (input instanceof ReadableStream) {
+			const [streamForSize, streamForUpload] = input.tee();
+			let size;
+			if (options?.size !== void 0) size = BigInt(options.size);
+			else size = await calculateStreamSize(streamForSize, options?.signal);
+			if (size >= BigInt(limit)) return this.#uploadFile({
+				data: streamForUpload,
+				name: options?.name || "upload",
+				type: options?.name?.endsWith(FILE_EXTENSION_CAR) || options?.isDirectory ? MIME_TYPE_CAR : MIME_TYPE_OCTET_STREAM,
+				size: Number(size)
+			}, options);
+			else {
+				const blob = await streamToBlob(streamForUpload, "application/octet-stream");
+				const file = new File([blob], options?.name || "upload", { type: blob.type });
+				return this.#uploadFile(file, options);
+			}
+		}
+		return this.#uploadFile(input, options);
+	}
+	async #isCarFileUpload(input, options) {
+		if (options?.isCarFile === true) return true;
+		if (options?.isCarFile === false) return false;
+		if (input instanceof File) {
+			if (input.type === MIME_TYPE_CAR || input.name.endsWith(FILE_EXTENSION_CAR)) return await isCarFile(input);
+		}
+		if (input instanceof ReadableStream && options?.name?.endsWith(FILE_EXTENSION_CAR)) return options?.isCarFile !== false;
+		return false;
+	}
+	async #uploadCarResult(carResult, name, options) {
+		const limit = await this.fetchUploadLimit();
+		if (carResult.size >= BigInt(limit)) return this.#uploadFile({
+			data: carResult.carStream,
+			name: `${name}${FILE_EXTENSION_CAR}`,
+			type: MIME_TYPE_CAR,
+			size: Number(carResult.size)
+		}, options);
+		else {
+			const blob = await streamToBlob(carResult.carStream, MIME_TYPE_CAR);
+			const file = new File([blob], `${name}${FILE_EXTENSION_CAR}`, { type: MIME_TYPE_CAR });
+			return this.#uploadFile(file, options);
+		}
+	}
+	async #uploadCarFile(input, options) {
+		const limit = await this.fetchUploadLimit();
+		if (input instanceof ReadableStream) {
+			const [streamForSize, streamForUpload] = input.tee();
+			let size;
+			if (options?.size !== void 0) size = BigInt(options.size);
+			else size = await calculateStreamSize(streamForSize, options?.signal);
+			if (size >= BigInt(limit)) return this.#uploadFile({
+				data: streamForUpload,
+				name: options?.name || "upload.car",
+				type: MIME_TYPE_CAR,
+				size: Number(size)
+			}, options);
+			else {
+				const blob = await streamToBlob(streamForUpload, MIME_TYPE_CAR);
+				const file = new File([blob], options?.name || "upload.car", { type: MIME_TYPE_CAR });
+				return this.#uploadFile(file, options);
+			}
+		}
+		if (input.type !== MIME_TYPE_CAR) input = new File([input], input.name, {
+			type: MIME_TYPE_CAR,
+			lastModified: input.lastModified
+		});
+		return this.#uploadFile(input, options);
+	}
+	async #uploadFile(input, options) {
+		const limit = await this.fetchUploadLimit();
+		let isLargeFile = false;
+		if (input instanceof File) isLargeFile = input.size > limit;
+		else isLargeFile = true;
+		const operation = await (isLargeFile ? this.tusHandler.upload(input, options) : this.xhrHandler.upload(input, options));
+		if (options?.waitForOperation && operation.result) {
+			const uploadResult = await operation.result;
+			operation.result = this.waitForOperation(uploadResult, options.operationPollingOptions);
+		}
+		return operation;
+	}
+	destroy() {
+		this.xhrHandler.destroy();
+		this.tusHandler.destroy();
+		destroyCarPreprocessor();
+	}
+};
+
+//#endregion
+export { UploadManager };
+//# sourceMappingURL=manager.js.map