@sendoracloud/sdk-react-native 1.27.0 → 1.29.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
@@ -321,9 +330,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 +406,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 +462,7 @@ declare class Auth {
     private refreshCooldownUntil;
     private takeoverListeners;
     private deletionCancelledListeners;
+    private authStateListeners;
     private lastDeletionCancelled;
     private lastTakeover;
     /**
@@ -413,6 +488,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 +529,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 +611,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.
@@ -882,6 +1003,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 +1808,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 +1823,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, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, 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 };

package/dist/index.d.ts

@@ -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
@@ -321,9 +330,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 +406,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 +462,7 @@ declare class Auth {
     private refreshCooldownUntil;
     private takeoverListeners;
     private deletionCancelledListeners;
+    private authStateListeners;
     private lastDeletionCancelled;
     private lastTakeover;
     /**
@@ -413,6 +488,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 +529,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 +611,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.
@@ -882,6 +1003,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 +1808,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 +1823,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, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, 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 };