@imbingox/acex 0.1.0-beta.0 → 0.1.0

package/dist/adapters/binance/native-market-adapter.d.ts

@@ -0,0 +1,102 @@
+import type { AdapterAccountBaseline, ExchangeAdapter, ExchangeCapabilities, NormalizedAccountEvent, NormalizedMarketEvent, NormalizedOrderEvent } from "../types.js";
+import type { BinanceMarketFamily } from "./market-types.js";
+import { type BinanceMarketRestClient } from "./rest-client.js";
+import { type BinanceMarketWsTransport } from "./ws-client.js";
+export interface CreateBinanceNativeMarketAdapterInput {
+    restClient?: BinanceMarketRestClient;
+    createTransport?: (input: {
+        family: BinanceMarketFamily;
+    }) => BinanceMarketWsTransport;
+    now?: () => number;
+}
+export declare class BinanceNativeMarketAdapter implements ExchangeAdapter {
+    #private;
+    readonly exchange = "binance";
+    readonly capabilities: ExchangeCapabilities;
+    constructor(input?: CreateBinanceNativeMarketAdapterInput);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    fetchMarketInfo(): Promise<{
+        exchange: string;
+        symbol: string;
+        baseAsset: string;
+        quoteAsset: string;
+        marketType: "spot" | "swap" | "future";
+        pricePrecision: number;
+        amountPrecision: number;
+        active: boolean;
+    }[]>;
+    subscribeL1Book(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    subscribeFundingRate(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    watchMarketEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedMarketEvent>;
+    setMarketEventSink(sink: ((event: NormalizedMarketEvent) => void) | undefined): void;
+    watchInternalErrors(): import("../../runtime/async-queue.js").AsyncQueue<Error>;
+    subscribeOrders(_input: {
+        accountId: string;
+    }): Promise<void>;
+    fetchOpenOrdersBaseline(_accountId: string): Promise<NormalizedOrderEvent["snapshot"][]>;
+    watchOrderEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedOrderEvent>;
+    setOrderEventSink(sink: ((event: NormalizedOrderEvent) => void) | undefined): void;
+    fetchAccountBaseline(_accountId: string): Promise<AdapterAccountBaseline>;
+    watchAccountEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedAccountEvent>;
+    setAccountEventSink(sink: ((event: NormalizedAccountEvent) => void) | undefined): void;
+    placeOrder(_input: {
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        amount: string;
+        clientOrderId: string;
+        type: string;
+        price?: string;
+        reduceOnly?: boolean;
+    }): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    amendOrder(_input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+        symbol?: string;
+        newPrice?: string;
+    }): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    cancelOrder(_input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+    }): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    cancelAllOrders(_input: {
+        accountId: string;
+        exchange: string;
+    }): Promise<{
+        accountId: string;
+        exchange: string;
+        canceledCount: number;
+    }>;
+    getHealth(): {
+        exchange: string;
+        status: string;
+        wsConnected: boolean;
+    };
+    handleTransportMessage(family: BinanceMarketFamily, payload: unknown): void;
+    handleTransportClose(family: BinanceMarketFamily): void;
+    handleTransportReconnect(family: BinanceMarketFamily): Promise<void>;
+}

package/dist/adapters/binance/native-market-adapter.js

