test: add MockExchange unit tests (#107)

Adds 8 unit tests for MockExchange covering determinism, order lifecycle,
balance accounting, resting/partial fills, cancel semantics, and reset.

The MockExchange implementation was developed independently on main;
this PR's test suite is the unique contribution and is merged with
full author credit.

Closes #19

Author: mooncitydev

core/src/BaseExchange.ts

@@ -826,17 +826,24 @@ export abstract class PredictionMarketExchange {
     }
 
     /**
-     * Fetch the current order book (bids/asks) for a specific outcome.
-     * Essential for calculating spread, depth, and execution prices.
+     * Fetch the order book (bids/asks) for a specific outcome.
      *
      * @param outcomeId - The Outcome ID (outcomeId) or market slug
-     * @param side - Optional 'yes' or 'no' to explicitly indicate the
-     *   outcome side. Required for exchanges where the API returns a
-     *   single orderbook per market (e.g. Limitless) and the caller
-     *   passes a slug instead of a token ID.
-     * @returns Current order book with bids and asks
+     * @param limit - Max number of bid/ask levels to return (CCXT-style).
+     *   For range queries, limits the number of snapshots returned.
+     * @param params - Optional parameters:
+     *   - `side`: 'yes' or 'no' — explicitly indicate the outcome side
+     *     (required for exchanges like Limitless where the API returns a
+     *     single orderbook per market).
+     *   - `since`: Unix timestamp (ms) — fetch a historical snapshot from
+     *     the archive at or before this time (hosted API only).
+     *   - `until`: Unix timestamp (ms) — when combined with `since`,
+     *     returns an array of OrderBook snapshots between `since` and
+     *     `until` (hosted API only).
+     * @returns Order book with bids and asks. Returns OrderBook[] when
+     *   both `since` and `until` are provided.
      */
-    async fetchOrderBook(outcomeId: string, side?: 'yes' | 'no'): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, limit?: number, params?: Record<string, any>): Promise<OrderBook> {
         throw new Error("Method fetchOrderBook not implemented.");
     }
 

core/src/exchanges/baozi/index.ts

@@ -123,7 +123,7 @@ export class BaoziExchange extends PredictionMarketExchange {
         return [];
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const rawMarket = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(rawMarket, outcomeId);
     }

core/src/exchanges/gemini-titan/index.ts

@@ -106,7 +106,7 @@ export class GeminiTitanExchange extends PredictionMarketExchange {
             .filter((e): e is UnifiedEvent => e !== null);
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const { instrumentSymbol } = fromOutcomeId(outcomeId);
         const raw = await this.fetcher.fetchRawOrderBook(instrumentSymbol);
         if (!raw) {

core/src/exchanges/hyperliquid/index.ts

@@ -128,7 +128,7 @@ export class HyperliquidExchange extends PredictionMarketExchange {
             .filter((e): e is UnifiedEvent => e !== null);
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(raw, outcomeId);
     }

core/src/exchanges/kalshi/index.ts

@@ -193,7 +193,7 @@ export class KalshiExchange extends PredictionMarketExchange {
     return this.normalizer.normalizeOHLCV(rawCandles, params);
   }
 
-  async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+  async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
     validateIdFormat(outcomeId, "OrderBook");
     const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
     return this.normalizer.normalizeOrderBook(raw, outcomeId);

core/src/exchanges/limitless/index.ts

@@ -200,14 +200,15 @@ export class LimitlessExchange extends PredictionMarketExchange {
         return this.normalizer.normalizeOHLCV!(rawPrices as any, params);
     }
 
-    async fetchOrderBook(outcomeId: string, side?: 'yes' | 'no'): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, limit?: number, params?: Record<string, any>): Promise<OrderBook> {
         const slug = await this.resolveSlug(outcomeId);
         const rawOrderBook = await this.fetcher.fetchRawOrderBook!(slug);
         const orderBook = this.normalizer.normalizeOrderBook!(rawOrderBook as any, outcomeId);
 
         // The Limitless API always returns the Yes-side order book regardless
         // of which token is queried. If the caller asked for the No token,
         // flip: noBid = 1 - yesAsk, noAsk = 1 - yesBid.
+        const side = params?.side;
         const isNoToken = side === 'no' || (!side && await this.isNoOutcome(outcomeId, slug));
         if (isNoToken) {
             return {

core/src/exchanges/mock/index.ts

@@ -317,7 +317,7 @@ export class MockExchange extends PredictionMarketExchange {
         return limit !== undefined ? events.slice(offset, offset + limit) : events.slice(offset);
     }
 
-    override async fetchOrderBook(id: string): Promise<OrderBook> {
+    override async fetchOrderBook(id: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const f = new SeededRng(id);
         const midPrice = round(f.float(0.1, 0.9), 3);
         const spread = round(f.float(0.005, 0.03), 3);

core/src/exchanges/myriad/index.ts

@@ -107,7 +107,7 @@ export class MyriadExchange extends PredictionMarketExchange {
         return this.normalizer.normalizeOHLCV(rawMarket, params, parsedOutcomeId);
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const parts = outcomeId.split(':');
         if (parts.length >= 3) {
             const [networkId, marketId, oid] = parts;

core/src/exchanges/opinion/index.ts

@@ -207,7 +207,7 @@ export class OpinionExchange extends PredictionMarketExchange {
         return this.normalizer.normalizeOHLCV({ history: rawPoints }, params);
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
         return this.normalizer.normalizeOrderBook(raw, outcomeId);
     }

core/src/exchanges/polymarket/index.ts

@@ -159,7 +159,7 @@ export class PolymarketExchange extends PredictionMarketExchange {
         return this.normalizer.normalizeOHLCV(raw, params);
     }
 
-    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, _limit?: number, _params?: Record<string, any>): Promise<OrderBook> {
         validateIdFormat(outcomeId, 'OrderBook');
         validateOutcomeId(outcomeId, 'OrderBook');
         const raw = await this.fetcher.fetchRawOrderBook(outcomeId);