perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/qfex/ws-transport.d.ts

@@ -0,0 +1,294 @@
+/**
+ * QFEX Trade WebSocket transport (design §14.2 as amended by §14.12 #2, #3, #4, #11, #13).
+ *
+ * The venue has no request id. Correlation therefore rests on four rules:
+ *  1. ONE command at a time per connection (FIFO) — reads share the queue.
+ *  2. An order is recognized by its GENERATED client order id only; every frame is ignored
+ *     until an order_response for that id arrives (ACK or rejection), then the order is pinned
+ *     to the `order_id` of that frame. A user-supplied id is never used (ids are not unique on
+ *     the venue).
+ *  3. The "sent" boundary is the call to `ws.send()`: a socket that is not OPEN before it =
+ *     NOT SENT (definite). Anything that goes wrong after it — send callback error, close,
+ *     timeout, ServerError, an error frame without a matching echo — is an UNKNOWN outcome
+ *     (ORDER_PENDING). Nothing is ever re-sent or replayed.
+ *  4. After any timeout / unknown outcome the connection is destroyed, so a late frame can
+ *     never meet the next command. The next command opens a fresh, re-authenticated,
+ *     re-subscribed connection.
+ *
+ * Status is never inferred from silence: a GTC / ALO order is returned as acknowledged
+ * (pending) right after its ACK; "open" comes only from a get_user_orders row.
+ *
+ * cancel_on_disconnect is NOT in the message whitelist: this transport cannot send it.
+ * (A different connection of the same user that enabled it — e.g. the official CLI — still
+ * cancels all of the account's orders when THAT connection drops.)
+ *
+ * Idle: between commands the socket is unref()'d so it never keeps the process alive, and it
+ * is closed after `idleCloseMs`. The server keeps an authenticated connection alive with
+ * WebSocket ping frames (docs authenticate page); `ws` answers them automatically.
+ */
+import type { RateLimitPolicy } from "../venue.js";
+import { type QfexErrFrame } from "./errors.js";
+import { type QfexCredentials } from "./signing.js";
+export interface QfexTimeouts {
+    connectMs: number;
+    authMs: number;
+    subscribeMs: number;
+    /** First correlated order_response after an add / modify. */
+    ackMs: number;
+    /** IOC / FOK: terminal frame, measured from the send (includes the 500 ms speed bump). */
+    immediateFinalMs: number;
+    /**
+     * ALO (post-only): how long after the send a terminal frame is awaited once the order was
+     * ACKed. Docs (docs.qfex.com "Order Entry"): "If an ALO order would immediately match with an
+     * existing order, it is **cancelled** instead." — the venue ACKs first and sends the CANCELLED
+     * order_response afterwards (live production 2026-10-05). The docs give no timing for that
+     * frame; the window covers the venue's 500 ms speed bump with margin. No frame in the window
+     * = the order rests (as before).
+     */
+    postOnlyFinalMs: number;
+    /** After a terminal frame: wait for fill frames until they add up. */
+    fillsMs: number;
+    cancelMs: number;
+    readMs: number;
+}
+export declare const QFEX_TIMEOUTS: QfexTimeouts;
+/** Idle connection lifetime for long-lived processes (MCP server, bots). */
+export declare const QFEX_IDLE_CLOSE_MS = 30000;
+/**
+ * Every message type this transport may send. `cancel_on_disconnect` is deliberately absent
+ * (unit-test pinned): enabling it would cancel ALL of the account's orders when a one-shot
+ * CLI connection closes.
+ */
+export declare const QFEX_SENDABLE_TYPES: ReadonlySet<string>;
+export type QfexFrame = Record<string, unknown>;
+export interface QfexOrderResponse {
+    order_id: string;
+    symbol: string;
+    status: string;
+    quantity: number;
+    price: number;
+    take_profit: number | null;
+    stop_loss: number | null;
+    side: "BUY" | "SELL";
+    type: string;
+    time_in_force: string;
+    user_id: string;
+    client_order_id: string;
+    quantity_remaining: number;
+    update_time: number;
+    trade_id: string | null;
+    /** Echo of the order's reduce-only flag (a JSON boolean on production frames; absent from the documented example). */
+    reduce_only?: boolean;
+}
+export interface QfexFillResponse {
+    trade_id: string;
+    symbol: string;
+    price: number;
+    quantity: number;
+    side: "BUY" | "SELL";
+    order_id: string;
+    client_order_id: string;
+    fee: number;
+}
+/** `order_response` payload of a frame, or null. Only frames with the fields correlation needs qualify. */
+export declare function orderResponseOf(frame: QfexFrame): QfexOrderResponse | null;
+export declare function fillResponseOf(frame: QfexFrame): QfexFillResponse | null;
+/**
+ * Error frame in any documented shape (design §14.12 #11):
+ *   { "err": { error_code, message, incoming_message } }            /websocket/errors + AsyncAPI
+ *   { "type": "Err", error_code, message, incoming_message }         /websocket/rate
+ *   { "type": "error", error_code, message }                         the docs' own client samples
+ * An absent or empty (`{}`) incoming_message is "no echo".
+ */
+export declare function errFrameOf(frame: QfexFrame): QfexErrFrame | null;
+export interface QfexSessionOptions {
+    /** wss://trade.qfex.com (no query). */
+    url: string;
+    network: "mainnet" | "testnet";
+    credentials: QfexCredentials;
+    /** Concrete account UUID the session authenticates as. */
+    accountId: string;
+    /** Builder code attached to the connection's auth; null = none. */
+    builderCode: string | null;
+    rateLimit: RateLimitPolicy;
+    timeouts: QfexTimeouts;
+    idleCloseMs: number;
+}
+type Waited = {
+    kind: "frame";
+    frame: QfexFrame;
+} | {
+    kind: "timeout";
+} | {
+    kind: "closed";
+    reason: string;
+};
+/** Frame source handed to a command body. */
+export interface QfexCommandIo {
+    /** Next frame, or timeout / close. A timeout or close marks the session for destruction unless `soft`. */
+    next(deadlineAt: number, soft?: boolean): Promise<Waited>;
+}
+/** Remediation of an order whose outcome is unknown: the status lookup by generated client id. */
+export declare function qfexPendingRemediation(spec: {
+    clientOrderId: string | null;
+    symbol: string | null;
+}): string;
+export declare class QfexTradeSession {
+    private readonly opts;
+    private conn;
+    private queue;
+    private idleTimer;
+    private inFlight;
+    /** Number of connections opened by this session (diagnostics / tests). */
+    connectCount: number;
+    constructor(opts: QfexSessionOptions);
+    private fail;
+    private nextFrame;
+    /** Drop the connection without a closing handshake; its late frames go nowhere. */
+    private destroy;
+    /** Close the connection (normal closure). Safe to call at any time; queued after the running command. */
+    close(): Promise<void>;
+    private setRef;
+    /** true when nothing owned by this session keeps the event loop alive. */
+    isIdleUnref(): boolean;
+    private sendRaw;
+    private notReady;
+    /** connect → auth → subscribe. Every failure here is BEFORE any command was sent. */
+    private open;
+    /** Authenticate only (key import): connect + auth + subscribe, then close. Sends no command. */
+    verifyAuth(): Promise<void>;
+    private closeNow;
+    private enqueue;
+    private onSigint;
+    /**
+     * Run one command: wait for the queue, connect if needed, send, then let `body` read frames.
+     * Throws PerpError. Mutating commands: not-sent failures are definite (ORDER_REJECTED "not
+     * sent"), post-send failures are ORDER_PENDING. The session is destroyed after any timeout,
+     * close or thrown non-definite error inside `body`.
+     */
+    private transact;
+    /** Unknown-outcome error of a mutating command (ORDER_PENDING, with the c:<id> lookup). */
+    private pending;
+    /**
+     * An error frame during a command. Read: the mapped error. Mutating: a definite refusal only
+     * when the venue echoed THIS request and the code is a refusal; otherwise unknown.
+     */
+    private errOutcome;
+    private assertUser;
+    /**
+     * add_order. Resolves once the venue has answered for THIS order as far as the order type
+     * allows: `immediate` (IOC / FOK) waits for a terminal frame; a resting order returns right
+     * after its first correlated frame — except `postOnly` (ALO), which waits postOnlyFinalMs for
+     * the venue's CANCELLED frame (it would have crossed) before it is reported resting. Throws the mapped rejection (definite), or ORDER_PENDING
+     * when nothing correlated arrived (session destroyed).
+     */
+    addOrder(req: {
+        params: Record<string, unknown> & {
+            symbol: string;
+            client_order_id: string;
+        };
+        immediate: boolean;
+        /** ALO: see QfexTimeouts.postOnlyFinalMs. */
+        postOnly?: boolean;
+        lotSize: string;
+        band: {
+            lower: string;
+            upper: string;
+        } | null;
+    }): Promise<QfexAddResult>;
+    /**
+     * cancel_order by ORDER ID (the adapter resolves client ids first: a client-id cancel would
+     * cancel every order sharing that id). Never throws for an unproven cancel — "unknown".
+     */
+    cancelOrder(symbol: string, orderId: string): Promise<QfexCancelOutcome>;
+    /** cancel_stop_order (TAKE_PROFIT / STOP_LOSS rows of get_user_orders). */
+    cancelStopOrder(symbol: string, stopOrderId: string): Promise<QfexCancelOutcome>;
+    private cancelById;
+    /**
+     * cancel_all_orders. The venue documents no completion signal: CANCELLED frames for the
+     * `expected` order ids are collected until all arrived or the window ends. What is not
+     * proven here is settled by the caller's verifying get_user_orders.
+     */
+    cancelAll(symbol: string | null, expected: ReadonlySet<string>, watch?: ReadonlySet<string>): Promise<{
+        cancelled: string[];
+        frames: QfexFrame[];
+        complete: boolean;
+        note: string | null;
+    }>;
+    /**
+     * modify_order (wire function; the adapter keeps amend gated until Q5 is verified).
+     * The reply carries a NEW order_id. It is accepted only when it is MODIFIED, carries the
+     * client id of the order being modified AND its symbol / side / type / price / quantity equal
+     * the request. A CANNOT_MODIFY_* / rejection frame is matched on the OLD order id.
+     */
+    modifyOrder(req: {
+        params: Record<string, unknown> & {
+            symbol: string;
+            order_id: string;
+            side: string;
+            order_type: string;
+            price: number;
+            quantity: number;
+        };
+        clientOrderId: string;
+        lotSize: string;
+        tickSize: string;
+    }): Promise<QfexOrderResponse>;
+    /** get_user_orders: every open order (stops included as TAKE_PROFIT / STOP_LOSS rows), all pages. */
+    getUserOrders(symbol: string | null): Promise<QfexOrderResponse[]>;
+}
+export interface QfexAddResult {
+    orderId: string;
+    clientOrderId: string;
+    /** Correlated order_response frames in arrival order ([0] = the ACK or first status). */
+    responses: QfexOrderResponse[];
+    /** fill_response frames of this order, de-duplicated by trade_id. */
+    fills: QfexFillResponse[];
+    /** The venue frame after which nothing of the order can execute; null when none arrived. */
+    terminal: QfexOrderResponse | null;
+    /** Why waiting stopped: a terminal frame, a resting order's ACK, or a timeout / close after the ACK. */
+    ended: "terminal" | "resting" | "timeout" | "closed";
+    frames: QfexFrame[];
+    /** user_id values that differ from the session account (Q22 unverified — reported, not failed). */
+    userIdMismatches: string[];
+}
+export type QfexCancelOutcome = {
+    kind: "cancelled";
+    frame: QfexOrderResponse;
+}
+/** The venue answered for this order and did NOT cancel it (NO_SUCH_ORDER, REJECTED, already FILLED). */
+ | {
+    kind: "refused";
+    status: string;
+    frame: QfexOrderResponse;
+}
+/** Sent, not proven either way. */
+ | {
+    kind: "unknown";
+    reason: string;
+};
+/** The process-wide session for this identity. A different builder code (or --no-builder) is a different session. */
+export declare function qfexTradeSession(opts: QfexSessionOptions): QfexTradeSession;
+export interface QfexMdsSnapshot {
+    /** Venue symbol → mark price entry (each carries its own venue timestamp). */
+    marks: Map<string, {
+        price: string;
+        time: number;
+    }>;
+    /** Venue symbol → open interest (base units). */
+    openInterest: Map<string, string>;
+    /** Venue symbol → 24h volume, quote notional. */
+    volumeNotional: Map<string, string>;
+    frame: QfexFrame;
+}
+/** Parse one `market_stats` frame. */
+export declare function parseMarketStats(frame: QfexFrame): QfexMdsSnapshot;
+/** How long a one-shot MDS snapshot may take (connect + first market_stats frame). */
+export declare const QFEX_MDS_TIMEOUT_MS = 3000;
+/**
+ * One `market_stats` snapshot from the public MDS WebSocket, then close. `symbol` = one venue
+ * symbol (order reference prices) or "*" (scans / listings). Throws PRICE_STALE when no
+ * snapshot arrives in time — never substitutes index / last / mid.
+ */
+export declare function fetchQfexMarketStats(mdsUrl: string, symbol: string, timeoutMs: number): Promise<QfexMdsSnapshot>;
+export {};