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

package/dist/client/enhancedResponse.cjs

@@ -0,0 +1,164 @@
+"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 enhancedResponse_exports = {};
+__export(enhancedResponse_exports, {
+  EnhancedTransactionResponse: () => EnhancedTransactionResponse,
+  canEnhanceResponse: () => canEnhanceResponse,
+  enhanceResponse: () => enhanceResponse
+});
+module.exports = __toCommonJS(enhancedResponse_exports);
+var import_pollingManager = require("../core/pollingManager");
+class EnhancedTransactionResponse {
+  /** The underlying relayer response */
+  response;
+  /** The hash if this is a submitted transaction */
+  hash;
+  /** The operation ID if this is a pending operation */
+  operationId;
+  /** Transaction context for event parsing */
+  context;
+  sdk;
+  // Using any to avoid circular dependency
+  constructor(response, sdk) {
+    this.response = response;
+    this.sdk = sdk;
+    if (response.type === "submitted" || response.type === "signed") {
+      this.hash = response.hash;
+      this.context = response.context;
+    } else if (response.type === "pending") {
+      this.operationId = response.operationId;
+    }
+  }
+  /**
+   * Waits for the transaction or operation to complete.
+   *
+   * @remarks
+   * This method provides intelligent handling based on the response type:
+   * - For 'submitted' responses with context: Uses waitForTransactionEvents for full event parsing
+   * - For 'submitted' responses without context: Waits for receipt only
+   * - For 'pending' responses: Uses PollingManager to track async operations
+   * - For 'confirmed' responses: Returns immediately with the receipt
+   *
+   * @param options - Optional configuration for polling behavior
+   * @returns Promise resolving to event results or transaction receipt
+   * @throws Error if the response type cannot be waited on
+   *
+   * @example
+   * ```typescript
+   * // With context for event parsing
+   * const enhanced = new EnhancedTransactionResponse(response, vana);
+   * const result = await enhanced.wait();
+   * if (result.expectedEvents?.FileAdded) {
+   *   console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+   * }
+   *
+   * // For pending operations
+   * const result = await enhanced.wait({
+   *   onStatusUpdate: (status) => console.log('Status:', status)
+   * });
+   * ```
+   */
+  async wait(options) {
+    if (this.response.type === "confirmed") {
+      return {
+        hash: this.response.hash,
+        receipt: this.response.receipt
+      };
+    }
+    if ((this.response.type === "submitted" || this.response.type === "signed") && this.context) {
+      return await this.sdk.waitForTransactionEvents({
+        hash: this.response.hash,
+        from: this.context.from,
+        contract: this.context.contract,
+        fn: this.context.fn
+      });
+    }
+    if (this.response.type === "submitted" || this.response.type === "signed") {
+      const receipt = await this.sdk.publicClient.waitForTransactionReceipt({
+        hash: this.response.hash
+      });
+      return {
+        hash: this.response.hash,
+        receipt
+      };
+    }
+    if (this.response.type === "pending") {
+      const sdkInternal = this.sdk;
+      const relayerCallback = sdkInternal.relayerCallback;
+      if (typeof relayerCallback !== "function") {
+        throw new Error("Relayer callback not configured for polling");
+      }
+      const pollingManager = new import_pollingManager.PollingManager(relayerCallback);
+      return await pollingManager.startPolling(this.response.operationId, {
+        signal: options?.signal,
+        onStatusUpdate: options?.onStatusUpdate,
+        timeout: options?.timeout
+      });
+    }
+    throw new Error(
+      `Cannot wait on response type: ${this.response.type}. Only 'submitted', 'signed', 'pending', and 'confirmed' responses can be waited on.`
+    );
+  }
+  /**
+   * Checks if this response can be waited on.
+   *
+   * @returns true if the response supports the wait() method
+   */
+  canWait() {
+    return this.response.type === "submitted" || this.response.type === "signed" || this.response.type === "pending" || this.response.type === "confirmed";
+  }
+  /**
+   * Gets a human-readable status description.
+   *
+   * @returns Status string describing the current state
+   */
+  getStatus() {
+    switch (this.response.type) {
+      case "pending":
+        return `Operation pending (ID: ${this.operationId})`;
+      case "submitted":
+      case "signed":
+        return `Transaction submitted (Hash: ${this.hash})`;
+      case "confirmed":
+        return `Transaction confirmed (Hash: ${this.response.hash})`;
+      case "direct":
+        return "Operation completed";
+      case "error":
+        return `Error: ${this.response.error}`;
+      default:
+        return "Unknown status";
+    }
+  }
+}
+function canEnhanceResponse(response) {
+  return response.type === "submitted" || response.type === "signed" || response.type === "pending" || response.type === "confirmed";
+}
+function enhanceResponse(response, sdk) {
+  if (canEnhanceResponse(response)) {
+    return new EnhancedTransactionResponse(response, sdk);
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EnhancedTransactionResponse,
+  canEnhanceResponse,
+  enhanceResponse
+});
+//# sourceMappingURL=enhancedResponse.cjs.map

