@sendoracloud/sdk-react-native 1.39.1 → 1.41.0

package/README.md

@@ -192,38 +192,90 @@ Full paste-ready recipes live in [`examples/links-share.tsx`](./examples/links-s
 
 `SendoraCloud.auth` covers anonymous sign-in, email + password, magic link, email OTP, TOTP MFA, recovery codes, OIDC / SAML SSO, Sign in with Apple, Google, Microsoft, LinkedIn, Facebook, Discord. See [auth quickstart](https://sendoracloud.com/docs/quickstart-react-native#auth).
 
-### Anonymous → identified lifecycle
+### Auth status — `status()` is the only way to tell `withheld` from `signed_out`
 
-The SDK creates an anonymous user on first `init()`. Every `track()` / `identify()` attaches to that `user_id` until the user signs up or signs in. Two transitions exist; both preserve analytics continuity, but the second one requires one extra line of code from your app:
+```ts
+await SendoraCloud.auth.authStateReady(); // resolves after the disk hydrate; never waits on the network
+switch (SendoraCloud.auth.status()) {
+  case "anonymous":  /* a guest session */ break;
+  case "identified": /* a signed-in account */ break;
+  case "signed_out": /* no session */ break;
+  case "unknown":    /* a refresh token exists but the user is not known yet */ break;
+  case "withheld":   /* the stored session belongs to another project — see below */ break;
+  default:           /* ⚠ REQUIRED: a later SDK may add a status (opt-in gated or in a MAJOR) */ break;
+}
+```
+
+`getUserSync()` is `null` and `isReady()` is `true` in `signed_out`, `unknown` AND `withheld` — only
+`status()` tells them apart. Always keep a `default` branch.
+
+### Anonymous → identified (1.41.0, ADR-033 "One Slot, Two Verbs")
 
-**Case 1 — fresh signup.** `auth.signUp(email, password)` detects the anonymous refresh token and calls `/auth-service/upgrade` first, which flips `is_anonymous=false` + sets the password on the SAME row. The `user_id` is preserved — no funnel break. Falls back to a fresh `/signup` if the bound user is already identified (rare race).
+The SDK creates an anonymous (guest) user on first `ensureSession()` / `signInAnonymously()`. From there
+there are exactly two verbs:
+
+**Link — the only upgrade (same `user.id`).** `signUp(email, password)` from a guest attaches the email to
+the SAME row (`/me/link/email`) — the id is preserved, no funnel break. `signInWith*({ link: true })`,
+`loginSocial({ link: true })`, `link*()` and the typed `auth.link(credential)` do the same for a social /
+Game Center / Play Games identity. Over an already-identified session `link:true` **attaches or errors —
+it never switches accounts**:
 
 ```ts
-const { user } = await SendoraCloud.auth.signUp(email, password);
-// user.id === the same id the anon user had. Done.
+const r = await SendoraCloud.auth.link({ kind: "gameCenter", ...payload });
+switch (r.status) {
+  case "done": /* r.upgraded (guest promoted) / r.alreadyLinked (nothing changed) */ break;
+  case "credential_in_use": // owned by another account — nothing changed
+    // await r.switchAccount()  → sign in to that account (bound to THIS credential); or r.keepCurrent()
+    break;
+  case "recent_auth_required": /* re-authenticate, then retry */ break;
+}
 ```
 
-**Case 2 — email already exists.** `signUp()` throws `EmailAlreadyTakenError` without consuming the anon refresh. You fall back to `signIn()` — but `signIn()` wipes the local anon identity, so anon events stay orphaned on the backend unless you transfer them with `auth.merge(anonRefresh)`. Capture the anon refresh BEFORE the signIn:
+`signUp()` over an identified session throws `AlreadyIdentifiedError` locally; an email already owned by
+another account throws `EmailAlreadyTakenError`.
 
-```ts
-try {
-  const { user } = await SendoraCloud.auth.signUp(email, password);
-} catch (err) {
-  if (!(err instanceof EmailAlreadyTakenError)) throw err;
+**Sign in — a switch that HOLDS the guest.** `signIn()`, `loginSocial()`, `signInWithGameCenter()` /
+`PlayGames()`, magic link, email OTP, SSO and `auth.signInWith(credential)` never delete, adopt or merge
+the guest any more. The guest's live tokens are **held on the device** (up to 5) and the account is
+installed: `guest_held{userId,count}` then ONE `signed_in{cause:'sign_in'}` (no `signed_out`). The guest's
+server row survives.
 
-  const anonRefresh = await SendoraCloud.auth.getRefreshToken();
-  const { user } = await SendoraCloud.auth.signIn(email, password);
+### Held guests
 
-  // Best-effort, silent-fail-tolerant — anon row may be already drained.
-  if (anonRefresh) {
-    SendoraCloud.auth.merge(anonRefresh).catch(() => undefined);
-  }
-}
+```ts
+const held = SendoraCloud.auth.getHeldGuests();      // newest first: [{ userId, heldAt, ... }]
+await SendoraCloud.auth.restoreHeldGuest(id);         // sign back in AS the guest (current account is held if it was a guest)
+await SendoraCloud.auth.discardHeldGuest(id);         // delete the guest server-side (real erasure)
+await SendoraCloud.auth.claimHeldGuest(id);           // OPTIONAL + destructive: merge the guest INTO the current account
 ```
 
-**Why merge isn't automatic on signIn.** Two people sharing a device (browser kiosk, family iPad) would silently get their anon-session events combined with a third party's real account. Forcing the merge call into your app keeps the data-mixing decision explicit. Wrap `signIn()` with the snippet above if you want auto behaviour.
+- `id` may be omitted only when exactly one guest is held (else `AMBIGUOUS_HELD_GUEST`).
+- `claimHeldGuest()` reassigns Sendora-side data and deletes the guest row (fires `auth.user_merged`); it
+  does not touch YOUR backend's data keyed on the guest id. **Never call it from an app whose backend does
+  not act on `auth.user_merged`** — most apps should restore or discard instead.
+- `init({ autoRestoreHeldGuest })` (default `true`): `ensureSession()` in `signed_out` restores the newest
+  held guest instead of minting, visibly (`signed_in{cause:'restore'}` + `guest_released{reason:'restored'}`).
+  A dead slot is released (`guest_released{reason:'dead'}`) and the next tried, then it mints.
+- `signInAnonymously({ forceNew: true })` from a guest holds it; with 5 held it throws `HeldGuestLimitError`.
+- `deleteAccount()` keeps held guests (never auto-restored afterwards);
+  `deleteAccount({ alsoDiscardHeldGuests: true })` deletes them too.
+- `SendoraCloud.reset()` keeps held guests (a guest's refresh token is its only credential);
+  `reset({ includeHeldGuests: true })` releases them locally (no server delete).
+- The deprecated `merge(token)` routes a token matching a held guest to `claimHeldGuest()`.
+
+### Project guard (`expectedProjectId`, opt-in)
 
-Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing-email](https://sendoracloud.com/docs/quickstart-react-native#anon-existing-email).
+```ts
+await SendoraCloud.init({ apiKey, projectId: PROJECT_ID, expectedProjectId: PROJECT_ID });
+```
+
+A stored, refreshed or restored session whose JWT `project` claim names a different project is
+**`withheld`**: nothing is written to storage, every auth verb rejects
+`AuthError{ kind: 'config', code: 'SESSION_WITHHELD' }`, `getAccessToken()` returns `null`, and
+`auth.getWithheld()` says whose session it was. Exits: relaunch with the matching key, or
+`auth.discardWithheld()` (clears the session only — held guests, the event queue and the analytics id are
+kept). A freshly minted / signed-in session that disagrees is rejected with `PROJECT_MISMATCH` and revoked.
+Subscribe with `SendoraCloud.onIdentityWithheld(cb)` to record the old user id before discarding.
 
 ## Config
 
@@ -240,12 +292,20 @@ Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing
   androidPackageName?: string;
   linkDomain?: string;          // Custom share host (e.g. "pulse.link"). Defaults to Sendora's.
   debug?: boolean;
+  expectedProjectId?: string;    // ADR-033 project guard (opt-in) — see "Project guard".
+  autoRestoreHeldGuest?: boolean; // Default true — see "Held guests".
 }
 ```
 
 ## 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` (`cause`: `mint` | `sign_in` | `restore` | `link`), `signed_out` (reason `user` | `session_expired` | `account_deleted` | `revoked` | `evicted` | `deleted`), `user_updated`, `guest_held`, `guest_released`, `session_withheld`, `device_takeover`, `deletion_cancelled`. Each subscriber first receives one `initial{status, user}` (1.41.0); with a live session it is followed by the same `signed_in{user}` replay 1.28–1.40 sent (no `cause`), so existing listeners keep working. New code: read `initial` and treat a cause-less `signed_in` right after it as the replay. 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 leave the current session and mint a fresh anonymous one (a guest left this way is held, not lost).
 
 ## JWT verification (custom backend)