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

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

@@ -0,0 +1,124 @@
+import type { ConsentResponse, CopResponse, LinkSessionResponse, ProviderSummary } from '../models';
+
+/** Phases the payment flow controller transitions through. */
+export type PaymentFlowPhase =
+  | 'idle'
+  | 'hydrating'
+  | 'bankSelection'
+  | 'consentDetails'
+  | 'redirecting'
+  | 'awaitingCallback'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled';
+
+export interface PaymentFlowState {
+  phase: PaymentFlowPhase;
+  session?: LinkSessionResponse;
+  providers: ProviderSummary[];
+  selectedProvider?: ProviderSummary;
+  consent?: ConsentResponse;
+  /** Confirmation-of-Payee result, threaded into the consentDetails phase. */
+  copResponse?: CopResponse;
+  /** True while Confirmation-of-Payee is loading for domestic SIP. */
+  isCopLoading?: boolean;
+  /**
+   * True when this session was actually eligible for Confirmation-of-Payee
+   * (UAE tenant, unverified, payment type supports it) — as opposed to
+   * merely supporting it by payment type. Lets the presenter distinguish
+   * "not applicable" from "was attempted but the response never arrived".
+   */
+  copApplicable?: boolean;
+  exchangeCode?: string;
+  linkSessionId?: string;
+  merchantRef?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  providerName?: string;
+}
+
+const EMPTY_PROVIDERS: ProviderSummary[] = [];
+
+export const PaymentFlowStates = {
+  idle(): PaymentFlowState {
+    return { phase: 'idle', providers: EMPTY_PROVIDERS };
+  },
+  hydrating(): PaymentFlowState {
+    return { phase: 'hydrating', providers: EMPTY_PROVIDERS };
+  },
+  bankSelection(args: {
+    session: LinkSessionResponse;
+    providers: ProviderSummary[];
+  }): PaymentFlowState {
+    return { phase: 'bankSelection', session: args.session, providers: args.providers };
+  },
+  consentDetails(args: {
+    session: LinkSessionResponse;
+    selectedProvider: ProviderSummary;
+    copResponse?: CopResponse;
+    isCopLoading?: boolean;
+    copApplicable?: boolean;
+  }): PaymentFlowState {
+    return {
+      phase: 'consentDetails',
+      session: args.session,
+      providers: EMPTY_PROVIDERS,
+      selectedProvider: args.selectedProvider,
+      ...(args.copResponse ? { copResponse: args.copResponse } : {}),
+      ...(args.isCopLoading !== undefined ? { isCopLoading: args.isCopLoading } : {}),
+      ...(args.copApplicable !== undefined ? { copApplicable: args.copApplicable } : {}),
+    };
+  },
+  redirecting(args: {
+    consent: ConsentResponse;
+    selectedProvider?: ProviderSummary;
+  }): PaymentFlowState {
+    return {
+      phase: 'redirecting',
+      providers: EMPTY_PROVIDERS,
+      consent: args.consent,
+      ...(args.selectedProvider ? { selectedProvider: args.selectedProvider } : {}),
+    };
+  },
+  awaitingCallback(args: {
+    providerName?: string;
+    session?: LinkSessionResponse;
+    selectedProvider?: ProviderSummary;
+  }): PaymentFlowState {
+    return {
+      phase: 'awaitingCallback',
+      providers: EMPTY_PROVIDERS,
+      ...(args.providerName ? { providerName: args.providerName } : {}),
+      ...(args.session ? { session: args.session } : {}),
+      ...(args.selectedProvider ? { selectedProvider: args.selectedProvider } : {}),
+    };
+  },
+  succeeded(args: {
+    exchangeCode?: string;
+    linkSessionId?: string;
+    merchantRef?: string;
+    selectedProvider?: ProviderSummary;
+    session?: LinkSessionResponse;
+  }): PaymentFlowState {
+    return {
+      phase: 'succeeded',
+      providers: EMPTY_PROVIDERS,
+      ...(args.exchangeCode ? { exchangeCode: args.exchangeCode } : {}),
+      ...(args.linkSessionId ? { linkSessionId: args.linkSessionId } : {}),
+      ...(args.merchantRef ? { merchantRef: args.merchantRef } : {}),
+      ...(args.selectedProvider ? { selectedProvider: args.selectedProvider } : {}),
+      ...(args.session ? { session: args.session } : {}),
+    };
+  },
+  failed(args: { errorCode: string; errorMessage?: string }): PaymentFlowState {
+    return {
+      phase: 'failed',
+      providers: EMPTY_PROVIDERS,
+      errorCode: args.errorCode,
+      ...(args.errorMessage ? { errorMessage: args.errorMessage } : {}),
+    };
+  },
+  cancelled(): PaymentFlowState {
+    return { phase: 'cancelled', providers: EMPTY_PROVIDERS };
+  },
+} as const;

