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

package/src/core/models/payment-return-params.ts

@@ -0,0 +1,34 @@
+/**
+ * Query-parameter helpers for bank / authorize return URIs.
+ *
+ * The Link service appends `exchange_code` on success and `error_code` on
+ * authorize failure (legacy integrations may still send `error`).
+ */
+
+export function isPaymentReturnCallbackUri(uri: URL | string): boolean {
+  let parsed: URL;
+  try {
+    parsed = typeof uri === 'string' ? new URL(uri) : uri;
+  } catch {
+    return false;
+  }
+  const params = parsed.searchParams;
+  if (params.has('exchange_code')) return true;
+  if (params.has('error_code')) return true;
+  if (params.has('error')) return true;
+  if (params.get('status') === 'failure') return true;
+  return false;
+}
+
+/**
+ * Extract the failure code from a payment-return URI, if present.
+ *
+ * `error_code` takes precedence over the legacy `error` query param. A
+ * `status=failure` with no other code resolves to `'authorize_failed'`.
+ */
+export function extractPaymentReturnErrorCode(params: URLSearchParams): string | undefined {
+  const code = params.get('error_code') ?? params.get('error');
+  if (code && code.length > 0) return code;
+  if (params.get('status') === 'failure') return 'authorize_failed';
+  return undefined;
+}

package/src/core/models/payment-type.ts

@@ -0,0 +1,54 @@
+import type { CreatePaymentRequestInput } from './index';
+
+export enum PaymentType {
+  singleInstantPayment = 'SingleInstantPayment',
+  fixedDefinedSchedule = 'FixedDefinedSchedule',
+  variableDefinedSchedule = 'VariableDefinedSchedule',
+  fixedPeriodicSchedule = 'FixedPeriodicSchedule',
+  variablePeriodicSchedule = 'VariablePeriodicSchedule',
+  fixedOnDemand = 'FixedOnDemand',
+  variableOnDemand = 'VariableOnDemand',
+  internationalPayment = 'InternationalPayment',
+}
+
+export type ConsentUiVariant = 'singlePayment' | 'international' | 'multiPayment';
+
+const MANDATE_TYPES = new Set<string>([
+  PaymentType.fixedDefinedSchedule,
+  PaymentType.variableDefinedSchedule,
+  PaymentType.fixedPeriodicSchedule,
+  PaymentType.variablePeriodicSchedule,
+  PaymentType.fixedOnDemand,
+  PaymentType.variableOnDemand,
+]);
+
+export function resolvedPaymentType(request: CreatePaymentRequestInput): PaymentType {
+  const t = request.type;
+  if (Object.values(PaymentType).includes(t as PaymentType)) {
+    return t as PaymentType;
+  }
+  return PaymentType.singleInstantPayment;
+}
+
+export function isMultiPayment(request: CreatePaymentRequestInput): boolean {
+  return MANDATE_TYPES.has(request.type);
+}
+
+export function isInternational(request: CreatePaymentRequestInput): boolean {
+  return (
+    request.instructions.isInternationalPayment === true ||
+    resolvedPaymentType(request) === PaymentType.internationalPayment
+  );
+}
+
+export function supportsConfirmationOfPayee(request: CreatePaymentRequestInput): boolean {
+  return (
+    resolvedPaymentType(request) === PaymentType.singleInstantPayment && !isInternational(request)
+  );
+}
+
+export function consentUiVariant(request: CreatePaymentRequestInput): ConsentUiVariant {
+  if (isMultiPayment(request)) return 'multiPayment';
+  if (isInternational(request)) return 'international';
+  return 'singlePayment';
+}

package/src/core/models/wire-mappers.ts

