js-bao-wss-client 2.1.0-alpha.9 → 2.1.0

package/README.md

@@ -921,10 +921,17 @@ const all = await client.documents.list({ includeRoot: true });
 
 ## OAuth Authentication
 
+Google registers a separate OAuth client per platform, so the server publishes a
+client MAP keyed by client type (`web`, `ios`, `android`, `desktop`,
+`chrome-extension`). A browser reads the `web` entry; there is no single
+"is Google available" flag, because one could only ever be right for one
+platform.
+
 ```typescript
-// Check if OAuth is available
-const hasOAuth = await client.checkOAuthAvailable();
-if (hasOAuth) {
+// Check if Google sign-in is available for THIS (browser) client: the provider
+// is enabled and the web entry is usable.
+const googleAvailable = await client.checkOAuthAvailable();
+if (googleAvailable) {
   // Start OAuth flow (redirects to Google)
   await client.startOAuthFlow();
 }
@@ -975,18 +982,45 @@ if (client.isAuthenticated()) {
 client.setToken("new-jwt-token");
 ```
 
-## Magic Link Authentication
+## Email Sign-In
 
-The client supports passwordless email authentication via magic links. Magic links must be enabled in the admin console for your app.
+One request sends ONE email carrying a 6-digit code and — when the redirect
+target is on the app's `[auth].emailRedirectUris` allow-list — a sign-in link.
+The user finishes with whichever suits them, and consuming either one retires
+both: one email signs a user in once. Email sign-in must be enabled for the app
+(`[auth].emailSignInEnabled`, on by default).
 
-### Request Magic Link
+### Request the email
 
 ```typescript
-// Send a magic link email to the user
-await client.magicLinkRequest("user@example.com");
+// `redirectUri` defaults to the client's oauthRedirectUri. With no target at
+// all the email carries the code alone, from the same template. A target that
+// IS sent must match the app's non-empty allow-list, or the request is
+// rejected 400 `Invalid redirect URI` — it never degrades to code-only.
+await client.emailSignInRequest("user@example.com", {
+  redirectUri: "https://app.example.com/auth/callback",
+});
+```
+
+Both credentials expire together, 15 minutes after the request. Rate limits
+apply (5 requests per email per hour, 20 per IP per hour).
+
+`magicLinkRequest` and `otpRequest` still work and are **deprecated**: both are
+aliases of the same issuance path and send the same email.
+
+### Finish with the code
+
+```typescript
+const { user, isNewUser } = await client.otpVerify("user@example.com", "123456");
+console.log("Logged in as:", user.email);
+
+// isNewUser is true if this is the user's first sign-in (account was just created)
+if (isNewUser) {
+  // Show onboarding flow for new users
+}
 ```
 
-### Handle Magic Link Callback
+### Finish with the link
 
 ```typescript
 // In your callback page (e.g., /oauth/callback)
@@ -998,7 +1032,6 @@ if (magicToken) {
   const { user, promptAddPasskey, isNewUser } = await client.magicLinkVerify(magicToken);
   console.log("Logged in as:", user.email);
 
-  // isNewUser is true if this is the user's first sign-in (account was just created)
   if (isNewUser) {
     // Show onboarding flow for new users
   }
@@ -1010,56 +1043,32 @@ if (magicToken) {
 }
 ```
 
-## OTP (Email Code) Authentication
-
-The client supports passwordless authentication via one-time 6-digit codes sent by email. OTP authentication must be enabled in the admin console for your app.
-
-### Request OTP Code
-
-```typescript
-// Send a 6-digit code to the user's email
-await client.otpRequest("user@example.com");
-```
-
-The code is valid for 10 minutes. Rate limits apply (5 codes per email per hour, 20 per IP per hour).
-
-### Verify OTP Code
-
-```typescript
-// Verify the code and complete authentication
-const { user, isNewUser } = await client.otpVerify("user@example.com", "123456");
-console.log("Logged in as:", user.email);
-
-// isNewUser is true if this is the user's first sign-in (account was just created)
-if (isNewUser) {
-  // Show onboarding flow for new users
-}
-```
-
 ### Error Handling
 
 ```typescript
 try {
   await client.otpVerify("user@example.com", "123456");
 } catch (error) {
-  if (error.code === "OTP_NOT_ENABLED") {
-    // OTP auth not enabled for this app
-  } else if (error.code === "RATE_LIMITED") {
+  if (error.code === "RATE_LIMITED") {
     // Too many attempts, try again later
   } else if (error.code === "OTP_MAX_ATTEMPTS") {
-    // Maximum verification attempts exceeded, request a new code
+    // Maximum verification attempts exceeded, request a new email
   } else if (error.code === "INVALID_TOKEN") {
     // Invalid or expired code
   }
 }
 ```
 
