@sendoracloud/sdk-react-native 1.27.0 → 1.30.0

package/dist/index.d.cts

@@ -221,10 +221,19 @@ declare class Storage {
  *       user_id is preserved on success. Throws
  *       EmailAlreadyTakenError on 409. Otherwise calls
  *       /auth-service/signup as a fresh account.
- *   signIn(email, password) — POST /auth-service/login. Wipes local
- *       identity (anonId rotated, userId cleared, tokens dropped)
- *       BEFORE the network call so any track() fired during the
- *       round-trip can't attach to the prior identity.
+ *   signIn(email, password) — POST /auth-service/login.
+ *
+ * HARD INVARIANT — a failed auth attempt leaves the caller exactly as
+ * it found them. Every credentialed path captures the anonymous
+ * refresh token into a local (for the device-takeover hint), performs
+ * its network call, validates the response, and only THEN clears the
+ * old identity and persists the new one. Clearing first would drop the
+ * refresh token — for an anonymous user the ONLY durable handle on the
+ * account — so any failure after that point (offline, 5xx, a mistyped
+ * OTP, a cancelled IdP callback) would orphan the account permanently.
+ * A track() fired during the round-trip therefore attaches to the
+ * still-anonymous identity, which is correct: the user is not
+ * identified yet, and the backend reattributes it via the takeover.
  *
  * All public auth ops are serialized through a single-flight chain
  * so a UI double-submit can't mint two anonymous users or interleave
@@ -308,8 +317,70 @@ declare class AlreadyIdentifiedError extends Error {
  * account instead, or link a different credential.
  */
 declare class CredentialInUseError extends Error {
-    constructor(message?: string);
+    /** Always `"CREDENTIAL_IN_USE"`. */
+    readonly code = "CREDENTIAL_IN_USE";
+    /**
+     * Always `"credential_in_use"`. Carried so this can be handled in the same
+     * `switch (err.kind)` as every other auth failure.
+     *
+     * NOTE this class deliberately does NOT extend `AuthError` — widening
+     * `instanceof AuthError` to include it would silently re-route an upgrading
+     * app that checks `AuthError` before this class. The taxonomy fields are
+     * duplicated instead.
+     */
+    readonly kind: "credential_in_use";
+    /** Always false — a different account owns it; retrying changes nothing. */
+    readonly retryable = false;
+    /** The provider whose credential collided, when the server named it. */
+    readonly provider?: string;
+    /**
+     * Which collision this was: `"identity"` = that exact provider identity is
+     * already linked to another account; `"email"` = the provider's verified
+     * email already belongs to one. Absent on older backends.
+     */
+    readonly collision?: "identity" | "email";
+    readonly status?: number;
+    constructor(message?: string, opts?: {
+        provider?: string;
+        collision?: "identity" | "email";
+        status?: number;
+    });
 }
+/**
+ * What a sign-in should do when the credential you present already belongs to
+ * an account (1.30.0).
+ *
+ * - `"adopt"` (default — and what every earlier release did unconditionally):
+ *   sign in to that account. This is the reinstall-recovery path: a Game Center
+ *   / Play Games player identity survives a reinstall server-side, so the
+ *   "collision" is usually the SAME person's earlier account. If this device is
+ *   anonymous, that anonymous account is retired — **its row is deleted** — and
+ *   `onDeviceTakeover` fires with its id.
+ * - `"reject"`: throw `CredentialInUseError` and change nothing at all. Use it
+ *   when the local anonymous session holds progress you are not willing to
+ *   trade. Mirrors Firebase `linkWithCredential`
+ *   (`auth/credential-already-in-use`) and Supabase `linkIdentity`.
+ *
+ * `"reject"` blocks the switch; it does not merge the two accounts. To offer
+ * "use my other account", catch the error and re-call with `"adopt"`, then
+ * migrate your own data from `onDeviceTakeover`'s `retiredAnonUserId`.
+ */
+type CredentialCollisionPolicy = "adopt" | "reject";
+/** Options for the Game Center / Play Games sign-in methods. */
+type GameSignInOptions = {
+    /**
+     * ADR-025 link-in-place. When this device is anonymous and the player
+     * identity is BRAND NEW, the anonymous account is promoted in place and the
+     * user id (sub) is preserved. Has no effect on a collision — see
+     * `onCredentialInUse` for that case.
+     */
+    link?: boolean;
+    /**
+     * What to do when the player identity already belongs to an account.
+     * Default `"adopt"`. See {@link CredentialCollisionPolicy}.
+     */
+    onCredentialInUse?: CredentialCollisionPolicy;
+};
 /** One credential linked to an account (ADR-030 read side, s58.270). */
 type LinkedIdentity = {
     provider: string;
@@ -321,9 +392,40 @@ type LinkedIdentitiesResponse = {
     identities: LinkedIdentity[];
     hasPassword: boolean;
 };
+/**
+ * Closed set of auth failure categories (1.28.0). Branch on `kind` instead of
+ * string-matching the ~20 raw `code`s the backend and transport can produce.
+ *
+ * Pairs with the hard guarantee this release introduces: **a failed auth
+ * attempt never changes the local session.** An offline sign-in, a mistyped
+ * OTP, a dismissed Game Center sheet and a 429 all leave `getUserSync()` and
+ * the stored refresh token exactly as they were.
+ */
+type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "already_identified" | "cancelled" | "config" | "unknown";
 declare class AuthError extends Error {
     code: string;
-    constructor(code: string, message: string);
+    /**
+     * Category of the failure — the field to branch on. See `AuthErrorKind`.
+     * Derived from `code` (+ HTTP status when known); never affects `code`,
+     * which stays exactly what shipped before 1.28.0.
+     */
+    readonly kind: AuthErrorKind;
+    /** True when retrying the SAME input can plausibly succeed later. */
+    readonly retryable: boolean;
+    /**
+     * Seconds to wait before retrying, when the server told us (429 backoff, or
+     * an ACCOUNT_LOCKED cool-off). Absent means "no server-provided hint" — for
+     * `account_locked` specifically, absent means the lock does NOT expire on
+     * its own and needs support.
+     */
+    readonly retryAfterSeconds?: number;
+    /** HTTP status when the failure came from a response (absent when offline). */
+    readonly status?: number;
+    constructor(code: string, message: string, opts?: {
+        status?: number;
+        retryAfterSeconds?: number;
+        kind?: AuthErrorKind;
+    });
 }
 interface AuthHooks {
     /** Storage shared with the parent SDK so re-hydration is consistent. */
@@ -366,6 +468,40 @@ interface DeletionCancelledEvent {
     /** Local clock at the time the SDK observed the event. */
     at: Date;
 }
+/**
+ * Why the local session ended (1.28.0). Before this, a session that died in
+ * the background emitted NOTHING — an app could not tell a deliberate sign-out
+ * apart from an expired refresh token, and only discovered the difference when
+ * `getAccessToken()` started returning null.
+ *
+ * - `user`            — the app called `signOut()`.
+ * - `session_expired` — the server rejected the stored refresh token (revoked,
+ *                       expired, rotated away). Transient network failures and
+ *                       rate limits do NOT produce this.
+ * - `account_deleted` — `deleteAccount()` succeeded.
+ */
+type AuthSignedOutReason = "user" | "session_expired" | "account_deleted";
+/**
+ * A single auth-state transition (1.28.0). Subscribe with
+ * `onAuthStateChanged` — one stream covering everything that used to need
+ * separate listeners (or had none at all).
+ */
+type AuthStateChange = {
+    event: "signed_in";
+    user: AuthUser;
+} | {
+    event: "signed_out";
+    user: null;
+    reason: AuthSignedOutReason;
+} | {
+    event: "device_takeover";
+    user: AuthUser | null;
+    retiredAnonUserId: string;
+} | {
+    event: "deletion_cancelled";
+    user: AuthUser | null;
+};
+type AuthStateListener = (change: AuthStateChange) => void;
 declare class Auth {
     private hooks;
     private user;
@@ -388,6 +524,7 @@ declare class Auth {
     private refreshCooldownUntil;
     private takeoverListeners;
     private deletionCancelledListeners;
+    private authStateListeners;
     private lastDeletionCancelled;
     private lastTakeover;
     /**
@@ -413,6 +550,11 @@ declare class Auth {
      */
     private readyPromise;
     private resolveReady;
+    /**
+     * True once `hydrate()` has run. Distinguishes "no session restored YET"
+     * from "genuinely signed out" for `onAuthStateChanged`'s replay-on-subscribe.
+     */
+    private hydrated;
     constructor(hooks: AuthHooks);
     /**
      * Re-hydrate session from storage. Called by the parent SDK during
@@ -449,6 +591,31 @@ declare class Auth {
      * + logged in dev mode. Auth state never depends on listener success.
      */
     onDeviceTakeover(listener: (evt: DeviceTakeoverEvent) => void): () => void;
+    /**
+     * Subscribe to every auth-state transition (1.28.0) — the single stream that
+     * answers "what happened to my session?". Firebase `onAuthStateChanged` /
+     * Supabase `onAuthStateChange` parity.
+     *
+     * The reason it exists: a session that dies in the BACKGROUND (the server
+     * rejected the stored refresh token) used to emit no signal whatsoever, so
+     * an app could not distinguish it from a deliberate sign-out and only
+     * noticed when `getAccessToken()` began returning null. That transition is
+     * now `{ event: "signed_out", reason: "session_expired" }`.
+     *
+     * Fires the CURRENT state immediately on subscribe once `init()` has
+     * hydrated (a `signed_in` when a session was restored from disk — including
+     * offline, since hydrate is disk-only), so a subscriber never misses the
+     * state it started in. Nothing is emitted for a signed-out cold start.
+     *
+     * A failed sign-in emits NOTHING: the session is unchanged, so there is no
+     * transition to report — the rejected promise is the whole story.
+     *
+     * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
+     * and never affects auth state. Returns an unsubscribe function.
+     */
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+    /** Fan a state change out to subscribers. Never throws. */
+    private emitAuthState;
     /**
      * Inspect the most recent device-takeover event observed by the
      * SDK. Cleared on signOut. Returns null when no takeover has
@@ -506,9 +673,25 @@ declare class Auth {
     getAccessToken(): Promise<string | null>;
     /** 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.
+     */
     signInAnonymously(opts?: {
         name?: string;
         metadata?: Record<string, unknown>;
+        forceNew?: boolean;
     }): Promise<AuthUser>;
     /**
      * Create an email/password account.
@@ -569,6 +752,13 @@ declare class Auth {
          * another account (collision → falls back to takeover/merge).
          */
         link?: boolean;
+        /**
+         * What to do if this social identity (or its verified email) already
+         * belongs to an account. Default `"adopt"` = sign in to it, retiring this
+         * device's anonymous account. `"reject"` throws `CredentialInUseError` and
+         * leaves everything untouched. See {@link CredentialCollisionPolicy}.
+         */
+        onCredentialInUse?: CredentialCollisionPolicy;
     }): Promise<AuthUser>;
     signInWithGoogle(code: string, redirectUri: string, link?: boolean): Promise<AuthUser>;
     signInWithGitHub(code: string, redirectUri: string): Promise<AuthUser>;
@@ -602,12 +792,8 @@ declare class Auth {
      * `link: true` KEEPS the same user id when upgrading an anonymous device
      * (ADR-025 link-in-place); no effect off-anon or on a collision.
      */
-    signInWithGameCenter(opts?: {
-        link?: boolean;
-    }): Promise<AuthUser>;
-    signInWithGameCenter(payload: GameCenterPayload, opts?: {
-        link?: boolean;
-    }): Promise<AuthUser>;
+    signInWithGameCenter(opts?: GameSignInOptions): Promise<AuthUser>;
+    signInWithGameCenter(payload: GameCenterPayload, opts?: GameSignInOptions): Promise<AuthUser>;
     /**
      * Google Play Games sign-in (email-less, Android-only).
      *
@@ -623,14 +809,10 @@ declare class Auth {
      *
      * `link: true` = ADR-025 link-in-place (same user id on an anon upgrade).
      */
-    signInWithPlayGames(opts?: {
-        link?: boolean;
-    }): Promise<AuthUser>;
+    signInWithPlayGames(opts?: GameSignInOptions): Promise<AuthUser>;
     signInWithPlayGames(payload: {
         serverAuthCode: string;
-    }, opts?: {
-        link?: boolean;
-    }): Promise<AuthUser>;
+    }, opts?: GameSignInOptions): Promise<AuthUser>;
     /** Link email + password to the current account (sub preserved). */
     linkEmailPassword(email: string, password: string): Promise<AuthUser>;
     /** Link an OAuth social identity (verified idToken or code) to the current account. */
@@ -882,6 +1064,29 @@ declare class Auth {
     }>;
     private callAuth;
     private persist;
+    /**
+     * Drop the local session.
+     *
+     * `reason` drives the `onAuthStateChanged` emission: a real sign-out reason
+     * emits `signed_out`, while `"replaced"` (the internal pre-`persist()` clear
+     * on a SUCCESSFUL sign-in) emits nothing — subscribers see one `signed_in`,
+     * not a spurious logout/login pair.
+     *
+     * ⚠ Never call this before a fallible network request. A failed sign-in must
+     * leave the caller exactly as it found them; for an anonymous session the
+     * refresh token dropped here is the ONLY durable handle on the account, so a
+     * pre-call wipe that is not followed by a successful `persist()` orphans the
+     * account permanently (offline: deterministically). Capture the anon refresh
+     * into a local, make the call, and wipe only after the response validates.
+     */
+    /**
+     * True when `sent` is still the refresh token on disk — i.e. nothing
+     * replaced or cleared the session while a request carrying it was in
+     * flight. Guards both directions of the refresh race: installing a rotated
+     * token over a session that has since been signed out or replaced, and
+     * wiping a fresh session because an OLD token was rejected.
+     */
+    private tokenStillCurrent;
     private wipeLocalIdentity;
 }
 
@@ -1664,6 +1869,12 @@ declare class SendoraSDK {
      * Clear identity + rotate the anonymous id. Call on logout. Awaits
      * the AsyncStorage writes so a caller who kills the app immediately
      * after doesn't leave stale identity on disk.
+     *
+     * Signs out through `auth` rather than just clearing storage: `clearAll()`
+     * removes the auth keys too, so doing it directly left `Auth` holding an
+     * in-memory user and reporting itself signed in while its refresh token was
+     * already gone — with the server-side session never revoked and no
+     * `onAuthStateChanged` emission telling the app the session had ended.
      */
     reset(): Promise<void>;
     /** Tear down auto-track listeners. Call in test harnesses. */
@@ -1673,4 +1884,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { AlreadyIdentifiedError, type AttachLinkingApiOptions, Auth, AuthError, type AuthTokens, type AuthUser, CredentialInUseError, EmailAlreadyTakenError, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };
+export { AlreadyIdentifiedError, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };