js-bao-wss-client 3.4.0 → 3.5.0-alpha.0

package/README.md

@@ -889,7 +889,7 @@ Additional flags:
 ### Pagination and tags
 
 - Paging params: `limit`, `cursor`, `forward`, `returnPage`. Default sort is by `grantedAt` (document permission grant time) descending; pass `forward: true` for ascending.
-- `returnPage: true` returns `{ items, cursor }` (backward-compatible array when omitted). With `refreshFromServer: true`, a background page walker fetches the remaining pages and updates the cache/`documentMetadataChanged` events; set `refreshFromServer: false` if you only want the first page. Note: cursors come from server responses; local-only/local-first paths do not fabricate cursors or enforce `limit` sizing—use `returnPage: true` when you need a cursor even if data is cached. To synchronously walk all pages yourself, loop on `{ returnPage: true, limit, cursor }` until `cursor` is null. To hydrate the full cache in one call, use `client.syncMetadata({ scope: "all", pageSize, includeRoot })` and then list with `refreshFromServer: false`.
+- `returnPage: true` returns `{ items, hasMore, nextCursor }` (backward-compatible array when omitted). With `refreshFromServer: true`, a background page walker fetches the remaining pages and updates the cache/`documentMetadataChanged` events; set `refreshFromServer: false` if you only want the first page. Note: cursors come from server responses; local-only/local-first paths do not fabricate cursors or enforce `limit` sizing—use `returnPage: true` when you need a cursor even if data is cached. To synchronously walk all pages yourself, loop on `{ returnPage: true, limit, cursor }`, passing each page's `nextCursor` back as `cursor`, until `nextCursor` is absent. To hydrate the full cache in one call, use `client.syncMetadata({ scope: "all", pageSize, includeRoot })` and then list with `refreshFromServer: false`.
 - Server page size defaults to 100 when `limit` is omitted; you can request smaller/larger pages within server limits.
 - Tag filtering: `tag: string` performs an exact-match filter server-side. Responses include `tags: string[]` and `grantedAt`; both are cached locally and usable offline (e.g., list + `tag` will be filtered from cache when offline/local-only). Root is also considered for tag queries—if you tag the root, it can appear in tag-filtered results even when the default list filters root out. When `refreshFromServer` is true with a tag, the client still fetches the full dataset in the background to keep the cache complete, then filters locally for the tag.
 - Tag CRUD: server endpoints exist (`POST /documents/:id/tags { tag }`, `DELETE /documents/:id/tags/:tag`) and document create accepts optional tags; the high-level client currently exposes tagging via HTTP helpers or `client.makeRequest`.
@@ -1410,8 +1410,8 @@ const page1 = await client.document(documentId).blobs().list({ limit: 10 });
 page1.items.forEach((b) => {
   console.log(b.blobId, b.filename, b.size);
 });
