js-bao-wss-client 1.3.7 → 1.3.9

package/dist/JsBaoClient.d.ts

@@ -8,7 +8,7 @@ import { BlobManager } from "./internal/blobManager";
 import { type AnalyticsEventInput } from "./internal/analyticsQueue";
 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 } from "./api/documentsApi";
+import { DocumentsAPI, DocumentContext, type DocumentInfo, type ResolveAliasParams, type CreateDocumentOptions } from "./api/documentsApi";
 import { type CacheFacade } from "./api/cacheFacade";
 import { MeAPI } from "./api/meApi";
 import { SessionAPI } from "./api/sessionApi";
@@ -24,12 +24,12 @@ export { JsBaoError, isJsBaoError } from "./errors";
 export type { JsBaoErrorCode } from "./errors";
 export { AuthError, AUTH_CODES } from "./internal/authController";
 export type { AuthCode } from "./internal/authController";
-export type { DocumentInfo, DocumentPermissionEntry, DocumentInvitation, DocumentInvitationResponse, DocumentAccessResult, DocumentGroupPermissionEntry, } from "./api/documentsApi";
+export type { DocumentInfo, DocumentPermissionEntry, DocumentInvitation, DocumentInvitationResponse, DocumentAccessResult, DocumentGroupPermissionEntry, DocumentAliasInfo, DocumentAliasScope, } from "./api/documentsApi";
 export type { UserProfile } from "./api/meApi";
 export type { SessionInfo } from "./api/sessionApi";
 export type { BasicUserInfo } from "./api/usersApi";
 export type { DatabaseInfo, DatabasePermissionEntry, DatabaseOwnershipTransferResult, DatabaseOperationInfo, CsvImportOptions, CsvImportProgress, CsvImportResult, } from "./api/databasesApi";
-export type { GroupInfo, GroupMemberInfo, GroupMembershipInfo, GroupDocumentInfo, } from "./api/groupsApi";
+export type { GroupInfo, GroupMemberInfo, GroupMembershipInfo, GroupDocumentInfo, PaginatedResult, } from "./api/groupsApi";
 export type { CollectionInfo, CollectionDocumentInfo, CollectionGroupPermissionInfo, CollectionMemberInfo, CollectionAccessInfo, DocumentCollectionInfo, } from "./api/collectionsApi";
 export type { RuleSetInfo, RuleSetSchema, RuleSetTestResult, RuleSetDebugResult, TraceEntry, TriggerDefInfo, ModelRulesInfo, } from "./api/ruleSetsApi";
 export type { GroupTypeConfigInfo } from "./api/groupTypeConfigsApi";
@@ -37,6 +37,19 @@ export type { DoDb, DOClientEngine, ModelIdentifier, ModelFieldInfo } from "js-b
 export type { CacheFacade } from "./api/cacheFacade";
 export type { ReasoningOptions, LlmChatOptions } from "./api/llmApi";
 export type { AnalyticsEventInput } from "./internal/analyticsQueue";
