@imbingox/acex 0.4.0-beta.7 → 0.4.0-beta.8

package/docs/api.md

@@ -1458,8 +1458,30 @@ interface AcexInternalError {
   ts: number;
 }
 
+interface AcexErrorDetails {
+  venue?: Venue;
+  accountId?: string;
+  symbol?: string;
+  venueError?: {
+    code?: string;
+    message?: string;
+  };
+  transport?: {
+    kind?: "timeout" | "http" | "network" | "rate_limited" | "parse";
+    status?: number;
+    statusText?: string;
+    retryAfterMs?: number;
+    retryable?: boolean;
+    attempts?: number;
+    rawBody?: string;
+    url?: string;
+  };
+}
+
 class AcexError extends Error {
   readonly code: AcexErrorCode;
+  readonly details?: AcexErrorDetails;
+  readonly cause?: unknown;
 }
 ```
 
@@ -1475,10 +1497,23 @@ try {
 } catch (err) {
   if (err instanceof AcexError) {
     console.log(err.code, err.message);
+    console.log(err.details?.venueError?.code);
+    console.log(err.details?.venueError?.message);
   }
 }
 ```
 
+`details.venueError` 是下游读取交易所结构化拒绝原因的首选字段，例如 Binance 返回 `{ "code": -2010, "msg": "Order would immediately trigger." }` 时会映射为：
+
+```ts
+{
+  code: "-2010",
+  message: "Order would immediately trigger.",
+}
+```
+
+`details.transport` 保留已脱敏的 HTTP/transport 诊断信息，例如 `kind`、`status`、`retryAfterMs`、`attempts`、`rawBody`、`url`。`rawBody` 和 `url` 只用于排障兜底，不建议作为业务分支首选字段。market stream 首包超时时，`MARKET_STREAM_TIMEOUT` 会带 `details.venue` / `details.symbol` 和底层 `cause`，通常不填 `details.venueError`。`cause` 保留底层错误链，用于高级调试。
+
 完整错误码列表：
 
 | Code | 典型场景 |

package/package.json

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

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

@@ -1,5 +1,4 @@
 import BigNumber from "bignumber.js";
-import { AcexError } from "../../errors.ts";
 import {
   type HttpClientMessages,
   httpRequest,
@@ -734,28 +733,21 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
     _credentials: AccountCredentials,
     _request: CreateOrderRequest,
   ): Promise<RawOrderUpdate> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
-      "Juplend is read-only and does not support createOrder",
-    );
+    throw new Error("Juplend is read-only and does not support createOrder");
   }
 
   cancelOrder(
     _credentials: AccountCredentials,
     _request: CancelOrderRequest,
   ): Promise<RawOrderUpdate> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
-      "Juplend is read-only and does not support cancelOrder",
-    );
+    throw new Error("Juplend is read-only and does not support cancelOrder");
   }
 
   cancelAllOrders(
     _credentials: AccountCredentials,
     _request: CancelAllOrdersRequest,
   ): Promise<RawOrderUpdate[]> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
+    throw new Error(
       "Juplend is read-only and does not support cancelAllOrders",
     );
   }

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

@@ -2,8 +2,12 @@ import type {
   PrivateUserDataAdapter,
   StreamHandle,
 } from "../adapters/types.ts";
-import { AcexError } from "../errors.ts";
-import { isTransportError, redactSecrets } from "../internal/http-client.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
+import { isTransportError } from "../internal/http-client.ts";
 import type {
   AccountRuntimeOptions,
   PrivateRuntimeReason,
@@ -55,14 +59,6 @@ function transportReason(
     : fallback;
 }
 
-function bootstrapErrorDetail(error: unknown): string {
-  if (!(error instanceof Error) || !error.message) {
-    return "";
-  }
-
-  return ` (${redactSecrets(error.message)})`;
-}
-
 export class PrivateSubscriptionCoordinator {
   private readonly context: ClientContext;
   private readonly adapters: Map<Venue, PrivateUserDataAdapter>;
@@ -260,6 +256,7 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "VENUE_NOT_SUPPORTED",
         `Venue is not supported yet: ${account.venue}`,
+        { details: buildAcexErrorDetails({ venue: account.venue }) },
       );
     }
 
