@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/config/types.ts

@@ -1,310 +1,298 @@
-/**
- * Public configuration and catalog types.
- *
- * Nothing here names Google Play Billing, `react-native-iap`, or any store
- * concept (FR-002). Apps speak in **product keys** and **entitlement keys** they
- * chose themselves; store product identifiers appear only inside catalog
- * configuration, never in app logic (FR-003).
- */
-
-/** An app-chosen logical entitlement, e.g. `no_ads`. What business logic asks about. */
-export type EntitlementKey = string;
-
-/** An app-chosen logical product, e.g. `premium_yearly`. Never a store identifier. */
-export type ProductKey = string;
-
-/**
- * How a product behaves once bought.
- *
- * `one_time_permanent` — bought once, kept forever.
- * `one_time_consumable` — bought, used up by the app, buyable again (FR-043).
- * `subscription` — recurring, with its own lifecycle (FR-048).
- */
-export type ProductType =
-	| 'one_time_permanent'
-	| 'one_time_consumable'
-	| 'subscription';
-
-/** Store identifiers per platform. iOS is optional and additive (FR-007). */
-export interface StoreProductIds {
-	android?: string;
-	ios?: string;
-}
-
-/** One product the app sells, and what it unlocks. */
-export interface CatalogEntry {
-	productKey: ProductKey;
-	productType: ProductType;
-	storeProductIds: StoreProductIds;
-	/** Entitlement keys this product confers. Many-to-many is supported (FR-010). */
-	grants: EntitlementKey[];
-}
-
-/** Separately configurable, and the basis of the production-transaction guard. */
-export type Environment = 'development' | 'test' | 'production';
-
-/**
- * Entitlement policy for a subscription whose renewal payment failed.
- *
- * Kept configurable because it is a business decision, not a technical constant
- * (FR-049). See `entitlements/policy.ts` for the defaults and why.
- */
-export type LapsePolicy = 'grant' | 'withhold';
-
-/** What to do when a configured validation hook cannot be reached (FR-072). */
-export type ValidationUnavailablePolicy = 'grant_and_queue' | 'withhold';
-
-/** Returned by every subscribe call. Idempotent and safe to call twice (FR-006). */
-export type Unsubscribe = () => void;
-
-export interface TimeoutConfig {
-	connectMs?: number;
-	productQueryMs?: number;
-	syncMs?: number;
-	/** Covers opening the store surface only. Time the user spends in it is not counted (FR-035). */
-	purchaseLaunchMs?: number;
-	/** Bounds each acknowledge or consume call; a timed-out attempt is retried. */
-	finalizeAttemptMs?: number;
-	/**
-	 * Bounds the app's `validateTransaction` hook. A hook that does not answer in
-	 * time is treated as unavailable, exactly like one that throws (FR-072b).
-	 * Added in 0.3.2.
-	 */
-	validateMs?: number;
-}
-
-export interface RetryConfig {
-	reconnect?: BackoffConfig;
-	finalize?: BackoffConfig;
-}
-
-export interface BackoffConfig {
-	initialDelayMs?: number;
-	maxDelayMs?: number;
-	factor?: number;
-	/** Attempts per session. Finalize is resumed next session rather than abandoned (FR-045). */
-	maxAttempts?: number;
-	jitter?: boolean;
-}
-
-/** What the app's backend is asked to decide about (FR-069). */
-export interface ValidationCandidate {
-	productKey: ProductKey;
-	productType: ProductType;
-	/** Opaque verification material for the backend. Never logged (FR-074). */
-	verificationPayload: string;
-	/** Ties this decision to one purchase cycle in the event stream (FR-076). */
-	correlationId: string;
-	/**
-	 * The store's identifier for this transaction (Play's order id). Not a secret,
-	 * and the only handle a backend has on re-validation, where
-	 * `verificationPayload` is empty because it is never persisted. Added in 0.3.2.
-	 */
-	transactionId: string;
-	/** Which store issued the transaction, so a backend picks the right API. Added in 0.3.2. */
-	platform: 'android' | 'ios';
-}
-
-export interface ValidationDecision {
-	approved: boolean;
-	/** Optional app-supplied reason, surfaced as a distinguishable outcome (FR-071). */
-	reason?: string;
-}
-
-export type ValidationHook = (
-	candidate: ValidationCandidate,
-) => Promise<ValidationDecision>;
-
-/** Diagnostics sink. Deliberately not tied to any analytics vendor (FR-080). */
-export interface LoggerAdapter {
-	debug?(message: string, meta?: Record<string, unknown>): void;
-	warn?(message: string, meta?: Record<string, unknown>): void;
-	error?(message: string, meta?: Record<string, unknown>): void;
-}
-
-export interface PaymentConfig {
-	catalog: CatalogEntry[];
-	/** Entitlement keys the app intends to query. Used for orphan detection (FR-011). */
-	entitlements: EntitlementKey[];
-	environment: Environment;
-	/**
-	 * Whether the running binary is a production build.
-	 *
-	 * Supplied by the app because only the app knows how it was built. Drives the
-	 * fail-closed guard: a non-production build declaring `production` must not
-	 * proceed (FR-015).
-	 */
-	isProductionBuild: boolean;
-	/**
-	 * Global sell switch. When false, purchases report `disabled` but entitlements
-	 * already held stay readable — turning off selling is not the same as taking
-	 * away what someone bought (FR-012).
-	 */
-	enabled?: boolean;
-	gracePolicy?: LapsePolicy;
-	holdPolicy?: LapsePolicy;
-	staleAfterMs?: number;
-	productCacheTtlMs?: number;
-	foregroundSyncMinIntervalMs?: number;
-	timeouts?: TimeoutConfig;
-	retry?: RetryConfig;
-	/**
-	 * Opaque cache-partition key (FR-057a).
-	 *
-	 * Not a user identifier: the package never interprets it, transmits it, or
-	 * attaches it to a transaction. Changing it makes the previous snapshot
-	 * unreadable, so a second app-account user cannot inherit the first one's
-	 * entitlements even if the app forgets to call `clearLocalData`.
-	 */
-	scopeToken?: string;
-	validateTransaction?: ValidationHook;
-	onValidationUnavailable?: ValidationUnavailablePolicy;
-	logger?: LoggerAdapter;
-}
-
-/** Opaque handle for a transaction. Exposes no raw store record (FR-051). */
-export interface TransactionRef {
-	readonly transactionId: string;
-	readonly productKey: ProductKey;
-}
-
-export interface PurchaseOptions {
-	/**
-	 * The app's obfuscated account identifier, passed straight through to the
-	 * store for fraud prevention. Never generated, inferred, or persisted by the
-	 * package (FR-034), and distinct from `scopeToken`.
-	 */
-	obfuscatedAccountId?: string;
-	/** Which pricing option to buy, for a subscription with several offers. */
-	offerKey?: string;
-}
-
-/**
- * Every way a purchase can end (FR-005).
- *
- * A discriminated union rather than a boolean plus an error, because the app has
- * to tell these apart: `user_cancelled` is a normal outcome to stay quiet about,
- * `pending` means wait, `already_owned` means re-sync, and `store_error` means
- * show something. Collapsing them is how apps end up reporting a cancellation as
- * a failure.
- */
-export type PurchaseResult =
-	| { kind: 'success'; productKey: ProductKey; transaction: TransactionRef }
-	/** Money has not arrived. No entitlement is granted (FR-037). */
-	| { kind: 'pending'; productKey: ProductKey; transaction: TransactionRef }
-	/** Normal, not an error. Must never be recorded as a technical failure (FR-032). */
-	| { kind: 'user_cancelled'; productKey: ProductKey }
-	/** Triggers a re-sync: this is how a reinstall repairs itself (FR-033). */
-	| { kind: 'already_owned'; productKey: ProductKey }
-	| { kind: 'ineligible'; productKey: ProductKey }
-	| { kind: 'unknown_product'; productKey: ProductKey }
-	| { kind: 'product_unavailable_in_region'; productKey: ProductKey }
-	/** Global sell switch is off (FR-012). */
-	| { kind: 'disabled' }
-	| { kind: 'not_ready'; status: PaymentStatusKind }
-	| { kind: 'unsupported' }
-	/** A second purchase while one is open. Refused, never queued (FR-031). */
-	| { kind: 'purchase_in_progress' }
-	/** Refused because this build may not create a production transaction (FR-014). */
-	| { kind: 'environment_blocked'; productKey: ProductKey; environment: Environment }
-	/** The app's backend said no (FR-071). Distinguishable from a network failure. */
-	| { kind: 'validation_rejected'; productKey: ProductKey; reason?: string }
-	| { kind: 'timeout'; productKey: ProductKey }
-	| { kind: 'network_error'; productKey: ProductKey }
-	| { kind: 'store_error'; productKey: ProductKey; code: string };
-
-/**
- * A purchase whose money has not arrived yet (FR-101), added in 0.2.0.
- *
- * One entry per product key, whatever number of pending transactions the store
- * reports for it. Carries no transaction id, token, or store object (FR-051) —
- * enough to render "payment pending" and to withhold Buy, nothing to act on.
- */
-export interface PendingPurchase {
-	readonly productKey: ProductKey;
-	/** When the store reports the purchase was made, in epoch milliseconds. Earliest if several. */
-	readonly since: number;
-}
-
-/**
- * The pending set, with how far it can be trusted (FR-101, FR-103).
- *
- * Read `status` first. `unknown` follows the entitlement rule exactly: never
- * synced, or synced longer ago than `staleAfterMs`. Under `unknown`, `purchases`
- * still lists what the last good sync saw, but an empty list there does **not**
- * mean "nothing is pending" — the same reason an `unknown` entitlement is not
- * `not_entitled`.
- */
-export interface PendingPurchasesState {
-	readonly status: 'known' | 'unknown';
-	readonly purchases: readonly PendingPurchase[];
-	/** True once the snapshot is older than `staleAfterMs`; `status` is then `unknown`. */
-	readonly isStale: boolean;
-}
-
-/**
- * How a pending purchase ended (FR-102).
- *
- * `settled` — the money arrived; an entitlement grant, if the product confers one,
- * follows. `expired` — the store reported that the pending window ran out.
- * `cancelled` — it ended without payment for any other reason, **including when
- * the store gives none**: Play simply stops reporting a declined or abandoned
- * pending purchase, so on Android every unpaid end is `cancelled`.
- */
-export type PendingResolution = 'settled' | 'cancelled' | 'expired';
-
-/** Outcome of finalizing or consuming a transaction (FR-044). */
-export type FinalizeResult =
-	| { kind: 'finalized' }
-	/** Already done. Idempotent by design, so this is a success, not an error. */
-	| { kind: 'already_finalized' }
-	| { kind: 'unknown_transaction' }
-	/** Queued for bounded retry; the condition stays observable (FR-045). */
-	| { kind: 'retry_scheduled'; attempts: number }
-	| { kind: 'failed'; code: string };
-
-/** A paid transaction not yet settled with the store, surfaced so it is not swallowed. */
-export interface UnfinalizedSummary {
-	productKey: ProductKey;
-	transactionId: string;
-	attempts: number;
-	purchasedAt: number;
-}
-
-/** Observable package status (FR-019). */
-export type PaymentStatusKind =
-	| 'not_started'
-	| 'connecting'
-	| 'ready'
-	| 'disabled'
-	| 'unavailable'
-	| 'failed';
-
-/** Why selling is impossible here, kept distinguishable so apps can tell users why (FR-021). */
-export type UnavailableReason =
-	| 'no_billing_service'
-	| 'billing_service_outdated'
-	| 'platform_unsupported';
-
-/**
- * A purchase the package refused because it could have been a real charge
- * outside production (FR-014).
- *
- * Exposed in status rather than only logged so an automated test can assert the
- * block happened, which is the difference between a guarantee and a hope.
- */
-export interface BlockedOperation {
-	productKey: ProductKey;
-	environment: Environment;
-	at: number;
-}
-
-export interface PaymentStatus {
-	kind: PaymentStatusKind;
-	unavailableReason?: UnavailableReason;
-	/** Whether retrying initialization could plausibly help (FR-024). */
-	retryable?: boolean;
-	/** Reconnect attempts made in this session, so a retry storm is visible (FR-020). */
-	reconnectAttempts?: number;
-	blockedOperations: BlockedOperation[];
-}
+/**
+ * Public configuration and catalog types.
+ *
+ * Nothing here names Google Play Billing, `react-native-iap`, or any store
+ * concept (FR-002). Apps speak in **product keys** and **entitlement keys** they
+ * chose themselves; store product identifiers appear only inside catalog
+ * configuration, never in app logic (FR-003).
+ */
+
+/** An app-chosen logical entitlement, e.g. `no_ads`. What business logic asks about. */
+export type EntitlementKey = string;
+
+/** An app-chosen logical product, e.g. `premium_yearly`. Never a store identifier. */
+export type ProductKey = string;
+
+/**
+ * How a product behaves once bought.
+ *
+ * `one_time_permanent` — bought once, kept forever.
+ * `one_time_consumable` — bought, used up by the app, buyable again (FR-043).
+ * `subscription` — recurring, with its own lifecycle (FR-048).
+ */
+export type ProductType = 'one_time_permanent' | 'one_time_consumable' | 'subscription';
+
+/** Store identifiers per platform. iOS is optional and additive (FR-007). */
+export interface StoreProductIds {
+	android?: string;
+	ios?: string;
+}
+
+/** One product the app sells, and what it unlocks. */
+export interface CatalogEntry {
+	productKey: ProductKey;
+	productType: ProductType;
+	storeProductIds: StoreProductIds;
+	/** Entitlement keys this product confers. Many-to-many is supported (FR-010). */
+	grants: EntitlementKey[];
+}
+
+/** Separately configurable, and the basis of the production-transaction guard. */
+export type Environment = 'development' | 'test' | 'production';
+
+/**
+ * Entitlement policy for a subscription whose renewal payment failed.
+ *
+ * Kept configurable because it is a business decision, not a technical constant
+ * (FR-049). See `entitlements/policy.ts` for the defaults and why.
+ */
+export type LapsePolicy = 'grant' | 'withhold';
+
+/** What to do when a configured validation hook cannot be reached (FR-072). */
+export type ValidationUnavailablePolicy = 'grant_and_queue' | 'withhold';
+
+/** Returned by every subscribe call. Idempotent and safe to call twice (FR-006). */
+export type Unsubscribe = () => void;
+
+export interface TimeoutConfig {
+	connectMs?: number;
+	productQueryMs?: number;
+	syncMs?: number;
+	/** Covers opening the store surface only. Time the user spends in it is not counted (FR-035). */
+	purchaseLaunchMs?: number;
+	/** Bounds each acknowledge or consume call; a timed-out attempt is retried. */
+	finalizeAttemptMs?: number;
+	/**
+	 * Bounds the app's `validateTransaction` hook. A hook that does not answer in
+	 * time is treated as unavailable, exactly like one that throws (FR-072b).
+	 * Added in 0.3.2.
+	 */
+	validateMs?: number;
+}
+
+export interface RetryConfig {
+	reconnect?: BackoffConfig;
+	finalize?: BackoffConfig;
+}
+
+export interface BackoffConfig {
+	initialDelayMs?: number;
+	maxDelayMs?: number;
+	factor?: number;
+	/** Attempts per session. Finalize is resumed next session rather than abandoned (FR-045). */
+	maxAttempts?: number;
+	jitter?: boolean;
+}
+
+/** What the app's backend is asked to decide about (FR-069). */
+export interface ValidationCandidate {
+	productKey: ProductKey;
+	productType: ProductType;
+	/** Opaque verification material for the backend. Never logged (FR-074). */
+	verificationPayload: string;
+	/** Ties this decision to one purchase cycle in the event stream (FR-076). */
+	correlationId: string;
+	/**
+	 * The store's identifier for this transaction (Play's order id). Not a secret,
+	 * and the only handle a backend has on re-validation, where
+	 * `verificationPayload` is empty because it is never persisted. Added in 0.3.2.
+	 */
+	transactionId: string;
+	/** Which store issued the transaction, so a backend picks the right API. Added in 0.3.2. */
+	platform: 'android' | 'ios';
+}
+
+export interface ValidationDecision {
+	approved: boolean;
+	/** Optional app-supplied reason, surfaced as a distinguishable outcome (FR-071). */
+	reason?: string;
+}
+
+export type ValidationHook = (candidate: ValidationCandidate) => Promise<ValidationDecision>;
+
+/** Diagnostics sink. Deliberately not tied to any analytics vendor (FR-080). */
+export interface LoggerAdapter {
+	debug?(message: string, meta?: Record<string, unknown>): void;
+	warn?(message: string, meta?: Record<string, unknown>): void;
+	error?(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface PaymentConfig {
+	catalog: CatalogEntry[];
+	/** Entitlement keys the app intends to query. Used for orphan detection (FR-011). */
+	entitlements: EntitlementKey[];
+	environment: Environment;
+	/**
+	 * Whether the running binary is a production build.
+	 *
+	 * Supplied by the app because only the app knows how it was built. Drives the
+	 * fail-closed guard: a non-production build declaring `production` must not
+	 * proceed (FR-015).
+	 */
+	isProductionBuild: boolean;
+	/**
+	 * Global sell switch. When false, purchases report `disabled` but entitlements
+	 * already held stay readable — turning off selling is not the same as taking
+	 * away what someone bought (FR-012).
+	 */
+	enabled?: boolean;
+	gracePolicy?: LapsePolicy;
+	holdPolicy?: LapsePolicy;
+	staleAfterMs?: number;
+	productCacheTtlMs?: number;
+	foregroundSyncMinIntervalMs?: number;
+	timeouts?: TimeoutConfig;
+	retry?: RetryConfig;
+	/**
+	 * Opaque cache-partition key (FR-057a).
+	 *
+	 * Not a user identifier: the package never interprets it, transmits it, or
+	 * attaches it to a transaction. Changing it makes the previous snapshot
+	 * unreadable, so a second app-account user cannot inherit the first one's
+	 * entitlements even if the app forgets to call `clearLocalData`.
+	 */
+	scopeToken?: string;
+	validateTransaction?: ValidationHook;
+	onValidationUnavailable?: ValidationUnavailablePolicy;
+	logger?: LoggerAdapter;
+}
+
+/** Opaque handle for a transaction. Exposes no raw store record (FR-051). */
+export interface TransactionRef {
+	readonly transactionId: string;
+	readonly productKey: ProductKey;
+}
+
+export interface PurchaseOptions {
+	/**
+	 * The app's obfuscated account identifier, passed straight through to the
+	 * store for fraud prevention. Never generated, inferred, or persisted by the
+	 * package (FR-034), and distinct from `scopeToken`.
+	 */
+	obfuscatedAccountId?: string;
+	/** Which pricing option to buy, for a subscription with several offers. */
+	offerKey?: string;
+}
+
+/**
+ * Every way a purchase can end (FR-005).
+ *
+ * A discriminated union rather than a boolean plus an error, because the app has
+ * to tell these apart: `user_cancelled` is a normal outcome to stay quiet about,
+ * `pending` means wait, `already_owned` means re-sync, and `store_error` means
+ * show something. Collapsing them is how apps end up reporting a cancellation as
+ * a failure.
+ */
+export type PurchaseResult =
+	| { kind: 'success'; productKey: ProductKey; transaction: TransactionRef }
+	/** Money has not arrived. No entitlement is granted (FR-037). */
+	| { kind: 'pending'; productKey: ProductKey; transaction: TransactionRef }
+	/** Normal, not an error. Must never be recorded as a technical failure (FR-032). */
+	| { kind: 'user_cancelled'; productKey: ProductKey }
+	/** Triggers a re-sync: this is how a reinstall repairs itself (FR-033). */
+	| { kind: 'already_owned'; productKey: ProductKey }
+	| { kind: 'ineligible'; productKey: ProductKey }
+	| { kind: 'unknown_product'; productKey: ProductKey }
+	| { kind: 'product_unavailable_in_region'; productKey: ProductKey }
+	/** Global sell switch is off (FR-012). */
+	| { kind: 'disabled' }
+	| { kind: 'not_ready'; status: PaymentStatusKind }
+	| { kind: 'unsupported' }
+	/** A second purchase while one is open. Refused, never queued (FR-031). */
+	| { kind: 'purchase_in_progress' }
+	/** Refused because this build may not create a production transaction (FR-014). */
+	| { kind: 'environment_blocked'; productKey: ProductKey; environment: Environment }
+	/** The app's backend said no (FR-071). Distinguishable from a network failure. */
+	| { kind: 'validation_rejected'; productKey: ProductKey; reason?: string }
+	| { kind: 'timeout'; productKey: ProductKey }
+	| { kind: 'network_error'; productKey: ProductKey }
+	| { kind: 'store_error'; productKey: ProductKey; code: string };
+
+/**
+ * A purchase whose money has not arrived yet (FR-101), added in 0.2.0.
+ *
+ * One entry per product key, whatever number of pending transactions the store
+ * reports for it. Carries no transaction id, token, or store object (FR-051) —
+ * enough to render "payment pending" and to withhold Buy, nothing to act on.
+ */
+export interface PendingPurchase {
+	readonly productKey: ProductKey;
+	/** When the store reports the purchase was made, in epoch milliseconds. Earliest if several. */
+	readonly since: number;
+}
+
+/**
+ * The pending set, with how far it can be trusted (FR-101, FR-103).
+ *
+ * Read `status` first. `unknown` follows the entitlement rule exactly: never
+ * synced, or synced longer ago than `staleAfterMs`. Under `unknown`, `purchases`
+ * still lists what the last good sync saw, but an empty list there does **not**
+ * mean "nothing is pending" — the same reason an `unknown` entitlement is not
+ * `not_entitled`.
+ */
+export interface PendingPurchasesState {
+	readonly status: 'known' | 'unknown';
+	readonly purchases: readonly PendingPurchase[];
+	/** True once the snapshot is older than `staleAfterMs`; `status` is then `unknown`. */
+	readonly isStale: boolean;
+}
+
+/**
+ * How a pending purchase ended (FR-102).
+ *
+ * `settled` — the money arrived; an entitlement grant, if the product confers one,
+ * follows. `expired` — the store reported that the pending window ran out.
+ * `cancelled` — it ended without payment for any other reason, **including when
+ * the store gives none**: Play simply stops reporting a declined or abandoned
+ * pending purchase, so on Android every unpaid end is `cancelled`.
+ */
+export type PendingResolution = 'settled' | 'cancelled' | 'expired';
+
+/** Outcome of finalizing or consuming a transaction (FR-044). */
+export type FinalizeResult =
+	| { kind: 'finalized' }
+	/** Already done. Idempotent by design, so this is a success, not an error. */
+	| { kind: 'already_finalized' }
+	| { kind: 'unknown_transaction' }
+	/** Queued for bounded retry; the condition stays observable (FR-045). */
+	| { kind: 'retry_scheduled'; attempts: number }
+	| { kind: 'failed'; code: string };
+
+/** A paid transaction not yet settled with the store, surfaced so it is not swallowed. */
+export interface UnfinalizedSummary {
+	productKey: ProductKey;
+	transactionId: string;
+	attempts: number;
+	purchasedAt: number;
+}
+
+/** Observable package status (FR-019). */
+export type PaymentStatusKind =
+	'not_started' | 'connecting' | 'ready' | 'disabled' | 'unavailable' | 'failed';
+
+/** Why selling is impossible here, kept distinguishable so apps can tell users why (FR-021). */
+export type UnavailableReason =
+	'no_billing_service' | 'billing_service_outdated' | 'platform_unsupported';
+
+/**
+ * A purchase the package refused because it could have been a real charge
+ * outside production (FR-014).
+ *
+ * Exposed in status rather than only logged so an automated test can assert the
+ * block happened, which is the difference between a guarantee and a hope.
+ */
+export interface BlockedOperation {
+	productKey: ProductKey;
+	environment: Environment;
+	at: number;
+}
+
+export interface PaymentStatus {
+	kind: PaymentStatusKind;
+	unavailableReason?: UnavailableReason;
+	/** Whether retrying initialization could plausibly help (FR-024). */
+	retryable?: boolean;
+	/** Reconnect attempts made in this session, so a retry storm is visible (FR-020). */
+	reconnectAttempts?: number;
+	blockedOperations: BlockedOperation[];
+}