@@ -0,0 +1,455 @@
+import { createAcexError } from "../../errors/acex-error.js";
+import { createAsyncQueue } from "../../runtime/async-queue.js";
+import { normalizeBookTickerEvent, normalizeMarkPriceEvent } from "./normalizers.js";
+import { createBinanceMarketRestClient } from "./rest-client.js";
+import { buildBinanceMarketIndex, getRecordByNativeSymbol, requireFundingMarketRecord, requireMarketRecord, } from "./symbol-router.js";
+import { createBinanceMarketWsTransport, } from "./ws-client.js";
+function createUnsupportedError(message) {
+    return createAcexError({
+        code: "CAPABILITY_NOT_SUPPORTED",
+        message,
+        retryable: false,
+        exchange: "binance",
+    });
+}
+function createAdapterLifecycleError(message) {
+    return createAcexError({
+        code: "VALIDATION_ERROR",
+        message,
+        retryable: false,
+        exchange: "binance",
+    });
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function subscriptionKey(subscription) {
+    return `${subscription.family}:${subscription.nativeSymbol}:${subscription.streamKind}`;
+}
+function marketTypeFor(record) {
+    if (record.family === "spot") {
+        return "spot";
+    }
+    return record.fundingEligible ? "swap" : "future";
+}
+function createSymbolEventKey(event) {
+    return `${event.family}:${event.nativeSymbol}`;
+}
+export class BinanceNativeMarketAdapter {
+    exchange = "binance";
+    capabilities = {
+        publicWs: true,
+        privateWs: false,
+        l1BookStream: true,
+        fundingRateStream: true,
+        accountStream: false,
+        orderStream: false,
+        fetchMarketInfo: true,
+        fetchBalances: false,
+        fetchPositions: false,
+        fetchRisk: false,
+        fetchOpenOrders: false,
+        fetchMyTrades: false,
+        fetchOrderById: false,
+    };
+    #restClient;
+    #createTransport;
+    #now;
+    #started = false;
+    #stopping = false;
+    #stopTask;
+    #marketIndex;
+    #marketInfo = [];
+    #transports = new Map();
+    #transportConnections = new Map();
+    #transportTasks = new Map();
+    #reconnectTasks = new Map();
+    #subscriptions = new Map();
+    #subscriptionTasks = new Map();
+    #marketQueue = createAsyncQueue({ maxBufferSize: 100 });
+    #marketEventSink;
+    #internalErrorQueue = createAsyncQueue({ maxBufferSize: 20 });
+    #orderQueue = createAsyncQueue({ maxBufferSize: 10 });
+    #orderEventSink;
+    #accountQueue = createAsyncQueue({ maxBufferSize: 10 });
+    #accountEventSink;
+    constructor(input = {}) {
+        this.#restClient = input.restClient ?? createBinanceMarketRestClient();
+        this.#createTransport =
+            input.createTransport ??
+                ((transportInput) => createBinanceMarketWsTransport({
+                    family: transportInput.family,
+                    createSocket: (url) => new WebSocket(url),
+                    onMessage: (payload) => {
+                        this.handleTransportMessage(transportInput.family, payload);
+                    },
+                    onClose: () => {
+                        this.handleTransportClose(transportInput.family);
+                    },
+                    onReconnect: async () => {
+                        await this.handleTransportReconnect(transportInput.family);
+                    },
+                }));
+        this.#now = input.now ?? (() => Date.now());
+    }
+    async start() {
+        if (this.#stopping || this.#stopTask !== undefined) {
+            throw createAdapterLifecycleError("market adapter cannot be started after stop begins");
+        }
+        if (this.#started) {
+            return;
+        }
+        this.#marketIndex = buildBinanceMarketIndex(await this.#restClient.fetchAllExchangeInfo());
+        this.#marketInfo = this.#marketIndex.markets.map((record) => ({
+            exchange: "binance",
+            symbol: record.unifiedSymbol,
+            baseAsset: record.baseAsset,
+            quoteAsset: record.quoteAsset,
+            marketType: marketTypeFor(record),
+            pricePrecision: record.pricePrecision,
+            amountPrecision: record.amountPrecision,
+            active: record.active,
+        }));
+        this.#started = true;
+    }
+    async stop() {
+        if (this.#stopTask !== undefined) {
+            await this.#stopTask;
+            return;
+        }
+        this.#stopTask = (async () => {
+            this.#stopping = true;
+            this.#started = false;
+            await Promise.allSettled([...this.#transports.values()].map((transport) => transport.close()));
+            await Promise.allSettled([
+                ...this.#transportTasks.values(),
+                ...this.#subscriptionTasks.values(),
+                ...this.#reconnectTasks.values(),
+            ]);
+            this.#transports.clear();
+            this.#transportConnections.clear();
+            this.#transportTasks.clear();
+            this.#reconnectTasks.clear();
+            this.#subscriptions.clear();
+            this.#subscriptionTasks.clear();
+            this.#marketIndex = undefined;
+            this.#marketInfo = [];
+            this.#marketQueue.close();
+            this.#internalErrorQueue.close();
+            this.#orderQueue.close();
+            this.#accountQueue.close();
+        })();
+        try {
+            await this.#stopTask;
+        }
+        finally {
+            this.#stopTask = undefined;
+        }
+    }
+    async fetchMarketInfo() {
+        this.#requireMarketIndex();
+        return this.#marketInfo.map((market) => ({ ...market }));
+    }
+    async subscribeL1Book(input) {
+        const marketIndex = this.#requireMarketIndex();
+        const record = requireMarketRecord(marketIndex, input.symbol);
+        await this.#ensureSubscribed(record, "l1Book", `${record.nativeSymbol.toLowerCase()}@bookTicker`);
+    }
+    async subscribeFundingRate(input) {
+        const marketIndex = this.#requireMarketIndex();
+        const record = requireFundingMarketRecord(marketIndex, input.symbol);
+        await this.#ensureSubscribed(record, "fundingRate", `${record.nativeSymbol.toLowerCase()}@markPrice@1s`);
+    }
+    watchMarketEvents() {
+        return this.#marketQueue;
+    }
+    setMarketEventSink(sink) {
+        this.#marketEventSink = sink;
+    }
+    watchInternalErrors() {
+        return this.#internalErrorQueue;
+    }
+    async subscribeOrders(_input) {
+        throw createUnsupportedError("private orders stay on ccxt adapter");
+    }
+    async fetchOpenOrdersBaseline(_accountId) {
+        throw createUnsupportedError("private orders stay on ccxt adapter");
+    }
+    watchOrderEvents() {
+        return this.#orderQueue;
+    }
+    setOrderEventSink(sink) {
+        this.#orderEventSink = sink;
+    }
+    async fetchAccountBaseline(_accountId) {
+        return {
+            balances: {},
+            positions: [],
+        };
+    }
+    watchAccountEvents() {
+        return this.#accountQueue;
+    }
+    setAccountEventSink(sink) {
+        this.#accountEventSink = sink;
+    }
+    async placeOrder(_input) {
+        throw createUnsupportedError("market adapter does not place orders");
+    }
+    async amendOrder(_input) {
+        throw createUnsupportedError("market adapter does not amend orders");
+    }
+    async cancelOrder(_input) {
+        throw createUnsupportedError("market adapter does not cancel orders");
+    }
+    async cancelAllOrders(_input) {
+        throw createUnsupportedError("market adapter does not cancel all orders");
+    }
+    getHealth() {
+        if (!this.#started) {
+            return {
+                exchange: this.exchange,
+                status: "idle",
+                wsConnected: false,
+            };
+        }
+        const subscribedFamilies = new Set();
+        for (const subscription of this.#subscriptions.values()) {
+            subscribedFamilies.add(subscription.family);
+        }
+        if (subscribedFamilies.size === 0) {
+            return {
+                exchange: this.exchange,
+                status: "healthy",
+                wsConnected: true,
+            };
+        }
+        const allFamiliesConnected = [...subscribedFamilies].every((family) => this.#transportConnections.get(family) === true);
+        return {
+            exchange: this.exchange,
+            status: allFamiliesConnected ? "healthy" : "degraded",
+            wsConnected: allFamiliesConnected,
+        };
+    }
+    handleTransportMessage(family, payload) {
+        if (this.#stopping || this.#marketIndex === undefined) {
+            return;
+        }
+        const nativeSymbol = this.#readPayloadSymbol(payload);
+        if (nativeSymbol === undefined) {
+            return;
+        }
+        const record = getRecordByNativeSymbol(this.#marketIndex, family, nativeSymbol);
+        if (record === undefined) {
+            return;
+        }
+        try {
+            const receivedAt = this.#now();
+            const event = this.#isFundingPayload(payload)
+                ? normalizeMarkPriceEvent(record, payload, receivedAt)
+                : normalizeBookTickerEvent(record, payload, receivedAt);
+            this.#emitMarketEvent(event);
+        }
+        catch (error) {
+            this.#emitInternalError(error);
+        }
+    }
+    handleTransportClose(family) {
+        if (this.#stopping || this.#marketIndex === undefined) {
+            return;
+        }
+        this.#transportConnections.set(family, false);
+        const receivedAt = this.#now();
+        const emittedSymbols = new Set();
+        for (const subscription of this.#subscriptions.values()) {
+            if (subscription.family !== family) {
+                continue;
+            }
+            const symbolEventKey = createSymbolEventKey(subscription);
+            if (emittedSymbols.has(symbolEventKey)) {
+                continue;
+            }
+            const record = getRecordByNativeSymbol(this.#marketIndex, family, subscription.nativeSymbol);
+            if (record === undefined) {
+                continue;
+            }
+            emittedSymbols.add(symbolEventKey);
+            this.#emitMarketEvent({
+                type: "market.disconnected",
+                exchange: "binance",
+                symbol: record.unifiedSymbol,
+                receivedAt,
+            });
+        }
+    }
+    async handleTransportReconnect(family) {
+        if (this.#stopping || !this.#started) {
+            return;
+        }
+        const existingTask = this.#reconnectTasks.get(family);
+        if (existingTask !== undefined) {
+            await existingTask;
+            return;
+        }
+        const task = this.#runTransportReconnect(family);
+        this.#reconnectTasks.set(family, task);
+        try {
+            await task;
+        }
+        finally {
+            this.#reconnectTasks.delete(family);
+        }
+    }
+    async #runTransportReconnect(family) {
+        if (this.#stopping || this.#marketIndex === undefined) {
+            return;
+        }
+        const transport = this.#transports.get(family);
+        if (transport === undefined) {
+            return;
+        }
+        const receivedAt = this.#now();
+        const emittedSymbols = new Set();
+        let reconnectSucceeded = true;
+        for (const subscription of this.#subscriptions.values()) {
+            if (this.#stopping) {
+                return;
+            }
+            if (subscription.family !== family) {
+                continue;
+            }
+            const record = getRecordByNativeSymbol(this.#marketIndex, family, subscription.nativeSymbol);
+            if (record !== undefined) {
+                const symbolEventKey = createSymbolEventKey(subscription);
+                if (!emittedSymbols.has(symbolEventKey)) {
+                    emittedSymbols.add(symbolEventKey);
+                    this.#emitMarketEvent({
+                        type: "market.reconnecting",
+                        exchange: "binance",
+                        symbol: record.unifiedSymbol,
+                        receivedAt,
+                    });
+                }
+            }
+            try {
+                await transport.ensureSubscribed(subscription.streamName);
+            }
+            catch (error) {
+                reconnectSucceeded = false;
+                this.#emitInternalError(error);
+            }
+        }
+        this.#transportConnections.set(family, reconnectSucceeded);
+    }
+    async #ensureSubscribed(record, streamKind, streamName) {
+        if (this.#stopping) {
+            throw createAdapterLifecycleError("market adapter must be started before using market methods");
+        }
+        const subscription = {
+            family: record.family,
+            nativeSymbol: record.nativeSymbol,
+            streamKind,
+            streamName,
+        };
+        const key = subscriptionKey(subscription);
+        if (this.#subscriptions.has(key)) {
+            return;
+        }
+        const existingTask = this.#subscriptionTasks.get(key);
+        if (existingTask !== undefined) {
+            await existingTask;
+            return;
+        }
+        const task = (async () => {
+            this.#subscriptions.set(key, subscription);
+            try {
+                const transport = await this.#getOrCreateTransport(record.family);
+                if (this.#stopping) {
+                    throw createAdapterLifecycleError("market adapter must be started before using market methods");
+                }
+                await transport.ensureSubscribed(streamName);
+            }
+            catch (error) {
+                this.#subscriptions.delete(key);
+                throw error;
+            }
+        })();
+        this.#subscriptionTasks.set(key, task);
+        try {
+            await task;
+        }
+        finally {
+            this.#subscriptionTasks.delete(key);
+        }
+    }
+    async #getOrCreateTransport(family) {
+        if (this.#stopping) {
+            throw createAdapterLifecycleError("market adapter must be started before using market methods");
+        }
+        const existing = this.#transports.get(family);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const existingTask = this.#transportTasks.get(family);
+        if (existingTask !== undefined) {
+            return await existingTask;
+        }
+        const task = (async () => {
+            const transport = this.#createTransport({ family });
+            this.#transports.set(family, transport);
+            try {
+                await transport.connect();
+                if (this.#stopping) {
+                    await transport.close();
+                    throw createAdapterLifecycleError("market adapter must be started before using market methods");
+                }
+                this.#transportConnections.set(family, true);
+                return transport;
+            }
+            catch (error) {
+                this.#transports.delete(family);
+                this.#transportConnections.delete(family);
+                throw error;
+            }
+        })();
+        this.#transportTasks.set(family, task);
+        try {
+            return await task;
+        }
+        finally {
+            this.#transportTasks.delete(family);
+        }
+    }
+    #requireMarketIndex() {
+        if (!this.#started || this.#marketIndex === undefined) {
+            throw createAdapterLifecycleError("market adapter must be started before using market methods");
+        }
+        return this.#marketIndex;
+    }
+    #readPayloadSymbol(payload) {
+        if (typeof payload !== "object" || payload === null || !("s" in payload)) {
+            return undefined;
+        }
+        const symbol = payload.s;
+        return typeof symbol === "string" ? symbol : undefined;
+    }
+    #isFundingPayload(payload) {
+        return typeof payload === "object" && payload !== null && "r" in payload;
+    }
+    #emitMarketEvent(event) {
+        if (this.#stopping) {
+            return;
+        }
+        if (this.#marketEventSink !== undefined) {
+            this.#marketEventSink(event);
+            return;
+        }
+        this.#marketQueue.push(event);
+    }
+    #emitInternalError(error) {
+        if (this.#stopping) {
+            return;
+        }
+        this.#internalErrorQueue.push(toError(error));
+    }
+}

