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

package/dist/quote-status-manager/quote-status-api-service.mjs

@@ -0,0 +1,237 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _QuoteStatusApiService_messenger, _QuoteStatusApiService_clientId, _QuoteStatusApiService_clientProduct, _QuoteStatusApiService_clientVersion, _QuoteStatusApiService_apiBaseUrl, _QuoteStatusApiService_onError;
+import { getClientHeaders } from "@metamask/bridge-controller";
+import { StructError } from "@metamask/superstruct";
+import { BridgeClientId } from "../types.mjs";
+import { getJwt } from "../utils/authentication.mjs";
+import { QuoteStatusBackendStatus, QuoteStatusUpdateRetryableBackendTypes, QuoteStatusFetchWithRetryOutcomeType } from "./constants.mjs";
+import { QuoteStatusGetError, QuoteStatusUpdateError } from "./errors.mjs";
+import { QuoteStatusGetWithRetryOutcome } from "./quote-status-get-with-retry-outcome.mjs";
+import { QuoteStatusUpdateWithRetryOutcome } from "./quote-status-update-with-retry-outcome.mjs";
+import { sleep } from "./utils.mjs";
+import { validateQuoteStatusGetResponse, validateQuoteStatusUpdateResponse } from "./validators.mjs";
+/**
+ * Service responsible for calling bridge quote status update APIs.
+ *
+ * It performs authentication, sends properly-scoped client headers, and validates
+ * error responses so callers can handle known update-status failures.
+ */
+export class QuoteStatusApiService {
+    /**
+     * Creates an API service for quote status update requests.
+     *
+     * @param options - Service dependencies and request configuration.
+     * @param options.messenger - Messenger used to retrieve the authentication token.
+     * @param options.clientId - Bridge client identifier used for request headers.
+     * @param options.clientProduct - Product name sent in client product headers.
+     * @param options.clientVersion - Optional client version sent in headers.
+     * @param options.apiBaseUrl - Base URL for the quote status API.
+     * @param options.onError - Optional callback for unexpected response-shape errors.
+     */
+    constructor({ messenger, clientId, clientProduct, clientVersion, apiBaseUrl, onError, }) {
+        _QuoteStatusApiService_messenger.set(this, void 0);
+        _QuoteStatusApiService_clientId.set(this, void 0);
+        _QuoteStatusApiService_clientProduct.set(this, void 0);
+        _QuoteStatusApiService_clientVersion.set(this, void 0);
+        _QuoteStatusApiService_apiBaseUrl.set(this, void 0);
+        _QuoteStatusApiService_onError.set(this, void 0);
+        __classPrivateFieldSet(this, _QuoteStatusApiService_messenger, messenger, "f");
+        __classPrivateFieldSet(this, _QuoteStatusApiService_clientId, clientId, "f");
+        __classPrivateFieldSet(this, _QuoteStatusApiService_clientProduct, clientProduct, "f");
+        __classPrivateFieldSet(this, _QuoteStatusApiService_clientVersion, clientVersion, "f");
+        __classPrivateFieldSet(this, _QuoteStatusApiService_apiBaseUrl, apiBaseUrl, "f");
+        __classPrivateFieldSet(this, _QuoteStatusApiService_onError, onError, "f");
+    }
+    /**
+     * Updates a quote status in the bridge quote-status API.
+     *
+     * The endpoint returns no payload on success (`2xx`) and a structured payload
+     * on non-`2xx` responses. This method returns `null` for successful updates and
+     * the validated error payload for unsuccessful updates.
+     *
+     * @param data - Request payload identifying quote and target status transition.
+     * @param data.quoteId - Unique quote identifier to update.
+     * @param data.srcTxHash - Source transaction hash associated with the quote.
+     * @param data.newStatus - Target quote status to persist.
+     * @param signal - Optional abort signal for canceling the request.
+     * @returns `null` for `2xx` responses, or a validated error response for non-`2xx`.
+     * @throws If the non-`2xx` response body does not match the expected schema.
+     */
+    async updateQuoteStatus(data, signal) {
+        const jwt = await getJwt(__classPrivateFieldGet(this, _QuoteStatusApiService_messenger, "f"));
+        // This method uses `globalThis.fetch` and reads the raw
+        // `Response` (including JSON on non-2xx). Wrappers like `handleFetch` that
+        // throw on non-2xx would prevent typed error handling in callers.
+        const res = await globalThis.fetch(`${__classPrivateFieldGet(this, _QuoteStatusApiService_apiBaseUrl, "f")}/quote/updateStatus`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-metamask-clientproduct': __classPrivateFieldGet(this, _QuoteStatusApiService_clientProduct, "f"),
+                ...(__classPrivateFieldGet(this, _QuoteStatusApiService_clientVersion, "f")
+                    ? { 'x-metamask-clientversion': __classPrivateFieldGet(this, _QuoteStatusApiService_clientVersion, "f") }
+                    : {}),
+                ...getClientHeaders({
+                    clientId: __classPrivateFieldGet(this, _QuoteStatusApiService_clientId, "f"),
+                    jwt,
+                }),
+            },
+            body: JSON.stringify(data),
+            signal,
+        });
+        if (res.ok) {
+            return null;
+        }
+        const responseData = await res.json();
+        try {
+            validateQuoteStatusUpdateResponse(responseData);
+            return responseData;
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _QuoteStatusApiService_onError, "f")?.call(this, new QuoteStatusUpdateError('unexpected response shape from quote/updateStatus', { quoteId: data.quoteId }));
+            throw error;
+        }
+    }
+    async getQuoteStatus(data, signal) {
+        const jwt = await getJwt(__classPrivateFieldGet(this, _QuoteStatusApiService_messenger, "f"));
+        // This method uses `globalThis.fetch` and reads the raw
+        // `Response` (including JSON on non-2xx). Wrappers like `handleFetch` that
+        // throw on non-2xx would prevent typed error handling in callers.
+        const res = await globalThis.fetch(`${__classPrivateFieldGet(this, _QuoteStatusApiService_apiBaseUrl, "f")}/getQuoteStatus?quoteId=${data.quoteId}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-metamask-clientproduct': __classPrivateFieldGet(this, _QuoteStatusApiService_clientProduct, "f"),
+                ...(__classPrivateFieldGet(this, _QuoteStatusApiService_clientVersion, "f")
+                    ? { 'x-metamask-clientversion': __classPrivateFieldGet(this, _QuoteStatusApiService_clientVersion, "f") }
+                    : {}),
+                ...getClientHeaders({
+                    clientId: __classPrivateFieldGet(this, _QuoteStatusApiService_clientId, "f"),
+                    jwt,
+                }),
+            },
+            signal,
+        });
+        if (!res.ok) {
+            // 5xx errors are transient (server-side); 4xx errors are client-side and
+            // non-retryable. The `retryable` flag lets `getQuoteStatusWithRetry`
+            // distinguish the two and only exit early for permanent failures.
+            const retryable = res.status >= 500;
+            const error = new QuoteStatusGetError(`request error to getQuoteStatus [${res.status}: ${res.statusText}]`, { quoteId: data.quoteId }, retryable);
+            __classPrivateFieldGet(this, _QuoteStatusApiService_onError, "f")?.call(this, error);
+            throw error;
+        }
+        const responseData = await res.json();
+        try {
+            validateQuoteStatusGetResponse(responseData);
+            return responseData;
+        }
+        catch (error) {
+            if (error instanceof StructError) {
+                const validationFailures = [];
+                for (const { path } of error.failures()) {
+                    const aggregatorId = responseData?.submittedTx?.bridge ??
+                        'unknown';
+                    const pathString = path?.join('.') || 'unknown';
+                    validationFailures.push([aggregatorId, pathString].join('|'));
+                }
+                const validationError = new QuoteStatusGetError('unexpected response shape from getQuoteStatus', { quoteId: data.quoteId, validationFailures });
+                __classPrivateFieldGet(this, _QuoteStatusApiService_onError, "f")?.call(this, validationError);
+                throw validationError;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Updates a quote status, retrying on transient backend failures.
+     *
+     * Wraps {@link updateQuoteStatus} in a bounded retry loop. A request is only
+     * retried when the backend returns an error whose type is in
+     * {@link QuoteStatusUpdateRetryableBackendTypes}; any other error response
+     * resolves immediately as non-retryable. Retries are spaced by
+     * `options.delayMsBetweenRetries`, and both the abort signal and the optional
+     * `options.retry` predicate are checked before each attempt so an
+     * in-flight or pending retry can be cancelled (e.g. when the entry's status
+     * changed while sleeping between retries).
+     *
+     * @param data - Request payload identifying the quote and target transition.
+     * @param data.quoteId - Unique quote identifier to update.
+     * @param data.srcTxHash - Source transaction hash associated with the quote.
+     * @param data.newStatus - Target quote status to persist.
+     * @param options - Retry configuration.
+     * @param options.maxRetries - Maximum number of retries after the initial attempt.
+     * @param options.delayMsBetweenRetries - Delay in milliseconds between attempts.
+     * @param options.retry - Optional predicate checked before each attempt;
+     * when it returns `false` the loop stops early and resolves as `Interrupted`.
+     * @param signal - Optional abort signal for canceling the request and its retries.
+     * @returns An outcome describing how the update resolved:
+     * `Accepted` when the backend accepted the update, `NonRetryable` for a
+     * non-retryable error response, `Interrupted` when aborted, or
+     * `RetryableExhausted` when all retries were used up on retryable errors.
+     * @throws If a request rejects for a reason other than the abort signal (e.g.
+     * an unexpected response shape from {@link updateQuoteStatus}).
+     */
+    async updateQuoteStatusWithRetry(data, options, signal) {
+        for (let attempt = 0; attempt <= options.maxRetries; attempt += 1) {
+            if (attempt > 0) {
+                await sleep(options.delayMsBetweenRetries);
+            }
+            if (signal?.aborted || options.retry?.() === false) {
+                return new QuoteStatusUpdateWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Interrupted);
+            }
+            try {
+                const response = await this.updateQuoteStatus(data, signal);
+                if (response === null) {
+                    return new QuoteStatusUpdateWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Accepted);
+                }
+                if (!QuoteStatusUpdateRetryableBackendTypes.includes(response.type)) {
+                    return new QuoteStatusUpdateWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.NonRetryable, response);
+                }
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    return new QuoteStatusUpdateWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Interrupted);
+                }
+                throw error;
+            }
+        }
+        return new QuoteStatusUpdateWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.RetryableExhausted);
+    }
+    async getQuoteStatusWithRetry(data, options, signal) {
+        for (let attempt = 0; attempt <= options.maxRetries; attempt += 1) {
+            if (attempt > 0) {
+                await sleep(options.delayMsBetweenRetries);
+            }
+            if (signal?.aborted) {
+                return new QuoteStatusGetWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Interrupted);
+            }
+            try {
+                const response = await this.getQuoteStatus(data, signal);
+                return new QuoteStatusGetWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Accepted, response);
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    return new QuoteStatusGetWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.Interrupted);
+                }
+                // Only short-circuit for non-retryable errors (e.g. 4xx, validation
+                // failures). Retryable errors (e.g. 5xx) fall through so the loop can
+                // attempt the next retry instead of returning NonRetryable immediately.
+                if (error instanceof QuoteStatusGetError && !error.retryable) {
+                    return new QuoteStatusGetWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.NonRetryable, undefined, error);
+                }
+            }
+        }
+        return new QuoteStatusGetWithRetryOutcome(QuoteStatusFetchWithRetryOutcomeType.RetryableExhausted);
+    }
+}
+_QuoteStatusApiService_messenger = new WeakMap(), _QuoteStatusApiService_clientId = new WeakMap(), _QuoteStatusApiService_clientProduct = new WeakMap(), _QuoteStatusApiService_clientVersion = new WeakMap(), _QuoteStatusApiService_apiBaseUrl = new WeakMap(), _QuoteStatusApiService_onError = new WeakMap();
+//# sourceMappingURL=quote-status-api-service.mjs.map

package/dist/quote-status-manager/quote-status-api-service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote-status-api-service.mjs","sourceRoot":"","sources":["../../src/quote-status-manager/quote-status-api-service.ts"],"names":[],"mappings":"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","sourcesContent":["import { getClientHeaders } from '@metamask/bridge-controller';\nimport { StructError } from '@metamask/superstruct';\n\nimport { BridgeClientId, BridgeStatusControllerMessenger } from '../types';\nimport { getJwt } from '../utils/authentication';\nimport {\n  QuoteStatusBackendStatus,\n  QuoteStatusUpdateRetryableBackendTypes,\n  QuoteStatusFetchWithRetryOutcomeType,\n} from './constants';\nimport { QuoteStatusGetError, QuoteStatusUpdateError } from './errors';\nimport { QuoteStatusGetWithRetryOutcome } from './quote-status-get-with-retry-outcome';\nimport { QuoteStatusUpdateWithRetryOutcome } from './quote-status-update-with-retry-outcome';\nimport {\n  QuoteStatusApiServiceOptions,\n  QuoteStatusGetResponse,\n  QuoteStatusUpdateResponse,\n} from './types';\nimport { sleep } from './utils';\nimport {\n  validateQuoteStatusGetResponse,\n  validateQuoteStatusUpdateResponse,\n} from './validators';\n\n/**\n * Service responsible for calling bridge quote status update APIs.\n *\n * It performs authentication, sends properly-scoped client headers, and validates\n * error responses so callers can handle known update-status failures.\n */\nexport class QuoteStatusApiService {\n  readonly #messenger: BridgeStatusControllerMessenger;\n\n  readonly #clientId: BridgeClientId;\n\n  readonly #clientProduct: string;\n\n  readonly #clientVersion: string | undefined;\n\n  readonly #apiBaseUrl: string;\n\n  readonly #onError: ((error: QuoteStatusUpdateError) => void) | undefined;\n\n  /**\n   * Creates an API service for quote status update requests.\n   *\n   * @param options - Service dependencies and request configuration.\n   * @param options.messenger - Messenger used to retrieve the authentication token.\n   * @param options.clientId - Bridge client identifier used for request headers.\n   * @param options.clientProduct - Product name sent in client product headers.\n   * @param options.clientVersion - Optional client version sent in headers.\n   * @param options.apiBaseUrl - Base URL for the quote status API.\n   * @param options.onError - Optional callback for unexpected response-shape errors.\n   */\n  constructor({\n    messenger,\n    clientId,\n    clientProduct,\n    clientVersion,\n    apiBaseUrl,\n    onError,\n  }: QuoteStatusApiServiceOptions) {\n    this.#messenger = messenger;\n    this.#clientId = clientId;\n    this.#clientProduct = clientProduct;\n    this.#clientVersion = clientVersion;\n    this.#apiBaseUrl = apiBaseUrl;\n    this.#onError = onError;\n  }\n\n  /**\n   * Updates a quote status in the bridge quote-status API.\n   *\n   * The endpoint returns no payload on success (`2xx`) and a structured payload\n   * on non-`2xx` responses. This method returns `null` for successful updates and\n   * the validated error payload for unsuccessful updates.\n   *\n   * @param data - Request payload identifying quote and target status transition.\n   * @param data.quoteId - Unique quote identifier to update.\n   * @param data.srcTxHash - Source transaction hash associated with the quote.\n   * @param data.newStatus - Target quote status to persist.\n   * @param signal - Optional abort signal for canceling the request.\n   * @returns `null` for `2xx` responses, or a validated error response for non-`2xx`.\n   * @throws If the non-`2xx` response body does not match the expected schema.\n   */\n  async updateQuoteStatus(\n    data: {\n      quoteId: string;\n      srcTxHash: string;\n      newStatus: QuoteStatusBackendStatus;\n    },\n    signal?: AbortSignal,\n  ): Promise<QuoteStatusUpdateResponse | null> {\n    const jwt = await getJwt(this.#messenger);\n\n    // This method uses `globalThis.fetch` and reads the raw\n    // `Response` (including JSON on non-2xx). Wrappers like `handleFetch` that\n    // throw on non-2xx would prevent typed error handling in callers.\n    const res = await globalThis.fetch(\n      `${this.#apiBaseUrl}/quote/updateStatus`,\n      {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'x-metamask-clientproduct': this.#clientProduct,\n          ...(this.#clientVersion\n            ? { 'x-metamask-clientversion': this.#clientVersion }\n            : {}),\n          ...getClientHeaders({\n            clientId: this.#clientId,\n            jwt,\n          }),\n        },\n        body: JSON.stringify(data),\n        signal,\n      },\n    );\n\n    if (res.ok) {\n      return null;\n    }\n\n    const responseData = await res.json();\n\n    try {\n      validateQuoteStatusUpdateResponse(responseData);\n      return responseData;\n    } catch (error) {\n      this.#onError?.(\n        new QuoteStatusUpdateError(\n          'unexpected response shape from quote/updateStatus',\n          { quoteId: data.quoteId },\n        ),\n      );\n      throw error;\n    }\n  }\n\n  async getQuoteStatus(\n    data: {\n      quoteId: string;\n    },\n    signal?: AbortSignal,\n  ): Promise<QuoteStatusGetResponse> {\n    const jwt = await getJwt(this.#messenger);\n\n    // This method uses `globalThis.fetch` and reads the raw\n    // `Response` (including JSON on non-2xx). Wrappers like `handleFetch` that\n    // throw on non-2xx would prevent typed error handling in callers.\n    const res = await globalThis.fetch(\n      `${this.#apiBaseUrl}/getQuoteStatus?quoteId=${data.quoteId}`,\n      {\n        method: 'GET',\n        headers: {\n          'Content-Type': 'application/json',\n          'x-metamask-clientproduct': this.#clientProduct,\n          ...(this.#clientVersion\n            ? { 'x-metamask-clientversion': this.#clientVersion }\n            : {}),\n          ...getClientHeaders({\n            clientId: this.#clientId,\n            jwt,\n          }),\n        },\n        signal,\n      },\n    );\n\n    if (!res.ok) {\n      // 5xx errors are transient (server-side); 4xx errors are client-side and\n      // non-retryable. The `retryable` flag lets `getQuoteStatusWithRetry`\n      // distinguish the two and only exit early for permanent failures.\n      const retryable = res.status >= 500;\n      const error = new QuoteStatusGetError(\n        `request error to getQuoteStatus [${res.status}: ${res.statusText}]`,\n        { quoteId: data.quoteId },\n        retryable,\n      );\n      this.#onError?.(error);\n      throw error;\n    }\n\n    const responseData = await res.json();\n\n    try {\n      validateQuoteStatusGetResponse(responseData);\n      return responseData;\n    } catch (error) {\n      if (error instanceof StructError) {\n        const validationFailures = [];\n\n        for (const { path } of error.failures()) {\n          const aggregatorId =\n            (responseData as QuoteStatusGetResponse)?.submittedTx?.bridge ??\n            ('unknown' as string);\n          const pathString = path?.join('.') || 'unknown';\n          validationFailures.push([aggregatorId, pathString].join('|'));\n        }\n\n        const validationError = new QuoteStatusGetError(\n          'unexpected response shape from getQuoteStatus',\n          { quoteId: data.quoteId, validationFailures },\n        );\n\n        this.#onError?.(validationError);\n\n        throw validationError;\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Updates a quote status, retrying on transient backend failures.\n   *\n   * Wraps {@link updateQuoteStatus} in a bounded retry loop. A request is only\n   * retried when the backend returns an error whose type is in\n   * {@link QuoteStatusUpdateRetryableBackendTypes}; any other error response\n   * resolves immediately as non-retryable. Retries are spaced by\n   * `options.delayMsBetweenRetries`, and both the abort signal and the optional\n   * `options.retry` predicate are checked before each attempt so an\n   * in-flight or pending retry can be cancelled (e.g. when the entry's status\n   * changed while sleeping between retries).\n   *\n   * @param data - Request payload identifying the quote and target transition.\n   * @param data.quoteId - Unique quote identifier to update.\n   * @param data.srcTxHash - Source transaction hash associated with the quote.\n   * @param data.newStatus - Target quote status to persist.\n   * @param options - Retry configuration.\n   * @param options.maxRetries - Maximum number of retries after the initial attempt.\n   * @param options.delayMsBetweenRetries - Delay in milliseconds between attempts.\n   * @param options.retry - Optional predicate checked before each attempt;\n   * when it returns `false` the loop stops early and resolves as `Interrupted`.\n   * @param signal - Optional abort signal for canceling the request and its retries.\n   * @returns An outcome describing how the update resolved:\n   * `Accepted` when the backend accepted the update, `NonRetryable` for a\n   * non-retryable error response, `Interrupted` when aborted, or\n   * `RetryableExhausted` when all retries were used up on retryable errors.\n   * @throws If a request rejects for a reason other than the abort signal (e.g.\n   * an unexpected response shape from {@link updateQuoteStatus}).\n   */\n  async updateQuoteStatusWithRetry(\n    data: {\n      quoteId: string;\n      srcTxHash: string;\n      newStatus: QuoteStatusBackendStatus;\n    },\n    options: {\n      maxRetries: number;\n      delayMsBetweenRetries: number;\n      retry?: () => boolean;\n    },\n    signal?: AbortSignal,\n  ): Promise<QuoteStatusUpdateWithRetryOutcome> {\n    for (let attempt = 0; attempt <= options.maxRetries; attempt += 1) {\n      if (attempt > 0) {\n        await sleep(options.delayMsBetweenRetries);\n      }\n\n      if (signal?.aborted || options.retry?.() === false) {\n        return new QuoteStatusUpdateWithRetryOutcome(\n          QuoteStatusFetchWithRetryOutcomeType.Interrupted,\n        );\n      }\n\n      try {\n        const response = await this.updateQuoteStatus(data, signal);\n\n        if (response === null) {\n          return new QuoteStatusUpdateWithRetryOutcome(\n            QuoteStatusFetchWithRetryOutcomeType.Accepted,\n          );\n        }\n\n        if (!QuoteStatusUpdateRetryableBackendTypes.includes(response.type)) {\n          return new QuoteStatusUpdateWithRetryOutcome(\n            QuoteStatusFetchWithRetryOutcomeType.NonRetryable,\n            response,\n          );\n        }\n      } catch (error) {\n        if (signal?.aborted) {\n          return new QuoteStatusUpdateWithRetryOutcome(\n            QuoteStatusFetchWithRetryOutcomeType.Interrupted,\n          );\n        }\n\n        throw error;\n      }\n    }\n\n    return new QuoteStatusUpdateWithRetryOutcome(\n      QuoteStatusFetchWithRetryOutcomeType.RetryableExhausted,\n    );\n  }\n\n  async getQuoteStatusWithRetry(\n    data: {\n      quoteId: string;\n    },\n    options: {\n      maxRetries: number;\n      delayMsBetweenRetries: number;\n    },\n    signal?: AbortSignal,\n  ): Promise<QuoteStatusGetWithRetryOutcome> {\n    for (let attempt = 0; attempt <= options.maxRetries; attempt += 1) {\n      if (attempt > 0) {\n        await sleep(options.delayMsBetweenRetries);\n      }\n\n      if (signal?.aborted) {\n        return new QuoteStatusGetWithRetryOutcome(\n          QuoteStatusFetchWithRetryOutcomeType.Interrupted,\n        );\n      }\n\n      try {\n        const response = await this.getQuoteStatus(data, signal);\n\n        return new QuoteStatusGetWithRetryOutcome(\n          QuoteStatusFetchWithRetryOutcomeType.Accepted,\n          response,\n        );\n      } catch (error) {\n        if (signal?.aborted) {\n          return new QuoteStatusGetWithRetryOutcome(\n            QuoteStatusFetchWithRetryOutcomeType.Interrupted,\n          );\n        }\n\n        // Only short-circuit for non-retryable errors (e.g. 4xx, validation\n        // failures). Retryable errors (e.g. 5xx) fall through so the loop can\n        // attempt the next retry instead of returning NonRetryable immediately.\n        if (error instanceof QuoteStatusGetError && !error.retryable) {\n          return new QuoteStatusGetWithRetryOutcome(\n            QuoteStatusFetchWithRetryOutcomeType.NonRetryable,\n            undefined,\n            error,\n          );\n        }\n      }\n    }\n\n    return new QuoteStatusGetWithRetryOutcome(\n      QuoteStatusFetchWithRetryOutcomeType.RetryableExhausted,\n    );\n  }\n}\n"]}

package/dist/quote-status-manager/quote-status-entry-store.cjs

@@ -0,0 +1,271 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _QuoteStatusEntryStore_instances, _QuoteStatusEntryStore_items, _QuoteStatusEntryStore_entryTtlMs, _QuoteStatusEntryStore_onPersistUpdates, _QuoteStatusEntryStore_subscribeToStatusUpdates, _QuoteStatusEntryStore_persistToState;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuoteStatusEntryStore = void 0;
+const constants_1 = require("./constants.cjs");
+const quote_status_state_fsm_1 = require("./quote-status-state-fsm.cjs");
+/**
+ * In-memory store for quote status update entries.
+ *
+ * The store deduplicates entries by key, tracks timestamps used for retries and
+ * TTL eviction, and persists a cloned snapshot on each mutating operation.
+ */
+class QuoteStatusEntryStore {
+    /**
+     * Creates a deterministic key for persisted quote status entries.
+     *
+     * @param entry - Entry identity fields.
+     * @param entry.quoteId - Quote identifier.
+     * @param entry.srcTxHash - Source transaction hash.
+     * @returns Stable key in `${quoteId}:${srcTxHash}` format.
+     */
+    static hash(entry) {
+        return `${entry.quoteId}:${entry.srcTxHash}`;
+    }
+    /**
+     * Creates a quote status entry store.
+     *
+     * @param options - Store dependencies and retention configuration.
+     * @param options.onPersistUpdates - Callback invoked with cloned snapshot updates.
+     * @param options.entryTtlMs - Entry time-to-live in milliseconds.
+     * @param options.initial - Optional initial persisted entries used to seed the store.
+     */
+    constructor({ onPersistUpdates, entryTtlMs, initial, }) {
+        _QuoteStatusEntryStore_instances.add(this);
+        _QuoteStatusEntryStore_items.set(this, void 0);
+        _QuoteStatusEntryStore_entryTtlMs.set(this, void 0);
+        _QuoteStatusEntryStore_onPersistUpdates.set(this, void 0);
+        __classPrivateFieldSet(this, _QuoteStatusEntryStore_onPersistUpdates, onPersistUpdates, "f");
+        __classPrivateFieldSet(this, _QuoteStatusEntryStore_entryTtlMs, entryTtlMs, "f");
+        __classPrivateFieldSet(this, _QuoteStatusEntryStore_items, new Map(Object.entries(initial ?? {}).map(([key, entry]) => {
+            const quoteStatusStateFsm = new quote_status_state_fsm_1.QuoteStatusStateFsm(entry.status);
+            return [
+                key,
+                // Entries from `initialDeferredUpdates` come from Immer-managed controller
+                // state, which deep-freezes all nested objects. Cloning each entry here
+                // ensures the in-memory queue holds mutable objects so that mutations
+                // (e.g. updating `status` or `lastAttemptAt`) work correctly without
+                // throwing a "read only property" error.
+                { ...entry, status: quoteStatusStateFsm },
+            ];
+        })), "f");
+        // Subscribe each seeded FSM after the map (and `#onPersistUpdates`) are set
+        // so that any later state transition persists the updated snapshot.
+        for (const entry of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values()) {
+            __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_subscribeToStatusUpdates).call(this, entry);
+        }
+    }
+    /**
+     * Adds a new entry when the key is not already present.
+     *
+     * If an entry already exists, only a missing `txMetaId` is backfilled to avoid
+     * resetting timestamps and creating duplicate submission updates.
+     *
+     * @param key - Unique map key for the entry.
+     * @param value - Entry payload without internal timestamps.
+     * @param value.quoteId - Quote identifier.
+     * @param value.srcTxHash - Source transaction hash.
+     * @param value.status - Latest quote status.
+     * @param value.txMetaId - Optional transaction metadata identifier.
+     * @returns The tracked entry (the existing one when the key is already
+     * present, otherwise the newly created entry).
+     */
+    put(key, value) {
+        // If an entry for this key is already in the queue
+        // do not overwrite it. Re-enqueueing would reset state and
+        // could cause duplicate SUBMITTED events.
+        const existing = __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").get(key);
+        if (existing) {
+            if (!existing.txMetaId && value.txMetaId) {
+                existing.txMetaId = value.txMetaId;
+                __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_persistToState).call(this);
+            }
+            return existing;
+        }
+        const now = Date.now();
+        const entry = {
+            ...value,
+            createdAt: now,
+            lastAttemptAt: now,
+        };
+        __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").set(key, entry);
+        __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_subscribeToStatusUpdates).call(this, entry);
+        __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_persistToState).call(this);
+        return entry;
+    }
+    /**
+     * Returns an iterator over all tracked entries.
+     *
+     * Stale entries are transitioned to {@link QuoteStatusState.Expired} first (but
+     * kept in the store), so the iterator reflects their up-to-date terminal state.
+     *
+     * @returns An iterator over the currently tracked entries.
+     */
+    values() {
+        this.expireStaleEntries();
+        return __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values();
+    }
+    /**
+     * Returns every tracked entry matching the provided quote identifier.
+     *
+     * Stale entries are transitioned to {@link QuoteStatusState.Expired} first so
+     * callers observe their up-to-date terminal state.
+     *
+     * @param quoteId - Quote identifier to match.
+     * @returns The matching entries (empty when none exist).
+     */
+    getByQuoteId(quoteId) {
+        this.expireStaleEntries();
+        const matches = [];
+        for (const entry of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values()) {
+            if (entry.quoteId === quoteId) {
+                matches.push(entry);
+            }
+        }
+        return matches;
+    }
+    /**
+     * Number of entries currently tracked by the store.
+     *
+     * Note that this includes terminal entries (`Completed`/`Expired`), which are
+     * retained rather than evicted; call {@link expireStaleEntries} (or
+     * {@link values}) first when an up-to-date view of entry states is required.
+     *
+     * @returns The count of tracked entries.
+     */
+    get size() {
+        return __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").size;
+    }
+    /**
+     * Looks up an entry by its transaction metadata identifier.
+     *
+     * If the matching entry has exceeded its TTL it is transitioned to
+     * {@link QuoteStatusState.Expired} (but kept) before being returned.
+     *
+     * @param txMetaId - Transaction metadata identifier to search for.
+     * @returns The matching entry, or `null` if none exists.
+     */
+    getByTxMetaId(txMetaId) {
+        for (const entry of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values()) {
+            if (entry.txMetaId === txMetaId) {
+                this.expireEntryIfStale(entry);
+                return entry;
+            }
+        }
+        return null;
+    }
+    /**
+     * Retrieves an entry by key.
+     *
+     * If the entry has exceeded its TTL it is transitioned to
+     * {@link QuoteStatusState.Expired} (but kept) before being returned.
+     *
+     * @param key - Unique map key for the entry.
+     * @returns The matching entry, or `null` if absent.
+     */
+    get(key) {
+        const entry = __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").get(key);
+        if (!entry) {
+            return null;
+        }
+        this.expireEntryIfStale(entry);
+        return entry;
+    }
+    /**
+     * Persists the current snapshot after an in-place mutation of a tracked entry.
+     *
+     * Used when fields such as `lastAttemptAt` are mutated directly on an entry
+     * the caller already holds. No-ops if the entry is no longer tracked (e.g. the
+     * store was cleared in the meantime), so persistence only reflects live entries.
+     *
+     * @param entry - The mutated entry to persist.
+     */
+    update(entry) {
+        if (!__classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").has(QuoteStatusEntryStore.hash(entry))) {
+            return;
+        }
+        __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_persistToState).call(this);
+    }
+    /**
+     * Transitions every stale entry to {@link QuoteStatusState.Expired}, keeping it
+     * in the store.
+     *
+     * Expired entries are retained so that later interactions with the same quote
+     * (e.g. a duplicate `reportSubmitted`) can be recognized and rejected. Each
+     * transition persists the updated snapshot via the entry's FSM subscription;
+     * already-terminal entries cannot transition and are left untouched.
+     */
+    expireStaleEntries() {
+        for (const entry of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values()) {
+            if (this.entryHasExpired(entry)) {
+                entry.status.transitionTo(constants_1.QuoteStatusState.Expired);
+            }
+        }
+    }
+    /**
+     * Determines whether an entry has outlived the configured TTL.
+     *
+     * Expiry is measured from the entry's `createdAt` timestamp, not its last
+     * attempt, so an entry's total lifetime is bounded regardless of retries.
+     *
+     * @param entry - Entry to check.
+     * @returns `true` if the entry's age exceeds the TTL.
+     */
+    entryHasExpired(entry) {
+        const now = Date.now();
+        return now - entry.createdAt > __classPrivateFieldGet(this, _QuoteStatusEntryStore_entryTtlMs, "f");
+    }
+    /**
+     * Transitions an entry to {@link QuoteStatusState.Expired} (keeping it) if it
+     * has exceeded its TTL.
+     *
+     * The transition persists the updated snapshot via the entry's FSM
+     * subscription. Already-terminal entries cannot transition and are left
+     * untouched.
+     *
+     * @param entry - Entry to check and possibly expire.
+     * @returns `true` if the entry was stale, otherwise `false`.
+     */
+    expireEntryIfStale(entry) {
+        if (this.entryHasExpired(entry)) {
+            entry.status.transitionTo(constants_1.QuoteStatusState.Expired);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Removes every entry from the store.
+     *
+     * Detaches each entry's FSM listeners before clearing to prevent leaks and
+     * stale persist callbacks. Does not emit a persistence update; callers are
+     * expected to use this during teardown.
+     */
+    clear() {
+        for (const entry of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").values()) {
+            entry.status.removeAllListeners();
+        }
+        __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f").clear();
+    }
+}
+exports.QuoteStatusEntryStore = QuoteStatusEntryStore;
+_QuoteStatusEntryStore_items = new WeakMap(), _QuoteStatusEntryStore_entryTtlMs = new WeakMap(), _QuoteStatusEntryStore_onPersistUpdates = new WeakMap(), _QuoteStatusEntryStore_instances = new WeakSet(), _QuoteStatusEntryStore_subscribeToStatusUpdates = function _QuoteStatusEntryStore_subscribeToStatusUpdates(entry) {
+    entry.status.onStateUpdate(() => __classPrivateFieldGet(this, _QuoteStatusEntryStore_instances, "m", _QuoteStatusEntryStore_persistToState).call(this));
+}, _QuoteStatusEntryStore_persistToState = function _QuoteStatusEntryStore_persistToState() {
+    const cloned = {};
+    for (const [key, entry] of __classPrivateFieldGet(this, _QuoteStatusEntryStore_items, "f")) {
+        cloned[key] = { ...entry, status: entry.status.state };
+    }
+    __classPrivateFieldGet(this, _QuoteStatusEntryStore_onPersistUpdates, "f").call(this, cloned);
+};
+//# sourceMappingURL=quote-status-entry-store.cjs.map

package/dist/quote-status-manager/quote-status-entry-store.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote-status-entry-store.cjs","sourceRoot":"","sources":["../../src/quote-status-manager/quote-status-entry-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { QuoteStatusState } from './constants';\nimport { QuoteStatusStateFsm } from './quote-status-state-fsm';\nimport {\n  QuoteStatusEntryStoreOptions,\n  QuoteStatusPersistEntry,\n  QuoteStatusRuntimeEntry,\n} from './types';\n\n/**\n * In-memory store for quote status update entries.\n *\n * The store deduplicates entries by key, tracks timestamps used for retries and\n * TTL eviction, and persists a cloned snapshot on each mutating operation.\n */\nexport class QuoteStatusEntryStore {\n  readonly #items: Map<string, QuoteStatusRuntimeEntry>;\n\n  readonly #entryTtlMs: number;\n\n  /**\n   * Creates a deterministic key for persisted quote status entries.\n   *\n   * @param entry - Entry identity fields.\n   * @param entry.quoteId - Quote identifier.\n   * @param entry.srcTxHash - Source transaction hash.\n   * @returns Stable key in `${quoteId}:${srcTxHash}` format.\n   */\n  static hash(\n    entry: Pick<QuoteStatusPersistEntry, 'quoteId' | 'srcTxHash'>,\n  ): string {\n    return `${entry.quoteId}:${entry.srcTxHash}`;\n  }\n\n  readonly #onPersistUpdates: (\n    updates: Record<string, QuoteStatusPersistEntry>,\n  ) => void;\n\n  /**\n   * Creates a quote status entry store.\n   *\n   * @param options - Store dependencies and retention configuration.\n   * @param options.onPersistUpdates - Callback invoked with cloned snapshot updates.\n   * @param options.entryTtlMs - Entry time-to-live in milliseconds.\n   * @param options.initial - Optional initial persisted entries used to seed the store.\n   */\n  constructor({\n    onPersistUpdates,\n    entryTtlMs,\n    initial,\n  }: QuoteStatusEntryStoreOptions) {\n    this.#onPersistUpdates = onPersistUpdates;\n    this.#entryTtlMs = entryTtlMs;\n    this.#items = new Map(\n      Object.entries(initial ?? {}).map(([key, entry]) => {\n        const quoteStatusStateFsm = new QuoteStatusStateFsm(entry.status);\n\n        return [\n          key,\n          // Entries from `initialDeferredUpdates` come from Immer-managed controller\n          // state, which deep-freezes all nested objects. Cloning each entry here\n          // ensures the in-memory queue holds mutable objects so that mutations\n          // (e.g. updating `status` or `lastAttemptAt`) work correctly without\n          // throwing a \"read only property\" error.\n          { ...entry, status: quoteStatusStateFsm },\n        ];\n      }),\n    );\n\n    // Subscribe each seeded FSM after the map (and `#onPersistUpdates`) are set\n    // so that any later state transition persists the updated snapshot.\n    for (const entry of this.#items.values()) {\n      this.#subscribeToStatusUpdates(entry);\n    }\n  }\n\n  /**\n   * Subscribes the entry's FSM so that every state transition persists the\n   * current snapshot. Kept in one place so seeded and runtime-added entries\n   * behave identically.\n   *\n   * @param entry - Entry whose FSM should trigger persistence on transition.\n   */\n  #subscribeToStatusUpdates(entry: QuoteStatusRuntimeEntry): void {\n    entry.status.onStateUpdate(() => this.#persistToState());\n  }\n\n  /**\n   * Adds a new entry when the key is not already present.\n   *\n   * If an entry already exists, only a missing `txMetaId` is backfilled to avoid\n   * resetting timestamps and creating duplicate submission updates.\n   *\n   * @param key - Unique map key for the entry.\n   * @param value - Entry payload without internal timestamps.\n   * @param value.quoteId - Quote identifier.\n   * @param value.srcTxHash - Source transaction hash.\n   * @param value.status - Latest quote status.\n   * @param value.txMetaId - Optional transaction metadata identifier.\n   * @returns The tracked entry (the existing one when the key is already\n   * present, otherwise the newly created entry).\n   */\n  put(\n    key: string,\n    value: Omit<QuoteStatusRuntimeEntry, 'createdAt' | 'lastAttemptAt'>,\n  ): QuoteStatusRuntimeEntry {\n    // If an entry for this key is already in the queue\n    // do not overwrite it. Re-enqueueing would reset state and\n    // could cause duplicate SUBMITTED events.\n    const existing = this.#items.get(key);\n    if (existing) {\n      if (!existing.txMetaId && value.txMetaId) {\n        existing.txMetaId = value.txMetaId;\n        this.#persistToState();\n      }\n      return existing;\n    }\n\n    const now = Date.now();\n    const entry: QuoteStatusRuntimeEntry = {\n      ...value,\n      createdAt: now,\n      lastAttemptAt: now,\n    };\n    this.#items.set(key, entry);\n    this.#subscribeToStatusUpdates(entry);\n    this.#persistToState();\n    return entry;\n  }\n\n  /**\n   * Returns an iterator over all tracked entries.\n   *\n   * Stale entries are transitioned to {@link QuoteStatusState.Expired} first (but\n   * kept in the store), so the iterator reflects their up-to-date terminal state.\n   *\n   * @returns An iterator over the currently tracked entries.\n   */\n  values(): IterableIterator<QuoteStatusRuntimeEntry> {\n    this.expireStaleEntries();\n    return this.#items.values();\n  }\n\n  /**\n   * Returns every tracked entry matching the provided quote identifier.\n   *\n   * Stale entries are transitioned to {@link QuoteStatusState.Expired} first so\n   * callers observe their up-to-date terminal state.\n   *\n   * @param quoteId - Quote identifier to match.\n   * @returns The matching entries (empty when none exist).\n   */\n  getByQuoteId(quoteId: string): QuoteStatusRuntimeEntry[] {\n    this.expireStaleEntries();\n\n    const matches: QuoteStatusRuntimeEntry[] = [];\n    for (const entry of this.#items.values()) {\n      if (entry.quoteId === quoteId) {\n        matches.push(entry);\n      }\n    }\n\n    return matches;\n  }\n\n  /**\n   * Number of entries currently tracked by the store.\n   *\n   * Note that this includes terminal entries (`Completed`/`Expired`), which are\n   * retained rather than evicted; call {@link expireStaleEntries} (or\n   * {@link values}) first when an up-to-date view of entry states is required.\n   *\n   * @returns The count of tracked entries.\n   */\n  get size(): number {\n    return this.#items.size;\n  }\n\n  /**\n   * Looks up an entry by its transaction metadata identifier.\n   *\n   * If the matching entry has exceeded its TTL it is transitioned to\n   * {@link QuoteStatusState.Expired} (but kept) before being returned.\n   *\n   * @param txMetaId - Transaction metadata identifier to search for.\n   * @returns The matching entry, or `null` if none exists.\n   */\n  getByTxMetaId(txMetaId: string): QuoteStatusRuntimeEntry | null {\n    for (const entry of this.#items.values()) {\n      if (entry.txMetaId === txMetaId) {\n        this.expireEntryIfStale(entry);\n        return entry;\n      }\n    }\n\n    return null;\n  }\n\n  /**\n   * Retrieves an entry by key.\n   *\n   * If the entry has exceeded its TTL it is transitioned to\n   * {@link QuoteStatusState.Expired} (but kept) before being returned.\n   *\n   * @param key - Unique map key for the entry.\n   * @returns The matching entry, or `null` if absent.\n   */\n  get(key: string): QuoteStatusRuntimeEntry | null {\n    const entry = this.#items.get(key);\n    if (!entry) {\n      return null;\n    }\n\n    this.expireEntryIfStale(entry);\n    return entry;\n  }\n\n  /**\n   * Persists the current snapshot after an in-place mutation of a tracked entry.\n   *\n   * Used when fields such as `lastAttemptAt` are mutated directly on an entry\n   * the caller already holds. No-ops if the entry is no longer tracked (e.g. the\n   * store was cleared in the meantime), so persistence only reflects live entries.\n   *\n   * @param entry - The mutated entry to persist.\n   */\n  update(entry: QuoteStatusRuntimeEntry): void {\n    if (!this.#items.has(QuoteStatusEntryStore.hash(entry))) {\n      return;\n    }\n\n    this.#persistToState();\n  }\n\n  /**\n   * Emits a cloned, serializable snapshot of all tracked entries via the\n   * `onPersistUpdates` callback.\n   *\n   * Each entry's FSM is flattened to its plain `status` value so the snapshot\n   * contains no class instances and is safe to store in controller state.\n   */\n  #persistToState(): void {\n    const cloned: Record<string, QuoteStatusPersistEntry> = {};\n    for (const [key, entry] of this.#items) {\n      cloned[key] = { ...entry, status: entry.status.state };\n    }\n    this.#onPersistUpdates(cloned);\n  }\n\n  /**\n   * Transitions every stale entry to {@link QuoteStatusState.Expired}, keeping it\n   * in the store.\n   *\n   * Expired entries are retained so that later interactions with the same quote\n   * (e.g. a duplicate `reportSubmitted`) can be recognized and rejected. Each\n   * transition persists the updated snapshot via the entry's FSM subscription;\n   * already-terminal entries cannot transition and are left untouched.\n   */\n  expireStaleEntries(): void {\n    for (const entry of this.#items.values()) {\n      if (this.entryHasExpired(entry)) {\n        entry.status.transitionTo(QuoteStatusState.Expired);\n      }\n    }\n  }\n\n  /**\n   * Determines whether an entry has outlived the configured TTL.\n   *\n   * Expiry is measured from the entry's `createdAt` timestamp, not its last\n   * attempt, so an entry's total lifetime is bounded regardless of retries.\n   *\n   * @param entry - Entry to check.\n   * @returns `true` if the entry's age exceeds the TTL.\n   */\n  entryHasExpired(entry: QuoteStatusRuntimeEntry): boolean {\n    const now = Date.now();\n    return now - entry.createdAt > this.#entryTtlMs;\n  }\n\n  /**\n   * Transitions an entry to {@link QuoteStatusState.Expired} (keeping it) if it\n   * has exceeded its TTL.\n   *\n   * The transition persists the updated snapshot via the entry's FSM\n   * subscription. Already-terminal entries cannot transition and are left\n   * untouched.\n   *\n   * @param entry - Entry to check and possibly expire.\n   * @returns `true` if the entry was stale, otherwise `false`.\n   */\n  expireEntryIfStale(entry: QuoteStatusRuntimeEntry): boolean {\n    if (this.entryHasExpired(entry)) {\n      entry.status.transitionTo(QuoteStatusState.Expired);\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Removes every entry from the store.\n   *\n   * Detaches each entry's FSM listeners before clearing to prevent leaks and\n   * stale persist callbacks. Does not emit a persistence update; callers are\n   * expected to use this during teardown.\n   */\n  clear(): void {\n    for (const entry of this.#items.values()) {\n      entry.status.removeAllListeners();\n    }\n\n    this.#items.clear();\n  }\n}\n"]}