js-bao-wss-client 2.2.0-alpha.2 → 2.2.0-alpha.4

package/README.md

@@ -740,7 +740,7 @@ The client emits `documentMetadataChanged` whenever local metadata changes or se
 - Typical emissions:
   - **created/local**: immediately after `documents.create(...)` updates local cache. `changedFields` often includes `createdAt`, `pendingCreate`, `localOnly`, and optionally `title`.
   - **updated/local**: after local changes such as `documents.update(...)` (optimistic `title`), sync status updates (`lastSyncedAt`, `hasUnsyncedLocalChanges`), or localBytes refresh.
-- **updated/server**: after `documents.list({ refreshFromServer: true })` or network-first list merges server metadata (e.g., `title`, `permission`), `changedFields` reflects updated properties.
+- **updated/server**: after `me.ownedDocuments({ refreshFromServer: true })` or network-first list merges server metadata (e.g., `title`, `permission`), `changedFields` reflects updated properties.
 - **evicted/local**: after `documents.evict(id)` or `documents.evictAll(...)`; `metadata` is `null`.
 - **deleted/server or local**: the first delete seen (server push, list refresh, or local `documents.delete`) emits a single `deleted` event; subsequent delete/evict/list refreshes for the same doc are suppressed to avoid duplicates (including 404/offline fallbacks after a successful delete).
 
@@ -810,11 +810,11 @@ await client.goOnline();
 
 ## Metadata Cache and Local Documents
 
-The client maintains an IndexedDB-backed metadata index so apps can render lists and document summaries offline. Local listing is merged into `documents.list(...)`; the former `documents.listLocal()` is removed.
+The client maintains an IndexedDB-backed metadata index so apps can render lists and document summaries offline. Local listing is merged into `me.ownedDocuments(...)`; the former `documents.listLocal()` is removed.
 
 ```typescript
 // List documents (cache-first with background refresh by default)
-const docs = await client.documents.list({
+const docs = await client.me.ownedDocuments({
   includeRoot: false,
   // Default behavior is cache-first with background refresh when local cache exists
   // You can control it explicitly with waitForLoad (see below)
@@ -841,7 +841,7 @@ client.setRetentionPolicy({
 
 Notes:
 
-- The client updates the local metadata cache automatically when `documents.list()` returns server data (including last-known permission and root doc metadata). Root is always cached from the server but filtered out of the returned list unless you pass `includeRoot: true`.
+- The client updates the local metadata cache automatically when `me.ownedDocuments()` returns server data (including last-known permission and root doc metadata). Root is always cached from the server but filtered out of the returned list unless you pass `includeRoot: true`.
 - Cache updates emit `documentMetadataChanged` events (typically with `action: "updated"`, `source: "server"`).
 - Local eviction emits `documentMetadataChanged` with `action: "evicted"`, `metadata: null`.
 - Delete emits a single `documentMetadataChanged` with `action: "deleted"`, then evicts locally without a second emission.
@@ -900,19 +900,19 @@ Events: `pendingCreateCommitted`, `pendingCreateFailed` help drive UI state.
 
 ## Root Documents
 
-Some apps use a per-user root document. The server always returns the root in list responses (unless tag-filtered), and the client caches it. By default `documents.list()` filters it out; pass `includeRoot: true` to surface it (works offline after it’s cached).
+Some apps use a per-user root document. The server always returns the root in list responses (unless tag-filtered), and the client caches it. By default `me.ownedDocuments()` filters it out; pass `includeRoot: true` to surface it (works offline after it’s cached).
 
 ```typescript
 // Exclude root (default)
-const docs = await client.documents.list();
+const docs = await client.me.ownedDocuments();
 
 // Include root document(s)
