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

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

@@ -0,0 +1,374 @@
+import { launchBankRedirect as defaultLaunchBankRedirect } from '../../internal/bank-redirect';
+import {
+  type HostedBridgeMessage,
+  parseHostedBridgeMessage,
+} from '../../internal/hosted/bridge-message';
+import { createLogger } from '../../internal/logger';
+import { readPaymentReturn } from '../models/payment-return-params';
+import { type HostedFlowState, HostedFlowStates, isTerminalPhase } from './hosted-flow-state';
+
+const log = createLogger('HostedFlowController');
+
+/** Opens a bank authorization URL outside the WebView. */
+export type BankLauncher = (url: string) => Promise<void>;
+
+/**
+ * How long the page has to become interactive, measured from when the webview
+ * mounts.
+ *
+ * A page can load and still never speak: its script can fail to fetch, or throw
+ * before it posts `spare.ready`. Nothing else would notice, and the payer would
+ * hold a blank frame for as long as they were willing to.
+ *
+ * Measured from the webview rather than from this controller, because a
+ * controller is built before the screen is: the sheet's animation and whatever
+ * the host waits on before rendering would otherwise be charged against the
+ * page's budget, and a page that merely loads slowly would be called unreachable.
+ */
+export const DEFAULT_READY_TIMEOUT_MS = 20_000;
+
+export interface HostedFlowControllerOptions {
+  reference: string;
+  bankLauncher?: BankLauncher;
+  /** Override the readiness timeout. Tests set this alongside fake timers. */
+  readyTimeoutMs?: number;
+}
+
+/**
+ * Drives a hosted payment from the messages the page sends and the deep link
+ * the OS delivers when the payer comes back.
+ *
+ * The SDK makes no API calls of its own: the page creates the consent, and the
+ * merchant's backend reads the result. So this controller only ever reacts —
+ * which is why every transition here is guarded against arriving after the flow
+ * has already resolved.
+ */
+export class HostedFlowController {
+  readonly reference: string;
+
+  private readonly bankLauncher: BankLauncher;
+  private readonly listeners = new Set<() => void>();
+  private readonly readyTimeoutMs: number;
+  private currentState: HostedFlowState;
+  private readyTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(options: HostedFlowControllerOptions) {
+    this.reference = options.reference;
+    this.bankLauncher =
+      options.bankLauncher ?? ((url) => defaultLaunchBankRedirect({ authorizationUrl: url }));
+    this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    this.currentState = HostedFlowStates.loading(options.reference);
+  }
+
+  /**
+   * Records that the webview carrying the page is on screen.
+   *
+   * Starts the clock the page has to become interactive. Called on mount rather
+   * than on load, so a document that never finishes arriving is covered too.
+   */
+  reportPageMounted(): void {
+    if (this.currentState.phase !== 'loading') return;
+    this.watchForReadiness();
+  }
+
+  get state(): HostedFlowState {
+    return this.currentState;
+  }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Reacts to a message from the hosted page.
+   *
+   * Resolves to whether the message was understood, so a caller can log what it
+   * dropped. An unrecognised message is not a failure: the page keeps working
+   * and the payer is unaffected.
+   */
+  async handleBridgeMessage(raw: unknown): Promise<boolean> {
+    const message: HostedBridgeMessage | null = parseHostedBridgeMessage(raw);
+    if (!message) {
+      log.info('dropped an unrecognised message from the hosted page');
+      return false;
+    }
+
+    // Only a page still on screen may drive the flow. The page posts on render,
+    // and a webview left behind a payer who has moved on can post again: a `ready`
+    // accepted while they are at their bank would drag the flow back to `hosted`,
+    // and the `openUrl` after it would open a second bank browser for a payment
+    // whose first authorization is already under way.
+    if (!this.isPagePresented()) {
+      log.info(`ignoring a '${message.type}' message from a page no longer on screen`);
+      return false;
+    }
+
+    switch (message.type) {
+      case 'ready':
+        this.stopWatchingForReadiness();
+        this.moveTo(HostedFlowStates.hosted(this.reference, this.currentState.attempt));
+        break;
+      case 'openUrl':
+        await this.openBank(message.url);
+        break;
+      case 'cancel':
+        // The page spoke, so it is not unreachable whatever it went on to say.
+        this.stopWatchingForReadiness();
+        this.moveTo(HostedFlowStates.cancelled(this.reference, this.currentState.attempt));
+        break;
+      case 'error':
+        this.stopWatchingForReadiness();
+        this.moveTo(
+          HostedFlowStates.failed({
+            reference: this.reference,
+            errorCode: message.code,
+            attempt: this.currentState.attempt,
+          }),
+        );
+        break;
+    }
+    return true;
+  }
+
+  /**
+   * Resolves the flow from the deep link the payer returned through.
+   *
+   * The outcome is read from the link rather than inferred: it is the only
+   * report of what the bank and the payment actually did.
+   */
+  /** Whether the page is still the thing on screen and may still be believed. */
+  private isPagePresented(): boolean {
+    const phase = this.currentState.phase;
+    return phase === 'loading' || phase === 'hosted';
+  }
+
+  handleReturn(uri: URL | string): void {
+    const { outcome, report } = readPaymentReturn(uri);
+
+    // A return that names a different payment is not this payment's business. The
+    // link is handed over by the OS and any app can send one, and a delayed
+    // callback for an earlier payment would otherwise resolve whichever one is
+    // open — with the wrong outcome attached to the wrong reference.
+    if (report.reference !== undefined && report.reference !== this.reference) {
+      log.warning('ignoring a return that names a different payment');
+      return;
+    }
+
+    this.stopWatchingForReadiness();
+
+    if (outcome === 'processed') {
+      this.moveTo(
+        HostedFlowStates.succeeded({
+          reference: this.reference,
+          attempt: this.currentState.attempt,
+          report,
+        }),
+      );
+      return;
+    }
+
+    // `unknown` is not a failure. The service has statuses this version has not
+    // been taught, and a payment still being decided must not be reported as one
+    // that failed — abandoned says "ask your backend", which is the truth.
+    if (outcome === 'unknown') {
+      log.info('the return did not say what happened — reporting it as unresolved');
+      this.moveTo(HostedFlowStates.abandoned(this.reference, this.currentState.attempt));
+      return;
+    }
+
+    this.moveTo(
+      HostedFlowStates.failed({
+        reference: this.reference,
+        errorCode: report.errorCode ?? 'authorize_failed',
+        attempt: this.currentState.attempt,
+        report,
+      }),
+    );
+  }
+
+  /**
+   * Records that the payment page could not be loaded.
+   *
+   * Only meaningful before the bank is opened. Once the payer is away, a load
+   * error is the WebView behind them and says nothing about their payment.
+   *
+   * Before the page has spoken this does not resolve the flow: nothing has been
+   * attempted, so the payer is offered the page again rather than told their
+   * payment failed.
+   *
+   * After it has spoken, it does. By then the payer may have chosen a bank and
+   * the page may have created a consent for it, and reloading from the start
+   * could create a second one while silently discarding what they entered.
+   */
+  failToLoad(): void {
+    const phase = this.currentState.phase;
+    if (phase !== 'loading' && phase !== 'hosted') {
+      log.info('ignoring a page load error raised behind the payer');
+      return;
+    }
+    this.stopWatchingForReadiness();
+
+    if (phase === 'hosted') {
+      log.severe('the page failed after it had already started — not offering a reload');
+      this.moveTo(
+        HostedFlowStates.failed({
+          reference: this.reference,
+          // Not `page_unavailable`: that means the page was never reached and
+          // nothing was attempted. This page was working, and the payer may have
+          // got as far as a consent before its frame died — a different thing for
+          // a merchant to look into, and a different thing to show the payer.
+          errorCode: 'page_lost',
+          attempt: this.currentState.attempt,
+        }),
+      );
+      return;
+    }
+
+    this.moveTo(HostedFlowStates.unreachable(this.reference, this.currentState.attempt));
+  }
+
+  /**
+   * Asks for the page again after it could not be reached.
+   *
+   * The attempt is counted so the screen mounts a fresh webview: reusing the one
+   * that failed would show the payer the same dead frame.
+   */
+  retry(): void {
+    if (this.currentState.phase !== 'unreachable') {
+      log.info('ignoring a retry for a payment that is not waiting on the page');
+      return;
+    }
+    const attempt = this.currentState.attempt + 1;
+    log.info(`asking for the payment page again (attempt ${attempt})`);
+    // The fresh webview reports itself mounted, which restarts the clock.
+    this.moveTo(HostedFlowStates.loading(this.reference, attempt));
+  }
+
+  /**
+   * Records that the payer gave up on a page that could not be reached.
+   *
+   * Reported as a failure rather than abandonment: the payer did not leave a
+   * payment in progress, the SDK never managed to present one.
+   */
+  giveUp(): void {
+    if (this.currentState.phase !== 'unreachable') {
+      log.info('ignoring a give-up for a payment that is not waiting on the page');
+      return;
+    }
+    this.stopWatchingForReadiness();
+    this.moveTo(
+      HostedFlowStates.failed({
+        reference: this.reference,
+        errorCode: 'page_unavailable',
+        attempt: this.currentState.attempt,
+      }),
+    );
+  }
+
+  /**
+   * Records that the payer left before the flow resolved.
+   *
+   * A payment already at the bank may still complete after this, so it is
+   * reported as abandoned rather than failed: the merchant's backend, not the
+   * app, is what knows.
+   */
+  abandon(): void {
+    this.stopWatchingForReadiness();
+
+    if (this.currentState.phase === 'unreachable') {
+      // Nothing was ever presented, so there is no payment that might still
+      // complete at the bank — which is what abandonment promises the merchant.
+      this.moveTo(
+        HostedFlowStates.failed({
+          reference: this.reference,
+          errorCode: 'page_unavailable',
+          attempt: this.currentState.attempt,
+        }),
+      );
+      return;
+    }
+
+    this.moveTo(HostedFlowStates.abandoned(this.reference, this.currentState.attempt));
+  }
+
+  dispose(): void {
+    this.stopWatchingForReadiness();
+    this.listeners.clear();
+  }
+
+  private watchForReadiness(): void {
+    this.stopWatchingForReadiness();
+    this.readyTimer = setTimeout(() => {
+      this.readyTimer = undefined;
+      if (this.currentState.phase !== 'loading') return;
+      log.severe('the payment page never became interactive — treating it as unreachable');
+      this.moveTo(HostedFlowStates.unreachable(this.reference, this.currentState.attempt));
+    }, this.readyTimeoutMs);
+  }
+
+  private stopWatchingForReadiness(): void {
+    if (this.readyTimer === undefined) return;
+    clearTimeout(this.readyTimer);
+    this.readyTimer = undefined;
+  }
+
+  /**
+   * Opens the bank and waits for the payer to be sent back.
+   *
+   * The URL is opened exactly once, and never once the flow has resolved. The
+   * page posts on render, so a rebuild can repeat the message; opening a second
+   * browser — or one for a payment the payer has already left — would leave them
+   * authorizing in a window whose return nobody is waiting for.
+   */
+  private async openBank(url: string): Promise<void> {
+    if (isTerminalPhase(this.currentState.phase)) {
+      log.info('not opening the bank for a payment that already resolved');
+      return;
+    }
+    if (
+      this.currentState.phase === 'redirecting' ||
+      this.currentState.phase === 'awaitingCallback'
+    ) {
+      log.info('bank already opened for this payment — ignoring');
+      return;
+    }
+
+    this.stopWatchingForReadiness();
+    this.moveTo(HostedFlowStates.redirecting(this.reference, this.currentState.attempt));
+
+    try {
+      await this.bankLauncher(url);
+      this.moveTo(HostedFlowStates.awaitingCallback(this.reference, this.currentState.attempt));
+    } catch {
+      // The platform's message is not logged: a native launcher's error can carry
+      // the whole authorize URL back, `request_uri` and state included.
+      log.severe('could not open the bank');
+      this.moveTo(
+        HostedFlowStates.failed({
+          reference: this.reference,
+          errorCode: 'redirect_failed',
+          attempt: this.currentState.attempt,
+        }),
+      );
+    }
+  }
+
+  private moveTo(next: HostedFlowState): void {
+    if (isTerminalPhase(this.currentState.phase)) {
+      log.info('ignoring transition after the flow already resolved');
+      return;
+    }
+    this.currentState = next;
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        /* a listener that throws must not stop the others from hearing */
+      }
+    }
+  }
+}

