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

package/src/ui/spare-link-host.tsx

@@ -1,16 +1,18 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { ActivityIndicator, Modal, SafeAreaView, StyleSheet, View } from 'react-native';
+import { ActivityIndicator, Modal, StyleSheet, View } from 'react-native';
+// `react-native`'s own SafeAreaView applies nothing on Android, which left the
+// hosted page's header under the status bar there. This one insets both platforms.
+import { SafeAreaView } from 'react-native-safe-area-context';
 import { enableScreens } from 'react-native-screens';
-import { LinkApiClient } from '../core/client/link-api-client';
-import { isPaymentReturnCallbackUri } from '../core/models/payment-return-params';
-import { executeResumeIfNeeded } from '../core/services/execute-resume-if-needed';
-import { PaymentFlowController } from '../core/services/payment-flow-controller';
+import {
+  type PaymentReturnReport,
+  isPaymentReturnCallbackUri,
+  readPaymentReturn,
+} from '../core/models/payment-return-params';
+import { type BankLauncher, HostedFlowController } from '../core/services/hosted-flow-controller';
 import type { PendingSessionStore } from '../core/services/pending-session-store';
-import { setBufferedRedirect } from '../core/services/redirect-buffer';
-import { userFriendlyMessageFor } from '../core/services/user-friendly-messages';
-import { launchBankRedirect as defaultLaunchBankRedirect } from '../internal/bank-redirect';
 import { createLogger } from '../internal/logger';
