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

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

@@ -1,5 +1,10 @@
 import { createHmac } from "node:crypto";
 import BigNumber from "bignumber.js";
+import {
+  type HttpClientMessages,
+  type HttpRetryPolicy,
+  httpRequest,
+} from "../../internal/http-client.ts";
 import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
 import type {
   AccountCredentials,
@@ -25,6 +30,7 @@ import type {
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type SignedRequestMethod = "GET" | "POST" | "DELETE";
+type FetchLike = typeof fetch;
 
 interface BinancePapiBalance {
   asset?: string;
@@ -144,7 +150,31 @@ type BinancePrivateMessage =
 const BINANCE_PAPI_REST_BASE_URL = "https://papi.binance.com";
 const BINANCE_PAPI_WS_BASE_URL = "wss://fstream.binance.com/pm/ws";
 const DEFAULT_RECV_WINDOW = 5_000;
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 const USDM_QUOTE_ASSETS = ["FDUSD", "USDC", "BUSD", "USDT"];
+const SAFE_READ_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: true,
+  maxAttempts: 3,
+};
+const NO_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: false,
+  maxAttempts: 1,
+};
+const LISTEN_KEY_KEEPALIVE_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: true,
+  maxAttempts: 3,
+};
+function getBinancePapiHttpMessages(timeoutMs: number): HttpClientMessages {
+  return {
+    http: ({ status, statusText, url, rawBody }) =>
+      `Binance PAPI request failed: ${status} ${statusText ?? ""} ${url}${
+        rawBody ? ` ${rawBody}` : ""
+      }`,
+    timeout: () => `Binance PAPI fetch timeout after ${timeoutMs}ms`,
+    aborted: () => "Binance PAPI fetch aborted",
+    parse: ({ url }) => `Binance PAPI response parse failed: ${url}`,
+  };
+}
 
 function requirePrivateCredentials(credentials: AccountCredentials): {
   apiKey: string;
@@ -521,21 +551,6 @@ function mapOrderUpdate(
   };
 }
 
-async function readJson<T>(response: Response, url: string): Promise<T> {
-  const text = await response.text();
-  if (!response.ok) {
-    throw new Error(
-      `Binance PAPI request failed: ${response.status} ${response.statusText} ${url} ${text}`,
-    );
-  }
-
-  if (!text) {
-    return {} as T;
-  }
-
-  return JSON.parse(text) as T;
-}
-
 export class BinancePrivateAdapter implements PrivateUserDataAdapter {
   readonly venue = "binance" as const;
   readonly readOnly = false;
@@ -569,6 +584,13 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     clientOrderId: true,
   };
 
+  constructor(
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+    } = {},
+  ) {}
+
   async bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
@@ -580,18 +602,24 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         "/papi/v1/balance",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiAccount>(
         "GET",
         "/papi/v1/account",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
         "/papi/v1/um/positionRisk",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
     ]);
 
@@ -621,12 +649,16 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         "/papi/v1/account",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
         "/papi/v1/um/positionRisk",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
     ]);
 
@@ -643,6 +675,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "/papi/v1/um/openOrders",
       credentials,
       accountOptions,