package/src/core/services/hosted-flow-state.ts

@@ -0,0 +1,123 @@
+import type { PaymentReturnReport } from '../models/payment-return-params';
+
+/**
+ * Where a hosted payment has got to.
+ *
+ * The phases the payer spends most of their time in — choosing a bank, reading
+ * the consent, confirming the payee — are all `hosted`: they happen inside the
+ * page, which does not report them, and the SDK has nothing to decide there.
+ */
+export type HostedFlowPhase =
+  /** The page is being fetched. Nothing is interactive yet. */
+  | 'loading'
+  /** The page is interactive and the payer is working through it. */
+  | 'hosted'
+  /**
+   * The page could not be loaded, or loaded and never became interactive.
+   *
+   * Deliberately not terminal. Nothing has been attempted — no consent, no bank,
+   * no money — so the payer is offered the page again rather than told their
+   * payment failed, and the flow stays open while they decide.
+   */
+  | 'unreachable'
+  /** A consent exists and the bank is being opened outside the WebView. */
+  | 'redirecting'
+  /** The bank has the payer. The next thing to happen is a deep link home. */
+  | 'awaitingCallback'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  /** The payer left before the flow resolved either way. */
+  | 'abandoned';
+
+/** Immutable snapshot of a hosted payment. */
+export interface HostedFlowState {
+  readonly phase: HostedFlowPhase;
+
+  /**
+   * The payment request this flow is paying. Also what the merchant's backend
+   * reads the authoritative result by.
+   */
+  readonly reference: string;
+
+  /**
+   * Everything the return deep link reported — the merchant's reference, the
+   * payment id, the signature, the failure detail.
+   *
+   * Carried whole so a parameter added to the return contract reaches the caller
+   * without threading a new field through every factory below.
+   */
+  readonly report?: PaymentReturnReport;
+
+  readonly errorCode?: string;
+
+  /**
+   * How many times the page has been asked for, starting at 1.
+   *
+   * The screen keys the webview on this so a retry mounts a fresh one; reusing
+   * the failed instance would show the payer the same dead frame.
+   */
+  readonly attempt: number;
+}
+
+const TERMINAL_PHASES: ReadonlySet<HostedFlowPhase> = new Set<HostedFlowPhase>([
+  'succeeded',
+  'failed',
+  'cancelled',
+  'abandoned',
+]);
+
+export function isTerminalPhase(phase: HostedFlowPhase): boolean {
+  return TERMINAL_PHASES.has(phase);
+}
+
+/** Factories for each phase, so no caller assembles a state by hand. */
+export const HostedFlowStates = {
+  loading(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'loading', reference, attempt };
+  },
+  hosted(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'hosted', reference, attempt };
+  },
+  unreachable(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'unreachable', reference, attempt };
+  },
+  redirecting(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'redirecting', reference, attempt };
+  },
+  awaitingCallback(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'awaitingCallback', reference, attempt };
+  },
+  succeeded(args: {
+    reference: string;
+    report?: PaymentReturnReport;
+    attempt?: number;
+  }): HostedFlowState {
+    return {
+      phase: 'succeeded',
+      reference: args.reference,
+      attempt: args.attempt ?? 1,
+      ...(args.report ? { report: args.report } : {}),
+    };
+  },
+  failed(args: {
+    reference: string;
+    errorCode: string;
+    report?: PaymentReturnReport;
+    attempt?: number;
+  }): HostedFlowState {
+    return {
+      phase: 'failed',
+      reference: args.reference,
+      errorCode: args.errorCode,
+      attempt: args.attempt ?? 1,
+      ...(args.report ? { report: args.report } : {}),
+    };
+  },
+  cancelled(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'cancelled', reference, attempt };
+  },
+  abandoned(reference: string, attempt = 1): HostedFlowState {
+    return { phase: 'abandoned', reference, attempt };
+  },
+} as const;

