@chipmobilesdk/rn-payment 0.6.0 → 0.7.0

package/lib/typescript/module/diagnostics/events.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 { redact, type PaymentErrorCode, type PaymentOperation } from './errors.js';
+import type { EntitlementKey, Environment, PendingResolution, ProductKey, Unsubscribe, UnavailableReason, PaymentStatusKind } from '../config/types.js';
+export type PaymentEventType = 'initialization' | 'connection_changed' | 'products_queried' | 'purchase_started' | 'purchase_succeeded' | 'purchase_cancelled' | 'purchase_pending' | 'purchase_pending_resolved' | 'purchase_failed' | 'transaction_finalized' | 'transaction_consumed' | 'finalize_retry_scheduled' | 'sync_completed' | 'entitlement_granted' | 'entitlement_revoked' | 'validation_decided' | 'validation_unavailable' | 'environment_blocked' | 'config_warning' | 'internal_error';
+interface BaseEvent {
+    timestamp: number;
+    /** Ties one purchase cycle together end to end. Absent for lifecycle events. */
+    correlationId?: string;
+}
+export type SyncTrigger = 'initialize' | 'foreground' | 'manual' | 'already_owned';
+export type PaymentEvent = BaseEvent & ({
+    type: 'initialization';
+    status: PaymentStatusKind;
+    unavailableReason?: UnavailableReason;
+    retryable?: boolean;
+} | {
+    type: 'connection_changed';
+    connected: boolean;
+    reason?: string;
+    attempt?: number;
+} | {
+    type: 'products_queried';
+    productKeys: ProductKey[];
+    found: number;
+    missing: ProductKey[];
+    fromCache: boolean;
+} | {
+    type: 'purchase_started';
+    productKey: ProductKey;
+} | {
+    type: 'purchase_succeeded';
+    productKey: ProductKey;
+} | {
+    type: 'purchase_cancelled';
+    productKey: ProductKey;
+} | {
+    type: 'purchase_pending';
+    productKey: ProductKey;
+} | {
+    type: 'purchase_pending_resolved';
+    productKey: ProductKey;
+    outcome: PendingResolution;
+} | {
+    type: 'purchase_failed';
+    productKey: ProductKey;
+    code: PaymentErrorCode;
+    retryable: boolean;
+} | {
+    type: 'transaction_finalized';
+    productKey: ProductKey;
+    attempts: number;
+} | {
+    type: 'transaction_consumed';
+    productKey: ProductKey;
+} | {
+    type: 'finalize_retry_scheduled';
+    productKey: ProductKey;
+    attempt: number;
+    delayMs: number;
+} | {
+    type: 'sync_completed';
+    restoredCount: number;
+    revokedCount: number;
+    trigger: SyncTrigger;
+} | {
+    type: 'entitlement_granted';
+    entitlementKey: EntitlementKey;
+    sources: ProductKey[];
+} | {
+    type: 'entitlement_revoked';
+    entitlementKey: EntitlementKey;
+    reason: 'expired' | 'revoked_by_store' | 'validation_rejected' | 'consumed';
+} | {
+    type: 'validation_decided';
+    productKey: ProductKey;
+    decision: 'approved' | 'rejected';
+} | {
+    type: 'validation_unavailable';
+    productKey: ProductKey;
+    fallback: 'grant_and_queue' | 'withhold';
+} | {
+    type: 'environment_blocked';
+    productKey: ProductKey;
+    environment: Environment;
+} | {
+    type: 'config_warning';
+    detail: string;
+} | {
+    type: 'internal_error';
+    code: PaymentErrorCode;
+    operation: PaymentOperation;
+});
+export type PaymentEventListener = (event: PaymentEvent) => void;
+/**
+ * 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.
+ */
+type WithOptionalTimestamp<T> = T extends unknown ? Omit<T, 'timestamp'> & {
+    timestamp?: number;
+} : never;
+export type PaymentEventInput = WithOptionalTimestamp<PaymentEvent>;
+export interface PaymentEmitter {
+    emit(event: PaymentEvent): void;
+    subscribe(listener: PaymentEventListener): Unsubscribe;
+    /** Disarms permanently. After this nothing is emitted (FR-082). */
+    dispose(): void;
+    listenerCount(): number;
+    disposed(): boolean;
+}
+/**
+ * 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 declare function createEmitter(onListenerError?: (error: unknown, event: PaymentEvent) => void): PaymentEmitter;
+/**
+ * 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 declare const FORBIDDEN_EVENT_FIELDS: readonly string[];
+/** Correlation ids tie one purchase cycle together; no user data goes into them. */
+export declare function createCorrelationId(counter: {
+    next: number;
+}, prefix?: string): string;
+export { redact };
+//# sourceMappingURL=events.d.ts.map

