@chipmobilesdk/rn-payment 0.1.0 → 0.2.1

package/src/adapter/port.ts

@@ -172,6 +172,18 @@ export interface ProviderPort {
 	/** 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). */

package/src/config/types.ts

@@ -198,6 +198,46 @@ export type PurchaseResult =
 	| { 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' }

package/src/diagnostics/events.ts

@@ -14,6 +14,7 @@ import { redact, type PaymentErrorCode, type PaymentOperation } from './errors';
 import type {
 	EntitlementKey,
 	Environment,
+	PendingResolution,
 	ProductKey,
 	Unsubscribe,
 	UnavailableReason,
@@ -28,6 +29,9 @@ export type PaymentEventType =
 	| 'purchase_succeeded'
 	| 'purchase_cancelled'
 	| 'purchase_pending'
+	// How a pending purchase ended, once per transaction. `settled` precedes the
+	// `entitlement_granted` it leads to (FR-102), added in 0.2.0.
+	| 'purchase_pending_resolved'
 	| 'purchase_failed'
 	| 'transaction_finalized'
 	| 'transaction_consumed'
@@ -74,6 +78,11 @@ export type PaymentEvent = BaseEvent &
 		| { 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;