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

package/lib/commonjs/version.js

@@ -5,10 +5,12 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.SDK_VERSION = void 0;
 /**
- * SDK version reported in telemetry and the default User-Agent. This file is
- * regenerated from `package.json` by the root `version` npm script on every
- * release bump (see the `version` script in the repo-root package.json), so it
- * always matches the published version — do not edit the literal by hand.
+ * SDK version reported in telemetry and the default User-Agent.
+ *
+ * GENERATED FILE — do not edit by hand. Written from package.json by
+ * scripts/sync-sdk-version.mjs (run by the root `version` npm script after
+ * `changeset version`). The src/index.ts smoke test asserts this matches
+ * package.json's version.
  */
-const SDK_VERSION = exports.SDK_VERSION = '0.1.0-beta.0';
+const SDK_VERSION = exports.SDK_VERSION = '1.0.0';
 //# sourceMappingURL=version.js.map

package/lib/commonjs/version.js.map

@@ -1 +1 @@
-{"version":3,"names":["SDK_VERSION","exports"],"sourceRoot":"../../src","sources":["version.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,WAAW,GAAAC,OAAA,CAAAD,WAAA,GAAG,cAAuB","ignoreList":[]}
+{"version":3,"names":["SDK_VERSION","exports"],"sourceRoot":"../../src","sources":["version.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,WAAW,GAAAC,OAAA,CAAAD,WAAA,GAAG,OAAgB","ignoreList":[]}

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

@@ -1,37 +1,252 @@
 "use strict";
 
+import { parseQueryParams } from "../../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.
+ *
+ * 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.
  *
- * The Link service appends `exchange_code` on success and `error_code` on
- * authorize failure (legacy integrations may still send `error`).
+ * **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);
+}
 export 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. */
+export function paymentReturnParams(uri) {
+  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) {
+  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) {
+  return nonEmpty(params.reference);
+}
+
+/** The merchant's own reference for the attempt, if present. */
+export 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.
+ */
+export function extractPaymentReturnPaymentId(params) {
+  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) {
+  return nonEmpty(params.mandateId);
+}
+
 /**
- * Extract the failure code from a payment-return URI, if present.
+ * The signature over this return, if it carried one.
  *
- * `error_code` takes precedence over the legacy `error` query param. A
- * `status=failure` with no other code resolves to `'authorize_failed'`.
+ * 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) {
+  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.
  */
 export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+
