@chipmobilesdk/rn-payment 0.6.0 → 0.7.0

package/lib/module/config/validate.js

@@ -0,0 +1,175 @@
+"use strict";
+
+/**
+ * Catalog validation (FR-011).
+ *
+ * Runs at `configure`, before any connection is opened, so a bad catalog fails
+ * at configuration time rather than at the moment a user taps Buy. Every failure
+ * **names the offending entry** — "invalid catalog" alone is useless in an app
+ * with thirty products.
+ *
+ * All problems are collected rather than thrown one at a time, so a developer
+ * fixes the catalog in one pass instead of rerunning to find the next fault.
+ */
+
+import { PaymentConfigError } from "../diagnostics/errors.js";
+import { resolveForegroundSyncMinIntervalMs, resolveProductCacheTtlMs, resolveRetry, resolveStaleAfterMs, resolveTimeouts } from "../core/timers.js";
+const PRODUCT_TYPES = ['one_time_permanent', 'one_time_consumable', 'subscription'];
+
+/** The platform whose store identifiers a catalog must supply. */
+
+/**
+ * A validated, indexed catalog plus every resolved policy value.
+ *
+ * Produced once so the hot paths never re-derive it, and so `getEntitlement` can
+ * stay a synchronous in-memory read (PERF-001).
+ */
+
+export function validateConfig(config, platform = 'android') {
+  const problems = [];
+  const offenders = [];
+  const entries = new Map();
+  const grants = new Map();
+  const sources = new Map();
+  const byStoreId = new Map();
+  if (config.catalog.length === 0) {
+    problems.push('catalog is empty');
+    offenders.push('catalog');
+  }
+  for (const entry of config.catalog) {
+    const key = entry.productKey;
+    if (!key || key.trim() === '') {
+      problems.push('a catalog entry has an empty productKey');
+      offenders.push('(empty productKey)');
+      continue;
+    }
+    if (entries.has(key)) {
+      problems.push(`duplicate productKey "${key}"`);
+      offenders.push(key);
+      continue;
+    }
+    if (!PRODUCT_TYPES.includes(entry.productType)) {
+      problems.push(`productKey "${key}" has invalid productType "${String(entry.productType)}"`);
+      offenders.push(key);
+    }
+    const storeId = entry.storeProductIds[platform];
+    if (!storeId || storeId.trim() === '') {
+      problems.push(`productKey "${key}" is missing a store product id for platform "${platform}"`);
+      offenders.push(key);
+    } else {
+      const existing = byStoreId.get(storeId);
+      if (existing !== undefined) {
+        // Two product keys pointing at one store id would make a store callback
+        // ambiguous, so the wrong entitlement could be granted.
+        problems.push(`store product id "${storeId}" is used by both "${existing}" and "${key}"`);
+        offenders.push(key);
+      } else {
+        byStoreId.set(storeId, key);
+      }
+    }
+    if (!Array.isArray(entry.grants) || entry.grants.length === 0) {
+      problems.push(`productKey "${key}" grants no entitlement`);
+      offenders.push(key);
+    }
+    entries.set(key, entry);
+    grants.set(key, [...(entry.grants ?? [])]);
+    for (const entitlement of entry.grants ?? []) {
+      const list = sources.get(entitlement);
+      if (list) {
+        list.push(key);
+      } else {
+        sources.set(entitlement, [key]);
+      }
+    }
+  }
+
+  // An entitlement the app intends to query but no product can grant is almost
+  // always a typo, and it would otherwise sit at `not_entitled` forever with no
+  // indication why.
+  for (const entitlement of config.entitlements) {
+    if (!sources.has(entitlement)) {
+      problems.push(`entitlement "${entitlement}" is declared but no catalog product grants it`);
+      offenders.push(entitlement);
+    }
+  }
+
+  // A product granting something the app never declared is the mirror problem:
+  // harmless at runtime, but a strong signal of a rename half-applied.
+  const declared = new Set(config.entitlements);
+  for (const entitlement of sources.keys()) {
+    if (!declared.has(entitlement)) {
+      problems.push(`entitlement "${entitlement}" is granted by a product but not declared in config.entitlements`);
+      offenders.push(entitlement);
+    }
+  }
+  if (problems.length > 0) {
+    throw new PaymentConfigError({
+      code: 'PAYMENT_INVALID_CATALOG',
+      message: `Payment catalog is invalid: ${problems.join('; ')}`,
+      operation: 'configure',
+      offenders: [...new Set(offenders)]
+    });
+  }
+  return {
+    entries,
+    grants,
+    sources: new Map([...sources].map(([k, v]) => [k, [...v]])),
+    byStoreId,
+    entitlementKeys: [...config.entitlements],
+    platform,
+    enabled: config.enabled ?? true,
+    gracePolicy: config.gracePolicy ?? 'grant',
+    holdPolicy: config.holdPolicy ?? 'withhold',
+    staleAfterMs: resolveStaleAfterMs(config.staleAfterMs),
+    productCacheTtlMs: resolveProductCacheTtlMs(config.productCacheTtlMs),
+    foregroundSyncMinIntervalMs: resolveForegroundSyncMinIntervalMs(config.foregroundSyncMinIntervalMs),
+    timeouts: resolveTimeouts(config.timeouts),
+    retry: resolveRetry(config.retry),
+    onValidationUnavailable: config.onValidationUnavailable ?? 'grant_and_queue'
+  };
+}
+
+/**
+ * The fail-closed environment guard (FR-015).
+ *
+ * Separate from catalog validation because it is not about the catalog's shape
+ * but about whether this binary is allowed to move real money at all. Checked
+ * before connecting, and it refuses rather than warns: a non-production build
+ * that declares `production` is one tap away from charging a real card, and
+ * continuing silently is exactly the failure this package exists to prevent.
+ */
+export function assertEnvironmentSafe(config) {
+  if (config.allowStoreTestPurchases === true && config.environment !== 'test') {
+    throw new PaymentConfigError({
+      code: 'PAYMENT_INVALID_CONFIG',
+      message: `allowStoreTestPurchases is only accepted with environment "test", not ` + `"${config.environment}": it exists for license testers, not for real users.`,
+      operation: 'configure',
+      offenders: ['allowStoreTestPurchases']
+    });
+  }
+  if (config.environment === 'production' && !config.isProductionBuild) {
+    throw new PaymentConfigError({
+      code: 'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
+      message: 'environment is "production" but isProductionBuild is false. Refusing to ' + 'initialize: a non-production build must not be able to create a real ' + 'transaction.',
+      operation: 'configure',
+      offenders: ['environment']
+    });
+  }
+}
+
+/**
+ * Whether this configuration may hand a purchase to a real store (FR-014).
+ *
+ * True in a production build configured for production, and in a `test`
+ * environment that opted in with `allowStoreTestPurchases` (PAY-16). False
+ * everywhere else. The engine records each refusal in observable status so a
+ * test can assert the block happened — the difference between a guarantee and a
+ * hope.
+ */
+export function mayCreateRealTransaction(config) {
+  if (config.environment === 'test' && config.allowStoreTestPurchases === true) {
+    return true;
+  }
+  return config.environment === 'production' && config.isProductionBuild;
+}
+//# sourceMappingURL=validate.js.map

