@flexemarkets/fm-sdk 0.0.2 → 0.0.3

package/dist/market-view.js

@@ -0,0 +1,440 @@
+/**
+ * MarketView — always-current view of a single marketplace, hiding
+ * transport details (WebSocket subscribe, snapshot+delta
+ * reconciliation, sequence-gap recovery, reconnect) behind a small
+ * read-side surface. Mirrors the Java + Python SDKs; same staged
+ * roadmap. See project_fm_sdk_canonical_client.
+ *
+ * Phase 1 scope: API surface + skeleton that delegates to the
+ * existing listen() / callback pipe. No reconciliation, no
+ * snapshot seed, no sharing, no reconnect — those land in Phase 2.
+ */
+import { OrderBooks } from "./orderbook.js";
+import { MarketplaceTrades } from "./trades.js";
+import { NO_SEQ } from "./stomp.js";
+export class DefaultMarketView {
+    marketplaceId;
+    markets;
+    _flexemarkets;
+    _orderBooks;
+    _trades;
+    _events = null;
+    _session = null;
+    _holding = null;
+    _sessionHandlers = [];
+    _holdingHandlers = [];
+    _bookHandlers = [];
+    _gapHandlers = [];
+    _reconnectHandlers = [];
+    _closed = false;
+    /**
+     * Highest ORDERS-UPDATE seq this view has applied so far. Deltas
+     * with `seq <= _lastAppliedSeq` are skipped — they've already been
+     * folded into the local state via the initial REST snapshot or a
+     * previously-applied delta. Initial value comes from the snapshot's
+     * `asOfSeq`; `NO_SEQ` disables filtering (older fm-server).
+     */
+    _lastAppliedSeq = NO_SEQ;
+    static async open(flexemarkets, marketplaceId) {
+        const markets = await flexemarkets.markets(marketplaceId);
+        const view = new DefaultMarketView(flexemarkets, marketplaceId, markets);
+        // Subscribe WS first (so deltas start buffering on the callback
+        // path), then fetch + apply the snapshot, only THEN allow live
+        // dispatch. _seedFromSnapshot flips _seedComplete=true atomically
+        // with the buffer drain on its synchronous tail.
+        //
+        // Phase 2d: own the EventListener directly rather than calling
+        // flexemarkets.listen() — that would clobber the singleton
+        // _eventListener and prevent multiple shared views from
+        // coexisting in one Flexemarkets.
+        view._events = await flexemarkets._connectEvents(marketplaceId, (event) => view._dispatch(event));
+        await view._seedFromSnapshot();
+        return view;
+    }
+    _seedComplete = false;
+    _seedBuffer = [];
+    // 100 matches the default per-market Trades capacity. Plumb through to
+    // observe() later if a caller needs deeper trade scrollback.
+    constructor(flexemarkets, marketplaceId, markets) {
+        this._flexemarkets = flexemarkets;
+        this.marketplaceId = marketplaceId;
+        this.markets = markets;
+        this._orderBooks = new OrderBooks(markets);
+        this._trades = new MarketplaceTrades(markets, 100);
+    }
+    /**
+     * Phase 2a snapshot seeding. Fetches the V1 active-orders and
+     * recent-trades snapshots, applies them to the local aggregators,
+     * and records the `asOfSeq` so subsequent WS deltas can be
+     * filtered to avoid double-applying anything the snapshot already
+     * reflects.
+     *
+     * Known race window: a delta whose order persisted between the
+     * server's seq capture and its order read can appear both in the
+     * snapshot and in a delta with `seq > asOfSeq`, leading to a
+     * double-apply. Same caveat as the existing V0 WS snapshot path.
+     * Phase 2b (gap recovery + ID-based dedup) closes the window.
+     */
+    async _seedFromSnapshot() {
+        const orders = await this._flexemarkets.activeOrdersV1(this.marketplaceId);
+        const trades = await this._flexemarkets.recentTradesV1(this.marketplaceId);
+        // Clear before reseeding so a resync (Phase 2b) doesn't double-add
+        // against existing price levels. Initial seed hits empty books so
+        // clear() is a no-op there.
+        this._orderBooks.clear();
+        this._trades.clear();
+        if (orders.body.length > 0)
+            this._orderBooks.update(orders.body);
+        if (trades.body.length > 0)
+            this._trades.update(trades.body);
+        this._lastAppliedSeq = orders.asOfSeq;
+        // Flip state and drain in a single synchronous block — no
+        // microtask boundary, so no concurrent dispatch can squeeze in
+        // between "buffer drained" and "_seedComplete=true" and leave its
+        // delta orphaned in the buffer.
+        const buffered = this._seedBuffer;
+        this._seedBuffer = [];
+        this._seedComplete = true;
+        this._resyncInFlight = false;
+        for (const update of buffered)
+            this._applyOrdersUpdate(update);
+    }
+    orderBook(marketId) {
+        this._ensureOpen();
+        return this._orderBooks.get(marketId) ?? null;
+    }
+    session() {
+        this._ensureOpen();
+        return this._session;
+    }
+    holding() {
+        this._ensureOpen();
+        return this._holding;
+    }
+    onSessionChange(handler) {
+        this._ensureOpen();
+        this._sessionHandlers.push(handler);
+        return () => {
+            const i = this._sessionHandlers.indexOf(handler);
+            if (i >= 0)
+                this._sessionHandlers.splice(i, 1);
+        };
+    }
+    onOrderBookChange(marketId, handler) {
+        this._ensureOpen();
+        const entry = { marketId, handler };
+        this._bookHandlers.push(entry);
+        return () => {
+            const i = this._bookHandlers.indexOf(entry);
+            if (i >= 0)
+                this._bookHandlers.splice(i, 1);
+        };
+    }
+    onHoldingChange(handler) {
+        this._ensureOpen();
+        this._holdingHandlers.push(handler);
+        return () => {
+            const i = this._holdingHandlers.indexOf(handler);
+            if (i >= 0)
+                this._holdingHandlers.splice(i, 1);
+        };
+    }
+    onGap(handler) {
+        this._ensureOpen();
+        this._gapHandlers.push(handler);
+        return () => {
+            const i = this._gapHandlers.indexOf(handler);
+            if (i >= 0)
+                this._gapHandlers.splice(i, 1);
+        };
+    }
+    onReconnect(handler) {
+        this._ensureOpen();
+        this._reconnectHandlers.push(handler);
+        return () => {
+            const i = this._reconnectHandlers.indexOf(handler);
+            if (i >= 0)
+                this._reconnectHandlers.splice(i, 1);
+        };
+    }
+    submitLimit(marketId, side, units, price) {
+        this._ensureOpen();
+        return this._flexemarkets.submitLimit(this.marketplaceId, marketId, side, units, price);
+    }
+    submitCancel(marketId, originalId) {
+        this._ensureOpen();
+        return this._flexemarkets.submitCancel(this.marketplaceId, marketId, originalId);
+    }
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        if (this._events !== null) {
+            try {
+                this._events.close();
+            }
+            catch { /* best-effort */ }
+            this._events = null;
+        }
+        // Flexemarkets is owned by the caller; we don't close it. If
+        // observe() was the only consumer, the caller can close
+        // Flexemarkets themselves.
+    }
+    _resyncInFlight = false;
+    _dispatch(event) {
+        if (this._closed)
+            return;
+        // FmEvent is a discriminated union.
+        if (_isOrdersUpdate(event)) {
+            if (!this._seedComplete || this._resyncInFlight) {
+                // Buffer until the REST snapshot has landed so we don't
+                // apply deltas before the seq watermark is established.
+                this._seedBuffer.push(event);
+                return;
+            }
+            // Phase 2b gap detection: a delta with seq > lastAppliedSeq+1
+            // means one or more frames were dropped. Refetch the snapshot
+            // and let the seq filter skip whatever the new asOfSeq covers.
+            if (event.seq !== NO_SEQ &&
+                this._lastAppliedSeq !== NO_SEQ &&
+                event.seq > this._lastAppliedSeq + 1) {
+                const expectedSeq = this._lastAppliedSeq + 1;
+                console.warn(`[MarketView] ORDERS-UPDATE seq gap on marketplace ${this.marketplaceId} ` +
+                    `— expected ${expectedSeq}, got ${event.seq}; resyncing from snapshot`);
+                const gap = {
+                    marketplaceId: this.marketplaceId,
+                    expectedSeq,
+                    receivedSeq: event.seq,
+                };
+                for (const h of this._gapHandlers) {
+                    try {
+                        h(gap);
+                    }
+                    catch { /* one bad handler can't stop recovery */ }
+                }
+                this._resyncInFlight = true;
+                this._seedComplete = false;
+                this._seedBuffer.push(event);
+                // _seedFromSnapshot flips both flags back atomically on its
+                // synchronous tail; nothing more to do in the .then().
+                void this._seedFromSnapshot();
+                return;
+            }
+            this._applyOrdersUpdate(event);
+            return;
+        }
+        if (_isSession(event)) {
+            this._session = event;
+            for (const h of this._sessionHandlers)
+                h(event);
+            return;
+        }
+        if (_isHolding(event)) {
+            this._holding = event;
+            for (const h of this._holdingHandlers)
+                h(event);
+            return;
+        }
+        if (_isTransportError(event)) {
+            this._handleTransportError();
+            return;
+        }
+        if (_isWsException(event)) {
+            // STOMP ERROR / parse failure. Logged for visibility;
+            // reconnecting won't help with a malformed frame, so we leave
+            // the view as-is.
+            console.warn(`[MarketView] WS error on marketplace ${this.marketplaceId}: ${event.command} ${event.body}`);
+            return;
+        }
+        // VERSION, SESSION-LIST — not reflected in the public surface yet.
+    }
+    /**
+     * Phase 2c auto-reconnect. On a WsTransportError, reconnect the
+     * underlying WS and re-seed from the V1 snapshot — reconnect is
+     * just the largest possible gap, so 2b's _seedFromSnapshot()
+     * (clear + REST snapshot + reapply + seq watermark) handles state
+     * convergence. One reconnect attempt; if it fails the view is left
+     * stale until the caller close()s and observe()s again.
+     */
+    _handleTransportError() {
+        if (this._resyncInFlight)
+            return; // already handling
+        console.warn(`[MarketView] WS transport error on marketplace ${this.marketplaceId}; reconnecting`);
+        this._resyncInFlight = true;
+        this._seedComplete = false;
+        void (async () => {
+            let outcome;
+            try {
+                if (this._events !== null)
+                    await this._events.reconnect();
+                await this._seedFromSnapshot();
+                outcome = { marketplaceId: this.marketplaceId, success: true, reason: null };
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                console.error(`[MarketView] Reconnect failed on marketplace ${this.marketplaceId}; view is stale: ${reason}`);
+                outcome = { marketplaceId: this.marketplaceId, success: false, reason };
+                // Leave _resyncInFlight=true so subsequent dispatches keep
+                // buffering rather than corrupting state; caller can close()
+                // and observe() to recover.
+            }
+            for (const h of this._reconnectHandlers) {
+                try {
+                    h(outcome);
+                }
+                catch { /* don't let one bad handler stop dispatch */ }
+            }
+        })();
+    }
+    _applyOrdersUpdate(update) {
+        // Phase 2a seq filter: drop deltas the snapshot already reflects.
+        // NO_SEQ disables filtering for older fm-server builds that don't
+        // stamp the header.
+        if (update.seq !== NO_SEQ &&
+            this._lastAppliedSeq !== NO_SEQ &&
+            update.seq <= this._lastAppliedSeq) {
+            return;
+        }
+        const orders = update.orders;
+        const touched = _marketIdsTouched(orders);
+        this._orderBooks.update(orders);
+        this._trades.update(orders);
+        for (const marketId of touched) {
+            const book = this._orderBooks.get(marketId);
+            if (!book)
+                continue;
+            for (const h of this._bookHandlers) {
+                if (h.marketId === marketId)
+                    h.handler(book);
+            }
+        }
+        if (update.seq !== NO_SEQ)
+            this._lastAppliedSeq = update.seq;
+    }
+    _ensureOpen() {
+        if (this._closed) {
+            throw new Error(`MarketView for marketplace ${this.marketplaceId} is closed`);
+        }
+    }
+}
+function _marketIdsTouched(orders) {
+    const seen = new Set();
+    for (const o of orders)
+        seen.add(o.marketId);
+    return [...seen];
+}
+function _isOrdersUpdate(event) {
+    return typeof event === "object" && event !== null && event.kind === "orders-update";
+}
+function _isSession(event) {
+    return typeof event === "object" && event !== null && "status" in event && "marketplaceId" in event;
+}
+function _isHolding(event) {
+    return typeof event === "object" && event !== null && "securities" in event;
+}
+function _isTransportError(event) {
+    return typeof event === "object" && event !== null && event.kind === "transport-error";
+}
+function _isWsException(event) {
+    return typeof event === "object" && event !== null && event.kind === "ws-exception";
+}
+/**
+ * Reader-side handle on a refcounted DefaultMarketView. Returned by
+ * Flexemarkets.observe(); multiple handles for the same marketplaceId
+ * share one underlying view + WS subscription + materialized state.
+ * Each handle's close() decrements the shared refcount and tears down
+ * the shared resources on the last close.
+ *
+ * Subscriptions registered via on*Change on this handle are tracked
+ * locally and closed when the handle closes — so a handler doesn't
+ * keep firing into stale state after the handle is gone.
+ */
+export class MarketViewHandle {
+    _shared;
+    _onClose;
+    _mySubscriptions = [];
+    _closed = false;
+    constructor(shared, onClose) {
+        this._shared = shared;
+        this._onClose = onClose;
+    }
+    get marketplaceId() {
+        return this._shared.marketplaceId;
+    }
+    get markets() {
+        this._check();
+        return this._shared.markets;
+    }
+    orderBook(marketId) {
+        this._check();
+        return this._shared.orderBook(marketId);
+    }
+    session() {
+        this._check();
+        return this._shared.session();
+    }
+    holding() {
+        this._check();
+        return this._shared.holding();
+    }
+    onSessionChange(handler) {
+        this._check();
+        const sub = this._shared.onSessionChange(handler);
+        this._mySubscriptions.push(sub);
+        return sub;
+    }
+    onOrderBookChange(marketId, handler) {
+        this._check();
+        const sub = this._shared.onOrderBookChange(marketId, handler);
+        this._mySubscriptions.push(sub);
+        return sub;
+    }
+    onHoldingChange(handler) {
+        this._check();
+        const sub = this._shared.onHoldingChange(handler);
+        this._mySubscriptions.push(sub);
+        return sub;
+    }
+    onGap(handler) {
+        this._check();
+        const sub = this._shared.onGap(handler);
+        this._mySubscriptions.push(sub);
+        return sub;
+    }
+    onReconnect(handler) {
+        this._check();
+        const sub = this._shared.onReconnect(handler);
+        this._mySubscriptions.push(sub);
+        return sub;
+    }
+    submitLimit(marketId, side, units, price) {
+        this._check();
+        return this._shared.submitLimit(marketId, side, units, price);
+    }
+    submitCancel(marketId, originalId) {
+        this._check();
+        return this._shared.submitCancel(marketId, originalId);
+    }
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        // Close subscriptions this handle registered so handlers don't
+        // fire into a closed handle. Subscription is a () => void; calling
+        // twice is idempotent per the existing TS Subscription contract.
+        for (const sub of this._mySubscriptions) {
+            try {
+                sub();
+            }
+            catch { /* best-effort */ }
+        }
+        this._mySubscriptions.length = 0;
+        this._onClose();
+    }
+    _check() {
+        if (this._closed) {
+            throw new Error(`MarketView handle for marketplace ${this._shared.marketplaceId} is closed`);
+        }
+    }
+}
+//# sourceMappingURL=market-view.js.map

