@imbingox/acex 0.1.0-beta.0 → 0.1.0-beta.1

package/src/managers/order-manager.ts

@@ -0,0 +1,304 @@
+import type {
+  AccountAwareManager,
+  ClientContext,
+  HealthReporter,
+  ManagerLifecycle,
+} from "../client/context.ts";
+import { AsyncEventBus } from "../internal/async-event-bus.ts";
+import { matchesOrderFilter } from "../internal/filters.ts";
+import type {
+  Exchange,
+  GetOrderInput,
+  OrderDataStatus,
+  OrderEvent,
+  OrderEventStreams,
+  OrderManager,
+  OrderSnapshot,
+  OrderSnapshotReplacedEvent,
+  OrderStatusChangedEvent,
+  SubscribeOrdersInput,
+  UnsubscribeOrdersInput,
+} from "../types/index.ts";
+
+interface OrderRecord {
+  accountId: string;
+  exchange: Exchange;
+  subscribed: boolean;
+  snapshots: Map<string, OrderSnapshot>;
+  status: OrderDataStatus;
+}
+
+function cloneOrderStatus(status: OrderDataStatus): OrderDataStatus {
+  return { ...status };
+}
+
+export class OrderManagerImpl
+  implements
+    OrderManager,
+    ManagerLifecycle,
+    AccountAwareManager,
+    HealthReporter<OrderDataStatus>
+{
+  readonly events: OrderEventStreams;
+
+  private readonly context: ClientContext;
+  private readonly orderBus = new AsyncEventBus<OrderEvent>();
+  private readonly orderStatusBus =
+    new AsyncEventBus<OrderStatusChangedEvent>();
+  private readonly records = new Map<string, OrderRecord>();
+
+  constructor(context: ClientContext) {
+    this.context = context;
+
+    this.events = {
+      status: (filter) =>
+        this.orderStatusBus.stream((event) =>
+          matchesOrderFilter(
+            { accountId: event.accountId, exchange: event.exchange },
+            filter,
+          ),
+        ),
+      updates: (filter) =>
+        this.orderBus.stream((event) =>
+          matchesOrderFilter(
+            {
+              accountId: event.accountId,
+              exchange: event.exchange,
+              symbol: "symbol" in event ? event.symbol : undefined,
+            },
+            filter,
+          ),
+        ),
+    };
+  }
+
+  // --- OrderManager public API ---
+
+  async subscribeOrders(input: SubscribeOrdersInput): Promise<void> {
+    this.context.assertStarted();
+    const account = this.context.getRegisteredAccount(input.accountId);
+    this.context.ensurePrivateCredentials(input.accountId);
+
+    const record = this.getOrCreateRecord(input.accountId, account.exchange);
+    record.subscribed = true;
+    record.status = {
+      ...this.createStatus(input.accountId, account.exchange, "active"),
+      ready: true,
+      runtimeStatus: "healthy",
+      lastReceivedAt: this.context.now(),
+      lastReadyAt: this.context.now(),
+    };
+
+    const event: OrderSnapshotReplacedEvent = {
+      type: "order.snapshot_replaced",
+      accountId: record.accountId,
+      exchange: record.exchange,
+      snapshot: [...record.snapshots.values()],
+      ts: this.context.now(),
+    };
+
+    this.orderBus.publish(event);
+    this.publishStatus(record);
+  }
+
+  async unsubscribeOrders(input: UnsubscribeOrdersInput): Promise<void> {
+    const record = this.records.get(input.accountId);
+    if (!record?.subscribed) {
+      return;
+    }
+
+    record.subscribed = false;
+    record.status = {
+      ...record.status,
+      activity: "inactive",
+      runtimeStatus: "stopped",
+      inactiveSince: this.context.now(),
+    };
+    this.publishStatus(record);
+  }
+
+  getOrder(input: GetOrderInput): OrderSnapshot | undefined {
+    const record = this.records.get(input.accountId);
+    if (!record) {
+      return undefined;
+    }
+
+    if (!input.orderId && !input.clientOrderId) {
+      return undefined;
+    }
+
+    for (const snapshot of record.snapshots.values()) {
+      if (input.orderId && snapshot.orderId === input.orderId) {
+        return snapshot;
+      }
+
+      if (
+        input.clientOrderId &&
+        snapshot.clientOrderId === input.clientOrderId
+      ) {
+        return snapshot;
+      }
+    }
+
+    return undefined;
+  }
+
+  getOpenOrders(accountId: string, symbol?: string): OrderSnapshot[] {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return [];
+    }
+
+    return [...record.snapshots.values()].filter((snapshot) => {
+      if (symbol && snapshot.symbol !== symbol) {
+        return false;
+      }
+
+      return (
+        snapshot.status === "open" || snapshot.status === "partially_filled"
+      );
+    });
+  }
+
+  getOrderStatus(accountId: string): OrderDataStatus | undefined {
+    const status = this.records.get(accountId)?.status;
+    return status ? cloneOrderStatus(status) : undefined;
+  }
+
+  // --- ManagerLifecycle ---
+
+  onClientStarted(): void {
+    const now = this.context.now();
+
+    for (const [accountId, record] of this.records) {
+      if (!record.subscribed) {
+        continue;
+      }
+
+      const account = this.context.getRegisteredAccount(accountId);
+      const creds = account.credentials;
+      if (!creds?.apiKey || !creds.secret) {
+        continue;
+      }
+
+      record.status = {
+        ...this.createStatus(accountId, account.exchange, "active"),
+        ready: true,
+        runtimeStatus: "healthy",
+        lastReceivedAt: now,
+        lastReadyAt: now,
+      };
+      this.publishStatus(record);
+    }
+  }
+
+  onClientStopping(now: number): void {
+    for (const record of this.records.values()) {
+      if (!record.subscribed) {
+        continue;
+      }
+
+      record.status = {
+        ...record.status,
+        activity: "inactive",
+        runtimeStatus: "stopped",
+        inactiveSince: now,
+      };
+      this.publishStatus(record);
+    }
+  }
+
+  // --- AccountAwareManager ---
+
+  onAccountRemoved(accountId: string, now: number): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    record.subscribed = false;
+    record.status = {
+      ...record.status,
+      activity: "inactive",
+      runtimeStatus: "stopped",
+      inactiveSince: now,
+    };
+    this.publishStatus(record);
+    this.records.delete(accountId);
+  }
+
+  onCredentialsUpdated(accountId: string, exchange: Exchange): void {
+    const record = this.records.get(accountId);
+    if (!record?.subscribed) {
+      return;
+    }
+
+    record.status = this.createStatus(accountId, exchange, "active");
+    record.status.ready = true;
+    record.status.runtimeStatus = "healthy";
+    record.status.lastReadyAt = this.context.now();
+    this.publishStatus(record);
+  }
+
+  // --- HealthReporter ---
+
+  getStatuses(): OrderDataStatus[] {
+    return [...this.records.values()]
+      .map((record) => cloneOrderStatus(record.status))
+      .sort((left, right) =>
+        `${left.exchange}:${left.accountId}`.localeCompare(
+          `${right.exchange}:${right.accountId}`,
+        ),
+      );
+  }
+
+  // --- Internal helpers ---
+
+  private getOrCreateRecord(
+    accountId: string,
+    exchange: Exchange,
+  ): OrderRecord {
+    const existing = this.records.get(accountId);
+    if (existing) {
+      return existing;
+    }
+
+    const record: OrderRecord = {
+      accountId,
+      exchange,
+      subscribed: false,
+      snapshots: new Map(),
+      status: this.createStatus(accountId, exchange, "inactive"),
+    };
+
+    this.records.set(accountId, record);
+    return record;
+  }
+
+  private createStatus(
+    accountId: string,
+    exchange: Exchange,
+    activity: "active" | "inactive",
+  ): OrderDataStatus {
+    return {
+      accountId,
+      exchange,
+      activity,
+      ready: false,
+      runtimeStatus: activity === "active" ? "bootstrap_pending" : "stopped",
+    };
+  }
+
+  private publishStatus(record: OrderRecord): void {
+    const event: OrderStatusChangedEvent = {
+      type: "order.status_changed",
+      accountId: record.accountId,
+      exchange: record.exchange,
+      status: cloneOrderStatus(record.status),
+      ts: this.context.now(),
+    };
+
+    this.orderStatusBus.publish(event);
+    this.context.publishHealthEvent(event);
+  }
+}