package/lib/module/config/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PaymentConfigError","resolveForegroundSyncMinIntervalMs","resolveProductCacheTtlMs","resolveRetry","resolveStaleAfterMs","resolveTimeouts","PRODUCT_TYPES","validateConfig","config","platform","problems","offenders","entries","Map","grants","sources","byStoreId","catalog","length","push","entry","key","productKey","trim","has","includes","productType","String","storeId","storeProductIds","existing","get","undefined","set","Array","isArray","entitlement","list","entitlements","declared","Set","keys","code","message","join","operation","map","k","v","entitlementKeys","enabled","gracePolicy","holdPolicy","staleAfterMs","productCacheTtlMs","foregroundSyncMinIntervalMs","timeouts","retry","onValidationUnavailable","assertEnvironmentSafe","allowStoreTestPurchases","environment","isProductionBuild","mayCreateRealTransaction"],"sourceRoot":"../../../src","sources":["config/validate.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/mutex.js

@@ -0,0 +1,22 @@
+"use strict";
+
+/**
+ * Concurrency primitives.
+ *
+ * These are what make three of the specification's guarantees structurally true
+ * rather than hoped for: concurrent initialization opens exactly one connection
+ * (FR-018), concurrent syncs make exactly one store request (FR-063), and a
+ * second purchase while one is open is refused rather than queued (FR-031).
+ *
+ * The distinction between the two primitives matters. `singleFlight` **joins**
+ * concurrent callers onto one operation — correct for init and sync, where every
+ * caller wants the same answer. `exclusive` **refuses** the second caller —
+ * correct for purchase, where joining would silently give two callers one
+ * transaction, and queueing would open a store surface the user no longer
+ * expects.
+ */
+
+// The primitives themselves are rn-core's; the reasoning above is why rn-payment
+// uses each where it does.
+export { createExclusive, createRateLimiter, createSingleFlight, withTimeout } from '@chipmobilesdk/rn-core';
+//# sourceMappingURL=mutex.js.map

