@opendatalabs/vana-sdk 0.1.0-alpha.ee24d86 → 0.1.0-alpha.eebb656

package/dist/core.cjs

@@ -0,0 +1,657 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var core_exports = {};
+__export(core_exports, {
+  VanaCore: () => VanaCore,
+  VanaCoreFactory: () => VanaCoreFactory
+});
+module.exports = __toCommonJS(core_exports);
+var import_types = require("./types");
+var import_errors = require("./errors");
+var import_permissions = require("./controllers/permissions");
+var import_data = require("./controllers/data");
+var import_schemas = require("./controllers/schemas");
+var import_server = require("./controllers/server");
+var import_protocol = require("./controllers/protocol");
+var import_storage = require("./storage");
+var import_viem = require("viem");
+var import_chains = require("./config/chains");
+var import_chains2 = require("./chains");
+var import_encryption = require("./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;
+  defaultPersonalServerUrl;
+  publicClient;
+  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, config) {
+    this.platform = platform;
+    this.validateConfig(config);
+    this.relayerCallbacks = config.relayerCallbacks;
+    this.downloadRelayer = config.downloadRelayer;
+    this.ipfsGateways = config.ipfsGateways;
+    this.defaultPersonalServerUrl = config.defaultPersonalServerUrl;
+    this.hasRequiredStorage = (0, import_types.hasStorageConfig)(config);
+    if (config.storage?.providers) {
+      this.storageManager = new import_storage.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;
+    if ((0, import_types.isWalletConfig)(config)) {
+      walletClient = config.walletClient;
+    } else if ((0, import_types.isChainConfig)(config)) {
+      if (!config.account) {
+        throw new import_errors.InvalidConfigurationError(
+          "Account is required when using ChainConfig"
+        );
+      }
+      const chain = import_chains.chains[config.chainId];
+      if (!chain) {
+        throw new import_errors.InvalidConfigurationError(
+          `Unsupported chain ID: ${config.chainId}`
+        );
+      }
+      walletClient = (0, import_viem.createWalletClient)({
+        chain,
+        transport: (0, import_viem.http)(config.rpcUrl ?? chain.rpcUrls.default.http[0]),
+        account: config.account
+      });
+    } else {
+      throw new import_errors.InvalidConfigurationError(
+        "Invalid configuration: must be either WalletConfig or ChainConfig"
+      );
+    }
+    const publicClient = (0, import_viem.createPublicClient)({
+      chain: walletClient.chain,
+      transport: (0, import_viem.http)()
+    });
+    this.publicClient = publicClient;
+    this.walletClient = walletClient;
+    const chainConfig = (0, import_chains2.getChainConfig)(walletClient.chain.id);
+    const subgraphUrl = config.subgraphUrl ?? chainConfig?.subgraphUrl;
+    const sharedContext = {
+      walletClient,
+      publicClient,
+      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: this.defaultPersonalServerUrl,
+      waitForTransactionEvents: this.waitForTransactionEvents.bind(this),
+      waitForOperation: this.waitForOperation.bind(this)
+    };
+    this.permissions = new import_permissions.PermissionsController(sharedContext);
+    this.data = new import_data.DataController(sharedContext);
+    this.schemas = new import_schemas.SchemaController(sharedContext);
+    this.server = new import_server.ServerController(sharedContext);
+    this.protocol = new import_protocol.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 import_errors.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 import_errors.InvalidConfigurationError("Configuration object is required");
+    }
+    if (config.relayerCallbacks !== void 0) {
+      if (typeof config.relayerCallbacks !== "object") {
+        throw new import_errors.InvalidConfigurationError(
+          "relayerCallbacks must be an object"
+        );
+      }
+    }
+    if (config.storage?.providers) {
+      if (typeof config.storage.providers !== "object") {
+        throw new import_errors.InvalidConfigurationError(
+          "storage.providers must be an object"
+        );
+      }
+      for (const [name, provider] of Object.entries(config.storage.providers)) {
+        if (!provider || typeof provider !== "object") {
+          throw new import_errors.InvalidConfigurationError(
+            `Storage provider '${name}' must be a valid StorageProvider object`
+          );
+        }
+      }
+      if (config.storage.defaultProvider) {
+        if (!(config.storage.defaultProvider in config.storage.providers)) {
+          throw new import_errors.InvalidConfigurationError(
+            `Default storage provider '${config.storage.defaultProvider}' not found in providers`
+          );
+        }
+      }
+    }
+    if ((0, import_types.isWalletConfig)(config)) {
+      if (!config.walletClient) {
+        throw new import_errors.InvalidConfigurationError("walletClient is required");
+      }
+      if (typeof config.walletClient !== "object" || !config.walletClient.signTypedData) {
+        throw new import_errors.InvalidConfigurationError(
+          "walletClient must be a valid viem WalletClient"
+        );
+      }
+      if (!config.walletClient.chain) {
+        throw new import_errors.InvalidConfigurationError(
+          "walletClient must have a chain configured"
+        );
+      }
+      if (!(0, import_types.isVanaChainId)(config.walletClient.chain.id)) {
+        throw new import_errors.InvalidConfigurationError(
+          `Unsupported chain ID: ${String(config.walletClient.chain.id)}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
+        );
+      }
+    } else if ((0, import_types.isChainConfig)(config)) {
+      if (!(0, import_types.isVanaChainId)(config.chainId)) {
+        throw new import_errors.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 import_errors.InvalidConfigurationError("rpcUrl must be a string");
+        }
+        if (config.rpcUrl.trim() === "") {
+          throw new import_errors.InvalidConfigurationError("rpcUrl cannot be empty");
+        }
+        try {
+          new URL(config.rpcUrl);
+        } catch {
+          throw new import_errors.InvalidConfigurationError("rpcUrl must be a valid URL");
+        }
+      }
+      if (config.account) {
+        if (typeof config.account !== "object" || !config.account.address) {
+          throw new import_errors.InvalidConfigurationError(
+            "account must be a valid viem Account object"
+          );
+        }
+      }
+    } else {
+      throw new import_errors.InvalidConfigurationError(
+        "Configuration must be either WalletConfig or ChainConfig"
+      );
+    }
+  }
+  /**
+   * 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();
+  }
+  /**
+   * 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..."
+   * ```
+   */
+  async getUserAddress() {
+    if (!this.walletClient.account) {
+      throw new Error("No wallet account connected");
+    }
+    const { account } = this.walletClient;
+    if (typeof account === "string") {
+      return account;
+    }
+    if (typeof account === "object" && account.address) {
+      return account.address;
+    }
+    throw new Error("Unable to determine wallet 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() {
+    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 (0, import_encryption.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 (0, import_encryption.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;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VanaCore,
+  VanaCoreFactory
+});
+//# sourceMappingURL=core.cjs.map