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

package/README.md

@@ -1,6 +1,6 @@
 # @spare-technologies/spare-link
 
-React Native SDK for [Spare Link](https://tryspare.com) — drop-in open-banking payments via a native checkout sheet.
+React Native SDK for [Spare Link](https://tryspare.com) — open-banking payments for iOS and Android.
 
 ```sh
 bun add @spare-technologies/spare-link
@@ -8,11 +8,19 @@ bun add @spare-technologies/spare-link
 npm i @spare-technologies/spare-link
 ```
 
+Full integration guide: [`docs/getting-started.md`](https://github.com/spare-technologies/link-rn/blob/main/docs/getting-started.md).
+
+## What this SDK does
+
+Your backend creates a payment request and gives the app the reference it returns. The SDK presents the payment flow for that reference, opens the payer's bank in a real browser when a consent exists, and reports the outcome carried by the return deep link.
+
+The SDK makes no API calls and holds no credentials. It reports only what the payment flow and the deep link tell it, which is why your backend reads the final result.
+
+The bank opens in a browser rather than inside the app for two reasons: banks commonly refuse to authorize a payment in an embedded view, and the address bar lets the payer check they are on a real bank page.
+
 ## Quickstart
 
-The SDK is instance-based (mirrors the Flutter `spare_link` API): create one `SpareLink`
-instance, mount one `SpareLinkHost` near your app root, and pass that instance to every
-screen that starts a payment.
+Create one `SpareLink` instance, mount one `SpareLinkHost` near your app root, and pass the instance to every screen that starts a payment.
 
 ```tsx
 import { SpareLink, SpareLinkHost, useSpareLinkDeepLinks } from '@spare-technologies/spare-link';
@@ -31,18 +39,69 @@ function App() {
     </SpareLinkHost>
   );
 }
+```
+
+Your backend creates the payment request with `channel: 'sdk_react_native'` and the return URLs your app is registered for. It then hands the app the reference. That reference is all the SDK needs.
 
-async function pay(spareLink: SpareLink, linkToken: string) {
-  const unsub = spareLink.events.subscribe((event) => console.log('event', event.type));
-  const session = await spareLink.start({ linkToken });
+```tsx
+async function pay(spareLink: SpareLink, reference: string) {
+  const session = await spareLink.start({ reference });
   const result = await session.result;
-  unsub();
-  if (result.status === 'success') {
-    // exchange `result.exchangeCode` on your backend → /link/exchange
-  }
+
+  // Confirm with your backend before you act on this. See "Confirming the result".
+  console.log(result.status, result.reference);
 }
 ```
 
+## Confirming the result
+
+Every result this SDK reports is read from a deep link. A deep link is not proof: the OS hands it over, and any installed app can register the same custom scheme.
+
+**The deep link an app receives is not signed, 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. There is therefore nothing on it to verify, and reading the record is the only way to establish what happened:
+
+```
+GET /payment-requests/{reference}
+```
+
+Call it from your backend with its own credentials before you fulfil anything.
+
+The deep link does carry `paymentId` on a single payment's success, or `mandateId` on a mandate's — record whichever is set. `signature` is populated only on Spare's https redirect, so expect it to be `undefined` in an app; when it is present it is an ES256 JWS over the return URL, which the SDK passes through unverified.
+
+## Payment statuses
+
+Each status belongs to one of three groups. Only the first group is routed to your `successRedirectUrl`; every other status is routed to your `failureRedirectUrl`, so both URLs must be registered and both must open your app.
+
+| Group | Statuses | `result.status` |
+| --- | --- | --- |
+| Settled | `Processed`, `Scheduled` | `'success'` |
+| Terminal failure | `Rejected`, `Errored` | `'failed'` |
+| Still in flight | `New`, `Consumed`, `ConsentRaised` | `'abandoned'` |
+
+`Scheduled` is a success: the bank has accepted a payment dated in the future, and the money has not moved yet. If your fulfilment requires settled funds, check the status you read back from your backend rather than the `'success'` result alone.
+
+The statuses in the third group are not outcomes — a request with one of them is still payable, so it should not appear on a return. If one does, the SDK reports `'abandoned'` and your backend resolves it. The SDK does the same for a status it does not recognise, because reporting an unknown status as a success would tell a payer their money moved when it may not have.
+
+`status` is always sent but **can be empty**, so `errorCode` is the reliable discriminator: it is present on every failure and on no success. Its value today is always `SP500`; use it for your own copy rather than to determine the outcome. An empty `status` alongside an `errorCode` is a failure, and the SDK reads it as one.
+
+Older builds of the service sent `status=success` / `status=failure` and the code as `error_code`. The SDK still reads those, so an environment that has not been updated does not misreport.
+
+## Peer dependencies
+
+Install these with Expo, so the versions match your Expo SDK:
+
+```sh
+npx expo install react-native-webview react-native-safe-area-context react-native-screens \
+  expo-web-browser expo-secure-store expo-font expo-linear-gradient @expo/vector-icons
+```
+
+npm and bun will install these automatically, and the declared ranges are pinned to the Expo 52 module line, so an automatic resolve lands on a compatible version. `expo install` is still the safer route: it reads your installed Expo SDK and picks the exact version that ships with it.
+
+The ranges are deliberately narrow. This release supports **Expo 52 only**, so an app on a newer Expo SDK gets a peer-dependency conflict at install time rather than a native build failure or a crash on device.
+
+`expo-web-browser` opens the bank, `expo-secure-store` stores the pending payment for recovery, and the rest render the payment flow. `react-native-svg` is an optional peer, loaded only if present; without it the SDK shows a plain activity indicator.
+
+The SDK requires no runtime permissions.
+
 ## Expo plugin
 
 Add to `app.config.ts`:
@@ -52,122 +111,101 @@ plugins: [
   [
     '@spare-technologies/spare-link/expo-plugin',
     {
-      locationUsageDescription: 'We use your location to verify the payment.',
-      merchantScheme: 'sparemerchantrn',
+      merchantScheme: 'myapp',
       merchantHost: 'callback',
     },
   ],
 ]
 ```
 
-The plugin injects:
+The plugin registers only the deep link the payer returns through:
+
+- **iOS**: a `CFBundleURLSchemes` entry for your app scheme.
+- **Android**: an intent-filter for `myapp://callback`.
 
-- **iOS**: `NSLocationWhenInUseUsageDescription` + `CFBundleURLSchemes` entry for the merchant scheme.
-- **Android**: `ACCESS_FINE_LOCATION` permission + intent-filter for `sparemerchantrn://callback` (and an optional `autoVerify=true` App Link for the Spare universal-link host).
+Use the same scheme and host your backend sets in `successRedirectUrl` and `failureRedirectUrl`. Rebuild your dev client after adding the plugin, because it changes native configuration.
+
+Earlier versions injected `ACCESS_FINE_LOCATION` and an iOS location usage description for device telemetry. The SDK no longer collects it, and the plugin requests no permissions.
+
+## Environments
+
+| Environment | Host |
+| --- | --- |
+| `sandbox` | `https://api.sandbox.tryspare.ae` |
+| `production` | `https://api.tryspare.ae` |
+
+Pass `baseUrl` to override the host. The payment flow currently serves **UAE only**; constructing with another tenant throws instead of showing the payer another country's flow.
 
 ## Deep-link handling
 
-`SpareLinkHost` forwards bank-return URIs to the SDK via `spareLink.handleRedirect(url)`. The `useSpareLinkDeepLinks(spareLink)` hook wires `Linking.addEventListener('url', …)` + `Linking.getInitialURL()` for you.
+`useSpareLinkDeepLinks(spareLink)` wires `Linking.addEventListener('url', …)` and `Linking.getInitialURL()` to `spareLink.handleRedirect(url)`. Call `handleRedirect` yourself if you have your own router — it returns `true` when the URI belonged to a payment, so you can leave your own routing untouched for anything else.
+
+A return that arrives before there is a flow to give it to is held, not discarded, and picked up by `start()` or `resumeIfNeeded()`.
 
 ## Cold-start recovery
 
-Construct the instance with a `pendingSessionStore` and call `spareLink.resumeIfNeeded()` on `AppState === 'active'`:
+Construct the instance with a store, and call `resumeIfNeeded()` when the app becomes active:
 
 ```tsx
-import { SecureStorePendingSessionStore, SpareLink, SpareLinkHost } from '@spare-technologies/spare-link';
-
-const store = new SecureStorePendingSessionStore();
-const spareLink = new SpareLink({ environment: 'sandbox', tenant: 'uae', pendingSessionStore: store });
+import { SecureStorePendingSessionStore, SpareLink } from '@spare-technologies/spare-link';
 
-<SpareLinkHost spareLink={spareLink}>
-  …
-</SpareLinkHost>
+const spareLink = new SpareLink({
+  environment: 'sandbox',
+  tenant: 'uae',
+  pendingSessionStore: new SecureStorePendingSessionStore(),
+});
 ```
 
 ```ts
-import { AppState } from 'react-native';
-
-AppState.addEventListener('change', (state) => {
-  if (state !== 'active') return;
-  void spareLink.resumeIfNeeded().then((recovery) => {
-    if (recovery.kind === 'recovered') {
-      // recovery.result is the terminal PaymentResult
-    }
-    // kind === 'awaitingUser' means the SDK opened its own recovery UI —
-    // the terminal outcome arrives later via `spareLink.events`.
-  });
-});
+const recovery = await spareLink.resumeIfNeeded();
 ```
 
-`spareLink.resumeIfNeeded()` reads the persisted record, polls `GET /link/status`, and resolves a `RecoveryResult`:
-
-- `{ kind: 'recovered', result }` — the session reached a terminal state; `result` is the `PaymentResult`.
-- `{ kind: 'awaitingUser', linkToken }` — the session is still non-terminal and the SDK opened its recovery UI (mounted by `SpareLinkHost`); the terminal outcome arrives later via `spareLink.events` / the `succeeded`/`failed`/`cancelled`/`abandoned` events.
-- `{ kind: 'none', reason }` — nothing to recover (`noPendingSession` | `flowAlreadyActive` | `persistenceUnavailable`).
-
-After `kMaxRecoveryAttempts` (3) non-terminal attempts the SDK resolves `PaymentFailed('recovery_exhausted')` and clears the record.
-
-## Testing with the harness
+- `{ kind: 'recovered', result }` — the return arrived before there was a flow to give it to, and the outcome was read from it.
+- `{ kind: 'none', reason: 'outcomeUnknown', reference }` — a payment was under way and no return arrived. **It may have completed.** The SDK holds no credentials and cannot ask; your backend resolves it using the reference.
+- `{ kind: 'none', reason: 'noPendingSession' | 'flowAlreadyActive' | 'persistenceUnavailable' }` — nothing to recover.
 
-Add `@spare-technologies/link-test-harness` as a dev dep — it ships a stateful MSW mock Link API with tofa-accurate `{ data }` envelopes:
+Without a `pendingSessionStore` you always get `persistenceUnavailable`, and a payment interrupted by the app closing is never reported.
 
-```ts
-import { setupMockLinkApi } from '@spare-technologies/link-test-harness';
-
-const server = setupMockLinkApi({ scenario: 'happyPath' });
-beforeAll(() => server.start());
-afterAll(() => server.stop());
-afterEach(() => server.reset());
-```
+## When the payment flow cannot be opened
 
-Available scenarios: `happyPath`, `sessionAlreadyInitialized`, `networkTimeout`, `consentRetry`, `sessionTimeout`, `recoveryViaStatus`, `appReturn`, `terminalCompleted | Failed | Cancelled | Expired`, `tenantMismatch`, `providerUnavailable`, `multipaymentFixedOnDemand`, `multipaymentFixedDefinedSchedule`, `internationalPayment`.
+If the flow fails to load, or loads and never becomes usable, the payer is told that the service is unreachable and that no payment has been taken, and is offered a retry. Nothing has been attempted at that point. If the payer gives up, the flow resolves as `PaymentFailed` with `page_unavailable`.
 
-For tests that don't want to mount `SpareLinkHost`, drive the instance's internal host delegate directly (see `SpareLink._attachHost` usage in the SDK's own `spare-link-instance.test.ts` for the pattern), or stub the app-level function that wraps `spareLink.start(...)` in your own integration layer.
+A failure after the flow was working reports `page_lost` instead.
 
 ## API reference
 
 ### `new SpareLink(options)`
 
-| Field | Type | Notes |
-| --- | --- | --- |
-| `environment` | `'sandbox' \| 'production'` | Default base URL is derived from this. |
-| `tenant` | `'ksa' \| 'uae' \| 'bah'` | Sent as the `X-Tenant` header. |
-| `baseUrl` | `string?` | Override the base URL (dev only). |
-| `fetch` | `typeof fetch?` | Inject a custom fetch for cert pinning. |
-| `requestTimeoutMs` | `number?` | Default `15_000`. |
-| `pendingSessionStore` | `PendingSessionStore?` | Enables cold-start recovery, e.g. `SecureStorePendingSessionStore`. |
+`{ environment, tenant, baseUrl?, pendingSessionStore? }`. Validates its config and throws on a `baseUrl` that is not a URL, or a tenant the payment flow cannot serve.
 
-### `spareLink.start({ linkToken })`
+### `spareLink.start({ reference })`
 
-Returns a `Promise<SpareLinkSession>` immediately; await `session.result` for the terminal `PaymentResult`. Never throws — invalid input resolves to `PaymentAbandoned` so callers don't need a try/catch.
+Presents the payment flow and resolves to a `SpareLinkSession`. `await session.result` for the terminal outcome. A second call during an active payment resolves as `'failed'` with `concurrent_start`.
 
 ### `PaymentResult` discriminated union
 
 ```ts
 type PaymentResult =
-  | PaymentSuccess     // { status: 'success', linkToken, exchangeCode?, merchantRef?, linkSessionId?, ... }
-  | PaymentCancelled   // { status: 'cancelled', linkToken, ... }
-  | PaymentFailed      // { status: 'failed', linkToken, errorCode, ... }
-  | PaymentAbandoned   // { status: 'abandoned', linkToken, ... }
+  | PaymentSuccess     // { status: 'success', reference, paymentId?, mandateId?, signature?, merchantRef?, ... }
+  | PaymentCancelled   // { status: 'cancelled', reference, ... }
+  | PaymentFailed      // { status: 'failed', reference, errorCode, errorReason?, ... }
+  | PaymentAbandoned   // { status: 'abandoned', reference, ... }
 ```
 
-### `SpareLinkEvent`
+`abandoned` means the flow ended without an outcome. A payment already at the bank may still complete, so it is not reported as a failure.
 
-Subscribe via `spareLink.events.subscribe((event) => ...)`. `event.type` is one of:
+### `SpareLinkEvent`
 
-```ts
-type SpareLinkEventType =
-  | 'initialized' | 'sessionLoaded' | 'consentStarted'
-  | 'redirectToBank' | 'bankCallbackReceived'
-  | 'succeeded' | 'failed' | 'cancelled' | 'abandoned';
-```
+`initialized`, `pageReady`, `redirectToBank`, `bankCallbackReceived`, then one of `succeeded` / `failed` / `cancelled` / `abandoned`. Analytics only — never required to drive the flow.
 
 ## Supported versions
 
 - **Expo SDK** ≥ 52 (tested with 52.0.x)
-- **React Native** ≥ 0.76
+- **React Native** ≥ 0.76.9
 - **React** ≥ 18.3
 
+Requires a custom dev client or a production build. The SDK uses native modules and does not run in Expo Go.
+
 ## License
 
-MIT — see [LICENSE](../../LICENSE).
+MIT — see [LICENSE](./LICENSE).

package/lib/commonjs/core/models/payment-return-params.js

@@ -4,39 +4,264 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.extractPaymentReturnErrorCode = extractPaymentReturnErrorCode;
+exports.extractPaymentReturnErrorDescription = extractPaymentReturnErrorDescription;
+exports.extractPaymentReturnErrorReason = extractPaymentReturnErrorReason;
+exports.extractPaymentReturnMandateId = extractPaymentReturnMandateId;
+exports.extractPaymentReturnMerchantRef = extractPaymentReturnMerchantRef;
+exports.extractPaymentReturnPaymentId = extractPaymentReturnPaymentId;
+exports.extractPaymentReturnReference = extractPaymentReturnReference;
+exports.extractPaymentReturnSignature = extractPaymentReturnSignature;
 exports.isPaymentReturnCallbackUri = isPaymentReturnCallbackUri;
+exports.isPaymentReturnSuccess = isPaymentReturnSuccess;
+exports.paymentReturnOutcome = paymentReturnOutcome;
+exports.paymentReturnParams = paymentReturnParams;
+exports.readPaymentReturn = readPaymentReturn;
+var _urlParts = require("../../internal/url-parts.js");
 /**
- * Query-parameter helpers for bank / authorize return URIs.
+ * Query parameters on the deep link that returns a payer to the app.
  *
- * The Link service appends `exchange_code` on success and `error_code` on
- * authorize failure (legacy integrations may still send `error`).
+ * 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 = 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 = new Set(['Rejected', 'Errored', 'failure']);
 
+/**
+ * Statuses that mean the request is still payable — not an outcome at all.
+ *
+ * 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 = 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) {
+  return SETTLED_STATUSES.has(status) || FAILED_STATUSES.has(status) || IN_FLIGHT_STATUSES.has(status);
+}
 function isPaymentReturnCallbackUri(uri) {
-  let parsed;
-  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. */
+function paymentReturnParams(uri) {
+  return (0, _urlParts.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.
+ */
+function isPaymentReturnSuccess(params) {
+  const status = nonEmpty(params.status);
+  return status !== undefined && SETTLED_STATUSES.has(status);
+}
+
+/** The payment request reference, if the return URI named one. */
+function extractPaymentReturnReference(params) {
+  return nonEmpty(params.reference);
+}
+
+/** The merchant's own reference for the attempt, if present. */
+function extractPaymentReturnMerchantRef(params) {
+  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.
+ */
+function extractPaymentReturnPaymentId(params) {
+  return nonEmpty(params.paymentId);
+}
+
 /**
- * Extract the failure code from a payment-return URI, if present.
+ * Spare's identifier for a mandate, present on a mandate's success.
  *
- * `error_code` takes precedence over the legacy `error` query param. A
- * `status=failure` with no other code resolves to `'authorize_failed'`.
+ * 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.
+ */
+function extractPaymentReturnMandateId(params) {
+  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.
+ */
+function extractPaymentReturnSignature(params) {
+  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) {
+  const key = nonEmpty(params.errorCode) ?? nonEmpty(params.error_code) ?? nonEmpty(params.error);
+  return key === SUCCESS_ERROR_KEY ? undefined : key;
+}
+
+/**
+ * The failure code from a payment return URI.
+ *
+ * A return that says only that it failed, naming no key, still yields something a
+ * merchant can branch on.
  */
 function extractPaymentReturnErrorCode(params) {
-  const code = params.get('error_code') ?? params.get('error');
-  if (code && code.length > 0) return code;
-  if (params.get('status') === 'failure') return 'authorize_failed';
+  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.
+ */
+function extractPaymentReturnErrorReason(params) {
+  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.
+ */
+function extractPaymentReturnErrorDescription(params) {
+  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.
+ */
+
+/**
+ * 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.
+ */
+
+function paymentReturnOutcome(params) {
+  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. */
+function readPaymentReturn(uri) {
+  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, value) {
+  return value === undefined ? {} : {
+    [key]: value
+  };
+}
+function nonEmpty(value) {
+  return value !== undefined && value.length > 0 ? value : undefined;
+}
 //# sourceMappingURL=payment-return-params.js.map

package/lib/commonjs/core/models/payment-return-params.js.map

@@ -1 +1 @@
-{"version":3,"names":["isPaymentReturnCallbackUri","uri","parsed","URL","params","searchParams","has","get","extractPaymentReturnErrorCode","code","length","undefined"],"sourceRoot":"../../../../src","sources":["core/models/payment-return-params.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEO,SAASA,0BAA0BA,CAACC,GAAiB,EAAW;EACrE,IAAIC,MAAW;EACf,IAAI;IACFA,MAAM,GAAG,OAAOD,GAAG,KAAK,QAAQ,GAAG,IAAIE,GAAG,CAACF,GAAG,CAAC,GAAGA,GAAG;EACvD,CAAC,CAAC,MAAM;IACN,OAAO,KAAK;EACd;EACA,MAAMG,MAAM,GAAGF,MAAM,CAACG,YAAY;EAClC,IAAID,MAAM,CAACE,GAAG,CAAC,eAAe,CAAC,EAAE,OAAO,IAAI;EAC5C,IAAIF,MAAM,CAACE,GAAG,CAAC,YAAY,CAAC,EAAE,OAAO,IAAI;EACzC,IAAIF,MAAM,CAACE,GAAG,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI;EACpC,IAAIF,MAAM,CAACG,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,EAAE,OAAO,IAAI;EACnD,OAAO,KAAK;AACd;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,6BAA6BA,CAACJ,MAAuB,EAAsB;EACzF,MAAMK,IAAI,GAAGL,MAAM,CAACG,GAAG,CAAC,YAAY,CAAC,IAAIH,MAAM,CAACG,GAAG,CAAC,OAAO,CAAC;EAC5D,IAAIE,IAAI,IAAIA,IAAI,CAACC,MAAM,GAAG,CAAC,EAAE,OAAOD,IAAI;EACxC,IAAIL,MAAM,CAACG,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,EAAE,OAAO,kBAAkB;EACjE,OAAOI,SAAS;AAClB","ignoreList":[]}
+{"version":3,"names":["_urlParts","require","SETTLED_STATUSES","Set","FAILED_STATUSES","IN_FLIGHT_STATUSES","SUCCESS_ERROR_KEY","isKnownStatus","status","has","isPaymentReturnCallbackUri","uri","params","paymentReturnParams","reference","undefined","merchantRef","errorCode","error_code","error","nonEmpty","parseQueryParams","toString","isPaymentReturnSuccess","extractPaymentReturnReference","extractPaymentReturnMerchantRef","extractPaymentReturnPaymentId","paymentId","extractPaymentReturnMandateId","mandateId","extractPaymentReturnSignature","sig","failureErrorKey","key","extractPaymentReturnErrorCode","extractPaymentReturnErrorReason","reason","extractPaymentReturnErrorDescription","error_description","paymentReturnOutcome","readPaymentReturn","outcome","report","defined","value","length"],"sourceRoot":"../../../../src","sources":["core/models/payment-return-params.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/models/pending-session-record.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=pending-session-record.js.map

package/lib/commonjs/core/models/pending-session-record.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["core/models/pending-session-record.ts"],"mappings":"","ignoreList":[]}