@chipmobilesdk/rn-payment 0.6.0 → 0.7.0

package/lib/module/engine/purchaseFailure.js

@@ -0,0 +1,72 @@
+"use strict";
+
+/**
+ * What a refused purchase means to the app (PAY-19).
+ *
+ * The store answers with a reason of its own; this turns it into the result the
+ * app sees, under the code it can branch on, so no store vocabulary leaks out.
+ * Split from the flow next door, which is about the sequence of calls.
+ */
+
+export const FAILURE_CODES = {
+  network_error: 'PAYMENT_NETWORK_ERROR',
+  unknown_product: 'PAYMENT_UNKNOWN_PRODUCT',
+  ineligible: 'PAYMENT_INELIGIBLE',
+  product_unavailable_in_region: 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
+};
+
+/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
+export function mapFailure(reason, productKey, status) {
+  switch (reason) {
+    case 'user_cancelled':
+      return {
+        kind: 'user_cancelled',
+        productKey
+      };
+    case 'already_owned':
+      return {
+        kind: 'already_owned',
+        productKey
+      };
+    case 'ineligible':
+      return {
+        kind: 'ineligible',
+        productKey
+      };
+    case 'unknown_product':
+      return {
+        kind: 'unknown_product',
+        productKey
+      };
+    case 'product_unavailable_in_region':
+      return {
+        kind: 'product_unavailable_in_region',
+        productKey
+      };
+    case 'not_ready':
+      // The engine's real status, not a guess (PAY-19).
+      return {
+        kind: 'not_ready',
+        status
+      };
+    case 'network_error':
+      return {
+        kind: 'network_error',
+        productKey
+      };
+    case 'timeout':
+      return {
+        kind: 'timeout',
+        productKey
+      };
+    case 'store_error':
+      return {
+        kind: 'store_error',
+        productKey,
+        code: 'PAYMENT_STORE_ERROR'
+      };
+  }
+}
+
+/** Plan-change parameters, which only `subscriptions.ts` supplies. */
+//# sourceMappingURL=purchaseFailure.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["FAILURE_CODES","network_error","unknown_product","ineligible","product_unavailable_in_region","mapFailure","reason","productKey","status","kind","code"],"sourceRoot":"../../../src","sources":["engine/purchaseFailure.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,OAAO,MAAMA,aAAwE,GAAG;EACvFC,aAAa,EAAE,uBAAuB;EACtCC,eAAe,EAAE,yBAAyB;EAC1CC,UAAU,EAAE,oBAAoB;EAChCC,6BAA6B,EAAE;AAChC,CAAC;;AAED;AACA,OAAO,SAASC,UAAUA,CACzBC,MAA6B,EAC7BC,UAAsB,EACtBC,MAAyB,EACR;EACjB,QAAQF,MAAM;IACb,KAAK,gBAAgB;MACpB,OAAO;QAAEG,IAAI,EAAE,gBAAgB;QAAEF;MAAW,CAAC;IAC9C,KAAK,eAAe;MACnB,OAAO;QAAEE,IAAI,EAAE,eAAe;QAAEF;MAAW,CAAC;IAC7C,KAAK,YAAY;MAChB,OAAO;QAAEE,IAAI,EAAE,YAAY;QAAEF;MAAW,CAAC;IAC1C,KAAK,iBAAiB;MACrB,OAAO;QAAEE,IAAI,EAAE,iBAAiB;QAAEF;MAAW,CAAC;IAC/C,KAAK,+BAA+B;MACnC,OAAO;QAAEE,IAAI,EAAE,+BAA+B;QAAEF;MAAW,CAAC;IAC7D,KAAK,WAAW;MACf;MACA,OAAO;QAAEE,IAAI,EAAE,WAAW;QAAED;MAAO,CAAC;IACrC,KAAK,eAAe;MACnB,OAAO;QAAEC,IAAI,EAAE,eAAe;QAAEF;MAAW,CAAC;IAC7C,KAAK,SAAS;MACb,OAAO;QAAEE,IAAI,EAAE,SAAS;QAAEF;MAAW,CAAC;IACvC,KAAK,aAAa;MACjB,OAAO;QAAEE,IAAI,EAAE,aAAa;QAAEF,UAAU;QAAEG,IAAI,EAAE;MAAsB,CAAC;EACzE;AACD;;AAEA","ignoreList":[]}

