@imbingox/acex 0.1.0 → 0.2.0

package/src/types/account.ts

@@ -0,0 +1,157 @@
+import type BigNumber from "bignumber.js";
+import type {
+  Exchange,
+  PrivateRuntimeReason,
+  PrivateRuntimeStatus,
+  SubscriptionActivity,
+} from "./shared.ts";
+
+export interface AccountDataStatus {
+  accountId: string;
+  exchange: Exchange;
+  activity: SubscriptionActivity;
+  ready: boolean;
+  runtimeStatus?: PrivateRuntimeStatus;
+  lastReceivedAt?: number;
+  lastReadyAt?: number;
+  inactiveSince?: number;
+  reason?: PrivateRuntimeReason;
+}
+
+export interface AccountStatusChangedEvent {
+  type: "account.status_changed";
+  accountId: string;
+  exchange: Exchange;
+  status: AccountDataStatus;
+  ts: number;
+}
+
+export type PositionSide = "long" | "short" | "net";
+
+export interface SubscribeAccountInput {
+  accountId: string;
+}
+
+export interface UnsubscribeAccountInput {
+  accountId: string;
+}
+
+export interface PositionKeyInput {
+  accountId: string;
+  symbol: string;
+  side?: PositionSide;
+}
+
+export interface AccountEventFilter {
+  accountId?: string;
+  exchange?: Exchange;
+  symbol?: string;
+}
+
+export interface BalanceSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  asset: string;
+  free: BigNumber;
+  used: BigNumber;
+  total: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface PositionSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  symbol: string;
+  side: PositionSide;
+  size: BigNumber;
+  entryPrice?: BigNumber;
+  markPrice?: BigNumber;
+  unrealizedPnl?: BigNumber;
+  leverage?: BigNumber;
+  liquidationPrice?: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface RiskSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  equity?: BigNumber;
+  marginRatio?: BigNumber;
+  initialMargin?: BigNumber;
+  maintenanceMargin?: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface AccountSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  balances: Record<string, BalanceSnapshot>;
+  positions: PositionSnapshot[];
+  risk?: RiskSnapshot;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+}
+
+export interface AccountEventBase {
+  accountId: string;
+  exchange: Exchange;
+  ts: number;
+}
+
+export interface BalanceUpdatedEvent extends AccountEventBase {
+  type: "balance.updated";
+  asset: string;
+  snapshot: BalanceSnapshot;
+}
+
+export interface PositionUpdatedEvent extends AccountEventBase {
+  type: "position.updated";
+  symbol: string;
+  snapshot: PositionSnapshot;
+}
+
+export interface RiskUpdatedEvent extends AccountEventBase {
+  type: "risk.updated";
+  snapshot: RiskSnapshot;
+}
+
+export interface AccountSnapshotReplacedEvent extends AccountEventBase {
+  type: "account.snapshot_replaced";
+  snapshot: AccountSnapshot;
+}
+
+export type AccountEvent =
+  | BalanceUpdatedEvent
+  | PositionUpdatedEvent
+  | RiskUpdatedEvent
+  | AccountSnapshotReplacedEvent;
+
+export interface AccountEventStreams {
+  updates(filter?: AccountEventFilter): AsyncIterable<AccountEvent>;
+  status(filter?: AccountEventFilter): AsyncIterable<AccountStatusChangedEvent>;
+}
+
+export interface AccountManager {
+  readonly events: AccountEventStreams;
+
+  subscribeAccount(input: SubscribeAccountInput): Promise<void>;
+  unsubscribeAccount(input: UnsubscribeAccountInput): Promise<void>;
+
+  getAccountSnapshot(accountId: string): AccountSnapshot | undefined;
+  getBalances(accountId: string): BalanceSnapshot[];
+  getBalance(accountId: string, asset: string): BalanceSnapshot | undefined;
+  getPositions(accountId: string, symbol?: string): PositionSnapshot[];
+  getPosition(input: PositionKeyInput): PositionSnapshot | undefined;
+  getRiskSnapshot(accountId: string): RiskSnapshot | undefined;
+  getAccountStatus(accountId: string): AccountDataStatus | undefined;
+}

package/src/types/client.ts

