blink-trade-sdk 0.1.0

package/dist/ws.js

@@ -0,0 +1,482 @@
+/**
+ * WebSocket protocol v1 (`/v1/ws`): frames, per-channel continuity, the
+ * client, and local state appliers. See `docs/v1/websocket.md`.
+ *
+ * The client subscribes by channel string; every server push is an `update`
+ * frame whose data fields are merged into the frame; stateful channels carry
+ * `previous_sequence` / `sequence`. `WsSession` is the transport-free state
+ * machine that tracks continuity per channel and turns a sequence gap or a
+ * server-closed subscription into a "resubscribe required" signal;
+ * `WsClient` drives it over a socket.
+ */
+import { WsTransport } from './ws-transport.js';
+export { WS_PROTOCOL_VERSION } from './ws-transport.js';
+/** `true` when the frame replaces local state: the first frame after subscribing, or any frame on a channel without sequences. */
+export function isSnapshot(frame) {
+    return frame.previous_sequence == null;
+}
+/** Narrow an account-channel frame: the snapshot carries the collections, later frames carry `operations`. */
+export function isAccountSnapshot(frame) {
+    return !('operations' in frame);
+}
+export function isAccountsSnapshot(frame) {
+    return !('operations' in frame);
+}
+/** Narrow an `update` frame by its channel name. */
+export function classifyUpdate(frame) {
+    const channel = parseChannel(frame.channel);
+    switch (channel?.kind) {
+        case 'markets':
+            return { kind: 'markets', frame: frame };
+        case 'market-stats':
+            return { kind: 'market-stats', frame: frame };
+        case 'bbo':
+            return { kind: 'bbo', frame: frame };
+        case 'orderbook':
+            return { kind: 'orderbook', frame: frame };
+        case 'trades':
+            return { kind: 'trades', frame: frame };
+        case 'candles':
+            return { kind: 'candles', frame: frame };
+        case 'mark-candles':
+            return { kind: 'mark-candles', frame: frame };
+        case 'funding-rates':
+            return { kind: 'funding-rates', frame: frame };
+        case 'accounts':
+            return { kind: 'accounts', frame: frame };
+        case 'account':
+            return { kind: 'account', frame: frame };
+        default:
+            return { kind: 'unknown', frame };
+    }
+}
+/** Channel-name builders. */
+export const channels = {
+    markets: () => 'markets',
+    marketStats: (marketType, marketId) => marketId === undefined ? `market-stats/${marketType}` : `market-stats/${marketType}/${marketId}`,
+    bbo: (marketType, marketId) => `bbo/${marketType}/${marketId}`,
+    orderbook: (marketType, marketId) => `orderbook/${marketType}/${marketId}`,
+    trades: (marketType, marketId) => `trades/${marketType}/${marketId}`,
+    candles: (marketType, marketId, resolution) => `candles/${marketType}/${marketId}/${resolution}`,
+    markCandles: (marketId, resolution) => `mark-candles/${marketId}/${resolution}`,
+    fundingRates: (marketId) => `funding-rates/${marketId}`,
+    accounts: (address) => `accounts/${address}`,
+    account: (address, subaccountId) => `account/${address}/${subaccountId}`,
+};
+/** Parse a channel name; `undefined` for names this SDK does not know. */
+export function parseChannel(channel) {
+    const parts = channel.split('/');
+    const marketType = (part) => part === 'perp' || part === 'spot' ? part : undefined;
+    const id = (part) => part !== undefined && /^[0-9]+$/.test(part) ? Number(part) : undefined;
+    const [head, a, b, c] = parts;
+    switch (head) {
+        case 'markets':
+            return parts.length === 1 ? { kind: 'markets' } : undefined;
+        case 'market-stats': {
+            const kind = marketType(a);
+            if (!kind)
+                return undefined;
+            if (parts.length === 2)
+                return { kind: 'market-stats', marketType: kind };
+            const marketId = id(b);
+            return parts.length === 3 && marketId !== undefined ? { kind: 'market-stats', marketType: kind, marketId } : undefined;
+        }
+        case 'bbo':
+        case 'orderbook':
+        case 'trades': {
+            const kind = marketType(a);
+            const marketId = id(b);
+            return parts.length === 3 && kind && marketId !== undefined ? { kind: head, marketType: kind, marketId } : undefined;
+        }
+        case 'candles': {
+            const kind = marketType(a);
+            const marketId = id(b);
+            return parts.length === 4 && kind && marketId !== undefined && c
+                ? { kind: 'candles', marketType: kind, marketId, resolution: c }
+                : undefined;
+        }
+        case 'mark-candles': {
+            const marketId = id(a);
+            return parts.length === 3 && marketId !== undefined && b ? { kind: 'mark-candles', marketId, resolution: b } : undefined;
+        }
+        case 'funding-rates': {
+            const marketId = id(a);
+            return parts.length === 2 && marketId !== undefined ? { kind: 'funding-rates', marketId } : undefined;
+        }
+        case 'accounts':
+            return parts.length === 2 && a ? { kind: 'accounts', address: a } : undefined;
+        case 'account': {
+            const subaccountId = id(b);
+            return parts.length === 3 && a && subaccountId !== undefined ? { kind: 'account', address: a, subaccountId } : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Transport-free protocol state: subscribed channels, the last installed
+ * sequence per channel, and continuity checks. Feed it every server frame
+ * with `ingest`.
+ */
+export class WsSession {
+    state = new Map();
+    /** Record a `subscribe` command. */
+    subscribe(channel) {
+        const state = this.state.get(channel);
+        if (state)
+            state.subscribed = true;
+        else
+            this.state.set(channel, { subscribed: true, pendingUnsubscribes: 0, installed: false, lastSequence: null });
+    }
+    /** Record an `unsubscribe` command; the channel stays tracked until the server's `unsubscribed` frame. */
+    unsubscribe(channel) {
+        const state = this.state.get(channel);
+        if (!state)
+            return;
+        state.subscribed = false;
+        state.pendingUnsubscribes += 1;
+        state.installed = false;
+        state.lastSequence = null;
+    }
+    /** Channels currently subscribed. */
+    channels() {
+        return [...this.state.entries()].filter(([, state]) => state.subscribed).map(([channel]) => channel);
+    }
+    /** Last installed sequence; `undefined` when nothing is installed, `null` when the channel has no sequence yet. */
+    lastSequence(channel) {
+        const state = this.state.get(channel);
+        return state?.installed ? state.lastSequence : undefined;
+    }
+    isInstalled(channel) {
+        return this.state.get(channel)?.installed ?? false;
+    }
+    /** Decode one server frame and update continuity. */
+    ingest(message) {
+        switch (message.type) {
+            case 'update': {
+                const state = this.state.get(message.channel);
+                const stateful = 'previous_sequence' in message;
+                if (!state)
+                    return { type: 'message', message };
+                if (!stateful) {
+                    state.installed = true;
+                    return { type: 'message', message };
+                }
+                const previous = message.previous_sequence ?? null;
+                const sequence = message.sequence ?? null;
+                if (!state.installed && previous === null) {
+                    state.installed = true;
+                    state.lastSequence = sequence;
+                    return { type: 'message', message };
+                }
+                if (state.installed && state.lastSequence === previous) {
+                    state.lastSequence = sequence;
+                    return { type: 'message', message };
+                }
+                const expected = state.installed ? state.lastSequence : null;
+                state.installed = false;
+                state.lastSequence = null;
+                return {
+                    type: 'resubscribe_required',
+                    channel: message.channel,
+                    reason: { kind: 'sequence_gap', expected, previous_sequence: previous, sequence },
+                };
+            }
+            case 'unsubscribed': {
+                const state = this.state.get(message.channel);
+                if (state) {
+                    state.pendingUnsubscribes = Math.max(0, state.pendingUnsubscribes - 1);
+                    if (!state.subscribed)
+                        this.state.delete(message.channel);
+                }
+                return { type: 'message', message };
+            }
+            case 'error': {
+                // 409 means the subscription already exists and stays live; every other channel error ends it.
+                if (message.channel !== undefined && message.code !== 409) {
+                    const state = this.state.get(message.channel);
+                    if (state) {
+                        this.state.delete(message.channel);
+                        if (state.installed) {
+                            return {
+                                type: 'resubscribe_required',
+                                channel: message.channel,
+                                reason: { kind: 'subscription_closed', code: message.code, message: message.message },
+                            };
+                        }
+                    }
+                }
+                return { type: 'message', message };
+            }
+            default:
+                return { type: 'message', message };
+        }
+    }
+}
+export class WsClient {
+    transport;
+    session = new WsSession();
+    constructor(url, options) {
+        const Socket = options.WebSocket;
+        this.transport = new WsTransport(url, {
+            socketFactory: Socket ? url => new Socket(url) : undefined,
+            keepaliveIntervalMs: options.keepaliveIntervalMs,
+            onMessage: message => {
+                const event = this.session.ingest(message);
+                if (event.type === 'message')
+                    options.onMessage(event.message);
+                else
+                    options.onResubscribeRequired?.({ channel: event.channel, reason: event.reason });
+            },
+            onClose: event => options.onClose?.(event),
+            onError: options.onError,
+            onProtocolError: options.onError,
+            onDiagnostic: (_code, message, detail) => options.onError?.(detail instanceof Error ? detail : new Error(message)),
+        });
+    }
+    /** Resolves with the server's `hello` once the connection is usable. */
+    ready() {
+        return this.transport.ready();
+    }
+    hello() {
+        return this.transport.hello();
+    }
+    /** Channels currently subscribed. */
+    channels() {
+        return this.session.channels();
+    }
+    /** Last installed sequence for a channel (see `WsSession.lastSequence`). */
+    lastSequence(channel) {
+        return this.session.lastSequence(channel);
+    }
+    isInstalled(channel) {
+        return this.session.isInstalled(channel);
+    }
+    /** Subscribe to a channel (`channels.orderbook('perp', 1)`); the first `update` is the snapshot. A duplicate subscribe yields a `409` error frame. */
+    async subscribe(channel) {
+        await this.transport.ready();
+        this.transport.send({ type: 'subscribe', channel });
+        this.session.subscribe(channel);
+    }
+    /** Unsubscribe; the server acknowledges with an `unsubscribed` frame. */
+    async unsubscribe(channel) {
+        await this.transport.ready();
+        this.transport.send({ type: 'unsubscribe', channel });
+        this.session.unsubscribe(channel);
+    }
+    /** Recover from `onResubscribeRequired`: unsubscribe (a no-op if the server already closed the channel) and subscribe again. */
+    async resubscribe(channel) {
+        await this.unsubscribe(channel);
+        await this.subscribe(channel);
+    }
+    close() {
+        this.transport.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Local state
+// ---------------------------------------------------------------------------
+/** A price-level order book built from `orderbook/...` updates. */
+export class LocalBook {
+    bidLevels = new Map();
+    askLevels = new Map();
+    sequence = null;
+    /** Apply an update: a snapshot replaces the book, a delta sets absolute sizes (size `0` removes the level). */
+    apply(frame) {
+        this.applyLevels(isSnapshot(frame), frame.orderbook);
+        this.sequence = frame.sequence ?? null;
+    }
+    applyLevels(snapshot, levels) {
+        if (snapshot) {
+            this.bidLevels.clear();
+            this.askLevels.clear();
+        }
+        for (const [side, updates] of [
+            [this.bidLevels, levels.bids],
+            [this.askLevels, levels.asks],
+        ]) {
+            for (const level of updates) {
+                if (BigInt(level.size_base_lots) === 0n)
+                    side.delete(level.price_ticks);
+                else
+                    side.set(level.price_ticks, level.size_base_lots);
+            }
+        }
+    }
+    /** Bids, best (highest price) first. */
+    bids() {
+        return sortedLevels(this.bidLevels, (a, b) => (a > b ? -1 : a < b ? 1 : 0));
+    }
+    /** Asks, best (lowest price) first. */
+    asks() {
+        return sortedLevels(this.askLevels, (a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    }
+    bestBid() {
+        return this.bids()[0];
+    }
+    bestAsk() {
+        return this.asks()[0];
+    }
+    isEmpty() {
+        return this.bidLevels.size === 0 && this.askLevels.size === 0;
+    }
+}
+function sortedLevels(levels, compare) {
+    return [...levels.entries()]
+        .map(([price_ticks, size_base_lots]) => ({ price_ticks, size_base_lots, price: BigInt(price_ticks) }))
+        .sort((a, b) => compare(a.price, b.price))
+        .map(({ price_ticks, size_base_lots }) => ({ price_ticks, size_base_lots }));
+}
+/** Documented per-collection keys for `upsert` / `delete` matching. */
+const COLLECTION_KEYS = {
+    account: ['subaccount_id'],
+    balances: ['token_id'],
+    positions: ['market_id'],
+    leverages: ['market_id'],
+    orders: ['market_type', 'client_order_id'],
+    delegations: ['subaccount_id', 'delegate'],
+    subaccounts: ['subaccount_id'],
+    fills: ['id', 'role'],
+    funding_payments: ['id'],
+};
+const APPEND_ONLY = new Set(['fills', 'funding_payments']);
+function rowMatches(collection, row, key) {
+    const fields = (COLLECTION_KEYS[collection] ?? []).filter((field) => key[field] !== undefined);
+    return fields.length > 0 && fields.every((field) => String(row[field]) === String(key[field]));
+}
+/**
+ * Apply one operation to a generic collection. Append-only collections are
+ * kept newest first (like the snapshot): an `insert` goes to the front, and a
+ * row whose key is already present (a replayed transaction) is dropped.
+ */
+export function applyOperation(rows, operation) {
+    const { collection, op } = operation;
+    switch (op) {
+        case 'reset':
+            return (operation.rows ?? []);
+        case 'insert':
+        case 'upsert': {
+            const row = requireRow(operation);
+            if (APPEND_ONLY.has(collection)) {
+                if (rows.some((existing) => rowMatches(collection, existing, row)))
+                    return rows;
+                return [row, ...rows];
+            }
+            const index = rows.findIndex((existing) => rowMatches(collection, existing, row));
+            if (index === -1)
+                return [...rows, row];
+            const next = rows.slice();
+            next[index] = row;
+            return next;
+        }
+        case 'delete': {
+            const key = requireRow(operation);
+            return rows.filter((existing) => !rowMatches(collection, existing, key));
+        }
+        default:
+            return rows;
+    }
+}
+function requireRow(operation) {
+    if (!operation.row)
+        throw new Error(`${operation.collection} ${operation.op} without row`);
+    return operation.row;
+}
+/**
+ * Typed state of one subaccount, maintained from the
+ * `account/{address}/{subaccount_id}` channel: the snapshot fills every
+ * collection, later frames carry `operations` applied in order with each
+ * collection's documented key. `fills` and `funding_payments` are kept newest
+ * first and grow with every insert; `truncateHistory` bounds them. Operations
+ * on unknown collections are ignored.
+ */
+export class AccountState {
+    account;
+    delegations = [];
+    balances = [];
+    positions = [];
+    leverages = [];
+    orders = [];
+    fills = [];
+    funding_payments = [];
+    apply(frame) {
+        if (isAccountSnapshot(frame))
+            this.install(frame);
+        else
+            for (const operation of frame.operations)
+                this.applyOperation(operation);
+    }
+    install(snapshot) {
+        this.account = snapshot.account;
+        this.delegations = snapshot.delegations ?? [];
+        this.balances = snapshot.balances ?? [];
+        this.positions = snapshot.positions ?? [];
+        this.leverages = snapshot.leverages ?? [];
+        this.orders = snapshot.orders ?? [];
+        this.fills = snapshot.fills ?? [];
+        this.funding_payments = snapshot.funding_payments ?? [];
+    }
+    applyOperation(operation) {
+        switch (operation.collection) {
+            case 'account':
+                if (operation.op === 'reset')
+                    this.account = operation.rows?.[0] ?? undefined;
+                else if (operation.op === 'delete')
+                    this.account = undefined;
+                else
+                    this.account = requireRow(operation);
+                break;
+            case 'delegations':
+                this.delegations = applyOperation(this.delegations, operation);
+                break;
+            case 'balances':
+                this.balances = applyOperation(this.balances, operation);
+                break;
+            case 'positions':
+                this.positions = applyOperation(this.positions, operation);
+                break;
+            case 'leverages':
+                this.leverages = applyOperation(this.leverages, operation);
+                break;
+            case 'orders':
+                this.orders = applyOperation(this.orders, operation);
+                break;
+            case 'fills':
+                this.fills = applyOperation(this.fills, operation);
+                break;
+            case 'funding_payments':
+                this.funding_payments = applyOperation(this.funding_payments, operation);
+                break;
+            default:
+                break;
+        }
+    }
+    /** Keep only the `maxRows` most recent `fills` and `funding_payments`. */
+    truncateHistory(maxRows) {
+        this.fills = this.fills.slice(0, maxRows);
+        this.funding_payments = this.funding_payments.slice(0, maxRows);
+    }
+}
+/** The `accounts/{address}` catalog, maintained from its snapshot and `reset` operations. */
+export class AccountCatalogState {
+    subaccounts = [];
+    delegations = [];
+    apply(frame) {
+        if (isAccountsSnapshot(frame)) {
+            this.subaccounts = frame.subaccounts ?? [];
+            this.delegations = frame.delegations ?? [];
+        }
+        else {
+            for (const operation of frame.operations)
+                this.applyOperation(operation);
+        }
+    }
+    applyOperation(operation) {
+        if (operation.collection === 'subaccounts') {
+            this.subaccounts = applyOperation(this.subaccounts, operation);
+        }
+        else if (operation.collection === 'delegations') {
+            this.delegations = applyOperation(this.delegations, operation);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "blink-trade-sdk",
+  "version": "0.1.0",
+  "description": "Blink exchange SDK: typed REST + WebSocket client for api.blink.trade",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alterity-systems/blink-sdk-ts.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test test/unit.test.ts test/managed-ws.test.ts test/ws-transport.test.ts",
+    "test:live": "bun test test/live.test.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepare": "npm run build",
+    "test:local": "bun test test/local.test.ts",
+    "test:package": "npm run build && node scripts/check-package.mjs",
+    "prepublishOnly": "npm run typecheck && bun run test && npm run test:package"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/bun": "^1.1.0"
+  },
+  "license": "MIT",
+  "packageManager": "bun@1.3.14",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}