package/lib/module/core/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createExclusive","createRateLimiter","createSingleFlight","withTimeout"],"sourceRoot":"../../../src","sources":["core/mutex.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA,SACCA,eAAe,EACfC,iBAAiB,EACjBC,kBAAkB,EAClBC,WAAW,QAEL,wBAAwB","ignoreList":[]}

package/lib/module/core/retry.js

@@ -0,0 +1,33 @@
+"use strict";
+
+/**
+ * Bounded backoff.
+ *
+ * "Bounded" is the whole point (FR-020, FR-045): an unbounded reconnect loop
+ * against a billing service that is down drains battery and hammers a system
+ * service, and an unbounded finalize loop hides a real failure behind noise.
+ *
+ * Delay computation is pure and separated from waiting so tests can assert the
+ * schedule without burning real time.
+ */
+
+import { computeBackoff } from '@chipmobilesdk/rn-core';
+/**
+ * Delay before `attempt` (1-based), capped and optionally jittered.
+ *
+ * Jitter is full jitter over [0, capped]: several devices that lost the billing
+ * connection at the same moment should not retry in lockstep.
+ */
+export function backoffDelayMs(attempt, config, random = Math.random) {
+  return computeBackoff(attempt, toSpec(config), random);
+}
+function toSpec(config) {
+  return {
+    initialDelayMs: config.initialDelayMs,
+    maxDelayMs: config.maxDelayMs,
+    factor: config.factor,
+    jitter: config.jitter ? 'full' : 'none',
+    maxAttempts: config.maxAttempts
+  };
+}
+//# sourceMappingURL=retry.js.map

package/lib/module/core/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["computeBackoff","backoffDelayMs","attempt","config","random","Math","toSpec","initialDelayMs","maxDelayMs","factor","jitter","maxAttempts"],"sourceRoot":"../../../src","sources":["core/retry.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,cAAc,QAAQ,wBAAwB;AAIvD;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAC7BC,OAAe,EACfC,MAA+B,EAC/BC,MAAoB,GAAGC,IAAI,CAACD,MAAM,EACzB;EACT,OAAOJ,cAAc,CAACE,OAAO,EAAEI,MAAM,CAACH,MAAM,CAAC,EAAEC,MAAM,CAAC;AACvD;AAEA,SAASE,MAAMA,CAACH,MAA+B,EAAE;EAChD,OAAO;IACNI,cAAc,EAAEJ,MAAM,CAACI,cAAc;IACrCC,UAAU,EAAEL,MAAM,CAACK,UAAU;IAC7BC,MAAM,EAAEN,MAAM,CAACM,MAAM;IACrBC,MAAM,EAAEP,MAAM,CAACO,MAAM,GAAI,MAAM,GAAc,MAAgB;IAC7DC,WAAW,EAAER,MAAM,CAACQ;EACrB,CAAC;AACF","ignoreList":[]}