@@ -272,6 +269,7 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "VENUE_NOT_SUPPORTED",
         `Venue is not supported yet: ${venue}`,
+        { details: buildAcexErrorDetails({ venue }) },
       );
     }
 
@@ -503,6 +501,12 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "CREDENTIALS_MISSING",
         `Account credentials are required for private subscriptions: ${account.accountId}`,
+        {
+          details: buildAcexErrorDetails({
+            accountId: account.accountId,
+            venue: account.venue,
+          }),
+        },
       );
     }
 
@@ -716,10 +720,23 @@ export class PrivateSubscriptionCoordinator {
           ),
         },
       );
-      const reason = bootstrapErrorDetail(error);
+      const details = buildAcexErrorDetails(
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+        error,
+      );
       throw new AcexError(
         "ACCOUNT_BOOTSTRAP_FAILED",
-        `Failed to bootstrap account data: ${record.accountId}${reason}`,
+        formatAcexErrorMessage(
+          `Failed to bootstrap account data: ${record.accountId}`,
+          details,
+        ),
+        {
+          cause: error,
+          details,
+        },
       );
     }
   }
@@ -766,9 +783,23 @@ export class PrivateSubscriptionCoordinator {
           reason: transportReason(error, "auth_failed"),
         },
       );
+      const details = buildAcexErrorDetails(
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+        error,
+      );
       throw new AcexError(
         "ORDER_BOOTSTRAP_FAILED",
-        `Failed to bootstrap order data: ${record.accountId}`,
+        formatAcexErrorMessage(
+          `Failed to bootstrap order data: ${record.accountId}`,
+          details,
+        ),
+        {
+          cause: error,
+          details,
+        },
       );
     }
   }

package/src/client/runtime.ts

@@ -9,7 +9,11 @@ import type {
   PrivateUserDataAdapter,
   RawOrderUpdate,
 } from "../adapters/types.ts";
