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

package/src/adapters/binance/server-time.ts

@@ -0,0 +1,106 @@
+import {
+  type HttpClientMessages,
+  httpRequest,
+  isTransportError,
+} from "../../internal/http-client.ts";
+import type {
+  RateLimiter,
+  RateLimitScope,
+  VenueServerTime,
+} from "../../types/index.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+interface BinanceServerTimeResponse {
+  serverTime?: unknown;
+}
+
+export interface FetchBinanceServerTimeOptions {
+  readonly rateLimiter?: RateLimiter;
+  readonly fetchFn?: FetchLike;
+  readonly now?: () => number;
+  readonly monotonicNow?: () => number;
+}
+
+const BINANCE_USDM_SERVER_TIME_URL = "https://fapi.binance.com/fapi/v1/time";
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+const BINANCE_SERVER_TIME_HTTP_MESSAGES: HttpClientMessages = {
+  http: ({ status, statusText }) =>
+    `Binance server time request failed: ${status} ${statusText ?? ""}`,
+};
+
+export async function fetchBinanceServerTime(
+  options: FetchBinanceServerTimeOptions = {},
+): Promise<VenueServerTime> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const now = options.now ?? Date.now;
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
+  const scope: RateLimitScope = {
+    venue: "binance",
+    endpointKey: "GET /fapi/v1/time",
+  };
+
+  await options.rateLimiter?.beforeRequest({ scope });
+
+  const requestSentAt = now();
+  const startMono = monotonicNow();
+
+  try {
+    const response = await httpRequest<BinanceServerTimeResponse>({
+      fetchFn,
+      url: BINANCE_USDM_SERVER_TIME_URL,
+      timeoutMs: DEFAULT_HTTP_TIMEOUT_MS,
+      parseAs: "json",
+      jsonParseMode: "response",
+      retryPolicy: {
+        idempotent: true,
+        maxAttempts: 1,
+      },
+      messages: BINANCE_SERVER_TIME_HTTP_MESSAGES,
+    });
+    const responseReceivedAt = now();
+    const endMono = monotonicNow();
+
+    await options.rateLimiter?.afterResponse(
+      { scope },
+      {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+      },
+    );
+
+    const { serverTime } = response.body;
+    if (typeof serverTime !== "number" || !Number.isFinite(serverTime)) {
+      throw new Error(
+        "Binance server time response missing numeric serverTime",
+      );
+    }
+
+    return {
+      serverTime,
+      requestSentAt,
+      responseReceivedAt,
+      roundTripMs: endMono - startMono,
+      estimatedOffsetMs: serverTime - (requestSentAt + responseReceivedAt) / 2,
+    };
+  } catch (error) {
+    if (isTransportError(error)) {
+      await options.rateLimiter?.onTransportError(
+        { scope },
+        {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+        },
+      );
+    }
+
+    throw error;
+  }
+}

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

@@ -1,5 +1,8 @@
 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 +69,8 @@ interface JuplendPriceApiEntry {
   decimals?: number | string;
 }
 