+export 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. */
+export 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/module/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;;AAEA,OAAO,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;AACA,OAAO,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":["parseQueryParams","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","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":";;AAAA,SAASA,gBAAgB,QAAQ,6BAA0B;;AAE3D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,gBAAqC,GAAG,IAAIC,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;;AAE5F;AACA;AACA;AACA;AACA,MAAMC,eAAoC,GAAG,IAAID,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;;AAExF;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAME,kBAAuC,GAAG,IAAIF,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;;AAE7F;AACA;AACA;AACA;AACA;AACA;AACA,MAAMG,iBAAiB,GAAG,mBAAmB;;AAE7C;AACA,SAASC,aAAaA,CAACC,MAAc,EAAW;EAC9C,OACEN,gBAAgB,CAACO,GAAG,CAACD,MAAM,CAAC,IAAIJ,eAAe,CAACK,GAAG,CAACD,MAAM,CAAC,IAAIH,kBAAkB,CAACI,GAAG,CAACD,MAAM,CAAC;AAEjG;AAEA,OAAO,SAASE,0BAA0BA,CAACC,GAAiB,EAAW;EACrE,MAAMC,MAAM,GAAGC,mBAAmB,CAACF,GAAG,CAAC;EACvC,IAAIC,MAAM,CAACE,SAAS,KAAKC,SAAS,EAAE,OAAO,IAAI;EAC/C,IAAIH,MAAM,CAACI,WAAW,KAAKD,SAAS,EAAE,OAAO,IAAI;EACjD,IAAIH,MAAM,CAACK,SAAS,KAAKF,SAAS,EAAE,OAAO,IAAI;EAC/C,IAAIH,MAAM,CAACM,UAAU,KAAKH,SAAS,EAAE,OAAO,IAAI;EAChD,IAAIH,MAAM,CAACO,KAAK,KAAKJ,SAAS,EAAE,OAAO,IAAI;EAC3C,MAAMP,MAAM,GAAGY,QAAQ,CAACR,MAAM,CAACJ,MAAM,CAAC;EACtC,IAAIA,MAAM,KAAKO,SAAS,IAAIR,aAAa,CAACC,MAAM,CAAC,EAAE,OAAO,IAAI;EAC9D,OAAO,KAAK;AACd;;AAEA;AACA,OAAO,SAASK,mBAAmBA,CAACF,GAAiB,EAA0B;EAC7E,OAAOV,gBAAgB,CAAC,OAAOU,GAAG,KAAK,QAAQ,GAAGA,GAAG,GAAGA,GAAG,CAACU,QAAQ,CAAC,CAAC,CAAC;AACzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAACV,MAA8B,EAAW;EAC9E,MAAMJ,MAAM,GAAGY,QAAQ,CAACR,MAAM,CAACJ,MAAM,CAAC;EACtC,OAAOA,MAAM,KAAKO,SAAS,IAAIb,gBAAgB,CAACO,GAAG,CAACD,MAAM,CAAC;AAC7D;;AAEA;AACA,OAAO,SAASe,6BAA6BA,CAACX,MAA8B,EAAsB;EAChG,OAAOQ,QAAQ,CAACR,MAAM,CAACE,SAAS,CAAC;AACnC;;AAEA;AACA,OAAO,SAASU,+BAA+BA,CAC7CZ,MAA8B,EACV;EACpB,OAAOQ,QAAQ,CAACR,MAAM,CAACI,WAAW,CAAC;AACrC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASS,6BAA6BA,CAACb,MAA8B,EAAsB;EAChG,OAAOQ,QAAQ,CAACR,MAAM,CAACc,SAAS,CAAC;AACnC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,6BAA6BA,CAACf,MAA8B,EAAsB;EAChG,OAAOQ,QAAQ,CAACR,MAAM,CAACgB,SAAS,CAAC;AACnC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,6BAA6BA,CAACjB,MAA8B,EAAsB;EAChG,OAAOQ,QAAQ,CAACR,MAAM,CAACkB,GAAG,CAAC;AAC7B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,eAAeA,CAACnB,MAA8B,EAAsB;EAC3E,MAAMoB,GAAG,GAAGZ,QAAQ,CAACR,MAAM,CAACK,SAAS,CAAC,IAAIG,QAAQ,CAACR,MAAM,CAACM,UAAU,CAAC,IAAIE,QAAQ,CAACR,MAAM,CAACO,KAAK,CAAC;EAC/F,OAAOa,GAAG,KAAK1B,iBAAiB,GAAGS,SAAS,GAAGiB,GAAG;AACpD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,6BAA6BA,CAACrB,MAA8B,EAAsB;EAChG,MAAMoB,GAAG,GAAGD,eAAe,CAACnB,MAAM,CAAC;EACnC,IAAIoB,GAAG,KAAKjB,SAAS,EAAE,OAAOiB,GAAG;EACjC,MAAMxB,MAAM,GAAGY,QAAQ,CAACR,MAAM,CAACJ,MAAM,CAAC;EACtC,IAAIA,MAAM,KAAKO,SAAS,IAAIX,eAAe,CAACK,GAAG,CAACD,MAAM,CAAC,EAAE,OAAO,kBAAkB;EAClF,OAAOO,SAAS;AAClB;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASmB,+BAA+BA,CAC7CtB,MAA8B,EACV;EACpB,MAAMuB,MAAM,GAAGf,QAAQ,CAACR,MAAM,CAACO,KAAK,CAAC;EACrC,OAAOgB,MAAM,KAAK7B,iBAAiB,GAAGS,SAAS,GAAGoB,MAAM;AAC1D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oCAAoCA,CAClDxB,MAA8B,EACV;EACpB,OAAOQ,QAAQ,CAACR,MAAM,CAACyB,iBAAiB,CAAC;AAC3C;;AAEA;AACA;AACA;AACA;AACA;AACA;;AAsBA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,OAAO,SAASC,oBAAoBA,CAAC1B,MAA8B,EAAwB;EACzF,MAAMJ,MAAM,GAAGY,QAAQ,CAACR,MAAM,CAACJ,MAAM,CAAC;;EAEtC;EACA;EACA;EACA;EACA,IAAIA,MAAM,KAAKO,SAAS,EAAE;IACxB,IAAIb,gBAAgB,CAACO,GAAG,CAACD,MAAM,CAAC,EAAE,OAAO,WAAW;IACpD,IAAIJ,eAAe,CAACK,GAAG,CAACD,MAAM,CAAC,EAAE,OAAO,UAAU;IAClD,OAAO,SAAS;EAClB;;EAEA;EACA;EACA;EACA,OAAOuB,eAAe,CAACnB,MAAM,CAAC,KAAKG,SAAS,GAAG,UAAU,GAAG,SAAS;AACvE;;AAEA;AACA,OAAO,SAASwB,iBAAiBA,CAAC5B,GAAiB,EAGjD;EACA,MAAMC,MAAM,GAAGC,mBAAmB,CAACF,GAAG,CAAC;EACvC,OAAO;IACL6B,OAAO,EAAEF,oBAAoB,CAAC1B,MAAM,CAAC;IACrC6B,MAAM,EAAE;MACN,GAAGC,OAAO,CAAC,WAAW,EAAEnB,6BAA6B,CAACX,MAAM,CAAC,CAAC;MAC9D,GAAG8B,OAAO,CAAC,aAAa,EAAElB,+BAA+B,CAACZ,MAAM,CAAC,CAAC;MAClE,GAAG8B,OAAO,CAAC,WAAW,EAAEjB,6BAA6B,CAACb,MAAM,CAAC,CAAC;MAC9D,GAAG8B,OAAO,CAAC,WAAW,EAAEf,6BAA6B,CAACf,MAAM,CAAC,CAAC;MAC9D,GAAG8B,OAAO,CAAC,WAAW,EAAEb,6BAA6B,CAACjB,MAAM,CAAC,CAAC;MAC9D,GAAG8B,OAAO,CAAC,WAAW,EAAET,6BAA6B,CAACrB,MAAM,CAAC,CAAC;MAC9D,GAAG8B,OAAO,CAAC,aAAa,EAAER,+BAA+B,CAACtB,MAAM,CAAC,CAAC;MAClE,GAAG8B,OAAO,CAAC,kBAAkB,EAAEN,oCAAoC,CAACxB,MAAM,CAAC;IAC7E;EACF,CAAC;AACH;AAEA,SAAS8B,OAAOA,CAACV,GAAW,EAAEW,KAAyB,EAA0B;EAC/E,OAAOA,KAAK,KAAK5B,SAAS,GAAG,CAAC,CAAC,GAAG;IAAE,CAACiB,GAAG,GAAGW;EAAM,CAAC;AACpD;AAEA,SAASvB,QAAQA,CAACuB,KAAyB,EAAsB;EAC/D,OAAOA,KAAK,KAAK5B,SAAS,IAAI4B,KAAK,CAACC,MAAM,GAAG,CAAC,GAAGD,KAAK,GAAG5B,SAAS;AACpE","ignoreList":[]}

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

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

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

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