package/src/types/account.ts

@@ -0,0 +1,160 @@
+import type {
+  Exchange,
+  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?:
+    | "credentials_missing"
+    | "auth_failed"
+    | "ws_disconnected"
+    | "heartbeat_timeout"
+    | "reconciling";
+}
+
+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: string;
+  used: string;
+  total: string;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface PositionSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  symbol: string;
+  side: PositionSide;
+  size: string;
+  entryPrice?: string;
+  markPrice?: string;
+  unrealizedPnl?: string;
+  leverage?: string;
+  liquidationPrice?: string;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  seq: number;
+}
+
+export interface RiskSnapshot {
+  accountId: string;
+  exchange: Exchange;
+  equity?: string;
+  marginRatio?: string;
+  initialMargin?: string;
+  maintenanceMargin?: string;
+  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,136 @@
+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?: string;
+  pricePrecision: number;
+  amountPrecision: number;
+  priceStep: string;
+  amountStep: string;
+  minAmount?: string;
+  minNotional?: string;
+  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 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: string;
+  bidSize: string;
+  askPrice: string;
+  askSize: string;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  version: number;
+}
+
+export interface FundingRateSnapshot {
+  exchange: Exchange;
+  symbol: string;
+  fundingRate: string;
+  nextFundingTime?: number;
+  markPrice?: string;
+  indexPrice?: string;
+  exchangeTs?: number;
+  receivedAt: number;
+  updatedAt: number;
+  version: number;
+}
+
+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(symbol: string): MarketDefinition | undefined;
+  listMarkets(): MarketDefinition[];
+  getL1Book(key: MarketKeyInput): L1Book | undefined;
+  getFundingRate(key: MarketKeyInput): FundingRateSnapshot | undefined;
+  getMarketStatus(key: MarketKeyInput): MarketDataStatus | undefined;
+}