@chipmobilesdk/rn-payment 0.6.0 → 0.7.0

package/lib/module/engine/finalize.js

@@ -0,0 +1,322 @@
+"use strict";
+
+/**
+ * The finalization queue — the package's hardest invariant (FR-041, FR-042).
+ *
+ * Google auto-refunds and revokes a purchase that is not acknowledged within
+ * **three days**. So finalization cannot be a step the app might forget, and it
+ * cannot live only in memory: the failure case FR-042 names is the app being
+ * force-killed in the instant between payment and acknowledgement.
+ *
+ * The ordering that makes this work is: **write the intent, then call the store.**
+ * A crash before the write means the purchase is still owned and the next sync
+ * re-queues it from `queryOwned`. A crash after the write means the queue has a
+ * record and the next startup drains it. There is no window where a paid
+ * transaction is forgotten.
+ *
+ * Consumption stays app-triggered (FR-043), because only the app knows whether
+ * the item was actually banked in its own data.
+ */
+
+import { backoffDelayMs } from "../core/retry.js";
+import { withTimeout } from "../core/mutex.js";
+import { PaymentError } from "../diagnostics/errors.js";
+import { pendingFinalizations } from "../persistence/snapshot.js";
+
+/** A Node `Timeout` and a browser numeric id are both valid here. */
+
+export function createFinalizer(deps) {
+  const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+  const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+
+  /** One timer per transaction, so two transactions retry independently. */
+  const timers = new Map();
+  /** Guards against two drains racing the same transaction. */
+  const inFlight = new Set();
+  const find = transactionId => deps.snapshot().purchases.find(p => p.transactionId === transactionId);
+  const patch = (transactionId, changes) => {
+    const snapshot = deps.snapshot();
+    deps.commit({
+      ...snapshot,
+      purchases: snapshot.purchases.map(p => p.transactionId === transactionId ? {
+        ...p,
+        ...changes
+      } : p)
+    });
+  };
+
+  /**
+   * One store call under `attemptTimeoutMs`. A call that never settles used to
+   * hold this transaction's in-flight guard and, through `drain`, the sync that
+   * awaited it. Timing out counts as a failed attempt, so the retry schedule and
+   * the next-session drain both still apply.
+   */
+  const bounded = (call, operation) => withTimeout(call, deps.attemptTimeoutMs, () => new PaymentError({
+    code: 'PAYMENT_TIMEOUT',
+    message: `The store did not answer the ${operation} call in time`,
+    operation,
+    retryable: true
+  }));
+  const clearTimer = transactionId => {
+    const timer = timers.get(transactionId);
+    if (timer !== undefined) {
+      clearTimeoutFn(timer);
+      timers.delete(transactionId);
+    }
+  };
+
+  /**
+   * Attempts one finalize call.
+   *
+   * A consumable is **not** acknowledged here: it waits for the app's explicit
+   * `consume`. Acknowledging it now would tell the store the entitlement was
+   * delivered before the app has recorded the item, and a crash in between would
+   * lose a paid item with no way to recover it.
+   */
+  const attempt = async transactionId => {
+    if (deps.disposed()) {
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_NOT_CONFIGURED'
+      };
+    }
+    const record = find(transactionId);
+    if (!record) {
+      return {
+        kind: 'unknown_transaction'
+      };
+    }
+    if (record.finalizeState === 'done') {
+      // Idempotent by design: calling twice is a success, not an error (FR-044).
+      return {
+        kind: 'already_finalized'
+      };
+    }
+    if (record.productType === 'one_time_consumable') {
+      // The app owns this moment. Nothing to do until it calls consume().
+      return {
+        kind: 'already_finalized'
+      };
+    }
+    if (inFlight.has(transactionId)) {
+      return {
+        kind: 'retry_scheduled',
+        attempts: record.attempts
+      };
+    }
+    inFlight.add(transactionId);
+    patch(transactionId, {
+      finalizeState: 'in_flight'
+    });
+    let failed = false;
+    try {
+      await bounded(deps.provider.acknowledge(record.token), 'finalize');
+    } catch {
+      failed = true;
+    } finally {
+      // Released before scheduling the retry, deliberately. The guard exists to
+      // stop two concurrent store calls for one transaction, nothing more — if
+      // it were still held here, the next scheduled attempt would be refused by
+      // our own lock and the retry schedule would silently stall after one try.
+      inFlight.delete(transactionId);
+    }
+    const attempts = record.attempts + 1;
+    if (!failed) {
+      clearTimer(transactionId);
+      patch(transactionId, {
+        finalizeState: 'done',
+        state: 'purchased',
+        attempts
+      });
+      deps.emit({
+        type: 'transaction_finalized',
+        productKey: record.productKey,
+        attempts
+      });
+      return {
+        kind: 'finalized'
+      };
+    }
+    patch(transactionId, {
+      finalizeState: 'failed',
+      attempts
+    });
+    return scheduleRetry(transactionId, record.productKey, attempts, 'acknowledge');
+  };
+
+  /**
+   * One consume call for a consumable the app has banked (FR-043).
+   *
+   * Refuses anything that is not a settled consumable. Consuming a subscription
+   * or a permanent unlock would tell the store the user used it up, and a
+   * pending purchase has nothing to consume yet.
+   */
+  const consumeAttempt = async transactionId => {
+    if (deps.disposed()) {
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_NOT_CONFIGURED'
+      };
+    }
+    const record = find(transactionId);
+    if (!record) {
+      return {
+        kind: 'unknown_transaction'
+      };
+    }
+    if (record.productType !== 'one_time_consumable') {
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_NOT_CONSUMABLE'
+      };
+    }
+    if (record.state === 'pending') {
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_PENDING'
+      };
+    }
+    if (record.state === 'consumed') {
+      // Consuming twice must grant the item once (FR-044).
+      return {
+        kind: 'already_finalized'
+      };
+    }
+    if (inFlight.has(transactionId)) {
+      // Concurrent consume calls collapse to one, for the same reason.
+      return {
+        kind: 'already_finalized'
+      };
+    }
+    inFlight.add(transactionId);
+    patch(transactionId, {
+      finalizeState: 'in_flight'
+    });
+    let failed = false;
+    try {
+      await bounded(deps.provider.consume(record.token), 'consume');
+    } catch {
+      failed = true;
+    } finally {
+      // Released before scheduling, for the same reason as in `attempt`.
+      inFlight.delete(transactionId);
+    }
+    const attempts = record.attempts + 1;
+    if (failed) {
+      patch(transactionId, {
+        finalizeState: 'failed',
+        attempts
+      });
+      return scheduleRetry(transactionId, record.productKey, attempts, 'consume');
+    }
+    clearTimer(transactionId);
+    // `consumed` is what stops it being an entitlement source, so a
+    // consumable never becomes a permanent unlock.
+    patch(transactionId, {
+      state: 'consumed',
+      finalizeState: 'done',
+      attempts
+    });
+    deps.emit({
+      type: 'transaction_consumed',
+      productKey: record.productKey
+    });
+    return {
+      kind: 'finalized'
+    };
+  };
+
+  /**
+   * Schedules the next attempt inside the per-session budget.
+   *
+   * Exhausting the budget is **not** giving up. The record stays `failed`, which
+   * `pendingFinalizations` still returns, so the next startup or foreground drain
+   * picks it up again. That is what keeps the package inside Play's three-day
+   * window without hammering a store that is currently refusing.
+   */
+  const scheduleRetry = (transactionId, productKey, attempts, operation) => {
+    if (deps.disposed()) {
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_FINALIZE_FAILED'
+      };
+    }
+    if (attempts >= deps.retry.finalize.maxAttempts) {
+      // Left queued deliberately — resumed next session, never abandoned.
+      return {
+        kind: 'failed',
+        code: 'PAYMENT_FINALIZE_FAILED'
+      };
+    }
+    const delayMs = backoffDelayMs(attempts + 1, deps.retry.finalize);
+    clearTimer(transactionId);
+    timers.set(transactionId, setTimeoutFn(() => {
+      timers.delete(transactionId);
+      const retry = operation === 'consume' ? consumeAttempt : attempt;
+      retry(transactionId).catch(() => undefined);
+    }, delayMs));
+    deps.emit({
+      type: 'finalize_retry_scheduled',
+      productKey,
+      attempt: attempts + 1,
+      delayMs
+    });
+    return {
+      kind: 'retry_scheduled',
+      attempts
+    };
+  };
+  return {
+    async enqueue(transactionId) {
+      const record = find(transactionId);
+      if (!record) {
+        return {
+          kind: 'unknown_transaction'
+        };
+      }
+      if (record.finalizeState === 'done') {
+        return {
+          kind: 'already_finalized'
+        };
+      }
+
+      // The write happens BEFORE the store call. This single ordering is what
+      // makes a kill between payment and acknowledgement recoverable.
+      if (record.finalizeState !== 'in_flight') {
+        patch(transactionId, {
+          finalizeState: 'queued'
+        });
+      }
+      return attempt(transactionId);
+    },
+    async drain() {
+      // Runs regardless of whether a purchase happened this session: the record
+      // it is looking for was probably written by a session that died.
+      for (const record of pendingFinalizations(deps.snapshot())) {
+        if (deps.disposed()) {
+          return;
+        }
+        await attempt(record.transactionId).catch(() => undefined);
+      }
+    },
+    consume(ref) {
+      return consumeAttempt(ref.transactionId);
+    },
+    unfinalized() {
+      return pendingFinalizations(deps.snapshot()).map(p => ({
+        productKey: p.productKey,
+        transactionId: p.transactionId,
+        attempts: p.attempts,
+        purchasedAt: p.purchasedAt
+      }));
+    },
+    dispose() {
+      for (const timer of timers.values()) {
+        clearTimeoutFn(timer);
+      }
+      timers.clear();
+      inFlight.clear();
+    }
+  };
+}
+//# sourceMappingURL=finalize.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["backoffDelayMs","withTimeout","PaymentError","pendingFinalizations","createFinalizer","deps","setTimeoutFn","setTimeout","clearTimeoutFn","clearTimeout","timers","Map","inFlight","Set","find","transactionId","snapshot","purchases","p","patch","changes","commit","map","bounded","call","operation","attemptTimeoutMs","code","message","retryable","clearTimer","timer","get","undefined","delete","attempt","disposed","kind","record","finalizeState","productType","has","attempts","add","failed","provider","acknowledge","token","state","emit","type","productKey","scheduleRetry","consumeAttempt","consume","retry","finalize","maxAttempts","delayMs","set","catch","enqueue","drain","ref","unfinalized","purchasedAt","dispose","values","clear"],"sourceRoot":"../../../src","sources":["engine/finalize.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/engine/foreground.js

