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

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, 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,24 @@ 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;
 }
 /**
  * Payload of the `workflowStatus` event (`client.on("workflowStatus", ...)`).
@@ -1600,8 +1560,8 @@ export interface JsBaoEvents {
     pendingCreateFailed: PendingCreateFailedEvent;
     meUpdated: MeUpdatedEvent;
     meUpdateFailed: MeUpdateFailedEvent;
-    invitation: InvitationEvent;
     notification: NotificationEvent;
+    directMessage: DirectMessageEvent;
     workflowStatus: WorkflowStatusEvent;
     workflowStarted: WorkflowStartedEvent;
     syncPerf: {
@@ -2900,8 +2860,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;
@@ -3714,9 +3674,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<{