package/dist/market-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"market-view.js","sourceRoot":"","sources":["../src/market-view.ts"],"names":[],"mappings":"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"}

package/dist/orderbook.d.ts

@@ -33,6 +33,13 @@ export declare class OrderBook {
     buyLevels(): [number, number][];
     /** Price levels sorted lowest-first (best ask first). */
     sellLevels(): [number, number][];
+    /**
+     * Reset to just-constructed state — empty levels, initialized=false.
+     * Used by MarketView's Phase 2b gap-recovery: refetch the snapshot,
+     * clear(), reapply via update(), so the next delta with
+     * isAvailable=false doesn't underflow against stale levels.
+     */
+    clear(): void;
 }
 /**
  * Container of OrderBook instances, one per market.
@@ -45,4 +52,6 @@ export declare class OrderBooks {
     bestPrice(marketId: number, side: string): number;
     collection(): OrderBook[];
     get(marketId: number): OrderBook;
+    /** Clear every contained book — see {@link OrderBook.clear}. */
+    clear(): void;
 }

package/dist/orderbook.js

@@ -118,6 +118,17 @@ export class OrderBook {
     sellLevels() {
         return [...this._sells.entries()].sort((a, b) => a[0] - b[0]);
     }
+    /**
+     * Reset to just-constructed state — empty levels, initialized=false.
+     * Used by MarketView's Phase 2b gap-recovery: refetch the snapshot,
+     * clear(), reapply via update(), so the next delta with
+     * isAvailable=false doesn't underflow against stale levels.
+     */
+    clear() {
+        this._buys.clear();
+        this._sells.clear();
+        this._initialized = false;
+    }
 }
 /**
  * Container of OrderBook instances, one per market.
@@ -146,5 +157,10 @@ export class OrderBooks {
     get(marketId) {
         return this._books.get(marketId);
     }
+    /** Clear every contained book — see {@link OrderBook.clear}. */
+    clear() {
+        for (const book of this._books.values())
+            book.clear();
+    }
 }
 //# sourceMappingURL=orderbook.js.map

