Improve tui demo

Publish as public package

See merge request GeneralProtocols/xo/sync-client!3

.cspell.json

@@ -0,0 +1,4 @@
+{
+    "version": "0.1",
+    "import": ["@generalprotocols/cspell-dictionary/cspell.json"]
+}

.gitignore

@@ -1,2 +1,4 @@
 /node_modules
 /dist
+/coverage
+/docs

.gitlab-ci.yml

@@ -0,0 +1,3 @@
+# Use the default NPM publishing template for the `@xo-cash/*` packages.
+include:
+    - component: $CI_SERVER_FQDN/GeneralProtocols/xo/pipelines/npm@v1.2.0

.prettierrc.mjs

@@ -0,0 +1,23 @@
+// Prettier configuration aligned with @xo-cash/eslint-config
+export default {
+    // Matches @stylistic/max-len': [ 'warn', 150, ...]
+    printWidth: 150,
+
+    // Matches @stylistic/no-tabs': [ 'error' ]
+    useTabs: false,
+
+    // Matches @stylistic/indent': [ 'error', 4, ...]
+    tabWidth: 4,
+
+    // Matches @stylistic/array-bracket-spacing': [ 'error', 'always', ...]
+    bracketSpacing: true,
+
+    // Matches @stylistic/quotes: ['error', 'single', { avoidEscape: true }], from @chalp/eslint-airbnb/base/stylistic.js
+    singleQuote: true,
+
+    // Matches @stylistic/semi: ['error', 'always'], from @chalp/eslint-airbnb/base/stylistic.js
+    semi: true,
+
+    // Matches @stylistic/arrow-parens: ['error', 'always'], from @chalp/eslint-airbnb/base/stylistic.js
+    arrowParens: 'always',
+};

demo/experimental/encrypted-client-per-resource.ts

@@ -1,8 +1,8 @@
-import { subtle, getRandomValues } from "node:crypto";
+import { subtle, getRandomValues } from 'node:crypto';
-import { fromExtendedJson, toExtendedJson } from "@xo-cash/utils";
+import { fromExtendedJson, toExtendedJson } from '@xo-cash/utils';
-import { sha256, binToBase64, binToHex } from "@bitauth/libauth";
+import { sha256, binToBase64, binToHex } from '@bitauth/libauth';
 
