@chipmobilesdk/rn-payment 0.5.0 → 0.7.0

package/lib/module/diagnostics/errors.js

@@ -0,0 +1,76 @@
+"use strict";
+
+/**
+ * Normalized public errors.
+ *
+ * Error codes are **public API**: renaming one is a breaking change (FR-078,
+ * LIB-008). They are the vocabulary an app branches on, so they must outlive any
+ * internal refactor and must never leak a store's own code.
+ */
+
+import { REDACTED, SdkError, createRedactor } from '@chipmobilesdk/rn-core';
+const identifiers = createRedactor();
+export const PAYMENT_ERROR_CODES = ['PAYMENT_NOT_CONFIGURED', 'PAYMENT_INVALID_CATALOG', 'PAYMENT_NOT_READY', 'PAYMENT_DISABLED', 'PAYMENT_UNAVAILABLE', 'PAYMENT_UNSUPPORTED_PLATFORM', 'PAYMENT_ENVIRONMENT_BLOCKED', 'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD', 'PAYMENT_PURCHASE_IN_PROGRESS', 'PAYMENT_USER_CANCELLED', 'PAYMENT_PENDING', 'PAYMENT_ALREADY_OWNED', 'PAYMENT_INELIGIBLE', 'PAYMENT_UNKNOWN_PRODUCT', 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION', 'PAYMENT_TIMEOUT', 'PAYMENT_NETWORK_ERROR', 'PAYMENT_STORE_ERROR', 'PAYMENT_FINALIZE_FAILED', 'PAYMENT_VALIDATION_REJECTED', 'PAYMENT_VALIDATION_UNAVAILABLE', 'PAYMENT_STORAGE_UNAVAILABLE', /** `consume` on a transaction that is not a consumable, added in 0.3.2. */
+'PAYMENT_NOT_CONSUMABLE',
+/**
+ * A timeout, backoff or interval outside its bounds, added in 0.5.0. These
+ * used to be reported as `PAYMENT_INVALID_CATALOG`, which is about products.
+ */
+'PAYMENT_INVALID_CONFIG'];
+
+/** Which operation produced an error. Part of the public error shape (FR-078). */
+
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-payment'`. */
+export class PaymentError extends SdkError {
+  /** Redacted where appropriate — never a raw receipt, token, or store object (FR-074). */
+
+  constructor(init) {
+    super('rn-payment', init.code, {
+      message: init.message,
+      retryable: init.retryable ?? false,
+      redactedCause: init.cause
+    });
+    this.name = 'PaymentError';
+    this.operation = init.operation;
+    this.cause = init.cause;
+  }
+}
+
+/**
+ * A configuration problem the app can act on.
+ *
+ * Separate from `PaymentError` because configuration faults are developer-facing
+ * and must never be shown to an end user — the message-key map keeps that
+ * separation explicit (FR-085).
+ */
+export class PaymentConfigError extends PaymentError {
+  /** The offending catalog entries or entitlement keys, named (FR-011). */
+
+  constructor(init) {
+    super({
+      ...init,
+      retryable: false
+    });
+    this.name = 'PaymentConfigError';
+    this.offenders = init.offenders ?? [];
+  }
+}
+
+/**
+ * Strips anything that must never reach a log or event.
+ *
+ * Applied at the boundary rather than trusted to call sites: a single forgotten
+ * interpolation is how receipts end up in logs (NFR-006).
+ *
+ * Identifier-only: what survives is what code defined, never what data carried.
+ * A `PaymentError` keeps its code and an `Error` its class name; every message
+ * and every string is dropped, because a store or consumer message can embed a
+ * purchase token or an account id and nothing here can tell which.
+ */
+export function redact(value) {
+  // An SDK error reduces to its code and any other Error to its class name
+  // (rn-core's identifier-only redactor). Strings never survive here, not even
+  // a leading constant: a store message is free text from a payments SDK.
+  return value instanceof Error ? identifiers.text(value) : REDACTED;
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/diagnostics/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["REDACTED","SdkError","createRedactor","identifiers","PAYMENT_ERROR_CODES","PaymentError","constructor","init","code","message","retryable","redactedCause","cause","name","operation","PaymentConfigError","offenders","redact","value","Error","text"],"sourceRoot":"../../../src","sources":["diagnostics/errors.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,QAAQ,EAAEC,QAAQ,EAAEC,cAAc,QAAQ,wBAAwB;AAE3E,MAAMC,WAAW,GAAGD,cAAc,CAAC,CAAC;AAEpC,OAAO,MAAME,mBAAmB,GAAG,CAClC,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,8BAA8B,EAC9B,6BAA6B,EAC7B,mDAAmD,EACnD,8BAA8B,EAC9B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,uCAAuC,EACvC,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,EAC7B,gCAAgC,EAChC,6BAA6B,EAC7B;AACA,wBAAwB;AACxB;AACD;AACA;AACA;AACC,wBAAwB,CACf;;AAIV;;AAcA;AACA,OAAO,MAAMC,YAAY,SAASJ,QAAQ,CAAmB;EAE5D;;EAGAK,WAAWA,CAACC,IAMX,EAAE;IACF,KAAK,CAAC,YAAY,EAAEA,IAAI,CAACC,IAAI,EAAE;MAC9BC,OAAO,EAAEF,IAAI,CAACE,OAAO;MACrBC,SAAS,EAAEH,IAAI,CAACG,SAAS,IAAI,KAAK;MAClCC,aAAa,EAAEJ,IAAI,CAACK;IACrB,CAAC,CAAC;IACF,IAAI,CAACC,IAAI,GAAG,cAAc;IAC1B,IAAI,CAACC,SAAS,GAAGP,IAAI,CAACO,SAAS;IAC/B,IAAI,CAACF,KAAK,GAAGL,IAAI,CAACK,KAAK;EACxB;AACD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,kBAAkB,SAASV,YAAY,CAAC;EACpD;;EAGAC,WAAWA,CAACC,IAKX,EAAE;IACF,KAAK,CAAC;MAAE,GAAGA,IAAI;MAAEG,SAAS,EAAE;IAAM,CAAC,CAAC;IACpC,IAAI,CAACG,IAAI,GAAG,oBAAoB;IAChC,IAAI,CAACG,SAAS,GAAGT,IAAI,CAACS,SAAS,IAAI,EAAE;EACtC;AACD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,KAAc,EAAU;EAC9C;EACA;EACA;EACA,OAAOA,KAAK,YAAYC,KAAK,GAAGhB,WAAW,CAACiB,IAAI,CAACF,KAAK,CAAC,GAAGlB,QAAQ;AACnE","ignoreList":[]}

package/lib/module/diagnostics/events.js

@@ -0,0 +1,117 @@
+"use strict";
+
+/**
+ * Typed events and the emitter.
+ *
+ * The bar is FR-077: the event stream **alone** must be enough to reconstruct a
+ * transaction's full lifecycle, so that "the user says they paid but has no
+ * entitlement" can be investigated from logs without a reproduction.
+ *
+ * Forbidden in every payload, without exception (FR-076, FR-074): store objects,
+ * raw receipts, verification payloads, backend tokens, payment details, the
+ * obfuscated account identifier, and the cache-scope token.
+ */
+
+import { createDiagnosticChannel, createEmitter as createCoreEmitter } from '@chipmobilesdk/rn-core';
+
+/** Every delivered event also goes to the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel('rn-payment');
+import { redact } from "./errors.js";
+
+/**
+ * A `PaymentEvent` with the timestamp left to the emitter.
+ *
+ * Distributive on purpose: a plain `Omit<PaymentEvent, 'timestamp'>` collapses the
+ * discriminated union into one object type with only the shared keys, which would
+ * reject every variant-specific field. `T extends unknown` forces the mapping to
+ * apply per member and keeps the union discriminated.
+ */
+
+/**
+ * Creates the emitter.
+ *
+ * Two properties are deliberate:
+ *
+ * 1. **A throwing listener cannot break anything** (FR-081). Each listener is
+ *    invoked defensively, the throw is handed to `onListenerError`, and delivery
+ *    continues to the remaining listeners. One app's broken analytics callback
+ *    must not stop the package granting an entitlement or stop another listener
+ *    hearing about it.
+ *
+ *    The failure is **not** re-emitted as an event, deliberately. A consumer's own
+ *    bug is not a payment-lifecycle event, and reporting it through the channel
+ *    that just failed would both invite recursion and double event traffic for
+ *    every event while that listener stays broken. It goes to the logger instead.
+ *
+ * 2. **After `dispose`, nothing is emitted** (FR-082). A store callback can
+ *    arrive after cleanup; it must be dropped silently rather than reach a
+ *    listener whose component is gone.
+ */
+export function createEmitter(onListenerError) {
+  // The event whose listeners are running, so a failure is reported against it.
+  let dispatching = null;
+  let isDisposed = false;
+  // rn-core's emitter: a snapshot per emit, each listener isolated, idempotent
+  // unsubscribe. Even the error reporter is isolated: if it throws, rn-core
+  // rethrows that on a fresh task rather than into the emit.
+  const emitter = createCoreEmitter({
+    onListenerError: error => {
+      if (!dispatching) return;
+      try {
+        onListenerError?.(error, dispatching);
+      } catch {
+        // The app's own reporter failed: nothing in the app is left to tell, so
+        // the failure goes to the SDK sinks rather than becoming an uncaught
+        // error on some later tick (FR-080).
+        channel.emit('listener_reporter_failed', 'error', {
+          eventType: dispatching.type
+        });
+      }
+    }
+  });
+  return {
+    emit(event) {
+      if (isDisposed) {
+        return;
+      }
+      const previous = dispatching;
+      dispatching = event;
+      try {
+        if (emitter.emit(event)) {
+          // The type and the cycle only: payment events carry product and
+          // entitlement keys an app may treat as personal.
+          channel.emit(event.type, /failed|error|blocked|rejected|revoked/.test(event.type) ? 'warn' : 'info', undefined, event.correlationId);
+        }
+      } finally {
+        dispatching = previous;
+      }
+    },
+    subscribe(listener) {
+      return isDisposed ? () => undefined : emitter.subscribe(listener);
+    },
+    dispose() {
+      isDisposed = true;
+      emitter.dispose();
+    },
+    listenerCount: () => emitter.listenerCount(),
+    disposed: () => isDisposed
+  };
+}
+
+/**
+ * Fields that must never appear in an event payload.
+ *
+ * Used by `__tests__/diagnostics.test.ts` to walk every emitted event across the
+ * whole suite. Enumerating the ban here rather than in the test keeps the rule
+ * next to the type it constrains.
+ */
+export const FORBIDDEN_EVENT_FIELDS = ['verificationPayload', 'receipt', 'purchaseToken', 'transactionReceipt', 'obfuscatedAccountId', 'scopeToken', 'token', 'signature'];
+
+/** Correlation ids tie one purchase cycle together; no user data goes into them. */
+export function createCorrelationId(counter, prefix = 'pc') {
+  const id = `${prefix}_${counter.next.toString(36)}`;
+  counter.next += 1;
+  return id;
+}
+export { redact };
+//# sourceMappingURL=events.js.map

package/lib/module/diagnostics/events.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createDiagnosticChannel","createEmitter","createCoreEmitter","channel","redact","onListenerError","dispatching","isDisposed","emitter","error","emit","eventType","type","event","previous","test","undefined","correlationId","subscribe","listener","dispose","listenerCount","disposed","FORBIDDEN_EVENT_FIELDS","createCorrelationId","counter","prefix","id","next","toString"],"sourceRoot":"../../../src","sources":["diagnostics/events.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SACCA,uBAAuB,EACvBC,aAAa,IAAIC,iBAAiB,QAC5B,wBAAwB;;AAE/B;AACA,MAAMC,OAAO,GAAGH,uBAAuB,CACtC,YACD,CAAC;AAED,SAASI,MAAM,QAAsD,aAAU;;AAoI/E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASH,aAAaA,CAC5BI,eAA+D,EAC9C;EACjB;EACA,IAAIC,WAAgC,GAAG,IAAI;EAC3C,IAAIC,UAAU,GAAG,KAAK;EACtB;EACA;EACA;EACA,MAAMC,OAAO,GAAGN,iBAAiB,CAAe;IAC/CG,eAAe,EAAEI,KAAK,IAAI;MACzB,IAAI,CAACH,WAAW,EAAE;MAClB,IAAI;QACHD,eAAe,GAAGI,KAAK,EAAEH,WAAW,CAAC;MACtC,CAAC,CAAC,MAAM;QACP;QACA;QACA;QACAH,OAAO,CAACO,IAAI,CAAC,0BAA0B,EAAE,OAAO,EAAE;UACjDC,SAAS,EAAEL,WAAW,CAACM;QACxB,CAAC,CAAC;MACH;IACD;EACD,CAAC,CAAC;EAEF,OAAO;IACNF,IAAIA,CAACG,KAAK,EAAE;MACX,IAAIN,UAAU,EAAE;QACf;MACD;MACA,MAAMO,QAAQ,GAAGR,WAAW;MAC5BA,WAAW,GAAGO,KAAK;MACnB,IAAI;QACH,IAAIL,OAAO,CAACE,IAAI,CAACG,KAAK,CAAC,EAAE;UACxB;UACA;UACAV,OAAO,CAACO,IAAI,CACXG,KAAK,CAACD,IAAI,EACV,uCAAuC,CAACG,IAAI,CAACF,KAAK,CAACD,IAAI,CAAC,GAAG,MAAM,GAAG,MAAM,EAC1EI,SAAS,EACTH,KAAK,CAACI,aACP,CAAC;QACF;MACD,CAAC,SAAS;QACTX,WAAW,GAAGQ,QAAQ;MACvB;IACD,CAAC;IACDI,SAASA,CAACC,QAA8B,EAAe;MACtD,OAAOZ,UAAU,GAAG,MAAMS,SAAS,GAAGR,OAAO,CAACU,SAAS,CAACC,QAAQ,CAAC;IAClE,CAAC;IACDC,OAAOA,CAAA,EAAS;MACfb,UAAU,GAAG,IAAI;MACjBC,OAAO,CAACY,OAAO,CAAC,CAAC;IAClB,CAAC;IACDC,aAAa,EAAEA,CAAA,KAAMb,OAAO,CAACa,aAAa,CAAC,CAAC;IAC5CC,QAAQ,EAAEA,CAAA,KAAMf;EACjB,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMgB,sBAAyC,GAAG,CACxD,qBAAqB,EACrB,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,OAAO,EACP,WAAW,CACX;;AAED;AACA,OAAO,SAASC,mBAAmBA,CAACC,OAAyB,EAAEC,MAAM,GAAG,IAAI,EAAU;EACrF,MAAMC,EAAE,GAAG,GAAGD,MAAM,IAAID,OAAO,CAACG,IAAI,CAACC,QAAQ,CAAC,EAAE,CAAC,EAAE;EACnDJ,OAAO,CAACG,IAAI,IAAI,CAAC;EACjB,OAAOD,EAAE;AACV;AAEA,SAASvB,MAAM","ignoreList":[]}

package/lib/module/diagnostics/messageKeys.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * Stable, localizable message keys with English default copy (FR-084, FR-085).
+ *
+ * The package takes no i18n runtime dependency: consuming apps map these keys to
+ * localized strings through whatever i18n system they already run. This is plain
+ * data, and the package never resolves or renders it.
+ *
+ * Message keys are **public API**: renaming one is a breaking change, on the
+ * same footing as an error code (FR-078).
+ *
+ * User-actionable copy and developer/configuration copy are kept in separate
+ * maps so an app cannot accidentally show "Payment catalog is invalid" to a
+ * customer — a configuration fault is a developer's problem, not a user's.
+ */
+
+/** Copy an end user may reasonably be shown. */
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
+/** Copy for developers and operators. **Never** surfaced to an end user. */
+
+export const DEFAULT_USER_MESSAGES = {
+  'payment.state.pending': 'Waiting for your payment to complete',
+  'payment.state.alreadyOwned': 'You already own this',
+  'payment.action.restore': 'Restore purchases',
+  'payment.restore.succeeded': 'Your purchases have been restored',
+  'payment.restore.nothingFound': 'No previous purchases found',
+  'payment.error.cancelled': 'Purchase cancelled',
+  'payment.error.network': "Couldn't reach the store. Check your connection and try again.",
+  'payment.error.unavailable': "Purchases aren't available on this device",
+  'payment.error.disabled': 'Purchases are currently unavailable',
+  'payment.subscription.grace': "There's a problem with your payment method",
+  'payment.subscription.hold': 'Your subscription is paused until payment is updated'
+};
+export const DEFAULT_DEVELOPER_MESSAGES = {
+  'payment.config.invalidCatalog': 'Payment catalog is invalid',
+  'payment.config.missingStoreId': 'Product is missing a store identifier for this platform',
+  'payment.config.productionInNonProductionBuild': 'Production payment configuration in a non-production build',
+  'payment.config.storageUnavailable': 'Local storage unavailable; entitlements will not survive restart',
+  'payment.config.environmentBlocked': 'Purchase blocked: this environment may not create a real transaction'
+};
+
+/**
+ * The catalog as an rn-core message set. Register `paymentMessages.user` with
+ * rn-i18n to translate it like app copy; the developer copy stays out of bundles.
+ */
+export const paymentMessages = defineMessages({
+  user: DEFAULT_USER_MESSAGES,
+  developer: DEFAULT_DEVELOPER_MESSAGES
+});
+export const DEFAULT_MESSAGES = paymentMessages.defaults;
+
+/** Every user-actionable key, for an app building its translation resource. */
+export const USER_MESSAGE_KEYS = paymentMessages.userKeys;
+
+/** Every developer-facing key, so an app can exclude them from user-visible bundles. */
+export const DEVELOPER_MESSAGE_KEYS = paymentMessages.developerKeys;
+
+/** True for keys safe to show an end user. Lets an app assert that at its boundary. */
+export function isUserMessageKey(key) {
+  return paymentMessages.audienceOf(key) === 'user';
+}
+//# sourceMappingURL=messageKeys.js.map

package/lib/module/diagnostics/messageKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["defineMessages","DEFAULT_USER_MESSAGES","DEFAULT_DEVELOPER_MESSAGES","paymentMessages","user","developer","DEFAULT_MESSAGES","defaults","USER_MESSAGE_KEYS","userKeys","DEVELOPER_MESSAGE_KEYS","developerKeys","isUserMessageKey","key","audienceOf"],"sourceRoot":"../../../src","sources":["diagnostics/messageKeys.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,SAASA,cAAc,QAAQ,wBAAwB;;AAgBvD;;AAeA,OAAO,MAAMC,qBAA4C,GAAG;EAC3D,uBAAuB,EAAE,sCAAsC;EAC/D,4BAA4B,EAAE,sBAAsB;EACpD,wBAAwB,EAAE,mBAAmB;EAC7C,2BAA2B,EAAE,mCAAmC;EAChE,8BAA8B,EAAE,6BAA6B;EAC7D,yBAAyB,EAAE,oBAAoB;EAC/C,uBAAuB,EAAE,gEAAgE;EACzF,2BAA2B,EAAE,2CAA2C;EACxE,wBAAwB,EAAE,qCAAqC;EAC/D,4BAA4B,EAAE,4CAA4C;EAC1E,2BAA2B,EAAE;AAC9B,CAAC;AAED,OAAO,MAAMC,0BAAsD,GAAG;EACrE,+BAA+B,EAAE,4BAA4B;EAC7D,+BAA+B,EAAE,yDAAyD;EAC1F,+CAA+C,EAC9C,4DAA4D;EAC7D,mCAAmC,EAClC,kEAAkE;EACnE,mCAAmC,EAClC;AACF,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGH,cAAc,CAAC;EAC7CI,IAAI,EAAEH,qBAAqB;EAC3BI,SAAS,EAAEH;AACZ,CAAC,CAAC;AAEF,OAAO,MAAMI,gBAAmC,GAAGH,eAAe,CAACI,QAAQ;;AAE3E;AACA,OAAO,MAAMC,iBAAiB,GAAGL,eAAe,CAACM,QAAmC;;AAEpF;AACA,OAAO,MAAMC,sBAAsB,GAAGP,eAAe,CAACQ,aAA6C;;AAEnG;AACA,OAAO,SAASC,gBAAgBA,CAACC,GAAsB,EAAgC;EACtF,OAAOV,eAAe,CAACW,UAAU,CAACD,GAAG,CAAC,KAAK,MAAM;AAClD","ignoreList":[]}

package/lib/module/engine/connection.js

@@ -0,0 +1,185 @@
+"use strict";
+
+/**
+ * The billing connection: connecting, watching it, and reconnecting with bounded
+ * backoff (FR-018 – FR-024, PAY-10).
+ *
+ * A reconnect is always a full teardown-then-connect cycle. The upstream
+ * binding's own `reconnect()` has reported success without rebuilding anything
+ * (openiap#408), so no shortcut is trusted here.
+ */
+
+import { backoffDelayMs } from "../core/retry.js";
+import { withTimeout } from "../core/mutex.js";
+import { PaymentError } from "../diagnostics/errors.js";
+export function createConnection(state, onPurchase) {
+  const {
+    provider,
+    resolved
+  } = state;
+  let connectionSub;
+  let purchaseSub;
+  let reconnectTimer;
+  let reconnectAttempts = 0;
+  /**
+   * Set once a connection succeeded. Recovery after an exhausted budget is only
+   * meaningful from there; a first connection that failed is the app's to retry
+   * through `initialize`.
+   */
+  let everConnected = false;
+  function scheduleReconnect() {
+    if (state.disposed) {
+      return;
+    }
+    if (reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+      // Out of budget for now, not for good: a retryable failure rather than a
+      // `connecting` that promised a reconnect nobody was going to make.
+      state.setStatus({
+        kind: 'failed',
+        retryable: true,
+        reconnectAttempts
+      });
+      return;
+    }
+    const attempt = reconnectAttempts + 1;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = undefined;
+      if (state.disposed) {
+        return;
+      }
+      reconnectAttempts = attempt;
+      state.setStatus({
+        kind: 'connecting',
+        reconnectAttempts
+      });
+      reconnectOnce().catch(() => undefined);
+    }, backoffDelayMs(attempt, resolved.retry.reconnect));
+  }
+  async function reconnectOnce() {
+    try {
+      await provider.disconnect();
+    } catch {
+      // Already down; nothing to tear down.
+    }
+    const outcome = await provider.connect();
+    if (state.disposed) {
+      return;
+    }
+    if (outcome.ok) {
+      reconnectAttempts = 0;
+      state.setStatus({
+        kind: 'ready',
+        reconnectAttempts: 0
+      });
+    } else {
+      scheduleReconnect();
+    }
+  }
+
+  /** Replaced, never stacked: a second subscription would hear everything twice. */
+  function watch() {
+    connectionSub?.();
+    connectionSub = provider.observeConnection((connected, reason) => {
+      if (state.disposed) {
+        return;
+      }
+      state.emit({
+        type: 'connection_changed',
+        connected,
+        reason,
+        attempt: reconnectAttempts
+      });
+      if (!connected && state.status.kind === 'ready') {
+        state.setStatus({
+          kind: 'connecting'
+        });
+        scheduleReconnect();
+      }
+    });
+    // Session-long: a pending purchase settling between sessions arrives here
+    // (FR-039), not only while a purchase is open.
+    purchaseSub?.();
+    purchaseSub = provider.observePurchases(purchase => {
+      if (!state.disposed) {
+        onPurchase(purchase);
+      }
+    });
+  }
+  return {
+    async connect() {
+      const outcome = await withTimeout(provider.connect(), resolved.timeouts.connectMs, () => new PaymentError({
+        code: 'PAYMENT_TIMEOUT',
+        message: 'Connecting to the billing service timed out',
+        operation: 'initialize',
+        retryable: true
+      })).catch(error => ({
+        ok: false,
+        reason: 'store_error',
+        retryable: error.retryable
+      }));
+      if (!outcome.ok) {
+        if (outcome.reason === 'store_error') {
+          state.setStatus({
+            kind: 'failed',
+            retryable: outcome.retryable
+          });
+          return {
+            ok: false,
+            error: new PaymentError({
+              code: 'PAYMENT_STORE_ERROR',
+              message: 'Could not connect to the billing service',
+              operation: 'initialize',
+              retryable: outcome.retryable
+            })
+          };
+        }
+        // No billing service, an outdated one, or an unsupported platform: each
+        // distinguishable, and none of them may break the host app (FR-021, FR-023).
+        state.setStatus({
+          kind: 'unavailable',
+          unavailableReason: outcome.reason,
+          retryable: outcome.retryable
+        });
+        return {
+          ok: false,
+          error: new PaymentError({
+            code: outcome.reason === 'platform_unsupported' ? 'PAYMENT_UNSUPPORTED_PLATFORM' : 'PAYMENT_UNAVAILABLE',
+            message: `Billing unavailable: ${outcome.reason}`,
+            operation: 'initialize',
+            retryable: outcome.retryable
+          })
+        };
+      }
+      watch();
+      everConnected = true;
+      state.setStatus({
+        kind: 'ready',
+        reconnectAttempts: 0
+      });
+      return {
+        ok: true
+      };
+    },
+    async recover() {
+      if (everConnected && !state.disposed && state.status.kind === 'failed' && reconnectTimer === undefined) {
+        reconnectAttempts = 0;
+        state.setStatus({
+          kind: 'connecting',
+          reconnectAttempts: 0
+        });
+        await reconnectOnce().catch(() => undefined);
+      }
+    },
+    dispose() {
+      connectionSub?.();
+      connectionSub = undefined;
+      purchaseSub?.();
+      purchaseSub = undefined;
+      if (reconnectTimer !== undefined) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = undefined;
+      }
+    }
+  };
+}
+//# sourceMappingURL=connection.js.map

package/lib/module/engine/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["backoffDelayMs","withTimeout","PaymentError","createConnection","state","onPurchase","provider","resolved","connectionSub","purchaseSub","reconnectTimer","reconnectAttempts","everConnected","scheduleReconnect","disposed","retry","reconnect","maxAttempts","setStatus","kind","retryable","attempt","setTimeout","undefined","reconnectOnce","catch","disconnect","outcome","connect","ok","watch","observeConnection","connected","reason","emit","type","status","observePurchases","purchase","timeouts","connectMs","code","message","operation","error","unavailableReason","recover","dispose","clearTimeout"],"sourceRoot":"../../../src","sources":["engine/connection.ts"],"mappings":"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","ignoreList":[]}