wscall-client 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hinsir-zxc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# wscall-client
+
+High-performance JavaScript client SDK for the [WSCALL](https://github.com/Hinsir-zxc/wscall) WebSocket RPC framework.
+
+Works in both **Node.js** (≥18) and modern **browsers** (native WebSocket + Web Crypto).
+
+## Features
+
+- **Protocol v3 binary codec** — compact 5-byte frame header, single-letter JSON keys, raw binary attachments (zero Base64 overhead).
+- **Encryption** — ChaCha20-Poly1305 and AES-256-GCM at frame level; no TLS required.
+- **ECDH key agreement** — X25519 dynamic per-connection session key (forward secrecy), no pre-shared key needed.
+- **Bidirectional messaging** — request/response RPC + server-pushed events with ACK correlation.
+- **Automatic reconnect** — exponential backoff with jitter; sticky failover across multiple server URLs.
+- **Zero-copy attachments** — send and receive binary files inline with RPC params or event data.
+
+## Installation
+
+```bash
+npm install wscall-client
+```
+
+For Node.js environments you also need a WebSocket implementation:
+
+```bash
+npm install ws
+```
+
+Browsers provide `WebSocket` natively — no extra dependency.
+
+## Quick Start
+
+### ECDH mode (recommended — no pre-shared key)
+
+```js
+import { WscallClient, WscallClientConfig } from 'wscall-client';
+
+const client = await WscallClient.connect(
+  'ws://127.0.0.1:9001/socket',
+  WscallClientConfig.ecdh()
+);
+
+// RPC call
+const res = await client.call('system.echo', { message: 'hello' });
+console.log(res.data); // { message: 'hello' }
+
+// Subscribe to server events
+client.onEvent('chat.message', (event) => {
+  console.log('New message:', event.data);
+  return { received: true }; // sent back as ACK receipt
+});
+
+// Emit an event (with ACK)
+const ack = await client.sendEvent('chat.message', { text: 'hi!' });
+console.log('Server acknowledged:', ack.receipt);
+
+client.close();
+```
+
+### PSK mode (pre-shared key)
+
+```js
+import { WscallClient, WscallClientConfig } from 'wscall-client';
+
+const key = new Uint8Array(32).fill(0x42); // 32-byte shared key
+
+const config = WscallClientConfig.pskChaCha20(key);
+const client = await WscallClient.connect('ws://127.0.0.1:9001/socket', config);
+```
+
+### Failover across multiple servers
+
+```js
+const config = WscallClientConfig.ecdh()
+  .withFailoverUrl('ws://backup1:9001/socket')
+  .withFailoverUrl('ws://backup2:9001/socket');
+
+const client = await WscallClient.connect('ws://primary:9001/socket', config);
+```
+
+On disconnect the client iterates through `[primary, ...failover]` starting from the last successfully connected URL (sticky failover).
+
+### File attachments
+
+```js
+import { createTextAttachment, attachmentRef } from 'wscall-client';
+
+const att = createTextAttachment('f1', 'hello.txt', 'text/plain', 'Hello, world!');
+
+const res = await client.call(
+  'files.inspect',
+  { file: attachmentRef('f1') },
+  [att]
+);
+```
+
+## API Overview
+
+### `WscallClient.connect(url, config?) → Promise<WscallClient>`
+
+Static factory. Connects to a WSCALL server and returns a ready client.
+
+### `WscallClientConfig`
+
+| Factory / Builder | Description |
+|-------------------|-------------|
+| `WscallClientConfig.ecdh()` | ECDH + ChaCha20 + auto-reconnect (default) |
+| `WscallClientConfig.plaintext()` | No encryption |
+| `WscallClientConfig.pskChaCha20(key)` | PSK with ChaCha20-Poly1305 |
+| `WscallClientConfig.pskAes256(key)` | PSK with AES-256-GCM |
+| `.withAutoReconnect(bool)` | Enable/disable auto-reconnect |
+| `.withTimeout(ms)` | Default request timeout |
+| `.withMetadata(obj)` | Default metadata sent with requests |
+| `.withFailoverUrl(url)` | Append a failover URL |
+| `.withFailoverUrls(urls)` | Set all failover URLs |
+
+### `client`
+
+| Method | Description |
+|--------|-------------|
+| `call(route, params?, attachments?, opts?)` | RPC call → `Promise<ApiResponse>` |
+| `sendEvent(name, data?, attachments?, opts?)` | Emit event → `Promise<EventAck>` |
+| `onEvent(name, handler)` | Subscribe to server events |
+| `offEvent(name, handler?)` | Unsubscribe |
+| `onConnected(handler)` | Connection established hook |
+| `onDisconnected(handler)` | Disconnection hook |
+| `close()` | Graceful shutdown (stops reconnect) |
+
+### Reconnect behavior
+
+1. Unexpected disconnects trigger automatic reconnect (default: enabled).
+2. First retry after 3 s, then exponential backoff (×2), capped at 30 s.
+3. Random sub-second jitter prevents thundering-herd storms.
+4. With `failoverUrls`, each cycle tries all URLs before applying backoff.
+5. `close()` stops all reconnect attempts.
+
+## Protocol Compatibility
+
+This SDK implements **WSCALL Protocol v3** (5-byte frame header, connection-level encryption). It requires a server running `wscall` ≥ 0.5.1.
+
+| SDK version | Protocol | Server compatibility |
+|-------------|----------|---------------------|
+| 0.3.x | v3 | wscall ≥ 0.5.1 |
+| 0.2.x | v2 | wscall 0.4.x – 0.5.0 |
+
+## Browser Usage
+
+```html
+<script type="module">
+  import { WscallClient, WscallClientConfig } from './node_modules/wscall-client/src/index.js';
+
+  const client = await WscallClient.connect('ws://localhost:9001/socket', WscallClientConfig.ecdh());
+  const res = await client.call('system.echo', { msg: 'from browser' });
+  console.log(res.data);
+</script>
+```
+
+In browsers the `ws` package is not needed — the native `WebSocket` global is used automatically.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@noble/ciphers` | ChaCha20-Poly1305 AEAD (pure JS, audited) |
+| `@noble/curves` | X25519 ECDH key agreement (pure JS, audited) |
+| `ws` *(optional peer)* | WebSocket implementation for Node.js |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "wscall-client",
+  "version": "0.3.0",
+  "description": "High-performance JavaScript client SDK for the WSCALL WebSocket RPC framework",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "demo": "node demo/demo.js",
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "websocket",
+    "rpc",
+    "wscall",
+    "binary-protocol",
+    "realtime",
+    "chacha20",
+    "aes-gcm",
+    "ecdh",
+    "x25519",
+    "event-driven"
+  ],
+  "author": "Hinsir-zxc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hinsir-zxc/wscall-client-js.git"
+  },
+  "homepage": "https://github.com/Hinsir-zxc/wscall-client-js#readme",
+  "bugs": {
+    "url": "https://github.com/Hinsir-zxc/wscall-client-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^1.2.1",
+    "@noble/curves": "^1.6.0"
+  },
+  "peerDependencies": {
+    "ws": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "ws": "^8.21.1"
+  }
+}