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

package/src/ui/screens/result-screen.tsx

@@ -0,0 +1,71 @@
+import { Ionicons } from '@expo/vector-icons';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { Colors, Spacing, Typography } from '../theme';
+
+export interface ResultScreenProps {
+  title: string;
+  isSuccess: boolean;
+  onDone: () => void;
+}
+
+export function ResultScreen({ title, isSuccess, onDone }: ResultScreenProps): JSX.Element {
+  return (
+    <View style={styles.container} testID="result-screen">
+      <View
+        testID={isSuccess ? 'result-success-icon' : 'result-failure-icon'}
+        style={[
+          styles.iconBubble,
+          { backgroundColor: isSuccess ? Colors.successGreen : Colors.errorRed },
+        ]}
+      >
+        <Ionicons name={isSuccess ? 'checkmark-sharp' : 'close-sharp'} size={40} color="#FFFFFF" />
+      </View>
+      <Text style={Typography.title} testID="result-heading">
+        {isSuccess ? 'Payment complete' : 'Payment failed'}
+      </Text>
+      <Text style={Typography.bodyMuted} testID="result-message">
+        {title}
+      </Text>
+      <Pressable
+        onPress={onDone}
+        accessibilityRole="button"
+        testID="result-done-btn"
+        style={[
+          styles.button,
+          { backgroundColor: isSuccess ? Colors.spareBlue : Colors.surfaceMuted },
+        ]}
+      >
+        <Text style={[Typography.button, { color: isSuccess ? '#FFFFFF' : Colors.textPrimary }]}>
+          Done
+        </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',
+  },
+  iconGlyph: { color: '#FFFFFF', fontSize: 36, fontWeight: '700' },
+  button: {
+    paddingHorizontal: Spacing.xl,
+    paddingVertical: Spacing.md,
+    borderRadius: 12,
+    minWidth: 160,
+    alignItems: 'center',
+    marginTop: Spacing.lg,
+  },
+});

package/src/ui/screens/resume-processing-screen.tsx