package/dist/client/enhancedResponse.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/enhancedResponse.ts"],"sourcesContent":["/**\n * Enhanced client-side response wrapper for relayer operations.\n *\n * @remarks\n * This module provides a fluent API for handling asynchronous relayer responses\n * by adding stateful behavior to the stateless response data. It enables the\n * `.wait()` pattern similar to ethers.js while maintaining clean separation\n * between server-side data transfer and client-side behavior.\n *\n * @module client/enhancedResponse\n */\n\nimport type { Hash, TransactionReceipt } from \"viem\";\nimport type {\n  UnifiedRelayerResponse,\n  TransactionContext,\n} from \"../types/relayer\";\nimport { PollingManager } from \"../core/pollingManager\";\nimport type { OperationStatus } from \"../types/options\";\n\n/**\n * Enhanced transaction response that provides a fluent API for waiting.\n *\n * @remarks\n * This class wraps a UnifiedRelayerResponse and provides a `.wait()` method\n * that intelligently handles both submitted transactions (via hash) and\n * pending operations (via operationId). It encapsulates the complexity of\n * polling and event parsing, providing a clean developer experience.\n *\n * @example\n * ```typescript\n * const response = await relayerClient.handleOperation(...);\n * const enhanced = vana.enhanceRelayerResponse(response);\n * if (enhanced) {\n *   const result = await enhanced.wait();\n *   console.log('Transaction confirmed:', result.hash);\n * }\n * ```\n *\n * @category Client\n */\nexport class EnhancedTransactionResponse {\n  /** The underlying relayer response */\n  public readonly response: UnifiedRelayerResponse;\n\n  /** The hash if this is a submitted transaction */\n  public readonly hash?: Hash;\n\n  /** The operation ID if this is a pending operation */\n  public readonly operationId?: string;\n\n  /** Transaction context for event parsing */\n  public readonly context?: TransactionContext;\n\n  private readonly sdk: any; // Using any to avoid circular dependency\n\n  constructor(response: UnifiedRelayerResponse, sdk: any) {\n    this.response = response;\n    this.sdk = sdk;\n\n    // Extract key properties based on response type\n    if (response.type === \"submitted\" || response.type === \"signed\") {\n      this.hash = response.hash;\n      this.context = response.context;\n    } else if (response.type === \"pending\") {\n      this.operationId = response.operationId;\n    }\n  }\n\n  /**\n   * Waits for the transaction or operation to complete.\n   *\n   * @remarks\n   * This method provides intelligent handling based on the response type:\n   * - For 'submitted' responses with context: Uses waitForTransactionEvents for full event parsing\n   * - For 'submitted' responses without context: Waits for receipt only\n   * - For 'pending' responses: Uses PollingManager to track async operations\n   * - For 'confirmed' responses: Returns immediately with the receipt\n   *\n   * @param options - Optional configuration for polling behavior\n   * @returns Promise resolving to event results or transaction receipt\n   * @throws Error if the response type cannot be waited on\n   *\n   * @example\n   * ```typescript\n   * // With context for event parsing\n   * const enhanced = new EnhancedTransactionResponse(response, vana);\n   * const result = await enhanced.wait();\n   * if (result.expectedEvents?.FileAdded) {\n   *   console.log('File ID:', result.expectedEvents.FileAdded.fileId);\n   * }\n   *\n   * // For pending operations\n   * const result = await enhanced.wait({\n   *   onStatusUpdate: (status) => console.log('Status:', status)\n   * });\n   * ```\n   */\n  async wait(options?: {\n    /** Callback for status updates during polling */\n    onStatusUpdate?: (status: OperationStatus) => void;\n    /** Abort signal for cancellation */\n    signal?: AbortSignal;\n    /** Timeout in milliseconds */\n    timeout?: number;\n  }): Promise<any> {\n    // Handle 'confirmed' responses - already complete\n    if (this.response.type === \"confirmed\") {\n      return {\n        hash: this.response.hash,\n        receipt: this.response.receipt,\n      };\n    }\n\n    // Handle 'submitted' or 'signed' responses with context - full event parsing\n    if (\n      (this.response.type === \"submitted\" || this.response.type === \"signed\") &&\n      this.context\n    ) {\n      // Use the SDK's waitForTransactionEvents with the preserved context\n      return await this.sdk.waitForTransactionEvents({\n        hash: this.response.hash,\n        from: this.context.from,\n        contract: this.context.contract,\n        fn: this.context.fn,\n      });\n    }\n\n    // Handle 'submitted' or 'signed' responses without context - receipt only\n    if (this.response.type === \"submitted\" || this.response.type === \"signed\") {\n      // Just wait for the receipt without event parsing\n      const receipt = await this.sdk.publicClient.waitForTransactionReceipt({\n        hash: this.response.hash,\n      });\n      return {\n        hash: this.response.hash,\n        receipt: receipt as TransactionReceipt,\n      };\n    }\n\n    // Handle 'pending' responses - use PollingManager\n    if (this.response.type === \"pending\") {\n      // Access the relayer callback from the SDK's internal config\n      const sdkInternal = this.sdk as any;\n      const relayerCallback = sdkInternal.relayerCallback;\n\n      if (typeof relayerCallback !== \"function\") {\n        throw new Error(\"Relayer callback not configured for polling\");\n      }\n\n      const pollingManager = new PollingManager(relayerCallback);\n      return await pollingManager.startPolling(this.response.operationId, {\n        signal: options?.signal,\n        onStatusUpdate: options?.onStatusUpdate,\n        timeout: options?.timeout,\n      });\n    }\n\n    // Response type cannot be waited on\n    throw new Error(\n      `Cannot wait on response type: ${(this.response as any).type}. ` +\n        `Only 'submitted', 'signed', 'pending', and 'confirmed' responses can be waited on.`,\n    );\n  }\n\n  /**\n   * Checks if this response can be waited on.\n   *\n   * @returns true if the response supports the wait() method\n   */\n  canWait(): boolean {\n    return (\n      this.response.type === \"submitted\" ||\n      this.response.type === \"signed\" ||\n      this.response.type === \"pending\" ||\n      this.response.type === \"confirmed\"\n    );\n  }\n\n  /**\n   * Gets a human-readable status description.\n   *\n   * @returns Status string describing the current state\n   */\n  getStatus(): string {\n    switch (this.response.type) {\n      case \"pending\":\n        return `Operation pending (ID: ${this.operationId})`;\n      case \"submitted\":\n      case \"signed\":\n        return `Transaction submitted (Hash: ${this.hash})`;\n      case \"confirmed\":\n        return `Transaction confirmed (Hash: ${this.response.hash})`;\n      case \"direct\":\n        return \"Operation completed\";\n      case \"error\":\n        return `Error: ${this.response.error}`;\n      default:\n        return \"Unknown status\";\n    }\n  }\n}\n\n/**\n * Type guard to check if a response can be enhanced.\n *\n * @param response - The unified relayer response to check\n * @returns true if the response can be wrapped in EnhancedTransactionResponse\n */\nexport function canEnhanceResponse(response: UnifiedRelayerResponse): boolean {\n  return (\n    response.type === \"submitted\" ||\n    response.type === \"signed\" ||\n    response.type === \"pending\" ||\n    response.type === \"confirmed\"\n  );\n}\n\n/**\n * Factory function to create an enhanced response if applicable.\n *\n * @param response - The unified relayer response\n * @param sdk - The Vana SDK instance\n * @returns EnhancedTransactionResponse if enhanceable, null otherwise\n *\n * @example\n * ```typescript\n * const response = await handleRelayerOperation(vana, request);\n * const enhanced = enhanceResponse(response, vana);\n * if (enhanced) {\n *   await enhanced.wait();\n * }\n * ```\n */\nexport function enhanceResponse(\n  response: UnifiedRelayerResponse,\n  sdk: any,\n): EnhancedTransactionResponse | null {\n  if (canEnhanceResponse(response)) {\n    return new EnhancedTransactionResponse(response, sdk);\n  }\n  return null;\n}\n"],"mappings":"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","names":[]}

