@pulsepairs/sdk 0.2.0

package/dist/ws.js

@@ -0,0 +1,224 @@
+/**
+ * WebSocket client with auto-reconnect + PR-19 auth handshake.
+ *
+ * Two paths:
+ *
+ *   - `connectPublic(channels)` — public channels only (`markets`,
+ *     `orderbook:*`, `trades:*`). Sends `{type:'subscribe', channels}`
+ *     immediately on open, no auth.
+ *
+ *   - `connectAuthed({ signAuth, channels })` — sends
+ *     `{type:'auth', ...}` first, awaits `auth_ok`, then sends
+ *     `{type:'subscribe', channels}`. Required for `orders:<wallet>` +
+ *     `balance:<wallet>` (PR-19 gates these behind a verified WsAuth
+ *     signature). On reconnect within the 24h token TTL, replays the
+ *     cached token via `{type:'auth', token}` — only re-prompts the
+ *     `signAuth` callback if the server rejects the cached token.
+ *
+ * Server message envelope (mirrors `src/ws/WebSocketServer.ts:235-293`):
+ *
+ *   client → server   { type: 'auth', wallet, timestamp, sessionId, signature }
+ *   server → client   { type: 'auth_ok', wallet, token, expiresAt }
+ *                  or { type: 'auth_error' }   (no reason echoed — anti-probe)
+ *
+ *   client → server   { type: 'auth', token }            (token replay)
+ *   server → client   { type: 'auth_ok', wallet, token } (token re-validated)
+ *
+ * State machine:
+ *   idle → authenticating → subscribing → live
+ *                                       → unauthed-failure  (signAuth rejected)
+ *
+ * The legacy `connect(SubscribePayload)` API is retained as a deprecated
+ * shim that routes to `connectPublic` so existing public-only callers
+ * keep working without code changes. The `wallet` field on the legacy
+ * payload is now silently ignored (it was never authenticated and
+ * post-PR-19 the server drops private subs from anonymous clients).
+ */
+export class UpDownWsClient {
+    url;
+    onMessage;
+    ws = null;
+    reconnect = 0;
+    timer = null;
+    closed = false;
+    mode = null;
+    state = "idle";
+    /** Cached token + expiry from the last successful auth_ok. Replayed on
+     *  reconnect; cleared if the server returns auth_error against it. */
+    cachedToken = null;
+    cachedTokenExpiresAt = 0;
+    constructor(url, onMessage) {
+        this.url = url;
+        this.onMessage = onMessage;
+    }
+    /**
+     * Subscribe to public channels only (`markets`, `orderbook:*`,
+     * `trades:*`). No signature required.
+     */
+    connectPublic(channels) {
+        this.closed = false;
+        this.mode = { kind: "public", channels: channels.slice() };
+        this.openSocket();
+    }
+    /**
+     * Authenticate via the PR-19 EIP-712 handshake, then subscribe.
+     * Required for `orders:*` and `balance:*` channels.
+     */
+    connectAuthed(opts) {
+        this.closed = false;
+        this.mode = {
+            kind: "authed",
+            opts: { ...opts, channels: opts.channels.slice() },
+        };
+        this.openSocket();
+    }
+    /**
+     * @deprecated Use `connectPublic(channels)` or `connectAuthed({ ... })`.
+     * Pre-PR-19 the WS server accepted `{type:'subscribe', wallet}` and
+     * auto-attached `orders:<wallet>` to the anonymous client; that path
+     * is now closed. The `wallet` field on the payload is ignored — if
+     * the channel list contains private channels they will be silently
+     * dropped by the server because the connection is unauthenticated.
+     */
+    connect(subscribe) {
+        this.connectPublic(subscribe.channels);
+    }
+    disconnect() {
+        this.closed = true;
+        this.state = "idle";
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.ws?.close();
+        this.ws = null;
+    }
+    openSocket() {
+        if (this.closed)
+            return;
+        const ws = new WebSocket(this.url);
+        this.ws = ws;
+        this.state = "idle";
+        ws.onopen = () => {
+            this.reconnect = 0;
+            void this.startHandshake();
+        };
+        ws.onmessage = (ev) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            void this.handleIncoming(parsed);
+        };
+        ws.onclose = () => {
+            if (this.closed)
+                return;
+            if (this.state === "unauthed-failure") {
+                // signAuth was rejected — don't reconnect into a hot loop.
+                return;
+            }
+            const attempt = this.reconnect++;
+            const delay = attempt > 12 ? 30_000 : Math.min(30_000, 1000 * 2 ** Math.min(attempt, 5));
+            this.timer = setTimeout(() => this.openSocket(), delay);
+        };
+        ws.onerror = () => ws.close();
+    }
+    async startHandshake() {
+        if (!this.mode || !this.ws)
+            return;
+        if (this.mode.kind === "public") {
+            this.state = "subscribing";
+            this.send({ type: "subscribe", channels: this.mode.channels });
+            // Public path: the `subscribed` reply marks us live, but for
+            // simplicity we mark live optimistically — onMessage delivery
+            // doesn't gate on it.
+            this.state = "live";
+            return;
+        }
+        // Authed path. Try token replay first if we have a non-expired cache.
+        this.state = "authenticating";
+        if (this.cachedToken && this.cachedTokenExpiresAt > Date.now()) {
+            this.send({ type: "auth", token: this.cachedToken });
+            return;
+        }
+        await this.runSignAndSendAuth();
+    }
+    async runSignAndSendAuth() {
+        if (!this.mode || this.mode.kind !== "authed")
+            return;
+        let creds;
+        try {
+            creds = await this.mode.opts.signAuth();
+        }
+        catch (err) {
+            this.state = "unauthed-failure";
+            this.mode.opts.onAuthError?.(err instanceof Error ? err.message : "signAuth threw");
+            this.ws?.close();
+            return;
+        }
+        if (creds.token) {
+            // Caller pre-cached a token — try replay first.
+            this.cachedToken = creds.token;
+            // Caller didn't supply expiry, so trust it for this attempt; if
+            // the server rejects we'll re-sign on auth_error.
+            this.cachedTokenExpiresAt = Math.max(this.cachedTokenExpiresAt, Date.now() + 60_000);
+            this.send({ type: "auth", token: creds.token });
+            return;
+        }
+        this.send({
+            type: "auth",
+            wallet: creds.wallet,
+            timestamp: creds.timestamp.toString(),
+            sessionId: creds.sessionId,
+            signature: creds.signature,
+        });
+    }
+    async handleIncoming(msg) {
+        if (msg.type === "auth_ok") {
+            const m = msg;
+            if (typeof m.token === "string") {
+                this.cachedToken = m.token;
+                // Server-supplied expiresAt is the source of truth (24h TTL).
+                // Fall back to TTL-from-now if the server omits it (token
+                // replay path doesn't echo expiresAt).
+                this.cachedTokenExpiresAt =
+                    typeof m.expiresAt === "number"
+                        ? m.expiresAt
+                        : Math.max(this.cachedTokenExpiresAt, Date.now() + 23 * 60 * 60 * 1000);
+            }
+            if (this.mode?.kind === "authed") {
+                this.state = "subscribing";
+                this.send({ type: "subscribe", channels: this.mode.opts.channels });
+                this.state = "live";
+            }
+            return;
+        }
+        if (msg.type === "auth_error") {
+            // Cached token is bad. Drop it and try a fresh sign — but only
+            // ONCE per connect cycle to avoid a sign loop if the user's
+            // wallet keeps rejecting.
+            if (this.cachedToken) {
+                this.cachedToken = null;
+                this.cachedTokenExpiresAt = 0;
+                await this.runSignAndSendAuth();
+                return;
+            }
+            // Fresh signature was rejected — terminal failure.
+            this.state = "unauthed-failure";
+            if (this.mode?.kind === "authed") {
+                this.mode.opts.onAuthError?.("auth_error");
+            }
+            this.ws?.close();
+            return;
+        }
+        this.onMessage(msg);
+    }
+    send(payload) {
+        if (this.ws && this.ws.readyState === 1 /* OPEN */) {
+            this.ws.send(JSON.stringify(payload));
+        }
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pulsepairs/sdk",
+  "version": "0.2.0",
+  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
+    "test": "node scripts/eip712-golden.test.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "example:taker": "npx tsx examples/simple-taker.ts",
+    "example:maker": "npx tsx examples/simple-maker.ts",
+    "example:dmm": "npx tsx examples/full-dmm-bot.ts"
+  },
+  "peerDependencies": {
+    "@aa-sdk/core": "^4.88.0",
+    "@account-kit/infra": "^4.88.0",
+    "@account-kit/smart-contracts": "^4.88.0",
+    "@account-kit/wallet-client": "^4.88.0",
+    "viem": "^2.21.0"
+  },
+  "peerDependenciesMeta": {
+    "@account-kit/smart-contracts": {
+      "optional": true
+    },
+    "@account-kit/wallet-client": {
+      "optional": true
+    },
+    "@account-kit/infra": {
+      "optional": true
+    },
+    "@aa-sdk/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.3",
+    "viem": "^2.47.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}