package/lib/module/core/services/hosted-flow-controller.js

@@ -0,0 +1,328 @@
+"use strict";
+
+import { launchBankRedirect as defaultLaunchBankRedirect } from "../../internal/bank-redirect.js";
+import { parseHostedBridgeMessage } from "../../internal/hosted/bridge-message.js";
+import { createLogger } from "../../internal/logger.js";
+import { readPaymentReturn } from "../models/payment-return-params.js";
+import { HostedFlowStates, isTerminalPhase } from "./hosted-flow-state.js";
+const log = createLogger('HostedFlowController');
+
+/** Opens a bank authorization URL outside the WebView. */
+
+/**
+ * How long the page has to become interactive, measured from when the webview
+ * mounts.
+ *
+ * A page can load and still never speak: its script can fail to fetch, or throw
+ * before it posts `spare.ready`. Nothing else would notice, and the payer would
+ * hold a blank frame for as long as they were willing to.
+ *
+ * Measured from the webview rather than from this controller, because a
+ * controller is built before the screen is: the sheet's animation and whatever
+ * the host waits on before rendering would otherwise be charged against the
+ * page's budget, and a page that merely loads slowly would be called unreachable.
+ */
+export const DEFAULT_READY_TIMEOUT_MS = 20_000;
+/**
+ * Drives a hosted payment from the messages the page sends and the deep link
+ * the OS delivers when the payer comes back.
+ *
+ * The SDK makes no API calls of its own: the page creates the consent, and the
+ * merchant's backend reads the result. So this controller only ever reacts —
+ * which is why every transition here is guarded against arriving after the flow
+ * has already resolved.
+ */
+export class HostedFlowController {
+  listeners = new Set();
+  constructor(options) {
+    this.reference = options.reference;
+    this.bankLauncher = options.bankLauncher ?? (url => defaultLaunchBankRedirect({
+      authorizationUrl: url
+    }));
+    this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    this.currentState = HostedFlowStates.loading(options.reference);
+  }
+
+  /**
+   * Records that the webview carrying the page is on screen.
+   *
+   * Starts the clock the page has to become interactive. Called on mount rather
+   * than on load, so a document that never finishes arriving is covered too.
+   */
+  reportPageMounted() {
+    if (this.currentState.phase !== 'loading') return;
+    this.watchForReadiness();
+  }
+  get state() {
+    return this.currentState;
+  }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Reacts to a message from the hosted page.
+   *
+   * Resolves to whether the message was understood, so a caller can log what it
+   * dropped. An unrecognised message is not a failure: the page keeps working
+   * and the payer is unaffected.
+   */
+  async handleBridgeMessage(raw) {
+    const message = parseHostedBridgeMessage(raw);
+    if (!message) {
+      log.info('dropped an unrecognised message from the hosted page');
+      return false;
+    }
+
+    // Only a page still on screen may drive the flow. The page posts on render,
+    // and a webview left behind a payer who has moved on can post again: a `ready`
+    // accepted while they are at their bank would drag the flow back to `hosted`,
+    // and the `openUrl` after it would open a second bank browser for a payment
+    // whose first authorization is already under way.
+    if (!this.isPagePresented()) {
+      log.info(`ignoring a '${message.type}' message from a page no longer on screen`);
+      return false;
+    }
+    switch (message.type) {
+      case 'ready':
+        this.stopWatchingForReadiness();
+        this.moveTo(HostedFlowStates.hosted(this.reference, this.currentState.attempt));
+        break;
+      case 'openUrl':
+        await this.openBank(message.url);
+        break;
+      case 'cancel':
+        // The page spoke, so it is not unreachable whatever it went on to say.
+        this.stopWatchingForReadiness();
+        this.moveTo(HostedFlowStates.cancelled(this.reference, this.currentState.attempt));
+        break;
+      case 'error':
+        this.stopWatchingForReadiness();
+        this.moveTo(HostedFlowStates.failed({
+          reference: this.reference,
+          errorCode: message.code,
+          attempt: this.currentState.attempt
+        }));
+        break;
+    }
+    return true;
+  }
+
+  /**
+   * Resolves the flow from the deep link the payer returned through.
+   *
+   * The outcome is read from the link rather than inferred: it is the only
+   * report of what the bank and the payment actually did.
+   */
+  /** Whether the page is still the thing on screen and may still be believed. */
+  isPagePresented() {
+    const phase = this.currentState.phase;
+    return phase === 'loading' || phase === 'hosted';
+  }
+  handleReturn(uri) {
+    const {
+      outcome,
+      report
+    } = readPaymentReturn(uri);
+
+    // A return that names a different payment is not this payment's business. The
+    // link is handed over by the OS and any app can send one, and a delayed
+    // callback for an earlier payment would otherwise resolve whichever one is
+    // open — with the wrong outcome attached to the wrong reference.
+    if (report.reference !== undefined && report.reference !== this.reference) {
+      log.warning('ignoring a return that names a different payment');
+      return;
+    }
+    this.stopWatchingForReadiness();
+    if (outcome === 'processed') {
+      this.moveTo(HostedFlowStates.succeeded({
+        reference: this.reference,
+        attempt: this.currentState.attempt,
+        report
+      }));
+      return;
+    }
+
+    // `unknown` is not a failure. The service has statuses this version has not
+    // been taught, and a payment still being decided must not be reported as one
+    // that failed — abandoned says "ask your backend", which is the truth.
+    if (outcome === 'unknown') {
+      log.info('the return did not say what happened — reporting it as unresolved');
+      this.moveTo(HostedFlowStates.abandoned(this.reference, this.currentState.attempt));
+      return;
+    }
+    this.moveTo(HostedFlowStates.failed({
+      reference: this.reference,
+      errorCode: report.errorCode ?? 'authorize_failed',
+      attempt: this.currentState.attempt,
+      report
+    }));
+  }
+
+  /**
+   * Records that the payment page could not be loaded.
+   *
+   * Only meaningful before the bank is opened. Once the payer is away, a load
+   * error is the WebView behind them and says nothing about their payment.
+   *
+   * Before the page has spoken this does not resolve the flow: nothing has been
+   * attempted, so the payer is offered the page again rather than told their
+   * payment failed.
+   *
+   * After it has spoken, it does. By then the payer may have chosen a bank and
+   * the page may have created a consent for it, and reloading from the start
+   * could create a second one while silently discarding what they entered.
+   */
+  failToLoad() {
+    const phase = this.currentState.phase;
+    if (phase !== 'loading' && phase !== 'hosted') {
+      log.info('ignoring a page load error raised behind the payer');
+      return;
+    }
+    this.stopWatchingForReadiness();
+    if (phase === 'hosted') {
+      log.severe('the page failed after it had already started — not offering a reload');
+      this.moveTo(HostedFlowStates.failed({
+        reference: this.reference,
+        // Not `page_unavailable`: that means the page was never reached and
+        // nothing was attempted. This page was working, and the payer may have
+        // got as far as a consent before its frame died — a different thing for
+        // a merchant to look into, and a different thing to show the payer.
+        errorCode: 'page_lost',
+        attempt: this.currentState.attempt
+      }));
+      return;
+    }
+    this.moveTo(HostedFlowStates.unreachable(this.reference, this.currentState.attempt));
+  }
+
+  /**
+   * Asks for the page again after it could not be reached.
+   *
+   * The attempt is counted so the screen mounts a fresh webview: reusing the one
+   * that failed would show the payer the same dead frame.
+   */
+  retry() {
+    if (this.currentState.phase !== 'unreachable') {
+      log.info('ignoring a retry for a payment that is not waiting on the page');
+      return;
+    }
+    const attempt = this.currentState.attempt + 1;
+    log.info(`asking for the payment page again (attempt ${attempt})`);
+    // The fresh webview reports itself mounted, which restarts the clock.
+    this.moveTo(HostedFlowStates.loading(this.reference, attempt));
+  }
+
+  /**
+   * Records that the payer gave up on a page that could not be reached.
+   *
+   * Reported as a failure rather than abandonment: the payer did not leave a
+   * payment in progress, the SDK never managed to present one.
+   */
+  giveUp() {
+    if (this.currentState.phase !== 'unreachable') {
+      log.info('ignoring a give-up for a payment that is not waiting on the page');
+      return;
+    }
+    this.stopWatchingForReadiness();
+    this.moveTo(HostedFlowStates.failed({
+      reference: this.reference,
+      errorCode: 'page_unavailable',
+      attempt: this.currentState.attempt
+    }));
+  }
+
+  /**
+   * Records that the payer left before the flow resolved.
+   *
+   * A payment already at the bank may still complete after this, so it is
+   * reported as abandoned rather than failed: the merchant's backend, not the
+   * app, is what knows.
+   */
+  abandon() {
+    this.stopWatchingForReadiness();
+    if (this.currentState.phase === 'unreachable') {
+      // Nothing was ever presented, so there is no payment that might still
+      // complete at the bank — which is what abandonment promises the merchant.
+      this.moveTo(HostedFlowStates.failed({
+        reference: this.reference,
+        errorCode: 'page_unavailable',
+        attempt: this.currentState.attempt
+      }));
+      return;
+    }
+    this.moveTo(HostedFlowStates.abandoned(this.reference, this.currentState.attempt));
+  }
+  dispose() {
+    this.stopWatchingForReadiness();
+    this.listeners.clear();
+  }
+  watchForReadiness() {
+    this.stopWatchingForReadiness();
+    this.readyTimer = setTimeout(() => {
+      this.readyTimer = undefined;
+      if (this.currentState.phase !== 'loading') return;
+      log.severe('the payment page never became interactive — treating it as unreachable');
+      this.moveTo(HostedFlowStates.unreachable(this.reference, this.currentState.attempt));
+    }, this.readyTimeoutMs);
+  }
+  stopWatchingForReadiness() {
+    if (this.readyTimer === undefined) return;
+    clearTimeout(this.readyTimer);
+    this.readyTimer = undefined;
+  }
+
+  /**
+   * Opens the bank and waits for the payer to be sent back.
+   *
+   * The URL is opened exactly once, and never once the flow has resolved. The
+   * page posts on render, so a rebuild can repeat the message; opening a second
+   * browser — or one for a payment the payer has already left — would leave them
+   * authorizing in a window whose return nobody is waiting for.
+   */
+  async openBank(url) {
+    if (isTerminalPhase(this.currentState.phase)) {
+      log.info('not opening the bank for a payment that already resolved');
+      return;
+    }
+    if (this.currentState.phase === 'redirecting' || this.currentState.phase === 'awaitingCallback') {
+      log.info('bank already opened for this payment — ignoring');
+      return;
+    }
+    this.stopWatchingForReadiness();
+    this.moveTo(HostedFlowStates.redirecting(this.reference, this.currentState.attempt));
+    try {
+      await this.bankLauncher(url);
+      this.moveTo(HostedFlowStates.awaitingCallback(this.reference, this.currentState.attempt));
+    } catch {
+      // The platform's message is not logged: a native launcher's error can carry
+      // the whole authorize URL back, `request_uri` and state included.
+      log.severe('could not open the bank');
+      this.moveTo(HostedFlowStates.failed({
+        reference: this.reference,
+        errorCode: 'redirect_failed',
+        attempt: this.currentState.attempt
+      }));
+    }
+  }
+  moveTo(next) {
+    if (isTerminalPhase(this.currentState.phase)) {
+      log.info('ignoring transition after the flow already resolved');
+      return;
+    }
+    this.currentState = next;
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        /* a listener that throws must not stop the others from hearing */
+      }
+    }
+  }
+}
+//# sourceMappingURL=hosted-flow-controller.js.map