@opendatalabs/vana-sdk 0.1.0-alpha.db07fe1 → 0.1.0-alpha.dc68f39

package/dist/core.js

@@ -0,0 +1,681 @@
+import {
+  isWalletConfig,
+  isChainConfig,
+  isReadOnlyConfig,
+  isAddressOnlyConfig,
+  isVanaChainId,
+  hasStorageConfig
+} from "./types";
+import { InvalidConfigurationError } from "./errors";
+import { PermissionsController } from "./controllers/permissions";
+import { DataController } from "./controllers/data";
+import { SchemaController } from "./controllers/schemas";
+import { ServerController } from "./controllers/server";
+import { ProtocolController } from "./controllers/protocol";
+import { StorageManager } from "./storage";
+import { createWalletClient, createPublicClient, http } from "viem";
+import { extractAddress } from "./utils/wallet";
+import { chains } from "./config/chains";
+import { getChainConfig, vanaMainnet } from "./chains";
+import {
+  encryptBlobWithSignedKey,
+  decryptBlobWithSignedKey
+} from "./utils/encryption";
+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, config) {
+    const core = new VanaCore(platform, config);
+    return core;
+  }
+  /**
+   * 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, config) {
+    return new VanaCore(platform, config);
+  }
+}
+class VanaCore {
+  /** Manages gasless data access permissions and trusted server registry. */
+  permissions;
+  /** Handles user data file operations. */
+  data;
+  /** Manages data schemas and refiners. */
+  schemas;
+  /** Provides personal server setup and trusted server interactions. */
+  server;
+  /** Offers low-level access to Vana protocol smart contracts. */
+  protocol;
+  /** Handles environment-specific operations like encryption and file systems. */
+  platform;
+  relayerCallbacks;
+  downloadRelayer;
+  storageManager;
+  hasRequiredStorage;
+  ipfsGateways;
+  publicClient;
+  walletClient;
+  _staticUserAddress;
+  // For read-only mode
+  /**
+   * 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, config) {
+    this.platform = platform;
+    this.validateConfig(config);
+    this.relayerCallbacks = config.relayerCallbacks;
+    this.downloadRelayer = config.downloadRelayer;
+    this.ipfsGateways = config.ipfsGateways;
+    this.hasRequiredStorage = hasStorageConfig(config);
+    if (config.storage?.providers) {
+      this.storageManager = new StorageManager();
+      for (const [name, provider] of Object.entries(config.storage.providers)) {
+        const isDefault = name === config.storage.defaultProvider;
+        this.storageManager.register(name, provider, isDefault);
+      }
+      if (!config.storage.defaultProvider && Object.keys(config.storage.providers).length > 0) {
+        const firstProviderName = Object.keys(config.storage.providers)[0];
+        this.storageManager.setDefaultProvider(firstProviderName);
+      }
+    }
+    let walletClient;
+    let publicClient;
+    let staticUserAddress;
+    let chainToUse;
+    if (isWalletConfig(config)) {
+      walletClient = config.walletClient;
+      chainToUse = walletClient.chain ?? vanaMainnet;
+      staticUserAddress = void 0;
+      if ("publicClient" in config && config.publicClient) {
+        publicClient = config.publicClient;
+      } else {
+        publicClient = createPublicClient({
+          chain: chainToUse,
+          transport: http()
+        });
+      }
+    } else if (isReadOnlyConfig(config)) {
+      walletClient = void 0;
+      publicClient = config.publicClient;
+      staticUserAddress = config.address;
+      chainToUse = config.publicClient.chain ?? vanaMainnet;
+    } else if (isAddressOnlyConfig(config)) {
+      walletClient = void 0;
+      staticUserAddress = config.address;
+      chainToUse = config.chain ?? vanaMainnet;
+      publicClient = createPublicClient({
+        chain: chainToUse,
+        transport: http()
+      });
+    } else if (isChainConfig(config)) {
+      if (!config.account) {
+        throw new InvalidConfigurationError(
+          "Account is required when using ChainConfig"
+        );
+      }
+      const chain = chains[config.chainId];
+      if (!chain) {
+        throw new InvalidConfigurationError(
+          `Unsupported chain ID: ${config.chainId}`
+        );
+      }
+      chainToUse = chain;
+      walletClient = createWalletClient({
+        chain,
+        transport: http(config.rpcUrl ?? chain.rpcUrls.default.http[0]),
+        account: config.account
+      });
+      staticUserAddress = void 0;
+      publicClient = createPublicClient({
+        chain,
+        transport: http()
+      });
+    } else {
+      throw new InvalidConfigurationError(
+        "Invalid configuration: must provide either walletClient, publicClient + address, or address alone"
+      );
+    }
+    this.publicClient = publicClient;
+    this.walletClient = walletClient;
+    this._staticUserAddress = staticUserAddress;
+    const chainConfig = getChainConfig(chainToUse.id);
+    const subgraphUrl = config.subgraphUrl ?? chainConfig?.subgraphUrl;
+    const personalServerUrl = config.defaultPersonalServerUrl ?? chainConfig?.personalServerUrl;
+    const self = this;
+    const sharedContext = {
+      walletClient,
+      publicClient,
+      get userAddress() {
+        return self.userAddress;
+      },
+      applicationClient: walletClient,
+      // Using same wallet for now
+      relayerCallbacks: this.relayerCallbacks,
+      downloadRelayer: this.downloadRelayer,
+      storageManager: this.storageManager,
+      subgraphUrl,
+      platform: this.platform,
+      // Pass the platform adapter to controllers
+      validateStorageRequired: this.validateStorageRequired.bind(this),
+      hasStorage: this.hasStorage.bind(this),
+      ipfsGateways: this.ipfsGateways,
+      defaultPersonalServerUrl: personalServerUrl,
+      waitForTransactionEvents: this.waitForTransactionEvents.bind(this),
+      waitForOperation: this.waitForOperation.bind(this)
+    };
+    this.permissions = new PermissionsController(sharedContext);
+    this.data = new DataController(sharedContext);
+    this.schemas = new SchemaController(sharedContext);
+    this.server = new ServerController(sharedContext);
+    this.protocol = new ProtocolController(sharedContext);
+  }
+  /**
+   * 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() {
+    if (!this.hasRequiredStorage) {
+      throw new InvalidConfigurationError(
+        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayerCallbacks.storeGrantFile implementation, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
+      );
+    }
+  }
+  /**
+   * 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() {
+    return this.hasRequiredStorage;
+  }
+  /**
+   * 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() {
+    return this.hasRequiredStorage;
+  }
+  /**
+   * 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
+   */
+  validateConfig(config) {
+    if (!config) {
+      throw new InvalidConfigurationError("Configuration object is required");
+    }
+    if (config.relayerCallbacks !== void 0) {
+      if (typeof config.relayerCallbacks !== "object") {
+        throw new InvalidConfigurationError(
+          "relayerCallbacks must be an object"
+        );
+      }
+    }
+    if (config.storage?.providers) {
+      if (typeof config.storage.providers !== "object") {
+        throw new InvalidConfigurationError(
+          "storage.providers must be an object"
+        );
+      }
+      for (const [name, provider] of Object.entries(config.storage.providers)) {
+        if (!provider || typeof provider !== "object") {
+          throw new InvalidConfigurationError(
+            `Storage provider '${name}' must be a valid StorageProvider object`
+          );
+        }
+      }
+      if (config.storage.defaultProvider) {
+        if (!(config.storage.defaultProvider in config.storage.providers)) {
+          throw new InvalidConfigurationError(
+            `Default storage provider '${config.storage.defaultProvider}' not found in providers`
+          );
+        }
+      }
+    }
+    if (isWalletConfig(config)) {
+      if (!config.walletClient) {
+        throw new InvalidConfigurationError("walletClient is required");
+      }
+      if (typeof config.walletClient !== "object" || !config.walletClient.signTypedData) {
+        throw new InvalidConfigurationError(
+          "walletClient must be a valid viem WalletClient"
+        );
+      }
+      if (!config.walletClient.chain) {
+        throw new InvalidConfigurationError(
+          "walletClient must have a chain configured"
+        );
+      }
+      if (!isVanaChainId(config.walletClient.chain.id)) {
+        throw new InvalidConfigurationError(
+          `Unsupported chain ID: ${String(config.walletClient.chain.id)}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
+        );
+      }
+    } else if (isChainConfig(config)) {
+      if (!isVanaChainId(config.chainId)) {
+        throw new InvalidConfigurationError(
+          `Unsupported chain ID: ${String(config.chainId)}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
+        );
+      }
+      if (config.rpcUrl) {
+        if (typeof config.rpcUrl !== "string") {
+          throw new InvalidConfigurationError("rpcUrl must be a string");
+        }
+        if (config.rpcUrl.trim() === "") {
+          throw new InvalidConfigurationError("rpcUrl cannot be empty");
+        }
+        try {
+          new URL(config.rpcUrl);
+        } catch {
+          throw new InvalidConfigurationError("rpcUrl must be a valid URL");
+        }
+      }
+      if (config.account) {
+        if (typeof config.account !== "object" || !config.account.address) {
+          throw new InvalidConfigurationError(
+            "account must be a valid viem Account object"
+          );
+        }
+      }
+    } else if (isReadOnlyConfig(config)) {
+      if (!config.publicClient) {
+        throw new InvalidConfigurationError(
+          "publicClient is required for read-only configuration"
+        );
+      }
+      if (!config.address) {
+        throw new InvalidConfigurationError(
+          "address is required for read-only configuration"
+        );
+      }
+    } else if (isAddressOnlyConfig(config)) {
+      if (!config.address) {
+        throw new InvalidConfigurationError(
+          "address is required for address-only configuration"
+        );
+      }
+    } else {
+      throw new InvalidConfigurationError(
+        "Invalid configuration: must provide either walletClient, publicClient + address, or address alone"
+      );
+    }
+  }
+  /**
+   * 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() {
+    return this.protocol.getChainId();
+  }
+  /**
+   * 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() {
+    return this.protocol.getChainName();
+  }
+  /**
+   * The user's wallet address.
+   * In wallet mode, this always returns the current wallet account address.
+   * In read-only mode, this returns the static address provided during initialization.
+   *
+   * @example
+   * ```typescript
+   * const address = vana.userAddress;
+   * console.log(`User address: ${address}`); // e.g., "User address: 0x742d35..."
+   * ```
+   */
+  get userAddress() {
+    if (this.walletClient?.account) {
+      return extractAddress(this.walletClient.account);
+    }
+    if (this._staticUserAddress) {
+      return this._staticUserAddress;
+    }
+    throw new Error("No user address available");
+  }
+  /**
+   * 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() {
+    return {
+      chainId: this.chainId,
+      chainName: this.chainName,
+      relayerCallbacks: this.relayerCallbacks,
+      storageProviders: this.storageManager?.getStorageProviders() ?? [],
+      defaultStorageProvider: this.storageManager?.getDefaultStorageProvider()
+    };
+  }
+  /**
+   * 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) {
+    this.platform = adapter;
+  }
+  /**
+   * 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() {
+    return this.platform;
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async encryptBlob(data, key) {
+    return encryptBlobWithSignedKey(data, key, this.platform);
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async decryptBlob(encryptedData, walletSignature) {
+    return decryptBlobWithSignedKey(
+      encryptedData,
+      walletSignature,
+      this.platform
+    );
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async waitForOperation(opOrId, options) {
+    return this.server.waitForOperation(opOrId, options);
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async waitForTransactionReceipt(hashOrObj, options) {
+    const hash = typeof hashOrObj === "string" ? hashOrObj : hashOrObj.hash;
+    return this.publicClient.waitForTransactionReceipt({
+      hash,
+      confirmations: options?.confirmations,
+      pollingInterval: options?.pollingInterval,
+      timeout: options?.timeout
+    });
+  }
+  /**
+   * Waits for transaction confirmation and extracts blockchain event data.
+   *
+   * @remarks
+   * This method leverages the context-carrying POJO architecture. When passed a
+   * `TransactionResult` with an `operation` field, it automatically parses the
+   * correct events from the transaction logs. For legacy compatibility, it accepts
+   * raw hashes but will not parse events without operation context.
+   *
+   * @param transaction - Transaction result with operation context
+   * @param options - Optional confirmation and timeout settings
+   * @returns Parsed event data specific to the transaction's operation type
+   * @throws {NetworkError} When transaction confirmation times out
+   * @throws {BlockchainError} When expected events are not found in the transaction
+   *
+   * @example
+   * ```typescript
+   * // Recommended: Pass the transaction result for automatic event parsing
+   * const tx = await vana.permissions.submitAddServerFilesAndPermissions(params);
+   * const events = await vana.waitForTransactionEvents<{ permissionId: bigint }>(tx);
+   * console.log(`Permission ID: ${events.permissionId}`);
+   *
+   * // Legacy: Raw hash without event parsing (returns receipt)
+   * const receipt = await vana.waitForTransactionEvents("0x123...");
+   * ```
+   *
+   * @see For understanding transaction flows, visit https://docs.vana.org/docs/transactions
+   */
+  async waitForTransactionEvents(transaction, options) {
+    const { parseTransaction } = await import("./utils/parseTransactionPojo");
+    const receipt = await this.waitForTransactionReceipt(
+      transaction.hash,
+      options
+    );
+    const result = parseTransaction(transaction, receipt);
+    return result;
+  }
+}
+export {
+  VanaCore,
+  VanaCoreFactory
+};
+//# sourceMappingURL=core.js.map