@opendatalabs/vana-sdk 0.1.0-alpha.d6bebb0 → 0.1.0-alpha.d7fc764

package/dist/core.d.ts

@@ -0,0 +1,466 @@
+import { Operation, PollingOptions, TransactionResult, TransactionWaitOptions } from './types/operations.js';
+import * as viem from 'viem';
+import { VanaConfigWithStorage, VanaConfig, StorageRequiredMarker, RuntimeConfig } from './types/config.js';
+import { SchemaController } from './controllers/schemas.js';
+import { P as PermissionsController } from './permissions-eo8YeLGf.js';
+import { DataController } from './controllers/data.js';
+import { ServerController } from './controllers/server.js';
+import { ProtocolController } from './controllers/protocol.js';
+import { VanaPlatformAdapter } from './platform/interface.js';
+import './generated/server/server-exports.js';
+import './generated/server/server.js';
+import './types/chains.js';
+import './types/storage.js';
+import './types/permissions.js';
+import './types/data.js';
+import './config/eventMappings.js';
+import './generated/abi/index.js';
+import './generated/abi/DataPortabilityPermissionsImplementation.js';
+import './generated/abi/DataPortabilityServersImplementation.js';
+import './generated/abi/DataPortabilityGranteesImplementation.js';
+import './generated/abi/VanaEpochImplementation.js';
+import './generated/abi/DLPRegistryImplementation.js';
+import './generated/abi/DLPTreasuryImplementation.js';
+import './generated/abi/DLPRewardDeployerTreasuryImplementation.js';
+import './generated/abi/DLPPerformanceImplementation.js';
+import './generated/abi/DLPRewardDeployerImplementation.js';
+import './generated/abi/DLPRootImplementation.js';
+import './generated/abi/DataLiquidityPoolImplementation.js';
+import './generated/abi/DLPRegistryTreasuryImplementation.js';
+import './storage/manager.js';
+import './utils/schemaValidation.js';
+import './types/personal.js';
+import './types/contracts.js';
+import './contracts/contractController.js';
+import 'abitype';
+import './core/client.js';
+import './config/chains.js';
+
+/**
+ * Factory functions for creating VanaCore instances with proper type safety
+ */
+declare class VanaCoreFactory {
+    /**
+     * Creates a VanaCore instance that enforces storage requirements at compile time.
+     * Use this factory when you know you'll need storage-dependent operations.
+     *
+     * @param platform - The platform adapter for environment-specific operations
+     * @param config - Configuration that includes required storage providers
+     * @returns VanaCore instance with storage validation
+     * @example
+     * ```typescript
+     * const vanaCore = VanaCoreFactory.createWithStorage(platformAdapter, {
+     *   walletClient: myWalletClient,
+     *   storage: {
+     *     providers: { ipfs: new IPFSStorage() },
+     *     defaultProvider: 'ipfs'
+     *   }
+     * });
+     * ```
+     */
+    static createWithStorage(platform: VanaPlatformAdapter, config: VanaConfigWithStorage): VanaCore & StorageRequiredMarker;
+    /**
+     * Creates a VanaCore instance without storage requirements.
+     * Storage-dependent operations will fail at runtime if not configured.
+     *
+     * @param platform - The platform adapter for environment-specific operations
+     * @param config - Basic configuration without required storage
+     * @returns VanaCore instance
+     * @example
+     * ```typescript
+     * const vanaCore = VanaCoreFactory.create(platformAdapter, {
+     *   walletClient: myWalletClient
+     * });
+     * ```
+     */
+    static create(platform: VanaPlatformAdapter, config: VanaConfig): VanaCore;
+}
+/**
+ * Provides the core SDK functionality for interacting with the Vana network.
+ *
+ * @remarks
+ * This environment-agnostic class contains all SDK logic and accepts a platform
+ * adapter to handle environment-specific operations. It initializes all controllers
+ * and manages shared context between them, providing a unified interface for
+ * data management, permissions, smart contracts, and storage operations.
+ *
+ * The class uses TypeScript overloading to enforce storage requirements at compile time.
+ * Methods that require storage will throw `InvalidConfigurationError` at runtime if
+ * storage providers are not configured, implementing a fail-fast approach to prevent
+ * errors during expensive operations.
+ *
+ * **Core Architecture:**
+ * - **Controllers**: Specialized modules for different Vana features (data, permissions, etc.)
+ * - **Platform Adapters**: Environment-specific implementations (browser vs Node.js)
+ * - **Storage Managers**: Abstraction layer for multiple storage providers
+ * - **Context Sharing**: Unified configuration and services across all controllers
+ *
+ * For public usage, use the platform-specific factory functions:
+ * - Browser: `import { Vana } from '@opendatalabs/vana-sdk/browser'`
+ * - Node.js: `import { Vana } from '@opendatalabs/vana-sdk/node'`
+ *
+ * @example
+ * ```typescript
+ * // Direct instantiation (advanced usage)
+ * import { VanaCore, BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';
+ *
+ * const core = new VanaCore(new BrowserPlatformAdapter(), {
+ *   walletClient: myWalletClient,
+ *   storage: {
+ *     providers: { ipfs: new IPFSStorage() },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * });
+ *
+ * // Access all controllers
+ * const files = await core.data.getUserFiles();
+ * const permissions = await core.permissions.grant({
+ *   grantee: '0x742d35...',
+ *   operation: 'read'
+ * });
+ * ```
+ * @category Core SDK
+ */
+declare class VanaCore {
+    /** Manages gasless data access permissions and trusted server registry. */
+    readonly permissions: PermissionsController;
+    /** Handles user data file operations. */
+    readonly data: DataController;
+    /** Manages data schemas and refiners. */
+    readonly schemas: SchemaController;
+    /** Provides personal server setup and trusted server interactions. */
+    readonly server: ServerController;
+    /** Offers low-level access to Vana protocol smart contracts. */
+    readonly protocol: ProtocolController;
+    /** Handles environment-specific operations like encryption and file systems. */
+    protected platform: VanaPlatformAdapter;
+    private readonly relayerCallbacks?;
+    private readonly downloadRelayer?;
+    private readonly storageManager?;
+    private readonly hasRequiredStorage;
+    private readonly ipfsGateways?;
+    private readonly defaultPersonalServerUrl?;
+    private readonly publicClient;
+    private readonly walletClient;
+    /**
+     * Initializes a new VanaCore client instance with the provided configuration.
+     *
+     * @remarks
+     * The constructor validates the configuration, initializes storage providers if configured,
+     * creates wallet and public clients, and sets up all SDK controllers with shared context.
+     *
+     * IMPORTANT: This constructor will validate storage requirements at runtime to fail fast.
+     * Methods that require storage will throw runtime errors if storage is not configured.
+     *
+     * @param platform - The platform adapter for environment-specific operations
+     * @param config - The configuration object specifying wallet or chain settings
+     * @throws {InvalidConfigurationError} When the configuration is invalid or incomplete
+     * @example
+     * ```typescript
+     * // Direct instantiation (consider using factory methods instead)
+     * const vanaCore = new VanaCore(platformAdapter, {
+     *   walletClient: myWalletClient,
+     * });
+     * ```
+     */
+    constructor(platform: VanaPlatformAdapter, config: VanaConfig);
+    /**
+     * Validates that storage is available for storage-dependent operations.
+     * This method enforces the fail-fast principle by checking storage availability
+     * at method call time rather than during expensive operations.
+     *
+     * @throws {InvalidConfigurationError} When storage is required but not configured
+     * @example
+     * ```typescript
+     * // This will throw if storage is not configured
+     * vana.validateStorageRequired();
+     * await vana.data.uploadFile(file); // Safe to proceed
+     * ```
+     */
+    validateStorageRequired(): void;
+    /**
+     * Checks whether storage is configured without throwing an error.
+     *
+     * @returns True if storage is properly configured
+     * @example
+     * ```typescript
+     * if (vana.hasStorage()) {
+     *   await vana.data.uploadFile(file);
+     * } else {
+     *   console.warn('Storage not configured - using pre-stored URLs only');
+     * }
+     * ```
+     */
+    hasStorage(): boolean;
+    /**
+     * Type guard to check if this instance has storage enabled at compile time.
+     * Use this when you need TypeScript to understand that storage is available.
+     *
+     * @returns True if storage is configured, with type narrowing
+     * @example
+     * ```typescript
+     * if (vana.isStorageEnabled()) {
+     *   // TypeScript knows storage is available here
+     *   await vana.data.uploadFile(file);
+     * }
+     * ```
+     */
+    isStorageEnabled(): this is VanaCore & StorageRequiredMarker;
+    /**
+     * Validates the provided configuration object against all requirements.
+     *
+     * @remarks
+     * This method performs comprehensive validation of wallet client configuration,
+     * chain configuration, storage providers, and relayer callbacks.
+     * @param config - The configuration object to validate
+     * @throws {InvalidConfigurationError} When any configuration parameter is invalid
+     */
+    private validateConfig;
+    /**
+     * Gets the current chain ID from the wallet client.
+     *
+     * @returns The numeric chain ID of the connected network
+     * @example
+     * ```typescript
+     * const chainId = vana.chainId;
+     * console.log(`Connected to chain: ${chainId}`); // e.g., "Connected to chain: 14800"
+     * ```
+     */
+    get chainId(): number;
+    /**
+     * Gets the current chain name from the wallet client.
+     *
+     * @returns The human-readable name of the connected network
+     * @example
+     * ```typescript
+     * const chainName = vana.chainName;
+     * console.log(`Connected to: ${chainName}`); // e.g., "Connected to: Moksha Testnet"
+     * ```
+     */
+    get chainName(): string;
+    /**
+     * Retrieves the user's wallet address from the connected client.
+     *
+     * @returns A Promise that resolves to the user's Ethereum address
+     * @example
+     * ```typescript
+     * const address = await vana.getUserAddress();
+     * console.log(`User address: ${address}`); // e.g., "User address: 0x742d35..."
+     * ```
+     */
+    getUserAddress(): Promise<viem.Address>;
+    /**
+     * Retrieves comprehensive runtime configuration information.
+     *
+     * @returns The current runtime configuration including chain, storage, and relayer settings
+     * @example
+     * ```typescript
+     * const config = vana.getConfig();
+     * console.log(`Chain: ${config.chainName} (${config.chainId})`);
+     * console.log(`Storage providers: ${config.storageProviders.join(", ")}`);
+     * ```
+     */
+    getConfig(): RuntimeConfig;
+    /**
+     * Sets the platform adapter for environment-specific operations.
+     * This is useful for testing and advanced use cases where you need
+     * to override the default platform detection.
+     *
+     * @param adapter - The platform adapter to use
+     * @example
+     * ```typescript
+     * // For testing with a mock adapter
+     * const mockAdapter = new MockPlatformAdapter();
+     * vana.setPlatformAdapter(mockAdapter);
+     *
+     * // For advanced use cases with custom adapters
+     * const customAdapter = new CustomPlatformAdapter();
+     * vana.setPlatformAdapter(customAdapter);
+     * ```
+     */
+    setPlatformAdapter(adapter: VanaPlatformAdapter): void;
+    /**
+     * Gets the current platform adapter.
+     * This is useful for advanced use cases where you need to access
+     * the platform adapter directly.
+     *
+     * @returns The current platform adapter
+     * @example
+     * ```typescript
+     * const adapter = vana.getPlatformAdapter();
+     * const encrypted = await adapter.encrypt(data, key);
+     * ```
+     */
+    getPlatformAdapter(): VanaPlatformAdapter;
+    /**
+     * Encrypts data using the Vana protocol standard encryption.
+     *
+     * @remarks
+     * This method implements the Vana network's standard encryption protocol using
+     * platform-appropriate cryptographic libraries. It automatically handles different
+     * input types (string or Blob) and produces encrypted output suitable for secure
+     * storage or transmission. The encryption is compatible with the network's
+     * decryption protocols and can be decrypted by authorized parties.
+     *
+     * @param data - The data to encrypt (string or Blob)
+     * @param key - The encryption key (typically generated via `generateEncryptionKey`)
+     * @returns The encrypted data as a Blob
+     * @throws {Error} When encryption fails due to invalid key or data format
+     * @example
+     * ```typescript
+     * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+     *
+     * // Generate encryption key from wallet signature
+     * const encryptionKey = await generateEncryptionKey(vana.walletClient);
+     *
+     * // Encrypt string data
+     * const sensitiveData = "User's private information";
+     * const encrypted = await vana.encryptBlob(sensitiveData, encryptionKey);
+     *
+     * // Encrypt file data
+     * const fileBlob = new Blob([fileContent], { type: 'application/json' });
+     * const encryptedFile = await vana.encryptBlob(fileBlob, encryptionKey);
+     *
+     * // Store encrypted data safely
+     * await storageProvider.upload(encrypted, 'encrypted-data.bin');
+     * ```
+     */
+    encryptBlob(data: string | Blob, key: string): Promise<Blob>;
+    /**
+     * Decrypts data that was encrypted using the Vana protocol.
+     *
+     * @remarks
+     * This method decrypts data that was previously encrypted using the Vana network's
+     * standard encryption protocol. It requires the same wallet signature that was used
+     * for encryption and automatically uses the appropriate platform adapter for
+     * cryptographic operations. The decrypted output maintains the original data format.
+     *
+     * @param encryptedData - The encrypted data (string or Blob)
+     * @param walletSignature - The wallet signature used as decryption key
+     * @returns The decrypted data as a Blob
+     * @throws {Error} When decryption fails due to invalid signature or corrupted data
+     * @example
+     * ```typescript
+     * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+     *
+     * // Retrieve encrypted data from storage
+     * const encryptedBlob = await storageProvider.download('encrypted-data.bin');
+     *
+     * // Generate the same key used for encryption
+     * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+     *
+     * // Decrypt the data
+     * const decrypted = await vana.decryptBlob(encryptedBlob, decryptionKey);
+     *
+     * // Convert back to original format
+     * const originalText = await decrypted.text();
+     * const originalJson = JSON.parse(originalText);
+     *
+     * console.log('Decrypted data:', originalJson);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Decrypt file downloaded from Vana network
+     * const userFiles = await vana.data.getUserFiles();
+     * const file = userFiles[0];
+     *
+     * // Download encrypted content
+     * const encrypted = await fetch(file.url).then(r => r.blob());
+     *
+     * // Decrypt with user's key
+     * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+     * const decrypted = await vana.decryptBlob(encrypted, decryptionKey);
+     *
+     * // Process original data
+     * const fileContent = await decrypted.arrayBuffer();
+     * ```
+     */
+    decryptBlob(encryptedData: string | Blob, walletSignature: string): Promise<Blob>;
+    /**
+     * Waits for an operation to complete and returns the final result.
+     *
+     * @remarks
+     * This method polls the operation status at regular intervals until it
+     * reaches a terminal state (succeeded, failed, or canceled). Supports
+     * ergonomic overloads to accept either an Operation object or just the ID.
+     *
+     * @param opOrId - Either an Operation object or operation ID string
+     * @param options - Optional polling configuration
+     * @returns The completed operation with result or error
+     * @throws {PersonalServerError} When the operation fails or times out
+     * @example
+     * ```typescript
+     * // Using operation object
+     * const operation = await vana.server.createOperation({ permissionId: 123 });
+     * const completed = await vana.waitForOperation(operation);
+     *
+     * // Using just the ID
+     * const completed = await vana.waitForOperation("op_abc123");
+     *
+     * // With custom timeout
+     * const completed = await vana.waitForOperation(operation, {
+     *   timeout: 60000,
+     *   pollingInterval: 1000
+     * });
+     * ```
+     */
+    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
+    /**
+     * Waits for a transaction to be confirmed and returns the receipt.
+     *
+     * @remarks
+     * This method polls for transaction confirmation on the blockchain.
+     * Supports ergonomic overloads to accept either a transaction result
+     * object or just the hash string.
+     *
+     * @param hashOrObj - Either a TransactionResult object or hash string
+     * @param options - Optional wait configuration
+     * @returns The transaction receipt with logs and status
+     * @example
+     * ```typescript
+     * // Using transaction result object
+     * const tx = await vana.permissions.grant(params);
+     * const receipt = await vana.waitForTransactionReceipt(tx);
+     *
+     * // Using just the hash
+     * const receipt = await vana.waitForTransactionReceipt("0x123...");
+     *
+     * // With custom confirmations
+     * const receipt = await vana.waitForTransactionReceipt(tx, {
+     *   confirmations: 3,
+     *   timeout: 60000
+     * });
+     * ```
+     */
+    waitForTransactionReceipt(hashOrObj: TransactionResult | {
+        hash: viem.Hash;
+    } | viem.Hash, options?: TransactionWaitOptions): Promise<viem.TransactionReceipt>;
+    /**
+     * Waits for transaction confirmation and parses events.
+     *
+     * @remarks
+     * This method waits for a transaction to be confirmed and then
+     * parses the logs to extract typed event data. The specific event
+     * type depends on the transaction operation.
+     *
+     * @param hashOrObj - Either a TransactionResult object or hash string
+     * @param options - Optional wait configuration
+     * @returns The parsed event data from the transaction
+     * @example
+     * ```typescript
+     * // Wait for permission grant events
+     * const tx = await vana.permissions.grant(params);
+     * const events = await vana.waitForTransactionEvents(tx);
+     * console.log(`Permission ID: ${events.permissionId}`);
+     *
+     * // Using just the hash
+     * const events = await vana.waitForTransactionEvents("0x123...");
+     * ```
+     */
+    waitForTransactionEvents<T = unknown>(hashOrObj: TransactionResult | {
+        hash: viem.Hash;
+    } | viem.Hash, options?: TransactionWaitOptions): Promise<T>;
+}
+
+export { VanaCore, VanaCoreFactory };