package/dist/client/enhancedResponse.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Enhanced client-side response wrapper for relayer operations.
+ *
+ * @remarks
+ * This module provides a fluent API for handling asynchronous relayer responses
+ * by adding stateful behavior to the stateless response data. It enables the
+ * `.wait()` pattern similar to ethers.js while maintaining clean separation
+ * between server-side data transfer and client-side behavior.
+ *
+ * @module client/enhancedResponse
+ */
+import type { Hash } from "viem";
+import type { UnifiedRelayerResponse, TransactionContext } from "../types/relayer";
+import type { OperationStatus } from "../types/options";
+/**
+ * Enhanced transaction response that provides a fluent API for waiting.
+ *
+ * @remarks
+ * This class wraps a UnifiedRelayerResponse and provides a `.wait()` method
+ * that intelligently handles both submitted transactions (via hash) and
+ * pending operations (via operationId). It encapsulates the complexity of
+ * polling and event parsing, providing a clean developer experience.
+ *
+ * @example
+ * ```typescript
+ * const response = await relayerClient.handleOperation(...);
+ * const enhanced = vana.enhanceRelayerResponse(response);
+ * if (enhanced) {
+ *   const result = await enhanced.wait();
+ *   console.log('Transaction confirmed:', result.hash);
+ * }
+ * ```
+ *
+ * @category Client
+ */
+export declare class EnhancedTransactionResponse {
+    /** The underlying relayer response */
+    readonly response: UnifiedRelayerResponse;
+    /** The hash if this is a submitted transaction */
+    readonly hash?: Hash;
+    /** The operation ID if this is a pending operation */
+    readonly operationId?: string;
+    /** Transaction context for event parsing */
+    readonly context?: TransactionContext;
+    private readonly sdk;
+    constructor(response: UnifiedRelayerResponse, sdk: any);
+    /**
+     * Waits for the transaction or operation to complete.
+     *
+     * @remarks
+     * This method provides intelligent handling based on the response type:
+     * - For 'submitted' responses with context: Uses waitForTransactionEvents for full event parsing
+     * - For 'submitted' responses without context: Waits for receipt only
+     * - For 'pending' responses: Uses PollingManager to track async operations
+     * - For 'confirmed' responses: Returns immediately with the receipt
+     *
+     * @param options - Optional configuration for polling behavior
+     * @returns Promise resolving to event results or transaction receipt
+     * @throws Error if the response type cannot be waited on
+     *
+     * @example
+     * ```typescript
+     * // With context for event parsing
+     * const enhanced = new EnhancedTransactionResponse(response, vana);
+     * const result = await enhanced.wait();
+     * if (result.expectedEvents?.FileAdded) {
+     *   console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+     * }
+     *
+     * // For pending operations
+     * const result = await enhanced.wait({
+     *   onStatusUpdate: (status) => console.log('Status:', status)
+     * });
+     * ```
+     */
+    wait(options?: {
+        /** Callback for status updates during polling */
+        onStatusUpdate?: (status: OperationStatus) => void;
+        /** Abort signal for cancellation */
+        signal?: AbortSignal;
+        /** Timeout in milliseconds */
+        timeout?: number;
+    }): Promise<any>;
+    /**
+     * Checks if this response can be waited on.
+     *
+     * @returns true if the response supports the wait() method
+     */
+    canWait(): boolean;
+    /**
+     * Gets a human-readable status description.
+     *
+     * @returns Status string describing the current state
+     */
+    getStatus(): string;
+}
+/**
+ * Type guard to check if a response can be enhanced.
+ *
+ * @param response - The unified relayer response to check
+ * @returns true if the response can be wrapped in EnhancedTransactionResponse
+ */
+export declare function canEnhanceResponse(response: UnifiedRelayerResponse): boolean;
+/**
+ * Factory function to create an enhanced response if applicable.
+ *
+ * @param response - The unified relayer response
+ * @param sdk - The Vana SDK instance
+ * @returns EnhancedTransactionResponse if enhanceable, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const response = await handleRelayerOperation(vana, request);
+ * const enhanced = enhanceResponse(response, vana);
+ * if (enhanced) {
+ *   await enhanced.wait();
+ * }
+ * ```
+ */
+export declare function enhanceResponse(response: UnifiedRelayerResponse, sdk: any): EnhancedTransactionResponse | null;

