@dabble/patches 0.2.21 → 0.2.22

package/dist/net/protocol/JSONRPCServer.d.ts

@@ -1,7 +1,8 @@
-import { type Unsubscriber } from '../../event-signal.js';
-import type { Notification, Request, ServerTransport } from './types.js';
-export type ConnectionSignalSubscriber = (connectionId: string, ...args: any[]) => any;
-export type MessageHandler<P = any, R = any> = (connectionId: string, params: P) => Promise<R> | R;
+import { type Signal, type Unsubscriber } from '../../event-signal.js';
+import type { AuthContext } from '../websocket/AuthorizationProvider.js';
+import type { Notification } from './types.js';
+export type ConnectionSignalSubscriber = (params: any, clientId?: string) => any;
+export type MessageHandler<P = any, R = any> = (params: P, ctx?: AuthContext) => Promise<R> | R;
 /**
  * Lightweight JSON-RPC 2.0 server adapter for {@link PatchesServer}.
  *
@@ -19,12 +20,12 @@ export type MessageHandler<P = any, R = any> = (connectionId: string, params: P)
  *     to the host application.
  */
 export declare class JSONRPCServer {
-    protected transport: ServerTransport;
     /** Map of fully-qualified JSON-RPC method → handler function */
     private readonly handlers;
     /** Allow external callers to emit server-initiated notifications. */
     private readonly notificationSignals;
-    constructor(transport: ServerTransport);
+    /** Allow external callers to emit server-initiated notifications. */
+    readonly onNotify: Signal<(msg: Notification, exceptConnectionId?: string) => void>;
     /**
      * Registers a JSON-RPC method.
      *
@@ -45,25 +46,20 @@ export declare class JSONRPCServer {
      * Sends a JSON-RPC notification (no `id`, therefore no response expected) to
      * the connected client.
      */
-    notify(connectionIds: string[], method: string, params?: any): void;
-    /**
-     * Handles incoming messages from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param raw - The raw message string.
-     */
-    protected _onMessage(connectionId: string, raw: string): Promise<void>;
-    /**
-     * Handles incoming JSON-RPC requests from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param req - The JSON-RPC request object.
-     */
-    protected _handleRequest(connectionId: string, req: Request): Promise<void>;
+    notify(method: string, params?: any, exceptConnectionId?: string): Promise<void>;
     /**
-     * Handles incoming JSON-RPC notifications from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param note - The JSON-RPC notification object.
+     * Synchronously processes a raw JSON-RPC frame from a client and returns the
+     * encoded response frame – or `undefined` when the message is a notification
+     * (no response expected).
+     *
+     * This helper makes the RPC engine usable for stateless transports such as
+     * HTTP: the host simply passes the request body and sends back the returned
+     * string (if any).
+     *
+     * WebSocket and other bidirectional transports delegate to the same logic
+     * internally; the returned string is forwarded over the socket.
      */
-    protected _handleNotification(connectionId: string, note: Notification): Promise<void>;
+    processMessage(raw: string, ctx?: AuthContext): Promise<string | undefined>;
     /**
      * Maps JSON-RPC method names to {@link PatchesServer} calls.
      * @param connectionId - The WebSocket transport object.
@@ -71,9 +67,5 @@ export declare class JSONRPCServer {
      * @param params - The JSON-RPC parameters.
      * @returns The result of the {@link PatchesServer} call.
      */
-    protected _dispatch(connectionId: string, method: string, params: any): Promise<any>;
-    /**
-     * Sends a JSON-RPC error object back to the client.
-     */
-    private _sendError;
+    protected _dispatch(method: string, params: any, ctx?: AuthContext): Promise<any>;
 }

package/dist/net/protocol/JSONRPCServer.js

@@ -1,5 +1,4 @@
 import { signal } from '../../event-signal.js';
