@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

package/dist/storage/index.js

@@ -1,11 +1,13 @@
 import { StorageError } from "../types/storage";
 import { GoogleDriveStorage } from "./providers/google-drive";
+import { DropboxStorage } from "./providers/dropbox";
 import { IpfsStorage } from "./providers/ipfs";
 import { PinataStorage } from "./providers/pinata";
 import { CallbackStorage } from "./providers/callback-storage";
 import { StorageManager } from "./manager";
 export {
   CallbackStorage,
+  DropboxStorage,
   GoogleDriveStorage,
   IpfsStorage,
   PinataStorage,

package/dist/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/index.ts"],"sourcesContent":["/**\n * Storage API for Vana SDK\n *\n * Provides unified interface for different storage providers\n * to upload, download, and manage user data files.\n *\n * ## Storage Provider Decision Tree\n *\n * Choose your storage provider based on your needs:\n *\n * **Need full CRUD operations and metadata?**\n * - ✅ Use `PinataStorage` - Managed IPFS with listing, deletion, and rich metadata\n *\n * **Want to use your own IPFS infrastructure?**\n * - ✅ Use `IpfsStorage.forInfura()` - Connect to Infura IPFS service\n * - ✅ Use `IpfsStorage.forLocalNode()` - Connect to local IPFS node\n * - ✅ Use `new IpfsStorage()` - Connect to any IPFS-compatible service\n *\n * **Want flexible callback-based storage?**\n * - ✅ Use `CallbackStorage` - Implement storage via custom callbacks (HTTP, WebSocket, etc.)\n *\n * **Need Google Drive integration?**\n * - ✅ Use `GoogleDriveStorage` - Direct Google Drive API with folder management\n *\n * @example\n * ```typescript\n * // Managed IPFS with full features\n * const pinata = new PinataStorage({ jwt: \"your-jwt\" });\n *\n * // Standard IPFS with Infura\n * const ipfs = IpfsStorage.forInfura({ projectId: \"...\", projectSecret: \"...\" });\n *\n * // Callback-based storage (flexible)\n * const storage = new CallbackStorage({\n *   async upload(blob, filename) {\n *     // Your custom upload logic\n *     const response = await fetch('/api/upload', { method: 'POST', body: blob });\n *     const data = await response.json();\n *     return { url: data.url, size: blob.size, contentType: blob.type };\n *   },\n *   async download(identifier) {\n *     // Your custom download logic\n *     const response = await fetch(`/api/download/${identifier}`);\n *     return response.blob();\n *   }\n * });\n * ```\n */\n\n// Re-export storage types from types module to avoid circular dependencies\nexport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageFile,\n  StorageListOptions,\n  StorageProviderConfig,\n} from \"../types/storage\";\n\nexport { StorageError } from \"../types/storage\";\n\n// Export storage providers\nexport { GoogleDriveStorage } from \"./providers/google-drive\";\nexport { IpfsStorage } from \"./providers/ipfs\";\nexport { PinataStorage } from \"./providers/pinata\";\nexport { CallbackStorage } from \"./providers/callback-storage\";\n\n// Export storage manager\nexport { StorageManager } from \"./manager\";\n\n// Export storage callback types\nexport type {\n  StorageCallbacks,\n  StorageDownloadOptions,\n  StorageListResult,\n} from \"../types/config\";\n"],"mappings":"AA0DA,SAAS,oBAAoB;AAG7B,SAAS,0BAA0B;AACnC,SAAS,mBAAmB;AAC5B,SAAS,qBAAqB;AAC9B,SAAS,uBAAuB;AAGhC,SAAS,sBAAsB;","names":[]}
+{"version":3,"sources":["../../src/storage/index.ts"],"sourcesContent":["/**\n * Storage API for Vana SDK\n *\n * Provides unified interface for different storage providers\n * to upload, download, and manage user data files.\n *\n * ## Storage Provider Decision Tree\n *\n * Choose your storage provider based on your needs:\n *\n * **Need full CRUD operations and metadata?**\n * - ✅ Use `PinataStorage` - Managed IPFS with listing, deletion, and rich metadata\n *\n * **Want to use your own IPFS infrastructure?**\n * - ✅ Use `IpfsStorage.forInfura()` - Connect to Infura IPFS service\n * - ✅ Use `IpfsStorage.forLocalNode()` - Connect to local IPFS node\n * - ✅ Use `new IpfsStorage()` - Connect to any IPFS-compatible service\n *\n * **Want flexible callback-based storage?**\n * - ✅ Use `CallbackStorage` - Implement storage via custom callbacks (HTTP, WebSocket, etc.)\n *\n * **Need Google Drive integration?**\n * - ✅ Use `GoogleDriveStorage` - Direct Google Drive API with folder management\n *\n * @example\n * ```typescript\n * // Managed IPFS with full features\n * const pinata = new PinataStorage({ jwt: \"your-jwt\" });\n *\n * // Standard IPFS with Infura\n * const ipfs = IpfsStorage.forInfura({ projectId: \"...\", projectSecret: \"...\" });\n *\n * // Callback-based storage (flexible)\n * const storage = new CallbackStorage({\n *   async upload(blob, filename) {\n *     // Your custom upload logic\n *     const response = await fetch('/api/upload', { method: 'POST', body: blob });\n *     const data = await response.json();\n *     return { url: data.url, size: blob.size, contentType: blob.type };\n *   },\n *   async download(identifier) {\n *     // Your custom download logic\n *     const response = await fetch(`/api/download/${identifier}`);\n *     return response.blob();\n *   }\n * });\n * ```\n */\n\n// Re-export storage types from types module to avoid circular dependencies\nexport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageFile,\n  StorageListOptions,\n  StorageProviderConfig,\n} from \"../types/storage\";\n\nexport { StorageError } from \"../types/storage\";\n\n// Export storage providers\nexport { GoogleDriveStorage } from \"./providers/google-drive\";\nexport { DropboxStorage } from \"./providers/dropbox\";\nexport { IpfsStorage } from \"./providers/ipfs\";\nexport { PinataStorage } from \"./providers/pinata\";\nexport { CallbackStorage } from \"./providers/callback-storage\";\n\n// Export storage manager\nexport { StorageManager } from \"./manager\";\n\n// Export storage callback types\nexport type {\n  StorageCallbacks,\n  StorageDownloadOptions,\n  StorageListResult,\n} from \"../types/config\";\n"],"mappings":"AA0DA,SAAS,oBAAoB;AAG7B,SAAS,0BAA0B;AACnC,SAAS,sBAAsB;AAC/B,SAAS,mBAAmB;AAC5B,SAAS,qBAAqB;AAC9B,SAAS,uBAAuB;AAGhC,SAAS,sBAAsB;","names":[]}

package/dist/storage/manager.cjs

@@ -51,10 +51,20 @@ class StorageManager {
     }
   }
   /**
-   * Get a registered storage provider
+   * Retrieves a registered storage provider.
    *
-   * @param name - Provider identifier, uses default if not specified
-   * @returns Storage provider instance
+   * @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;
@@ -76,25 +86,49 @@ class StorageManager {
     return provider;
   }
   /**
-   * List all registered providers
+   * Lists all registered provider names.
+   *
+   * @returns Array of registered provider identifiers
    *
-   * @returns Array of provider names
+   * @example
+   * ```typescript
+   * const providers = storage.listProviders();
+   * console.log('Available providers:', providers);
+   * // Output: ['ipfs', 'pinata', 'google-drive']
+   * ```
    */
   listProviders() {
     return Array.from(this.providers.keys());
   }
   /**
-   * Get the default provider name
+   * Gets the current default provider name.
    *
-   * @returns Default provider name or null
+   * @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;
   }
   /**
-   * Set the default provider
+   * Sets the default storage provider.
+   *
+   * @param name - Provider identifier to set as default.
+   *   Must be a registered provider name.
    *
-   * @param name - Provider identifier
+   * @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)) {
@@ -133,50 +167,99 @@ class StorageManager {
     return provider.upload(file, filename);
   }
   /**
-   * Download a file using the specified or default provider
+   * 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
    *
-   * @param url - The storage URL
-   * @param providerName - Optional provider to use
-   * @returns Promise with file blob
+   * @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);
   }
   /**
-   * List files using the specified or default provider
+   * 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
    *
-   * @param options - Optional filtering and pagination
-   * @param providerName - Optional provider to use
-   * @returns Promise with file list
+   * @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);
   }
   /**
-   * Delete a file using the specified or default provider
+   * Deletes a file from storage.
    *
-   * @param url - The storage URL
-   * @param providerName - Optional provider to use
-   * @returns Promise with success status
+   * @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);
   }
   /**
-   * Get list of registered storage provider names
+   * Gets all registered storage provider names.
    *
-   * @returns Array of provider names
+   * @returns Array of provider identifiers
+   *
+   * @deprecated Use `listProviders()` instead
+   *
+   * @example
+   * ```typescript
+   * const providers = storage.getStorageProviders();
+   * ```
    */
   getStorageProviders() {
     return Array.from(this.providers.keys());
   }
   /**
-   * Get the default storage provider name
+   * Gets the default storage provider name.
    *
-   * @returns Default provider name or undefined
+   * @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;

package/dist/storage/manager.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/manager.ts"],"sourcesContent":["import 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   * Get a registered storage provider\n   *\n   * @param name - Provider identifier, uses default if not specified\n   * @returns Storage provider instance\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   * List all registered providers\n   *\n   * @returns Array of provider names\n   */\n  listProviders(): string[] {\n    return Array.from(this.providers.keys());\n  }\n\n  /**\n   * Get the default provider name\n   *\n   * @returns Default provider name or null\n   */\n  getDefaultProvider(): string | null {\n    return this.defaultProvider;\n  }\n\n  /**\n   * Set the default provider\n   *\n   * @param name - Provider identifier\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   * Download a file using the specified or default provider\n   *\n   * @param url - The storage URL\n   * @param providerName - Optional provider to use\n   * @returns Promise with file blob\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   * List files using the specified or default provider\n   *\n   * @param options - Optional filtering and pagination\n   * @param providerName - Optional provider to use\n   * @returns Promise with file list\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   * Delete a file using the specified or default provider\n   *\n   * @param url - The storage URL\n   * @param providerName - Optional provider to use\n   * @returns Promise with success status\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   * Get list of registered storage provider names\n   *\n   * @returns Array of provider names\n   */\n  getStorageProviders(): string[] {\n    return Array.from(this.providers.keys());\n  }\n\n  /**\n   * Get the default storage provider name\n   *\n   * @returns Default provider name or undefined\n   */\n  getDefaultStorageProvider(): string | undefined {\n    return this.defaultProvider ?? undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,qBAA6B;AAwCtB,MAAM,eAAe;AAAA,EAClB,YAA0C,oBAAI,IAAI;AAAA,EAClD,kBAAiC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBzC,SAAS,MAAc,UAA2B,YAAY,OAAa;AACzE,SAAK,UAAU,IAAI,MAAM,QAAQ;AAEjC,QAAI,aAAa,KAAK,oBAAoB,MAAM;AAC9C,WAAK,kBAAkB;AAAA,IACzB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,YAAY,MAAgC;AAC1C,UAAM,eAAe,QAAQ,KAAK;AAElC,QAAI,CAAC,cAAc;AACjB,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,UAAM,WAAW,KAAK,UAAU,IAAI,YAAY;AAChD,QAAI,CAAC,UAAU;AACb,YAAM,IAAI;AAAA,QACR,qBAAqB,YAAY;AAAA,QACjC;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,gBAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,UAAU,KAAK,CAAC;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,qBAAoC;AAClC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,mBAAmB,MAAoB;AACrC,QAAI,CAAC,KAAK,UAAU,IAAI,IAAI,GAAG;AAC7B,YAAM,IAAI;AAAA,QACR,gCAAgC,IAAI;AAAA,QACpC;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,SAAK,kBAAkB;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,MAAM,OACJ,MACA,UACA,cAC8B;AAC9B,UAAM,WAAW,KAAK,YAAY,YAAY;AAC9C,WAAO,SAAS,OAAO,MAAM,QAAQ;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,SAAS,KAAa,cAAsC;AAChE,UAAM,WAAW,KAAK,YAAY,YAAY;AAC9C,WAAO,SAAS,SAAS,GAAG;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,KACJ,SACA,cACwB;AACxB,UAAM,WAAW,KAAK,YAAY,YAAY;AAC9C,WAAO,SAAS,KAAK,OAAO;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,OAAO,KAAa,cAAyC;AACjE,UAAM,WAAW,KAAK,YAAY,YAAY;AAC9C,WAAO,SAAS,OAAO,GAAG;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,sBAAgC;AAC9B,WAAO,MAAM,KAAK,KAAK,UAAU,KAAK,CAAC;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,4BAAgD;AAC9C,WAAO,KAAK,mBAAmB;AAAA,EACjC;AACF;","names":[]}
+{"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/manager.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Manages multiple storage providers with a unified interface.
+ *
+ * @remarks
+ * This module provides centralized management of storage providers, enabling
+ * applications to work with multiple storage backends through a single API.
+ * It handles provider registration, default selection, and operation routing.
+ *
+ * @category Storage
+ * @module storage/manager
+ */
 import type { StorageProvider, StorageUploadResult, StorageFile, StorageListOptions } from "../types/storage";
 /**
  * Manages multiple storage providers with a unified interface for file operations.
@@ -61,28 +72,62 @@ export declare class StorageManager {
      */
     register(name: string, provider: StorageProvider, isDefault?: boolean): void;
     /**
-     * Get a registered storage provider
+     * Retrieves a registered storage provider.
+     *
+     * @param name - Provider identifier.
+     *   If not specified, returns the default provider.
+     * @returns The requested storage provider instance
      *
-     * @param name - Provider identifier, uses default if not specified
-     * @returns 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?: string): StorageProvider;
     /**
-     * List all registered providers
+     * Lists all registered provider names.
+     *
+     * @returns Array of registered provider identifiers
      *
-     * @returns Array of provider names
+     * @example
+     * ```typescript
+     * const providers = storage.listProviders();
+     * console.log('Available providers:', providers);
+     * // Output: ['ipfs', 'pinata', 'google-drive']
+     * ```
      */
     listProviders(): string[];
     /**
-     * Get the default provider name
+     * Gets the current default provider name.
+     *
+     * @returns Default provider identifier or null if none set
      *
-     * @returns Default provider name or null
+     * @example
+     * ```typescript
+     * const defaultName = storage.getDefaultProvider();
+     * if (defaultName) {
+     *   console.log(`Using ${defaultName} by default`);
+     * }
+     * ```
      */
     getDefaultProvider(): string | null;
     /**
-     * Set the default provider
+     * Sets the default storage provider.
      *
-     * @param name - Provider identifier
+     * @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: string): void;
     /**
@@ -109,39 +154,88 @@ export declare class StorageManager {
      */
     upload(file: Blob, filename?: string, providerName?: string): Promise<StorageUploadResult>;
     /**
-     * Download a file using the specified or default provider
+     * 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
      *
-     * @param url - The storage URL
-     * @param providerName - Optional provider to use
-     * @returns Promise with file blob
+     * @throws {StorageError} If download fails or provider unavailable
+     *
+     * @example
+     * ```typescript
+     * const blob = await storage.download('ipfs://QmXxx...');
+     * const text = await blob.text();
+     * ```
      */
     download(url: string, providerName?: string): Promise<Blob>;
     /**
-     * List files using the specified or default provider
+     * 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
      *
-     * @param options - Optional filtering and pagination
-     * @param providerName - Optional provider to use
-     * @returns Promise with file list
+     * @example
+     * ```typescript
+     * const files = await storage.list(
+     *   { namePattern: '*.json', limit: 10 },
+     *   'google-drive'
+     * );
+     * ```
      */
     list(options?: StorageListOptions, providerName?: string): Promise<StorageFile[]>;
     /**
-     * Delete a file using the specified or default provider
+     * Deletes a file from storage.
      *
-     * @param url - The storage URL
-     * @param providerName - Optional provider to use
-     * @returns Promise with success status
+     * @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');
+     * }
+     * ```
      */
     delete(url: string, providerName?: string): Promise<boolean>;
     /**
-     * Get list of registered storage provider names
+     * Gets all registered storage provider names.
+     *
+     * @returns Array of provider identifiers
      *
-     * @returns Array of provider names
+     * @deprecated Use `listProviders()` instead
+     *
+     * @example
+     * ```typescript
+     * const providers = storage.getStorageProviders();
+     * ```
      */
     getStorageProviders(): string[];
     /**
-     * Get the default storage provider name
+     * Gets the default storage provider name.
+     *
+     * @returns Default provider identifier or undefined if none set
+     *
+     * @deprecated Use `getDefaultProvider()` instead
      *
-     * @returns Default provider name or undefined
+     * @example
+     * ```typescript
+     * const defaultProvider = storage.getDefaultStorageProvider();
+     * ```
      */
     getDefaultStorageProvider(): string | undefined;
 }

package/dist/storage/manager.js

@@ -28,10 +28,20 @@ class StorageManager {
     }
   }
   /**
-   * Get a registered storage provider
+   * Retrieves a registered storage provider.
    *
-   * @param name - Provider identifier, uses default if not specified
-   * @returns Storage provider instance
+   * @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;
@@ -53,25 +63,49 @@ class StorageManager {
     return provider;
   }
   /**
-   * List all registered providers
+   * Lists all registered provider names.
+   *
+   * @returns Array of registered provider identifiers
    *
-   * @returns Array of provider names
+   * @example
+   * ```typescript
+   * const providers = storage.listProviders();
+   * console.log('Available providers:', providers);
+   * // Output: ['ipfs', 'pinata', 'google-drive']
+   * ```
    */
   listProviders() {
     return Array.from(this.providers.keys());
   }
   /**
-   * Get the default provider name
+   * Gets the current default provider name.
    *
-   * @returns Default provider name or null
+   * @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;
   }
   /**
-   * Set the default provider
+   * Sets the default storage provider.
+   *
+   * @param name - Provider identifier to set as default.
+   *   Must be a registered provider name.
    *
-   * @param name - Provider identifier
+   * @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)) {
@@ -110,50 +144,99 @@ class StorageManager {
     return provider.upload(file, filename);
   }
   /**
-   * Download a file using the specified or default provider
+   * 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
    *
-   * @param url - The storage URL
-   * @param providerName - Optional provider to use
-   * @returns Promise with file blob
+   * @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);
   }
   /**
-   * List files using the specified or default provider
+   * 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
    *
-   * @param options - Optional filtering and pagination
-   * @param providerName - Optional provider to use
-   * @returns Promise with file list
+   * @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);
   }
   /**
-   * Delete a file using the specified or default provider
+   * Deletes a file from storage.
    *
-   * @param url - The storage URL
-   * @param providerName - Optional provider to use
-   * @returns Promise with success status
+   * @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);
   }
   /**
-   * Get list of registered storage provider names
+   * Gets all registered storage provider names.
    *
-   * @returns Array of provider names
+   * @returns Array of provider identifiers
+   *
+   * @deprecated Use `listProviders()` instead
+   *
+   * @example
+   * ```typescript
+   * const providers = storage.getStorageProviders();
+   * ```
    */
   getStorageProviders() {
     return Array.from(this.providers.keys());
   }
   /**
-   * Get the default storage provider name
+   * Gets the default storage provider name.
    *
-   * @returns Default provider name or undefined
+   * @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;