package/lib/module/engine/receiptValidation.js

@@ -0,0 +1,87 @@
+"use strict";
+
+/**
+ * Asking the app's backend whether a purchase is real (FR-069a, FR-072b).
+ *
+ * The hook is optional and bounded by a timeout, and its answer decides whether
+ * an entitlement is granted — so what happens when it throws, times out, or is
+ * absent is the whole point of this module. Split from the flow next door,
+ * which is about the sequence of store calls.
+ *
+ * A hook that could not answer is never an implicit approval: the configured
+ * `onValidationUnavailable` decides, and the default refuses.
+ */
+
+import { withTimeout } from "../core/mutex.js";
+import { PaymentError } from "../diagnostics/errors.js";
+
+/** What the backend decided about one purchase. */
+
+export function createReceiptValidation(deps) {
+  const {
+    resolved
+  } = deps;
+  const askHook = (hook, candidate) => withTimeout(hook(candidate), resolved.timeouts.validateMs, () => new PaymentError({
+    code: 'PAYMENT_VALIDATION_UNAVAILABLE',
+    message: 'The validation hook did not answer in time',
+    operation: 'validate',
+    retryable: true
+  }));
+
+  /**
+   * Runs the app's backend check, if configured.
+   *
+   * Called for newly completed purchases only (FR-069a) — sync and restore trust
+   * a decision already made, which is what keeps restore working while the
+   * backend is unreachable.
+   */
+  const validate = async (purchase, productKey, correlationId) => {
+    const hook = deps.config.validateTransaction;
+    if (!hook) {
+      return {
+        outcome: 'approved'
+      };
+    }
+    const entry = resolved.entries.get(productKey);
+    try {
+      const decision = await askHook(hook, {
+        productKey,
+        productType: entry?.productType ?? 'one_time_permanent',
+        verificationPayload: purchase.verificationPayload ?? '',
+        correlationId,
+        transactionId: purchase.transactionId,
+        platform: deps.platform
+      });
+      deps.emit({
+        type: 'validation_decided',
+        productKey,
+        decision: decision.approved ? 'approved' : 'rejected'
+      });
+      return decision.approved ? {
+        outcome: 'approved'
+      } : {
+        outcome: 'rejected',
+        reason: decision.reason
+      };
+    } catch {
+      // A hook that throws is unavailable, never an implicit approval (FR-072b).
+      const fallback = resolved.onValidationUnavailable;
+      deps.emit({
+        type: 'validation_unavailable',
+        productKey,
+        fallback
+      });
+      return fallback === 'grant_and_queue' ? {
+        outcome: 'granted_pending_revalidation'
+      } : {
+        outcome: 'rejected',
+        reason: 'validation_unavailable'
+      };
+    }
+  };
+  return {
+    askHook,
+    validate
+  };
+}
+//# sourceMappingURL=receiptValidation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["withTimeout","PaymentError","createReceiptValidation","deps","resolved","askHook","hook","candidate","timeouts","validateMs","code","message","operation","retryable","validate","purchase","productKey","correlationId","config","validateTransaction","outcome","entry","entries","get","decision","productType","verificationPayload","transactionId","platform","emit","type","approved","reason","fallback","onValidationUnavailable"],"sourceRoot":"../../../src","sources":["engine/receiptValidation.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,SAASA,WAAW,QAAQ,kBAAe;AAC3C,SAASC,YAAY,QAAQ,0BAAuB;;AASpD;;AAMA,OAAO,SAASC,uBAAuBA,CAACC,IAA2B,EAAE;EACpE,MAAM;IAAEC;EAAS,CAAC,GAAGD,IAAI;EAEzB,MAAME,OAAO,GAAGA,CACfC,IAAuD,EACvDC,SAA2E,KAE3EP,WAAW,CACVM,IAAI,CAACC,SAAS,CAAC,EACfH,QAAQ,CAACI,QAAQ,CAACC,UAAU,EAC5B,MACC,IAAIR,YAAY,CAAC;IAChBS,IAAI,EAAE,gCAAgC;IACtCC,OAAO,EAAE,4CAA4C;IACrDC,SAAS,EAAE,UAAU;IACrBC,SAAS,EAAE;EACZ,CAAC,CACH,CAAC;;EAEF;AACD;AACA;AACA;AACA;AACA;AACA;EACC,MAAMC,QAAQ,GAAG,MAAAA,CAChBC,QAA0B,EAC1BC,UAAsB,EACtBC,aAAqB,KAKjB;IACJ,MAAMX,IAAI,GAAGH,IAAI,CAACe,MAAM,CAACC,mBAAmB;IAC5C,IAAI,CAACb,IAAI,EAAE;MACV,OAAO;QAAEc,OAAO,EAAE;MAAW,CAAC;IAC/B;IAEA,MAAMC,KAAK,GAAGjB,QAAQ,CAACkB,OAAO,CAACC,GAAG,CAACP,UAAU,CAAC;IAC9C,IAAI;MACH,MAAMQ,QAAQ,GAAG,MAAMnB,OAAO,CAACC,IAAI,EAAE;QACpCU,UAAU;QACVS,WAAW,EAAEJ,KAAK,EAAEI,WAAW,IAAI,oBAAoB;QACvDC,mBAAmB,EAAEX,QAAQ,CAACW,mBAAmB,IAAI,EAAE;QACvDT,aAAa;QACbU,aAAa,EAAEZ,QAAQ,CAACY,aAAa;QACrCC,QAAQ,EAAEzB,IAAI,CAACyB;MAChB,CAAC,CAAC;MACFzB,IAAI,CAAC0B,IAAI,CAAC;QACTC,IAAI,EAAE,oBAAoB;QAC1Bd,UAAU;QACVQ,QAAQ,EAAEA,QAAQ,CAACO,QAAQ,GAAG,UAAU,GAAG;MAC5C,CAAC,CAAC;MACF,OAAOP,QAAQ,CAACO,QAAQ,GACrB;QAAEX,OAAO,EAAE;MAAW,CAAC,GACvB;QAAEA,OAAO,EAAE,UAAU;QAAEY,MAAM,EAAER,QAAQ,CAACQ;MAAO,CAAC;IACpD,CAAC,CAAC,MAAM;MACP;MACA,MAAMC,QAAQ,GAAG7B,QAAQ,CAAC8B,uBAAuB;MACjD/B,IAAI,CAAC0B,IAAI,CAAC;QAAEC,IAAI,EAAE,wBAAwB;QAAEd,UAAU;QAAEiB;MAAS,CAAC,CAAC;MACnE,OAAOA,QAAQ,KAAK,iBAAiB,GAClC;QAAEb,OAAO,EAAE;MAA+B,CAAC,GAC3C;QAAEA,OAAO,EAAE,UAAU;QAAEY,MAAM,EAAE;MAAyB,CAAC;IAC7D;EACD,CAAC;EAED,OAAO;IAAE3B,OAAO;IAAES;EAAS,CAAC;AAC7B","ignoreList":[]}