-import { PatchesServer } from '../../server/PatchesServer.js';
 /**
  * Lightweight JSON-RPC 2.0 server adapter for {@link PatchesServer}.
  *
@@ -17,13 +16,13 @@ import { PatchesServer } from '../../server/PatchesServer.js';
  *     to the host application.
  */
 export class JSONRPCServer {
-    constructor(transport) {
-        this.transport = transport;
+    constructor() {
         /** Map of fully-qualified JSON-RPC method → handler function */
         this.handlers = new Map();
         /** Allow external callers to emit server-initiated notifications. */
         this.notificationSignals = new Map();
-        transport.onMessage(this._onMessage.bind(this));
+        /** Allow external callers to emit server-initiated notifications. */
+        this.onNotify = signal();
     }
     // -------------------------------------------------------------------------
     // Registration API
@@ -63,63 +62,56 @@ export class JSONRPCServer {
      * Sends a JSON-RPC notification (no `id`, therefore no response expected) to
      * the connected client.
      */
-    notify(connectionIds, method, params) {
+    async notify(method, params, exceptConnectionId) {
         const msg = { jsonrpc: '2.0', method, params };
-        const msgStr = JSON.stringify(msg);
-        connectionIds.forEach(id => this.transport.send(id, msgStr));
+        this.onNotify.emit(msg, exceptConnectionId);
     }
     /**
-     * Handles incoming messages from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param raw - The raw message string.
+     * Synchronously processes a raw JSON-RPC frame from a client and returns the
+     * encoded response frame – or `undefined` when the message is a notification
+     * (no response expected).
+     *
+     * This helper makes the RPC engine usable for stateless transports such as
+     * HTTP: the host simply passes the request body and sends back the returned
+     * string (if any).
+     *
+     * WebSocket and other bidirectional transports delegate to the same logic
+     * internally; the returned string is forwarded over the socket.
      */
-    async _onMessage(connectionId, raw) {
+    async processMessage(raw, ctx) {
         let message;
+        // --- Parse & basic validation ------------------------------------------------
         try {
             message = JSON.parse(raw);
         }
         catch (err) {
-            this._sendError(connectionId, null, -32700, 'Parse error', err);
-            return;
+            return rpcError(-32700, 'Parse error', err);
+        }
+        // Ensure it looks like a JSON-RPC call (must have a method field)
+        if (!message || typeof message !== 'object' || !('method' in message)) {
+            const invalidId = message?.id ?? null;
+            return rpcError(-32600, 'Invalid Request', invalidId);
         }
-        if (message && typeof message === 'object' && 'method' in message) {
-            // Notification or request either way--delegate.
-            if ('id' in message && message.id !== undefined) {
-                await this._handleRequest(connectionId, message);
+        // --- Distinguish request vs. notification -----------------------------------
+        if ('id' in message && message.id !== undefined) {
+            // -> Request ----------------------------------------------------------------
+            try {
+                const result = await this._dispatch(message.method, message.params, ctx);
+                const response = { jsonrpc: '2.0', id: message.id, result };
+                return JSON.stringify(response);
             }
-            else {
-                await this._handleNotification(connectionId, message);
+            catch (err) {
+                return rpcError(err?.code ?? -32000, err?.message ?? 'Server error', err?.stack);
             }
         }
         else {
-            // Client sent something we do not understand.
-            this._sendError(connectionId, message?.id ?? null, -32600, 'Invalid Request');
-        }
-    }
-    /**
-     * Handles incoming JSON-RPC requests from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param req - The JSON-RPC request object.
-     */
-    async _handleRequest(connectionId, req) {
-        try {
-            const result = await this._dispatch(connectionId, req.method, req.params);
-            const response = { jsonrpc: '2.0', id: req.id, result };
-            this.transport.send(connectionId, JSON.stringify(response));
-        }
-        catch (err) {
-            this._sendError(connectionId, req.id, -32000, err?.message ?? 'Server error', err?.stack);
-        }
-    }
-    /**
-     * Handles incoming JSON-RPC notifications from the client.
-     * @param connectionId - The WebSocket transport object.
-     * @param note - The JSON-RPC notification object.
-     */
-    async _handleNotification(connectionId, note) {
-        const thisSignal = this.notificationSignals.get(note.method);
-        if (thisSignal) {
-            thisSignal.emit(connectionId, note.params);
+            // -> Notification -----------------------------------------------------------
+            // Forward the notification to any listeners and return nothing.
+            const thisSignal = this.notificationSignals.get(message.method);
+            if (thisSignal) {
+                thisSignal.emit(message.params, ctx?.clientId);
+            }
+            return undefined;
         }
     }
     /**
@@ -129,7 +121,7 @@ export class JSONRPCServer {
      * @param params - The JSON-RPC parameters.
      * @returns The result of the {@link PatchesServer} call.
      */
-    async _dispatch(connectionId, method, params) {
+    async _dispatch(method, params, ctx) {
         const handler = this.handlers.get(method);
         if (!handler) {
             throw new Error(`Unknown method '${method}'.`);
@@ -137,17 +129,9 @@ export class JSONRPCServer {
         if (!params || typeof params !== 'object' || Array.isArray(params)) {
             throw new Error(`Invalid parameters for method '${method}'.`);
         }
-        return handler(connectionId, params);
-    }
-    /**
-     * Sends a JSON-RPC error object back to the client.
-     */
-    _sendError(connectionId, id, code, message, data) {
-        const errorObj = {
-            jsonrpc: '2.0',
-            id: id,
-            error: { code, message, data },
-        }; // type cast because TS cannot narrow when error present
-        this.transport.send(connectionId, JSON.stringify(errorObj));
+        return handler(params, ctx);
     }
 }
+function rpcError(code, message, data) {
+    return JSON.stringify({ jsonrpc: '2.0', id: null, error: { code, message, data } });
+}

package/dist/net/protocol/types.d.ts

@@ -39,6 +39,12 @@ export interface ServerTransport {
     send(toConnectionId: string, raw: string): void | Promise<void>;
     /** Subscribe to incoming raw frames from any client */
     onMessage(cb: (fromConnectionId: string, raw: string) => void): Unsubscriber;
+    /** Lists all subscriptions for a document. */
+    listSubscriptions(docId: string): Promise<string[]>;
+    /** Adds a subscription for a client to one or more documents. */
+    addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
+    /** Removes a subscription for a client from one or more documents. */
+    removeSubscription(clientId: string, docIds: string[]): Promise<string[]>;
 }
 /**
  * Represents a JSON-RPC 2.0 request object.

package/dist/net/websocket/AuthorizationProvider.d.ts

@@ -5,13 +5,22 @@
  * "write" – mutating operations (commitChanges, deleteDoc, …)
  */
 export type Access = 'read' | 'write';
+/**
+ * Context object for authorization providers.
+ * @property {string} clientId - The ID of the client making the request.
+ * @property {any} [data] - Additional data associated with the request.
+ */
+export interface AuthContext {
+    clientId?: string;
+    [k: string]: any;
+}
 /**
  * Allows the host application to decide whether a given connection can perform
  * a certain action on a document.  Implementations are entirely application-
  * specific – they may look at a JWT decoded during the WebSocket handshake,
  * consult an ACL service, inspect the actual RPC method, etc.
  */
-export interface AuthorizationProvider {
+export interface AuthorizationProvider<T extends AuthContext = AuthContext> {
     /**
      * General-purpose hook executed for every JSON-RPC call that targets a
      * document. Implementations are free to look only at the first three
@@ -22,13 +31,13 @@ export interface AuthorizationProvider {
      * Returning `true` (or a resolved promise with `true`) permits the action.
      * Returning `false` or throwing will cause the RPC to fail with an error.
      *
-     * @param connectionId  WebSocket connection ID of the caller
+     * @param ctx           Context object containing client ID and additional data
      * @param docId         Logical document to be accessed (branch IDs count)
      * @param kind          High-level access category – `'read' | 'write'`
      * @param method        JSON-RPC method name (e.g. `getDoc`, `branch.merge`)
      * @param params        The exact parameter object supplied by the client
      */
-    canAccess(connectionId: string, docId: string, kind: Access, method: string, params?: Record<string, any>): boolean | Promise<boolean>;
+    canAccess(ctx: T | undefined, docId: string, kind: Access, method: string, params?: Record<string, any>): boolean | Promise<boolean>;
 }
 /**
  * A permissive provider that authorises every action.  Used as the default so

package/dist/net/websocket/RPCServer.d.ts

@@ -0,0 +1,120 @@
+import type { PatchesBranchManager } from '../../server/PatchesBranchManager.js';
+import type { PatchesHistoryManager } from '../../server/PatchesHistoryManager.js';
+import type { PatchesServer } from '../../server/PatchesServer.js';
+import type { Change, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions } from '../../types.js';
+import { JSONRPCServer } from '../protocol/JSONRPCServer.js';
+import type { ServerTransport } from '../protocol/types.js';
+import type { AuthContext, AuthorizationProvider } from './AuthorizationProvider.js';
+/**
+ * High-level client for the Patches real-time collaboration service.
+ * This class provides document subscription, patch notification handling,
+ * versioning, and other OT-specific functionality over a JSON RPC interface.
+ */
+export interface RPCServerOptions {
+    transport: ServerTransport;
+    patches: PatchesServer;
+    history?: PatchesHistoryManager;
+    branches?: PatchesBranchManager;
+    auth?: AuthorizationProvider;
+}
+export declare class RPCServer {
+    rpc: JSONRPCServer;
+    auth: AuthorizationProvider;
+    protected patches: PatchesServer;
+    protected history?: PatchesHistoryManager;
+    protected branches?: PatchesBranchManager;
+    /**
+     * Creates a new Patches WebSocket client instance.
+     * @param patches - The patches server instance to handle document operations
+     * @param history - (Optional) History manager instance to handle versioning operations
+     * @param branches - (Optional) Branch manager instance to handle branching operations
+     * @param auth - (Optional) Authorization provider implementation. Defaults to a permissive provider.
+     */
+    constructor({ patches, history, branches, auth }: RPCServerOptions);
+    /**
+     * Gets the latest state (content and revision) of a document.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The document parameters
+     * @param params.docId - The ID of the document
+     * @param params.atRev - Optional revision number to get document state at
+     */
+    getDoc(params: {
+        docId: string;
+        atRev?: number;
+    }, ctx?: AuthContext): Promise<import("../../types.js").PatchesSnapshot<any>>;
+    /**
+     * Gets changes that occurred for a document after a specific revision number.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The change request parameters
+     * @param params.docId - The ID of the document
+     * @param params.rev - The revision number after which to fetch changes
+     */
+    getChangesSince(params: {
+        docId: string;
+        rev: number;
+    }, ctx?: AuthContext): Promise<Change[]>;
+    /**
+     * Applies a set of client-generated changes to a document on the server.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The change parameters
+     * @param params.docId - The ID of the document
+     * @param params.changes - An array of changes to apply
+     */
+    commitChanges(params: {
+        docId: string;
+        changes: Change[];
+    }, ctx?: AuthContext): Promise<Change[]>;
+    /**
+     * Deletes a document on the server.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The deletion parameters
+     * @param params.docId - The ID of the document to delete
+     */
+    deleteDoc(params: {
+        docId: string;
+    }, ctx?: AuthContext): Promise<void>;
+    listVersions(params: {
+        docId: string;
+        options?: ListVersionsOptions;
+    }, ctx?: AuthContext): Promise<import("../../types.js").VersionMetadata[]>;
+    createVersion(params: {
+        docId: string;
+        metadata: EditableVersionMetadata;
+    }, ctx?: AuthContext): Promise<string>;
+    updateVersion(params: {
+        docId: string;
+        versionId: string;
+        metadata: EditableVersionMetadata;
+    }, ctx?: AuthContext): Promise<void>;
+    getStateAtVersion(params: {
+        docId: string;
+        versionId: string;
+    }, ctx?: AuthContext): Promise<any>;
+    getChangesForVersion(params: {
+        docId: string;
+        versionId: string;
+    }, ctx?: AuthContext): Promise<Change[]>;
+    listServerChanges(params: {
+        docId: string;
+        options?: ListChangesOptions;
+    }, ctx?: AuthContext): Promise<Change[]>;
+    listBranches(params: {
+        docId: string;
+    }, ctx?: AuthContext): Promise<import("../../types.js").Branch[]>;
+    createBranch(params: {
+        docId: string;
+        rev: number;
+        metadata?: EditableVersionMetadata;
+    }, ctx?: AuthContext): Promise<string>;
+    closeBranch(params: {
+        branchId: string;
+    }, ctx?: AuthContext): Promise<void>;
+    mergeBranch(params: {
+        branchId: string;
+    }, ctx?: AuthContext): Promise<Change[]>;
+    protected assertAccess(ctx: AuthContext | undefined, docId: string, kind: 'read' | 'write', method: string, params?: Record<string, any>): Promise<void>;
+    protected assertRead(ctx: AuthContext | undefined, docId: string, method: string, params?: Record<string, any>): Promise<void>;
+    protected assertWrite(ctx: AuthContext | undefined, docId: string, method: string, params?: Record<string, any>): Promise<void>;
+    protected assertHistoryEnabled(): void;
+    protected assertBranchingEnabled(): void;
+}

package/dist/net/websocket/RPCServer.js

@@ -0,0 +1,187 @@
+import { JSONRPCServer } from '../protocol/JSONRPCServer.js';
+import { allowAll } from './AuthorizationProvider.js';
+export class RPCServer {
+    /**
+     * Creates a new Patches WebSocket client instance.
+     * @param patches - The patches server instance to handle document operations
+     * @param history - (Optional) History manager instance to handle versioning operations
+     * @param branches - (Optional) Branch manager instance to handle branching operations
+     * @param auth - (Optional) Authorization provider implementation. Defaults to a permissive provider.
+     */
+    constructor({ patches, history, branches, auth = allowAll }) {
+        this.rpc = new JSONRPCServer();
+        this.patches = patches;
+        this.history = history;
+        this.branches = branches;
+        this.auth = auth;
+        // Document operations
+        this.rpc.registerMethod('getDoc', this.getDoc.bind(this));
+        this.rpc.registerMethod('getChangesSince', this.getChangesSince.bind(this));
+        this.rpc.registerMethod('commitChanges', this.commitChanges.bind(this));
+        this.rpc.registerMethod('deleteDoc', this.deleteDoc.bind(this));
+        // History manager operations (if provided)
+        if (this.history) {
+            this.rpc.registerMethod('listVersions', this.listVersions.bind(this));
+            this.rpc.registerMethod('createVersion', this.createVersion.bind(this));
+            this.rpc.registerMethod('updateVersion', this.updateVersion.bind(this));
+            this.rpc.registerMethod('getVersionState', this.getStateAtVersion.bind(this));
+            this.rpc.registerMethod('getVersionChanges', this.getChangesForVersion.bind(this));
+            this.rpc.registerMethod('listServerChanges', this.listServerChanges.bind(this));
+        }
+        // Branch manager operations (if provided)
+        if (this.branches) {
+            this.rpc.registerMethod('listBranches', this.listBranches.bind(this));
+            this.rpc.registerMethod('createBranch', this.createBranch.bind(this));
+            this.rpc.registerMethod('closeBranch', this.closeBranch.bind(this));
+            this.rpc.registerMethod('mergeBranch', this.mergeBranch.bind(this));
+        }
+        // -------------------------------------------------------------------------
+        // Listen to core server events and forward as JSON-RPC notifications
+        // -------------------------------------------------------------------------
+        this.patches.onChangesCommitted((docId, changes, originClientId) => {
+            this.rpc.notify('changesCommitted', { docId, changes }, originClientId);
+        });
+        this.patches.onDocDeleted((docId, originClientId) => {
+            this.rpc.notify('docDeleted', { docId }, originClientId);
+        });
+    }
+    /**
+     * Gets the latest state (content and revision) of a document.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The document parameters
+     * @param params.docId - The ID of the document
+     * @param params.atRev - Optional revision number to get document state at
+     */
+    async getDoc(params, ctx) {
+        const { docId, atRev } = params;
+        await this.assertRead(ctx, docId, 'getDoc', params);
+        return this.patches.getDoc(docId, atRev);
+    }
+    /**
+     * Gets changes that occurred for a document after a specific revision number.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The change request parameters
+     * @param params.docId - The ID of the document
+     * @param params.rev - The revision number after which to fetch changes
+     */
+    async getChangesSince(params, ctx) {
+        const { docId, rev } = params;
+        await this.assertRead(ctx, docId, 'getChangesSince', params);
+        return this.patches.getChangesSince(docId, rev);
+    }
+    /**
+     * Applies a set of client-generated changes to a document on the server.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The change parameters
+     * @param params.docId - The ID of the document
+     * @param params.changes - An array of changes to apply
+     */
+    async commitChanges(params, ctx) {
+        const { docId, changes } = params;
+        await this.assertWrite(ctx, docId, 'commitChanges', params);
+        const [priorChanges, newChanges] = await this.patches.commitChanges(docId, changes, ctx?.clientId);
+        return [...priorChanges, ...newChanges];
+    }
+    /**
+     * Deletes a document on the server.
+     * @param connectionId - The ID of the connection making the request
+     * @param params - The deletion parameters
+     * @param params.docId - The ID of the document to delete
+     */
+    async deleteDoc(params, ctx) {
+        const { docId } = params;
+        await this.assertWrite(ctx, docId, 'deleteDoc', params);
+        await this.patches.deleteDoc(docId, ctx?.clientId);
+    }
+    // ---------------------------------------------------------------------------
+    // History Manager wrappers
+    // ---------------------------------------------------------------------------
+    async listVersions(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, options } = params;
+        await this.assertRead(ctx, docId, 'listVersions', params);
+        return this.history.listVersions(docId, options ?? {});
+    }
+    async createVersion(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, metadata } = params;
+        await this.assertWrite(ctx, docId, 'createVersion', params);
+        return this.history.createVersion(docId, metadata);
+    }
+    async updateVersion(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, versionId, metadata } = params;
+        await this.assertWrite(ctx, docId, 'updateVersion', params);
+        return this.history.updateVersion(docId, versionId, metadata);
+    }
+    async getStateAtVersion(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, versionId } = params;
+        await this.assertRead(ctx, docId, 'getStateAtVersion', params);
+        return this.history.getStateAtVersion(docId, versionId);
+    }
+    async getChangesForVersion(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, versionId } = params;
+        await this.assertRead(ctx, docId, 'getChangesForVersion', params);
+        return this.history.getChangesForVersion(docId, versionId);
+    }
+    async listServerChanges(params, ctx) {
+        this.assertHistoryEnabled();
+        const { docId, options } = params;
+        await this.assertRead(ctx, docId, 'listServerChanges', params);
+        return this.history.listServerChanges(docId, options ?? {});
+    }
+    // ---------------------------------------------------------------------------
+    // Branch Manager wrappers
+    // ---------------------------------------------------------------------------
+    async listBranches(params, ctx) {
+        this.assertBranchingEnabled();
+        const { docId } = params;
+        await this.assertRead(ctx, docId, 'listBranches', params);
+        return this.branches.listBranches(docId);
+    }
+    async createBranch(params, ctx) {
+        this.assertBranchingEnabled();
+        const { docId, rev, metadata } = params;
+        await this.assertWrite(ctx, docId, 'createBranch', params);
+        return this.branches.createBranch(docId, rev, metadata);
+    }
+    async closeBranch(params, ctx) {
+        this.assertBranchingEnabled();
+        const { branchId } = params;
+        await this.assertWrite(ctx, branchId, 'closeBranch', params);
+        return this.branches.closeBranch(branchId, 'closed');
+    }
+    async mergeBranch(params, ctx) {
+        this.assertBranchingEnabled();
+        const { branchId } = params;
+        await this.assertWrite(ctx, branchId, 'mergeBranch', params);
+        return this.branches.mergeBranch(branchId);
+    }
+    // ---------------------------------------------------------------------------
+    // Authorization helpers
+    // ---------------------------------------------------------------------------
+    async assertAccess(ctx, docId, kind, method, params) {
+        const ok = await this.auth.canAccess(ctx, docId, kind, method, params);
+        if (!ok) {
+            throw new Error(`${kind.toUpperCase()}_FORBIDDEN:${docId}`);
+        }
+    }
+    assertRead(ctx, docId, method, params) {
+        return this.assertAccess(ctx, docId, 'read', method, params);
+    }
+    assertWrite(ctx, docId, method, params) {
+        return this.assertAccess(ctx, docId, 'write', method, params);
+    }
+    assertHistoryEnabled() {
+        if (!this.history) {
+            throw new Error('History is not enabled');
+        }
+    }
+    assertBranchingEnabled() {
+        if (!this.branches) {
+            throw new Error('Branching is not enabled');
+        }
+    }
+}

package/dist/net/websocket/WebSocketServer.d.ts

@@ -1,144 +1,36 @@
-import type { PatchesBranchManager } from '../../server/PatchesBranchManager.js';
-import type { PatchesHistoryManager } from '../../server/PatchesHistoryManager.js';
-import type { PatchesServer } from '../../server/PatchesServer.js';
-import type { Change, EditableVersionMetadata, ListVersionsOptions } from '../../types.js';
-import { JSONRPCServer } from '../protocol/JSONRPCServer.js';
 import type { ServerTransport } from '../protocol/types.js';
-import type { AuthorizationProvider } from './AuthorizationProvider.js';
+import type { AuthContext, AuthorizationProvider } from './AuthorizationProvider.js';
+import type { RPCServer } from './RPCServer.js';
 /**
  * High-level client for the Patches real-time collaboration service.
  * This class provides document subscription, patch notification handling,
- * versioning, and other OT-specific functionality
- * over a WebSocket connection.
+ * versioning, and other OT-specific functionality over a WebSocket connection.
  */
-export interface WebSocketServerOptions {
-    transport: ServerTransport;
-    patches: PatchesServer;
-    history?: PatchesHistoryManager;
-    branches?: PatchesBranchManager;
-    auth?: AuthorizationProvider;
-}
 export declare class WebSocketServer {
     protected transport: ServerTransport;
-    protected rpc: JSONRPCServer;
-    protected patches: PatchesServer;
-    protected history?: PatchesHistoryManager;
-    protected branches?: PatchesBranchManager;
     protected auth: AuthorizationProvider;
     /**
      * Creates a new Patches WebSocket client instance.
+     *
      * @param transport - The transport layer implementation that will be used for sending/receiving messages
-     * @param patches - The patches server instance to handle document operations
-     * @param auth - (Optional) Authorization provider implementation. Defaults to a permissive provider.
      */
-    constructor({ transport, patches, history, branches, auth }: WebSocketServerOptions);
-    protected assertAccess(connectionId: string, docId: string, kind: 'read' | 'write', method: string, params?: Record<string, any>): Promise<void>;
-    protected assertRead(connectionId: string, docId: string, method: string, params?: Record<string, any>): Promise<void>;
-    protected assertWrite(connectionId: string, docId: string, method: string, params?: Record<string, any>): Promise<void>;
-    protected assertHistoryEnabled(): void;
-    protected assertBranchingEnabled(): void;
+    constructor(transport: ServerTransport, rpcServer: RPCServer);
     /**
      * Subscribes the client to one or more documents to receive real-time updates.
      * @param connectionId - The ID of the connection making the request
      * @param params - The subscription parameters
      * @param params.ids - Document ID or IDs to subscribe to
      */
-    subscribe(connectionId: string, params: {
+    subscribe(params: {
         ids: string | string[];
-    }): Promise<string[]>;
+    }, ctx?: AuthContext): Promise<string[]>;
     /**
      * Unsubscribes the client from one or more documents.
      * @param connectionId - The ID of the connection making the request
      * @param params - The unsubscription parameters
      * @param params.ids - Document ID or IDs to unsubscribe from
      */
-    unsubscribe(connectionId: string, params: {
+    unsubscribe(params: {
         ids: string | string[];
-    }): Promise<string[]>;
-    /**
-     * Gets the latest state (content and revision) of a document.
-     * @param _connectionId - The ID of the connection making the request
-     * @param params - The document parameters
-     * @param params.docId - The ID of the document
-     * @param params.atRev - Optional revision number to get document state at
-     */
-    getDoc(_connectionId: string, params: {
-        docId: string;
-        atRev?: number;
-    }): Promise<import("../../types.js").PatchesSnapshot<any>>;
-    /**
-     * Gets changes that occurred for a document after a specific revision number.
-     * @param _connectionId - The ID of the connection making the request
-     * @param params - The change request parameters
-     * @param params.docId - The ID of the document
-     * @param params.rev - The revision number after which to fetch changes
-     */
-    getChangesSince(_connectionId: string, params: {
-        docId: string;
-        rev: number;
-    }): Promise<Change[]>;
-    /**
-     * Applies a set of client-generated changes to a document on the server.
-     * @param connectionId - The ID of the connection making the request
-     * @param params - The change parameters
-     * @param params.docId - The ID of the document
-     * @param params.changes - An array of changes to apply
-     */
-    commitChanges(connectionId: string, params: {
-        docId: string;
-        changes: Change[];
-    }): Promise<Change[]>;
-    /**
-     * Deletes a document on the server.
-     * @param connectionId - The ID of the connection making the request
-     * @param params - The deletion parameters
-     * @param params.docId - The ID of the document to delete
-     */
-    deleteDoc(connectionId: string, params: {
-        docId: string;
-    }): Promise<void>;
-    listVersions(connectionId: string, params: {
-        docId: string;
-        options?: ListVersionsOptions;
-    }): Promise<import("../../types.js").VersionMetadata[]>;
-    createVersion(connectionId: string, params: {
-        docId: string;
-        metadata: EditableVersionMetadata;
-    }): Promise<string>;
-    updateVersion(connectionId: string, params: {
-        docId: string;
-        versionId: string;
-        metadata: EditableVersionMetadata;
-    }): Promise<void>;
-    getStateAtVersion(connectionId: string, params: {
-        docId: string;
-        versionId: string;
-    }): Promise<any>;
-    getChangesForVersion(connectionId: string, params: {
-        docId: string;
-        versionId: string;
-    }): Promise<Change[]>;
-    listServerChanges(connectionId: string, params: {
-        docId: string;
-        options?: {
-            limit?: number;
-            startAfterRev?: number;
-            endBeforeRev?: number;
-            reverse?: boolean;
-        };
-    }): Promise<Change[]>;
-    listBranches(connectionId: string, params: {
-        docId: string;
-    }): Promise<import("../../types.js").Branch[]>;
-    createBranch(connectionId: string, params: {
-        docId: string;
-        rev: number;
-        metadata?: EditableVersionMetadata;
-    }): Promise<string>;
-    closeBranch(connectionId: string, params: {
-        branchId: string;
-    }): Promise<void>;
-    mergeBranch(connectionId: string, params: {
-        branchId: string;
-    }): Promise<Change[]>;
+    }, ctx?: AuthContext): Promise<string[]>;
 }

package/dist/net/websocket/WebSocketServer.js

@@ -1,84 +1,48 @@
-import { JSONRPCServer } from '../protocol/JSONRPCServer.js';
 import { allowAll } from './AuthorizationProvider.js';
+/**
+ * High-level client for the Patches real-time collaboration service.
+ * This class provides document subscription, patch notification handling,
+ * versioning, and other OT-specific functionality over a WebSocket connection.
+ */
 export class WebSocketServer {
     /**
      * Creates a new Patches WebSocket client instance.
+     *
      * @param transport - The transport layer implementation that will be used for sending/receiving messages
-     * @param patches - The patches server instance to handle document operations
-     * @param auth - (Optional) Authorization provider implementation. Defaults to a permissive provider.
      */
-    constructor({ transport, patches, history, branches, auth = allowAll }) {
+    constructor(transport, rpcServer) {
         this.transport = transport;
-        this.rpc = new JSONRPCServer(this.transport);
-        this.patches = patches;
-        this.history = history;
-        this.branches = branches;
-        this.auth = auth;
+        const { rpc, auth } = rpcServer;
+        this.auth = auth || allowAll;
         // Subscription operations
-        this.rpc.registerMethod('subscribe', this.subscribe.bind(this));
-        this.rpc.registerMethod('unsubscribe', this.unsubscribe.bind(this));
-        // Document operations
-        this.rpc.registerMethod('getDoc', this.getDoc.bind(this));
-        this.rpc.registerMethod('getChangesSince', this.getChangesSince.bind(this));
-        this.rpc.registerMethod('commitChanges', this.commitChanges.bind(this));
-        this.rpc.registerMethod('deleteDoc', this.deleteDoc.bind(this));
-        // History manager operations (if provided)
-        if (this.history) {
-            this.rpc.registerMethod('listVersions', this.listVersions.bind(this));
-            this.rpc.registerMethod('createVersion', this.createVersion.bind(this));
-            this.rpc.registerMethod('updateVersion', this.updateVersion.bind(this));
-            this.rpc.registerMethod('getVersionState', this.getStateAtVersion.bind(this));
-            this.rpc.registerMethod('getVersionChanges', this.getChangesForVersion.bind(this));
-            this.rpc.registerMethod('listServerChanges', this.listServerChanges.bind(this));
-        }
-        // Branch manager operations (if provided)
-        if (this.branches) {
-            this.rpc.registerMethod('listBranches', this.listBranches.bind(this));
-            this.rpc.registerMethod('createBranch', this.createBranch.bind(this));
-            this.rpc.registerMethod('closeBranch', this.closeBranch.bind(this));
-            this.rpc.registerMethod('mergeBranch', this.mergeBranch.bind(this));
-        }
-    }
-    // ---------------------------------------------------------------------------
-    // Authorization helpers
-    // ---------------------------------------------------------------------------
-    async assertAccess(connectionId, docId, kind, method, params) {
-        const ok = await this.auth.canAccess(connectionId, docId, kind, method, params);
-        if (!ok) {
-            throw new Error(`${kind.toUpperCase()}_FORBIDDEN:${docId}`);
-        }
-    }
-    assertRead(connectionId, docId, method, params) {
-        return this.assertAccess(connectionId, docId, 'read', method, params);
-    }
-    assertWrite(connectionId, docId, method, params) {
-        return this.assertAccess(connectionId, docId, 'write', method, params);
-    }
-    assertHistoryEnabled() {
-        if (!this.history) {
-            throw new Error('History is not enabled');
-        }
-    }
-    assertBranchingEnabled() {
-        if (!this.branches) {
-            throw new Error('Branching is not enabled');
-        }
+        rpc.registerMethod('subscribe', this.subscribe.bind(this));
+        rpc.registerMethod('unsubscribe', this.unsubscribe.bind(this));
+        rpc.onNotify(async (msg) => {
+            if (!msg.params?.docId)
+                return;
+            const { docId } = msg.params;
+            const msgString = JSON.stringify(msg);
+            const clientIds = await this.transport.listSubscriptions(docId);
+            clientIds.forEach(clientId => {
+                this.transport.send(clientId, msgString);
+            });
+        });
     }
-    // --- Patches API Methods ---
-    // === Subscription Operations ===
     /**
      * Subscribes the client to one or more documents to receive real-time updates.
      * @param connectionId - The ID of the connection making the request
      * @param params - The subscription parameters
      * @param params.ids - Document ID or IDs to subscribe to
      */
-    async subscribe(connectionId, params) {
+    async subscribe(params, ctx) {
+        if (!ctx?.clientId)
+            return [];
         const { ids } = params;
         const allIds = Array.isArray(ids) ? ids : [ids];
         const allowed = [];
         await Promise.all(allIds.map(async (id) => {
             try {
-                if (await this.auth.canAccess(connectionId, id, 'read', 'subscribe', params)) {
+                if (await this.auth.canAccess(ctx, id, 'read', 'subscribe', params)) {
                     allowed.push(id);
                 }
             }
@@ -89,9 +53,7 @@ export class WebSocketServer {
         if (allowed.length === 0) {
             return [];
         }
-        // retain original input shape for call but we only pass allowed
-        const input = Array.isArray(ids) ? allowed : allowed[0];
-        return this.patches.subscribe(connectionId, input);
+        return this.transport.addSubscription(ctx.clientId, allowed);
     }
     /**
      * Unsubscribes the client from one or more documents.
@@ -99,136 +61,13 @@ export class WebSocketServer {
      * @param params - The unsubscription parameters
      * @param params.ids - Document ID or IDs to unsubscribe from
      */
-    async unsubscribe(connectionId, params) {
+    async unsubscribe(params, ctx) {
+        if (!ctx?.clientId)
+            return [];
         const { ids } = params;
         // We deliberately do **not** enforce authorization here –
         // removing a subscription doesn't leak information and helps
         // clean up server-side state if a client has lost access mid-session.
-        return this.patches.unsubscribe(connectionId, ids);
-    }
-    // === Document Operations ===
-    /**
-     * Gets the latest state (content and revision) of a document.
-     * @param _connectionId - The ID of the connection making the request
-     * @param params - The document parameters
-     * @param params.docId - The ID of the document
-     * @param params.atRev - Optional revision number to get document state at
-     */
-    async getDoc(_connectionId, params) {
-        const { docId, atRev } = params;
-        await this.assertRead(_connectionId, docId, 'getDoc', params);
-        return this.patches.getDoc(docId, atRev);
-    }
-    /**
-     * Gets changes that occurred for a document after a specific revision number.
-     * @param _connectionId - The ID of the connection making the request
-     * @param params - The change request parameters
-     * @param params.docId - The ID of the document
-     * @param params.rev - The revision number after which to fetch changes
-     */
-    async getChangesSince(_connectionId, params) {
-        const { docId, rev } = params;
-        await this.assertRead(_connectionId, docId, 'getChangesSince', params);
-        return this.patches.getChangesSince(docId, rev);
-    }
-    /**
-     * Applies a set of client-generated changes to a document on the server.
-     * @param connectionId - The ID of the connection making the request
-     * @param params - The change parameters
-     * @param params.docId - The ID of the document
-     * @param params.changes - An array of changes to apply
-     */
-    async commitChanges(connectionId, params) {
-        const { docId, changes } = params;
-        await this.assertWrite(connectionId, docId, 'commitChanges', params);
-        const [priorChanges, newChanges] = await this.patches.commitChanges(docId, changes);
-        // Notify other clients that the new changes have been committed
-        const connectionIds = this.transport.getConnectionIds().filter(id => id !== connectionId);
-        if (connectionIds.length > 0) {
-            this.rpc.notify(connectionIds, 'changesCommitted', { docId, changes: newChanges });
-        }
-        return [...priorChanges, ...newChanges];
-    }
-    /**
-     * Deletes a document on the server.
-     * @param connectionId - The ID of the connection making the request
-     * @param params - The deletion parameters
-     * @param params.docId - The ID of the document to delete
-     */
-    async deleteDoc(connectionId, params) {
-        const { docId } = params;
-        await this.assertWrite(connectionId, docId, 'deleteDoc', params);
-        await this.patches.deleteDoc(docId);
-        // Notify other clients that the document has been deleted
-        const connectionIds = this.transport.getConnectionIds().filter(id => id !== connectionId);
-        if (connectionIds.length > 0) {
-            this.rpc.notify(connectionIds, 'docDeleted', { docId });
-        }
-    }
-    // ---------------------------------------------------------------------------
-    // History Manager wrappers
-    // ---------------------------------------------------------------------------
-    async listVersions(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, options } = params;
-        await this.assertRead(connectionId, docId, 'listVersions', params);
-        return this.history.listVersions(docId, options ?? {});
-    }
-    async createVersion(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, metadata } = params;
-        await this.assertWrite(connectionId, docId, 'createVersion', params);
-        return this.history.createVersion(docId, metadata);
-    }
-    async updateVersion(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, versionId, metadata } = params;
-        await this.assertWrite(connectionId, docId, 'updateVersion', params);
-        return this.history.updateVersion(docId, versionId, metadata);
-    }
-    async getStateAtVersion(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, versionId } = params;
-        await this.assertRead(connectionId, docId, 'getStateAtVersion', params);
-        return this.history.getStateAtVersion(docId, versionId);
-    }
-    async getChangesForVersion(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, versionId } = params;
-        await this.assertRead(connectionId, docId, 'getChangesForVersion', params);
-        return this.history.getChangesForVersion(docId, versionId);
-    }
-    async listServerChanges(connectionId, params) {
-        this.assertHistoryEnabled();
-        const { docId, options } = params;
-        await this.assertRead(connectionId, docId, 'listServerChanges', params);
-        return this.history.listServerChanges(docId, options ?? {});
-    }
-    // ---------------------------------------------------------------------------
-    // Branch Manager wrappers
-    // ---------------------------------------------------------------------------
-    async listBranches(connectionId, params) {
-        this.assertBranchingEnabled();
-        const { docId } = params;
-        await this.assertRead(connectionId, docId, 'listBranches', params);
-        return this.branches.listBranches(docId);
-    }
-    async createBranch(connectionId, params) {
-        this.assertBranchingEnabled();
-        const { docId, rev, metadata } = params;
-        await this.assertWrite(connectionId, docId, 'createBranch', params);
-        return this.branches.createBranch(docId, rev, metadata);
-    }
-    async closeBranch(connectionId, params) {
-        this.assertBranchingEnabled();
-        const { branchId } = params;
-        await this.assertWrite(connectionId, branchId, 'closeBranch', params);
-        return this.branches.closeBranch(branchId, 'closed');
-    }
-    async mergeBranch(connectionId, params) {
-        this.assertBranchingEnabled();
-        const { branchId } = params;
-        await this.assertWrite(connectionId, branchId, 'mergeBranch', params);
-        return this.branches.mergeBranch(branchId);
+        return this.transport.removeSubscription(ctx?.clientId, Array.isArray(ids) ? ids : [ids]);
     }
 }

package/dist/server/PatchesServer.d.ts

@@ -19,21 +19,11 @@ export interface PatchesServerOptions {
 export declare class PatchesServer {
     readonly store: PatchesStoreBackend;
     private readonly sessionTimeoutMillis;
+    /** Notifies listeners whenever a batch of changes is *successfully* committed. */
+    readonly onChangesCommitted: import("../event-signal.js").Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
+    /** Notifies listeners when a document is deleted. */
+    readonly onDocDeleted: import("../event-signal.js").Signal<(docId: string, originClientId?: string) => void>;
     constructor(store: PatchesStoreBackend, options?: PatchesServerOptions);
-    /**
-     * Subscribes the connected client to one or more documents.
-     * @param clientId - The ID of the client.
-     * @param ids Document ID(s) to subscribe to.
-     * @returns A list of document IDs the client is now successfully subscribed to.
-     */
-    subscribe(clientId: string, ids: string | string[]): Promise<string[]>;
-    /**
-     * Unsubscribes the connected client from one or more documents.
-     * @param clientId - The ID of the client.
-     * @param ids Document ID(s) to unsubscribe from.
-     * @returns A list of document IDs the client is now successfully unsubscribed from.
-     */
-    unsubscribe(clientId: string, ids: string | string[]): Promise<string[]>;
     /**
      * Get the latest version of a document and changes since the last version.
      * @param docId - The ID of the document.
@@ -51,16 +41,18 @@ export declare class PatchesServer {
      * Commits a set of changes to a document, applying operational transformation as needed.
      * @param docId - The ID of the document.
      * @param changes - The changes to commit.
+     * @param originClientId - The ID of the client that initiated the commit.
      * @returns A tuple of [committedChanges, transformedChanges] where:
      *   - committedChanges: Changes that were already committed to the server after the client's base revision
      *   - transformedChanges: The client's changes after being transformed against concurrent changes
      */
-    commitChanges(docId: string, changes: Change[]): Promise<[Change[], Change[]]>;
+    commitChanges(docId: string, changes: Change[], originClientId?: string): Promise<[Change[], Change[]]>;
     /**
      * Deletes a document.
      * @param docId The document ID.
+     * @param originClientId - The ID of the client that initiated the delete operation.
      */
-    deleteDoc(docId: string): Promise<void>;
+    deleteDoc(docId: string, originClientId?: string): Promise<void>;
     /**
      * Create a new named version snapshot of a document's current state.
      * @param docId The document ID.

package/dist/server/PatchesServer.js

@@ -1,4 +1,5 @@
 import { createId } from 'crypto-id';
+import { signal } from '../event-signal.js';
 import { applyPatch } from '../json-patch/applyPatch.js';
 import { transformPatch } from '../json-patch/transformPatch.js';
 import { applyChanges } from '../utils.js';
@@ -10,29 +11,12 @@ import { applyChanges } from '../utils.js';
 export class PatchesServer {
     constructor(store, options = {}) {
         this.store = store;
+        /** Notifies listeners whenever a batch of changes is *successfully* committed. */
+        this.onChangesCommitted = signal();
+        /** Notifies listeners when a document is deleted. */
+        this.onDocDeleted = signal();
         this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1000;
     }
-    // --- Patches API Methods ---
-    // === Subscription Operations ===
-    /**
-     * Subscribes the connected client to one or more documents.
-     * @param clientId - The ID of the client.
-     * @param ids Document ID(s) to subscribe to.
-     * @returns A list of document IDs the client is now successfully subscribed to.
-     */
-    subscribe(clientId, ids) {
-        return this.store.addSubscription(clientId, Array.isArray(ids) ? ids : [ids]);
-    }
-    /**
-     * Unsubscribes the connected client from one or more documents.
-     * @param clientId - The ID of the client.
-     * @param ids Document ID(s) to unsubscribe from.
-     * @returns A list of document IDs the client is now successfully unsubscribed from.
-     */
-    unsubscribe(clientId, ids) {
-        return this.store.removeSubscription(clientId, Array.isArray(ids) ? ids : [ids]);
-    }
-    // === Document Operations ===
     /**
      * Get the latest version of a document and changes since the last version.
      * @param docId - The ID of the document.
@@ -54,11 +38,12 @@ export class PatchesServer {
      * Commits a set of changes to a document, applying operational transformation as needed.
      * @param docId - The ID of the document.
      * @param changes - The changes to commit.
+     * @param originClientId - The ID of the client that initiated the commit.
      * @returns A tuple of [committedChanges, transformedChanges] where:
      *   - committedChanges: Changes that were already committed to the server after the client's base revision
      *   - transformedChanges: The client's changes after being transformed against concurrent changes
      */
-    async commitChanges(docId, changes) {
+    async commitChanges(docId, changes, originClientId) {
         if (changes.length === 0) {
             return [[], []];
         }
@@ -142,15 +127,21 @@ export class PatchesServer {
         if (transformedChanges.length > 0) {
             await this.store.saveChanges(docId, transformedChanges);
         }
+        // Fire event for realtime transports (WebSocket, etc.)
+        if (transformedChanges.length > 0) {
+            await this.onChangesCommitted.emit(docId, transformedChanges, originClientId);
+        }
         // Return committed changes and newly transformed changes separately
         return [committedChanges, transformedChanges];
     }
     /**
      * Deletes a document.
      * @param docId The document ID.
+     * @param originClientId - The ID of the client that initiated the delete operation.
      */
-    deleteDoc(docId) {
-        return this.store.deleteDoc(docId);
+    async deleteDoc(docId, originClientId) {
+        await this.store.deleteDoc(docId);
+        await this.onDocDeleted.emit(docId, originClientId);
     }
     // === Version Operations ===
     /**

package/dist/server/types.d.ts

@@ -4,10 +4,6 @@ import type { Branch, Change, EditableVersionMetadata, ListChangesOptions, ListV
  * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
  */
 export interface PatchesStoreBackend {
-    /** Adds a subscription for a client to one or more documents. */
-    addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
-    /** Removes a subscription for a client from one or more documents. */
-    removeSubscription(clientId: string, docIds: string[]): Promise<string[]>;
     /** Saves a batch of committed server changes. */
     saveChanges(docId: string, changes: Change[]): Promise<void>;
     /** Lists committed server changes based on revision numbers. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {