@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-payment` are recorded here.
+
+This package follows semantic versioning. **Entitlement keys are yours**, but
+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.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.
+
+### Added
+
+**Entitlements**
+
+- `getEntitlement`, `getAllEntitlements`, `subscribeEntitlements` — synchronous,
+  in-memory reads safe to call on a render path.
+- Three states: `unknown`, `entitled`, `not_entitled`. `unknown` is both the
+  initial state and re-entrant, so a long-offline paying user is never reported
+  as unpaid.
+- Many-to-many product↔entitlement mapping. An entitlement stays valid while any
+  granting product remains.
+- Source attribution: which of *your* product keys currently grants an
+  entitlement.
+
+**Selling**
+
+- `purchase` with a typed outcome covering success, pending, user cancellation,
+  already-owned, ineligible, unknown product, region unavailability, disabled,
+  not-ready, unsupported, timeout, network error, store error, environment block,
+  and validation rejection.
+- One purchase flow at a time. A second request is refused, never queued.
+- `already_owned` triggers a re-sync, which is how a reinstall repairs itself.
+- Consumables with app-controlled consumption via `consume`.
+- Subscriptions with expiry, auto-renew, and cancelled-but-valid reporting.
+- `changePlan` with four proration modes; `openSubscriptionManagement`;
+  `confirmPriceChange`.
+
+**Finalization**
+
+- A persisted queue drained at startup, on foreground, and after each purchase.
+  A purchase survives the app being killed between payment and acknowledgement.
+- Idempotent finalization and consumption.
+- Bounded per-session retry that resumes in the next session rather than
+  abandoning a paid transaction.
+- `getUnfinalized()` so "paid but not settled" is observable.
+
+**Products and pricing**
+
+- `getProducts` / `refreshProducts` returning store-formatted prices, currency
+  codes, numeric prices for comparison, billing periods, trials, and
+  introductory pricing.
+- Offer eligibility as the store determined it.
+- In-memory cache with a configurable TTL, defaulting to 15 minutes.
+
+**Sync, restore, and offline**
+
+- Automatic sync at initialization and on foreground, rate-limited.
+- `restore` distinguishing "restored" from "nothing found".
+- Revocation on the next sync when the store stops reporting a transaction.
+- Offline reads from the last successful sync, expiring to `unknown` after a
+  configurable ceiling (7 days by default).
+- `clearLocalData` and optional cache-scope partitioning.
+
+**Safety**
+
+- Fail-closed initialization when a non-production build declares `production`.
+- Runtime block on any chargeable purchase outside production, recorded in
+  observable state.
+- No exported way to grant an arbitrary entitlement.
+
+**Optional server validation**
+
+- A hook that decides entitlement for newly completed purchases.
+- Configurable fallback when the backend is unreachable, defaulting to grant and
+  queue for re-validation.
+
+**React**
+
+- `PaymentProvider`, `useEntitlement`, `useEntitlements`, `usePaymentStatus`,
+  `usePurchase`, `useProducts`, `useSync`.
+
+**Diagnostics**
+
+- 19 typed event types with correlation ids, sufficient to reconstruct a
+  transaction's lifecycle from logs alone.
+- 22 stable error codes.
+- A localizable message-key map with English defaults and no i18n dependency.
+
+**Testing**
+
+- A fake store behind `@chipmobilesdk/rn-payment/testing` driving every outcome,
+  both callback orderings, connection loss, refunds, and crash-then-recover
+  finalization.
+
+### Known limitations
+
+- **Grace period and account hold are not separable on Android.** Play returns a
+  grace-period subscription as active and stops returning a held one, so
+  `renewalState` reports `indeterminate` rather than inventing a distinction. The
+  default policy still behaves correctly with no backend; a non-default policy
+  needs server data through the validation hook.
+- **iOS is contract-only.** `createStoreProvider()` returns a stub that reports
+  `unavailable` on iOS. The host app still starts and runs.
+- **The Android adapter is unverified against an installed binding.** See the
+  README's compatibility section.
+
+### Migration
+
+None — this is a new package.