@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# 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.1.0] — unreleased
+
+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.