-import { AcexError, type AcexErrorCode } from "../errors.ts";
+import {
+  AcexError,
+  type AcexErrorCode,
+  buildAcexErrorDetails,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
 import { ReactiveRateLimiter } from "../internal/rate-limiter.ts";
@@ -431,7 +435,9 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     message: string,
     metadata?: Omit<AcexInternalError, "error" | "source" | "ts">,
   ): AcexError {
-    const error = new AcexError(code, message);
+    const error = new AcexError(code, message, {
+      details: buildAcexErrorDetails(metadata),
+    });
     this.errorBus.publish({
       source: "client",
       ts: this.now(),

package/src/errors.ts

@@ -1,3 +1,6 @@
+import { isTransportError } from "./internal/http-client.ts";
+import type { Venue } from "./types/shared.ts";
+
 export type AcexErrorCode =
   | "ACCOUNT_ALREADY_EXISTS"
   | "ACCOUNT_BOOTSTRAP_FAILED"
@@ -17,12 +20,162 @@ export type AcexErrorCode =
   | "ORDER_CREATE_FAILED"
   | "ORDER_INPUT_INVALID";
 
+export type AcexErrorTransportKind =
+  | "timeout"
+  | "http"
+  | "network"
+  | "rate_limited"
+  | "parse";
+
+export interface AcexVenueErrorDetails {
+  readonly code?: string;
+  readonly message?: string;
+}
+
+export interface AcexErrorTransportDetails {
+  readonly kind?: AcexErrorTransportKind;
+  readonly status?: number;
+  readonly statusText?: string;
+  readonly retryAfterMs?: number;
+  readonly retryable?: boolean;
+  readonly attempts?: number;
+  readonly rawBody?: string;
+  readonly url?: string;
+}
+
+export interface AcexErrorDetails {
+  readonly venue?: Venue;
+  readonly accountId?: string;
+  readonly symbol?: string;
+  readonly venueError?: AcexVenueErrorDetails;
+  readonly transport?: AcexErrorTransportDetails;
+}
+
+export interface AcexErrorOptions {
+  readonly cause?: unknown;
+  readonly details?: AcexErrorDetails;
+}
+
 export class AcexError extends Error {
   readonly code: AcexErrorCode;
+  readonly details?: AcexErrorDetails;
+  override readonly cause?: unknown;
 
-  constructor(code: AcexErrorCode, message: string) {
-    super(message);
+  constructor(
+    code: AcexErrorCode,
+    message: string,
+    options: AcexErrorOptions = {},
+  ) {
+    super(message, { cause: options.cause });
     this.name = "AcexError";
     this.code = code;
+    this.details = options.details;
+    this.cause = options.cause;
+  }
+}
+
+export function buildAcexErrorDetails(
+  context?: Pick<AcexErrorDetails, "venue" | "accountId" | "symbol">,
+  cause?: unknown,
+): AcexErrorDetails | undefined {
+  const transport = buildTransportDetails(cause);
+  const venueError = parseVenueErrorDetails(transport?.rawBody);
+  const details: AcexErrorDetails = {
+    venue: context?.venue,
+    accountId: context?.accountId,
+    symbol: context?.symbol,
+    venueError,
+    transport,
+  };
+
+  return hasDetails(details) ? details : undefined;
+}
+
+export function formatAcexErrorMessage(
+  message: string,
+  details?: AcexErrorDetails,
+): string {
+  const venueErrorMessage = details?.venueError?.message?.trim();
+  if (!venueErrorMessage) {
+    return message;
+  }
+
+  const venue = details?.venue;
+  const venueLabel = venue ? formatVenueLabel(venue) : "Exchange";
+  return `${message} (${venueLabel} rejected: ${venueErrorMessage})`;
+}
+
+function buildTransportDetails(
+  cause: unknown,
+): AcexErrorTransportDetails | undefined {
+  if (!isTransportError(cause)) {
+    return undefined;
+  }
+
+  return pruneUndefined({
+    kind: cause.kind,
+    status: cause.status,
+    statusText: cause.statusText,
+    retryAfterMs: cause.retryAfterMs,
+    retryable: cause.retryable,
+    attempts: cause.attempts,
+    rawBody: cause.rawBody,
+    url: cause.url,
+  });
+}
+
+function parseVenueErrorDetails(
+  rawBody: string | undefined,
+): AcexVenueErrorDetails | undefined {
+  if (!rawBody) {
+    return undefined;
   }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return undefined;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return undefined;
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const code = record.code;
+  const message = record.msg ?? record.message;
+
+  if (
+    (typeof code !== "string" && typeof code !== "number") ||
+    typeof message !== "string" ||
+    message.trim() === ""
+  ) {
+    return undefined;
+  }
+
+  return {
+    code: String(code),
+    message,
+  };
+}
+
+function hasDetails(details: AcexErrorDetails): boolean {
+  return Boolean(
+    details.venue ||
+      details.accountId ||
+      details.symbol ||
+      details.venueError ||
+      details.transport,
+  );
+}
+
+function formatVenueLabel(venue: Venue): string {
+  return `${venue.charAt(0).toUpperCase()}${venue.slice(1)}`;
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(input: T): T {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => value !== undefined),
+  ) as T;
 }

package/src/index.ts

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

package/src/managers/market-manager.ts

@@ -14,7 +14,11 @@ import type {
   HealthReporter,
   ManagerLifecycle,
 } from "../client/context.ts";
-import { AcexError } from "../errors.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { toCanonical } from "../internal/decimal.ts";
 import { matchesMarketFilter } from "../internal/filters.ts";
@@ -606,9 +610,17 @@ export class MarketManagerImpl
   }
 
   private createCatalogLoadError(venue: Venue, error: unknown): AcexError {
+    const details = buildAcexErrorDetails({ venue }, error);
     const wrapped = new AcexError(
       "MARKET_CATALOG_LOAD_FAILED",
-      `Failed to load market catalog from ${venue}`,
+      formatAcexErrorMessage(
+        `Failed to load market catalog from ${venue}`,
+        details,
+      ),
+      {
+        cause: error,
+        details,
+      },
     );
     this.context.publishRuntimeError(
       "adapter",
@@ -621,9 +633,17 @@ export class MarketManagerImpl
   }
 
   private createServerTimeFetchError(venue: Venue, error: unknown): AcexError {
+    const details = buildAcexErrorDetails({ venue }, error);
     const wrapped = new AcexError(
       "MARKET_SERVER_TIME_FETCH_FAILED",
-      `Failed to fetch server time from ${venue}`,
+      formatAcexErrorMessage(
+        `Failed to fetch server time from ${venue}`,
+        details,
+      ),
+      {
+        cause: error,
+        details,
+      },
     );
     this.context.publishRuntimeError(
       "adapter",
@@ -758,11 +778,20 @@ export class MarketManagerImpl
 
     try {
       await record.l1BookStream.ready;
-    } catch {
+    } catch (error) {
+      record.l1BookStream.close();
       record.l1BookStream = undefined;
+      const details = buildAcexErrorDetails(
+        { venue: market.venue, symbol: market.symbol },
+        error,
+      );
       const timeoutError = new AcexError(
         "MARKET_STREAM_TIMEOUT",
         `Timed out waiting for market data: ${market.symbol}`,
+        {
+          cause: error,
+          details,
+        },
       );
       this.context.publishRuntimeError("runtime", timeoutError, {
         venue: market.venue,
@@ -786,11 +815,20 @@ export class MarketManagerImpl
 
     try {
       await record.fundingRateStream.ready;
-    } catch {
+    } catch (error) {
+      record.fundingRateStream.close();
       record.fundingRateStream = undefined;
+      const details = buildAcexErrorDetails(
+        { venue: market.venue, symbol: market.symbol },
+        error,
+      );
       const timeoutError = new AcexError(
         "MARKET_STREAM_TIMEOUT",
         `Timed out waiting for market data: ${market.symbol}`,
+        {
+          cause: error,
+          details,
+        },
       );
       this.context.publishRuntimeError("runtime", timeoutError, {
         venue: market.venue,
@@ -1189,7 +1227,9 @@ export class MarketManagerImpl
     metadata?: { venue?: Venue; symbol?: string },
     source: "market" | "client" = "market",
   ): AcexError {
-    const error = new AcexError(code, message);
+    const error = new AcexError(code, message, {
+      details: buildAcexErrorDetails(metadata),
+    });
     this.context.publishRuntimeError(source, error, metadata);
     return error;
   }

package/src/managers/order-manager.ts

@@ -8,7 +8,11 @@ import type {
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
-import { AcexError } from "../errors.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { toCanonical } from "../internal/decimal.ts";
 import { matchesOrderFilter } from "../internal/filters.ts";
@@ -656,7 +660,8 @@ export class OrderManagerImpl
       symbol?: string;
     },
   ): AcexError {
-    const error = new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata);
+    const error = new AcexError(code, message, { details });
     this.context.publishRuntimeError("order", error, metadata);
     return error;
   }
@@ -683,6 +688,10 @@ export class OrderManagerImpl
       error instanceof Error ? error : new Error(message),
       metadata,
     );
-    return new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata, error);
+    return new AcexError(code, formatAcexErrorMessage(message, details), {
+      cause: error,
+      details,
+    });
   }
 }