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

package/dist/types/operationStore.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 operationStore_exports = {};
+module.exports = __toCommonJS(operationStore_exports);
+//# sourceMappingURL=operationStore.cjs.map

package/dist/types/operationStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/operationStore.ts"],"sourcesContent":["/**\n * Operation storage interfaces for queuing and managing asynchronous operations.\n *\n * @module\n */\n\nimport type { Hash, TransactionReceipt } from \"viem\";\nimport type { UnifiedRelayerRequest } from \"./relayer\";\n\n/**\n * The state of an asynchronous, relayed operation.\n *\n * @remarks\n * This is the data the application backend is responsible for persisting.\n * It serves as a complete recovery log for a given operation.\n *\n * @category Operations\n */\nexport interface OperationState {\n  status: \"pending\" | \"confirmed\" | \"failed\";\n  transactionHash: Hash;\n  originalRequest: UnifiedRelayerRequest;\n  nonce?: number;\n  retryCount: number;\n  lastAttemptedGas: { maxFeePerGas?: string; maxPriorityFeePerGas?: string };\n  submittedAt: number; // Unix timestamp (ms)\n  finalReceipt?: TransactionReceipt;\n  error?: string;\n}\n\n/**\n * Simple storage interface for operation state tracking.\n *\n * @remarks\n * This interface is used by the relayer handler to track operation state\n * in a stateful mode. Implementations can use any backend storage system.\n *\n * @category Operations\n */\nexport interface IRelayerStateStore {\n  /**\n   * Gets the state of an operation.\n   *\n   * @param operationId - The operation ID\n   * @returns The operation state or null if not found\n   */\n  get(operationId: string): Promise<OperationState | null>;\n\n  /**\n   * Sets the state of an operation.\n   *\n   * @param operationId - The operation ID\n   * @param state - The operation state to store\n   */\n  set(operationId: string, state: OperationState): Promise<void>;\n}\n\n/**\n * Represents a stored operation in the queue.\n */\nexport interface StoredOperation {\n  /** Unique identifier for the operation */\n  id: string;\n  /** Current status of the operation */\n  status: \"queued\" | \"processing\" | \"submitted\" | \"completed\" | \"failed\";\n  /** Serialized transaction or operation data */\n  data: string;\n  /** Number of retry attempts */\n  retryCount?: number;\n  /** Timestamp when the operation was created */\n  createdAt?: number;\n  /** Additional metadata */\n  metadata?: any;\n}\n\n/**\n * Interface for operation storage backends.\n *\n * @remarks\n * Implementations of this interface provide persistent storage for queued\n * operations in a distributed relayer system. This allows operations to\n * be processed asynchronously and recovered after failures.\n *\n * Common implementations include:\n * - PostgreSQL for production environments\n * - MongoDB for document-based storage\n * - DynamoDB for serverless deployments\n * - In-memory storage for testing\n *\n * @example\n * ```typescript\n * class PostgresOperationStore implements IOperationStore {\n *   async storeOperation(operation) {\n *     await this.db.query(\n *       'INSERT INTO operations (id, status, data) VALUES ($1, $2, $3)',\n *       [operation.id, 'queued', operation.data]\n *     );\n *   }\n *\n *   async getQueuedOperations(options) {\n *     const result = await this.db.query(\n *       'SELECT * FROM operations WHERE status = $1 LIMIT $2',\n *       ['queued', options.limit || 100]\n *     );\n *     return result.rows;\n *   }\n * }\n * ```\n *\n * @category Storage\n */\nexport interface IOperationStore {\n  /**\n   * Stores a new operation in the queue.\n   *\n   * @param operation - The operation to store\n   * @returns Promise that resolves when the operation is stored\n   */\n  storeOperation(operation: {\n    id: string;\n    data: any;\n    metadata?: any;\n  }): Promise<void>;\n\n  /**\n   * Retrieves queued operations for processing.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of queued operations\n   */\n  getQueuedOperations(options?: { limit?: number }): Promise<StoredOperation[]>;\n\n  /**\n   * Updates the status of an operation.\n   *\n   * @param operationId - The ID of the operation to update\n   * @param status - The new status\n   * @param metadata - Optional metadata to store with the update\n   * @returns Promise that resolves when the status is updated\n   */\n  updateStatus(\n    operationId: string,\n    status: string,\n    metadata?: any,\n  ): Promise<void>;\n\n  /**\n   * Gets operations currently being processed.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of processing operations\n   */\n  getProcessingOperations?(options?: {\n    limit?: number;\n  }): Promise<StoredOperation[]>;\n\n  /**\n   * Gets failed operations.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of failed operations\n   */\n  getFailedOperations?(options?: {\n    limit?: number;\n  }): Promise<StoredOperation[]>;\n\n  /**\n   * Gets the status of a specific operation.\n   *\n   * @param operationId - The ID of the operation to check\n   * @returns Promise resolving to the operation or null if not found\n   */\n  getOperation?(operationId: string): Promise<StoredOperation | null>;\n\n  /**\n   * Deletes an operation from storage.\n   *\n   * @param operationId - The ID of the operation to delete\n   * @returns Promise that resolves when the operation is deleted\n   */\n  deleteOperation?(operationId: string): Promise<void>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/operationStore.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Operation storage interfaces for queuing and managing asynchronous operations.
+ *
+ * @module
+ */
+import type { Hash, TransactionReceipt } from "viem";
+import type { UnifiedRelayerRequest } from "./relayer";
+/**
+ * The state of an asynchronous, relayed operation.
+ *
+ * @remarks
+ * This is the data the application backend is responsible for persisting.
+ * It serves as a complete recovery log for a given operation.
+ *
+ * @category Operations
+ */
+export interface OperationState {
+    status: "pending" | "confirmed" | "failed";
+    transactionHash: Hash;
+    originalRequest: UnifiedRelayerRequest;
+    nonce?: number;
+    retryCount: number;
+    lastAttemptedGas: {
+        maxFeePerGas?: string;
+        maxPriorityFeePerGas?: string;
+    };
+    submittedAt: number;
+    finalReceipt?: TransactionReceipt;
+    error?: string;
+}
+/**
+ * Simple storage interface for operation state tracking.
+ *
+ * @remarks
+ * This interface is used by the relayer handler to track operation state
+ * in a stateful mode. Implementations can use any backend storage system.
+ *
+ * @category Operations
+ */
+export interface IRelayerStateStore {
+    /**
+     * Gets the state of an operation.
+     *
+     * @param operationId - The operation ID
+     * @returns The operation state or null if not found
+     */
+    get(operationId: string): Promise<OperationState | null>;
+    /**
+     * Sets the state of an operation.
+     *
+     * @param operationId - The operation ID
+     * @param state - The operation state to store
+     */
+    set(operationId: string, state: OperationState): Promise<void>;
+}
+/**
+ * Represents a stored operation in the queue.
+ */
+export interface StoredOperation {
+    /** Unique identifier for the operation */
+    id: string;
+    /** Current status of the operation */
+    status: "queued" | "processing" | "submitted" | "completed" | "failed";
+    /** Serialized transaction or operation data */
+    data: string;
+    /** Number of retry attempts */
+    retryCount?: number;
+    /** Timestamp when the operation was created */
+    createdAt?: number;
+    /** Additional metadata */
+    metadata?: any;
+}
+/**
+ * Interface for operation storage backends.
+ *
+ * @remarks
+ * Implementations of this interface provide persistent storage for queued
+ * operations in a distributed relayer system. This allows operations to
+ * be processed asynchronously and recovered after failures.
+ *
+ * Common implementations include:
+ * - PostgreSQL for production environments
+ * - MongoDB for document-based storage
+ * - DynamoDB for serverless deployments
+ * - In-memory storage for testing
+ *
+ * @example
+ * ```typescript
+ * class PostgresOperationStore implements IOperationStore {
+ *   async storeOperation(operation) {
+ *     await this.db.query(
+ *       'INSERT INTO operations (id, status, data) VALUES ($1, $2, $3)',
+ *       [operation.id, 'queued', operation.data]
+ *     );
+ *   }
+ *
+ *   async getQueuedOperations(options) {
+ *     const result = await this.db.query(
+ *       'SELECT * FROM operations WHERE status = $1 LIMIT $2',
+ *       ['queued', options.limit || 100]
+ *     );
+ *     return result.rows;
+ *   }
+ * }
+ * ```
+ *
+ * @category Storage
+ */
+export interface IOperationStore {
+    /**
+     * Stores a new operation in the queue.
+     *
+     * @param operation - The operation to store
+     * @returns Promise that resolves when the operation is stored
+     */
+    storeOperation(operation: {
+        id: string;
+        data: any;
+        metadata?: any;
+    }): Promise<void>;
+    /**
+     * Retrieves queued operations for processing.
+     *
+     * @param options - Query options
+     * @returns Promise resolving to an array of queued operations
+     */
+    getQueuedOperations(options?: {
+        limit?: number;
+    }): Promise<StoredOperation[]>;
+    /**
+     * Updates the status of an operation.
+     *
+     * @param operationId - The ID of the operation to update
+     * @param status - The new status
+     * @param metadata - Optional metadata to store with the update
+     * @returns Promise that resolves when the status is updated
+     */
+    updateStatus(operationId: string, status: string, metadata?: any): Promise<void>;
+    /**
+     * Gets operations currently being processed.
+     *
+     * @param options - Query options
+     * @returns Promise resolving to an array of processing operations
+     */
+    getProcessingOperations?(options?: {
+        limit?: number;
+    }): Promise<StoredOperation[]>;
+    /**
+     * Gets failed operations.
+     *
+     * @param options - Query options
+     * @returns Promise resolving to an array of failed operations
+     */
+    getFailedOperations?(options?: {
+        limit?: number;
+    }): Promise<StoredOperation[]>;
+    /**
+     * Gets the status of a specific operation.
+     *
+     * @param operationId - The ID of the operation to check
+     * @returns Promise resolving to the operation or null if not found
+     */
+    getOperation?(operationId: string): Promise<StoredOperation | null>;
+    /**
+     * Deletes an operation from storage.
+     *
+     * @param operationId - The ID of the operation to delete
+     * @returns Promise that resolves when the operation is deleted
+     */
+    deleteOperation?(operationId: string): Promise<void>;
+}

package/dist/types/operationStore.js

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

package/dist/types/operationStore.js.map

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

package/dist/types/operations.cjs

@@ -32,7 +32,7 @@ function isTransactionResult(obj) {
   if (typeof obj !== "object" || obj === null || !("hash" in obj)) {
     return false;
   }
-  const hash = obj.hash;
+  const { hash } = obj;
   return typeof hash === "string" && hash.startsWith("0x");
 }
 function toOperation(response) {
@@ -42,7 +42,7 @@ function toOperation(response) {
     createdAt: Date.now(),
     // Server doesn't provide this, so we use current time
     result: response.status === "succeeded" ? response.result : void 0,
-    error: response.status === "failed" ? response.result || void 0 : void 0
+    error: response.status === "failed" ? response.result ?? void 0 : void 0
   };
 }
 function getOperationId(opOrId) {

package/dist/types/operations.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\n\n/**\n * Server operation result as a plain object.\n * Fully serializable for API responses and cross-process communication.\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Transaction submission result as a plain object.\n * Contains immediate transaction details without waiting for confirmation.\n */\nexport interface TransactionResult {\n  /** Transaction hash */\n  hash: Hash;\n  /** Sender address */\n  from?: Address;\n  /** Recipient address */\n  to?: Address;\n  /** Transaction nonce */\n  nonce?: number;\n  /** Transaction value in wei */\n  value?: bigint;\n  /** Chain ID where transaction was submitted */\n  chainId?: number;\n}\n\n/**\n * Extended transaction receipt with Vana-specific fields\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Options for polling operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Options for waiting for transaction confirmation\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @param obj - The object to validate as an Operation.\n * @returns `true` if the object has required Operation properties, `false` otherwise.\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @param obj - The object to validate as a TransactionResult.\n * @returns `true` if the object has a valid transaction hash, `false` otherwise.\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const hash = (obj as Record<string, unknown>).hash;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @param response - The raw server response containing operation status data.\n * @returns An Operation object with normalized fields for client consumption.\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? response.result || undefined : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string.\n * @returns The operation ID string for use in API calls.\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string.\n * @returns The transaction hash as a `0x`-prefixed string.\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+EO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAQO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,OAAQ,IAAgC;AAC9C,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAQO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAW,SAAS,UAAU,SAAY;AAAA,EAClE;AACF;AAQO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAQO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}
+{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n// Re-export TransactionOptions from the new options module\nexport type { TransactionOptions } from \"./options\";\n\n/**\n * Represents a server-side operation status and result.\n *\n * @remarks\n * Operations track asynchronous server processes like data refinement or ML inference.\n * Poll operation status using `vana.server.waitForOperation()` until completion.\n * Fully serializable for API responses and cross-process communication.\n *\n * @category Operations\n * @see {@link https://docs.vana.org/docs/operations | Operations Guide}\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Represents a submitted blockchain transaction as a self-describing POJO.\n *\n * @remarks\n * Transaction results MUST include contract and function for proper event parsing.\n * This strongly-typed design enables automatic event extraction without heuristics.\n * Use `vana.waitForTransactionEvents()` to retrieve typed events from the receipt.\n *\n * **Architecture:**\n * POJOs (Plain Old JavaScript Objects) ensure serialization safety and framework\n * independence. Contract and function fields enable deterministic event parsing.\n *\n * @category Operations\n * @example\n * ```typescript\n * const result: TransactionResult = {\n *   hash: '0x123...',\n *   from: '0x456...',\n *   contract: 'DataRegistry',\n *   fn: 'addFile',\n *   chainId: 14800\n * };\n *\n * // Wait for events\n * const events = await vana.waitForTransactionEvents(result);\n * ```\n */\nexport interface TransactionResult<\n  C extends Contract = Contract,\n  F extends Fn<C> = Fn<C>,\n> {\n  /** Transaction hash for tracking and confirmation */\n  hash: Hash;\n  /** Sender's wallet address */\n  from: Address;\n  /** Contract that was called (required for event parsing) */\n  contract: C;\n  /** Function that was called (required for event parsing) */\n  fn: F;\n  /** Network chain ID where transaction was submitted */\n  chainId?: number;\n  /** Transaction value in wei (for payable functions) */\n  value?: bigint;\n  /** Transaction sequence number for the sender */\n  nonce?: number;\n  /** Contract address (if different from standard deployment) */\n  to?: Address;\n}\n\n/**\n * Extends viem's TransactionReceipt with Vana-specific event data.\n *\n * @remarks\n * Includes parsed event data when available after transaction confirmation.\n * Use this for detailed transaction analysis and event processing.\n *\n * @category Operations\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Configures polling behavior for asynchronous operations.\n *\n * @remarks\n * Controls how frequently and how long to poll for operation completion.\n * Lower intervals provide faster updates but increase server load.\n *\n * @category Operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Configures transaction confirmation waiting behavior.\n *\n * @remarks\n * Controls confirmation depth and timeout for transaction finality.\n * Higher confirmations provide more security against chain reorganizations.\n *\n * @category Operations\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @remarks\n * Type guard for runtime validation of operation objects from external sources.\n * Use when deserializing operations from API responses or storage.\n *\n * @param obj - The object to validate as an Operation\n * @returns `true` if the object has required Operation properties, `false` otherwise\n *\n * @example\n * ```typescript\n * const response = await fetch('/api/operation/123');\n * const data = await response.json();\n *\n * if (isOperation(data)) {\n *   console.log(`Operation ${data.id}: ${data.status}`);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @remarks\n * Type guard for runtime validation of transaction results.\n * Checks for required hash field with proper `0x` prefix.\n *\n * @param obj - The object to validate as a TransactionResult\n * @returns `true` if the object has a valid transaction hash, `false` otherwise\n *\n * @example\n * ```typescript\n * if (isTransactionResult(result)) {\n *   await vana.waitForTransactionEvents(result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const { hash } = obj as Record<string, unknown>;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @remarks\n * Normalizes server responses into consistent Operation format.\n * Separates success results from error messages based on status.\n *\n * @param response - The raw server response containing operation status data\n * @returns An Operation object with normalized fields for client consumption\n *\n * @example\n * ```typescript\n * const serverResponse = await api.getOperation('op-123');\n * const operation = toOperation<MLResult>(serverResponse);\n *\n * if (operation.status === 'succeeded') {\n *   console.log('Result:', operation.result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? (response.result ?? undefined) : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @remarks\n * Utility for handling both Operation objects and raw ID strings.\n * Enables flexible API design accepting either format.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string\n * @returns The operation ID string for use in API calls\n *\n * @example\n * ```typescript\n * // Works with both formats\n * await vana.server.getOperation(operation); // Operation object\n * await vana.server.getOperation('op-123');  // ID string\n * ```\n *\n * @category Operations\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @remarks\n * Utility for handling TransactionResult objects, hash objects, or raw hash strings.\n * Enables consistent hash extraction across different transaction representations.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string\n * @returns The transaction hash as a `0x`-prefixed string\n *\n * @example\n * ```typescript\n * // All these work\n * const hash1 = getTransactionHash(transactionResult);\n * const hash2 = getTransactionHash({ hash: '0x123...' });\n * const hash3 = getTransactionHash('0x123...');\n * ```\n *\n * @category Operations\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0JO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAqBO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,EAAE,KAAK,IAAI;AACjB,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAwBO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAY,SAAS,UAAU,SAAa;AAAA,EACpE;AACF;AAqBO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAsBO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}

package/dist/types/operations.d.ts

@@ -1,12 +1,19 @@
-import { Hash, Address, TransactionReceipt as TransactionReceipt$1 } from 'viem';
-import { GetOperationResponse } from '../generated/server/server-exports.js';
-import '../generated/server/server.js';
-
+import type { Hash, TransactionReceipt as ViemReceipt, Address } from "viem";
+import type { GetOperationResponse } from "../generated/server/server-exports";
+import type { Contract, Fn } from "../generated/event-types";
+export type { TransactionOptions } from "./options";
 /**
- * Server operation result as a plain object.
+ * Represents a server-side operation status and result.
+ *
+ * @remarks
+ * Operations track asynchronous server processes like data refinement or ML inference.
+ * Poll operation status using `vana.server.waitForOperation()` until completion.
  * Fully serializable for API responses and cross-process communication.
+ *
+ * @category Operations
+ * @see {@link https://docs.vana.org/docs/operations | Operations Guide}
  */
-interface Operation<T = unknown> {
+export interface Operation<T = unknown> {
     /** Unique operation identifier */
     id: string;
     /** Current operation status */
@@ -23,43 +30,88 @@ interface Operation<T = unknown> {
     metadata?: Record<string, unknown>;
 }
 /**
- * Transaction submission result as a plain object.
- * Contains immediate transaction details without waiting for confirmation.
+ * Represents a submitted blockchain transaction as a self-describing POJO.
+ *
+ * @remarks
+ * Transaction results MUST include contract and function for proper event parsing.
+ * This strongly-typed design enables automatic event extraction without heuristics.
+ * Use `vana.waitForTransactionEvents()` to retrieve typed events from the receipt.
+ *
+ * **Architecture:**
+ * POJOs (Plain Old JavaScript Objects) ensure serialization safety and framework
+ * independence. Contract and function fields enable deterministic event parsing.
+ *
+ * @category Operations
+ * @example
+ * ```typescript
+ * const result: TransactionResult = {
+ *   hash: '0x123...',
+ *   from: '0x456...',
+ *   contract: 'DataRegistry',
+ *   fn: 'addFile',
+ *   chainId: 14800
+ * };
+ *
+ * // Wait for events
+ * const events = await vana.waitForTransactionEvents(result);
+ * ```
  */
-interface TransactionResult {
-    /** Transaction hash */
+export interface TransactionResult<C extends Contract = Contract, F extends Fn<C> = Fn<C>> {
+    /** Transaction hash for tracking and confirmation */
     hash: Hash;
-    /** Sender address */
-    from?: Address;
-    /** Recipient address */
-    to?: Address;
-    /** Transaction nonce */
-    nonce?: number;
-    /** Transaction value in wei */
-    value?: bigint;
-    /** Chain ID where transaction was submitted */
+    /** Sender's wallet address */
+    from: Address;
+    /** Contract that was called (required for event parsing) */
+    contract: C;
+    /** Function that was called (required for event parsing) */
+    fn: F;
+    /** Network chain ID where transaction was submitted */
     chainId?: number;
+    /** Transaction value in wei (for payable functions) */
+    value?: bigint;
+    /** Transaction sequence number for the sender */
+    nonce?: number;
+    /** Contract address (if different from standard deployment) */
+    to?: Address;
 }
 /**
- * Extended transaction receipt with Vana-specific fields
+ * Extends viem's TransactionReceipt with Vana-specific event data.
+ *
+ * @remarks
+ * Includes parsed event data when available after transaction confirmation.
+ * Use this for detailed transaction analysis and event processing.
+ *
+ * @category Operations
  */
-interface TransactionReceipt extends TransactionReceipt$1 {
+export interface TransactionReceipt extends ViemReceipt {
     /** Parsed event data if available */
     events?: unknown;
 }
 /**
- * Options for polling operations
+ * Configures polling behavior for asynchronous operations.
+ *
+ * @remarks
+ * Controls how frequently and how long to poll for operation completion.
+ * Lower intervals provide faster updates but increase server load.
+ *
+ * @category Operations
  */
-interface PollingOptions {
+export interface PollingOptions {
     /** Polling interval in milliseconds (default: 500) */
     pollingInterval?: number;
     /** Maximum time to wait in milliseconds (default: 30000) */
     timeout?: number;
 }
 /**
- * Options for waiting for transaction confirmation
+ * Configures transaction confirmation waiting behavior.
+ *
+ * @remarks
+ * Controls confirmation depth and timeout for transaction finality.
+ * Higher confirmations provide more security against chain reorganizations.
+ *
+ * @category Operations
  */
-interface TransactionWaitOptions {
+export interface TransactionWaitOptions {
     /** Number of confirmations to wait for (default: 1) */
     confirmations?: number;
     /** Polling interval in milliseconds (default: 1000) */
@@ -70,39 +122,109 @@ interface TransactionWaitOptions {
 /**
  * Validates whether an object conforms to the Operation interface.
  *
- * @param obj - The object to validate as an Operation.
- * @returns `true` if the object has required Operation properties, `false` otherwise.
+ * @remarks
+ * Type guard for runtime validation of operation objects from external sources.
+ * Use when deserializing operations from API responses or storage.
+ *
+ * @param obj - The object to validate as an Operation
+ * @returns `true` if the object has required Operation properties, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/operation/123');
+ * const data = await response.json();
+ *
+ * if (isOperation(data)) {
+ *   console.log(`Operation ${data.id}: ${data.status}`);
+ * }
+ * ```
+ *
+ * @category Operations
  */
-declare function isOperation(obj: unknown): obj is Operation;
+export declare function isOperation(obj: unknown): obj is Operation;
 /**
  * Validates whether an object conforms to the TransactionResult interface.
  *
- * @param obj - The object to validate as a TransactionResult.
- * @returns `true` if the object has a valid transaction hash, `false` otherwise.
+ * @remarks
+ * Type guard for runtime validation of transaction results.
+ * Checks for required hash field with proper `0x` prefix.
+ *
+ * @param obj - The object to validate as a TransactionResult
+ * @returns `true` if the object has a valid transaction hash, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isTransactionResult(result)) {
+ *   await vana.waitForTransactionEvents(result);
+ * }
+ * ```
+ *
+ * @category Operations
  */
-declare function isTransactionResult(obj: unknown): obj is TransactionResult;
+export declare function isTransactionResult(obj: unknown): obj is TransactionResult;
 /**
  * Converts a server response to an Operation POJO.
  *
- * @param response - The raw server response containing operation status data.
- * @returns An Operation object with normalized fields for client consumption.
+ * @remarks
+ * Normalizes server responses into consistent Operation format.
+ * Separates success results from error messages based on status.
+ *
+ * @param response - The raw server response containing operation status data
+ * @returns An Operation object with normalized fields for client consumption
+ *
+ * @example
+ * ```typescript
+ * const serverResponse = await api.getOperation('op-123');
+ * const operation = toOperation<MLResult>(serverResponse);
+ *
+ * if (operation.status === 'succeeded') {
+ *   console.log('Result:', operation.result);
+ * }
+ * ```
+ *
+ * @category Operations
  */
-declare function toOperation<T>(response: GetOperationResponse): Operation<T>;
+export declare function toOperation<T>(response: GetOperationResponse): Operation<T>;
 /**
  * Extracts the operation ID from flexible input types.
  *
- * @param opOrId - An Operation object containing an `id` field or a raw operation ID string.
- * @returns The operation ID string for use in API calls.
+ * @remarks
+ * Utility for handling both Operation objects and raw ID strings.
+ * Enables flexible API design accepting either format.
+ *
+ * @param opOrId - An Operation object containing an `id` field or a raw operation ID string
+ * @returns The operation ID string for use in API calls
+ *
+ * @example
+ * ```typescript
+ * // Works with both formats
+ * await vana.server.getOperation(operation); // Operation object
+ * await vana.server.getOperation('op-123');  // ID string
+ * ```
+ *
+ * @category Operations
  */
-declare function getOperationId(opOrId: Operation | string): string;
+export declare function getOperationId(opOrId: Operation | string): string;
 /**
  * Extracts the transaction hash from flexible input types.
  *
- * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string.
- * @returns The transaction hash as a `0x`-prefixed string.
+ * @remarks
+ * Utility for handling TransactionResult objects, hash objects, or raw hash strings.
+ * Enables consistent hash extraction across different transaction representations.
+ *
+ * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string
+ * @returns The transaction hash as a `0x`-prefixed string
+ *
+ * @example
+ * ```typescript
+ * // All these work
+ * const hash1 = getTransactionHash(transactionResult);
+ * const hash2 = getTransactionHash({ hash: '0x123...' });
+ * const hash3 = getTransactionHash('0x123...');
+ * ```
+ *
+ * @category Operations
  */
-declare function getTransactionHash(txOrHash: TransactionResult | {
+export declare function getTransactionHash(txOrHash: TransactionResult | {
     hash: Hash;
 } | Hash): Hash;
-
-export { type Operation, type PollingOptions, type TransactionReceipt, type TransactionResult, type TransactionWaitOptions, getOperationId, getTransactionHash, isOperation, isTransactionResult, toOperation };

package/dist/types/operations.js

@@ -5,7 +5,7 @@ function isTransactionResult(obj) {
   if (typeof obj !== "object" || obj === null || !("hash" in obj)) {
     return false;
   }
-  const hash = obj.hash;
+  const { hash } = obj;
   return typeof hash === "string" && hash.startsWith("0x");
 }
 function toOperation(response) {
@@ -15,7 +15,7 @@ function toOperation(response) {
     createdAt: Date.now(),
     // Server doesn't provide this, so we use current time
     result: response.status === "succeeded" ? response.result : void 0,
-    error: response.status === "failed" ? response.result || void 0 : void 0
+    error: response.status === "failed" ? response.result ?? void 0 : void 0
   };
 }
 function getOperationId(opOrId) {

package/dist/types/operations.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\n\n/**\n * Server operation result as a plain object.\n * Fully serializable for API responses and cross-process communication.\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Transaction submission result as a plain object.\n * Contains immediate transaction details without waiting for confirmation.\n */\nexport interface TransactionResult {\n  /** Transaction hash */\n  hash: Hash;\n  /** Sender address */\n  from?: Address;\n  /** Recipient address */\n  to?: Address;\n  /** Transaction nonce */\n  nonce?: number;\n  /** Transaction value in wei */\n  value?: bigint;\n  /** Chain ID where transaction was submitted */\n  chainId?: number;\n}\n\n/**\n * Extended transaction receipt with Vana-specific fields\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Options for polling operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Options for waiting for transaction confirmation\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @param obj - The object to validate as an Operation.\n * @returns `true` if the object has required Operation properties, `false` otherwise.\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @param obj - The object to validate as a TransactionResult.\n * @returns `true` if the object has a valid transaction hash, `false` otherwise.\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const hash = (obj as Record<string, unknown>).hash;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @param response - The raw server response containing operation status data.\n * @returns An Operation object with normalized fields for client consumption.\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? response.result || undefined : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string.\n * @returns The operation ID string for use in API calls.\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string.\n * @returns The transaction hash as a `0x`-prefixed string.\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":"AA+EO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAQO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,OAAQ,IAAgC;AAC9C,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAQO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAW,SAAS,UAAU,SAAY;AAAA,EAClE;AACF;AAQO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAQO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}
+{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n// Re-export TransactionOptions from the new options module\nexport type { TransactionOptions } from \"./options\";\n\n/**\n * Represents a server-side operation status and result.\n *\n * @remarks\n * Operations track asynchronous server processes like data refinement or ML inference.\n * Poll operation status using `vana.server.waitForOperation()` until completion.\n * Fully serializable for API responses and cross-process communication.\n *\n * @category Operations\n * @see {@link https://docs.vana.org/docs/operations | Operations Guide}\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Represents a submitted blockchain transaction as a self-describing POJO.\n *\n * @remarks\n * Transaction results MUST include contract and function for proper event parsing.\n * This strongly-typed design enables automatic event extraction without heuristics.\n * Use `vana.waitForTransactionEvents()` to retrieve typed events from the receipt.\n *\n * **Architecture:**\n * POJOs (Plain Old JavaScript Objects) ensure serialization safety and framework\n * independence. Contract and function fields enable deterministic event parsing.\n *\n * @category Operations\n * @example\n * ```typescript\n * const result: TransactionResult = {\n *   hash: '0x123...',\n *   from: '0x456...',\n *   contract: 'DataRegistry',\n *   fn: 'addFile',\n *   chainId: 14800\n * };\n *\n * // Wait for events\n * const events = await vana.waitForTransactionEvents(result);\n * ```\n */\nexport interface TransactionResult<\n  C extends Contract = Contract,\n  F extends Fn<C> = Fn<C>,\n> {\n  /** Transaction hash for tracking and confirmation */\n  hash: Hash;\n  /** Sender's wallet address */\n  from: Address;\n  /** Contract that was called (required for event parsing) */\n  contract: C;\n  /** Function that was called (required for event parsing) */\n  fn: F;\n  /** Network chain ID where transaction was submitted */\n  chainId?: number;\n  /** Transaction value in wei (for payable functions) */\n  value?: bigint;\n  /** Transaction sequence number for the sender */\n  nonce?: number;\n  /** Contract address (if different from standard deployment) */\n  to?: Address;\n}\n\n/**\n * Extends viem's TransactionReceipt with Vana-specific event data.\n *\n * @remarks\n * Includes parsed event data when available after transaction confirmation.\n * Use this for detailed transaction analysis and event processing.\n *\n * @category Operations\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Configures polling behavior for asynchronous operations.\n *\n * @remarks\n * Controls how frequently and how long to poll for operation completion.\n * Lower intervals provide faster updates but increase server load.\n *\n * @category Operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Configures transaction confirmation waiting behavior.\n *\n * @remarks\n * Controls confirmation depth and timeout for transaction finality.\n * Higher confirmations provide more security against chain reorganizations.\n *\n * @category Operations\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @remarks\n * Type guard for runtime validation of operation objects from external sources.\n * Use when deserializing operations from API responses or storage.\n *\n * @param obj - The object to validate as an Operation\n * @returns `true` if the object has required Operation properties, `false` otherwise\n *\n * @example\n * ```typescript\n * const response = await fetch('/api/operation/123');\n * const data = await response.json();\n *\n * if (isOperation(data)) {\n *   console.log(`Operation ${data.id}: ${data.status}`);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @remarks\n * Type guard for runtime validation of transaction results.\n * Checks for required hash field with proper `0x` prefix.\n *\n * @param obj - The object to validate as a TransactionResult\n * @returns `true` if the object has a valid transaction hash, `false` otherwise\n *\n * @example\n * ```typescript\n * if (isTransactionResult(result)) {\n *   await vana.waitForTransactionEvents(result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const { hash } = obj as Record<string, unknown>;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @remarks\n * Normalizes server responses into consistent Operation format.\n * Separates success results from error messages based on status.\n *\n * @param response - The raw server response containing operation status data\n * @returns An Operation object with normalized fields for client consumption\n *\n * @example\n * ```typescript\n * const serverResponse = await api.getOperation('op-123');\n * const operation = toOperation<MLResult>(serverResponse);\n *\n * if (operation.status === 'succeeded') {\n *   console.log('Result:', operation.result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? (response.result ?? undefined) : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @remarks\n * Utility for handling both Operation objects and raw ID strings.\n * Enables flexible API design accepting either format.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string\n * @returns The operation ID string for use in API calls\n *\n * @example\n * ```typescript\n * // Works with both formats\n * await vana.server.getOperation(operation); // Operation object\n * await vana.server.getOperation('op-123');  // ID string\n * ```\n *\n * @category Operations\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @remarks\n * Utility for handling TransactionResult objects, hash objects, or raw hash strings.\n * Enables consistent hash extraction across different transaction representations.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string\n * @returns The transaction hash as a `0x`-prefixed string\n *\n * @example\n * ```typescript\n * // All these work\n * const hash1 = getTransactionHash(transactionResult);\n * const hash2 = getTransactionHash({ hash: '0x123...' });\n * const hash3 = getTransactionHash('0x123...');\n * ```\n *\n * @category Operations\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":"AA0JO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAqBO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,EAAE,KAAK,IAAI;AACjB,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAwBO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAY,SAAS,UAAU,SAAa;AAAA,EACpE;AACF;AAqBO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAsBO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}

package/dist/types/options.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 options_exports = {};
+module.exports = __toCommonJS(options_exports);
+//# sourceMappingURL=options.cjs.map

package/dist/types/options.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/options.ts"],"sourcesContent":["/**\n * @file Standard option types for Vana SDK methods\n * @module vana-sdk/types/options\n */\n\n/**\n * Transaction options for blockchain write operations.\n *\n * @remarks\n * Aligned with viem's transaction parameters for consistency.\n * These options control gas pricing, limits, polling behavior, and other transaction-specific settings.\n *\n * @example\n * ```typescript\n * // Basic usage with gas options\n * await vana.data.upload(params, {\n *   gas: 1000000n,\n *   maxFeePerGas: 20000000000n\n * });\n *\n * // With status updates for long-running operations\n * await vana.permissions.grant({ grantee: '0x...' }, {\n *   onStatusUpdate: (status) => {\n *     if (status.type === 'queued') {\n *       console.log(`Position in queue: ${status.position}`);\n *     }\n *   }\n * });\n *\n * // With cancellation support\n * const controller = new AbortController();\n * const promise = vana.permissions.grant({ grantee: '0x...' }, {\n *   signal: controller.signal\n * });\n * // Cancel after 30 seconds\n * setTimeout(() => controller.abort(), 30000);\n * ```\n *\n * @category Options\n */\nexport interface TransactionOptions {\n  /** Gas limit for the transaction */\n  gas?: bigint;\n\n  /** Gas price in wei (for legacy transactions) */\n  gasPrice?: bigint;\n\n  /** Maximum fee per gas in wei (EIP-1559) */\n  maxFeePerGas?: bigint;\n\n  /** Maximum priority fee per gas in wei (EIP-1559) */\n  maxPriorityFeePerGas?: bigint;\n\n  /** Transaction nonce override */\n  nonce?: number;\n\n  /** ETH value to send with transaction */\n  value?: bigint;\n\n  /**\n   * AbortSignal for cancelling long-running operations.\n   *\n   * @remarks\n   * Useful for cancelling pending transactions or polling operations.\n   * When aborted, the operation will throw an error immediately.\n   */\n  signal?: AbortSignal;\n\n  /**\n   * Callback for receiving status updates during long-running operations.\n   *\n   * @remarks\n   * Called whenever the operation status changes (e.g., from pending to queued).\n   * Useful for showing progress in UI during multi-minute operations.\n   *\n   * @param status - The current operation status\n   */\n  onStatusUpdate?: (status: OperationStatus) => void;\n\n  /**\n   * Custom polling options for long-running operations.\n   *\n   * @remarks\n   * Overrides default polling behavior for operations that use the relayer.\n   * Generally not needed unless you have specific timing requirements.\n   */\n  pollingOptions?: {\n    /** Total timeout in milliseconds (default: 300000 = 5 min) */\n    timeout?: number;\n    /** Initial polling interval in milliseconds (default: 1000) */\n    initialInterval?: number;\n    /** Maximum polling interval in milliseconds (default: 10000) */\n    maxInterval?: number;\n  };\n}\n\n/**\n * Represents the current status of a blockchain operation.\n *\n * @remarks\n * Used for status updates during long-running operations via the onStatusUpdate callback.\n * Provides detailed information about the operation's progress through its lifecycle.\n *\n * @category Options\n */\nexport type OperationStatus =\n  | {\n      /** Operation is pending, not yet processed */\n      type: \"pending\";\n      /** The operation ID for tracking */\n      operationId: string;\n    }\n  | {\n      /** Operation is queued for processing */\n      type: \"queued\";\n      /** Position in the processing queue */\n      position?: number;\n      /** Estimated wait time in seconds */\n      estimatedWait?: number;\n    }\n  | {\n      /** Operation is actively being processed */\n      type: \"processing\";\n    }\n  | {\n      /** Transaction has been submitted to blockchain */\n      type: \"submitted\";\n      /** The transaction hash */\n      hash: `0x${string}`;\n    }\n  | {\n      /** Transaction has been confirmed on-chain */\n      type: \"confirmed\";\n      /** The transaction hash */\n      hash: `0x${string}`;\n      /** The transaction receipt if available */\n      receipt?: unknown;\n    }\n  | {\n      /** Operation failed with an error */\n      type: \"failed\";\n      /** Error message describing the failure */\n      error: string;\n      /** Operation ID if available for recovery */\n      operationId?: string;\n    };\n\n/**\n * Source selection for data queries.\n *\n * @remarks\n * - `chain`: Query directly from blockchain (immediate consistency)\n * - `subgraph`: Query from indexed subgraph (may lag 15-60s)\n * - `auto`: SDK chooses optimal source (default)\n *\n * @category Options\n */\nexport type DataSource = \"chain\" | \"subgraph\" | \"auto\";\n\n/**\n * Consistency options for read operations.\n *\n * @remarks\n * Controls data freshness requirements and source selection.\n * Essential for read-after-write consistency when data must reflect recent transactions.\n *\n * @example\n * ```typescript\n * // Ensure data includes a recent transaction\n * const files = await vana.data.getUserFiles({ owner }, {\n *   minBlock: receipt.blockNumber,\n *   waitForSync: 30000  // Wait up to 30s\n * });\n * ```\n *\n * @category Options\n */\nexport interface ConsistencyOptions {\n  /**\n   * Minimum block number the data source must have indexed.\n   *\n   * @remarks\n   * Operation will fail or wait (if waitForSync set) until source reaches this block.\n   * Critical for ensuring recently created data is visible.\n   */\n  minBlock?: number;\n\n  /**\n   * Maximum milliseconds to wait for data source to sync to minBlock.\n   *\n   * @remarks\n   * If not set, operation fails immediately when source is behind.\n   * Useful for critical operations where waiting is preferable to failure.\n   *\n   * @default undefined (no waiting)\n   */\n  waitForSync?: number;\n\n  /**\n   * Explicitly select data source.\n   *\n   * @remarks\n   * Useful for debugging or when specific consistency guarantees are needed.\n   * Not all methods support all sources - unsupported selections will error.\n   *\n   * @default 'auto'\n   */\n  source?: DataSource;\n\n  /**\n   * AbortSignal for cancelling long-running operations.\n   *\n   * @remarks\n   * Particularly useful with waitForSync to cancel polling operations.\n   * Properly cleans up timers and pending requests when aborted.\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * const promise = vana.data.getUserFiles(\n   *   { owner },\n   *   { waitForSync: 30000, signal: controller.signal }\n   * );\n   *\n   * // Cancel after 5 seconds\n   * setTimeout(() => controller.abort(), 5000);\n   * ```\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Pagination options for list operations.\n *\n * @remarks\n * Controls result set size, ordering, and pagination.\n * By default returns first 100 items to prevent accidental large fetches.\n *\n * @example\n * ```typescript\n * // Get all files (explicit opt-in)\n * const allFiles = await vana.data.getUserFiles({ owner }, {\n *   fetchAll: true\n * });\n *\n * // Get 10 most recent files\n * const recentFiles = await vana.data.getUserFiles({ owner }, {\n *   limit: 10,\n *   orderBy: 'addedAtBlock',\n *   orderDirection: 'desc'\n * });\n * ```\n *\n * @category Options\n */\nexport interface PaginationOptions {\n  /**\n   * Maximum number of items to return.\n   *\n   * @remarks\n   * Prevents accidental large fetches. Use fetchAll: true for unlimited.\n   *\n   * @default 100\n   */\n  limit?: number;\n\n  /**\n   * Number of items to skip (for manual pagination).\n   *\n   * @default 0\n   */\n  offset?: number;\n\n  /**\n   * Field to order results by.\n   *\n   * @remarks\n   * Field names depend on the entity type.\n   * Common: 'id', 'addedAtBlock', 'addedAtTimestamp'\n   */\n  orderBy?: string;\n\n  /**\n   * Sort direction for orderBy field.\n   *\n   * @default 'desc' for timestamp/block fields, 'asc' for others\n   */\n  orderDirection?: \"asc\" | \"desc\";\n\n  /**\n   * Explicitly fetch all available items.\n   *\n   * @remarks\n   * Override safety limit. SDK will paginate internally to fetch all results.\n   * Use with caution - can result in many API calls and large memory usage.\n   *\n   * @default false\n   */\n  fetchAll?: boolean;\n}\n\n/**\n * Combined options for read operations that return lists.\n *\n * @remarks\n * Convenience type combining consistency and pagination controls.\n *\n * @category Options\n */\nexport type ListOptions = ConsistencyOptions & PaginationOptions;\n\n/**\n * Combined options for write operations that may read data.\n *\n * @remarks\n * Some write operations need to read data (e.g., schema validation).\n * This type combines transaction and consistency options.\n *\n * @category Options\n */\nexport type WriteOptions = TransactionOptions & ConsistencyOptions;\n\n/**\n * Legacy transaction options type for backwards compatibility.\n *\n * @deprecated Use TransactionOptions instead. Will be removed in next major version.\n * @category Options\n */\nexport interface LegacyTransactionOptions {\n  /** @deprecated Use `gas` instead */\n  gasLimit?: bigint;\n  gasPrice?: bigint;\n  maxFeePerGas?: bigint;\n  maxPriorityFeePerGas?: bigint;\n  nonce?: number;\n  value?: bigint;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}