package/lib/module/core/timers.js

@@ -0,0 +1,198 @@
+"use strict";
+
+/**
+ * Timeout, retry, and cache policy.
+ *
+ * Defaults and bounds live here rather than at each call site so there is one
+ * place to read what the package will wait for, and so consumers can read the
+ * values they are bound by instead of discovering them from a timeout in
+ * production.
+ *
+ * Out-of-band values are a configuration error rather than being silently
+ * clamped: quietly turning a 1-second timeout into 3 seconds would tell the app
+ * it configured something it did not.
+ */
+
+import { checkRange } from '@chipmobilesdk/rn-core';
+import { PaymentConfigError } from "../diagnostics/errors.js";
+/** Local IPC to Play Services. Slower than this means unavailable, not busy. */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/** A network round trip; a paywall that hangs longer should show its error state. */
+export const DEFAULT_PRODUCT_QUERY_TIMEOUT_MS = 15_000;
+/** Runs at startup, so it must not hold the first render hostage. */
+export const DEFAULT_SYNC_TIMEOUT_MS = 20_000;
+/**
+ * Covers opening the store surface only.
+ *
+ * Time the user spends *inside* the store's own UI is deliberately excluded
+ * (FR-035): a user reading the terms, switching to their banking app for an OTP,
+ * or simply hesitating must never have their purchase cancelled by our clock.
+ */
+export const DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS = 30_000;
+/** Per finalize attempt, not per transaction — the queue owns overall persistence. */
+export const DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS = 15_000;
+/** The app's backend hook. A user is waiting on a purchase result behind it. */
+export const DEFAULT_VALIDATE_TIMEOUT_MS = 15_000;
+/**
+ * The ceiling on a purchase flow whose outcome includes the user's own time in
+ * the store UI, so is otherwise untimed (FR-035). Not a timeout on the user: it
+ * exists only so a binding that never answers cannot hold the purchase lock for
+ * the rest of the session. A purchase that completes later still arrives through
+ * the store update channel and is granted then.
+ */
+export const PURCHASE_FLOW_CEILING_MS = 10 * 60_000;
+export const CONNECT_TIMEOUT_BOUNDS = {
+  min: 3_000,
+  max: 60_000
+};
+export const PRODUCT_QUERY_TIMEOUT_BOUNDS = {
+  min: 3_000,
+  max: 60_000
+};
+export const SYNC_TIMEOUT_BOUNDS = {
+  min: 5_000,
+  max: 120_000
+};
+export const PURCHASE_LAUNCH_TIMEOUT_BOUNDS = {
+  min: 5_000,
+  max: 120_000
+};
+export const FINALIZE_ATTEMPT_TIMEOUT_BOUNDS = {
+  min: 3_000,
+  max: 60_000
+};
+export const VALIDATE_TIMEOUT_BOUNDS = {
+  min: 3_000,
+  max: 120_000
+};
+
+/**
+ * Prices and offer eligibility are shown at the moment of purchase, so a short
+ * TTL with on-demand refresh beats a long one (FR-029).
+ */
+export const DEFAULT_PRODUCT_CACHE_TTL_MS = 900_000;
+export const PRODUCT_CACHE_TTL_BOUNDS = {
+  min: 60_000,
+  max: 86_400_000
+};
+
+/**
+ * How long a successful sync keeps entitlements trustworthy offline: **7 days**.
+ *
+ * Fixed by the specification (FR-055) after weighing both failure directions.
+ * The realistic offline cases — travel, poor coverage, a device left unused —
+ * resolve within days. Seven days covers a holiday without connectivity while
+ * bounding how long a refunded entitlement can outlive its refund to one week.
+ *
+ * Past this the entitlement becomes `unknown`, never `not_entitled` (FR-055a):
+ * the package stops asserting rather than telling a paying customer they did not
+ * pay.
+ */
+export const DEFAULT_STALE_AFTER_MS = 604_800_000;
+export const STALE_AFTER_BOUNDS = {
+  min: 3_600_000,
+  max: 7_776_000_000
+};
+
+/** Keeps rapid app switching from becoming a request storm (PERF-002). */
+export const DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS = 60_000;
+export const FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS = {
+  min: 0,
+  max: 3_600_000
+};
+
+/** Bounded so a dropped billing connection cannot become a retry storm (FR-020). */
+export const DEFAULT_RECONNECT_BACKOFF = {
+  initialDelayMs: 1_000,
+  maxDelayMs: 30_000,
+  factor: 2,
+  maxAttempts: 5,
+  jitter: true
+};
+
+/**
+ * Finalize retry.
+ *
+ * Bounded **per session** but never permanently abandoned: Google auto-refunds
+ * an unacknowledged purchase after three days, so exhausting this session's
+ * attempts must leave the transaction queued for the next launch, not dropped
+ * (FR-045).
+ */
+export const DEFAULT_FINALIZE_BACKOFF = {
+  initialDelayMs: 2_000,
+  maxDelayMs: 60_000,
+  factor: 2,
+  maxAttempts: 5,
+  jitter: true
+};
+export const BACKOFF_MAX_DELAY_BOUNDS = {
+  min: 5_000,
+  max: 600_000
+};
+export const BACKOFF_ATTEMPT_BOUNDS = {
+  min: 1,
+  max: 10
+};
+/** A first retry sooner than this is a storm; later than this, the user has given up. */
+export const BACKOFF_INITIAL_DELAY_BOUNDS = {
+  min: 100,
+  max: 60_000
+};
+/** 1 is a constant delay; 0 or below would retry at once, forever (CORE-05). */
+export const BACKOFF_FACTOR_BOUNDS = {
+  min: 1,
+  max: 10
+};
+function invalidConfig(label) {
+  return message => new PaymentConfigError({
+    code: 'PAYMENT_INVALID_CONFIG',
+    message,
+    operation: 'configure',
+    offenders: [label]
+  });
+}
+function requireInBounds(label, value, fallback, bounds, unit = 'ms') {
+  return value === undefined ? fallback : checkRange(label, value, bounds, invalidConfig(label), unit);
+}
+export function resolveTimeouts(config) {
+  return {
+    connectMs: requireInBounds('timeouts.connectMs', config?.connectMs, DEFAULT_CONNECT_TIMEOUT_MS, CONNECT_TIMEOUT_BOUNDS),
+    productQueryMs: requireInBounds('timeouts.productQueryMs', config?.productQueryMs, DEFAULT_PRODUCT_QUERY_TIMEOUT_MS, PRODUCT_QUERY_TIMEOUT_BOUNDS),
+    syncMs: requireInBounds('timeouts.syncMs', config?.syncMs, DEFAULT_SYNC_TIMEOUT_MS, SYNC_TIMEOUT_BOUNDS),
+    purchaseLaunchMs: requireInBounds('timeouts.purchaseLaunchMs', config?.purchaseLaunchMs, DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS, PURCHASE_LAUNCH_TIMEOUT_BOUNDS),
+    finalizeAttemptMs: requireInBounds('timeouts.finalizeAttemptMs', config?.finalizeAttemptMs, DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS, FINALIZE_ATTEMPT_TIMEOUT_BOUNDS),
+    validateMs: requireInBounds('timeouts.validateMs', config?.validateMs, DEFAULT_VALIDATE_TIMEOUT_MS, VALIDATE_TIMEOUT_BOUNDS)
+  };
+}
+function resolveBackoff(label, config, fallback) {
+  const maxDelayMs = requireInBounds(`${label}.maxDelayMs`, config?.maxDelayMs, fallback.maxDelayMs, BACKOFF_MAX_DELAY_BOUNDS);
+  const maxAttempts = requireInBounds(`${label}.maxAttempts`, config?.maxAttempts, fallback.maxAttempts, BACKOFF_ATTEMPT_BOUNDS, '');
+  const initialDelayMs = requireInBounds(`${label}.initialDelayMs`, config?.initialDelayMs, fallback.initialDelayMs, BACKOFF_INITIAL_DELAY_BOUNDS);
+  const factor = requireInBounds(`${label}.factor`, config?.factor, fallback.factor, BACKOFF_FACTOR_BOUNDS, '');
+  if (initialDelayMs > maxDelayMs) {
+    throw invalidConfig(`${label}.initialDelayMs`)(`${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms)`);
+  }
+  return {
+    initialDelayMs,
+    maxDelayMs,
+    factor,
+    maxAttempts,
+    jitter: config?.jitter ?? fallback.jitter
+  };
+}
+export function resolveRetry(config) {
+  return {
+    reconnect: resolveBackoff('retry.reconnect', config?.reconnect, DEFAULT_RECONNECT_BACKOFF),
+    finalize: resolveBackoff('retry.finalize', config?.finalize, DEFAULT_FINALIZE_BACKOFF)
+  };
+}
+export function resolveStaleAfterMs(value) {
+  return requireInBounds('staleAfterMs', value, DEFAULT_STALE_AFTER_MS, STALE_AFTER_BOUNDS);
+}
+export function resolveProductCacheTtlMs(value) {
+  return requireInBounds('productCacheTtlMs', value, DEFAULT_PRODUCT_CACHE_TTL_MS, PRODUCT_CACHE_TTL_BOUNDS);
+}
+export function resolveForegroundSyncMinIntervalMs(value) {
+  return requireInBounds('foregroundSyncMinIntervalMs', value, DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS, FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS);
+}
+//# sourceMappingURL=timers.js.map

