@imbingox/acex 0.1.0-beta.0 → 0.1.0

package/dist/core/client.d.ts

@@ -1,3 +1,4 @@
+import { type BinanceUsdmExchangeLike, type CreateBinanceUsdmExchangeInput } from "../adapters/ccxt/binance-usdm-exchange.js";
 import type { ExchangeAdapter } from "../adapters/types.js";
 import { type AccountManager } from "../managers/account-manager.js";
 import { type MarketManager } from "../managers/market-manager.js";
@@ -5,6 +6,9 @@ import { type OrderManager } from "../managers/order-manager.js";
 import { createHealthStore } from "../store/health-store.js";
 import type { ClientStatus, Exchange } from "../types/public.js";
 import { createRuntime } from "./runtime.js";
+export interface CreateClientOptions {
+    sandbox?: boolean;
+}
 export interface RegisterAccountInput {
     accountId: string;
     exchange: Exchange;
@@ -14,24 +18,33 @@ export interface RegisterAccountInput {
         password?: string;
     };
 }
+export interface RegisterAccountResult {
+    accountId: string;
+    exchange: Exchange;
+}
 interface InternalCreateClientOptions {
     adapter?: ExchangeAdapter;
 }
+interface CreatePublicClientDependencies {
+    createExchange?: (input: CreateBinanceUsdmExchangeInput) => BinanceUsdmExchangeLike;
+    createAdapter?: (input: {
+        accountId: string;
+        exchange: BinanceUsdmExchangeLike;
+    }) => ExchangeAdapter;
+}
 export interface AcexClient {
     readonly market: MarketManager;
     readonly account: AccountManager;
     readonly order: OrderManager;
     getStatus(): ClientStatus;
     getHealth(): ReturnType<ReturnType<typeof createHealthStore>["snapshot"]>;
-    registerAccount(input: RegisterAccountInput): Promise<{
-        accountId: string;
-        exchange: Exchange;
-    }>;
+    registerAccount(input: RegisterAccountInput): Promise<RegisterAccountResult>;
     start(): Promise<void>;
     stop(): Promise<void>;
     watchErrors(): ReturnType<ReturnType<typeof createRuntime>["watchErrors"]>;
     watchHealth(): ReturnType<ReturnType<typeof createRuntime>["watchHealth"]>;
 }
 export declare function createInternalClient(options?: InternalCreateClientOptions): AcexClient;
-export declare function createClient(): AcexClient;
+export declare function createPublicClient(options?: CreateClientOptions, dependencies?: CreatePublicClientDependencies): AcexClient;
+export declare function createClient(options?: CreateClientOptions): AcexClient;
 export {};

package/dist/core/client.js

@@ -1,8 +1,16 @@
+import { BinanceCompositeAdapter } from "../adapters/binance/composite-adapter.js";
+import { BinanceNativeMarketAdapter } from "../adapters/binance/native-market-adapter.js";
+import { CcxtBinanceUsdMAdapter } from "../adapters/ccxt/binance-usdm-ccxt-adapter.js";
+import { createBinanceUsdmExchange, } from "../adapters/ccxt/binance-usdm-exchange.js";
+import { createAcexError, isAcexError } from "../errors/acex-error.js";
 import { createIdleAccountManager } from "../managers/account-manager.js";
 import { createIdleMarketManager } from "../managers/market-manager.js";
 import { createIdleOrderManager } from "../managers/order-manager.js";
+import { createAsyncQueue } from "../runtime/async-queue.js";
 import { createHealthStore } from "../store/health-store.js";
+import { IMPLEMENTED_EXCHANGES } from "../types/public.js";
 import { createRuntime } from "./runtime.js";
+const PUBLIC_EXCHANGE = IMPLEMENTED_EXCHANGES[0];
 async function* emptyAsyncIterable() { }
 export function createInternalClient(options = {}) {
     let status = "idle";
@@ -40,6 +48,356 @@ export function createInternalClient(options = {}) {
         },
     };
 }
