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

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

@@ -0,0 +1,254 @@
+import { useEffect, useRef, useState } from 'react';
+import { ActivityIndicator, StyleSheet, View } from 'react-native';
+import { Text } from 'react-native';
+import { isMultiPayment, resolvedPaymentType } from '../core/models/payment-type';
+import { summaryFromState } from '../core/services/consent-presenter';
+import {
+  buildMultiPaymentRules,
+  rulesSectionTitle,
+} from '../core/services/multi-payment-rules-presenter';
+import type { PaymentFlowController } from '../core/services/payment-flow-controller';
+import { userFriendlyMessageFor } from '../core/services/user-friendly-messages';
+import { DEFAULT_AWAITING_CALLBACK_POLL_MS } from '../public/constants';
+import type { SpareLinkCallbacks } from '../public/spare-link-callbacks';
+import { usePaymentFlowState } from './hooks/use-payment-flow-state';
+import { BankSelectionScreen } from './screens/bank-selection-screen';
+import { ConsentDetailsScreen } from './screens/consent-details-screen';
+import { MandateSetupSuccessScreen } from './screens/mandate-setup-success-screen';
+import { RedirectHandoffScreen } from './screens/redirect-handoff-screen';
+import { ResultScreen } from './screens/result-screen';
+import { ResumeProcessingScreen } from './screens/resume-processing-screen';
+import { Colors, Typography } from './theme';
+
+export interface PaymentFlowPageProps {
+  controller: PaymentFlowController;
+  /** Called when the flow resolves to a terminal phase. Hosts the Modal close. */
+  onResolved: () => void;
+  callbacks?: SpareLinkCallbacks;
+  /**
+   * Bank redirect launcher. Defaults to a noop in tests (the SDK substitutes
+   * the real `BankRedirect.launch` in {@link SpareLinkHost}). Receives the
+   * consent's `authorizationUrl` (+ optional bank `mobileAppUrl`) and returns
+   * once the system has handed off to the bank.
+   */
+  launchBankRedirect?: (args: { authorizationUrl: string; mobileAppUrl?: string }) => Promise<void>;
+}
+
+export function PaymentFlowPage(props: PaymentFlowPageProps): JSX.Element {
+  const { controller, onResolved, launchBankRedirect } = props;
+  const state = usePaymentFlowState(controller);
+  const [processing, setProcessing] = useState(false);
+  const [mandateAcknowledged, setMandateAcknowledged] = useState(false);
+  const hydratedRef = useRef(false);
+  const terminalFiredRef = useRef(false);
+  const mandateClosedRef = useRef(false);
+
+  useEffect(() => {
+    if (hydratedRef.current) return;
+    hydratedRef.current = true;
+    // Recovery parks at awaitingCallback before mount (Flutter parity) — GET /link
+    // is one-time and must not be called again on resume.
+    if (controller.state.phase !== 'idle') return;
+    void controller.hydrate().catch(() => {
+      // hydrate already setStates failed — callback will fire below.
+    });
+  }, [controller]);
+
+  // Launch bank redirect once we hit `redirecting`.
+  useEffect(() => {
+    if (state.phase !== 'redirecting' || !state.consent) return;
+    const consent = state.consent;
+    let cancelled = false;
+    (async () => {
+      try {
+        await launchBankRedirect?.({
+          authorizationUrl: consent.redirectUrl,
+          ...(consent.mobileAppUrl ? { mobileAppUrl: consent.mobileAppUrl } : {}),
+        });
+        if (cancelled) return;
+        controller.fireEvent('redirectToBank');
+        controller.setAwaitingCallbackState({
+          ...(state.selectedProvider ? { providerName: state.selectedProvider.name } : {}),
+        });
+      } catch {
+        if (!cancelled) {
+          void controller.reportError('bank_launch_failed');
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [state.phase, state.consent, state.selectedProvider, launchBankRedirect, controller]);
+
+  // Poll /link/status while waiting for the bank — production and sandbox.
+  useEffect(() => {
+    if (state.phase !== 'awaitingCallback') return;
+    const id = setInterval(() => {
+      void controller.pollStatus();
+    }, DEFAULT_AWAITING_CALLBACK_POLL_MS);
+    return () => clearInterval(id);
+  }, [state.phase, controller]);
+
+  // Fire terminal callbacks exactly once.
+  // or re-delivered terminal state (e.g. a duplicate callback) can't fire
+  // onSuccess/onEvent twice — integrators treat onSuccess as fire-once
+  // (navigate, capture funds, record analytics).
+  useEffect(() => {
+    const phase = state.phase;
+    if (phase !== 'succeeded' && phase !== 'failed' && phase !== 'cancelled') return;
+    if (terminalFiredRef.current) return;
+    if (phase === 'succeeded') {
+      const request = state.session?.request;
+      if (request && isMultiPayment(request) && !mandateAcknowledged) return;
+    }
+    terminalFiredRef.current = true;
+    if (phase === 'succeeded') {
+      props.callbacks?.onSuccess?.(state.exchangeCode, state.linkSessionId);
+      props.callbacks?.onEvent?.('succeeded');
+    } else if (phase === 'failed') {
+      props.callbacks?.onEvent?.('failed');
+    } else {
+      props.callbacks?.onEvent?.('cancelled');
+    }
+  }, [
+    state.phase,
+    state.exchangeCode,
+    state.linkSessionId,
+    state.session,
+    mandateAcknowledged,
+    props.callbacks,
+  ]);
+
+  useEffect(() => {
+    if (state.phase !== 'succeeded' || !mandateAcknowledged || mandateClosedRef.current) return;
+    const request = state.session?.request;
+    if (!request || !isMultiPayment(request)) return;
+    mandateClosedRef.current = true;
+    onResolved();
+  }, [state.phase, state.session, mandateAcknowledged, onResolved]);
+
+  switch (state.phase) {
+    case 'idle':
+    case 'hydrating':
+      return <LoadingState />;
+
+    case 'bankSelection':
+      return (
+        <BankSelectionScreen
+          providers={state.providers}
+          isProcessing={processing}
+          onSelected={async (bankId) => {
+            setProcessing(true);
+            try {
+              controller.selectBank(bankId);
+            } finally {
+              setProcessing(false);
+            }
+          }}
+          onCancel={async () => {
+            setProcessing(true);
+            try {
+              await controller.cancel();
+            } finally {
+              setProcessing(false);
+            }
+          }}
+        />
+      );
+
+    case 'consentDetails': {
+      const summary = summaryFromState(state);
+      if (!summary) return <LoadingState />;
+      return (
+        <ConsentDetailsScreen
+          display={summary}
+          isProcessing={processing}
+          {...(state.isCopLoading ? { isCopLoading: true } : {})}
+          onContinue={async () => {
+            setProcessing(true);
+            try {
+              await controller.confirmConsent();
+            } catch {
+              // controller already setStates failed
+            } finally {
+              setProcessing(false);
+            }
+          }}
+          onCancel={async () => {
+            setProcessing(true);
+            try {
+              await controller.cancel();
+            } finally {
+              setProcessing(false);
+            }
+          }}
+        />
+      );
+    }
+
+    case 'redirecting':
+      return <RedirectHandoffScreen />;
+
+    case 'awaitingCallback':
+      return (
+        <ResumeProcessingScreen
+          {...(controller.awaitingCallbackStartedAtMs !== undefined
+            ? { awaitingCallbackStartedAtMs: controller.awaitingCallbackStartedAtMs }
+            : {})}
+          onCancel={async () => {
+            await controller.cancel();
+          }}
+        />
+      );
+
+    case 'succeeded': {
+      const request = state.session?.request;
+      if (request && isMultiPayment(request) && !mandateAcknowledged) {
+        const paymentType = resolvedPaymentType(request);
+        return (
+          <MandateSetupSuccessScreen
+            rulesTitle={rulesSectionTitle(paymentType)}
+            rules={buildMultiPaymentRules(paymentType, request.instructions)}
+            paymentType={paymentType}
+            onDone={() => setMandateAcknowledged(true)}
+          />
+        );
+      }
+      return <ResultScreen title="Your payment was successful." isSuccess onDone={onResolved} />;
+    }
+
+    case 'failed':
+      return (
+        <ResultScreen
+          title={userFriendlyMessageFor(state.errorCode ?? 'unknown_error')}
+          isSuccess={false}
+          onDone={onResolved}
+        />
+      );
+
+    case 'cancelled':
+      return (
+        <ResultScreen title="The payment was cancelled." isSuccess={false} onDone={onResolved} />
+      );
+  }
+}
+
+function LoadingState(): JSX.Element {
+  return (
+    <View style={styles.loading} testID="payment-flow-loading">
+      <ActivityIndicator size="large" color={Colors.spareBlue} />
+      <Text style={Typography.bodyMuted}>Loading…</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  loading: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 12,
+    backgroundColor: Colors.surfacePage,
+  },
+});

package/src/ui/screens/bank-selection-screen.tsx

@@ -0,0 +1,209 @@
+import { Ionicons } from '@expo/vector-icons';
+import { useMemo, useState } from 'react';
+import { Image, Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
+import type { ProviderSummary } from '../../core/models';
+import { Colors, FONT_FAMILY, Spacing } from '../theme';
+import { Footer, LayoutWHeader } from '../widgets';
+
+export interface BankSelectionScreenProps {
+  providers: ProviderSummary[];
+  onSelected: (bankId: string) => void;
+  onCancel: () => void;
+  isProcessing?: boolean;
+}
+
+/**
+ * CBUAE-approved bank picker. Port of Flutter `bank_selection_screen.dart`:
+ * "Choose your bank" inside a white card with a search field and logo rows
+ * (blue-outline selection), wrapped in the shared {@link LayoutWHeader} stepper
+ * chrome with a "Proceed using Altareq" footer.
+ */
+export function BankSelectionScreen(props: BankSelectionScreenProps): JSX.Element {
+  const [query, setQuery] = useState('');
+  const [selectedId, setSelectedId] = useState<string | undefined>(undefined);
+
+  const trimmed = query.trim().toLowerCase();
+  const filtered = useMemo(
+    () =>
+      trimmed
+        ? props.providers.filter((p) => p.name.toLowerCase().includes(trimmed))
+        : props.providers,
+    [props.providers, trimmed],
+  );
+
+  const isBankSelected = !!selectedId;
+
+  return (
+    <LayoutWHeader
+      progress={0}
+      onBackPress={props.onCancel}
+      {...(props.isProcessing ? { backDisabled: true } : {})}
+    >
+      <View style={styles.container} testID="bank-selection-screen">
+        <View style={styles.card}>
+          <Text style={styles.cardTitle} testID="bank-selection-title">
+            Choose your bank
+          </Text>
+          <View style={styles.searchRow}>
+            <TextInput
+              accessibilityLabel="Search account providers"
+              testID="bank-selection-search"
+              value={query}
+              onChangeText={setQuery}
+              placeholder="Enter account provider..."
+              placeholderTextColor={Colors.textMuted}
+              style={styles.searchInput}
+            />
+            {query.length > 0 ? (
+              <Pressable
+                accessibilityRole="button"
+                testID="bank-selection-search-clear"
+                onPress={() => setQuery('')}
+                hitSlop={8}
+              >
+                <Ionicons name="close" size={18} color={Colors.textMuted} />
+              </Pressable>
+            ) : (
+              <Ionicons name="search" size={18} color={Colors.textMuted} />
+            )}
+          </View>
+
+          {filtered.length === 0 ? (
+            <Text testID="bank-selection-empty" style={styles.empty}>
+              {trimmed ? `No banks match "${query.trim()}"` : 'No banks available'}
+            </Text>
+          ) : (
+            filtered.map((provider) => (
+              <BankRow
+                key={provider.id}
+                provider={provider}
+                isSelected={provider.id === selectedId}
+                onPress={() => setSelectedId(provider.id)}
+              />
+            ))
+          )}
+        </View>
+
+        <View style={styles.spacer} />
+
+        <Footer
+          continueButtonText="Proceed using Altareq"
+          continueTestID="bank-selection-continue-btn"
+          cancelTestID="bank-selection-cancel-btn"
+          onCancel={props.onCancel}
+          disabledContinueButton={!isBankSelected}
+          {...(isBankSelected ? { onContinue: () => props.onSelected(selectedId as string) } : {})}
+          {...(props.isProcessing ? { isLoading: true } : {})}
+        />
+      </View>
+    </LayoutWHeader>
+  );
+}
+
+function BankRow(props: {
+  provider: ProviderSummary;
+  isSelected: boolean;
+  onPress: () => void;
+}): JSX.Element {
+  const { provider, isSelected } = props;
+  const [logoFailed, setLogoFailed] = useState(false);
+  const showLogo = !!provider.logoUrl && !logoFailed;
+  return (
+    <Pressable
+      testID={`bank-row-${provider.code}`}
+      accessibilityRole="button"
+      onPress={props.onPress}
+      style={[styles.row, isSelected && styles.rowSelected]}
+    >
+      {showLogo ? (
+        <Image
+          source={{ uri: provider.logoUrl }}
+          style={styles.logo}
+          resizeMode="contain"
+          onError={() => setLogoFailed(true)}
+        />
+      ) : (
+        <View style={[styles.logo, styles.logoFallback]}>
+          <Ionicons name="business-outline" size={20} color={Colors.textMuted} />
+        </View>
+      )}
+      <Text style={[styles.rowName, isSelected && styles.rowNameSelected]} numberOfLines={1}>
+        {provider.name}
+      </Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+  card: {
+    backgroundColor: Colors.surfaceCard,
+    borderRadius: 12,
+    paddingHorizontal: 12,
+    paddingVertical: 16,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: Colors.divider,
+    shadowColor: '#000000',
+    shadowOpacity: 0.06,
+    shadowRadius: 6,
+    shadowOffset: { width: 0, height: 2 },
+    elevation: 2,
+  },
+  cardTitle: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 16,
+    fontWeight: '700',
+    color: Colors.textPrimary,
+    marginBottom: 12,
+  },
+  searchRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: Colors.divider,
+    borderRadius: 12,
+    paddingHorizontal: 12,
+    height: 44,
+    marginBottom: Spacing.md,
+  },
+  searchInput: {
+    flex: 1,
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textPrimary,
+    paddingVertical: 0,
+  },
+  empty: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    textAlign: 'center',
+    paddingVertical: Spacing.xl,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    marginVertical: 4,
+    borderRadius: 10,
+    borderWidth: 1.5,
+    borderColor: 'transparent',
+  },
+  rowSelected: { borderColor: Colors.spareBlue },
+  logo: { width: 36, height: 36, borderRadius: 4 },
+  logoFallback: {
+    backgroundColor: Colors.surfaceMuted,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  rowName: {
+    flex: 1,
+    marginLeft: 12,
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textPrimary,
+  },
+  rowNameSelected: { color: Colors.spareBlue, fontWeight: '600' },
+  spacer: { flex: 1, minHeight: Spacing.xl },
+});

package/src/ui/screens/consent-details-screen.tsx

@@ -0,0 +1,106 @@
+import { ScrollView, StyleSheet, Text, View } from 'react-native';
+import type { ConsentSummaryData } from '../../core/services/consent-presenter';
+import { ConsentSummarySection } from '../consent/consent-summary-section';
+import { present } from '../consent/label-value-rows';
+import { Colors, FONT_FAMILY, Spacing } from '../theme';
+import { Footer, LayoutWHeader } from '../widgets';
+
+export interface ConsentDetailsScreenProps {
+  display: ConsentSummaryData;
+  onContinue: () => void;
+  onCancel: () => void;
+  isProcessing?: boolean;
+  isCopLoading?: boolean;
+}
+
+/**
+ * CBUAE-approved consent screen. Port of Flutter `consent_details_screen.dart`.
+ */
+export function ConsentDetailsScreen(props: ConsentDetailsScreenProps): JSX.Element {
+  const { display, onContinue, onCancel, isProcessing, isCopLoading } = props;
+  const bankName = present(display.bankName, 'your bank');
+  const disableContinue =
+    isCopLoading ?? (display.variant === 'singlePayment' ? display.isCopLoading : false);
+  const backDisabled = !!isProcessing;
+  return (
+    <LayoutWHeader progress={0.5} onBackPress={onCancel} backDisabled={backDisabled}>
+      <ScrollView
+        style={styles.scroll}
+        contentContainerStyle={styles.content}
+        testID="consent-details-screen"
+      >
+        <Text style={styles.title} testID="consent-details-title">
+          Permission to make a payment
+        </Text>
+        <Text style={styles.intro} testID="consent-details-intro">
+          To make a payment we need your permission to securely initiate payment order from{' '}
+          {bankName}.
+        </Text>
+
+        <ConsentSummarySection data={display} />
+
+        {display.variant === 'multiPayment' ? (
+          <View style={styles.balancePermission} testID="consent-balance-permission">
+            <Text style={styles.title}>Permission to check balance</Text>
+            <Text style={styles.balanceIntro}>
+              You also allow us to check the available funds before making a payment
+            </Text>
+          </View>
+        ) : null}
+
+        <View style={styles.footerWrap}>
+          <Footer
+            onContinue={onContinue}
+            continueButtonText="Pay using Altareq"
+            continueTestID="consent-proceed-btn"
+            showCancelButton={false}
+            disabledContinueButton={disableContinue}
+            {...(isProcessing ? { isLoading: true } : {})}
+          />
+        </View>
+
+        <Text style={styles.disclaimer} testID="consent-details-disclaimer">
+          We will securely transfer you to{' '}
+          <Text style={styles.disclaimerBold}>{display.bankName}</Text> to authorize and make the
+          payment.
+        </Text>
+      </ScrollView>
+    </LayoutWHeader>
+  );
+}
+
+const styles = StyleSheet.create({
+  scroll: { flex: 1 },
+  content: { paddingBottom: Spacing.xl },
+  title: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 18,
+    fontWeight: '700',
+    color: Colors.textPrimary,
+  },
+  intro: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    lineHeight: 22,
+    marginTop: 10,
+    marginBottom: 20,
+  },
+  balancePermission: { marginTop: 20 },
+  balanceIntro: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    lineHeight: 22,
+    marginTop: Spacing.sm,
+  },
+  footerWrap: { marginTop: 20 },
+  disclaimer: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    lineHeight: 22,
+    marginTop: Spacing.md,
+  },
+  disclaimerBold: { fontWeight: '700', color: Colors.textMuted },
+});