@@ -0,0 +1,315 @@
+/**
+ * Pure functions translating snake_case wire payloads from tofa into camelCase
+ * SDK models. Kept separate from the API client so they're trivially unit-testable
+ * without HTTP setup.
+ */
+
+import type {
+  AmountDto,
+  ConsentResponse,
+  CopResponse,
+  CreatePaymentRequestInput,
+  CurrencyRequest,
+  LinkSessionResponse,
+  LinkStatusResponse,
+  PatchTokenResponse,
+  PaymentInstructions,
+  PaymentScheduleEntry,
+  PeriodicControls,
+  PeriodicSchedule,
+  ProviderCountry,
+  ProviderSummary,
+  TelemetryResponse,
+} from './index';
+
+type Json = Record<string, unknown>;
+
+function asString(v: unknown, field: string): string {
+  if (typeof v !== 'string') {
+    throw new TypeError(`Expected string for ${field}, got ${typeof v}`);
+  }
+  return v;
+}
+
+function asOptionalString(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function asBool(v: unknown, field: string): boolean {
+  if (typeof v !== 'boolean') {
+    throw new TypeError(`Expected boolean for ${field}, got ${typeof v}`);
+  }
+  return v;
+}
+
+function asObject(v: unknown, field: string): Json {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+    throw new TypeError(`Expected object for ${field}, got ${typeof v}`);
+  }
+  return v as Json;
+}
+
+function asArray(v: unknown, field: string): unknown[] {
+  if (!Array.isArray(v)) {
+    throw new TypeError(`Expected array for ${field}, got ${typeof v}`);
+  }
+  return v;
+}
+
+function asOptionalInt(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function mapAmount(raw: unknown, field: string): AmountDto {
+  const o = asObject(raw, field);
+  return {
+    amount: asString(o.amount, `${field}.amount`),
+    currency: asString(o.currency, `${field}.currency`),
+  };
+}
+
+function mapOptionalAmount(raw: unknown, field: string): AmountDto | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  return mapAmount(raw, field);
+}
+
+function mapPeriodicControls(raw: unknown): PeriodicControls {
+  const o = asObject(raw, 'periodicSchedule.controls');
+  const out: PeriodicControls = {};
+  const maxAmount = mapOptionalAmount(
+    o.maxCumulativeAmountPerPeriod,
+    'periodicSchedule.controls.maxCumulativeAmountPerPeriod',
+  );
+  if (maxAmount) out.maxCumulativeAmountPerPeriod = maxAmount;
+  const maxPayments = asOptionalInt(o.maxCumulativeNumberOfPaymentsPerPeriod);
+  if (maxPayments !== undefined) out.maxCumulativeNumberOfPaymentsPerPeriod = maxPayments;
+  return out;
+}
+
+function mapPeriodicSchedule(raw: unknown): PeriodicSchedule {
+  const o = asObject(raw, 'instructions.periodicSchedule');
+  const out: PeriodicSchedule = {};
+  const frequency = asOptionalString(o.frequency);
+  if (frequency) out.frequency = frequency;
+  const startDate = asOptionalString(o.startDate);
+  if (startDate) out.startDate = startDate;
+  const endDate = asOptionalString(o.endDate);
+  if (endDate) out.endDate = endDate;
+  const amount = mapOptionalAmount(o.amount, 'instructions.periodicSchedule.amount');
+  if (amount) out.amount = amount;
+  const maxAmount = mapOptionalAmount(o.maxAmount, 'instructions.periodicSchedule.maxAmount');
+  if (maxAmount) out.maxAmount = maxAmount;
+  if (o.controls !== undefined && o.controls !== null) {
+    out.controls = mapPeriodicControls(o.controls);
+  }
+  return out;
+}
+
+function mapPaymentScheduleEntry(raw: unknown, idx: number): PaymentScheduleEntry {
+  const o = asObject(raw, `instructions.paymentSchedule[${idx}]`);
+  const out: PaymentScheduleEntry = {};
+  const amount = mapOptionalAmount(o.amount, `instructions.paymentSchedule[${idx}].amount`);
+  if (amount) out.amount = amount;
+  const maxAmount = mapOptionalAmount(
+    o.maxAmount,
+    `instructions.paymentSchedule[${idx}].maxAmount`,
+  );
+  if (maxAmount) out.maxAmount = maxAmount;
+  const paymentExecutionDate = asOptionalString(o.paymentExecutionDate);
+  if (paymentExecutionDate) out.paymentExecutionDate = paymentExecutionDate;
+  return out;
+}
+
+function mapCurrencyRequest(raw: unknown): CurrencyRequest {
+  const o = asObject(raw, 'instructions.currencyRequest');
+  const out: CurrencyRequest = {};
+  const priority = asOptionalString(o.priority);
+  if (priority) out.priority = priority;
+  const purpose = asOptionalString(o.purpose);
+  if (purpose) out.purpose = purpose;
+  const chargeBearer = asOptionalString(o.chargeBearer);
+  if (chargeBearer) out.chargeBearer = chargeBearer;
+  return out;
+}
+
+function mapPaymentInstructions(raw: unknown): PaymentInstructions {
+  const o = asObject(raw, 'request.instructions');
+  const out: PaymentInstructions = {};
+  if (o.amount !== undefined && o.amount !== null) {
+    out.amount = mapAmount(o.amount, 'request.instructions.amount');
+  }
+  if (typeof o.isInternationalPayment === 'boolean') {
+    out.isInternationalPayment = o.isInternationalPayment;
+  }
+  const maxPayments = asOptionalInt(o.maxCumulativeNumberOfPayments);
+  if (maxPayments !== undefined) out.maxCumulativeNumberOfPayments = maxPayments;
+  const maxCumulativeAmount = mapOptionalAmount(
+    o.maxCumulativeAmount,
+    'request.instructions.maxCumulativeAmount',
+  );
+  if (maxCumulativeAmount) out.maxCumulativeAmount = maxCumulativeAmount;
+  if (o.paymentSchedule !== undefined && o.paymentSchedule !== null) {
+    const entries = asArray(o.paymentSchedule, 'request.instructions.paymentSchedule');
+    out.paymentSchedule = entries.map((entry, idx) => mapPaymentScheduleEntry(entry, idx));
+  }
+  if (o.periodicSchedule !== undefined && o.periodicSchedule !== null) {
+    out.periodicSchedule = mapPeriodicSchedule(o.periodicSchedule);
+  }
+  if (o.currencyRequest !== undefined && o.currencyRequest !== null) {
+    out.currencyRequest = mapCurrencyRequest(o.currencyRequest);
+  }
+  return out;
+}
+
+export function mapCreatePaymentRequestInput(raw: unknown): CreatePaymentRequestInput {
+  const o = asObject(raw, 'request');
+  const creditorAccount = asObject(o.creditorAccount, 'request.creditorAccount');
+  const out: CreatePaymentRequestInput = {
+    id: asString(o.id, 'request.id'),
+    internalReference: asString(o.internalReference, 'request.internalReference'),
+    status: asString(o.status, 'request.status'),
+    type: asString(o.type, 'request.type'),
+    creditorType: asString(o.creditorType, 'request.creditorType'),
+    purpose: asString(o.purpose, 'request.purpose'),
+    merchantReference: asString(o.merchantReference, 'request.merchantReference'),
+    createdAt: asString(o.createdAt, 'request.createdAt'),
+    updatedAt: asString(o.updatedAt, 'request.updatedAt'),
+    isCopVerified: asBool(o.isCopVerified, 'request.isCopVerified'),
+    creditorAccount: {
+      schemeName: asString(creditorAccount.schemeName, 'request.creditorAccount.schemeName'),
+      identification: asString(
+        creditorAccount.identification,
+        'request.creditorAccount.identification',
+      ),
+    },
+    instructions: mapPaymentInstructions(o.instructions),
+  };
+  const creditorName = asOptionalString(creditorAccount.name);
+  if (creditorName) out.creditorAccount.name = creditorName;
+  const ref = asOptionalString(o.creditorReference);
+  if (ref) out.creditorReference = ref;
+  return out;
+}
+
+export function mapLinkSessionResponse(raw: unknown): LinkSessionResponse {
+  const o = asObject(raw, 'data');
+  const out: LinkSessionResponse = {
+    request: mapCreatePaymentRequestInput(o.request),
+  };
+  const providerId = asOptionalString(o.providerId ?? o.provider_id);
+  if (providerId) out.providerId = providerId;
+  return out;
+}
+
+export function mapConsentResponse(raw: unknown): ConsentResponse {
+  const o = asObject(raw, 'data');
+  const redirectUrl = asString(o.redirect_url ?? o.redirectUrl, 'data.redirect_url');
+  const out: ConsentResponse = { redirectUrl };
+  const mobileAppUrl = asOptionalString(o.mobile_app_url ?? o.mobileAppUrl);
+  if (mobileAppUrl) out.mobileAppUrl = mobileAppUrl;
+  return out;
+}
+
+export function mapLinkStatusResponse(raw: unknown): LinkStatusResponse {
+  const o = asObject(raw, 'data');
+  const out: LinkStatusResponse = {
+    linkSessionId: asString(o.link_session_id ?? o.linkSessionId, 'data.link_session_id'),
+    status: asString(o.status, 'data.status'),
+    intent: asString(o.intent, 'data.intent'),
+    resourceType: asString(o.resource_type ?? o.resourceType, 'data.resource_type'),
+    expiresAt: asString(o.expires_at ?? o.expiresAt, 'data.expires_at'),
+  };
+  const failureCode = asOptionalString(o.failure_code ?? o.failureCode);
+  if (failureCode) out.failureCode = failureCode;
+  const cancelledAt = asOptionalString(o.cancelled_at ?? o.cancelledAt);
+  if (cancelledAt) out.cancelledAt = cancelledAt;
+  const completedAt = asOptionalString(o.completed_at ?? o.completedAt);
+  if (completedAt) out.completedAt = completedAt;
+  const failedAt = asOptionalString(o.failed_at ?? o.failedAt);
+  if (failedAt) out.failedAt = failedAt;
+  return out;
+}
+
+export function mapCopResponse(raw: unknown): CopResponse {
+  const o = asObject(raw, 'data');
+  // tofa returns camelCase `matchIndicator`; we accept both casings to be tolerant.
+  const out: CopResponse = {
+    matchIndicator: asString(o.matchIndicator ?? o.match_indicator, 'data.matchIndicator'),
+  };
+  const maskedName = asOptionalString(o.maskedName ?? o.masked_name);
+  if (maskedName) out.maskedName = maskedName;
+  return out;
+}
+
+export function mapTelemetryResponse(raw: unknown): TelemetryResponse {
+  // tofa returns `{}` today — anything in there is bonus.
+  const o = asObject(raw, 'data');
+  const out: TelemetryResponse = {};
+  if (typeof o.accepted === 'boolean') out.accepted = o.accepted;
+  const linkSessionId = asOptionalString(o.link_session_id ?? o.linkSessionId);
+  if (linkSessionId) out.linkSessionId = linkSessionId;
+  return out;
+}
+
+export function mapPatchTokenResponse(raw: unknown): PatchTokenResponse {
+  const o = asObject(raw, 'data');
+  const out: PatchTokenResponse = { status: asString(o.status, 'data.status') };
+  const linkSessionRaw = o.link_session ?? o.linkSession;
+  if (linkSessionRaw) {
+    const ls = asObject(linkSessionRaw, 'data.link_session');
+    out.linkSession = {
+      linkSessionId: asString(
+        ls.link_session_id ?? ls.linkSessionId,
+        'link_session.link_session_id',
+      ),
+      status: asString(ls.status, 'link_session.status'),
+      cancelledAt: (asOptionalString(ls.cancelled_at ?? ls.cancelledAt) ?? null) as string | null,
+      failedAt: (asOptionalString(ls.failed_at ?? ls.failedAt) ?? null) as string | null,
+      failureCode: (asOptionalString(ls.failure_code ?? ls.failureCode) ?? null) as string | null,
+    };
+  }
+  return out;
+}
+
+export function mapProviderCountry(raw: unknown): ProviderCountry {
+  const o = asObject(raw, 'country');
+  return {
+    englishName: asString(o.englishName, 'country.englishName'),
+    iso3166Code: asString(o.iso3166Code, 'country.iso3166Code'),
+  };
+}
+
+export function mapProviderSummary(raw: unknown): ProviderSummary {
+  const o = asObject(raw, 'provider');
+  // tofa providers don't always carry an id at the top level — fall back to code.
+  const id = asOptionalString(o.id) ?? asString(o.code, 'provider.code');
+  return {
+    id,
+    code: asString(o.code, 'provider.code'),
+    name: asString(o.name, 'provider.name'),
+    logoUrl: asOptionalString(o.logoUrl ?? o.logo) ?? '',
+    status: asString(o.status, 'provider.status'),
+    country: o.country ? mapProviderCountry(o.country) : { englishName: '', iso3166Code: '' },
+  };
+}
+
+export function mapProvidersResponse(raw: unknown): ProviderSummary[] {
+  const arr = asArray(raw, 'data');
+  return arr.map((p, idx) =>
+    mapProviderSummary(
+      p ??
+        (() => {
+          throw new TypeError(`providers[${idx}] is null`);
+        })(),
+    ),
+  );
+}
+
+/** Unwraps the tofa `{ data: ... }` success envelope. */
+export function unwrap(payload: unknown): unknown {
+  const o = asObject(payload, 'response');
+  if (!('data' in o)) {
+    throw new TypeError('Response missing { data } envelope');
+  }
+  return o.data;
+}