@@ -0,0 +1,111 @@
+import { useEffect, useState } from 'react';
+import { Alert, Pressable, StyleSheet, Text, View } from 'react-native';
+import { linkFontFamilyForWeight } from '../theme/fonts';
+import { GradientSpinner } from '../widgets/gradient-spinner';
+import { HandoffScreenLayout } from '../widgets/handoff-screen-layout';
+
+const DEFAULT_CANCEL_DELAY_MS = 30_000;
+
+function confirmCancel(onCancel: () => void): void {
+  Alert.alert(
+    'Cancel payment?',
+    'Your payment may already be processing at the bank. Are you sure you want to cancel?',
+    [
+      { text: 'Continue waiting', style: 'cancel' },
+      { text: 'Cancel payment', style: 'destructive', onPress: onCancel },
+    ],
+  );
+}
+
+export interface ResumeProcessingScreenProps {
+  onCancel?: () => void;
+  /** Cancel button hidden for this long. Defaults to 30s. */
+  cancelButtonDelayMs?: number;
+  /** Awaiting-callback start time from the controller — used so a rebuild
+   *  doesn't restart the cancel delay clock from zero. */
+  awaitingCallbackStartedAtMs?: number;
+}
+
+export function ResumeProcessingScreen(props: ResumeProcessingScreenProps): JSX.Element {
+  const delay = props.cancelButtonDelayMs ?? DEFAULT_CANCEL_DELAY_MS;
+  const [showCancel, setShowCancel] = useState(() => {
+    if (!props.awaitingCallbackStartedAtMs) return false;
+    return Date.now() - props.awaitingCallbackStartedAtMs >= delay;
+  });
+
+  useEffect(() => {
+    if (showCancel) return;
+    const startedAt = props.awaitingCallbackStartedAtMs ?? Date.now();
+    const remaining = Math.max(0, delay - (Date.now() - startedAt));
+    const t = setTimeout(() => setShowCancel(true), remaining);
+    return () => clearTimeout(t);
+  }, [delay, props.awaitingCallbackStartedAtMs, showCancel]);
+
+  return (
+    <HandoffScreenLayout testID="resume-processing-screen">
+      <View style={styles.content}>
+        <GradientSpinner testID="resume-processing-spinner" />
+        <View style={styles.copy}>
+          <Text style={styles.title} testID="resume-processing-message">
+            Confirming your payment…
+          </Text>
+          <Text style={styles.subtitle}>Please don't close the app.</Text>
+        </View>
+        {showCancel && props.onCancel ? (
+          <Pressable
+            onPress={() => {
+              const onCancel = props.onCancel;
+              if (onCancel) confirmCancel(onCancel);
+            }}
+            accessibilityRole="button"
+            testID="resume-processing-cancel-btn"
+            style={styles.cancelButton}
+          >
+            <Text style={styles.cancelLabel}>Cancel payment</Text>
+          </Pressable>
+        ) : null}
+      </View>
+    </HandoffScreenLayout>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: {
+    alignItems: 'center',
+  },
+  copy: {
+    alignItems: 'center',
+    gap: 12,
+    marginTop: 32,
+  },
+  title: {
+    fontFamily: linkFontFamilyForWeight('600'),
+    fontSize: 20,
+    fontWeight: '600',
+    color: '#FFFFFF',
+    textAlign: 'center',
+    lineHeight: 26,
+  },
+  subtitle: {
+    fontFamily: linkFontFamilyForWeight('400'),
+    fontSize: 15,
+    fontWeight: '400',
+    color: 'rgba(255,255,255,0.7)',
+    textAlign: 'center',
+    lineHeight: 22,
+  },
+  cancelButton: {
+    marginTop: 20,
+    paddingVertical: 12,
+    paddingHorizontal: 32,
+    borderRadius: 24,
+    borderWidth: 1,
+    borderColor: 'rgba(255,255,255,0.38)',
+  },
+  cancelLabel: {
+    fontFamily: linkFontFamilyForWeight('500'),
+    fontSize: 15,
+    fontWeight: '500',
+    color: 'rgba(255,255,255,0.7)',
+  },
+});

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

