@imbingox/acex 0.1.0 → 0.2.0

package/src/client/runtime.ts

@@ -0,0 +1,410 @@
+import { BinanceMarketAdapter } from "../adapters/binance/adapter.ts";
+import { BinancePrivateAdapter } from "../adapters/binance/private-adapter.ts";
+import type {
+  CancelAllOrdersRequest,
+  CancelOrderRequest,
+  CreateOrderRequest,
+  PrivateUserDataAdapter,
+  RawOrderUpdate,
+} from "../adapters/types.ts";
+import { AcexError, type AcexErrorCode } from "../errors.ts";
+import { AsyncEventBus } from "../internal/async-event-bus.ts";
+import { matchesHealthFilter } from "../internal/filters.ts";
+import { AccountManagerImpl } from "../managers/account-manager.ts";
+import { MarketManagerImpl } from "../managers/market-manager.ts";
+import { OrderManagerImpl } from "../managers/order-manager.ts";
+import type {
+  AccountCredentials,
+  AccountManager,
+  AcexClient,
+  AcexInternalError,
+  CancelAllOrdersInput,
+  CancelOrderInput,
+  ClientEventStreams,
+  ClientHealthSnapshot,
+  ClientStatus,
+  ClientStatusChangedEvent,
+  CreateClientOptions,
+  CreateOrderInput,
+  HealthEvent,
+  HealthEventFilter,
+  MarketManager,
+  OrderManager,
+  RegisterAccountInput,
+  RegisterAccountResult,
+  StopOptions,
+} from "../types/index.ts";
+import {
+  type ClientContext,
+  hasPrivateCredentials,
+  mergeCredentials,
+  type PrivateAccountDataConsumer,
+  type PrivateOrderDataConsumer,
+  type RegisteredAccountRecord,
+} from "./context.ts";
+import { PrivateSubscriptionCoordinator } from "./private-subscription-coordinator.ts";
+
+const activeClients = new Set<AcexClientImpl>();
+
+export function stopAllClientsForTests(): void {
+  const clients = [...activeClients];
+  activeClients.clear();
+  for (const client of clients) {
+    void client.stop().catch(() => {
+      // Test cleanup should be best-effort and never mask the original failure.
+    });
+  }
+}
+
+class ClientEventStreamsImpl implements ClientEventStreams {
+  constructor(
+    private readonly healthBus: AsyncEventBus<HealthEvent>,
+    private readonly errorBus: AsyncEventBus<AcexInternalError>,
+  ) {}
+
+  errors(): AsyncIterable<AcexInternalError> {
+    return this.errorBus.stream();
+  }
+
+  health(filter?: HealthEventFilter): AsyncIterable<HealthEvent> {
+    return this.healthBus.stream((event) => matchesHealthFilter(event, filter));
+  }
+}
+
+export class AcexClientImpl implements AcexClient, ClientContext {
+  readonly market: MarketManager;
+  readonly account: AccountManager;
+  readonly order: OrderManager;
+  readonly events: ClientEventStreams;
+
+  private status: ClientStatus = "idle";
+  private readonly healthBus = new AsyncEventBus<HealthEvent>();
+  private readonly errorBus = new AsyncEventBus<AcexInternalError>();
+  private readonly registeredAccounts = new Map<
+    string,
+    RegisteredAccountRecord
+  >();
+  private readonly marketManager: MarketManagerImpl;
+  private readonly accountManager: AccountManagerImpl;
+  private readonly orderManager: OrderManagerImpl;
+  private readonly privateAdapter: PrivateUserDataAdapter;
+  private readonly privateCoordinator: PrivateSubscriptionCoordinator;
+
+  constructor(options: CreateClientOptions = {}) {
+    activeClients.add(this);
+
+    const marketAdapter = new BinanceMarketAdapter();
+    this.privateAdapter = new BinancePrivateAdapter();
+
+    this.marketManager = new MarketManagerImpl(this, marketAdapter, {
+      initialL1TimeoutMs: options.market?.l1InitialMessageTimeoutMs,
+      l1StaleAfterMs: options.market?.l1StaleAfterMs,
+      l1ReconnectDelayMs: options.market?.l1ReconnectDelayMs,
+      l1ReconnectMaxDelayMs: options.market?.l1ReconnectMaxDelayMs,
+    });
+    this.accountManager = new AccountManagerImpl(this);
+    this.orderManager = new OrderManagerImpl(this);
+    this.privateCoordinator = new PrivateSubscriptionCoordinator(
+      this,
+      this.privateAdapter,
+      this.accountManager as PrivateAccountDataConsumer,
+      this.orderManager as PrivateOrderDataConsumer,
+      options.account,
+    );
+
+    this.market = this.marketManager;
+    this.account = this.accountManager;
+    this.order = this.orderManager;
+    this.events = new ClientEventStreamsImpl(this.healthBus, this.errorBus);
+  }
+
+  // --- AcexClient public API ---
+
+  getStatus(): ClientStatus {
+    return this.status;
+  }
+
+  getHealth(): ClientHealthSnapshot {
+    return {
+      clientStatus: this.status,
+      markets: this.marketManager.getStatuses(),
+      accounts: this.accountManager.getStatuses(),
+      orders: this.orderManager.getStatuses(),
+      updatedAt: this.now(),
+    };
+  }
+
+  async registerAccount(
+    input: RegisterAccountInput,
+  ): Promise<RegisterAccountResult> {
+    if (this.registeredAccounts.has(input.accountId)) {
+      throw this.createError(
+        "ACCOUNT_ALREADY_EXISTS",
+        `Account already exists: ${input.accountId}`,
+        { accountId: input.accountId, exchange: input.exchange },
+      );
+    }
+
+    this.registeredAccounts.set(input.accountId, {
+      accountId: input.accountId,
+      exchange: input.exchange,
+      credentials: input.credentials,
+      options: input.options,
+    });
+
+    return {
+      accountId: input.accountId,
+      exchange: input.exchange,
+    };
+  }
+
+  async updateAccountCredentials(
+    accountId: string,
+    credentials: AccountCredentials,
+  ): Promise<void> {
+    const account = this.registeredAccounts.get(accountId);
+    if (!account) {
+      throw this.createError(
+        "ACCOUNT_NOT_FOUND",
+        `Account not found: ${accountId}`,
+        { accountId },
+      );
+    }
+
+    account.credentials = mergeCredentials(account.credentials, credentials);
+
+    if (this.status !== "running") {
+      return;
+    }
+
+    this.accountManager.onCredentialsUpdated(accountId, account.exchange);
+    this.orderManager.onCredentialsUpdated(accountId, account.exchange);
+    this.privateCoordinator.onCredentialsUpdated(accountId);
+  }
+
+  async removeAccount(accountId: string): Promise<void> {
+    const account = this.registeredAccounts.get(accountId);
+    if (!account) {
+      throw this.createError(
+        "ACCOUNT_NOT_FOUND",
+        `Account not found: ${accountId}`,
+        { accountId },
+      );
+    }
+
+    const now = this.now();
+    this.privateCoordinator.onAccountRemoved(accountId);
+    this.accountManager.onAccountRemoved(accountId, now);
+    this.orderManager.onAccountRemoved(accountId, now);
+    this.registeredAccounts.delete(accountId);
+  }
+
+  async start(): Promise<void> {
+    if (this.status === "running") {
+      return;
+    }
+
+    this.setClientStatus("starting");
+    this.setClientStatus("running");
+
+    this.marketManager.onClientStarted();
+    this.accountManager.onClientStarted();
+    this.orderManager.onClientStarted();
+    this.privateCoordinator.onClientStarted();
+  }
+
+  async stop(_options?: StopOptions): Promise<void> {
+    if (this.status === "stopped" || this.status === "idle") {
+      if (this.status !== "stopped") {
+        this.setClientStatus("stopped");
+      }
+      return;
+    }
+
+    this.setClientStatus("stopping");
+
+    const now = this.now();
+    this.privateCoordinator.onClientStopping();
+    this.marketManager.onClientStopping(now);
+    this.accountManager.onClientStopping(now);
+    this.orderManager.onClientStopping(now);
+
+    this.setClientStatus("stopped");
+  }
+
+  // --- ClientContext ---
+
+  now(): number {
+    return Date.now();
+  }
+
+  assertStarted(): void {
+    if (this.status !== "running") {
+      throw this.createError(
+        "CLIENT_NOT_STARTED",
+        "Client must be started before subscribing to data",
+      );
+    }
+  }
+
+  getRegisteredAccount(accountId: string): RegisteredAccountRecord {
+    const account = this.registeredAccounts.get(accountId);
+    if (!account) {
+      throw this.createError(
+        "ACCOUNT_NOT_FOUND",
+        `Account not found: ${accountId}`,
+        { accountId },
+      );
+    }
+
+    return account;
+  }
+
+  ensurePrivateCredentials(accountId: string): void {
+    const account = this.getRegisteredAccount(accountId);
+    if (hasPrivateCredentials(account.credentials)) {
+      return;
+    }
+
+    throw this.createError(
+      "CREDENTIALS_MISSING",
+      `Account credentials are required for private subscriptions: ${accountId}`,
+      { accountId, exchange: account.exchange },
+    );
+  }
+
+  subscribePrivateAccountFeed(accountId: string): Promise<void> {
+    return this.privateCoordinator.subscribeAccountFeed(accountId);
+  }
+
+  unsubscribePrivateAccountFeed(accountId: string): void {
+    this.privateCoordinator.unsubscribeAccountFeed(accountId);
+  }
+
+  subscribePrivateOrderFeed(accountId: string): Promise<void> {
+    return this.privateCoordinator.subscribeOrderFeed(accountId);
+  }
+
+  unsubscribePrivateOrderFeed(accountId: string): void {
+    this.privateCoordinator.unsubscribeOrderFeed(accountId);
+  }
+
+  createOrder(input: CreateOrderInput): Promise<RawOrderUpdate> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CreateOrderRequest = {
+      symbol: input.symbol,
+      side: input.side,
+      type: input.type,
+      amount: input.amount,
+      price: input.type === "limit" ? input.price : undefined,
+      clientOrderId: input.clientOrderId,
+      reduceOnly: input.reduceOnly,
+      positionSide: input.positionSide,
+    };
+
+    return this.privateAdapter.createOrder(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
+  cancelOrder(input: CancelOrderInput): Promise<RawOrderUpdate> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CancelOrderRequest = {
+      symbol: input.symbol,
+      orderId: input.orderId,
+      clientOrderId: input.clientOrderId,
+    };
+
+    return this.privateAdapter.cancelOrder(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
+  cancelAllOrders(input: CancelAllOrdersInput): Promise<RawOrderUpdate[]> {
+    const account = this.getPrivateCommandAccount(input.accountId);
+    const request: CancelAllOrdersRequest = {
+      symbol: input.symbol,
+    };
+
+    return this.privateAdapter.cancelAllOrders(
+      account.credentials ?? {},
+      request,
+      account.options,
+    );
+  }
+
+  publishRuntimeError(
+    source: AcexInternalError["source"],
+    error: Error,
+    metadata?: Omit<AcexInternalError, "error" | "source" | "ts">,
+  ): void {
+    this.errorBus.publish({
+      source,
+      ts: this.now(),
+      error,
+      ...metadata,
+    });
+  }
+
+  publishHealthEvent(event: HealthEvent): void {
+    this.healthBus.publish(event);
+  }
+
+  // --- Private ---
+
+  private setClientStatus(status: ClientStatus): void {
+    if (this.status === status) {
+      return;
+    }
+
+    this.status = status;
+
+    const event: ClientStatusChangedEvent = {
+      type: "client.status_changed",
+      status,
+      ts: this.now(),
+    };
+
+    this.healthBus.publish(event);
+  }
+
+  private createError(
+    code: AcexErrorCode,
+    message: string,
+    metadata?: Omit<AcexInternalError, "error" | "source" | "ts">,
+  ): AcexError {
+    const error = new AcexError(code, message);
+    this.errorBus.publish({
+      source: "client",
+      ts: this.now(),
+      error,
+      ...metadata,
+    });
+    return error;
+  }
+
+  private getPrivateCommandAccount(accountId: string): RegisteredAccountRecord {
+    const account = this.getRegisteredAccount(accountId);
+    if (account.exchange !== this.privateAdapter.exchange) {
+      throw this.createError(
+        "EXCHANGE_NOT_SUPPORTED",
+        `Exchange is not supported yet: ${account.exchange}`,
+        { accountId, exchange: account.exchange },
+      );
+    }
+
+    if (!hasPrivateCredentials(account.credentials)) {
+      throw this.createError(
+        "CREDENTIALS_MISSING",
+        `Account credentials are required for private order commands: ${accountId}`,
+        { accountId, exchange: account.exchange },
+      );
+    }
+
+    return account;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+export type AcexErrorCode =
+  | "ACCOUNT_ALREADY_EXISTS"
+  | "ACCOUNT_BOOTSTRAP_FAILED"
+  | "ACCOUNT_NOT_FOUND"
+  | "CLIENT_NOT_STARTED"
+  | "CREDENTIALS_MISSING"
+  | "EXCHANGE_NOT_SUPPORTED"
+  | "MARKET_CATALOG_LOAD_FAILED"
+  | "MARKET_INACTIVE"
+  | "MARKET_FUNDING_RATE_UNSUPPORTED"
+  | "MARKET_NOT_FOUND"
+  | "MARKET_STREAM_TIMEOUT"
+  | "ORDER_BOOTSTRAP_FAILED"
+  | "ORDER_CANCEL_ALL_FAILED"
+  | "ORDER_CANCEL_FAILED"
+  | "ORDER_CREATE_FAILED"
+  | "ORDER_INPUT_INVALID";
+
+export class AcexError extends Error {
+  readonly code: AcexErrorCode;
+
+  constructor(code: AcexErrorCode, message: string) {
+    super(message);
+    this.name = "AcexError";
+    this.code = code;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { BigNumber } from "bignumber.js";
+export { createClient } from "./client/create-client.ts";
+export type { AcexErrorCode } from "./errors.ts";
+export { AcexError } from "./errors.ts";
+export * from "./types/index.ts";

package/src/internal/async-event-bus.ts

@@ -0,0 +1,100 @@
+type EventPredicate<T> = (event: T) => boolean;
+
+interface BusListener<T> {
+  close(): void;
+  dispatch(event: T): void;
+}
+
+function doneResult<T>(): IteratorResult<T> {
+  return { done: true, value: undefined as T };
+}
+
+export class AsyncEventBus<T> {
+  private readonly listeners = new Set<BusListener<T>>();
+
+  publish(event: T): void {
+    for (const listener of this.listeners) {
+      listener.dispatch(event);
+    }
+  }
+
+  stream<U extends T = T>(
+    filter: ((event: T) => event is U) | EventPredicate<T> = () => true,
+  ): AsyncIterable<U> {
+    let closed = false;
+    const queue: U[] = [];
+    let pendingResolve: ((result: IteratorResult<U>) => void) | undefined;
+
+    const close = () => {
+      if (closed) {
+        return;
+      }
+
+      closed = true;
+      this.listeners.delete(listener);
+
+      if (pendingResolve) {
+        const resolve = pendingResolve;
+        pendingResolve = undefined;
+        resolve(doneResult<U>());
+      }
+    };
+
+    const listener: BusListener<T> = {
+      close,
+      dispatch: (event) => {
+        if (closed || !filter(event)) {
+          return;
+        }
+
+        const typedEvent = event as U;
+        if (pendingResolve) {
+          const resolve = pendingResolve;
+          pendingResolve = undefined;
+          resolve({ done: false, value: typedEvent });
+          return;
+        }
+
+        queue.push(typedEvent);
+      },
+    };
+
+    this.listeners.add(listener);
+
+    const iterator: AsyncIterableIterator<U> = {
+      [Symbol.asyncIterator]() {
+        return iterator;
+      },
+      next: async () => {
+        if (closed) {
+          return doneResult<U>();
+        }
+
+        const queued = queue.shift();
+        if (queued !== undefined) {
+          return { done: false, value: queued };
+        }
+
+        return await new Promise<IteratorResult<U>>((resolve) => {
+          pendingResolve = resolve;
+        });
+      },
+      return: async () => {
+        close();
+        return doneResult<U>();
+      },
+      throw: async (error?: unknown) => {
+        close();
+        throw error;
+      },
+    };
+
+    return iterator;
+  }
+
+  close(): void {
+    for (const listener of [...this.listeners]) {
+      listener.close();
+    }
+  }
+}

package/src/internal/filters.ts

@@ -0,0 +1,117 @@
+import type {
+  AccountEventFilter,
+  Exchange,
+  HealthEvent,
+  HealthEventFilter,
+  MarketEventFilter,
+  OrderEventFilter,
+} from "../types/index.ts";
+
+export function matchesMarketFilter(
+  event: { exchange: Exchange; symbol: string },
+  filter?: MarketEventFilter,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  if (filter.exchange && event.exchange !== filter.exchange) {
+    return false;
+  }
+
+  if (filter.symbol && event.symbol !== filter.symbol) {
+    return false;
+  }
+
+  return true;
+}
+
+export function matchesAccountFilter(
+  event: { accountId: string; exchange: Exchange; symbol?: string },
+  filter?: AccountEventFilter,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  if (filter.accountId && event.accountId !== filter.accountId) {
+    return false;
+  }
+
+  if (filter.exchange && event.exchange !== filter.exchange) {
+    return false;
+  }
+
+  if (filter.symbol && event.symbol !== filter.symbol) {
+    return false;
+  }
+
+  return true;
+}
+
+export function matchesOrderFilter(
+  event: { accountId: string; exchange: Exchange; symbol?: string },
+  filter?: OrderEventFilter,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  if (filter.accountId && event.accountId !== filter.accountId) {
+    return false;
+  }
+
+  if (filter.exchange && event.exchange !== filter.exchange) {
+    return false;
+  }
+
+  if (filter.symbol && event.symbol !== filter.symbol) {
+    return false;
+  }
+
+  return true;
+}
+
+export function matchesHealthFilter(
+  event: HealthEvent,
+  filter?: HealthEventFilter,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  if (filter.scope) {
+    const actualScope =
+      event.type === "client.status_changed"
+        ? "client"
+        : event.type === "market.status_changed"
+          ? "market"
+          : event.type === "account.status_changed"
+            ? "account"
+            : "order";
+
+    if (actualScope !== filter.scope) {
+      return false;
+    }
+  }
+
+  if (filter.exchange) {
+    if (!("exchange" in event) || event.exchange !== filter.exchange) {
+      return false;
+    }
+  }
+
+  if (filter.accountId) {
+    if (!("accountId" in event) || event.accountId !== filter.accountId) {
+      return false;
+    }
+  }
+
+  if (filter.symbol) {
+    if (!("symbol" in event) || event.symbol !== filter.symbol) {
+      return false;
+    }
+  }
+
+  return true;
+}