-import { BaseSyncClient, type Resource, type ResourcesRecord } from "../../src/shared/base-client.js";
+import { BaseSyncClient, type Resource, type ResourcesRecord } from '../../source/shared/base-client.js';
 
 type ResourceKey = {
     resourceId: string;
@@ -32,7 +32,7 @@ export class EncryptedClientPerResource<T = unknown> extends BaseSyncClient<T> {
                 this.emit('resource-instance-updated', {
                     ...message,
                     resourceId: resourceKey.resourceId,
-          value: await EncryptedClientPerResource.decrypt(resourceKey.keyMaterial, message.value) as T,
+                    value: (await EncryptedClientPerResource.decrypt(resourceKey.keyMaterial, message.value)) as T,
                 });
             } catch (error) {
                 this.emit('error', error instanceof Error ? error : new Error(String(error)));
@@ -75,17 +75,21 @@ export class EncryptedClientPerResource<T = unknown> extends BaseSyncClient<T> {
      * @returns The resources record with decrypted values, keyed by original resource ID
      */
     private async decryptResources(resources: ResourcesRecord<string>): Promise<ResourcesRecord<T>> {
-    const entries = await Promise.all(Object.entries(resources).map(async ([ hashedResourceId, resource ]) => {
+        const entries = await Promise.all(
+            Object.entries(resources).map(async ([hashedResourceId, resource]) => {
                 const { resourceId, keyMaterial } = this.getResourceKey(hashedResourceId);
 
-      const instances: Resource<T>[] = await Promise.all(resource.instances.map(async (instance) => ({
+                const instances: Resource<T>[] = await Promise.all(
+                    resource.instances.map(async (instance) => ({
                         ...instance,
                         resourceId,
-        value: await EncryptedClientPerResource.decrypt(keyMaterial, instance.value) as T,
+                        value: (await EncryptedClientPerResource.decrypt(keyMaterial, instance.value)) as T,
-      })));
+                    })),
+                );
 
-      return [ resourceId, { ...resource, instances } ] as const;
+                return [resourceId, { ...resource, instances }] as const;
-    }));
+            }),
+        );
 
         return Object.fromEntries(entries);
     }
@@ -107,12 +111,14 @@ export class EncryptedClientPerResource<T = unknown> extends BaseSyncClient<T> {
     }
 
     public async writeMany(resources: Record<string, T>): Promise<ResourcesRecord<T>> {
-    const encryptedEntries = await Promise.all(Object.entries(resources).map(async ([ resourceId, value ]) => {
+        const encryptedEntries = await Promise.all(
+            Object.entries(resources).map(async ([resourceId, value]) => {
                 const hashedResourceId = this.hashResourceId(resourceId);
                 const { keyMaterial } = this.getResourceKey(hashedResourceId);
 
-      return [ hashedResourceId, await EncryptedClientPerResource.encrypt(keyMaterial, value) ] as const;
+                return [hashedResourceId, await EncryptedClientPerResource.encrypt(keyMaterial, value)] as const;
-    }));
+            }),
+        );
 
         const response = await this.client.writeMany(Object.fromEntries(encryptedEntries));
 
@@ -152,7 +158,7 @@ export class EncryptedClientPerResource<T = unknown> extends BaseSyncClient<T> {
         const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, encodedValue);
 
         // Prepend the IV so it can be recovered when decrypting
-    return binToBase64(Buffer.concat([ iv, new Uint8Array(encrypted) ]));
+        return binToBase64(Buffer.concat([iv, new Uint8Array(encrypted)]));
     }
 
     /**

demo/experimental/encrypted-client.ts

@@ -1,8 +1,8 @@
-import { subtle, getRandomValues } from "node:crypto";
+import { subtle, getRandomValues } from 'node:crypto';
-import { fromExtendedJson, toExtendedJson } from "@xo-cash/utils";
+import { fromExtendedJson, toExtendedJson } from '@xo-cash/utils';
-import { sha256, binToBase64 } from "@bitauth/libauth";
+import { sha256, binToBase64 } from '@bitauth/libauth';
 
-import { BaseSyncClient, type ResourcesRecord } from "../../src/shared/base-client.js";
+import { BaseSyncClient, type ResourcesRecord } from '../../source/shared/base-client.js';
 
 /**
  * Encrypts every resource with a single shared key.
@@ -10,7 +10,10 @@ import { BaseSyncClient, type ResourcesRecord } from "../../src/shared/base-clie
 export class EncryptedClient<T = unknown> extends BaseSyncClient<T> {
     private readonly encryptionKey: Uint8Array;
 
-  constructor(private readonly client: BaseSyncClient<string>, encryptionKey: Uint8Array | string) {
+    constructor(
+        private readonly client: BaseSyncClient<string>,
+        encryptionKey: Uint8Array | string,
+    ) {
         super();
 
         // Hash the encryption key into 32 bytes if it is a string
@@ -20,7 +23,7 @@ export class EncryptedClient<T = unknown> extends BaseSyncClient<T> {
             try {
                 this.emit('resource-instance-updated', {
                     ...message,
-          value: await EncryptedClient.decrypt(this.encryptionKey, message.value) as T,
+                    value: (await EncryptedClient.decrypt(this.encryptionKey, message.value)) as T,
                 });
             } catch (error) {
                 this.emit('error', error instanceof Error ? error : new Error(String(error)));
@@ -34,14 +37,18 @@ export class EncryptedClient<T = unknown> extends BaseSyncClient<T> {
      * @returns The resources record with decrypted values
      */
     private async decryptResources(resources: ResourcesRecord<string>): Promise<ResourcesRecord<T>> {
-    const entries = await Promise.all(Object.entries(resources).map(async ([ resourceId, resource ]) => {
+        const entries = await Promise.all(
-      const instances = await Promise.all(resource.instances.map(async (instance) => ({
+            Object.entries(resources).map(async ([resourceId, resource]) => {
+                const instances = await Promise.all(
+                    resource.instances.map(async (instance) => ({
                         ...instance,
-        value: await EncryptedClient.decrypt(this.encryptionKey, instance.value) as T,
+                        value: (await EncryptedClient.decrypt(this.encryptionKey, instance.value)) as T,
-      })));
+                    })),
+                );
 
-      return [ resourceId, { ...resource, instances } ] as const;
+                return [resourceId, { ...resource, instances }] as const;
-    }));
+            }),
+        );
 
         return Object.fromEntries(entries);
     }
@@ -61,9 +68,11 @@ export class EncryptedClient<T = unknown> extends BaseSyncClient<T> {
     }
 
     public async writeMany(resources: Record<string, T>): Promise<ResourcesRecord<T>> {
-    const encryptedEntries = await Promise.all(Object.entries(resources).map(async ([ resourceId, value ]) => {
+        const encryptedEntries = await Promise.all(
-      return [ resourceId, await EncryptedClient.encrypt(this.encryptionKey, value) ] as const;
+            Object.entries(resources).map(async ([resourceId, value]) => {
-    }));
+                return [resourceId, await EncryptedClient.encrypt(this.encryptionKey, value)] as const;
+            }),
+        );
 
         const response = await this.client.writeMany(Object.fromEntries(encryptedEntries));
 
@@ -103,7 +112,7 @@ export class EncryptedClient<T = unknown> extends BaseSyncClient<T> {
         const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, encodedValue);
 
         // Prepend the IV so it can be recovered when decrypting
-    return binToBase64(Buffer.concat([ iv, new Uint8Array(encrypted) ]));
+        return binToBase64(Buffer.concat([iv, new Uint8Array(encrypted)]));
     }
 
     /**

demo/shared.ts

@@ -1,21 +1,23 @@
-import type { BaseSyncClient, ResourcesRecord } from "../src/shared/base-client.js";
+import type { BaseSyncClient, ResourcesRecord } from '../source/shared/base-client.js';
 
 export const writeMany = async (client: BaseSyncClient<{ message: string }>): Promise<ResourcesRecord<{ message: string }>> => {
     // Create a group of resources with changes
-  const resources = Object.fromEntries(Array.from({ length: 10 }, (_, index) => [
+    const resources = Object.fromEntries(
+        Array.from({ length: 10 }, (_, index) => [
             `resource-${index}`,
             {
                 message: `Hello, world! this is the minimal sync client using ${client.constructor.name} ${index}`,
             },
-  ]));
+        ]),
+    );
 
     // Write the resources to the server
     const res = await client.writeMany(resources);
 
     return res;
-}
+};
 
-export const readMany = async (client: BaseSyncClient<{ message: string }>,): Promise<ResourcesRecord<{ message: string }>> => {
+export const readMany = async (client: BaseSyncClient<{ message: string }>): Promise<ResourcesRecord<{ message: string }>> => {
     // Create a list of resource IDs
     const resources = Array.from({ length: 10 }, (_, index) => `resource-${index}`);
 
@@ -23,4 +25,4 @@ export const readMany = async (client: BaseSyncClient<{ message: string }>,): Pr
     const res = await client.readMany(resources);
 
     return res;
-}
+};

demo/suite.ts

@@ -1,16 +1,16 @@
-import { PrivateKey } from "@xo-cash/primitives";
+import { PrivateKey } from '@xo-cash/primitives';
 
 // Core clients
-import type { BaseSyncClient } from "../src/shared/base-client.js";
+import type { BaseSyncClient } from '../source/shared/base-client.js';
-import { SSEClient } from '../src/sse/client.js';
+import { SSEClient } from '../source/sse/client.js';
-import { WsClient } from "../src/ws/client.js";
+import { WsClient } from '../source/ws/client.js';
 
 // Experimental clients
-import { EncryptedClientPerResource } from "./experimental/encrypted-client-per-resource.js";
+import { EncryptedClientPerResource } from './experimental/encrypted-client-per-resource.js';
-import { EncryptedClient } from "./experimental/encrypted-client.js";
+import { EncryptedClient } from './experimental/encrypted-client.js';
 
 // Shared functions
-import { writeMany, readMany } from "./shared.js";
+import { writeMany, readMany } from './shared.js';
 
 const privateKey = PrivateKey.fromString('c440ce6ac5b63ae7bc4af9891b80b7a88ccdeebba5e43246885e9ec56f912ac2');
 
@@ -18,7 +18,9 @@ const clients = {
     sse: new SSEClient<{ message: string }>('https://dev.v2.sync.xo.harvmaster.com', privateKey),
     ws: new WsClient<{ message: string }>('wss://dev.v2.sync.xo.harvmaster.com', privateKey),
     encrypted: new EncryptedClient<{ message: string }>(new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey), 'secret'),
-  encryptedPerResource: new EncryptedClientPerResource<{ message: string }>(new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey)),
+    encryptedPerResource: new EncryptedClientPerResource<{ message: string }>(
+        new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey),
+    ),
 };
 
 // Test the suite for a given client
@@ -34,7 +36,9 @@ const testSuite = async (client: BaseSyncClient<{ message: string }>) => {
     await client.subscribe('test');
 
     // Write a new value to the resource
-  await client.write('test', {'message': 'Hello, world! this is the minimal sync client using ' + client.constructor.name});
+    await client.write('test', {
+        message: 'Hello, world! this is the minimal sync client using ' + client.constructor.name,
+    });
 
     // Read the current value of the resource
     const data = await client.read('test');
@@ -52,7 +56,7 @@ const testSuite = async (client: BaseSyncClient<{ message: string }>) => {
         await client.disconnect();
         process.exit(0);
     });
-}
+};
 
 // Get the clients to test
 const selectClients = (params: string[]): BaseSyncClient<{ message: string }>[] => {
@@ -68,7 +72,7 @@ const selectClients = (params: string[]): BaseSyncClient<{ message: string }>[]
 
     // Return the clients that are known to the clients object
     return names.map((n) => clients[n as keyof typeof clients]);
-}
+};
 
 // Get the params
 const params = process.argv.slice(2);

demo/tui.ts

@@ -1,54 +1,98 @@
-import { PrivateKey } from "@xo-cash/primitives";
+/// <reference types="node" />
+import readline from 'node:readline';
 
-import type { BaseSyncClient } from "../src/shared/base-client.js";
+import { PrivateKey } from '@xo-cash/primitives';
 
-import { SSEClient } from "../src/sse/client.js";
+import type { BaseSyncClient } from '../source/shared/base-client.js';
-import { EncryptedClientPerResource } from "./experimental/encrypted-client-per-resource.js";
+
+import { SSEClient } from '../source/sse/client.js';
+import { EncryptedClientPerResource } from './experimental/encrypted-client-per-resource.js';
 
 const privateKey = PrivateKey.fromString('c440ce6ac5b63ae7bc4af9891b80b7a88ccdeebba5e43246885e9ec56f912ac2');
 
 // Define some formatting helpers
 const formatResourceId = (resourceId: string) => {
     return `\x1b[32m${resourceId}\x1b[0m`;
-}
+};
+
 const formatMessage = (message: string) => {
     return `\x1b[34m${message}\x1b[0m`;
-}
+};
+
 const resetFormatting = () => {
-  return `\x1b[0m`;
+    return '\x1b[0m';
-}
+};
+
+// readline lets us get both whole lines and individual keypresses (for Escape)
+// escapeCodeTimeout: how long to wait after Escape to see if it's part of a key sequence (default 500ms)
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout, escapeCodeTimeout: 0 });
 
 const startTUI = async (client: BaseSyncClient<string>) => {
     // Listen and log out the resource change
     client.on('resource-instance-updated', (message) => {
         // Print the message with colours
-    console.log(`${formatResourceId(message.resourceId)}:${formatResourceId(message.publicKey)} updated: ${formatMessage(message.value)}${resetFormatting()}`);
+        console.log(
+            `${formatResourceId(message.resourceId)}:${formatResourceId(message.publicKey)} updated: ${formatMessage(message.value)}${resetFormatting()}`,
+        );
     });
 
     // Connect to the sync server and subscribe to the resource
     await client.connect();
-  await client.subscribe('encrypted-test');
 
-  // Start the TUI loop
+    const writeResourceLoop = async (resourceId: string) => {
         while (true) {
             // Print the prompt
             process.stdout.write('> ');
 
             // Wait for the user to enter a command
-    const data = await new Promise((resolve) => process.stdin.once('data', resolve));
+            // Resolves with the typed line, or null if Escape was pressed
+            const onKeypress = (_char: string, key: readline.Key) => key?.name === 'escape' && rl.emit('line', null);
+            process.stdin.on('keypress', onKeypress);
+            const line = await new Promise<string | null>((resolve) => rl.once('line', resolve));
+            process.stdin.off('keypress', onKeypress);
 
-    // If the user entered a command, write it to the resource
+            // Escape exits the loop
-    if (data) {
+            if (line === null) return;
-      const message = data.toString().trim();
+
-      await client.write('encrypted-test', message);
+            if (line.trim()) {
+                await client.write(resourceId, line.trim());
             }
         }
-}
+    };
+
+    const selectResource = async () => {
+        while (true) {
+            console.log('Enter a resource:');
+
+            // Print the prompt
+            process.stdout.write('> ');
+
+            // Wait for the user to enter a command
+            const line = await new Promise<string>((resolve) => rl.once('line', resolve));
+            const resourceId = line.trim();
+
+            if (resourceId) {
+                // Subscribe to the resource
+                await client.subscribe(resourceId);
+
+                // Read the current instances
+                const instance = await client.read(resourceId);
+                console.dir(instance, { depth: null });
+
+                // Write to the resource
+                await writeResourceLoop(resourceId);
+            }
+        }
+    };
+
+    // Start the TUI loop
+    await selectResource();
+};
 
 const clients = {
-  'sse': new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey),
+    sse: new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey),
-  'encrypted': new EncryptedClientPerResource<string>(new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey)),
+    encrypted: new EncryptedClientPerResource<string>(new SSEClient<string>('https://dev.v2.sync.xo.harvmaster.com', privateKey)),
-}
+};
 
 const params = process.argv.slice(2);
 const client = params[0] === 'false' ? clients.sse : clients.encrypted;

eslint.config.mjs

@@ -0,0 +1,8 @@
+import baseConfig from '@xo-cash/eslint-config';
+
+export default [
+    {
+        ignores: [ 'coverage/**', 'docs/**', 'demo/**' ],
+    },
+    ...baseConfig,
+];

package.json

@@ -16,8 +16,8 @@
     },
     "exports": {
         ".": {
-      "import": "./dist/src/index.js",
+            "import": "./dist/index.mjs",
-      "require": "./dist/src/index.cjs"
+            "require": "./dist/index.cjs"
         }
     },
     "files": [
@@ -26,6 +26,9 @@
     "keywords": [],
     "author": "GeneralProtocols",
     "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
     "dependencies": {
         "@bitauth/libauth": "^3.0.0",
         "@xo-cash/primitives": "^0.0.2",

readme.md

@@ -1,20 +1,19 @@
 # Installation
 
 ```
-git clone https://git.harvmaster.com/Harvmaster/sync-server-example.git
+git clone hgit@gitlab.com:GeneralProtocols/xo/sync-client.git
-cd sync-server-example
+cd sync-client
 npm ci
 ```
 
 # Running
 
-There are 2 examples in the `src/index.ts` file.
+There are 2 examples in the `demo` folder.
 
-- `testSSE()` - Example using the SSE client
+- The `suite` will run general read/write operations on various clients.
-- `testWS()` - Example using the WebSocket client
+- The `tui` will allow you to write values into the console as well as monitor for updates.
+
+- `npx tsx ./demo/suite.ts` - Optionally, add `sse` | `ws` | `encryped` | `encryptedPerResource` to select a specific implementation to test. Defaults to all clients.
+- `npx tsx ./demo/tui.ts` - Optionally add `false` to use a SSE without encryption. Default is `EncryptedClientPerResource`
 
-To run the examples, you can use the following command:
 
-```
-npm run start
-```

source/index.ts

@@ -0,0 +1,4 @@
+export * from './shared/base-client.ts';
+
+export * from './sse/client.ts';
+export * from './ws/client.ts';

source/shared/base-client.ts

@@ -0,0 +1,266 @@
+import { binToHex, flattenBinArray, secp256k1, sha256 } from '@bitauth/libauth';
+
+import { toExtendedJson, EventEmitter, fromExtendedJson } from '@xo-cash/utils';
+import type { WriteRequest } from '../types.ts';
+import z from 'zod';
+
+export type AuthenticatedRequestHeaders = {
+    'X-Public-Key': string;
+    'X-Timestamp': string;
+    'X-Signature': string;
+};
+
+export type SignedPayload = { publicKey: string; signature: string };
+
+export type XOSyncClientEventMap<T = unknown> = {
+    'connection-updated': 'connected' | 'disconnected';
+    'resource-instance-updated': Resource<T> & {
+        resourceId: string;
+    };
+    'subscriptions-updated': Set<string>;
+    error: Error;
+};
+
+export type Resource<PayloadType = unknown> = z.infer<typeof BaseSyncClient.resourceInstanceSchema> & {
+    value: PayloadType;
+};
+
+export type ResourcesRecord<PayloadType = unknown> = Record<string, { instances: Resource<PayloadType>[] }>;
+
+export abstract class BaseSyncClient<T = unknown> extends EventEmitter<XOSyncClientEventMap<T>> {
+    /**
+     * Connects to the sync server
+     */
+    abstract connect(): Promise<void>;
+
+    /**
+     * Disconnects from the sync server
+     */
+    abstract disconnect(): Promise<void>;
+
+    /**
+     * Sign and write one resource
+     * @param resourceId - The resource ID to write to
+     * @param value - The value to write
+     * @returns The Resource Object with the decoded value
+     */
+    async write(resourceId: string, value: T): Promise<Resource<T>[]> {
+        // Write the resource to the server
+        const response = await this.writeMany({ [resourceId]: value });
+
+        // Get the resource from the response
+        const resource = response[resourceId];
+
+        // If the resource is not found, throw an error
+        if (!resource) {
+            throw new Error(`Resource ${resourceId} not found`);
+        }
+
+        // Return the resource instances
+        return resource.instances;
+    }
+
+    /**
+     * Writes multiple values to resources
+     * @param resources - The resources to write to
+     * @returns The resources with the written values
+     */
+    abstract writeMany(resources: Record<string, T>): Promise<ResourcesRecord<T>>;
+
+    /**
+     * Reads a value from a resource
+     * @param resourceId - The resource ID to read from
+     * @returns The resource with the read value
+     */
+    async read(resourceId: string): Promise<Resource<T>[]> {
+        // Read the resource from the server
+        const response = await this.readMany([ resourceId ]);
+
+        // Get the resource from the response
+        const resource = response[resourceId];
+
+        // If the resource is not found, throw an error
+        if (!resource) {
+            throw new Error(`Resource ${resourceId} not found`);
+        }
+
+        // Return the resource instances
+        return resource.instances;
+    }
+
+    /**
+     * Reads multiple values from resources
+     * @param resourceIds - The resource IDs to read from
+     * @returns The resources with the read values
+     */
+    abstract readMany(resourceIds: string[]): Promise<ResourcesRecord<T>>;
+
+    /**
+     * Subscribes to a resource
+     * @param resourceId - The resource ID to subscribe to
+     */
+    abstract subscribe(resourceId: string): Promise<void>;
+
+    /**
+     * Unsubscribes from a resource
+     * @param resourceId - The resource ID to unsubscribe from
+     */
+    abstract unsubscribe(resourceId: string): Promise<void>;
+
+    /**
+     * Derives the resource private key from the private key and resource ID
+     * @param privateKey - The private key to derive the resource private key from
+     * @param resourceId - The resource ID to derive the resource private key from
+     * @returns The resource private key
+     */
+    static deriveResourcePrivateKey(privateKey: Uint8Array, resourceId: string): Uint8Array {
+        // Convert the resource ID to bytes
+        const resourceIdBytes = new TextEncoder().encode(resourceId);
+
+        // Hash the private key and resource ID
+        return sha256.hash(flattenBinArray([ privateKey, resourceIdBytes ]));
+    }
+
+    /**
+     * Signs a payload with the private key and returns the public key and signature
+     * @param privateKey - The private key to sign the payload with
+     * @param payload - The payload to sign
+     * @returns The public key and signature
+     */
+    static signPayload(privateKey: Uint8Array, payload: string): SignedPayload {
+        // Convert the payload to Binary and hash it
+        const payloadHash = sha256.hash(new TextEncoder().encode(payload));
+
+        // Derive the public key
+        const publicKey = secp256k1.derivePublicKeyCompressed(privateKey);
+
+        // If the public key is a string, throw an error
+        if (typeof publicKey === 'string') {
+            throw new Error('Failed to derive public key');
+        }
+
+        // Sign the payload
+        const signature = secp256k1.signMessageHashDER(privateKey, payloadHash);
+
+        // If the signature is a string, throw an error
+        if (typeof signature === 'string') {
+            throw new Error('Failed to sign message');
+        }
+
+        return {
+            publicKey: binToHex(publicKey),
+            signature: binToHex(signature),
+        };
+    }
+
+    /**
+     * Signs a write request with the private key and returns the write request
+     * @param privateKey - The private key to sign the write request with
+     * @param resourceId - The resource ID to write to
+     * @param value - The value to write
+     * @returns The write request
+     */
+    static signWriteRequest(privateKey: Uint8Array, resourceId: string, value: Uint8Array): WriteRequest {
+        // Derive the resource private key
+        const derivedKey = this.deriveResourcePrivateKey(privateKey, resourceId);
+
+        // Create the payload
+        const timestamp = Date.now();
+        const payload = `${timestamp}:${resourceId}:${toExtendedJson(value)}`;
+
+        // Sign the payload
+        const { publicKey, signature } = this.signPayload(derivedKey, payload);
+
+        return {
+            id: resourceId,
+            value,
+            publicKey,
+            timestamp,
+            signature,
+        };
+    }
+
+    /**
+     * Signs a request with the private key and returns the public key, timestamp, and signature
+     * @param privateKey - The private key to sign the request with
+     * @param path - The path of the request
+     * @param body - The body of the request
+     * @returns The public key, timestamp, and signature
+     */
+    static signRequest(privateKey: Uint8Array, path: string, body: unknown): AuthenticatedRequestHeaders {
+        // Create the payload
+        const timestamp = Date.now();
+
+        // Convert the body to a string if it isn't already a string
+        const bodyStr = typeof body === 'string' ? body : toExtendedJson(body);
+
+        // Create the payload as `Timestamp:Path:Body`
+        const payload = `${timestamp}:${path}:${bodyStr}`;
+
+        // Sign the payload
+        const { publicKey, signature } = this.signPayload(privateKey, payload);
+
+        return {
+            'X-Public-Key': publicKey,
+            'X-Timestamp': timestamp.toString(),
+            'X-Signature': signature,
+        };
+    }
+
+    /**
+     * Decodes the 'blob' field of the Resource Object from the server from a read/write
+     * @param response - The ResourceResponse Object from the server from a read/write
+     * @returns The Resource Object with the decoded value
+     */
+    static decodeResourcesResponse<T = unknown>(response: z.infer<typeof BaseSyncClient.resourcesResponseSchema>): ResourcesRecord<T> {
+        return Object.entries(response.resources).reduce<ResourcesRecord<T>>((acc, [ resourceId, resource ]) => {
+            // Get the instances
+            const instances = resource.instances;
+
+            // Decode the instances
+            const decodedInstances = instances.map((instance) => {
+                return BaseSyncClient.decodeBlobValue<T>(instance);
+            });
+
+            // Add the decoded instances to the accumulator
+            acc[resourceId] = {
+                ...resource,
+                instances: decodedInstances,
+            };
+
+            // Return the accumulator
+            return acc;
+        }, {});
+    }
+
+    static decodeBlobValue<T = unknown>(instance: z.infer<typeof BaseSyncClient.resourceInstanceSchema>): Resource<T> {
+        const decodedBlob = new TextDecoder().decode(instance.blob);
+        const value = fromExtendedJson(decodedBlob) as T;
+
+        return {
+            ...instance,
+            value,
+        };
+    }
+
+    static resourceInstanceSchema = z.object({
+        resourceId: z.string(),
+        blob: z.instanceof(Uint8Array),
+        timestamp: z.number(),
+        publicKey: z.string(),
+        signature: z.string(),
+    });
+
+    static rawResourcesSchema = z.object({
+        instances: z.array(BaseSyncClient.resourceInstanceSchema),
+    });
+
+    static resourcesResponseSchema = z.object({
+        resources: z.record(
+            // Resource ID
+            z.string(),
+            // Resource instances
+            BaseSyncClient.rawResourcesSchema,
+        ),
+    });
+}

source/sse/client.ts

@@ -0,0 +1,263 @@
+import { SSESession, toExtendedJson, fromExtendedJson } from '@xo-cash/utils';
+import type { PrivateKey } from '@xo-cash/primitives';
+
+import { BaseSyncClient, type ResourcesRecord } from '../shared/base-client.ts';
+
+export class SSEClient<PayloadType = unknown> extends BaseSyncClient<PayloadType> {
+    private readonly url: string;
+    public sseSession: SSESession | undefined;
+    private readonly subscriptions: Set<string> = new Set();
+
+    private privateKey: PrivateKey;
+    private textEncoder = new TextEncoder();
+
+    private get subscriptionUrl(): string {
+        return `${this.url}/data/subscribe`;
+    }
+
+    /**
+     * Creates a new SSE client
+     * @param url - The URL of the server
+     * @param privateKey - The private key to use for authentication
+     */
+    constructor(url: string, privateKey: PrivateKey) {
+        super();
+
+        this.url = url;
+        this.privateKey = privateKey;
+
+        // Whenever we get a new subscription, we need to reconnect the session with the new subscriptions in the body
+        // We add a small debounce to this to prevent parallel subscriptions from causing multiple reconnects
+        this.on(
+            'subscriptions-updated',
+            () => {
+                // Nothing awaits this listener, so report failures as an error event instead of an unhandled rejection
+                this.reconnect().catch((error) => this.emit('error', error));
+            },
+            25,
+        );
+    }
+
+    /**
+     * Connects to the server
+     */
+    async connect(): Promise<void> {
+        // The server rejects a subscribe request with no resource IDs, so there is nothing to connect to yet.
+        // subscribe() connects once there is a subscription. read() and write() are plain fetches and don't need a session.
+        if (this.subscriptions.size === 0) {
+            return;
+        }
+
+        this.sseSession ??= this.createSession();
+
+        await this.sseSession.connect();
+    }
+
+    /**
+     * Disconnects from the server
+     */
+    async disconnect(): Promise<void> {
+        this.sseSession?.disconnect();
+    }
+
+    /**
+     * Reconnects to the server
+     */
+    async reconnect(): Promise<void> {
+        // Close the current session. Its subscription list is fixed in the request body, so it can't be reused
+        this.sseSession?.close();
+        this.sseSession = undefined;
+
+        // Connect a new session with the current subscriptions
+        await this.connect();
+    }
+
+    /**
+     * Creates a new SSE session
+     * @returns The SSE session
+     */
+    private createSession(): SSESession {
+        // Build the request body
+        const body = toExtendedJson({ resourceId: [ ...this.subscriptions ] });
+
+        // Create a new SSE session
+        const session = new SSESession(this.subscriptionUrl, {
+            onRequest: async (request): Promise<RequestInit> => {
+                // Get the path from the URL
+                const url = new URL(this.subscriptionUrl);
+                const path = url.pathname;
+
+                // Sign the request body
+                const authHeaders = BaseSyncClient.signRequest(this.privateKey.toBytes(), path, request.body);
+
+                // Initialize the request headers if they don't exist
+                request.headers ??= {};
+
+                // Add the authentication headers to the request
+                request.headers = {
+                    ...request.headers,
+                    ...authHeaders,
+                };
+
+                // Return the request with the authentication headers
+                return request;
+            },
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body,
+            method: 'POST',
+            // Reconnect when the server ends the stream (e.g. a restart or a proxy idle timeout). By default only errors are retried
+            persistent: true,
+        });
+
+        // Create a listener to re-emit the connected and disconnected events
+        session.on('connected', this.handleOnConnectionUpdated.bind(this, 'connected'));
+        session.on('disconnected', this.handleOnConnectionUpdated.bind(this, 'disconnected'));
+
+        // Create a listener to re-emit the messages
+        session.on('message', (message): void => {
+            const parsedMessage = BaseSyncClient.resourceInstanceSchema.safeParse(fromExtendedJson(message.data));
+            if (!parsedMessage.success) {
+                return;
+            }
+
+            this.emit('resource-instance-updated', {
+                ...parsedMessage.data,
+                value: fromExtendedJson(new TextDecoder().decode(parsedMessage.data.blob)) as PayloadType,
+            });
+        });
+
+        // Create a listener to re-emit the errors
+        session.on('error', (error) => {
+            this.emit('error', error);
+        });
+
+        // Return the session
+        return session;
+    }
+
+    /**
+     * Send a POST /data/write request to the server
+     * @param resources - The resources to write
+     * @returns The Resource Object with the decoded value
+     */
+    async writeMany(resources: Record<string, PayloadType>): Promise<ResourcesRecord<PayloadType>> {
+        // Sign the resource write requests
+        const signedResources = Object.entries(resources).map(([ resourceId, value ]) => {
+            const valueStr = toExtendedJson(value);
+            const valueBytes = this.textEncoder.encode(valueStr);
+
+            return BaseSyncClient.signWriteRequest(this.privateKey.toBytes(), resourceId, valueBytes);
+        });
+
+        // Send the resource write requests to the server
+        const res = await this.sendRequest('/data/write', {
+            resources: signedResources,
+        });
+
+        // If the response is not ok, throw an error
+        if (!res.ok) {
+            const error = await res.json();
+            throw new Error(`Failed to write resources [${Object.keys(resources).join(', ')}] (${res.statusText}): ${JSON.stringify(error)}`);
+        }
+
+        // Decode the response and return the resources
+        const decodedResources = await this.decodeResponse(res);
+
+        // Return the decoded resources
+        return decodedResources;
+    }
+
+    /**
+     * Send a POST /data/read request to the server
+     * @param resourceIds - The resource IDs to read
+     * @returns The resources with the read values
+     */
+    async readMany(resourceIds: string[]): Promise<ResourcesRecord<PayloadType>> {
+        // Send the resource read requests to the server
+        const res = await this.sendRequest('/data/get', {
+            resourceId: resourceIds,
+        });
+
+        // If the response is not ok, throw an error
+        if (!res.ok) {
+            throw new Error(`Failed to read resources [${resourceIds.join(', ')}] (${res.statusText})`);
+        }
+
+        // Decode the response and return the resources
+        const decodedResources = await this.decodeResponse(res);
+
+        // Return the decoded resources
+        return decodedResources;
+    }
+
+    /**
+     * Destroy the current SSE Session, then re-create it with the additional resource ID in the subscription list
+     * @param resourceId - The resource ID to add to the subscription list
+     */
+    async subscribe(resourceId: string): Promise<void> {
+        this.subscriptions.add(resourceId);
+
+        this.emit('subscriptions-updated', this.subscriptions);
+    }
+
+    /**
+     * Destroy the current SSE Session, then re-create it without the resource ID in the subscription list
+     * @param resourceId - The resource ID to remove from the subscription list
+     */
+    async unsubscribe(resourceId: string): Promise<void> {
+        this.subscriptions.delete(resourceId);
+
+        this.emit('subscriptions-updated', this.subscriptions);
+    }
+
+    async handleOnConnectionUpdated(value: 'connected' | 'disconnected'): Promise<void> {
+        this.emit('connection-updated', value);
+    }
+
+    /**
+     * Sends a request to the server
+     * @param path - The path to send the request to
+     * @param body - The body of the request
+     * @returns The response from the server
+     */
+    private async sendRequest(path: string, body: unknown): Promise<Response> {
+        // Build the URL
+        const url = `${this.url}${path}`;
+
+        // Format the body as Extended JSON
+        const formattedBody = toExtendedJson(body);
+
+        // Send the request to the server
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...BaseSyncClient.signRequest(this.privateKey.toBytes(), path, body),
+            },
+            body: formattedBody,
+        });
+
+        // Return the response
+        return res;
+    }
+
+    /**
+     * Decodes the blobs on the response body to the type T
+     * @param response - The response to decode
+     * @returns The decoded resources
+     */
+    private async decodeResponse(response: Response): Promise<ResourcesRecord<PayloadType>> {
+        // Decode the response from Extended JSON
+        const text = fromExtendedJson(await response.text());
+
+        // Parse the response as a record of resources
+        const resources = BaseSyncClient.resourcesResponseSchema.parse(text);
+
+        // Decode the blobs and convert them from extended json to the type T
+        const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
+
+        return decodedResources;
+    }
+}

