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

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

@@ -0,0 +1,607 @@
+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)}`;
+}