@chipmobilesdk/rn-payment 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,7 +7,96 @@ product keys, error codes, event names, state values, message keys, and the
 public API shape are this package's contract: renaming any of them is a breaking
 change.
 
-## [0.1.0] — unreleased
+## [0.2.0] — 2026-10-12
+
+Additive minor release closing one gap that surfaced when `0.1.0` met an app that
+must show a pending payment after a restart. It is a **capability** gap: `0.1.0`'s
+engine refused to grant a pending purchase, but an app could only *see* one in the
+session that started it. Reconstructing the pending set meant importing the billing
+library, which this package exists to prevent.
+
+It also fixes a **serious defect on Android devices**: a pending purchase was
+granted. See [Fixed](#fixed). **Upgrade from `0.1.0` before shipping.**
+
+**Upgrading requires one change, compile-time only:** `PaymentEventType` gained a
+member. See [Migration](#migration).
+
+### Added
+
+**Pending purchases, visible across sessions**
+
+- `getPendingPurchases()` and `subscribePendingPurchases(listener)` on the engine,
+  and `usePendingPurchases(productKeys?)` in React. They return a
+  `PendingPurchasesState`: a `status` (`known` | `unknown`), an `isStale` flag, and
+  `purchases`, one `{ productKey, since }` per product. No transaction id, token or
+  store object.
+- Read from the persisted snapshot, so the set survives an app kill and an offline
+  restart. It is judged by the **same staleness rule as entitlements**, now shared
+  code rather than a parallel copy: never synced, or older than `staleAfterMs`,
+  reports `unknown`, never an empty "nothing pending".
+- Pushed only when the set, its status, or its staleness changes. A sync that finds
+  nothing new re-renders nothing.
+
+**How a pending purchase ended**
+
+- `purchase_pending_resolved` event, `{ productKey, outcome }`, with `outcome`
+  `settled` | `cancelled` | `expired`, emitted once per pending transaction.
+  `settled` precedes the `entitlement_granted` it leads to.
+- Detected from the snapshot commit itself, so it is exactly-once by construction:
+  a store push and a sync racing on one settlement emit one event, a sync that
+  changed nothing emits none, and `clearLocalData()` emits none, because discarding
+  a record locally is not the store ending it.
+- **On Android every unpaid end is `cancelled`.** Play does not say whether a pending
+  purchase was declined or expired; it stops reporting it. The package does not
+  guess from elapsed time. `expired` is reported only by a store that says so,
+  through a new optional `pendingEndReason` on the internal provider port.
+
+**Testing**
+
+- Fake store: `settlePending`, `cancelPending` and `expirePending` change store-side
+  state the way the real store does, so the engine sees the change at its next sync,
+  in the same session or after a simulated app kill.
+
+### Fixed
+
+- **On a device, a pending purchase was granted.** The Android adapter read only
+  Play's numeric purchase state and treated anything else as purchased. The
+  `react-native-iap` 16.x binding hands JavaScript the state as a **string**
+  (`'pending' | 'purchased' | 'unknown'`) and does not carry the numeric one across,
+  so every pending purchase fell through to "purchased": entitlement granted, and an
+  acknowledgement attempted, for money that had not arrived. The engine's own
+  "pending never grants" rule was intact; the adapter fed it the wrong state. No
+  test could see it, because tests drive the fake store, which bypasses the adapter.
+  The adapter now reads either form, and anything it does not recognize is
+  `unspecified`, never purchased. Checked against the installed 16.7.3 declarations
+  and its JavaScript bridge.
+- **An `unspecified` purchase state is never treated as paid.** `0.1.0` persisted
+  Play's unknown state as `purchased`, granting it and queuing an acknowledgement.
+  Now a new transaction in that state is left out until the store says what it is,
+  a known one keeps what the package already knew (uncertainty is neither a grant nor
+  a refund), a store push in that state is ignored, and `purchase()` returning one
+  answers `store_error`, retryable: if the money did move, a retry gets
+  `already_owned`, which re-syncs and grants.
+
+### Unchanged, deliberately
+
+- **Pending never grants**, under any configuration. The new surface is read-only.
+- **No storage migration.** The schema stays at version 1. `0.1.0` already persisted
+  pending records; `0.2.0` only reads them.
+- `purchase()` still returns `pending`, and `purchase_pending` still fires, exactly
+  as before.
+
+### Migration
+
+| Union | New member |
+|---|---|
+| `PaymentEventType` / `PaymentEvent` | `'purchase_pending_resolved'` |
+
+An exhaustive `switch` over either needs the new case or a `default`. A
+hand-written `PaymentEngine`, typically a test mock, needs `getPendingPurchases` and
+`subscribePendingPurchases`. Nothing else changes.
+
+## [0.1.0] — 2026-10-06
 
 First version. Android only, via Google Play Billing.