@0xmonaco/types 1.0.51 → 1.0.54

package/dist/websocket/events/orders-events.d.ts

@@ -102,39 +102,38 @@ export interface CommonOrderEventData {
     /**
      * `true` when the order was admitted post-only (maker-only), so a subscriber
      * can confirm the flag was honoured without a round trip to `getOrder`.
-     * Carried on the `OrderPlaced` acknowledgement, the taker fill, and the
-     * resting order's lifecycle — `OrderPartiallyCancelled` (an in-place
-     * reduction, which is how an MM's own `remainingQuantityTarget` replace is
-     * announced), `OrderCancelled` and `OrderExpired`.
+     * Carried on the `OrderPlaced` acknowledgement, fills in **both roles** —
+     * the maker fill gained it in 0XM-2729 — and the resting order's lifecycle:
+     * `OrderPartiallyCancelled` (an in-place reduction, which is how an MM's own
+     * `remainingQuantityTarget` replace is announced), `OrderCancelled` and
+     * `OrderExpired`.
      *
-     * Declared on the shared block, but two variants can never carry it, and
-     * this optional field is the only thing that says so: a **maker fill**,
-     * which is out of scope because a maker already learned the flag from its
-     * own acknowledgement; and **`OrderRejected`**, which only ever describes a
-     * MARKET order with no liquidity or an unfilled IOC/FOK — and post-only is
-     * refused on both, so no post-only order can reach it.
+     * The maker fill is the one that matters: a post-only order that would have
+     * crossed is refused at admission and emits nothing, so an admitted
+     * post-only order can never produce a taker fill — it rests, and every fill
+     * it ever has is a maker fill. Until 0XM-2729 that meant the flag was absent
+     * on precisely the fills a post-only order produces; now the fill that
+     * partially fills or retires a post-only quote carries it.
      *
-     * Only ever present as `true`: on a variant that CARRIES the field, an order
-     * that is not post-only omits the key rather than sending `postOnly: false`,
-     * exactly as the REST read model's `postOnly?: boolean` does, so
-     * `event.data.postOnly ?? false` reads the same as REST *for that event*.
+     * Two variants never carry it, and a post-only order can reach neither.
+     * `OrderRejected` only describes a MARKET order with no liquidity or an
+     * unfilled IOC/FOK. And `OrderCancelled` has two server payloads: the
+     * resting-order cancellation listed above carries the field, while the one
+     * reporting an IOC or market order's REMAINDER after a partial fill is a
+     * different payload that declares no `post_only` at all. Post-only is
+     * refused on MARKET and IOC/FOK alike, so neither is reachable — which is
+     * why the single `OrderCancelledEvent` interface can declare the field
+     * without lying about any frame a post-only order actually produces.
      *
-     * That equivalence is per-event, and it does NOT hold on a maker fill.
-     * A post-only order rests and therefore fills as a maker, and the maker
-     * payload never declares the field — so `?? false` there would return
-     * `false` for an order REST reports as `true`. Absence on a maker fill
-     * carries NO information. Track `postOnly` as order-level state learned from
-     * the `OrderPlaced` acknowledgement (or a REST read) and carry it forward;
-     * never re-derive it from whichever event arrived last.
-     *
-     * On a carrying variant, absent is not evidence the flag was dropped — it is
-     * the ordinary shape of a non-post-only order, and also what an order placed
-     * before the flag was persisted reports.
-     *
-     * A post-only order that WOULD have crossed the book is rejected before
-     * acceptance and emits no event at all (see `clientOrderId`), so in practice
-     * the flag reaches a subscriber on a resting order's lifecycle — never on a
-     * taker fill, which an admitted post-only order cannot produce.
+     * Only ever present as `true`: an order that is not post-only omits the key
+     * rather than sending `postOnly: false`, exactly as the REST read model's
+     * `postOnly?: boolean` does — so `event.data.postOnly ?? false` reads the
+     * same as REST on every carrying variant, maker fills included. Absent is
+     * not evidence the flag was dropped: it is the ordinary shape of a
+     * non-post-only order, and also what an order placed before the flag was
+     * persisted reports (a maker fill emitted by a server predating 0XM-2729
+     * likewise omits it). The order-level value on the acknowledgement or a
+     * REST read remains the authority for such orders.
      * Wire: `post_only`.
      */
     postOnly?: boolean;

package/dist/websocket/events/position-events.d.ts

@@ -5,8 +5,8 @@
  * liquidation price, isolated margin, leverage).
  *
  * This is an authenticated channel - requires the signed session-key handshake.
- * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
- * state rather than disconnected, so there is no gap signal to reconcile.
+ * Detected broadcast lag closes the connection with 1013 and requires resync.
+ * A lost terminal position update need not have a later replacement.
  */
 /**
  * Position side. The server emits `LONG` or `SHORT` for an open position.

package/dist/websocket/events/position-events.js

@@ -5,6 +5,6 @@
  * liquidation price, isolated margin, leverage).
  *
  * This is an authenticated channel - requires the signed session-key handshake.
- * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
- * state rather than disconnected, so there is no gap signal to reconcile.
+ * Detected broadcast lag closes the connection with 1013 and requires resync.
+ * A lost terminal position update need not have a later replacement.
  */

package/dist/websocket/index.d.ts

@@ -7,3 +7,4 @@ export * from "./base";
 export * from "./client";
 export * from "./clients/orderbook-client";
 export * from "./events";
+export * from "./snapshots";

package/dist/websocket/index.js

@@ -7,3 +7,4 @@ export * from "./base";
 export * from "./client";
 export * from "./clients/orderbook-client";
 export * from "./events";
+export * from "./snapshots";

package/dist/websocket/snapshots.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Subscribe-time WebSocket snapshot types.
+ *
+ * The server injects one `Snapshot` frame per subscription, after the
+ * `Subscribed` ack and before that subscription's first live diff. Its `data`
+ * is the channel's COMPLETE current state as a flat array — a consumer that
+ * applies it wholesale needs no REST baseline read for that channel.
+ *
+ * Two rules hold across every channel:
+ *
+ * - **A snapshot row is the channel's terminal-state payload, not its event
+ *   envelope.** The live frame wraps its payload (`{ event_type, user_id, data }`
+ *   for the authenticated channels); a snapshot row IS the payload, with no
+ *   wrapper and no change metadata. That is why the rows are delivered to their
+ *   own callback instead of the event handler: reducing both would apply the
+ *   same state twice, in two different shapes.
+ * - **The row type is the channel's own `…EventData`**, so the baseline and the
+ *   diffs that follow it describe state identically. `orders` is the one
+ *   exception and has its own {@link OrderSnapshotItem}: a resting order carries
+ *   fields no single order event does (`status` alongside the fill totals) and
+ *   carries none of the change-only fill metadata.
+ *
+ * A channel whose server arm is not implemented yet simply never sends the
+ * frame, so its callback is never invoked. That is a silent no-op, never an
+ * error.
+ */
+import type { OrderSide, OrderType, TimeInForce, TradingMode } from "../trading";
+/**
+ * Receives one channel's complete subscribe-time state.
+ *
+ * Invoked at most once per `Snapshot` frame, always with an array — an empty
+ * baseline arrives as `[]` rather than being skipped, so a consumer can tell
+ * "nothing is open" apart from "no baseline yet".
+ *
+ * Delivery is all-or-nothing: a frame with any unreadable row is withheld
+ * entirely rather than delivered short, because the array is contractually
+ * COMPLETE and a consumer that replaced state from a truncated one would delete
+ * whatever the unreadable row described.
+ *
+ * A frame is produced per WIRE subscription, so on a channel this client
+ * already holds a second subscriber's callback waits for the next reconnect;
+ * see `MonacoWebSocket` for the full rule.
+ */
+export type SnapshotHandler<T> = (items: T[]) => void;
+/**
+ * One resting order in an `orders` channel snapshot.
+ *
+ * The server builds this to be field-compatible with the live order event's
+ * `data` — same names, same casing, decimals as strings — and injects the three
+ * identity fields the read model does not itself carry (`userId`,
+ * `applicationId`, and the resolved `tradingPair` symbol).
+ *
+ * The change-only fill metadata of an order EVENT is deliberately absent: a
+ * snapshot describes resting state, not a fill, so there is no `eventType`,
+ * `tradeId`, `executionPrice`, `lastFillQuantity`, `role`, `fee`, `feeRaw`,
+ * `tradesCount` or slippage. The cumulative `filledQuantity` /
+ * `averageFillPrice` totals are present, because those are state.
+ *
+ * Nullability mirrors the wire exactly. Every optional field below is a Rust
+ * `Option` serialized WITHOUT `skip_serializing_if`, so the key is always
+ * present and carries `null` when unset — hence `| null` rather than `?`.
+ * `clientOrderId` is the sole field the server omits outright, so it is the
+ * sole `?`.
+ *
+ * The value unions are widened (`Union | (string & {})`) for the same reason
+ * the order event's are: the parser hands an unrecognized value through rather
+ * than dropping the row, so a closed type would promise something the runtime
+ * does not honour.
+ */
+export interface OrderSnapshotItem {
+    /** Order identifier (UUID) */
+    orderId: string;
+    /** Owning user (UUID), taken from the authenticated session */
+    userId: string;
+    /** Owning application (UUID), taken from the authenticated session */
+    applicationId: string;
+    /** Trading pair identifier (UUID) */
+    tradingPairId: string;
+    /** Trading pair symbol, e.g. "BTC/USDC" */
+    tradingPair: string;
+    /** Trading mode (e.g. "SPOT", "MARGIN") */
+    tradingMode: TradingMode | (string & {});
+    /** Order side */
+    side: OrderSide | (string & {});
+    /** Order type */
+    orderType: OrderType | (string & {});
+    /** Limit price (decimal string); `null` for a market order */
+    price: string | null;
+    /** Order quantity (decimal string) */
+    quantity: string;
+    /** `quantity` in RAW (integer, base-unit) precision */
+    quantityRaw: string;
+    /** Cumulative quantity filled (decimal string) */
+    filledQuantity: string;
+    /** `filledQuantity` in RAW (integer, base-unit) precision */
+    filledQuantityRaw: string;
+    /** Quantity still resting (decimal string) */
+    remainingQuantity: string | null;
+    /** `remainingQuantity` in RAW (integer, base-unit) precision */
+    remainingQuantityRaw: string | null;
+    /** Order status; the snapshot carries only resting statuses */
+    status: string;
+    /** Time in force */
+    timeInForce: TimeInForce | (string & {}) | null;
+    /** Average fill price (decimal string); `null` before the first fill */
+    averageFillPrice: string | null;
+    /** Order creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last update timestamp (ISO 8601) */
+    updatedAt: string | null;
+    /** Margin account backing a margin/perp order (UUID) */
+    marginAccountId: string | null;
+    /** Position the order is linked to (UUID) */
+    positionId: string | null;
+    /** Leverage for a margin/perp order (decimal string) */
+    leverage: string | null;
+    /** Whether the order can only reduce existing exposure */
+    reduceOnly: boolean;
+    /**
+     * Client-assigned correlation handle, carried so the baseline and the live
+     * events that follow it identify orders the same way. Omitted — not `null` —
+     * when the order carried none, matching the live event payload.
+     */
+    clientOrderId?: string;
+    /**
+     * Sequencer step this order's state was last written by — the SAME counter
+     * the live order events and the REST endpoints carry (0XM-2440).
+     *
+     * The one field here that is not resting state. It is carried because a
+     * reconnecting client ranks this frame against the events it has already
+     * applied by comparing exactly this value, so the frame would be unusable
+     * for its own purpose without it. Compare with `>=`, not `>`: on the stream
+     * equal versions mean the same sequencer step rather than identical state,
+     * and the snapshot row is that step's final state.
+     *
+     * Omitted — not `null` — when unknown, which is what an order last written
+     * before the field existed reports. Absent means unknown, never zero.
+     */
+    version?: number;
+}