+type FetchLike = typeof fetch;
+
 interface JuplendTokenSearchEntry {
   id?: string;
   address?: string;
@@ -86,6 +91,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 +272,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 +316,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 +345,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 +386,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 +443,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 +459,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 +499,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 +513,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 +531,8 @@ async function loadVaults(
         const enrichedVaults = await enrichVaultsWithJupApi({
           apiKey,
           baseVaults,
+          fetchFn,
+          timeoutMs,
         });
         enrichmentCache.set(cacheKey, {
           loadedAt: now,
@@ -545,9 +572,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 +695,11 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
   constructor(
     private readonly rpcUrl?: string,
     private readonly jupApiKey?: string,
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+      readonly pollIntervalMs?: 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 {
@@ -697,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",
     );
   }
@@ -726,13 +755,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

@@ -9,6 +9,7 @@ import type {
   VenueAccountCapabilities,
   VenueMarketCapabilities,
   VenueOrderCapabilities,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface StreamHandle {
@@ -74,6 +75,7 @@ export interface MarketAdapter {
   readonly venue: Venue;
   readonly marketCapabilities: VenueMarketCapabilities;
   loadMarkets(): Promise<MarketDefinition[]>;
+  fetchServerTime?(): Promise<VenueServerTime>;
   createL1BookStream(
     market: MarketDefinition,
     callbacks: L1BookStreamCallbacks,
@@ -174,6 +176,16 @@ export interface RawOrderUpdate {
   receivedAt: number;
 }
 
+export interface RawOpenOrdersSnapshot {
+  orders: RawOrderUpdate[];
+  snapshotReceivedAt: number;
+  snapshotExchangeTs?: number;
+}
+
+export type FetchOrderRequest =
+  | { symbol: string; orderId: string; clientOrderId?: string }
+  | { symbol: string; clientOrderId: string; orderId?: string };
+
 export interface CreateOrderRequest {
   symbol: string;
   side: OrderSide;
@@ -210,7 +222,6 @@ export interface PrivateStreamOptions {
   reconnectDelayMs: number;
   reconnectMaxDelayMs: number;
   listenKeyKeepAliveMs: number;
-  juplendPollIntervalMs?: number;
   now?: () => number;
 }
 
@@ -228,10 +239,23 @@ export interface PrivateUserDataAdapter {
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawAccountUpdate>;
+  reconcileAccount?(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountBootstrap>;
   bootstrapOpenOrders(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawOrderUpdate[]>;
+  fetchOpenOrders?(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawOpenOrdersSnapshot>;
+  fetchOrder?(
+    credentials: AccountCredentials,
+    request: FetchOrderRequest,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawOrderUpdate | undefined>;
   createOrder(
     credentials: AccountCredentials,
     request: CreateOrderRequest,

package/src/client/context.ts

@@ -1,6 +1,7 @@
 import type {
   RawAccountBootstrap,
   RawAccountUpdate,
+  RawOpenOrdersSnapshot,
   RawOrderUpdate,
 } from "../adapters/types.ts";
 import type {
@@ -10,9 +11,11 @@ import type {
   CancelOrderInput,
   CreateOrderInput,
   HealthEvent,
+  OrderSnapshot,
   PrivateRuntimeReason,
   PrivateRuntimeStatus,
   Venue,
+  VenueOrderCapabilities,
 } from "../types/index.ts";
 
 export interface RegisteredAccountRecord {
@@ -26,6 +29,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;
@@ -75,7 +79,13 @@ export interface PrivateAccountDataConsumer {
     accountId: string,
     venue: Venue,
     update: RawAccountUpdate,
-    options?: { preserveStatus?: boolean },
+    options?: { preserveStatus?: boolean; requestStartedAt?: number },
+  ): void;
+  onPrivateAccountReconcile(
+    accountId: string,
+    venue: Venue,
+    snapshot: RawAccountBootstrap,
+    options: { requestStartedAt: number; preserveStatus?: boolean },
   ): void;
   onPrivateAccountStreamState(
     accountId: string,
@@ -89,13 +99,22 @@ export interface PrivateOrderDataConsumer {
   onPrivateOrderBootstrap(
     accountId: string,
     venue: Venue,
-    snapshots: RawOrderUpdate[],
-  ): void;
+    snapshot: RawOpenOrdersSnapshot,
+    options: { requestStartedAt: number; preserveStatus?: boolean },
+  ): OrderSnapshot[];
+  onPrivateOrderReconcile(
+    accountId: string,
+    venue: Venue,
+    snapshot: RawOpenOrdersSnapshot,
+    options: { requestStartedAt: number; preserveStatus?: boolean },
+  ): OrderSnapshot[];
   onPrivateOrderUpdate(
     accountId: string,
     venue: Venue,
     update: RawOrderUpdate,
+    options?: { requestStartedAt?: number; preserveStatus?: boolean },
   ): void;
+  getPrivateOpenOrders(accountId: string): OrderSnapshot[];
   onPrivateOrderStreamState(
     accountId: string,
     venue: Venue,
@@ -105,13 +124,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(