@@ -0,0 +1,394 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { ActivityIndicator, Modal, SafeAreaView, StyleSheet, View } from 'react-native';
+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 { 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 type { PaymentResult } from '../public/payment-result';
+import {
+  paymentAbandoned,
+  paymentCancelled,
+  paymentFailed,
+  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 { Colors } from './theme';
+import { useLinkFonts } from './theme/fonts';
+import { ModalDismissButton } from './widgets/modal-dismiss-button';
+
+enableScreens();
+
+const log = createLogger('SpareLinkHost');
+
+interface ActiveFlow {
+  controller: PaymentFlowController;
+  linkToken: string;
+  resolve: (result: PaymentResult) => void;
+  onSessionLoaded?: (linkSessionId: string) => void;
+}
+
+export interface SpareLinkHostProps {
+  /** Instance this host wires UI and recovery to. */
+  spareLink: SpareLink;
+  /**
+   * Override the instance's pending session store for this mount.
+   * When omitted, uses `spareLink.pendingSessionStore`.
+   */
+  pendingSessionStore?: PendingSessionStore;
+  launchBankRedirect?: (args: { authorizationUrl: string; mobileAppUrl?: string }) => Promise<void>;
+  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).
+ */
+export function SpareLinkHost(props: SpareLinkHostProps): JSX.Element {
+  const { spareLink, showDismissButton = true, launchBankRedirect } = props;
+  const pendingSessionStore = props.pendingSessionStore ?? spareLink.pendingSessionStore;
+  const fontsLoaded = useLinkFonts();
+  const [active, setActive] = useState<ActiveFlow | null>(null);
+  const activeRef = useRef<ActiveFlow | 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],
+  );
+
+  const close = useCallback(
+    (flow: ActiveFlow, result: PaymentResult) => {
+      void pendingSessionStore?.clear().catch(() => {
+        log.warning('close: pendingSessionStore.clear() failed — continuing');
+      });
+      flow.resolve(result);
+      flow.controller.dispose();
+      if (activeRef.current === flow) {
+        activeRef.current = null;
+        setActive(null);
+      }
+    },
+    [pendingSessionStore],
+  );
+
+  const startFlow = useCallback(
+    (args: {
+      linkToken: string;
+      resolve: (result: PaymentResult) => void;
+      onSessionLoaded?: (linkSessionId: string) => void;
+    }) => {
+      if (activeRef.current) {
+        log.warning('start: a payment flow is already in progress — rejecting concurrent call');
+        args.resolve(
+          paymentFailed({
+            linkToken: args.linkToken,
+            errorCode: 'concurrent_start',
+            message: 'A payment flow is already in progress.',
+            resolvedAtMs: Date.now(),
+          }),
+        );
+        return;
+      }
+
+      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 flow: ActiveFlow = {
+        controller,
+        linkToken: args.linkToken,
+        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(),
+          }),
+        );
+      });
+    },
+    [spareLink, pendingSessionStore, emitMappedEvent, close],
+  );
+
+  const handleRedirect = useCallback(
+    async (uri: URL | string): Promise<boolean> => {
+      const current = activeRef.current;
+      const asString = typeof uri === 'string' ? uri : uri.toString();
+      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');
+        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],
+  );
+
+  const resumeIfNeeded = useCallback(async (): Promise<RecoveryResult> => {
+    if (!pendingSessionStore) {
+      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 (terminal) {
+      spareLink.emitTerminal(terminal);
+      return { kind: 'recovered', result: terminal };
+    }
+    if (flowOpened && openedLinkToken) {
+      return mapHostRecovery({ kind: 'inProgress', linkToken: openedLinkToken });
+    }
+    return noRecovery('noPendingSession');
+  }, [pendingSessionStore, spareLink, openRecoveryFlow]);
+
+  useEffect(() => {
+    const detach = spareLink._attachHost({
+      startFlow,
+      handleRedirect,
+      resumeIfNeeded,
+      isFlowActive: () => activeRef.current != null,
+    });
+    return detach;
+  }, [spareLink, startFlow, handleRedirect, resumeIfNeeded]);
+
+  const onResolved = 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]);
+
+  const onDismissPressed = useCallback(() => {
+    const current = activeRef.current;
+    if (!current) {
+      onResolved();
+      return;
+    }
+    spareLink.emitEvent(
+      SpareLinkEvents.abandoned(
+        paymentAbandoned({ linkToken: current.linkToken, resolvedAtMs: Date.now() }),
+      ),
+    );
+    void current.controller.cancel().finally(onResolved);
+  }, [onResolved, spareLink]);
+
+  const launcher = useMemo(
+    () => launchBankRedirect ?? defaultLaunchBankRedirect,
+    [launchBankRedirect],
+  );
+
+  return (
+    <>
+      {props.children}
+      <Modal
+        animationType="slide"
+        visible={!!active}
+        onRequestClose={onDismissPressed}
+        presentationStyle="overFullScreen"
+        testID="spare-link-modal"
+      >
+        <SafeAreaView
+          accessibilityViewIsModal
+          accessibilityRole="alert"
+          style={styles.modalRoot}
+          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}
+        </SafeAreaView>
+      </Modal>
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  modalRoot: { flex: 1, backgroundColor: Colors.surfacePage },
+  flowWrap: { flex: 1 },
+  fontLoading: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+});

package/src/ui/theme/assets.ts

