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

package/src/public/spare-link-host-api.ts

@@ -0,0 +1,28 @@
+import type { PaymentResult } from './payment-result';
+import type { RecoveryResult } from './recovery-result';
+import type { SpareLinkSession } from './spare-link-session';
+
+/**
+ * Imperative API the {@link SpareLinkHost} mounts and wires to a
+ * {@link SpareLink} instance.
+ *
+ * @internal
+ */
+export interface SpareLinkHostApi {
+  start(args: { linkToken: string }): Promise<SpareLinkSession>;
+  handleRedirect(uri: URL | string): Promise<boolean>;
+  resumeIfNeeded(): Promise<RecoveryResult>;
+  isFlowActive(): boolean;
+}
+
+/** @internal */
+export interface SpareLinkHostDelegate {
+  startFlow(args: {
+    linkToken: string;
+    resolve: (result: PaymentResult) => void;
+    onSessionLoaded?: (linkSessionId: string) => void;
+  }): void;
+  handleRedirect(uri: URL | string): Promise<boolean>;
+  resumeIfNeeded(): Promise<RecoveryResult>;
+  isFlowActive(): boolean;
+}

package/src/public/spare-link-instance.ts

@@ -0,0 +1,289 @@
+import type { PendingSessionStore } from '../core/services/pending-session-store';
+import { type EventEmitter, createEventEmitter } from '../internal/event-emitter';
+import { type PaymentResult, paymentAbandoned } from './payment-result';
+import { type NoRecoveryReason, type RecoveryResult, isSessionRecovered } from './recovery-result';
+import {
+  type PaymentEnvironment,
+  type SpareApiTenant,
+  defaultBaseUrlFor,
+} from './spare-link-config';
+import { type SpareLinkEvent, SpareLinkEvents } from './spare-link-event';
+import type { SpareLinkHostDelegate } from './spare-link-host-api';
+import { SpareLinkSession } from './spare-link-session';
+
+export interface SpareLinkOptions {
+  environment: PaymentEnvironment;
+  tenant: SpareApiTenant;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  requestTimeoutMs?: number;
+  /** Store for crash-safe recovery. Defaults to none — wire e.g. `SecureStorePendingSessionStore`. */
+  pendingSessionStore?: PendingSessionStore;
+}
+
+interface PendingStart {
+  linkToken: string;
+  resolve: (session: SpareLinkSession) => void;
+}
+
+interface PendingRedirect {
+  uri: URL | string;
+  resolve: (handled: boolean) => void;
+}
+
+interface PendingResume {
+  resolve: (result: RecoveryResult) => void;
+}
+
+/**
+ * Entry point for the Spare Link payment SDK — aligned with Flutter's
+ * instance-based {@link SpareLink} API.
+ *
+ * Mount {@link SpareLinkHost} once near your app root and pass this instance:
+ *
+ * ```tsx
+ * const spareLink = useMemo(
+ *   () => new SpareLink({ environment: 'sandbox', tenant: 'uae' }),
+ *   [],
+ * );
+ *
+ * <SpareLinkHost spareLink={spareLink}>
+ *   <App />
+ * </SpareLinkHost>
+ * ```
+ */
+export class SpareLink {
+  readonly environment: PaymentEnvironment;
+  readonly tenant: SpareApiTenant;
+  readonly baseUrl: string | undefined;
+  readonly fetch: typeof fetch | undefined;
+  readonly requestTimeoutMs: number | undefined;
+  readonly pendingSessionStore: PendingSessionStore | undefined;
+
+  private readonly _events = createEventEmitter<SpareLinkEvent>();
+  private _host: SpareLinkHostDelegate | null = null;
+  private _disposed = false;
+
+  private readonly _pendingStarts: PendingStart[] = [];
+  private readonly _pendingRedirects: PendingRedirect[] = [];
+  private readonly _pendingResumes: PendingResume[] = [];
+
+  constructor(options: SpareLinkOptions) {
+    this.environment = options.environment;
+    this.tenant = options.tenant;
+    this.baseUrl = options.baseUrl;
+    this.fetch = options.fetch;
+    this.requestTimeoutMs = options.requestTimeoutMs;
+    this.pendingSessionStore = options.pendingSessionStore;
+  }
+
+  /** Lifecycle events for all flows started on this instance. */
+  get events(): EventEmitter<SpareLinkEvent> {
+    return this._events;
+  }
+
+  get resolvedBaseUrl(): string {
+    return this.baseUrl ?? defaultBaseUrlFor(this.environment);
+  }
+
+  /** Returns `true` while a payment flow started via {@link start} is in progress. */
+  get isFlowActive(): boolean {
+    return this._host?.isFlowActive() ?? false;
+  }
+
+  /**
+   * Starts a new payment flow.
+   *
+   * Returns a {@link SpareLinkSession} immediately; await `session.result`
+   * for the terminal outcome.
+   */
+  async start(args: { linkToken: string }): Promise<SpareLinkSession> {
+    const { linkToken } = args;
+    if (!linkToken) {
+      const result = paymentAbandoned({
+        linkToken: '',
+        message: 'SpareLinkConfig: linkToken must not be empty',
+        resolvedAtMs: Date.now(),
+      });
+      this._emitTerminal(result);
+      return new SpareLinkSession({ linkToken: '', result: Promise.resolve(result) });
+    }
+
+    if (this._disposed) {
+      const result = paymentAbandoned({
+        linkToken,
+        message: 'SpareLink has been disposed.',
+        resolvedAtMs: Date.now(),
+      });
+      this._emitTerminal(result);
+      return new SpareLinkSession({ linkToken, result: Promise.resolve(result) });
+    }
+
+    this._events.emit(SpareLinkEvents.initialized(linkToken));
+
+    if (!this._host) {
+      return new Promise<SpareLinkSession>((resolve) => {
+        this._pendingStarts.push({ linkToken, resolve });
+      });
+    }
+
+    return this._hostStart(linkToken);
+  }
+
+  /** Processes a deep-link URI received from the bank. */
+  async handleRedirect(uri: URL | string): Promise<boolean> {
+    if (this._disposed) return false;
+    if (!this._host) {
+      return new Promise<boolean>((resolve) => {
+        this._pendingRedirects.push({ uri, resolve });
+      });
+    }
+    return this._host.handleRedirect(uri);
+  }
+
+  /** Checks for a pending session saved during a previous flow and recovers it. */
+  async resumeIfNeeded(): Promise<RecoveryResult> {
+    if (this._disposed) {
+      return { kind: 'none', reason: 'persistenceUnavailable' };
+    }
+    if (!this.pendingSessionStore) {
+      return { kind: 'none', reason: 'persistenceUnavailable' };
+    }
+    if (!this._host) {
+      return new Promise<RecoveryResult>((resolve) => {
+        this._pendingResumes.push({ resolve });
+      });
+    }
+    return this._host.resumeIfNeeded();
+  }
+
+  dispose(): void {
+    this._disposed = true;
+
+    const starts = this._pendingStarts.splice(0);
+    const redirects = this._pendingRedirects.splice(0);
+    const resumes = this._pendingResumes.splice(0);
+
+    for (const p of starts) {
+      const result = paymentAbandoned({
+        linkToken: p.linkToken,
+        message: 'SpareLink has been disposed.',
+        resolvedAtMs: Date.now(),
+      });
+      this._emitTerminal(result);
+      p.resolve(new SpareLinkSession({ linkToken: p.linkToken, result: Promise.resolve(result) }));
+    }
+    for (const p of redirects) {
+      p.resolve(false);
+    }
+    for (const p of resumes) {
+      p.resolve({ kind: 'none', reason: 'persistenceUnavailable' });
+    }
+
+    this._events.dispose();
+    this._host = null;
+  }
+
+  /**
+   * Called by {@link SpareLinkHost} on mount. Drains any buffered calls.
+   *
+   * @internal
+   */
+  _attachHost(host: SpareLinkHostDelegate): () => void {
+    this._host = host;
+    this._drainPending(host);
+    return () => {
+      if (this._host === host) this._host = null;
+    };
+  }
+
+  /** @internal */
+  emitEvent(event: SpareLinkEvent): void {
+    this._events.emit(event);
+  }
+
+  /** @internal */
+  emitTerminal(result: PaymentResult): void {
+    this._emitTerminal(result);
+  }
+
+  private _emitTerminal(result: PaymentResult): void {
+    switch (result.status) {
+      case 'success':
+        this._events.emit(SpareLinkEvents.succeeded(result));
+        break;
+      case 'failed':
+        this._events.emit(SpareLinkEvents.failed(result));
+        break;
+      case 'cancelled':
+        this._events.emit(SpareLinkEvents.cancelled(result));
+        break;
+      case 'abandoned':
+        this._events.emit(SpareLinkEvents.abandoned(result));
+        break;
+    }
+  }
+
+  private async _hostStart(linkToken: string): Promise<SpareLinkSession> {
+    const host = this._host;
+    if (!host) {
+      return new Promise<SpareLinkSession>((resolve) => {
+        this._pendingStarts.push({ linkToken, resolve });
+      });
+    }
+
+    let resolveResult!: (result: PaymentResult) => void;
+    const resultPromise = new Promise<PaymentResult>((resolve) => {
+      resolveResult = resolve;
+    });
+    const session = new SpareLinkSession({ linkToken, result: resultPromise });
+
+    host.startFlow({
+      linkToken,
+      resolve: (result) => {
+        this._emitTerminal(result);
+        resolveResult(result);
+      },
+      onSessionLoaded: (linkSessionId) => {
+        session.updateLinkSessionId(linkSessionId);
+        this._events.emit(SpareLinkEvents.sessionLoaded(linkToken, linkSessionId));
+      },
+    });
+
+    return session;
+  }
+
+  private _drainPending(host: SpareLinkHostDelegate): void {
+    const starts = this._pendingStarts.splice(0);
+    const redirects = this._pendingRedirects.splice(0);
+    const resumes = this._pendingResumes.splice(0);
+
+    for (const p of starts) {
+      void this._hostStart(p.linkToken).then(p.resolve);
+    }
+    for (const p of redirects) {
+      void host.handleRedirect(p.uri).then(p.resolve, () => p.resolve(false));
+    }
+    for (const p of resumes) {
+      void host
+        .resumeIfNeeded()
+        .then(p.resolve, () => p.resolve({ kind: 'none', reason: 'persistenceUnavailable' }));
+    }
+  }
+}
+
+/** Map legacy recovery helper outcomes to Flutter-aligned {@link RecoveryResult}. */
+export function mapHostRecovery(
+  recovery: RecoveryResult | { kind: 'inProgress'; linkToken: string },
+): RecoveryResult {
+  if (recovery.kind === 'inProgress') {
+    return { kind: 'awaitingUser', linkToken: recovery.linkToken };
+  }
+  return recovery;
+}
+
+export function noRecovery(reason: NoRecoveryReason): RecoveryResult {
+  return { kind: 'none', reason };
+}
+
+export { isSessionRecovered };

