@metamask-previews/bridge-status-controller 73.1.0-preview-e12e4a38f → 74.0.0-preview-4f9d41d

package/dist/quote-status-manager/quotes-status-manager.d.cts

@@ -0,0 +1,124 @@
+import { BridgeClientId, BridgeStatusControllerMessenger } from "../types.cjs";
+import { QuoteStatusUpdateError } from "./errors.cjs";
+import { QuoteStatusPersistEntry } from "./types.cjs";
+/**
+ * Tracks bridge/swap quotes through their lifecycle and keeps the backend in
+ * sync with the latest known status of each quote.
+ *
+ * Quotes are reported via {@link reportSubmitted} and {@link reportFinalised},
+ * stored as runtime entries, and pushed to the backend. Updates that fail in a
+ * retryable way are retried on a periodic timer until each entry reaches a
+ * terminal state, at which point it is evicted and the timer stops once the
+ * store is empty.
+ */
+export declare class QuoteStatusManager {
+    #private;
+    /**
+     * Creates a new manager and immediately processes any persisted entries.
+     *
+     * @param options - Constructor options.
+     * @param options.messenger - Messenger used to communicate with the backend
+     * API service.
+     * @param options.clientId - Identifier of the client making the requests.
+     * @param options.clientProduct - Name of the client product making the
+     * requests.
+     * @param options.clientVersion - Optional version of the client product.
+     * @param options.apiBaseUrl - Base URL of the quote status backend API.
+     * @param options.onPersistUpdates - Callback invoked to persist entry updates.
+     * @param options.onError - Optional callback invoked when a non-recoverable
+     * error occurs.
+     * @param options.isEnabled - Optional predicate gating whether the manager
+     * performs any work.
+     * @param options.entryTtlMs - Time-to-live, in milliseconds, after which a
+     * tracked entry is evicted.
+     * @param options.updateIntervalMs - How often the manager re-processes entries that
+     * have not yet reached a terminal state
+     * @param options.initialData - Persisted entries to rehydrate on startup.
+     */
+    constructor({ messenger, clientId, clientProduct, clientVersion, apiBaseUrl, onError, isEnabled, onPersistUpdates, entryTtlMs, updateIntervalMs, initialData, }: {
+        messenger: BridgeStatusControllerMessenger;
+        clientId: BridgeClientId;
+        clientProduct: string;
+        clientVersion?: string;
+        apiBaseUrl: string;
+        onPersistUpdates: (updates: Record<string, QuoteStatusPersistEntry>) => void;
+        onError?: (error: QuoteStatusUpdateError) => void;
+        isEnabled?: () => boolean;
+        entryTtlMs: number;
+        updateIntervalMs: number;
+        initialData: Record<string, QuoteStatusPersistEntry>;
+    });
+    /**
+     * Whether quote-status tracking and backend sync are currently active.
+     *
+     * Reflects the latest value returned by the optional `isEnabled` predicate
+     * supplied at construction time. When no predicate was provided, this is
+     * always `false` and all public methods that gate on enablement no-op.
+     *
+     * @returns `true` when the `isEnabled` predicate returns a truthy value.
+     */
+    get enabled(): boolean;
+    /**
+     * Reports that a previously submitted quote has finalized on-chain.
+     *
+     * Looks up the tracked entry by its transaction metadata id, transitions it to
+     * the appropriate terminal state, and processes the update. No-ops when the
+     * manager is disabled, and surfaces an error when the entry is missing or
+     * cannot transition to the finalized state.
+     *
+     * @param txMetaId - Transaction metadata id of the finalized quote.
+     * @param success - Whether the transaction finalized successfully.
+     */
+    reportFinalised(txMetaId: string, success: boolean): void;
+    /**
+     * Reports that a quote has been submitted on-chain and begins tracking it.
+     *
+     * Creates a new entry in the `Submitted` state, starts the retry timer, and
+     * processes the initial status update. No-ops when the manager is disabled,
+     * and surfaces an error if the entry cannot be retrieved after being stored.
+     *
+     * @param quoteId - Identifier of the submitted quote.
+     * @param srcTxHash - Hash of the source-chain transaction for the quote.
+     * @param txMetaId - Optional transaction metadata id used to correlate
+     * finalization reports.
+     */
+    reportSubmitted(quoteId: string, srcTxHash: string, txMetaId?: string): void;
+    /**
+     * Tears down the manager by stopping the retry timer and clearing all tracked
+     * entries.
+     */
+    destroy(): void;
+    /**
+     * Reconciles quote-status entries whose finalization was missed while the
+     * client was closed. Called once during initialization.
+     *
+     * Swap/bridge source transactions report their final status through the
+     * `TransactionController:transactionStatusUpdated` subscription
+     * ({@link #onTransactionConfirmed}/{@link #onTransactionFailed}). When a source
+     * transaction reaches a terminal state while the client is not running, that
+     * event is never re-emitted on the next startup, so the persisted entry would
+     * remain `Submitted` until it expires via TTL. This replays the missed terminal
+     * event for both swaps and bridges: a confirmed source transaction is reported
+     * as a finalized success and a failed/dropped one as a finalized failure.
+     *
+     * `rejected` is ignored because the transaction was never broadcast.
+     */
+    init(): void;
+    /**
+     * Fetches the current quote status from the backend with automatic retries.
+     *
+     * Unlike {@link reportSubmitted} and {@link reportFinalised}, this is a
+     * read-only query and does not mutate tracked entries. Returns `null` when
+     * the manager is disabled ({@link enabled} is `false`).
+     *
+     * @param quoteId - Identifier of the quote whose status should be fetched.
+     * @param options - Retry configuration.
+     * @param options.maxRetries - Maximum number of retries after the initial attempt.
+     * @param options.delayMsBetweenRetries - Delay in milliseconds between attempts.
+     */
+    getStatus(quoteId: string, options?: {
+        maxRetries?: number;
+        delayMsBetweenRetries?: number;
+    }): void;
+}
+//# sourceMappingURL=quotes-status-manager.d.cts.map

