blink-trade-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alterity Systems
+
+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,140 @@
+# blink-trade-sdk
+
+Typed client for Blink API v1 and the protocol-v1 WebSocket stream.
+
+```sh
+npm install blink-trade-sdk
+```
+
+```ts
+import { RestClient, WsClient, LocalBook, channels, classifyUpdate } from 'blink-trade-sdk';
+
+const api = new RestClient('https://api.blink.trade');
+const markets = await api.markets();
+const book = await api.orderbook(markets[0].market_id, markets[0].market_type, 10);
+
+const localBook = new LocalBook();
+const ws = new WsClient('wss://api.blink.trade/v1/ws', {
+  onMessage: (message) => {
+    if (message.type !== 'update') return;
+    const update = classifyUpdate(message);
+    if (update.kind === 'orderbook') localBook.apply(update.frame); // snapshot first, then deltas
+    if (update.kind === 'trades') console.log(update.frame.trades);
+  },
+  onResubscribeRequired: ({ channel, reason }) => {
+    console.log(channel, reason); // discard local state; a fresh snapshot follows
+    void ws.resubscribe(channel);
+  },
+});
+await ws.ready();
+await ws.subscribe(channels.orderbook('perp', 1));
+await ws.subscribe('trades/perp/1');
+```
+
+`WsClient` waits for the protocol-v1 `hello` (`protocol_version: 1`,
+`keepalive_timeout_ms`) and rejects any other server. Subscriptions are
+channel strings (`markets`, `market-stats/perp/1`, `bbo/perp/1`,
+`orderbook/perp/1`, `trades/perp/1`, `candles/perp/1/1m`,
+`mark-candles/1/1m`, `funding-rates/1`, `accounts/<address>`,
+`account/<address>/<subaccount_id>`); `channels` builds them and
+`parseChannel` reads them. The first `update` after subscribing is the
+snapshot (`previous_sequence: null`). The client checks `previous_sequence`
+against the last installed `sequence` per channel; a gap, or a subscription
+the server closed (an `error` frame naming the channel), is reported through
+`onResubscribeRequired` and the frame is dropped — call `resubscribe` and
+reinstall the snapshot. Every other frame (`hello`, `update`, `unsubscribed`,
+`error`) reaches `onMessage`.
+
+`classifyUpdate` narrows an update by channel. `LocalBook` maintains a
+price-level book from `orderbook/...` frames; `AccountState` applies the
+`account/<address>/<subaccount_id>` snapshot and its `operations` deltas
+(`reset` / `insert` / `upsert` / `delete`); `AccountCatalogState` does the same
+for `accounts/<address>`.
+
+Keepalive uses transport pings where the runtime exposes `WebSocket.ping`
+(Bun, `ws`) and protocol-v1 JSON `ping`/`pong` in browsers. Both run at half
+`keepalive_timeout_ms`, keeping idle subscriptions connected.
+
+Prices are ticks, sizes are base lots, balances are token atoms, and values
+that may exceed JavaScript's safe integer range are decimal strings.
+
+See [docs.blink.trade](https://docs.blink.trade) for the REST, WebSocket, and
+transaction-signing references.
+
+Run `bun run test` and `bun run build` before publishing; `bun run test:live`
+streams the market-data channels from the production gateway.
+
+## Managed browser subscriptions
+
+`BlinkSocketManager` adds reconnect/backoff, reference-counted subscriptions,
+late-consumer snapshots, snapshot timeouts, browser keepalive and diagnostics.
+Both clients use the same physical transport (connection setup, hello validation,
+JSON parsing and heartbeat) and `WsSession` sequence validation. Use one
+manager per application/tab and dispose it when the application shuts down.
+
+```ts
+import { BlinkSocketManager, LocalBook, channels, gatewayWebSocketUrl } from 'blink-trade-sdk';
+const manager = new BlinkSocketManager(gatewayWebSocketUrl('http://localhost:3001'));
+const book = new LocalBook();
+const stop = manager.subscribe(channels.orderbook('perp', 1), frame => {
+  if (frame.type === 'update') {
+    // frame.snapshot is explicit: null sequence does not imply a new snapshot.
+    book.applyLevels(frame.snapshot, frame.data.orderbook as import('blink-trade-sdk').BookLevels);
+  }
+});
+// stop() releases this consumer; manager.dispose() closes everything.
+```
+
+The frontend uses this manager, channel builders, `LocalBook`, candle types and
+`RestClient`. Sovereign transaction signing/submission is outside this SDK's
+REST/WebSocket data API scope. List methods `orders`, `fills`, and `trades`
+return the first page and default to the gateway's maximum of 100 rows; pass a
+smaller limit as the final argument when needed.
+
+## Local end-to-end tests
+
+Start the rollup repository's `local_sdk_stack` fixture as described in
+`crates/integration-tests/README.md`. With its public endpoint manifest:
+
+```sh
+BLINK_API=http://127.0.0.1:<gateway-port> bun run test:live
+LOCAL_SDK_STACK_MANIFEST=/tmp/blink-local-stack.json bun run test:local
+```
+
+The local suite covers account/balance/position/order/fill REST projections,
+transaction lookup, spot books, mark candles, BLP, all channel families,
+account-state deltas, subscription sharing, and forced reconnect snapshots.
+It only accepts loopback endpoints and skips when no manifest is provided.
+`bun test` also discovers `test/live.test.ts`, which defaults to the public API;
+use `bun run test` for the offline suite.
+
+Git dependencies run `prepare` to generate `dist`; consumers do not need a
+local checkout or copied SDK source.
+
+## Package release checks
+
+The committed lockfile and `packageManager` pin make SDK builds reproducible.
+`bun run test:package` packs the SDK, installs the tarball in a temporary consumer
+without lifecycle scripts, and exercises the published entry point. CI runs this
+along with the offline suite. `prepublishOnly` repeats these gates for a release.
+
+The package is distributed publicly as `blink-trade-sdk` on
+`https://registry.npmjs.org/`. The source repository can remain private.
+
+For the first release, authenticate the npm account that will own the package
+with `npm login`, then run `npm publish` from a clean, validated checkout.
+`publishConfig` fixes the public registry and access level. The publish hook
+runs the offline tests, type checks and isolated package installation check.
+
+For subsequent releases, configure an npm [trusted publisher](https://docs.npmjs.com/trusted-publishers/)
+with owner `alterity-systems`, repository `blink-sdk-ts`, workflow `publish.yml`,
+and permission to run `npm publish`. Merge the workflow into the default branch,
+then dispatch it at the intended release ref with the exact package version and
+distribution tag (`latest` for stable releases, `next` for prereleases). It
+rejects a mismatched version before publishing. No npm token secret is needed.
+Npm provenance is only available when the source repository is public.
+
+Frontend consumers should pin an exact published version, e.g.
+`bun add --exact blink-trade-sdk@0.1.0`, then run their normal checks. Remove the
+vendored artifact, provenance file and `scripts/update-blink-sdk.mjs` after the
+registry installation succeeds.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/** Typed client for the Blink v1 REST API and protocol-v1 WebSocket API. */
+import type { Balance, BlpInfo, Candle, Fill, MarkCandle, Market, MarketStats, MarketType, Order, Orderbook, Position, Resolution, Status, Subaccount, Trade, Transaction } from './types.js';
+export * from './types.js';
+export * from './ws.js';
+export declare class BlinkApiError extends Error {
+    readonly status: number;
+    readonly code: number;
+    constructor(status: number, code: number, message: string);
+}
+export declare class RestClient {
+    private readonly base;
+    constructor(base: string);
+    get<T>(path: string): Promise<T>;
+    private query;
+    status(): Promise<Status>;
+    markets(marketType?: MarketType | 'all', marketId?: number): Promise<Market[]>;
+    market(marketId: number, marketType: MarketType): Promise<Market>;
+    marketStats(marketId: number, marketType: MarketType): Promise<MarketStats>;
+    orderbook(marketId: number, marketType: MarketType, depth?: number): Promise<Orderbook>;
+    trades(marketId: number, marketType: MarketType, limit?: number): Promise<Trade[]>;
+    candles(marketId: number, marketType: MarketType, resolution: Resolution, startTimestamp: number, endTimestamp: number, countBack: number): Promise<Candle[]>;
+    markPriceCandles(marketId: number, resolution: Resolution, startTimestamp: number, endTimestamp: number, countBack: number): Promise<MarkCandle[]>;
+    subaccount(address: string, subaccountId: number): Promise<Subaccount>;
+    balances(address: string, subaccountId: number): Promise<Balance[]>;
+    positions(address: string, subaccountId: number): Promise<Position[]>;
+    orders(address: string, subaccountId: number, status: 'active' | 'history' | 'all', limit?: number): Promise<Order[]>;
+    fills(address: string, subaccountId: number, limit?: number): Promise<Fill[]>;
+    transaction(hash: string): Promise<Transaction>;
+    blp(): Promise<BlpInfo>;
+}
+export { BlinkSocketManager, BLINK_WS_PROTOCOL_VERSION, gatewayWebSocketUrl } from './managed-ws.js';
+export type { BlinkSocketManagerOptions, ConnectionStatus, SocketDiagnostic, ChannelFrame, ChannelUpdate as ManagedChannelUpdate, ChannelReset, ChannelError, FrameHandler } from './managed-ws.js';

package/dist/index.js

@@ -0,0 +1,130 @@
+/** Typed client for the Blink v1 REST API and protocol-v1 WebSocket API. */
+export * from './types.js';
+export * from './ws.js';
+export class BlinkApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'BlinkApiError';
+    }
+}
+export class RestClient {
+    base;
+    constructor(base) {
+        this.base = base.replace(/\/+$/, '');
+    }
+    async get(path) {
+        const response = await fetch(this.base + path);
+        if (!response.ok) {
+            let message = response.statusText;
+            let code = response.status;
+            try {
+                const body = (await response.json());
+                code = body.code ?? code;
+                message = body.message ?? message;
+            }
+            catch {
+                // Preserve the HTTP fallback for non-JSON failures.
+            }
+            throw new BlinkApiError(response.status, code, message);
+        }
+        return (await response.json());
+    }
+    query(path, values) {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(values)) {
+            if (value !== undefined)
+                query.set(key, String(value));
+        }
+        const encoded = query.toString();
+        return encoded ? `${path}?${encoded}` : path;
+    }
+    async status() {
+        const body = await this.get('/v1/status');
+        return { status: body.status, timestamp_ns: body.timestamp_ns };
+    }
+    async markets(marketType = 'all', marketId) {
+        const body = await this.get(this.query('/v1/markets', { market_type: marketType, market_id: marketId }));
+        return body.markets;
+    }
+    async market(marketId, marketType) {
+        const market = (await this.markets(marketType, marketId))[0];
+        if (!market)
+            throw new BlinkApiError(404, 404, 'market not found');
+        return market;
+    }
+    async marketStats(marketId, marketType) {
+        const body = await this.get(this.query('/v1/marketStats', { market_type: marketType, market_id: marketId }));
+        const stats = body.market_stats[0];
+        if (!stats)
+            throw new BlinkApiError(404, 404, 'market stats not found');
+        return stats;
+    }
+    async orderbook(marketId, marketType, depth = 100) {
+        const body = await this.get(this.query('/v1/orderBook', { market_type: marketType, market_id: marketId, depth }));
+        return { timestamp_ns: body.timestamp_ns, sequence: body.sequence, ...body.orderbook };
+    }
+    async trades(marketId, marketType, limit = 100) {
+        const body = await this.get(this.query('/v1/trades', { market_type: marketType, market_id: marketId, limit }));
+        return body.trades;
+    }
+    async candles(marketId, marketType, resolution, startTimestamp, endTimestamp, countBack) {
+        const body = await this.get(this.query('/v1/candles', {
+            market_type: marketType,
+            market_id: marketId,
+            resolution,
+            start_timestamp: startTimestamp,
+            end_timestamp: endTimestamp,
+            count_back: countBack,
+        }));
+        return body.candles;
+    }
+    async markPriceCandles(marketId, resolution, startTimestamp, endTimestamp, countBack) {
+        const body = await this.get(this.query('/v1/markCandles', {
+            market_id: marketId,
+            resolution,
+            start_timestamp: startTimestamp,
+            end_timestamp: endTimestamp,
+            count_back: countBack,
+        }));
+        return body.candles;
+    }
+    async subaccount(address, subaccountId) {
+        const body = await this.get(this.query('/v1/account', { address, subaccount_id: subaccountId }));
+        const subaccount = body.subaccounts.find((row) => row.subaccount_id === subaccountId);
+        if (!subaccount)
+            throw new BlinkApiError(404, 404, 'subaccount not found');
+        return subaccount;
+    }
+    async balances(address, subaccountId) {
+        const body = await this.get(this.query('/v1/balances', { address, subaccount_id: subaccountId }));
+        return body.balances;
+    }
+    async positions(address, subaccountId) {
+        const body = await this.get(this.query('/v1/positions', { address, subaccount_id: subaccountId }));
+        return body.positions;
+    }
+    async orders(address, subaccountId, status, limit = 100) {
+        const body = await this.get(this.query('/v1/orders', { address, subaccount_id: subaccountId, status, limit }));
+        return body.orders;
+    }
+    async fills(address, subaccountId, limit = 100) {
+        const body = await this.get(this.query('/v1/fills', { address, subaccount_id: subaccountId, role: 'all', limit }));
+        return body.fills;
+    }
+    async transaction(hash) {
+        const body = await this.get(this.query('/v1/transactions', { hash }));
+        const transaction = body.transactions[0];
+        if (!transaction)
+            throw new BlinkApiError(404, 404, 'transaction not found');
+        return transaction;
+    }
+    async blp() {
+        const body = await this.get('/v1/blp');
+        return body.blp;
+    }
+}
+export { BlinkSocketManager, BLINK_WS_PROTOCOL_VERSION, gatewayWebSocketUrl } from './managed-ws.js';