package/dist/orderbook.js.map

@@ -1 +1 @@
-{"version":3,"file":"orderbook.js","sourceRoot":"","sources":["../src/orderbook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"orderbook.js","sourceRoot":"","sources":["../src/orderbook.ts"],"names":[],"mappings":"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"}

package/dist/snapshot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * REST snapshot response bundle: parsed body + the `x-fm-as-of-seq`
+ * header value the snapshot was read at. Returned by `Flexemarkets`
+ * V1 snapshot methods so `MarketView` (and any other caller that
+ * mixes REST snapshots with WS deltas) can reconcile the two
+ * streams: apply deltas whose `seq` is greater than `asOfSeq` and
+ * skip those whose seq is less than or equal.
+ *
+ * `asOfSeq` is `-1` when the server didn't stamp the response
+ * (older fm-server). Callers that depend on the seq for correctness
+ * should treat `-1` as "snapshot reconciliation unavailable" and
+ * either wholesale-replace state on every snapshot fetch or fall
+ * back to a periodic poll.
+ */
+export interface Snapshot<T> {
+    readonly body: T;
+    readonly asOfSeq: number;
+}

package/dist/snapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":""}

package/dist/stomp.d.ts

@@ -23,8 +23,25 @@ export interface WsException {
     body: string;
     exception: Error;
 }
-export type FmEvent = Version | Session | Session[] | Holding | Order[] | WsTransportError | WsException;
+/**
+ * ORDERS-UPDATE delta from the WS stream, carrying the parsed orders
+ * plus the per-marketplace `seq` header fm-server stamps each frame
+ * with. Consumers reconcile this against a REST `Snapshot`: apply
+ * deltas whose `seq` is greater than the snapshot's `asOfSeq` and
+ * skip those whose seq is less than or equal.
+ *
+ * `seq` is `-1` when the server didn't stamp the header (older
+ * fm-server).
+ */
+export interface OrdersUpdate {
+    readonly kind: "orders-update";
+    readonly orders: Order[];
+    readonly seq: number;
+}
+export type FmEvent = Version | Session | Session[] | Holding | OrdersUpdate | WsTransportError | WsException;
 export type EventCallback = (event: FmEvent) => void;
+/** Sentinel for "no seq header" — see OrdersUpdate.seq docstring. */
+export declare const NO_SEQ = -1;
 export declare class EventListener {
     private readonly _wsUrl;
     private readonly _bearerToken;

package/dist/stomp.js

@@ -7,6 +7,27 @@
 import WebSocket from "ws";
 const HEARTBEAT_MS = 30_000;
 const NULL = "\x00";
+/**
+ * Prefix on the `/app` SUBSCRIBE destination selecting fm-server's WS
+ * API version. Empty string → V0 (`/app/marketplaces/{id}`); `"/v1"` →
+ * V1 (`/app/v1/marketplaces/{id}`). V1 omits the bulk ORDERS-UPDATE
+ * snapshot on subscribe, keeping inbound frames small. V1 is the
+ * default; override with `FM_WS_API_VERSION=v0` if talking to an old
+ * fm-server that doesn't speak V1.
+ *
+ * NB: V1 SUBSCRIBE delivers an empty ORDERS-UPDATE; consumers that
+ * need the active book at startup should fetch it via REST
+ * (`GET /api/v1/marketplaces/{id}/orders/active`) and reconcile
+ * against incoming deltas using the `seq` header.
+ */
+const API_VERSION_PREFIX = (() => {
+    const v = (process.env.FM_WS_API_VERSION ?? "v1").trim().toLowerCase();
+    if (v === "v0")
+        return "";
+    if (v === "v1")
+        return "/v1";
+    throw new Error(`FM_WS_API_VERSION must be 'v0' or 'v1', got: ${v}`);
+})();
 export function encodeFrame(frame) {
     const lines = [frame.command];
     for (const [k, v] of Object.entries(frame.headers)) {
@@ -46,6 +67,9 @@ export function decodeFrame(raw) {
 // Event parsing — mirrors Python _parse_event / Java EventParser
 // ---------------------------------------------------------------------------
 const MESSAGE_TYPE = "message-type";
+const SEQ_HEADER = "seq";
+/** Sentinel for "no seq header" — see OrdersUpdate.seq docstring. */
+export const NO_SEQ = -1;
 function parseEvent(frame, parseHolding, parseOrder) {
     const msgType = frame.headers[MESSAGE_TYPE];
     if (msgType === undefined)
@@ -66,12 +90,22 @@ function parseEvent(frame, parseHolding, parseOrder) {
             return parseSession(data);
         case "HOLDING-UPDATE":
             return parseHolding(data);
-        case "ORDERS-UPDATE":
-            return parseOrders(data, parseOrder);
+        case "ORDERS-UPDATE": {
+            const seq = _parseSeq(frame.headers[SEQ_HEADER]);
+            return { kind: "orders-update", orders: parseOrders(data, parseOrder), seq };
+        }
         default:
             return null;
     }
 }
+/** Parse the per-frame `seq` header; falls back to NO_SEQ on absent
+ *  or malformed values. */
+function _parseSeq(value) {
+    if (value === undefined)
+        return NO_SEQ;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : NO_SEQ;
+}
 function parseVersion(data) {
     if (typeof data === "object" && data !== null && "version" in data) {
         return { version: data.version ?? 0 };
@@ -214,11 +248,18 @@ export class EventListener {
         this._ws.send(encodeFrame(frame));
     }
     _subscribe() {
+        // fm-server publishes broadcasts on the V0 destination paths
+        // (/topic/marketplaces/{id}, /user/queue/marketplaces/{id}) for
+        // both V0 and V1 clients — only the @SubscribeMapping gating the
+        // initial snapshot lives at the /v1 prefix. So pub/sub subscriptions
+        // stay on V0 paths regardless of the chosen api-version; only the
+        // /app destination flips. Mirrors fm-ui's web-socket.service.ts
+        // and the Java SDK Events.java pattern.
         const resource = `/marketplaces/${this._marketplaceId}`;
         for (const dest of [
             `/user/queue${resource}`,
             `/topic${resource}`,
-            `/app${resource}`,
+            `/app${API_VERSION_PREFIX}${resource}`,
         ]) {
             const frame = {
                 command: "SUBSCRIBE",