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

package/plugins/with-spare-link.js

@@ -5,28 +5,25 @@
  * ```ts
  * plugins: [
  *   ['@spare-technologies/spare-link/expo-plugin', {
- *     locationUsageDescription: 'We use your location to verify the payment.',
  *     merchantScheme: 'sparemerchantrn',
  *     merchantHost: 'callback',
- *     universalLinkHost: 'link.krshnas.com', // optional
  *   }],
  * ]
  * ```
  *
+ * All this registers is the deep link the payer returns through. The SDK asks
+ * for no runtime permissions: the hosted page collects the bank's risk signals
+ * itself, so nothing here reads the device.
+ *
  * Written as plain CJS so the Expo CLI's plugin loader (which `require()`s
  * this file) works regardless of whether Node loads it as ESM or CJS.
  *
  * @typedef {Object} SpareLinkPluginOptions
- * @property {string} [locationUsageDescription]
  * @property {string} [merchantScheme]
  * @property {string} [merchantHost]
- * @property {string} [universalLinkHost]
  */
 
-const { AndroidConfig, withAndroidManifest, withInfoPlist } = require('@expo/config-plugins');
-
-const DEFAULT_LOCATION_DESCRIPTION =
-  'Spare Link uses your location to confirm the payment as part of the bank security checks.';
+const { withAndroidManifest, withInfoPlist } = require('@expo/config-plugins');
 
 /**
  * @param {import('@expo/config-plugins').ExpoConfig} config
@@ -36,10 +33,8 @@ function withSpareLink(config, props) {
   const opts = props ?? {};
   let next = config;
 
-  // iOS — location permission + URL scheme.
+  // iOS — the return URL scheme, and nothing else.
   next = withInfoPlist(next, (cfg) => {
-    cfg.modResults.NSLocationWhenInUseUsageDescription =
-      opts.locationUsageDescription ?? DEFAULT_LOCATION_DESCRIPTION;
     if (opts.merchantScheme) {
       const types = cfg.modResults.CFBundleURLTypes ?? [];
       const exists = types.some(
@@ -54,10 +49,6 @@ function withSpareLink(config, props) {
     return cfg;
   });
 
-  next = AndroidConfig.Permissions.withPermissions(next, [
-    'android.permission.ACCESS_FINE_LOCATION',
-  ]);
-
   if (opts.merchantScheme) {
     const scheme = opts.merchantScheme;
     next = withAndroidManifest(next, (cfg) => {
@@ -76,17 +67,6 @@ function withSpareLink(config, props) {
           ? [{ $: { 'android:scheme': scheme, 'android:host': opts.merchantHost } }]
           : [{ $: { 'android:scheme': scheme } }],
       });
-      if (opts.universalLinkHost) {
-        activity['intent-filter'].push({
-          $: { 'android:autoVerify': 'true' },
-          action: [{ $: { 'android:name': 'android.intent.action.VIEW' } }],
-          category: [
-            { $: { 'android:name': 'android.intent.category.DEFAULT' } },
-            { $: { 'android:name': 'android.intent.category.BROWSABLE' } },
-          ],
-          data: [{ $: { 'android:scheme': 'https', 'android:host': opts.universalLinkHost } }],
-        });
-      }
       return cfg;
     });
   }

package/src/core/models/index.ts

@@ -1,139 +1 @@
-/**
- * SDK-side models. These are the camelCase shapes returned from the
- * {@link LinkApiClient} — translated from the snake_case wire format defined
- * by tofa (see harness `src/types/wire.ts` for the raw wire shapes).
- */
-
-export interface AmountDto {
-  amount: string;
-  currency: string;
-}
-
-export interface PaymentScheduleEntry {
-  amount?: AmountDto;
-  maxAmount?: AmountDto;
-  paymentExecutionDate?: string;
-}
-
-export interface PeriodicControls {
-  maxCumulativeAmountPerPeriod?: AmountDto;
-  maxCumulativeNumberOfPaymentsPerPeriod?: number;
-}
-
-export interface PeriodicSchedule {
-  frequency?: string;
-  startDate?: string;
-  endDate?: string;
-  amount?: AmountDto;
-  maxAmount?: AmountDto;
-  controls?: PeriodicControls;
-}
-
-export interface CurrencyRequest {
-  priority?: string;
-  purpose?: string;
-  chargeBearer?: string;
-}
-
-export interface PaymentInstructions {
-  amount?: AmountDto;
-  isInternationalPayment?: boolean;
-  maxCumulativeNumberOfPayments?: number;
-  maxCumulativeAmount?: AmountDto;
-  paymentSchedule?: PaymentScheduleEntry[];
-  periodicSchedule?: PeriodicSchedule;
-  currencyRequest?: CurrencyRequest;
-}
-
-/** Payment request DTO as carried by GET /link. */
-export interface CreatePaymentRequestInput {
-  id: string;
-  internalReference: string;
-  status: string;
-  type: string;
-  creditorType: string;
-  purpose: string;
-  creditorReference?: string;
-  merchantReference: string;
-  createdAt: string;
-  updatedAt: string;
-  isCopVerified: boolean;
-  creditorAccount: {
-    schemeName: string;
-    identification: string;
-    name?: string;
-  };
-  instructions: PaymentInstructions;
-}
-
-export interface LinkSessionResponse {
-  request: CreatePaymentRequestInput;
-  providerId?: string;
-}
-
-export interface ConsentResponse {
-  redirectUrl: string;
-  mobileAppUrl?: string;
-}
-
-export interface LinkStatusResponse {
-  linkSessionId: string;
-  /** created | initialized | redirected | callback_received | completed | failed | cancelled | expired */
-  status: string;
-  /** payment | account */
-  intent: string;
-  /** sip | multipayment | account */
-  resourceType: string;
-  expiresAt: string;
-  failureCode?: string;
-  cancelledAt?: string;
-  completedAt?: string;
-  failedAt?: string;
-}
-
-export interface CopResponse {
-  /** `Match` | `NoMatch` | `Unavailable` */
-  matchIndicator: string;
-  maskedName?: string;
-}
-
-export interface TelemetryResponse {
-  accepted?: boolean;
-  linkSessionId?: string;
-}
-
-export interface PatchTokenResponse {
-  status: string;
-  linkSession?: {
-    linkSessionId: string;
-    status: string;
-    cancelledAt: string | null;
-    failedAt: string | null;
-    failureCode: string | null;
-  };
-}
-
-export interface ProviderCountry {
-  englishName: string;
-  iso3166Code: string;
-}
-
-export interface ProviderSummary {
-  id: string;
-  code: string;
-  name: string;
-  logoUrl: string;
-  status: string;
-  country: ProviderCountry;
-}
-
-/** Persisted record describing an in-flight payment for cold-start recovery. */
-export interface PendingSessionRecord {
-  sessionId: string;
-  selectedBankId: string;
-  authorizationUrl: string;
-  consentAt?: number;
-  recoveryAttempts: number;
-  /** Merchant reference from the link session, used to bind buffered return URIs. */
-  merchantRef?: string;
-}
+export type { PendingSessionRecord } from './pending-session-record';

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