package/src/core/services/payment-result-mapper.ts

@@ -0,0 +1,41 @@
+import type { PaymentResult } from '../../public/payment-result';
+import {
+  paymentAbandoned,
+  paymentCancelled,
+  paymentFailed,
+  paymentSuccess,
+} from '../../public/payment-result';
+import type { PaymentFlowState } from './payment-flow-state';
+
+/** Map a terminal controller state to a {@link PaymentResult}. */
+export function paymentResultFromFlowState(
+  state: PaymentFlowState,
+  linkToken: string,
+  bankId?: string,
+): PaymentResult | null {
+  const resolvedBankId = bankId ?? state.selectedProvider?.id;
+  switch (state.phase) {
+    case 'succeeded':
+      return paymentSuccess({
+        linkToken,
+        ...(state.exchangeCode ? { exchangeCode: state.exchangeCode } : {}),
+        ...(state.linkSessionId ? { linkSessionId: state.linkSessionId } : {}),
+        ...(state.merchantRef ? { merchantRef: state.merchantRef } : {}),
+        ...(resolvedBankId ? { bankId: resolvedBankId } : {}),
+        resolvedAtMs: Date.now(),
+      });
+    case 'failed':
+      return paymentFailed({
+        linkToken,
+        errorCode: state.errorCode ?? 'unknown_error',
+        resolvedAtMs: Date.now(),
+      });
+    case 'cancelled':
+      return paymentCancelled({
+        linkToken,
+        ...(resolvedBankId ? { bankId: resolvedBankId } : {}),
+        resolvedAtMs: Date.now(),
+      });
+  }
+  return paymentAbandoned({ linkToken, resolvedAtMs: Date.now() });
+}

package/src/core/services/pending-session-store.ts

@@ -0,0 +1,12 @@
+import type { PendingSessionRecord } from '../models';
+
+/**
+ * Persistence abstraction the controller uses to survive cold-start.
+ * Production impl: `SecureStorePendingSessionStore` (expo-secure-store) —
+ * added in Phase 3. Tests use harness's `InMemoryPendingSessionStore`.
+ */
+export interface PendingSessionStore {
+  save(record: PendingSessionRecord): Promise<void>;
+  load(): Promise<PendingSessionRecord | null>;
+  clear(): Promise<void>;
+}

package/src/core/services/presentation-utils.ts

@@ -0,0 +1,4 @@
+export function formatAmount(value: { amount: string; currency: string } | undefined): string {
+  if (!value) return '—';
+  return `${value.amount} ${value.currency}`;
+}

package/src/core/services/redirect-buffer.ts

@@ -0,0 +1,34 @@
+/** Module-level buffer for a bank-return URI received before a flow is active. */
+interface BufferedRedirect {
+  uri: string;
+}
+
+let buffered: BufferedRedirect | null = null;
+/** Fingerprint of the last consumed URI — blocks re-buffer after consume / double-delivery. */
+let lastHandledUri: string | null = null;
+
+export function setBufferedRedirect(uri: string): void {
+  if (uri === buffered?.uri || uri === lastHandledUri) {
+    return;
+  }
+  buffered = { uri };
+}
+
+export function peekBufferedRedirect(): string | null {
+  return buffered?.uri ?? null;
+}
+
+export function consumeBufferedRedirect(): string | null {
+  const value = buffered?.uri ?? null;
+  buffered = null;
+  if (value) {
+    lastHandledUri = value;
+  }
+  return value;
+}
+
+/** @internal Clears buffer state between tests. */
+export function resetRedirectBufferForTests(): void {
+  buffered = null;
+  lastHandledUri = null;
+}

package/src/core/services/user-friendly-messages.ts

