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

package/dist/types/config.d.ts

@@ -0,0 +1,720 @@
+import type { WalletClient, PublicClient, Account, Address, Chain } from "viem";
+import type { VanaChainId, VanaChain } from "./chains";
+import type { StorageProvider, StorageUploadResult, StorageListOptions } from "./storage";
+import type { RelayerConfig } from "./relayer";
+import type { IOperationStore, IRelayerStateStore } from "./operationStore";
+/**
+ * Marker interface to indicate that a Vana instance has storage configured.
+ * Used for compile-time type safety to ensure storage-dependent methods
+ * are only called on properly configured instances.
+ *
+ * @category Configuration
+ */
+export interface StorageRequiredMarker {
+    readonly __storageRequired: true;
+}
+/**
+ * Configures storage providers for SDK file operations.
+ *
+ * @remarks
+ * Supports multiple backends with automatic fallback.
+ * IPFS for decentralization, Pinata for reliability,
+ * Google Drive for development, custom for flexibility.
+ *
+ * **Provider Selection:**
+ * - IPFS: Decentralized, permanent storage ideal for production
+ * - Pinata: Managed IPFS with guaranteed availability
+ * - Google Drive: Centralized, suitable for development/testing
+ * - Custom providers: Implement StorageProvider interface
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * const storage: StorageConfig = {
+ *   providers: {
+ *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),
+ *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })
+ *   },
+ *   defaultProvider: 'ipfs'
+ * };
+ * ```
+ */
+export interface StorageConfig {
+    /**
+     * Map of provider name to storage provider instance.
+     *   Common provider names: "ipfs", "pinata", "googledrive", "s3".
+     *   Custom names allowed for custom provider implementations.
+     */
+    providers: Record<string, StorageProvider>;
+    /**
+     * Default provider name to use when none specified.
+     *   Must match a key in the providers map. Falls back to first provider if not specified.
+     */
+    defaultProvider?: string;
+}
+/**
+ * Download relayer callbacks for proxying CORS-restricted downloads.
+ *
+ * Provides a callback to proxy download requests through your application server
+ * when direct browser access fails due to CORS restrictions (e.g., Google Drive).
+ *
+ * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:
+ * 1. MUST block requests to private/internal IPs (SSRF protection)
+ * 2. SHOULD NOT restrict domains (files can be hosted anywhere)
+ *
+ * @category Configuration
+ * @example Client-side implementation:
+ * ```typescript
+ * const downloadRelayer: DownloadRelayerCallbacks = {
+ *   async proxyDownload(url) {
+ *     const response = await fetch('/api/proxy', {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       body: JSON.stringify({ url })
+ *     });
+ *     return response.blob();
+ *   }
+ * };
+ * ```
+ *
+ * @example Server-side proxy endpoint (Next.js):
+ * ```typescript
+ * // /api/proxy/route.ts
+ * import { promises as dns } from 'dns';
+ * import { isIPv4 } from 'net';
+ *
+ * async function handleProxy(url: string) {
+ *   const { hostname } = new URL(url);
+ *
+ *   // Resolve hostname to IP (handle localhost specially)
+ *   const ip = hostname === 'localhost' ? '127.0.0.1' :
+ *              isIPv4(hostname) ? hostname :
+ *              await dns.lookup(hostname).then(r => r.address);
+ *
+ *   // SSRF Protection: Block private/internal IPs
+ *   if (isIPv4(ip)) {
+ *     const [a, b] = ip.split('.').map(Number);
+ *     if (a === 10 || a === 127 || a === 0 ||
+ *         (a === 172 && b >= 16 && b <= 31) ||
+ *         (a === 192 && b === 168) ||
+ *         (a === 169 && b === 254) ||
+ *         a >= 224) { // Also block multicast/reserved
+ *       return new Response('Private/internal addresses not allowed', { status: 403 });
+ *     }
+ *   }
+ *
+ *   // Proxy the request
+ *   const response = await fetch(url, { redirect: 'manual' });
+ *
+ *   // Handle redirects (with recursion limit)
+ *   if (response.status >= 301 && response.status <= 308) {
+ *     const location = response.headers.get('location');
+ *     if (location) return handleProxy(new URL(location, url).href);
+ *   }
+ *
+ *   const data = await response.arrayBuffer();
+ *   return new Response(data, {
+ *     headers: {
+ *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',
+ *       'Access-Control-Allow-Origin': '*'
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export interface DownloadRelayerCallbacks {
+    /**
+     * Proxy a download request through your application server
+     *
+     * @param url - The URL to download from
+     * @returns Promise resolving to the downloaded content as a Blob
+     */
+    proxyDownload: (url: string) => Promise<Blob>;
+}
+/**
+ * Storage callback functions for flexible storage operations.
+ *
+ * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide
+ * custom callback functions to handle storage operations in any way they choose.
+ * This pattern matches the relayer callbacks approach, providing maximum flexibility.
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * const storageCallbacks: StorageCallbacks = {
+ *   async upload(blob, filename, metadata) {
+ *     // Custom implementation - could be HTTP, S3, local filesystem, etc.
+ *     const formData = new FormData();
+ *     formData.append('file', blob, filename);
+ *     const response = await fetch('/api/storage/upload', {
+ *       method: 'POST',
+ *       body: formData
+ *     });
+ *     const data = await response.json();
+ *     return {
+ *       url: data.url,
+ *       size: blob.size,
+ *       contentType: blob.type,
+ *       metadata: data.metadata
+ *     };
+ *   },
+ *
+ *   async download(identifier) {
+ *     const response = await fetch(`/api/storage/download/${identifier}`);
+ *     return response.blob();
+ *   }
+ * };
+ * ```
+ */
+export interface StorageCallbacks {
+    /**
+     * Upload a blob to storage
+     *
+     * @param blob - The data to upload
+     * @param filename - Optional filename hint
+     * @param metadata - Optional metadata for the upload
+     * @returns Upload result with identifier and metadata
+     */
+    upload: (blob: Blob, filename?: string, metadata?: Record<string, unknown>) => Promise<StorageUploadResult>;
+    /**
+     * Download data from storage
+     *
+     * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)
+     * @param options - Optional download options
+     * @returns The downloaded data as a Blob
+     */
+    download: (identifier: string, options?: StorageDownloadOptions) => Promise<Blob>;
+    /**
+     * List stored items (optional)
+     *
+     * @param prefix - Optional prefix to filter results
+     * @param options - Optional listing options
+     * @returns Array of storage items with metadata
+     */
+    list?: (prefix?: string, options?: StorageListOptions) => Promise<StorageListResult>;
+    /**
+     * Delete a stored item (optional)
+     *
+     * @param identifier - The storage identifier to delete
+     * @returns Promise that resolves to true if deletion succeeded
+     */
+    delete?: (identifier: string) => Promise<boolean>;
+    /**
+     * Extract identifier from a URL or return as-is (optional)
+     * Used for backward compatibility with URL-based systems
+     *
+     * @param url - The URL to extract from
+     * @returns The extracted identifier
+     */
+    extractIdentifier?: (url: string) => string;
+}
+/**
+ * Options for storage download operations
+ *
+ * @category Configuration
+ */
+export interface StorageDownloadOptions {
+    /** Optional HTTP headers */
+    headers?: Record<string, string>;
+    /** Optional abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Optional byte range for partial downloads */
+    range?: {
+        start?: number;
+        end?: number;
+    };
+}
+/**
+ * Result from storage list operations
+ *
+ * @category Configuration
+ */
+export interface StorageListResult {
+    /** Array of storage items */
+    items: Array<{
+        /** Item identifier */
+        identifier: string;
+        /** Item size in bytes */
+        size?: number;
+        /** Last modified timestamp */
+        lastModified?: Date;
+        /** Item metadata */
+        metadata?: Record<string, unknown>;
+    }>;
+    /** Continuation token for pagination */
+    continuationToken?: string;
+    /** Whether more results are available */
+    hasMore?: boolean;
+}
+/**
+ * Base configuration interface without storage requirements
+ *
+ * @category Configuration
+ */
+export interface BaseConfig {
+    /**
+     * Optional relayer configuration for handling gasless transactions.
+     * Can be a URL string for convenience, or a callback for full control.
+     *
+     * @example
+     * ```typescript
+     * // Simple URL (SDK handles transport)
+     * relayer: '/api/relay'
+     *
+     * // Full control with callback
+     * relayer: async (request) => {
+     *   const response = await fetch('/api/relay', {
+     *     method: 'POST',
+     *     body: JSON.stringify(request)
+     *   });
+     *   return response.json();
+     * }
+     * ```
+     */
+    relayer?: RelayerConfig;
+    /**
+     * Optional download relayer for proxying CORS-restricted downloads.
+     * Provides a proxy mechanism for files stored on servers with CORS restrictions.
+     */
+    downloadRelayer?: DownloadRelayerCallbacks;
+    /**
+     * Optional storage providers configuration for file upload/download.
+     *   Required for: upload(), grant() without pre-stored URLs, schema operations.
+     *   See StorageConfig for provider selection guidance.
+     */
+    storage?: StorageConfig;
+    /**
+     * Optional subgraph URL for querying user files and permissions.
+     * If not provided, defaults to the built-in subgraph URL for the current chain.
+     * Can be overridden per method call if needed.
+     * Obtain chain-specific URLs from Vana documentation or deployment info.
+     */
+    subgraphUrl?: string;
+    /**
+     * Optional default IPFS gateways to use for fetching files.
+     * These gateways will be used by default in fetchFromIPFS unless overridden per-call.
+     * If not provided, the SDK will use public gateways.
+     * Order matters: first successful gateway is used.
+     *
+     * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']
+     */
+    ipfsGateways?: string[];
+    /**
+     * Default personal server base URL for server operations.
+     * Required for ServerController methods like getIdentity(), createOperation(), etc.
+     *
+     * @example 'https://my-personal-server.example.com'
+     */
+    defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     *
+     * @example
+     * ```typescript
+     * const vana = createVana({
+     *   walletClient,
+     *   relayer: '/api/relay',
+     *   operationStore: myOperationStore
+     * });
+     * ```
+     */
+    operationStore?: IOperationStore | IRelayerStateStore;
+}
+/**
+ * Base configuration interface that requires storage for storage-dependent operations
+ *
+ * @category Configuration
+ */
+export interface BaseConfigWithStorage {
+    /**
+     * Optional relayer configuration for handling gasless transactions.
+     * Can be a URL string for convenience, or a callback for full control.
+     *
+     * @example
+     * ```typescript
+     * // Simple URL (SDK handles transport)
+     * relayer: '/api/relay'
+     *
+     * // Full control with callback
+     * relayer: async (request) => {
+     *   const response = await fetch('/api/relay', {
+     *     method: 'POST',
+     *     body: JSON.stringify(request)
+     *   });
+     *   return response.json();
+     * }
+     * ```
+     */
+    relayer?: RelayerConfig;
+    /**
+     * Optional download relayer for proxying CORS-restricted downloads.
+     * Provides a proxy mechanism for files stored on servers with CORS restrictions.
+     */
+    downloadRelayer?: DownloadRelayerCallbacks;
+    /** Required storage providers configuration for file upload/download */
+    storage: StorageConfig;
+    /**
+     * Optional subgraph URL for querying user files and permissions.
+     * If not provided, defaults to the built-in subgraph URL for the current chain.
+     * Can be overridden per method call if needed.
+     */
+    subgraphUrl?: string;
+    /**
+     * Optional default IPFS gateways to use for fetching files.
+     * These gateways will be used by default in fetchFromIPFS unless overridden per-call.
+     * If not provided, the SDK will use public gateways.
+     *
+     * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']
+     */
+    ipfsGateways?: string[];
+    /**
+     * Default personal server base URL for server operations.
+     * Required for ServerController methods like getIdentity(), createOperation(), etc.
+     *
+     * @example 'https://my-personal-server.example.com'
+     */
+    defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     */
+    operationStore?: IOperationStore | IRelayerStateStore;
+}
+/**
+ * Configuration with wallet client
+ *
+ * @category Configuration
+ */
+export interface WalletConfig extends BaseConfig {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient & {
+        chain: VanaChain;
+    };
+}
+/**
+ * Configuration with wallet client that requires storage
+ *
+ * @category Configuration
+ */
+export interface WalletConfigWithStorage extends BaseConfigWithStorage {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient & {
+        chain: VanaChain;
+    };
+}
+/**
+ * Configuration with chain and account details
+ *
+ * @category Configuration
+ */
+export interface ChainConfig extends BaseConfig {
+    /**
+     * The chain ID for Vana network.
+     *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).
+     *   Use chain constants from '@vana/sdk' for type safety.
+     */
+    chainId: VanaChainId;
+    /**
+     * RPC URL for the chain (optional, will use default for the chain if not provided).
+     *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).
+     *   Override for custom nodes or local development.
+     */
+    rpcUrl?: string;
+    /**
+     * Optional account for signing transactions.
+     *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.
+     *   Required for write operations; read-only operations work without account.
+     */
+    account?: Account;
+}
+/**
+ * Configuration with chain and account details that requires storage
+ *
+ * @category Configuration
+ */
+export interface ChainConfigWithStorage extends BaseConfigWithStorage {
+    /** The chain ID for Vana network */
+    chainId: VanaChainId;
+    /** RPC URL for the chain (optional, will use default for the chain if not provided) */
+    rpcUrl?: string;
+    /** Optional account for signing transactions */
+    account?: Account;
+}
+/**
+ * Configuration with wallet client and optional public client
+ *
+ * @category Configuration
+ */
+export interface VanaConfigWithWallet extends BaseConfig {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient;
+    /** Optional PublicClient for read operations (derived from wallet if not provided) */
+    publicClient?: PublicClient;
+}
+/**
+ * Configuration for read-only operations with public client and address
+ *
+ * @category Configuration
+ */
+export interface VanaConfigReadOnly extends BaseConfig {
+    /** The viem PublicClient instance for read operations */
+    publicClient: PublicClient;
+    /** The user's address for read operations */
+    address: Address;
+}
+/**
+ * Configuration for minimal read-only operations with just an address
+ *
+ * @category Configuration
+ */
+export interface VanaConfigAddressOnly extends BaseConfig {
+    /** The user's address for read operations */
+    address: Address;
+    /** Optional chain configuration (will use default if not provided) */
+    chain?: Chain;
+}
+/**
+ * Configuration with wallet client and optional public client that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient;
+    /** Optional PublicClient for read operations (derived from wallet if not provided) */
+    publicClient?: PublicClient;
+}
+/**
+ * Configuration for read-only operations with public client and address that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {
+    /** The viem PublicClient instance for read operations */
+    publicClient: PublicClient;
+    /** The user's address for read operations */
+    address: Address;
+}
+/**
+ * Configuration for minimal read-only operations with just an address that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigAddressOnlyWithStorage extends BaseConfigWithStorage {
+    /** The user's address for read operations */
+    address: Address;
+    /** Optional chain configuration (will use default if not provided) */
+    chain?: Chain;
+}
+/**
+ * Main configuration interface for initializing the Vana SDK.
+ *
+ * The SDK supports three initialization modes:
+ * 1. Full mode with wallet client for signing transactions
+ * 2. Read-only mode with public client and address for read operations
+ * 3. Minimal mode with just an address and optional chain
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * // Mode 1: Full configuration with wallet client
+ * const configWithWallet: VanaConfig = {
+ *   walletClient: createWalletClient({
+ *     account: privateKeyToAccount('0x...'),
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   })
+ * };
+ *
+ * // Mode 2: Read-only with public client and address
+ * const configReadOnly: VanaConfig = {
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   address: '0x1234...'
+ * };
+ *
+ * // Mode 3: Minimal with just address
+ * const configMinimal: VanaConfig = {
+ *   address: '0x1234...',
+ *   chain: moksha // optional
+ * };
+ * ```
+ */
+export type VanaConfig = VanaConfigWithWallet | VanaConfigReadOnly | VanaConfigAddressOnly | WalletConfig | ChainConfig;
+/**
+ * Configuration interface for Vana SDK that requires storage providers.
+ *
+ * Use this type when you need to ensure storage is configured for operations
+ * like file uploads, permission grants without pre-stored URLs, or schema creation.
+ * Supports all three initialization modes with required storage.
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * // Full configuration with wallet client and storage
+ * const configWithWallet: VanaConfigWithStorage = {
+ *   walletClient: createWalletClient({
+ *     account: privateKeyToAccount('0x...'),
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   storage: {
+ *     providers: {
+ *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })
+ *     },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * };
+ *
+ * // Read-only configuration with storage
+ * const configReadOnly: VanaConfigWithStorage = {
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   address: '0x1234...',
+ *   storage: {
+ *     providers: {
+ *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })
+ *     },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * };
+ * ```
+ */
+export type VanaConfigWithStorage = VanaConfigWithWalletWithStorage | VanaConfigReadOnlyWithStorage | VanaConfigAddressOnlyWithStorage | WalletConfigWithStorage | ChainConfigWithStorage;
+/**
+ * Runtime configuration information
+ *
+ * @category Configuration
+ */
+export interface RuntimeConfig {
+    /** Current chain ID */
+    chainId: VanaChainId;
+    /** Current chain name */
+    chainName: string;
+    /** Available storage providers */
+    storageProviders: string[];
+    /** Default storage provider */
+    defaultStorageProvider?: string;
+    /** Current relayer configuration */
+    relayerConfig?: RelayerConfig;
+}
+/**
+ * Validates whether a configuration object has a wallet client (any wallet-based config).
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config contains a walletClient
+ * @example
+ * ```typescript
+ * if (isWalletConfig(config)) {
+ *   console.log('Using wallet client:', config.walletClient.account?.address);
+ * } else {
+ *   console.log('Read-only or chain config');
+ * }
+ * ```
+ */
+export declare function isWalletConfig(config: VanaConfig): config is VanaConfigWithWallet | WalletConfig;
+/**
+ * Validates whether a configuration object is a read-only config with public client.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has publicClient and address but no walletClient
+ * @example
+ * ```typescript
+ * if (isReadOnlyConfig(config)) {
+ *   console.log('Read-only mode with address:', config.address);
+ * }
+ * ```
+ */
+export declare function isReadOnlyConfig(config: VanaConfig): config is VanaConfigReadOnly;
+/**
+ * Validates whether a configuration object is an address-only config.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has only address (and optionally chain) but no clients
+ * @example
+ * ```typescript
+ * if (isAddressOnlyConfig(config)) {
+ *   console.log('Address-only mode:', config.address);
+ * }
+ * ```
+ */
+export declare function isAddressOnlyConfig(config: VanaConfig): config is VanaConfigAddressOnly;
+/**
+ * Validates whether a configuration object is a ChainConfig.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config is a ChainConfig (contains chainId but not walletClient)
+ * @example
+ * ```typescript
+ * if (isChainConfig(config)) {
+ *   console.log('Chain ID:', config.chainId);
+ *   console.log('RPC URL:', config.rpcUrl);
+ * } else {
+ *   console.log('Using pre-configured wallet client');
+ * }
+ * ```
+ */
+export declare function isChainConfig(config: VanaConfig): config is ChainConfig;
+/**
+ * Validates whether a configuration has required storage providers.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has storage providers configured
+ * @example
+ * ```typescript
+ * if (hasStorageConfig(config)) {
+ *   // Safe to use storage-dependent operations
+ *   await vana.data.uploadFile(file);
+ * } else {
+ *   console.log('Storage not configured - some operations may fail');
+ * }
+ * ```
+ */
+export declare function hasStorageConfig(config: VanaConfig): config is VanaConfigWithStorage;
+/**
+ * Configuration validation options
+ *
+ * @category Configuration
+ */
+export interface ConfigValidationOptions {
+    /** Whether to validate storage providers */
+    validateStorage?: boolean;
+    /** Whether to validate relayer URL */
+    validateRelayer?: boolean;
+    /** Whether to validate chain configuration */
+    validateChain?: boolean;
+}
+/**
+ * Configuration validation result
+ *
+ * @category Configuration
+ */
+export interface ConfigValidationResult {
+    /** Whether the configuration is valid */
+    valid: boolean;
+    /** List of validation errors */
+    errors: string[];
+    /** List of validation warnings */
+    warnings: string[];
+}
+/**
+ * Marker interface to enforce the presence of operationStore at compile time.
+ * This interface is used to ensure that certain operations requiring a relayer
+ * can only be called when the SDK has been properly configured with an operation store.
+ *
+ * @category Configuration
+ */
+export interface RelayerRequiredMarker {
+    readonly __relayerConfigured: true;
+}