@@ -1,34 +1,282 @@
+import { parseQueryParams } from '../../internal/url-parts';
+
+/**
+ * Query parameters on the deep link that returns a payer to the app.
+ *
+ * Both channels are told the same thing in the same words. A success carries
+ * `reference`, `status` and either `paymentId` or `mandateId`. A failure carries
+ * `reference`, `errorCode` and `status`. `merchantRef` is on both when the request
+ * recorded one, and `status` is always present but may be empty.
+ *
+ * `errorCode` is what tells the two apart: it is on every failure and on no
+ * success, so an outcome can be read without recognising a status.
+ *
+ * **A deep link to an app is not signed.** `sig` is added on the browser channel
+ * only, deliberately: any installed app can claim a custom scheme, so a signature
+ * on a deep link would be a proof handed to whoever intercepted it. When it is
+ * present it is an ES256 JWS over the return URL, and it is carried through
+ * unverified — checking it needs Spare's public key, which the SDK does not hold.
+ *
+ * The query is read by {@link parseQueryParams} rather than through `URL`,
+ * because React Native's `URL.searchParams` never parses the URL it was given.
+ */
+
+/**
+ * Statuses that mean the payment is done and will not change.
+ *
+ * `Scheduled` is a success: a future-dated payment the bank has accepted has
+ * succeeded, the money simply has not moved yet. A caller that needs settled funds
+ * specifically must read the status back from its own backend — this SDK reports
+ * every settled status as `processed`, because all of them are terminal and all of
+ * them resolve to the merchant's success URL.
+ *
+ * `success` is the word an app used to be sent instead of the request's own status.
+ * The service now sends one vocabulary to both channels, so it should no longer
+ * arrive — it is still read because an environment running the earlier build would
+ * otherwise report a completed payment as unresolved.
+ */
+const SETTLED_STATUSES: ReadonlySet<string> = new Set(['Processed', 'Scheduled', 'success']);
+
+/**
+ * Statuses that mean the payment will not happen. `failure` is legacy, for the same
+ * reason `success` is in {@link SETTLED_STATUSES}.
+ */
+const FAILED_STATUSES: ReadonlySet<string> = new Set(['Rejected', 'Errored', 'failure']);
+
 /**
- * Query-parameter helpers for bank / authorize return URIs.
+ * Statuses that mean the request is still payable — not an outcome at all.
  *
- * The Link service appends `exchange_code` on success and `error_code` on
- * authorize failure (legacy integrations may still send `error`).
+ * A return should never carry one: the payer has come back, so the request has
+ * moved on. One arriving here means the outcome is still being decided, which is
+ * `unknown` rather than either answer.
  */