package/src/ui/screens/index.ts

@@ -0,0 +1,12 @@
+export { BankSelectionScreen, type BankSelectionScreenProps } from './bank-selection-screen';
+export { ConsentDetailsScreen, type ConsentDetailsScreenProps } from './consent-details-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/mandate-setup-success-screen.tsx

@@ -0,0 +1,72 @@
+import { ScrollView, StyleSheet, Text, View } from 'react-native';
+import type { PaymentType } from '../../core/models/payment-type';
+import type { LabelValueRow } from '../../core/services/multi-payment-rules-presenter';
+import { MultiPaymentRulesList } from '../consent/multi-payment-rules-list';
+import { Colors, FONT_FAMILY, Spacing } from '../theme';
+import { Footer } from '../widgets';
+
+export interface MandateSetupSuccessScreenProps {
+  rulesTitle: string;
+  rules: LabelValueRow[];
+  paymentType: PaymentType;
+  onDone: () => void;
+}
+
+export function MandateSetupSuccessScreen(props: MandateSetupSuccessScreenProps): JSX.Element {
+  return (
+    <View style={styles.root} testID="mandate-setup-success-screen">
+      <Text style={styles.title}>Setup successful</Text>
+      <Text style={styles.subtitle}>Successfully set up your payment method</Text>
+      <ScrollView style={styles.scroll} contentContainerStyle={styles.scrollContent}>
+        <View style={styles.card}>
+          <MultiPaymentRulesList
+            rulesTitle={props.rulesTitle}
+            rules={props.rules}
+            paymentType={props.paymentType}
+          />
+        </View>
+      </ScrollView>
+      <Footer
+        onContinue={props.onDone}
+        continueButtonText="Done"
+        continueTestID="mandate-success-done-btn"
+        showCancelButton={false}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    backgroundColor: Colors.surfacePage,
+    paddingHorizontal: 24,
+    paddingTop: 32,
+    paddingBottom: Spacing.lg,
+  },
+  title: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 22,
+    fontWeight: '700',
+    color: Colors.textPrimary,
+    textAlign: 'center',
+  },
+  subtitle: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    textAlign: 'center',
+    marginTop: 12,
+    marginBottom: 24,
+  },
+  scroll: { flex: 1 },
+  scrollContent: { paddingBottom: Spacing.md },
+  card: {
+    backgroundColor: Colors.cardMutedBg,
+    borderRadius: 16,
+    paddingVertical: 16,
+    paddingHorizontal: 20,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: Colors.divider,
+  },
+});

package/src/ui/screens/redirect-handoff-screen.tsx

@@ -0,0 +1,33 @@
+import { StyleSheet, Text, View } from 'react-native';
+import { linkFontFamilyForWeight } from '../theme/fonts';
+import { GradientSpinner } from '../widgets/gradient-spinner';
+import { HandoffScreenLayout } from '../widgets/handoff-screen-layout';
+
+/** Shown while the SDK is opening the bank app/browser. Purely informational. */
+export function RedirectHandoffScreen(): JSX.Element {
+  return (
+    <HandoffScreenLayout testID="redirect-handoff-screen">
+      <View style={styles.content}>
+        <GradientSpinner testID="redirect-handoff-spinner" />
+        <Text style={styles.message} testID="redirect-handoff-message">
+          {"You'll be redirected to your bank,\ndon't close this window."}
+        </Text>
+      </View>
+    </HandoffScreenLayout>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: {
+    alignItems: 'center',
+    gap: 32,
+  },
+  message: {
+    fontFamily: linkFontFamilyForWeight('400'),
+    fontSize: 16,
+    fontWeight: '400',
+    color: '#FFFFFF',
+    textAlign: 'center',
+    lineHeight: 24,
+  },
+});