@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.1.0

package/dist/storage/manager.js

@@ -0,0 +1,248 @@
+import { StorageError } from "../types/storage";
+class StorageManager {
+  providers = /* @__PURE__ */ new Map();
+  defaultProvider = null;
+  /**
+   * Registers a storage provider with the manager.
+   *
+   * @remarks
+   * This method adds a new storage provider to the manager's registry and optionally
+   * sets it as the default provider for subsequent operations. If no default provider
+   * is currently set, the first registered provider automatically becomes the default.
+   * @param name - Unique identifier for the provider
+   * @param provider - The storage provider instance implementing the `StorageProvider` interface
+   * @param isDefault - Whether this provider should be set as the default (defaults to `false`)
+   * @example
+   * ```typescript
+   * const pinata = new PinataStorage({ jwt: 'your-jwt-token' });
+   * storage.register('pinata', pinata, true); // Set as default
+   *
+   * const ipfs = new IPFSStorage({ apiEndpoint: 'https://...' });
+   * storage.register('ipfs', ipfs); // Not default
+   * ```
+   */
+  register(name, provider, isDefault = false) {
+    this.providers.set(name, provider);
+    if (isDefault || this.defaultProvider === null) {
+      this.defaultProvider = name;
+    }
+  }
+  /**
+   * Retrieves a registered storage provider.
+   *
+   * @param name - Provider identifier.
+   *   If not specified, returns the default provider.
+   * @returns The requested storage provider instance
+   *
+   * @throws {StorageError} With code 'NO_PROVIDER' if no provider available
+   * @throws {StorageError} With code 'PROVIDER_NOT_FOUND' if named provider doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const provider = storage.getProvider('pinata');
+   * const config = provider.getConfig();
+   * ```
+   */
+  getProvider(name) {
+    const providerName = name ?? this.defaultProvider;
+    if (!providerName) {
+      throw new StorageError(
+        "No storage provider specified and no default provider set",
+        "NO_PROVIDER",
+        "manager"
+      );
+    }
+    const provider = this.providers.get(providerName);
+    if (!provider) {
+      throw new StorageError(
+        `Storage provider '${providerName}' not found`,
+        "PROVIDER_NOT_FOUND",
+        "manager"
+      );
+    }
+    return provider;
+  }
+  /**
+   * Lists all registered provider names.
+   *
+   * @returns Array of registered provider identifiers
+   *
+   * @example
+   * ```typescript
+   * const providers = storage.listProviders();
+   * console.log('Available providers:', providers);
+   * // Output: ['ipfs', 'pinata', 'google-drive']
+   * ```
+   */
+  listProviders() {
+    return Array.from(this.providers.keys());
+  }
+  /**
+   * Gets the current default provider name.
+   *
+   * @returns Default provider identifier or null if none set
+   *
+   * @example
+   * ```typescript
+   * const defaultName = storage.getDefaultProvider();
+   * if (defaultName) {
+   *   console.log(`Using ${defaultName} by default`);
+   * }
+   * ```
+   */
+  getDefaultProvider() {
+    return this.defaultProvider;
+  }
+  /**
+   * Sets the default storage provider.
+   *
+   * @param name - Provider identifier to set as default.
+   *   Must be a registered provider name.
+   *
+   * @throws {StorageError} With code 'PROVIDER_NOT_FOUND' if provider not registered
+   *
+   * @example
+   * ```typescript
+   * storage.setDefaultProvider('pinata');
+   * // Now all operations without provider name will use Pinata
+   * ```
+   */
+  setDefaultProvider(name) {
+    if (!this.providers.has(name)) {
+      throw new StorageError(
+        `Cannot set default provider '${name}': provider not registered`,
+        "PROVIDER_NOT_FOUND",
+        "manager"
+      );
+    }
+    this.defaultProvider = name;
+  }
+  /**
+   * Uploads a file using the specified or default storage provider.
+   *
+   * @remarks
+   * This method uploads a file to the specified provider or falls back to the default
+   * provider if none is specified. The upload result includes the storage URL, file size,
+   * content type, and provider-specific metadata that can be used for subsequent operations.
+   * @param file - The file blob to upload
+   * @param filename - Optional custom filename (defaults to auto-generated name)
+   * @param providerName - Optional provider identifier (uses default if not specified)
+   * @returns A Promise that resolves to the storage upload result with URL and metadata
+   * @throws {StorageError} When no provider is available or upload fails
+   * @example
+   * ```typescript
+   * // Upload to default provider
+   * const result = await storage.upload(fileBlob, 'data.json');
+   * console.log(`Uploaded to: ${result.url}`);
+   *
+   * // Upload to specific provider
+   * const result2 = await storage.upload(fileBlob, 'data.json', 'pinata');
+   * ```
+   */
+  async upload(file, filename, providerName) {
+    const provider = this.getProvider(providerName);
+    return provider.upload(file, filename);
+  }
+  /**
+   * Downloads a file from storage.
+   *
+   * @param url - The storage URL to download from.
+   *   Format depends on the storage provider.
+   * @param providerName - Optional provider identifier.
+   *   Uses default provider if not specified.
+   * @returns The downloaded file as a Blob
+   *
+   * @throws {StorageError} If download fails or provider unavailable
+   *
+   * @example
+   * ```typescript
+   * const blob = await storage.download('ipfs://QmXxx...');
+   * const text = await blob.text();
+   * ```
+   */
+  async download(url, providerName) {
+    const provider = this.getProvider(providerName);
+    return provider.download(url);
+  }
+  /**
+   * Lists files in storage.
+   *
+   * @param options - Optional filtering and pagination.
+   * @param options.namePattern - Pattern to filter files.
+   * @param options.limit - Maximum files to return.
+   * @param providerName - Optional provider identifier.
+   *   Uses default provider if not specified.
+   * @returns Array of file metadata
+   *
+   * @throws {StorageError} If listing fails or not supported by provider
+   *
+   * @example
+   * ```typescript
+   * const files = await storage.list(
+   *   { namePattern: '*.json', limit: 10 },
+   *   'google-drive'
+   * );
+   * ```
+   */
+  async list(options, providerName) {
+    const provider = this.getProvider(providerName);
+    return provider.list(options);
+  }
+  /**
+   * Deletes a file from storage.
+   *
+   * @param url - The storage URL to delete.
+   *   Must be a valid URL for the provider.
+   * @param providerName - Optional provider identifier.
+   *   Uses default provider if not specified.
+   * @returns True if deletion succeeded, false otherwise
+   *
+   * @throws {StorageError} If deletion fails or not supported by provider
+   *
+   * @example
+   * ```typescript
+   * const success = await storage.delete('ipfs://QmXxx...');
+   * if (success) {
+   *   console.log('File deleted successfully');
+   * }
+   * ```
+   */
+  async delete(url, providerName) {
+    const provider = this.getProvider(providerName);
+    return provider.delete(url);
+  }
+  /**
+   * Gets all registered storage provider names.
+   *
+   * @returns Array of provider identifiers
+   *
+   * @deprecated Use `listProviders()` instead
+   *
+   * @example
+   * ```typescript
+   * const providers = storage.getStorageProviders();
+   * ```
+   */
+  getStorageProviders() {
+    return Array.from(this.providers.keys());
+  }
+  /**
+   * Gets the default storage provider name.
+   *
+   * @returns Default provider identifier or undefined if none set
+   *
+   * @deprecated Use `getDefaultProvider()` instead
+   *
+   * @example
+   * ```typescript
+   * const defaultProvider = storage.getDefaultStorageProvider();
+   * ```
+   */
+  getDefaultStorageProvider() {
+    return this.defaultProvider ?? void 0;
+  }
+}
+export {
+  StorageManager
+};
+//# sourceMappingURL=manager.js.map