-const all = await client.documents.list({ includeRoot: true });
+const all = await client.me.ownedDocuments({ includeRoot: true });
 ```
 
 ## Behavior changes
 
-- **Root documents listing**: `documents.list()` excludes root docs by default. Opt-in with `{ includeRoot: true }`.
+- **Root documents listing**: `me.ownedDocuments()` excludes root docs by default. Opt-in with `{ includeRoot: true }`.
 - **Offline mode requests**: When `networkMode` is `"offline"`, HTTP calls fail fast with code `OFFLINE`.
 - **Open options**: `documents.open()` uses `{ waitForLoad, enableNetworkSync, retainLocal, availabilityWaitMs }`. Older options like `waitForPermission`, `offlineWritePolicy`, per-doc `offline`, `provisionalPermission`, and `startNetwork` are removed.
 - **Create return shape**: `documents.create()` returns `{ metadata }` (no `Y.Doc`).
@@ -1160,8 +1160,11 @@ const { metadata } = await client.documents.create({
 });
 console.log("Created document:", metadata.documentId);
 
-// List all documents user has access to
-const documents = await client.documents.list();
+// List documents. There are two readers, and they are disjoint: the documents
+// the user owns, and the documents shared with them. Reading both is what it
+// takes to see everything the user has access to.
+const owned = await client.me.ownedDocuments(); // DocumentInfo[]
+const { items: shared } = await client.me.sharedDocuments(); // page 1 of { items, nextCursor }
 
 // Get document details (network)
 const docInfo = await client.documents.get(documentId);
@@ -1284,9 +1287,6 @@ await client.document(documentId).transferOwnership(newOwnerId);
 const accessResult = await client.documents.validateAccess(documentId);
 if (accessResult.hasAccess) {
   console.log("User has access:", accessResult.permission);
-  if (accessResult.viaInvitation) {
-    console.log("Access via invitation");
-  }
 }
 ```
 