@@ -0,0 +1,39 @@
+/**
+ * Maps machine-readable error codes to safe user-facing copy.
+ * Raw backend or bank messages must never be shown directly.
+ */
+export function userFriendlyMessageFor(errorCode: string): string {
+  switch (errorCode) {
+    case 'network_timeout':
+      return 'Connection timed out. Please check your connection and try again.';
+    case 'session_expired':
+      return 'Your payment session has expired. Please start again.';
+    case 'session_cancelled':
+      return 'The payment was cancelled.';
+    case 'session_already_completed':
+      return 'This payment has already been completed.';
+    case 'invalid_token':
+      return 'The payment link is invalid or has expired.';
+    case 'bank_unavailable':
+      return 'Your bank is temporarily unavailable. Please try again later.';
+    case 'consent_creation_failed':
+      return 'Unable to initiate the payment. Please try again.';
+    case 'rate_limit_exceeded':
+      return 'Too many attempts. Please wait a moment and try again.';
+    case 'redirect_failed':
+    case 'bank_launch_failed':
+      return 'Unable to open your bank app. Please try again.';
+    case 'session_timeout':
+      return 'The payment timed out waiting for your bank. Please try again.';
+    case 'recovery_exhausted':
+      return 'This payment session could not be recovered. Please start again.';
+    case 'hydration_error':
+    case 'network_error':
+    case 'SP500':
+      return 'Your bank could not complete the payment. Please try again.';
+    case 'authorize_failed':
+      return 'Payment could not be completed. Please try again.';
+    default:
+      return 'Something went wrong. Please try again.';
+  }
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+// Public exports of @spare-technologies/spare-link.
+
+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 {
+  isPaymentReturnCallbackUri,
+  extractPaymentReturnErrorCode,
+} 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';
+
+// Storage interface
+export type { PendingSessionStore } from './core/services/pending-session-store';
+
+// 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';
+export { Colors, Typography, Spacing, FONT_FAMILY } from './ui/theme';
+
+// Native platform integration
+export {
+  collectTelemetry,
+  launchBankRedirect,
+  type BankRedirectArgs,
+  SecureStorePendingSessionStore,
+  useSpareLinkDeepLinks,
+} from './internal';

package/src/internal/bank-redirect.ts

@@ -0,0 +1,61 @@
+/**
+ * Bank redirect launcher. Port of Flutter `BankRedirect.launch`
+ * (lib/src/internal/bank_redirect.dart).
+ *
+ * Strategy:
+ *   1. If `mobileAppUrl` is provided (e.g. `altareq://authorize?...`), try
+ *      `Linking.openURL` after checking `canOpenURL` — this launches the
+ *      bank's app directly without a browser tab.
+ *   2. Otherwise (or if step 1 fails) open `authorizationUrl` via
+ *      `expo-web-browser`'s in-app browser if installed; fall back to the
+ *      system browser via `Linking.openURL`.
+ */
+import { Linking } from 'react-native';
+import { createLogger } from './logger';
+
+const log = createLogger('BankRedirect');
+
+export interface BankRedirectArgs {
+  authorizationUrl: string;
+  mobileAppUrl?: string;
+}
+
+interface WebBrowserLike {
+  openBrowserAsync(url: string): Promise<unknown>;
+}
+
+async function loadWebBrowser(): Promise<WebBrowserLike | null> {
+  try {
+    return (await import('expo-web-browser')) as unknown as WebBrowserLike;
+  } catch {
+    return null;
+  }
+}
+
+export async function launchBankRedirect(args: BankRedirectArgs): Promise<void> {
+  if (args.mobileAppUrl) {
+    log.info('launch: trying mobile app deep link');
+    try {
+      const can = await Linking.canOpenURL(args.mobileAppUrl);
+      if (can) {
+        await Linking.openURL(args.mobileAppUrl);
+        log.info('launch: mobile app deep link succeeded');
+        return;
+      }
+      log.warning('launch: mobile deep link unavailable — falling back to browser');
+    } catch (e) {
+      log.warning(
+        `launch: mobile deep link failed (${e instanceof Error ? e.message : String(e)}) — falling back`,
+      );
+    }
+  }
+
+  const wb = await loadWebBrowser();
+  if (wb?.openBrowserAsync) {
+    log.info('launch: opening authorization URL in in-app browser');
+    await wb.openBrowserAsync(args.authorizationUrl);
+    return;
+  }
+  log.info('launch: opening authorization URL in system browser');
+  await Linking.openURL(args.authorizationUrl);
+}

package/src/internal/deep-link-listener.ts

@@ -0,0 +1,31 @@
+/**
+ * Convenience hook that wires `Linking.addEventListener('url', ...)` +
+ * `Linking.getInitialURL()` to {@link SpareLink.handleRedirect}.
+ */
+import { useEffect } from 'react';
+import { Linking } from 'react-native';
+import type { SpareLink } from '../public/spare-link-instance';
+
+export function useSpareLinkDeepLinks(spareLink: SpareLink): void {
+  useEffect(() => {
+    let removed = false;
+    let lastUrl: string | null = null;
+    const handle = (url: string) => {
+      if (url === lastUrl) return;
+      lastUrl = url;
+      void spareLink.handleRedirect(url);
+    };
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      handle(url);
+    });
+    void Linking.getInitialURL().then((initial) => {
+      if (initial && !removed) {
+        handle(initial);
+      }
+    });
+    return () => {
+      removed = true;
+      subscription.remove();
+    };
+  }, [spareLink]);
+}

package/src/internal/event-emitter.ts