package/src/index.ts

@@ -4,110 +4,41 @@ export { SDK_VERSION } from './version';
 
 export * from './public';
 
-// Errors
-export { PaymentApiError, isPaymentApiError } from './core/errors/payment-api-error';
-
-// Models (camelCase SDK shapes)
-export type {
-  CreatePaymentRequestInput,
-  AmountDto,
-  PaymentInstructions,
-  PaymentScheduleEntry,
-  PeriodicSchedule,
-  PeriodicControls,
-  CurrencyRequest,
-  LinkSessionResponse,
-  ConsentResponse,
-  LinkStatusResponse,
-  CopResponse,
-  TelemetryResponse,
-  PatchTokenResponse,
-  ProviderCountry,
-  ProviderSummary,
-  PendingSessionRecord,
-} from './core/models';
-
 // Bank-return URI helpers (handy for hosts implementing their own deep-link
 // router that needs to know whether a URI belongs to the payment flow).
 export {
+  type PaymentReturnReport,
   isPaymentReturnCallbackUri,
+  readPaymentReturn,
   extractPaymentReturnErrorCode,
+  extractPaymentReturnErrorDescription,
+  extractPaymentReturnErrorReason,
+  extractPaymentReturnPaymentId,
+  extractPaymentReturnMandateId,
+  extractPaymentReturnReference,
+  extractPaymentReturnMerchantRef,
+  extractPaymentReturnSignature,
+  isPaymentReturnSuccess,
+  paymentReturnParams,
 } from './core/models/payment-return-params';
 
