@metaflux-dex/client 0.0.1

package/dist/ws.js

@@ -0,0 +1,221 @@
+// MTF-native WebSocket client — connect, subscribe/unsubscribe, typed frames.
+//
+// Mirrors the Rust SDK's `WsClient` behavior (reconnect with backoff, replay of
+// active subscriptions, heartbeat ping) and the SERVER wire protocol
+// (`metaflux/crates/api-node/src/ws/subscribe.rs` + `fanout.rs`):
+//
+//   client → server:
+//     {"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}}
+//     {"method":"unsubscribe","subscription":{"type":"trades"}}
+//     {"method":"ping"}
+//   server → client:
+//     {"channel":"subscriptionResponse","data":{"method":"subscribe","subscription":{...}}}
+//     {"channel":"l2Book","data":{...}} | {"channel":"error","data":{"error":"..."}}
+//
+// Channel names are the EXACT server `Channel::wire_name()` strings (camelCase:
+// `l2Book`, `userEvents`). `coin` is the market symbol string and is optional
+// (e.g. `userEvents` carries none).
+//
+// Transport: the standard `WebSocket` global (browser-native; Node ≥ 22 ships
+// it globally, which is the SDK's floor). No `ws` npm dependency — keeping the
+// SDK dependency-free for both runtimes.
+/// All known channels — handy for callers that want to subscribe broadly.
+export const WS_CHANNELS = [
+    'l2Book',
+    'trades',
+    'bbo',
+    'fills',
+    'candles',
+    'userEvents',
+];
+const DEFAULT_CONFIG = {
+    pingIntervalMs: 30_000,
+    initialBackoffMs: 250,
+    maxBackoffMs: 30_000,
+    autoReconnect: true,
+};
+/// Subscription set equality key — `(channel, coin)` is the server's routing
+/// key, so two subscriptions are identical iff both match.
+function subKey(s) {
+    return `${s.type}:${s.coin ?? ''}`;
+}
+/// MTF-native WebSocket client.
+///
+/// Usage:
+/// ```ts
+/// const ws = new WsClient('wss://api.mtf.exchange/ws');
+/// ws.onMessage((f) => { if (f.channel === 'l2Book') handleBook(f.data); });
+/// await ws.connect();
+/// await ws.subscribe({ type: 'l2Book', coin: 'BTC' });
+/// // ... later
+/// ws.close();
+/// ```
+///
+/// `connect()` resolves once the socket is OPEN. Active subscriptions are
+/// re-issued automatically after a reconnect. Drop with `close()`.
+export class WsClient {
+    url;
+    config;
+    socket;
+    /// Active subscriptions, replayed on (re)connect. Keyed for dedupe.
+    active = new Map();
+    handlers = [];
+    pingTimer;
+    reconnectTimer;
+    backoffMs;
+    /// True once `close()` is called — suppresses auto-reconnect.
+    closed = false;
+    constructor(url, config = {}) {
+        if (url.length === 0) {
+            throw new RangeError('WsClient url must be non-empty');
+        }
+        this.url = url;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.backoffMs = this.config.initialBackoffMs;
+    }
+    /// Register an inbound-frame handler. Multiple handlers fan out; each
+    /// receives every frame. Returns an unsubscribe function.
+    onMessage(handler) {
+        this.handlers.push(handler);
+        return () => {
+            const i = this.handlers.indexOf(handler);
+            if (i >= 0)
+                this.handlers.splice(i, 1);
+        };
+    }
+    /// Open the connection. Resolves when the socket reaches OPEN; rejects if the
+    /// initial connect errors. Subsequent reconnects (if `autoReconnect`) happen
+    /// transparently in the background.
+    async connect() {
+        this.closed = false;
+        await this.openOnce();
+    }
+    /// Subscribe to a channel. The subscription is recorded and replayed on
+    /// reconnect. Idempotent — a duplicate `(channel, coin)` is a no-op (matching
+    /// the server, which silently ignores duplicate subscribes).
+    async subscribe(sub) {
+        const key = subKey(sub);
+        if (!this.active.has(key)) {
+            this.active.set(key, sub);
+        }
+        this.send({ method: 'subscribe', subscription: sub });
+    }
+    /// Unsubscribe from a channel.
+    async unsubscribe(sub) {
+        this.active.delete(subKey(sub));
+        this.send({ method: 'unsubscribe', subscription: sub });
+    }
+    /// Whether the socket is currently OPEN.
+    get isOpen() {
+        return this.socket?.readyState === 1; // WebSocket.OPEN
+    }
+    /// Close the connection and cancel auto-reconnect. After `close()` the client
+    /// is inert until `connect()` is called again.
+    close() {
+        this.closed = true;
+        this.clearTimers();
+        if (this.socket !== undefined) {
+            try {
+                this.socket.close();
+            }
+            catch {
+                // Already closing / closed.
+            }
+            this.socket = undefined;
+        }
+    }
+    // -------------------------------------------------------------------------
+    openOnce() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const sock = new WebSocket(this.url);
+            this.socket = sock;
+            sock.onopen = () => {
+                this.backoffMs = this.config.initialBackoffMs;
+                // Replay active subscriptions on (re)connect.
+                for (const sub of this.active.values()) {
+                    this.send({ method: 'subscribe', subscription: sub });
+                }
+                this.startPing();
+                settled = true;
+                resolve();
+            };
+            sock.onmessage = (ev) => {
+                this.dispatch(typeof ev.data === 'string' ? ev.data : String(ev.data));
+            };
+            sock.onerror = () => {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`WsClient failed to connect to ${this.url}`));
+                }
+                // Post-open errors are handled by onclose → reconnect.
+            };
+            sock.onclose = () => {
+                this.clearTimers();
+                this.socket = undefined;
+                if (!this.closed && this.config.autoReconnect) {
+                    this.scheduleReconnect();
+                }
+            };
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer !== undefined)
+            return;
+        const delay = this.backoffMs;
+        this.backoffMs = Math.min(this.backoffMs * 2, this.config.maxBackoffMs);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.closed)
+                return;
+            // Best-effort reconnect; failures retry via the next onclose.
+            void this.openOnce().catch(() => {
+                if (!this.closed && this.config.autoReconnect) {
+                    this.scheduleReconnect();
+                }
+            });
+        }, delay);
+    }
+    startPing() {
+        this.clearPing();
+        this.pingTimer = setInterval(() => {
+            this.send({ method: 'ping' });
+        }, this.config.pingIntervalMs);
+    }
+    send(obj) {
+        if (this.socket?.readyState === 1) {
+            this.socket.send(JSON.stringify(obj));
+        }
+        // If not open, the frame is dropped; subscribe state is replayed on the
+        // next open, so a dropped subscribe self-heals. A dropped ping is benign.
+    }
+    dispatch(raw) {
+        let frame;
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.channel !== 'string')
+                return; // ignore malformed
+            frame = { channel: parsed.channel, data: parsed.data };
+        }
+        catch {
+            return; // ignore non-JSON frames
+        }
+        for (const h of this.handlers) {
+            h(frame);
+        }
+    }
+    clearTimers() {
+        this.clearPing();
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    clearPing() {
+        if (this.pingTimer !== undefined) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = undefined;
+        }
+    }
+}
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@metaflux-dex/client",
+  "version": "0.0.1",
+  "description": "MetaFlux (MTF) TypeScript client SDK — WASM-backed crypto + ESM-only fetch wrappers.",
+  "type": "module",
+  "author": "MetaFlux",
+  "homepage": "https://github.com/mtf-exchange/metaflux-client-typescript#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mtf-exchange/metaflux-client-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mtf-exchange/metaflux-client-typescript/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./wasm": {
+      "import": "./pkg/metaflux_client_wasm.js",
+      "types": "./pkg/metaflux_client_wasm.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "pkg",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "metaflux",
+    "mtf",
+    "dex",
+    "perp",
+    "client",
+    "sdk",
+    "wasm"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build wasm/ --target web --out-dir ../pkg",
+    "build:ts": "tsc",
+    "build": "pnpm run build:wasm && pnpm run build:ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ __tests__/",
+    "typecheck": "tsc --noEmit"
+  }
+}