package/src/public/spare-link-session.ts

@@ -0,0 +1,28 @@
+import type { PaymentResult } from './payment-result';
+
+/**
+ * Handle for an in-flight or completed payment started via {@link SpareLink.start}.
+ *
+ * Mirrors Flutter's `SpareLinkSession` — `linkToken` is available immediately;
+ * await `result` for the terminal outcome.
+ */
+export class SpareLinkSession {
+  readonly linkToken: string;
+  linkSessionId: string | undefined;
+  readonly result: Promise<PaymentResult>;
+
+  constructor(args: {
+    linkToken: string;
+    result: Promise<PaymentResult>;
+    linkSessionId?: string;
+  }) {
+    this.linkToken = args.linkToken;
+    this.linkSessionId = args.linkSessionId;
+    this.result = args.result;
+  }
+
+  /** Called internally when the server provides {@link linkSessionId}. */
+  updateLinkSessionId(value: string): void {
+    this.linkSessionId = value;
+  }
+}

package/src/public/spare-link.ts

@@ -0,0 +1,2 @@
+export { SpareLink, mapHostRecovery, noRecovery, isSessionRecovered } from './spare-link-instance';
+export type { SpareLinkOptions } from './spare-link-instance';

package/src/ui/consent/charge-bearer-display.tsx

