@imbingox/acex 0.4.0-beta.4 → 0.4.0-beta.6

package/docs/api.md

@@ -345,6 +345,7 @@ interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
   listMarkets(venue?: Venue): MarketDefinition[];
   getMarket(venue: Venue, symbol: string): MarketDefinition | undefined;
   getMarkets(symbol: string): MarketDefinition[];
@@ -368,6 +369,7 @@ interface MarketManager {
 
 ```ts
 await client.market.loadMarkets();
+const reloadSummaries = await client.market.reloadMarkets("binance");
 
 const all = client.market.listMarkets();
 const binanceOnly = client.market.listMarkets("binance");
@@ -378,6 +380,25 @@ const allBtcPerp = client.market.getMarkets("BTC/USDT:USDT");
 
 `getMarkets(symbol)` 严格按完整统一 symbol 匹配。
 
+`loadMarkets()` 会懒加载并缓存当前已注册 venue 的市场目录；已加载过的 venue 不会重复拉取。`reloadMarkets(venue?)` 用于主动刷新市场目录：传入 `venue` 时只刷新该 venue，省略时刷新所有已注册 market adapter。它和 `loadMarkets()` 一样不要求 client 已 `start()`，因此可在 `start()` 前或 `stop()` 后调用。
+
+`reloadMarkets()` 返回每个 venue 的刷新摘要：
+
+```ts
+type MarketCatalogReloadSummary = {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+};
+```
+
+`added` / `removed` 是本次刷新相对旧目录变化的 symbol 列表，`total` 是刷新后该 venue 的目录数量。catalog 拉取失败时，对应 summary 为 `ok: false`，`error.code = "MARKET_CATALOG_LOAD_FAILED"`，旧目录会保留，方法不会因为该 venue 的 catalog 失败而 reject；未注册 runtime adapter 的合法 venue（例如当前 market adapter 未接入的 `bybit`）仍会抛 `VENUE_NOT_SUPPORTED`。
+
+如果刷新会新增 symbol，调用方应先 `await client.market.reloadMarkets(venue)`，再按 summary 订阅新增 symbol。已加载 venue 上的后台 reload 不会阻塞并发 `subscribe*()`；reload 完成前订阅新增 symbol 仍可能按旧目录返回 `MARKET_NOT_FOUND`。
+
 `MarketDefinition` 见 [§9](#9-数据类型参考)。价格/数量相关字段（`priceStep`、`amountStep`、`contractSize`、`minAmount`、`minNotional`）都是 canonical decimal string；需要运算时用 `new BigNumber(field)` 自行解析。
 
 归一化下单价格和数量：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.6",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

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

@@ -699,6 +699,7 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
     private readonly options: {
       readonly fetchFn?: FetchLike;
       readonly httpTimeoutMs?: number;
+      readonly pollIntervalMs?: number;
     } = {},
   ) {}
 
@@ -762,13 +763,13 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
   createPrivateStream(
     credentials: AccountCredentials,
     callbacks: PrivateStreamCallbacks,
-    options: PrivateStreamOptions,
+    _options: PrivateStreamOptions,
     accountOptions?: Record<string, unknown>,
   ): StreamHandle {
     let closed = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
     const pollIntervalMs =
-      options.juplendPollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+      this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
 
     const poll = async (): Promise<void> => {
       try {

package/src/adapters/types.ts

@@ -210,7 +210,6 @@ export interface PrivateStreamOptions {
   reconnectDelayMs: number;
   reconnectMaxDelayMs: number;
   listenKeyKeepAliveMs: number;
-  juplendPollIntervalMs?: number;
   now?: () => number;
 }
 

package/src/client/context.ts

@@ -13,6 +13,7 @@ import type {
   PrivateRuntimeReason,
   PrivateRuntimeStatus,
   Venue,
+  VenueOrderCapabilities,
 } from "../types/index.ts";
 
 export interface RegisteredAccountRecord {
@@ -26,6 +27,7 @@ export interface ClientContext {
   now(): number;
   assertStarted(): void;
   getRegisteredAccount(accountId: string): RegisteredAccountRecord;
+  getPrivateOrderCapabilities(venue: Venue): VenueOrderCapabilities | undefined;
   ensurePrivateCredentials(accountId: string): void;
   subscribePrivateAccountFeed(accountId: string): Promise<void>;
   unsubscribePrivateAccountFeed(accountId: string): void;
@@ -105,13 +107,11 @@ export interface PrivateOrderDataConsumer {
 
 export function hasPrivateCredentials(
   credentials?: AccountCredentials,
-  venue?: Venue,
+  credentialsRequired = true,
 ): boolean {
-  if (venue === "juplend") {
-    return true;
-  }
-
-  return Boolean(credentials?.apiKey && credentials.secret);
+  return credentialsRequired
+    ? Boolean(credentials?.apiKey && credentials.secret)
+    : true;
 }
 
 export function mergeCredentials(

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

@@ -73,7 +73,6 @@ export class PrivateSubscriptionCoordinator {
   private readonly streamReconnectMaxDelayMs: number;
   private readonly listenKeyKeepAliveMs: number;
   private readonly binanceRiskPollIntervalMs: number;
-  private readonly juplendPollIntervalMs?: number;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
 
   constructor(
@@ -102,7 +101,6 @@ export class PrivateSubscriptionCoordinator {
       options.binance?.riskPollIntervalMs,
       DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS,
     );
-    this.juplendPollIntervalMs = options.juplend?.pollIntervalMs;
   }
 
   async subscribeAccountFeed(accountId: string): Promise<void> {
@@ -115,7 +113,8 @@ export class PrivateSubscriptionCoordinator {
     }
 
     try {
-      if (record.venue === "juplend") {
+      const adapter = this.getAdapter(record.venue);
+      if (adapter.accountCapabilities.updates === "polling") {
         await this.bootstrapAccount(record, account);
         await this.ensureStream(record, account);
       } else {
@@ -233,7 +232,11 @@ export class PrivateSubscriptionCoordinator {
     this.stopAccountRefreshPolling(record);
 
     try {
-      if (record.venue === "juplend" && record.accountSubscribed) {
+      const adapter = this.getAdapter(record.venue);
+      if (
+        adapter.accountCapabilities.updates === "polling" &&
+        record.accountSubscribed
+      ) {
         await this.bootstrapAccount(record, account);
         await this.ensureStream(record, account);
       } else {
@@ -318,7 +321,7 @@ export class PrivateSubscriptionCoordinator {
 
   private ensureAccountRefreshPolling(record: PrivateSubscriptionRecord): void {
     if (
-      record.venue !== "binance" ||
+      typeof this.getAdapter(record.venue).refreshAccount !== "function" ||
       !record.accountSubscribed ||
       record.accountRefreshTimer ||
       record.accountRefreshInFlight
@@ -339,7 +342,10 @@ export class PrivateSubscriptionCoordinator {
   }
 
   private scheduleAccountRefreshPoll(record: PrivateSubscriptionRecord): void {
-    if (record.venue !== "binance" || !record.accountSubscribed) {
+    if (
+      typeof this.getAdapter(record.venue).refreshAccount !== "function" ||
+      !record.accountSubscribed
+    ) {
       return;
     }
 
@@ -348,7 +354,7 @@ export class PrivateSubscriptionCoordinator {
       record.accountRefreshTimer = undefined;
       if (
         generation !== record.accountRefreshGeneration ||
-        record.venue !== "binance" ||
+        typeof this.getAdapter(record.venue).refreshAccount !== "function" ||
         !record.accountSubscribed
       ) {
         return;
@@ -374,7 +380,10 @@ export class PrivateSubscriptionCoordinator {
           }
 
           record.accountRefreshInFlight = undefined;
-          if (record.accountSubscribed && record.venue === "binance") {
+          if (
+            record.accountSubscribed &&
+            typeof this.getAdapter(record.venue).refreshAccount === "function"
+          ) {
             this.scheduleAccountRefreshPoll(record);
           }
         });
@@ -488,15 +497,15 @@ export class PrivateSubscriptionCoordinator {
     record: PrivateSubscriptionRecord,
     account: RegisteredAccountRecord,
   ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
     const credentials = account.credentials;
-    if (!credentials && record.venue !== "juplend") {
+    if (adapter.accountCapabilities.credentialsRequired && !credentials) {
       throw new AcexError(
         "CREDENTIALS_MISSING",
         `Account credentials are required for private subscriptions: ${account.accountId}`,
       );
     }
 
-    const adapter = this.getAdapter(record.venue);
     const stream = adapter.createPrivateStream(
       credentials ?? {},
       {
@@ -592,7 +601,6 @@ export class PrivateSubscriptionCoordinator {
         reconnectDelayMs: this.streamReconnectDelayMs,
         reconnectMaxDelayMs: this.streamReconnectMaxDelayMs,
         listenKeyKeepAliveMs: this.listenKeyKeepAliveMs,
-        juplendPollIntervalMs: this.juplendPollIntervalMs,
         now: () => this.context.now(),
       },
       { ...account.options, accountId: account.accountId },
@@ -664,7 +672,8 @@ export class PrivateSubscriptionCoordinator {
     account: RegisteredAccountRecord,
   ): Promise<void> {
     try {
-      const bootstrap = await this.getAdapter(record.venue).bootstrapAccount(
+      const adapter = this.getAdapter(record.venue);
+      const bootstrap = await adapter.bootstrapAccount(
         account.credentials ?? {},
         { ...account.options, accountId: account.accountId },
       );
@@ -700,7 +709,10 @@ export class PrivateSubscriptionCoordinator {
           ready: false,
           reason: transportReason(
             error,
-            record.venue === "juplend" ? "http_failed" : "auth_failed",
+            this.getAdapter(record.venue).accountCapabilities
+              .credentialsRequired
+              ? "auth_failed"
+              : "http_failed",
           ),
         },
       );

package/src/client/runtime.ts

@@ -38,6 +38,7 @@ import type {
   StopOptions,
   Venue,
   VenueCapabilities,
+  VenueOrderCapabilities,
 } from "../types/index.ts";
 import {
   type ClientContext,
@@ -114,6 +115,9 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       new JuplendPrivateAdapter(
         options.account?.juplend?.rpcUrl,
         options.account?.juplend?.jupApiKey,
+        {
+          pollIntervalMs: options.account?.juplend?.pollIntervalMs,
+        },
       ),
     ];
     this.privateAdapters = new Map(
@@ -298,9 +302,20 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return account;
   }
 
+  getPrivateOrderCapabilities(
+    venue: Venue,
+  ): VenueOrderCapabilities | undefined {
+    return this.privateAdapters.get(venue)?.orderCapabilities;
+  }
+
   ensurePrivateCredentials(accountId: string): void {
     const account = this.getRegisteredAccount(accountId);
-    if (hasPrivateCredentials(account.credentials, account.venue)) {
+    if (
+      hasPrivateCredentials(
+        account.credentials,
+        this.getPrivateCredentialsRequired(account.venue),
+      )
+    ) {
       return;
     }
 
@@ -429,7 +444,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   private getPrivateCommandAccount(accountId: string): RegisteredAccountRecord {
     const account = this.getRegisteredAccount(accountId);
     const adapter = this.getPrivateAdapter(account.venue);
-    if (adapter.venue === "juplend") {
+    if (!adapter.orderCapabilities.supported) {
       throw this.createError(
         "VENUE_NOT_SUPPORTED",
         `Venue does not support private order commands: ${account.venue}`,
@@ -437,7 +452,12 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       );
     }
 
-    if (!hasPrivateCredentials(account.credentials, account.venue)) {
+    if (
+      !hasPrivateCredentials(
+        account.credentials,
+        adapter.accountCapabilities.credentialsRequired,
+      )
+    ) {
       throw this.createError(
         "CREDENTIALS_MISSING",
         `Account credentials are required for private order commands: ${accountId}`,
@@ -448,6 +468,13 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return account;
   }
 
+  private getPrivateCredentialsRequired(venue: Venue): boolean {
+    return (
+      this.privateAdapters.get(venue)?.accountCapabilities
+        .credentialsRequired ?? true
+    );
+  }
+
   private getPrivateAdapter(venue: Venue): PrivateUserDataAdapter {
     const adapter = this.privateAdapters.get(venue);
     if (!adapter) {

package/src/managers/market-manager.ts

@@ -23,6 +23,7 @@ import type {
   FundingRateUpdatedEvent,
   L1Book,
   L1BookUpdatedEvent,
+  MarketCatalogReloadSummary,
   MarketDataStatus,
   MarketDataStreamStatus,
   MarketDefinition,
@@ -63,6 +64,13 @@ interface MarketRecord {
   fundingRateStream?: StreamHandle;
 }
 
+interface CatalogFetchResult {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+}
+
 const DEFAULT_INITIAL_L1_TIMEOUT_MS = 15_000;
 const DEFAULT_L1_STALE_AFTER_MS = 15_000;
 const DEFAULT_L1_RECONNECT_DELAY_MS = 1_000;
@@ -114,7 +122,10 @@ export class MarketManagerImpl
   private readonly definitions = new Map<string, MarketDefinition>();
   private readonly records = new Map<string, MarketRecord>();
   private readonly loadedCatalogVenues = new Set<Venue>();
-  private readonly catalogPromises = new Map<Venue, Promise<void>>();
+  private readonly catalogPromises = new Map<
+    Venue,
+    Promise<CatalogFetchResult>
+  >();
   private readonly initialL1TimeoutMs: number;
   private readonly l1StaleAfterMs: number;
   private readonly l1ReconnectDelayMs: number;
@@ -166,6 +177,30 @@ export class MarketManagerImpl
     );
   }
 
+  async reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]> {
+    if (venue !== undefined) {
+      this.assertSupportedVenue(venue);
+      return [await this.reloadVenue(venue)];
+    }
+
+    const venues = [...this.adapters.keys()];
+    const settled = await Promise.allSettled(
+      venues.map((registeredVenue) => this.reloadVenue(registeredVenue)),
+    );
+    const summaries: MarketCatalogReloadSummary[] = [];
+
+    for (const result of settled) {
+      if (result.status === "fulfilled") {
+        summaries.push(result.value);
+        continue;
+      }
+
+      throw result.reason;
+    }
+
+    return summaries;
+  }
+
   async subscribeL1Book(input: SubscribeL1BookInput): Promise<void> {
     this.context.assertStarted();
     const market = await this.resolveMarketDefinition(input);
@@ -438,51 +473,132 @@ export class MarketManagerImpl
       return;
     }
 
-    let catalogPromise = this.catalogPromises.get(venue);
-    if (!catalogPromise) {
-      catalogPromise = this.fetchAndStoreMarketCatalog(venue);
-      this.catalogPromises.set(venue, catalogPromise);
-    }
+    await this.fetchCatalogCoalesced(venue);
+  }
 
+  private async reloadVenue(venue: Venue): Promise<MarketCatalogReloadSummary> {
     try {
-      await catalogPromise;
+      const result = await this.fetchCatalogCoalesced(venue);
+      return { ...result, ok: true };
     } catch (error) {
-      this.catalogPromises.delete(venue);
+      if (
+        error instanceof AcexError &&
+        error.code === "MARKET_CATALOG_LOAD_FAILED"
+      ) {
+        return {
+          venue,
+          added: [],
+          removed: [],
+          total: this.countVenueMarkets(venue),
+          ok: false,
+          error,
+        };
+      }
+
       throw error;
     }
   }
 
-  private async fetchAndStoreMarketCatalog(venue: Venue): Promise<void> {
+  private async fetchCatalogCoalesced(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
+    let catalogPromise = this.catalogPromises.get(venue);
+    if (!catalogPromise) {
+      catalogPromise = this.fetchAndStoreMarketCatalog(venue).finally(() => {
+        this.catalogPromises.delete(venue);
+      });
+      this.catalogPromises.set(venue, catalogPromise);
+    }
+
+    return await catalogPromise;
+  }
+
+  private async fetchAndStoreMarketCatalog(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
     const adapter = this.getMarketAdapter(venue);
+    let markets: MarketDefinition[];
 
     try {
-      const markets = await adapter.loadMarkets();
+      markets = await adapter.loadMarkets();
+    } catch (error) {
+      throw this.createCatalogLoadError(venue, error);
+    }
 
-      for (const [key, market] of this.definitions) {
-        if (market.venue === venue) {
-          this.definitions.delete(key);
-        }
-      }
+    const mismatchedMarket = markets.find((market) => market.venue !== venue);
+    if (mismatchedMarket) {
+      throw this.createCatalogLoadError(
+        venue,
+        new Error(
+          `Market catalog from ${venue} included ${mismatchedMarket.venue} market: ${mismatchedMarket.symbol}`,
+        ),
+      );
+    }
+
+    const previousKeys = this.getVenueMarketKeys(venue);
 
-      for (const market of markets) {
-        this.definitions.set(marketKey(market), market);
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        this.definitions.delete(key);
       }
+    }
 
-      this.loadedCatalogVenues.add(venue);
-    } catch (error) {
-      const wrapped = new AcexError(
-        "MARKET_CATALOG_LOAD_FAILED",
-        `Failed to load market catalog from ${venue}`,
-      );
-      this.context.publishRuntimeError(
-        "adapter",
-        error instanceof Error
-          ? error
-          : new Error("Unknown catalog load failure"),
-        { venue },
-      );
-      throw wrapped;
+    for (const market of markets) {
+      this.definitions.set(marketKey(market), market);
     }
+
+    this.loadedCatalogVenues.add(venue);
+
+    const currentKeys = this.getVenueMarketKeys(venue);
+    return {
+      venue,
+      added: this.diffMarketSymbols(venue, currentKeys, previousKeys),
+      removed: this.diffMarketSymbols(venue, previousKeys, currentKeys),
+      total: currentKeys.size,
+    };
+  }
+
+  private getVenueMarketKeys(venue: Venue): Set<string> {
+    const keys = new Set<string>();
+
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        keys.add(key);
+      }
+    }
+
+    return keys;
+  }
+
+  private countVenueMarkets(venue: Venue): number {
+    return this.getVenueMarketKeys(venue).size;
+  }
+
+  private diffMarketSymbols(
+    venue: Venue,
+    left: Set<string>,
+    right: Set<string>,
+  ): string[] {
+    const prefix = `${venue}:`;
+    return [...left]
+      .filter((key) => !right.has(key))
+      .map((key) => key.slice(prefix.length))
+      .sort((leftSymbol, rightSymbol) => leftSymbol.localeCompare(rightSymbol));
+  }
+
+  private createCatalogLoadError(venue: Venue, error: unknown): AcexError {
+    const wrapped = new AcexError(
+      "MARKET_CATALOG_LOAD_FAILED",
+      `Failed to load market catalog from ${venue}`,
+    );
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error("Unknown catalog load failure"),
+      { venue },
+    );
+    return wrapped;
   }
 
   private async resolveMarketDefinition(input: {

package/src/managers/order-manager.ts

@@ -102,7 +102,10 @@ export class OrderManagerImpl
   async subscribeOrders(input: SubscribeOrdersInput): Promise<void> {
     this.context.assertStarted();
     const account = this.context.getRegisteredAccount(input.accountId);
-    if (account.venue === "juplend") {
+    if (
+      this.context.getPrivateOrderCapabilities(account.venue)?.updates ===
+      "unsupported"
+    ) {
       throw this.createError(
         "VENUE_NOT_SUPPORTED",
         `Venue does not support private order subscriptions: ${account.venue}`,

package/src/types/market.ts

@@ -1,4 +1,5 @@
 import type BigNumber from "bignumber.js";
+import type { AcexError } from "../errors.ts";
 import type { MarketFreshness, SubscriptionActivity, Venue } from "./shared.ts";
 
 export type MarketType = "spot" | "swap" | "future";
@@ -26,6 +27,15 @@ export interface MarketDefinition {
   raw: Record<string, unknown>;
 }
 
+export interface MarketCatalogReloadSummary {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+}
+
 export interface MarketDataStatus {
   venue: Venue;
   symbol: string;
@@ -159,6 +169,7 @@ export interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
   subscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   unsubscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;