@chipmobilesdk/rn-payment 0.5.0 → 0.7.0

package/lib/commonjs/entitlements/aggregate.js

@@ -0,0 +1,212 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.aggregate = aggregate;
+exports.diffEntitlements = diffEntitlements;
+exports.initialEntitlements = initialEntitlements;
+exports.shareUnchanged = shareUnchanged;
+exports.snapshotCertainty = snapshotCertainty;
+var _rnCore = require("@chipmobilesdk/rn-core");
+var _mapping = require("./mapping.js");
+var _policy = require("./policy.js");
+/**
+ * Entitlement aggregation — the package's primary output.
+ *
+ * Everything else exists to make this one answer correct. The most damaging
+ * defect class in a payment SDK lives here: collapsing "not yet synced" into "not
+ * entitled" makes a paying user watch ads flash on cold start or see a purchased
+ * feature sit locked.
+ *
+ * Two rules do most of the work:
+ *
+ * - **A pending purchase is never a source** (FR-037). Enforced here, in
+ *   aggregation, rather than at each call site, so no future code path can grant
+ *   on money that has not arrived.
+ * - **Uncertainty resolves to `unknown`, never `not_entitled`** (FR-047,
+ *   FR-055a). Never synced, stale, or scope-changed all mean "we do not know",
+ *   and the package says so rather than asserting the user did not pay.
+ */
+
+/** A purchase that currently confers its entitlements. */
+function isValidSource(purchase, input) {
+  // Only a purchase the store confirmed grants. Pending money is not money, and a
+  // state this version does not know is no basis for a grant either (PAY-13).
+  if (purchase.state !== 'purchased') {
+    return false;
+  }
+  // A backend that said no is final (FR-071). A queued re-validation still
+  // grants, which is the documented `grant_and_queue` fallback (FR-072).
+  if (purchase.validationState === 'rejected') {
+    return false;
+  }
+  if (purchase.productType === 'subscription') {
+    if ((0, _policy.hasExpired)(purchase.expiresAt, input.now)) {
+      return false;
+    }
+    const renewalState = (0, _policy.deriveRenewalState)({
+      expiresAt: purchase.expiresAt,
+      willAutoRenew: purchase.willAutoRenew,
+      reportsGraceAndHoldDistinctly: input.reportsGraceAndHoldDistinctly
+    });
+    return (0, _policy.grantsUnderPolicy)(renewalState, {
+      gracePolicy: input.config.gracePolicy,
+      holdPolicy: input.config.holdPolicy
+    });
+  }
+
+  // A consumable that has not been consumed yet is owned, but it must never
+  // become a permanent entitlement — consumption flips it to `consumed` above.
+  return true;
+}
+function subscriptionDetailFor(purchases, input) {
+  const subs = purchases.filter(p => p.productType === 'subscription');
+  if (subs.length === 0) {
+    return undefined;
+  }
+
+  // Where several subscriptions grant one entitlement, the one running longest
+  // is what the user experiences, so report that one.
+  const furthest = subs.reduce((best, candidate) => {
+    const bestAt = best.expiresAt ?? Number.MAX_SAFE_INTEGER;
+    const candidateAt = candidate.expiresAt ?? Number.MAX_SAFE_INTEGER;
+    return candidateAt > bestAt ? candidate : best;
+  });
+  const renewalState = (0, _policy.deriveRenewalState)({
+    expiresAt: furthest.expiresAt,
+    willAutoRenew: furthest.willAutoRenew,
+    reportsGraceAndHoldDistinctly: input.reportsGraceAndHoldDistinctly
+  });
+  return {
+    expiresAt: furthest.expiresAt,
+    willAutoRenew: furthest.willAutoRenew === true,
+    isCancelledButValid: renewalState === 'cancelled_valid',
+    renewalState
+  };
+}
+
+/**
+ * Computes the full entitlement map.
+ *
+ * Pure and synchronous by design: it runs on render paths, so it must never
+ * touch I/O (PERF-001). The engine calls it after any state change and caches the
+ * result.
+ */
+/**
+ * How far the snapshot can be trusted right now.
+ *
+ * Shared by entitlements and the pending set (FR-103) so the two can never
+ * disagree about whether the package knows anything — a paywall that showed
+ * "not entitled" next to "nothing pending" from one stale snapshot would offer
+ * Buy to a user whose payment is in flight.
+ */
+function snapshotCertainty(input) {
+  const {
+    config,
+    snapshot,
+    hasSynced,
+    now
+  } = input;
+  const isStale = snapshot.lastSyncedAt !== undefined && now - snapshot.lastSyncedAt > config.staleAfterMs;
+
+  // Both roads lead to `unknown`, never to a confident "no". Never having synced
+  // and having synced too long ago are the same epistemic state: we cannot
+  // currently support a claim either way.
+  return {
+    isStale,
+    undetermined: !hasSynced || isStale
+  };
+}
+function aggregate(input) {
+  const {
+    config,
+    snapshot
+  } = input;
+  const {
+    isStale,
+    undetermined
+  } = snapshotCertainty(input);
+  const valid = snapshot.purchases.filter(p => isValidSource(p, input));
+  const result = {};
+  for (const key of config.entitlementKeys) {
+    const granting = valid.filter(p => (0, _mapping.entitlementsFor)(config, p.productKey).includes(key));
+    const sources = [...new Set(granting.map(p => p.productKey))];
+    result[key] = {
+      key,
+      // An entitlement stays valid while at least one source remains (FR-052).
+      status: undetermined ? 'unknown' : sources.length > 0 ? 'entitled' : 'not_entitled',
+      sources,
+      subscription: subscriptionDetailFor(granting, input),
+      lastSyncedAt: snapshot.lastSyncedAt,
+      isStale
+    };
+  }
+  return result;
+}
+
+/** The initial map, before anything is known. Every key starts at `unknown` (FR-047). */
+function initialEntitlements(config) {
+  const result = {};
+  for (const key of config.entitlementKeys) {
+    result[key] = {
+      key,
+      status: 'unknown',
+      sources: [],
+      lastSyncedAt: undefined,
+      isStale: false
+    };
+  }
+  return result;
+}
+/**
+ * Diffs two maps to produce change signals.
+ *
+ * Emitting from a diff rather than from grant call sites is what makes the
+ * exactly-once guarantees structural (FR-079): a successful subscription renewal
+ * changes no status, so it produces no event and cannot double-signal (FR-068);
+ * and an entitlement with three sources fires once on transition, not once per
+ * source.
+ */
+function diffEntitlements(previous, next) {
+  const changes = [];
+  for (const key of Object.keys(next)) {
+    const before = previous[key]?.status ?? 'unknown';
+    const after = next[key].status;
+    if (before !== after) {
+      changes.push({
+        key,
+        previous: before,
+        next: after,
+        sources: next[key].sources
+      });
+    }
+  }
+  return changes;
+}
+function sameEntitlement(a, b) {
+  return a.status === b.status && a.isStale === b.isStale && a.lastSyncedAt === b.lastSyncedAt && a.sources.length === b.sources.length && a.sources.every((source, index) => source === b.sources[index]) && (0, _rnCore.shallowEqual)(a.subscription, b.subscription);
+}
+
+/**
+ * `next`, with every entitlement that did not change replaced by the object it
+ * replaces, and `previous` itself when nothing changed (PERF-03, PAY-08). A hook
+ * selecting one entitlement then sees the same object and does not re-render.
+ */
+function shareUnchanged(previous, next) {
+  const keys = Object.keys(next);
+  let changed = keys.length !== Object.keys(previous).length;
+  const shared = {};
+  for (const key of keys) {
+    const before = previous[key];
+    const after = next[key];
+    if (before && sameEntitlement(before, after)) {
+      shared[key] = before;
+    } else {
+      shared[key] = after;
+      changed = true;
+    }
+  }
+  return changed ? shared : previous;
+}
+//# sourceMappingURL=aggregate.js.map

package/lib/commonjs/entitlements/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","_mapping","_policy","isValidSource","purchase","input","state","validationState","productType","hasExpired","expiresAt","now","renewalState","deriveRenewalState","willAutoRenew","reportsGraceAndHoldDistinctly","grantsUnderPolicy","gracePolicy","config","holdPolicy","subscriptionDetailFor","purchases","subs","filter","p","length","undefined","furthest","reduce","best","candidate","bestAt","Number","MAX_SAFE_INTEGER","candidateAt","isCancelledButValid","snapshotCertainty","snapshot","hasSynced","isStale","lastSyncedAt","staleAfterMs","undetermined","aggregate","valid","result","key","entitlementKeys","granting","entitlementsFor","productKey","includes","sources","Set","map","status","subscription","initialEntitlements","diffEntitlements","previous","next","changes","Object","keys","before","after","push","sameEntitlement","a","b","every","source","index","shallowEqual","shareUnchanged","changed","shared"],"sourceRoot":"../../../src","sources":["entitlements/aggregate.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/entitlements/mapping.js

@@ -0,0 +1,41 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.entitlementsFor = entitlementsFor;
+exports.productKeyForStoreId = productKeyForStoreId;
+exports.storeIdForProductKey = storeIdForProductKey;
+/**
+ * Product ↔ entitlement indexing.
+ *
+ * The relation is many-to-many (FR-010): monthly, yearly, and lifetime products
+ * may all grant `no_ads`, and one bundle product may grant several entitlements.
+ *
+ * Both directions are indexed once at configure time. The reverse direction is
+ * what makes two requirements cheap on hot paths: naming which product currently
+ * grants an entitlement (FR-051), and keeping an entitlement valid while *any*
+ * source remains (FR-052).
+ */
+
+/** Entitlements a product confers. Empty for an unknown key rather than throwing. */
+function entitlementsFor(config, productKey) {
+  return config.grants.get(productKey) ?? [];
+}
+
+/**
+ * Translates a store product id back to the app's own product key.
+ *
+ * Needed because store callbacks and `queryOwned` speak in store ids, while
+ * everything above the adapter speaks in product keys (FR-003). Returns
+ * `undefined` for an id absent from the catalog — which happens legitimately when
+ * a user owns something from a build whose catalog has since changed, so it must
+ * be handled rather than treated as impossible.
+ */
+function productKeyForStoreId(config, storeProductId) {
+  return config.byStoreId.get(storeProductId);
+}
+function storeIdForProductKey(config, productKey) {
+  return config.entries.get(productKey)?.storeProductIds[config.platform];
+}
+//# sourceMappingURL=mapping.js.map

