0xtrails 0.13.2 → 0.14.0

package/src/intentReceiptPoller.ts

@@ -1,327 +0,0 @@
-import type { TrailsClient } from "./trailsClient.js"
-import type {
-  IntentReceipt,
-  WaitIntentReceiptResponse,
-  TransactionStatus,
-} from "@0xtrails/api"
-import { logger } from "./logger.js"
-import { MINUTE_MS } from "./utils/time.js"
-
-const POLL_INTERVAL = 150 // 150 ms
-const MAX_WAIT_TIME = 15 * MINUTE_MS // 15 minutes
-
-/**
- * Callback invoked when the deposit transaction hash is discovered (for gasless flows).
- * @param txHash - The transaction hash of the deposit transaction
- * @param receipt - The full IntentReceipt containing additional metadata
- */
-export type OnDepositTransactionFound = (
-  txHash: string,
-  receipt: IntentReceipt,
-) => Promise<void>
-
-/**
- * Callback invoked when the origin transaction hash is discovered.
- * @param txHash - The transaction hash of the origin transaction
- * @param receipt - The full IntentReceipt containing additional metadata
- */
-export type OnOriginTransactionFound = (
-  txHash: string,
-  receipt: IntentReceipt,
-) => Promise<void>
-
-/**
- * Callback invoked when the destination transaction hash is discovered.
- * @param txHash - The transaction hash of the destination transaction
- * @param receipt - The full IntentReceipt containing additional metadata
- */
-export type OnDestinationTransactionFound = (
-  txHash: string,
-  receipt: IntentReceipt,
-) => Promise<void>
-
-/**
- * Callback invoked when the intent receipt is updated (regardless of which field changed).
- * @param receipt - The full IntentReceipt
- * @param done - Whether the intent has reached a terminal status
- */
-export type OnReceiptUpdate = (
-  receipt: IntentReceipt,
-  done: boolean,
-) => Promise<void>
-
-export interface IntentReceiptPollerCallbacks {
-  onDepositTransactionFound?: OnDepositTransactionFound
-  onOriginTransactionFound?: OnOriginTransactionFound
-  onDestinationTransactionFound?: OnDestinationTransactionFound
-  onReceiptUpdate?: OnReceiptUpdate
-}
-
-export interface IntentReceiptPollerOptions {
-  intentId: string
-  trailsClient: TrailsClient
-  callbacks?: IntentReceiptPollerCallbacks
-  maxWaitTime?: number
-  pollInterval?: number
-  abortSignal?: AbortSignal
-}
-
-/**
- * Unified intent receipt poller that monitors a single intent ID and invokes callbacks
- * as origin and destination transactions are discovered. This consolidates what was
- * previously done via separate polling loops.
- *
- * @param options - Configuration for polling including intent ID, client, and callbacks
- * @returns A promise that resolves when the intent reaches a terminal status or times out
- *
- * Usage:
- * ```
- * const poller = pollIntentReceipt({
- *   intentId: intent.intentId,
- *   trailsClient,
- *   callbacks: {
- *     onOriginTransactionFound: async (txHash, receipt) => {
- *       // Handle origin transaction discovery
- *     },
- *     onDestinationTransactionFound: async (txHash, receipt) => {
- *       // Handle destination transaction discovery
- *     },
- *     onReceiptUpdate: async (receipt, done) => {
- *       // Handle any receipt update
- *     },
- *   },
- * })
- * ```
- */
-export async function pollIntentReceipt(
-  options: IntentReceiptPollerOptions,
-): Promise<IntentReceipt | null> {
-  const {
-    intentId,
-    trailsClient,
-    callbacks,
-    maxWaitTime = MAX_WAIT_TIME,
-    pollInterval = POLL_INTERVAL,
-    abortSignal,
-  } = options
-
-  const startTime = Date.now()
-  let lastDepositTxHash: string | undefined
-  let lastOriginTxHash: string | undefined
-  let lastDestinationTxHash: string | undefined
-  let lastReceipt: IntentReceipt | null = null
-  let lastReceiptStates: TransactionStatus[] = []
-
-  logger.console.log("[trails-sdk] Starting unified intent receipt polling", {
-    intentId,
-    maxWaitTime,
-    pollInterval,
-  })
-
-  try {
-    while (Date.now() - startTime < maxWaitTime) {
-      // Check abort signal
-      if (abortSignal?.aborted) {
-        logger.console.log(
-          "[trails-sdk] Intent receipt polling aborted via signal",
-          {
-            intentId,
-          },
-        )
-        return lastReceipt
-      }
-
-      try {
-        // Perform single waitIntentReceipt call
-        const response: WaitIntentReceiptResponse =
-          await trailsClient.waitIntentReceipt({
-            intentId,
-            lastReceiptStates,
-          })
-
-        const receipt = response.intentReceipt
-        lastReceipt = receipt
-        lastReceiptStates = response.receiptStates
-
-        logger.console.log("[trails-sdk] Unified intent receipt update", {
-          intentId,
-          status: receipt.status,
-          done: response.done,
-          depositTxHash: receipt.depositTransaction?.txnHash,
-          originTxHash: receipt.originTransaction?.txnHash,
-          destinationTxHash: receipt.destinationTransaction?.txnHash,
-        })
-
-        // Check if deposit transaction was discovered (and not already reported)
-        // This is used for gasless flows where the user's deposit is tracked separately
-        if (
-          receipt.depositTransaction?.txnHash &&
-          receipt.depositTransaction.txnHash !== lastDepositTxHash
-        ) {
-          lastDepositTxHash = receipt.depositTransaction.txnHash
-          logger.console.log(
-            "[trails-sdk] Deposit transaction discovered via unified poller",
-            {
-              intentId,
-              txHash: lastDepositTxHash,
-            },
-          )
-
-          if (callbacks?.onDepositTransactionFound) {
-            try {
-              await callbacks.onDepositTransactionFound(
-                lastDepositTxHash,
-                receipt,
-              )
-            } catch (error) {
-              logger.console.error(
-                "[trails-sdk] Error in onDepositTransactionFound callback",
-                {
-                  error: error instanceof Error ? error.message : String(error),
-                },
-              )
-            }
-          }
-        }
-
-        // Check if origin transaction was discovered (and not already reported)
-        if (
-          receipt.originTransaction?.txnHash &&
-          receipt.originTransaction.txnHash !== lastOriginTxHash
-        ) {
-          lastOriginTxHash = receipt.originTransaction.txnHash
-          logger.console.log(
-            "[trails-sdk] Origin transaction discovered via unified poller",
-            {
-              intentId,
-              txHash: lastOriginTxHash,
-            },
-          )
-
-          if (callbacks?.onOriginTransactionFound) {
-            try {
-              await callbacks.onOriginTransactionFound(
-                lastOriginTxHash,
-                receipt,
-              )
-            } catch (error) {
-              logger.console.error(
-                "[trails-sdk] Error in onOriginTransactionFound callback",
-                {
-                  error: error instanceof Error ? error.message : String(error),
-                },
-              )
-            }
-          }
-        }
-
-        // Check if destination transaction was discovered (and not already reported)
-        if (
-          receipt.destinationTransaction?.txnHash &&
-          receipt.destinationTransaction.txnHash !== lastDestinationTxHash
-        ) {
-          lastDestinationTxHash = receipt.destinationTransaction.txnHash
-          logger.console.log(
-            "[trails-sdk] Destination transaction discovered via unified poller",
-            {
-              intentId,
-              txHash: lastDestinationTxHash,
-            },
-          )
-
-          if (callbacks?.onDestinationTransactionFound) {
-            try {
-              await callbacks.onDestinationTransactionFound(
-                lastDestinationTxHash,
-                receipt,
-              )
-            } catch (error) {
-              logger.console.error(
-                "[trails-sdk] Error in onDestinationTransactionFound callback",
-                {
-                  error: error instanceof Error ? error.message : String(error),
-                },
-              )
-            }
-          }
-        }
-
-        // Invoke generic receipt update callback
-        if (callbacks?.onReceiptUpdate) {
-          try {
-            await callbacks.onReceiptUpdate(receipt, response.done)
-          } catch (error) {
-            logger.console.error(
-              "[trails-sdk] Error in onReceiptUpdate callback",
-              {
-                error: error instanceof Error ? error.message : String(error),
-              },
-            )
-          }
-        }
-
-        // Defensive fallback for backend lag/inconsistency:
-        // if receipt status has not flipped to terminal yet, but destination
-        // transaction is already succeeded and we have a finished marker, treat
-        // the flow as complete to avoid indefinite pending UI.
-        const summary = (
-          receipt as unknown as { summary?: { finishedAt?: string | null } }
-        ).summary
-        const hasFinishedMarker = Boolean(
-          summary?.finishedAt ||
-            receipt.destinationTransaction?.txnMinedAt ||
-            receipt.destinationTransaction?.txnHash,
-        )
-        const destinationSucceeded =
-          receipt.destinationTransaction?.status === "SUCCEEDED"
-        if (destinationSucceeded && hasFinishedMarker) {
-          logger.console.warn(
-            "[trails-sdk] Treating receipt as complete via destination-success fallback",
-            {
-              intentId,
-              status: receipt.status,
-              destinationTxHash: receipt.destinationTransaction?.txnHash,
-              hasFinishedMarker,
-            },
-          )
-          return receipt
-        }
-
-        // If intent is done, stop polling
-        if (response.done) {
-          logger.console.log("[trails-sdk] Intent receipt polling complete", {
-            intentId,
-            status: receipt.status,
-          })
-          return receipt
-        }
-      } catch (error) {
-        logger.console.warn("[trails-sdk] Error polling intent receipt", {
-          intentId,
-          error: error instanceof Error ? error.message : String(error),
-        })
-        // Continue polling on error
-      }
-
-      // Wait a very short period of time before next poll.
-      // We do not want to wait long, as we want quick feedback to users
-      // on state changes.
-      await new Promise((resolve) => setTimeout(resolve, pollInterval))
-    }
-
-    logger.console.warn("[trails-sdk] Intent receipt polling timeout", {
-      intentId,
-      maxWaitTime,
-    })
-    return lastReceipt
-  } catch (error) {
-    logger.console.error(
-      "[trails-sdk] Unexpected error in intent receipt polling",
-      {
-        intentId,
-        error: error instanceof Error ? error.message : String(error),
-      },
-    )
-    return lastReceipt
-  }
-}