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

package/dist/types/storage.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Defines interface for storage provider implementations.
+ *
+ * @remarks
+ * Abstracts storage backends (IPFS, Google Drive, Pinata) behind
+ * common interface for encrypted file operations.
+ *
+ * @category Storage
+ * @example
+ * ```typescript
+ * class MyStorage implements StorageProvider {
+ *   async upload(file: Blob): Promise<StorageUploadResult> {
+ *     const url = await uploadToService(file);
+ *     return { url, size: file.size, contentType: file.type };
+ *   }
+ *
+ *   async download(url: string): Promise<Blob> {
+ *     return fetch(url).then(r => r.blob());
+ *   }
+ * }
+ * ```
+ */
+export interface StorageProvider {
+    /**
+     * Upload a file to the storage provider
+     *
+     * @param file - The file to upload
+     * @param filename - Optional custom filename
+     * @returns Promise with storage URL and metadata
+     */
+    upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
+    /**
+     * Download a file from the storage provider
+     *
+     * @param url - The storage URL
+     * @returns Promise with file blob
+     */
+    download(url: string): Promise<Blob>;
+    /**
+     * List files from the storage provider
+     *
+     * @param options - Optional filtering and pagination
+     * @returns Promise with file list
+     */
+    list(options?: StorageListOptions): Promise<StorageFile[]>;
+    /**
+     * Delete a file from the storage provider
+     *
+     * @param url - The storage URL
+     * @returns Promise with success status
+     */
+    delete(url: string): Promise<boolean>;
+    /**
+     * Get provider-specific configuration
+     *
+     * @returns Provider configuration object
+     */
+    getConfig(): StorageProviderConfig;
+}
+export interface StorageUploadResult {
+    /** Public URL to access the file */
+    url: string;
+    /** File size in bytes */
+    size: number;
+    /** Content type/MIME type */
+    contentType: string;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface StorageFile {
+    /** File identifier */
+    id: string;
+    /** File name */
+    name: string;
+    /** Public URL to access the file */
+    url: string;
+    /** File size in bytes */
+    size: number;
+    /** Content type/MIME type */
+    contentType: string;
+    /** Upload timestamp */
+    createdAt: Date;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface StorageListOptions {
+    /** Maximum number of files to return */
+    limit?: number;
+    /** Pagination cursor/offset */
+    offset?: string | number;
+    /** Filter by file name pattern */
+    namePattern?: string;
+    /** Filter by content type */
+    contentType?: string;
+}
+export interface StorageProviderConfig {
+    /** Provider name */
+    name: string;
+    /** Provider type */
+    type: string;
+    /** Whether authentication is required */
+    requiresAuth: boolean;
+    /** Supported features */
+    features: {
+        upload: boolean;
+        download: boolean;
+        list: boolean;
+        delete: boolean;
+    };
+}
+export declare class StorageError extends Error {
+    readonly code: string;
+    readonly provider: string;
+    constructor(message: string, code: string, provider: string, options?: {
+        cause?: Error;
+    });
+}

package/dist/types/storage.js

@@ -0,0 +1,15 @@
+class StorageError extends Error {
+  code;
+  provider;
+  // The 'cause' property is now inherited from the base Error class
+  constructor(message, code, provider, options) {
+    super(message, options);
+    this.name = "StorageError";
+    this.code = code;
+    this.provider = provider;
+  }
+}
+export {
+  StorageError
+};
+//# sourceMappingURL=storage.js.map

package/dist/types/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/storage.ts"],"sourcesContent":["/**\n * Defines interface for storage provider implementations.\n *\n * @remarks\n * Abstracts storage backends (IPFS, Google Drive, Pinata) behind\n * common interface for encrypted file operations.\n *\n * @category Storage\n * @example\n * ```typescript\n * class MyStorage implements StorageProvider {\n *   async upload(file: Blob): Promise<StorageUploadResult> {\n *     const url = await uploadToService(file);\n *     return { url, size: file.size, contentType: file.type };\n *   }\n *\n *   async download(url: string): Promise<Blob> {\n *     return fetch(url).then(r => r.blob());\n *   }\n * }\n * ```\n */\nexport interface StorageProvider {\n  /**\n   * Upload a file to the storage provider\n   *\n   * @param file - The file to upload\n   * @param filename - Optional custom filename\n   * @returns Promise with storage URL and metadata\n   */\n  upload(file: Blob, filename?: string): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with file blob\n   */\n  download(url: string): Promise<Blob>;\n\n  /**\n   * List files from the storage provider\n   *\n   * @param options - Optional filtering and pagination\n   * @returns Promise with file list\n   */\n  list(options?: StorageListOptions): Promise<StorageFile[]>;\n\n  /**\n   * Delete a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with success status\n   */\n  delete(url: string): Promise<boolean>;\n\n  /**\n   * Get provider-specific configuration\n   *\n   * @returns Provider configuration object\n   */\n  getConfig(): StorageProviderConfig;\n}\n\nexport interface StorageUploadResult {\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageFile {\n  /** File identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Upload timestamp */\n  createdAt: Date;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageListOptions {\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Pagination cursor/offset */\n  offset?: string | number;\n  /** Filter by file name pattern */\n  namePattern?: string;\n  /** Filter by content type */\n  contentType?: string;\n}\n\nexport interface StorageProviderConfig {\n  /** Provider name */\n  name: string;\n  /** Provider type */\n  type: string;\n  /** Whether authentication is required */\n  requiresAuth: boolean;\n  /** Supported features */\n  features: {\n    upload: boolean;\n    download: boolean;\n    list: boolean;\n    delete: boolean;\n  };\n}\n\nexport class StorageError extends Error {\n  public readonly code: string;\n  public readonly provider: string;\n  // The 'cause' property is now inherited from the base Error class\n\n  constructor(\n    message: string,\n    code: string,\n    provider: string,\n    options?: { cause?: Error },\n  ) {\n    // Pass the options object with 'cause' to the super constructor\n    super(message, options);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.provider = provider;\n  }\n}\n"],"mappings":"AAuHO,MAAM,qBAAqB,MAAM;AAAA,EACtB;AAAA,EACA;AAAA;AAAA,EAGhB,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;","names":[]}

package/dist/types/transactionResults.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var transactionResults_exports = {};
+module.exports = __toCommonJS(transactionResults_exports);
+//# sourceMappingURL=transactionResults.cjs.map

package/dist/types/transactionResults.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/transactionResults.ts"],"sourcesContent":["import type { Address } from \"viem\";\n// BaseTransactionResult will be replaced once migration is complete\ninterface BaseTransactionResult {\n  transactionHash: `0x${string}`;\n  blockNumber: bigint;\n  gasUsed: bigint;\n}\n\n/**\n * Transaction result types for all SDK operations.\n * These interfaces define the structure of data returned by enhanced\n * transaction methods that parse blockchain events automatically.\n */\n\n// =============================================================================\n// PERMISSION OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful permission grant operation.\n * Contains data from the PermissionAdded blockchain event.\n */\nexport interface PermissionGrantResult extends BaseTransactionResult {\n  /** Unique permission ID for this grant */\n  permissionId: bigint;\n  /** Address of the user who granted the permission */\n  user: Address;\n  /** URL where the grant file is stored (IPFS/CDN) */\n  grant: string;\n  /** Array of file IDs covered by this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * Result of a successful permission revocation operation.\n * Contains data from the PermissionRevoked blockchain event.\n */\nexport interface PermissionRevokeResult extends BaseTransactionResult {\n  /** ID of the permission that was revoked */\n  permissionId: bigint;\n}\n\n/**\n * Result of a successful server trust operation.\n * Contains data from the ServerTrusted blockchain event.\n */\nexport interface ServerTrustResult extends BaseTransactionResult {\n  /** Address of the user who trusted the server (from event) */\n  user: Address;\n  /** Numeric ID of the trusted server (from event) */\n  serverId: bigint;\n  /** Address of the trusted server (from params/derived) */\n  serverAddress?: Address;\n  /** URL of the trusted server (from params/provided) */\n  serverUrl?: string;\n}\n\n/**\n * Result of a successful server untrust operation.\n * Contains data from the ServerUntrusted blockchain event.\n */\nexport interface ServerUntrustResult extends BaseTransactionResult {\n  /** Address of the user who untrusted the server */\n  user: Address;\n  /** Address/ID of the untrusted server */\n  serverId: Address;\n}\n\n/**\n * Result of a successful server registration operation.\n * Contains data from the ServerRegistered blockchain event.\n */\nexport interface ServerRegisterResult extends BaseTransactionResult {\n  /** Unique server ID assigned by the registry */\n  serverId: bigint;\n  /** URL of the registered server */\n  url: string;\n  /** Owner address of the server */\n  owner: Address;\n}\n\n/**\n * Result of a successful server update operation.\n * Contains data from the ServerUpdated blockchain event.\n */\nexport interface ServerUpdateResult extends BaseTransactionResult {\n  /** ID of the server that was updated */\n  serverId: bigint;\n  /** New URL of the server */\n  url: string;\n}\n\n/**\n * Result of a successful grantee registration operation.\n * Contains data from the GranteeRegistered blockchain event.\n */\nexport interface GranteeRegisterResult extends BaseTransactionResult {\n  /** Unique grantee ID assigned by the registry */\n  granteeId: bigint;\n  /** Address of the registered grantee */\n  granteeAddress: Address;\n  /** Display name of the grantee */\n  name: string;\n}\n\n// =============================================================================\n// DATA REGISTRY OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful file addition operation.\n * Contains data from the FileAddedV2 blockchain event.\n */\nexport interface FileAddedResult extends BaseTransactionResult {\n  /** Unique file ID assigned by the registry */\n  fileId: bigint;\n  /** Address of the file owner */\n  ownerAddress: Address;\n  /** URL where the file is stored */\n  url: string;\n  /** Schema ID associated with the file (0 for no schema) */\n  schemaId: bigint;\n}\n\n/**\n * Result of a successful schema addition operation.\n * Contains data from the SchemaAdded blockchain event.\n */\nexport interface SchemaAddedResult extends BaseTransactionResult {\n  /** Unique schema ID assigned by the registry */\n  schemaId: bigint;\n  /** Human-readable name of the schema */\n  name: string;\n  /** Schema dialect (e.g., \"jsonschema\") */\n  dialect: string;\n  /** URL where the schema definition is stored */\n  definitionUrl: string;\n}\n\n/**\n * Result of a successful refiner addition operation.\n * Contains data from the RefinerAdded blockchain event.\n */\nexport interface RefinerAddedResult extends BaseTransactionResult {\n  /** Unique refiner ID assigned by the registry */\n  refinerId: bigint;\n  /** DLP ID this refiner belongs to */\n  dlpId: bigint;\n  /** Human-readable name of the refiner */\n  name: string;\n  /** Schema ID this refiner uses */\n  schemaId: bigint;\n  /** URL where the schema definition is stored */\n  schemaDefinitionUrl: string;\n  /** URL with refiner processing instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Result of a successful schema ID update operation.\n * Contains data from the RefinerSchemaUpdated blockchain event.\n */\nexport interface SchemaUpdateResult extends BaseTransactionResult {\n  /** ID of the refiner that was updated */\n  refinerId: bigint;\n  /** New schema ID */\n  schemaId: bigint;\n  /** URL of the new schema definition */\n  schemaDefinitionUrl: string;\n}\n\n/**\n * Result of a successful file permission addition operation.\n * Contains data from the FilePermissionAdded blockchain event.\n */\nexport interface FilePermissionResult extends BaseTransactionResult {\n  /** File ID the permission was added to */\n  fileId: bigint;\n  /** Account that was granted permission */\n  account: Address;\n  /** Encrypted key for file access */\n  encryptedKey: string;\n}\n\n// =============================================================================\n// UNION TYPES FOR GENERIC OPERATIONS\n// =============================================================================\n\n/**\n * Union type of all possible transaction result types.\n * Useful for generic functions that handle multiple operation types.\n */\nexport type AnyTransactionResult =\n  | PermissionGrantResult\n  | PermissionRevokeResult\n  | ServerTrustResult\n  | ServerUntrustResult\n  | ServerRegisterResult\n  | ServerUpdateResult\n  | GranteeRegisterResult\n  | FileAddedResult\n  | SchemaAddedResult\n  | RefinerAddedResult\n  | SchemaUpdateResult\n  | FilePermissionResult;\n\n// =============================================================================\n// TYPE UTILITIES\n// =============================================================================\n\n/**\n * Maps transaction operation names to their result types.\n * Used for type inference in generic transaction parsing functions.\n */\nexport interface TransactionResultMap {\n  grant: PermissionGrantResult;\n  revoke: PermissionRevokeResult;\n  revokePermission: PermissionRevokeResult;\n  addServerFilesAndPermissions: PermissionGrantResult;\n  trustServer: ServerTrustResult;\n  untrustServer: ServerUntrustResult;\n  registerServer: ServerRegisterResult;\n  updateServer: ServerUpdateResult;\n  addAndTrustServer: ServerTrustResult;\n  registerGrantee: GranteeRegisterResult;\n  addFile: FileAddedResult;\n  addFileWithPermissionsAndSchema: FileAddedResult;\n  addFileWithSchema: FileAddedResult;\n  addFileWithPermissions: FileAddedResult;\n  addRefinement: RefinerAddedResult;\n  addRefiner: RefinerAddedResult;\n  updateSchemaId: SchemaUpdateResult;\n  addSchema: SchemaAddedResult;\n  updateRefinement: SchemaUpdateResult;\n  addFilePermission: FilePermissionResult;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/transactionResults.d.ts

@@ -0,0 +1,193 @@
+import type { Address } from "viem";
+interface BaseTransactionResult {
+    transactionHash: `0x${string}`;
+    blockNumber: bigint;
+    gasUsed: bigint;
+}
+/**
+ * Transaction result types for all SDK operations.
+ * These interfaces define the structure of data returned by enhanced
+ * transaction methods that parse blockchain events automatically.
+ */
+/**
+ * Result of a successful permission grant operation.
+ * Contains data from the PermissionAdded blockchain event.
+ */
+export interface PermissionGrantResult extends BaseTransactionResult {
+    /** Unique permission ID for this grant */
+    permissionId: bigint;
+    /** Address of the user who granted the permission */
+    user: Address;
+    /** URL where the grant file is stored (IPFS/CDN) */
+    grant: string;
+    /** Array of file IDs covered by this permission */
+    fileIds: readonly bigint[];
+}
+/**
+ * Result of a successful permission revocation operation.
+ * Contains data from the PermissionRevoked blockchain event.
+ */
+export interface PermissionRevokeResult extends BaseTransactionResult {
+    /** ID of the permission that was revoked */
+    permissionId: bigint;
+}
+/**
+ * Result of a successful server trust operation.
+ * Contains data from the ServerTrusted blockchain event.
+ */
+export interface ServerTrustResult extends BaseTransactionResult {
+    /** Address of the user who trusted the server (from event) */
+    user: Address;
+    /** Numeric ID of the trusted server (from event) */
+    serverId: bigint;
+    /** Address of the trusted server (from params/derived) */
+    serverAddress?: Address;
+    /** URL of the trusted server (from params/provided) */
+    serverUrl?: string;
+}
+/**
+ * Result of a successful server untrust operation.
+ * Contains data from the ServerUntrusted blockchain event.
+ */
+export interface ServerUntrustResult extends BaseTransactionResult {
+    /** Address of the user who untrusted the server */
+    user: Address;
+    /** Address/ID of the untrusted server */
+    serverId: Address;
+}
+/**
+ * Result of a successful server registration operation.
+ * Contains data from the ServerRegistered blockchain event.
+ */
+export interface ServerRegisterResult extends BaseTransactionResult {
+    /** Unique server ID assigned by the registry */
+    serverId: bigint;
+    /** URL of the registered server */
+    url: string;
+    /** Owner address of the server */
+    owner: Address;
+}
+/**
+ * Result of a successful server update operation.
+ * Contains data from the ServerUpdated blockchain event.
+ */
+export interface ServerUpdateResult extends BaseTransactionResult {
+    /** ID of the server that was updated */
+    serverId: bigint;
+    /** New URL of the server */
+    url: string;
+}
+/**
+ * Result of a successful grantee registration operation.
+ * Contains data from the GranteeRegistered blockchain event.
+ */
+export interface GranteeRegisterResult extends BaseTransactionResult {
+    /** Unique grantee ID assigned by the registry */
+    granteeId: bigint;
+    /** Address of the registered grantee */
+    granteeAddress: Address;
+    /** Display name of the grantee */
+    name: string;
+}
+/**
+ * Result of a successful file addition operation.
+ * Contains data from the FileAddedV2 blockchain event.
+ */
+export interface FileAddedResult extends BaseTransactionResult {
+    /** Unique file ID assigned by the registry */
+    fileId: bigint;
+    /** Address of the file owner */
+    ownerAddress: Address;
+    /** URL where the file is stored */
+    url: string;
+    /** Schema ID associated with the file (0 for no schema) */
+    schemaId: bigint;
+}
+/**
+ * Result of a successful schema addition operation.
+ * Contains data from the SchemaAdded blockchain event.
+ */
+export interface SchemaAddedResult extends BaseTransactionResult {
+    /** Unique schema ID assigned by the registry */
+    schemaId: bigint;
+    /** Human-readable name of the schema */
+    name: string;
+    /** Schema dialect (e.g., "jsonschema") */
+    dialect: string;
+    /** URL where the schema definition is stored */
+    definitionUrl: string;
+}
+/**
+ * Result of a successful refiner addition operation.
+ * Contains data from the RefinerAdded blockchain event.
+ */
+export interface RefinerAddedResult extends BaseTransactionResult {
+    /** Unique refiner ID assigned by the registry */
+    refinerId: bigint;
+    /** DLP ID this refiner belongs to */
+    dlpId: bigint;
+    /** Human-readable name of the refiner */
+    name: string;
+    /** Schema ID this refiner uses */
+    schemaId: bigint;
+    /** URL where the schema definition is stored */
+    schemaDefinitionUrl: string;
+    /** URL with refiner processing instructions */
+    refinementInstructionUrl: string;
+}
+/**
+ * Result of a successful schema ID update operation.
+ * Contains data from the RefinerSchemaUpdated blockchain event.
+ */
+export interface SchemaUpdateResult extends BaseTransactionResult {
+    /** ID of the refiner that was updated */
+    refinerId: bigint;
+    /** New schema ID */
+    schemaId: bigint;
+    /** URL of the new schema definition */
+    schemaDefinitionUrl: string;
+}
+/**
+ * Result of a successful file permission addition operation.
+ * Contains data from the FilePermissionAdded blockchain event.
+ */
+export interface FilePermissionResult extends BaseTransactionResult {
+    /** File ID the permission was added to */
+    fileId: bigint;
+    /** Account that was granted permission */
+    account: Address;
+    /** Encrypted key for file access */
+    encryptedKey: string;
+}
+/**
+ * Union type of all possible transaction result types.
+ * Useful for generic functions that handle multiple operation types.
+ */
+export type AnyTransactionResult = PermissionGrantResult | PermissionRevokeResult | ServerTrustResult | ServerUntrustResult | ServerRegisterResult | ServerUpdateResult | GranteeRegisterResult | FileAddedResult | SchemaAddedResult | RefinerAddedResult | SchemaUpdateResult | FilePermissionResult;
+/**
+ * Maps transaction operation names to their result types.
+ * Used for type inference in generic transaction parsing functions.
+ */
+export interface TransactionResultMap {
+    grant: PermissionGrantResult;
+    revoke: PermissionRevokeResult;
+    revokePermission: PermissionRevokeResult;
+    addServerFilesAndPermissions: PermissionGrantResult;
+    trustServer: ServerTrustResult;
+    untrustServer: ServerUntrustResult;
+    registerServer: ServerRegisterResult;
+    updateServer: ServerUpdateResult;
+    addAndTrustServer: ServerTrustResult;
+    registerGrantee: GranteeRegisterResult;
+    addFile: FileAddedResult;
+    addFileWithPermissionsAndSchema: FileAddedResult;
+    addFileWithSchema: FileAddedResult;
+    addFileWithPermissions: FileAddedResult;
+    addRefinement: RefinerAddedResult;
+    addRefiner: RefinerAddedResult;
+    updateSchemaId: SchemaUpdateResult;
+    addSchema: SchemaAddedResult;
+    updateRefinement: SchemaUpdateResult;
+    addFilePermission: FilePermissionResult;
+}
+export {};

package/dist/types/transactionResults.js

@@ -0,0 +1 @@
+//# sourceMappingURL=transactionResults.js.map

package/dist/types/transactionResults.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/utils.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var utils_exports = {};
+module.exports = __toCommonJS(utils_exports);
+//# sourceMappingURL=utils.cjs.map

package/dist/types/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/utils.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Makes all properties in T optional except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are optional, but specific properties remain required.\n * Commonly used for update operations where only certain fields must be provided.\n *\n * @example\n * ```typescript\n * interface User {\n *   id: string;\n *   name: string;\n *   email: string;\n *   age: number;\n * }\n *\n * // Only 'id' is required, all other properties are optional\n * type UserUpdate = PartialExcept<User, 'id'>;\n *\n * const update: UserUpdate = {\n *   id: '123', // Required\n *   name: 'John' // Optional\n *   // email and age are also optional\n * };\n * ```\n * @category Reference\n */\nexport type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;\n\n/**\n * Makes all properties in T required except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are required, but specific properties remain optional.\n * Commonly used for creation operations where most fields are mandatory.\n *\n * @example\n * ```typescript\n * interface Config {\n *   apiUrl: string;\n *   timeout?: number;\n *   retries?: number;\n *   debug?: boolean;\n * }\n *\n * // All properties required except 'debug'\n * type StrictConfig = RequiredExcept<Config, 'debug'>;\n *\n * const config: StrictConfig = {\n *   apiUrl: 'https://api.vana.com', // Required\n *   timeout: 5000, // Required (was optional, now required)\n *   retries: 3, // Required (was optional, now required)\n *   // debug remains optional\n * };\n * ```\n * @category Reference\n */\nexport type RequiredExcept<T, K extends keyof T> = Required<T> &\n  Partial<Pick<T, K>>;\n\n/**\n * Extracts the return type of a promise\n *\n * @remarks\n * This utility type unwraps the type contained within a Promise.\n * If the type is not a Promise, it returns the type unchanged.\n * Note: TypeScript 4.5+ includes a built-in Awaited type with similar functionality.\n *\n * @example\n * ```typescript\n * type AsyncString = Promise<string>;\n * type SyncString = string;\n *\n * // Extracts 'string' from Promise<string>\n * type Result1 = Awaited<AsyncString>; // string\n *\n * // Returns 'string' unchanged since it's not a Promise\n * type Result2 = Awaited<SyncString>; // string\n *\n * // Practical usage with async functions\n * async function fetchUser(): Promise<{ id: string; name: string }> {\n *   // ...\n * }\n *\n * type User = Awaited<ReturnType<typeof fetchUser>>; // { id: string; name: string }\n * ```\n * @category Reference\n */\nexport type Awaited<T> = T extends Promise<infer U> ? U : T;\n\n/**\n * Creates a type that accepts either T or a Promise<T>\n *\n * @remarks\n * This utility type is useful for functions that can work with both\n * synchronous and asynchronous values. It allows flexible APIs that\n * can accept immediate values or promises that resolve to those values.\n *\n * @example\n * ```typescript\n * // Function that accepts either a value or a promise of that value\n * async function processData(data: MaybePromise<string>): Promise<string> {\n *   // await works on both promises and regular values\n *   const resolved = await data;\n *   return resolved.toUpperCase();\n * }\n *\n * // Both calls are valid:\n * processData('hello'); // Synchronous value\n * processData(Promise.resolve('world')); // Asynchronous value\n *\n * // Common use case in SDK callbacks\n * interface StorageProvider {\n *   // Provider can implement sync or async file reading\n *   read(path: string): MaybePromise<Buffer>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * Creates a type that accepts either T or an array of T\n *\n * @remarks\n * This utility type is useful for functions that can accept either a single\n * value or an array of values, providing a more flexible API. The implementation\n * can normalize the input to always work with arrays internally.\n *\n * @example\n * ```typescript\n * // Function that accepts either a single ID or multiple IDs\n * function deleteItems(ids: MaybeArray<string>): void {\n *   // Normalize to array\n *   const idArray = Array.isArray(ids) ? ids : [ids];\n *   idArray.forEach(id => console.log(`Deleting ${id}`));\n * }\n *\n * // Both calls are valid:\n * deleteItems('item-1'); // Single item\n * deleteItems(['item-1', 'item-2', 'item-3']); // Multiple items\n *\n * // Common use case in permissions\n * interface GrantPermissionsParams {\n *   permissions: MaybeArray<Permission>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybeArray<T> = T | T[];\n\n/**\n * Pagination parameters for controlling result set size and navigation.\n *\n * Used across SDK methods that return lists of items to control how many items\n * are returned and to navigate through large result sets efficiently.\n *\n * @category Reference\n * @example\n * ```typescript\n * const pagination: PaginationParams = {\n *   limit: 20, // Return 20 items\n *   offset: 40, // Skip first 40 items (page 3)\n *   cursor: 'eyJpZCI6MTIzfQ==' // Or use cursor-based pagination\n * };\n *\n * const files = await vana.data.getUserFiles({\n *   owner: userAddress,\n *   pagination\n * });\n * ```\n */\nexport interface PaginationParams {\n  /** Maximum number of items to return */\n  limit?: number;\n  /** Number of items to skip */\n  offset?: number;\n  /** Cursor for cursor-based pagination */\n  cursor?: string;\n}\n\n/**\n * Pagination result containing items and metadata for navigating large datasets.\n *\n * @remarks\n * This interface standardizes paginated responses across the SDK, providing\n * consistent metadata for implementing pagination UI components and handling\n * multi-page data fetching. Supports both offset-based and cursor-based pagination.\n *\n * @example\n * ```typescript\n * // Fetching paginated user files\n * async function getAllUserFiles(userAddress: string): Promise<File[]> {\n *   const allFiles: File[] = [];\n *   let cursor: string | undefined;\n *\n *   do {\n *     const result: PaginationResult<File> = await vana.data.getUserFiles({\n *       owner: userAddress,\n *       pagination: { limit: 50, cursor }\n *     });\n *\n *     allFiles.push(...result.items);\n *     cursor = result.nextCursor;\n *\n *     console.log(`Fetched ${result.count} of ${result.total} files`);\n *   } while (result.hasMore);\n *\n *   return allFiles;\n * }\n * ```\n * @category Reference\n */\nexport interface PaginationResult<T> {\n  /** Array of items */\n  items: T[];\n  /** Total number of items available */\n  total: number;\n  /** Number of items returned */\n  count: number;\n  /** Whether there are more items available */\n  hasMore: boolean;\n  /** Cursor for next page */\n  nextCursor?: string;\n}\n\n/**\n * Block range parameters for filtering blockchain events and transactions.\n *\n * @remarks\n * Used to specify a range of blocks when querying blockchain data.\n * Both parameters are optional - omitting fromBlock starts from genesis,\n * omitting toBlock goes to the latest block. Be cautious with large ranges\n * as they may result in heavy RPC loads or timeouts.\n *\n * @example\n * ```typescript\n * // Get events from the last 1000 blocks\n * const currentBlock = await vana.protocol.getBlockNumber();\n * const events = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: currentBlock - 1000n,\n *     toBlock: currentBlock\n *   }\n * });\n *\n * // Get all historical events (use with caution)\n * const allEvents = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: 0n\n *     // toBlock omitted = up to latest\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface BlockRange {\n  /** Starting block number */\n  fromBlock?: bigint;\n  /** Ending block number */\n  toBlock?: bigint;\n}\n\n/**\n * Transaction receipt with additional metadata for tracking transaction results.\n *\n * @remarks\n * Provides comprehensive information about executed transactions including\n * gas usage, success status, and emitted events. Use the logs array to\n * decode events emitted by smart contracts during transaction execution.\n * The receipt is available after a transaction is mined and included in a block.\n *\n * @example\n * ```typescript\n * // Execute transaction and wait for receipt\n * const receipt = await vana.permissions.grant({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Check transaction success\n * if (receipt.status === 'success') {\n *   console.log(`Gas used: ${receipt.gasUsed}`);\n *   console.log(`Block: ${receipt.blockNumber}`);\n *\n *   // Decode events from logs\n *   receipt.logs.forEach(log => {\n *     if (log.topics[0] === PERMISSION_GRANTED_TOPIC) {\n *       console.log('Permission granted event detected');\n *     }\n *   });\n * } else {\n *   console.error('Transaction reverted');\n * }\n * ```\n * @category Reference\n */\nexport interface TransactionReceipt {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number */\n  blockNumber: bigint;\n  /** Block hash */\n  blockHash: Hash;\n  /** Gas used */\n  gasUsed: bigint;\n  /** Transaction status */\n  status: \"success\" | \"reverted\";\n  /** Contract address if contract deployment */\n  contractAddress?: Address;\n  /** Event logs */\n  logs: Array<{\n    address: Address;\n    topics: Hash[];\n    data: string;\n  }>;\n}\n\n/**\n * Response wrapper for API results providing consistent error handling.\n *\n * @remarks\n * Standardizes API responses across the SDK, making it easy to handle\n * both successful and failed requests. The generic type parameter T\n * represents the expected data type for successful responses. Check\n * the success flag before accessing data to ensure type safety.\n *\n * @example\n * ```typescript\n * // Handling API responses\n * async function fetchUserData(userId: string): Promise<User | null> {\n *   const response: ApiResponse<User> = await api.getUser(userId);\n *\n *   if (response.success) {\n *     console.log('User fetched:', response.data.name);\n *     // Access metadata if available\n *     if (response.metadata?.cached) {\n *       console.log('Data was cached');\n *     }\n *     return response.data;\n *   } else {\n *     console.error('Failed to fetch user:', response.error);\n *     return null;\n *   }\n * }\n *\n * // Type-safe error handling\n * interface UserData {\n *   id: string;\n *   name: string;\n * }\n *\n * const result: ApiResponse<UserData> = await api.call('/users/123');\n * if (result.success) {\n *   // TypeScript knows result.data is UserData here\n *   console.log(result.data.name);\n * }\n * ```\n * @category Reference\n */\nexport interface ApiResponse<T> {\n  /** Response data */\n  data: T;\n  /** Success status */\n  success: boolean;\n  /** Error message if not successful */\n  error?: string;\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Retry configuration for handling transient failures with exponential backoff.\n *\n * @remarks\n * Configures automatic retry behavior for operations that may fail due to\n * temporary issues like network problems or rate limits. Supports exponential\n * backoff to avoid overwhelming services. The shouldRetry function allows\n * custom logic to determine which errors warrant a retry attempt.\n *\n * @example\n * ```typescript\n * // Simple retry configuration\n * const basicRetry: RetryConfig = {\n *   attempts: 3,\n *   delay: 1000 // 1 second between retries\n * };\n *\n * // Exponential backoff configuration\n * const exponentialRetry: RetryConfig = {\n *   attempts: 5,\n *   delay: 1000,\n *   backoffMultiplier: 2, // Double delay each time\n *   maxDelay: 30000, // Cap at 30 seconds\n *   shouldRetry: (error) => {\n *     // Only retry network and timeout errors\n *     return error.name === 'NetworkError' ||\n *            error.message.includes('timeout');\n *   }\n * };\n *\n * // Usage with SDK\n * const vana = new Vana({\n *   retryConfig: exponentialRetry\n * });\n * ```\n * @category Reference\n */\nexport interface RetryConfig {\n  /** Number of retry attempts */\n  attempts: number;\n  /** Delay between retries in milliseconds */\n  delay: number;\n  /** Backoff multiplier */\n  backoffMultiplier?: number;\n  /** Maximum delay in milliseconds */\n  maxDelay?: number;\n  /** Function to determine if error should be retried */\n  shouldRetry?: (error: Error) => boolean;\n}\n\n/**\n * Cache configuration for optimizing repeated data fetches.\n *\n * @remarks\n * Configures in-memory caching behavior to reduce redundant API calls and\n * improve performance. The cache automatically evicts expired entries based\n * on TTL and removes least-recently-used items when maxSize is reached.\n * Use appropriate TTL values based on your data freshness requirements.\n *\n * @example\n * ```typescript\n * // Short-lived cache for frequently changing data\n * const userCache: CacheConfig = {\n *   ttl: 60000, // 1 minute\n *   maxSize: 100, // Store up to 100 users\n *   prefix: 'user:' // Cache keys like 'user:123'\n * };\n *\n * // Long-lived cache for stable data\n * const schemaCache: CacheConfig = {\n *   ttl: 3600000, // 1 hour\n *   maxSize: 1000, // Store up to 1000 schemas\n *   prefix: 'schema:'\n * };\n *\n * // Disable caching by setting TTL to 0\n * const noCache: CacheConfig = {\n *   ttl: 0 // No caching\n * };\n * ```\n * @category Reference\n */\nexport interface CacheConfig {\n  /** Cache TTL in milliseconds */\n  ttl: number;\n  /** Maximum cache size */\n  maxSize?: number;\n  /** Cache key prefix */\n  prefix?: string;\n}\n\n/**\n * Validation result for data integrity checks and schema validation.\n *\n * @remarks\n * Provides detailed feedback about validation outcomes, distinguishing between\n * errors (which prevent processing) and warnings (which indicate potential issues).\n * Used throughout the SDK for validating permissions, file formats, schemas,\n * and API parameters before operations.\n *\n * @example\n * ```typescript\n * // Validating user input\n * function validateFileUpload(file: File): ValidationResult {\n *   const errors: string[] = [];\n *   const warnings: string[] = [];\n *\n *   // Check file size\n *   if (file.size > 100 * 1024 * 1024) {\n *     errors.push('File size exceeds 100MB limit');\n *   } else if (file.size > 50 * 1024 * 1024) {\n *     warnings.push('Large file may take time to upload');\n *   }\n *\n *   // Check file type\n *   if (!file.type.startsWith('image/')) {\n *     errors.push('Only image files are allowed');\n *   }\n *\n *   return {\n *     valid: errors.length === 0,\n *     errors,\n *     warnings\n *   };\n * }\n *\n * // Using validation result\n * const result = validateFileUpload(file);\n * if (!result.valid) {\n *   console.error('Validation failed:', result.errors.join(', '));\n * } else {\n *   if (result.warnings.length > 0) {\n *     console.warn('Warnings:', result.warnings.join(', '));\n *   }\n *   // Proceed with upload\n * }\n * ```\n * @category Reference\n */\nexport interface ValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors */\n  errors: string[];\n  /** Validation warnings */\n  warnings: string[];\n}\n\n/**\n * Status information for health checks and service monitoring.\n *\n * @remarks\n * Used to report the health status of various SDK components including\n * storage providers, RPC connections, and personal servers. The details\n * field can contain provider-specific information for debugging.\n * Timestamps use Unix epoch milliseconds.\n *\n * @example\n * ```typescript\n * // Checking storage provider health\n * const status: StatusInfo = await storage.getStatus();\n *\n * if (!status.healthy) {\n *   console.error(`Storage unhealthy: ${status.message}`);\n *   // Check how long the issue has persisted\n *   const downtime = Date.now() - status.lastCheck;\n *   if (downtime > 300000) { // 5 minutes\n *     // Switch to backup provider\n *   }\n * }\n *\n * // Detailed status with custom fields\n * const serverStatus: StatusInfo = {\n *   healthy: true,\n *   message: 'All systems operational',\n *   lastCheck: Date.now(),\n *   details: {\n *     uptime: 3600000, // 1 hour\n *     requestsServed: 1234,\n *     avgResponseTime: 145, // ms\n *     activeConnections: 23\n *   }\n * };\n * ```\n * @category Reference\n */\nexport interface StatusInfo {\n  /** Whether the service is healthy */\n  healthy: boolean;\n  /** Status message */\n  message?: string;\n  /** Last check timestamp */\n  lastCheck: number;\n  /** Additional status details */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Rate limit information for API throttling and quota management.\n *\n * @remarks\n * Provides visibility into rate limiting status to help applications\n * implement appropriate backoff strategies. Rate limits protect services\n * from overload and ensure fair resource usage. Use this information\n * to pace requests and avoid hitting limits.\n *\n * @example\n * ```typescript\n * // Check rate limit before making requests\n * const rateLimit: RateLimitInfo = await api.getRateLimit();\n *\n * console.log(`Requests: ${rateLimit.requests}/${rateLimit.limit}`);\n * console.log(`Resets in: ${rateLimit.resetTime} seconds`);\n *\n * // Implement backoff if approaching limit\n * if (rateLimit.requests >= rateLimit.limit * 0.9) {\n *   console.warn('Approaching rate limit, slowing down');\n *   await new Promise(resolve =>\n *     setTimeout(resolve, rateLimit.resetTime * 1000)\n *   );\n * }\n *\n * // Calculate requests per second allowed\n * const rps = rateLimit.limit / rateLimit.window;\n * console.log(`Max ${rps} requests per second allowed`);\n * ```\n * @category Reference\n */\nexport interface RateLimitInfo {\n  /** Current request count */\n  requests: number;\n  /** Maximum requests allowed */\n  limit: number;\n  /** Time window in seconds */\n  window: number;\n  /** Time until reset in seconds */\n  resetTime: number;\n}\n\n/**\n * File upload progress tracking for user feedback and monitoring.\n *\n * @remarks\n * Provides real-time progress information during file uploads, enabling\n * applications to show progress bars and estimated completion times.\n * The speed calculation is typically based on a rolling average to\n * smooth out network fluctuations.\n *\n * @example\n * ```typescript\n * // Upload with progress tracking\n * await vana.data.upload(file, {\n *   onProgress: (progress: UploadProgress) => {\n *     // Update progress bar\n *     progressBar.style.width = `${progress.percentage}%`;\n *\n *     // Show upload speed\n *     const speedMBps = (progress.speed / 1024 / 1024).toFixed(2);\n *     speedDisplay.textContent = `${speedMBps} MB/s`;\n *\n *     // Show time remaining\n *     const minutes = Math.floor(progress.estimatedTimeRemaining / 60);\n *     const seconds = progress.estimatedTimeRemaining % 60;\n *     timeDisplay.textContent = `${minutes}:${seconds.toString().padStart(2, '0')}`;\n *\n *     // Log progress milestones\n *     if (progress.percentage === 25 ||\n *         progress.percentage === 50 ||\n *         progress.percentage === 75) {\n *       console.log(`Upload ${progress.percentage}% complete`);\n *     }\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface UploadProgress {\n  /** Bytes uploaded */\n  loaded: number;\n  /** Total bytes to upload */\n  total: number;\n  /** Upload percentage (0-100) */\n  percentage: number;\n  /** Upload speed in bytes per second */\n  speed: number;\n  /** Estimated time remaining in seconds */\n  estimatedTimeRemaining: number;\n}\n\n/**\n * Network information for blockchain connectivity and monitoring.\n *\n * @remarks\n * Provides comprehensive details about the connected blockchain network,\n * including configuration URLs and real-time status. Use this information\n * to verify network connectivity, display network details to users, and\n * construct explorer links for transactions.\n *\n * @example\n * ```typescript\n * // Get current network info\n * const network: NetworkInfo = await vana.protocol.getNetworkInfo();\n *\n * console.log(`Connected to: ${network.chainName} (ID: ${network.chainId})`);\n * console.log(`Current block: ${network.currentBlock}`);\n *\n * // Check network health\n * if (network.status !== 'healthy') {\n *   console.warn(`Network ${network.status}: consider switching RPC`);\n * }\n *\n * // Generate explorer link for transaction\n * function getExplorerLink(txHash: string): string {\n *   if (!network.explorerUrl) {\n *     return `Transaction: ${txHash}`;\n *   }\n *   return `${network.explorerUrl}/tx/${txHash}`;\n * }\n *\n * // Verify expected network\n * const EXPECTED_CHAIN_ID = 1337; // Vana testnet\n * if (network.chainId !== EXPECTED_CHAIN_ID) {\n *   throw new Error(`Wrong network! Expected ${EXPECTED_CHAIN_ID}, got ${network.chainId}`);\n * }\n * ```\n * @category Reference\n */\nexport interface NetworkInfo {\n  /** Chain ID */\n  chainId: number;\n  /** Chain name */\n  chainName: string;\n  /** RPC URL */\n  rpcUrl: string;\n  /** Block explorer URL */\n  explorerUrl?: string;\n  /** Current block number */\n  currentBlock: bigint;\n  /** Network status */\n  status: \"healthy\" | \"degraded\" | \"down\";\n}\n\n/**\n * Gas estimate information for transaction cost prediction.\n *\n * @remarks\n * Provides detailed gas pricing estimates to help users understand transaction\n * costs before execution. Supports both legacy (gasPrice) and EIP-1559\n * (maxFeePerGas) pricing models. The estimatedCost is calculated based on\n * current network conditions and may vary by the time of actual execution.\n *\n * @example\n * ```typescript\n * // Get gas estimate before transaction\n * const estimate: GasEstimate = await vana.permissions.estimateGas({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Convert to human-readable format\n * const costInEth = Number(estimate.estimatedCost) / 1e18;\n * console.log(`Estimated cost: ${costInEth.toFixed(6)} ETH`);\n *\n * // Check if user has sufficient balance\n * const balance = await vana.protocol.getBalance(userAddress);\n * if (balance < estimate.estimatedCost) {\n *   throw new Error(`Insufficient balance. Need ${costInEth} ETH`);\n * }\n *\n * // Use estimate for transaction with buffer\n * await vana.permissions.grant(params, {\n *   gasLimit: estimate.gasLimit * 110n / 100n, // 10% buffer\n *   maxFeePerGas: estimate.maxFeePerGas,\n *   maxPriorityFeePerGas: estimate.maxPriorityFeePerGas\n * });\n * ```\n * @category Reference\n */\nexport interface GasEstimate {\n  /** Gas limit */\n  gasLimit: bigint;\n  /** Gas price */\n  gasPrice: bigint;\n  /** Max fee per gas */\n  maxFeePerGas?: bigint;\n  /** Max priority fee per gas */\n  maxPriorityFeePerGas?: bigint;\n  /** Estimated cost in wei */\n  estimatedCost: bigint;\n}\n\n/**\n * Time range parameters for filtering operations by time period.\n *\n * Used in various SDK methods to specify date/time ranges for queries,\n * analytics, and data filtering operations. Times are specified as Unix timestamps.\n *\n * @category Reference\n * @example\n * ```typescript\n * const lastWeek: TimeRange = {\n *   from: Date.now() - (7 * 24 * 60 * 60 * 1000), // 7 days ago\n *   to: Date.now()\n * };\n *\n * const permissions = await vana.permissions.getUserPermissions({\n *   timeRange: lastWeek\n * });\n * ```\n */\nexport interface TimeRange {\n  /** Start time (Unix timestamp) */\n  from?: number;\n  /** End time (Unix timestamp) */\n  to?: number;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}