@@ -0,0 +1,21 @@
+"use strict";
+
+/**
+ * Opt-in foreground sync over rn-core's shared lifecycle port (PERF-07, FR-059).
+ *
+ * `handleForeground()` stays the app's to call: the engine does not decide what a
+ * foreground return is. An app that is happy with "back from the background" calls
+ * this once instead of wiring `AppState` itself, and shares the one native
+ * subscription every package uses. A trip through `inactive` alone (a biometric
+ * prompt, iOS Control Center) is not a return. On Android the Play purchase sheet
+ * does send the app to the background, so a purchase is followed by a sync; the
+ * engine's foreground rate limit keeps that to one request per interval.
+ */
+import { appLifecycle, onForeground } from '@chipmobilesdk/rn-core';
+export function syncOnForeground(engine, lifecycle = appLifecycle()) {
+  return onForeground(() => {
+    // Sync reports its own failures through status and diagnostics.
+    engine.handleForeground().catch(() => undefined);
+  }, lifecycle);
+}
+//# sourceMappingURL=foreground.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["appLifecycle","onForeground","syncOnForeground","engine","lifecycle","handleForeground","catch","undefined"],"sourceRoot":"../../../src","sources":["engine/foreground.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SACCA,YAAY,EACZC,YAAY,QAGN,wBAAwB;AAI/B,OAAO,SAASC,gBAAgBA,CAC/BC,MAA+C,EAC/CC,SAA2B,GAAGJ,YAAY,CAAC,CAAC,EAC9B;EACd,OAAOC,YAAY,CAAC,MAAM;IACzB;IACAE,MAAM,CAACE,gBAAgB,CAAC,CAAC,CAACC,KAAK,CAAC,MAAMC,SAAS,CAAC;EACjD,CAAC,EAAEH,SAAS,CAAC;AACd","ignoreList":[]}

