@spare-technologies/spare-link 0.1.0-beta.0 → 1.0.0

package/lib/module/core/services/multi-payment-rules-presenter.js

@@ -1,146 +0,0 @@
-"use strict";
-
-import { PaymentType } from "../models/payment-type.js";
-import { formatAmount } from "./presentation-utils.js";
-function present(value, fallback = '—') {
-  const v = value?.trim();
-  return v ? v : fallback;
-}
-function presentInt(value, fallback = '—') {
-  if (value === undefined) return fallback;
-  return String(value);
-}
-function formatDate(raw) {
-  if (!raw?.trim()) return '—';
-  const parsed = new Date(raw.trim());
-  if (Number.isNaN(parsed.getTime())) return raw.trim();
-  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-  const day = String(parsed.getUTCDate()).padStart(2, '0');
-  const month = months[parsed.getUTCMonth()];
-  return `${day} ${month} ${parsed.getUTCFullYear()}`;
-}
-function definedSchedule(type, instructions) {
-  const isFixed = type === PaymentType.fixedDefinedSchedule;
-  const amountLabel = isFixed ? 'Amount' : 'Max Amount';
-  const schedule = instructions.paymentSchedule ?? [];
-  const rows = [];
-  for (const entry of schedule) {
-    const amountDto = isFixed ? entry.amount : entry.maxAmount;
-    rows.push({
-      label: amountLabel,
-      value: formatAmount(amountDto)
-    });
-    rows.push({
-      label: 'Date',
-      value: formatDate(entry.paymentExecutionDate)
-    });
-  }
-  return rows;
-}
-function periodicSchedule(type, instructions) {
-  const isFixed = type === PaymentType.fixedPeriodicSchedule;
-  const periodic = instructions.periodicSchedule;
-  const amountDto = isFixed ? periodic?.amount : periodic?.maxAmount;
-  const amountLabel = isFixed ? 'Amount' : 'Max per Payment';
-  const rows = [{
-    label: amountLabel,
-    value: formatAmount(amountDto)
-  }, {
-    label: 'First Payment Date',
-    value: formatDate(periodic?.startDate)
-  }, {
-    label: 'Payment repeats every',
-    value: present(periodic?.frequency)
-  }, {
-    label: 'Stop payment on',
-    value: formatDate(periodic?.endDate)
-  }, {
-    label: 'Total number of payments',
-    value: presentInt(instructions.maxCumulativeNumberOfPayments)
-  }];
-  if (!isFixed) {
-    rows.push({
-      label: 'Total Value Allowed',
-      value: formatAmount(instructions.maxCumulativeAmount)
-    });
-  }
-  return rows;
-}
-function fixedOnDemand(instructions) {
-  const periodic = instructions.periodicSchedule;
-  const frequency = periodic?.frequency;
-  return [{
-    label: 'Amount',
-    value: formatAmount(periodic?.amount)
-  }, {
-    label: 'Total number of payments allowed',
-    value: presentInt(instructions.maxCumulativeNumberOfPayments)
-  }, {
-    label: 'Total Value Allowed',
-    value: formatAmount(instructions.maxCumulativeAmount)
-  }, {
-    label: 'Limits Every',
-    value: present(frequency)
-  }, {
-    label: `Max Value per ${present(frequency)}`,
-    value: formatAmount(periodic?.controls?.maxCumulativeAmountPerPeriod)
-  }, {
-    label: `Max Payments per ${present(frequency)}`,
-    value: presentInt(periodic?.controls?.maxCumulativeNumberOfPaymentsPerPeriod)
-  }, {
-    label: 'Expiry Date',
-    value: formatDate(periodic?.endDate)
-  }];
-}
-function variableOnDemand(instructions) {
-  const periodic = instructions.periodicSchedule;
-  const frequency = periodic?.frequency;
-  return [{
-    label: 'First Payment Date',
-    value: formatDate(periodic?.startDate)
-  }, {
-    label: 'Expiry Date',
-    value: formatDate(periodic?.endDate)
-  }, {
-    label: 'Max per Payment',
-    value: formatAmount(periodic?.maxAmount)
-  }, {
-    label: 'Total number of payments allowed',
-    value: presentInt(instructions.maxCumulativeNumberOfPayments)
-  }, {
-    label: 'Total Value Allowed',
-    value: formatAmount(instructions.maxCumulativeAmount)
-  }, {
-    label: 'Limits Every',
-    value: present(frequency)
-  }, {
-    label: `Max Value per ${present(frequency)}`,
-    value: formatAmount(periodic?.controls?.maxCumulativeAmountPerPeriod)
-  }, {
-    label: `Max Payments per ${present(frequency)}`,
-    value: presentInt(periodic?.controls?.maxCumulativeNumberOfPaymentsPerPeriod)
-  }];
-}
-export function buildMultiPaymentRules(type, instructions) {
-  switch (type) {
-    case PaymentType.fixedDefinedSchedule:
-    case PaymentType.variableDefinedSchedule:
-      return definedSchedule(type, instructions);
-    case PaymentType.fixedPeriodicSchedule:
-    case PaymentType.variablePeriodicSchedule:
-      return periodicSchedule(type, instructions);
-    case PaymentType.fixedOnDemand:
-      return fixedOnDemand(instructions);
-    case PaymentType.variableOnDemand:
-      return variableOnDemand(instructions);
-    default:
-      return [];
-  }
-}
-export function rulesSectionTitle(type) {
-  if (type === PaymentType.fixedDefinedSchedule || type === PaymentType.variableDefinedSchedule) {
-    return 'Payment schedule';
-  }
-  return 'Payment rules';
-}
-//# sourceMappingURL=multi-payment-rules-presenter.js.map