package/dist/quote-status-manager/quotes-status-manager.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotes-status-manager.d.cts","sourceRoot":"","sources":["../../src/quote-status-manager/quotes-status-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,+BAA+B,EAAE,qBAAiB;AAa3E,OAAO,EAAE,sBAAsB,EAAE,qBAAiB;AAKlD,OAAO,EAAE,uBAAuB,EAA2B,oBAAgB;AAE3E;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;;IAqB7B;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,aAAa,EACb,UAAU,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,GACZ,EAAE;QACD,SAAS,EAAE,+BAA+B,CAAC;QAC3C,QAAQ,EAAE,cAAc,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,KAC7C,IAAI,CAAC;QACV,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;QAClD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;KACtD;IAsBD;;;;;;;;OAQG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAoCzD;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAgC5E;;;OAGG;IACH,OAAO,IAAI,IAAI;IAKf;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,IAAI;IAuCZ;;;;;;;;;;;OAWG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAIhC,GACA,IAAI;CA8YR"}

package/dist/quote-status-manager/quotes-status-manager.d.mts

@@ -0,0 +1,124 @@
+import { BridgeClientId, BridgeStatusControllerMessenger } from "../types.mjs";
+import { QuoteStatusUpdateError } from "./errors.mjs";
+import { QuoteStatusPersistEntry } from "./types.mjs";
+/**
+ * Tracks bridge/swap quotes through their lifecycle and keeps the backend in
+ * sync with the latest known status of each quote.
+ *
+ * Quotes are reported via {@link reportSubmitted} and {@link reportFinalised},
+ * stored as runtime entries, and pushed to the backend. Updates that fail in a
+ * retryable way are retried on a periodic timer until each entry reaches a
+ * terminal state, at which point it is evicted and the timer stops once the
+ * store is empty.
+ */
+export declare class QuoteStatusManager {
+    #private;
+    /**
+     * Creates a new manager and immediately processes any persisted entries.
+     *
+     * @param options - Constructor options.
+     * @param options.messenger - Messenger used to communicate with the backend
+     * API service.
+     * @param options.clientId - Identifier of the client making the requests.
+     * @param options.clientProduct - Name of the client product making the
+     * requests.
+     * @param options.clientVersion - Optional version of the client product.
+     * @param options.apiBaseUrl - Base URL of the quote status backend API.
+     * @param options.onPersistUpdates - Callback invoked to persist entry updates.
+     * @param options.onError - Optional callback invoked when a non-recoverable
+     * error occurs.
+     * @param options.isEnabled - Optional predicate gating whether the manager
+     * performs any work.
+     * @param options.entryTtlMs - Time-to-live, in milliseconds, after which a
+     * tracked entry is evicted.
+     * @param options.updateIntervalMs - How often the manager re-processes entries that
+     * have not yet reached a terminal state
+     * @param options.initialData - Persisted entries to rehydrate on startup.
+     */
+    constructor({ messenger, clientId, clientProduct, clientVersion, apiBaseUrl, onError, isEnabled, onPersistUpdates, entryTtlMs, updateIntervalMs, initialData, }: {
+        messenger: BridgeStatusControllerMessenger;
+        clientId: BridgeClientId;
+        clientProduct: string;
+        clientVersion?: string;
+        apiBaseUrl: string;
+        onPersistUpdates: (updates: Record<string, QuoteStatusPersistEntry>) => void;
+        onError?: (error: QuoteStatusUpdateError) => void;
+        isEnabled?: () => boolean;
+        entryTtlMs: number;
+        updateIntervalMs: number;
+        initialData: Record<string, QuoteStatusPersistEntry>;
+    });
+    /**
+     * Whether quote-status tracking and backend sync are currently active.
+     *
+     * Reflects the latest value returned by the optional `isEnabled` predicate
+     * supplied at construction time. When no predicate was provided, this is
+     * always `false` and all public methods that gate on enablement no-op.
+     *
+     * @returns `true` when the `isEnabled` predicate returns a truthy value.
+     */
+    get enabled(): boolean;
+    /**
+     * Reports that a previously submitted quote has finalized on-chain.
+     *
+     * Looks up the tracked entry by its transaction metadata id, transitions it to
+     * the appropriate terminal state, and processes the update. No-ops when the
+     * manager is disabled, and surfaces an error when the entry is missing or
+     * cannot transition to the finalized state.
+     *
+     * @param txMetaId - Transaction metadata id of the finalized quote.
+     * @param success - Whether the transaction finalized successfully.
+     */
+    reportFinalised(txMetaId: string, success: boolean): void;
+    /**
+     * Reports that a quote has been submitted on-chain and begins tracking it.
+     *
+     * Creates a new entry in the `Submitted` state, starts the retry timer, and
+     * processes the initial status update. No-ops when the manager is disabled,
+     * and surfaces an error if the entry cannot be retrieved after being stored.
+     *
+     * @param quoteId - Identifier of the submitted quote.
+     * @param srcTxHash - Hash of the source-chain transaction for the quote.
+     * @param txMetaId - Optional transaction metadata id used to correlate
+     * finalization reports.
+     */
+    reportSubmitted(quoteId: string, srcTxHash: string, txMetaId?: string): void;
+    /**
+     * Tears down the manager by stopping the retry timer and clearing all tracked
+     * entries.
+     */
+    destroy(): void;
+    /**
+     * Reconciles quote-status entries whose finalization was missed while the
+     * client was closed. Called once during initialization.
+     *
+     * Swap/bridge source transactions report their final status through the
+     * `TransactionController:transactionStatusUpdated` subscription
+     * ({@link #onTransactionConfirmed}/{@link #onTransactionFailed}). When a source
+     * transaction reaches a terminal state while the client is not running, that
+     * event is never re-emitted on the next startup, so the persisted entry would
+     * remain `Submitted` until it expires via TTL. This replays the missed terminal
+     * event for both swaps and bridges: a confirmed source transaction is reported
+     * as a finalized success and a failed/dropped one as a finalized failure.
+     *
+     * `rejected` is ignored because the transaction was never broadcast.
+     */
+    init(): void;
+    /**
+     * Fetches the current quote status from the backend with automatic retries.
+     *
+     * Unlike {@link reportSubmitted} and {@link reportFinalised}, this is a
+     * read-only query and does not mutate tracked entries. Returns `null` when
+     * the manager is disabled ({@link enabled} is `false`).
+     *
+     * @param quoteId - Identifier of the quote whose status should be fetched.
+     * @param options - Retry configuration.
+     * @param options.maxRetries - Maximum number of retries after the initial attempt.
+     * @param options.delayMsBetweenRetries - Delay in milliseconds between attempts.
+     */
+    getStatus(quoteId: string, options?: {
+        maxRetries?: number;
+        delayMsBetweenRetries?: number;
+    }): void;
+}
+//# sourceMappingURL=quotes-status-manager.d.mts.map

package/dist/quote-status-manager/quotes-status-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotes-status-manager.d.mts","sourceRoot":"","sources":["../../src/quote-status-manager/quotes-status-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,+BAA+B,EAAE,qBAAiB;AAa3E,OAAO,EAAE,sBAAsB,EAAE,qBAAiB;AAKlD,OAAO,EAAE,uBAAuB,EAA2B,oBAAgB;AAE3E;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;;IAqB7B;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,aAAa,EACb,UAAU,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,GACZ,EAAE;QACD,SAAS,EAAE,+BAA+B,CAAC;QAC3C,QAAQ,EAAE,cAAc,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,KAC7C,IAAI,CAAC;QACV,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;QAClD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;KACtD;IAsBD;;;;;;;;OAQG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAoCzD;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAgC5E;;;OAGG;IACH,OAAO,IAAI,IAAI;IAKf;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,IAAI;IAuCZ;;;;;;;;;;;OAWG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAIhC,GACA,IAAI;CA8YR"}