package/lib/typescript/module/diagnostics/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../src/diagnostics/events.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/diagnostics/messageKeys.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Stable, localizable message keys with English default copy (FR-084, FR-085).
+ *
+ * The package takes no i18n runtime dependency: consuming apps map these keys to
+ * localized strings through whatever i18n system they already run. This is plain
+ * data, and the package never resolves or renders it.
+ *
+ * Message keys are **public API**: renaming one is a breaking change, on the
+ * same footing as an error code (FR-078).
+ *
+ * User-actionable copy and developer/configuration copy are kept in separate
+ * maps so an app cannot accidentally show "Payment catalog is invalid" to a
+ * customer — a configuration fault is a developer's problem, not a user's.
+ */
+export interface PaymentUserMessageMap {
+    'payment.state.pending': string;
+    'payment.state.alreadyOwned': string;
+    'payment.action.restore': string;
+    'payment.restore.succeeded': string;
+    'payment.restore.nothingFound': string;
+    'payment.error.cancelled': string;
+    'payment.error.network': string;
+    'payment.error.unavailable': string;
+    'payment.error.disabled': string;
+    'payment.subscription.grace': string;
+    'payment.subscription.hold': string;
+}
+/** Copy for developers and operators. **Never** surfaced to an end user. */
+export interface PaymentDeveloperMessageMap {
+    'payment.config.invalidCatalog': string;
+    'payment.config.missingStoreId': string;
+    'payment.config.productionInNonProductionBuild': string;
+    'payment.config.storageUnavailable': string;
+    'payment.config.environmentBlocked': string;
+}
+export type PaymentMessageMap = PaymentUserMessageMap & PaymentDeveloperMessageMap;
+export type PaymentUserMessageKey = keyof PaymentUserMessageMap;
+export type PaymentDeveloperMessageKey = keyof PaymentDeveloperMessageMap;
+export type PaymentMessageKey = keyof PaymentMessageMap;
+export declare const DEFAULT_USER_MESSAGES: PaymentUserMessageMap;
+export declare const DEFAULT_DEVELOPER_MESSAGES: PaymentDeveloperMessageMap;
+/**
+ * The catalog as an rn-core message set. Register `paymentMessages.user` with
+ * rn-i18n to translate it like app copy; the developer copy stays out of bundles.
+ */
+export declare const paymentMessages: import("@chipmobilesdk/rn-core").MessageSet<PaymentUserMessageMap, PaymentDeveloperMessageMap>;
+export declare const DEFAULT_MESSAGES: PaymentMessageMap;
+/** Every user-actionable key, for an app building its translation resource. */
+export declare const USER_MESSAGE_KEYS: PaymentUserMessageKey[];
+/** Every developer-facing key, so an app can exclude them from user-visible bundles. */
+export declare const DEVELOPER_MESSAGE_KEYS: PaymentDeveloperMessageKey[];
+/** True for keys safe to show an end user. Lets an app assert that at its boundary. */
+export declare function isUserMessageKey(key: PaymentMessageKey): key is PaymentUserMessageKey;
+//# sourceMappingURL=messageKeys.d.ts.map

