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

package/src/core/services/payment-flow-controller.ts

@@ -1,607 +0,0 @@
-import { createLogger } from '../../internal/logger';
-import { redactPaymentReturnUri } from '../../internal/redact-uri';
-import {
-  DEFAULT_AWAITING_CALLBACK_POLL_MS,
-  DEFAULT_AWAITING_CALLBACK_TIMEOUT_MS,
-} from '../../public/constants';
-import type { PaymentEnvironment } from '../../public/spare-link-config';
-/** Simple string tag for internal controller callbacks — not the public SpareLinkEvent. */
-type PaymentFlowEventTag =
-  | 'initialized'
-  | 'sessionLoaded'
-  | 'consentStarted'
-  | 'redirectToBank'
-  | 'bankCallbackReceived'
-  | 'succeeded'
-  | 'failed'
-  | 'cancelled'
-  | 'abandoned';
-import type { LinkApiClient } from '../client/link-api-client';
-import { isPaymentApiError } from '../errors/payment-api-error';
-import type { ConsentResponse, CopResponse, LinkSessionResponse, ProviderSummary } from '../models';
-import { isBankCallbackReceivedStatus } from '../models/link-session-status';
-import { extractPaymentReturnErrorCode } from '../models/payment-return-params';
-import { supportsConfirmationOfPayee } from '../models/payment-type';
-import {
-  type PaymentFlowPhase,
-  type PaymentFlowState,
-  PaymentFlowStates,
-} from './payment-flow-state';
-import type { PendingSessionStore } from './pending-session-store';
-
-/** Minimum surface required from a `Clock` injected for testability. */
-export interface Clock {
-  now(): number;
-}
-
-const REAL_CLOCK: 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');
-
-export interface PaymentFlowControllerOptions {
-  sessionToken: string;
-  apiClient: LinkApiClient;
-  pendingSessionStore?: PendingSessionStore;
-  awaitingCallbackTimeoutMs?: number;
-  /**
-   * Deployment environment. In `sandbox`, the controller treats a non-terminal
-   * `/link/status` response during awaitingCallback as success: the sandbox bank
-   * authorizes consent but never settles the payment, so the status endpoint
-   * stays non-terminal forever and the flow could otherwise only ever time out.
-   * Production keeps strict terminal-only behavior. Defaults to `production`.
-   */
-  environment?: PaymentEnvironment;
-  /**
-   * Interval for the sandbox awaiting-callback status poll. Ignored outside
-   * sandbox. Defaults to {@link DEFAULT_AWAITING_CALLBACK_POLL_MS}.
-   */
-  awaitingCallbackPollMs?: number;
-  /** Optional clock injection for deterministic timeout tests. */
-  clock?: Clock;
-  /** Telemetry collector — called once before POST /link/consent. */
-  collectTelemetry?: () => Promise<Record<string, unknown>>;
-  /** UUID generator used for the consent Idempotency-Key. */
-  uuid?: () => string;
-  /** Callback for internal flow event tags. Exceptions are swallowed. */
-  onEvent?: (event: PaymentFlowEventTag) => void;
-}
-
-type Listener = (state: PaymentFlowState) => void;
-
-const TERMINAL_PHASES = new Set<PaymentFlowPhase>(['succeeded', 'failed', 'cancelled']);
-
-function isTerminal(phase: PaymentFlowPhase): boolean {
-  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 {
-  readonly sessionToken: string;
-  readonly apiClient: LinkApiClient;
-  readonly pendingSessionStore?: PendingSessionStore;
-
-  private readonly awaitingCallbackTimeoutMs: number;
-  private readonly environment: PaymentEnvironment;
-  private readonly awaitingCallbackPollMs: number;
-  private readonly clock: Clock;
-  private readonly collectTelemetry?: () => Promise<Record<string, unknown>>;
-  private readonly uuid: () => string;
-  private readonly onEventCallback?: (event: PaymentFlowEventTag) => void;
-
-  private _state: PaymentFlowState = PaymentFlowStates.idle();
-  private _listeners = new Set<Listener>();
-  private _consentIdempotencyKey: string | undefined;
-  private _callbackTimer: ReturnType<typeof setTimeout> | undefined;
-  private _awaitingCallbackStartedAtMs: number | undefined;
-  /** Last provider the user selected — retained so success/awaiting states that
-   *  arrive without it (poll/callback) can still report `bankId`. */
-  private _selectedProvider: ProviderSummary | undefined;
-  private _disposed = false;
-  /** Re-entrance guard — second `hydrate()` returns the in-flight promise. */
-  private _hydratePromise: Promise<void> | undefined;
-  /** Consecutive `pollStatus` transport failures since the last successful response. */
-  private _pollStatusConsecutiveFailures = 0;
-
-  constructor(opts: PaymentFlowControllerOptions) {
-    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(): PaymentFlowState {
-    return this._state;
-  }
-
-  get awaitingCallbackStartedAtMs(): number | undefined {
-    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: Listener): () => void {
-    this._listeners.add(listener);
-    try {
-      listener(this._state);
-    } catch {
-      // swallow — listener bugs never break the controller
-    }
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-
-  private setState(next: PaymentFlowState): void {
-    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: PaymentFlowEventTag): void {
-    try {
-      this.onEventCallback?.(event);
-    } catch {
-      // swallow integrator errors
-    }
-  }
-
-  // ---- Timers --------------------------------------------------------------
-
-  private cancelCallbackTimeout(): void {
-    if (this._callbackTimer) {
-      clearTimeout(this._callbackTimer);
-      this._callbackTimer = undefined;
-    }
-  }
-
-  private startCallbackTimeout(): void {
-    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(): Promise<void> {
-    if (this._disposed) return Promise.resolve();
-    if (this._hydratePromise) return this._hydratePromise;
-    this._hydratePromise = this._doHydrate().finally(() => {
-      this._hydratePromise = undefined;
-    });
-    return this._hydratePromise;
-  }
-
-  private async _doHydrate(): Promise<void> {
-    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: string): void {
-    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`.
-   */
-  private loadCopInBackground(session: LinkSessionResponse, provider: ProviderSummary): void {
-    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,
-        }),
-      );
-    })();
-  }
-
-  private shouldPerformCop(session: LinkSessionResponse): boolean {
-    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(): Promise<void> {
-    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: ConsentResponse;
-    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: URL | string): void {
-    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: 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(): Promise<void> {
-    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: string): Promise<void> {
-    log.severe(`reportError: reporting error code=${code}`);
-    this.setState(PaymentFlowStates.failed({ errorCode: code }));
-    // Fire-and-forget; we already transitioned.
-    void this.patchTokenBestEffort('error', code);
-  }
-
-  private async patchTokenBestEffort(
-    action: 'cancel' | 'error',
-    errorCode?: string,
-  ): Promise<void> {
-    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: { providerName?: string } = {}): void {
-    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(): Promise<void> {
-    // 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: Record<string, unknown>): Promise<void> {
-    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?: string): Promise<CopResponse | null> {
-    try {
-      return await this.apiClient.getConfirmPayee(this.sessionToken, providerId);
-    } catch {
-      return null;
-    }
-  }
-
-  private async postTelemetryAutomatic(): Promise<void> {
-    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(): ProviderSummary[] {
-    return this._state.providers;
-  }
-
-  /** Returns the active session, if any. */
-  get session(): LinkSessionResponse | undefined {
-    return this._state.session;
-  }
-
-  /**
-   * Releases resources: cancels timers, clears listeners, and aborts the
-   * underlying API client's in-flight fetches. Idempotent.
-   */
-  dispose(): void {
-    if (this._disposed) return;
-    log.info('dispose: releasing apiClient');
-    this._disposed = true;
-    this.cancelCallbackTimeout();
-    this._listeners.clear();
-    this.apiClient.dispose();
-  }
-}
-
-function fallbackUuid(): string {
-  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)}`;
-}