@0xmonaco/react 1.0.50 → 1.0.53

package/dist/hooks/useUserOrders/useUserOrders.d.ts

@@ -1,11 +1,138 @@
+import type { Order, OrderEvent, OrderSnapshotItem, OrderStatus } from "@0xmonaco/types";
 import type { UseUserOrdersReturn } from "./types";
+export declare function useUserOrders(maxOrders?: number): UseUserOrdersReturn;
 /**
- * Hook for subscribing to real-time user order events via WebSocket (authenticated)
+ * Map one `orders` snapshot row onto the REST `Order` model, or `null` when
+ * this SDK version cannot describe it.
  *
- * Fetches initial orders from the REST API, then subscribes to real-time updates.
- * Requires authentication - the user must be logged in with a session key.
- * User is identified on the backend from the signed session-key handshake.
+ * Same decline contract as {@link orderFromEvent}, for the same reason: the
+ * wire values are handed through unvalidated, and relabelling a future order
+ * type or side renders an order as something it is not. `status` joins the
+ * declining set here, unlike on an `OrderPlaced` — that event IS a submitted
+ * order whatever string it carries, whereas a snapshot row's status is the
+ * order's actual resting state and has no honest substitute.
  *
- * @param maxOrders - Maximum number of orders to keep in state (default: 50)
+ * The row's optionals arrive as explicit `null` (Rust `Option`s serialized
+ * without `skip_serializing_if`), so they are normalized to absent: the REST
+ * model declares them `?:`, and leaking `null` past it would have consumers
+ * branching on a value the model says cannot occur.
  */
