js-bao-wss-client 3.5.0-alpha.1 → 3.5.0-alpha.2

package/README.md

@@ -1028,9 +1028,6 @@ await client.emailSignInRequest("user@example.com", {
 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

package/dist/JsBaoClient.d.ts

@@ -62,7 +62,7 @@ export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI, DocumentIngests
 export type { DatabasesAPI } from "./api/databasesApi";
 export type { CollectionsAPI } from "./api/collectionsApi";
 export type { AgentsAPI, AgentSessionsAPI } from "./api/agentSessionsApi";
-export type { AgentSessionMemberRole, AgentSessionMembers, AgentSessionInfo, AgentSessionListItem, ListAgentSessionsOptions, AgentSessionRenameResult, AgentSessionDeleteResult, AgentSessionMembersResult, } from "./api/agentSessionsApi";
+export type { AgentSessionMemberRole, AgentSessionMembers, AgentSessionInfo, AgentSessionListItem, ListAgentSessionsOptions, AgentSessionRenameResult, AgentSessionDeleteResult, AgentSessionMembersResult, AgentSessionStatus, AgentTurnPause, AgentSessionTurnSummary, AgentSessionInspectedTurn, AgentSessionInspectedCall, AgentSessionObjectState, AgentSessionSendBody, AgentSessionSendResult, AgentCallAnswer, AgentCallAnswerResult, AgentSessionCancelResult, AgentSessionEvent, AgentSessionEventResult, } from "./api/agentSessionsApi";
 export type { MeAPI } from "./api/meApi";
 export type { SessionAPI } from "./api/sessionApi";
 export type { UsersAPI } from "./api/usersApi";
@@ -94,7 +94,7 @@ export type { DocumentDebugSnapshot, DocumentPermission, LocalDocumentEntry, Loc
 export type { LogLevel } from "./internal/logger";
 export type { RequestOptions } from "./internal/httpClient";
 export type { LocksAPI } from "./api/locksApi";
-export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionRun, FunctionRunError, FunctionRunErrorCode, FunctionRunSettled, FunctionRunSlice, FunctionRunStatus, FunctionRunStatusValue, FunctionRunTerminalStatus, FunctionWaitOptions, } from "./api/functionsApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, FunctionRun, FunctionRunError, FunctionRunErrorCode, FunctionRunSettled, FunctionRunSlice, FunctionRunStatus, FunctionRunStatusValue, FunctionRunTerminalStatus, FunctionWaitOptions, FunctionRunListOptions, FunctionRunPage, FunctionStepRun, FunctionRunSteps, } from "./api/functionsApi";
 export type { LockHandle, LockContention, AcquireResponse, AcquireOptions, BlockingAcquireOptions, ReleaseResult, RenewResult, LockStatus, LockListEntry, LockListResult, } from "./api/locksApi";
 export type { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 export type { ResourceMetadataReadResult, ResourceMetadataWriteResult, ResourceMetadataBatchRequestItem, ResourceMetadataBatchParams, ResourceMetadataBatchCategoryResult, ResourceMetadataBatchResourceResult, ResourceMetadataBatchResult, ResourceMetadataListEntry, ResourceMetadataListResult, ResourceMetadataDeleteResult, ResourceMetadataResolveParams, ResourceMetadataResolveResult, } from "./api/resourceMetadataApi";
@@ -407,12 +407,26 @@ export interface ExecutePromptResult<R = unknown> {
      */
     upstreamStatus?: number;
     /**
-     * `"PROMPT_UPSTREAM_TIMEOUT"` when the provider itself ran out of time,
-     * which is the one failure of the model call that carries a code. Absent on
-     * success and on every other provider failure, so `error` with no
+     * `"PROMPT_UPSTREAM_TIMEOUT"` when the provider itself ran out of time;
+     * `"PROMPT_UPSTREAM_REJECTED"` when the provider refused the request as
+     * invalid (`upstreamStatus` 400) — a setting the model does not support,
+     * such as a reasoning level, with the provider's message in `error`; fix
+     * the configuration rather than retrying;
+     * `"PROMPT_STRICT_OUTPUT_SCHEMA_MISSING"` when a strict-output config's
+     * prompt has no usable `outputSchema`, refused before the provider call; and
+     * `"PROMPT_OUTPUT_TRUNCATED"` when the completion came back empty because
+     * it spent the whole output token limit (`truncated` is `true` beside it).
+     * Absent on success and on every other provider failure, so `error` with no
      * `errorCode` still means "the call failed for some other reason".
      */
-    errorCode?: "PROMPT_UPSTREAM_TIMEOUT";
+    errorCode?: "PROMPT_UPSTREAM_TIMEOUT" | "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING" | "PROMPT_OUTPUT_TRUNCATED" | "PROMPT_UPSTREAM_REJECTED";
+    /**
+     * `true` when the provider stopped at the output token limit (the config's
+     * `maxTokens`) before the answer was finished; absent otherwise. A cut-off
+     * answer is still `success: true`, with the partial text in `output`. On
+     * Gemini, reasoning tokens count against the same limit. Raise `maxTokens`.
+     */
+    truncated?: true;
     metrics: {
         durationMs: number;
         inputTokens?: number;
@@ -1727,6 +1741,24 @@ export interface ListLocalDocumentsOptions {
     /** If true, only returns documents that have local data stored. */
     onlyWithLocalData?: boolean;
 }
+/** What {@link JsBaoClient.getLargeDocumentStorage} reports. */
+export interface LargeDocumentStorageInfo {
+    /** Whether there is durable local storage to keep a large document in. */
+    persistent: boolean;
+    /** Bytes this origin may keep, or `null` when the platform will not say. */
+    quotaBytes: number | null;
+    /** Bytes the origin already holds, other documents included. */
+    usedBytes?: number;
+    /**
+     * Whether the browser keeps that storage when it is short of space, as it
+     * answered the client's request: `persisted` (already was), `granted`,
+     * `declined` or `unsupported` (no API to ask). Absent until the `opfs`
+     * engine has opened a large document, which is when it asks. On `declined`
+     * and `unsupported` the local copy, unsynced writes included, is
+     * best-effort.
+     */
+    persistence?: "persisted" | "granted" | "declined" | "unsupported";
+}
 /** Options for {@link JsBaoClient.evictAllLocal}. */
 export interface EvictAllLocalOptions {
     /** If true, only evicts documents that are fully synced with the server. */
@@ -2696,6 +2728,13 @@ export declare class JsBaoClient extends Observable<any> {
      * next user's.
      */
     private scopeReconcileGeneration;
+    /**
+     * Bumped whenever the signed-in user changes, logout included. A metadata
+     * answer fetched under one generation is about that user's documents: once
+     * the generation has moved on, it is dropped rather than merged into the
+     * cache the next user reads (#4150).
+     */
+    private metadataSessionGeneration;
     /**
      * Reconcile the local metadata cache against the user's whole document
      * scope, evicting the documents the server no longer has (#2852).
@@ -3176,6 +3215,19 @@ export declare class JsBaoClient extends Observable<any> {
      * exactly as {@link format2ServerStateVectors} is.
      */
     private readonly format2HandshakeStateVectors;
+    /**
+     * Documents whose epoch move still owes the sync of its fresh overlay
+     * (#4194, finding 4194-R3).
+     *
+     * A move carries the unacknowledged writes into the fresh overlay before its
+     * update listener is attached, so the sync that follows is the only thing
+     * that sends them. When a handshake is still in flight, `sendSyncStep1`
+     * returns without starting one, and that handshake's `syncComplete` would
+     * close the document's cycle with the carried writes never sent. The debt is
+     * recorded here, settled by the next cycle that actually starts, and claimed
+     * by the in-flight handshake's `syncComplete` when none has.
+     */
+    private readonly format2OwedMoveSyncs;
     /**
      * Documents whose adopted sequences are owed a claim that had no baseline
      * to build one against (finding 3431-R16).
@@ -4284,6 +4336,25 @@ export declare class JsBaoClient extends Observable<any> {
      * @group Documents
      */
     registerModel(model: TypedModelConstructor<any> | any): Promise<void>;
+    /**
+     * What this device can hold a large document in, and whether the browser
+     * keeps it.
+     *
+     * The capability is the one a large document's load decides on —
+     * `largeDocumentStorage.capability` when configured, what the platform
+     * reports otherwise. With the `opfs` engine, the client asks the browser for
+     * persistent storage when it first opens a large document, and
+     * `persistence` carries the answer.
+     *
+     * ```ts
+     * const { persistence } = await client.getLargeDocumentStorage();
+     * if (persistence === "declined") showSyncReminder();
+     * ```
+     *
+     * @throws If the client is destroyed or its js-bao runtime failed to start
+     * @group Offline & Sync
+     */
+    getLargeDocumentStorage(): Promise<LargeDocumentStorageInfo>;
     /** 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 */
@@ -4629,8 +4700,6 @@ export declare class JsBaoClient extends Observable<any> {
          * 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
@@ -4653,22 +4722,6 @@ export declare class JsBaoClient extends Observable<any> {
     }): 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
-     * @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
@@ -4689,18 +4742,6 @@ export declare class JsBaoClient extends Observable<any> {
         promptAddPasskey?: boolean;
         isNewUser?: boolean;
     }>;
-    /**
-     * 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
-     */
-    otpRequest(email: string): Promise<{
-        success: boolean;
-    }>;
     /**
      * Verify a one-time password (OTP) code and authenticate the user.
      * On success, the client will be authenticated and connected.
@@ -4849,10 +4890,6 @@ export declare class JsBaoClient extends Observable<any> {
          * 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;
     }>;
@@ -4935,14 +4972,20 @@ export declare class JsBaoClient extends Observable<any> {
      * epoch lock. An ordinary document on a hydrated session still pays nothing.
      */
     private _persistedNamingReader;
-    private _putMetadataToIdb;
     /**
      * Persist a DELTA of one document's metadata row (#3746) — the fields named
-     * and nothing else, merged into whatever is stored. What the document-open
-     * path writes with, so opening one document in one tab cannot regress a field
-     * another tab's rotation or a listing wrote.
+     * and nothing else, merged into whatever is stored, a field named
+     * `undefined` removed. Every metadata write the client makes goes through
+     * here since #3779, so no write from one tab can regress a field another
+     * tab's rotation or a listing wrote.
+     *
+     * A failure is NOT caught here: it rejects through to
+     * `DocumentManager.safeMetadataMerge`, the one place that counts and
+     * escalates metadata write failures.
      */
     private _mergeMetadataToIdb;
+    /** The merge hook alone, for the client's own direct metadata writes. */
+    private metadataMergeContext;
     private _deleteMetadataFromIdb;
     private _enforceRetentionPolicy;
     /** Get the current network status including connectivity and transport state.