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

package/src/core/services/execute-resume-if-needed.ts

@@ -0,0 +1,243 @@
+import { kMaxRecoveryAttempts } from '../../public/constants';
+import type { PaymentResult } from '../../public/payment-result';
+import { paymentCancelled, paymentFailed, paymentSuccess } from '../../public/payment-result';
+import type { SpareLinkCallbacks } from '../../public/spare-link-callbacks';
+import {
+  type SpareLinkResumeConfig,
+  defaultBaseUrlFor,
+  tenantCountryCode,
+} from '../../public/spare-link-config';
+import { LinkApiClient } from '../client/link-api-client';
+import type { PendingSessionRecord } from '../models';
+import { PaymentFlowController } from './payment-flow-controller';
+import { paymentResultFromFlowState } from './payment-result-mapper';
+import type { PendingSessionStore } from './pending-session-store';
+import { consumeBufferedRedirect, peekBufferedRedirect } from './redirect-buffer';
+
+export const MAX_RECOVERABLE_AGE_MS = 30 * 60 * 1000;
+
+export interface ResumeSessionArgs {
+  config: SpareLinkResumeConfig;
+  callbacks?: SpareLinkCallbacks;
+}
+
+export interface ResumeSessionDeps {
+  pendingSessionStore: PendingSessionStore;
+  /** True when a live modal flow is already mounted. */
+  isFlowActive: () => boolean;
+  /** Open the SDK modal parked at awaitingCallback for non-terminal recovery. */
+  openRecoveryFlow: (args: {
+    controller: PaymentFlowController;
+    config: SpareLinkResumeConfig & { linkToken: string };
+    callbacks?: SpareLinkCallbacks;
+  }) => void;
+  now?: () => number;
+}
+
+function merchantRefFromUri(uri: string): string | undefined {
+  try {
+    const value = new URL(uri).searchParams.get('merchantRef');
+    return value && value.length > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Requires a positive `merchantRef` bind between the buffered URI and the
+ * pending record — if either side lacks one we can't confirm the URI belongs
+ * to this session, so it must not be applied (a stale/unbound URI could
+ * otherwise attach to the wrong pending session).
+ */
+function bufferedUriMatchesRecord(uri: string, record: PendingSessionRecord): boolean {
+  const uriMerchantRef = merchantRefFromUri(uri);
+  if (!record.merchantRef || !uriMerchantRef) return false;
+  return record.merchantRef === uriMerchantRef;
+}
+
+function createResumeApiClient(config: SpareLinkResumeConfig): LinkApiClient {
+  return new LinkApiClient({
+    baseUrl: config.baseUrl ?? defaultBaseUrlFor(config.environment),
+    tenant: tenantCountryCode(config.tenant),
+    ...(config.fetch ? { fetch: config.fetch } : {}),
+    ...(config.requestTimeoutMs !== undefined ? { requestTimeoutMs: config.requestTimeoutMs } : {}),
+  });
+}
+
+function createRecoveryController(
+  record: PendingSessionRecord,
+  config: SpareLinkResumeConfig,
+  store: PendingSessionStore,
+  callbacks?: SpareLinkCallbacks,
+): PaymentFlowController {
+  return new PaymentFlowController({
+    sessionToken: record.sessionId,
+    environment: config.environment,
+    apiClient: createResumeApiClient(config),
+    pendingSessionStore: store,
+    ...(callbacks?.onEvent ? { onEvent: callbacks.onEvent } : {}),
+  });
+}
+
+async function terminalFromBufferedUri(
+  record: PendingSessionRecord,
+  config: SpareLinkResumeConfig,
+  store: PendingSessionStore,
+  bufferedUri: string,
+  callbacks?: SpareLinkCallbacks,
+): Promise<PaymentResult | null> {
+  const controller = createRecoveryController(record, config, store, callbacks);
+  try {
+    controller.handleCallback(bufferedUri);
+    const result = paymentResultFromFlowState(
+      controller.state,
+      record.sessionId,
+      record.selectedBankId,
+    );
+    if (
+      result &&
+      (controller.state.phase === 'succeeded' ||
+        controller.state.phase === 'failed' ||
+        controller.state.phase === 'cancelled')
+    ) {
+      await store.clear();
+      return result;
+    }
+    return null;
+  } finally {
+    controller.dispose();
+  }
+}
+
+/**
+ * Cold-start recovery orchestrator — mirrors Flutter `SpareLink.resumeIfNeeded`.
+ * Returns a terminal {@link PaymentResult}, `null` when nothing to do / still
+ * pending, and opens the recovery UI via `openRecoveryFlow` for non-terminal
+ * sessions that need user-visible awaiting state.
+ */
+export async function executeResumeIfNeeded(
+  args: ResumeSessionArgs,
+  deps: ResumeSessionDeps,
+): Promise<PaymentResult | null> {
+  const { pendingSessionStore: store } = deps;
+  const now = deps.now ?? (() => Date.now());
+
+  if (deps.isFlowActive()) return null;
+
+  let record: PendingSessionRecord | null;
+  try {
+    record = await store.load();
+  } catch {
+    return null;
+  }
+  if (!record) return null;
+
+  if (record.consentAt !== undefined && now() - record.consentAt > MAX_RECOVERABLE_AGE_MS) {
+    await store.clear();
+    return paymentFailed({
+      linkToken: record.sessionId,
+      errorCode: 'session_expired',
+      message: 'Pending session is older than the recovery window.',
+      resolvedAtMs: now(),
+    });
+  }
+
+  if (record.recoveryAttempts >= kMaxRecoveryAttempts) {
+    await store.clear();
+    return paymentFailed({
+      linkToken: record.sessionId,
+      errorCode: 'recovery_exhausted',
+      message: 'Maximum recovery attempts reached.',
+      resolvedAtMs: now(),
+    });
+  }
+
+  // Peek first — only consume the buffered URI once we've positively bound it
+  // to this record. On mismatch, leave it alone so a genuinely-matching
+  // session (checked on a later resume attempt) can still claim it.
+  const bufferedUri = peekBufferedRedirect();
+  if (bufferedUri && bufferedUriMatchesRecord(bufferedUri, record)) {
+    consumeBufferedRedirect();
+    return terminalFromBufferedUri(record, args.config, store, bufferedUri, args.callbacks);
+  }
+
+  const apiClient = createResumeApiClient(args.config);
+  try {
+    const status = await apiClient.getStatus(record.sessionId);
+    await store.save({
+      ...record,
+      recoveryAttempts: record.recoveryAttempts + 1,
+    });
+
+    switch (status.status) {
+      case 'completed':
+        await store.clear();
+        return paymentSuccess({
+          linkToken: record.sessionId,
+          bankId: record.selectedBankId,
+          ...(status.linkSessionId ? { linkSessionId: status.linkSessionId } : {}),
+          resolvedAtMs: now(),
+        });
+      case 'failed':
+        await store.clear();
+        return paymentFailed({
+          linkToken: record.sessionId,
+          errorCode: status.failureCode ?? 'session_failed',
+          resolvedAtMs: now(),
+        });
+      case 'cancelled':
+        await store.clear();
+        return paymentCancelled({
+          linkToken: record.sessionId,
+          bankId: record.selectedBankId,
+          resolvedAtMs: now(),
+        });
+      case 'expired':
+        await store.clear();
+        return paymentFailed({
+          linkToken: record.sessionId,
+          errorCode: 'session_expired',
+          resolvedAtMs: now(),
+        });
+      default: {
+        const controller = createRecoveryController(record, args.config, store, args.callbacks);
+        // Hydrate so `state.session` (payment type, mandate details) is
+        // available to the recovery UI and threaded into the terminal
+        // PaymentResult — without this, resume paths skip the mandate
+        // setup-success screen and drop `paymentType` on success.
+        await controller.hydrate().catch(() => {
+          /* best-effort — recovery still proceeds without session details */
+        });
+        controller.setAwaitingCallbackState({ providerName: record.selectedBankId });
+        deps.openRecoveryFlow({
+          controller,
+          config: { ...args.config, linkToken: record.sessionId },
+          ...(args.callbacks ? { callbacks: args.callbacks } : {}),
+        });
+        return null;
+      }
+    }
+  } catch {
+    const controller = createRecoveryController(record, args.config, store, args.callbacks);
+    await controller.hydrate().catch(() => {
+      /* best-effort — recovery still proceeds without session details */
+    });
+    controller.setAwaitingCallbackState({ providerName: record.selectedBankId });
+    try {
+      await store.save({
+        ...record,
+        recoveryAttempts: record.recoveryAttempts + 1,
+      });
+    } catch {
+      /* swallow */
+    }
+    deps.openRecoveryFlow({
+      controller,
+      config: { ...args.config, linkToken: record.sessionId },
+      ...(args.callbacks ? { callbacks: args.callbacks } : {}),
+    });
+    return null;
+  } finally {
+    apiClient.dispose();
+  }
+}

package/src/core/services/multi-payment-rules-presenter.ts

@@ -0,0 +1,158 @@
+import type { PaymentInstructions } from '../models';
+import { PaymentType } from '../models/payment-type';
+import { formatAmount } from './presentation-utils';
+
+export interface LabelValueRow {
+  label: string;
+  value: string;
+}
+
+function present(value: string | undefined, fallback = '—'): string {
+  const v = value?.trim();
+  return v ? v : fallback;
+}
+
+function presentInt(value: number | undefined, fallback = '—'): string {
+  if (value === undefined) return fallback;
+  return String(value);
+}
+
+function formatDate(raw: string | undefined): string {
+  if (!raw?.trim()) return '—';
+  const parsed = new Date(raw.trim());
+  if (Number.isNaN(parsed.getTime())) return raw.trim();
+  const months = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+  ];
+  const day = String(parsed.getUTCDate()).padStart(2, '0');
+  const month = months[parsed.getUTCMonth()];
+  return `${day} ${month} ${parsed.getUTCFullYear()}`;
+}
+
+function definedSchedule(type: PaymentType, instructions: PaymentInstructions): LabelValueRow[] {
+  const isFixed = type === PaymentType.fixedDefinedSchedule;
+  const amountLabel = isFixed ? 'Amount' : 'Max Amount';
+  const schedule = instructions.paymentSchedule ?? [];
+  const rows: LabelValueRow[] = [];
+  for (const entry of schedule) {
+    const amountDto = isFixed ? entry.amount : entry.maxAmount;
+    rows.push({ label: amountLabel, value: formatAmount(amountDto) });
+    rows.push({ label: 'Date', value: formatDate(entry.paymentExecutionDate) });
+  }
+  return rows;
+}
+
+function periodicSchedule(type: PaymentType, instructions: PaymentInstructions): LabelValueRow[] {
+  const isFixed = type === PaymentType.fixedPeriodicSchedule;
+  const periodic = instructions.periodicSchedule;
+  const amountDto = isFixed ? periodic?.amount : periodic?.maxAmount;
+  const amountLabel = isFixed ? 'Amount' : 'Max per Payment';
+  const rows: LabelValueRow[] = [
+    { label: amountLabel, value: formatAmount(amountDto) },
+    { label: 'First Payment Date', value: formatDate(periodic?.startDate) },
+    { label: 'Payment repeats every', value: present(periodic?.frequency) },
+    { label: 'Stop payment on', value: formatDate(periodic?.endDate) },
+    {
+      label: 'Total number of payments',
+      value: presentInt(instructions.maxCumulativeNumberOfPayments),
+    },
+  ];
+  if (!isFixed) {
+    rows.push({
+      label: 'Total Value Allowed',
+      value: formatAmount(instructions.maxCumulativeAmount),
+    });
+  }
+  return rows;
+}
+
+function fixedOnDemand(instructions: PaymentInstructions): LabelValueRow[] {
+  const periodic = instructions.periodicSchedule;
+  const frequency = periodic?.frequency;
+  return [
+    { label: 'Amount', value: formatAmount(periodic?.amount) },
+    {
+      label: 'Total number of payments allowed',
+      value: presentInt(instructions.maxCumulativeNumberOfPayments),
+    },
+    {
+      label: 'Total Value Allowed',
+      value: formatAmount(instructions.maxCumulativeAmount),
+    },
+    { label: 'Limits Every', value: present(frequency) },
+    {
+      label: `Max Value per ${present(frequency)}`,
+      value: formatAmount(periodic?.controls?.maxCumulativeAmountPerPeriod),
+    },
+    {
+      label: `Max Payments per ${present(frequency)}`,
+      value: presentInt(periodic?.controls?.maxCumulativeNumberOfPaymentsPerPeriod),
+    },
+    { label: 'Expiry Date', value: formatDate(periodic?.endDate) },
+  ];
+}
+
+function variableOnDemand(instructions: PaymentInstructions): LabelValueRow[] {
+  const periodic = instructions.periodicSchedule;
+  const frequency = periodic?.frequency;
+  return [
+    { label: 'First Payment Date', value: formatDate(periodic?.startDate) },
+    { label: 'Expiry Date', value: formatDate(periodic?.endDate) },
+    { label: 'Max per Payment', value: formatAmount(periodic?.maxAmount) },
+    {
+      label: 'Total number of payments allowed',
+      value: presentInt(instructions.maxCumulativeNumberOfPayments),
+    },
+    {
+      label: 'Total Value Allowed',
+      value: formatAmount(instructions.maxCumulativeAmount),
+    },
+    { label: 'Limits Every', value: present(frequency) },
+    {
+      label: `Max Value per ${present(frequency)}`,
+      value: formatAmount(periodic?.controls?.maxCumulativeAmountPerPeriod),
+    },
+    {
+      label: `Max Payments per ${present(frequency)}`,
+      value: presentInt(periodic?.controls?.maxCumulativeNumberOfPaymentsPerPeriod),
+    },
+  ];
+}
+
+export function buildMultiPaymentRules(
+  type: PaymentType,
+  instructions: PaymentInstructions,
+): LabelValueRow[] {
+  switch (type) {
+    case PaymentType.fixedDefinedSchedule:
+    case PaymentType.variableDefinedSchedule:
+      return definedSchedule(type, instructions);
+    case PaymentType.fixedPeriodicSchedule:
+    case PaymentType.variablePeriodicSchedule:
+      return periodicSchedule(type, instructions);
+    case PaymentType.fixedOnDemand:
+      return fixedOnDemand(instructions);
+    case PaymentType.variableOnDemand:
+      return variableOnDemand(instructions);
+    default:
+      return [];
+  }
+}
+
+export function rulesSectionTitle(type: PaymentType): string {
+  if (type === PaymentType.fixedDefinedSchedule || type === PaymentType.variableDefinedSchedule) {
+    return 'Payment schedule';
+  }
+  return 'Payment rules';
+}