source/sse/index.ts

@@ -0,0 +1 @@
+export * from './client.ts';

source/types.ts

@@ -0,0 +1,11 @@
+export type WriteRequest = {
+    id: string;
+    publicKey: string;
+    timestamp: number;
+
+    /**
+     * sha256(timestamp + id + toExtendedJson(value))
+     */
+    signature: string;
+    value: unknown;
+};

source/ws/client.ts

@@ -0,0 +1,410 @@
+import { ExponentialBackoff, fromExtendedJson, toExtendedJson } from '@xo-cash/utils';
+import type { PrivateKey } from '@xo-cash/primitives';
+
+import { WsMessageSchema, WsSuccessResponseSchema, WsErrorResponseSchema, type WsMessage } from './types.ts';
+import { BaseSyncClient, type ResourcesRecord } from '../shared/base-client.ts';
+
+/** A request sent over the sync server's WebSocket connection. */
+type WsRequest = {
+    id?: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+};
+
+type PendingRequest = {
+    resolve: (body: unknown) => void;
+    reject: (error: Error) => void;
+};
+
+export type WsClientOptions = {
+
+    /** Called for server-pushed events and uncorrelated server errors. */
+    onMessage: (message: WsMessage) => void;
+
+    /** Called for transport errors and malformed server messages. */
+    onError: (error: Error) => void;
+};
+
+/**
+ * Minimal WebSocket client for the XO sync server.
+ *
+ * - one connection is opened at `/ws`, on demand: every request awaits the
+ *   connection first, so callers never need to wait for one themselves;
+ * - request IDs correlate concurrent read/write/unsubscribe calls;
+ * - subscriptions are remembered and re-sent on every new socket, because the
+ *   server drops a socket's topics when it closes; and
+ * - a dropped connection fails pending requests and is reopened with backoff
+ *   until `disconnect()` is called. Requests made in the meantime wait for it.
+ *
+ * Heartbeats and request timeouts are not implemented.
+ */
+export class WsClient<PayloadType = unknown> extends BaseSyncClient<PayloadType> {
+    private readonly url: string;
+    private readonly privateKey: PrivateKey;
+    private readonly pendingRequests = new Map<string, PendingRequest>();
+    private readonly messageListeners = new Set<(message: WsMessage) => void>();
+    private readonly errorListeners = new Set<(error: Error) => void>();
+    private readonly textEncoder = new TextEncoder();
+
+    /** Resource IDs to (re)subscribe to whenever a socket opens. */
+    private readonly subscriptions = new Set<string>();
+
+    /**
+     * The current connection: resolves to an open socket once a connection attempt succeeds.
+     * Undefined until `connect()` and after `disconnect()`, which also means "don't reconnect".
+     */
+    private webSocket: Promise<WebSocket> | undefined;
+
+    /** Retries a failed connection attempt forever (maxAttempts 0), waiting up to 30s between attempts. */
+    private readonly connectBackoff = new ExponentialBackoff({
+        maxAttempts: 0,
+        maxDelay: 30_000,
+    });
+
+    constructor(url: string, privateKey: PrivateKey, options: Partial<WsClientOptions> = {}) {
+        super();
+
+        this.url = url;
+        this.privateKey = privateKey;
+        this.messageListeners.add(options.onMessage ?? ((): void => {}));
+        this.errorListeners.add(options.onError ?? ((): void => {}));
+    }
+
+    /** Connect, and keep reconnecting on drops until `disconnect()` is called. */
+    async connect(): Promise<void> {
+        await this.getWebSocket();
+    }
+
+    /**
+     * Close the socket and stop reconnecting.
+     *
+     * Closing a WebSocket automatically removes all of its server-side topics,
+     * so disconnect does not need to send an unsubscribe request first.
+     * Subscriptions are kept, and are replayed if the client connects again.
+     *
+     * Resolves without waiting for the socket to finish closing; `connection-updated` fires when it does.
+     */
+    async disconnect(): Promise<void> {
+        const attempt = this.webSocket;
+        this.webSocket = undefined;
+
+        this.rejectPendingRequests(new Error('WebSocket client disconnected'));
+
+        // If the attempt is still retrying, it sees it is no longer current after its next handshake,
+        // closes that socket and stops. Its rejection is handled here.
+        attempt?.then(
+            (socket) => socket.close(),
+            () => {},
+        );
+    }
+
+    /**
+     * The current socket, starting a connection attempt if there isn't one.
+     *
+     * A new socket has no topics on the server, so starting an attempt also queues a subscribe for
+     * every remembered subscription. They are sent through send(), so they go out once the socket opens.
+     */
+    private getWebSocket(): Promise<WebSocket> {
+        if (this.webSocket) {
+            return this.webSocket;
+        }
+
+        this.webSocket = this.openWebSocket();
+
+        for (const resourceId of this.subscriptions) {
+            // A failure here means the attempt was stopped by disconnect() or the socket closed before the
+            // frame was sent. A close starts a new attempt, which replays this again, so there is nothing to do.
+            this.send('/data/subscribe', { resourceId: [ resourceId ] }).catch(() => {});
+        }
+
+        return this.webSocket;
+    }
+
+    /**
+     * Retry opening a socket until one opens. Use getWebSocket() instead of calling this directly.
+     *
+     * `this.webSocket === attempt` tells whether this attempt is still the current connection.
+     * It stops being current when `disconnect()` is called.
+     */
+    private openWebSocket(): Promise<WebSocket> {
+        const attempt: Promise<WebSocket> = this.connectBackoff.run(
+            async ({ stopRetries }) => {
+                // `attempt` is only read after this await: run() calls this function before `attempt` is assigned.
+                const socket = await WsClient.waitForOpen(new WebSocket(WsClient.httpToWsUrl(this.url)));
+
+                // disconnect() was called while connecting. The thrown error rejects `attempt`.
+                if (this.webSocket !== attempt) {
+                    socket.close();
+                    stopRetries('WebSocket client disconnected');
+                    throw new Error('WebSocket client disconnected');
+                }
+
+                socket.onmessage = (event): void => this.handleMessage(String(event.data));
+                socket.onerror = (): void => this.emitError(new Error('WebSocket error'));
+                socket.onclose = async (): Promise<void> => {
+                    this.rejectPendingRequests(new Error('WebSocket connection closed'));
+                    this.emit('connection-updated', 'disconnected');
+
+                    // Reconnect, unless disconnect() was called
+                    if (this.webSocket === attempt) {
+                        this.webSocket = undefined;
+                        await this.getWebSocket();
+                    }
+                };
+
+                this.emit('connection-updated', 'connected');
+
+                return socket;
+            },
+            {
+                // Report failed handshakes, but not the error thrown above after disconnect()
+                onError: (error) => {
+                    if (this.webSocket === attempt) {
+                        this.emitError(error);
+                    }
+                },
+            },
+        );
+
+        // Nothing may be awaiting this attempt (e.g. a reconnect started by onclose), and it rejects if disconnect() stops it.
+        // Mark the rejection as handled so it isn't reported as unhandled. Callers awaiting `attempt` still receive it.
+        attempt.catch(() => {});
+
+        return attempt;
+    }
+
+    async readMany(resourceIds: string[]): Promise<ResourcesRecord<PayloadType>> {
+        // Read the resources from the server
+        const response = await this.request('/data/get', {
+            resourceId: resourceIds,
+        });
+
+        // Parse the response as a record of resources
+        const resources = BaseSyncClient.resourcesResponseSchema.parse(response);
+
+        // Decode the resources and convert the blobs from Uint8Arrays to the type T
+        const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
+
+        return decodedResources;
+    }
+
+    async writeMany(resourcesToWrite: Record<string, PayloadType>): Promise<ResourcesRecord<PayloadType>> {
+        // Sign the resources
+        const signedResources = Object.entries(resourcesToWrite).map(([ resourceId, value ]) => {
+            const valueStr = toExtendedJson(value);
+            const valueBytes = this.textEncoder.encode(valueStr);
+
+            return BaseSyncClient.signWriteRequest(this.privateKey.toBytes(), resourceId, valueBytes);
+        });
+
+        // Write the resources to the server
+        const response = await this.request('/data/write', {
+            resources: signedResources,
+        });
+
+        // Parse the response as a record of resources
+        const resources = BaseSyncClient.resourcesResponseSchema.parse(response);
+
+        // Decode the resources and convert the blobs from Uint8Arrays to the type T
+        const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
+
+        return decodedResources;
+    }
+
+    /**
+     * Subscribe to one resource topic, now and on every future socket.
+     *
+     * The server never replies to a successful subscribe (the route stays pending until the topic is
+     * removed), so this resolves once the frame is sent. A failed subscribe comes back as an `error`
+     * message that matches no pending request, which handleMessage() reports through emitError().
+     *
+     * @param resourceId - The resource ID to subscribe to
+     */
+    async subscribe(resourceId: string): Promise<void> {
+        await this.send('/data/subscribe', { resourceId: [ resourceId ] });
+
+        // Remembered only after sending: if send() started a new socket, getWebSocket() replays the
+        // existing subscriptions, and this one isn't among them yet. Sending it twice in the same
+        // millisecond gives identical signatures, which the server rejects as a replay.
+        this.subscriptions.add(resourceId);
+    }
+
+    /**
+     * Unsubscribe from one resource topic.
+     * @param resourceId - The resource ID to unsubscribe from
+     */
+    async unsubscribe(resourceId: string): Promise<void> {
+        this.subscriptions.delete(resourceId);
+
+        // Not connected: the server holds no topics for us, and future sockets won't replay this one.
+        if (!this.webSocket) {
+            return;
+        }
+
+        await this.request('/data/unsubscribe', { resourceId: [ resourceId ] });
+    }
+
+    /** Send a request and wait for the response carrying the same ID. */
+    private async request(path: string, body: unknown): Promise<unknown> {
+        const id = crypto.randomUUID();
+
+        await this.send(path, body, id);
+
+        // Registered after sending, so only requests that were actually sent can be rejected by a close.
+        // The reply can't arrive first: socket messages are delivered as later events.
+        return new Promise<unknown>((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve, reject });
+        });
+    }
+
+    /**
+     * Connect if needed, then sign and send one request envelope using the shared Extended JSON codec.
+     * @param path - The path of the request
+     * @param body - The body of the request
+     * @param id - The ID of the request
+     */
+    private async send(path: string, body: unknown, id: string = crypto.randomUUID()): Promise<void> {
+        const socket = await this.getWebSocket();
+
+        // The socket can close between being awaited and being used. A closed socket drops frames silently.
+        if (socket.readyState !== WebSocket.OPEN) {
+            throw new Error('WebSocket is not connected');
+        }
+
+        // Signed after connecting: the server rejects signatures older than its timestamp window (5 minutes by default).
+        const headers = BaseSyncClient.signRequest(this.privateKey.toBytes(), path, toExtendedJson(body));
+        const request: WsRequest = { id, path, body, headers };
+
+        socket.send(toExtendedJson(request));
+    }
+
+    /**
+     * Resolve with the socket once it opens, or reject if the handshake fails.
+     * @param socket - The WebSocket to wait for
+     * @returns The WebSocket
+     */
+    private static waitForOpen(socket: WebSocket): Promise<WebSocket> {
+        return new Promise((resolve, reject) => {
+            socket.onopen = (): void => resolve(socket);
+            socket.onerror = (): void => reject(new Error('WebSocket connection failed'));
+        });
+    }
+
+    /**
+     * Decode and route one frame received from the sync server.
+     * @param raw - The raw message received from the sync server
+     */
+    private handleMessage(raw: string): void {
+        const { success, data: message } = WsMessageSchema.safeParse(fromExtendedJson(raw));
+        if (!success) {
+            this.emitError(new Error('Invalid WebSocket message'));
+
+            return;
+        }
+
+        // Only response/error messages with an outstanding ID are RPC replies.
+        // Application events are left for message listeners, even if they have IDs.
+        const pending = message.id ? this.pendingRequests.get(message.id) : undefined;
+
+        // If the message has no outstanding ID, it is a subscription event so we will just notify the listeners
+        if (!pending) {
+            for (const listener of this.messageListeners) {
+                listener(message);
+            }
+
+            // Errors with no pending request are failed subscribes (see sendSubscribe) or uncorrelated server errors.
+            const error = WsErrorResponseSchema.safeParse(message);
+            if (error.success) {
+                this.emitError(new Error(`${error.data.error} (${error.data.statusCode})`));
+
+                return;
+            }
+
+            if (message.type === 'instance-changed') {
+                const parsedMessage = BaseSyncClient.resourceInstanceSchema.safeParse(message.data);
+                if (!parsedMessage.success) {
+                    return;
+                }
+
+                this.emit('resource-instance-updated', {
+                    ...parsedMessage.data,
+                    value: fromExtendedJson(new TextDecoder().decode(parsedMessage.data.blob)) as PayloadType,
+                });
+            }
+
+            return;
+        }
+
+        // Delete the pending request
+        this.pendingRequests.delete(message.id!);
+
+        // If the message is an error, reject the pending request
+        if (message.type === 'error') {
+            const error = WsErrorResponseSchema.parse(message);
+            pending.reject(new Error(`${error.error} (${error.statusCode})`));
+
+            return;
+        }
+
+        // If the message is a response, resolve the pending request
+        if (message.type === 'response') {
+            const response = WsSuccessResponseSchema.parse(message);
+
+            // If the response is not successful, reject the pending request
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                pending.reject(new Error(`Request failed (${response.statusCode})`));
+
+                return;
+            }
+
+            // If the response is successful, resolve the pending request
+            pending.resolve(response.body);
+        }
+    }
+
+    /**
+     * Helper to emit an error to all error listeners
+     * @param error - The error to emit
+     */
+    private emitError(error: Error): void {
+        for (const listener of this.errorListeners) {
+            listener(error);
+        }
+    }
+
+    /**
+     * Helper for when the client disconnects
+     * @param error - The error to reject the pending requests with
+     */
+    private rejectPendingRequests(error: Error): void {
+        for (const pending of this.pendingRequests.values()) {
+            pending.reject(error);
+        }
+
+        this.pendingRequests.clear();
+    }
+
+    /**
+     * Helper to convert an HTTP URL to a WebSocket URL
+     * @param httpUrl - The HTTP URL to convert
+     * @returns The WebSocket URL
+     */
+    static httpToWsUrl(httpUrl: string): string {
+        const url = new URL(httpUrl);
+
+        if (url.protocol === 'http:') {
+            url.protocol = 'ws:';
+        } else if (url.protocol === 'https:') {
+            url.protocol = 'wss:';
+        } else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+            throw new Error(`Unsupported sync server protocol: ${url.protocol}`);
+        }
+
+        // The constructor accepts either the server root or the complete `/ws` URL.
+        const pathname = url.pathname.replace(/\/+$/, '');
+        url.pathname = pathname.endsWith('/ws') ? pathname : `${pathname}/ws`;
+
+        return url.toString();
+    }
+}

