@dabble/patches 0.2.14 → 0.2.16

package/dist/client/PatchesHistoryClient.d.ts

@@ -1,18 +1,11 @@
+import type { PatchesAPI } from '../net/protocol/types.js';
 import type { Change, ListVersionsOptions, VersionMetadata } from '../types.js';
-/**
- * Transport interface for fetching history data (WebSocket, REST, etc.)
- */
-export interface HistoryTransport {
-    listVersions(docId: string, options?: ListVersionsOptions): Promise<VersionMetadata[]>;
-    getVersionState(docId: string, versionId: string): Promise<any>;
-    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
-}
 /**
  * Client-side history/scrubbing interface for a document.
  * Read-only: allows listing versions, loading states/changes, and scrubbing.
  */
 export declare class PatchesHistoryClient<T = any> {
-    private readonly transport;
+    private readonly api;
     /** Document ID */
     readonly id: string;
     /** Event signal for versions changes */
@@ -22,13 +15,17 @@ export declare class PatchesHistoryClient<T = any> {
     private _versions;
     private _state;
     private cache;
-    constructor(id: string, transport: HistoryTransport);
+    constructor(id: string, api: PatchesAPI);
     /** List of loaded versions */
     get versions(): VersionMetadata[];
     /** Current state (for scrubbing) */
     get state(): any;
     /** List version metadata for this document (with options) */
     listVersions(options?: ListVersionsOptions): Promise<VersionMetadata[]>;
+    /** Create a new named version snapshot of the document's current state. */
+    createVersion(name: string): Promise<string>;
+    /** Update the name of a specific version. */
+    updateVersion(versionId: string, updates: Pick<VersionMetadata, 'name'>): Promise<void>;
     /** Load the state for a specific version */
     getStateAtVersion(versionId: string): Promise<any>;
     /** Load the changes for a specific version */

package/dist/client/PatchesHistoryClient.js

@@ -36,8 +36,8 @@ class LRUCache {
  * Read-only: allows listing versions, loading states/changes, and scrubbing.
  */
 export class PatchesHistoryClient {
-    constructor(id, transport) {
-        this.transport = transport;
+    constructor(id, api) {
+        this.api = api;
         /** Event signal for versions changes */
         this.onVersionsChange = signal();
         /** Event signal for state changes */
@@ -57,15 +57,26 @@ export class PatchesHistoryClient {
     }
     /** List version metadata for this document (with options) */
     async listVersions(options) {
-        this._versions = await this.transport.listVersions(this.id, options);
+        this._versions = await this.api.listVersions(this.id, options);
         this.onVersionsChange.emit(this._versions);
         return this._versions;
     }
+    /** Create a new named version snapshot of the document's current state. */
+    async createVersion(name) {
+        const versionId = await this.api.createVersion(this.id, name);
+        await this.listVersions(); // Refresh the list of versions
+        return versionId;
+    }
+    /** Update the name of a specific version. */
+    async updateVersion(versionId, updates) {
+        await this.api.updateVersion(this.id, versionId, updates);
+        await this.listVersions(); // Refresh the list of versions
+    }
     /** Load the state for a specific version */
     async getStateAtVersion(versionId) {
         let data = this.cache.get(versionId);
         if (!data || data.state === undefined) {
-            const state = await this.transport.getVersionState(this.id, versionId);
+            const { state } = await this.api.getVersionState(this.id, versionId);
             data = { ...data, state };
             this.cache.set(versionId, data);
         }
@@ -77,7 +88,7 @@ export class PatchesHistoryClient {
     async getChangesForVersion(versionId) {
         let data = this.cache.get(versionId);
         if (!data || data.changes === undefined) {
-            const changes = await this.transport.getVersionChanges(this.id, versionId);
+            const changes = await this.api.getVersionChanges(this.id, versionId);
             data = { ...data, changes };
             this.cache.set(versionId, data);
         }

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

@@ -1,5 +1,5 @@
 import { type SignalSubscriber, type Unsubscriber } from '../../event-signal.js';
-import type { Transport } from './types.js';
+import type { ClientTransport } from './types.js';
 /**
  * Implementation of a JSON-RPC 2.0 client that communicates over a provided transport layer.
  * This client handles sending requests, notifications, and processing responses from a server.
@@ -15,7 +15,7 @@ export declare class JSONRPCClient {
      *
      * @param transport - The transport layer implementation that will be used for sending/receiving messages
      */
-    constructor(transport: Transport);
+    constructor(transport: ClientTransport);
     /**
      * Sends a JSON-RPC request to the server and returns a promise for the response.
      *

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

@@ -0,0 +1,79 @@
+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;
+/**
+ * Lightweight JSON-RPC 2.0 server adapter for {@link PatchesServer}.
+ *
+ * The class is intentionally transport-agnostic: it only needs an object that
+ * fulfils the {@link Transport} contract (i.e. something that can exchange
+ * string messages and notify when one arrives).  This makes it suitable for
+ * WebSocket, TCP, or even `postMessage` usage.
+ *
+ * A new instance is typically created per connected client.  You therefore
+ * pass in:
+ *   • the {@link Transport} that represents this client connection
+ *   • a shared (singleton) {@link PatchesServer}
+ *   • the unique `clientId` that identifies the connection in subscription
+ *     calls.  How you generate that ID (auth token, random GUID, etc.) is left
+ *     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);
+    /**
+     * Registers a JSON-RPC method.
+     *
+     * @param method   Fully-qualified method name (e.g. "patches.subscribe").
+     * @param handler  Function that performs the work and returns the result.
+     */
+    registerMethod<TParams = any, TResult = any>(method: string, handler: MessageHandler<TParams, TResult>): void;
+    /**
+     * Subscribes to server-sent notifications for a specific method.
+     *
+     * @param method - The notification method name to subscribe to
+     * @param handler - The callback function that will be invoked when notifications are received
+     * @returns A function that can be called to unsubscribe from the notifications
+     * @template T - The type of the handler function
+     */
+    on<T extends ConnectionSignalSubscriber = ConnectionSignalSubscriber>(method: string, handler: T): Unsubscriber;
+    /**
+     * 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>;
+    /**
+     * Handles incoming JSON-RPC notifications from the client.
+     * @param connectionId - The WebSocket transport object.
+     * @param note - The JSON-RPC notification object.
+     */
+    protected _handleNotification(connectionId: string, note: Notification): Promise<void>;
+    /**
+     * Maps JSON-RPC method names to {@link PatchesServer} calls.
+     * @param connectionId - The WebSocket transport object.
+     * @param method - The JSON-RPC method name.
+     * @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;
+}

package/dist/net/protocol/JSONRPCServer.js

@@ -0,0 +1,153 @@
+import { signal } from '../../event-signal.js';
+import { PatchesServer } from '../../server/PatchesServer.js';
+/**
+ * Lightweight JSON-RPC 2.0 server adapter for {@link PatchesServer}.
+ *
+ * The class is intentionally transport-agnostic: it only needs an object that
+ * fulfils the {@link Transport} contract (i.e. something that can exchange
+ * string messages and notify when one arrives).  This makes it suitable for
+ * WebSocket, TCP, or even `postMessage` usage.
+ *
+ * A new instance is typically created per connected client.  You therefore
+ * pass in:
+ *   • the {@link Transport} that represents this client connection
+ *   • a shared (singleton) {@link PatchesServer}
+ *   • the unique `clientId` that identifies the connection in subscription
+ *     calls.  How you generate that ID (auth token, random GUID, etc.) is left
+ *     to the host application.
+ */
+export class JSONRPCServer {
+    constructor(transport) {
+        this.transport = transport;
+        /** 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));
+    }
+    // -------------------------------------------------------------------------
+    // Registration API
+    // -------------------------------------------------------------------------
+    /**
+     * Registers a JSON-RPC method.
+     *
+     * @param method   Fully-qualified method name (e.g. "patches.subscribe").
+     * @param handler  Function that performs the work and returns the result.
+     */
+    registerMethod(method, handler) {
+        if (this.handlers.has(method)) {
+            throw new Error(`A handler for method '${method}' is already registered.`);
+        }
+        this.handlers.set(method, handler);
+    }
+    // -------------------------------------------------------------------------
+    // Public helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribes to server-sent notifications for a specific method.
+     *
+     * @param method - The notification method name to subscribe to
+     * @param handler - The callback function that will be invoked when notifications are received
+     * @returns A function that can be called to unsubscribe from the notifications
+     * @template T - The type of the handler function
+     */
+    on(method, handler) {
+        let thisSignal = this.notificationSignals.get(method);
+        if (!thisSignal) {
+            thisSignal = signal();
+            this.notificationSignals.set(method, thisSignal);
+        }
+        return thisSignal(handler);
+    }
+    /**
+     * Sends a JSON-RPC notification (no `id`, therefore no response expected) to
+     * the connected client.
+     */
+    notify(connectionIds, method, params) {
+        const msg = { jsonrpc: '2.0', method, params };
+        const msgStr = JSON.stringify(msg);
+        connectionIds.forEach(id => this.transport.send(id, msgStr));
+    }
+    /**
+     * Handles incoming messages from the client.
+     * @param connectionId - The WebSocket transport object.
+     * @param raw - The raw message string.
+     */
+    async _onMessage(connectionId, raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (err) {
+            this._sendError(connectionId, null, -32700, 'Parse error', err);
+            return;
+        }
+        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);
+            }
+            else {
+                await this._handleNotification(connectionId, message);
+            }
+        }
+        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);
+        }
+    }
+    /**
+     * Maps JSON-RPC method names to {@link PatchesServer} calls.
+     * @param connectionId - The WebSocket transport object.
+     * @param method - The JSON-RPC method name.
+     * @param params - The JSON-RPC parameters.
+     * @returns The result of the {@link PatchesServer} call.
+     */
+    async _dispatch(connectionId, method, params) {
+        const handler = this.handlers.get(method);
+        if (!handler) {
+            throw new Error(`Unknown method '${method}'.`);
+        }
+        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));
+    }
+}

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

@@ -1,4 +1,5 @@
-import type { Change, PatchesSnapshot, PatchesState, VersionMetadata } from '../../types';
+import type { Unsubscriber } from '../../event-signal.js';
+import type { Change, ListVersionsOptions, PatchesSnapshot, PatchesState, VersionMetadata } from '../../types';
 /**
  * Represents the possible states of a network transport connection.
  * - 'connecting': Connection is being established
@@ -8,35 +9,36 @@ import type { Change, PatchesSnapshot, PatchesState, VersionMetadata } from '../
  */
 export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';
 /**
- * Interface defining the core functionality of a transport layer.
- * Transport implementations provide a communication channel between client and server,
- * abstracting the underlying protocol details (WebSocket, WebRTC, etc.).
+ * Minimal contract that the JSON-RPC layer (and therefore Patches core) relies on.
+ * A transport only needs the ability to **send** raw strings and **deliver** raw
+ * strings it receives from the other side.
+ *
+ * Anything beyond that (connect/disconnect lifecycle, connection state, etc.) is
+ * not needed or handled by Patches and so is not defined here.
  */
-export interface Transport {
+export interface ClientTransport {
     /**
-     * Establishes the connection for this transport.
-     * @returns A promise that resolves when the connection is established
+     * Sends a raw, already-encoded message over the wire.
      */
-    connect(): Promise<void>;
+    send(raw: string): void | Promise<void>;
     /**
-     * Terminates the connection for this transport.
+     * Subscribes to incoming raw messages. Returns an {@link Unsubscriber} so the
+     * caller can remove the handler if it no longer cares about incoming data.
      */
-    disconnect(): void;
-    /**
-     * Sends data through this transport.
-     * @param data - The string data to send
-     */
-    send(data: string): void;
-    /**
-     * Registers a handler for incoming messages.
-     * @param handler - Function that will be called when a message is received
-     */
-    onMessage(handler: (data: string) => void): void;
-    /**
-     * Registers a handler for connection state changes.
-     * @param handler - Function that will be called when the connection state changes
-     */
-    onStateChange(handler: (state: ConnectionState) => void): void;
+    onMessage(cb: (raw: string) => void): Unsubscriber;
+}
+/**
+ * Minimal contract for server-side transports that can have **multiple** logical peers.
+ * Each message must indicate the **from / to** connection. Any additional lifecycle
+ * management (upgrade, close, etc.) stays inside the concrete adapter.
+ */
+export interface ServerTransport {
+    /** Get a list of all active connection IDs */
+    getConnectionIds(): string[];
+    /** Send a raw JSON-RPC string to a specific connection */
+    send(toConnectionId: string, raw: string): void | Promise<void>;
+    /** Subscribe to incoming raw frames from any client */
+    onMessage(cb: (fromConnectionId: string, raw: string) => void): Unsubscriber;
 }
 /**
  * Represents a JSON-RPC 2.0 request object.
@@ -117,13 +119,13 @@ export interface PatchesAPI {
     /** Create a new named version snapshot of a document's current state. */
     createVersion(docId: string, name: string): Promise<string>;
     /** List metadata for saved versions of a document. */
-    listVersions(docId: string, options: ListOptions): Promise<VersionMetadata[]>;
+    listVersions(docId: string, options?: ListVersionsOptions): Promise<VersionMetadata[]>;
     /** Get the state snapshot for a specific version ID. */
     getVersionState(docId: string, versionId: string): Promise<PatchesState>;
     /** Get the original Change objects associated with a specific version ID. */
     getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
     /** Update the name of a specific version. */
-    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+    updateVersion(docId: string, versionId: string, updates: Pick<VersionMetadata, 'name'>): Promise<void>;
 }
 export interface PatchesNotificationParams {
     docId: string;

package/dist/net/webrtc/WebRTCTransport.d.ts

@@ -1,12 +1,12 @@
 import Peer from 'simple-peer';
-import { AbstractTransport } from '../AbstractTransport.js';
+import type { ClientTransport } from '../protocol/types.js';
 import type { WebSocketTransport } from '../websocket/WebSocketTransport.js';
 /**
  * WebRTC-based transport implementation that enables direct peer-to-peer communication.
  * Uses a WebSocket transport as a signaling channel to establish WebRTC connections.
  * Once connections are established, data flows directly between peers without going through a server.
  */
-export declare class WebRTCTransport extends AbstractTransport {
+export declare class WebRTCTransport implements ClientTransport {
     private transport;
     private rpc;
     private peers;
@@ -31,7 +31,7 @@ export declare class WebRTCTransport extends AbstractTransport {
      * Signal that emits when the underlying signaling transport's state changes.
      * This is delegated directly from the WebSocketTransport.
      */
-    readonly onStateChange: import("../../event-signal.js").Signal<(state: import("../index.js").ConnectionState) => void>;
+    readonly onStateChange: import("../../event-signal.js").Signal<(state: import("../protocol/types.js").ConnectionState) => void>;
     /**
      * Creates a new WebRTC transport instance.
      * @param transport - The WebSocket transport to use for signaling
@@ -46,7 +46,7 @@ export declare class WebRTCTransport extends AbstractTransport {
      * Gets the current connection state of the underlying signaling transport.
      * @returns The current connection state
      */
-    get state(): import("../index.js").ConnectionState;
+    get state(): import("../protocol/types.js").ConnectionState;
     /**
      * Establishes the connection by connecting to the signaling server.
      * Peer connections will be established automatically after this.

package/dist/net/webrtc/WebRTCTransport.js

@@ -1,19 +1,17 @@
 import Peer from 'simple-peer';
 import { signal } from '../../event-signal.js';
 import { JSONRPCClient } from '../../net/protocol/JSONRPCClient.js';
-import { AbstractTransport } from '../AbstractTransport.js';
 /**
  * WebRTC-based transport implementation that enables direct peer-to-peer communication.
  * Uses a WebSocket transport as a signaling channel to establish WebRTC connections.
  * Once connections are established, data flows directly between peers without going through a server.
  */
-export class WebRTCTransport extends AbstractTransport {
+export class WebRTCTransport {
     /**
      * Creates a new WebRTC transport instance.
      * @param transport - The WebSocket transport to use for signaling
      */
     constructor(transport) {
-        super();
         this.transport = transport;
         this.peers = new Map();
         /**

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

@@ -0,0 +1,37 @@
+/**
+ * Access level requested for an operation.
+ *
+ * "read"  – non-mutating operations (subscribe, getDoc, listVersions, …)
+ * "write" – mutating operations (commitChanges, deleteDoc, …)
+ */
+export type Access = 'read' | 'write';
+/**
+ * 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 {
+    /**
+     * General-purpose hook executed for every JSON-RPC call that targets a
+     * document. Implementations are free to look only at the first three
+     * arguments (connection, docId, kind) or also inspect the method name and
+     * original params for fine-grained rules (e.g. suggestion-only commits,
+     * owner-only deletes, branch permissions, …).
+     *
+     * 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 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>;
+}
+/**
+ * A permissive provider that authorises every action.  Used as the default so
+ * existing callers that don't care about auth continue to work unchanged.
+ */
+export declare const allowAll: AuthorizationProvider;

package/dist/net/websocket/AuthorizationProvider.js

@@ -0,0 +1,7 @@
+/**
+ * A permissive provider that authorises every action.  Used as the default so
+ * existing callers that don't care about auth continue to work unchanged.
+ */
+export const allowAll = {
+    canAccess: () => true,
+};

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

@@ -1,6 +1,6 @@
 import { type Signal } from '../../event-signal.js';
-import type { Change, PatchesSnapshot, VersionMetadata } from '../../types.js';
-import type { ConnectionState, ListOptions, PatchesAPI, PatchesNotificationParams } from '../protocol/types.js';
+import type { Change, ListVersionsOptions, PatchesSnapshot, VersionMetadata } from '../../types.js';
+import type { ConnectionState, PatchesAPI, PatchesNotificationParams } from '../protocol/types.js';
 import { type WebSocketOptions } from './WebSocketTransport.js';
 /**
  * High-level client for the Patches real-time collaboration service.
@@ -81,7 +81,7 @@ export declare class PatchesWebSocket implements PatchesAPI {
      * @param options - Options for filtering or pagination (e.g., limit, offset).
      * @returns A promise resolving with an array of version metadata objects.
      */
-    listVersions(docId: string, options?: ListOptions): Promise<VersionMetadata[]>;
+    listVersions(docId: string, options?: ListVersionsOptions): Promise<VersionMetadata[]>;
     /**
      * Gets the document state snapshot corresponding to a specific version ID.
      * @param docId - The ID of the document.
@@ -103,5 +103,5 @@ export declare class PatchesWebSocket implements PatchesAPI {
      * @param name - The new name for the version.
      * @returns A promise resolving when the update is confirmed.
      */
-    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+    updateVersion(docId: string, versionId: string, updates: Pick<VersionMetadata, 'name'>): Promise<void>;
 }

package/dist/net/websocket/PatchesWebSocket.js

@@ -110,7 +110,7 @@ export class PatchesWebSocket {
      * @param options - Options for filtering or pagination (e.g., limit, offset).
      * @returns A promise resolving with an array of version metadata objects.
      */
-    async listVersions(docId, options = {}) {
+    async listVersions(docId, options) {
         return this.rpc.request('listVersions', { docId, options });
     }
     /**
@@ -138,7 +138,7 @@ export class PatchesWebSocket {
      * @param name - The new name for the version.
      * @returns A promise resolving when the update is confirmed.
      */
-    async updateVersion(docId, versionId, name) {
-        return this.rpc.request('updateVersion', { docId, versionId, name });
+    async updateVersion(docId, versionId, updates) {
+        return this.rpc.request('updateVersion', { docId, versionId, updates });
     }
 }