package/lib/typescript/module/diagnostics/messageKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageKeys.d.ts","sourceRoot":"","sources":["../../../../src/diagnostics/messageKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,WAAW,qBAAqB;IACrC,uBAAuB,EAAE,MAAM,CAAC;IAChC,4BAA4B,EAAE,MAAM,CAAC;IACrC,wBAAwB,EAAE,MAAM,CAAC;IACjC,2BAA2B,EAAE,MAAM,CAAC;IACpC,8BAA8B,EAAE,MAAM,CAAC;IACvC,yBAAyB,EAAE,MAAM,CAAC;IAClC,uBAAuB,EAAE,MAAM,CAAC;IAChC,2BAA2B,EAAE,MAAM,CAAC;IACpC,wBAAwB,EAAE,MAAM,CAAC;IACjC,4BAA4B,EAAE,MAAM,CAAC;IACrC,2BAA2B,EAAE,MAAM,CAAC;CACpC;AAED,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IAC1C,+BAA+B,EAAE,MAAM,CAAC;IACxC,+BAA+B,EAAE,MAAM,CAAC;IACxC,+CAA+C,EAAE,MAAM,CAAC;IACxD,mCAAmC,EAAE,MAAM,CAAC;IAC5C,mCAAmC,EAAE,MAAM,CAAC;CAC5C;AAED,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,0BAA0B,CAAC;AAEnF,MAAM,MAAM,qBAAqB,GAAG,MAAM,qBAAqB,CAAC;AAChE,MAAM,MAAM,0BAA0B,GAAG,MAAM,0BAA0B,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,iBAAiB,CAAC;AAExD,eAAO,MAAM,qBAAqB,EAAE,qBAYnC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,0BASxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,gGAG1B,CAAC;AAEH,eAAO,MAAM,gBAAgB,EAAE,iBAA4C,CAAC;AAE5E,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,EAA+B,qBAAqB,EAAE,CAAC;AAErF,wFAAwF;AACxF,eAAO,MAAM,sBAAsB,EAAoC,0BAA0B,EAAE,CAAC;AAEpG,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,GAAG,IAAI,qBAAqB,CAErF"}

package/lib/typescript/module/engine/connection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The billing connection: connecting, watching it, and reconnecting with bounded
+ * backoff (FR-018 – FR-024, PAY-10).
+ *
+ * A reconnect is always a full teardown-then-connect cycle. The upstream
+ * binding's own `reconnect()` has reported success without rebuilding anything
+ * (openiap#408), so no shortcut is trusted here.
+ */
+import type { ProviderPurchase } from '../adapter/port.js';
+import { PaymentError } from '../diagnostics/errors.js';
+import type { EngineState } from './state.js';
+export type InitOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    error: PaymentError;
+};
+export interface Connection {
+    /** Connects and attaches the watchers; status follows the outcome. */
+    connect(): Promise<InitOutcome>;
+    /**
+     * A fresh reconnect budget and one immediate attempt, when an earlier budget
+     * ran out: a foreground return is when the network the app lost is usually
+     * back.
+     */
+    recover(): Promise<void>;
+    dispose(): void;
+}
+export declare function createConnection(state: EngineState, onPurchase: (purchase: ProviderPurchase) => void): Connection;
+//# sourceMappingURL=connection.d.ts.map

package/lib/typescript/module/engine/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/engine/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAiB,CAAC;AAIxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAS,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,UAAU;IAC1B,sEAAsE;IACtE,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAChC;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,GAC9C,UAAU,CAiKZ"}

package/lib/typescript/module/engine/engine.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The engine: status, initialization, entitlement reads, and sync.
+ *
+ * Owns the concurrency guarantees that make three requirements structurally true
+ * rather than hoped for — one connection under concurrent init (FR-018), one
+ * store request under concurrent sync (FR-063), and a rate-limited foreground
+ * sync (PERF-002).
+ *
+ * It never imports a store type. The only thing it talks to is `ProviderPort`,
+ * which is what keeps the binding replaceable and iOS additive (FR-002, FR-007).
+ *
+ * This file composes (PAY-10): state and its publication live in `state.ts`, the
+ * connection in `connection.ts`, sync in `sync.ts`, and the internals tests reach
+ * for in `internals.ts`, off the public type (PAY-11).
+ */
+import type { ProviderPort } from '../adapter/port.js';
+import { type TargetPlatform } from '../config/validate.js';
+import type { EntitlementKey, FinalizeResult, PaymentConfig, PaymentStatus, PendingPurchasesState, ProductKey, PurchaseOptions, PurchaseResult, TransactionRef, UnfinalizedSummary, Unsubscribe } from '../config/types.js';
+import { PaymentError } from '../diagnostics/errors.js';
+import { type PaymentEventListener, type SyncTrigger } from '../diagnostics/events.js';
+import type { EntitlementMap, EntitlementState } from '../entitlements/aggregate.js';
+import { type SnapshotStore } from '../persistence/mmkv-store.js';
+import { type InitOutcome } from './connection.js';
+import { type ProductQueryResult } from './products.js';
+import { type PriceChangeResult, type ProrationMode } from './subscriptions.js';
+import { type SyncOutcome } from './sync.js';
+export type { SyncOutcome } from './sync.js';
+export type { InitOutcome } from './connection.js';
+export type RestoreOutcome = {
+    ok: true;
+    restored: true;
+    entitlements: EntitlementKey[];
+}
+/** Distinct from a failure so an app never shows a false success (FR-061). */
+ | {
+    ok: true;
+    restored: false;
+} | {
+    ok: false;
+    error: PaymentError;
+};
+export interface EngineDeps {
+    /** Injected so the fake store is a drop-in replacement (NFR-007). */
+    provider: ProviderPort;
+    snapshotStore?: SnapshotStore;
+    platform?: TargetPlatform;
+    now?: () => number;
+}
+export interface PaymentEngine {
+    initialize(): Promise<InitOutcome>;
+    cleanup(): void;
+    getStatus(): PaymentStatus;
+    subscribeStatus(listener: (status: PaymentStatus) => void): Unsubscribe;
+    getEntitlement(key: EntitlementKey): EntitlementState;
+    getAllEntitlements(): EntitlementMap;
+    subscribeEntitlements(listener: (entitlements: EntitlementMap) => void): Unsubscribe;
+    /**
+     * Purchases whose money has not arrived, in this session or an earlier one
+     * (FR-101). Synchronous and in-memory, like `getEntitlement`. Added in 0.2.0.
+     */
+    getPendingPurchases(): PendingPurchasesState;
+    /** Pushed only when the set, its status, or its staleness changes (FR-101). */
+    subscribePendingPurchases(listener: (pending: PendingPurchasesState) => void): Unsubscribe;
+    sync(trigger?: SyncTrigger): Promise<SyncOutcome>;
+    restore(): Promise<RestoreOutcome>;
+    getLastSyncedAt(): number | undefined;
+    clearLocalData(): Promise<void>;
+    subscribeEvents(listener: PaymentEventListener): Unsubscribe;
+    purchase(productKey: ProductKey, options?: PurchaseOptions): Promise<PurchaseResult>;
+    /** App-triggered consumption of a consumable (FR-043). */
+    consume(ref: TransactionRef): Promise<FinalizeResult>;
+    /** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
+    getUnfinalized(): UnfinalizedSummary[];
+    getProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+    refreshProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+    changePlan(fromProductKey: ProductKey, toProductKey: ProductKey, mode: ProrationMode, options?: PurchaseOptions): Promise<PurchaseResult>;
+    /** Opens the **store's** management screen; never a self-built one (FR-066). */
+    openSubscriptionManagement(productKey?: ProductKey): Promise<void>;
+    confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
+    /**
+     * Call when the app returns to the foreground (FR-059).
+     *
+     * Left to the app rather than subscribing to `AppState` internally: the package
+     * must not decide what "foreground" means for a host that may be backgrounded
+     * by its own modal, a biometric prompt, or the store's purchase sheet. The
+     * engine rate-limits it regardless (PERF-002).
+     */
+    handleForeground(): Promise<void>;
+}
+/** How many refused operations `status.blockedOperations` keeps. */
+export declare const MAX_BLOCKED_OPERATIONS = 20;
+export declare function createEngine(config: PaymentConfig, deps: EngineDeps): PaymentEngine;
+//# sourceMappingURL=engine.d.ts.map

package/lib/typescript/module/engine/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/engine/engine.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/engine/finalize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 type { FinalizeResult, TransactionRef, UnfinalizedSummary } from '../config/types.js';
+import type { ProviderPort } from '../adapter/port.js';
+import type { ResolvedRetry } from '../core/timers.js';
+import { type PersistedSnapshot } from '../persistence/snapshot.js';
+import type { PaymentEventInput } from '../diagnostics/events.js';
+export interface FinalizerDeps {
+    provider: ProviderPort;
+    retry: ResolvedRetry;
+    /** `timeouts.finalizeAttemptMs`: one acknowledge or consume call may take no longer. */
+    attemptTimeoutMs: number;
+    snapshot: () => PersistedSnapshot;
+    commit: (next: PersistedSnapshot) => void;
+    emit: (event: PaymentEventInput) => void;
+    now: () => number;
+    disposed: () => boolean;
+    /** Injected so a test can run the retry schedule without waiting it out. */
+    setTimeoutFn?: (fn: () => void, ms: number) => FinalizeTimerHandle;
+    clearTimeoutFn?: (handle: FinalizeTimerHandle) => void;
+}
+/** A Node `Timeout` and a browser numeric id are both valid here. */
+type FinalizeTimerHandle = ReturnType<typeof setTimeout> | number;
+export interface Finalizer {
+    /** Records the intent to finalize, then attempts it. Safe to call repeatedly. */
+    enqueue(transactionId: string): Promise<FinalizeResult>;
+    /** Drains every outstanding finalization. Runs at startup and on foreground. */
+    drain(): Promise<void>;
+    /** App-triggered consumption of a consumable (FR-043). */
+    consume(ref: TransactionRef): Promise<FinalizeResult>;
+    /** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
+    unfinalized(): UnfinalizedSummary[];
+    /** Cancels pending retries. Idempotent, called from cleanup. */
+    dispose(): void;
+}
+export declare function createFinalizer(deps: FinalizerDeps): Finalizer;
+export {};
+//# sourceMappingURL=finalize.d.ts.map

package/lib/typescript/module/engine/finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../../../src/engine/finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACX,cAAc,EAEd,cAAc,EACd,kBAAkB,EAClB,MAAM,oBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAgB,CAAC;AAIpD,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,4BAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAAuB,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,wFAAwF;IACxF,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;IAClC,MAAM,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,mBAAmB,CAAC;IACnE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACvD;AAED,qEAAqE;AACrE,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,SAAS;IACzB,iFAAiF;IACjF,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD,gFAAgF;IAChF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,0DAA0D;IAC1D,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACtD,gFAAgF;IAChF,WAAW,IAAI,kBAAkB,EAAE,CAAC;IACpC,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAmR9D"}

package/lib/typescript/module/engine/foreground.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { type AppLifecyclePort, type Unsubscribe } from '@chipmobilesdk/rn-core';
+import type { PaymentEngine } from './engine.js';
+export declare function syncOnForeground(engine: Pick<PaymentEngine, 'handleForeground'>, lifecycle?: AppLifecyclePort): Unsubscribe;
+//# sourceMappingURL=foreground.d.ts.map

package/lib/typescript/module/engine/foreground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreground.d.ts","sourceRoot":"","sources":["../../../../src/engine/foreground.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAGN,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAU,CAAC;AAE9C,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC,EAC/C,SAAS,GAAE,gBAAiC,GAC1C,WAAW,CAKb"}

package/lib/typescript/module/engine/internals.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+import type { ProductKey } from '../config/types.js';
+import type { ResolvedConfig } from '../config/validate.js';
+import type { PaymentEmitter } from '../diagnostics/events.js';
+import type { PersistedSnapshot } from '../persistence/snapshot.js';
+import type { PaymentEngine } from './engine.js';
+export interface EngineInternals {
+    resolvedConfig(): ResolvedConfig;
+    nextCorrelationId(): string;
+    emitter(): PaymentEmitter;
+    snapshot(): PersistedSnapshot;
+    commitSnapshot(next: PersistedSnapshot): void;
+    mayCreateRealTransaction(): boolean;
+    /** Records a purchase refused because this environment may not move real money (FR-014). */
+    recordBlockedOperation(productKey: ProductKey): void;
+}
+export declare function attachEngineInternals(engine: PaymentEngine, internals: EngineInternals): void;
+/** The internals of an engine `createEngine` made. Throws for any other object. */
+export declare function engineInternals(engine: PaymentEngine): EngineInternals;
+//# sourceMappingURL=internals.d.ts.map

package/lib/typescript/module/engine/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../../../../src/engine/internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAU,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC/B,cAAc,IAAI,cAAc,CAAC;IACjC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,OAAO,IAAI,cAAc,CAAC;IAC1B,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9C,wBAAwB,IAAI,OAAO,CAAC;IACpC,4FAA4F;IAC5F,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACrD;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI,CAE7F;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAMtE"}

package/lib/typescript/module/engine/pending.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 type { ResolvedConfig } from '../config/validate.js';
+import type { PendingPurchasesState, PendingResolution, ProductKey } from '../config/types.js';
+import type { PersistedSnapshot } from '../persistence/snapshot.js';
+export declare const UNKNOWN_PENDING: PendingPurchasesState;
+/**
+ * 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 declare function derivePending(input: {
+    config: ResolvedConfig;
+    snapshot: PersistedSnapshot;
+    hasSynced: boolean;
+    now: number;
+}): PendingPurchasesState;
+export interface PendingTransition {
+    readonly productKey: ProductKey;
+    readonly outcome: PendingResolution;
+}
+/**
+ * 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 declare function pendingTransitions(previous: PersistedSnapshot, next: PersistedSnapshot, config: ResolvedConfig, endReason: (transactionId: string) => 'cancelled' | 'expired' | undefined): PendingTransition[];
+/** Whether a listener has anything new to hear. */
+export declare function samePending(a: PendingPurchasesState, b: PendingPurchasesState): boolean;
+//# sourceMappingURL=pending.d.ts.map

