@imbingox/acex 0.4.0-beta.11 → 0.4.0-beta.13

package/docs/api.md

@@ -100,7 +100,7 @@ const risk = client.account.getRiskSnapshot("main-binance");
 const openOrders = client.order.getOpenOrders("main-binance");
 ```
 
-Binance 账户能力当前面向 PAPI UM。账户风险字段会由私有 WS 事件和 `/papi/v1/account` + `/papi/v1/um/positionRisk` REST refresh 共同维护；默认每 60s 还会用 `/papi/v1/balance`、`/papi/v1/account`、`/papi/v1/um/positionRisk` 和订单 REST 接口做 private reconcile。Binance 全账户 `/papi/v1/um/openOrders` 不带 symbol 时 request weight 较高，默认 60s 是保守值。
+Binance 账户能力当前面向 PAPI UM。账户风险字段会由私有 WS 事件和 `/papi/v1/account` + `/papi/v1/um/positionRisk` REST refresh 共同维护；默认每 60s 还会用 `/papi/v1/balance`、`/papi/v1/account`、`/papi/v1/um/positionRisk` 和订单 REST 接口做 private reconcile。Binance 全账户 `/papi/v1/um/openOrders` 不带 symbol 时 request weight 较高，默认 60s 是保守值。读取余额、仓位或风险数据时必须订阅 `client.account.subscribeAccount()`；`client.order.subscribeOrders()` 只维护订单缓存，即使底层复用同一条 private WS，也不会维护 account 仓位缓存。
 
 ### 2.4 注册 Juplend 只读账户
 
@@ -242,6 +242,7 @@ const client = createClient({
     binance: {
       riskPollIntervalMs: 5_000,
       privateReconcileIntervalMs: 60_000,
+      privateStreamStaleAfterMs: 65 * 60_000,
     },
     juplend: {
       pollIntervalMs: 30_000,
@@ -392,7 +393,7 @@ interface AccountManager {
 
 `AccountSnapshot.balances` 是 `Record<string, BalanceSnapshot>`，数组视图用 `getBalances()`。
 
-Binance account update 是 REST bootstrap + WS 增量 + REST risk refresh + private reconcile 的组合。risk refresh 是增量语义，不会因 REST 缺失项删除本地 position；private reconcile 是全量校准语义，会清理 REST 全量余额/仓位中缺失或归零的本地记录。Juplend 每次 poll 都是全量快照，成功 poll 会替换 balances / positions / risk，用于清理已关闭或不再匹配的 position。
+Binance account update 是 REST bootstrap + WS 增量 + REST risk refresh + private reconcile 的组合。WS `ACCOUNT_UPDATE` 会更新发生变化的余额和仓位；`/papi/v1/account` + `/papi/v1/um/positionRisk` refresh 用于校准风险字段和 mark-to-market 仓位字段。risk refresh 是增量语义，不会因 REST 缺失项删除本地 position；private reconcile 是全量校准语义，会清理 REST 全量余额/仓位中缺失或归零的本地记录。Juplend 每次 poll 都是全量快照，成功 poll 会替换 balances / positions / risk，用于清理已关闭或不再匹配的 position。
 
 Account 事件用于消费余额、仓位、风险或全量快照替换：
 
@@ -586,6 +587,7 @@ interface CreateClientOptions {
     binance?: {
       riskPollIntervalMs?: number;
       privateReconcileIntervalMs?: number;
+      privateStreamStaleAfterMs?: number;
     };
     juplend?: {
       pollIntervalMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.11",
+  "version": "0.4.0-beta.13",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -39,6 +39,7 @@
     "test:live:order": "bun run scripts/live-order-smoke.ts",
     "test:live:order:smoke": "bun run scripts/live-order-smoke.ts --duration 10",
     "test:live:order:soak": "bun run scripts/live-order-smoke.ts --duration 60 --disconnect-after 5",
+    "test:live:order:listen-key": "bun run scripts/live-order-smoke.ts --duration 60 --expire-listen-key-after 5",
     "version-packages": "changeset version && files=\"package.json\"; if [ -f .changeset/pre.json ]; then files=\"$files .changeset/pre.json\"; fi; if [ -f CHANGELOG.md ]; then files=\"$files CHANGELOG.md\"; fi; biome check --write $files",
     "test:unit": "bun test tests/unit",
     "test:integration": "bun test --max-concurrency=1 tests/integration",

package/src/adapters/binance/private-adapter.ts

@@ -93,6 +93,11 @@ interface BinancePapiOpenOrder {
   time?: number;
 }
 
+interface BinancePapiCancelAllResponse {
+  code?: number | string;
+  msg?: string;
+}
+
 interface BinanceListenKeyResponse {
   listenKey?: string;
 }
@@ -150,9 +155,16 @@ interface BinanceOrderTradeUpdateMessage {
   o?: BinanceOrderTradeUpdatePayload;
 }
 
+interface BinanceListenKeyExpiredMessage {
+  e?: string;
+  E?: number;
+  listenKey?: string;
+}
+
 type BinancePrivateMessage =
   | BinanceAccountUpdateMessage
-  | BinanceOrderTradeUpdateMessage;
+  | BinanceOrderTradeUpdateMessage
+  | BinanceListenKeyExpiredMessage;
 
 const BINANCE_PAPI_REST_BASE_URL = "https://papi.binance.com";
 const BINANCE_PAPI_WS_BASE_URL = "wss://fstream.binance.com/pm/ws";
@@ -220,6 +232,10 @@ function getStringOption(
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function toError(value: unknown, fallback: string): Error {
+  return value instanceof Error ? value : new Error(fallback);
+}
+
 function signQuery(query: string, secret: string): string {
   return createHmac("sha256", secret).update(query).digest("hex");
 }
@@ -529,7 +545,9 @@ function mapAccountUpdatePosition(
 
 function parsePrivateMessage(data: string): BinancePrivateMessage | undefined {
   const parsed = JSON.parse(data) as BinancePrivateMessage;
-  return parsed.e === "ACCOUNT_UPDATE" || parsed.e === "ORDER_TRADE_UPDATE"
+  return parsed.e === "ACCOUNT_UPDATE" ||
+    parsed.e === "ORDER_TRADE_UPDATE" ||
+    parsed.e === "listenKeyExpired"
     ? parsed
     : undefined;
 }
@@ -540,6 +558,12 @@ function isAccountUpdateMessage(
   return message.e === "ACCOUNT_UPDATE";
 }
 
+function isListenKeyExpiredMessage(
+  message: BinancePrivateMessage,
+): message is BinanceListenKeyExpiredMessage {
+  return message.e === "listenKeyExpired";
+}
+
 function mapAccountUpdate(
   message: BinanceAccountUpdateMessage,
   receivedAt: number,
@@ -859,21 +883,53 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     request: CancelAllOrdersRequest,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawOrderUpdate[]> {
-    const receivedAt = Date.now();
-    const responses = await this.signedRequest<BinancePapiOpenOrder[]>(
+    const symbol = encodeUmSymbol(request.symbol);
+    const openOrders = await this.signedRequest<BinancePapiOpenOrder[]>(
+      "GET",
+      "/papi/v1/um/openOrders",
+      credentials,
+      accountOptions,
+      {
+        symbol,
+      },
+      SAFE_READ_RETRY_POLICY,
+    );
+
+    // Venue responds {code,msg}; returned updates are synthesized from the
+    // pre-fetch. Orders that fill between fetch and cancel are corrected by
+    // the WS terminal event / reconcile.
+    const response = await this.signedRequest<BinancePapiCancelAllResponse>(
       "DELETE",
       "/papi/v1/um/allOpenOrders",
       credentials,
       accountOptions,
       {
-        symbol: encodeUmSymbol(request.symbol),
+        symbol,
       },
       NO_RETRY_POLICY,
     );
 
-    return responses.flatMap((response) => {
-      const mapped = mapOpenOrder(response, receivedAt);
-      return mapped ? [mapped] : [];
+    if (response.code !== undefined && `${response.code}` !== "200") {
+      throw new Error(
+        `Binance PAPI cancelAllOrders failed: code=${response.code}, msg=${
+          response.msg ?? ""
+        }`,
+      );
+    }
+
+    const receivedAt = Date.now();
+    return openOrders.flatMap((order) => {
+      const mapped = mapOpenOrder(order, receivedAt);
+      return mapped
+        ? [
+            {
+              ...mapped,
+              status: "canceled",
+              exchangeTs: undefined,
+              receivedAt,
+            },
+          ]
+        : [];
     });
   }
 
@@ -883,75 +939,158 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     options: PrivateStreamOptions,
     accountOptions?: Record<string, unknown>,
   ): StreamHandle {
+    interface PrivateStreamSession {
+      readonly listenKey: string;
+      websocket?: StreamHandle;
+      keepAliveTimer?: TimerHandle;
+      stopped: boolean;
+    }
+
+    type RecoveryReason =
+      | "heartbeat_timeout"
+      | "keepalive_failed"
+      | "listen_key_expired";
+
     let closed = false;
-    let listenKey: string | undefined;
-    let keepAliveTimer: TimerHandle | undefined;
-    let websocket: StreamHandle | undefined;
+    let activeSession: PrivateStreamSession | undefined;
+    let recoveryInFlight: Promise<void> | undefined;
+    let recoveryRetryTimer: ReturnType<typeof setTimeout> | undefined;
     let openedOnce = false;
 
-    const clearKeepAlive = () => {
-      if (keepAliveTimer) {
-        clearInterval(keepAliveTimer);
-        keepAliveTimer = undefined;
+    const clearRecoveryRetry = () => {
+      if (recoveryRetryTimer) {
+        clearTimeout(recoveryRetryTimer);
+        recoveryRetryTimer = undefined;
       }
     };
 
-    const closeListenKey = () => {
-      if (!listenKey) {
+    const closeListenKey = (listenKey: string) => {
+      void this.closeUserDataStream(
+        credentials,
+        listenKey,
+        accountOptions,
+      ).catch((error) => {
+        if (!closed) {
+          callbacks.onError(
+            toError(error, "Failed to close Binance PAPI listenKey"),
+          );
+        }
+      });
+    };
+
+    const closeSession = (
+      session: PrivateStreamSession | undefined,
+      shouldCloseListenKey: boolean,
+    ) => {
+      if (!session || session.stopped) {
         return;
       }
 
-      const key = listenKey;
-      listenKey = undefined;
-      void this.closeUserDataStream(credentials, key, accountOptions).catch(
-        (error) => {
-          callbacks.onError(
-            error instanceof Error
-              ? error
-              : new Error("Failed to close Binance PAPI listenKey"),
-          );
-        },
-      );
+      session.stopped = true;
+      if (session.keepAliveTimer) {
+        clearInterval(session.keepAliveTimer);
+        session.keepAliveTimer = undefined;
+      }
+      session.websocket?.close();
+      session.websocket = undefined;
+      if (shouldCloseListenKey) {
+        closeListenKey(session.listenKey);
+      }
     };
 
-    const ready = (async () => {
-      listenKey = await this.startUserDataStream(credentials, accountOptions);
+    const activateSession = (nextSession: PrivateStreamSession) => {
       if (closed) {
-        closeListenKey();
+        closeSession(nextSession, true);
+        return;
+      }
+
+      const previousSession = activeSession;
+      activeSession = nextSession;
+      closeSession(previousSession, true);
+
+      if (openedOnce) {
+        callbacks.onReconnected();
+      } else {
+        openedOnce = true;
+      }
+    };
+
+    const scheduleRecoveryRetry = (reason: RecoveryReason) => {
+      if (closed || recoveryRetryTimer) {
         return;
       }
 
-      keepAliveTimer = setInterval(() => {
-        if (!listenKey) {
+      recoveryRetryTimer = setTimeout(() => {
+        recoveryRetryTimer = undefined;
+        recoverPrivateStream(reason);
+      }, options.reconnectDelayMs);
+    };
+
+    const createSession = async (): Promise<
+      PrivateStreamSession | undefined
+    > => {
+      const listenKey = await this.startUserDataStream(
+        credentials,
+        accountOptions,
+      );
+      if (closed) {
+        closeListenKey(listenKey);
+        return undefined;
+      }
+
+      const nextSession: PrivateStreamSession = {
+        listenKey,
+        stopped: false,
+      };
+
+      nextSession.keepAliveTimer = setInterval(() => {
+        if (closed || activeSession !== nextSession) {
           return;
         }
 
         void this.keepAliveUserDataStream(
           credentials,
-          listenKey,
+          nextSession.listenKey,
           accountOptions,
         ).catch((error) => {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onError(
-            error instanceof Error
-              ? error
-              : new Error("Failed to keep Binance PAPI listenKey alive"),
+            toError(error, "Failed to keep Binance PAPI listenKey alive"),
           );
+          recoverPrivateStream("keepalive_failed");
         });
       }, options.listenKeyKeepAliveMs);
 
-      websocket = createManagedWebSocket<BinancePrivateMessage>({
+      nextSession.websocket = createManagedWebSocket<BinancePrivateMessage>({
         url: `${BINANCE_PAPI_WS_BASE_URL}/${listenKey}`,
         initialMessageTimeoutMs: options.openTimeoutMs,
         readyWhen: "open",
         now: options.now,
         parseMessage: parsePrivateMessage,
         onOpen() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           if (openedOnce) {
             callbacks.onReconnected();
+          } else {
+            openedOnce = true;
           }
-          openedOnce = true;
         },
         onMessage(message, receivedAt) {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
+          if (isListenKeyExpiredMessage(message)) {
+            recoverPrivateStream("listen_key_expired");
+            return;
+          }
+
           if (isAccountUpdateMessage(message)) {
             callbacks.onAccountUpdate(mapAccountUpdate(message, receivedAt));
             return;
@@ -963,13 +1102,31 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
           }
         },
         onUnexpectedClose() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onDisconnected();
         },
         onError() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onError(
             new Error("WebSocket error for Binance PAPI private stream"),
           );
         },
+        messageWatchdog: {
+          staleAfterMs: options.staleAfterMs,
+          onStale() {
+            if (closed || activeSession !== nextSession) {
+              return;
+            }
+
+            recoverPrivateStream("heartbeat_timeout");
+          },
+        },
         reconnect: {
           initialDelayMs: options.reconnectDelayMs,
           maxDelayMs: options.reconnectMaxDelayMs,
@@ -977,7 +1134,60 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         },
       });
 
-      await websocket.ready;
+      try {
+        await nextSession.websocket.ready;
+      } catch (error) {
+        closeSession(nextSession, true);
+        throw error;
+      }
+
+      return nextSession;
+    };
+
+    const recoverPrivateStream = (reason: RecoveryReason) => {
+      if (closed || recoveryInFlight) {
+        return;
+      }
+
+      clearRecoveryRetry();
+      if (reason === "heartbeat_timeout") {
+        callbacks.onFreshnessChange("stale", "heartbeat_timeout");
+      } else {
+        callbacks.onDisconnected();
+      }
+
+      const recovery = (async () => {
+        const previousSession = activeSession;
+        activeSession = undefined;
+        closeSession(previousSession, true);
+
+        try {
+          const nextSession = await createSession();
+          if (nextSession) {
+            activateSession(nextSession);
+          }
+        } catch (error) {
+          if (!closed) {
+            callbacks.onError(
+              toError(error, "Failed to rebuild Binance PAPI private stream"),
+            );
+            scheduleRecoveryRetry(reason);
+          }
+        }
+      })().finally(() => {
+        if (recoveryInFlight === recovery) {
+          recoveryInFlight = undefined;
+        }
+      });
+
+      recoveryInFlight = recovery;
+    };
+
+    const ready = (async () => {
+      const initialSession = await createSession();
+      if (initialSession) {
+        activateSession(initialSession);
+      }
     })();
 
     return {
@@ -988,9 +1198,9 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         }
 
         closed = true;
-        clearKeepAlive();
-        websocket?.close();
-        closeListenKey();
+        clearRecoveryRetry();
+        closeSession(activeSession, true);
+        activeSession = undefined;
       },
     };
   }

package/src/adapters/types.ts

@@ -212,6 +212,7 @@ export interface PrivateStreamCallbacks {
   onAccountSnapshot(snapshot: RawAccountBootstrap): void;
   onAccountUpdate(update: RawAccountUpdate): void;
   onOrderUpdate(update: RawOrderUpdate): void;
+  onFreshnessChange(freshness: "stale", reason: "heartbeat_timeout"): void;
   onDisconnected(): void;
   onReconnected(): void;
   onError(error: Error): void;
@@ -222,6 +223,7 @@ export interface PrivateStreamOptions {
   reconnectDelayMs: number;
   reconnectMaxDelayMs: number;
   listenKeyKeepAliveMs: number;
+  staleAfterMs: number;
   now?: () => number;
 }
 

package/src/client/private-subscription-coordinator.ts

@@ -47,6 +47,7 @@ const DEFAULT_STREAM_OPEN_TIMEOUT_MS = 15_000;
 const DEFAULT_STREAM_RECONNECT_DELAY_MS = 1_000;
 const DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS = 10_000;
 const DEFAULT_LISTEN_KEY_KEEPALIVE_MS = 30 * 60 * 1_000;
+const DEFAULT_PRIVATE_STREAM_STALE_AFTER_MS = 65 * 60_000;
 const DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS = 5_000;
 const DEFAULT_BINANCE_PRIVATE_RECONCILE_INTERVAL_MS = 60_000;
 const MAX_ORDER_TERMINAL_BACKFILLS_PER_RECONCILE = 20;
@@ -90,6 +91,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly streamReconnectDelayMs: number;
   private readonly streamReconnectMaxDelayMs: number;
   private readonly listenKeyKeepAliveMs: number;
+  private readonly binancePrivateStreamStaleAfterMs: number;
   private readonly binanceRiskPollIntervalMs: number;
   private readonly binancePrivateReconcileIntervalMs: number | undefined;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
@@ -116,6 +118,10 @@ export class PrivateSubscriptionCoordinator {
       DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS;
     this.listenKeyKeepAliveMs =
       options.listenKeyKeepAliveMs ?? DEFAULT_LISTEN_KEY_KEEPALIVE_MS;
+    this.binancePrivateStreamStaleAfterMs = normalizePositiveInterval(
+      options.binance?.privateStreamStaleAfterMs,
+      DEFAULT_PRIVATE_STREAM_STALE_AFTER_MS,
+    );
     this.binanceRiskPollIntervalMs = normalizePositiveInterval(
       options.binance?.riskPollIntervalMs,
       DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS,
@@ -1180,6 +1186,30 @@ export class PrivateSubscriptionCoordinator {
             update,
           );
         },
+        onFreshnessChange: (_freshness, reason) => {
+          if (record.accountSubscribed) {
+            this.accountConsumer.onPrivateAccountStreamState(
+              record.accountId,
+              record.venue,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.accountReady,
+                reason,
+              },
+            );
+          }
+          if (record.ordersSubscribed) {
+            this.orderConsumer.onPrivateOrderStreamState(
+              record.accountId,
+              record.venue,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.orderReady,
+                reason,
+              },
+            );
+          }
+        },
         onDisconnected: () => {
           if (record.accountSubscribed) {
             this.accountConsumer.onPrivateAccountStreamState(
@@ -1236,6 +1266,7 @@ export class PrivateSubscriptionCoordinator {
         reconnectDelayMs: this.streamReconnectDelayMs,
         reconnectMaxDelayMs: this.streamReconnectMaxDelayMs,
         listenKeyKeepAliveMs: this.listenKeyKeepAliveMs,
+        staleAfterMs: this.binancePrivateStreamStaleAfterMs,
         now: () => this.context.now(),
       },
       { ...account.options, accountId: account.accountId },

package/src/internal/watermark.ts

@@ -28,6 +28,17 @@ export function shouldApplyWatermarkedUpdate(
   const graceMs = options.graceMs ?? CROSS_CLOCK_WATERMARK_GRACE_MS;
   const requestStartedAt = options.requestStartedAt;
 
+  if (options.source === "command" && requestStartedAt !== undefined) {
+    const hasMissingExchangeTs =
+      current.exchangeTs === undefined || incoming.exchangeTs === undefined;
+    if (hasMissingExchangeTs) {
+      return (
+        current.receivedAt <= requestStartedAt &&
+        incoming.receivedAt >= current.receivedAt
+      );
+    }
+  }
+
   if (
     options.source === "rest" &&
     requestStartedAt !== undefined &&

package/src/managers/order/data-status.ts

@@ -0,0 +1,61 @@
+import type { OrderDataStatus, Venue } from "../../types/index.ts";
+
+export const DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL = 500;
+
+export function cloneOrderStatus(status: OrderDataStatus): OrderDataStatus {
+  return { ...status };
+}
+
+export function createOrderDataStatus(
+  accountId: string,
+  venue: Venue,
+  activity: "active" | "inactive",
+): OrderDataStatus {
+  return {
+    accountId,
+    venue,
+    activity,
+    ready: false,
+    runtimeStatus: activity === "active" ? "bootstrap_pending" : "stopped",
+  };
+}
+
+export function normalizeMaxClosedOrdersPerSymbol(
+  value: number | undefined,
+): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL;
+}
+
+export function successfulStatus(
+  status: OrderDataStatus,
+  options: {
+    ready?: boolean;
+    lastReceivedAt?: number;
+    lastReadyAt?: number;
+    preserveStatus?: boolean;
+  },
+): OrderDataStatus {
+  const preservesStreamState =
+    options.preserveStatus &&
+    (status.runtimeStatus === "reconnecting" ||
+      status.reason === "ws_disconnected" ||
+      status.reason === "heartbeat_timeout");
+  const ready = options.ready ?? true;
+
+  return {
+    ...status,
+    activity: "active",
+    ready,
+    runtimeStatus: preservesStreamState ? status.runtimeStatus : "healthy",
+    reason: preservesStreamState ? status.reason : undefined,
+    lastReceivedAt: options.lastReceivedAt ?? status.lastReceivedAt,
+    lastReadyAt: ready
+      ? (options.lastReadyAt ??
+        (options.preserveStatus ? status.lastReadyAt : undefined) ??
+        Date.now())
+      : status.lastReadyAt,
+    inactiveSince: undefined,
+  };
+}