package/dist/client/enhancedResponse.js

@@ -0,0 +1,138 @@
+import { PollingManager } from "../core/pollingManager";
+class EnhancedTransactionResponse {
+  /** The underlying relayer response */
+  response;
+  /** The hash if this is a submitted transaction */
+  hash;
+  /** The operation ID if this is a pending operation */
+  operationId;
+  /** Transaction context for event parsing */
+  context;
+  sdk;
+  // Using any to avoid circular dependency
+  constructor(response, sdk) {
+    this.response = response;
+    this.sdk = sdk;
+    if (response.type === "submitted" || response.type === "signed") {
+      this.hash = response.hash;
+      this.context = response.context;
+    } else if (response.type === "pending") {
+      this.operationId = response.operationId;
+    }
+  }
+  /**
+   * Waits for the transaction or operation to complete.
+   *
+   * @remarks
+   * This method provides intelligent handling based on the response type:
+   * - For 'submitted' responses with context: Uses waitForTransactionEvents for full event parsing
+   * - For 'submitted' responses without context: Waits for receipt only
+   * - For 'pending' responses: Uses PollingManager to track async operations
+   * - For 'confirmed' responses: Returns immediately with the receipt
+   *
+   * @param options - Optional configuration for polling behavior
+   * @returns Promise resolving to event results or transaction receipt
+   * @throws Error if the response type cannot be waited on
+   *
+   * @example
+   * ```typescript
+   * // With context for event parsing
+   * const enhanced = new EnhancedTransactionResponse(response, vana);
+   * const result = await enhanced.wait();
+   * if (result.expectedEvents?.FileAdded) {
+   *   console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+   * }
+   *
+   * // For pending operations
+   * const result = await enhanced.wait({
+   *   onStatusUpdate: (status) => console.log('Status:', status)
+   * });
+   * ```
+   */
+  async wait(options) {
+    if (this.response.type === "confirmed") {
+      return {
+        hash: this.response.hash,
+        receipt: this.response.receipt
+      };
+    }
+    if ((this.response.type === "submitted" || this.response.type === "signed") && this.context) {
+      return await this.sdk.waitForTransactionEvents({
+        hash: this.response.hash,
+        from: this.context.from,
+        contract: this.context.contract,
+        fn: this.context.fn
+      });
+    }
+    if (this.response.type === "submitted" || this.response.type === "signed") {
+      const receipt = await this.sdk.publicClient.waitForTransactionReceipt({
+        hash: this.response.hash
+      });
+      return {
+        hash: this.response.hash,
+        receipt
+      };
+    }
+    if (this.response.type === "pending") {
+      const sdkInternal = this.sdk;
+      const relayerCallback = sdkInternal.relayerCallback;
+      if (typeof relayerCallback !== "function") {
+        throw new Error("Relayer callback not configured for polling");
+      }
+      const pollingManager = new PollingManager(relayerCallback);
+      return await pollingManager.startPolling(this.response.operationId, {
+        signal: options?.signal,
+        onStatusUpdate: options?.onStatusUpdate,
+        timeout: options?.timeout
+      });
+    }
+    throw new Error(
+      `Cannot wait on response type: ${this.response.type}. Only 'submitted', 'signed', 'pending', and 'confirmed' responses can be waited on.`
+    );
+  }
+  /**
+   * Checks if this response can be waited on.
+   *
+   * @returns true if the response supports the wait() method
+   */
+  canWait() {
+    return this.response.type === "submitted" || this.response.type === "signed" || this.response.type === "pending" || this.response.type === "confirmed";
+  }
+  /**
+   * Gets a human-readable status description.
+   *
+   * @returns Status string describing the current state
+   */
+  getStatus() {
+    switch (this.response.type) {
+      case "pending":
+        return `Operation pending (ID: ${this.operationId})`;
+      case "submitted":
+      case "signed":
+        return `Transaction submitted (Hash: ${this.hash})`;
+      case "confirmed":
+        return `Transaction confirmed (Hash: ${this.response.hash})`;
+      case "direct":
+        return "Operation completed";
+      case "error":
+        return `Error: ${this.response.error}`;
+      default:
+        return "Unknown status";
+    }
+  }
+}
+function canEnhanceResponse(response) {
+  return response.type === "submitted" || response.type === "signed" || response.type === "pending" || response.type === "confirmed";
+}
+function enhanceResponse(response, sdk) {
+  if (canEnhanceResponse(response)) {
+    return new EnhancedTransactionResponse(response, sdk);
+  }
+  return null;
+}
+export {
+  EnhancedTransactionResponse,
+  canEnhanceResponse,
+  enhanceResponse
+};
+//# sourceMappingURL=enhancedResponse.js.map