+export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
+export type { DocumentBlobContext, BlobUploadSourceOptions, BlobUploadResult, BlobListResult, BlobUploadStatus, BlobReadOptions, BlobPrefetchOptions, BlobProxyUrlOptions, BlobDisposition, } from "./internal/blobManager";
+export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI } from "./api/documentsApi";
+export type { DatabasesAPI } from "./api/databasesApi";
+export type { CollectionsAPI } from "./api/collectionsApi";
+export type { GeminiAPI } from "./api/geminiApi";
+export type { LlmAPI } from "./api/llmApi";
+export type { MeAPI } from "./api/meApi";
+export type { SessionAPI } from "./api/sessionApi";
+export type { UsersAPI } from "./api/usersApi";
+export type { GroupsAPI } from "./api/groupsApi";
+export type { RuleSetsAPI } from "./api/ruleSetsApi";
+export type { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 export interface AnalyticsAutoEventsOptions {
     dailyAuth?: boolean;
     returnActive?: boolean;
@@ -518,6 +531,67 @@ export interface WorkflowDefineOptions {
     /** Handler to apply workflow results to the document. Called automatically when this workflow completes with needsApply. */
     onApply: WorkflowApplyHandler;
 }
+/** Options for {@link JsBaoClient.waitForUserId}. */
+export interface WaitForUserIdOptions {
+    /** Maximum time to wait before rejecting (ms). */
+    timeoutMs?: number;
+}
+/** Options for {@link JsBaoClient.waitForAuthReady}. */
+export interface WaitForAuthReadyOptions {
+    /** Maximum time to wait before rejecting (ms). */
+    timeoutMs?: number;
+}
+/** Options for {@link JsBaoClient.enableOfflineAccess}. */
+export interface EnableOfflineAccessOptions {
+    /** If true, attempts passkey-based largeBlob storage before falling back to PIN. */
+    preferBiometric?: boolean;
+    /** If true, falls back to PIN-based offline access when passkey largeBlob is unavailable. */
+    allowPinFallback?: boolean;
+    /** Number of days the offline grant remains valid before requiring online re-authentication. */
+    ttlDays?: number;
+    /** Controls whether offline data survives sign-out. */
+    retention?: {
+        /** If true, keeps offline data when the user logs out. */
+        preserveOnSignOut?: boolean;
+    };
+    /** Async function that prompts the user for a PIN and returns it. */
+    pinProvider?: () => Promise<string>;
+}
+/** Options for {@link JsBaoClient.revokeOfflineGrant}. */
+export interface RevokeOfflineGrantOptions {
+    /** If true, also deletes all locally stored document data. */
+    wipeLocal?: boolean;
+}
+/** Options for {@link JsBaoClient.logout}. */
+export interface LogoutOptions {
+    /** URL to navigate to after logout completes (browser only). */
+    redirectTo?: string;
+    /** If true, deletes all locally cached document data and KV cache. */
+    wipeLocal?: boolean;
+    /** If true, revokes the stored offline access grant. */
+    revokeOffline?: boolean;
+    /** If false, preserves the in-memory offline identity after logout (default true). */
+    clearOfflineIdentity?: boolean;
+    /** If true, awaits WebSocket disconnection before resolving; set to false to avoid blocking UI (default false). */
+    waitForDisconnect?: boolean;
+}
+/** Options for {@link JsBaoClient.goOffline}. */
+export interface GoOfflineOptions {
+    /** Human-readable reason for going offline (stored in network status). */
+    reason?: string;
+}
+/** Options for {@link JsBaoClient.listLocalDocumentsUnified}. */
+export interface ListLocalDocumentsOptions {
+    /** If true, includes the user's root document in the results. */
+    includeRoot?: boolean;
+    /** If true, only returns documents that have local data stored. */
+    onlyWithLocalData?: boolean;
+}
+/** Options for {@link JsBaoClient.evictAllLocal}. */
+export interface EvictAllLocalOptions {
+    /** If true, only evicts documents that are fully synced with the server. */
+    onlySynced?: boolean;
+}
 export interface JsBaoEvents {
     error: {
         error: any;
@@ -574,6 +648,7 @@ export interface JsBaoEvents {
 }
 export interface AnalyticsClient {
     logEvent(event: AnalyticsEventInput): void;
+    logSnapshot(context?: Record<string, any>): void;
     flush(): void;
     setPlanOverride(plan: string | null | undefined): void;
     setAppVersionOverride(version: string | null | undefined): void;
@@ -624,6 +699,8 @@ export declare class JsBaoClient extends Observable<any> {
     private lastOnlineAt;
     private lastConnectionError;
     private lastEmittedPermission;
+    /** Analytics client for tracking events and metrics.
+     * @group Sub-APIs */
     readonly analytics: AnalyticsClient;
     private analyticsQueue;
     private analyticsCleanup?;
@@ -652,6 +729,8 @@ export declare class JsBaoClient extends Observable<any> {
     private buildLogged;
     private retentionPolicy;
     private kvCache;
+    /** Key-value cache facade backed by IndexedDB.
+     * @group Sub-APIs */
     cache: CacheFacade;
     private authPersistEnabled;
     private authStorageNamespace;
@@ -689,20 +768,51 @@ export declare class JsBaoClient extends Observable<any> {
     private serviceWorkerBridgeLastToken;
     private pendingSelfRemovalDocs;
     private pendingSelfRemovalTimers;
+    /** Sub-API for managing documents (list, create, get, delete, share).
+     * @group Sub-APIs */
     documents: DocumentsAPI;
+    /** Get a scoped API for a specific document
+     * @param documentId - The document to scope operations to
+     * @group Documents */
     document(documentId: string): DocumentContext;
+    /** Sub-API for the current authenticated user's profile and preferences.
+     * @group Sub-APIs */
     me: MeAPI;
+    /** Sub-API for session management (sign in, sign out, token refresh).
+     * @group Sub-APIs */
     session: SessionAPI;
+    /** Sub-API for LLM (large language model) operations.
+     * @group Sub-APIs */
     llm: LlmAPI;
+    /** Sub-API for Gemini model operations.
+     * @group Sub-APIs */
     gemini: GeminiAPI;
+    /** Sub-API for managing app users.
+     * @group Sub-APIs */
     users: UsersAPI;
+    /** Sub-API for managing databases.
+     * @group Sub-APIs */
     databases: DatabasesAPI;
+    /** Sub-API for managing groups and memberships.
+     * @group Sub-APIs */
     groups: GroupsAPI;
+    /** Sub-API for managing document collections.
+     * @group Sub-APIs */
     collections: CollectionsAPI;
+    /** Sub-API for managing rule sets.
+     * @group Sub-APIs */
     ruleSets: RuleSetsAPI;
+    /** Sub-API for managing group type configurations.
+     * @group Sub-APIs */
     groupTypeConfigs: GroupTypeConfigsAPI;
+    /** Sub-API for managing third-party integrations.
+     * @group Sub-APIs */
     integrations: IntegrationsAPI;
+    /** Sub-API for managing and executing workflows.
+     * @group Sub-APIs */
     workflows: WorkflowsAPI;
+    /** Sub-API for managing and executing prompts.
+     * @group Sub-APIs */
     prompts: PromptsAPI;
     private workflowApplyHandlers;
     private httpClient;
@@ -710,7 +820,13 @@ export declare class JsBaoClient extends Observable<any> {
     private controllerPreviousToken;
     private controllerTokenCause;
     private normalizeRefreshProxyOption;
+    /** Mark a document as pending self-removal to suppress duplicate server delete events.
+     * @param documentId - The document being removed by the current user
+     * @group Documents */
     markSelfRemovalPending(documentId: string): void;
+    /** Clear the self-removal pending flag for a document.
+     * @param documentId - The document to clear the pending self-removal flag for
+     * @group Documents */
     clearSelfRemovalPending(documentId: string): void;
     private normalizeProxyBase;
     private detectInitialOfflineState;
@@ -728,14 +844,34 @@ export declare class JsBaoClient extends Observable<any> {
     private get wsLastCloseInitiator();
     private set wsLastCloseInitiator(value);
     constructor(options: JsBaoClientOptions);
+    /** Subscribe to a client event.
+     * @param type - The event name to listen for
+     * @param f - Callback invoked when the event fires
+     * @group Events */
     on<K extends keyof JsBaoEvents>(type: K, f: (payload: JsBaoEvents[K]) => void): void;
+    /** Unsubscribe from a client event.
+     * @param type - The event name to stop listening for
+     * @param f - The callback to remove
+     * @group Events */
     off<K extends keyof JsBaoEvents>(type: K, f: (payload: JsBaoEvents[K]) => void): void;
+    /** Emit a client event.
+     * @param type - The event name to emit
+     * @param args - The event payload wrapped in an array
+     * @group Events */
     emit<K extends keyof JsBaoEvents>(type: K, args: [JsBaoEvents[K]]): void;
     private isWebSocketOpen;
     private _logWsState;
     private _closeWs;
     /**
      * Exchange an OAuth authorization code for an access token without constructing a client instance.
+     * @param params - OAuth exchange parameters
+     * @param params.apiUrl - The API server base URL
+     * @param params.appId - The application ID
+     * @param params.code - The authorization code received from the OAuth provider
+     * @param params.state - The state parameter for CSRF verification
+     * @param params.refreshProxyBaseUrl - Optional proxy URL for refresh token cookie handling
+     * @param params.refreshProxyCookieMaxAgeSeconds - Max age in seconds for the refresh proxy cookie
+     * @group Authentication
      */
     static exchangeOAuthCode(params: {
         apiUrl: string;
@@ -746,13 +882,34 @@ export declare class JsBaoClient extends Observable<any> {
         refreshProxyCookieMaxAgeSeconds?: number;
     }): Promise<string>;
     private _buildServerDocumentsContext;
+    /** Sync document metadata with the server.
+     * @param options - Controls the scope and behavior of the metadata sync
+     * @group Offline & Sync */
     syncMetadata(options?: SyncMetadataOptions): Promise<void>;
+    /** Sync metadata for a specific document.
+     * @param documentId - The document whose metadata to sync
+     * @param options - Optional sync behavior controls
+     * @param options.payload - Pre-fetched metadata payload to merge instead of fetching from server
+     * @param options.payloadType - Whether the payload contains full metadata objects or just IDs
+     * @param options.background - If true, silently swallows errors instead of throwing
+     * @param options.shouldRetain - Predicate controlling which documents are kept in the local cache
+     * @group Offline & Sync */
     syncMetadataForDocument(documentId: string, options?: {
         payload?: any;
         payloadType?: "full" | "ids";
         background?: boolean;
         shouldRetain?: (docId: string) => boolean;
     }): Promise<void>;
+    /** 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
+     * @param options.scope - Whether to replace all metadata or merge a single document
+     * @param options.payloadType - Whether items contain full metadata or just document IDs
+     * @param options.authoritative - If true, evicts local entries not present in the server list
+     * @param options.retainIds - Document IDs to keep locally even if missing from the server list
+     * @param options.targetDocumentId - Specific document ID to update when scope is "single"
+     * @param options.shouldRetain - Predicate controlling which documents are kept during eviction
+     * @group Offline & Sync */
     upsertServerDocuments(items: Array<{
         documentId: string;
         title?: string;
@@ -767,13 +924,32 @@ export declare class JsBaoClient extends Observable<any> {
         targetDocumentId?: string;
         shouldRetain?: (documentId: string) => boolean;
     }): void;
+    /** Get the API base URL.
+     * @group Configuration */
     getApiUrl(): string;
+    /** Get the app ID.
+     * @group Configuration */
     getAppId(): string;
+    /** Get the blob manager for direct blob operations.
+     * @group Blobs */
     getBlobManager(): BlobManager;
+    /** Set the maximum number of concurrent blob uploads.
+     * @param value - Maximum number of blob uploads that can run in parallel
+     * @group Blobs */
     setBlobUploadConcurrency(value: number): void;
+    /** Get the current blob upload concurrency limit.
+     * @group Blobs */
     getBlobUploadConcurrency(): number;
+    /** Mark a document's metadata as deleted locally.
+     * @param documentId - The document to mark as deleted
+     * @group Documents */
     markMetadataDeleted(documentId: string): number | undefined;
+    /** Check if a document's metadata has been marked as deleted.
+     * @param documentId - The document to check
+     * @group Documents */
     isMetadataDeleted(documentId: string): boolean;
+    /** Get the global admin app ID.
+     * @group Configuration */
     getGlobalAdminAppId(): string;
     private initializeJsBao;
     private _syncKvUserId;
@@ -791,8 +967,18 @@ export declare class JsBaoClient extends Observable<any> {
     private initializeStorageProvider;
     private _doInitializeStorageProvider;
     private runAuthBootstrap;
+    /**
+     * Wait for the initial authentication bootstrap to complete (token refresh, offline unlock, etc.).
+     * @group Authentication
+     */
     waitForAuthBootstrap(): Promise<void>;
     private initialize;
+    /** Make an authenticated HTTP request to the API server.
+     * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param path - API endpoint path relative to the app base URL
+     * @param data - Request body payload (sent as JSON)
+     * @param options - Additional request options (headers, timeout, etc.)
+     * @group Connection */
     makeRequest(method: string, path: string, data?: any, options?: RequestOptions): Promise<any>;
     private makeRawRequest;
     private callIntegration;
@@ -810,29 +996,67 @@ export declare class JsBaoClient extends Observable<any> {
     private defineWorkflow;
     private handleWorkflowApply;
     private executePrompt;
+    /** Check if the current user has read-only access to a document.
+     * @param documentId - The document to check
+     * @group Documents */
     isDocumentReadOnly(documentId: string): boolean;
+    /** Get the current user's permission level for a document.
+     * @param documentId - The document to check permissions for
+     * @group Documents */
     getDocumentPermission(documentId: string): DocumentAccessLevel | null;
+    /**
+     * Get the root document ID for the authenticated user.
+     * @group Authentication
+     */
     getRootDocId(): string | null;
+    /**
+     * Get the current authenticated user's ID.
+     * @group Authentication
+     */
     getUserId(): string | null;
+    /**
+     * Get the current authentication state including mode (online/offline/none) and user ID.
+     * @returns Object with `authenticated` flag, current auth `mode`, and optional `userId`
+     * @group Authentication
+     */
     getAuthState(): {
         authenticated: boolean;
         mode: "online" | "offline" | "none";
         userId?: string;
     };
+    /**
+     * Check if the client is currently authenticated.
+     * @group Authentication
+     */
     isAuthenticated(): boolean;
+    /**
+     * Get info about how auth tokens are persisted (memory vs storage).
+     * @returns Object with persistence `mode` ("memory" or "persisted") and whether the stored token has been `hydrated`
+     * @group Authentication
+     */
     getAuthPersistenceInfo(): {
         mode: "memory" | "persisted";
         hydrated: boolean;
     };
-    waitForUserId(options?: {
-        timeoutMs?: number;
-    }): Promise<string>;
-    waitForAuthReady(options?: {
-        timeoutMs?: number;
-    }): Promise<{
+    /**
+     * Wait until a user ID is available (authenticated).
+     * @param options - Optional configuration
+     * @group Authentication
+     */
+    waitForUserId(options?: WaitForUserIdOptions): Promise<string>;
+    /**
+     * Wait until the client is authenticated and return the auth mode and user ID.
+     * @param options - Optional configuration
+     * @returns The authenticated `userId` and auth `mode` ("online" or "offline")
+     * @group Authentication
+     */
+    waitForAuthReady(options?: WaitForAuthReadyOptions): Promise<{
         userId: string;
         mode: "online" | "offline";
     }>;
+    /** Check if a document is the user's root document.
+     * @param documentId - The document to check
+     * @group Documents */
     isRootDocument(documentId: string): boolean;
     private syncBlobManagerIdentity;
     private initServiceWorkerBridge;
@@ -868,23 +1092,46 @@ export declare class JsBaoClient extends Observable<any> {
     private logServiceWorkerControl;
     private logServiceWorkerTokenUpdate;
     private logSessionEndEvent;
+    /** Get the analytics context for LLM operations.
+     * @group Configuration */
     getLlmAnalyticsContext(): {
-        logEvent: (event: AnalyticsEventInput) => void;
+        logEvent: (event: Omit<AnalyticsEventInput, "user_ulid">) => void;
         isEnabled: (phase?: "start" | "success" | "failure") => boolean;
     } | null;
+    /** Get the analytics context for Gemini operations.
+     * @group Configuration */
     getGeminiAnalyticsContext(): {
-        logEvent: (event: AnalyticsEventInput) => void;
+        logEvent: (event: Omit<AnalyticsEventInput, "user_ulid">) => void;
         isEnabled: (phase?: "start" | "success" | "failure") => boolean;
     } | null;
     private sanitizeOverride;
     private readEnvNumber;
+    /** Check if a document is synced with the server.
+     * @param documentId - The document to check sync status for
+     * @group Offline & Sync */
     isSynced(documentId: string): boolean;
+    /** Set the local user's awareness state for a document (e.g., cursor position, selection).
+     * @param documentId - The document to set awareness for
+     * @param state - Arbitrary awareness data (cursor, selection, user info) to broadcast to collaborators
+     * @group Awareness */
     setAwareness(documentId: string, state: any): void;
     private getIndexedDbNames;
     private doesIndexedDbExist;
+    /** Check if a document has IndexedDB persistence.
+     * @param documentId - The document to check for local persistence
+     * @group Offline & Sync */
     hasIndexedDbPersistence(documentId: string): Promise<boolean>;
+    /** Update the local snapshot flag for a document.
+     * @param documentId - The document to update the snapshot flag for
+     * @param hasSnapshot - Whether the document has a local IndexedDB snapshot
+     * @group Offline & Sync */
     updateLocalSnapshotFlag(documentId: string, hasSnapshot: boolean): Promise<void>;
     private sendAwarenessState;
+    /** Remove awareness states for specific clients.
+     * @param documentId - The document to remove awareness from
+     * @param clientIds - Array of client IDs whose awareness states should be removed
+     * @param _reason - Optional reason for removal (used for logging)
+     * @group Awareness */
     removeAwareness(documentId: string, clientIds: string[], _reason?: string): void;
     private updateHandler;
     private enqueueLocalUpdate;
@@ -901,6 +1148,9 @@ export declare class JsBaoClient extends Observable<any> {
     private clearSyncWatchdog;
     private clearAllSyncWatchdogs;
     private handleSyncWatchdogTimeout;
+    /** Compute a hash of the document's current state.
+     * @param documentId - The document to hash
+     * @group Documents */
     getDocHash(documentId: string): Promise<string>;
     /**
      * Reset the y-indexeddb persistence for a document and re-sync from server.
@@ -936,20 +1186,49 @@ export declare class JsBaoClient extends Observable<any> {
     private handleOfflineAuthMessage;
     private handleUploadUrlResponse;
     private handleLlmMessage;
+    /** Connect to the WebSocket server.
+     * @group Connection */
     connect(): void;
+    /** Force a WebSocket reconnection.
+     * @group Connection */
     forceReconnect(): void;
+    /** Get the unique ID for this client connection.
+     * @group Connection */
     getConnectionId(): string;
+    /** Disconnect from the WebSocket server.
+     * @group Connection */
     disconnect(): Promise<void>;
+    /** Destroy the client, disconnecting and cleaning up all resources.
+     * @group Connection */
     destroy(): Promise<void>;
+    /** Set whether the client should maintain a WebSocket connection.
+     * @param shouldConnect - If true, the client will connect and auto-reconnect; if false, it disconnects and stays disconnected
+     * @group Connection */
     setShouldConnect(shouldConnect: boolean): Promise<void>;
     private _updateStatus;
     private safeGetNetworkStatus;
     private _emitPermission;
+    /** Update a document's locally stored metadata (title, tags).
+     * @param documentId - The document to update metadata for
+     * @param updates - Fields to update in the local metadata cache
+     * @param updates.title - New document title
+     * @param updates.tags - New document tags
+     * @group Documents */
     updateLocalMetadata(documentId: string, updates: {
         title?: string;
         tags?: string[];
     }): Promise<void>;
     private _updateSynced;
+    /** Open a document for real-time collaboration and sync.
+     * @param documentId - The document to open
+     * @param options - Controls how the document is loaded and synced
+     * @param options.waitForLoad - Controls when the returned promise resolves: "local" for local data only, "network" to wait for server sync, "localIfAvailableElseNetwork" to prefer local but fall back to network
+     * @param options.enableNetworkSync - If false, opens the document without subscribing to server updates (default true)
+     * @param options.retainLocal - If true, persists the document data locally for offline access (default true)
+     * @param options.availabilityWaitMs - How long to wait for initial data before resolving with an empty doc (ms, default 30000)
+     * @param options.deferNetworkSync - If true, opens locally without starting server sync until startNetworkSync() is called
+     * @param options.requestSyncPerf - If true, requests sync performance timings from the server
+     * @group Documents */
     openDocument(documentId: string, options?: {
         waitForLoad?: "local" | "network" | "localIfAvailableElseNetwork";
         enableNetworkSync?: boolean;
@@ -958,6 +1237,14 @@ export declare class JsBaoClient extends Observable<any> {
         deferNetworkSync?: boolean;
         requestSyncPerf?: boolean;
     }): Promise<Y.Doc>;
+    /** Resolve a document alias and open the document.
+     * @param alias - Alias parameters identifying the document (scope, aliasKey, optional userId)
+     * @param options - Controls how the resolved document is loaded and synced
+     * @param options.waitForLoad - Controls when the returned promise resolves: "local", "network", or "localIfAvailableElseNetwork"
+     * @param options.enableNetworkSync - If false, opens the document without subscribing to server updates
+     * @param options.retainLocal - If true, persists the document data locally for offline access
+     * @param options.availabilityWaitMs - How long to wait for initial data before resolving with an empty doc (ms)
+     * @group Documents */
     openDocumentByAlias(alias: ResolveAliasParams, options?: {
         waitForLoad?: "local" | "network" | "localIfAvailableElseNetwork";
         enableNetworkSync?: boolean;
@@ -967,15 +1254,41 @@ export declare class JsBaoClient extends Observable<any> {
         doc: Y.Doc;
         metadata: LocalMetadataEntry | null;
     }>;
+    /** Close an open document and stop syncing.
+     * @param documentId - The document to close
+     * @param options - Optional close behavior
+     * @param options.evictLocal - If true, removes the document's local data from storage on close
+     * @group Documents */
     closeDocument(documentId: string, options?: {
         evictLocal?: boolean;
     }): Promise<void>;
+    /** Map a js-bao model name to a specific document ID.
+     * @param modelName - The model class name to map
+     * @param documentId - The document that should store instances of this model
+     * @group Documents */
     addDocumentModelMapping(modelName: string, documentId: string): void;
+    /** Remove a model-to-document mapping.
+     * @param modelName - The model class name to unmap
+     * @group Documents */
     clearDocumentModelMapping(modelName: string): void;
+    /** Get the document ID mapped to a model name.
+     * @param modelName - The model class name to look up
+     * @group Documents */
     getDocumentModelMapping(modelName: string): string | null;
+    /** Set the default document ID used by js-bao models when no explicit mapping exists.
+     * @param documentId - The document to use as the default for all unmapped models
+     * @group Documents */
     setDefaultDocumentId(documentId: string): void;
+    /** Clear the default document ID.
+     * @group Documents */
     clearDefaultDocumentId(): void;
+    /** Get the current default document ID.
+     * @group Documents */
     getDefaultDocumentId(): string | null;
+    /** Get offline status information for a document.
+     * @param documentId - The document to get offline info for
+     * @returns Object with `offlineEnabled`, `hasPersistence`, `isIdbSyncing` flags, optional `updatesStoreSize`, and `hasUnsyncedLocalChanges`
+     * @group Offline & Sync */
     getOfflineInfo(documentId: string): {
         offlineEnabled: boolean;
         hasPersistence: boolean;
@@ -983,33 +1296,50 @@ export declare class JsBaoClient extends Observable<any> {
         updatesStoreSize?: number;
         hasUnsyncedLocalChanges?: boolean;
     };
+    /** Check if a document has local data available.
+     * @param documentId - The document to check for local data
+     * @group Offline & Sync */
     hasLocalCopy(documentId: string): boolean;
+    /** Set the client's log verbosity level.
+     * @param level - The minimum log level to output (e.g. "debug", "warn", "error")
+     * @group Configuration */
     setLogLevel(level: LogLevel): void;
-    enableOfflineAccess(options?: {
-        preferBiometric?: boolean;
-        allowPinFallback?: boolean;
-        ttlDays?: number;
-        retention?: {
-            preserveOnSignOut?: boolean;
-        };
-        pinProvider?: () => Promise<string>;
-    }): Promise<{
+    /** Enable offline access using passkey or PIN authentication.
+     * @param options - Controls how offline credentials are created and stored
+     * @returns Object with `enabled` flag, the `method` used (largeBlob, pin, or signed), and an optional `reason` if not enabled
+     * @group Offline & Sync */
+    enableOfflineAccess(options?: EnableOfflineAccessOptions): Promise<{
         enabled: boolean;
         method?: "largeBlob" | "pin" | "signed";
         reason?: string;
     }>;
+    /** Unlock offline access using stored credentials.
+     * @param pinProvider - Async function that prompts the user for a PIN; required when the offline grant uses PIN-based storage
+     * @group Offline & Sync */
     unlockOffline(pinProvider?: () => Promise<string>): Promise<boolean>;
+    /** Check if an offline access grant is currently active.
+     * @group Offline & Sync */
     isOfflineGrantAvailable(): boolean;
+    /** Get detailed status of the offline access grant.
+     * @returns Object with `available` flag, optional `expiresAt` timestamp, `daysLeft` until expiry, and storage `method`
+     * @group Offline & Sync */
     getOfflineGrantStatus(): {
         available: boolean;
         expiresAt?: string;
         daysLeft?: number;
         method?: "largeBlob" | "pin" | "signed";
     };
+    /** Renew the offline access grant while online.
+     * @param pinProvider - Async function that prompts for a PIN; required for PIN-based grants
+     * @group Offline & Sync */
     renewOfflineGrantOnline(pinProvider?: () => Promise<string>): Promise<boolean>;
-    revokeOfflineGrant(opts?: {
-        wipeLocal?: boolean;
-    }): Promise<void>;
+    /** Revoke the offline access grant.
+     * @param opts - Optional revocation behavior
+     * @group Offline & Sync */
+    revokeOfflineGrant(opts?: RevokeOfflineGrantOptions): Promise<void>;
+    /** Get the offline identity (user info available when offline).
+     * @returns The offline user identity with `userId`, `appId`, `rootDocId`, and optional `email`/`name`, or null if unavailable
+     * @group Offline & Sync */
     getOfflineIdentity(): {
         userId: string;
         appId: string;
@@ -1019,27 +1349,74 @@ export declare class JsBaoClient extends Observable<any> {
     } | null;
     private buildCommitRetryContext;
     private ensureAuthReadyForRequest;
+    /** Check if an offline grant is stored locally.
+     * @group Offline & Sync */
     hasOfflineGrantStored(): Promise<boolean>;
     private unsubscribeFromDocument;
+    /** Get the raw Yjs Doc instance for a document.
+     * @param documentId - The document to retrieve
+     * @group Documents */
     getDoc(documentId: string): Y.Doc | undefined;
+    /** Run a function as a local Yjs transaction (batches updates).
+     * @param documentId - The document to transact against
+     * @param fn - Function to execute within the transaction; all Yjs mutations inside are batched into a single update
+     * @group Documents */
     runLocalTransaction(documentId: string, fn: () => void): void;
+    /** Check if a document is currently open.
+     * @param documentId - The document to check
+     * @group Documents */
     isDocOpen(documentId: string): boolean;
+    /** Check if the WebSocket is currently connected.
+     * @group Connection */
     isConnected(): boolean;
+    /** Check if a document's data is synced with the server.
+     * @param documentId - The document to check sync status for
+     * @group Offline & Sync */
     isDocumentSynced(documentId: string): boolean;
+    /** Wait until a document is synced with the server.
+     * @param documentId - The document to wait for
+     * @param timeoutMs - Maximum time to wait before rejecting (ms, default 30000)
+     * @group Offline & Sync */
     waitForSync(documentId: string, timeoutMs?: number): Promise<void>;
     private requestUploadUrl;
     private handleAwarenessRefresh;
     private handleAwarenessMessage;
     private _emitAwarenessChange;
     private _broadcastAwareness;
+    /** Set the local awareness state for a document.
+     * @param documentId - The document to set awareness for
+     * @param state - Arbitrary awareness data (cursor, selection, user info) to broadcast to collaborators
+     * @group Awareness */
     setLocalAwarenessState(documentId: string, state: any): void;
+    /** Get the local user's current awareness state for a document.
+     * @param documentId - The document to get local awareness for
+     * @group Awareness */
     getLocalAwarenessState(documentId: string): any | null;
+    /** Get all users' awareness states for a document.
+     * @param documentId - The document to get awareness states for
+     * @group Awareness */
     getAwarenessStates(documentId: string): Map<string, any>;
+    /** Remove awareness states for specific clients and broadcast the removal to the server.
+     * @param documentId - The document to remove awareness from
+     * @param clientIds - Array of client IDs whose awareness states should be removed
+     * @param _reason - Optional reason for removal (used for logging)
+     * @group Awareness */
     removeAwarenessStates(documentId: string, clientIds: string[], _reason?: string): void;
     private applyTokenFromController;
     private applyTokenEffects;
     private pushAuthTokenToSocket;
+    /**
+     * Get the current JWT auth token.
+     * @group Authentication
+     */
     getToken(): string | null;
+    /**
+     * Manually set the JWT auth token.
+     * @param token - The JWT token to use for authentication, or null to clear
+     * @param options - Optional metadata
+     * @param options.cause - Reason for the token change (used in event payloads and logging)
+     * @group Authentication
+     */
     setToken(token: string | null, options?: {
         cause?: string;
     }): void;
@@ -1047,25 +1424,39 @@ export declare class JsBaoClient extends Observable<any> {
      * Logout: best-effort server cookie clear, shutdown networking, clear auth state, and optional local eviction.
      * - Preserves stored offline grant by default (does not delete it)
      * - Clears in-memory offline identity so the client is not considered authenticated
+     * @param options - Controls logout behavior
+     * @group Authentication
+     */
+    logout(options?: LogoutOptions): Promise<void>;
+    /**
+     * Check if OAuth authentication is available for this app.
+     * @group Authentication
      */
-    logout(options?: {
-        redirectTo?: string;
-        wipeLocal?: boolean;
-        revokeOffline?: boolean;
-        clearOfflineIdentity?: boolean;
-        waitForDisconnect?: boolean;
-    }): Promise<void>;
     checkOAuthAvailable(): Promise<boolean>;
+    /**
+     * Start the OAuth authentication flow by redirecting to the OAuth provider.
+     * @param continueUrl - URL to return to after the OAuth flow completes
+     * @param options - Additional flow options
+     * @param options.waitlist - If provided, enrolls the user in the app's waitlist with optional source and note
+     * @group Authentication
+     */
     startOAuthFlow(continueUrl?: string, options?: {
         waitlist?: {
             source?: string | null;
             note?: string | null;
         };
     }): Promise<void>;
+    /**
+     * Handle the OAuth callback after the user completes the OAuth flow.
+     * @param code - The authorization code from the OAuth provider
+     * @param state - The state parameter for CSRF verification
+     * @group Authentication
+     */
     handleOAuthCallback(code: string, state: string): Promise<void>;
     /**
      * Get the app's authentication configuration.
      * Useful for checking what auth methods are available before showing login UI.
+     * @group Authentication
      */
     getAppConfig(): Promise<{
         appId: string;
@@ -1076,11 +1467,23 @@ export declare class JsBaoClient extends Observable<any> {
         hasPasskey: boolean;
         magicLinkEnabled: boolean;
     }>;
+    /**
+     * Request a magic link email for passwordless authentication.
+     * @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
+     * @group Authentication
+     */
     magicLinkRequest(email: string, options?: {
         redirectUri?: string;
     }): Promise<{
         success: boolean;
     }>;
+    /**
+     * Verify a magic link token and authenticate the user.
+     * @param token - The magic link token from the email URL
+     * @group Authentication
+     */
     magicLinkVerify(token: string): Promise<{
         user: {
             userId: string;
@@ -1093,6 +1496,8 @@ 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()`.
+     * @param email - The email address to send the OTP code to
+     * @group Authentication
      */
     otpRequest(email: string): Promise<{
         success: boolean;
@@ -1100,6 +1505,9 @@ export declare class JsBaoClient extends Observable<any> {
     /**
      * Verify a one-time password (OTP) code and authenticate the user.
      * On success, the client will be authenticated and connected.
+     * @param email - The email address the OTP was sent to
+     * @param code - The OTP code entered by the user
+     * @group Authentication
      */
     otpVerify(email: string, code: string): Promise<{
         user: {
@@ -1109,10 +1517,20 @@ export declare class JsBaoClient extends Observable<any> {
         };
         isNewUser?: boolean;
     }>;
+    /**
+     * Start the passkey authentication flow, returns challenge options for the browser.
+     * @group Authentication
+     */
     passkeyAuthStart(): Promise<{
         options: any;
         challengeToken: string;
     }>;
+    /**
+     * Complete passkey authentication with the browser's credential response.
+     * @param credential - The credential response from the browser's WebAuthn API
+     * @param challengeToken - The challenge token returned by passkeyAuthStart()
+     * @group Authentication
+     */
     passkeyAuthFinish(credential: any, challengeToken: string): Promise<{
         user: {
             userId: string;
@@ -1121,13 +1539,28 @@ export declare class JsBaoClient extends Observable<any> {
         };
         isNewUser?: boolean;
     }>;
+    /**
+     * Start registering a new passkey for the current user.
+     * @group Authentication
+     */
     passkeyRegisterStart(): Promise<{
         options: any;
         challengeToken: string;
     }>;
+    /**
+     * Complete passkey registration with the browser's credential response.
+     * @param credential - The credential response from the browser's WebAuthn API
+     * @param challengeToken - The challenge token returned by passkeyRegisterStart()
+     * @param deviceName - Optional human-readable name for this passkey (e.g. "MacBook Pro")
+     * @group Authentication
+     */
     passkeyRegisterFinish(credential: any, challengeToken: string, deviceName?: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * List all passkeys registered for the current user.
+     * @group Authentication
+     */
     passkeyList(): Promise<{
         passkeys: Array<{
             passkeyId: string;
@@ -1136,9 +1569,21 @@ export declare class JsBaoClient extends Observable<any> {
             lastUsedAt?: string;
         }>;
     }>;
+    /**
+     * Delete a registered passkey by ID.
+     * @param passkeyId - The ID of the passkey to delete
+     * @group Authentication
+     */
     passkeyDelete(passkeyId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Update a passkey's metadata such as its device name.
+     * @param passkeyId - The ID of the passkey to update
+     * @param params - Fields to update
+     * @param params.deviceName - New human-readable name for the passkey
+     * @group Authentication
+     */
     passkeyUpdate(passkeyId: string, params: {
         deviceName: string;
     }): Promise<{
@@ -1149,6 +1594,10 @@ export declare class JsBaoClient extends Observable<any> {
             lastUsedAt?: string;
         };
     }>;
+    /**
+     * Get detailed authentication configuration including enabled providers and passkey settings.
+     * @group Authentication
+     */
     getAuthConfig(): Promise<{
         appId: string;
         name: string;
@@ -1172,6 +1621,9 @@ export declare class JsBaoClient extends Observable<any> {
     private _putMetadataToIdb;
     private _deleteMetadataFromIdb;
     private _enforceRetentionPolicy;
+    /** Get the current network status including connectivity and transport state.
+     * @returns Object with network `mode`, WebSocket `transport` state, `isOnline` flag, and optional `lastOnlineAt`/`lastError`
+     * @group Network */
     getNetworkStatus(): {
         mode: "auto" | "online" | "offline";
         transport: "connected" | "connecting" | "disconnected";
@@ -1180,27 +1632,60 @@ export declare class JsBaoClient extends Observable<any> {
         lastOnlineAt?: string;
         lastError?: string;
     };
+    /** Check if the client is currently online.
+     * @group Network */
     isOnline(): boolean;
+    /** Set the network mode (auto, online, or offline).
+     * @param mode - "auto" to connect/disconnect based on connectivity, "online" to force connection, "offline" to force disconnection
+     * @group Network */
     setNetworkMode(mode: "auto" | "online" | "offline"): Promise<void>;
-    goOffline(opts?: {
-        reason?: string;
-    }): Promise<void>;
+    /** Switch the client to offline mode.
+     * @param opts - Optional configuration
+     * @group Network */
+    goOffline(opts?: GoOfflineOptions): Promise<void>;
+    /** Switch the client back to online mode.
+     * @group Network */
     goOnline(): Promise<void>;
+    /** Start network syncing for a document that was opened with deferred sync.
+     * @param documentId - The document to begin syncing with the server
+     * @group Offline & Sync */
     startNetworkSync(documentId: string): Promise<void>;
+    /** List IDs of all currently open documents.
+     * @group Documents */
     listOpenDocuments(): string[];
+    /** List all documents stored locally.
+     * @group Offline & Sync */
     listLocalDocuments(): Promise<LocalDocumentEntry[]>;
-    listLocalDocumentsUnified(options?: {
-        includeRoot?: boolean;
-        onlyWithLocalData?: boolean;
-    }): Promise<DocumentInfo[]>;
+    /** List documents with merged local and server metadata.
+     * @param options - Optional filters
+     * @group Offline & Sync */
+    listLocalDocumentsUnified(options?: ListLocalDocumentsOptions): Promise<DocumentInfo[]>;
+    /** Get locally stored metadata for a document.
+     * @param documentId - The document to get metadata for
+     * @group Offline & Sync */
     getLocalMetadata(documentId: string): Promise<LocalMetadataEntry | null>;
+    /** Remove a document's local data from storage.
+     * @param documentId - The document to evict
+     * @param opts - Optional eviction behavior
+     * @param opts.force - If true, evicts even if the document has unsynced local changes
+     * @param opts.suppressMetadataEvent - If true, does not emit a documentMetadataChanged event
+     * @group Offline & Sync */
     evictLocalDocument(documentId: string, opts?: {
         force?: boolean;
         suppressMetadataEvent?: boolean;
     }): Promise<void>;
-    evictAllLocal(opts?: {
-        onlySynced?: boolean;
-    }): Promise<void>;
+    /** Remove all locally stored document data.
+     * @param opts - Optional eviction behavior
+     * @group Offline & Sync */
+    evictAllLocal(opts?: EvictAllLocalOptions): Promise<void>;
+    /** Configure the local document retention policy.
+     * @param opts - Retention policy settings
+     * @param opts.default - Default retention mode: "persist" keeps documents across sessions, "session" evicts on sign-out
+     * @param opts.maxDocs - Maximum number of documents to keep locally; oldest are evicted first
+     * @param opts.maxBytes - Maximum total bytes of local document data; oldest documents evicted when exceeded
+     * @param opts.ttlMs - Time-to-live in milliseconds; documents older than this are evicted
+     * @param opts.preserveOnSignOut - If true, retains local data even when the user signs out
+     * @group Offline & Sync */
     setRetentionPolicy(opts: {
         default: "persist" | "session";
         maxDocs?: number;
@@ -1208,16 +1693,23 @@ export declare class JsBaoClient extends Observable<any> {
         ttlMs?: number;
         preserveOnSignOut?: boolean;
     }): void;
-    createDocument(options: {
-        title?: string;
-        localOnly?: boolean;
-        tags?: string[];
-    }): Promise<{
+    /** Create a new document, optionally local-only for offline-first creation.
+     * @param options - Document creation options
+     * @group Documents */
+    createDocument(options: CreateDocumentOptions): Promise<{
         metadata: any;
     }>;
+    /** Retry committing a pending offline-created document to the server.
+     * @param documentId - The pending document to retry committing
+     * @group Documents */
     retryCommit(documentId: string): Promise<{
         created: boolean;
     } | null>;
+    /** Commit a locally created document to the server.
+     * @param documentId - The locally created document to commit
+     * @param opts - Optional commit behavior
+     * @param opts.onExists - What to do if the document already exists on the server: "link" adopts the existing document, "fail" throws an error
+     * @group Documents */
     commitOfflineCreate(documentId: string, opts?: {
         onExists?: "link" | "fail";
     }): Promise<{
@@ -1225,15 +1717,28 @@ export declare class JsBaoClient extends Observable<any> {
         linked?: boolean;
         reason?: string;
     }>;
+    /** List all documents pending server creation.
+     * @group Documents */
     listPendingCreates(): Promise<Array<{
         documentId: string;
         title?: string;
         createdAt: string;
     }>>;
+    /** Check if a document is pending server creation.
+     * @param documentId - The document to check
+     * @group Documents */
     isPendingCreate(documentId: string): boolean;
+    /** Cancel a pending offline document creation.
+     * @param documentId - The pending document to cancel
+     * @param opts - Optional cleanup behavior
+     * @param opts.evictLocal - If true, also removes the document's local data from storage
+     * @group Documents */
     cancelPendingCreate(documentId: string, opts?: {
         evictLocal?: boolean;
     }): Promise<void>;
+    /** Get debug information about a document's internal state.
+     * @param documentId - The document to inspect
+     * @group Documents */
     getDocDebug(documentId: string): DocumentDebugSnapshot;
 }
 export declare function initializeClient(options: JsBaoClientOptions, waitOptions?: {