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

package/src/ui/hooks/use-hosted-flow-state.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from 'react';
+import type { HostedFlowController } from '../../core/services/hosted-flow-controller';
+import type { HostedFlowState } from '../../core/services/hosted-flow-state';
+
+/**
+ * React hook that bridges {@link HostedFlowController}'s observable to the
+ * component tree via `useSyncExternalStore`. Re-renders when the controller
+ * notifies a new state.
+ */
+export function useHostedFlowState(controller: HostedFlowController): HostedFlowState {
+  return useSyncExternalStore(
+    (notify) => controller.subscribe(notify),
+    () => controller.state,
+    () => controller.state,
+  );
+}

package/src/ui/hosted/hosted-payment-page.tsx

@@ -0,0 +1,178 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { ActivityIndicator, StyleSheet, Text, View } from 'react-native';
+import type { HostedFlowController } from '../../core/services/hosted-flow-controller';
+import { isTerminalPhase } from '../../core/services/hosted-flow-state';
+import { useHostedFlowState } from '../hooks/use-hosted-flow-state';
+import { PageUnavailableScreen } from '../screens/page-unavailable-screen';
+import { RedirectHandoffScreen } from '../screens/redirect-handoff-screen';
+import { ResultScreen } from '../screens/result-screen';
+import { ResumeProcessingScreen } from '../screens/resume-processing-screen';
+import { Colors, Spacing, Typography } from '../theme';
+import { HostedPaymentWebView } from './hosted-payment-webview';
+
+/** How long a resolved outcome stays on screen before the flow hands back. */
+const RESULT_DWELL_MS = 1200;
+
+export interface HostedPaymentPageProps {
+  controller: HostedFlowController;
+  /** Resolved API base URL — the hosted page is served from the same host. */
+  baseUrl: string;
+  /** Called once the outcome has been shown and the flow should hand back. */
+  onResolved: () => void;
+}
+
+/**
+ * The screen a payer sees for the whole flow.
+ *
+ * Most of it is the hosted page. The native screens cover the moments the page
+ * cannot: while it loads, while the payer is away at their bank, and once there is
+ * an outcome to report.
+ */
+export function HostedPaymentPage(props: HostedPaymentPageProps): JSX.Element {
+  const { controller, baseUrl, onResolved } = props;
+  const state = useHostedFlowState(controller);
+
+  /**
+   * When the payer left for the bank.
+   *
+   * Held here rather than in the waiting screen because returning from the browser
+   * can remount it, and a fresh component would otherwise restart the wait from
+   * zero and never offer the payer a way out.
+   */
+  const awaitingSinceMs = useRef<number | undefined>(undefined);
+  if (state.phase === 'awaitingCallback' && awaitingSinceMs.current === undefined) {
+    awaitingSinceMs.current = Date.now();
+  }
+
+  // Only a page that was *never reached* gets the recovery treatment: the payer
+  // already read why and chose to leave, so there is nothing to report back and no
+  // reason to show a result screen on the way out.
+  //
+  // A page that failed after it was working (`page_lost`) is a different case. It
+  // is terminal, so a retry there would render a button that does nothing, and the
+  // payer has not read anything yet — they get the result screen.
+  const wasNeverReached = state.errorCode === 'page_unavailable';
+
+  // Leaves the outcome on screen briefly, then hands it to the caller. Resolving in
+  // the same frame the outcome arrives would flash the result past a payer who has
+  // been waiting on it.
+  const resolved = isTerminalPhase(state.phase);
+  useEffect(() => {
+    if (!resolved) return;
+    const timer = setTimeout(onResolved, wasNeverReached ? 0 : RESULT_DWELL_MS);
+    return () => clearTimeout(timer);
+  }, [resolved, onResolved, wasNeverReached]);
+
+  const handleBridgeMessage = useCallback(
+    (message: unknown) => {
+      void controller.handleBridgeMessage(message);
+    },
+    [controller],
+  );
+
+  const handleLoadFailure = useCallback(() => {
+    controller.failToLoad();
+  }, [controller]);
+
+  const handlePageMounted = useCallback(() => {
+    controller.reportPageMounted();
+  }, [controller]);
+
+  const handleRetry = useCallback(() => {
+    controller.retry();
+  }, [controller]);
+
+  const handleGiveUp = useCallback(() => {
+    controller.giveUp();
+  }, [controller]);
+
+  switch (state.phase) {
+    case 'loading':
+    case 'hosted':
+      return (
+        <View style={styles.fill}>
+          <View
+            style={styles.fill}
+            // While covered the page is not just invisible but unreachable: left
+            // in the tree, a screen reader could act on content nobody can see.
+            accessibilityElementsHidden={state.phase === 'loading'}
+            importantForAccessibility={state.phase === 'loading' ? 'no-hide-descendants' : 'auto'}
+          >
+            <HostedPaymentWebView
+              // Keyed on the attempt so a retry mounts a fresh webview. Reusing the
+              // instance that failed would show the payer the same dead frame.
+              key={state.attempt}
+              baseUrl={baseUrl}
+              reference={controller.reference}
+              onBridgeMessage={handleBridgeMessage}
+              onLoadFailure={handleLoadFailure}
+              onMounted={handlePageMounted}
+            />
+          </View>
+          {/*
+            The webview is a blank frame until the page paints, and a retry starts
+            that over. Covered rather than tinted, so the payer sees something
+            happening instead of a white void they cannot interpret.
+          */}
+          {state.phase === 'loading' ? (
+            <View style={styles.loadingCover} testID="hosted-payment-loading">
+              {/*
+                Not GradientSpinner: its stops run white → teal → white and its
+                no-SVG fallback draws a white top border, so on a white cover
+                most of the arc would be invisible — the opposite of the point.
+              */}
+              <ActivityIndicator
+                size="large"
+                color={Colors.spareBlue}
+                testID="hosted-payment-loading-spinner"
+              />
+              <Text style={[Typography.bodyMuted, styles.loadingLabel]}>
+                {state.attempt > 1 ? 'Trying again…' : 'Loading your payment…'}
+              </Text>
+            </View>
+          ) : null}
+        </View>
+      );
+    case 'unreachable':
+      return <PageUnavailableScreen onRetry={handleRetry} onCancel={handleGiveUp} />;
+    case 'redirecting':
+      return <RedirectHandoffScreen />;
+    case 'awaitingCallback':
+      return (
+        <ResumeProcessingScreen
+          {...(awaitingSinceMs.current !== undefined
+            ? { awaitingCallbackStartedAtMs: awaitingSinceMs.current }
+            : {})}
+          // The bank may never send the payer back. This is their way out of a
+          // screen that would otherwise wait forever. It reports the flow as
+          // unresolved rather than cancelled, because a payer who authorized and
+          // then lost the return has still paid.
+          onCancel={() => controller.abandon()}
+        />
+      );
+    case 'succeeded':
+      return <ResultScreen title="Payment complete" isSuccess onDone={onResolved} />;
+    case 'failed':
+      return wasNeverReached ? (
+        <PageUnavailableScreen onRetry={handleRetry} onCancel={handleGiveUp} />
+      ) : (
+        <ResultScreen title="Payment failed" isSuccess={false} onDone={onResolved} />
+      );
+    case 'cancelled':
+      return <ResultScreen title="Payment cancelled" isSuccess={false} onDone={onResolved} />;
+    case 'abandoned':
+      return <ResultScreen title="Payment not completed" isSuccess={false} onDone={onResolved} />;
+  }
+}
+
+const styles = StyleSheet.create({
+  fill: { flex: 1, backgroundColor: Colors.surfacePage },
+  loadingCover: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: Spacing.lg,
+    backgroundColor: Colors.surfacePage,
+  },
+  loadingLabel: { textAlign: 'center' },
+});