package/lib/commonjs/entitlements/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["entitlementsFor","config","productKey","grants","get","productKeyForStoreId","storeProductId","byStoreId","storeIdForProductKey","entries","storeProductIds","platform"],"sourceRoot":"../../../src","sources":["entitlements/mapping.ts"],"mappings":";;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA;AACO,SAASA,eAAeA,CAC9BC,MAAsB,EACtBC,UAAsB,EACM;EAC5B,OAAOD,MAAM,CAACE,MAAM,CAACC,GAAG,CAACF,UAAU,CAAC,IAAI,EAAE;AAC3C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,oBAAoBA,CACnCJ,MAAsB,EACtBK,cAAsB,EACG;EACzB,OAAOL,MAAM,CAACM,SAAS,CAACH,GAAG,CAACE,cAAc,CAAC;AAC5C;AAEO,SAASE,oBAAoBA,CACnCP,MAAsB,EACtBC,UAAsB,EACD;EACrB,OAAOD,MAAM,CAACQ,OAAO,CAACL,GAAG,CAACF,UAAU,CAAC,EAAEQ,eAAe,CAACT,MAAM,CAACU,QAAQ,CAAC;AACxE","ignoreList":[]}

package/lib/commonjs/entitlements/policy.js

@@ -0,0 +1,110 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.deriveRenewalState = deriveRenewalState;
+exports.grantsUnderPolicy = grantsUnderPolicy;
+exports.hasExpired = hasExpired;
+/**
+ * Grace and hold entitlement policy.
+ *
+ * This is a **business decision, not a technical constant** (FR-049), so it is
+ * configurable with documented defaults.
+ *
+ * ## The defaults, and why
+ *
+ * `gracePolicy: 'grant'` — a grace period means the store is still retrying a
+ * payment method that failed for reasons usually outside the user's control: an
+ * expired card, a bank decline, a temporary hold. Revoking immediately punishes a
+ * paying customer for a billing hiccup they may not know about yet.
+ *
+ * `holdPolicy: 'withhold'` — account hold means the store has given up retrying.
+ * The subscription is effectively unpaid, and continuing to serve paid features
+ * indefinitely is giving away the product.
+ *
+ * ## What Android can actually tell us
+ *
+ * Client-side Play Billing **cannot** separate grace from hold: a grace-period
+ * subscription is still returned as active, and one in account hold stops being
+ * returned at all — indistinguishable from expired, cancelled, or refunded.
+ *
+ * Fortunately the platform's own behavior matches the defaults above. Play keeps
+ * returning a grace-period purchase, so the entitlement holds. Play stops
+ * returning a held one, so it lapses at the next sync. **The default policy is
+ * therefore correct with no backend at all.**
+ *
+ * What is *not* achievable client-side is a non-default policy — withholding
+ * during grace, or granting during hold — because that needs the state the client
+ * cannot see. Such an app supplies it through the validation hook (FR-069). This
+ * limitation is documented rather than papered over (FR-058).
+ */
+
+/**
+ * A subscription's renewal state as far as the package can honestly tell.
+ *
+ * `indeterminate` is not a failure — it is the truthful answer when the platform
+ * reports a subscription as active but cannot say whether that is a healthy
+ * renewal, a cancelled-but-still-paid period, or a grace period.
+ */
+
+/**
+ * Derives the renewal state without inventing information.
+ *
+ * The temptation is to read `willAutoRenew === false` as "grace period", but that
+ * same value is what a deliberate cancellation looks like. Guessing would mean
+ * showing "there's a problem with your payment method" to someone who simply
+ * chose not to renew — so when the provider cannot distinguish, neither do we.
+ */
+function deriveRenewalState(facts) {
+  if (facts.reportsGraceAndHoldDistinctly && facts.providerRenewalState) {
+    switch (facts.providerRenewalState) {
+      case 'grace':
+        return 'grace';
+      case 'hold':
+        return 'hold';
+      case 'active':
+        return facts.willAutoRenew === false ? 'cancelled_valid' : 'active';
+    }
+  }
+  if (facts.willAutoRenew === false) {
+    // Still inside a paid period with auto-renew off. Genuinely ambiguous
+    // between "cancelled" and "in grace", so report the one that is certainly
+    // true — the period is paid for — and let the app decide how to present it.
+    return 'cancelled_valid';
+  }
+  if (facts.willAutoRenew === true) {
+    return 'active';
+  }
+  return 'indeterminate';
+}
+
+/**
+ * Whether a subscription in this state should confer its entitlement.
+ *
+ * `hold` reaching this function at all requires a provider that reports it,
+ * which Android does not. On Android a held subscription simply stops being
+ * returned, so it never becomes a source and the entitlement lapses — the same
+ * result the `withhold` default expresses.
+ */
+function grantsUnderPolicy(state, policy) {
+  switch (state) {
+    case 'active':
+    case 'cancelled_valid':
+      return true;
+    case 'grace':
+      return policy.gracePolicy === 'grant';
+    case 'hold':
+      return policy.holdPolicy === 'grant';
+    case 'indeterminate':
+      // The store is still reporting the purchase as owned. Withholding here
+      // would revoke from a paying user because of our own uncertainty.
+      return true;
+  }
+}
+
+/** True once a subscription's paid period has genuinely elapsed (FR-048). */
+function hasExpired(expiresAt, now) {
+  return expiresAt !== undefined && expiresAt <= now;
+}
+//# sourceMappingURL=policy.js.map