package/lib/module/engine/internals.js

@@ -0,0 +1,26 @@
+"use strict";
+
+/**
+ * What tests and diagnostics need from an engine, off its public type (PAY-11).
+ *
+ * Until 0.6.0 these were methods of `PaymentEngine`, so any consumer could commit
+ * a snapshot of its own and grant itself an entitlement the store never sold,
+ * and a hand-written engine double had to implement all of them. They live in a
+ * WeakMap keyed by the engine now, and this module is not exported from the
+ * package entrypoint.
+ */
+
+const registry = new WeakMap();
+export function attachEngineInternals(engine, internals) {
+  registry.set(engine, internals);
+}
+
+/** The internals of an engine `createEngine` made. Throws for any other object. */
+export function engineInternals(engine) {
+  const internals = registry.get(engine);
+  if (!internals) {
+    throw new Error('engineInternals: this engine was not created by createEngine');
+  }
+  return internals;
+}
+//# sourceMappingURL=internals.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["registry","WeakMap","attachEngineInternals","engine","internals","set","engineInternals","get","Error"],"sourceRoot":"../../../src","sources":["engine/internals.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAkBA,MAAMA,QAAQ,GAAG,IAAIC,OAAO,CAAiC,CAAC;AAE9D,OAAO,SAASC,qBAAqBA,CAACC,MAAqB,EAAEC,SAA0B,EAAQ;EAC9FJ,QAAQ,CAACK,GAAG,CAACF,MAAM,EAAEC,SAAS,CAAC;AAChC;;AAEA;AACA,OAAO,SAASE,eAAeA,CAACH,MAAqB,EAAmB;EACvE,MAAMC,SAAS,GAAGJ,QAAQ,CAACO,GAAG,CAACJ,MAAM,CAAC;EACtC,IAAI,CAACC,SAAS,EAAE;IACf,MAAM,IAAII,KAAK,CAAC,8DAA8D,CAAC;EAChF;EACA,OAAOJ,SAAS;AACjB","ignoreList":[]}