package/dist/websocket/snapshots.js

@@ -0,0 +1,26 @@
+/**
+ * Subscribe-time WebSocket snapshot types.
+ *
+ * The server injects one `Snapshot` frame per subscription, after the
+ * `Subscribed` ack and before that subscription's first live diff. Its `data`
+ * is the channel's COMPLETE current state as a flat array — a consumer that
+ * applies it wholesale needs no REST baseline read for that channel.
+ *
+ * Two rules hold across every channel:
+ *
+ * - **A snapshot row is the channel's terminal-state payload, not its event
+ *   envelope.** The live frame wraps its payload (`{ event_type, user_id, data }`
+ *   for the authenticated channels); a snapshot row IS the payload, with no
+ *   wrapper and no change metadata. That is why the rows are delivered to their
+ *   own callback instead of the event handler: reducing both would apply the
+ *   same state twice, in two different shapes.
+ * - **The row type is the channel's own `…EventData`**, so the baseline and the
+ *   diffs that follow it describe state identically. `orders` is the one
+ *   exception and has its own {@link OrderSnapshotItem}: a resting order carries
+ *   fields no single order event does (`status` alongside the fill totals) and
+ *   carries none of the change-only fill metadata.
+ *
+ * A channel whose server arm is not implemented yet simply never sends the
+ * frame, so its callback is never invoked. That is a silent no-op, never an
+ * error.
+ */