@xapy/orderbook 0.1.28 → 0.1.30

package/dist/exchanges/mexc/index.cjs

@@ -0,0 +1,729 @@
+'use strict';
+
+// src/core/symbol.ts
+function parseSymbol(symbol) {
+  const [pair, settle] = symbol.split(":");
+  const parts = (pair ?? "").split("/");
+  const base = parts[0]?.toUpperCase();
+  const quote = parts[1]?.toUpperCase();
+  if (!base || !quote) {
+    throw new Error(
+      `invalid symbol "${symbol}" \u2014 expected "BASE/QUOTE" or "BASE/QUOTE:SETTLE"`
+    );
+  }
+  if (settle && settle.toUpperCase() !== quote) {
+    throw new Error(
+      `unsupported settlement currency in "${symbol}" \u2014 only linear (settle === quote) is supported`
+    );
+  }
+  return {
+    base,
+    quote,
+    market: settle ? "perpetual" : "spot",
+    pair: `${base}/${quote}`
+  };
+}
+
+// src/transport/http.ts
+async function httpJson(req) {
+  const url = req.transformUrl ? req.transformUrl(req.url) : req.url;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), req.timeoutMs ?? 1e4);
+  try {
+    const res = await fetch(url, {
+      method: req.method ?? "GET",
+      headers: req.headers,
+      body: req.body,
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`HTTP ${res.status} ${res.statusText}: ${text.slice(0, 200)}`);
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/core/errors.ts
+var ExchangeError = class extends Error {
+  constructor(exchange, message, cause) {
+    super(
+      `[${exchange}] ${message}`,
+      cause === void 0 ? void 0 : { cause }
+    );
+    this.exchange = exchange;
+    this.name = "ExchangeError";
+  }
+  exchange;
+};
+
+// src/exchanges/mexc/contracts.ts
+var MEXC_SPOT_REST = "https://api.mexc.com";
+var MEXC_FUTURES_REST = "https://contract.mexc.com";
+var cache = null;
+var inflight = null;
+async function fetchContracts(opts) {
+  const res = await httpJson({
+    url: `${MEXC_FUTURES_REST}/api/v1/contract/detail`,
+    timeoutMs: opts.timeoutMs,
+    transformUrl: opts.transformUrl
+  });
+  const rows = res.data ?? [];
+  if (rows.length === 0) {
+    throw new ExchangeError(
+      "mexc",
+      res.message ? `${res.code}: ${res.message}` : "empty contract/detail response"
+    );
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) map.set(row.symbol.toUpperCase(), row);
+  return map;
+}
+function loadContracts(opts) {
+  inflight ??= fetchContracts(opts).then(
+    (m) => {
+      cache = m;
+      inflight = null;
+      return m;
+    },
+    (err) => {
+      inflight = null;
+      throw err;
+    }
+  );
+  return inflight;
+}
+async function resolveContractSize(symbol, opts) {
+  const k = symbol.toUpperCase();
+  const hit = cache?.get(k);
+  const contract = hit ?? (await loadContracts(opts)).get(k);
+  if (!contract) {
+    throw new ExchangeError(
+      "mexc",
+      `unknown futures contract "${symbol}" \u2014 not listed on mexc`
+    );
+  }
+  const size = Number(contract.contractSize);
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new ExchangeError(
+      "mexc",
+      `contract "${symbol}" has no usable contractSize (${contract.contractSize})`
+    );
+  }
+  return size;
+}
+
+// src/exchanges/mexc/symbols.ts
+var QUOTES = ["USDT", "USDC", "TUSD", "USD", "BTC", "ETH"];
+function toMexcSymbol(symbol, market) {
+  const [base, quote] = symbol.split("/");
+  if (!base || !quote) {
+    throw new Error(`invalid symbol "${symbol}" \u2014 expected "BASE/QUOTE"`);
+  }
+  return market === "perpetual" ? `${base.toUpperCase()}_${quote.toUpperCase()}` : `${base}${quote}`.toUpperCase();
+}
+function fromMexcSymbol(s, market) {
+  const upper = s.toUpperCase();
+  if (market === "perpetual") {
+    const [base, quote] = upper.split("_");
+    return base && quote ? `${base}/${quote}` : upper;
+  }
+  for (const q of QUOTES) {
+    if (upper.endsWith(q) && upper.length > q.length) {
+      return `${upper.slice(0, -q.length)}/${q}`;
+    }
+  }
+  return upper;
+}
+
+// src/exchanges/mexc/rest.ts
+var toSpotLevels = (rows) => (rows ?? []).map(([p, s]) => ({ price: Number(p), size: Number(s) }));
+var toFuturesLevels = (rows, contractSize) => (rows ?? []).map(([price, vol]) => ({
+  price: Number(price),
+  size: Number(vol) * contractSize
+}));
+async function fetchMexcOrderbook(opts) {
+  const symbol = toMexcSymbol(opts.symbol, opts.market);
+  const depth = opts.depth ?? 50;
+  if (opts.market === "spot") {
+    const data = await httpJson({
+      url: `${MEXC_SPOT_REST}/api/v3/depth?symbol=${symbol}&limit=${depth}`,
+      timeoutMs: opts.timeoutMs,
+      transformUrl: opts.transformUrl
+    });
+    return {
+      exchange: "mexc",
+      symbol: fromMexcSymbol(symbol, opts.market),
+      market: opts.market,
+      bids: toSpotLevels(data.bids),
+      asks: toSpotLevels(data.asks),
+      // The spot depth endpoint returns no timestamp of its own.
+      timestamp: Date.now(),
+      sequence: data.lastUpdateId
+    };
+  }
+  const contractSize = await resolveContractSize(symbol, opts);
+  const res = await httpJson({
+    url: `${MEXC_FUTURES_REST}/api/v1/contract/depth/${symbol}?limit=${depth}`,
+    timeoutMs: opts.timeoutMs,
+    transformUrl: opts.transformUrl
+  });
+  if (!res.data) {
+    throw new ExchangeError(
+      "mexc",
+      res.message ? `${res.code}: ${res.message}` : "empty orderbook response"
+    );
+  }
+  return {
+    exchange: "mexc",
+    symbol: fromMexcSymbol(symbol, opts.market),
+    market: opts.market,
+    bids: toFuturesLevels(res.data.bids, contractSize),
+    asks: toFuturesLevels(res.data.asks, contractSize),
+    timestamp: res.data.timestamp ?? Date.now(),
+    sequence: Number(res.data.version ?? 0)
+  };
+}
+
+// src/core/book-merger.ts
+var BookMerger = class {
+  bids = /* @__PURE__ */ new Map();
+  // price -> size
+  asks = /* @__PURE__ */ new Map();
+  sequence = -1;
+  timestamp = 0;
+  hasSnapshot = false;
+  apply(event) {
+    if (event.kind === "snapshot") {
+      this.bids.clear();
+      this.asks.clear();
+      for (const { price, size } of event.bids) {
+        if (size > 0) this.bids.set(price, size);
+      }
+      for (const { price, size } of event.asks) {
+        if (size > 0) this.asks.set(price, size);
+      }
+      this.sequence = event.sequence;
+      this.timestamp = event.timestamp;
+      this.hasSnapshot = true;
+      return this.emit();
+    }
+    if (!this.hasSnapshot) {
+      return { ok: false, reason: "no-snapshot" };
+    }
+    if (event.sequence <= this.sequence) {
+      return this.emit();
+    }
+    if (event.prevSequence !== void 0) {
+      if (event.prevSequence !== this.sequence) {
+        return {
+          ok: false,
+          reason: "gap",
+          expected: this.sequence,
+          received: event.prevSequence
+        };
+      }
+    } else if (event.sequence !== this.sequence + 1) {
+      return {
+        ok: false,
+        reason: "gap",
+        expected: this.sequence + 1,
+        received: event.sequence
+      };
+    }
+    for (const { price, size } of event.bids) {
+      if (size === 0) this.bids.delete(price);
+      else this.bids.set(price, size);
+    }
+    for (const { price, size } of event.asks) {
+      if (size === 0) this.asks.delete(price);
+      else this.asks.set(price, size);
+    }
+    this.sequence = event.sequence;
+    this.timestamp = event.timestamp;
+    return this.emit();
+  }
+  reset() {
+    this.bids.clear();
+    this.asks.clear();
+    this.sequence = -1;
+    this.timestamp = 0;
+    this.hasSnapshot = false;
+  }
+  /** Returns true once the merger has a usable book. */
+  isReady() {
+    return this.hasSnapshot;
+  }
+  emit() {
+    const bids = [];
+    for (const [price, size] of this.bids) bids.push({ price, size });
+    bids.sort((a, b) => b.price - a.price);
+    const asks = [];
+    for (const [price, size] of this.asks) asks.push({ price, size });
+    asks.sort((a, b) => a.price - b.price);
+    return {
+      ok: true,
+      bids,
+      asks,
+      sequence: this.sequence,
+      timestamp: this.timestamp
+    };
+  }
+};
+
+// src/core/event-emitter.ts
+var TypedEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, fn) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return this;
+  }
+  off(event, fn) {
+    this.listeners.get(event)?.delete(fn);
+    return this;
+  }
+  emit(event, ...args) {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) return false;
+    for (const fn of set) fn(...args);
+    return true;
+  }
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+};
+
+// src/core/stream.ts
+var OrderbookStream = class extends TypedEmitter {
+  constructor(onClose) {
+    super();
+    this.onClose = onClose;
+  }
+  onClose;
+  closed = false;
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.onClose();
+    this.removeAllListeners();
+  }
+  /** Yields each maintained book as it becomes available. */
+  async *iter() {
+    const queue = [];
+    let resolveNext = null;
+    let pendingError = null;
+    let ended = false;
+    const onUpdate = (b) => {
+      queue.push(b);
+      resolveNext?.();
+    };
+    const onError = (e) => {
+      pendingError = e;
+      resolveNext?.();
+    };
+    const onClose = () => {
+      ended = true;
+      resolveNext?.();
+    };
+    this.on("update", onUpdate);
+    this.on("error", onError);
+    this.on("disconnected", onClose);
+    try {
+      while (true) {
+        if (pendingError) throw pendingError;
+        const next = queue.shift();
+        if (next) {
+          yield next;
+          continue;
+        }
+        if (ended || this.closed) return;
+        await new Promise((r) => {
+          resolveNext = r;
+        });
+        resolveNext = null;
+      }
+    } finally {
+      this.off("update", onUpdate);
+      this.off("error", onError);
+      this.off("disconnected", onClose);
+    }
+  }
+};
+
+// src/core/reconnect.ts
+var Backoff = class _Backoff {
+  attempt = 0;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  static withDefaults(opts = {}) {
+    return new _Backoff({
+      initialMs: opts.initialMs ?? 500,
+      maxMs: opts.maxMs ?? 3e4,
+      factor: opts.factor ?? 2,
+      jitter: opts.jitter ?? 0.3,
+      maxAttempts: opts.maxAttempts ?? 0
+    });
+  }
+  next() {
+    if (this.opts.maxAttempts > 0 && this.attempt >= this.opts.maxAttempts) {
+      return null;
+    }
+    this.attempt += 1;
+    const base = Math.min(
+      this.opts.initialMs * Math.pow(this.opts.factor, this.attempt - 1),
+      this.opts.maxMs
+    );
+    const jitterRange = base * this.opts.jitter;
+    const wait = Math.max(0, base + (Math.random() * 2 - 1) * jitterRange);
+    return { wait, attempt: this.attempt };
+  }
+  reset() {
+    this.attempt = 0;
+  }
+};
+var hasNativeWebSocket = typeof globalThis.WebSocket !== "undefined";
+
+// src/transport/ws.ts
+function toError(value, fallback = "unknown error") {
+  if (value instanceof Error) {
+    return value.message ? value : new Error(`${value.name}: ${fallback}`);
+  }
+  if (typeof value === "string" && value) return new Error(value);
+  return new Error(fallback);
+}
+function normalizeWsError(ev) {
+  const detail = ev?.message || (ev?.error instanceof Error ? ev.error.message : void 0) || (typeof ev?.error === "string" ? ev.error : void 0);
+  return new Error(detail ? `WebSocket error: ${detail}` : "WebSocket error");
+}
+function describeClose(ev) {
+  if (ev?.reason) return ev.reason;
+  return ev?.code === void 0 ? "closed" : `closed (code ${ev.code})`;
+}
+var cachedCtor = null;
+async function getWebSocketCtor() {
+  if (cachedCtor) return cachedCtor;
+  if (hasNativeWebSocket) {
+    cachedCtor = globalThis.WebSocket;
+    return cachedCtor;
+  }
+  try {
+    const mod = await import('ws');
+    const ctor = mod.default ?? mod.WebSocket;
+    if (!ctor) throw new Error("missing default export");
+    cachedCtor = ctor;
+    return cachedCtor;
+  } catch (err) {
+    throw new Error(
+      "WebSocket unavailable; install peer dep `ws` for Node <22. " + (err instanceof Error ? err.message : String(err))
+    );
+  }
+}
+var WSClient = class extends TypedEmitter {
+  constructor(cfg) {
+    super();
+    this.cfg = cfg;
+    this.backoff = Backoff.withDefaults(cfg.reconnect);
+  }
+  cfg;
+  ws = null;
+  backoff;
+  closed = false;
+  pingTimer = null;
+  async connect() {
+    if (this.closed) return;
+    const WS = await getWebSocketCtor();
+    const url = typeof this.cfg.url === "function" ? await this.cfg.url() : this.cfg.url;
+    const ws = new WS(url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = async () => {
+      this.backoff.reset();
+      this.startPing();
+      this.emit("open");
+      try {
+        await this.cfg.onOpen?.({
+          send: (d) => ws.send(d),
+          close: () => this.close()
+        });
+      } catch (err) {
+        this.emit("error", toError(err, "onOpen handler failed"));
+      }
+    };
+    ws.onmessage = (e) => {
+      let result;
+      try {
+        result = this.cfg.onMessage(e.data);
+      } catch (err) {
+        this.emit("error", toError(err, "onMessage handler failed"));
+        return;
+      }
+      if (result && typeof result.catch === "function") {
+        result.catch(
+          (err) => this.emit("error", toError(err, "onMessage handler failed"))
+        );
+      }
+    };
+    ws.onerror = (e) => {
+      this.emit("error", normalizeWsError(e));
+    };
+    ws.onclose = (e) => {
+      this.stopPing();
+      const reason = describeClose(e);
+      this.emit("close", reason);
+      if (!this.closed) this.scheduleReconnect();
+    };
+  }
+  send(data) {
+    this.ws?.send(data);
+  }
+  close() {
+    this.closed = true;
+    this.stopPing();
+    try {
+      this.ws?.close();
+    } catch {
+    }
+  }
+  startPing() {
+    if (!this.cfg.pingIntervalMs || !this.cfg.pingPayload) return;
+    this.stopPing();
+    this.pingTimer = setInterval(() => {
+      try {
+        this.ws?.send(this.cfg.pingPayload());
+      } catch {
+      }
+    }, this.cfg.pingIntervalMs);
+  }
+  stopPing() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+  scheduleReconnect() {
+    const next = this.backoff.next();
+    if (!next) {
+      this.emit("error", new Error("max reconnect attempts exceeded"));
+      return;
+    }
+    this.emit("reconnecting", next.attempt, next.wait);
+    setTimeout(() => {
+      this.connect().catch((e) => this.emit("error", toError(e, "reconnect failed")));
+    }, next.wait);
+  }
+};
+
+// src/exchanges/mexc/ws.ts
+var WS_FUTURES = "wss://contract.mexc.com/edge";
+var PING_INTERVAL_MS = 2e4;
+function streamMexcOrderbook(opts) {
+  if (opts.market !== "perpetual") {
+    throw new Error(
+      `mexc spot streaming requires the protobuf WS feed, which this adapter does not decode \u2014 use fetchOrderbook("${opts.symbol}") for a REST snapshot, or stream the perpetual ("${opts.symbol}:${opts.symbol.split("/")[1]}")`
+    );
+  }
+  const symbol = toMexcSymbol(opts.symbol, opts.market);
+  const unified = fromMexcSymbol(symbol, opts.market);
+  const contractSize = resolveContractSize(symbol, opts);
+  contractSize.catch(() => {
+  });
+  const merger = new BookMerger();
+  let seedVersion = -1;
+  let lastVersion = -1;
+  let snapshotInFlight = false;
+  let snapshotDone = false;
+  let buffered = [];
+  let recovering = false;
+  let scale = 0;
+  let ws = null;
+  const stream = new OrderbookStream(() => ws?.close());
+  const emit = (r) => {
+    const book = {
+      exchange: "mexc",
+      symbol: unified,
+      market: opts.market,
+      bids: r.bids,
+      asks: r.asks,
+      timestamp: r.timestamp,
+      sequence: r.sequence
+    };
+    stream.emit("update", book);
+  };
+  const triggerSnapshot = () => {
+    if (snapshotInFlight) return;
+    snapshotInFlight = true;
+    contractSize.then(async (size) => {
+      scale = size;
+      return fetchMexcOrderbook({
+        symbol: opts.symbol,
+        market: opts.market,
+        depth: opts.depth ?? 200,
+        timeoutMs: opts.timeoutMs,
+        transformUrl: opts.transformUrl
+      });
+    }).then((snap) => {
+      seedVersion = snap.sequence;
+      const r = merger.apply({
+        kind: "snapshot",
+        bids: snap.bids,
+        asks: snap.asks,
+        sequence: snap.sequence,
+        timestamp: snap.timestamp
+      });
+      if (r.ok) emit(r);
+      snapshotDone = true;
+      lastVersion = -1;
+      const pending = buffered;
+      buffered = [];
+      for (const d of pending) processDelta(d);
+    }).catch((err) => stream.emit("error", err)).finally(() => {
+      snapshotInFlight = false;
+    });
+  };
+  const resync = () => {
+    if (recovering) return;
+    recovering = true;
+    merger.reset();
+    seedVersion = -1;
+    snapshotDone = false;
+    lastVersion = -1;
+    buffered = [];
+    setTimeout(() => {
+      recovering = false;
+      triggerSnapshot();
+    }, 100);
+  };
+  const processDelta = (d) => {
+    const end = Number(d.end ?? d.version ?? 0);
+    const begin = Number(d.begin ?? end);
+    if (end <= seedVersion) return;
+    let prevSequence;
+    if (lastVersion < 0) {
+      if (begin - 1 > seedVersion) {
+        resync();
+        return;
+      }
+      prevSequence = seedVersion;
+    } else {
+      prevSequence = begin - 1;
+    }
+    const r = merger.apply({
+      kind: "delta",
+      bids: toFuturesLevels(d.bids, scale),
+      asks: toFuturesLevels(d.asks, scale),
+      sequence: end,
+      prevSequence,
+      timestamp: d.timestamp ?? d.cts ?? Date.now()
+    });
+    if (r.ok) {
+      lastVersion = end;
+      emit(r);
+    } else if (r.reason === "gap" || r.reason === "no-snapshot") {
+      resync();
+    }
+  };
+  const onMessage = (raw) => {
+    if (typeof raw !== "string") return;
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.channel === "push.depth") {
+      if (msg.symbol && msg.symbol !== symbol) return;
+      const d = msg.data;
+      if (!d) return;
+      if (!snapshotDone) {
+        buffered.push(d);
+        if (!snapshotInFlight) triggerSnapshot();
+        return;
+      }
+      processDelta(d);
+      return;
+    }
+    if (msg.channel === "rs.error" || msg.channel?.startsWith("rs.error")) {
+      stream.emit("error", new ExchangeError("mexc", String(msg.data)));
+      return;
+    }
+    if (msg.channel === "rs.sub.depth" && msg.data !== "success") {
+      stream.emit(
+        "error",
+        new ExchangeError("mexc", `subscribe rejected: ${String(msg.data)}`)
+      );
+    }
+  };
+  ws = new WSClient({
+    url: WS_FUTURES,
+    onOpen: (handle) => {
+      merger.reset();
+      seedVersion = -1;
+      snapshotDone = false;
+      lastVersion = -1;
+      buffered = [];
+      handle.send(
+        JSON.stringify({ method: "sub.depth", param: { symbol } })
+      );
+    },
+    onMessage,
+    pingIntervalMs: PING_INTERVAL_MS,
+    pingPayload: () => JSON.stringify({ method: "ping" })
+  });
+  ws.on("open", () => stream.emit("connected"));
+  ws.on("close", (r) => stream.emit("disconnected", r));
+  ws.on("reconnecting", (a, w) => stream.emit("reconnecting", a, w));
+  ws.on("error", (e) => stream.emit("error", e));
+  ws.connect().catch((e) => stream.emit("error", e));
+  return stream;
+}
+
+// src/exchanges/mexc/index.ts
+var MexcClient = class {
+  exchange = "mexc";
+  transformUrl;
+  timeoutMs;
+  constructor(opts = {}) {
+    this.transformUrl = opts.transformUrl;
+    this.timeoutMs = opts.timeoutMs;
+  }
+  fetchOrderbook(symbol, opts = {}) {
+    const { pair, market } = parseSymbol(symbol);
+    return fetchMexcOrderbook({
+      symbol: pair,
+      market,
+      depth: opts.depth,
+      timeoutMs: this.timeoutMs,
+      transformUrl: this.transformUrl
+    });
+  }
+  /** Perpetuals only — see the class note on spot. */
+  streamOrderbook(symbol, opts = {}) {
+    const { pair, market } = parseSymbol(symbol);
+    return streamMexcOrderbook({
+      symbol: pair,
+      market,
+      depth: opts.depth,
+      transformUrl: this.transformUrl,
+      timeoutMs: this.timeoutMs
+    });
+  }
+};
+
+exports.MEXC_FUTURES_REST = MEXC_FUTURES_REST;
+exports.MEXC_SPOT_REST = MEXC_SPOT_REST;
+exports.MexcClient = MexcClient;
+exports.fetchMexcOrderbook = fetchMexcOrderbook;
+exports.fromMexcSymbol = fromMexcSymbol;
+exports.streamMexcOrderbook = streamMexcOrderbook;
+exports.toMexcSymbol = toMexcSymbol;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map