@@ -0,0 +1,68 @@
+import { Ionicons } from '@expo/vector-icons';
+import { StyleSheet, Text, View } from 'react-native';
+import { Colors, FONT_FAMILY } from '../theme';
+
+export interface ChargeBearerDisplayProps {
+  chargeBearer: string | undefined;
+}
+
+const OPTIONS = [
+  { label: 'Shared', apiValue: 'Shared' },
+  { label: 'Debtor', apiValue: 'BorneByDebtor' },
+  { label: 'Creditor', apiValue: 'BorneByCreditor' },
+] as const;
+
+export function ChargeBearerDisplay(props: ChargeBearerDisplayProps): JSX.Element {
+  const bearer = props.chargeBearer?.trim();
+  return (
+    <View style={styles.card} testID="charge-bearer-display">
+      <Text style={styles.title}>Charges model</Text>
+      <View style={styles.options}>
+        {OPTIONS.map((option) => {
+          const selected = bearer === option.apiValue;
+          return (
+            <View key={option.apiValue} style={styles.option}>
+              {selected ? (
+                <Ionicons name="checkmark-circle" size={20} color={Colors.spareBlue} />
+              ) : (
+                <View style={styles.unselectedMarker} />
+              )}
+              <Text style={[styles.optionLabel, selected && styles.optionLabelSelected]}>
+                {option.label}
+              </Text>
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: Colors.surfaceCard,
+    borderRadius: 16,
+    paddingVertical: 14,
+    paddingHorizontal: 20,
+    marginBottom: 14,
+    gap: 16,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: Colors.divider,
+    shadowColor: '#000000',
+    shadowOpacity: 0.06,
+    shadowRadius: 6,
+    shadowOffset: { width: 0, height: 2 },
+    elevation: 2,
+  },
+  title: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    fontWeight: '700',
+    color: Colors.textPrimary,
+  },
+  options: { flexDirection: 'row', flexWrap: 'wrap', gap: 24 },
+  option: { flexDirection: 'row', alignItems: 'center', gap: 4 },
+  unselectedMarker: { width: 20, height: 20 },
+  optionLabel: { fontFamily: FONT_FAMILY, fontSize: 14, color: Colors.textMuted },
+  optionLabelSelected: { color: Colors.textPrimary, fontWeight: '600' },
+});

package/src/ui/consent/consent-accordion.tsx

@@ -0,0 +1,89 @@
+import { Ionicons } from '@expo/vector-icons';
+import { useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { Colors } from '../theme';
+import { linkFontFamilyForWeight } from '../theme/fonts';
+
+export interface ConsentAccordionItem {
+  header: string;
+  children: React.ReactNode;
+  initiallyExpanded?: boolean;
+}
+
+export interface ConsentAccordionProps {
+  items: ConsentAccordionItem[];
+}
+
+export function ConsentAccordion(props: ConsentAccordionProps): JSX.Element {
+  return (
+    <View style={styles.wrap} testID="consent-accordion">
+      {props.items.map((item, index) => (
+        <View key={item.header}>
+          <AccordionSection {...item} />
+          {index < props.items.length - 1 ? (
+            <View style={styles.divider} testID="consent-accordion-divider" />
+          ) : null}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+function AccordionSection(props: ConsentAccordionItem): JSX.Element {
+  const [expanded, setExpanded] = useState(props.initiallyExpanded ?? true);
+  return (
+    <View style={styles.section}>
+      <Pressable
+        accessibilityRole="button"
+        onPress={() => setExpanded((e) => !e)}
+        style={styles.header}
+      >
+        <Text style={styles.headerText}>{props.header}</Text>
+        <Ionicons
+          name={expanded ? 'chevron-up' : 'chevron-down'}
+          size={18}
+          color={Colors.spareBlue}
+        />
+      </Pressable>
+      {expanded ? <View style={styles.body}>{props.children}</View> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    backgroundColor: Colors.cardMutedBg,
+    borderRadius: 16,
+    paddingVertical: 8,
+    paddingHorizontal: 0,
+    marginBottom: 14,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: Colors.divider,
+    shadowColor: '#404029',
+    shadowOpacity: 0.08,
+    shadowRadius: 4,
+    shadowOffset: { width: 0, height: 1 },
+    elevation: 2,
+  },
+  section: { paddingVertical: 8 },
+  header: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingHorizontal: 20,
+    minHeight: 48,
+  },
+  headerText: {
+    fontFamily: linkFontFamilyForWeight('700'),
+    fontSize: 16,
+    fontWeight: '700',
+    color: Colors.textPrimary,
+  },
+  body: { paddingTop: 4, paddingBottom: 12 },
+  divider: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: Colors.divider,
+    marginHorizontal: 20,
+    marginVertical: 4,
+  },
+});

package/src/ui/consent/consent-summary-section.tsx

@@ -0,0 +1,19 @@
+import type { ConsentSummaryData } from '../../core/services/consent-presenter';
+import { InternationalPaymentSummary } from './international-payment-summary';
+import { MultiPaymentSummary } from './multi-payment-summary';
+import { SinglePaymentSummary } from './single-payment-summary';
+
+export interface ConsentSummarySectionProps {
+  data: ConsentSummaryData;
+}
+
+export function ConsentSummarySection(props: ConsentSummarySectionProps): JSX.Element {
+  switch (props.data.variant) {
+    case 'singlePayment':
+      return <SinglePaymentSummary data={props.data} />;
+    case 'international':
+      return <InternationalPaymentSummary data={props.data} />;
+    case 'multiPayment':
+      return <MultiPaymentSummary data={props.data} />;
+  }
+}

package/src/ui/consent/cop-information.tsx

@@ -0,0 +1,121 @@
+import { Ionicons } from '@expo/vector-icons';
+import { useEffect, useRef } from 'react';
+import { Animated, StyleSheet, Text, View } from 'react-native';
+import type { CopDisplayData, CopMatchIndicator } from '../../core/services/consent-presenter';
+import { Colors, FONT_FAMILY } from '../theme';
+
+/** Matches {@link LabelValueRows} default horizontal inset inside accordions. */
+const ACCORDION_BODY_INSET = 20;
+
+const COP_COLORS: Record<CopMatchIndicator, string> = {
+  match: '#81C784',
+  partialMatch: '#E57373',
+  noMatch: '#FFB74D',
+  unknown: Colors.textMuted,
+};
+
+const COP_ICONS: Record<CopMatchIndicator, keyof typeof Ionicons.glyphMap> = {
+  match: 'checkmark-circle-outline',
+  partialMatch: 'warning-outline',
+  noMatch: 'close-circle-outline',
+  unknown: 'information-circle-outline',
+};
+
+export function CopLoadingPlaceholder(): JSX.Element {
+  const opacity = useRef(new Animated.Value(0.35)).current;
+
+  useEffect(() => {
+    const animation = Animated.loop(
+      Animated.sequence([
+        Animated.timing(opacity, { toValue: 1, duration: 450, useNativeDriver: true }),
+        Animated.timing(opacity, { toValue: 0.35, duration: 450, useNativeDriver: true }),
+      ]),
+    );
+    animation.start();
+    return () => animation.stop();
+  }, [opacity]);
+
+  return (
+    <View style={styles.loadingRow} testID="consent-cop-loading">
+      <Animated.View style={[styles.loadingBar, styles.loadingBarWide, { opacity }]} />
+      <Animated.View style={[styles.loadingBar, styles.loadingBarNarrow, { opacity }]} />
+    </View>
+  );
+}
+
+export function CopInformation(props: { display: CopDisplayData }): JSX.Element {
+  const { display } = props;
+  const color = COP_COLORS[display.indicator];
+  const icon = COP_ICONS[display.indicator];
+
+  if (display.indicator === 'match') {
+    return (
+      <View style={styles.matchRow} testID="consent-cop-information">
+        <Text style={[styles.statusLabel, { color }]}>{display.statusLabel}</Text>
+        <Ionicons name={icon} size={18} color={color} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.column} testID="consent-cop-information">
+      <View style={styles.statusRow}>
+        <View style={styles.statusLeft}>
+          <Ionicons name={icon} size={18} color={color} />
+          <Text style={[styles.statusLabel, { color }]}>{display.statusLabel}</Text>
+        </View>
+        {display.maskedName ? <Text style={styles.maskedName}>{display.maskedName}</Text> : null}
+      </View>
+      {display.paragraphs.map((paragraph) => (
+        <Text key={paragraph} style={[styles.paragraph, { color }]}>
+          {paragraph}
+        </Text>
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  loadingRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingTop: 4,
+    paddingHorizontal: ACCORDION_BODY_INSET,
+  },
+  loadingBar: {
+    height: 12,
+    backgroundColor: '#E5E7EB',
+    borderRadius: 4,
+  },
+  loadingBarWide: { width: 96 },
+  loadingBarNarrow: { width: 48 },
+  matchRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingTop: 4,
+    paddingHorizontal: ACCORDION_BODY_INSET,
+  },
+  column: {
+    gap: 8,
+    paddingTop: 4,
+    paddingHorizontal: ACCORDION_BODY_INSET,
+  },
+  statusRow: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    justifyContent: 'space-between',
+    gap: 8,
+  },
+  statusLeft: { flexDirection: 'row', alignItems: 'center', gap: 4, flex: 1 },
+  statusLabel: { fontFamily: FONT_FAMILY, fontSize: 14, fontWeight: '500' },
+  maskedName: {
+    fontFamily: FONT_FAMILY,
+    fontSize: 14,
+    color: Colors.textMuted,
+    textAlign: 'right',
+    flex: 1,
+  },
+  paragraph: { fontFamily: FONT_FAMILY, fontSize: 14, lineHeight: 22, fontWeight: '400' },
+});