-export declare function useUserOrders(maxOrders?: number): UseUserOrdersReturn;
+export declare function orderFromSnapshotItem(item: OrderSnapshotItem): Order | null;
+/**
+ * Apply a subscribe-time `orders` snapshot to the current list.
+ *
+ * The snapshot carries RESTING orders only, so — unlike the balances one — it
+ * is not the whole list this hook shows. Replacing wholesale would erase every
+ * filled or cancelled order the user just placed, so it reconciles through
+ * the same version-first ordering as {@link mergeOrders}, with its cap applied
+ * by age.
+ *
+ * It IS complete for the persisted resting set, so absence identifies rows that
+ * need resolution — but it is not itself a terminal-state tombstone. On a fast
+ * reconnect persistence may lag a newer resting event retained from the prior
+ * connection, while an order that really filled or was cancelled during the
+ * outage is absent for the same reason: it no longer rests. The pure merge
+ * therefore keeps omitted resting rows and reports their ids so the caller can
+ * issue the targeted `getOrder` required by the shared order contract. That
+ * point read is cache-first and returns the state/version that can be ranked.
+ * Terminal rows are kept exactly as before: the snapshot never carried them,
+ * so their absence says nothing.
+ *
+ * A snapshot row is ranked against the order already held on `version`. The
+ * snapshot wins when its version is equal or higher, because it is the final
+ * state for that sequencer step; a lower version loses. A versioned local row
+ * also wins over an unversioned snapshot: the latter cannot be ranked and may
+ * be persisted state lagging the previous connection's live stream. When both
+ * sides are unversioned, the pre-counter fallback keeps the snapshot's original
+ * precedence instead of comparing incompatible timestamps; that also permits a
+ * validly-null `updatedAt`.
+ *
+ * A snapshot row is LAYERED over the order it already knows rather than
+ * replacing it. `OrderSnapshotItem` is not a whole `Order`: it carries no
+ * `postOnly`, `expirationDate`, `positionSide`, `terminalReason` or fee
+ * aggregates. Substituting a winning snapshot row would otherwise erase every
+ * one of those — including `postOnly`, where absence is never evidence of
+ * `false`. Spreading the row over the existing order lets the snapshot own
+ * exactly the fields it describes and leaves the rest standing.
+ *
+ * The fee aggregates are the one part that can then go stale rather than
+ * missing: they accumulate with fills, and a fill this connection never saw
+ * moves them. So a snapshot row that reports MORE filled quantity than the row
+ * it supersedes schedules the debounced REST re-read, which is the only source
+ * for them. A snapshot that changes nothing about the fill state schedules
+ * nothing, so a quiet reconnect still costs no request.
+ *
+ * `hasUndescribableRow` reports rows this version declined, `hasOfflineFill`
+ * rows whose fills this connection never saw, and `missingRestingOrderIds`
+ * names snapshot omissions that need point reads. The first two let the caller
+ * schedule the debounced list re-read; the last must not use a list page because
+ * an old order can fall outside it.
+ *
+ * Pure, and called with the current list read from a ref rather than from
+ * inside a state updater — an updater must stay free of side effects, and its
+ * signals exist precisely to drive those reads.
+ */
+export declare function applyOrderSnapshot(current: Order[], items: OrderSnapshotItem[], limit: number): {
+    orders: Order[];
+    hasUndescribableRow: boolean;
+    hasOfflineFill: boolean;
+    missingRestingOrderIds: string[];
+};
+/**
+ * The statuses the subscribe-time snapshot treats as resting.
+ *
+ * Mirrors the server's own `SNAPSHOT_RESTING_ORDER_STATUSES` — an order in one
+ * of these is still working on the book, so the snapshot carries it and its
+ * absence therefore means it stopped resting. Every other status is terminal
+ * or post-trade, never carried, so absence says nothing about it.
+ *
+ * The two sets must not drift: a status the server started treating as resting
+ * but this one does not would put its orders back in the stale-forever case
+ * this drop exists to fix, and one this set claims but the server does not
+ * would delete rows on an absence that means nothing. Exported so
+ * `useUserOrders.test.ts` can pin it against the Rust constant directly.
+ *
+ * A `Record<..., true>` over a subset of `OrderStatus`, read through
+ * `Object.hasOwn`, for the same reasons as {@link asKnown}: no prototype walk,
+ * and the union's own membership is checked by the compiler.
+ */
+export declare const SNAPSHOT_RESTING_STATUSES: Partial<Record<OrderStatus, true>>;
+/**
+ * Map snapshot rows onto the REST model, reporting whether any was declined.
+ *
+ * Split out of {@link applyOrderSnapshot} because it needs no view of the
+ * current list, which makes the mapping — and the decline rule that governs it
+ * — testable on its own.
+ */
+export declare function snapshotOrderRows(items: OrderSnapshotItem[]): {
+    rows: Order[];
+    hasUndescribableRow: boolean;
+};
+/**
+ * Reconcile a REST read against live state, ranking on `version` first.
+ *
+ * The resync runs with the subscription open, so `fetched` may already be stale
+ * by the time it lands. Three cases:
+ *
+ * - In both: when either row has `version`, the versioned side wins; when both
+ *   do, the incoming REST row wins on `>=` because it is that step's final
+ *   state. Only when neither has a version does `updatedAt` arbitrate.
+ * - Live only: keep it. Either it was placed over the socket after the read
+ *   started, or it is an older row the page no longer reaches — the two are
+ *   indistinguishable here, which is why the cap is applied by age below
+ *   rather than by which side a row came from.
+ * - REST only: take it. This is the order the resync exists to recover.
+ *
+ * The union is then sorted newest-first by `createdAt` and truncated to
+ * `limit`, so the row dropped at the cap is the genuinely oldest one. A missing
+ * or unparseable `createdAt` sorts last rather than to the top.
+ */
+export declare function mergeOrders(current: Order[], fetched: Order[], limit: number): Order[];
+/**
+ * Create an Order object from an OrderPlaced event
+ */
+export declare function orderFromEvent(event: OrderEvent): Order | null;
+/**
+ * Update an existing Order with data from a WebSocket event
+ */
+export declare function updateOrderFromEvent(order: Order, event: OrderEvent): Order;