package/dist/storage/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/manager.ts"],"sourcesContent":["/**\n * Manages multiple storage providers with a unified interface.\n *\n * @remarks\n * This module provides centralized management of storage providers, enabling\n * applications to work with multiple storage backends through a single API.\n * It handles provider registration, default selection, and operation routing.\n *\n * @category Storage\n * @module storage/manager\n */\n\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageFile,\n  StorageListOptions,\n} from \"../types/storage\";\nimport { StorageError } from \"../types/storage\";\n\n/**\n * Manages multiple storage providers with a unified interface for file operations.\n *\n * @remarks\n * The StorageManager provides a consistent API for uploading, downloading, and managing\n * files across different storage backends including IPFS, Pinata, Google Drive, and\n * server-managed storage. It handles provider registration, default provider selection,\n * and automatic fallback scenarios for robust file operations.\n *\n * Used internally by DataController for encrypted file storage, but can also be used\n * directly for custom storage workflows. Each provider implements the `StorageProvider`\n * interface to ensure consistent behavior across different storage backends.\n *\n * The manager supports provider-specific configurations and features while maintaining\n * a uniform API surface for applications.\n * @example\n * ```typescript\n * import { StorageManager, IPFSStorage, PinataStorage } from '@opendatalabs/vana-sdk';\n *\n * const storage = new StorageManager();\n *\n * // Register multiple providers\n * storage.register('ipfs', new IPFSStorage({\n *   apiEndpoint: 'https://api.pinata.cloud/pinning/pinFileToIPFS'\n * }), true);\n * storage.register('pinata', new PinataStorage({\n *   jwt: 'your-pinata-jwt-token'\n * }));\n *\n * // Upload to default provider\n * const result = await storage.upload(fileBlob, 'myfile.json');\n *\n * // Upload to specific provider\n * const result2 = await storage.upload(fileBlob, 'myfile.json', 'pinata');\n * ```\n * @category Storage\n * @see {@link https://docs.vana.com/developer/vana-sdk-documentation/core-modules/storage-providers | Storage Providers Guide} for configuration details\n */\nexport class StorageManager {\n  private providers: Map<string, StorageProvider> = new Map();\n  private defaultProvider: string | null = null;\n\n  /**\n   * Registers a storage provider with the manager.\n   *\n   * @remarks\n   * This method adds a new storage provider to the manager's registry and optionally\n   * sets it as the default provider for subsequent operations. If no default provider\n   * is currently set, the first registered provider automatically becomes the default.\n   * @param name - Unique identifier for the provider\n   * @param provider - The storage provider instance implementing the `StorageProvider` interface\n   * @param isDefault - Whether this provider should be set as the default (defaults to `false`)\n   * @example\n   * ```typescript\n   * const pinata = new PinataStorage({ jwt: 'your-jwt-token' });\n   * storage.register('pinata', pinata, true); // Set as default\n   *\n   * const ipfs = new IPFSStorage({ apiEndpoint: 'https://...' });\n   * storage.register('ipfs', ipfs); // Not default\n   * ```\n   */\n  register(name: string, provider: StorageProvider, isDefault = false): void {\n    this.providers.set(name, provider);\n\n    if (isDefault || this.defaultProvider === null) {\n      this.defaultProvider = name;\n    }\n  }\n\n  /**\n   * Retrieves a registered storage provider.\n   *\n   * @param name - Provider identifier.\n   *   If not specified, returns the default provider.\n   * @returns The requested storage provider instance\n   *\n   * @throws {StorageError} With code 'NO_PROVIDER' if no provider available\n   * @throws {StorageError} With code 'PROVIDER_NOT_FOUND' if named provider doesn't exist\n   *\n   * @example\n   * ```typescript\n   * const provider = storage.getProvider('pinata');\n   * const config = provider.getConfig();\n   * ```\n   */\n  getProvider(name?: string): StorageProvider {\n    const providerName = name ?? this.defaultProvider;\n\n    if (!providerName) {\n      throw new StorageError(\n        \"No storage provider specified and no default provider set\",\n        \"NO_PROVIDER\",\n        \"manager\",\n      );\n    }\n\n    const provider = this.providers.get(providerName);\n    if (!provider) {\n      throw new StorageError(\n        `Storage provider '${providerName}' not found`,\n        \"PROVIDER_NOT_FOUND\",\n        \"manager\",\n      );\n    }\n\n    return provider;\n  }\n\n  /**\n   * Lists all registered provider names.\n   *\n   * @returns Array of registered provider identifiers\n   *\n   * @example\n   * ```typescript\n   * const providers = storage.listProviders();\n   * console.log('Available providers:', providers);\n   * // Output: ['ipfs', 'pinata', 'google-drive']\n   * ```\n   */\n  listProviders(): string[] {\n    return Array.from(this.providers.keys());\n  }\n\n  /**\n   * Gets the current default provider name.\n   *\n   * @returns Default provider identifier or null if none set\n   *\n   * @example\n   * ```typescript\n   * const defaultName = storage.getDefaultProvider();\n   * if (defaultName) {\n   *   console.log(`Using ${defaultName} by default`);\n   * }\n   * ```\n   */\n  getDefaultProvider(): string | null {\n    return this.defaultProvider;\n  }\n\n  /**\n   * Sets the default storage provider.\n   *\n   * @param name - Provider identifier to set as default.\n   *   Must be a registered provider name.\n   *\n   * @throws {StorageError} With code 'PROVIDER_NOT_FOUND' if provider not registered\n   *\n   * @example\n   * ```typescript\n   * storage.setDefaultProvider('pinata');\n   * // Now all operations without provider name will use Pinata\n   * ```\n   */\n  setDefaultProvider(name: string): void {\n    if (!this.providers.has(name)) {\n      throw new StorageError(\n        `Cannot set default provider '${name}': provider not registered`,\n        \"PROVIDER_NOT_FOUND\",\n        \"manager\",\n      );\n    }\n    this.defaultProvider = name;\n  }\n\n  /**\n   * Uploads a file using the specified or default storage provider.\n   *\n   * @remarks\n   * This method uploads a file to the specified provider or falls back to the default\n   * provider if none is specified. The upload result includes the storage URL, file size,\n   * content type, and provider-specific metadata that can be used for subsequent operations.\n   * @param file - The file blob to upload\n   * @param filename - Optional custom filename (defaults to auto-generated name)\n   * @param providerName - Optional provider identifier (uses default if not specified)\n   * @returns A Promise that resolves to the storage upload result with URL and metadata\n   * @throws {StorageError} When no provider is available or upload fails\n   * @example\n   * ```typescript\n   * // Upload to default provider\n   * const result = await storage.upload(fileBlob, 'data.json');\n   * console.log(`Uploaded to: ${result.url}`);\n   *\n   * // Upload to specific provider\n   * const result2 = await storage.upload(fileBlob, 'data.json', 'pinata');\n   * ```\n   */\n  async upload(\n    file: Blob,\n    filename?: string,\n    providerName?: string,\n  ): Promise<StorageUploadResult> {\n    const provider = this.getProvider(providerName);\n    return provider.upload(file, filename);\n  }\n\n  /**\n   * Downloads a file from storage.\n   *\n   * @param url - The storage URL to download from.\n   *   Format depends on the storage provider.\n   * @param providerName - Optional provider identifier.\n   *   Uses default provider if not specified.\n   * @returns The downloaded file as a Blob\n   *\n   * @throws {StorageError} If download fails or provider unavailable\n   *\n   * @example\n   * ```typescript\n   * const blob = await storage.download('ipfs://QmXxx...');\n   * const text = await blob.text();\n   * ```\n   */\n  async download(url: string, providerName?: string): Promise<Blob> {\n    const provider = this.getProvider(providerName);\n    return provider.download(url);\n  }\n\n  /**\n   * Lists files in storage.\n   *\n   * @param options - Optional filtering and pagination.\n   * @param options.namePattern - Pattern to filter files.\n   * @param options.limit - Maximum files to return.\n   * @param providerName - Optional provider identifier.\n   *   Uses default provider if not specified.\n   * @returns Array of file metadata\n   *\n   * @throws {StorageError} If listing fails or not supported by provider\n   *\n   * @example\n   * ```typescript\n   * const files = await storage.list(\n   *   { namePattern: '*.json', limit: 10 },\n   *   'google-drive'\n   * );\n   * ```\n   */\n  async list(\n    options?: StorageListOptions,\n    providerName?: string,\n  ): Promise<StorageFile[]> {\n    const provider = this.getProvider(providerName);\n    return provider.list(options);\n  }\n\n  /**\n   * Deletes a file from storage.\n   *\n   * @param url - The storage URL to delete.\n   *   Must be a valid URL for the provider.\n   * @param providerName - Optional provider identifier.\n   *   Uses default provider if not specified.\n   * @returns True if deletion succeeded, false otherwise\n   *\n   * @throws {StorageError} If deletion fails or not supported by provider\n   *\n   * @example\n   * ```typescript\n   * const success = await storage.delete('ipfs://QmXxx...');\n   * if (success) {\n   *   console.log('File deleted successfully');\n   * }\n   * ```\n   */\n  async delete(url: string, providerName?: string): Promise<boolean> {\n    const provider = this.getProvider(providerName);\n    return provider.delete(url);\n  }\n\n  /**\n   * Gets all registered storage provider names.\n   *\n   * @returns Array of provider identifiers\n   *\n   * @deprecated Use `listProviders()` instead\n   *\n   * @example\n   * ```typescript\n   * const providers = storage.getStorageProviders();\n   * ```\n   */\n  getStorageProviders(): string[] {\n    return Array.from(this.providers.keys());\n  }\n\n  /**\n   * Gets the default storage provider name.\n   *\n   * @returns Default provider identifier or undefined if none set\n   *\n   * @deprecated Use `getDefaultProvider()` instead\n   *\n   * @example\n   * ```typescript\n   * const defaultProvider = storage.getDefaultStorageProvider();\n   * ```\n   */\n  getDefaultStorageProvider(): string | undefined {\n    return this.defaultProvider ?? undefined;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/storage/providers/callback-storage.cjs