package/lib/typescript/module/engine/pending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.d.ts","sourceRoot":"","sources":["../../../../src/engine/pending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AACzD,OAAO,KAAK,EAEX,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,MAAM,oBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAAyB,CAAC;AAGjE,eAAO,MAAM,eAAe,EAAE,qBAI7B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACpC,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACZ,GAAG,qBAAqB,CAoBxB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,GAAG,SAAS,GACvE,iBAAiB,EAAE,CAgBrB;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,CAAC,EAAE,qBAAqB,EAAE,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAWvF"}

package/lib/typescript/module/engine/products.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Product query, normalization, and the in-memory price cache (US11).
+ *
+ * Two rules shape this module:
+ *
+ * - **Prices come from the store, formatted.** An app must never build a price
+ *   string (FR-028): only the store knows the right currency symbol, its
+ *   placement, the decimal separator, and the grouping for the user's locale. A
+ *   hand-built "$9.99" is wrong in most of the world.
+ * - **Offer eligibility is reported, never computed.** The store decides who
+ *   qualifies for a trial or an introductory price (FR-026). Guessing locally
+ *   would promise a trial the store then refuses at checkout.
+ *
+ * The cache is in **memory only** and short-lived. Persisting prices would risk
+ * showing a stale one as current in a later session, and a paywall is exactly
+ * where that matters.
+ */
+import type { ProductKey, ProductType } from '../config/types.js';
+import type { ResolvedConfig } from '../config/validate.js';
+import type { ProviderPort } from '../adapter/port.js';
+import { PaymentError } from '../diagnostics/errors.js';
+import type { PaymentEventInput } from '../diagnostics/events.js';
+export interface Offer {
+    offerKey: string;
+    billingPeriod: string;
+    formattedPrice: string;
+    priceAmountMicros: number;
+    currencyCode: string;
+    trialPeriod?: string;
+    introductoryPrice?: {
+        formattedPrice: string;
+        period: string;
+        cycles: number;
+    };
+    /** As the store determined it. Never computed here (FR-026). */
+    isEligible: boolean;
+}
+export interface ProductInfo {
+    productKey: ProductKey;
+    productType: ProductType;
+    title: string;
+    description: string;
+    /** Store-formatted and locale-correct. For display (FR-024). */
+    formattedPrice: string;
+    currencyCode: string;
+    /** For comparison and sorting only — never for display (FR-028). */
+    priceAmountMicros: number;
+    offers: Offer[];
+}
+/** Why a requested product produced nothing, kept distinct from a network error. */
+export type MissingProductReason = 'not_in_catalog'
+/** Does not exist, is unapproved, or is not sold in this country (FR-027). */
+ | 'not_available_from_store';
+export interface MissingProduct {
+    productKey: ProductKey;
+    reason: MissingProductReason;
+}
+export type ProductQueryResult = {
+    ok: true;
+    products: ProductInfo[];
+    /** Reported separately so an app shows an explanation, not an empty row. */
+    missing: MissingProduct[];
+    fromCache: boolean;
+} | {
+    ok: false;
+    error: PaymentError;
+};
+export interface ProductsDeps {
+    resolved: ResolvedConfig;
+    provider: ProviderPort;
+    emit: (event: PaymentEventInput) => void;
+    now: () => number;
+}
+export interface Products {
+    get(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+    /** Bypasses the cache; for a pull-to-refresh on a paywall (FR-029). */
+    refresh(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+    /** Drops the cache, e.g. after a locale or account change. */
+    invalidate(): void;
+}
+export declare function createProducts(deps: ProductsDeps): Products;
+//# sourceMappingURL=products.d.ts.map

package/lib/typescript/module/engine/products.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"products.d.ts","sourceRoot":"","sources":["../../../../src/engine/products.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,oBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,oBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAAuB,CAAC;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAAuB,CAAC;AAG/D,MAAM,WAAW,KAAK;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;IACF,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAC7B,gBAAgB;AAClB,8EAA8E;GAC5E,0BAA0B,CAAC;AAE9B,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,4EAA4E;IAC5E,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CAClB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzC,GAAG,EAAE,MAAM,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC5D,uEAAuE;IACvE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChE,8DAA8D;IAC9D,UAAU,IAAI,IAAI,CAAC;CACnB;AAiCD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CA8J3D"}