+      undefined,
+      SAFE_READ_RETRY_POLICY,
     );
 
     return orders.flatMap((order) => {
@@ -681,6 +715,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
             : `${request.reduceOnly}`,
         positionSide: encodePositionSide(request.positionSide),
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -709,6 +744,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         orderId: request.orderId,
         origClientOrderId: request.clientOrderId,
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -735,6 +771,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       {
         symbol: encodeUmSymbol(request.symbol),
       },
+      NO_RETRY_POLICY,
     );
 
     return responses.flatMap((response) => {
@@ -863,6 +900,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
     queryParams?: Record<string, string | undefined>,
+    retryPolicy?: HttpRetryPolicy,
   ): Promise<T> {
     const { apiKey, secret } = requirePrivateCredentials(credentials);
     const params = new URLSearchParams();
@@ -882,14 +920,22 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     params.set("signature", signQuery(params.toString(), secret));
 
     const url = `${BINANCE_PAPI_REST_BASE_URL}${path}?${params.toString()}`;
-    const response = await fetch(url, {
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    const response = await httpRequest<T>({
+      fetchFn: this.options.fetchFn,
+      url,
       method,
       headers: {
         "X-MBX-APIKEY": apiKey,
       },
+      timeoutMs,
+      parseAs: "json",
+      emptyBody: "empty_object",
+      retryPolicy: retryPolicy ?? NO_RETRY_POLICY,
+      messages: getBinancePapiHttpMessages(timeoutMs),
     });
 
-    return readJson<T>(response, url);
+    return response.body;
   }
 
   private async startUserDataStream(
@@ -898,6 +944,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     const response = await this.userStreamRequest<BinanceListenKeyResponse>(
       "POST",
       credentials,
+      undefined,
+      NO_RETRY_POLICY,
     );
     if (!response.listenKey) {
       throw new Error("Binance PAPI did not return a listenKey");
@@ -914,6 +962,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "PUT",
       credentials,
       listenKey,
+      LISTEN_KEY_KEEPALIVE_RETRY_POLICY,
     );
   }
 
@@ -925,6 +974,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "DELETE",
       credentials,
       listenKey,
+      NO_RETRY_POLICY,
     );
   }
 
@@ -932,6 +982,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     method: "POST" | "PUT" | "DELETE",
     credentials: AccountCredentials,
     listenKey?: string,
+    retryPolicy: HttpRetryPolicy = NO_RETRY_POLICY,
   ): Promise<T> {
     const { apiKey } = requirePrivateCredentials(credentials);
     const params = new URLSearchParams();
@@ -943,13 +994,21 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     const url = `${BINANCE_PAPI_REST_BASE_URL}/papi/v1/listenKey${
       query ? `?${query}` : ""
     }`;
-    const response = await fetch(url, {
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    const response = await httpRequest<T>({
+      fetchFn: this.options.fetchFn,
+      url,
       method,
       headers: {
         "X-MBX-APIKEY": apiKey,
       },
+      timeoutMs,
+      parseAs: "json",
+      emptyBody: "empty_object",
+      retryPolicy,
+      messages: getBinancePapiHttpMessages(timeoutMs),
     });
 
-    return readJson<T>(response, url);
+    return response.body;
   }
 }

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

@@ -1,5 +1,9 @@
 import BigNumber from "bignumber.js";
 import { AcexError } from "../../errors.ts";
+import {
+  type HttpClientMessages,
+  httpRequest,
+} from "../../internal/http-client.ts";
 import type {
   AccountCredentials,
   VenueAccountCapabilities,
@@ -66,6 +70,8 @@ interface JuplendPriceApiEntry {
   decimals?: number | string;
 }
 
+type FetchLike = typeof fetch;
+
 interface JuplendTokenSearchEntry {
   id?: string;
   address?: string;
@@ -86,6 +92,13 @@ const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 // not mint-atomic token amounts.
 const POSITION_AMOUNT_SCALE_DECIMALS = 9;
 const VAULT_CACHE_TTL_MS = 60 * 60 * 1_000;
+function getJuplendHttpMessages(timeoutMs: number): HttpClientMessages {
+  return {
+    http: ({ status, statusText }) => `Juplend HTTP ${status}: ${statusText}`,
+    timeout: () => `Juplend fetch timeout after ${timeoutMs}ms`,
+    aborted: () => "Juplend fetch aborted",
+  };
+}
 
 interface JuplendVaultEnrichmentCacheEntry {
   loadedAt: number;
@@ -260,52 +273,30 @@ function buildRisk(input: {
   };
 }
 
-async function readJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const controller = new AbortController();
-  const upstreamSignal = init?.signal;
-  let timedOut = false;
-  const onUpstreamAbort = () => {
-    controller.abort();
-  };
-
-  if (upstreamSignal?.aborted) {
-    controller.abort();
-  } else if (upstreamSignal) {
-    upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
-  }
-
-  const timeout = setTimeout(() => {
-    timedOut = true;
-    controller.abort();
-  }, DEFAULT_HTTP_TIMEOUT_MS);
-
-  try {
-    const response = await fetch(url, {
-      ...init,
-      signal: controller.signal,
-    });
-    if (!response.ok) {
-      throw new Error(
-        `Juplend HTTP ${response.status}: ${response.statusText}`,
-      );
-    }
+async function requestJuplendJson<T>(
+  url: string,
+  init: RequestInit | undefined,
+  fetchFn: FetchLike | undefined,
+  timeoutMs: number,
+): Promise<T> {
+  const response = await httpRequest<T>({
+    fetchFn,
+    url,
+    method: init?.method,
+    headers: init?.headers,
+    body: init?.body,
+    signal: init?.signal ?? undefined,
+    timeoutMs,
+    parseAs: "json",
+    jsonParseMode: "response",
+    retryPolicy: {
+      idempotent: true,
+      maxAttempts: 3,
+    },
+    messages: getJuplendHttpMessages(timeoutMs),
+  });
 
-    return (await response.json()) as T;
-  } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error(
-        timedOut
-          ? `Juplend fetch timeout after ${DEFAULT_HTTP_TIMEOUT_MS}ms`
-          : "Juplend fetch aborted",
-      );
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-    if (upstreamSignal) {
-      upstreamSignal.removeEventListener("abort", onUpstreamAbort);
-    }
-  }
+  return response.body;
 }
 
 function getJupApiKey(explicitApiKey?: string): string | undefined {
@@ -326,12 +317,19 @@ function withBaseUrl(baseUrl: string, path: string): string {
 
 async function loadVaultMetadataFromLiteApi(
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendVaultMetadata>> {
-  const response = await readJson<
+  const response = await requestJuplendJson<
     JuplendVaultMetadata[] | { data?: JuplendVaultMetadata[] }
-  >(withBaseUrl(JUP_LITE_API_BASE_URL, LEND_VAULTS_PATH), {
-    headers: buildApiHeaders(apiKey),
-  });
+  >(
+    withBaseUrl(JUP_LITE_API_BASE_URL, LEND_VAULTS_PATH),
+    {
+      headers: buildApiHeaders(apiKey),
+    },
+    fetchFn,
+    timeoutMs,
+  );
   const rawVaults = Array.isArray(response) ? response : response.data;
   const vaults = new Map<string, JuplendVaultMetadata>();
 
@@ -348,17 +346,21 @@ async function loadVaultMetadataFromLiteApi(
 async function loadTokenSearchMap(
   mintAddresses: string[],
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendTokenMetadata>> {
   if (mintAddresses.length === 0) {
     return new Map();
   }
 
   const query = encodeURIComponent(mintAddresses.join(","));
-  const response = await readJson<JuplendTokenSearchEntry[]>(
+  const response = await requestJuplendJson<JuplendTokenSearchEntry[]>(
     `${withBaseUrl(JUP_API_BASE_URL, TOKENS_SEARCH_PATH)}?query=${query}`,
     {
       headers: buildApiHeaders(apiKey),
     },
+    fetchFn,
+    timeoutMs,
   );
 
   const tokens = new Map<string, JuplendTokenMetadata>();
@@ -385,17 +387,23 @@ async function loadTokenSearchMap(
 async function loadPriceMap(
   mintAddresses: string[],
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendPriceApiEntry>> {
   if (mintAddresses.length === 0) {
     return new Map();
   }
 
   const ids = encodeURIComponent(mintAddresses.join(","));
-  const response = await readJson<Record<string, JuplendPriceApiEntry>>(
+  const response = await requestJuplendJson<
+    Record<string, JuplendPriceApiEntry>
+  >(
     `${withBaseUrl(JUP_API_BASE_URL, PRICE_V3_PATH)}?ids=${ids}`,
     {
       headers: buildApiHeaders(apiKey),
     },
+    fetchFn,
+    timeoutMs,
   );
 
   return new Map(Object.entries(response ?? {}));
@@ -436,6 +444,8 @@ function mergeTokenMetadata(
 async function enrichVaultsWithJupApi(input: {
   apiKey?: string;
   baseVaults: Map<string, JuplendVaultMetadata>;
+  fetchFn?: FetchLike;
+  timeoutMs: number;
 }): Promise<Map<string, JuplendVaultMetadata>> {
   const mintAddresses = new Set<string>();
   for (const vault of input.baseVaults.values()) {
@@ -450,8 +460,18 @@ async function enrichVaultsWithJupApi(input: {
   }
 
   const [tokenMap, priceMap] = await Promise.all([
-    loadTokenSearchMap([...mintAddresses], input.apiKey),
-    loadPriceMap([...mintAddresses], input.apiKey),
+    loadTokenSearchMap(
+      [...mintAddresses],
+      input.apiKey,
+      input.fetchFn,
+      input.timeoutMs,
+    ),
+    loadPriceMap(
+      [...mintAddresses],
+      input.apiKey,
+      input.fetchFn,
+      input.timeoutMs,
+    ),
   ]);
 
   const enriched = new Map<string, JuplendVaultMetadata>();
@@ -480,6 +500,8 @@ async function enrichVaultsWithJupApi(input: {
 async function loadVaults(
   now: number,
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendVaultMetadata>> {
   const cacheKey = getEnrichmentCacheKey(apiKey);
   const cached = enrichmentCache.get(cacheKey);
@@ -492,7 +514,11 @@ async function loadVaults(
   const inflight = enrichmentCachePromise.get(cacheKey);
   if (!inflight) {
     const nextPromise = (async () => {
-      const baseVaults = await loadVaultMetadataFromLiteApi(apiKey);
+      const baseVaults = await loadVaultMetadataFromLiteApi(
+        apiKey,
+        fetchFn,
+        timeoutMs,
+      );
       if (!apiKey) {
         enrichmentCache.set(cacheKey, {
           loadedAt: now,
@@ -506,6 +532,8 @@ async function loadVaults(
         const enrichedVaults = await enrichVaultsWithJupApi({
           apiKey,
           baseVaults,
+          fetchFn,
+          timeoutMs,
         });
         enrichmentCache.set(cacheKey, {
           loadedAt: now,
@@ -545,9 +573,11 @@ async function mapAccount(
   receivedAt: number,
   rpcUrl: string | undefined,
   jupApiKey: string | undefined,
+  fetchFn: FetchLike | undefined,
+  timeoutMs: number,
 ): Promise<JuplendMappedAccount> {
   const [vaults, positionResult] = await Promise.all([
-    loadVaults(receivedAt, jupApiKey),
+    loadVaults(receivedAt, jupApiKey, fetchFn, timeoutMs),
     readJuplendPositions({
       walletAddress: accountOptions.walletAddress,
       vaultId: accountOptions.vaultId,
@@ -666,6 +696,10 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
   constructor(
     private readonly rpcUrl?: string,
     private readonly jupApiKey?: string,
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+    } = {},
   ) {}
 
   async bootstrapAccount(
@@ -679,6 +713,8 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
       receivedAt,
       this.rpcUrl,
       getJupApiKey(this.jupApiKey),
+      this.options.fetchFn,
+      this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
     );
 
     return {

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

@@ -3,7 +3,12 @@ import type {
   StreamHandle,
 } from "../adapters/types.ts";
 import { AcexError } from "../errors.ts";
-import type { AccountRuntimeOptions, Venue } from "../types/index.ts";
+import { isTransportError, redactSecrets } from "../internal/http-client.ts";
+import type {
+  AccountRuntimeOptions,
+  PrivateRuntimeReason,
+  Venue,
+} from "../types/index.ts";
 import type {
   ClientContext,
   PrivateAccountDataConsumer,
@@ -41,6 +46,23 @@ function normalizePositiveInterval(
     : fallback;
 }
 
+function transportReason(
+  error: unknown,
+  fallback: PrivateRuntimeReason,
+): PrivateRuntimeReason {
+  return isTransportError(error) && error.kind === "rate_limited"
+    ? "rate_limited"
+    : 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>;
@@ -435,7 +457,7 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: record.accountReady,
-          reason: "http_failed",
+          reason: transportReason(error, "http_failed"),
         },
       );
     }
@@ -559,7 +581,7 @@ export class PrivateSubscriptionCoordinator {
               {
                 runtimeStatus: "degraded",
                 ready: record.accountReady,
-                reason: "http_failed",
+                reason: transportReason(error, "http_failed"),
               },
             );
           }
@@ -676,11 +698,13 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: false,
-          reason: record.venue === "juplend" ? "http_failed" : "auth_failed",
+          reason: transportReason(
+            error,
+            record.venue === "juplend" ? "http_failed" : "auth_failed",
+          ),
         },
       );
-      const reason =
-        error instanceof Error && error.message ? ` (${error.message})` : "";
+      const reason = bootstrapErrorDetail(error);
       throw new AcexError(
         "ACCOUNT_BOOTSTRAP_FAILED",
         `Failed to bootstrap account data: ${record.accountId}${reason}`,
@@ -727,7 +751,7 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: false,
-          reason: "auth_failed",
+          reason: transportReason(error, "auth_failed"),
         },
       );
       throw new AcexError(

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();
+}