@@ -0,0 +1,248 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var callback_storage_exports = {};
+__export(callback_storage_exports, {
+  CallbackStorage: () => CallbackStorage
+});
+module.exports = __toCommonJS(callback_storage_exports);
+var import_storage = require("../../types/storage");
+class CallbackStorage {
+  /**
+   * Creates a new callback-based storage provider.
+   *
+   * @param callbacks - User-provided storage operation callbacks.
+   *   Must include at minimum `upload` and `download` functions.
+   * @throws {Error} If required callbacks are missing
+   */
+  constructor(callbacks) {
+    this.callbacks = callbacks;
+    if (!callbacks.upload || !callbacks.download) {
+      throw new Error(
+        "CallbackStorage requires both upload and download callbacks"
+      );
+    }
+  }
+  /**
+   * Uploads a file using the user-provided callback.
+   *
+   * @param file - The blob to upload.
+   *   Can be any Blob-compatible object including File.
+   * @param filename - Optional filename for the upload.
+   *   If not provided, callback may generate a name.
+   * @returns Upload result containing URL and metadata
+   *
+   * @throws {StorageError} With code 'INVALID_UPLOAD_RESULT' if callback returns invalid data
+   * @throws {StorageError} With code 'UPLOAD_ERROR' if upload fails
+   *
+   * @example
+   * ```typescript
+   * const file = new File(['content'], 'data.json');
+   * const result = await storage.upload(file);
+   * console.log('Uploaded to:', result.url);
+   * ```
+   */
+  async upload(file, filename) {
+    try {
+      const result = await this.callbacks.upload(file, filename);
+      if (!result.url || result.url.trim() === "") {
+        throw new import_storage.StorageError(
+          "Upload callback returned invalid result: missing or empty url",
+          "INVALID_UPLOAD_RESULT",
+          "callback-storage"
+        );
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof import_storage.StorageError) {
+        throw error;
+      }
+      throw new import_storage.StorageError(
+        `Upload failed: ${error instanceof Error ? error.message : String(error)}`,
+        "UPLOAD_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  /**
+   * Downloads a file using the user-provided callback.
+   *
+   * @param url - The URL or identifier to download.
+   *   If `extractIdentifier` callback is provided, it will be used to extract the identifier.
+   * @returns The downloaded file as a Blob
+   *
+   * @throws {StorageError} With code 'INVALID_DOWNLOAD_RESULT' if callback returns non-Blob
+   * @throws {StorageError} With code 'DOWNLOAD_ERROR' if download fails
+   *
+   * @example
+   * ```typescript
+   * const blob = await storage.download('https://storage.example.com/file123');
+   * const text = await blob.text();
+   * ```
+   */
+  async download(url) {
+    try {
+      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
+      const blob = await this.callbacks.download(identifier);
+      if (!(blob instanceof Blob)) {
+        throw new import_storage.StorageError(
+          "Download callback returned invalid result: expected Blob",
+          "INVALID_DOWNLOAD_RESULT",
+          "callback-storage"
+        );
+      }
+      return blob;
+    } catch (error) {
+      if (error instanceof import_storage.StorageError) {
+        throw error;
+      }
+      throw new import_storage.StorageError(
+        `Download failed: ${error instanceof Error ? error.message : String(error)}`,
+        "DOWNLOAD_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  /**
+   * Lists files using the user-provided callback.
+   *
+   * @param options - Optional list options.
+   * @param options.namePattern - Pattern to filter files by name.
+   *   Implementation depends on callback.
+   * @param options.limit - Maximum number of files to return.
+   *   Implementation depends on callback.
+   * @returns Array of storage file metadata
+   *
+   * @throws {StorageError} With code 'NOT_SUPPORTED' if list callback not provided
+   * @throws {StorageError} With code 'LIST_ERROR' if listing fails
+   *
+   * @remarks
+   * This operation is optional and only available if a `list` callback
+   * is provided during construction.
+   *
+   * @example
+   * ```typescript
+   * const files = await storage.list({ namePattern: '*.json' });
+   * files.forEach(file => console.log(file.name, file.size));
+   * ```
+   */
+  async list(options) {
+    if (!this.callbacks.list) {
+      throw new import_storage.StorageError(
+        "List operation not supported - no list callback provided",
+        "NOT_SUPPORTED",
+        "callback-storage"
+      );
+    }
+    try {
+      const result = await this.callbacks.list(options?.namePattern, options);
+      return result.items.map((item, index) => ({
+        id: item.identifier,
+        name: item.identifier.split("/").pop() ?? `file-${index}`,
+        url: item.identifier,
+        size: item.size ?? 0,
+        contentType: "application/octet-stream",
+        createdAt: item.lastModified ?? /* @__PURE__ */ new Date(),
+        metadata: item.metadata
+      }));
+    } catch (error) {
+      throw new import_storage.StorageError(
+        `List failed: ${error instanceof Error ? error.message : String(error)}`,
+        "LIST_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  /**
+   * Deletes a file using the user-provided callback.
+   *
+   * @param url - The URL or identifier to delete.
+   *   If `extractIdentifier` callback is provided, it will be used to extract the identifier.
+   * @returns True if deletion succeeded, false otherwise
+   *
+   * @throws {StorageError} With code 'NOT_SUPPORTED' if delete callback not provided
+   * @throws {StorageError} With code 'DELETE_ERROR' if deletion fails
+   *
+   * @remarks
+   * This operation is optional and only available if a `delete` callback
+   * is provided during construction.
+   *
+   * @example
+   * ```typescript
+   * const deleted = await storage.delete('https://storage.example.com/file123');
+   * if (deleted) {
+   *   console.log('File deleted successfully');
+   * }
+   * ```
+   */
+  async delete(url) {
+    if (!this.callbacks.delete) {
+      throw new import_storage.StorageError(
+        "Delete operation not supported - no delete callback provided",
+        "NOT_SUPPORTED",
+        "callback-storage"
+      );
+    }
+    try {
+      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
+      return await this.callbacks.delete(identifier);
+    } catch (error) {
+      throw new import_storage.StorageError(
+        `Delete failed: ${error instanceof Error ? error.message : String(error)}`,
+        "DELETE_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  /**
+   * Returns the provider's configuration and capabilities.
+   *
+   * @returns Configuration object indicating supported features
+   *
+   * @example
+   * ```typescript
+   * const config = storage.getConfig();
+   * if (config.features.list) {
+   *   // List operation is supported
+   *   const files = await storage.list();
+   * }
+   * ```
+   */
+  getConfig() {
+    return {
+      name: "callback-storage",
+      type: "callback",
+      requiresAuth: false,
+      features: {
+        upload: true,
+        download: true,
+        list: !!this.callbacks.list,
+        delete: !!this.callbacks.delete
+      }
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CallbackStorage
+});
+//# sourceMappingURL=callback-storage.cjs.map

package/dist/storage/providers/callback-storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/storage/providers/callback-storage.ts"],"sourcesContent":["/**\n * Provides user-defined storage operations through callback functions.\n *\n * @remarks\n * This module implements a flexible storage provider that delegates all\n * operations to user-provided callbacks. It enables custom storage\n * integrations without modifying the SDK, supporting any backend including\n * HTTP APIs, WebSocket servers, cloud storage services, or local filesystems.\n *\n * @category Storage\n * @module storage/providers/callback-storage\n */\n\nimport type { StorageCallbacks } from \"../../types/config\";\nimport {\n  StorageError,\n  type StorageProvider,\n  type StorageUploadResult,\n  type StorageFile,\n  type StorageListOptions,\n  type StorageProviderConfig,\n} from \"../../types/storage\";\n\n/**\n * Delegates storage operations to user-provided callback functions.\n *\n * @remarks\n * This provider enables custom storage integrations by delegating all\n * operations to user-defined callbacks. It follows the same flexible\n * pattern as relayer callbacks, allowing implementations via HTTP,\n * WebSocket, direct cloud APIs, local filesystem, or any other backend.\n *\n * The provider validates callback results and wraps errors in consistent\n * `StorageError` types for uniform error handling across the SDK.\n *\n * @example\n * ```typescript\n * // HTTP-based implementation\n * const httpCallbacks: StorageCallbacks = {\n *   async upload(blob, filename) {\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type\n *     };\n *   },\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n *\n * const storage = new CallbackStorage(httpCallbacks);\n *\n * // Direct S3 implementation\n * const s3Callbacks: StorageCallbacks = {\n *   async upload(blob, filename) {\n *     const url = await getPresignedUploadUrl(filename);\n *     await fetch(url, { method: 'PUT', body: blob });\n *     return {\n *       url: `s3://my-bucket/${filename}`,\n *       size: blob.size,\n *       contentType: blob.type\n *     };\n *   },\n *   async download(identifier) {\n *     const url = await getPresignedDownloadUrl(identifier);\n *     const response = await fetch(url);\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @category Storage\n */\nexport class CallbackStorage implements StorageProvider {\n  /**\n   * Creates a new callback-based storage provider.\n   *\n   * @param callbacks - User-provided storage operation callbacks.\n   *   Must include at minimum `upload` and `download` functions.\n   * @throws {Error} If required callbacks are missing\n   */\n  constructor(private readonly callbacks: StorageCallbacks) {\n    if (!callbacks.upload || !callbacks.download) {\n      throw new Error(\n        \"CallbackStorage requires both upload and download callbacks\",\n      );\n    }\n  }\n\n  /**\n   * Uploads a file using the user-provided callback.\n   *\n   * @param file - The blob to upload.\n   *   Can be any Blob-compatible object including File.\n   * @param filename - Optional filename for the upload.\n   *   If not provided, callback may generate a name.\n   * @returns Upload result containing URL and metadata\n   *\n   * @throws {StorageError} With code 'INVALID_UPLOAD_RESULT' if callback returns invalid data\n   * @throws {StorageError} With code 'UPLOAD_ERROR' if upload fails\n   *\n   * @example\n   * ```typescript\n   * const file = new File(['content'], 'data.json');\n   * const result = await storage.upload(file);\n   * console.log('Uploaded to:', result.url);\n   * ```\n   */\n  async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n    try {\n      const result = await this.callbacks.upload(file, filename);\n\n      // Validate the result has required fields\n      if (!result.url || result.url.trim() === \"\") {\n        throw new StorageError(\n          \"Upload callback returned invalid result: missing or empty url\",\n          \"INVALID_UPLOAD_RESULT\",\n          \"callback-storage\",\n        );\n      }\n\n      return result;\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Upload failed: ${error instanceof Error ? error.message : String(error)}`,\n        \"UPLOAD_ERROR\",\n        \"callback-storage\",\n        { cause: error instanceof Error ? error : undefined },\n      );\n    }\n  }\n\n  /**\n   * Downloads a file using the user-provided callback.\n   *\n   * @param url - The URL or identifier to download.\n   *   If `extractIdentifier` callback is provided, it will be used to extract the identifier.\n   * @returns The downloaded file as a Blob\n   *\n   * @throws {StorageError} With code 'INVALID_DOWNLOAD_RESULT' if callback returns non-Blob\n   * @throws {StorageError} With code 'DOWNLOAD_ERROR' if download fails\n   *\n   * @example\n   * ```typescript\n   * const blob = await storage.download('https://storage.example.com/file123');\n   * const text = await blob.text();\n   * ```\n   */\n  async download(url: string): Promise<Blob> {\n    try {\n      // Extract identifier if callback is provided, otherwise use URL as-is\n      const identifier = this.callbacks.extractIdentifier\n        ? this.callbacks.extractIdentifier(url)\n        : url;\n\n      const blob = await this.callbacks.download(identifier);\n\n      if (!(blob instanceof Blob)) {\n        throw new StorageError(\n          \"Download callback returned invalid result: expected Blob\",\n          \"INVALID_DOWNLOAD_RESULT\",\n          \"callback-storage\",\n        );\n      }\n\n      return blob;\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Download failed: ${error instanceof Error ? error.message : String(error)}`,\n        \"DOWNLOAD_ERROR\",\n        \"callback-storage\",\n        { cause: error instanceof Error ? error : undefined },\n      );\n    }\n  }\n\n  /**\n   * Lists files using the user-provided callback.\n   *\n   * @param options - Optional list options.\n   * @param options.namePattern - Pattern to filter files by name.\n   *   Implementation depends on callback.\n   * @param options.limit - Maximum number of files to return.\n   *   Implementation depends on callback.\n   * @returns Array of storage file metadata\n   *\n   * @throws {StorageError} With code 'NOT_SUPPORTED' if list callback not provided\n   * @throws {StorageError} With code 'LIST_ERROR' if listing fails\n   *\n   * @remarks\n   * This operation is optional and only available if a `list` callback\n   * is provided during construction.\n   *\n   * @example\n   * ```typescript\n   * const files = await storage.list({ namePattern: '*.json' });\n   * files.forEach(file => console.log(file.name, file.size));\n   * ```\n   */\n  async list(options?: StorageListOptions): Promise<StorageFile[]> {\n    if (!this.callbacks.list) {\n      throw new StorageError(\n        \"List operation not supported - no list callback provided\",\n        \"NOT_SUPPORTED\",\n        \"callback-storage\",\n      );\n    }\n\n    try {\n      const result = await this.callbacks.list(options?.namePattern, options);\n\n      // Convert list result to StorageFile format\n      return result.items.map((item, index) => ({\n        id: item.identifier,\n        name: item.identifier.split(\"/\").pop() ?? `file-${index}`,\n        url: item.identifier,\n        size: item.size ?? 0,\n        contentType: \"application/octet-stream\",\n        createdAt: item.lastModified ?? new Date(),\n        metadata: item.metadata,\n      }));\n    } catch (error) {\n      throw new StorageError(\n        `List failed: ${error instanceof Error ? error.message : String(error)}`,\n        \"LIST_ERROR\",\n        \"callback-storage\",\n        { cause: error instanceof Error ? error : undefined },\n      );\n    }\n  }\n\n  /**\n   * Deletes a file using the user-provided callback.\n   *\n   * @param url - The URL or identifier to delete.\n   *   If `extractIdentifier` callback is provided, it will be used to extract the identifier.\n   * @returns True if deletion succeeded, false otherwise\n   *\n   * @throws {StorageError} With code 'NOT_SUPPORTED' if delete callback not provided\n   * @throws {StorageError} With code 'DELETE_ERROR' if deletion fails\n   *\n   * @remarks\n   * This operation is optional and only available if a `delete` callback\n   * is provided during construction.\n   *\n   * @example\n   * ```typescript\n   * const deleted = await storage.delete('https://storage.example.com/file123');\n   * if (deleted) {\n   *   console.log('File deleted successfully');\n   * }\n   * ```\n   */\n  async delete(url: string): Promise<boolean> {\n    if (!this.callbacks.delete) {\n      throw new StorageError(\n        \"Delete operation not supported - no delete callback provided\",\n        \"NOT_SUPPORTED\",\n        \"callback-storage\",\n      );\n    }\n\n    try {\n      // Extract identifier if callback is provided, otherwise use URL as-is\n      const identifier = this.callbacks.extractIdentifier\n        ? this.callbacks.extractIdentifier(url)\n        : url;\n\n      return await this.callbacks.delete(identifier);\n    } catch (error) {\n      throw new StorageError(\n        `Delete failed: ${error instanceof Error ? error.message : String(error)}`,\n        \"DELETE_ERROR\",\n        \"callback-storage\",\n        { cause: error instanceof Error ? error : undefined },\n      );\n    }\n  }\n\n  /**\n   * Returns the provider's configuration and capabilities.\n   *\n   * @returns Configuration object indicating supported features\n   *\n   * @example\n   * ```typescript\n   * const config = storage.getConfig();\n   * if (config.features.list) {\n   *   // List operation is supported\n   *   const files = await storage.list();\n   * }\n   * ```\n   */\n  getConfig(): StorageProviderConfig {\n    return {\n      name: \"callback-storage\",\n      type: \"callback\",\n      requiresAuth: false,\n      features: {\n        upload: true,\n        download: true,\n        list: !!this.callbacks.list,\n        delete: !!this.callbacks.delete,\n      },\n    };\n  }\n}\n"],"mappings":"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","names":[]}