@@ -0,0 +1,79 @@
+import type {
+  AccountDataStatus,
+  AccountManager,
+  AccountStatusChangedEvent,
+} from "./account.ts";
+import type {
+  MarketDataStatus,
+  MarketManager,
+  MarketStatusChangedEvent,
+} from "./market.ts";
+import type {
+  OrderDataStatus,
+  OrderManager,
+  OrderStatusChangedEvent,
+} from "./order.ts";
+import type {
+  AccountCredentials,
+  AcexInternalError,
+  ClientStatus,
+  CreateClientOptions,
+  Exchange,
+  RegisterAccountInput,
+  RegisterAccountResult,
+  StopOptions,
+} from "./shared.ts";
+
+export interface ClientHealthSnapshot {
+  clientStatus: ClientStatus;
+  markets: MarketDataStatus[];
+  accounts: AccountDataStatus[];
+  orders: OrderDataStatus[];
+  updatedAt: number;
+}
+
+export interface ClientStatusChangedEvent {
+  type: "client.status_changed";
+  status: ClientStatus;
+  ts: number;
+}
+
+export type HealthEvent =
+  | ClientStatusChangedEvent
+  | MarketStatusChangedEvent
+  | AccountStatusChangedEvent
+  | OrderStatusChangedEvent;
+
+export interface HealthEventFilter {
+  scope?: "client" | "market" | "account" | "order";
+  exchange?: Exchange;
+  accountId?: string;
+  symbol?: string;
+}
+
+export interface ClientEventStreams {
+  health(filter?: HealthEventFilter): AsyncIterable<HealthEvent>;
+  errors(): AsyncIterable<AcexInternalError>;
+}
+
+export interface AcexClient {
+  readonly market: MarketManager;
+  readonly account: AccountManager;
+  readonly order: OrderManager;
+  readonly events: ClientEventStreams;
+
+  getStatus(): ClientStatus;
+  getHealth(): ClientHealthSnapshot;
+
+  registerAccount(input: RegisterAccountInput): Promise<RegisterAccountResult>;
+  updateAccountCredentials(
+    accountId: string,
+    credentials: AccountCredentials,
+  ): Promise<void>;
+  removeAccount(accountId: string): Promise<void>;
+
+  start(): Promise<void>;
+  stop(options?: StopOptions): Promise<void>;
+}
+
+export type CreateClient = (options?: CreateClientOptions) => AcexClient;

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./account.ts";
+export * from "./client.ts";
+export * from "./market.ts";
+export * from "./order.ts";
+export * from "./shared.ts";

package/src/types/market.ts

@@ -0,0 +1,150 @@
+import type BigNumber from "bignumber.js";
+import type {
+  Exchange,
+  MarketFreshness,
+  SubscriptionActivity,
+} from "./shared.ts";
+
+export type MarketType = "spot" | "swap" | "future";
+
+export interface MarketDefinition {
+  exchange: Exchange;
+  symbol: string;
+  id: string;
+  type: MarketType;
+  base: string;
+  quote: string;
+  settle?: string;
+  active: boolean;
+  contract: boolean;
+  linear?: boolean;
+  inverse?: boolean;
+  contractSize?: BigNumber;
+  pricePrecision: number;
+  amountPrecision: number;
+  priceStep: BigNumber;
+  amountStep: BigNumber;
+  minAmount?: BigNumber;
+  minNotional?: BigNumber;
+  expiry?: number;
+  raw: Record<string, unknown>;
+}
+
+export interface MarketDataStatus {
+  exchange: Exchange;
+  symbol: string;
+  activity: SubscriptionActivity;
+  ready: boolean;
+  freshness?: MarketFreshness;
+  lastReceivedAt?: number;
+  lastReadyAt?: number;
+  inactiveSince?: number;
+  reason?: "ws_disconnected" | "heartbeat_timeout" | "reconciling";
+}
+
+export interface MarketDataStreamStatus {
+  activity: SubscriptionActivity;
+  ready: boolean;
+  freshness?: MarketFreshness;
+  lastReceivedAt?: number;
+  lastReadyAt?: number;
+  inactiveSince?: number;
+  reason?: MarketDataStatus["reason"];
+}
+
+export interface MarketKeyInput {
+  exchange: Exchange;
+  symbol: string;
+}
+
+export interface SubscribeL1BookInput extends MarketKeyInput {}
+
+export interface SubscribeFundingRateInput extends MarketKeyInput {}
+
+export interface MarketEventFilter {
+  exchange?: Exchange;
+  symbol?: string;
+}
+
+export interface L1Book {
+  exchange: Exchange;
+  symbol: string;
+  bidPrice: BigNumber;
+  bidSize: BigNumber;
+  askPrice: BigNumber;
+  askSize: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  version: number;
+  status: MarketDataStreamStatus;
+}
+
+export interface FundingRateSnapshot {
+  exchange: Exchange;
+  symbol: string;
+  fundingRate: BigNumber;
+  nextFundingTime?: number;
+  markPrice?: BigNumber;
+  indexPrice?: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  version: number;
+  status: MarketDataStreamStatus;
+}
+
+export interface MarketStatusChangedEvent {
+  type: "market.status_changed";
+  exchange: Exchange;
+  symbol: string;
+  status: MarketDataStatus;
+  ts: number;
+}
+
+export interface L1BookUpdatedEvent {
+  type: "l1_book.updated";
+  exchange: Exchange;
+  symbol: string;
+  snapshot: L1Book;
+  ts: number;
+}
+
+export interface FundingRateUpdatedEvent {
+  type: "funding_rate.updated";
+  exchange: Exchange;
+  symbol: string;
+  snapshot: FundingRateSnapshot;
+  ts: number;
+}
+
+export type MarketEvent =
+  | L1BookUpdatedEvent
+  | FundingRateUpdatedEvent
+  | MarketStatusChangedEvent;
+
+export interface MarketEventStreams {
+  l1BookUpdates(filter?: MarketEventFilter): AsyncIterable<L1BookUpdatedEvent>;
+  fundingRateUpdates(
+    filter?: MarketEventFilter,
+  ): AsyncIterable<FundingRateUpdatedEvent>;
+  status(filter?: MarketEventFilter): AsyncIterable<MarketStatusChangedEvent>;
+  all(filter?: MarketEventFilter): AsyncIterable<MarketEvent>;
+}
+
+export interface MarketManager {
+  readonly events: MarketEventStreams;
+
+  loadMarkets(): Promise<void>;
+  subscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
+  unsubscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
+  subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;
+  unsubscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;
+
+  getMarket(exchange: Exchange, symbol: string): MarketDefinition | undefined;
+  findMarkets(symbol: string): MarketDefinition[];
+  listMarkets(exchange?: Exchange): MarketDefinition[];
+  getL1Book(key: MarketKeyInput): L1Book | undefined;
+  getFundingRate(key: MarketKeyInput): FundingRateSnapshot | undefined;
+  getMarketStatus(key: MarketKeyInput): MarketDataStatus | undefined;
+}