@@ -1680,50 +1680,35 @@ function encodeRFC5987(value) {
 
 The canonical request uses only `origin + pathname`, so all disposition variants reuse the same cache entry. Metadata can live in memory (as shown) or in IndexedDB if you need to survive worker restarts. Because cached responses are stored without `Content-Disposition`, each hit reapplies headers based on the active request. Extend the sample with background eviction or cache versioning as needed.
 
-### Document Invitations
-
-```typescript
-// Create an invitation
-const invitation = await client.documents.createInvitation(
-  documentId,
-  "user@example.com",
-  "read-write" // 'read-write' | 'reader'
-);
-console.log("Invitation created:", invitation.invitationId);
+### Document Sharing
 
-// List all invitations for a document
-const invitations = await client.documents.listInvitations(documentId);
+Per-document invitations were removed in client `3.0.0`. Sharing is
+immediate: `updatePermissions` grants access to a registered user on the spot,
+and for an email that has not registered yet it writes a deferred grant plus an
+app-level invitation whose `inviteToken` the recipient redeems.
 
-// Update an invitation (changes permission)
-const updatedInvitation = await client.documents.updateInvitation(
-  documentId,
-  "user@example.com",
-  "reader"
-);
+```typescript
+// Share with an existing user (takes effect immediately) or defer the grant
+// for an email that has not registered yet.
+const grant = await client.documents.updatePermissions(documentId, {
+  email: "user@example.com",
+  permission: "read-write", // 'read-write' | 'reader'
+});
+if (grant.deferred) {
+  console.log("Deferred until they accept:", grant.inviteToken);
+}
 
-// Get specific invitation
-const inv = await client.documents.getInvitation(
-  documentId,
-  "user@example.com"
-);
+// Deferred grants still waiting on their recipient
+const pending = await client.documents.listPendingInvitations(documentId);
 
-// Delete an invitation
-await client.documents.deleteInvitation(documentId, invitationId);
+// Withdraw access (a live grant or a pending deferred one)
+await client.documents.removePermission(documentId, {
+  email: "user@example.com",
+});
 
-// Accept or decline (invitee)
-await client.document(documentId).acceptInvitation();
-await client.document(documentId).declineInvitation(invitationId);
-```
-
-### Pending Document Invitations (for the current user)
-
-```typescript
-// List documents you’ve been invited to (pending, unexpired)
-const pending = await client.me.pendingDocumentInvitations();
-// Each item includes a best-effort `document` block with metadata (title, tags, createdAt, lastModified, createdBy)
-for (const inv of pending) {
-  console.log(inv.document?.title, inv.document?.tags);
-}
+// The recipient redeems the app-level invitation, which resolves every
+// deferred grant issued to their email.
+await client.invitations.accept(inviteToken);
 ```
 
 ### Users
@@ -1734,53 +1719,6 @@ const user = await client.users.getBasic("u01H...");
 console.log(user.name, user.email, user.appRole);
 ```
 
-### Invitation events
-
-The client emits a unified `invitation` event for real-time invitation changes delivered over the WebSocket. Payload:
-
-- `{ type: "invitation"; action: "created" | "updated" | "cancelled" | "declined" | "accepted"; invitationId; documentId; permission; title?; invitedBy?; invitedAt?; expiresAt?; acceptedBy?; document?: { title?; tags?; createdAt?; lastModified?; createdBy? } }`
-
-#### Actions — who receives each
-
-Events are **targeted**: most actions are delivered to only one side of the invitation (inviter _or_ invitee, not both). A consumer that only subscribes from the invitee side will never see `accepted`, and a consumer that only subscribes from the inviter side will never see `created`, `updated`, or `cancelled`. Both sides of the UI should handle the actions relevant to them.
-
-| `action`     | Delivered to          | When it fires                                                                 |
-| ------------ | --------------------- | ----------------------------------------------------------------------------- |
-| `created`    | **Invitee only**      | A new pending invitation has been issued to this user.                        |
-| `updated`    | **Invitee only**      | An existing pending invitation's permission / expiry was changed.             |
-| `cancelled`  | **Invitee only**      | The inviter (or an admin) cancelled a pending invitation before acceptance.   |
-| `declined`   | **Invitee + inviter** | The invitee explicitly declined; both sides are notified.                     |
-| `accepted`   | **Inviter only**      | The invitee accepted; `acceptedBy` carries the accepting user's `userId`.     |
-
-Consumers writing a `switch` on `evt.action` should include a `default` branch that's either a no-op or a warning rather than throwing — new action values may be added in the future (non-breaking).
-
-Example:
-
-```ts
-client.on("invitation", (evt) => {
-  switch (evt.action) {
-    case "created":
-    case "updated":
-    case "cancelled":
-      // invitee-side: refresh pending-invitations list / badge
-      break;
-    case "declined":
-      // inviter-side: invite is no longer pending
-      break;
-    case "accepted":
-      // inviter-side: new collaborator
-      console.log(`${evt.acceptedBy} accepted invitation to ${evt.documentId}`);
-      break;
-    default:
-      // Unknown action — log and ignore rather than throw, so the client
-      // stays forward-compatible if new action values are added later.
-      console.warn("Unknown invitation action", evt);
-  }
-});
-```
-
-Use this to refresh invitation lists or badge counts without polling.
-
 ## Large Language Models (LLM)
 
 > **Deprecated.** The direct LLM client API (`client.llm.*`) is deprecated and will be removed in a future major release. Use managed prompts (`client.prompts.execute`) or a workflow `llm.chat` step instead.
@@ -3485,13 +3423,12 @@ class CollaborativeEditor {
     permission: "read-write" | "reader"
   ) {
     try {
-      const invitation = await this.client.documents.createInvitation(
-        documentId,
+      const grant = await this.client.documents.updatePermissions(documentId, {
         email,
-        permission
-      );
-      console.log("Invitation sent:", invitation.invitationId);
-      return invitation;
+        permission,
+      });
+      console.log("Shared with", email, grant);
+      return grant;
     } catch (error) {
       console.error("Failed to invite user:", error);
       throw error;

package/dist/JsBaoClient.d.ts

@@ -37,7 +37,7 @@ export { JsBaoError, isJsBaoError, LockTimeoutError, JsBaoApiError, isJsBaoApiEr
 export type { JsBaoErrorCode } from "./errors";
 export { AuthError, AUTH_CODES, googleWebClientAvailable, } from "./internal/authController";
 export type { AuthCode, GoogleClientConfig, GoogleClientsConfig, } from "./internal/authController";
-export type { DocumentInfo, DocumentPermissionEntry, DocumentInvitation, DocumentInvitationResponse, DocumentAccessResult, DocumentGroupPermissionEntry, DocumentAliasInfo, DocumentAliasScope, PermissionUpdateResult, DirectPermissionGrant, DeferredPermissionGrant, PendingInvitationEntry, PendingGroupInvitationEntry, LinkAccessResult, } from "./api/documentsApi";
+export type { DocumentInfo, DocumentPermissionEntry, DocumentAccessResult, DocumentGroupPermissionEntry, DocumentAliasInfo, DocumentAliasScope, PermissionUpdateResult, DirectPermissionGrant, DeferredPermissionGrant, PendingInvitationEntry, PendingGroupInvitationEntry, LinkAccessResult, } from "./api/documentsApi";
 export type { UserProfile, SharedDocument, SharedDocumentListResult, SharedDocumentsOptions, OwnedDocumentsOptions, } from "./api/meApi";
 export type { SessionInfo } from "./api/sessionApi";
 export type { BasicUserInfo, BatchUserProfile } from "./api/usersApi";
@@ -93,7 +93,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, } from "./api/functionsApi";
+export type { FunctionsAPI, FunctionInvokeOptions, FunctionInvokeResult, FunctionInvokeStatus, FunctionInvokeLimits, FunctionStartOptions, FunctionStartResult, FunctionRunRef, } 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";
@@ -865,64 +865,80 @@ export interface NotificationEvent {
     createdAt: string;
 }
 /**
- * Real-time notification that a document invitation has changed state.
+ * A message a server function sent to this user or this connection.
  *
- * Emitted over the `invitation` event channel (`client.on("invitation", ...)`).
+ * Emitted over the `directMessage` event channel
+ * (`client.on("directMessage", ...)`) when a function calls `ctx.users.send`
+ * or `ctx.connections.send` while this client is connected. `payload` is the
+ * function's own value, passed through unread by the platform.
  *
- * **Important:** events are targeted — most actions are delivered to only one
- * side of the invitation (inviter _or_ invitee, not both). Consumers must
- * write a switch that handles every action value, or they will silently drop
- * events. See {@link InvitationEvent.action} for the full list and who
- * receives each.
+ * It is a LIVE frame with no durable record behind it: a client that was
+ * offline when the function ran does not receive it later. `functionKey` is
+ * the frame's only attribution — a function running in system mode acts for
+ * nobody, so there is no user to name.
  */
-export interface InvitationEvent {
-    type: "invitation";
-    /**
-     * The lifecycle transition that just occurred for this invitation.
-     *
-     * **Targeting (who receives each action — note the asymmetry):**
-     *
-     * - `"created"`   — sent to the **invitee only**. A new invitation has been
-     *                   sent to them; their UI should surface it.
-     * - `"updated"`   — sent to the **invitee only**. An existing pending
-     *                   invitation was changed (e.g. permission re-issued /
-     *                   expiry extended).
-     * - `"cancelled"` — sent to the **invitee only**. The inviter (or an admin)
-     *                   cancelled the pending invitation; the invitee's UI
-     *                   should drop it from their pending list.
-     * - `"declined"`  — sent to **both the invitee and the inviter**. The
-     *                   invitee explicitly declined; both sides' UIs should
-     *                   update (invitee removes from pending, inviter sees the
-     *                   outcome).
-     * - `"accepted"`  — sent to the **inviter only**. The invitee accepted and
-     *                   now holds a `DocumentPermission`; the inviter's UI can
-     *                   update collaborator lists. `acceptedBy` carries the
-     *                   accepting user's `userId`.
-     *
-     * New action values may be added in the future (non-breaking); consumer
-     * switches should include a `default` branch that is either a no-op or a
-     * warning rather than throwing.
-     */
-    action: "created" | "updated" | "cancelled" | "declined" | "accepted";
-    invitationId: string;
-    documentId: string;
-    permission: string;
-    title?: string;
-    invitedBy?: string;
-    invitedAt?: string;
-    expiresAt?: string;
-    /**
-     * UserId of the invitee who accepted. Populated only when `action === "accepted"`.
-     */
-    acceptedBy?: string;
-    document?: {
-        documentId?: string;
-        title?: string;
-        tags?: string[];
-        createdAt?: string;
-        lastModified?: string;
-        createdBy?: string;
-    };
+export interface DirectMessageEvent {
+    type: "direct.message";
+    payload: unknown;
+    functionKey: string;
+    /** When the platform sent it, ISO 8601. */
+    sentAt: string;
+}
+/**
+ * A message a server function published to a channel this client has joined.
+ *
+ * Emitted over the `channelMessage` event channel
+ * (`client.on("channelMessage", ...)`) for every channel this client holds a
+ * live membership in — the `channel` field says which. `payload` is the
+ * function's own value, passed through unread by the platform.
+ *
+ * Like {@link DirectMessageEvent} it is a LIVE frame with no durable record
+ * behind it, and `functionKey` is its only attribution: a function publishing
+ * from a database-change trigger runs as the app and acts for no user.
+ */
+export interface ChannelMessageEvent {
+    type: "channel.message";
+    channel: string;
+    payload: unknown;
+    functionKey: string;
+    /** When the platform sent it, ISO 8601. */
+    sentAt: string;
+}
+/**
+ * A live channel membership, returned by
+ * {@link JsBaoClient.subscribeToChannel}.
+ *
+ * `expiresAt` is epoch milliseconds and is the membership's whole lifetime:
+ * expiry is the only revocation a channel grant has, so past it the server
+ * stops delivering even though this socket stays open. Renewing means asking
+ * the authorizing function for another grant and subscribing again — which
+ * replaces this membership rather than adding one.
+ */
+export interface ChannelSubscription {
+    channel: string;
+    expiresAt: number;
+    /** Leave the channel. Idempotent. */
+    unsubscribe: () => void;
+}
+/**
+ * A channel subscription the server refused when nothing was waiting on it.
+ *
+ * Emitted over the `channelSubscribeFailed` event channel
+ * (`client.on("channelSubscribeFailed", ...)`). The case this exists for is
+ * RECONNECT: after the socket comes back the client presents each held grant
+ * again, and a grant that expired while the connection was down is refused with
+ * no pending call to reject. The registration for that channel — and only that
+ * channel — is dropped, and this is how an app hears about it, so it can ask
+ * its authorizing function for a fresh grant and subscribe again.
+ *
+ * A refusal that answers a {@link JsBaoClient.subscribeToChannel} call is
+ * reported by rejecting that promise instead, so a failure is never announced
+ * twice. `message` is the server's uniform refusal: an expired, tampered,
+ * cross-app or cross-user grant are deliberately indistinguishable.
+ */
+export interface ChannelSubscribeFailedEvent {
+    channel: string;
+    message: string;
 }
 /**
  * Payload of the `workflowStatus` event (`client.on("workflowStatus", ...)`).
@@ -1600,8 +1616,10 @@ export interface JsBaoEvents {
     pendingCreateFailed: PendingCreateFailedEvent;
     meUpdated: MeUpdatedEvent;
     meUpdateFailed: MeUpdateFailedEvent;
-    invitation: InvitationEvent;
     notification: NotificationEvent;
+    directMessage: DirectMessageEvent;
+    channelMessage: ChannelMessageEvent;
+    channelSubscribeFailed: ChannelSubscribeFailedEvent;
     workflowStatus: WorkflowStatusEvent;
     workflowStarted: WorkflowStartedEvent;
     syncPerf: {
@@ -1959,6 +1977,50 @@ export declare class JsBaoClient extends Observable<any> {
     /** Registry of active database subscriptions — routes inbound `db.change`
      *  frames to the right callback and drives reconnect re-subscribe. */
     private dbSubscriptions;
+    /**
+     * Channel memberships this client is holding, `channel → grant` (#3184).
+     *
+     * The GRANT is stored, not just the channel, because a membership is keyed
+     * by a connection: after a reconnect the server has no record of it, and the
+     * only thing that re-establishes one is presenting the credential again. A
+     * grant that has expired in the meantime is refused, and the refusal drops
+     * exactly that channel's registration.
+     */
+    private channelGrants;
+    /**
+     * Subscribes waiting for their own channel's ack (D3184-007).
+     *
+     * `sent` records whether the frame this call is waiting on ever reached the
+     * wire — R3184-002. A subscribe made before the socket opened registers its
+     * grant and nudges the connection, but sends nothing; the open handler has
+     * to send THAT attempt rather than queue a second one behind it, or the
+     * caller waits out the full 20 s timeout on a connection that came up
+     * immediately.
+     */
+    private pendingChannelSubscribes;
+    /**
+     * How many times this channel has been left — R3184-005.
+     *
+     * A subscribe queued behind an in-flight one is a continuation that has not
+     * run yet, and `unsubscribeFromChannel` cannot cancel a `.then`. Without a
+     * generation, leaving a channel while a renewal was queued would run that
+     * renewal afterwards: the registration would come back, a subscribe would go
+     * out, and the client would be delivered to on a channel it had explicitly
+     * left. Each attempt captures the count it was created under and does
+     * nothing if it has moved.
+     */
+    private channelEpochs;
+    /**
+     * One subscribe at a time per channel — CR3184-004.
+     *
+     * The server answers a subscribe with a frame that names the CHANNEL and
+     * nothing finer, which is what lets subscriptions to DIFFERENT channels be
+     * told apart. Two requests for the SAME channel cannot be: the first answer
+     * would settle both, so an expired grant racing a renewal would reject the
+     * renewal too and drop a registration the server had accepted. Chaining them
+     * keeps every answer attributable to the request that asked for it.
+     */
+    private channelSubscribeChain;
     /** Sub-API for managing documents (list, create, get, delete, share).
      * @group Sub-APIs */
     documents: DocumentsAPI;
@@ -2900,8 +2962,8 @@ export declare class JsBaoClient extends Observable<any> {
     private handlePendingCreateCommitted;
     private handlePendingCreateFailed;
     private handleDocumentMetadataUpdate;
-    private handleInvitationMessage;
     private handleNotificationMessage;
+    private handleDirectMessage;
     private handleWorkflowStatusMessage;
     private handleWorkflowStartedMessage;
     private handleOfflineAuthMessage;
@@ -3112,6 +3174,94 @@ export declare class JsBaoClient extends Observable<any> {
     /** Check if an offline grant is stored locally.
      * @group Offline & Sync */
     hasOfflineGrantStored(): Promise<boolean>;
+    /**
+     * Join a channel a server function authorized.
+     *
+     * `grant` is the token `ctx.channels.authorize` handed back: a signed,
+     * short-lived credential naming this app, this channel and this user. The
+     * promise resolves on the server's ack FOR THIS CHANNEL, so concurrent
+     * subscribes cannot resolve each other, and rejects on the server's uniform
+     * refusal — an expired, tampered, cross-app or cross-user grant are
+     * deliberately indistinguishable, so the rejection says only that the grant
+     * was not accepted.
+     *
+     * Calling it again with a fresh grant RENEWS the membership: expiry is the
+     * only revocation a channel has, so an app that wants a long-lived channel
+     * re-invokes its authorizing function before `expiresAt` and subscribes
+     * again. Frames arrive as `client.on("channelMessage", …)`.
+     *
+     * Two calls for the SAME channel run one after the other, so a renewal
+     * issued while an earlier subscribe is still in flight is answered on its own
+     * merits rather than by whichever frame arrives first.
+     *
+     * @group Realtime
+     */
+    subscribeToChannel(channel: string, grant: string): Promise<ChannelSubscription>;
+    /** The generation `unsubscribeFromChannel` bumps — R3184-005. */
+    private channelEpoch;
+    /**
+     * Re-present a stored grant after a reconnect — through the SAME chain an
+     * explicit subscribe uses (SO3184-006).
+     *
+     * The reconnect pass used to write straight to the socket, which put an
+     * attempt on the wire that the per-channel bookkeeping knew nothing about.
+     * The server's answer names the channel and nothing finer, so a refusal of
+     * the re-issued (possibly expired) grant would settle a RENEWAL the app made
+     * in the meantime: the fresh subscribe would reject and its registration
+     * would be deleted, while the server had accepted it and was delivering to
+     * it. Chaining keeps every answer attributable to the request that asked for
+     * it, exactly as `subscribeToChannel` does.
+     *
+     * Nobody is waiting on this one, so its refusal is announced as
+     * `channelSubscribeFailed` (CR3184-005) rather than rejecting a promise.
+     */
+    private reissueChannelSubscribe;
+    /**
+     * Give up on every subscribe waiting for an answer, because the socket that
+     * would have carried it is gone (SO3184-006).
+     *
+     * The GRANTS stay: the socket failed, not the credential, and the reconnect
+     * pass presents each one again. What must not stay is a pending attempt —
+     * its answer can never arrive, and leaving it in the per-channel chain would
+     * hold the re-issue behind it for the full 20 s timeout.
+     */
+    private abortPendingChannelSubscribes;
+    private startChannelSubscribe;
+    /**
+     * Put the subscribes that never reached the wire onto it — R3184-002.
+     *
+     * A call made while the socket was down registered its grant, created its
+     * promise and sent nothing. On open its frame is sent for the attempt that
+     * is already waiting, so the ack settles the original call. Channels with
+     * nothing pending go the other way, through the ordinary re-issue.
+     *
+     * Returns the channels it sent for, so the reconnect pass does not queue a
+     * second attempt for them.
+     */
+    private flushUnsentChannelSubscribes;
+    /**
+     * Leave a channel. Idempotent, and safe on a closed socket: the
+     * registration goes either way, so a reconnect does not bring it back.
+     *
+     * A subscribe still in flight, or queued behind one, is cancelled with it:
+     * leaving means leaving, so a queued renewal cannot put the membership back
+     * afterwards, and a `subscribeToChannel` promise still waiting for its ack
+     * rejects rather than resolving with a subscription to a channel this client
+     * has already left.
+     *
+     * @group Realtime
+     */
+    unsubscribeFromChannel(channel: string): void;
+    private sendChannelSubscribe;
+    /**
+     * Settle every call waiting on one channel — with the ack, or with the
+     * refusal. Only that channel's waiters and only that channel's
+     * registration: a client with several subscriptions must not lose the ones
+     * that worked (D3184-007).
+     */
+    private settleChannelSubscribe;
+    private handleChannelSubscribed;
+    private handleChannelMessage;
     /**
      * Internal entry point for DatabasesAPI.subscribe(). Ensures the WS is
      * connected, registers the callback with the registry, sends the
@@ -3714,9 +3864,11 @@ export declare class JsBaoClient extends Observable<any> {
         ttlMs?: number;
         preserveOnSignOut?: boolean;
     }): void;
-    /** Create a new document. Writable locally immediately, with the server
+    /** Create a new document. Writes local metadata only, with the server
      * commit racing in the background — unless `options.localOnly` is set, in
-     * which case the document never syncs.
+     * which case the document never syncs. The document is NOT opened: call
+     * `documents.open(documentId)` before reading or writing it, or the write
+     * throws "Document `<id>` is not open".
      * @param options - Document creation options
      * @group Documents */
     createDocument(options: CreateDocumentOptions): Promise<{