package/dist/managed-ws.d.ts

@@ -0,0 +1,135 @@
+import { type WebSocketLike } from './ws-transport.js';
+/**
+ * Gateway websocket protocol v1 (`/v1/ws`, docs/v1/websocket.md).
+ *
+ * One physical socket per tab. Channel strings carry their own parameters and
+ * are both the server subscription identity and the client routing key, so a
+ * channel is subscribed at most once no matter how many consumers share it.
+ */
+export declare const BLINK_WS_PROTOCOL_VERSION = 1;
+export type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'incompatible';
+export type SocketDiagnostic = {
+    at: number;
+    level: 'info' | 'warning' | 'error';
+    code: string;
+    message: string;
+    detail?: unknown;
+};
+/**
+ * One continuity-checked `update` frame. `snapshot` is true for the frame that
+ * (re)installs the channel: the first update after subscribing. A null sequence alone does not
+ * identify a snapshot once the channel is installed. `data` holds every wire field except
+ * the envelope (`type`, `channel`, `timestamp_ns`, `sequence`,
+ * `previous_sequence`), e.g. `orderbook`, `trades`, `candles`, `operations`.
+ */
+export type ChannelUpdate = {
+    type: 'update';
+    channel: string;
+    snapshot: boolean;
+    sequence: string | null;
+    previous_sequence: string | null;
+    timestamp_ns: string | null;
+    data: Record<string, unknown>;
+};
+/**
+ * The channel's installed state is no longer continuous (socket closed,
+ * server closed the stream, sequence gap, or a consumer forced a replacement).
+ * The next frame for the channel is a fresh snapshot.
+ */
+export type ChannelReset = {
+    type: 'reset';
+    channel: string;
+    reason: string;
+};
+/** A server error scoped to the channel that is not retried automatically. */
+export type ChannelError = {
+    type: 'error';
+    channel: string;
+    code: number | null;
+    message: string;
+};
+export type ChannelFrame = ChannelUpdate | ChannelReset | ChannelError;
+export type FrameHandler = (frame: ChannelFrame) => void;
+type StatusHandler = (status: ConnectionStatus) => void;
+type DiagnosticHandler = (diagnostic: SocketDiagnostic) => void;
+export type BlinkSocketManagerOptions = {
+    socketFactory?: (url: string) => WebSocketLike;
+    random?: () => number;
+    schedule?: typeof setTimeout;
+    cancelSchedule?: typeof clearTimeout;
+    repeat?: typeof setInterval;
+    cancelRepeat?: typeof clearInterval;
+    now?: () => number;
+};
+export declare class BlinkSocketManager {
+    private readonly url;
+    private readonly options;
+    private socket;
+    private session;
+    private channels;
+    private statusHandlers;
+    private diagnosticHandlers;
+    private diagnostics;
+    private status;
+    private connectScheduled;
+    private reconnectTimer;
+    private watchdogTimer;
+    private reconnectAttempt;
+    private generation;
+    private helloAccepted;
+    private protocolRejected;
+    private keepaliveTimeoutMs;
+    constructor(url: string, options?: BlinkSocketManagerOptions);
+    /**
+     * Attach a consumer to a channel. The first consumer subscribes the channel
+     * on the server; further consumers share it. A consumer that attaches after
+     * the channel's snapshot was installed cannot rebuild that snapshot from
+     * deltas, so the server subscription is replaced and every consumer receives
+     * a fresh lifecycle (`reset`, then a snapshot `update`).
+     */
+    subscribe(channel: string, handler: FrameHandler): () => void;
+    /** Replace one channel's server subscription so it re-installs a snapshot. */
+    resubscribe(channel: string, reason: string): void;
+    onStatus(handler: StatusHandler): () => void;
+    onDiagnostic(handler: DiagnosticHandler): () => void;
+    getDiagnostics(): readonly SocketDiagnostic[];
+    getStatus(): ConnectionStatus;
+    /** Exposed for diagnostics and focused unit tests. */
+    debugState(): {
+        channels: number;
+        awaitingSnapshot: number;
+        keepaliveTimeoutMs: number;
+        status: ConnectionStatus;
+    };
+    dispose(): void;
+    private ensureConnection;
+    private connect;
+    private handleClose;
+    private handleMessage;
+    private handleUpdate;
+    private handleError;
+    private rejectProtocol;
+    private sendSubscribe;
+    private replaceSubscription;
+    private removeChannel;
+    private clearRetry;
+    /** Replace subscriptions whose snapshot never arrived. */
+    private startWatchdog;
+    private stopWatchdog;
+    private clearTimers;
+    private scheduleReconnect;
+    private canSend;
+    private send;
+    private dispatch;
+    private now;
+    private setStatus;
+    private addDiagnostic;
+}
+export declare function gatewayWebSocketUrl(apiUrl: string): string;
+export declare const __testing: {
+    SOCKET_CONNECTING: number;
+    SOCKET_OPEN: number;
+    SNAPSHOT_TIMEOUT_MS: number;
+    STREAM_RETRY_MS: number;
+};
+export {};