@sendoracloud/sdk-react-native 1.39.1 → 1.41.0

package/CHANGELOG.md

@@ -0,0 +1,747 @@
+# Changelog
+
+## 1.41.0 — sign-in no longer retires the guest: it is held on the device (ADR-033 wave 1)
+
+**Two semantic changes, both strictly less destructive than before; everything else is additive
+(MINOR under ADR-023 — no signature, storage key, event or status code removed).** Parity: web 3.24.0 /
+iOS 5.4.0 / Android 4.26.0. Law: `docs/decisions/033-sdk-auth-mechanism.md` ("One Slot, Two Verbs").
+
+1. **Sign-in no longer retires the guest — it is held on the device.** A sign-in from a guest session
+   (`signIn`, `loginSocial`, `signInWithGameCenter`/`PlayGames`, `challengeMfa`, `verifyMagicLink`,
+   `verifyEmailOtp`, `consumeSsoFragment`, `signInWith`) never sends `prevAnonRefreshToken`,
+   `linkAnonymous` or `onCredentialInUse` any more, so the server can never delete, adopt or remap the
+   guest as a side effect of a sign-in. Instead the guest's live tokens go into one of five fixed secure
+   slots on the device and the account is installed: `guest_held{userId,count,user}` then ONE
+   `signed_in{cause:'sign_in'}`, no `signed_out`. The guest's server row survives; `getHeldGuests()`
+   lists it; `onDeviceTakeover` / `getLastAnonRetirement()` keep working but no longer fire for this
+   SDK's own sign-ins (`anonRetirement` is `"none"`).
+2. **`link:true` over an identified session attaches or errors — it never switches.**
+   `signInWith*({link:true})` / `loginSocial({link:true})` from an identified session go to
+   `/me/link/*`: an identity already on the account resolves quietly (no event, no revoke, no step-up),
+   one owned elsewhere throws `CredentialInUseError` (or switches when `onCredentialInUse:"adopt"`,
+   holding a guest if there was one), a stale session throws `RECENT_AUTH_REQUIRED`. From a guest it is
+   the same-`sub` promotion it always was (and still emits the legacy `signed_in{cause:'link'}`,
+   §8-Q18); in `signed_out` it is a plain sign-in. `signUp()` from a guest now calls `/me/link/email`
+   (never `/upgrade`); over an identified session it throws `AlreadyIdentifiedError` locally.
+
+**New surface (all additive):**
+- `auth.status(): "unknown" | "signed_out" | "anonymous" | "identified" | "withheld"` and
+  `auth.authStateReady()` (resolves after hydrate, never waits on the network). ⚠ **`status()` is the only
+  way to tell `withheld` (and `unknown`) from `signed_out`** — `getUserSync()` is `null` and `isReady()` is
+  `true` in all three. ⚠ **Consumers MUST default-branch on `AuthStatus`**: a later value ships opt-in-gated
+  or in a MAJOR.
+- Events on `onAuthStateChanged`: `initial{status,user,withheld?}` (replayed once per subscriber, in every
+  status). With a live session (`anonymous` / `identified`) it is FOLLOWED by the same `signed_in{user}`
+  replay 1.28–1.40 sent (no `cause`) — kept, because removing an event is not a MINOR change (ADR-023);
+  `signed_out` / `unknown` / `withheld` get `initial` only,
+  `user_updated{user,cause}`, `guest_held`, `guest_released{userId,reason,endReason?}`,
+  `session_withheld`; `signed_in` gains `cause: 'mint'|'sign_in'|'restore'|'link'`;
+  `signed_out.reason` gains `revoked | evicted | deleted` (the server's own `endReason`).
+- Held guests: `getHeldGuests()`, `getHeldGuest()`, `claimHeldGuest(id?)` (merge INTO the current
+  account — OPTIONAL and destructive; never call it from a backend that does not act on
+  `auth.user_merged`), `restoreHeldGuest(id?)`, `discardHeldGuest(id?)` (a real server delete). `id` may be
+  omitted only when exactly one guest is held (`AMBIGUOUS_HELD_GUEST` otherwise). Errors
+  `HeldGuestLimitError` (the device holds 5 guests), `HeldGuestProjectMismatch`.
+- `init({ autoRestoreHeldGuest })` (default `true`): `ensureSession()` / `signInAnonymously()` in
+  `signed_out` restore the newest eligible held guest instead of minting — visibly
+  (`signed_in{cause:'restore'}` + `guest_released{restored}`); a dead slot is released and the next tried,
+  then it mints in the same call. `signInAnonymously({forceNew:true})` from a guest holds it; at the cap it
+  throws `HeldGuestLimitError` and mutates nothing.
+- `init({ expectedProjectId })` (opt-in project guard): a stored/refreshed/restored session whose JWT
+  `project` claim disagrees is `withheld` — zero storage writes, every verb rejects
+  `AuthError{kind:'config', code:'SESSION_WITHHELD'}`, `getAccessToken*()`/`getRefreshToken()` return
+  `null`; exits are `discardWithheld()` (local only; keeps held guests, the queue and `user_id`) or a
+  relaunch with the matching key. A fresh mint/sign-in that disagrees rejects
+  `AuthError{kind:'config', code:'PROJECT_MISMATCH'}` and revokes the minted token.
+  `getWithheld()`, `Sendora.onIdentityWithheld(cb)`. Absent claim = unknown (never match); explicit
+  `null` = mismatch.
+- Typed verbs: `auth.link(credential): LinkResult` (`done{upgraded,alreadyLinked}` |
+  `credential_in_use{provider,collision,switchAccount(),keepCurrent()}` | `recent_auth_required`) and
+  `auth.signInWith(credential): SignInResult` (`done{previous:{userId,isAnonymous,held},reactivated}` |
+  `mfa_required{verify(code)}`). `switchAccount()` is bound to the refused credential (same payload under
+  5 min; a Game Center credential is re-fetched after that and a changed player aborts
+  `CREDENTIAL_CHANGED`).
+- `deleteAccount({ alsoDiscardHeldGuests })` → `{ ..., heldGuests, discardFailed }`. By default held guests
+  SURVIVE on device and server with auto-restore suppressed (explicit `restoreHeldGuest(id)` only).
+- `Sendora.reset({ includeHeldGuests })`: `reset()` now KEEPS held guests (a guest's refresh token is its
+  only credential); the option releases them locally (`guest_released{reason:'reset'}`, no server delete).
+  The clear is an exact key list of the active namespace, no longer a `startsWith(prefix)` sweep.
+- `merge(token)` (deprecated) routes a token that matches a held slot to `claimHeldGuest()`; otherwise the
+  raw `/merge` as before. `getRefreshToken()` kept (null in `withheld`).
+- `POST /anonymous` carries a per-attempt `mintKey` (a retried mint after a crash returns the same guest).
+- Bearer verbs (`enrollMfa`, `disableMfa`, `listMySessions`, `revokeSession`, `revokeAllSessions`,
+  `sendVerificationEmail`) now refresh an expired access token first (parity with web).
+
+**On disk (additive, ADR-023):** the four frozen keys keep their format and are written on every install
+(a 1.40.0 downgrade reads a valid session; held slots are simply ignored). New keys: `auth_session`
+(single-record form, read first on hydrate, written forward from the frozen keys on the first 1.41 launch —
+no network, same status), `auth_held_0..auth_held_4` (literal names, in `SECURE_KEYS`, so they route through
+your `secureStorage` adapter), `auth_mint_key` (non-secret, removed on a successful mint).
+`sendora_schema_version` → `"2"` (never bumped in a withheld hydrate).
+The four frozen keys stay the authority on whether a session exists: if a downgraded 1.40.x signs out
+(it clears only the four keys), the next 1.41 launch discards the leftover `auth_session` instead of
+reinstalling it.
+
+Guards: `test/auth-machine-conformance.test.ts` replays the shared ADR-033 table (36 rows + 19 project-verdict
+cases from `packages/shared`); `test/held-guests.test.ts` (ADR §5 tests 1–13, the refresh-during-native-sheet
+interleaving, dual-write/downgrade, the B15 held report, `merge()` routing). Mutation record in `CLAUDE.md`.
+
+## 1.40.0 — signInAnonymously() no longer replaces a signed-in account; CHANGELOG ships in the package
+
+**Behaviour change (reported by RopoLabs, verified against the shipped bundle).**
+`signInAnonymously()` reused an existing *anonymous* session but fell straight through when
+the current session was an identified account: it minted a guest and overwrote the
+account's tokens locally, with no `signed_out` on `onAuthStateChanged` (the path never
+wipes — it persists over the top). An app calling it defensively on a "looks signed out"
+reading silently converted a paying account into a fresh guest. It now returns the current
+session whatever its kind; `forceNew: true` is the only way to replace an identified
+session, and it does so silently. Read `user.isAnonymous` to know which you got. The
+account itself was never at risk server-side (recoverable by its credential) — the device
+had just become a stranger to it. Same fix in web 3.23.0 / iOS 5.3.0 / Android 4.25.0.
+
+- **`onAuthStateChanged` docs now say what it is not:** a transition stream, not a health
+  signal. A transient refresh failure (offline, timeout, 429, 5xx) emits nothing because
+  nothing changed; only a server-rejected refresh token produces
+  `signed_out(session_expired)`. Use `getAccessToken()` for liveness.
+- **`CHANGELOG.md` is in the published tarball** — the README told you to read it before
+  upgrading and the file was not there. The `repository` field pointed at a repository
+  that does not exist and was removed (this SDK is developed in a private monorepo).
+- `EventQueue.flush()`'s doc comment caught up with 1.39.1's head-of-line rotation.
+- **Server-side, no SDK change:** `auth.deleteAccount()` now also erases the account's
+  events (including guest events merged onto it), profile, entities, push-token
+  registrations and SMS/email sends. It previously erased credentials and the account row
+  only. If your privacy page says Sendora erases a deleted user's analytics, it is true
+  from this backend release.
+
+Guard: `test/anonymous-over-account.test.ts` (drives the real `Auth`: identified +
+refresh → no mint / no wipe / token untouched; `forceNew` mints; anonymous reuse holds;
+cached user without a refresh token still mints).
+
+## 1.39.1 — the event queue no longer outlives account deletion
+
+**Follow-up to 1.39.0 (reported by RopoLabs/Word Hurdle).** The retrying queue added in
+1.39.0 kept events across `auth.deleteAccount()` — so anything queued on a slow connection
+just before a confirmed deletion was delivered *after* it, still carrying the deleted
+account's `userId` and anonymous id. For an app that honors App Store 5.1.1(v) / GDPR
+erasure, that resurrected part of the account.
+
+- The queue is now cleared when an account is deleted. A plain `signOut()` still keeps its
+  queued events (they legitimately belong to that signed-in session — only deletion clears).
+- Also: a single event the server keeps rejecting no longer holds up everything behind it —
+  a repeatedly-failing event rotates to the back of the queue.
+
+No API or config change. Other SDKs (web/iOS/Android) already cleared their queue on
+deletion and were unaffected.
+
+## 1.39.0 — analytics events no longer leak an unhandled rejection; persisted retrying queue
+
+**Bug fix (reported by RopoLabs/Word Hurdle, with a repro against the shipped bundle).** A slow
+`/api/v1/events` request used to surface in your crash reporter as an unhandled promise rejection
+(`Request timed out: POST /api/v1/events (30000ms)`) and the event was dropped. `sendEvent()` awaited
+a transport that throws on its 30 s timeout, and every caller — including auto-track — discarded the
+rejecting promise. Since auto-track fires `session.start`/`app.opened`/lifecycle events with no call
+from your app, any app with users on slow networks saw the noise, and the dropped events biased
+session/engagement metrics toward users on fast networks.
+
+- Event delivery now runs through a **persisted, retrying queue**: a failed or slow send is retried
+  with backoff (up to 60 s), survives app restarts, and flushes when the app returns to the
+  foreground — so a slow network **delays** events instead of losing them. An event is dropped only
+  once the server accepts it, or permanently refuses it (a 4xx a retry can't fix).
+- A failed event can **no longer surface as an unhandled rejection.** `sendEvent()` is synchronous and
+  never throws.
+- No API change, no wire change, no configuration needed — upgrade and it's fixed. (A new internal
+  storage key `sendora_event_queue` holds unsent events; additive, ignored by older SDK versions.)
+
+Other SDKs (web/iOS/Android) already had this queue design and were unaffected.
+
+## 1.36.0 — failure reporting, insecure-storage warnings, and the step-up error kind
+
+⚠⚠ **Three methods reported failure as success, and `request()` never throws on a non-2xx** — it
+warns and returns the `Response`. So the discarded return value was the only place a refusal could
+surface. `disableMfa()` is **step-up gated**, so the app said MFA was off while TOTP stayed armed
+server-side; `revokeSession(id)` / `revokeAllSessions()` back a "sign out this device" button that
+reported success on a device that was never signed out. All three now throw.
+
+⚠ **`unwrap` was dropping the HTTP status**, so every failure routed through it classified as kind
+`unknown` — a 429 and a 503 both reporting as not-worth-retrying. It now carries `status` and
+`retryAfterSeconds`. This also changes `enrollMfa` and `confirmMfa`, whose errors move from `unknown`
+to a status-derived kind. That is the intended taxonomy and matches web/iOS/Android.
+
+**New error kind: `recent_auth_required`** — the credential is valid; the authentication behind it is
+too old to authorise a credential change (403 `RECENT_AUTH_REQUIRED`). Not a request for new input:
+re-authenticate and retry the same call. It previously fell through to `invalid_credential`,
+documented as "needs NEW input".
+
+**Insecure storage is no longer silent.** Without an encrypted-storage module the SDK falls back to
+`AsyncStorage`, which is plaintext on disk. That fallback used to happen quietly; it now warns, so a
+production app cannot ship tokens in the clear without anyone having been told.
+
+⚠ React Native implements no passkey management, so the gated `DELETE /passkeys/:id` route has no
+call site here.
+
+## 1.35.0 — unlink(provider): remove a linked sign-in method
+
+Parity: RN 1.35.0 / web 3.19.0 / iOS 4.20.0 / Android 4.20.0. Additive.
+
+The write half of `listLinkedIdentities()`. An app could already render
+"Connected: Google · Game Center"; ``auth.unlink(provider)`` is what the Disconnect
+button beside each entry calls.
+
+**⚠ The server refuses to remove the last way into the account** — code
+`LAST_CREDENTIAL`, kind ``"last_credential"``. An account with no credentials still
+exists and still holds the user's data, but nothing can ever authenticate into
+it again: no password to reset, no identity to present. That is permanent
+lockout, not an inconvenience, and it is unrecoverable without manual database
+surgery. A password counts as a credential, so an account with email+password
+plus one social identity may drop the social one.
+
+Supabase enforces the same floor (`unlinkIdentity` requires >= 2 identities);
+Firebase's `unlink()` does not and will strip the last provider. We follow
+Supabase, deliberately.
+
+**Prefer preventing the tap to explaining the refusal.** Read
+`listLinkedIdentities()` and disable Disconnect when
+`identities.length + (hasPassword ? 1 : 0) <= 1`. The error is the backstop, not the UX.
+
+An unlinked provider returns `NOT_FOUND` rather than reporting success — a
+screen saying "disconnected" about a credential that is still attached tells
+the user something untrue about their account.
+
+
+<!-- 1.7.0–1.19.0 reconciled from release history (per-version notes in CLAUDE.md + docs/STATUS.md); the changelog had drifted at 1.6.2. All additive; no frozen storage key / header / wire-shape changed (ADR-023). -->
+
+## 1.34.0 — getAccessToken() no longer returns a token past its own `exp`
+
+Parity: web 3.18.0 / iOS 4.19.0 / Android 4.19.0. Customer-reported (Word
+Hurdle), with a repro that runs against the shipped bundle.
+
+**Fixed (HIGH — silent, up to a full token TTL).** `getAccessToken()`
+documents a hard contract: it never returns a token past its `exp`. It enforced
+a different value — a deadline computed as `Date.now() + expiresIn` at mint,
+persisted, and restored verbatim. That deadline is deliberately
+**skew-invariant** (a permanently wrong clock cancels on both sides, because
+the deadline is written in the same frame it is later read in) but blind to a
+clock that **moves**. Step the clock backwards between mint and read — an
+iPhone acquiring automatic time after a long power-off, a restore, or a manual
+set — and the tracked deadline is stale by exactly the size of the correction,
+across relaunches. Observed on a physical device with a token **1929 seconds
+past its `exp`**: every request 401'd while the app still rendered as signed
+in, and nothing emitted `signed_out`, because the fast path returns before
+reaching `persist()` or `wipeLocalIdentity()`, the only emitters.
+
+The token's own `exp` is now required as well. **Requiring it alone would have
+been worse than the bug** — a device whose clock is fast by more than the token
+TTL reads every freshly-minted token as already expired, so every call
+refreshes, forever (measured at 10 reads → 10 refreshes). A one-shot probe
+bounds it: when a refresh performed *because* the two deadlines disagreed comes
+back with a token that STILL reads expired, the clock is proven fast rather
+than the deadline stale, and the `exp` guard is released for that process.
+Never persisted — a stored "my clock is fast" belief would outlive the
+correction that made it false.
+
+Also fixed, both surfaced by the same report:
+
+- The rotate short-circuit inside `refreshAccessToken()` returned a stored
+  token on a bare `> Date.now()` — **no safety margin and no `exp` check** — on
+  the one path meant to repair an expired token.
+- The proactive-refresh cron reasoned only from the tracked deadline, so during
+  this window it never fired; and it had **no call site outside `persist()`**,
+  meaning a cold launch ran with no cron at all. It is now armed from
+  `hydrate()` too, and repairs rather than only anticipating.
+
+**Added — `getAccessToken({ forceRefresh: true })`.** The supported way to say
+"your tracked deadline is wrong". It skips the cache but not the single-flight
+or the backoff cooldown, so force-refreshing on every 401 cannot turn a server
+outage into a hot loop. Replaces reaching into the private `accessExpiresAt`
+field, which is what the workaround for this bug required.
+
+**Added — `Sendora.init({ storagePrefix })`.** Namespaces every on-device key
+the SDK owns, for one codebase pointed at more than one project (staging beside
+production, debug beside release). Omitted, behaviour is byte-identical to
+prior releases. ⚠ Changing it signs the device out — nothing migrates between
+prefixes. Applies to the `secureStorage` adapter too when set. `secureStorage`
+alone does not solve this: `auth_access_expires` and the anon id stay in
+AsyncStorage and still collide.
+
+Tests: `test/token-expiry.test.ts` drives a controllable clock through correct
+/ constantly-fast / stepped-back, plus the opaque-token and `forceRefresh`
+paths. Both controls encode what must NOT change. Mutation-proven 3/3 —
+dropping the `exp` guard and moving the probe to mint time each resurrect the
+bug; dropping the skew escape produces the 10-for-10 refresh loop.
+
+## 1.33.0 — getLastAnonRetirement(): did my guest account survive?
+
+Parity: web 3.17.0 / iOS 4.18.0 / Android 4.18.0. Additive.
+
+`retiredAnonUserId` is present-or-absent, and the absence covered two
+situations needing opposite handling: the guest account was retired but not
+named, versus nothing was retired and the guest is still alive and claimable.
+Sign-in responses now carry `anonRetirement`, and `getLastAnonRetirement()`
+returns the last value (cleared on sign-out): `retired` (row deleted, id
+arrives via `onDeviceTakeover`), `preserved` (a guest token WAS sent and the
+guest was NOT retired — that account still exists, so "recover your other
+account" is a real offer), `none` (no guest token sent).
+
+⚠ Recorded ONLY when the server states it. An older backend omits the field
+entirely, and treating that as `none` would assert a fact we were never told.
+
+## 1.32.0 — the credential-collision default is now safe by construction
+
+Parity: web 3.16.0 / iOS 4.17.0 / Android 4.17.0. **Behaviour change to the
+DEFAULT.**
+
+`onCredentialInUse` shipped in 1.30.0 defaulting to `adopt` for compatibility.
+That was the wrong call: the destructive path was what you got by *not* knowing
+the option existed, and it succeeded silently. The default is now conditional
+on whether adopting would destroy anything — a fresh install with no guest
+session adopts (the reinstall-recovery path, never refused); a live guest
+session is refused with `CREDENTIAL_IN_USE` so the app can ask the player.
+
+⚠ **If you rely on silent adopt** — you consume the device-takeover signal to
+migrate progress on a returning player — pass `onCredentialInUse: "adopt"`
+explicitly. The adopt path itself is unchanged and still fires the takeover
+webhook.
+
+## 1.31.0 — onDeviceTakeover doc fix: the account-deleting paths were missing
+
+Parity: web 3.15.0 / iOS 4.16.0 / Android 4.16.0. Documentation-only; no
+behaviour change.
+
+The doc comment on `onDeviceTakeover` enumerated where the listener fires and
+**omitted the Game Center and Play Games paths — the only ones that DELETE an
+account.** It does fire there, so this was purely a doc defect, but an
+integrator reading that list would reasonably skip the one handler those paths
+most need. A CI guard now asserts each SDK's doc block names its gaming path.
+
+## 1.30.0 — credential-collision policy + anonymous link promotion
+
+Parity: web 3.14.0 / iOS 4.15.0 / Android 4.15.0.
+
+- **`onCredentialInUse: "adopt" | "reject"`** on `signInWithGameCenter` /
+  `signInWithPlayGames` / `loginSocial`. Omitted = `adopt` = every prior
+  release. On a collision the sign-in ADOPTS the owning account and hard-deletes
+  this device's anonymous row — a 200, so neither the 1.28.0 wipe-ordering fix
+  nor "a failed sign-in costs nothing" ever covered it. `"reject"` throws
+  `CredentialInUseError` and leaves the session byte-identical. Note `link:
+  true` does NOT help: the collision branch ignores it.
+- **`CredentialInUseError`** gained `.kind` / `.retryable` / `.code` /
+  `.status` plus `.provider` and `.collision`. Deliberately still not an
+  `AuthError` subclass — widening `instanceof` would silently re-route an
+  upgrading app.
+- **Linking from an ANONYMOUS session now works and rotates the session.**
+  `linkGameCenter` / `linkPlayGames` / `linkSocial` were gated to identified
+  accounts; the backend now promotes an anonymous caller in place (sub
+  preserved) and returns rotated tokens, which the SDK installs — not optional,
+  since the old refresh token is revoked server-side.
+
+## 1.29.0 — token refresh actually works again + the remaining loss routes
+
+Parity: web 3.13.0 / iOS 4.14.0 / Android 4.14.0.
+
+- **⚠ `/token/refresh` response shape (CRITICAL, pre-existing).** The rotated
+  trio lives under `data.tokens`; **web, iOS and Android all read `data.*`** —
+  the flat shape the backend stopped sending in s58.76. Reading the wrong level
+  fails silently: refresh returns null forever, the session dies at
+  access-token expiry, and the app mints a fresh guest. A shared
+  `readRotatedTokens()` now accepts either level.
+- **A generic 401 no longer wipes the session.** `isDeadRefreshError` accepted
+  `UNAUTHORIZED`/`HTTP_401` as a catch-all — which is exactly what the API-key
+  middleware returns for a rotated publishable key, so **rotating a `pk_` key
+  would have wiped every install's anonymous account at once.** Narrowed to
+  `INVALID_REFRESH_TOKEN`.
+- **A corrupt user blob is now recoverable** — the refresh adopts the `user`
+  the backend returns, but only when there is none.
+- **The refresh race, both directions** — a response landing after `signOut()`
+  no longer resurrects the session, and a stale rejection no longer wipes a
+  newer one. Both gate on `tokenStillCurrent(sent)`.
+- **`Sendora.reset()` went through `auth.signOut()`** instead of clearing auth
+  keys behind `Auth`'s back.
+- **`signIn` now carries `status` + `retryAfterSeconds`** — it is the only
+  route that produces `ACCOUNT_LOCKED`, so the cool-off countdown was
+  indistinguishable from a permanent lock.
+
+## 1.28.0 — a failed sign-in no longer destroys the account
+
+**Fixed (HIGH — silent, permanent data loss).** `loginSocial` (and every
+`signInWith*` wrapper), `signInWithGameCenter`, `signInWithPlayGames`,
+`verifyMagicLink`, `verifyEmailOtp` and `consumeSsoFragment` cleared the local
+session — *including the refresh token* — before their network call, and
+restored nothing on failure. For an anonymous user that token is the only
+durable handle on the account, so a failed attempt orphaned the account
+permanently; with no connectivity it happened every time. `consumeSsoFragment`
+wiped before even parsing the callback, so cancelling at the identity provider
+also cost the account. All six now clear the old session only after the
+response validates. **A failed auth attempt now leaves `getUserSync()` and the
+stored refresh token exactly as they were.**
+
+**Fixed.** A `429` from the background token refresh was treated as a
+permanently dead refresh token and wiped the session; rate limits are transient
+and now take the normal backoff path. A corrupt cached-user blob no longer
+deletes the still-valid refresh token alongside it.
+
+**Added.** `AuthError.kind` / `.retryable` / `.retryAfterSeconds` / `.status` —
+a closed failure taxonomy (`network`, `server`, `rate_limited`,
+`invalid_credential`, `account_locked`, `credential_in_use`,
+`already_identified`, `cancelled`, `config`, `unknown`) to branch on instead of
+matching raw codes. Existing `code` values are unchanged.
+
+**Added.** `auth.onAuthStateChanged(listener)` — one stream for `signed_in`,
+`signed_out` (`reason: "user" | "session_expired" | "account_deleted"`),
+`device_takeover` and `deletion_cancelled`. A session that dies in the
+background now reports `session_expired` instead of vanishing silently.
+Replays the current state on subscribe. `onDeviceTakeover` /
+`onDeletionCancelled` are unaffected.
+
+## 1.26.0 — `onDeletionCancelled` (account-restore signal)
+
+New `auth.onDeletionCancelled(listener)` + `auth.getLastDeletionCancelled()` —
+fires when a sign-in **cancelled a pending self-service account deletion** within
+its grace window (the account is restored, same user_id). Mirrors
+`onDeviceTakeover`: dispatched centrally from `persist()` reading a new
+`reactivatedFromDeletion` flag the backend now returns on **every** sign-in
+response (was password-login-only). Use it to show "your account deletion was
+cancelled" + reconcile local state. Pairs with the new server-side
+`auth.deletion_cancelled` / `auth.deletion_scheduled` webhooks (s58.269).
+Additive, SDK-only (not in the golden wire contract).
+
+## 1.25.0 — identity linking on an identified session (ADR-030) + signUp() fix
+
+**New: link a SECOND credential to an already-signed-in account, preserving the
+same user id (sub)** — the cross-platform account-unification primitive. Unlike
+`signUp()` / `loginSocial({link})` (which only preserve the sub from an
+*anonymous* session), these work on an already-identified account:
+
+- `auth.linkEmailPassword(email, password)` — attach email + password.
+- `auth.linkGoogle({ idToken | code, redirectUri })` / `auth.linkApple({ … })` /
+  `auth.linkSocial({ provider, … })` — attach an OAuth identity.
+- `auth.linkGameCenter(payload?)` / `auth.linkPlayGames(payload?)` — attach a
+  gaming identity (no-arg drives the native fetch via the gaming companion).
+
+All require a signed-in session (Bearer), preserve the sub, do NOT rotate tokens,
+and refresh the cached user in place. Collision (the credential already belongs to
+another account) throws the new **`CredentialInUseError`** — Sendora never
+auto-merges two real accounts. Use to make one account reachable across platforms
+(e.g. a Game Center player on iOS links email/Google, then signs in on Android to
+the SAME sub).
+
+**Fix: `signUp()` on an already-identified session** now throws the new
+**`AlreadyIdentifiedError`** instead of a misleading `EmailAlreadyTakenError`, and
+no longer wipes the session or mints a duplicate account. (The backend now returns
+a distinct `NOT_ANONYMOUS` code, ADR-030 §4.)
+
+Additive + SDK-only surface (not in the golden wire contract); no frozen storage
+key / header / route touched. Verified via `test/link.test.ts` (18 assertions) +
+`tsc` + built `dist`.
+
+## 1.24.0 — `AuthUser.signupMethod` + `.lastLoginMethod`
+
+The `AuthUser` object now carries two optional read-only fields: `signupMethod`
+(how the account was first created, immutable) and `lastLoginMethod` (most recent
+authentication). Free-form provider tokens: `password | anonymous | google |
+apple | github | microsoft | linkedin | facebook | discord | gamecenter |
+playgames | magic_link | email_otp | passkey | oidc | saml | scim | import`.
+Populated by the backend on the login/signup/social/game response (s58.266, mig
+0094); flow through `persist()` unchanged, so `getUserSync()` / `getCurrentUser()`
+expose them with **zero new plumbing**. Display-only (UI / routing) — never an
+authorization signal. **Additive + tolerant**: `undefined` against a pre-s58.266
+backend, `null` for an end-user row created before that backend shipped
+(backfilled on their next sign-in); `isAuthApiResponse` type-checks them only when
+present. No frozen storage key / header / wire-shape changed (ADR-023) — installed
+apps on ≤1.23.1 keep working; upgrading is opt-in.
+
+## 1.23.1 — config plugin: fix Expo SDK 54 `expo prebuild` break (ESM→CJS import)
+
+`app.plugin.js` now **default-imports** `@expo/config-plugins` and destructures at
+runtime instead of a NAMED import. The named form (`import { …, AndroidConfig, … }`)
+relied on Node's cjs-module-lexer statically surfacing every member of the
+CommonJS package — under config-plugins 54 (Expo SDK 54) `AndroidConfig` is not,
+so the import threw `SyntaxError: does not provide an export named 'AndroidConfig'`
+at load time and aborted `expo prebuild`. Default-import is version-agnostic (the
+default export is the CJS `module.exports`). **No behavior change** — identical
+transforms, JS/native runtime untouched; only the deep-link config plugin's load
+path is fixed. Regression-guarded in `test/plugin.test.ts` (rejects the named
+form). Verified against the real `@expo/config-plugins` (named throws, default
+resolves `AndroidConfig.Manifest.getMainApplicationOrThrow`). Reported by a
+customer on Expo SDK 54; the companion `@sendoracloud/sdk-react-native-gaming`
+1.0.1 carries the same fix.
+
+## 1.23.0 — Game Center / Play Games no-arg sign-in (native in a companion package)
+
+Adds the JS so 1.21.0's gaming sign-in can fetch the provider payload itself — no
+app-supplied GameKit / Play Games code:
+
+- **`auth.signInWithGameCenter()`** (no args) drives Game Center natively and posts
+  the identity payload.
+- **`auth.signInWithPlayGames()`** (no args) drives Play Games v2 and posts the
+  `serverAuthCode`.
+
+The native code (GameKit Swift / Play Games Kotlin + the gaming config plugin)
+lives in an **optional companion package, `@sendoracloud/sdk-react-native-gaming`**
+— so **non-gaming apps don't pull the Android `play-services-games-v2`
+dependency**. Install the companion + its config plugin only for gaming sign-in.
+
+This SDK stays pure JS. `src/native.ts` resolves the companion's native module
+zero-dependency off `globalThis.expo.modules.SendoraGameAuth` (Metro-safe, CLAUDE
+rule #1 — no expo import). The no-arg call is **optional at runtime**: without the
+companion (or in Expo Go / bare RN) it throws a clear "install
+@sendoracloud/sdk-react-native-gaming + Dev Client" error, and the
+**explicit-payload overloads from 1.21.0 still work everywhere** —
+`signInWithGameCenter(payload)` / `signInWithPlayGames({ serverAuthCode })`
+unchanged and additive. Overload dispatch keys on `"publicKeyUrl" in arg` /
+`"serverAuthCode" in arg`; the no-arg native fetch runs INSIDE the serialized op
+(a cancelled sheet leaves the session untouched).
+
+The 1.22.0 deep-link config plugin (`app.plugin.js`, `{ linkSubdomain }`) is
+unchanged — gaming config moved out to the companion's own plugin.
+
+Additive; no frozen storage key / header / wire-shape changed. JS overload +
+native-fetch logic unit-tested (`test/game-auth.test.ts`). **On-device smoke (real
+Game Center + Play Games accounts, via the companion) is the release gate.**
+
+## 1.22.0 — Expo config plugin (auto-wire deep-link associated domains)
+
+Ships an Expo config plugin at the package root (`app.plugin.js`) so apps don't
+hand-edit iOS entitlements / Android manifests for deep links. In app.json:
+`["@sendoracloud/sdk-react-native", { "linkSubdomain": "wordhurdle" }]` →
+`applinks:wordhurdle.sendoracloud.app` (iOS associated-domains) + an autoVerify
+App Links intent-filter (Android). `linkDomains: [...]` adds BYO/custom hosts
+(combines with `linkSubdomain`). **Opt-in + build-time** (runs at
+`expo prebuild`) — never touches an already-built/installed app; both platforms
+**MERGE + dedupe** (no clobber of existing domains; `createRunOncePlugin` guards
+double-apply). ESM plugin → Expo SDK 50+. Pure transforms unit-tested
+(`test/plugin.test.ts`). Additive; no runtime SDK / frozen-contract change.
+
+## 1.21.0 — Game Center + Play Games sign-in
+
+`auth.signInWithGameCenter(payload, { link })` (Apple, iOS) and
+`auth.signInWithPlayGames({ serverAuthCode }, { link })` (Google, Android) —
+email-less, player-keyed sign-in. Forward the native provider payload (obtain it
+via a GameKit / Play Games native module or the Sendora Expo plugin) to the new
+`/auth-service/login/{game-center,play-games}` endpoints. Shares the anon
+device-takeover + ADR-025 `link` (link-in-place, same user id preserved)
+semantics with `loginSocial`. Additive; no frozen storage key / header /
+wire-shape changed (`linkAnonymous`/`prevAnonRefreshToken` are optional backend
+fields, not in the golden contract).
+
+## 1.20.0 — anon→social link-in-place (ADR-025)
+
+`loginSocial` / `signInWithApple` / `signInWithGoogle` accept an opt-in `link?: boolean`. When the device is anonymous and `link: true`, an anon→social upgrade forwards `linkAnonymous` so the backend promotes the anon row **in place** — the user id (`sub`) is **preserved** (fires `auth.user_upgraded`) instead of a device-takeover that mints a new id (Firebase `linkWithCredential` parity). No effect off-anon, or on a collision (identity already owned / email taken → prior takeover/merge). Additive + opt-in; `link` absent/false = prior behaviour exactly. Design: `docs/decisions/025-anon-social-link-in-place.md`.
+
+## 1.19.0 — `getUserSync()` + `isReady()`
+
+Synchronous, non-throwing accessors for the **verified auth principal** at cold start. `getUserSync(): AuthUser | null` returns the in-memory session hydrated during `init()` (`id` = the JWT `sub` — the durable server-verified key), zero I/O. `isReady(): boolean` distinguishes "still restoring the session" from "genuinely signed out". SDK-only; not in the golden wire contract.
+
+## 1.18.0 — opt-in encrypted-at-rest storage (`secureStorage` adapter)
+
+Optional, default-off. `Sendora.init({ secureStorage })` takes an app-supplied Keychain/Keystore `SecureStorageAdapter`; the SECURE_KEYS (`auth_refresh_token`/`auth_access_token`/`auth_user`) route through it with transparent plaintext→secure dual-read migration (never signs anyone out). Graceful fallback to AsyncStorage on adapter failure. SDK never imports expo-secure-store (Supabase `auth.storage` model → Metro-safe). Omit it = exact prior behaviour.
+
+## 1.17.0 — `getAnonymousIdSync()`
+
+Additive sync read of the anon id (`this.anonId || null`) — lets offline-first callers read-or-fallback at cold start without a try/catch around the throwing `getAnonymousId()`.
+
+## 1.16.0 — device app version + native build number
+
+`device.appVersion` + native build number attached to the device context (surfaces on the dashboard Audience page).
+
+## 1.15.0 — appVersion for modern Expo (New Architecture)
+
+Reads app version from the canonical modern source `ExpoApplication.nativeApplicationVersion` (fixes the 1.13.0 dead path on Expo SDK 50+). Hardened `expoModule()` resolution mirrors expo-modules-core's `requireOptionalNativeModule`. Still zero-dep / zero Metro risk.
+
+## 1.14.0 — ADR-023 SDK compatibility headers + schema marker
+
+`X-Sendora-SDK-{Name,Version}` headers on every request + a local `sendora_schema_version=1` marker (forward hook for on-device migrations). Additive; backend ignores the headers today.
+
+## 1.13.0 — Expo New-Architecture device read (appVersion + model)
+
+Reads Expo native modules off `globalThis.expo.modules[name]` (New-Arch registry) first, legacy `NativeModules` second — `device.model` ← `ExpoDevice.modelName` when expo-device is installed. No dependency, no Metro risk.
+
+## 1.12.0 — appVersion auto-reads Expo Constants
+
+`device.appVersion` auto-detects on Expo via `NativeModules.ExponentConstants` with zero new dependency (superseded by 1.13.0/1.15.0 for New-Arch).
+
+## 1.11.0 — top-level `sessionId` on events
+
+Events now carry a top-level `sessionId` (not just nested in properties), powering the Audience "Sessions & engagement" metrics for RN. iOS/Android parity.
+
+## 1.10.0 — appVersion auto-detect (Metro-safe)
+
+`device.appVersion` resolves from config → `EXPO_PUBLIC_APP_VERSION` → global → "". Deliberately no `require()` of expo-constants / device-info (Metro-safe).
+
+## 1.9.0 — device/tech context (ADR-022)
+
+Every event's `context.device` block: `{ type, os, osVersion, model, appVersion }`, built from RN's `Platform`. Powers the dashboard Analytics → Audience page.
+
+## 1.8.2 — `getAccessToken()` never returns an expired token
+
+Hard contract (matches iOS/Android + Supabase/Auth0/Firebase token clients): a valid cached token if ≥30s life remains; else await the single-flight `/token/refresh` and return the FRESH token; `null` during post-failure backoff. Reverses the Wave-62 stale-while-refreshing return that could hand out a token past `exp`. The ≤10s AbortController bound (the real hang fix) is preserved.
+
+## 1.8.1 — refresh-before-delete
+
+`auth.deleteAccount()` resolves a fresh access token via `getAccessToken()` before the `DELETE`, fixing 401s when a stale cached token was sent for the one-shot destructive call.
+
+## 1.7.0 — self-service account deletion
+
+`auth.deleteAccount()` (Apple Guideline 5.1.1(v)) → `{ status: "purged" | "pending", scheduledPurgeAt, graceDays }`. Disables + revokes immediately; hard-deletes at `scheduledPurgeAt` unless the user signs back in within the per-project grace window. Wipes local identity on success.
+
+## 1.6.2 — MFA-from-anonymous device-takeover fix (audit s58.203 follow-up)
+
+Fixes lost device-takeover when an MFA-enabled user signs in from an anonymous device:
+- `signIn()` previously wiped the local anon identity **before** the network call, so when the response was an MFA challenge the anon refresh token was gone — `challengeMfa()` forwarded no `prevAnonRefreshToken`, the backend never retired the anon row / reassigned push tokens, and the device ended with **two user_ids + duplicate pushes**.
+- Now: `signIn()` captures the anon refresh token, does NOT wipe before the call, and on an MFA-required response **stashes** it keyed to the `mfaChallengeToken`. `challengeMfa()` forwards the stashed token, and the anon identity is wiped **only after a successful mint** — a wrong/expired code preserves the anon session for retry. Mirrors the non-MFA `signIn()` ordering.
+
+No public API change.
+
+## 1.6.1 — s58.203 audit P0: dead namespaces + anonymous push fixed
+
+Two production-breaking fixes:
+- **15 endpoint paths across 8 namespaces were missing the `/api/v1` prefix** → every call resolved to a 404. Affected: `push.trackOpen`, `push.liveActivities`, `push.geofences`, `attribution`, `support`, `consent`, `surveys`, `messages` (in-app), `flags`, `chatbot`. All now hit their real backend routes.
+- **`registerPushToken` sent `userId: null` for anonymous users** → backend Zod rejected it (422), so anonymous devices could never register for push. Now omits `userId` when anonymous (matches `sendEvent`).
+
+No public API change. Upgrade required for any app using those namespaces or registering push before sign-in.
+
+## 1.5.0 — Wave 73 unread support count
+
+New `support.getUnreadCount(widgetId)` returns the number of tickets the signed-in user (anon or identified) has with new activity since their last view. Returns 0 when no SDK auth is on file. Backed by W72's `GET /widgets/:id/my-tickets/unread-count`.
+
+Recommended cadence: poll on AppState `active` + every 60s while the app is active.
+
+```ts
+useEffect(() => {
+  let cancelled = false;
+  const tick = async () => {
+    const n = await SendoraCloud.support.getUnreadCount("widget-uuid");
+    if (!cancelled) setBadge(n);
+  };
+  void tick();
+  const id = setInterval(tick, 60_000);
+  return () => { cancelled = true; clearInterval(id); };
+}, []);
+```
+
+## 1.4.0 — Wave 69 in-app ticket history
+
+New `<TicketHistory />` + `useTicketHistory(widgetId, getAccessToken, defaults?)` on the `/contact-widget` subpath. Opens the worker-hosted `/embed/tickets` view in a `<Modal>` + `<WebView>` so the submitter can see all their past tickets + reply inline.
+
+Backend (chatbot module):
+- `GET /widgets/:widgetId/my-tickets` — list (Bearer JWT auth).
+- `GET /widgets/:widgetId/my-tickets/:ticketId` — single ticket + replies.
+- `POST /widgets/:widgetId/my-tickets/:ticketId/replies` — customer reply. Auto-reopens resolved/closed tickets. Emits `support.in_app_reply` event.
+
+JWT is passed in the URL hash fragment and scrubbed on load — never appears in server logs or referer.
+
+```tsx
+import SendoraCloud from "@sendoracloud/sdk-react-native";
+import { useTicketHistory } from "@sendoracloud/sdk-react-native/contact-widget";
+
+const history = useTicketHistory(
+  "widget-uuid",
+  () => SendoraCloud.auth.getAccessToken(),
+);
+
+<Button title="My tickets" onPress={history.open} />
+<history.View />
+```
+
+Anonymous SDK rows + identified users both work — anon tickets are filtered by `user_id` only, identified users also pick up legacy tickets matched on email.
+
+## 1.3.0 — Wave 68 contact widget identity handling
+
+`<ContactWidget />` + `useContactWidget()` now accept:
+
+- `prefillUserId` — Sendora `userId` (anon or identified) that gets posted with the ticket so it stitches to the same profile as analytics events.
+- `lockEmail` — when true + `prefillEmail` is set, the email field is hidden + read-only.
+
+`useContactWidget(widgetId, { user })` now accepts the SDK's `AuthUser` shorthand and auto-resolves prefill:
+
+- identified user (`emailVerified && !isAnonymous`) → email locked + userId attached.
+- anonymous SDK row → userId attached, email field shown for entry.
+- no user → standard form.
+
+Backend gets `userId` stored on the new ticket row + the embed posts it for you. Hint only, not an auth boundary — see security note in `useContactWidget` docstring.
+
+```tsx
+import SendoraCloud from "@sendoracloud/sdk-react-native";
+import { useContactWidget } from "@sendoracloud/sdk-react-native/contact-widget";
+
+const user = SendoraCloud.auth.getCurrentUser();
+const contact = useContactWidget("widget-uuid", { user });
+```
+
+## 1.2.0 — Wave 66 mobile Contact Widget
+
+New subpath import `@sendoracloud/sdk-react-native/contact-widget` ships `<ContactWidget />` + `useContactWidget()` hook. Opens the worker-hosted embed at `https://go.sendoracloud.com/embed/contact?widgetId=…` inside a `<Modal>` + `<WebView>`. The HTML form posts to `POST /widgets/:id/submit` server-side — same backend the web `widget.js` uses.
+
+On submit success the embed page navigates to `sendora://close?ticketId=…&portalUrl=…`. `onShouldStartLoadWithRequest` intercepts the scheme, fires `onClose({ ticketId, portalUrl, submitted })`, host sets `visible=false`.
+
+`react-native-webview` is an **optional** peer dep. Apps that don't use the contact widget aren't required to install it — Metro only resolves it when the subpath is imported.
+
+**Mount**:
+```tsx
+import { useContactWidget } from "@sendoracloud/sdk-react-native/contact-widget";
+
+const contact = useContactWidget("widget-uuid", { theme: "auto" });
+
+<Button title="Contact us" onPress={contact.open} />
+<contact.View />
+```
+
+Single source of truth = the worker route. UI / theme / copy updates = redeploy worker. Zero SDK release.
+
+## 1.1.0
+
+**Cold-launch hang fix — architectural.**
+
+Pulse News (1.0.5) reported `sdk.auth.getAccessToken()` hanging indefinitely on iOS cold launches from Universal Links. Root cause: iOS NSURLSession stalls up to ~70s on cold-URL-launch contention; SDK's single-flight `refreshInflight` shared one stuck promise across every concurrent caller, hanging the JS bridge until iOS WatchdogTermination fired. No internal timeout, no abort.
+
+**5-layer fix** (every layer below holds even if layers above misfire):
+
+1. **`http.ts` — AbortController + per-call timeout on every fetch.**
+   Auth paths: 10s. Ingest paths: 30s. On expiry the AbortController fires + the underlying socket cancels (not orphaned waiting on NSURLSession 70s error). Throws typed `NetworkTimeoutError` so callers can distinguish from non-2xx.
+
+2. **`auth.getAccessToken()` — stale-while-refreshing.**
+   Expired cached token + refresh inflight → return stale cached anyway. Backend's 60s grace window accepts slightly-stale access tokens, so the caller's downstream RPC succeeds against grace while the in-flight refresh resolves out of band. Pre-1.1.0: every concurrent caller blocked on the same stuck inflight promise.
+
+3. **`auth.refreshAccessToken()` — exponential backoff on transient failures.**
+   `NetworkTimeoutError` and other non-dead-refresh errors increment `refreshFailureCount` + arm a cooldown (1s → 2s → 4s → ... capped 30s). `getAccessToken()` consults the cooldown + returns stale rather than firing fresh fetches into a stalled network.
+
+4. **AppState foreground — reset refresh state.**
+   When the app comes back to active, `resetRefreshState()` clears `refreshFailureCount + refreshCooldownUntil` so the user returning from a network blip gets an immediate fresh attempt, not a wait for the exponential timer.
+
+5. **Permanent vs transient distinction.**
+   Dead-refresh errors (backend rotated away, family revoked, session pruned) still wipe identity + stop the retry loop at the source. Transient errors (network timeout, 5xx, JSON parse) do NOT wipe — refresh token may still be valid.
+
+**Caller migration:** None required. `getAccessToken()` still returns `string | null`. `withSendoraBearer`-style wrappers can keep their per-call timeout — the SDK now backs them up at multiple layers instead of trusting iOS to terminate.
+
+**Breaking changes:** None. `NetworkTimeoutError` is a new exported class; existing `instanceof Error` checks still work.
+
+Closes Pulse News dogfooding bug report. Operator carry-over: npm publish + tag `sdk-react-native-v1.1.0`.
+
+## 1.0.0
+
+**Breaking change.** Backend (s58.104) now exposes unprefixed alias routes and
+resolves `orgId` from the API key server-side.
+
+- **Removed** `orgId` from `SendoraConfig`. Backend derives the org from the
+  apiKey row server-side.
+- Outgoing payloads (`/api/v1/events`, `/api/v1/push/tokens`, …) no longer
+  include the `orgId` field.
+- `publicKey` remains a deprecated alias for `apiKey`.
+
+### Migration
+
+Drop `orgId` from your `SendoraCloud.init({...})` call:
+
+```diff
+  await SendoraCloud.init({
+    apiKey: "pk_prod_...",
+-   orgId: "<ORG_ID>",
+  });
+```
+
+All public method signatures (`identify`, `track`, `screen`,
+`registerPushToken`, `links.*`, `auth.*`, `attribution.*`, push helpers, …)
+are unchanged.
+
+## 0.20.x and earlier
+
+See git history at https://github.com/sendoracloud/sdk-react-native/commits/main