package/dist/adapters/binance/normalizers.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedMarketEvent } from "../types.js";
+import type { BinanceMarketRecord } from "./market-types.js";
+export declare function normalizeBookTickerEvent(record: BinanceMarketRecord, payload: unknown, receivedAt: number): Extract<NormalizedMarketEvent, {
+    type: "l1_book.updated";
+}>;
+export declare function normalizeMarkPriceEvent(record: BinanceMarketRecord, payload: unknown, receivedAt: number): Extract<NormalizedMarketEvent, {
+    type: "funding_rate.updated";
+}>;

package/dist/adapters/binance/normalizers.js

@@ -0,0 +1,123 @@
+import { createAcexError } from "../../errors/acex-error.js";
+function createPayloadShapeError(stream, message) {
+    return createAcexError({
+        code: "VALIDATION_ERROR",
+        message: `invalid binance ${stream} payload: ${message}`,
+        retryable: false,
+        exchange: "binance",
+    });
+}
+function createPayloadValidationError(stream, record, payloadSymbol) {
+    return createAcexError({
+        code: "VALIDATION_ERROR",
+        message: `invalid binance ${stream} payload symbol: expected ${record.nativeSymbol}, received ${payloadSymbol}`,
+        retryable: false,
+        exchange: "binance",
+    });
+}
+function assertNativeSymbolMatches(stream, record, payloadSymbol) {
+    if (payloadSymbol !== record.nativeSymbol) {
+        throw createPayloadValidationError(stream, record, payloadSymbol);
+    }
+}
+function assertFundingEligible(record) {
+    if (!record.fundingEligible) {
+        throw createAcexError({
+            code: "CAPABILITY_NOT_SUPPORTED",
+            message: "funding rate is not supported for spot or delivery markets",
+            retryable: false,
+            exchange: "binance",
+        });
+    }
+}
+function asPayloadRecord(stream, payload) {
+    if (typeof payload !== "object" || payload === null) {
+        throw createPayloadShapeError(stream, "payload must be an object");
+    }
+    return payload;
+}
+function readRequiredStringField(stream, payload, field) {
+    const value = payload[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw createPayloadShapeError(stream, `missing or invalid ${field}`);
+    }
+    return value;
+}
+function readRequiredFiniteNumberField(stream, payload, field) {
+    const value = payload[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw createPayloadShapeError(stream, `missing or invalid ${field}`);
+    }
+    return value;
+}
+function readOptionalFiniteNumberField(stream, payload, field) {
+    const value = payload[field];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw createPayloadShapeError(stream, `missing or invalid ${field}`);
+    }
+    return value;
+}
+function parseBookTickerPayload(record, payload) {
+    const parsed = asPayloadRecord("bookTicker", payload);
+    const symbol = readRequiredStringField("bookTicker", parsed, "s");
+    const bidPrice = readRequiredStringField("bookTicker", parsed, "b");
+    const bidSize = readRequiredStringField("bookTicker", parsed, "B");
+    const askPrice = readRequiredStringField("bookTicker", parsed, "a");
+    const askSize = readRequiredStringField("bookTicker", parsed, "A");
+    const exchangeTs = readOptionalFiniteNumberField("bookTicker", parsed, "E");
+    if (record.family === "spot") {
+        if (exchangeTs !== undefined) {
+            throw createPayloadShapeError("bookTicker", "spot bookTicker payload must not include E");
+        }
+    }
+    else if (exchangeTs === undefined) {
+        throw createPayloadShapeError("bookTicker", `${record.family} bookTicker payload must include E`);
+    }
+    return {
+        s: symbol,
+        b: bidPrice,
+        B: bidSize,
+        a: askPrice,
+        A: askSize,
+        ...(exchangeTs === undefined ? {} : { E: exchangeTs }),
+    };
+}
+function parseMarkPricePayload(payload) {
+    const parsed = asPayloadRecord("markPrice", payload);
+    return {
+        s: readRequiredStringField("markPrice", parsed, "s"),
+        r: readRequiredStringField("markPrice", parsed, "r"),
+        E: readRequiredFiniteNumberField("markPrice", parsed, "E"),
+    };
+}
+export function normalizeBookTickerEvent(record, payload, receivedAt) {
+    const parsed = parseBookTickerPayload(record, payload);
+    assertNativeSymbolMatches("bookTicker", record, parsed.s);
+    return {
+        type: "l1_book.updated",
+        exchange: "binance",
+        symbol: record.unifiedSymbol,
+        bidPrice: parsed.b,
+        bidSize: parsed.B,
+        askPrice: parsed.a,
+        askSize: parsed.A,
+        ...(parsed.E === undefined ? {} : { exchangeTs: parsed.E }),
+        receivedAt,
+    };
+}
+export function normalizeMarkPriceEvent(record, payload, receivedAt) {
+    assertFundingEligible(record);
+    const parsed = parseMarkPricePayload(payload);
+    assertNativeSymbolMatches("markPrice", record, parsed.s);
+    return {
+        type: "funding_rate.updated",
+        exchange: "binance",
+        symbol: record.unifiedSymbol,
+        fundingRate: parsed.r,
+        exchangeTs: parsed.E,
+        receivedAt,
+    };
+}