source/ws/index.ts

@@ -0,0 +1 @@
+export * from './client.ts';

source/ws/types.ts

@@ -19,7 +19,7 @@ export const WsErrorResponseSchema = z.object({
 });
 export type WsErrorResponse = z.infer<typeof WsErrorResponseSchema>;
 
-export const WsResponseSchema = z.discriminatedUnion('type', [WsSuccessResponseSchema, WsErrorResponseSchema]);
+export const WsResponseSchema = z.discriminatedUnion('type', [ WsSuccessResponseSchema, WsErrorResponseSchema ]);
 export type WsResponse = z.infer<typeof WsResponseSchema>;
 
 /**
@@ -36,5 +36,5 @@ export const WsEventSchema = z.object({
 });
 export type WsEvent = z.infer<typeof WsEventSchema>;
 
-export const WsMessageSchema = z.union([WsResponseSchema, WsEventSchema]);
+export const WsMessageSchema = z.union([ WsResponseSchema, WsEventSchema ]);
 export type WsMessage = z.infer<typeof WsMessageSchema>;

src/index.ts

@@ -1,4 +0,0 @@
-export * from './shared/base-client.js';
-
-export * from './sse/client.js';
-export * from './ws/client.js';

src/shared/base-client.ts

@@ -1,267 +0,0 @@
-import { binToHex, flattenBinArray, secp256k1, sha256 } from "@bitauth/libauth";
-
-import { toExtendedJson, EventEmitter, fromExtendedJson } from "@xo-cash/utils";
-import type { WriteRequest } from "../types.js";
-import z from "zod";
-
-export type AuthenticatedRequestHeaders = {
-  'X-Public-Key': string;
-  'X-Timestamp': string;
-  'X-Signature': string;
-};
-
-export type SignedPayload = { publicKey: string; signature: string };
-
-export type XOSyncClientEventMap<T = unknown> = {
-  'connection-updated': 'connected' | 'disconnected';
-  'resource-instance-updated': Resource<T> & {
-    resourceId: string;
-  };
-  'subscriptions-updated': Set<string>;
-  'error': Error;
-};
-
-export type Resource<PayloadType = unknown> = z.infer<typeof BaseSyncClient.resourceInstanceSchema> & {
-  value: PayloadType;
-};
-
-export type ResourcesRecord<PayloadType = unknown> = Record<string, { instances: Resource<PayloadType>[] }>;
-
-export abstract class BaseSyncClient<T = unknown> extends EventEmitter<XOSyncClientEventMap<T>> {
-
-  /**
-   * Connects to the sync server
-   */
-  abstract connect(): Promise<void>;
-
-  /**
-   * Disconnects from the sync server
-   */
-  abstract disconnect(): Promise<void>;
-  
-  /**
-   * Sign and write one resource
-   * @param resourceId - The resource ID to write to
-   * @param value - The value to write
-   * @returns The Resource Object with the decoded value
-   */
-  async write(resourceId: string, value: T): Promise<Resource<T>[]> {
-    // Write the resource to the server
-    const response = await this.writeMany({ [resourceId]: value });
-    
-    // Get the resource from the response
-    const resource = response[resourceId];
-
-    // If the resource is not found, throw an error
-    if (!resource) {
-      throw new Error(`Resource ${resourceId} not found`);
-    }
-
-    // Return the resource instances
-    return resource.instances;
-  }
-  
-  /**
-   * Writes multiple values to resources
-   * @param resources - The resources to write to
-   * @returns The resources with the written values
-   */
-  abstract writeMany(resources: Record<string, T>): Promise<ResourcesRecord<T>>;
-
-  /**
-   * Reads a value from a resource
-   * @param resourceId - The resource ID to read from
-   * @returns The resource with the read value
-   */
-  async read(resourceId: string): Promise<Resource<T>[]> {
-    // Read the resource from the server
-    const response = await this.readMany([ resourceId ]);
-
-    // Get the resource from the response
-    const resource = response[resourceId];
-
-    // If the resource is not found, throw an error
-    if (!resource) {
-      throw new Error(`Resource ${resourceId} not found`);
-    }
-
-    // Return the resource instances
-    return resource.instances;
-  }
-
-  /**
-   * Reads multiple values from resources
-   * @param resourceIds - The resource IDs to read from
-   * @returns The resources with the read values
-   */
-  abstract readMany(resourceIds: string[]): Promise<ResourcesRecord<T>>;
-
-  /**
-   * Subscribes to a resource
-   * @param resourceId - The resource ID to subscribe to
-   */
-  abstract subscribe(resourceId: string): Promise<void>;
-
-  /**
-   * Unsubscribes from a resource
-   * @param resourceId - The resource ID to unsubscribe from
-   */
-  abstract unsubscribe(resourceId: string): Promise<void>;
-
-  /**
-   * Derives the resource private key from the private key and resource ID
-   * @param privateKey - The private key to derive the resource private key from
-   * @param resourceId - The resource ID to derive the resource private key from
-   * @returns The resource private key
-   */
-  static deriveResourcePrivateKey(privateKey: Uint8Array, resourceId: string): Uint8Array {
-    // Convert the resource ID to bytes
-    const resourceIdBytes = new TextEncoder().encode(resourceId);
-
-    // Hash the private key and resource ID
-    return sha256.hash(flattenBinArray([ privateKey, resourceIdBytes ]));
-  }
-
-  /**
-   * Signs a payload with the private key and returns the public key and signature
-   * @param privateKey - The private key to sign the payload with
-   * @param payload - The payload to sign
-   * @returns The public key and signature
-   */
-  static signPayload(privateKey: Uint8Array, payload: string): SignedPayload {
-    // Convert the payload to Binary and hash it
-    const payloadHash = sha256.hash(new TextEncoder().encode(payload));
-
-    // Derive the public key
-    const publicKey = secp256k1.derivePublicKeyCompressed(privateKey);
-    
-    // If the public key is a string, throw an error
-    if (typeof publicKey === 'string') {
-      throw new Error('Failed to derive public key');
-    }
-
-    // Sign the payload
-    const signature = secp256k1.signMessageHashDER(privateKey, payloadHash);
-
-    // If the signature is a string, throw an error
-    if (typeof signature === 'string') {
-      throw new Error('Failed to sign message');
-    }
-
-    return {
-      publicKey: binToHex(publicKey),
-      signature: binToHex(signature),
-    };
-  }
-
-  /**
-   * Signs a write request with the private key and returns the write request
-   * @param privateKey - The private key to sign the write request with
-   * @param resourceId - The resource ID to write to
-   * @param value - The value to write
-   * @returns The write request
-   */
-  static signWriteRequest(privateKey: Uint8Array, resourceId: string, value: Uint8Array): WriteRequest {
-    // Derive the resource private key
-    const derivedKey = this.deriveResourcePrivateKey(privateKey, resourceId);
-
-    // Create the payload
-    const timestamp = Date.now();
-    const payload = `${timestamp}:${resourceId}:${toExtendedJson(value)}`;
-
-    // Sign the payload
-    const { publicKey, signature } = this.signPayload(derivedKey, payload);
-
-    return { 
-      id: resourceId,
-      value,
-      publicKey,
-      timestamp,
-      signature,
-    };
-  }
-
-  /**
-   * Signs a request with the private key and returns the public key, timestamp, and signature
-   * @param privateKey - The private key to sign the request with
-   * @param path - The path of the request
-   * @param body - The body of the request
-   * @returns The public key, timestamp, and signature
-   */
-  static signRequest(privateKey: Uint8Array, path: string, body: unknown): AuthenticatedRequestHeaders {
-    // Create the payload
-    const timestamp = Date.now();
-
-    // Convert the body to a string if it isn't already a string
-    const bodyStr = typeof body === 'string' ? body : toExtendedJson(body);
-
-    // Create the payload as `Timestamp:Path:Body`
-    const payload = `${timestamp}:${path}:${bodyStr}`;
-
-    // Sign the payload
-    const { publicKey, signature } = this.signPayload(privateKey, payload);
-
-    return {
-      'X-Public-Key': publicKey,
-      'X-Timestamp': timestamp.toString(),
-      'X-Signature': signature,
-    };
-  }
-
-  /**
-   * Decodes the 'blob' field of the Resource Object from the server from a read/write
-   * @param response - The ResourceResponse Object from the server from a read/write
-   * @returns The Resource Object with the decoded value
-   */
-  static decodeResourcesResponse<T = unknown>(response: z.infer<typeof BaseSyncClient.resourcesResponseSchema>): ResourcesRecord<T> {
-    return Object.entries(response.resources).reduce<ResourcesRecord<T>>((acc, [resourceId, resource]) => {
-      // Get the instances
-      const instances = resource.instances;
-
-      // Decode the instances
-      const decodedInstances = instances.map((instance) => {
-        return BaseSyncClient.decodeBlobValue<T>(instance);
-      });
-
-      // Add the decoded instances to the accumulator
-      acc[resourceId] = {
-        ...resource,
-        instances: decodedInstances,
-      };
-
-      // Return the accumulator
-      return acc;
-    }, {});
-  }
-
-  static decodeBlobValue<T = unknown>(instance: z.infer<typeof BaseSyncClient.resourceInstanceSchema>): Resource<T> {
-    const decodedBlob = new TextDecoder().decode(instance.blob);
-    const value = fromExtendedJson(decodedBlob) as T;
-
-    return {
-      ...instance,
-      value,
-    };
-  }
-
-  static resourceInstanceSchema = z.object({
-    resourceId: z.string(),
-    blob: z.instanceof(Uint8Array),
-    timestamp: z.number(),
-    publicKey: z.string(),
-    signature: z.string(),
-  });
-
-  static rawResourcesSchema = z.object({
-    instances: z.array(BaseSyncClient.resourceInstanceSchema),
-  });
-
-  static resourcesResponseSchema = z.object({
-    resources: z.record(
-      // Resource ID
-      z.string(), 
-      // Resource instances
-      BaseSyncClient.rawResourcesSchema,
-    ),
-  });
-}