package/lib/module/core/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["checkRange","PaymentConfigError","DEFAULT_CONNECT_TIMEOUT_MS","DEFAULT_PRODUCT_QUERY_TIMEOUT_MS","DEFAULT_SYNC_TIMEOUT_MS","DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS","DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS","DEFAULT_VALIDATE_TIMEOUT_MS","PURCHASE_FLOW_CEILING_MS","CONNECT_TIMEOUT_BOUNDS","min","max","PRODUCT_QUERY_TIMEOUT_BOUNDS","SYNC_TIMEOUT_BOUNDS","PURCHASE_LAUNCH_TIMEOUT_BOUNDS","FINALIZE_ATTEMPT_TIMEOUT_BOUNDS","VALIDATE_TIMEOUT_BOUNDS","DEFAULT_PRODUCT_CACHE_TTL_MS","PRODUCT_CACHE_TTL_BOUNDS","DEFAULT_STALE_AFTER_MS","STALE_AFTER_BOUNDS","DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS","FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS","DEFAULT_RECONNECT_BACKOFF","initialDelayMs","maxDelayMs","factor","maxAttempts","jitter","DEFAULT_FINALIZE_BACKOFF","BACKOFF_MAX_DELAY_BOUNDS","BACKOFF_ATTEMPT_BOUNDS","BACKOFF_INITIAL_DELAY_BOUNDS","BACKOFF_FACTOR_BOUNDS","invalidConfig","label","message","code","operation","offenders","requireInBounds","value","fallback","bounds","unit","undefined","resolveTimeouts","config","connectMs","productQueryMs","syncMs","purchaseLaunchMs","finalizeAttemptMs","validateMs","resolveBackoff","resolveRetry","reconnect","finalize","resolveStaleAfterMs","resolveProductCacheTtlMs","resolveForegroundSyncMinIntervalMs"],"sourceRoot":"../../../src","sources":["core/timers.ts"],"mappings":"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","ignoreList":[]}

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