package/dist/client/enhancedResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/enhancedResponse.ts"],"sourcesContent":["/**\n * Enhanced client-side response wrapper for relayer operations.\n *\n * @remarks\n * This module provides a fluent API for handling asynchronous relayer responses\n * by adding stateful behavior to the stateless response data. It enables the\n * `.wait()` pattern similar to ethers.js while maintaining clean separation\n * between server-side data transfer and client-side behavior.\n *\n * @module client/enhancedResponse\n */\n\nimport type { Hash, TransactionReceipt } from \"viem\";\nimport type {\n  UnifiedRelayerResponse,\n  TransactionContext,\n} from \"../types/relayer\";\nimport { PollingManager } from \"../core/pollingManager\";\nimport type { OperationStatus } from \"../types/options\";\n\n/**\n * Enhanced transaction response that provides a fluent API for waiting.\n *\n * @remarks\n * This class wraps a UnifiedRelayerResponse and provides a `.wait()` method\n * that intelligently handles both submitted transactions (via hash) and\n * pending operations (via operationId). It encapsulates the complexity of\n * polling and event parsing, providing a clean developer experience.\n *\n * @example\n * ```typescript\n * const response = await relayerClient.handleOperation(...);\n * const enhanced = vana.enhanceRelayerResponse(response);\n * if (enhanced) {\n *   const result = await enhanced.wait();\n *   console.log('Transaction confirmed:', result.hash);\n * }\n * ```\n *\n * @category Client\n */\nexport class EnhancedTransactionResponse {\n  /** The underlying relayer response */\n  public readonly response: UnifiedRelayerResponse;\n\n  /** The hash if this is a submitted transaction */\n  public readonly hash?: Hash;\n\n  /** The operation ID if this is a pending operation */\n  public readonly operationId?: string;\n\n  /** Transaction context for event parsing */\n  public readonly context?: TransactionContext;\n\n  private readonly sdk: any; // Using any to avoid circular dependency\n\n  constructor(response: UnifiedRelayerResponse, sdk: any) {\n    this.response = response;\n    this.sdk = sdk;\n\n    // Extract key properties based on response type\n    if (response.type === \"submitted\" || response.type === \"signed\") {\n      this.hash = response.hash;\n      this.context = response.context;\n    } else if (response.type === \"pending\") {\n      this.operationId = response.operationId;\n    }\n  }\n\n  /**\n   * Waits for the transaction or operation to complete.\n   *\n   * @remarks\n   * This method provides intelligent handling based on the response type:\n   * - For 'submitted' responses with context: Uses waitForTransactionEvents for full event parsing\n   * - For 'submitted' responses without context: Waits for receipt only\n   * - For 'pending' responses: Uses PollingManager to track async operations\n   * - For 'confirmed' responses: Returns immediately with the receipt\n   *\n   * @param options - Optional configuration for polling behavior\n   * @returns Promise resolving to event results or transaction receipt\n   * @throws Error if the response type cannot be waited on\n   *\n   * @example\n   * ```typescript\n   * // With context for event parsing\n   * const enhanced = new EnhancedTransactionResponse(response, vana);\n   * const result = await enhanced.wait();\n   * if (result.expectedEvents?.FileAdded) {\n   *   console.log('File ID:', result.expectedEvents.FileAdded.fileId);\n   * }\n   *\n   * // For pending operations\n   * const result = await enhanced.wait({\n   *   onStatusUpdate: (status) => console.log('Status:', status)\n   * });\n   * ```\n   */\n  async wait(options?: {\n    /** Callback for status updates during polling */\n    onStatusUpdate?: (status: OperationStatus) => void;\n    /** Abort signal for cancellation */\n    signal?: AbortSignal;\n    /** Timeout in milliseconds */\n    timeout?: number;\n  }): Promise<any> {\n    // Handle 'confirmed' responses - already complete\n    if (this.response.type === \"confirmed\") {\n      return {\n        hash: this.response.hash,\n        receipt: this.response.receipt,\n      };\n    }\n\n    // Handle 'submitted' or 'signed' responses with context - full event parsing\n    if (\n      (this.response.type === \"submitted\" || this.response.type === \"signed\") &&\n      this.context\n    ) {\n      // Use the SDK's waitForTransactionEvents with the preserved context\n      return await this.sdk.waitForTransactionEvents({\n        hash: this.response.hash,\n        from: this.context.from,\n        contract: this.context.contract,\n        fn: this.context.fn,\n      });\n    }\n\n    // Handle 'submitted' or 'signed' responses without context - receipt only\n    if (this.response.type === \"submitted\" || this.response.type === \"signed\") {\n      // Just wait for the receipt without event parsing\n      const receipt = await this.sdk.publicClient.waitForTransactionReceipt({\n        hash: this.response.hash,\n      });\n      return {\n        hash: this.response.hash,\n        receipt: receipt as TransactionReceipt,\n      };\n    }\n\n    // Handle 'pending' responses - use PollingManager\n    if (this.response.type === \"pending\") {\n      // Access the relayer callback from the SDK's internal config\n      const sdkInternal = this.sdk as any;\n      const relayerCallback = sdkInternal.relayerCallback;\n\n      if (typeof relayerCallback !== \"function\") {\n        throw new Error(\"Relayer callback not configured for polling\");\n      }\n\n      const pollingManager = new PollingManager(relayerCallback);\n      return await pollingManager.startPolling(this.response.operationId, {\n        signal: options?.signal,\n        onStatusUpdate: options?.onStatusUpdate,\n        timeout: options?.timeout,\n      });\n    }\n\n    // Response type cannot be waited on\n    throw new Error(\n      `Cannot wait on response type: ${(this.response as any).type}. ` +\n        `Only 'submitted', 'signed', 'pending', and 'confirmed' responses can be waited on.`,\n    );\n  }\n\n  /**\n   * Checks if this response can be waited on.\n   *\n   * @returns true if the response supports the wait() method\n   */\n  canWait(): boolean {\n    return (\n      this.response.type === \"submitted\" ||\n      this.response.type === \"signed\" ||\n      this.response.type === \"pending\" ||\n      this.response.type === \"confirmed\"\n    );\n  }\n\n  /**\n   * Gets a human-readable status description.\n   *\n   * @returns Status string describing the current state\n   */\n  getStatus(): string {\n    switch (this.response.type) {\n      case \"pending\":\n        return `Operation pending (ID: ${this.operationId})`;\n      case \"submitted\":\n      case \"signed\":\n        return `Transaction submitted (Hash: ${this.hash})`;\n      case \"confirmed\":\n        return `Transaction confirmed (Hash: ${this.response.hash})`;\n      case \"direct\":\n        return \"Operation completed\";\n      case \"error\":\n        return `Error: ${this.response.error}`;\n      default:\n        return \"Unknown status\";\n    }\n  }\n}\n\n/**\n * Type guard to check if a response can be enhanced.\n *\n * @param response - The unified relayer response to check\n * @returns true if the response can be wrapped in EnhancedTransactionResponse\n */\nexport function canEnhanceResponse(response: UnifiedRelayerResponse): boolean {\n  return (\n    response.type === \"submitted\" ||\n    response.type === \"signed\" ||\n    response.type === \"pending\" ||\n    response.type === \"confirmed\"\n  );\n}\n\n/**\n * Factory function to create an enhanced response if applicable.\n *\n * @param response - The unified relayer response\n * @param sdk - The Vana SDK instance\n * @returns EnhancedTransactionResponse if enhanceable, null otherwise\n *\n * @example\n * ```typescript\n * const response = await handleRelayerOperation(vana, request);\n * const enhanced = enhanceResponse(response, vana);\n * if (enhanced) {\n *   await enhanced.wait();\n * }\n * ```\n */\nexport function enhanceResponse(\n  response: UnifiedRelayerResponse,\n  sdk: any,\n): EnhancedTransactionResponse | null {\n  if (canEnhanceResponse(response)) {\n    return new EnhancedTransactionResponse(response, sdk);\n  }\n  return null;\n}\n"],"mappings":"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","names":[]}