-export function createClient() {
-    return createInternalClient();
+export function createPublicClient(options = {}, dependencies = {}) {
+    const idleMarket = createIdleMarketManager();
+    const idleAccount = createIdleAccountManager();
+    const idleOrder = createIdleOrderManager();
+    const accountEvents = createAsyncQueue({ maxBufferSize: 100 });
+    const errors = createAsyncQueue({ maxBufferSize: 100 });
+    const healthStore = createHealthStore();
+    const healthEvents = createAsyncQueue({ maxBufferSize: 100 });
+    const accounts = new Map();
+    let status = "idle";
+    let activeClient;
+    let activeAdapter;
+    const market = {
+        async subscribeL1Book(input) {
+            assertSupportedExchange(input.exchange);
+            const client = await requireStartedClient();
+            await client.market.subscribeL1Book(input);
+            syncHealth();
+        },
+        async subscribeFundingRate(input) {
+            assertSupportedExchange(input.exchange);
+            const client = await requireStartedClient();
+            await client.market.subscribeFundingRate(input);
+            syncHealth();
+        },
+        getL1Book(key) {
+            return getCurrentClient().market.getL1Book(key);
+        },
+        getFundingRate(key) {
+            return getCurrentClient().market.getFundingRate(key);
+        },
+        getMarketSnapshot(key) {
+            return getCurrentClient().market.getMarketSnapshot(key);
+        },
+        getMarketStatus(key) {
+            return getCurrentClient().market.getMarketStatus(key);
+        },
+    };
+    const account = {
+        async subscribeAccount(input) {
+            getRegisteredAccount(input.accountId);
+            const client = await requireStartedClient();
+            await client.account.subscribeAccount(input);
+            syncHealth();
+        },
+        getBalance(accountId, asset) {
+            return getCurrentClient().account.getBalance(accountId, asset);
+        },
+        getBalances(accountId) {
+            return getCurrentClient().account.getBalances(accountId);
+        },
+        getPosition(input) {
+            return getCurrentClient().account.getPosition(input);
+        },
+        getPositions(accountId) {
+            return getCurrentClient().account.getPositions(accountId);
+        },
+        getAccountSnapshot(accountId) {
+            return getCurrentClient().account.getAccountSnapshot(accountId);
+        },
+        getAccountStatus(accountId) {
+            return getCurrentClient().account.getAccountStatus(accountId);
+        },
+        getRiskSnapshot(accountId) {
+            return getCurrentClient().account.getRiskSnapshot(accountId);
+        },
+        watchAccountEvents() {
+            return accountEvents;
+        },
+    };
+    const order = {
+        async subscribeOrders(input) {
+            getRegisteredAccount(input.accountId);
+            const client = await requireStartedClient();
+            await client.order.subscribeOrders(input);
+            syncHealth();
+        },
+        async placeOrder(input) {
+            getRegisteredAccount(input.accountId);
+            assertSupportedExchange(input.exchange);
+            const client = await requireStartedClient();
+            const ack = await client.order.placeOrder(input);
+            syncHealth();
+            return ack;
+        },
+        async amendOrder(input) {
+            getRegisteredAccount(input.accountId);
+            assertSupportedExchange(input.exchange);
+            const client = await requireStartedClient();
+            const ack = await client.order.amendOrder(input);
+            syncHealth();
+            return ack;
+        },
+        async cancelOrder(input) {
+            getRegisteredAccount(input.accountId);
+            assertSupportedExchange(input.exchange);
+            const client = await requireStartedClient();
+            const ack = await client.order.cancelOrder(input);
+            syncHealth();
+            return ack;
+        },
+        async cancelAllOrders(input) {
+            getRegisteredAccount(input.accountId);
+            assertSupportedExchange(input.exchange);
+            const result = await requireStartedClient().then((client) => client.order.cancelAllOrders(input));
+            syncHealth();
+            return result;
+        },
+        getOrder(input) {
+            return getCurrentClient().order.getOrder(input);
+        },
+        getOpenOrders(accountId) {
+            return getCurrentClient().order.getOpenOrders(accountId);
+        },
+        getOrderStatus(accountId) {
+            return getCurrentClient().order.getOrderStatus(accountId);
+        },
+    };
+    function getCurrentClient() {
+        return (activeClient ?? {
+            market: idleMarket,
+            account: idleAccount,
+            order: idleOrder,
+        });
+    }
+    function bridgeEvents(source, push) {
+        void (async () => {
+            try {
+                for await (const value of source) {
+                    push(value);
+                }
+            }
+            catch { }
+        })();
+    }
+    function attachClientBridges(client) {
+        bridgeEvents(client.account.watchAccountEvents(), (event) => {
+            accountEvents.push(event);
+        });
+        bridgeEvents(client.watchErrors(), (event) => {
+            errors.push(event);
+        });
+        bridgeEvents(client.watchHealth(), (event) => {
+            healthEvents.push(event);
+        });
+    }
+    function getRegisteredAccount(accountId) {
+        const account = accounts.get(accountId);
+        if (account === undefined) {
+            throw createAcexError({
+                code: "ACCOUNT_NOT_FOUND",
+                message: `account not found: ${accountId}`,
+                retryable: false,
+                accountId,
+            });
+        }
+        return account;
+    }
+    function getOnlyRegisteredAccount() {
+        const registered = [...accounts.values()][0];
+        if (registered === undefined) {
+            throw createAcexError({
+                code: "VALIDATION_ERROR",
+                message: "registerAccount() must be called before start()",
+                retryable: false,
+            });
+        }
+        return registered;
+    }
+    function assertNonEmpty(value, field) {
+        if (value.trim().length === 0) {
+            throw createAcexError({
+                code: "VALIDATION_ERROR",
+                message: `missing required field: ${field}`,
+                retryable: false,
+            });
+        }
+    }
+    function assertSupportedExchange(exchange) {
+        if (exchange !== PUBLIC_EXCHANGE) {
+            throw createAcexError({
+                code: "EXCHANGE_NOT_SUPPORTED",
+                message: `unsupported exchange: ${exchange}`,
+                retryable: false,
+                exchange,
+            });
+        }
+    }
+    function syncHealth() {
+        healthStore.setClientStatus(status);
+        if (activeAdapter !== undefined) {
+            healthStore.setExchangeHealth(activeAdapter.exchange, activeAdapter.getHealth());
+        }
+        if (activeClient === undefined) {
+            return;
+        }
+        for (const accountId of accounts.keys()) {
+            const accountStatus = activeClient.account.getAccountStatus(accountId);
+            if (accountStatus !== undefined) {
+                healthStore.setAccountStatus(accountId, accountStatus);
+            }
+            const orderStatus = activeClient.order.getOrderStatus(accountId);
+            if (orderStatus !== undefined) {
+                healthStore.setOrderStatus(accountId, orderStatus);
+            }
+        }
+    }
+    async function ensureActiveClient() {
+        if (activeClient !== undefined) {
+            return activeClient;
+        }
+        const registered = getOnlyRegisteredAccount();
+        try {
+            const exchangeInput = {
+                apiKey: registered.credentials.apiKey,
+                secret: registered.credentials.secret,
+                ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+            };
+            const exchange = dependencies.createExchange?.(exchangeInput) ?? createBinanceUsdmExchange(exchangeInput);
+            activeAdapter =
+                dependencies.createAdapter?.({
+                    accountId: registered.accountId,
+                    exchange,
+                }) ??
+                    new BinanceCompositeAdapter({
+                        marketAdapter: new BinanceNativeMarketAdapter(),
+                        privateAdapter: new CcxtBinanceUsdMAdapter({
+                            accountId: registered.accountId,
+                            exchange: exchange,
+                        }),
+                    });
+            activeClient = createInternalClient({ adapter: activeAdapter });
+            attachClientBridges(activeClient);
+            return activeClient;
+        }
+        catch (error) {
+            throw toClientError(error, {
+                exchange: registered.exchange,
+                accountId: registered.accountId,
+            });
+        }
+    }
+    async function requireStartedClient() {
+        if (status !== "running") {
+            throw createAcexError({
+                code: "VALIDATION_ERROR",
+                message: "client.start() must be called before using runtime APIs",
+                retryable: false,
+            });
+        }
+        return ensureActiveClient();
+    }
+    return {
+        market,
+        account,
+        order,
+        getStatus: () => status,
+        getHealth() {
+            syncHealth();
+            return healthStore.snapshot();
+        },
+        watchErrors() {
+            return errors;
+        },
+        watchHealth() {
+            return healthEvents;
+        },
+        async registerAccount(input) {
+            assertNonEmpty(input.accountId, "accountId");
+            assertNonEmpty(input.credentials.apiKey, "credentials.apiKey");
+            assertNonEmpty(input.credentials.secret, "credentials.secret");
+            assertSupportedExchange(input.exchange);
+            if (accounts.has(input.accountId)) {
+                throw createAcexError({
+                    code: "VALIDATION_ERROR",
+                    message: `duplicate accountId: ${input.accountId}`,
+                    retryable: false,
+                    accountId: input.accountId,
+                    exchange: input.exchange,
+                });
+            }
+            if (accounts.size > 0) {
+                throw createAcexError({
+                    code: "CAPABILITY_NOT_SUPPORTED",
+                    message: "public createClient() currently supports one registered account",
+                    retryable: false,
+                    exchange: input.exchange,
+                });
+            }
+            accounts.set(input.accountId, input);
+            if (status === "running" && activeClient === undefined) {
+                const client = await ensureActiveClient();
+                await client.start();
+            }
+            syncHealth();
+            return {
+                accountId: input.accountId,
+                exchange: input.exchange,
+            };
+        },
+        async start() {
+            if (status === "running") {
+                return;
+            }
+            const registered = getOnlyRegisteredAccount();
+            status = "starting";
+            syncHealth();
+            try {
+                const client = await ensureActiveClient();
+                await client.start();
+                status = "running";
+                syncHealth();
+            }
+            catch (error) {
+                status = "idle";
+                syncHealth();
+                throw toClientError(error, {
+                    exchange: registered.exchange,
+                    accountId: registered.accountId,
+                });
+            }
+        },
+        async stop() {
+            if (status === "stopped") {
+                return;
+            }
+            status = "stopping";
+            syncHealth();
+            await activeClient?.stop();
+            status = "stopped";
+            syncHealth();
+        },
+    };
+}
+export function createClient(options = {}) {
+    return createPublicClient(options);
+}
+function toClientError(error, context) {
+    if (isAcexError(error)) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return createAcexError({
+        code: message.includes("ccxt.pro.binanceusdm is not available")
+            ? "CAPABILITY_NOT_SUPPORTED"
+            : "INTERNAL_ERROR",
+        message,
+        retryable: false,
+        ...(context.exchange === undefined ? {} : { exchange: context.exchange }),
+        ...(context.accountId === undefined ? {} : { accountId: context.accountId }),
+        cause: error,
+    });
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createClient } from "./core/client.js";
 export { createAcexError, isAcexError } from "./errors/acex-error.js";
 export { IMPLEMENTED_EXCHANGES } from "./types/public.js";
-export type { AcexErrorCode, ClientStatus, Exchange, ImplementedExchange, Logger, } from "./types/public.js";
+export type { AcexClient, CreateClientOptions, RegisterAccountInput, RegisterAccountResult, } from "./core/client.js";
+export type { AcexErrorCode, ClientStatus, Exchange, ImplementedExchange, } from "./types/public.js";
 export type { AcexError, CreateAcexErrorInput } from "./errors/acex-error.js";

package/dist/runtime/ws-connection-supervisor.d.ts

@@ -0,0 +1,76 @@
+export type WsConnectionState = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+export interface WsSocketLike {
+    readyState: number;
+    send(data: string | ArrayBufferLike | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    ping?(data?: string | ArrayBufferLike | Uint8Array): void;
+    pong?(data?: string | ArrayBufferLike | Uint8Array): void;
+    terminate?(): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: string | Buffer | ArrayBuffer | ArrayBufferView;
+    }) => void) | null;
+    onping?: ((event: {
+        data?: string | Buffer | ArrayBuffer | ArrayBufferView;
+    }) => void) | null;
+    onpong?: ((event: {
+        data?: string | Buffer | ArrayBuffer | ArrayBufferView;
+    }) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+type CustomHeartbeatCleanup = (() => void | Promise<void>) | undefined;
+type CustomHeartbeatContext = {
+    socket: WsSocketLike;
+    markActivity: () => void;
+    send: (data: string | ArrayBufferLike | Uint8Array) => void;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    reportError: (error: unknown) => void;
+};
+type HeartbeatConfig = {
+    kind: "passive_read_timeout";
+    idleTimeoutMs: number;
+} | {
+    kind: "native_ping_pong";
+    heartbeatIntervalMs: number;
+    idleTimeoutMs: number;
+} | {
+    kind: "app_ping_message";
+    heartbeatIntervalMs: number;
+    idleTimeoutMs: number;
+    buildPingMessage: () => string | ArrayBufferLike | Uint8Array;
+} | {
+    kind: "custom";
+    idleTimeoutMs: number;
+    heartbeatIntervalMs?: number;
+    start: (context: CustomHeartbeatContext) => CustomHeartbeatCleanup | Promise<CustomHeartbeatCleanup>;
+};
+interface CreateWsConnectionSupervisorInput {
+    createSocket: () => WsSocketLike;
+    heartbeat: HeartbeatConfig;
+    backoff: {
+        baseDelayMs: number;
+        maxDelayMs: number;
+        jitter: boolean;
+    };
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    onOpen?: () => void;
+    onMessage?: (event: {
+        data: string | Buffer | ArrayBuffer | ArrayBufferView;
+    }) => void;
+    onClose?: () => void;
+    onDisconnect?: () => void;
+    onReconnect?: () => void | Promise<void>;
+    onError?: (error: Error) => void;
+}
+export interface WsConnectionSupervisor {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    send(data: string | ArrayBufferLike | Uint8Array): void;
+    getState(): WsConnectionState;
+    getLastActivityAt(): number | undefined;
+}
+export declare function createWsConnectionSupervisor(input: CreateWsConnectionSupervisorInput): WsConnectionSupervisor;
+export {};