package/src/core/services/consent-presenter.ts

@@ -0,0 +1,213 @@
+import type { CopResponse } from '../models';
+import {
+  type ConsentUiVariant,
+  type PaymentType,
+  consentUiVariant,
+  resolvedPaymentType,
+} from '../models/payment-type';
+import {
+  type LabelValueRow,
+  buildMultiPaymentRules,
+  rulesSectionTitle,
+} from './multi-payment-rules-presenter';
+import type { PaymentFlowState } from './payment-flow-state';
+import { formatAmount } from './presentation-utils';
+
+export { formatAmount } from './presentation-utils';
+
+/** CoP match outcome, normalized from {@link CopResponse.matchIndicator}. */
+export type CopMatchIndicator = 'match' | 'partialMatch' | 'noMatch' | 'unknown';
+
+/** User-facing Confirmation-of-Payee copy for the consent screen. */
+export interface CopDisplayData {
+  statusLabel: string;
+  indicator: CopMatchIndicator;
+  maskedName?: string;
+  paragraphs: string[];
+}
+
+interface ConsentSummaryDataBase {
+  bankName: string;
+  variant: ConsentUiVariant;
+}
+
+/** Domestic single instant payment consent summary. */
+export interface SinglePaymentSummaryData extends ConsentSummaryDataBase {
+  variant: 'singlePayment';
+  formattedAmount: string;
+  iban: string;
+  paymentReference: string | undefined;
+  paymentPurpose: string | undefined;
+  creditorName: string | undefined;
+  isCopLoading: boolean;
+  copDisplay: CopDisplayData | undefined;
+}
+
+/** Multi-payment (mandate) consent summary. */
+export interface MultiPaymentSummaryData extends ConsentSummaryDataBase {
+  variant: 'multiPayment';
+  paymentType: PaymentType;
+  creditorType: string;
+  externalReference: string;
+  paymentPurpose: string | undefined;
+  rulesTitle: string;
+  rules: LabelValueRow[];
+  iban: string;
+  creditorName: string | undefined;
+}
+
+/** International payment consent summary. */
+export interface InternationalPaymentSummaryData extends ConsentSummaryDataBase {
+  variant: 'international';
+  formattedAmount: string;
+  iban: string;
+  paymentReference: string | undefined;
+  paymentPurpose: string | undefined;
+  priority: string | undefined;
+  chargeBearer: string | undefined;
+  creditorName: string | undefined;
+}
+
+export type ConsentSummaryData =
+  | SinglePaymentSummaryData
+  | InternationalPaymentSummaryData
+  | MultiPaymentSummaryData;
+
+/** @deprecated Use {@link ConsentSummaryData} instead. */
+export type ConsentDisplayData = SinglePaymentSummaryData;
+
+function present(value: string | undefined, fallback = '—'): string {
+  const v = value?.trim();
+  return v ? v : fallback;
+}
+
+export { present as presentField };
+
+function parseMatchIndicator(raw: string): CopMatchIndicator {
+  switch (raw) {
+    case 'Match':
+      return 'match';
+    case 'PartialMatch':
+      return 'partialMatch';
+    case 'NoMatch':
+      return 'noMatch';
+    default:
+      return 'unknown';
+  }
+}
+
+const UNAVAILABLE_COP: CopDisplayData = {
+  statusLabel: 'Unavailable',
+  indicator: 'unknown',
+  paragraphs: [
+    'The Payee Confirmation Service is not available right now for this account.',
+    'Your payment could go to the wrong person or organization. Please retry later when the service is available OR proceed at your own risk to make the payment to this account.',
+  ],
+};
+
+/**
+ * Maps a {@link CopResponse} to consent-screen copy. Ported from the Flutter
+ * SDK's `ConsentPresenter.formatCop`. Returns unavailable messaging when there
+ * is no response (API error or not yet fetched).
+ */
+export function formatCop(response: CopResponse | undefined): CopDisplayData {
+  if (!response) return UNAVAILABLE_COP;
+
+  const indicator = parseMatchIndicator(response.matchIndicator);
+  const maskedName = presentMaskedName(response.maskedName);
+
+  switch (indicator) {
+    case 'match':
+      return { statusLabel: 'Confirmed', indicator, paragraphs: [] };
+    case 'partialMatch':
+      return {
+        statusLabel: 'Partial Match',
+        indicator,
+        ...(maskedName ? { maskedName } : {}),
+        paragraphs: [
+          'The Name you provided is similar to, but does NOT match the Name of the account owner.',
+          'Your payment could go to the wrong person or organization. Please go back to re-enter the Payee details OR proceed at your own risk to make the payment to this account.',
+        ],
+      };
+    case 'noMatch':
+      return {
+        statusLabel: 'No Match',
+        indicator,
+        ...(maskedName ? { maskedName } : {}),
+        paragraphs: [
+          'The Name you provided does NOT match the Name of the account owner.',
+          'Your payment could go to the wrong person or organization. Please go back to re-enter the Payee Name OR proceed at your own risk to make the payment to this account.',
+        ],
+      };
+    default:
+      return UNAVAILABLE_COP;
+  }
+}
+
+function presentMaskedName(maskedName: string | undefined): string | undefined {
+  const v = maskedName?.trim();
+  return v ? v : undefined;
+}
+
+export function summaryFromState(state: PaymentFlowState): ConsentSummaryData | null {
+  if (state.phase !== 'consentDetails') return null;
+  const session = state.session;
+  const provider = state.selectedProvider;
+  if (!session || !provider) return null;
+
+  const request = session.request;
+  const bankName = provider.name;
+  const variant = consentUiVariant(request);
+
+  if (variant === 'multiPayment') {
+    const paymentType = resolvedPaymentType(request);
+    return {
+      variant: 'multiPayment',
+      bankName,
+      paymentType,
+      creditorType: request.creditorType,
+      externalReference: request.merchantReference,
+      paymentPurpose: request.purpose,
+      rulesTitle: rulesSectionTitle(paymentType),
+      rules: buildMultiPaymentRules(paymentType, request.instructions),
+      iban: request.creditorAccount.identification,
+      creditorName: request.creditorAccount.name ?? request.creditorReference,
+    };
+  }
+
+  if (variant === 'international') {
+    return {
+      variant: 'international',
+      bankName,
+      formattedAmount: formatAmount(request.instructions.amount),
+      iban: request.creditorAccount.identification,
+      paymentReference: request.merchantReference,
+      paymentPurpose: request.purpose,
+      priority: request.instructions.currencyRequest?.priority,
+      chargeBearer: request.instructions.currencyRequest?.chargeBearer,
+      creditorName: request.creditorAccount.name ?? request.creditorReference,
+    };
+  }
+
+  return {
+    variant: 'singlePayment',
+    bankName,
+    formattedAmount: formatAmount(request.instructions.amount),
+    iban: request.creditorAccount.identification,
+    paymentReference: request.merchantReference,
+    paymentPurpose: request.purpose,
+    creditorName: request.creditorAccount.name ?? request.creditorReference,
+    isCopLoading: (state.copApplicable ?? false) && (state.isCopLoading ?? false),
+    copDisplay:
+      (state.copApplicable ?? false) && !state.isCopLoading
+        ? formatCop(state.copResponse)
+        : undefined,
+  };
+}
+
+/** @deprecated Use {@link summaryFromState} instead. */
+export function presentConsent(state: PaymentFlowState): SinglePaymentSummaryData | null {
+  const summary = summaryFromState(state);
+  if (!summary || summary.variant !== 'singlePayment') return null;
+  return summary;
+}