-import { collectTelemetry } from '../internal/telemetry-collector';
+import { redactPaymentReturnUri } from '../internal/redact-uri';
 import type { PaymentResult } from '../public/payment-result';
 import {
   paymentAbandoned,
@@ -19,10 +21,9 @@ import {
   paymentSuccess,
 } from '../public/payment-result';
 import type { RecoveryResult } from '../public/recovery-result';
-import { tenantCountryCode } from '../public/spare-link-config';
-import { type SpareLinkEventType, SpareLinkEvents } from '../public/spare-link-event';
-import { type SpareLink, mapHostRecovery, noRecovery } from '../public/spare-link-instance';
-import { PaymentFlowPage } from './payment-flow-page';
+import { SpareLinkEvents } from '../public/spare-link-event';
+import { type SpareLink, noRecovery } from '../public/spare-link-instance';
+import { HostedPaymentPage } from './hosted/hosted-payment-page';
 import { Colors } from './theme';
 import { useLinkFonts } from './theme/fonts';
 import { ModalDismissButton } from './widgets/modal-dismiss-button';
@@ -32,10 +33,9 @@ enableScreens();
 const log = createLogger('SpareLinkHost');
 
 interface ActiveFlow {
-  controller: PaymentFlowController;
-  linkToken: string;
+  controller: HostedFlowController;
+  reference: string;
   resolve: (result: PaymentResult) => void;
-  onSessionLoaded?: (linkSessionId: string) => void;
 }
 
 export interface SpareLinkHostProps {
@@ -46,14 +46,15 @@ export interface SpareLinkHostProps {
    * When omitted, uses `spareLink.pendingSessionStore`.
    */
   pendingSessionStore?: PendingSessionStore;
-  launchBankRedirect?: (args: { authorizationUrl: string; mobileAppUrl?: string }) => Promise<void>;
+  /** Override how a bank authorization URL is opened. Tests inject a fake. */
+  launchBankRedirect?: BankLauncher;
   showDismissButton?: boolean;
   children?: React.ReactNode;
 }
 
 /**
  * Host component that mounts the SDK modal and connects a {@link SpareLink}
- * instance — Flutter-aligned integration (one instance, one host).
+ * instance — one instance, one host.
  */
 export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
   const { spareLink, showDismissButton = true, launchBankRedirect } = props;
@@ -62,37 +63,38 @@ export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
   const [active, setActive] = useState<ActiveFlow | null>(null);
   const activeRef = useRef<ActiveFlow | null>(null);
 
+  /** A return that arrived before there was a flow to give it to. */
+  const bufferedRedirect = useRef<string | null>(null);
+
   useEffect(() => {
     activeRef.current = active;
   }, [active]);
 
-  const emitMappedEvent = useCallback(
-    (linkToken: string, event: SpareLinkEventType, linkSessionId?: string) => {
-      switch (event) {
-        case 'sessionLoaded':
-          spareLink.emitEvent(SpareLinkEvents.sessionLoaded(linkToken, linkSessionId));
-          break;
-        case 'consentStarted':
-          spareLink.emitEvent(SpareLinkEvents.consentStarted(linkToken));
-          break;
-        case 'redirectToBank':
-          spareLink.emitEvent(SpareLinkEvents.redirectToBank(linkToken));
-          break;
-        case 'bankCallbackReceived':
-          spareLink.emitEvent(SpareLinkEvents.bankCallbackReceived(linkToken));
-          break;
-        default:
-          break;
-      }
-    },
-    [spareLink],
-  );
+  /**
+   * Serializes every write to the pending-session store.
+   *
+   * The store is pluggable, so it cannot be assumed to order its own writes: a
+   * `clear` overtaking a slow `save` would leave a record for a payment that has
+   * already resolved, and the next cold start would offer to recover it.
+   */
+  const persistQueue = useRef<Promise<unknown>>(Promise.resolve());
+  const enqueuePersist = useCallback((op: () => Promise<void>): Promise<void> => {
+    const next = persistQueue.current.then(op, op);
+    // Kept un-rejected so one failure does not poison the queue behind it.
+    persistQueue.current = next.catch(() => undefined);
+    return next;
+  }, []);
+
+  const clearPending = useCallback(() => {
+    if (!pendingSessionStore) return;
+    void enqueuePersist(() => pendingSessionStore.clear()).catch(() => {
+      log.warning('could not clear the pending payment — continuing');
+    });
+  }, [pendingSessionStore, enqueuePersist]);
 
   const close = useCallback(
     (flow: ActiveFlow, result: PaymentResult) => {
-      void pendingSessionStore?.clear().catch(() => {
-        log.warning('close: pendingSessionStore.clear() failed — continuing');
-      });
+      clearPending();
       flow.resolve(result);
       flow.controller.dispose();
       if (activeRef.current === flow) {
@@ -100,22 +102,46 @@ export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
         setActive(null);
       }
     },
-    [pendingSessionStore],
+    [clearPending],
   );
 
+  /** Maps a resolved flow onto the result the caller awaits. */
+  const resultFor = useCallback((flow: ActiveFlow): PaymentResult => {
+    const s = flow.controller.state;
+    const base = {
+      reference: s.reference,
+      ...reportedFields(s.report),
+      resolvedAtMs: Date.now(),
+    };
+    switch (s.phase) {
+      case 'succeeded':
+        return paymentSuccess(base);
+      case 'cancelled':
+        return paymentCancelled(base);
+      case 'failed':
+        return paymentFailed({ ...base, errorCode: s.errorCode ?? 'internal_error' });
+      default:
+        // Anything else resolving is the payer leaving mid-flow, which may still
+        // complete at the bank — so it is reported as unresolved, not as a failure.
+        return paymentAbandoned(base);
+    }
+  }, []);
+
+  const onResolved = useCallback(() => {
+    const current = activeRef.current;
+    if (!current) return;
+    close(current, resultFor(current));
+  }, [close, resultFor]);
+
   const startFlow = useCallback(
-    (args: {
-      linkToken: string;
-      resolve: (result: PaymentResult) => void;
-      onSessionLoaded?: (linkSessionId: string) => void;
-    }) => {
+    (args: { reference: string; resolve: (result: PaymentResult) => void }) => {
       if (activeRef.current) {
-        log.warning('start: a payment flow is already in progress — rejecting concurrent call');
+        log.warning('start: a payment is already in progress — rejecting concurrent call');
         args.resolve(
           paymentFailed({
-            linkToken: args.linkToken,
+            reference: args.reference,
             errorCode: 'concurrent_start',
-            message: 'A payment flow is already in progress.',
+            message: 'A payment is already in progress.',
             resolvedAtMs: Date.now(),
           }),
         );
@@ -123,159 +149,142 @@ export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
       }
 
       log.info(`start: tenant=${spareLink.tenant}, environment=${spareLink.environment}`);
-      const controller = new PaymentFlowController({
-        sessionToken: args.linkToken,
-        environment: spareLink.environment,
-        apiClient: new LinkApiClient({
-          baseUrl: spareLink.resolvedBaseUrl,
-          tenant: tenantCountryCode(spareLink.tenant),
-          ...(spareLink.fetch ? { fetch: spareLink.fetch } : {}),
-          ...(spareLink.requestTimeoutMs !== undefined
-            ? { requestTimeoutMs: spareLink.requestTimeoutMs }
-            : {}),
-        }),
-        collectTelemetry,
-        ...(pendingSessionStore ? { pendingSessionStore } : {}),
-        onEvent: (event) => {
-          emitMappedEvent(args.linkToken, event as SpareLinkEventType);
-          if (event === 'sessionLoaded') {
-            const linkSessionId = controller.state.linkSessionId;
-            if (linkSessionId) {
-              args.onSessionLoaded?.(linkSessionId);
-            }
-          }
-        },
+
+      const controller = new HostedFlowController({
+        reference: args.reference,
+        ...(launchBankRedirect ? { bankLauncher: launchBankRedirect } : {}),
       });
 
       const flow: ActiveFlow = {
         controller,
-        linkToken: args.linkToken,
+        reference: args.reference,
         resolve: args.resolve,
-        ...(args.onSessionLoaded ? { onSessionLoaded: args.onSessionLoaded } : {}),
       };
-      activeRef.current = flow;
-      setActive(flow);
 
-      void controller.hydrate().catch((err) => {
-        log.severe(`start: hydration failed — ${err instanceof Error ? err.message : String(err)}`);
-        close(
-          flow,
-          paymentFailed({
-            linkToken: args.linkToken,
-            errorCode: 'hydration_error',
-            message: 'Unable to load payment session. Please try again.',
-            resolvedAtMs: Date.now(),
-          }),
-        );
+      controller.subscribe(() => {
+        const phase = controller.state.phase;
+        if (phase === 'hosted') {
+          spareLink.emitEvent(SpareLinkEvents.pageReady(args.reference));
+        } else if (phase === 'redirecting') {
+          spareLink.emitEvent(SpareLinkEvents.redirectToBank(args.reference));
+        }
       });
+
+      // Claimed synchronously so a second `start` in the same tick is rejected by
+      // the guard above rather than racing this one.
+      activeRef.current = flow;
+
+      // Recorded *before* the page is presented, so the payer cannot reach their
+      // bank on a payment a cold start would not know about. A store that cannot
+      // write is not a reason to refuse the payment.
+      const present = () => {
+        if (activeRef.current !== flow) return;
+        setActive(flow);
+
+        // A return can beat the page onto the screen when the app was resumed
+        // rather than launched, so replay one that arrived before there was a flow.
+        const buffered = bufferedRedirect.current;
+        if (buffered) {
+          bufferedRedirect.current = null;
+          controller.handleReturn(buffered);
+        }
+      };
+
+      if (!pendingSessionStore) {
+        present();
+        return;
+      }
+
+      void enqueuePersist(() => pendingSessionStore.save({ reference: args.reference }))
+        .catch(() => {
+          log.warning('could not record the pending payment — continuing');
+        })
+        .finally(present);
     },
-    [spareLink, pendingSessionStore, emitMappedEvent, close],
+    [spareLink, pendingSessionStore, launchBankRedirect, enqueuePersist],
   );
 
   const handleRedirect = useCallback(
     async (uri: URL | string): Promise<boolean> => {
-      const current = activeRef.current;
       const asString = typeof uri === 'string' ? uri : uri.toString();
+      log.info(`handleRedirect: ${redactPaymentReturnUri(asString)}`);
+
+      if (!isPaymentReturnCallbackUri(asString)) return false;
+
+      const current = activeRef.current;
       if (!current) {
-        if (!isPaymentReturnCallbackUri(asString)) {
-          log.fine('handleRedirect: URI does not belong to payment flow — ignoring');
-          return false;
-        }
-        setBufferedRedirect(asString);
-        log.info('handleRedirect: no active controller — buffering URI for recovery');
+        log.info('handleRedirect: no active payment — holding for recovery');
+        bufferedRedirect.current = asString;
         return true;
       }
-      if (!isPaymentReturnCallbackUri(asString)) {
-        log.fine('handleRedirect: URI does not belong to payment flow — ignoring');
-        return false;
-      }
-      log.info('handleRedirect: forwarding to controller');
-      try {
-        current.controller.handleCallback(uri);
-        spareLink.emitEvent(SpareLinkEvents.bankCallbackReceived(current.linkToken));
-        return true;
-      } catch {
-        return false;
-      }
-    },
-    [spareLink],
-  );
 
-  const openRecoveryFlow = useCallback(
-    (args: {
-      controller: PaymentFlowController;
-      linkToken: string;
-      resolve?: (result: PaymentResult) => void;
-    }) => {
-      if (activeRef.current) {
-        args.controller.dispose();
-        return;
-      }
-      const flow: ActiveFlow = {
-        controller: args.controller,
-        linkToken: args.linkToken,
-        resolve:
-          args.resolve ??
-          (() => {
-            /* recovery UI only */
-          }),
-      };
-      activeRef.current = flow;
-      setActive(flow);
-      spareLink.emitEvent(SpareLinkEvents.initialized(args.linkToken));
+      spareLink.emitEvent(SpareLinkEvents.bankCallbackReceived(current.reference));
+      current.controller.handleReturn(asString);
+      return true;
     },
     [spareLink],
   );
 
   const resumeIfNeeded = useCallback(async (): Promise<RecoveryResult> => {
-    if (!pendingSessionStore) {
+    if (activeRef.current) return noRecovery('flowAlreadyActive');
+    if (!pendingSessionStore) return noRecovery('persistenceUnavailable');
+
+    let record: { reference: string } | null = null;
+    try {
+      record = await pendingSessionStore.load();
+    } catch {
+      log.warning('resumeIfNeeded: could not read the pending payment');
       return noRecovery('persistenceUnavailable');
     }
-    if (activeRef.current) {
-      return noRecovery('flowAlreadyActive');
-    }
 
-    let flowOpened = false;
-    let openedLinkToken: string | undefined;
-
-    const terminal = await executeResumeIfNeeded(
-      {
-        config: {
-          environment: spareLink.environment,
-          tenant: spareLink.tenant,
-          ...(spareLink.baseUrl ? { baseUrl: spareLink.baseUrl } : {}),
-          ...(spareLink.fetch ? { fetch: spareLink.fetch } : {}),
-          ...(spareLink.requestTimeoutMs !== undefined
-            ? { requestTimeoutMs: spareLink.requestTimeoutMs }
-            : {}),
-        },
-      },
-      {
-        pendingSessionStore,
-        isFlowActive: () => activeRef.current != null,
-        openRecoveryFlow: ({ controller, config }) => {
-          flowOpened = true;
-          openedLinkToken = config.linkToken;
-          openRecoveryFlow({
-            controller,
-            linkToken: config.linkToken,
-            resolve: (result) => {
-              spareLink.emitTerminal(result);
-            },
-          });
-        },
-      },
-    );
+    if (!record) return noRecovery('noPendingSession');
 
-    if (terminal) {
-      spareLink.emitTerminal(terminal);
-      return { kind: 'recovered', result: terminal };
-    }
-    if (flowOpened && openedLinkToken) {
-      return mapHostRecovery({ kind: 'inProgress', linkToken: openedLinkToken });
+    const buffered = bufferedRedirect.current;
+    if (buffered) {
+      const { outcome, report } = readPaymentReturn(buffered);
+
+      // The buffered link is only this payment's if it says so. Pairing whatever
+      // arrived with whatever was persisted is how a callback for one payment
+      // resolves another.
+      if (report.reference !== undefined && report.reference !== record.reference) {
+        log.warning('resumeIfNeeded: the buffered return names a different payment — keeping it');
+        return noRecovery('outcomeUnknown', record.reference);
+      }
+
+      bufferedRedirect.current = null;
+      clearPending();
+
+      const base = {
+        reference: record.reference,
+        ...reportedFields(report),
+        resolvedAtMs: Date.now(),
+      };
+
+      // A return that did not say what happened is not a failure — the backend
+      // holds the outcome, which is what `outcomeUnknown` tells the caller.
+      if (outcome === 'unknown') {
+        log.info('resumeIfNeeded: the buffered return did not say what happened');
+        return noRecovery('outcomeUnknown', record.reference);
+      }
+
+      const result: PaymentResult =
+        outcome === 'processed'
+          ? paymentSuccess(base)
+          : paymentFailed({
+              ...base,
+              errorCode: report.errorCode ?? 'authorize_failed',
+            });
+
+      spareLink.emitTerminal(result);
+      return { kind: 'recovered', result };
     }
-    return noRecovery('noPendingSession');
-  }, [pendingSessionStore, spareLink, openRecoveryFlow]);
+
+    log.info(
+      'resumeIfNeeded: a payment was pending and no return arrived — the backend holds the outcome',
+    );
+    clearPending();
+    return noRecovery('outcomeUnknown', record.reference);
+  }, [pendingSessionStore, spareLink, clearPending]);
 
   useEffect(() => {
     const detach = spareLink._attachHost({
@@ -287,67 +296,34 @@ export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
     return detach;
   }, [spareLink, startFlow, handleRedirect, resumeIfNeeded]);
 
-  const onResolved = useCallback(() => {
+  /**
+   * A dismiss mid-flow means the payer left, which the caller must hear about — a
+   * silent close would strand whoever is awaiting the result.
+   */
+  const onDismissPressed = useCallback(() => {
     const current = activeRef.current;
     if (!current) return;
-    const s = current.controller.state;
-    let result: PaymentResult;
-    switch (s.phase) {
-      case 'succeeded':
-        result = paymentSuccess({
-          linkToken: current.linkToken,
-          ...(s.exchangeCode ? { exchangeCode: s.exchangeCode } : {}),
-          ...(s.linkSessionId ? { linkSessionId: s.linkSessionId } : {}),
-          ...(s.merchantRef ? { merchantRef: s.merchantRef } : {}),
-          ...(s.selectedProvider ? { bankId: s.selectedProvider.id } : {}),
-          ...(s.session?.request?.type ? { paymentType: s.session.request.type } : {}),
-          resolvedAtMs: Date.now(),
-        });
-        break;
-      case 'failed': {
-        const errorCode = s.errorCode ?? 'unknown_error';
-        result = paymentFailed({
-          linkToken: current.linkToken,
-          errorCode,
-          message: userFriendlyMessageFor(errorCode),
-          resolvedAtMs: Date.now(),
-        });
-        break;
-      }
-      case 'cancelled':
-        result = paymentCancelled({
-          linkToken: current.linkToken,
-          resolvedAtMs: Date.now(),
-        });
-        break;
-      default:
-        result = paymentAbandoned({
-          linkToken: current.linkToken,
-          resolvedAtMs: Date.now(),
-        });
-        break;
-    }
-    close(current, result);
-  }, [close]);
+    current.controller.abandon();
+    close(current, resultFor(current));
+  }, [close, resultFor]);
 
-  const onDismissPressed = useCallback(() => {
-    const current = activeRef.current;
-    if (!current) {
-      onResolved();
-      return;
+  const modalBody = useMemo(() => {
+    if (!active) return null;
+    if (!fontsLoaded) {
+      return (
+        <View style={styles.fontLoading}>
+          <ActivityIndicator size="large" color={Colors.spareBlue} />
+        </View>
+      );
     }
-    spareLink.emitEvent(
-      SpareLinkEvents.abandoned(
-        paymentAbandoned({ linkToken: current.linkToken, resolvedAtMs: Date.now() }),
-      ),
+    return (
+      <HostedPaymentPage
+        controller={active.controller}
+        baseUrl={spareLink.resolvedBaseUrl}
+        onResolved={onResolved}
+      />
     );
-    void current.controller.cancel().finally(onResolved);
-  }, [onResolved, spareLink]);
-
-  const launcher = useMemo(
-    () => launchBankRedirect ?? defaultLaunchBankRedirect,
-    [launchBankRedirect],
-  );
+  }, [active, fontsLoaded, spareLink, onResolved]);
 
   return (
     <>
@@ -366,21 +342,7 @@ export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
           testID="spare-link-modal-root"
         >
           <ModalDismissButton visible={showDismissButton} onPress={onDismissPressed} />
-          {active ? (
-            <View style={styles.flowWrap}>
-              {fontsLoaded ? (
-                <PaymentFlowPage
-                  controller={active.controller}
-                  onResolved={onResolved}
-                  launchBankRedirect={launcher}
-                />
-              ) : (
-                <View style={styles.fontLoading}>
-                  <ActivityIndicator size="large" color={Colors.spareBlue} />
-                </View>
-              )}
-            </View>
-          ) : null}
+          {active ? <View style={styles.flowWrap}>{modalBody}</View> : null}
         </SafeAreaView>
       </Modal>
     </>
@@ -392,3 +354,21 @@ const styles = StyleSheet.create({
   flowWrap: { flex: 1 },
   fontLoading: { flex: 1, alignItems: 'center', justifyContent: 'center' },
 });
+
+/**
+ * Lifts what the return reported onto the result the caller awaits.
+ *
+ * `errorCode` is not among them: a failure's code has a fallback the report does
+ * not, so it is set where the failure is built.
+ */
+function reportedFields(report: PaymentReturnReport | undefined) {
+  if (!report) return {};
+  return {
+    ...(report.merchantRef ? { merchantRef: report.merchantRef } : {}),
+    ...(report.paymentId ? { paymentId: report.paymentId } : {}),
+    ...(report.mandateId ? { mandateId: report.mandateId } : {}),
+    ...(report.signature ? { signature: report.signature } : {}),
+    ...(report.errorReason ? { errorReason: report.errorReason } : {}),
+    ...(report.errorDescription ? { message: report.errorDescription } : {}),
+  };
+}

package/src/ui/widgets/index.ts

@@ -1,5 +1,4 @@
-export { CustomStepper, type CustomStepperProps } from './stepper';
-export { LayoutWHeader, type LayoutWHeaderProps } from './layout-w-header';
 export { Footer, type FooterProps } from './footer';
 export { GradientSpinner, type GradientSpinnerProps } from './gradient-spinner';
 export { HandoffScreenLayout, type HandoffScreenLayoutProps } from './handoff-screen-layout';
+export { ModalDismissButton, type ModalDismissButtonProps } from './modal-dismiss-button';

package/src/version.ts

@@ -1,7 +1,9 @@
 /**
- * SDK version reported in telemetry and the default User-Agent. This file is
- * regenerated from `package.json` by the root `version` npm script on every
- * release bump (see the `version` script in the repo-root package.json), so it
- * always matches the published version — do not edit the literal by hand.
+ * SDK version reported in telemetry and the default User-Agent.
+ *
+ * GENERATED FILE — do not edit by hand. Written from package.json by
+ * scripts/sync-sdk-version.mjs (run by the root `version` npm script after
+ * `changeset version`). The src/index.ts smoke test asserts this matches
+ * package.json's version.
  */
-export const SDK_VERSION = '0.1.0-beta.0' as const;
+export const SDK_VERSION = '1.0.0' as const;