@@ -0,0 +1,17 @@
+import type { ImageSourcePropType } from 'react-native';
+
+/**
+ * Bundled image assets for the Spare Link checkout UI. Mirrors Flutter's
+ * `ConsentAssets` (`lib/src/ui/theme/assets.dart`). The PNGs live in
+ * `packages/spare-link-rn/assets/images/` and are resolved by Metro at build
+ * time via `require`, so they ship with the SDK package (`files` includes
+ * `assets`).
+ */
+export const Assets = {
+  spareLogo: require('../../../assets/images/spare_logo.png') as ImageSourcePropType,
+  altareqIconMini: require('../../../assets/images/altareq_logo_mini.png') as ImageSourcePropType,
+  altareqLogoWhiteBg:
+    require('../../../assets/images/altareq_logo_white_bg.png') as ImageSourcePropType,
+  altareqLogoTransparentBg:
+    require('../../../assets/images/altareq_logo_transparent_bg.png') as ImageSourcePropType,
+} as const;

package/src/ui/theme/colors.ts

@@ -0,0 +1,32 @@
+/** Color palette for the Spare Link checkout UI. */
+export const Colors = {
+  textPrimary: '#000000',
+  textLabel: '#030732',
+  textMuted: '#868E96',
+  textSubtle: '#56575B',
+  surfaceCard: '#FFFFFF',
+  surfaceMuted: '#EDEDF0',
+  surfacePage: '#FFFFFF',
+  divider: '#D8D8D8',
+  spareBlue: '#2F5BFF',
+  errorRed: '#E5484D',
+  successGreen: '#30A46C',
+  gradientStart: '#28D0CF',
+  gradientMid: '#4F75FF',
+  gradientEnd: '#0B1E5E',
+  /** Redirect / awaiting-callback screens — matches Flutter handoff gradient. */
+  handoffGradientStart: '#00C8AF',
+  handoffGradientMid: '#0070D8',
+  handoffGradientEnd: '#001A6E',
+  buttonDisabled: '#C4C4C4',
+  cardMutedBg: '#F7F7F7',
+} as const;
+
+export type ColorToken = keyof typeof Colors;
+
+/** Flutter `RedirectHandoffScreen` / `ResumeProcessingScreen` gradient stops. */
+export const HandoffGradient = {
+  start: Colors.handoffGradientStart,
+  mid: Colors.handoffGradientMid,
+  end: Colors.handoffGradientEnd,
+} as const;

package/src/ui/theme/fonts.ts

@@ -0,0 +1,25 @@
+import { useFonts } from 'expo-font';
+import type { TextStyle } from 'react-native';
+
+export const FONT_FAMILY = 'MetroSans-Regular';
+
+export const LINK_FONT_MAP = {
+  'MetroSans-Light': require('../../../assets/fonts/MetroSans-Light.otf'),
+  'MetroSans-Regular': require('../../../assets/fonts/MetroSans-Regular.otf'),
+  'MetroSans-Medium': require('../../../assets/fonts/MetroSans-Medium.otf'),
+  'MetroSans-SemiBold': require('../../../assets/fonts/MetroSans-SemiBold.otf'),
+  'MetroSans-Bold': require('../../../assets/fonts/MetroSans-Bold.otf'),
+} as const;
+
+export function useLinkFonts(): boolean {
+  const [loaded] = useFonts(LINK_FONT_MAP);
+  return loaded;
+}
+
+export function linkFontFamilyForWeight(weight: TextStyle['fontWeight']): string {
+  if (weight === '700' || weight === 'bold') return 'MetroSans-Bold';
+  if (weight === '600') return 'MetroSans-SemiBold';
+  if (weight === '500') return 'MetroSans-Medium';
+  if (weight === '300' || weight === '200' || weight === '100') return 'MetroSans-Light';
+  return 'MetroSans-Regular';
+}

package/src/ui/theme/index.ts

@@ -0,0 +1,11 @@
+export { Colors, type ColorToken, HandoffGradient } from './colors';
+export { Typography, FONT_FAMILY, linkFontFamilyForWeight, useLinkFonts } from './typography';
+
+export const Spacing = {
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 24,
+  xxl: 32,
+} as const;