-if (page1.cursor) {
-  const page2 = await blobs.list({ cursor: page1.cursor });
+if (page1.nextCursor) {
+  const page2 = await blobs.list({ cursor: page1.nextCursor });
 }
 ```
 
@@ -1941,6 +1941,13 @@ const group = await client.groups.create({
   description: "All engineers",
 });
 
+// Create a group and stamp resource metadata on it in the same call
+const readingGroup = await client.groups.create({
+  groupType: "class-reading-group",
+  name: "Reading group",
+  initialMetadata: { classLink: { classId: "class-A" } },
+});
+
 // List groups
 const groups = await client.groups.list();
 const teams = await client.groups.list({ type: "team" });

package/dist/JsBaoClient.d.ts

@@ -43,7 +43,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, GrantPermissionParams, 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, 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 { 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";
@@ -72,7 +72,7 @@ export type { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 export type { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 export type { CronTriggersAPI } 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, DocumentIngestSession, DocumentIngestCounterBucket, DocumentIngestStageCounters, DocumentIngestChunkUpload, DocumentIngestChunkUploadResult, DocumentIngestPage, DocumentSnapshotBuild, DocumentSnapshotPage, DocumentSnapshotRequest, } from "./api/documentsApi";
+export type { CreateDocumentOptions, CreateWithAliasOptions, GetOrCreateWithAliasOptions, DeleteDocumentOptions, DocumentAccessRequest, DocumentAccessRequestResponse, DocumentListOptions, DocumentListPage, EvictAllDocumentsOptions, EvictDocumentOptions, GrantGroupPermissionParams, ResolveAliasParams, SetAliasParams, UpdateDocumentData, DocumentIngestSession, DocumentIngestCounterBucket, DocumentIngestStageCounters, DocumentIngestChunkUpload, DocumentIngestChunkUploadResult, DocumentIngestPage, DocumentSnapshotBuild, DocumentSnapshotPage, DocumentSnapshotRequest, } from "./api/documentsApi";
 export type { CreateDatabaseParams, UpdateDatabaseParams } from "./api/databasesApi";
 export type { CreateCollectionParams, UpdateCollectionParams, GrantCollectionGroupPermissionParams, ListCollectionsOptions, } from "./api/collectionsApi";
 export type { ListResult } from "./api/listResult";
@@ -91,7 +91,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, FunctionWaitForResult, 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, } 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";
@@ -1388,8 +1388,6 @@ export interface ListWorkflowRunsResult {
     nextCursor?: string;
     /** True when a next page exists. */
     hasMore?: boolean;
-    /** @deprecated Alias of `nextCursor` kept for one deprecation window. */
-    cursor?: string;
     /**
      * How many runs the server examined to produce this page.
      *
@@ -3037,14 +3035,6 @@ export declare class JsBaoClient extends Observable<any> {
      * @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
-     * @deprecated No longer called internally — `hasIndexedDbSnapshot` is now
-     *   ignored in favour of checking live ydoc content via `ydocHasData()`.
-     *   Retained for external callers; will be removed in a future major version.
-     * @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
@@ -4487,8 +4477,6 @@ export declare class JsBaoClient extends Observable<any> {
      * @param timeoutMs - Maximum time to wait before rejecting (ms, default 30000)
      * @group Offline & Sync */
     waitForInitialSync(documentId: string, timeoutMs?: number): Promise<void>;
-    /** @deprecated Use {@link waitForInitialSync} instead. */
-    waitForSync(documentId: string, timeoutMs?: number): Promise<void>;
     /**
      * Wait until the server confirms it has all of this client's writes.
      * Polls {@link checkStateVector} until `includesWrites` is true.

package/dist/JsBaoClient.js

@@ -1755,14 +1755,12 @@ export class JsBaoClient extends Observable {
                     const path = `/${endpoint}${qs.length ? `?${qs.join("&")}` : ""}`;
                     const response = await this.makeRequest("GET", path);
                     if (Array.isArray(response)) {
-                        return { items: response, cursor: null };
+                        return { items: response, nextCursor: null };
                     }
                     const page = response;
-                    // #1316: prefer `nextCursor`; fall back to the deprecated `cursor`
-                    // alias for older servers.
                     return {
                         items: page.items || [],
-                        cursor: page.nextCursor ?? page.cursor ?? null,
+                        nextCursor: page.nextCursor ?? null,
                     };
                 };
                 const allItems = [];
@@ -1782,7 +1780,7 @@ export class JsBaoClient extends Observable {
                                 allIds.add(id);
                             allItems.push(item);
                         }
-                        cursor = page.cursor || null;
+                        cursor = page.nextCursor || null;
                     } while (cursor);
                 }
                 items = allItems;
@@ -2077,13 +2075,13 @@ export class JsBaoClient extends Observable {
                 // response says nothing about where the scope ends.
                 if (Array.isArray(response))
                     return null;
-                const items = response?.items ?? response?.documents;
+                const items = response?.items;
                 // A body that never mentioned `items` is not a page of this scope, and
                 // an empty list read as the whole scope evicts everything.
                 if (!Array.isArray(items))
                     return null;
                 collected.push(...items);
-                const next = response?.nextCursor ?? response?.cursor ?? null;
+                const next = response?.nextCursor ?? null;
                 if (!next) {
                     // No continuation token. If the page nevertheless says more rows
                     // remain, the walk cannot ask for them and so never reached the end
@@ -3733,16 +3731,13 @@ export class JsBaoClient extends Observable {
         const path = `/workflows/runs${params.length ? `?${params.join("&")}` : ""}`;
         const response = await this.makeRequest("GET", path);
         const page = response;
-        // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias
-        // for older servers.
-        const nextCursor = page?.nextCursor ?? page?.cursor ?? undefined;
+        const nextCursor = page?.nextCursor ?? undefined;
         const result = {
             items: page?.items ?? [],
             hasMore: typeof page?.hasMore === "boolean" ? page.hasMore : !!nextCursor,
         };
         if (nextCursor != null) {
             result.nextCursor = nextCursor;
-            result.cursor = nextCursor;
         }
         // #2237: filtered listings report how far the server's walk got. Only
         // surfaced when the server actually sent a number — `undefined` means
@@ -4701,52 +4696,6 @@ export class JsBaoClient extends Observable {
         }
         return false;
     }
-    /** 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
-     * @deprecated No longer called internally — `hasIndexedDbSnapshot` is now
-     *   ignored in favour of checking live ydoc content via `ydocHasData()`.
-     *   Retained for external callers; will be removed in a future major version.
-     * @group Offline & Sync */
-    async updateLocalSnapshotFlag(documentId, hasSnapshot) {
-        const metaIndex = this.docManager.metadataIndex;
-        const existing = metaIndex.get(documentId);
-        const currentFlag = existing?.hasIndexedDbSnapshot === true;
-        if (hasSnapshot === currentFlag)
-            return;
-        const next = (existing || { documentId });
-        const changedFields = ["hasIndexedDbSnapshot"];
-        if (hasSnapshot) {
-            next.hasIndexedDbSnapshot = true;
-            if (typeof next.localBytes !== "number" || next.localBytes <= 0) {
-                next.localBytes = 1;
-                changedFields.push("localBytes");
-            }
-        }
-        else {
-            delete next.hasIndexedDbSnapshot;
-            if (typeof next.localBytes === "number" && next.localBytes > 0) {
-                next.localBytes = 0;
-                changedFields.push("localBytes");
-            }
-        }
-        metaIndex.set(documentId, next);
-        try {
-            await this._putMetadataToIdb(next);
-        }
-        catch (_) { }
-        try {
-            this.emit("documentMetadataChanged", [
-                {
-                    documentId,
-                    metadata: next,
-                    changedFields,
-                    source: "local",
-                },
-            ]);
-        }
-        catch (_) { }
-    }
     // Send awareness state to server
     sendAwarenessState(documentId) {
         if (!this.ws || !this.wsconnected)
@@ -11606,10 +11555,6 @@ export class JsBaoClient extends Observable {
             this.on("sync", onSync);
         });
     }
-    /** @deprecated Use {@link waitForInitialSync} instead. */
-    waitForSync(documentId, timeoutMs = 30000) {
-        return this.waitForInitialSync(documentId, timeoutMs);
-    }
     /**
      * Wait until the server confirms it has all of this client's writes.
      * Polls {@link checkStateVector} until `includesWrites` is true.

package/dist/agents/sessionModels.generated.d.ts

@@ -18,24 +18,31 @@ export { encodeJsonColumn, decodeJsonColumn } from "./sessionModelRuntime";
 export type { PrimitiveQueueEntry } from "./sessionModelRuntime";
 /** The schema version a session row carries in `schemaVersion`. */
 export declare const AGENT_SESSION_SCHEMA_VERSION = 1;
+/** Values this client recognizes for `PrimitiveSessionStatus`. */
 export declare const PRIMITIVE_SESSION_STATUSES: readonly ["idle", "thinking", "running_tool", "awaiting_answer", "failed", "expired", "cancelled"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveSessionStatus = (typeof PRIMITIVE_SESSION_STATUSES)[number] | "unknown";
+/** Values this client recognizes for `PrimitivePartKind`. */
 export declare const PRIMITIVE_PART_KINDS: readonly ["text", "reasoning", "tool_call", "file", "event"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitivePartKind = (typeof PRIMITIVE_PART_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveTextState`. */
 export declare const PRIMITIVE_TEXT_STATES: readonly ["streaming", "done"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveTextState = (typeof PRIMITIVE_TEXT_STATES)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveToolCallState`. */
 export declare const PRIMITIVE_TOOL_CALL_STATES: readonly ["input-streaming", "input-available", "approval-requested", "approval-responded", "output-available", "output-error", "output-denied"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveToolCallState = (typeof PRIMITIVE_TOOL_CALL_STATES)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveAuthorKind`. */
 export declare const PRIMITIVE_AUTHOR_KINDS: readonly ["user", "agent", "app"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveAuthorKind = (typeof PRIMITIVE_AUTHOR_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveStepKind`. */
 export declare const PRIMITIVE_STEP_KINDS: readonly ["model_call", "tool_call"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveStepKind = (typeof PRIMITIVE_STEP_KINDS)[number] | "unknown";
+/** Values this client recognizes for `PrimitiveStepStatus`. */
 export declare const PRIMITIVE_STEP_STATUSES: readonly ["running", "completed", "failed"];
 /** `"unknown"` is a value a newer server sent that this client does not know. */
 export type PrimitiveStepStatus = (typeof PRIMITIVE_STEP_STATUSES)[number] | "unknown";
@@ -182,18 +189,21 @@ interface PrimitivePartRecordBase {
     modifiedAt?: string;
     row?: PrimitivePartRow;
 }
+/** A decoded `PrimitivePart` record with `kind: "text"`. */
 export interface PrimitiveTextPartRecord extends PrimitivePartRecordBase {
     kind: "text";
     state?: PrimitiveTextState;
     text?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "reasoning"`. */
 export interface PrimitiveReasoningPartRecord extends PrimitivePartRecordBase {
     kind: "reasoning";
     state?: PrimitiveTextState;
     text?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "tool_call"`. */
 export interface PrimitiveToolCallPartRecord extends PrimitivePartRecordBase {
     kind: "tool_call";
     state?: PrimitiveToolCallState;
@@ -213,6 +223,7 @@ export interface PrimitiveToolCallPartRecord extends PrimitivePartRecordBase {
     artifactBlobId?: string;
     providerMetadata?: Record<string, unknown>;
 }
+/** A decoded `PrimitivePart` record with `kind: "file"`. */
 export interface PrimitiveFilePartRecord extends PrimitivePartRecordBase {
     kind: "file";
     mediaType?: string;
@@ -220,6 +231,7 @@ export interface PrimitiveFilePartRecord extends PrimitivePartRecordBase {
     blobId?: string;
     sizeBytes?: number;
 }
+/** A decoded `PrimitivePart` record with `kind: "event"`. */
 export interface PrimitiveEventPartRecord extends PrimitivePartRecordBase {
     kind: "event";
     eventKind?: string;
@@ -233,6 +245,7 @@ export interface PrimitiveUnknownPartRecord extends PrimitivePartRecordBase {
     rawKind: string;
     row: PrimitivePartRow;
 }
+/** A decoded `PrimitivePart` record, including unrecognized kinds. */
 export type PrimitivePartRecord = PrimitiveTextPartRecord | PrimitiveReasoningPartRecord | PrimitiveToolCallPartRecord | PrimitiveFilePartRecord | PrimitiveEventPartRecord | PrimitiveUnknownPartRecord;
 /** The attributes of a `PrimitivePart` model instance. */
 export interface PrimitivePartAttrs {

package/dist/agents/sessionModels.generated.js

@@ -20,6 +20,7 @@ import { decodeModelRow, encodeModelRecord, registerSessionModels, sessionRowInv
 export { encodeJsonColumn, decodeJsonColumn } from "./sessionModelRuntime";
 /** The schema version a session row carries in `schemaVersion`. */
 export const AGENT_SESSION_SCHEMA_VERSION = 1;
+/** Values this client recognizes for `PrimitiveSessionStatus`. */
 export const PRIMITIVE_SESSION_STATUSES = [
     "idle",
     "thinking",
@@ -29,6 +30,7 @@ export const PRIMITIVE_SESSION_STATUSES = [
     "expired",
     "cancelled",
 ];
+/** Values this client recognizes for `PrimitivePartKind`. */
 export const PRIMITIVE_PART_KINDS = [
     "text",
     "reasoning",
@@ -36,7 +38,9 @@ export const PRIMITIVE_PART_KINDS = [
     "file",
     "event",
 ];
+/** Values this client recognizes for `PrimitiveTextState`. */
 export const PRIMITIVE_TEXT_STATES = ["streaming", "done"];
+/** Values this client recognizes for `PrimitiveToolCallState`. */
 export const PRIMITIVE_TOOL_CALL_STATES = [
     "input-streaming",
     "input-available",
@@ -46,8 +50,11 @@ export const PRIMITIVE_TOOL_CALL_STATES = [
     "output-error",
     "output-denied",
 ];
+/** Values this client recognizes for `PrimitiveAuthorKind`. */
 export const PRIMITIVE_AUTHOR_KINDS = ["user", "agent", "app"];
+/** Values this client recognizes for `PrimitiveStepKind`. */
 export const PRIMITIVE_STEP_KINDS = ["model_call", "tool_call"];
+/** Values this client recognizes for `PrimitiveStepStatus`. */
 export const PRIMITIVE_STEP_STATUSES = [
     "running",
     "completed",