js-bao-wss-client 2.1.0-alpha.8 → 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?: {
@@ -1884,6 +1898,96 @@ export declare class JsBaoClient extends Observable<any> {
         background?: boolean;
         shouldRetain?: (docId: string) => boolean;
     }): Promise<void>;
+    /**
+     * Documents per page for the whole-scope walk. The server caps `limit` at
+     * 100 (`parseListLimitParam`), so asking for more buys nothing.
+     */
+    private static readonly SCOPE_RECONCILE_PAGE_SIZE;
+    /**
+     * How many pages the walk follows before giving up. 100 pages × 100 rows
+     * bounds it at 10k documents; a scope larger than that (or a server handing
+     * back an endless cursor) is simply not reconciled, which is the safe
+     * direction — nothing is deleted.
+     */
+    private static readonly SCOPE_RECONCILE_MAX_PAGES;
+    /**
+     * Shortest gap between two whole-scope reconciliations. A walk costs one
+     * request per 100 documents, so a client that reconnects through a flaky
+     * network must not pay for it on every socket.
+     */
+    private scopeReconcileMinIntervalMs;
+    /** The walk currently running, so concurrent connects share one. */
+    private scopeReconcileInFlight;
+    /** When the last walk finished, completed or not. */
+    private scopeReconcileLastRunAt;
+    /**
+     * Bumped whenever the signed-in user changes. Both the staleness window and
+     * a walk in flight are about one user's scope, and say nothing about the
+     * next user's.
+     */
+    private scopeReconcileGeneration;
+    /**
+     * Reconcile the local metadata cache against the user's whole document
+     * scope, evicting the documents the server no longer has (#2852).
+     *
+     * Eviction used to happen only inside `documents.list()`, whose response is
+     * reconciled `authoritative: true`. Both clients steer developers off that
+     * method (#628) and onto `me.ownedDocuments` / `me.sharedDocuments`, which
+     * are strict subsets of the cached scope and so stay merge-only — correct
+     * for a subset, but it left an app that never calls the deprecated method
+     * with no eviction path at all: metadata rows and multi-megabyte `yjs_docs`
+     * snapshots of deleted documents accumulated for as long as it kept
+     * launching.
+     *
+     * So this runs on its own schedule — once per connect, and at most once per
+     * `scopeReconcileMinIntervalMs` — rather than as a side effect of a listing
+     * call, which would put a full scope walk behind every list.
+     *
+     * The walk is what makes the result trustworthy. An unpaged `GET /documents`
+     * returns a bare array 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 whole scope would delete real local data for
+     * anyone with more than 100 documents. The paged form returns
+     * `{ items, hasMore, nextCursor }`, which is followed here to exhaustion, and
+     * 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. 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
      * @param options - Controls how the merge is performed
@@ -2615,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
@@ -2654,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
      */
@@ -2781,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;
@@ -2975,7 +3123,9 @@ export declare class JsBaoClient extends Observable<any> {
         ttlMs?: number;
         preserveOnSignOut?: boolean;
     }): void;
-    /** Create a new document, optionally local-only for offline-first creation.
+    /** Create a new document. Writable locally immediately, with the server
+     * commit racing in the background — unless `options.localOnly` is set, in
+     * which case the document never syncs.
      * @param options - Document creation options
      * @group Documents */
     createDocument(options: CreateDocumentOptions): Promise<{