package/lib/module/core/services/multi-payment-rules-presenter.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["PaymentType","formatAmount","present","value","fallback","v","trim","presentInt","undefined","String","formatDate","raw","parsed","Date","Number","isNaN","getTime","months","day","getUTCDate","padStart","month","getUTCMonth","getUTCFullYear","definedSchedule","type","instructions","isFixed","fixedDefinedSchedule","amountLabel","schedule","paymentSchedule","rows","entry","amountDto","amount","maxAmount","push","label","paymentExecutionDate","periodicSchedule","fixedPeriodicSchedule","periodic","startDate","frequency","endDate","maxCumulativeNumberOfPayments","maxCumulativeAmount","fixedOnDemand","controls","maxCumulativeAmountPerPeriod","maxCumulativeNumberOfPaymentsPerPeriod","variableOnDemand","buildMultiPaymentRules","variableDefinedSchedule","variablePeriodicSchedule","rulesSectionTitle"],"sourceRoot":"../../../../src","sources":["core/services/multi-payment-rules-presenter.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/services/payment-flow-controller.js

@@ -1,544 +0,0 @@
-"use strict";
-
-import { createLogger } from "../../internal/logger.js";
-import { redactPaymentReturnUri } from "../../internal/redact-uri.js";
-import { DEFAULT_AWAITING_CALLBACK_POLL_MS, DEFAULT_AWAITING_CALLBACK_TIMEOUT_MS } from "../../public/constants.js";
-
-/** Simple string tag for internal controller callbacks — not the public SpareLinkEvent. */
-
-import { isPaymentApiError } from "../errors/payment-api-error.js";
-import { isBankCallbackReceivedStatus } from "../models/link-session-status.js";
-import { extractPaymentReturnErrorCode } from "../models/payment-return-params.js";
-import { supportsConfirmationOfPayee } from "../models/payment-type.js";
-import { PaymentFlowStates } from "./payment-flow-state.js";
-
-/** Minimum surface required from a `Clock` injected for testability. */
-
-const REAL_CLOCK = {
-  now: () => Date.now()
-};
-
-/**
- * Number of consecutive `pollStatus` transport failures we tolerate before
- * giving up and transitioning to `failed('network_error')`. Bounds the request
- * volume against a flaky network during the 5-minute awaiting-callback window.
- */
-const POLL_STATUS_MAX_CONSECUTIVE_FAILURES = 5;
-const log = createLogger('PaymentFlowController');
-const TERMINAL_PHASES = new Set(['succeeded', 'failed', 'cancelled']);
-function isTerminal(phase) {
-  return TERMINAL_PHASES.has(phase);
-}
-
-/**
- * Drives the payment flow state machine. Exposes a `subscribe`/`unsubscribe`
- * API so React's `useSyncExternalStore` can bridge to a hook.
- *
- * `subscribe` fires the listener synchronously with the current state so new
- * subscribers don't miss the initial snapshot.
- */
-export class PaymentFlowController {
-  _state = PaymentFlowStates.idle();
-  _listeners = new Set();
-
-  /** Last provider the user selected — retained so success/awaiting states that
-   *  arrive without it (poll/callback) can still report `bankId`. */
-
-  _disposed = false;
-  /** Re-entrance guard — second `hydrate()` returns the in-flight promise. */
-
-  /** Consecutive `pollStatus` transport failures since the last successful response. */
-  _pollStatusConsecutiveFailures = 0;
-  constructor(opts) {
-    this.sessionToken = opts.sessionToken;
-    this.apiClient = opts.apiClient;
-    if (opts.pendingSessionStore) this.pendingSessionStore = opts.pendingSessionStore;
-    this.awaitingCallbackTimeoutMs = opts.awaitingCallbackTimeoutMs ?? DEFAULT_AWAITING_CALLBACK_TIMEOUT_MS;
-    this.environment = opts.environment ?? 'production';
-    this.awaitingCallbackPollMs = opts.awaitingCallbackPollMs ?? DEFAULT_AWAITING_CALLBACK_POLL_MS;
-    this.clock = opts.clock ?? REAL_CLOCK;
-    if (opts.collectTelemetry) this.collectTelemetry = opts.collectTelemetry;
-    this.uuid = opts.uuid ?? fallbackUuid;
-    if (opts.onEvent) this.onEventCallback = opts.onEvent;
-  }
-
-  // ---- Subscription API ----------------------------------------------------
-
-  get state() {
-    return this._state;
-  }
-  get awaitingCallbackStartedAtMs() {
-    return this._awaitingCallbackStartedAtMs;
-  }
-
-  /**
-   * Register a listener. The listener is invoked synchronously with the
-   * current state so new subscribers have the initial snapshot, then again
-   * on every subsequent change.
-   */
-  subscribe(listener) {
-    this._listeners.add(listener);
-    try {
-      listener(this._state);
-    } catch {
-      // swallow — listener bugs never break the controller
-    }
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-  setState(next) {
-    if (this._disposed) return;
-    this._state = next;
-    if (isTerminal(next.phase)) {
-      this.cancelCallbackTimeout();
-      this._consentIdempotencyKey = undefined;
-    }
-    for (const l of this._listeners) {
-      try {
-        l(next);
-      } catch {
-        // listener exceptions never break the controller
-      }
-    }
-  }
-  fireEvent(event) {
-    try {
-      this.onEventCallback?.(event);
-    } catch {
-      // swallow integrator errors
-    }
-  }
-
-  // ---- Timers --------------------------------------------------------------
-
-  cancelCallbackTimeout() {
-    if (this._callbackTimer) {
-      clearTimeout(this._callbackTimer);
-      this._callbackTimer = undefined;
-    }
-  }
-  startCallbackTimeout() {
-    this.cancelCallbackTimeout();
-    this._callbackTimer = setTimeout(() => {
-      if (this._state.phase !== 'awaitingCallback') return;
-      void this.reportError('session_timeout');
-    }, this.awaitingCallbackTimeoutMs);
-  }
-
-  // ---- Phase transitions ---------------------------------------------------
-
-  /**
-   * `GET /link` + `GET /link/providers`, then transitions to bankSelection.
-   * Re-entrant: a second concurrent call returns the in-flight promise instead
-   * of firing duplicate requests.
-   */
-  hydrate() {
-    if (this._disposed) return Promise.resolve();
-    if (this._hydratePromise) return this._hydratePromise;
-    this._hydratePromise = this._doHydrate().finally(() => {
-      this._hydratePromise = undefined;
-    });
-    return this._hydratePromise;
-  }
-  async _doHydrate() {
-    log.info('hydrate: starting session hydration');
-    this.setState(PaymentFlowStates.hydrating());
-    try {
-      const [session, providers] = await Promise.all([this.apiClient.getSession(this.sessionToken), this.apiClient.getProviders(this.sessionToken)]);
-      log.info(`hydrate: loaded session with ${providers.length} provider(s)`);
-      this.setState(PaymentFlowStates.bankSelection({
-        session,
-        providers
-      }));
-      this.fireEvent('sessionLoaded');
-    } catch (err) {
-      log.severe(`hydrate: failed — ${err instanceof Error ? err.message : String(err)}`);
-      const code = isPaymentApiError(err) ? err.code : 'hydration_error';
-      const message = err instanceof Error ? err.message : String(err);
-      this.setState(PaymentFlowStates.failed({
-        errorCode: code,
-        errorMessage: message
-      }));
-      throw err;
-    }
-  }
-
-  /** Move bankSelection → consentDetails. */
-  selectBank(bankId) {
-    log.info(`selectBank: bankId=${bankId}`);
-    const current = this._state;
-    const session = current.session;
-    if (!session) {
-      throw new Error('Cannot select bank before session is loaded.');
-    }
-    const provider = current.providers.find(p => p.id === bankId);
-    if (!provider) {
-      log.severe(`selectBank: unknown bankId=${bankId}`);
-      throw new Error(`Unknown bank id: ${bankId}`);
-    }
-    // Retained so success states reached via poll/callback (which don't carry
-    // the provider) still resolve a `bankId` in the PaymentResult.
-    this._selectedProvider = provider;
-    const willLoadCop = this.shouldPerformCop(session);
-    this.setState(PaymentFlowStates.consentDetails({
-      session,
-      selectedProvider: provider,
-      isCopLoading: willLoadCop,
-      copApplicable: willLoadCop
-    }));
-    if (willLoadCop) {
-      this.loadCopInBackground(session, provider);
-    }
-  }
-
-  /**
-   * Best-effort Confirmation-of-Payee fetch — never blocks {@link selectBank}
-   * or fails the flow. Mirrors the Flutter controller: gated to UAE + un-verified
-   * sessions, and the result is merged into the consentDetails state only if the
-   * user is still on that screen for the same provider. Ported from
-   * `payment_flow_controller.dart:_loadCopInBackground`.
-   */
-  loadCopInBackground(session, provider) {
-    void (async () => {
-      const cop = await this.getCoP(provider.id);
-      if (this._state.phase !== 'consentDetails') return;
-      if (this._state.selectedProvider?.id !== provider.id) return;
-      this.setState(PaymentFlowStates.consentDetails({
-        session,
-        selectedProvider: provider,
-        ...(cop ? {
-          copResponse: cop
-        } : {}),
-        isCopLoading: false,
-        copApplicable: true
-      }));
-    })();
-  }
-  shouldPerformCop(session) {
-    if (this.apiClient.tenantHeader !== 'UAE') return false;
-    if (session.request.isCopVerified === true) return false;
-    if (!supportsConfirmationOfPayee(session.request)) return false;
-    return true;
-  }
-
-  /** `POST /link/consent`, persists pending record, transitions to redirecting. */
-  async confirmConsent() {
-    log.info('confirmConsent: posting consent');
-    const selectedProvider = this._state.selectedProvider;
-    if (!selectedProvider) {
-      log.severe('confirmConsent: no provider selected');
-      throw new Error('Cannot confirm consent without a selected provider.');
-    }
-    this.fireEvent('consentStarted');
-    if (!this._consentIdempotencyKey) {
-      this._consentIdempotencyKey = this.uuid();
-    }
-
-    // Best-effort telemetry before posting consent.
-    await this.postTelemetryAutomatic();
-    let consent;
-    try {
-      consent = await this.apiClient.postConsent({
-        linkToken: this.sessionToken,
-        bankId: selectedProvider.id,
-        idempotencyKey: this._consentIdempotencyKey
-      });
-    } catch (err) {
-      // Without this the flow would be stranded in `consentDetails` with no
-      // terminal state — the caller's catch assumes we already transitioned.
-      const code = isPaymentApiError(err) ? err.code : 'consent_failed';
-      const message = err instanceof Error ? err.message : String(err);
-      this.setState(PaymentFlowStates.failed({
-        errorCode: code,
-        errorMessage: message
-      }));
-      void this.patchTokenBestEffort('error', code);
-      throw err;
-    }
-    if (this.pendingSessionStore) {
-      try {
-        const merchantRef = this._state.session?.request?.merchantReference;
-        await this.pendingSessionStore.save({
-          sessionId: this.sessionToken,
-          selectedBankId: selectedProvider.id,
-          authorizationUrl: consent.redirectUrl,
-          consentAt: this.clock.now(),
-          recoveryAttempts: 0,
-          ...(merchantRef ? {
-            merchantRef
-          } : {})
-        });
-      } catch {
-        log.warning('confirmConsent: store.save() failed — continuing');
-        // store failures should not block the flow
-      }
-    }
-    log.info('confirmConsent: → redirecting');
-    this.setState(PaymentFlowStates.redirecting({
-      consent,
-      selectedProvider
-    }));
-  }
-
-  /**
-   * Parses a callback URI and transitions to succeeded / failed. Accepts either
-   * a `URL` instance or a string. A malformed URI resolves to
-   * `failed('invalid_callback')` instead of throwing.
-   */
-  handleCallback(uri) {
-    log.info(`handleCallback: received URI=${redactPaymentReturnUri(typeof uri === 'string' ? uri : uri.toString())}`);
-    // Deep-link callbacks are commonly re-delivered (cold start + warm
-    // foreground). Once the flow is terminal, ignore further callbacks so we
-    // never re-transition and re-fire terminal callbacks.
-    if (isTerminal(this._state.phase)) return;
-    let url;
-    if (typeof uri === 'string') {
-      try {
-        url = new URL(uri);
-      } catch {
-        this.setState(PaymentFlowStates.failed({
-          errorCode: 'invalid_callback',
-          errorMessage: 'The callback URI could not be parsed.'
-        }));
-        return;
-      }
-    } else {
-      url = uri;
-    }
-    this.fireEvent('bankCallbackReceived');
-    const params = url.searchParams;
-
-    // Prefer the new `error_code` query param over legacy `error`. Also accept
-    // `status=failure` with no other code as `authorize_failed`.
-    const error = extractPaymentReturnErrorCode(params);
-    if (error) {
-      const description = params.get('error_description') ?? undefined;
-      this.setState(PaymentFlowStates.failed({
-        errorCode: error,
-        ...(description ? {
-          errorMessage: description
-        } : {})
-      }));
-      return;
-    }
-    const exchangeCode = params.get('exchange_code') ?? undefined;
-    const linkSessionId = params.get('session_id') ?? undefined;
-    const merchantRef = params.get('merchantRef') ?? undefined;
-    if (exchangeCode) {
-      this.setState(PaymentFlowStates.succeeded({
-        exchangeCode,
-        ...(linkSessionId ? {
-          linkSessionId
-        } : {}),
-        ...(merchantRef ? {
-          merchantRef
-        } : {}),
-        ...(this._selectedProvider ? {
-          selectedProvider: this._selectedProvider
-        } : {}),
-        ...(this._state.session ? {
-          session: this._state.session
-        } : {})
-      }));
-      return;
-    }
-    this.setState(PaymentFlowStates.failed({
-      errorCode: 'invalid_callback',
-      errorMessage: 'The callback URI is missing required parameters.'
-    }));
-  }
-
-  /** Best-effort cancel — PATCH /link with action=cancel, then transitions to cancelled. */
-  async cancel() {
-    log.info('cancel: user cancelled the payment flow');
-    await this.patchTokenBestEffort('cancel');
-    this.setState(PaymentFlowStates.cancelled());
-  }
-
-  /** Best-effort error report — sets failed state immediately, PATCH is fire-and-forget. */
-  async reportError(code) {
-    log.severe(`reportError: reporting error code=${code}`);
-    this.setState(PaymentFlowStates.failed({
-      errorCode: code
-    }));
-    // Fire-and-forget; we already transitioned.
-    void this.patchTokenBestEffort('error', code);
-  }
-  async patchTokenBestEffort(action, errorCode) {
-    try {
-      await this.apiClient.patchToken({
-        linkToken: this.sessionToken,
-        action,
-        ...(errorCode ? {
-          errorCode
-        } : {})
-      });
-    } catch {
-      // swallow — PATCH is best-effort
-    }
-  }
-
-  /**
-   * UI calls this after handing off to the bank — starts the 5-minute timeout
-   * and pins the awaiting-callback start time.
-   */
-  setAwaitingCallbackState(args = {}) {
-    this._awaitingCallbackStartedAtMs ??= this.clock.now();
-    this.setState(PaymentFlowStates.awaitingCallback({
-      ...(args.providerName ? {
-        providerName: args.providerName
-      } : {}),
-      ...(this._state.session ? {
-        session: this._state.session
-      } : {}),
-      ...(this._selectedProvider ? {
-        selectedProvider: this._selectedProvider
-      } : {})
-    }));
-    this.startCallbackTimeout();
-  }
-
-  /**
-   * Best-effort status polling. Transitions to a terminal state on
-   * `completed | failed | cancelled | expired`; otherwise leaves the flow in
-   * the current phase. After {@link POLL_STATUS_MAX_CONSECUTIVE_FAILURES}
-   * consecutive transport failures the controller gives up with
-   * `failed('network_error')` to stop hammering an unreachable backend.
-   */
-  async pollStatus() {
-    // A status response can land after a bank callback or the timeout has
-    // already resolved the flow; never overwrite a terminal state.
-    if (isTerminal(this._state.phase)) return;
-    try {
-      const status = await this.apiClient.getStatus(this.sessionToken);
-      this._pollStatusConsecutiveFailures = 0;
-      // Re-check: the await above yields, so a terminal callback may have
-      // arrived while the request was in flight.
-      if (isTerminal(this._state.phase)) return;
-      switch (status.status) {
-        case 'completed':
-          this.setState(PaymentFlowStates.succeeded({
-            ...(status.linkSessionId ? {
-              linkSessionId: status.linkSessionId
-            } : {}),
-            ...(this._selectedProvider ? {
-              selectedProvider: this._selectedProvider
-            } : {}),
-            ...(this._state.session ? {
-              session: this._state.session
-            } : {})
-          }));
-          return;
-        case 'failed':
-          this.setState(PaymentFlowStates.failed({
-            errorCode: status.failureCode ?? 'session_failed'
-          }));
-          return;
-        case 'cancelled':
-          this.setState(PaymentFlowStates.cancelled());
-          return;
-        case 'expired':
-          this.setState(PaymentFlowStates.failed({
-            errorCode: 'session_expired'
-          }));
-          return;
-        default:
-          // Non-terminal. In sandbox, only treat `callback_received` as success —
-          // the bank has actually returned. `redirected` means consent was posted
-          // but the user may not have authorized yet; auto-success there caused
-          // false positives on cold-start recovery.
-          if (this.environment === 'sandbox' && this._state.phase === 'awaitingCallback' && isBankCallbackReceivedStatus(status.status)) {
-            this.setState(PaymentFlowStates.succeeded({
-              ...(status.linkSessionId ? {
-                linkSessionId: status.linkSessionId
-              } : {}),
-              ...(this._selectedProvider ? {
-                selectedProvider: this._selectedProvider
-              } : {}),
-              ...(this._state.session ? {
-                session: this._state.session
-              } : {})
-            }));
-          }
-          return;
-      }
-    } catch {
-      this._pollStatusConsecutiveFailures += 1;
-      log.warning(`pollStatus: failed (${this._pollStatusConsecutiveFailures}/${POLL_STATUS_MAX_CONSECUTIVE_FAILURES})`);
-      if (this._pollStatusConsecutiveFailures >= POLL_STATUS_MAX_CONSECUTIVE_FAILURES) {
-        if (isTerminal(this._state.phase) || this._state.phase !== 'awaitingCallback') return;
-        this.setState(PaymentFlowStates.failed({
-          errorCode: 'network_error',
-          errorMessage: 'Unable to reach the Spare backend after multiple attempts.'
-        }));
-      }
-    }
-  }
-
-  /** Best-effort telemetry — never throws, never changes state. */
-  async postTelemetry(payload) {
-    try {
-      await this.apiClient.postTelemetry({
-        linkToken: this.sessionToken,
-        payload
-      });
-    } catch (err) {
-      log.warning(`postTelemetry: best-effort telemetry failed — ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  /** Best-effort CoP — returns result or null on failure. */
-  async getCoP(providerId) {
-    try {
-      return await this.apiClient.getConfirmPayee(this.sessionToken, providerId);
-    } catch {
-      return null;
-    }
-  }
-  async postTelemetryAutomatic() {
-    if (!this.collectTelemetry) return;
-    log.fine('postTelemetryAutomatic: collecting and posting device telemetry');
-    try {
-      const payload = await this.collectTelemetry();
-      await this.apiClient.postTelemetry({
-        linkToken: this.sessionToken,
-        payload
-      });
-    } catch (err) {
-      log.warning(`postTelemetryAutomatic: failed — ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  /** Returns the active providers list — convenience for the UI layer. */
-  get providers() {
-    return this._state.providers;
-  }
-
-  /** Returns the active session, if any. */
-  get session() {
-    return this._state.session;
-  }
-
-  /**
-   * Releases resources: cancels timers, clears listeners, and aborts the
-   * underlying API client's in-flight fetches. Idempotent.
-   */
-  dispose() {
-    if (this._disposed) return;
-    log.info('dispose: releasing apiClient');
-    this._disposed = true;
-    this.cancelCallbackTimeout();
-    this._listeners.clear();
-    this.apiClient.dispose();
-  }
-}
-function fallbackUuid() {
-  const bytes = new Uint8Array(16);
-  for (let i = 0; i < 16; i += 1) bytes[i] = Math.floor(Math.random() * 256);
-  bytes[6] = (bytes[6] ?? 0) & 0x0f | 0x40;
-  bytes[8] = (bytes[8] ?? 0) & 0x3f | 0x80;
-  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-}
-//# sourceMappingURL=payment-flow-controller.js.map