@imbingox/acex 0.3.1-beta.0 → 0.4.0-beta.10

package/src/client/runtime.ts

@@ -9,9 +9,14 @@ 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";
 import { AccountManagerImpl } from "../managers/account-manager.ts";
 import { MarketManagerImpl } from "../managers/market-manager.ts";
 import { OrderManagerImpl } from "../managers/order-manager.ts";
@@ -37,6 +42,7 @@ import type {
   StopOptions,
   Venue,
   VenueCapabilities,
+  VenueOrderCapabilities,
 } from "../types/index.ts";
 import {
   type ClientContext,
@@ -102,13 +108,20 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   constructor(options: CreateClientOptions = {}) {
     activeClients.add(this);
 
-    const marketAdapter = new BinanceMarketAdapter();
+    const rateLimiter = options.rateLimiter ?? new ReactiveRateLimiter();
+    const marketAdapter = new BinanceMarketAdapter({ rateLimiter });
     this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [
-      new BinancePrivateAdapter(),
+      new BinancePrivateAdapter({
+        signingClock: options.clock,
+        rateLimiter,
+      }),
       new JuplendPrivateAdapter(
         options.account?.juplend?.rpcUrl,
         options.account?.juplend?.jupApiKey,
+        {
+          pollIntervalMs: options.account?.juplend?.pollIntervalMs,
+        },
       ),
     ];
     this.privateAdapters = new Map(
@@ -122,7 +135,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       l1ReconnectMaxDelayMs: options.market?.l1ReconnectMaxDelayMs,
     });
     this.accountManager = new AccountManagerImpl(this);
-    this.orderManager = new OrderManagerImpl(this);
+    this.orderManager = new OrderManagerImpl(this, options.order);
     this.privateCoordinator = new PrivateSubscriptionCoordinator(
       this,
       privateAdapters,
@@ -293,9 +306,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;
     }
 
@@ -339,7 +363,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).createOrder(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 
@@ -354,7 +378,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).cancelOrder(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 
@@ -367,7 +391,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).cancelAllOrders(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 
@@ -411,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(),
@@ -424,7 +450,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}`,
@@ -432,7 +458,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}`,
@@ -443,6 +474,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/client/venue-capabilities.ts

@@ -42,6 +42,7 @@ const typeOnlyNotes = [
 
 const unsupportedMarket: VenueMarketCapabilities = {
   catalog: "unsupported",
+  serverTime: "unsupported",
   l1Book: "unsupported",
   fundingRate: "unsupported",
   marketTypes: [],

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"
@@ -6,6 +9,7 @@ export type AcexErrorCode =
   | "CREDENTIALS_MISSING"
   | "VENUE_NOT_SUPPORTED"
   | "MARKET_CATALOG_LOAD_FAILED"
+  | "MARKET_SERVER_TIME_FETCH_FAILED"
   | "MARKET_INACTIVE"
   | "MARKET_FUNDING_RATE_UNSUPPORTED"
   | "MARKET_NOT_FOUND"
@@ -16,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/internal/decimal.ts

@@ -0,0 +1,19 @@
+import BigNumber from "bignumber.js";
+import type { DecimalInput } from "../types/index.ts";
+
+/**
+ * Convert a decimal value to its canonical string form: full precision, no
+ * scientific notation, no trailing zeros.
+ *
+ * Throws on non-finite input (NaN / Infinity) so producers can never leak
+ * sentinel strings into public output fields. Call sites that legitimately
+ * accept non-finite input (e.g. order-input validation) must guard before
+ * calling this.
+ */
+export function toCanonical(value: DecimalInput): string {
+  const bn = new BigNumber(value);
+  if (!bn.isFinite()) {
+    throw new RangeError(`invalid non-finite DecimalInput: ${bn.toString()}`);
+  }
+  return bn.toFixed();
+}