package/lib/commonjs/entitlements/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["deriveRenewalState","facts","reportsGraceAndHoldDistinctly","providerRenewalState","willAutoRenew","grantsUnderPolicy","state","policy","gracePolicy","holdPolicy","hasExpired","expiresAt","now","undefined"],"sourceRoot":"../../../src","sources":["entitlements/policy.ts"],"mappings":";;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,kBAAkBA,CAACC,KAAwB,EAAgB;EAC1E,IAAIA,KAAK,CAACC,6BAA6B,IAAID,KAAK,CAACE,oBAAoB,EAAE;IACtE,QAAQF,KAAK,CAACE,oBAAoB;MACjC,KAAK,OAAO;QACX,OAAO,OAAO;MACf,KAAK,MAAM;QACV,OAAO,MAAM;MACd,KAAK,QAAQ;QACZ,OAAOF,KAAK,CAACG,aAAa,KAAK,KAAK,GAAG,iBAAiB,GAAG,QAAQ;IACrE;EACD;EAEA,IAAIH,KAAK,CAACG,aAAa,KAAK,KAAK,EAAE;IAClC;IACA;IACA;IACA,OAAO,iBAAiB;EACzB;EAEA,IAAIH,KAAK,CAACG,aAAa,KAAK,IAAI,EAAE;IACjC,OAAO,QAAQ;EAChB;EAEA,OAAO,eAAe;AACvB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,KAAmB,EAAEC,MAAyB,EAAW;EAC1F,QAAQD,KAAK;IACZ,KAAK,QAAQ;IACb,KAAK,iBAAiB;MACrB,OAAO,IAAI;IACZ,KAAK,OAAO;MACX,OAAOC,MAAM,CAACC,WAAW,KAAK,OAAO;IACtC,KAAK,MAAM;MACV,OAAOD,MAAM,CAACE,UAAU,KAAK,OAAO;IACrC,KAAK,eAAe;MACnB;MACA;MACA,OAAO,IAAI;EACb;AACD;;AAEA;AACO,SAASC,UAAUA,CAACC,SAA6B,EAAEC,GAAW,EAAW;EAC/E,OAAOD,SAAS,KAAKE,SAAS,IAAIF,SAAS,IAAIC,GAAG;AACnD","ignoreList":[]}

