js-bao-wss-client 3.5.0-alpha.0 → 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

@@ -33,6 +33,7 @@ import { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 import { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 import { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 import { CollectionsAPI } from "./api/collectionsApi";
+import { AgentsAPI } from "./api/agentSessionsApi";
 import { InvitationsAPI } from "./api/invitationsApi";
 import { NotificationsAPI } from "./api/notificationsApi";
 export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
@@ -43,7 +44,7 @@ export type { DocumentInfo, DocumentPermissionEntry, DocumentAccessResult, Docum
 export type { UserProfile, SharedDocument, SharedDocumentListResult, SharedDocumentsOptions, OwnedDocumentsOptions, } from "./api/meApi";
 export type { SessionInfo } from "./api/sessionApi";
 export type { BasicUserInfo, BatchUserProfile } from "./api/usersApi";
-export type { DatabaseInfo, DatabasePermissionEntry, DatabaseGroupPermissionEntry, GrantDatabaseGroupPermissionParams, DatabaseOwnershipTransferResult, DatabaseOperationInfo, AddManagerParams, CsvImportOptions, CsvImportProgress, CsvImportResult, CelContextResult, ExecuteOperationOptions, DatabaseChangeEvent, DatabaseChangePayload, DatabaseSubscribeOptions, ListDatabasesOptions, DatabaseListPage, OperationType, OperationFilter, QueryDefinition, MutationOperation, MutationDefinition, CountDefinition, AggregateOperation, AggregateDefinition, PipelineStep, PipelineDefinition, ApplyToQuerySource, ApplyToQueryAction, ApplyToQueryDefinition, OperationDefinition, CreateOperationParams, UpdateOperationParams, } from "./api/databasesApi";
+export type { DatabaseInfo, DatabasePermissionEntry, DatabaseGroupPermissionEntry, GrantDatabaseGroupPermissionParams, DatabaseOwnershipTransferResult, DatabaseOperationInfo, AddManagerParams, CsvImportOptions, CsvImportProgress, CsvImportResult, ExecuteOperationOptions, DatabaseChangeEvent, DatabaseChangePayload, DatabaseSubscribeOptions, ListDatabasesOptions, DatabaseListPage, OperationType, OperationFilter, QueryDefinition, MutationOperation, MutationDefinition, CountDefinition, AggregateOperation, AggregateDefinition, PipelineStep, PipelineDefinition, ApplyToQuerySource, ApplyToQueryAction, ApplyToQueryDefinition, OperationDefinition, CreateOperationParams, UpdateOperationParams, } from "./api/databasesApi";
 export type { GroupInfo, GroupMemberInfo, GroupMembershipInfo, GroupDocumentInfo, GroupDatabaseInfo, ListUserMembershipsOptions, DirectGroupAdd, DeferredGroupAdd, GroupAddMemberResult, } from "./api/groupsApi";
 export type { CollectionInfo, CollectionDocumentInfo, CollectionGroupPermissionInfo, CollectionMemberInfo, CollectionAccessInfo, DocumentCollectionInfo, AddCollectionMemberParams, DirectCollectionAdd, DeferredCollectionAdd, CollectionAddMemberResult, PendingCollectionInvitationEntry, } from "./api/collectionsApi";
 export type { RuleSetInfo, RuleSetSchema, RuleSetTestResult, RuleSetDebugResult, TraceEntry, TriggerDefInfo, ModelRulesInfo, PathDeclaration, RuleLoads, RuleExpression, CategoryRules, } from "./api/ruleSetsApi";
@@ -60,13 +61,15 @@ export type { DocumentBlobContext, BlobUploadSourceOptions, BlobUploadResult, Bl
 export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI, DocumentIngestsAPI, DocumentSnapshotsAPI, } from "./api/documentsApi";
 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, 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";
 export type { GroupsAPI } from "./api/groupsApi";
 export type { RuleSetsAPI } from "./api/ruleSetsApi";
 export type { NotificationsAPI, NotificationInfo, NotificationListOptions, NotificationListResult, NotificationSendResult, SendNotificationParams, PushDeviceInfo, RegisterPushDeviceParams, } from "./api/notificationsApi";
-export type { BlobBucketsAPI, BlobBucketInfo, BlobBucketTtlTier, BlobBucketPreset, BlobBucketAccessPolicy, CreateBlobBucketParams, UpdateBlobBucketParams, BlobInfo, BlobUploadParams, BucketBlobUploadResult, BucketBlobListResult, BlobListOptions, BlobSignedUrlResult, BatchBlobDeleteResult, } from "./api/blobBucketsApi";
+export type { BlobBucketsAPI, BlobBucketInfo, BlobBucketTtlTier, BlobBucketPreset, CreateBlobBucketParams, UpdateBlobBucketParams, BlobInfo, BlobUploadParams, BucketBlobUploadResult, BucketBlobListResult, BlobListOptions, BlobSignedUrlResult, BatchBlobDeleteResult, } from "./api/blobBucketsApi";
 export type { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
 export type { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 export type { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
@@ -91,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";
@@ -404,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;
@@ -1724,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. */
@@ -2517,6 +2552,10 @@ export declare class JsBaoClient extends Observable<any> {
     /** Sub-API for managing document collections.
      * @group Sub-APIs */
     collections: CollectionsAPI;
+    /** Sub-API for agents: `agents.sessions` lists, reads, renames and deletes
+     * agent sessions and manages their members.
+     * @group Sub-APIs */
+    agents: AgentsAPI;
     /** Sub-API for managing rule sets.
      * @group Sub-APIs */
     ruleSets: RuleSetsAPI;
@@ -2689,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).
@@ -3169,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).
@@ -4277,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 */
@@ -4622,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
@@ -4646,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
@@ -4682,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.
@@ -4842,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;
     }>;
@@ -4928,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.