package/src/ui/hosted/hosted-payment-webview.tsx

@@ -0,0 +1,164 @@
+import { useCallback, useEffect } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { WebView, type WebViewMessageEvent } from 'react-native-webview';
+import { buildHostedPaymentUrl, isHostedOriginUrl } from '../../internal/hosted/hosted-url';
+import { createLogger } from '../../internal/logger';
+import { parseUrlParts } from '../../internal/url-parts';
+import { Colors } from '../theme';
+
+const log = createLogger('HostedPaymentWebView');
+
+/**
+ * Reduces a URL to scheme and host for logging.
+ *
+ * The path carries the payment request reference, which is the flow's only
+ * credential and stays out of the log. Scheme and host are what distinguish a
+ * misconfigured environment from a service that is down.
+ */
+function safeOrigin(url: string): string {
+  const parts = parseUrlParts(url);
+  return parts ? `${parts.scheme}://${parts.host}` : '[unparseable URL]';
+}
+
+/**
+ * Whether a navigation the WebView is about to make should be allowed.
+ *
+ * Only the hosted origin may load in-frame. Bank authentication deliberately
+ * happens in a real browser, so a bank URL arriving here means the page's handoff
+ * did not reach us — following it would put the payer on a bank page with no
+ * address bar, which is the signal they rely on to tell a real one from a copy.
+ * Kept as a plain function because the WebView does not render under Jest, and
+ * this is the part worth testing.
+ */
+export function shouldAllowHostedNavigation(args: { baseUrl: string; url: string }): boolean {
+  return isHostedOriginUrl(args);
+}
+
+export interface HostedPaymentWebViewProps {
+  /** Resolved API base URL — the hosted page is served from the same host. */
+  baseUrl: string;
+  /** The payment request this flow is paying. */
+  reference: string;
+  /**
+   * Called with each raw message the page posts. Parsing belongs to the caller so
+   * this component stays a transport.
+   */
+  onBridgeMessage: (message: unknown) => void;
+  /** Called when the page itself could not be loaded. */
+  onLoadFailure?: () => void;
+  /**
+   * Called once this webview is on screen.
+   *
+   * Starts the clock the page has to become interactive, measured from here so
+   * that whatever the host did before rendering is not charged against it.
+   */
+  onMounted?: () => void;
+}
+
+/**
+ * Hosts the hosted payment page.
+ *
+ * The page owns bank selection, the payee check and the consent screen, so this
+ * component carries no payment logic of its own: it loads one URL, forwards what
+ * the page reports, and refuses to navigate anywhere else.
+ */
+export function HostedPaymentWebView(props: HostedPaymentWebViewProps): JSX.Element {
+  const { baseUrl, reference, onBridgeMessage, onLoadFailure, onMounted } = props;
+  const uri = buildHostedPaymentUrl({ baseUrl, reference });
+
+  // This reports that *this* webview exists, and a retry mounts a fresh instance
+  // which reports itself anew. Re-running on a new callback identity would
+  // restart the page's clock without a new page having been asked for.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: mount-only by design
+  useEffect(() => {
+    onMounted?.();
+  }, []);
+
+  const handleMessage = useCallback(
+    (event: WebViewMessageEvent) => {
+      onBridgeMessage(event.nativeEvent.data);
+    },
+    [onBridgeMessage],
+  );
+
+  // Every navigation is routed through here rather than through `originWhitelist`.
+  // A URL that fails the whitelist is handed to `Linking.openURL` by
+  // react-native-webview with no scheme check of its own and without consulting
+  // this callback, which would let the page reach `intent://` or any registered
+  // scheme on the device. Whitelisting everything keeps that branch unreachable
+  // and leaves the decision here, where an off-origin navigation is refused
+  // outright and the bank arrives over the bridge instead.
+  const handleShouldStartLoad = useCallback(
+    ({ url }: { url: string }) => shouldAllowHostedNavigation({ baseUrl, url }),
+    [baseUrl],
+  );
+
+  return (
+    // The page is a full-bleed document that knows nothing about this device's
+    // notch or home indicator. `SpareLinkHost` holds the inset out for the whole
+    // modal, so this fills what it is given.
+    <View style={styles.container} testID="hosted-payment-webview">
+      <WebView
+        source={{ uri }}
+        onMessage={handleMessage}
+        originWhitelist={ALLOW_ALL_ORIGINS}
+        onShouldStartLoadWithRequest={handleShouldStartLoad}
+        // react-native-webview reports only main-frame failures: `onHttpError` is
+        // guarded by `isForMainFrame`, and it overrides the main-frame-only
+        // `onReceivedError` overload. So a 404 on a favicon the WebView asked for
+        // on its own cannot fail the payment.
+        //
+        // What went wrong is logged before it is collapsed into
+        // `page_unavailable`, which on its own cannot tell a service that is down
+        // from a host that was never reachable.
+        onError={({ nativeEvent }) => {
+          log.severe(
+            `could not load the payment page from ${safeOrigin(uri)} ` +
+              `(${nativeEvent.description ?? `code ${nativeEvent.code}`})`,
+          );
+          onLoadFailure?.();
+        }}
+        onHttpError={({ nativeEvent }) => {
+          log.severe(
+            `the payment page at ${safeOrigin(uri)} answered ` + `HTTP ${nativeEvent.statusCode}`,
+          );
+          onLoadFailure?.();
+        }}
+        // A webview whose process dies reports neither of the callbacks above: the
+        // frame simply goes blank and stays blank. iOS terminates the content
+        // process under memory pressure and Android's renderer can be reclaimed
+        // outright, so both are treated as the page having failed to load.
+        onContentProcessDidTerminate={() => {
+          log.severe('the payment page process was terminated by the system (iOS)');
+          onLoadFailure?.();
+        }}
+        onRenderProcessGone={({ nativeEvent }) => {
+          log.severe(
+            `the payment page renderer was lost (Android, crashed=${nativeEvent.didCrash})`,
+          );
+          onLoadFailure?.();
+        }}
+        style={styles.webview}
+        javaScriptEnabled
+        domStorageEnabled
+        // The page holds a payment in progress and nothing else should share its
+        // storage, on this device or between payers on it.
+        incognito
+        // The bank is handed to the OS browser over the bridge, so nothing here
+        // needs popups.
+        setSupportMultipleWindows={false}
+        allowFileAccess={false}
+        allowUniversalAccessFromFileURLs={false}
+        allowFileAccessFromFileURLs={false}
+        testID="hosted-payment-webview-instance"
+      />
+    </View>
+  );
+}
+
+const ALLOW_ALL_ORIGINS = ['*'];
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: Colors.surfacePage },
+  webview: { flex: 1, backgroundColor: Colors.surfacePage },
+});

