@sendoracloud/sdk-react-native 1.39.1 → 1.40.0

package/CHANGELOG.md

@@ -0,0 +1,661 @@
+# Changelog
+
+## 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

package/README.md

@@ -245,7 +245,13 @@ Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing
 
 ## Stability
 
-This SDK is on the **1.x line**. Patch bumps (1.x.y → 1.x.z) are backwards-compatible; minor bumps may include opt-in feature additions. Breaking changes only on major bumps — always read the [CHANGELOG](./CHANGELOG.md) before upgrading.
+This SDK is on the **1.x line**. Patch bumps (1.x.y → 1.x.z) are backwards-compatible; minor bumps may include opt-in feature additions. Breaking changes only on major bumps — always read `CHANGELOG.md`, which ships inside the package (`node_modules/@sendoracloud/sdk-react-native/CHANGELOG.md`), before upgrading.
+
+### Auth state is a transition stream, not a health signal
+
+`auth.onAuthStateChanged()` reports confirmed transitions only — `signed_in`, `signed_out` (reason `user` | `session_expired` | `account_deleted`), `device_takeover`, `deletion_cancelled`. A transient failure of the background token refresh (offline, timeout, HTTP 429, 5xx) emits **nothing**: the stored refresh token is kept and the refresh retried with backoff, so no state changed. "No event" means "no confirmed transition", never "the session is fine". Only a server-rejected refresh token produces `signed_out(session_expired)`. For liveness, read `getAccessToken()` — `null` means no usable token right now.
+
+`signInAnonymously()` returns the **current** session when one exists, anonymous or identified — it never replaces a signed-in account with a guest. Pass `forceNew: true` to deliberately abandon whatever session is current and mint a fresh anonymous one.
 
 ## JWT verification (custom backend)
 

package/dist/index.cjs

@@ -228,7 +228,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.39.1",
+  version: "1.40.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -250,6 +250,7 @@ var package_default = {
     "dist",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "app.plugin.js",
     "plugin"
@@ -284,7 +285,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts && tsx test/anonymous-over-account.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -295,10 +296,6 @@ var package_default = {
     typescript: "^5.0.0"
   },
   license: "MIT",
-  repository: {
-    type: "git",
-    url: "https://github.com/sendoracloud/sdk-react-native"
-  },
   homepage: "https://sendoracloud.com/sdks"
 };
 