@@ -0,0 +1,42 @@
+/** Minimal typed pub/sub — TypeScript equivalent of Dart's broadcast Stream. */
+export type Unsubscribe = () => void;
+
+export interface EventEmitter<T> {
+  /** Subscribe to events. Returns an unsubscribe function. */
+  subscribe(listener: (event: T) => void): Unsubscribe;
+  /** Alias for {@link subscribe} — mirrors Flutter's `Stream.listen`. */
+  listen(listener: (event: T) => void): Unsubscribe;
+}
+
+export function createEventEmitter<T>(): EventEmitter<T> & {
+  emit(event: T): void;
+  dispose(): void;
+} {
+  const listeners = new Set<(event: T) => void>();
+  let closed = false;
+
+  function subscribe(listener: (event: T) => void): Unsubscribe {
+    if (closed) return () => {};
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return {
+    subscribe,
+    listen: subscribe,
+    emit(event) {
+      if (closed) return;
+      for (const listener of listeners) {
+        try {
+          listener(event);
+        } catch {
+          /* swallow — same as Flutter/Dart stream */
+        }
+      }
+    },
+    dispose() {
+      closed = true;
+      listeners.clear();
+    },
+  };
+}

package/src/internal/index.ts

@@ -0,0 +1,4 @@
+export { collectTelemetry } from './telemetry-collector';
+export { launchBankRedirect, type BankRedirectArgs } from './bank-redirect';
+export { SecureStorePendingSessionStore } from './secure-store-pending-session-store';
+export { useSpareLinkDeepLinks } from './deep-link-listener';

package/src/internal/logger.ts

@@ -0,0 +1,81 @@
+export type SpareLinkLogLevel = 'fine' | 'info' | 'warning' | 'severe';
+
+const LEVEL_RANK: Record<SpareLinkLogLevel, number> = {
+  fine: 10,
+  info: 20,
+  warning: 30,
+  severe: 40,
+};
+
+export interface SpareLinkLogRecord {
+  level: SpareLinkLogLevel;
+  loggerName: string;
+  message: string;
+  time: Date;
+}
+
+export type SpareLinkLogSink = (record: SpareLinkLogRecord) => void;
+
+interface LoggingConfig {
+  level: SpareLinkLogLevel;
+  sink: SpareLinkLogSink;
+}
+
+let config: LoggingConfig | null = null;
+
+function isDevBuild(): boolean {
+  if (typeof __DEV__ === 'boolean') return __DEV__;
+  return process.env.NODE_ENV !== 'production';
+}
+
+function defaultLevel(): SpareLinkLogLevel {
+  return isDevBuild() ? 'info' : 'severe';
+}
+
+function defaultSink(): SpareLinkLogSink {
+  return (record) => {
+    const line = `${record.level.toUpperCase()}: ${record.time.toISOString()}: ${record.loggerName}: ${record.message}`;
+    if (record.level === 'severe' || record.level === 'warning') {
+      console.warn(line);
+    } else {
+      console.info(line);
+    }
+  };
+}
+
+/** Configure SDK logging — mirrors Flutter `Logger.root.level` + `onRecord.listen`. */
+export function configureSpareLinkLogging(opts: {
+  level?: SpareLinkLogLevel;
+  sink?: SpareLinkLogSink;
+}): void {
+  config = {
+    level: opts.level ?? defaultLevel(),
+    sink: opts.sink ?? defaultSink(),
+  };
+}
+
+/** @internal test helper */
+export function resetSpareLinkLoggingForTests(): void {
+  config = null;
+}
+
+export interface SpareLinkLogger {
+  fine(message: string): void;
+  info(message: string): void;
+  warning(message: string): void;
+  severe(message: string): void;
+}
+
+export function createLogger(loggerName: string): SpareLinkLogger {
+  const emit = (level: SpareLinkLogLevel, message: string) => {
+    const active = config ?? { level: defaultLevel(), sink: () => {} };
+    if (LEVEL_RANK[level] < LEVEL_RANK[active.level]) return;
+    active.sink({ level, loggerName, message, time: new Date() });
+  };
+  return {
+    fine: (m) => emit('fine', m),
+    info: (m) => emit('info', m),
+    warning: (m) => emit('warning', m),
+    severe: (m) => emit('severe', m),
+  };
+}

package/src/internal/redact-uri.ts

@@ -0,0 +1,18 @@
+const SENSITIVE_QUERY_KEYS = new Set(['exchange_code', 'error_description']);
+
+/** Redacts sensitive query params before logging bank-return URIs. */
+export function redactPaymentReturnUri(uri: string): string {
+  try {
+    const parsed = new URL(uri);
+    let changed = false;
+    for (const key of SENSITIVE_QUERY_KEYS) {
+      if (parsed.searchParams.has(key)) {
+        parsed.searchParams.set(key, '[REDACTED]');
+        changed = true;
+      }
+    }
+    return changed ? parsed.toString() : uri;
+  } catch {
+    return '[invalid-uri]';
+  }
+}