package/src/ui/screens/index.ts

@@ -1,12 +1,10 @@
-export { BankSelectionScreen, type BankSelectionScreenProps } from './bank-selection-screen';
-export { ConsentDetailsScreen, type ConsentDetailsScreenProps } from './consent-details-screen';
+export {
+  PageUnavailableScreen,
+  type PageUnavailableScreenProps,
+} from './page-unavailable-screen';
 export { RedirectHandoffScreen } from './redirect-handoff-screen';
 export {
   ResumeProcessingScreen,
   type ResumeProcessingScreenProps,
 } from './resume-processing-screen';
 export { ResultScreen, type ResultScreenProps } from './result-screen';
-export {
-  MandateSetupSuccessScreen,
-  type MandateSetupSuccessScreenProps,
-} from './mandate-setup-success-screen';

package/src/ui/screens/page-unavailable-screen.tsx

@@ -0,0 +1,94 @@
+import { Ionicons } from '@expo/vector-icons';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { Colors, Spacing, Typography } from '../theme';
+
+export interface PageUnavailableScreenProps {
+  /** Asks for the payment page again. */
+  onRetry: () => void;
+  /** Gives up and hands the outcome back to the caller. */
+  onCancel: () => void;
+}
+
+/**
+ * Shown when the payment page could not be loaded, or loaded and never became
+ * interactive.
+ *
+ * It deliberately does not say the payment failed. Nothing has been attempted at
+ * this point — no consent, no bank, no money — and telling a payer their payment
+ * failed when the app could not open the page is the one thing they must not be
+ * told. It says what is true, says nothing has been taken, and offers the page
+ * again, because an unreachable service is usually unreachable briefly.
+ */
+export function PageUnavailableScreen(props: PageUnavailableScreenProps): JSX.Element {
+  return (
+    <View style={styles.container} testID="page-unavailable-screen">
+      <View style={styles.iconBubble}>
+        <Ionicons name="cloud-offline-outline" size={36} color={Colors.textMuted} />
+      </View>
+      <Text style={Typography.title} testID="page-unavailable-message">
+        We couldn't reach the payment service
+      </Text>
+      <Text style={[Typography.bodyMuted, styles.centered]}>
+        No payment has been taken. Check your connection and try again.
+      </Text>
+      <Pressable
+        onPress={props.onRetry}
+        accessibilityRole="button"
+        testID="page-unavailable-retry-btn"
+        style={[styles.button, styles.retryButton]}
+      >
+        <Text style={[Typography.button, styles.retryLabel]}>Try again</Text>
+      </Pressable>
+      <Pressable
+        onPress={props.onCancel}
+        accessibilityRole="button"
+        testID="page-unavailable-cancel-btn"
+        style={[styles.button, styles.cancelButton]}
+      >
+        <Text style={[Typography.button, styles.cancelLabel]}>Cancel</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: Spacing.xl,
+    gap: Spacing.lg,
+    backgroundColor: Colors.surfacePage,
+  },
+  iconBubble: {
+    width: 72,
+    height: 72,
+    borderRadius: 36,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: Colors.surfaceMuted,
+  },
+  centered: {
+    textAlign: 'center',
+  },
+  button: {
+    paddingHorizontal: Spacing.xl,
+    paddingVertical: Spacing.md,
+    borderRadius: 12,
+    minWidth: 160,
+    alignItems: 'center',
+  },
+  retryButton: {
+    marginTop: Spacing.md,
+    backgroundColor: Colors.spareBlue,
+  },
+  retryLabel: {
+    color: '#FFFFFF',
+  },
+  cancelButton: {
+    backgroundColor: Colors.surfaceMuted,
+  },
+  cancelLabel: {
+    color: Colors.textPrimary,
+  },
+});