package/src/types/order.ts

@@ -0,0 +1,177 @@
+import type BigNumber from "bignumber.js";
+import type { PositionSide } from "./account.ts";
+import type {
+  Exchange,
+  PrivateRuntimeReason,
+  PrivateRuntimeStatus,
+  SubscriptionActivity,
+} from "./shared.ts";
+
+export interface OrderDataStatus {
+  accountId: string;
+  exchange: Exchange;
+  activity: SubscriptionActivity;
+  ready: boolean;
+  runtimeStatus?: PrivateRuntimeStatus;
+  lastReceivedAt?: number;
+  lastReadyAt?: number;
+  inactiveSince?: number;
+  reason?: PrivateRuntimeReason;
+}
+
+export interface OrderStatusChangedEvent {
+  type: "order.status_changed";
+  accountId: string;
+  exchange: Exchange;
+  status: OrderDataStatus;
+  ts: number;
+}
+
+export type OrderSide = "buy" | "sell";
+
+export type OrderStatus =
+  | "open"
+  | "partially_filled"
+  | "filled"
+  | "canceled"
+  | "rejected"
+  | "expired";
+
+export type CreateOrderType = "limit" | "market";
+
+export interface SubscribeOrdersInput {
+  accountId: string;
+}
+
+export interface UnsubscribeOrdersInput {
+  accountId: string;
+}
+
+export interface GetOrderInput {
+  accountId: string;
+  orderId?: string;
+  clientOrderId?: string;
+}
+
+interface CreateOrderInputBase {
+  accountId: string;
+  symbol: string;
+  side: OrderSide;
+  amount: string;
+  clientOrderId?: string;
+  reduceOnly?: boolean;
+  positionSide?: PositionSide;
+}
+
+export interface CreateLimitOrderInput extends CreateOrderInputBase {
+  type: "limit";
+  price: string;
+}
+
+export interface CreateMarketOrderInput extends CreateOrderInputBase {
+  type: "market";
+}
+
+export type CreateOrderInput = CreateLimitOrderInput | CreateMarketOrderInput;
+
+export interface CancelOrderInput {
+  accountId: string;
+  symbol: string;
+  orderId?: string;
+  clientOrderId?: string;
+}
+
+export interface CancelAllOrdersInput {
+  accountId: string;
+  symbol: string;
+}
+
+export interface OrderEventFilter {
+  accountId?: string;
+  exchange?: Exchange;
+  symbol?: string;
+}
+
+export interface OrderSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  orderId?: string;
+  clientOrderId?: string;
+  symbol: string;
+  side: OrderSide;
+  type: string;
+  status: OrderStatus;
+  price?: BigNumber;
+  triggerPrice?: BigNumber;
+  amount: BigNumber;
+  filled: BigNumber;
+  remaining?: BigNumber;
+  reduceOnly?: boolean;
+  positionSide?: PositionSide;
+  avgFillPrice?: BigNumber;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface OrderEventBase {
+  accountId: string;
+  exchange: Exchange;
+  symbol: string;
+  ts: number;
+}
+
+export interface OrderUpdatedEvent extends OrderEventBase {
+  type: "order.updated";
+  snapshot: OrderSnapshot;
+}
+
+export interface OrderFilledEvent extends OrderEventBase {
+  type: "order.filled";
+  snapshot: OrderSnapshot;
+}
+
+export interface OrderCanceledEvent extends OrderEventBase {
+  type: "order.canceled";
+  snapshot: OrderSnapshot;
+}
+
+export interface OrderRejectedEvent extends OrderEventBase {
+  type: "order.rejected";
+  snapshot: OrderSnapshot;
+}
+
+export interface OrderSnapshotReplacedEvent {
+  type: "order.snapshot_replaced";
+  accountId: string;
+  exchange: Exchange;
+  snapshot: OrderSnapshot[];
+  ts: number;
+}
+
+export type OrderEvent =
+  | OrderUpdatedEvent
+  | OrderFilledEvent
+  | OrderCanceledEvent
+  | OrderRejectedEvent
+  | OrderSnapshotReplacedEvent;
+
+export interface OrderEventStreams {
+  updates(filter?: OrderEventFilter): AsyncIterable<OrderEvent>;
+  status(filter?: OrderEventFilter): AsyncIterable<OrderStatusChangedEvent>;
+}
+
+export interface OrderManager {
+  readonly events: OrderEventStreams;
+
+  subscribeOrders(input: SubscribeOrdersInput): Promise<void>;
+  unsubscribeOrders(input: UnsubscribeOrdersInput): Promise<void>;
+  createOrder(input: CreateOrderInput): Promise<OrderSnapshot>;
+  cancelOrder(input: CancelOrderInput): Promise<OrderSnapshot>;
+  cancelAllOrders(input: CancelAllOrdersInput): Promise<OrderSnapshot[]>;
+
+  getOrder(input: GetOrderInput): OrderSnapshot | undefined;
+  getOpenOrders(accountId: string, symbol?: string): OrderSnapshot[];
+  getOrderStatus(accountId: string): OrderDataStatus | undefined;
+}

