@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/adapter/port.ts

@@ -1,215 +1,209 @@
-/**
- * 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 token of the active subscription being replaced. The store
-	 * migrates *that* purchase rather than creating a second one (FR-065).
-	 */
-	replacePurchaseToken?: ProviderToken;
-	/** Plan change: the store product id of the 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;
-	/**
-	 * Whether `launchPurchase` settles only once the user has left the store's
-	 * purchase surface.
-	 *
-	 * `true` for the Play adapter: the binding gives no "surface opened" signal and
-	 * reports the outcome only when the flow ends, so the time the user spends in
-	 * Play is inside the call. The engine then does not apply its launch timeout,
-	 * which would otherwise cancel a user still choosing a payment method (FR-035).
-	 * The binding always ends the flow with a result or an error, so the call
-	 * cannot hang. `false` for the fake store, whose launch returns at once.
-	 */
-	purchaseOutcomeIncludesStoreTime: 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;
-}
+/**
+ * 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 token of the active subscription being replaced. The store
+	 * migrates *that* purchase rather than creating a second one (FR-065).
+	 */
+	replacePurchaseToken?: ProviderToken;
+	/** Plan change: the store product id of the 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;
+	/**
+	 * Whether `launchPurchase` settles only once the user has left the store's
+	 * purchase surface.
+	 *
+	 * `true` for the Play adapter: the binding gives no "surface opened" signal and
+	 * reports the outcome only when the flow ends, so the time the user spends in
+	 * Play is inside the call. The engine then does not apply its launch timeout,
+	 * which would otherwise cancel a user still choosing a payment method (FR-035).
+	 * The binding always ends the flow with a result or an error, so the call
+	 * cannot hang. `false` for the fake store, whose launch returns at once.
+	 */
+	purchaseOutcomeIncludesStoreTime: 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;
+}