+const IN_FLIGHT_STATUSES: ReadonlySet<string> = new Set(['New', 'Consumed', 'ConsentRaised']);
+
+/**
+ * The one error key that reports a success rather than a failure.
+ *
+ * It arrives in `errorCode` like every other key, so anything that treats the
+ * presence of a key as a failure reports a completed payment as a failed one.
+ */
+const SUCCESS_ERROR_KEY = 'request_processed';
+
+/** Every status this version has been taught, whatever it means. */
+function isKnownStatus(status: string): boolean {
+  return (
+    SETTLED_STATUSES.has(status) || FAILED_STATUSES.has(status) || IN_FLIGHT_STATUSES.has(status)
+  );
+}
 
 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;
+  const params = paymentReturnParams(uri);
+  if (params.reference !== undefined) return true;
+  if (params.merchantRef !== undefined) return true;
+  if (params.errorCode !== undefined) return true;
+  if (params.error_code !== undefined) return true;
+  if (params.error !== undefined) return true;
+  const status = nonEmpty(params.status);
+  if (status !== undefined && isKnownStatus(status)) return true;
   return false;
 }
 
+/** Reads the query of a return URI into the shape the extractors below take. */
+export function paymentReturnParams(uri: URL | string): Record<string, string> {
+  return parseQueryParams(typeof uri === 'string' ? uri : uri.toString());
+}
+
+/**
+ * Whether the return URI reports a completed payment.
+ *
+ * Only a known settled status counts. Absent, in-flight or a status this version
+ * has not been taught is read as not-a-success: a payer returned without one has
+ * not been told their payment succeeded, and neither should the app.
+ */
+export function isPaymentReturnSuccess(params: Record<string, string>): boolean {
+  const status = nonEmpty(params.status);
+  return status !== undefined && SETTLED_STATUSES.has(status);
+}
+
+/** The payment request reference, if the return URI named one. */
+export function extractPaymentReturnReference(params: Record<string, string>): string | undefined {
+  return nonEmpty(params.reference);
+}
+
+/** The merchant's own reference for the attempt, if present. */
+export function extractPaymentReturnMerchantRef(
+  params: Record<string, string>,
+): string | undefined {
+  return nonEmpty(params.merchantRef);
+}
+
+/**
+ * Spare's identifier for the payment itself, present on a success.
+ *
+ * Distinct from the reference, which names the *request*. This is what a merchant
+ * records against the order.
+ */
+export function extractPaymentReturnPaymentId(params: Record<string, string>): string | undefined {
+  return nonEmpty(params.paymentId);
+}
+
+/**
+ * Spare's identifier for a mandate, present on a mandate's success.
+ *
+ * A return carries this or {@link extractPaymentReturnPaymentId}, never both: a
+ * single payment names a payment, every mandate type names a mandate. Read
+ * whichever is present rather than assuming which one the flow produced.
+ */
+export function extractPaymentReturnMandateId(params: Record<string, string>): string | undefined {
+  return nonEmpty(params.mandateId);
+}
+
+/**
+ * The signature over this return, if it carried one.
+ *
+ * An ES256 JWS whose payload is the return URL. Handed to the caller unverified —
+ * checking it needs Spare's public key, which the SDK does not hold.
+ */
+export function extractPaymentReturnSignature(params: Record<string, string>): string | undefined {
+  return nonEmpty(params.sig);
+}
+
+/**
+ * The failure key from a payment return URI, if it reported one.
+ *
+ * `errorCode` is the name both channels now use, and it is what tells the two
+ * outcomes apart: the service puts it on every failure and on no success, so a
+ * reader never has to recognise a status to know the payment did not happen.
+ *
+ * `error_code` and `error` are legacy — an earlier build sent the code under the
+ * snake_case name, and older returns carried a separate machine-readable reason.
+ * Both are still read so an environment running that build is not misread.
+ *
+ * {@link SUCCESS_ERROR_KEY} is excluded, because a success reports itself through
+ * the same field and must not come back out of here looking like a reason the
+ * payment failed.
+ */
+function failureErrorKey(params: Record<string, string>): string | undefined {
+  const key = nonEmpty(params.errorCode) ?? nonEmpty(params.error_code) ?? nonEmpty(params.error);
+  return key === SUCCESS_ERROR_KEY ? undefined : key;
+}
+
 /**
- * Extract the failure code from a payment-return URI, if present.
+ * The failure code from a payment return URI.
  *
- * `error_code` takes precedence over the legacy `error` query param. A
- * `status=failure` with no other code resolves to `'authorize_failed'`.
+ * A return that says only that it failed, naming no key, still yields something a
+ * merchant can branch on.
  */