src/sse/client.ts

@@ -1,254 +0,0 @@
-import { SSESession, toExtendedJson, fromExtendedJson } from '@xo-cash/utils';
-import { PrivateKey } from '@xo-cash/primitives'
-
-import { BaseSyncClient, type ResourcesRecord } from '../shared/base-client.js';
-
-export class SSEClient<PayloadType = unknown> extends BaseSyncClient<PayloadType> {
-  private readonly url: string;
-  public sseSession: SSESession | undefined;
-  private readonly subscriptions: Set<string> = new Set();
-
-  private privateKey: PrivateKey;
-  private textEncoder = new TextEncoder();
-
-  private get subscriptionUrl() {
-    return `${this.url}/data/subscribe`;
-  }
-
-  /**
-   * Creates a new SSE client
-   * @param url - The URL of the server
-   * @param privateKey - The private key to use for authentication
-   */
-  constructor(url: string, privateKey: PrivateKey) {
-    super();
-
-    this.url = url;
-    this.privateKey = privateKey;
-
-    // Whenever we get a new subscription, we need to reconnect the session with the new subscriptions in the body
-    // We add a small debounce to this to prevent parallel subscriptions from causing multiple reconnects
-    this.on('subscriptions-updated', () => {
-      // Nothing awaits this listener, so report failures as an error event instead of an unhandled rejection
-      this.reconnect().catch((error) => this.emit('error', error));
-    }, 25);
-  }
-
-  /**
-   * Connects to the server
-   */
-  async connect() {
-    // The server rejects a subscribe request with no resource IDs, so there is nothing to connect to yet.
-    // subscribe() connects once there is a subscription. read() and write() are plain fetches and don't need a session.
-    if (this.subscriptions.size === 0) {
-      return;
-    }
-
-    this.sseSession ??= this.createSession();
-
-    await this.sseSession.connect();
-  }
-
-  /**
-   * Disconnects from the server
-   */
-  async disconnect() {
-    await this.sseSession?.disconnect();
-  }
-
-  /**
-   * Reconnects to the server
-   */
-  async reconnect() {
-    // Close the current session. Its subscription list is fixed in the request body, so it can't be reused
-    this.sseSession?.close();
-    this.sseSession = undefined;
-
-    // Connect a new session with the current subscriptions
-    await this.connect();
-  }
-
-  /**
-   * Creates a new SSE session
-   * @returns The SSE session
-   */
-  private createSession() {
-    // Build the request body
-    const body = toExtendedJson({ resourceId: [ ...this.subscriptions ] });
-
-    // Create a new SSE session
-    const session = new SSESession(this.subscriptionUrl, {
-      onRequest: async (request) => {
-        // Get the path from the URL
-        const url = new URL(this.subscriptionUrl);
-        const path = url.pathname;
-
-        // Sign the request body
-        const authHeaders = BaseSyncClient.signRequest(this.privateKey.toBytes(), path, request.body);
-
-        // Initialize the request headers if they don't exist
-        request.headers ??= {};
-
-        // Add the authentication headers to the request
-        request.headers = {
-          ...request.headers,
-          ...authHeaders,
-        }
-
-        // Return the request with the authentication headers
-        return request;
-      },
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body,
-      method: 'POST',
-      // Reconnect when the server ends the stream (e.g. a restart or a proxy idle timeout). By default only errors are retried
-      persistent: true,
-    });
-
-    // Create a listener to re-emit the connected and disconnected events
-    session.on('connected', this.handleOnConnectionUpdated.bind(this, 'connected'));
-    session.on('disconnected', this.handleOnConnectionUpdated.bind(this, 'disconnected'));
-
-    // Create a listener to re-emit the messages
-    session.on('message', (message) => {
-      const parsedMessage = BaseSyncClient.resourceInstanceSchema.safeParse(fromExtendedJson(message.data));
-      if (!parsedMessage.success) {
-        return;
-      }
-
-      this.emit('resource-instance-updated', {
-        ...parsedMessage.data,
-        value: fromExtendedJson(new TextDecoder().decode(parsedMessage.data.blob)) as PayloadType,
-      });
-    });
-
-    // Create a listener to re-emit the errors
-    session.on('error', (error) => {
-      this.emit('error', error);
-    });
-
-    // Return the session
-    return session;
-  }
-  
-  /**
-   * Send a POST /data/write request to the server
-   * @param resources - The resources to write
-   * @returns The Resource Object with the decoded value
-   */
-  async writeMany(resources: Record<string, PayloadType>): Promise<ResourcesRecord<PayloadType>> {
-    // Sign the resource write requests
-    const signedResources = Object.entries(resources).map(([resourceId, value]) => {
-      const valueStr = toExtendedJson(value);
-      const valueBytes = this.textEncoder.encode(valueStr);
-      return BaseSyncClient.signWriteRequest(this.privateKey.toBytes(), resourceId, valueBytes);
-    });
-
-    // Send the resource write requests to the server
-    const res = await this.sendRequest('/data/write', { resources: signedResources });
-
-    // If the response is not ok, throw an error
-    if (!res.ok) {
-      const error = await res.json();
-      throw new Error(`Failed to write resources [${Object.keys(resources).join(', ')}] (${res.statusText}): ${JSON.stringify(error)}`);
-    }
-
-    // Decode the response and return the resources
-    const decodedResources = await this.decodeResponse(res);
-
-    // Return the decoded resources
-    return decodedResources;
-  }
-
-  /**
-   * Send a POST /data/read request to the server
-   * @param resourceIds - The resource IDs to read
-   * @returns The resources with the read values
-   */
-  async readMany(resourceIds: string[]): Promise<ResourcesRecord<PayloadType>> {
-    // Send the resource read requests to the server
-    const res = await this.sendRequest('/data/get', { resourceId: resourceIds });
-
-    // If the response is not ok, throw an error
-    if (!res.ok) {
-      throw new Error(`Failed to read resources [${resourceIds.join(', ')}] (${res.statusText})`);
-    }
-
-    // Decode the response and return the resources
-    const decodedResources = await this.decodeResponse(res);
-
-    // Return the decoded resources
-    return decodedResources;
-  }
-
-  /**
-   * Destroy the current SSE Session, then re-create it with the additional resource ID in the subscription list
-   * @param resourceId - The resource ID to add to the subscription list
-   */
-  async subscribe(resourceId: string) {
-    this.subscriptions.add(resourceId);
-
-    this.emit('subscriptions-updated', this.subscriptions);
-  }
-
-  /**
-   * Destroy the current SSE Session, then re-create it without the resource ID in the subscription list
-   * @param resourceId - The resource ID to remove from the subscription list
-   */
-  async unsubscribe(resourceId: string) {
-    this.subscriptions.delete(resourceId);
-
-    this.emit('subscriptions-updated', this.subscriptions);
-  }
-
-  async handleOnConnectionUpdated(value: 'connected' | 'disconnected') {
-    this.emit('connection-updated', value);
-  }
-
-  /**
-   * Sends a request to the server
-   * @param path - The path to send the request to
-   * @param body - The body of the request
-   * @returns The response from the server
-   */
-  private async sendRequest(path: string, body: unknown): Promise<Response> {
-    // Build the URL
-    const url = `${this.url}${path}`;
-
-    // Format the body as Extended JSON
-    const formattedBody = toExtendedJson(body);
-
-    // Send the request to the server
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...BaseSyncClient.signRequest(this.privateKey.toBytes(), path, body),
-      },
-      body: formattedBody,
-    });
-
-    // Return the response
-    return res;
-  }
-
-  /**
-   * Decodes the blobs on the response body to the type T
-   * @param response - The response to decode
-   * @returns The decoded resources
-   */
-  private async decodeResponse(response: Response): Promise<ResourcesRecord<PayloadType>> {
-    // Decode the response from Extended JSON
-    const text = fromExtendedJson(await response.text())
-
-    // Parse the response as a record of resources
-    const resources = BaseSyncClient.resourcesResponseSchema.parse(text);
-
-    // Decode the blobs and convert them from extended json to the type T
-    const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
-
-    return decodedResources;
-  }
-}

