@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/adapter/port.ts

@@ -0,0 +1,198 @@
+/**
+ * The provider port — **private**, never exported from `src/index.ts`.
+ *
+ * This is the boundary between the platform-neutral engine and a store-specific
+ * adapter. It exists to make three things true:
+ *
+ * 1. No store type reaches the public surface, because only the adapter ever
+ *    sees one (FR-002).
+ * 2. An iOS adapter can be added by implementing this interface, changing no
+ *    consumer call (FR-007).
+ * 3. The fake store is a drop-in replacement, so every outcome and ordering is
+ *    testable with no device, network, or store account (NFR-007).
+ *
+ * `Provider*` types are the port's **own** normalized shapes, not the binding's.
+ * The adapter translates; nothing above it sees a `react-native-iap` value.
+ */
+
+import type { ProductType, Unsubscribe } from '../config/types';
+
+/** A store's own product identifier. Confined to configuration and this layer. */
+export type StoreProductId = string;
+
+/** Opaque handle the store uses to identify a transaction for finalization. */
+export type ProviderToken = string;
+
+export type ProviderPurchaseState = 'purchased' | 'pending' | 'unspecified';
+
+export interface ProviderOffer {
+	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 locally (FR-026). */
+	isEligible: boolean;
+}
+
+export interface ProviderProduct {
+	storeProductId: StoreProductId;
+	productType: ProductType;
+	title: string;
+	description: string;
+	formattedPrice: string;
+	currencyCode: string;
+	priceAmountMicros: number;
+	offers: ProviderOffer[];
+}
+
+export interface ProviderPurchase {
+	storeProductId: StoreProductId;
+	transactionId: string;
+	token: ProviderToken;
+	state: ProviderPurchaseState;
+	purchasedAt: number;
+	isAcknowledged: boolean;
+	/** Subscription-only, and only where the platform supplies it. */
+	expiresAt?: number;
+	willAutoRenew?: boolean;
+	/**
+	 * Opaque material for the app's backend. Passed to the validation hook and
+	 * **never** logged or put in an event (FR-074).
+	 */
+	verificationPayload?: string;
+}
+
+export type ProviderFailureReason =
+	| 'user_cancelled'
+	| 'already_owned'
+	| 'ineligible'
+	| 'unknown_product'
+	| 'product_unavailable_in_region'
+	| 'not_ready'
+	| 'network_error'
+	| 'timeout'
+	| 'store_error';
+
+export type ProviderConnectOutcome =
+	| { ok: true }
+	| {
+			ok: false;
+			reason: 'no_billing_service' | 'billing_service_outdated' | 'platform_unsupported' | 'store_error';
+			retryable: boolean;
+	  };
+
+export type ProviderPurchaseOutcome =
+	| { ok: true; purchase: ProviderPurchase }
+	| { ok: false; reason: ProviderFailureReason; detail?: string };
+
+export type ProviderPriceChangeOutcome =
+	| { ok: true; confirmed: boolean }
+	| { ok: false; reason: ProviderFailureReason };
+
+export interface ProviderPurchaseRequest {
+	storeProductId: StoreProductId;
+	productType: ProductType;
+	offerKey?: string;
+	/** App-supplied, passed straight through. Never generated or stored (FR-034). */
+	obfuscatedAccountId?: string;
+	/** Plan change: the currently-active subscription being replaced. */
+	replaceStoreProductId?: StoreProductId;
+	prorationMode?: string;
+}
+
+/**
+ * What the platform can actually do.
+ *
+ * This is how honest degradation is enforced rather than left to good intentions.
+ * `reportsGraceAndHoldDistinctly` is `false` on Android, because client-side Play
+ * Billing genuinely cannot separate the two: a grace-period subscription is still
+ * returned as active, and one in account hold stops being returned at all, making
+ * it indistinguishable from expired, cancelled, or refunded.
+ *
+ * The entitlement layer reads this flag and reports `indeterminate` instead of
+ * fabricating a distinction from `willAutoRenew` — which cannot separate grace
+ * from cancelled-but-valid either. Claiming otherwise would breach FR-058.
+ */
+export interface ProviderCapabilities {
+	supportsSubscriptions: boolean;
+	supportsPlanChange: boolean;
+	supportsPriceChangeConfirmation: boolean;
+	reportsGraceAndHoldDistinctly: boolean;
+	/** Externally-initiated purchases: false on Android, true for a future iOS adapter. */
+	supportsExternalTransactions: boolean;
+	/**
+	 * Whether this adapter can move real money.
+	 *
+	 * `true` for the store adapter, `false` for the fake store. This is what lets
+	 * FR-014's block be precise: the engine refuses a purchase when the
+	 * environment may not create a production transaction **and** the provider is
+	 * one that actually would. Without it the guard would either block the test
+	 * suite — which must be able to buy things — or wave real purchases through in
+	 * a development build.
+	 */
+	createsRealTransactions: boolean;
+}
+
+export interface ProviderPort {
+	connect(): Promise<ProviderConnectOutcome>;
+	disconnect(): Promise<void>;
+
+	/**
+	 * Reports a **real** disconnect.
+	 *
+	 * The engine must never infer connectivity from an unrelated call failing.
+	 * The upstream binding historically left its `connected` flag true after a
+	 * disconnect and had a `reconnect()` that could report success without
+	 * rebuilding anything (openiap#408), so detection belongs here, behind a
+	 * contract test.
+	 */
+	observeConnection(
+		listener: (connected: boolean, reason?: string) => void,
+	): Unsubscribe;
+
+	queryProducts(
+		storeProductIds: StoreProductId[],
+		productType: ProductType,
+	): Promise<ProviderProduct[]>;
+
+	/** Owned and pending purchases. Pending ones are **flagged, never filtered** (FR-037). */
+	queryOwned(): Promise<ProviderPurchase[]>;
+
+	launchPurchase(
+		request: ProviderPurchaseRequest,
+	): Promise<ProviderPurchaseOutcome>;
+
+	/** Store-initiated updates, including a pending purchase settling later (FR-039). */
+	observePurchases(listener: (purchase: ProviderPurchase) => void): Unsubscribe;
+
+	/**
+	 * Why a pending purchase the store has stopped reporting ended, if the store
+	 * says (FR-102). Optional, and synchronous because it is asked about a
+	 * transaction the store already dropped, not fetched.
+	 *
+	 * Play gives no reason — a declined or abandoned pending purchase simply
+	 * vanishes from `queryOwned` — so the Android adapter leaves this out and the
+	 * engine reports `cancelled`. It is never inferred from age: guessing the
+	 * store's pending window would be inventing a fact.
+	 */
+	pendingEndReason?(transactionId: string): 'cancelled' | 'expired' | undefined;
+
+	/** Must be safe to call for an already-finalized transaction (FR-044). */
+	acknowledge(token: ProviderToken): Promise<void>;
+	/** Must be safe to call twice; the item is granted once (FR-044). */
+	consume(token: ProviderToken): Promise<void>;
+
+	openSubscriptionManagement(storeProductId?: StoreProductId): Promise<void>;
+	confirmPriceChange(
+		storeProductId: StoreProductId,
+	): Promise<ProviderPriceChangeOutcome>;
+
+	capabilities(): ProviderCapabilities;
+}

package/src/config/types.ts

@@ -0,0 +1,295 @@
+/**
+ * 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;
+	finalizeAttemptMs?: 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;
+}
+
+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[];
+}