-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';
+export function extractPaymentReturnErrorCode(params: Record<string, string>): string | undefined {
+  const key = failureErrorKey(params);
+  if (key !== undefined) return key;
+  const status = nonEmpty(params.status);
+  if (status !== undefined && FAILED_STATUSES.has(status)) return 'authorize_failed';
   return undefined;
 }
+
+/**
+ * The machine-readable reason a payment did not complete, e.g. `user_cancelled`.
+ *
+ * Kept alongside the code because the code is often generic where this is not.
+ */
+export function extractPaymentReturnErrorReason(
+  params: Record<string, string>,
+): string | undefined {
+  const reason = nonEmpty(params.error);
+  return reason === SUCCESS_ERROR_KEY ? undefined : reason;
+}
+
+/**
+ * The human-readable failure text, if the return carried one.
+ *
+ * For the merchant's logs and their own copy decisions — not shown to the payer
+ * by this SDK, which cannot verify anything the link says.
+ */
+export function extractPaymentReturnErrorDescription(
+  params: Record<string, string>,
+): string | undefined {
+  return nonEmpty(params.error_description);
+}
+
+/**
+ * Everything a return said, gathered once.
+ *
+ * Carried whole through the flow so a new parameter reaches the caller by being
+ * read here, rather than by being threaded through every state factory.
+ */
+export interface PaymentReturnReport {
+  /**
+   * The payment request this return is about.
+   *
+   * Compared against the payment in flight before the outcome is applied: a
+   * delayed or spoofed callback naming another payment must not resolve this one.
+   */
+  readonly reference?: string;
+  readonly merchantRef?: string;
+  readonly paymentId?: string;
+  /**
+   * Spare's identifier for a mandate. Set instead of `paymentId` when the flow
+   * created a mandate rather than a single payment.
+   */
+  readonly mandateId?: string;
+  readonly signature?: string;
+  readonly errorCode?: string;
+  readonly errorReason?: string;
+  readonly errorDescription?: string;
+}
+
+/**
+ * What a return said about the payment.
+ *
+ * `unknown` is not a failure. The status vocabulary grows, and a payment the
+ * service has not finished deciding on must not be reported as one that failed —
+ * the merchant's backend is what resolves it.
+ */
+export type PaymentReturnOutcome = 'processed' | 'rejected' | 'unknown';
+
+export function paymentReturnOutcome(params: Record<string, string>): PaymentReturnOutcome {
+  const status = nonEmpty(params.status);
+
+  // The status is the authoritative field, so a recognised one settles it — an
+  // error key alongside does not override it. In-flight and unrecognised statuses
+  // both fall through to `unknown`: one is a payment still being decided, the
+  // other a value this version has not been taught, and neither is an outcome.
+  if (status !== undefined) {
+    if (SETTLED_STATUSES.has(status)) return 'processed';
+    if (FAILED_STATUSES.has(status)) return 'rejected';
+    return 'unknown';
+  }
+
+  // No status at all. A failure key is still a report of failure, so it is read as
+  // one — but the success key on its own is not read as a success. Reporting money
+  // moved on the strength of one field is the one mistake with no way back.
+  return failureErrorKey(params) !== undefined ? 'rejected' : 'unknown';
+}
+
+/** Reads a return URI into an outcome and everything it reported. */
+export function readPaymentReturn(uri: URL | string): {
+  outcome: PaymentReturnOutcome;
+  report: PaymentReturnReport;
+} {
+  const params = paymentReturnParams(uri);
+  return {
+    outcome: paymentReturnOutcome(params),
+    report: {
+      ...defined('reference', extractPaymentReturnReference(params)),
+      ...defined('merchantRef', extractPaymentReturnMerchantRef(params)),
+      ...defined('paymentId', extractPaymentReturnPaymentId(params)),
+      ...defined('mandateId', extractPaymentReturnMandateId(params)),
+      ...defined('signature', extractPaymentReturnSignature(params)),
+      ...defined('errorCode', extractPaymentReturnErrorCode(params)),
+      ...defined('errorReason', extractPaymentReturnErrorReason(params)),
+      ...defined('errorDescription', extractPaymentReturnErrorDescription(params)),
+    },
+  };
+}
+
+function defined(key: string, value: string | undefined): Record<string, string> {
+  return value === undefined ? {} : { [key]: value };
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value !== undefined && value.length > 0 ? value : undefined;
+}

package/src/core/models/pending-session-record.ts

@@ -0,0 +1,10 @@
+/**
+ * What the SDK remembers about a payment that was still in flight.
+ *
+ * Only the reference: the SDK holds no credentials and can ask the service
+ * nothing, so the record exists to tell a cold start which payment to hand the
+ * merchant's backend for resolution — not to resume the flow itself.
+ */
+export interface PendingSessionRecord {
+  reference: string;
+}