package/src/types/shared.ts

@@ -0,0 +1,93 @@
+export const SUPPORTED_EXCHANGES = ["binance", "okx", "bybit", "gate"] as const;
+
+export type Exchange = (typeof SUPPORTED_EXCHANGES)[number];
+
+export type ClientStatus =
+  | "idle"
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug(msg: string, context?: Record<string, unknown>): void;
+  info(msg: string, context?: Record<string, unknown>): void;
+  warn(msg: string, context?: Record<string, unknown>): void;
+  error(msg: string, context?: Record<string, unknown>): void;
+}
+
+export interface MarketRuntimeOptions {
+  l1InitialMessageTimeoutMs?: number;
+  l1StaleAfterMs?: number;
+  l1ReconnectDelayMs?: number;
+  l1ReconnectMaxDelayMs?: number;
+}
+
+export interface AccountRuntimeOptions {
+  streamOpenTimeoutMs?: number;
+  streamReconnectDelayMs?: number;
+  streamReconnectMaxDelayMs?: number;
+  listenKeyKeepAliveMs?: number;
+}
+
+export interface CreateClientOptions {
+  sandbox?: boolean;
+  logger?: Logger;
+  logLevel?: LogLevel;
+  market?: MarketRuntimeOptions;
+  account?: AccountRuntimeOptions;
+}
+
+export interface AccountCredentials {
+  apiKey?: string;
+  secret?: string;
+  password?: string;
+  extra?: Record<string, string>;
+}
+
+export interface RegisterAccountInput {
+  accountId: string;
+  exchange: Exchange;
+  credentials?: AccountCredentials;
+  options?: Record<string, unknown>;
+}
+
+export interface RegisterAccountResult {
+  accountId: string;
+  exchange: Exchange;
+}
+
+export interface StopOptions {
+  graceful?: boolean;
+  timeoutMs?: number;
+}
+
+export interface AcexInternalError {
+  source: "client" | "market" | "account" | "order" | "adapter" | "runtime";
+  exchange?: Exchange;
+  accountId?: string;
+  symbol?: string;
+  error: Error;
+  ts: number;
+}
+
+export type SubscriptionActivity = "active" | "inactive";
+
+export type MarketFreshness = "fresh" | "stale" | "reconciling";
+
+export type PrivateRuntimeStatus =
+  | "bootstrap_pending"
+  | "healthy"
+  | "degraded"
+  | "reconnecting"
+  | "reconciling"
+  | "stopped";
+
+export type PrivateRuntimeReason =
+  | "credentials_missing"
+  | "auth_failed"
+  | "ws_disconnected"
+  | "heartbeat_timeout"
+  | "reconciling";