package/lib/module/engine/pending.js

@@ -0,0 +1,95 @@
+"use strict";
+
+/**
+ * The pending set, and how a pending purchase ends (FR-101 – FR-104), added in
+ * 0.2.0.
+ *
+ * 0.1.0 handled pending purchases correctly on the grant side — pending never
+ * grants, a settled one is granted at the next sync, an abandoned one is removed
+ * — but an app could only *see* one in the session it started in. The record
+ * was already persisted with a `pending` state; this module is the read side of
+ * it, and nothing more. It decides nothing about granting: that stays in
+ * `entitlements/aggregate.ts`, where pending is refused unconditionally.
+ *
+ * Pure: no provider, no I/O, no React. The engine calls it from `commit`.
+ */
+
+import { snapshotCertainty } from "../entitlements/aggregate.js";
+export const UNKNOWN_PENDING = {
+  status: 'unknown',
+  purchases: [],
+  isStale: false
+};
+
+/**
+ * Derives the pending set from the snapshot.
+ *
+ * Read from the persisted record, so it survives an app kill and an offline
+ * restart, and judged by the very staleness rule entitlements use (FR-103).
+ * Products no longer in the catalog are left out: an app cannot render a row,
+ * or withhold a Buy button, for a product key it no longer has.
+ */
+export function derivePending(input) {
+  const {
+    config,
+    snapshot
+  } = input;
+  const {
+    isStale,
+    undetermined
+  } = snapshotCertainty(input);
+  const earliest = new Map();
+  for (const purchase of snapshot.purchases) {
+    if (purchase.state !== 'pending' || !config.entries.has(purchase.productKey)) {
+      continue;
+    }
+    const known = earliest.get(purchase.productKey);
+    if (known === undefined || purchase.purchasedAt < known) {
+      earliest.set(purchase.productKey, purchase.purchasedAt);
+    }
+  }
+  const purchases = [...earliest].map(([productKey, since]) => ({
+    productKey,
+    since
+  })).sort((a, b) => a.since - b.since || a.productKey.localeCompare(b.productKey));
+  return {
+    status: undetermined ? 'unknown' : 'known',
+    purchases,
+    isStale
+  };
+}
+/**
+ * Every pending transaction that stopped being pending between two snapshots.
+ *
+ * Computed from the commit itself rather than at each call site that might end
+ * a pending purchase — sync, a store push, a purchase — which is what makes
+ * "exactly once" structural (FR-104, FR-079). A store push and a sync racing on
+ * one settling purchase both commit, but only the first commit sees it leave
+ * the pending set.
+ *
+ * A record that disappeared ended without payment. Why is the store's to say;
+ * when it says nothing, `cancelled` (see `PendingResolution`).
+ */
+export function pendingTransitions(previous, next, config, endReason) {
+  const transitions = [];
+  for (const before of previous.purchases) {
+    if (before.state !== 'pending' || !config.entries.has(before.productKey)) {
+      continue;
+    }
+    const after = next.purchases.find(p => p.transactionId === before.transactionId);
+    if (after?.state === 'pending') {
+      continue;
+    }
+    transitions.push({
+      productKey: before.productKey,
+      outcome: after ? 'settled' : endReason(before.transactionId) ?? 'cancelled'
+    });
+  }
+  return transitions;
+}
+
+/** Whether a listener has anything new to hear. */
+export function samePending(a, b) {
+  return a.status === b.status && a.isStale === b.isStale && a.purchases.length === b.purchases.length && a.purchases.every((purchase, index) => purchase.productKey === b.purchases[index].productKey && purchase.since === b.purchases[index].since);
+}
+//# sourceMappingURL=pending.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["snapshotCertainty","UNKNOWN_PENDING","status","purchases","isStale","derivePending","input","config","snapshot","undetermined","earliest","Map","purchase","state","entries","has","productKey","known","get","undefined","purchasedAt","set","map","since","sort","a","b","localeCompare","pendingTransitions","previous","next","endReason","transitions","before","after","find","p","transactionId","push","outcome","samePending","length","every","index"],"sourceRoot":"../../../src","sources":["engine/pending.ts"],"mappings":"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","ignoreList":[]}