package/lib/commonjs/index.js

@@ -0,0 +1,266 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "BACKOFF_ATTEMPT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.BACKOFF_ATTEMPT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "BACKOFF_MAX_DELAY_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.BACKOFF_MAX_DELAY_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "CONNECT_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.CONNECT_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_CONNECT_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_CONNECT_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_DEVELOPER_MESSAGES", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.DEFAULT_DEVELOPER_MESSAGES;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_FINALIZE_BACKOFF", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_FINALIZE_BACKOFF;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_MESSAGES", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.DEFAULT_MESSAGES;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_PRODUCT_CACHE_TTL_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_PRODUCT_CACHE_TTL_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_PRODUCT_QUERY_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_PRODUCT_QUERY_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_RECONNECT_BACKOFF", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_RECONNECT_BACKOFF;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_STALE_AFTER_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_STALE_AFTER_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_SYNC_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_SYNC_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_USER_MESSAGES", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.DEFAULT_USER_MESSAGES;
+  }
+});
+Object.defineProperty(exports, "DEVELOPER_MESSAGE_KEYS", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.DEVELOPER_MESSAGE_KEYS;
+  }
+});
+Object.defineProperty(exports, "FINALIZE_ATTEMPT_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.FINALIZE_ATTEMPT_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "PAYMENT_ERROR_CODES", {
+  enumerable: true,
+  get: function () {
+    return _errors.PAYMENT_ERROR_CODES;
+  }
+});
+Object.defineProperty(exports, "PRODUCT_CACHE_TTL_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.PRODUCT_CACHE_TTL_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "PRODUCT_QUERY_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.PRODUCT_QUERY_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "PURCHASE_LAUNCH_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.PURCHASE_LAUNCH_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "PaymentConfigError", {
+  enumerable: true,
+  get: function () {
+    return _errors.PaymentConfigError;
+  }
+});
+Object.defineProperty(exports, "PaymentError", {
+  enumerable: true,
+  get: function () {
+    return _errors.PaymentError;
+  }
+});
+Object.defineProperty(exports, "PaymentProvider", {
+  enumerable: true,
+  get: function () {
+    return _PaymentProvider.PaymentProvider;
+  }
+});
+Object.defineProperty(exports, "STALE_AFTER_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.STALE_AFTER_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "SYNC_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.SYNC_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "USER_MESSAGE_KEYS", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.USER_MESSAGE_KEYS;
+  }
+});
+Object.defineProperty(exports, "createEngine", {
+  enumerable: true,
+  get: function () {
+    return _engine.createEngine;
+  }
+});
+Object.defineProperty(exports, "createStoreProvider", {
+  enumerable: true,
+  get: function () {
+    return _createStoreProvider.createStoreProvider;
+  }
+});
+Object.defineProperty(exports, "isUserMessageKey", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.isUserMessageKey;
+  }
+});
+Object.defineProperty(exports, "paymentMessages", {
+  enumerable: true,
+  get: function () {
+    return _messageKeys.paymentMessages;
+  }
+});
+Object.defineProperty(exports, "syncOnForeground", {
+  enumerable: true,
+  get: function () {
+    return _foreground.syncOnForeground;
+  }
+});
+Object.defineProperty(exports, "useEntitlement", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useEntitlement;
+  }
+});
+Object.defineProperty(exports, "useEntitlements", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useEntitlements;
+  }
+});
+Object.defineProperty(exports, "usePaymentEngine", {
+  enumerable: true,
+  get: function () {
+    return _PaymentProvider.usePaymentEngine;
+  }
+});
+Object.defineProperty(exports, "usePaymentStatus", {
+  enumerable: true,
+  get: function () {
+    return _hooks.usePaymentStatus;
+  }
+});
+Object.defineProperty(exports, "usePendingPurchases", {
+  enumerable: true,
+  get: function () {
+    return _hooks.usePendingPurchases;
+  }
+});
+Object.defineProperty(exports, "useProducts", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useProducts;
+  }
+});
+Object.defineProperty(exports, "usePurchase", {
+  enumerable: true,
+  get: function () {
+    return _hooks.usePurchase;
+  }
+});
+Object.defineProperty(exports, "useSync", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useSync;
+  }
+});
+var _timers = require("./core/timers.js");
+var _createStoreProvider = require("./adapter/createStoreProvider.js");
+var _engine = require("./engine/engine.js");
+var _foreground = require("./engine/foreground.js");
+var _PaymentProvider = require("./react/PaymentProvider.js");
+var _hooks = require("./react/hooks.js");
+var _errors = require("./diagnostics/errors.js");
+var _messageKeys = require("./diagnostics/messageKeys.js");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_timers","require","_createStoreProvider","_engine","_foreground","_PaymentProvider","_hooks","_errors","_messageKeys"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,IAAAA,OAAA,GAAAC,OAAA;AAiDA,IAAAC,oBAAA,GAAAD,OAAA;AAIA,IAAAE,OAAA,GAAAF,OAAA;AASA,IAAAG,WAAA,GAAAH,OAAA;AAGA,IAAAI,gBAAA,GAAAJ,OAAA;AAEA,IAAAK,MAAA,GAAAL,OAAA;AAYA,IAAAM,OAAA,GAAAN,OAAA;AAYA,IAAAO,YAAA,GAAAP,OAAA","ignoreList":[]}

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}