+When email sign-in is disabled the request endpoints answer a plain 400 with
+`"Email sign-in is not enabled for this app"` and no error code — gate the UI
+on `getAuthConfig()`'s `emailSignInEnabled` instead.
+
 ## Passkey Authentication
 
 The client supports WebAuthn/passkey authentication for passwordless sign-in. Passkeys must be enabled in the admin console for your app.
 
-Note: Passkeys can only be added to existing accounts (created via OAuth or Magic Link). To use passkey authentication:
-1. User creates account via OAuth or Magic Link
+Note: Passkeys can only be added to existing accounts (created via OAuth or email sign-in). To use passkey authentication:
+1. User creates account via OAuth or email sign-in
 2. User adds a passkey to their account
 3. User can then sign in with the passkey on future visits
 
@@ -1073,14 +1082,15 @@ const config = await client.getAuthConfig();
 if (config.hasPasskey) {
   console.log("Passkeys are available");
 }
-if (config.magicLinkEnabled) {
-  console.log("Magic link sign-in is available");
-}
-if (config.otpEnabled) {
-  console.log("OTP (email code) sign-in is available");
+if (config.emailSignInEnabled) {
+  console.log("Email sign-in is available");
 }
-if (config.hasOAuth) {
-  console.log("Google OAuth is available");
+// Per-platform Google configuration. `usable` is the server's shape verdict for
+// one entry — a client id, at least one redirect URI, and a client secret
+// exactly when that client type takes one. Availability is that AND the
+// provider switch, which is what `checkOAuthAvailable()` computes.
+if (config.googleOAuthEnabled && config.googleClients.clients.web?.usable) {
+  console.log("Google OAuth is available in the browser");
 }
 ```
 

package/dist/JsBaoClient.d.ts

@@ -8,6 +8,7 @@ import { type SubscribeOptions } from "./internal/databaseSubscriptions";
 import { type StorageConfig, type YjsPersistenceFactory } from "./internal/storage/index.js";
 import { BlobManager } from "./internal/blobManager";
 import { type AnalyticsEventInput } from "./internal/analyticsQueue";
+import { type GoogleClientsConfig } from "./internal/authController";
 import { type RequestOptions } from "./internal/httpClient";
 import { type DocumentPermission as DocumentAccessLevel, type LocalDocumentEntry, type LocalMetadataEntry, type DocumentDebugSnapshot } from "./internal/documentManager";
 import { DocumentsAPI, DocumentContext, type DocumentInfo, type ResolveAliasParams, type CreateDocumentOptions } from "./api/documentsApi";
@@ -32,8 +33,8 @@ import { InvitationsAPI } from "./api/invitationsApi";
 import { NotificationsAPI } from "./api/notificationsApi";
 export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
 export type { JsBaoErrorCode } from "./errors";
-export { AuthError, AUTH_CODES } from "./internal/authController";
-export type { AuthCode } from "./internal/authController";
+export { AuthError, AUTH_CODES, googleWebClientAvailable, } from "./internal/authController";
+export type { AuthCode, GoogleClientConfig, GoogleClientsConfig, } from "./internal/authController";
 export type { DocumentInfo, DocumentPermissionEntry, DocumentInvitation, DocumentInvitationResponse, DocumentAccessResult, DocumentGroupPermissionEntry, DocumentAliasInfo, DocumentAliasScope, PermissionUpdateResult, DirectPermissionGrant, DeferredPermissionGrant, PendingInvitationEntry, PendingGroupInvitationEntry, LinkAccessResult, } from "./api/documentsApi";
 export type { UserProfile, SharedDocument, SharedDocumentListResult, SharedDocumentsOptions, OwnedDocumentsOptions, } from "./api/meApi";
 export type { SessionInfo } from "./api/sessionApi";
@@ -69,7 +70,7 @@ export type { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 export type { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 export type { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 export type { CronTriggersAPI } from "./api/cronTriggersApi";
-export type { CronTriggerInfo, CreateCronTriggerParams, UpdateCronTriggerParams, CronTriggerListResult, } from "./api/cronTriggersApi";
+export type { CronTriggerInfo, CreateCronTriggerParams, UpdateCronTriggerParams, CronTriggerListResult, ObjectStatus, } from "./api/cronTriggersApi";
 export type { CreateDocumentOptions, CreateOfflineOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, } from "./api/documentsApi";
 export type { CreateDatabaseParams, UpdateDatabaseParams } from "./api/databasesApi";
 export type { CreateCollectionParams, UpdateCollectionParams, GrantCollectionGroupPermissionParams, ListCollectionsOptions, } from "./api/collectionsApi";
@@ -325,7 +326,10 @@ export interface PromptsAPI {
      * refusal rejects with a `JsBaoApiError` whose `status` is `403` and whose
      * `code` is `"PROMPT_ACCESS_DENIED"` — including when the prompt has no rule
      * stored at all, which denies every caller who is not an app admin or owner.
-     * A prompt that is neither `active` nor `draft` rejects with a `400`.
+     * A prompt that is not in service rejects with a `400` whose `code` is
+     * `"PROMPT_NOT_EXECUTABLE"`. Availability is a single server-owned `status`:
+     * only an `active` prompt executes here, and `primitive prompts enable`
+     * puts an inactive one back in service.
      */
     execute<V extends object = Record<string, unknown>, R = unknown>(promptKey: string, options: ExecutePromptOptions<V>): Promise<ExecutePromptResult<R>>;
 }
@@ -384,6 +388,16 @@ export interface JsBaoClientOptions {
     };
     sync?: {
         outboundDebounceMs?: number;
+        /**
+         * How long a handshake may take before the client gives up on it and lets
+         * the reconnect logic retry, in milliseconds. Defaults to 10000, and is
+         * also settable through `CLIENT_SYNC_HANDSHAKE_TIMEOUT_MS`.
+         *
+         * The budget covers both halves: opening the WebSocket (an endpoint that
+         * accepts the connection but never answers the upgrade is abandoned here,
+         * rather than holding the connect open forever) and the sync handshake
+         * that follows it.
+         */
         handshakeTimeoutMs?: number;
     };
     commitRetryBackoff?: {
@@ -1938,9 +1952,41 @@ export declare class JsBaoClient extends Observable<any> {
      * only the union of a completed walk evicts. Anything short of that — a
      * failed request, a server that ignores `limit` and answers with a bare
      * array, a page that claims more rows with no cursor to ask for them, a
-     * cursor that stops advancing, the page cap — evicts nothing.
+     * cursor that stops advancing, the page cap — evicts nothing. Nor does a
+     * completed walk whose union is empty: the request asks `includeRoot=true`,
+     * so zero rows is an anomalous answer rather than a user with no documents
+     * (#2859).
      */
     private reconcileDocumentScope;
+    /**
+     * The hand-off from an unpaged `documents.list()` to the scope walk (#2919).
+     *
+     * `documentsApi` used to reconcile the caller's own listing response
+     * `authoritative: true` whenever the request was not paged. But the unpaged
+     * `GET /documents` is a bare array the server silently truncated at
+     * dynamo-bao's 100-row `defaultQueryLimit`, so a truncated listing and a
+     * complete one are the same bytes: reading one as the server's whole view of
+     * the scope deleted the metadata row — and the cached CRDT state, unflushed
+     * offline edits included — of every cached document past the truncation
+     * point. So the response now merges only, and the eviction decision is left
+     * to `reconcileDocumentScope`, whose paged walk is the only read that can
+     * say where the scope ends. Mirrors the swift-client's
+     * `reconcileByWalkingScope(seenIds:)` (#2827 / PR #2841).
+     *
+     * `seenIds` is what the caller's response already accounted for. When no
+     * cached document is missing from it, an authoritative pass would have
+     * nothing to delete and the walk is skipped — an app whose documents fit in
+     * one response issues no extra request. The root is exempt from that
+     * question: the listing filters it out of its own response, so it is always
+     * "missing", and treating it as a truncation would put a scope walk behind
+     * every listing.
+     *
+     * The walk is NOT forced. Above the truncation threshold every unpaged
+     * listing looks truncated, so forcing would make each `documents.list()` pay
+     * a full N/100-request walk; it shares the connect-time walk's staleness
+     * window instead.
+     */
+    private _reconcileScopeAfterListing;
     private _runScopeReconcile;
     /** Update local metadata cache with server document data.
      * @param items - Array of server document records to merge into the local cache
@@ -2673,12 +2719,49 @@ export declare class JsBaoClient extends Observable<any> {
         name: string;
         mode: "public" | "invite-only" | "domain";
         waitlistEnabled: boolean;
-        hasOAuth: boolean;
+        /**
+         * Whether THIS (browser) client can start Google sign-in: the provider is
+         * enabled and the `web` entry is usable. A single server-side flag could
+         * not tell a web-configured app from a native-configured one, so this is
+         * computed per platform from the client map.
+         */
+        googleAvailable: boolean;
         hasPasskey: boolean;
+        /**
+         * Is email sign-in available? ONE flag: one request sends one email
+         * carrying both credentials.
+         */
+        emailSignInEnabled: boolean;
+        /** @deprecated Always equal to `emailSignInEnabled`. */
         magicLinkEnabled: boolean;
     }>;
+    /**
+     * Request one sign-in email. It carries a 6-digit code and — when a redirect
+     * target is available AND the app allow-lists it — a sign-in link, so the
+     * user can finish on the device they started on or on whichever device has
+     * their mail. Nothing selects a method up front.
+     *
+     * Finish with `otpVerify(email, code)` for the code, or `magicLinkVerify(token)`
+     * for the link. Consuming either one retires both: one email, one session.
+     *
+     * @param email - The email address to sign in
+     * @param options - Optional configuration
+     * @param options.redirectUri - Where the link should land. Defaults to the
+     *   client's `oauthRedirectUri`. With neither, the email carries the code
+     *   alone rather than failing.
+     * @group Authentication
+     */
+    emailSignInRequest(email: string, options?: {
+        redirectUri?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
     /**
      * Request a magic link email for passwordless authentication.
+     *
+     * @deprecated Use {@link emailSignInRequest}. This is an alias of it — the
+     * server issues through the same path and sends the same email, which now
+     * also carries a 6-digit code.
      * @param email - The email address to send the magic link to
      * @param options - Optional configuration
      * @param options.redirectUri - Override the default OAuth redirect URI for the magic link callback
@@ -2712,6 +2795,9 @@ export declare class JsBaoClient extends Observable<any> {
     /**
      * Request a one-time password (OTP) code to be sent to the specified email.
      * The code can be verified using `otpVerify()`.
+     *
+     * @deprecated Use {@link emailSignInRequest}. This is an alias of it that
+     * carries no redirect target, so the email it sends is code-only.
      * @param email - The email address to send the OTP code to
      * @group Authentication
      */
@@ -2839,17 +2925,21 @@ export declare class JsBaoClient extends Observable<any> {
         mode: string;
         waitlistEnabled: boolean;
         googleOAuthEnabled: boolean;
-        googleClientId: string | null;
-        hasOAuth: boolean;
-        redirectUris: string[] | null;
+        googleClients: GoogleClientsConfig;
         passkeyEnabled: boolean;
-        passkeyRpId: string | null;
-        passkeyRpName: string | null;
         passkeyRpConfig: Record<string, {
             name: string;
         }> | null;
         hasPasskey: boolean;
+        /**
+         * Is email sign-in available at all (#2884)? ONE flag — one request sends
+         * one email carrying both credentials, so there is no per-method
+         * availability to report.
+         */
+        emailSignInEnabled: boolean;
+        /** @deprecated (#2884) Always equal to `emailSignInEnabled`. */
         magicLinkEnabled: boolean;
+        /** @deprecated (#2884) Always equal to `emailSignInEnabled`. */
         otpEnabled: boolean;
         hasApple: boolean;
         appleSignInEnabled: boolean;

package/dist/JsBaoClient.js

@@ -11,7 +11,7 @@ import { deleteIdbByName } from "./internal/storage/idbUtils.js";
 import { BlobManager } from "./internal/blobManager";
 import { BrowserConnectivityMonitor, CONNECTIVITY_LOST, CONNECTIVITY_RESTORED, USER_SET, } from "./internal/connectivityMonitor";
 import { createAnalyticsQueue, } from "./internal/analyticsQueue";
-import { AuthController, exchangeOAuthCode, parseJwtPayload, } from "./internal/authController";
+import { AuthController, exchangeOAuthCode, googleWebClientAvailable, parseJwtPayload, } from "./internal/authController";
 import { HttpClient, } from "./internal/httpClient";
 import { DocumentManager, } from "./internal/documentManager";
 import { ensureArrayBuffer, toBase64, fromBase64, decompressGzip, } from "./utils/binary";
@@ -38,7 +38,7 @@ import { CollectionsAPI } from "./api/collectionsApi";
 import { InvitationsAPI } from "./api/invitationsApi";
 import { NotificationsAPI } from "./api/notificationsApi";
 export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
-export { AuthError, AUTH_CODES } from "./internal/authController";
+export { AuthError, AUTH_CODES, googleWebClientAvailable, } from "./internal/authController";
 export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
 const DEFAULT_RETURN_ACTIVE_MIN_MS = 5 * 60 * 1000;
 const DEFAULT_SYNC_ERROR_MIN_MS = 30 * 1000;
@@ -771,6 +771,10 @@ export class JsBaoClient extends Observable {
         this.wsManager = new WebSocketManager({
             logger,
             maxReconnectDelayMs: this.maxReconnectDelay,
+            // The handshake budget covers the socket coming up as well as the sync
+            // handshake that follows it: an endpoint that accepts the connection and
+            // never answers the upgrade must not hold connect() open forever (#2923).
+            connectTimeoutMs: this.syncWatchdogTimeoutMs,
             hasAccessToken: () => !!this.token,
             buildConnectionRequest: (connectionId) => this.buildWebSocketRequest(connectionId),
             createWebSocket: (url, headers) => this.createWebSocketInstance(url, headers),
@@ -1384,7 +1388,10 @@ export class JsBaoClient extends Observable {
      * only the union of a completed walk evicts. Anything short of that — a
      * failed request, a server that ignores `limit` and answers with a bare
      * array, a page that claims more rows with no cursor to ask for them, a
-     * cursor that stops advancing, the page cap — evicts nothing.
+     * cursor that stops advancing, the page cap — evicts nothing. Nor does a
+     * completed walk whose union is empty: the request asks `includeRoot=true`,
+     * so zero rows is an anomalous answer rather than a user with no documents
+     * (#2859).
      */
     reconcileDocumentScope(options) {
         if (this.scopeReconcileInFlight)
@@ -1418,6 +1425,62 @@ export class JsBaoClient extends Observable {
         this.scopeReconcileInFlight = run;
         return run;
     }
+    /**
+     * The hand-off from an unpaged `documents.list()` to the scope walk (#2919).
+     *
+     * `documentsApi` used to reconcile the caller's own listing response
+     * `authoritative: true` whenever the request was not paged. But the unpaged
+     * `GET /documents` is a bare array the server silently truncated at
+     * dynamo-bao's 100-row `defaultQueryLimit`, so a truncated listing and a
+     * complete one are the same bytes: reading one as the server's whole view of
+     * the scope deleted the metadata row — and the cached CRDT state, unflushed
+     * offline edits included — of every cached document past the truncation
+     * point. So the response now merges only, and the eviction decision is left
+     * to `reconcileDocumentScope`, whose paged walk is the only read that can
+     * say where the scope ends. Mirrors the swift-client's
+     * `reconcileByWalkingScope(seenIds:)` (#2827 / PR #2841).
+     *
+     * `seenIds` is what the caller's response already accounted for. When no
+     * cached document is missing from it, an authoritative pass would have
+     * nothing to delete and the walk is skipped — an app whose documents fit in
+     * one response issues no extra request. The root is exempt from that
+     * question: the listing filters it out of its own response, so it is always
+     * "missing", and treating it as a truncation would put a scope walk behind
+     * every listing.
+     *
+     * The walk is NOT forced. Above the truncation threshold every unpaged
+     * listing looks truncated, so forcing would make each `documents.list()` pay
+     * a full N/100-request walk; it shares the connect-time walk's staleness
+     * window instead.
+     */
+    async _reconcileScopeAfterListing(seenIds) {
+        // The index is what says which documents are cached, and at launch it is
+        // filled asynchronously from persistence. Asking before that read lands
+        // finds nothing unaccounted for and skips a walk that was owed.
+        try {
+            await this._loadAllMetadataFromIdb();
+        }
+        catch { }
+        const rootDocId = this.getRootDocId();
+        let unaccounted = false;
+        for (const [documentId, meta] of this.docManager.metadataIndex) {
+            if (!documentId || seenIds.has(documentId))
+                continue;
+            if (rootDocId && documentId === rootDocId)
+                continue;
+            // Local-only documents and pending creates the server has never heard of
+            // are absent from every listing, and say nothing about truncation.
+            if (meta?.localOnly === true)
+                continue;
+            if (this.isPendingCreate(documentId))
+                continue;
+            unaccounted = true;
+            break;
+        }
+        if (!unaccounted)
+            return;
+        void this.reconcileDocumentScope({ reason: "list-truncated" });
+    }
     async _runScopeReconcile(reason, generation) {
         // The index is what says which documents are cached, and at launch it is
         // filled asynchronously from persistence. Walking before that read lands
@@ -1504,11 +1567,29 @@ export class JsBaoClient extends Observable {
                 // A scope walked as one user says nothing about the one signed in now.
                 if (generation !== this.scopeReconcileGeneration)
                     return;
+                // A completed walk that found nothing at all. The request asks
+                // `includeRoot=true`, so the server's answer to it always carries at
+                // least the caller's root: zero rows is an anomalous answer, not a user
+                // with no documents, and reading it as the whole scope evicts every
+                // cached document on the device (#2859). One row — the root, and
+                // nothing else — is the user whose documents really were all deleted,
+                // and that page still evicts the rest of the cache.
+                if (union.length === 0) {
+                    logger.debug("[metadata] scope reconcile declined (walk found no documents)", {
+                        reason,
+                        pages: page + 1,
+                    });
+                    return;
+                }
                 logger.debug("[metadata] scope reconcile walked the scope", {
                     reason,
                     documents: union.length,
                     pages: page + 1,
                 });
+                // The walk asks for the root, so the union carries it — retaining it by
+                // id as well means the cache does not depend on the server having said
+                // so. Mirrors the swift client's `reconcileScopeAtConnect`.
+                const rootDocId = this.getRootDocId();
                 await this.syncMetadata({
                     scope: "all",
                     payloadType: "full",
@@ -1516,6 +1597,7 @@ export class JsBaoClient extends Observable {
                     authoritative: true,
                     includeRoot: true,
                     background: true,
+                    retainIds: rootDocId ? [rootDocId] : undefined,
                     shouldRetain: (documentId) => !isEvictable(documentId),
                 });
                 return;
@@ -4614,7 +4696,13 @@ export class JsBaoClient extends Observable {
             return new WebSocketImpl(finalUrl);
         }
         logger.log(`[DIAGNOSTIC] Node.js environment - using headers option`);
-        return new WebSocketImpl(wsUrl, { headers });
+        // `handshakeTimeout` makes the transport itself give up on an upgrade that
+        // is never answered; the manager's own connect deadline covers the socket
+        // implementations (browser included) that have no such option.
+        return new WebSocketImpl(wsUrl, {
+            headers,
+            handshakeTimeout: this.syncWatchdogTimeoutMs,
+        });
     }
     shouldTriggerHandshakeRecovery() {
         // A close the client asked for is not a handshake the server refused. A
@@ -4625,6 +4713,15 @@ export class JsBaoClient extends Observable {
         // close.
         if (this.wsLastCloseInitiator === "forceReconnect")
             return false;
+        // An endpoint that never answered the upgrade refused nothing either: the
+        // connect deadline abandoned the attempt without the server ever ruling on
+        // the token (#2923). Treating that as an auth failure would refresh
+        // against an endpoint that is not answering, and — because recovery
+        // suppresses `shouldReconnect` — swallow the one reconnect the manager
+        // would otherwise schedule, leaving the retry to a refresh that may never
+        // succeed. A transport timeout belongs to the backoff loop.
+        if (this.wsLastCloseInitiator === "connectTimeout")
+            return false;
         if (this.wsHandshakeCompleted)
             return false;
         if (this.wsHandshakeRecoveryInFlight)
@@ -7104,14 +7201,43 @@ export class JsBaoClient extends Observable {
             name: config.name,
             mode: config.mode,
             waitlistEnabled: config.waitlistEnabled,
-            hasOAuth: config.hasOAuth,
+            googleAvailable: googleWebClientAvailable(config),
             hasPasskey: config.hasPasskey,
-            magicLinkEnabled: config.magicLinkEnabled,
+            emailSignInEnabled: config.emailSignInEnabled,
+            magicLinkEnabled: config.emailSignInEnabled,
         };
     }
+    // ============ Email Sign-In (#2884) ============
+    /**
+     * Request one sign-in email. It carries a 6-digit code and — when a redirect
+     * target is available AND the app allow-lists it — a sign-in link, so the
+     * user can finish on the device they started on or on whichever device has
+     * their mail. Nothing selects a method up front.
+     *
+     * Finish with `otpVerify(email, code)` for the code, or `magicLinkVerify(token)`
+     * for the link. Consuming either one retires both: one email, one session.
+     *
+     * @param email - The email address to sign in
+     * @param options - Optional configuration
+     * @param options.redirectUri - Where the link should land. Defaults to the
+     *   client's `oauthRedirectUri`. With neither, the email carries the code
+     *   alone rather than failing.
+     * @group Authentication
+     */
+    async emailSignInRequest(email, options) {
+        const redirectUri = options?.redirectUri || this.options.oauthRedirectUri;
+        return this.auth.emailSignInRequest({
+            email,
+            ...(redirectUri ? { redirectUri } : {}),
+        });
+    }
     // ============ Magic Link Methods ============
     /**
      * Request a magic link email for passwordless authentication.
+     *
+     * @deprecated Use {@link emailSignInRequest}. This is an alias of it — the
+     * server issues through the same path and sends the same email, which now
+     * also carries a 6-digit code.
      * @param email - The email address to send the magic link to
      * @param options - Optional configuration
      * @param options.redirectUri - Override the default OAuth redirect URI for the magic link callback
@@ -7142,6 +7268,9 @@ export class JsBaoClient extends Observable {
     /**
      * Request a one-time password (OTP) code to be sent to the specified email.
      * The code can be verified using `otpVerify()`.
+     *
+     * @deprecated Use {@link emailSignInRequest}. This is an alias of it that
+     * carries no redirect target, so the email it sends is code-only.
      * @param email - The email address to send the OTP code to
      * @group Authentication
      */
@@ -7247,8 +7376,8 @@ export class JsBaoClient extends Observable {
         if (!this.token &&
             this.options.autoOAuth &&
             this.options.oauthRedirectUri) {
-            const hasOAuth = await this.auth.checkOAuthAvailable();
-            if (hasOAuth) {
+            const googleAvailable = await this.auth.checkOAuthAvailable();
+            if (googleAvailable) {
                 await this.auth.startOAuthFlow({
                     redirectUri: this.options.oauthRedirectUri,
                 });