@opendatalabs/vana-sdk 2.3.0 → 3.0.1

package/dist/types/operationStore.d.ts

@@ -1,171 +0,0 @@
-/**
- * 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

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

package/dist/types/operationStore.js.map

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

package/dist/types/operations.cjs

@@ -1,53 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var operations_exports = {};
-__export(operations_exports, {
-  getOperationId: () => getOperationId,
-  getTransactionHash: () => getTransactionHash,
-  isOperation: () => isOperation,
-  isTransactionResult: () => isTransactionResult
-});
-module.exports = __toCommonJS(operations_exports);
-function isOperation(obj) {
-  return typeof obj === "object" && obj !== null && "kind" in obj && "id" in obj && "status" in obj && obj.kind === "OperationStatus" && typeof obj.id === "string" && typeof obj.status === "string";
-}
-function isTransactionResult(obj) {
-  if (typeof obj !== "object" || obj === null || !("hash" in obj)) {
-    return false;
-  }
-  const { hash } = obj;
-  return typeof hash === "string" && hash.startsWith("0x");
-}
-function getOperationId(opOrId) {
-  return typeof opOrId === "string" ? opOrId : opOrId.id;
-}
-function getTransactionHash(txOrHash) {
-  if (typeof txOrHash === "string") {
-    return txOrHash;
-  }
-  return txOrHash.hash;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getOperationId,
-  getTransactionHash,
-  isOperation,
-  isTransactionResult
-});
-//# sourceMappingURL=operations.cjs.map

package/dist/types/operations.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type {\n  GetOperationResponse,\n  ArtifactInfo,\n} 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 an artifact generated by a server operation.\n *\n * @remarks\n * Artifacts are files generated during operations like Gemini agent analysis.\n * These can be downloaded separately using the artifact download API.\n * This type is imported directly from the server's OpenAPI schema.\n *\n * @category Operations\n */\nexport type Artifact = ArtifactInfo;\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 * This type is now directly imported from the server's OpenAPI schema for type safety.\n *\n * @category Operations\n * @see {@link https://docs.vana.org/docs/operations | Operations Guide}\n */\nexport type Operation = GetOperationResponse;\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 (GetOperationResponse) type.\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 * Validates against the server's OpenAPI schema structure.\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    \"kind\" in obj &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    (obj as Record<string, unknown>).kind === \"OperationStatus\" &&\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 * 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;AA2JO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,UAAU,OACV,QAAQ,OACR,YAAY,OACX,IAAgC,SAAS,qBAC1C,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;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,204 +0,0 @@
-import type { Hash, TransactionReceipt as ViemReceipt, Address } from "viem";
-import type { GetOperationResponse, ArtifactInfo } from "../generated/server/server-exports";
-import type { Contract, Fn } from "../generated/event-types";
-export type { TransactionOptions } from "./options";
-/**
- * Represents an artifact generated by a server operation.
- *
- * @remarks
- * Artifacts are files generated during operations like Gemini agent analysis.
- * These can be downloaded separately using the artifact download API.
- * This type is imported directly from the server's OpenAPI schema.
- *
- * @category Operations
- */
-export type Artifact = ArtifactInfo;
-/**
- * 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.
- * This type is now directly imported from the server's OpenAPI schema for type safety.
- *
- * @category Operations
- * @see {@link https://docs.vana.org/docs/operations | Operations Guide}
- */
-export type Operation = GetOperationResponse;
-/**
- * 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);
- * ```
- */
-export interface TransactionResult<C extends Contract = Contract, F extends Fn<C> = Fn<C>> {
-    /** Transaction hash for tracking and confirmation */
-    hash: Hash;
-    /** 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;
-}
-/**
- * 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
- */
-export interface TransactionReceipt extends ViemReceipt {
-    /** Parsed event data if available */
-    events?: unknown;
-}
-/**
- * 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
- */
-export interface PollingOptions {
-    /** Polling interval in milliseconds (default: 500) */
-    pollingInterval?: number;
-    /** Maximum time to wait in milliseconds (default: 30000) */
-    timeout?: number;
-}
-/**
- * Configures transaction confirmation waiting behavior.
- *
- * @remarks
- * Controls confirmation depth and timeout for transaction finality.
- * Higher confirmations provide more security against chain reorganizations.
- *
- * @category Operations
- */
-export interface TransactionWaitOptions {
-    /** Number of confirmations to wait for (default: 1) */
-    confirmations?: number;
-    /** Polling interval in milliseconds (default: 1000) */
-    pollingInterval?: number;
-    /** Maximum time to wait in milliseconds (default: 30000) */
-    timeout?: number;
-}
-/**
- * Validates whether an object conforms to the Operation (GetOperationResponse) type.
- *
- * @remarks
- * Type guard for runtime validation of operation objects from external sources.
- * Use when deserializing operations from API responses or storage.
- * Validates against the server's OpenAPI schema structure.
- *
- * @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
- */
-export declare function isOperation(obj: unknown): obj is Operation;
-/**
- * Validates whether an object conforms to the TransactionResult interface.
- *
- * @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
- */
-export declare function isTransactionResult(obj: unknown): obj is TransactionResult;
-/**
- * Extracts the operation ID from flexible input types.
- *
- * @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
- */
-export declare function getOperationId(opOrId: Operation | string): string;
-/**
- * Extracts the transaction hash from flexible input types.
- *
- * @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
- */
-export declare function getTransactionHash(txOrHash: TransactionResult | {
-    hash: Hash;
-} | Hash): Hash;

package/dist/types/operations.js

@@ -1,26 +0,0 @@
-function isOperation(obj) {
-  return typeof obj === "object" && obj !== null && "kind" in obj && "id" in obj && "status" in obj && obj.kind === "OperationStatus" && typeof obj.id === "string" && typeof obj.status === "string";
-}
-function isTransactionResult(obj) {
-  if (typeof obj !== "object" || obj === null || !("hash" in obj)) {
-    return false;
-  }
-  const { hash } = obj;
-  return typeof hash === "string" && hash.startsWith("0x");
-}
-function getOperationId(opOrId) {
-  return typeof opOrId === "string" ? opOrId : opOrId.id;
-}
-function getTransactionHash(txOrHash) {
-  if (typeof txOrHash === "string") {
-    return txOrHash;
-  }
-  return txOrHash.hash;
-}
-export {
-  getOperationId,
-  getTransactionHash,
-  isOperation,
-  isTransactionResult
-};
-//# sourceMappingURL=operations.js.map

package/dist/types/operations.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type {\n  GetOperationResponse,\n  ArtifactInfo,\n} 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 an artifact generated by a server operation.\n *\n * @remarks\n * Artifacts are files generated during operations like Gemini agent analysis.\n * These can be downloaded separately using the artifact download API.\n * This type is imported directly from the server's OpenAPI schema.\n *\n * @category Operations\n */\nexport type Artifact = ArtifactInfo;\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 * This type is now directly imported from the server's OpenAPI schema for type safety.\n *\n * @category Operations\n * @see {@link https://docs.vana.org/docs/operations | Operations Guide}\n */\nexport type Operation = GetOperationResponse;\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 (GetOperationResponse) type.\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 * Validates against the server's OpenAPI schema structure.\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    \"kind\" in obj &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    (obj as Record<string, unknown>).kind === \"OperationStatus\" &&\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 * 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":"AA2JO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,UAAU,OACV,QAAQ,OACR,YAAY,OACX,IAAgC,SAAS,qBAC1C,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;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

@@ -1,17 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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":[]}