package/lib/module/engine/state.js

@@ -0,0 +1,196 @@
+"use strict";
+
+/**
+ * The engine's state and the one way it changes (PAY-10).
+ *
+ * Status, the persisted snapshot, entitlements and pending purchases live here
+ * with the listeners that hear about them. Every change goes through `commit`
+ * (the snapshot) or `setStatus`, so diffing and emission are written once:
+ * an entitlement is granted or revoked exactly once however many sources it has
+ * (FR-079), a renewal that changes nothing emits nothing (FR-068), and an
+ * unchanged map is the same object (PERF-03).
+ */
+import { createListenerSet } from '@chipmobilesdk/rn-core';
+import { redact } from "../diagnostics/errors.js";
+import { createEmitter } from "../diagnostics/events.js";
+import { aggregate, diffEntitlements, initialEntitlements, shareUnchanged } from "../entitlements/aggregate.js";
+import { emptySnapshot } from "../persistence/snapshot.js";
+import { derivePending, pendingTransitions, samePending, UNKNOWN_PENDING } from "./pending.js";
+export function createEngineState(config, resolved, provider, store, now) {
+  // A listener that throws is a consumer bug, so it goes to the app's own logger
+  // rather than back into the event stream (FR-080, FR-081).
+  const emitter = createEmitter((error, event) => {
+    config.logger?.error?.('payment event listener threw', {
+      eventType: event.type,
+      reason: redact(error)
+    });
+  });
+  const listenerOptions = {
+    onListenerError: error => config.logger?.error?.('payment listener threw', {
+      reason: redact(error)
+    })
+  };
+
+  /**
+   * Why an entitlement that was held is held no more, from what its sources left
+   * behind (PAY-12): a backend rejection, a consumed item, an expired
+   * subscription — or, when the store simply stopped reporting it, a refund.
+   */
+  function revokeReason(sources) {
+    const records = state.snapshot.purchases.filter(record => sources.includes(record.productKey));
+    if (records.some(record => record.validationState === 'rejected')) {
+      return 'validation_rejected';
+    }
+    if (records.some(record => record.state === 'consumed')) {
+      return 'consumed';
+    }
+    const at = now();
+    if (records.some(record => record.expiresAt !== undefined && record.expiresAt <= at)) {
+      return 'expired';
+    }
+    return 'revoked_by_store';
+  }
+  function publishPending(next) {
+    // Diffed: a sync that changes nothing is the common case, and an app
+    // rendering "payment pending" has no use for a re-render that says the same.
+    if (samePending(state.pending, next)) {
+      return;
+    }
+    state.pending = next;
+    state.pendingListeners.notify(next);
+  }
+  function recompute() {
+    if (state.disposed) {
+      return;
+    }
+    const previous = state.entitlements;
+    state.entitlements = shareUnchanged(previous, aggregate({
+      config: resolved,
+      snapshot: state.snapshot,
+      hasSynced: state.hasSynced,
+      reportsGraceAndHoldDistinctly: provider.capabilities().reportsGraceAndHoldDistinctly,
+      now: now()
+    }));
+    for (const change of diffEntitlements(previous, state.entitlements)) {
+      if (change.next === 'entitled') {
+        state.emit({
+          type: 'entitlement_granted',
+          entitlementKey: change.key,
+          sources: change.sources
+        });
+      } else if (change.previous === 'entitled') {
+        state.emit({
+          type: 'entitlement_revoked',
+          entitlementKey: change.key,
+          reason: revokeReason(previous[change.key]?.sources ?? [])
+        });
+      }
+    }
+    if (state.entitlements !== previous) {
+      state.entitlementListeners.notify(state.entitlements);
+    }
+    publishPending(derivePending({
+      config: resolved,
+      snapshot: state.snapshot,
+      hasSynced: state.hasSynced,
+      now: now()
+    }));
+  }
+  const state = {
+    config,
+    resolved,
+    provider,
+    store,
+    now,
+    emitter,
+    statusListeners: createListenerSet(listenerOptions),
+    entitlementListeners: createListenerSet(listenerOptions),
+    pendingListeners: createListenerSet(listenerOptions),
+    disposed: false,
+    hasSynced: false,
+    snapshot: emptySnapshot(config.scopeToken),
+    entitlements: initialEntitlements(resolved),
+    status: {
+      kind: resolved.enabled ? 'not_started' : 'disabled',
+      blockedOperations: []
+    },
+    pending: UNKNOWN_PENDING,
+    emit(event) {
+      emitter.emit({
+        ...event,
+        timestamp: event.timestamp ?? now()
+      });
+    },
+    setStatus(next) {
+      if (state.disposed) {
+        return;
+      }
+      state.status = {
+        ...state.status,
+        ...next
+      };
+      state.emit({
+        type: 'initialization',
+        status: state.status.kind,
+        unavailableReason: state.status.unavailableReason,
+        retryable: state.status.retryable
+      });
+      state.statusListeners.notify(state.status);
+    },
+    commit(next) {
+      // Read before the swap: a transition is "pending before, not pending now",
+      // and only the commit sees both sides (FR-104).
+      const ended = pendingTransitions(state.snapshot, next, resolved, transactionId => provider.pendingEndReason?.(transactionId));
+      state.snapshot = next;
+      if (store.save(next) === false) {
+        // The write-intent-first guarantee (FR-042) did not hold for this write.
+        // Said out loud: the app learns its finalize queue may not survive a kill.
+        state.emit({
+          type: 'internal_error',
+          code: 'PAYMENT_STORAGE_UNAVAILABLE',
+          operation: 'persist'
+        });
+      }
+      // Before `recompute`, so `settled` precedes the `entitlement_granted` it
+      // causes (FR-102).
+      for (const transition of ended) {
+        state.emit({
+          type: 'purchase_pending_resolved',
+          productKey: transition.productKey,
+          outcome: transition.outcome
+        });
+      }
+      recompute();
+    },
+    hydrate() {
+      state.snapshot = store.load(config.scopeToken);
+      // A record with `lastSyncedAt` was written by a sync that succeeded, so it
+      // is a basis for asserting entitlement — and the only one a build with
+      // selling disabled will ever have (FR-012, FR-053).
+      if (state.snapshot.lastSyncedAt !== undefined) {
+        state.hasSynced = true;
+      }
+      if (!store.isDurable()) {
+        state.emit({
+          type: 'config_warning',
+          detail: 'Local storage unavailable; entitlements will not survive restart'
+        });
+      }
+      recompute();
+    },
+    forget() {
+      store.clearAll();
+      state.snapshot = emptySnapshot(config.scopeToken);
+      state.hasSynced = false;
+      // Back to `unknown`, not `not_entitled`: after a logout there is no basis
+      // for either claim until the next sync.
+      state.entitlements = initialEntitlements(resolved);
+      state.entitlementListeners.notify(state.entitlements);
+      // No `purchase_pending_resolved`: the records were discarded locally, not
+      // ended at the store.
+      publishPending(UNKNOWN_PENDING);
+    }
+  };
+  return state;
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["createListenerSet","redact","createEmitter","aggregate","diffEntitlements","initialEntitlements","shareUnchanged","emptySnapshot","derivePending","pendingTransitions","samePending","UNKNOWN_PENDING","createEngineState","config","resolved","provider","store","now","emitter","error","event","logger","eventType","type","reason","listenerOptions","onListenerError","revokeReason","sources","records","state","snapshot","purchases","filter","record","includes","productKey","some","validationState","at","expiresAt","undefined","publishPending","next","pending","pendingListeners","notify","recompute","disposed","previous","entitlements","hasSynced","reportsGraceAndHoldDistinctly","capabilities","change","emit","entitlementKey","key","entitlementListeners","statusListeners","scopeToken","status","kind","enabled","blockedOperations","timestamp","setStatus","unavailableReason","retryable","commit","ended","transactionId","pendingEndReason","save","code","operation","transition","outcome","hydrate","load","lastSyncedAt","isDurable","detail","forget","clearAll"],"sourceRoot":"../../../src","sources":["engine/state.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/engine/subscriptions.js

@@ -0,0 +1,119 @@
+"use strict";
+
+/**
+ * Subscription plan changes and the route to the store's management screen (US12).
+ *
+ * Two platform rules drive this module:
+ *
+ * - **Proration is the app's decision, inside what the store permits** (FR-065).
+ *   Whether a user who upgrades gets charged immediately, keeps their remaining
+ *   time, or starts a fresh period is a product and pricing choice, so the
+ *   package forwards it rather than picking.
+ * - **Cancellation belongs to the store.** Platforms forbid an app presenting its
+ *   own cancellation screen, so this module offers only a route to the store's
+ *   (FR-066) — there is deliberately no self-built alternative anywhere in the
+ *   package.
+ */
+
+import { storeIdForProductKey } from "../entitlements/mapping.js";
+
+/**
+ * How already-paid time is handled when a plan changes.
+ *
+ * Named for the user-visible effect rather than mirroring a store's enum, so the
+ * same vocabulary will map onto StoreKit later (FR-004).
+ */
+
+/** Store-specific replacement codes stay here, behind the neutral vocabulary above. */
+const PRORATION_CODES = {
+  immediate_with_time_proration: 'WITH_TIME_PRORATION',
+  immediate_and_charge_full_price: 'CHARGE_FULL_PRICE',
+  immediate_and_charge_prorated_price: 'CHARGE_PRORATED_PRICE',
+  deferred: 'DEFERRED'
+};
+export function createSubscriptions(deps) {
+  const {
+    resolved
+  } = deps;
+  return {
+    async changePlan(fromProductKey, toProductKey, mode, options) {
+      if (!deps.provider.capabilities().supportsPlanChange) {
+        return {
+          kind: 'unsupported'
+        };
+      }
+      const target = resolved.entries.get(toProductKey);
+      if (!target) {
+        return {
+          kind: 'unknown_product',
+          productKey: toProductKey
+        };
+      }
+      if (!resolved.entries.has(fromProductKey)) {
+        return {
+          kind: 'unknown_product',
+          productKey: fromProductKey
+        };
+      }
+
+      // The store needs the *token* of the subscription being replaced, not its
+      // product id — that is how it knows which active purchase to migrate, and
+      // it is why a plan change needs a live local record rather than just two
+      // product keys.
+      const active = deps.snapshot().purchases.find(p => p.productKey === fromProductKey && p.productType === 'subscription' && p.state === 'purchased');
+      if (!active) {
+        // No subscription to replace. Treated as a plain purchase would be
+        // surprising — the caller asked to *change* something that is not there,
+        // which almost always means its own state is stale.
+        return {
+          kind: 'already_owned',
+          productKey: fromProductKey
+        };
+      }
+
+      // Routed through the normal purchase flow on purpose: a plan change is a
+      // purchase, so it must inherit the single-flight lock, the environment
+      // guard, validation, and the finalization queue rather than reimplementing
+      // any of them.
+      return deps.purchase(toProductKey, {
+        ...options,
+        replaceProductKey: fromProductKey,
+        prorationMode: PRORATION_CODES[mode]
+      });
+    },
+    async openManagement(productKey) {
+      const storeProductId = productKey ? storeIdForProductKey(resolved, productKey) : undefined;
+      // No-ops rather than throwing where the platform has no such screen: this
+      // is wired to a button, and a button that crashes is worse than one that
+      // does nothing on a platform that cannot honour it.
+      await deps.provider.openSubscriptionManagement(storeProductId);
+    },
+    async confirmPriceChange(productKey) {
+      if (!deps.provider.capabilities().supportsPriceChangeConfirmation) {
+        return {
+          kind: 'unsupported'
+        };
+      }
+      const storeProductId = storeIdForProductKey(resolved, productKey);
+      if (!storeProductId) {
+        return {
+          kind: 'failed',
+          code: 'PAYMENT_UNKNOWN_PRODUCT'
+        };
+      }
+      const outcome = await deps.provider.confirmPriceChange(storeProductId);
+      if (!outcome.ok) {
+        return {
+          kind: 'failed',
+          code: 'PAYMENT_STORE_ERROR'
+        };
+      }
+      return outcome.confirmed ? {
+        kind: 'confirmed'
+      } : {
+        kind: 'dismissed'
+      };
+    }
+  };
+}
+//# sourceMappingURL=subscriptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["storeIdForProductKey","PRORATION_CODES","immediate_with_time_proration","immediate_and_charge_full_price","immediate_and_charge_prorated_price","deferred","createSubscriptions","deps","resolved","changePlan","fromProductKey","toProductKey","mode","options","provider","capabilities","supportsPlanChange","kind","target","entries","get","productKey","has","active","snapshot","purchases","find","p","productType","state","purchase","replaceProductKey","prorationMode","openManagement","storeProductId","undefined","openSubscriptionManagement","confirmPriceChange","supportsPriceChangeConfirmation","code","outcome","ok","confirmed"],"sourceRoot":"../../../src","sources":["engine/subscriptions.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/engine/sync.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * Syncing with the store, and the one translation from a store purchase to a
+ * persisted record (PAY-10).
+ *
+ * The purchase flow and sync both build records here, so they cannot disagree
+ * about what a transaction still owes: a disagreement is how a paid purchase
+ * goes unacknowledged and is refunded three days later.
+ */
+
+import { PaymentError } from "../diagnostics/errors.js";
+import { productKeyForStoreId } from "../entitlements/mapping.js";
+import { createRateLimiter, createSingleFlight, withTimeout } from "../core/mutex.js";
+import { resolveFinalizeState } from "../persistence/snapshot.js";
+/** The persisted record for one store purchase, keeping what we already knew about it. */
+export function toPersistedRecord(resolved, purchase, productKey, existing) {
+  return {
+    transactionId: purchase.transactionId,
+    productKey,
+    productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
+    token: purchase.token,
+    state: purchase.state === 'pending' ? 'pending' : 'purchased',
+    purchasedAt: purchase.purchasedAt,
+    // Finalize progress survives: a sync must never reset a queued
+    // acknowledgement and lose the paid transaction.
+    finalizeState: resolveFinalizeState(purchase, existing),
+    attempts: existing?.attempts ?? 0,
+    validationState: existing?.validationState ?? 'not_required',
+    expiresAt: purchase.expiresAt,
+    willAutoRenew: purchase.willAutoRenew
+  };
+}
+
+/** Store purchases as records, dropping products this catalog does not know. */
+function toPersisted(resolved, purchases, known) {
+  const records = [];
+  for (const purchase of purchases) {
+    // Legitimately possible: a user owns something from a build whose catalog
+    // has since changed. Ignored rather than treated as impossible.
+    const productKey = productKeyForStoreId(resolved, purchase.storeProductId);
+    if (!productKey || !resolved.entries.has(productKey)) {
+      continue;
+    }
+    const existing = known.find(p => p.transactionId === purchase.transactionId);
+    if (purchase.state === 'unspecified') {
+      // No basis for granting, finalizing or ending anything: a new transaction
+      // waits until the store says what it is, a known one keeps what we knew.
+      if (existing) {
+        records.push(existing);
+      }
+      continue;
+    }
+    records.push(toPersistedRecord(resolved, purchase, productKey, existing));
+  }
+  return records;
+}
+function purchasedIds(records) {
+  return new Set(records.filter(p => p.state === 'purchased').map(p => p.transactionId));
+}
+/**
+ * `settle` runs after every successful sync, outside the sync flight: the finalize
+ * drain and backend revalidation (FR-039, FR-042, FR-072a). Inside the flight, one
+ * store call or hook that never answered held it, and every later sync joined
+ * that stuck promise for the rest of the session.
+ */
+export function createSync(state, settle) {
+  const {
+    resolved,
+    provider,
+    now
+  } = state;
+  const syncFlight = createSingleFlight();
+  const settleFlight = createSingleFlight();
+  const foregroundLimiter = createRateLimiter(resolved.foregroundSyncMinIntervalMs, now);
+  async function querySnapshot(trigger) {
+    try {
+      const owned = await withTimeout(provider.queryOwned(), resolved.timeouts.syncMs, () => new PaymentError({
+        code: 'PAYMENT_TIMEOUT',
+        message: 'Syncing entitlements timed out',
+        operation: 'sync',
+        retryable: true
+      }));
+      const before = purchasedIds(state.snapshot.purchases);
+      const records = toPersisted(resolved, owned, state.snapshot.purchases);
+      const after = purchasedIds(records);
+      // A transaction the store no longer reports is revoked — a refund. The
+      // cache must not resurrect it (FR-064, FR-055).
+      const revokedCount = [...before].filter(id => !after.has(id)).length;
+      const restoredCount = [...after].filter(id => !before.has(id)).length;
+      state.hasSynced = true;
+      state.commit({
+        ...state.snapshot,
+        purchases: records,
+        lastSyncedAt: now()
+      });
+      state.emit({
+        type: 'sync_completed',
+        restoredCount,
+        revokedCount,
+        trigger
+      });
+      return {
+        ok: true,
+        restoredCount,
+        revokedCount
+      };
+    } catch (error) {
+      const paymentError = error instanceof PaymentError ? error : new PaymentError({
+        code: 'PAYMENT_STORE_ERROR',
+        message: 'Sync failed',
+        operation: 'sync',
+        retryable: true
+      });
+      // A failed sync leaves the previous snapshot in place, so offline
+      // entitlements survive rather than being wiped (FR-053).
+      state.emit({
+        type: 'internal_error',
+        code: paymentError.code,
+        operation: 'sync'
+      });
+      return {
+        ok: false,
+        error: paymentError
+      };
+    }
+  }
+  return {
+    async sync(trigger = 'manual') {
+      if (state.disposed || !resolved.enabled) {
+        return {
+          ok: false,
+          error: new PaymentError({
+            code: 'PAYMENT_DISABLED',
+            message: 'Payments are disabled',
+            operation: 'sync'
+          })
+        };
+      }
+      // Rejected rather than deferred: the next foreground event tries again,
+      // whereas queueing would fire a burst once the interval elapsed (PERF-002).
+      if (trigger === 'foreground' && !foregroundLimiter.tryAcquire()) {
+        return {
+          ok: true,
+          restoredCount: 0,
+          revokedCount: 0
+        };
+      }
+      // Concurrent callers join one flight: one store request (FR-063).
+      const outcome = await syncFlight.run(() => querySnapshot(trigger));
+      if (outcome.ok) {
+        await settleFlight.run(settle);
+      }
+      return outcome;
+    }
+  };
+}
+//# sourceMappingURL=sync.js.map