-// API client
-export { LinkApiClient, type LinkApiClientOptions } from './core/client/link-api-client';
-
-// Controller + state machine
-export {
-  PaymentFlowController,
-  type PaymentFlowControllerOptions,
-  type Clock,
-} from './core/services/payment-flow-controller';
-export {
-  PaymentFlowStates,
-  type PaymentFlowPhase,
-  type PaymentFlowState,
-} from './core/services/payment-flow-state';
+// Types a caller reads off a result or a state, without the machinery that
+// produces them. The orchestration internals — the controller, the raw webview,
+// the phase hook, the individual screens — are deliberately not exported: they
+// are how `SpareLinkHost` is built, not a surface anyone should build against,
+// and exporting them makes every internal rename a breaking change.
+export type { HostedFlowPhase, HostedFlowState } from './core/services/hosted-flow-state';
 
 // Storage interface
 export type { PendingSessionStore } from './core/services/pending-session-store';
+export type { PendingSessionRecord } from './core/models';
 
-// Consent presenter (UI helper, pure function)
-export {
-  presentConsent,
-  summaryFromState,
-  formatAmount,
-  formatCop,
-  type ConsentSummaryData,
-  type SinglePaymentSummaryData,
-  type InternationalPaymentSummaryData,
-  type MultiPaymentSummaryData,
-  type ConsentDisplayData,
-  type CopDisplayData,
-  type CopMatchIndicator,
-} from './core/services/consent-presenter';
-
-export {
-  buildMultiPaymentRules,
-  rulesSectionTitle,
-  type LabelValueRow,
-} from './core/services/multi-payment-rules-presenter';
-
-export {
-  isMultiPayment,
-  isInternational,
-  supportsConfirmationOfPayee,
-  resolvedPaymentType,
-  consentUiVariant,
-  PaymentType,
-  type ConsentUiVariant,
-} from './core/models/payment-type';
-
-// UI surface
-export {
-  SpareLinkHost,
-  type SpareLinkHostProps,
-} from './ui/spare-link-host';
-export { PaymentFlowPage, type PaymentFlowPageProps } from './ui/payment-flow-page';
-export { usePaymentFlowState } from './ui/hooks/use-payment-flow-state';
-export {
-  BankSelectionScreen,
-  type BankSelectionScreenProps,
-  ConsentDetailsScreen,
-  type ConsentDetailsScreenProps,
-  RedirectHandoffScreen,
-  ResumeProcessingScreen,
-  type ResumeProcessingScreenProps,
-  ResultScreen,
-  type ResultScreenProps,
-  MandateSetupSuccessScreen,
-  type MandateSetupSuccessScreenProps,
-} from './ui/screens';
+// UI surface: one component to mount, and the theme to match it.
+export { SpareLinkHost, type SpareLinkHostProps } from './ui/spare-link-host';
 export { Colors, Typography, Spacing, FONT_FAMILY } from './ui/theme';
 
 // Native platform integration
 export {
-  collectTelemetry,
   launchBankRedirect,
   type BankRedirectArgs,
   SecureStorePendingSessionStore,