src/sse/index.ts

@@ -1 +0,0 @@
-export * from './client.js';

src/types.ts

@@ -1,11 +0,0 @@
-export type WriteRequest = {
-  id: string;
-  publicKey: string;
-  timestamp: number;
-
-  /**
-   * sha256(timestamp + id + toExtendedJson(value))
-   */
-  signature: string;
-  value: unknown;
-};

src/ws/client.ts

@@ -1,395 +0,0 @@
-import { ExponentialBackoff, fromExtendedJson, toExtendedJson } from '@xo-cash/utils';
-import type { PrivateKey } from '@xo-cash/primitives';
-
-import { WsMessageSchema, WsSuccessResponseSchema, WsErrorResponseSchema, type WsMessage } from './types.js';
-import { BaseSyncClient, type ResourcesRecord } from '../shared/base-client.js';
-
-/** A request sent over the sync server's WebSocket connection. */
-type WsRequest = {
-  id?: string;
-  path: string;
-  body?: unknown;
-  headers?: Record<string, string>;
-};
-
-type PendingRequest = {
-  resolve: (body: unknown) => void;
-  reject: (error: Error) => void;
-};
-
-export type WsClientOptions = {
-  /** Called for server-pushed events and uncorrelated server errors. */
-  onMessage: (message: WsMessage) => void;
-
-  /** Called for transport errors and malformed server messages. */
-  onError: (error: Error) => void;
-};
-
-/**
- * Minimal WebSocket client for the XO sync server.
- *
- * - one connection is opened at `/ws`, on demand: every request awaits the
- *   connection first, so callers never need to wait for one themselves;
- * - request IDs correlate concurrent read/write/unsubscribe calls;
- * - subscriptions are remembered and re-sent on every new socket, because the
- *   server drops a socket's topics when it closes; and
- * - a dropped connection fails pending requests and is reopened with backoff
- *   until `disconnect()` is called. Requests made in the meantime wait for it.
- *
- * Heartbeats and request timeouts are not implemented.
- */
-export class WsClient<PayloadType = unknown> extends BaseSyncClient<PayloadType> {
-  private readonly url: string;
-  private readonly privateKey: PrivateKey;
-  private readonly pendingRequests = new Map<string, PendingRequest>();
-  private readonly messageListeners = new Set<(message: WsMessage) => void>();
-  private readonly errorListeners = new Set<(error: Error) => void>();
-  private readonly textEncoder = new TextEncoder();
-  
-  /** Resource IDs to (re)subscribe to whenever a socket opens. */
-  private readonly subscriptions = new Set<string>();
-
-  /**
-   * The current connection: resolves to an open socket once a connection attempt succeeds.
-   * Undefined until `connect()` and after `disconnect()`, which also means "don't reconnect".
-   */
-  private webSocket: Promise<WebSocket> | undefined;
-
-  /** Retries a failed connection attempt forever (maxAttempts 0), waiting up to 30s between attempts. */
-  private readonly connectBackoff = new ExponentialBackoff({ maxAttempts: 0, maxDelay: 30_000 });
-
-  constructor(
-    url: string,
-    privateKey: PrivateKey,
-    options: Partial<WsClientOptions> = {},
-  ) {
-    super();
-
-    this.url = url;
-    this.privateKey = privateKey;
-    this.messageListeners.add(options.onMessage ?? (() => {}));
-    this.errorListeners.add(options.onError ?? (() => {}));
-  }
-
-  /** Connect, and keep reconnecting on drops until `disconnect()` is called. */
-  async connect(): Promise<void> {
-    await this.getWebSocket();
-  }
-
-  /**
-   * Close the socket and stop reconnecting.
-   *
-   * Closing a WebSocket automatically removes all of its server-side topics,
-   * so disconnect does not need to send an unsubscribe request first.
-   * Subscriptions are kept, and are replayed if the client connects again.
-   *
-   * Resolves without waiting for the socket to finish closing; `connection-updated` fires when it does.
-   */
-  async disconnect(): Promise<void> {
-    const attempt = this.webSocket;
-    this.webSocket = undefined;
-
-    this.rejectPendingRequests(new Error('WebSocket client disconnected'));
-
-    // If the attempt is still retrying, it sees it is no longer current after its next handshake,
-    // closes that socket and stops. Its rejection is handled here.
-    attempt?.then((socket) => socket.close(), () => {});
-  }
-
-  /**
-   * The current socket, starting a connection attempt if there isn't one.
-   *
-   * A new socket has no topics on the server, so starting an attempt also queues a subscribe for
-   * every remembered subscription. They are sent through send(), so they go out once the socket opens.
-   */
-  private getWebSocket(): Promise<WebSocket> {
-    if (this.webSocket) {
-      return this.webSocket;
-    }
-
-    this.webSocket = this.openWebSocket();
-
-    for (const resourceId of this.subscriptions) {
-      // A failure here means the attempt was stopped by disconnect() or the socket closed before the
-      // frame was sent. A close starts a new attempt, which replays this again, so there is nothing to do.
-      this.send('/data/subscribe', { resourceId: [resourceId] }).catch(() => {});
-    }
-
-    return this.webSocket;
-  }
-
-  /**
-   * Retry opening a socket until one opens. Use getWebSocket() instead of calling this directly.
-   *
-   * `this.webSocket === attempt` tells whether this attempt is still the current connection.
-   * It stops being current when `disconnect()` is called.
-   */
-  private openWebSocket(): Promise<WebSocket> {
-    const attempt: Promise<WebSocket> = this.connectBackoff.run(async ({ stopRetries }) => {
-      // `attempt` is only read after this await: run() calls this function before `attempt` is assigned.
-      const socket = await WsClient.waitForOpen(new WebSocket(WsClient.httpToWsUrl(this.url)));
-
-      // disconnect() was called while connecting. The thrown error rejects `attempt`.
-      if (this.webSocket !== attempt) {
-        socket.close();
-        stopRetries('WebSocket client disconnected');
-        throw new Error('WebSocket client disconnected');
-      }
-
-      socket.onmessage = (event) => this.handleMessage(String(event.data));
-      socket.onerror = () => this.emitError(new Error('WebSocket error'));
-      socket.onclose = () => {
-        this.rejectPendingRequests(new Error('WebSocket connection closed'));
-        this.emit('connection-updated', 'disconnected');
-
-        // Reconnect, unless disconnect() was called
-        if (this.webSocket === attempt) {
-          this.webSocket = undefined;
-          this.getWebSocket();
-        }
-      };
-
-      this.emit('connection-updated', 'connected');
-
-      return socket;
-    }, {
-      // Report failed handshakes, but not the error thrown above after disconnect()
-      onError: (error) => {
-        if (this.webSocket === attempt) {
-          this.emitError(error);
-        }
-      },
-    });
-
-    // Nothing may be awaiting this attempt (e.g. a reconnect started by onclose), and it rejects if disconnect() stops it.
-    // Mark the rejection as handled so it isn't reported as unhandled. Callers awaiting `attempt` still receive it.
-    attempt.catch(() => {});
-
-    return attempt;
-  }
-
-  async readMany(resourceIds: string[]): Promise<ResourcesRecord<PayloadType>> {
-    // Read the resources from the server
-    const response = await this.request('/data/get', { resourceId: resourceIds });
-
-    // Parse the response as a record of resources
-    const resources = BaseSyncClient.resourcesResponseSchema.parse(response);
-
-    // Decode the resources and convert the blobs from Uint8Arrays to the type T
-    const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
-
-    return decodedResources;
-  }
-
-  async writeMany(resourcesToWrite: Record<string, PayloadType>): Promise<ResourcesRecord<PayloadType>> {
-    // Sign the resources
-    const signedResources = Object.entries(resourcesToWrite).map(([resourceId, value]) => {
-      const valueStr = toExtendedJson(value);
-      const valueBytes = this.textEncoder.encode(valueStr);
-      return BaseSyncClient.signWriteRequest(this.privateKey.toBytes(), resourceId, valueBytes);
-    });
-
-    // Write the resources to the server
-    const response = await this.request('/data/write', { resources: signedResources });
-
-    // Parse the response as a record of resources
-    const resources = BaseSyncClient.resourcesResponseSchema.parse(response);
-
-    // Decode the resources and convert the blobs from Uint8Arrays to the type T
-    const decodedResources = BaseSyncClient.decodeResourcesResponse<PayloadType>(resources);
-
-    return decodedResources;
-  }
-
-  /**
-   * Subscribe to one resource topic, now and on every future socket.
-   *
-   * The server never replies to a successful subscribe (the route stays pending until the topic is
-   * removed), so this resolves once the frame is sent. A failed subscribe comes back as an `error`
-   * message that matches no pending request, which handleMessage() reports through emitError().
-   * 
-   * @param resourceId - The resource ID to subscribe to
-   */
-  async subscribe(resourceId: string): Promise<void> {
-    await this.send('/data/subscribe', { resourceId: [resourceId] });
-
-    // Remembered only after sending: if send() started a new socket, getWebSocket() replays the
-    // existing subscriptions, and this one isn't among them yet. Sending it twice in the same
-    // millisecond gives identical signatures, which the server rejects as a replay.
-    this.subscriptions.add(resourceId);
-  }
-
-  /**
-   * Unsubscribe from one resource topic.
-   * @param resourceId - The resource ID to unsubscribe from
-   */
-  async unsubscribe(resourceId: string): Promise<void> {
-    this.subscriptions.delete(resourceId);
-
-    // Not connected: the server holds no topics for us, and future sockets won't replay this one.
-    if (!this.webSocket) {
-      return;
-    }
-
-    await this.request('/data/unsubscribe', { resourceId: [resourceId] });
-  }
-
-  /** Send a request and wait for the response carrying the same ID. */
-  private async request(path: string, body: unknown): Promise<unknown> {
-    const id = crypto.randomUUID();
-
-    await this.send(path, body, id);
-
-    // Registered after sending, so only requests that were actually sent can be rejected by a close.
-    // The reply can't arrive first: socket messages are delivered as later events.
-    return new Promise<unknown>((resolve, reject) => {
-      this.pendingRequests.set(id, { resolve, reject });
-    });
-  }
-
-  /**
-   * Connect if needed, then sign and send one request envelope using the shared Extended JSON codec.
-   * @param path - The path of the request
-   * @param body - The body of the request
-   * @param id - The ID of the request
-   */
-  private async send(path: string, body: unknown, id: string = crypto.randomUUID()): Promise<void> {
-    const socket = await this.getWebSocket();
-
-    // The socket can close between being awaited and being used. A closed socket drops frames silently.
-    if (socket.readyState !== WebSocket.OPEN) {
-      throw new Error('WebSocket is not connected');
-    }
-
-    // Signed after connecting: the server rejects signatures older than its timestamp window (5 minutes by default).
-    const headers = BaseSyncClient.signRequest(this.privateKey.toBytes(), path, toExtendedJson(body));
-    const request: WsRequest = { id, path, body, headers };
-
-    socket.send(toExtendedJson(request));
-  }
-
-  /**
-   * Resolve with the socket once it opens, or reject if the handshake fails.
-   * @param socket - The WebSocket to wait for
-   * @returns The WebSocket
-   */
-  private static waitForOpen(socket: WebSocket): Promise<WebSocket> {
-    return new Promise((resolve, reject) => {
-      socket.onopen = () => resolve(socket);
-      socket.onerror = () => reject(new Error('WebSocket connection failed'));
-    });
-  }
-
-  /**
-   * Decode and route one frame received from the sync server.
-   * @param raw - The raw message received from the sync server
-   */
-  private handleMessage(raw: string): void {
-    const { success, data: message } = WsMessageSchema.safeParse(fromExtendedJson(raw));
-    if (!success) {
-      this.emitError(new Error('Invalid WebSocket message'));
-      return;
-    }
-
-    // Only response/error messages with an outstanding ID are RPC replies.
-    // Application events are left for message listeners, even if they have IDs.
-    const pending = message.id ? this.pendingRequests.get(message.id) : undefined;
-
-    // If the message has no outstanding ID, it is a subscription event so we will just notify the listeners
-    if (!pending) {
-      for (const listener of this.messageListeners) {
-        listener(message);
-      }
-
-      // Errors with no pending request are failed subscribes (see sendSubscribe) or uncorrelated server errors.
-      const error = WsErrorResponseSchema.safeParse(message);
-      if (error.success) {
-        this.emitError(new Error(`${error.data.error} (${error.data.statusCode})`));
-        return;
-      }
-
-      if (message.type === 'instance-changed') {
-        const parsedMessage = BaseSyncClient.resourceInstanceSchema.safeParse(message.data);
-        if (!parsedMessage.success) {
-          return;
-        }
-
-        this.emit('resource-instance-updated', {
-          ...parsedMessage.data,
-          value: fromExtendedJson(new TextDecoder().decode(parsedMessage.data.blob)) as PayloadType,
-        });
-      }
-
-      return;
-    }
-
-    // Delete the pending request
-    this.pendingRequests.delete(message.id!);
-
-    // If the message is an error, reject the pending request
-    if (message.type === 'error') {
-      const error = WsErrorResponseSchema.parse(message);
-      pending.reject(new Error(`${error.error} (${error.statusCode})`));
-      return;
-    }
-
-    // If the message is a response, resolve the pending request
-    if (message.type === 'response') {
-      const response = WsSuccessResponseSchema.parse(message);
-
-      // If the response is not successful, reject the pending request
-      if (response.statusCode < 200 || response.statusCode >= 300) {
-        pending.reject(new Error(`Request failed (${response.statusCode})`));
-        return;
-      }
-
-      // If the response is successful, resolve the pending request
-      pending.resolve(response.body);
-    }
-  }
-
-  /**
-   * Helper to emit an error to all error listeners
-   * @param error - The error to emit
-   */
-  private emitError(error: Error): void {
-    for (const listener of this.errorListeners) {
-      listener(error);
-    }
-  }
-
-  /**
-   * Helper for when the client disconnects
-   * @param error - The error to reject the pending requests with
-   */
-  private rejectPendingRequests(error: Error): void {
-    for (const pending of this.pendingRequests.values()) {
-      pending.reject(error);
-    }
-
-    this.pendingRequests.clear();
-  }
-
-  /**
-   * Helper to convert an HTTP URL to a WebSocket URL
-   * @param httpUrl - The HTTP URL to convert
-   * @returns The WebSocket URL
-   */
-  static httpToWsUrl(httpUrl: string): string {
-    const url = new URL(httpUrl);
-
-    if (url.protocol === 'http:') {
-      url.protocol = 'ws:';
-    } else if (url.protocol === 'https:') {
-      url.protocol = 'wss:';
-    } else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
-      throw new Error(`Unsupported sync server protocol: ${url.protocol}`);
-    }
-
-    // The constructor accepts either the server root or the complete `/ws` URL.
-    const pathname = url.pathname.replace(/\/+$/, '');
-    url.pathname = pathname.endsWith('/ws') ? pathname : `${pathname}/ws`;
-
-    return url.toString();
-  }
-}

src/ws/index.ts

@@ -1 +0,0 @@
-export * from './client.js';

tsconfig.json

@@ -2,6 +2,7 @@
     // Visit https://aka.ms/tsconfig to read more about this file
     "compilerOptions": {
         // File Layout
+        "rootDir": "./source",
         "outDir": "./dist",
 
         // Environment Settings
@@ -27,5 +28,10 @@
         "noUncheckedSideEffectImports": true,
         "moduleDetection": "force",
         "skipLibCheck": true,
-  }
+
+        // GP
+        "allowImportingTsExtensions": true,
+        "rewriteRelativeImportExtensions": true
+    },
+    "include": ["source/**/*"]
 }