@@ -798,6 +795,15 @@ var Auth = class {
    * A failed sign-in emits NOTHING: the session is unchanged, so there is no
    * transition to report — the rejected promise is the whole story.
    *
+   * ⚠ This is a TRANSITION stream, not a health or connectivity signal (1.40.0
+   * doc fix, reported by RopoLabs). A transient failure of the background
+   * token refresh — offline, timeout, HTTP 429, 5xx, an unparseable response —
+   * emits nothing: the stored refresh token is kept and the refresh retried
+   * with backoff, so no state changed. "No event" therefore means "no
+   * confirmed transition", never "the session is fine". Only a server-REJECTED
+   * refresh token produces `signed_out(session_expired)`. For liveness read
+   * `getAccessToken()` (null = no usable token right now).
+   *
    * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
    * and never affects auth state. Returns an unsubscribe function.
    */
@@ -1010,24 +1016,41 @@ var Auth = class {
     return this.accessToken;
   }
   /**
-   * Mint (or return) an anonymous session.
-   *
-   * Reuses the existing anonymous user when there already is one — the same
-   * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-   * that calls this defensively on every cold launch (the most natural thing
-   * to write) mints a fresh `user_id` each time, and `persist()` overwrites
-   * the stored refresh token — the previous anonymous account's only durable
-   * handle — with no takeover, no webhook and no state event. That is the same
-   * silent progress loss as a failed sign-in wiping the session, except it
-   * happens on a *healthy* network.
-   *
-   * Pass `forceNew: true` to deliberately abandon the current anonymous
-   * session and mint a separate one.
+   * Return the current session, minting an anonymous one only when there is
+   * none.
+   *
+   * Reuses the existing session when there already is one — anonymous OR
+   * identified. The anonymous half is the same short-circuit Firebase's
+   * `signInAnonymously` performs. Without it, an app that calls this
+   * defensively on every cold launch (the most natural thing to write) mints a
+   * fresh `user_id` each time, and `persist()` overwrites the stored refresh
+   * token — the previous anonymous account's only durable handle — with no
+   * takeover, no webhook and no state event. That is the same silent progress
+   * loss as a failed sign-in wiping the session, except it happens on a
+   * *healthy* network.
+   *
+   * ⚠ The identified half closes the same hole from the other side (1.40.0,
+   * reported by RopoLabs). Until then the guard was `existing.isAnonymous`, so
+   * a plain `signInAnonymously()` over a LIVE ACCOUNT session fell through,
+   * minted a guest and overwrote the account's tokens locally — with no
+   * `signed_out`, because this path never wipes anything; it persists over the
+   * top. An app that called it on a "looks signed out" reading silently turned
+   * a paying account into a fresh guest, and its own session-death listener
+   * never fired. The account itself survives (row + server session untouched,
+   * recoverable by its credential) but the device is now a stranger to it.
+   * Returning the identified session is a no-op for that caller and the honest
+   * answer to "make sure I have a session" — read `user.isAnonymous` if you
+   * need to know which kind you got.
+   *
+   * Pass `forceNew: true` to deliberately abandon the current session —
+   * whichever kind — and mint a separate anonymous one. That is the ONLY way
+   * this method replaces an identified session, and it does so silently (the
+   * caller asked for it); `signOut()` first if you want a `signed_out`.
    */
   signInAnonymously(opts) {
     return this.serialize(async () => {
       const existing = this.user;
-      if (!opts?.forceNew && existing?.isAnonymous && this.hooks.storage.get(REFRESH_KEY)) {
+      if (!opts?.forceNew && existing && this.hooks.storage.get(REFRESH_KEY)) {
         return existing;
       }
       const data = await this.callAuth("/api/v1/auth-service/anonymous", {
@@ -2924,11 +2947,15 @@ var EventQueue = class {
     }, ms);
   }
   /**
-   * Drain the queue FIFO. Removes an event only when the server ACCEPTED it (2xx)
-   * or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it — and stops
-   * draining — on a transient failure (timeout throw, network null, 408/429/5xx),
-   * then arms a capped-exponential-backoff retry. The entire post lives inside the
-   * try/catch, so `NetworkTimeoutError` can never surface as an unhandled rejection.
+   * Drain the queue in order. Removes an event only when the server ACCEPTED it
+   * (2xx) or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it —
+   * and stops draining — on a transient failure (timeout throw, network null,
+   * 408/429/5xx), then arms a capped-exponential-backoff retry. ⚠ Since 1.39.1 a
+   * transiently-failing HEAD is first rotated to the BACK, so one poison event
+   * cannot hold everything behind it; delivery order is therefore best-effort,
+   * not strict FIFO (identity travels in each event body, not by slot). The
+   * entire post lives inside the try/catch, so `NetworkTimeoutError` can never
+   * surface as an unhandled rejection.
    */
   async flush() {
     if (this.flushing || this.q.length === 0) return;

package/dist/index.d.cts

@@ -716,6 +716,15 @@ declare class Auth {
      * A failed sign-in emits NOTHING: the session is unchanged, so there is no
      * transition to report — the rejected promise is the whole story.
      *
+     * ⚠ This is a TRANSITION stream, not a health or connectivity signal (1.40.0
+     * doc fix, reported by RopoLabs). A transient failure of the background
+     * token refresh — offline, timeout, HTTP 429, 5xx, an unparseable response —
+     * emits nothing: the stored refresh token is kept and the refresh retried
+     * with backoff, so no state changed. "No event" therefore means "no
+     * confirmed transition", never "the session is fine". Only a server-REJECTED
+     * refresh token produces `signed_out(session_expired)`. For liveness read
+     * `getAccessToken()` (null = no usable token right now).
+     *
      * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
      * and never affects auth state. Returns an unsubscribe function.
      */
@@ -850,19 +859,36 @@ declare class Auth {
     /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
     getAccessTokenSync(): string | null;
     /**
-     * Mint (or return) an anonymous session.
-     *
-     * Reuses the existing anonymous user when there already is one — the same
-     * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-     * that calls this defensively on every cold launch (the most natural thing
-     * to write) mints a fresh `user_id` each time, and `persist()` overwrites
-     * the stored refresh token — the previous anonymous account's only durable
-     * handle — with no takeover, no webhook and no state event. That is the same
-     * silent progress loss as a failed sign-in wiping the session, except it
-     * happens on a *healthy* network.
-     *
-     * Pass `forceNew: true` to deliberately abandon the current anonymous
-     * session and mint a separate one.
+     * Return the current session, minting an anonymous one only when there is
+     * none.
+     *
+     * Reuses the existing session when there already is one — anonymous OR
+     * identified. The anonymous half is the same short-circuit Firebase's
+     * `signInAnonymously` performs. Without it, an app that calls this
+     * defensively on every cold launch (the most natural thing to write) mints a
+     * fresh `user_id` each time, and `persist()` overwrites the stored refresh
+     * token — the previous anonymous account's only durable handle — with no
+     * takeover, no webhook and no state event. That is the same silent progress
+     * loss as a failed sign-in wiping the session, except it happens on a
+     * *healthy* network.
+     *
+     * ⚠ The identified half closes the same hole from the other side (1.40.0,
+     * reported by RopoLabs). Until then the guard was `existing.isAnonymous`, so
+     * a plain `signInAnonymously()` over a LIVE ACCOUNT session fell through,
+     * minted a guest and overwrote the account's tokens locally — with no
+     * `signed_out`, because this path never wipes anything; it persists over the
+     * top. An app that called it on a "looks signed out" reading silently turned
+     * a paying account into a fresh guest, and its own session-death listener
+     * never fired. The account itself survives (row + server session untouched,
+     * recoverable by its credential) but the device is now a stranger to it.
+     * Returning the identified session is a no-op for that caller and the honest
+     * answer to "make sure I have a session" — read `user.isAnonymous` if you
+     * need to know which kind you got.
+     *
+     * Pass `forceNew: true` to deliberately abandon the current session —
+     * whichever kind — and mint a separate anonymous one. That is the ONLY way
+     * this method replaces an identified session, and it does so silently (the
+     * caller asked for it); `signOut()` first if you want a `signed_out`.
      */
     signInAnonymously(opts?: {
         name?: string;

package/dist/index.d.ts

@@ -716,6 +716,15 @@ declare class Auth {
      * A failed sign-in emits NOTHING: the session is unchanged, so there is no
      * transition to report — the rejected promise is the whole story.
      *
+     * ⚠ This is a TRANSITION stream, not a health or connectivity signal (1.40.0
+     * doc fix, reported by RopoLabs). A transient failure of the background
+     * token refresh — offline, timeout, HTTP 429, 5xx, an unparseable response —
+     * emits nothing: the stored refresh token is kept and the refresh retried
+     * with backoff, so no state changed. "No event" therefore means "no
+     * confirmed transition", never "the session is fine". Only a server-REJECTED
+     * refresh token produces `signed_out(session_expired)`. For liveness read
+     * `getAccessToken()` (null = no usable token right now).
+     *
      * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
      * and never affects auth state. Returns an unsubscribe function.
      */
@@ -850,19 +859,36 @@ declare class Auth {
     /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
     getAccessTokenSync(): string | null;
     /**
-     * Mint (or return) an anonymous session.
-     *
-     * Reuses the existing anonymous user when there already is one — the same
-     * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-     * that calls this defensively on every cold launch (the most natural thing
-     * to write) mints a fresh `user_id` each time, and `persist()` overwrites
-     * the stored refresh token — the previous anonymous account's only durable
-     * handle — with no takeover, no webhook and no state event. That is the same
-     * silent progress loss as a failed sign-in wiping the session, except it
-     * happens on a *healthy* network.
-     *
-     * Pass `forceNew: true` to deliberately abandon the current anonymous
-     * session and mint a separate one.
+     * Return the current session, minting an anonymous one only when there is
+     * none.
+     *
+     * Reuses the existing session when there already is one — anonymous OR
+     * identified. The anonymous half is the same short-circuit Firebase's
+     * `signInAnonymously` performs. Without it, an app that calls this
+     * defensively on every cold launch (the most natural thing to write) mints a
+     * fresh `user_id` each time, and `persist()` overwrites the stored refresh
+     * token — the previous anonymous account's only durable handle — with no
+     * takeover, no webhook and no state event. That is the same silent progress
+     * loss as a failed sign-in wiping the session, except it happens on a
+     * *healthy* network.
+     *
+     * ⚠ The identified half closes the same hole from the other side (1.40.0,
+     * reported by RopoLabs). Until then the guard was `existing.isAnonymous`, so
+     * a plain `signInAnonymously()` over a LIVE ACCOUNT session fell through,
+     * minted a guest and overwrote the account's tokens locally — with no
+     * `signed_out`, because this path never wipes anything; it persists over the
+     * top. An app that called it on a "looks signed out" reading silently turned
+     * a paying account into a fresh guest, and its own session-death listener
+     * never fired. The account itself survives (row + server session untouched,
+     * recoverable by its credential) but the device is now a stranger to it.
+     * Returning the identified session is a no-op for that caller and the honest
+     * answer to "make sure I have a session" — read `user.isAnonymous` if you
+     * need to know which kind you got.
+     *
+     * Pass `forceNew: true` to deliberately abandon the current session —
+     * whichever kind — and mint a separate anonymous one. That is the ONLY way
+     * this method replaces an identified session, and it does so silently (the
+     * caller asked for it); `signOut()` first if you want a `signed_out`.
      */
     signInAnonymously(opts?: {
         name?: string;

package/dist/index.js

@@ -183,7 +183,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.39.1",
+  version: "1.40.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -205,6 +205,7 @@ var package_default = {
     "dist",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "app.plugin.js",
     "plugin"
@@ -239,7 +240,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts && tsx test/anonymous-over-account.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -250,10 +251,6 @@ var package_default = {
     typescript: "^5.0.0"
   },
   license: "MIT",
-  repository: {
-    type: "git",
-    url: "https://github.com/sendoracloud/sdk-react-native"
-  },
   homepage: "https://sendoracloud.com/sdks"
 };
 
@@ -753,6 +750,15 @@ var Auth = class {
    * A failed sign-in emits NOTHING: the session is unchanged, so there is no
    * transition to report — the rejected promise is the whole story.
    *
+   * ⚠ This is a TRANSITION stream, not a health or connectivity signal (1.40.0
+   * doc fix, reported by RopoLabs). A transient failure of the background
+   * token refresh — offline, timeout, HTTP 429, 5xx, an unparseable response —
+   * emits nothing: the stored refresh token is kept and the refresh retried
+   * with backoff, so no state changed. "No event" therefore means "no
+   * confirmed transition", never "the session is fine". Only a server-REJECTED
+   * refresh token produces `signed_out(session_expired)`. For liveness read
+   * `getAccessToken()` (null = no usable token right now).
+   *
    * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
    * and never affects auth state. Returns an unsubscribe function.
    */
@@ -965,24 +971,41 @@ var Auth = class {
     return this.accessToken;
   }
   /**
-   * Mint (or return) an anonymous session.
-   *
-   * Reuses the existing anonymous user when there already is one — the same
-   * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-   * that calls this defensively on every cold launch (the most natural thing
-   * to write) mints a fresh `user_id` each time, and `persist()` overwrites
-   * the stored refresh token — the previous anonymous account's only durable
-   * handle — with no takeover, no webhook and no state event. That is the same
-   * silent progress loss as a failed sign-in wiping the session, except it
-   * happens on a *healthy* network.
-   *
-   * Pass `forceNew: true` to deliberately abandon the current anonymous
-   * session and mint a separate one.
+   * Return the current session, minting an anonymous one only when there is
+   * none.
+   *
+   * Reuses the existing session when there already is one — anonymous OR
+   * identified. The anonymous half is the same short-circuit Firebase's
+   * `signInAnonymously` performs. Without it, an app that calls this
+   * defensively on every cold launch (the most natural thing to write) mints a
+   * fresh `user_id` each time, and `persist()` overwrites the stored refresh
+   * token — the previous anonymous account's only durable handle — with no
+   * takeover, no webhook and no state event. That is the same silent progress
+   * loss as a failed sign-in wiping the session, except it happens on a
+   * *healthy* network.
+   *
+   * ⚠ The identified half closes the same hole from the other side (1.40.0,
+   * reported by RopoLabs). Until then the guard was `existing.isAnonymous`, so
+   * a plain `signInAnonymously()` over a LIVE ACCOUNT session fell through,
+   * minted a guest and overwrote the account's tokens locally — with no
+   * `signed_out`, because this path never wipes anything; it persists over the
+   * top. An app that called it on a "looks signed out" reading silently turned
+   * a paying account into a fresh guest, and its own session-death listener
+   * never fired. The account itself survives (row + server session untouched,
+   * recoverable by its credential) but the device is now a stranger to it.
+   * Returning the identified session is a no-op for that caller and the honest
+   * answer to "make sure I have a session" — read `user.isAnonymous` if you
+   * need to know which kind you got.
+   *
+   * Pass `forceNew: true` to deliberately abandon the current session —
+   * whichever kind — and mint a separate anonymous one. That is the ONLY way
+   * this method replaces an identified session, and it does so silently (the
+   * caller asked for it); `signOut()` first if you want a `signed_out`.
    */
   signInAnonymously(opts) {
     return this.serialize(async () => {
       const existing = this.user;
-      if (!opts?.forceNew && existing?.isAnonymous && this.hooks.storage.get(REFRESH_KEY)) {
+      if (!opts?.forceNew && existing && this.hooks.storage.get(REFRESH_KEY)) {
         return existing;
       }
       const data = await this.callAuth("/api/v1/auth-service/anonymous", {
@@ -2884,11 +2907,15 @@ var EventQueue = class {
     }, ms);
   }
   /**
-   * Drain the queue FIFO. Removes an event only when the server ACCEPTED it (2xx)
-   * or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it — and stops
-   * draining — on a transient failure (timeout throw, network null, 408/429/5xx),
-   * then arms a capped-exponential-backoff retry. The entire post lives inside the
-   * try/catch, so `NetworkTimeoutError` can never surface as an unhandled rejection.
+   * Drain the queue in order. Removes an event only when the server ACCEPTED it
+   * (2xx) or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it —
+   * and stops draining — on a transient failure (timeout throw, network null,
+   * 408/429/5xx), then arms a capped-exponential-backoff retry. ⚠ Since 1.39.1 a
+   * transiently-failing HEAD is first rotated to the BACK, so one poison event
+   * cannot hold everything behind it; delivery order is therefore best-effort,
+   * not strict FIFO (identity travels in each event body, not by slot). The
+   * entire post lives inside the try/catch, so `NetworkTimeoutError` can never
+   * surface as an unhandled rejection.
    */
   async flush() {
     if (this.flushing || this.q.length === 0) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.39.1",
+  "version": "1.40.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,6 +22,7 @@
     "dist",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "app.plugin.js",
     "plugin"
@@ -56,7 +57,7 @@
   "scripts": {
     "build": "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     "typecheck": "tsc --noEmit",
-    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts"
+    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts && tsx test/anonymous-over-account.test.ts"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",
@@ -67,9 +68,5 @@
     "typescript": "^5.0.0"
   },
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sendoracloud/sdk-react-native"
-  },
   "homepage": "https://sendoracloud.com/sdks"
 }