pmxt-core 2.44.4 → 2.44.5

package/dist/router/Router.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Router = void 0;
 const BaseExchange_1 = require("../BaseExchange");
+const errors_1 = require("../errors");
 const logger_1 = require("../utils/logger");
 const client_1 = require("./client");
 // ---------------------------------------------------------------------------
@@ -28,13 +29,82 @@ function mergeOrderBooks(books) {
     };
 }
 // ---------------------------------------------------------------------------
+const MOCK_MARKET_OR_OUTCOME_ID_RE = /^(mock-m\d+)(?:-(?:yes|no|\d+))?$/;
+const MOCK_EVENT_ID_RE = /^mock-event-\d+$/;
+class LocalRouterMatchLookupUnsupported extends errors_1.BaseError {
+    constructor(kind, identifier) {
+        super(`LOCAL_MATCH_LOOKUP_UNSUPPORTED: Router match lookup for local mock ${kind} ` +
+            `"${identifier}" cannot be served by the hosted match catalog. ` +
+            `Configure RouterOptions.localExchanges.mock when using Router in-process; ` +
+            `the /api/router sidecar endpoint resolves bundled mock IDs locally and returns [] because mock fixtures have no hosted cross-venue matches.`, 501, 'LOCAL_MATCH_LOOKUP_UNSUPPORTED', false, 'Router');
+    }
+}
+function sourceExchangeIsMock(sourceExchange) {
+    return typeof sourceExchange === 'string' && sourceExchange.toLowerCase() === 'mock';
+}
+function lookupString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function mockMarketIdFromLocalId(id) {
+    const value = lookupString(id);
+    if (!value)
+        return undefined;
+    return value.match(MOCK_MARKET_OR_OUTCOME_ID_RE)?.[1];
+}
+function isMockEventId(id) {
+    const value = lookupString(id);
+    return value !== undefined && MOCK_EVENT_ID_RE.test(value);
+}
+function isMockUrl(url, resource) {
+    const value = lookupString(url);
+    if (!value)
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.hostname === 'mock.pmxt.dev' && parsed.pathname.startsWith(`/${resource}/`);
+    }
+    catch {
+        return value.includes(`mock.pmxt.dev/${resource}/`);
+    }
+}
+function describeMarketLookup(params) {
+    return params.market?.marketId
+        ?? lookupString(params.marketId)
+        ?? lookupString(params.slug)
+        ?? lookupString(params.url)
+        ?? 'unknown';
+}
+function describeEventLookup(params) {
+    return params.event?.id
+        ?? lookupString(params.eventId)
+        ?? lookupString(params.slug)
+        ?? 'unknown';
+}
+function isLocalMockMarketLookup(params) {
+    return sourceExchangeIsMock(params.market?.sourceExchange)
+        || mockMarketIdFromLocalId(params.market?.marketId) !== undefined
+        || mockMarketIdFromLocalId(params.marketId) !== undefined
+        || mockMarketIdFromLocalId(params.slug) !== undefined
+        || isMockUrl(params.url, 'market');
+}
+function isLocalMockEventLookup(params) {
+    return sourceExchangeIsMock(params.event?.sourceExchange)
+        || isMockEventId(params.event?.id)
+        || isMockEventId(params.eventId)
+        || isMockEventId(params.slug);
+}
+function findByUrl(items, url) {
+    return items.find((item) => item.url === url);
+}
 class Router extends BaseExchange_1.PredictionMarketExchange {
     client;
     exchanges;
+    localExchanges;
     constructor(options) {
         super({ apiKey: options.apiKey });
         this.client = new client_1.PmxtApiClient(options.apiKey, options.baseUrl);
         this.exchanges = options.exchanges ?? {};
+        this.localExchanges = options.localExchanges ?? options.exchanges ?? {};
         this.rateLimit = 100;
     }
     get name() {
@@ -126,7 +196,10 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
     // -----------------------------------------------------------------------
     async fetchMarketMatches(params = {}) {
         if (params.market && !params.marketId) {
-            if (params.market.slug && !params.slug) {
+            if (sourceExchangeIsMock(params.market.sourceExchange)) {
+                params = { ...params, marketId: params.market.marketId };
+            }
+            else if (params.market.slug && !params.slug) {
                 params = { ...params, slug: params.market.slug };
             }
             else {
@@ -139,6 +212,9 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         if (!hasIdentifier) {
             return this.fetchMarketMatchesBrowse(params);
         }
+        if (await this.resolveLocalMockMarketLookup(params)) {
+            return [];
+        }
         // Lookup mode: find matches for a specific market.
         const response = await this.client.getMarketMatches(params);
         const matches = response.matches ?? [];
@@ -172,7 +248,10 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
     // -----------------------------------------------------------------------
     async fetchEventMatches(params = {}) {
         if (params.event && !params.eventId) {
-            if (params.event.slug && !params.slug) {
+            if (sourceExchangeIsMock(params.event.sourceExchange)) {
+                params = { ...params, eventId: params.event.id };
+            }
+            else if (params.event.slug && !params.slug) {
                 params = { ...params, slug: params.event.slug };
             }
             else {
@@ -185,6 +264,9 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
             const results = await this.client.browseEventMatches(params);
             return Array.isArray(results) ? results : [];
         }
+        if (await this.resolveLocalMockEventLookup(params)) {
+            return [];
+        }
         // Lookup mode: find matches for a specific event.
         const response = await this.client.getEventMatches(params);
         return response.matches ?? [];
@@ -278,6 +360,75 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         logger_1.logger.warn('fetchArbitrage is deprecated, use fetchMatchedPrices instead');
         return this.fetchArbitrageInternal(params);
     }
+    getLocalExchange(name) {
+        const target = name.toLowerCase();
+        for (const [key, exchange] of Object.entries(this.localExchanges)) {
+            if (key.toLowerCase() === target || exchange.name.toLowerCase() === target) {
+                return exchange;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Local mock IDs are sidecar-only fixtures. Hosted match endpoints do not
+     * know them, so resolve them locally when possible and avoid opaque hosted
+     * "not found" responses.
+     */
+    async resolveLocalMockMarketLookup(params) {
+        if (!isLocalMockMarketLookup(params))
+            return false;
+        const identifier = describeMarketLookup(params);
+        const mock = this.getLocalExchange('mock');
+        if (!mock) {
+            throw new LocalRouterMatchLookupUnsupported('market', identifier);
+        }
+        if (params.market && sourceExchangeIsMock(params.market.sourceExchange)) {
+            return true;
+        }
+        const localMarketId = mockMarketIdFromLocalId(params.marketId)
+            ?? mockMarketIdFromLocalId(params.slug);
+        if (localMarketId) {
+            await mock.fetchMarket({ marketId: localMarketId });
+            return true;
+        }
+        const url = lookupString(params.url);
+        if (url && isMockUrl(url, 'market')) {
+            const markets = await mock.fetchMarkets();
+            if (!findByUrl(markets, url)) {
+                throw new errors_1.MarketNotFound(url, mock.name);
+            }
+            return true;
+        }
+        return true;
+    }
+    async resolveLocalMockEventLookup(params) {
+        if (!isLocalMockEventLookup(params))
+            return false;
+        const identifier = describeEventLookup(params);
+        const mock = this.getLocalExchange('mock');
+        if (!mock) {
+            throw new LocalRouterMatchLookupUnsupported('event', identifier);
+        }
+        if (params.event && sourceExchangeIsMock(params.event.sourceExchange)) {
+            return true;
+        }
+        const localEventId = isMockEventId(params.eventId) ? params.eventId
+            : isMockEventId(params.slug) ? params.slug
+                : undefined;
+        if (localEventId) {
+            await mock.fetchEvent({ eventId: localEventId });
+            return true;
+        }
+        const url = lookupString(params.url);
+        if (url && isMockUrl(url, 'event')) {
+            const events = await mock.fetchEvents();
+            if (!findByUrl(events, url)) {
+                throw new errors_1.EventNotFound(url, mock.name);
+            }
+            return true;
+        }
+        return true;
+    }
     async fetchArbitrageInternal(params) {
         // Try the dedicated bulk endpoint first (single DB query).
         try {

package/dist/router/types.d.ts

@@ -6,6 +6,11 @@ export interface RouterOptions {
     baseUrl?: string;
     /** Exchange instances for cross-venue orderbook aggregation. Keyed by exchange name (e.g. 'polymarket', 'kalshi'). */
     exchanges?: Record<string, PredictionMarketExchange>;
+    /**
+     * Local exchange instances used only to resolve sidecar-only fixture IDs
+     * before hosted catalog match lookups. Does not affect orderbook routing.
+     */
+    localExchanges?: Record<string, PredictionMarketExchange>;
 }
 export interface MatchResult {
     market: UnifiedMarket;

package/dist/server/app.d.ts

@@ -1,4 +1,5 @@
 import { Express } from "express";
+import { Server as HttpServer } from "http";
 import { createWebSocketHandler, CreateWebSocketHandlerOptions } from "./ws-handler";
 /**
  * Options accepted by {@link createApp}.
@@ -33,12 +34,25 @@ export interface CreateAppOptions {
  * wrap the sidecar in their own auth / quota / usage middleware and serve
  * it as part of a larger Express application.
  *
- * The returned app registers:
+ * The returned app registers HTTP routes only:
  *   - `GET  /health`
  *   - (optional) the built-in `x-pmxt-access-token` auth check
  *   - `POST /api/:exchange/:method`
  *   - the error handler
  *
+ * WebSocket upgrades do not pass through Express routing. Local servers
+ * created from this app can expose `/ws` by attaching the WebSocket endpoint
+ * to the underlying HTTP server:
+ *
+ * ```ts
+ * import { createApp, attachWebSocketEndpoint } from 'pmxt-core';
+ *
+ * const accessToken = process.env.PMXT_ACCESS_TOKEN;
+ * const app = createApp({ accessToken });
+ * const server = app.listen(4000, "127.0.0.1");
+ * attachWebSocketEndpoint(server, { accessToken });
+ * ```
+ *
  * Usage:
  * ```ts
  * import express from 'express';
@@ -51,6 +65,16 @@ export interface CreateAppOptions {
  * ```
  */
 export declare function createApp(options?: CreateAppOptions): Express;
+export type WebSocketEndpoint = ReturnType<typeof createWebSocketHandler>;
+/**
+ * Attach the PMXT streaming WebSocket endpoint to an HTTP server.
+ *
+ * Use this with servers built from `createApp()` when you need `/ws` support
+ * for watchOrderBook, watchOrderBooks, or watchTrades. The access token should
+ * match the one passed to `createApp()` so HTTP and WebSocket requests share
+ * the same local auth policy.
+ */
+export declare function attachWebSocketEndpoint(server: HttpServer, options?: CreateWebSocketHandlerOptions): WebSocketEndpoint;
 /**
  * Start the PMXT sidecar server on the given port with the built-in
  * access-token auth middleware enabled. Returns the underlying
@@ -59,6 +83,6 @@ export declare function createApp(options?: CreateAppOptions): Express;
  * Automatically attaches a WebSocket endpoint at `/ws` for streaming
  * methods (watchOrderBook, watchOrderBooks, watchTrades).
  */
-export declare function startServer(port: number, accessToken: string): Promise<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>>;
+export declare function startServer(port: number, accessToken: string): Promise<HttpServer<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>>;
 export { createWebSocketHandler };
 export type { CreateWebSocketHandlerOptions };

package/dist/server/app.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebSocketHandler = void 0;
 exports.createApp = createApp;
+exports.attachWebSocketEndpoint = attachWebSocketEndpoint;
 exports.startServer = startServer;
 const express_1 = __importDefault(require("express"));
 const cors_1 = __importDefault(require("cors"));
@@ -13,6 +14,9 @@ const path_1 = __importDefault(require("path"));
 const ws_handler_1 = require("./ws-handler");
 Object.defineProperty(exports, "createWebSocketHandler", { enumerable: true, get: function () { return ws_handler_1.createWebSocketHandler; } });
 const exchange_factory_1 = require("./exchange-factory");
+const feed_routes_1 = require("./feed-routes");
+const sql_route_1 = require("./sql-route");
+const router_1 = require("../router");
 const errors_1 = require("../errors");
 const logger_1 = require("../utils/logger");
 function loadMethodVerbs() {
@@ -142,7 +146,14 @@ const defaultExchanges = {
     opinion: null,
     metaculus: null,
     smarkets: null,
+    mock: null,
 };
+function getDefaultExchange(exchangeName) {
+    if (!defaultExchanges[exchangeName]) {
+        defaultExchanges[exchangeName] = (0, exchange_factory_1.createExchange)(exchangeName);
+    }
+    return defaultExchanges[exchangeName];
+}
 /**
  * Build an Express app that serves the PMXT sidecar API surface without
  * binding to a port.
@@ -151,12 +162,25 @@ const defaultExchanges = {
  * wrap the sidecar in their own auth / quota / usage middleware and serve
  * it as part of a larger Express application.
  *
- * The returned app registers:
+ * The returned app registers HTTP routes only:
  *   - `GET  /health`
  *   - (optional) the built-in `x-pmxt-access-token` auth check
  *   - `POST /api/:exchange/:method`
  *   - the error handler
  *
+ * WebSocket upgrades do not pass through Express routing. Local servers
+ * created from this app can expose `/ws` by attaching the WebSocket endpoint
+ * to the underlying HTTP server:
+ *
+ * ```ts
+ * import { createApp, attachWebSocketEndpoint } from 'pmxt-core';
+ *
+ * const accessToken = process.env.PMXT_ACCESS_TOKEN;
+ * const app = createApp({ accessToken });
+ * const server = app.listen(4000, "127.0.0.1");
+ * attachWebSocketEndpoint(server, { accessToken });
+ * ```
+ *
  * Usage:
  * ```ts
  * import express from 'express';
@@ -195,6 +219,10 @@ function createApp(options = {}) {
             next();
         });
     }
+    app.use("/v0/sql", (0, sql_route_1.createSqlRouter)());
+    // Mount before /api/:exchange/:method so "feeds" is not interpreted as
+    // an exchange name by the generic dispatcher.
+    app.use("/api/feeds", (0, feed_routes_1.createFeedRouter)());
     // Shared dispatch used by both GET and POST handlers below. Given the
     // method name, the positional args, and optional credentials, it
     // resolves the exchange instance (singleton or per-request) and
@@ -208,7 +236,12 @@ function createApp(options = {}) {
                 // calls — not a server-side env var.  Each request may carry a
                 // different key, so Router is never cached as a singleton.
                 const bearer = req.headers.authorization?.replace(/^Bearer\s+/i, "") || "";
-                exchange = (0, exchange_factory_1.createExchange)(exchangeName, undefined, bearer);
+                exchange = new router_1.Router({
+                    apiKey: bearer,
+                    localExchanges: {
+                        mock: getDefaultExchange("mock"),
+                    },
+                });
             }
             else if (credentials &&
                 (credentials.privateKey ||
@@ -217,10 +250,7 @@ function createApp(options = {}) {
                 exchange = (0, exchange_factory_1.createExchange)(exchangeName, credentials);
             }
             else {
-                if (!defaultExchanges[exchangeName]) {
-                    defaultExchanges[exchangeName] = (0, exchange_factory_1.createExchange)(exchangeName);
-                }
-                exchange = defaultExchanges[exchangeName];
+                exchange = getDefaultExchange(exchangeName);
             }
             if (req.headers["x-pmxt-verbose"] === "true") {
                 exchange.verbose = true;
@@ -327,6 +357,19 @@ function createApp(options = {}) {
     });
     return app;
 }
+/**
+ * Attach the PMXT streaming WebSocket endpoint to an HTTP server.
+ *
+ * Use this with servers built from `createApp()` when you need `/ws` support
+ * for watchOrderBook, watchOrderBooks, or watchTrades. The access token should
+ * match the one passed to `createApp()` so HTTP and WebSocket requests share
+ * the same local auth policy.
+ */
+function attachWebSocketEndpoint(server, options = {}) {
+    const wsHandler = (0, ws_handler_1.createWebSocketHandler)(options);
+    wsHandler.attach(server);
+    return wsHandler;
+}
 /**
  * Start the PMXT sidecar server on the given port with the built-in
  * access-token auth middleware enabled. Returns the underlying
@@ -338,8 +381,6 @@ function createApp(options = {}) {
 async function startServer(port, accessToken) {
     const app = createApp({ accessToken });
     const server = app.listen(port, "127.0.0.1");
-    // Attach WebSocket handler for streaming subscriptions
-    const wsHandler = (0, ws_handler_1.createWebSocketHandler)({ accessToken });
-    wsHandler.attach(server);
+    attachWebSocketEndpoint(server, { accessToken });
     return server;
 }

package/dist/server/feed-routes.js

@@ -66,6 +66,8 @@ function createFeedRouter() {
     // GET /api/feeds/:feed/fetchOHLCV?symbol=BTC/USDT&timeframe=1h&since=...&limit=...
     router.get('/:feed/fetchOHLCV', async (req, res, next) => {
         try {
+            if (sendUnsupportedIfNeeded(req, res, 'fetchOHLCV'))
+                return;
             const symbol = req.query.symbol;
             if (typeof symbol !== 'string') {
                 res.status(400).json({ success: false, error: 'Missing required query parameter: symbol' });
@@ -87,10 +89,10 @@ function createFeedRouter() {
     router.get('/:feed/fetchOrderBook', async (req, res, next) => {
         try {
             const feed = req._feed;
-            if (typeof feed.fetchOrderBook !== 'function') {
-                res.status(501).json({ success: false, error: `Feed '${req.params.feed}' does not support fetchOrderBook` });
+            if (sendUnsupportedIfNeeded(req, res, 'fetchOrderBook'))
                 return;
-            }
+            if (typeof feed.fetchOrderBook !== 'function')
+                return sendUnsupported(res, getFeedParam(req), 'fetchOrderBook');
             const symbol = req.query.symbol;
             if (typeof symbol !== 'string') {
                 res.status(400).json({ success: false, error: 'Missing required query parameter: symbol' });
@@ -107,10 +109,10 @@ function createFeedRouter() {
     router.get('/:feed/fetchOracleRound', async (req, res, next) => {
         try {
             const feed = req._feed;
-            if (typeof feed.fetchOracleRound !== 'function') {
-                res.status(501).json({ success: false, error: `Feed '${req.params.feed}' does not support fetchOracleRound` });
+            if (sendUnsupportedIfNeeded(req, res, 'fetchOracleRound'))
                 return;
-            }
+            if (typeof feed.fetchOracleRound !== 'function')
+                return sendUnsupported(res, getFeedParam(req), 'fetchOracleRound');
             const feedName = req.query.feed;
             if (typeof feedName !== 'string') {
                 res.status(400).json({ success: false, error: 'Missing required query parameter: feed' });
@@ -127,10 +129,10 @@ function createFeedRouter() {
     router.get('/:feed/fetchOracleHistory', async (req, res, next) => {
         try {
             const feed = req._feed;
-            if (typeof feed.fetchOracleHistory !== 'function') {
-                res.status(501).json({ success: false, error: `Feed '${req.params.feed}' does not support fetchOracleHistory` });
+            if (sendUnsupportedIfNeeded(req, res, 'fetchOracleHistory'))
                 return;
-            }
+            if (typeof feed.fetchOracleHistory !== 'function')
+                return sendUnsupported(res, getFeedParam(req), 'fetchOracleHistory');
             const feedName = req.query.feed;
             if (typeof feedName !== 'string') {
                 res.status(400).json({ success: false, error: 'Missing required query parameter: feed' });
@@ -150,10 +152,10 @@ function createFeedRouter() {
     router.get('/:feed/fetchHistoricalPrices', async (req, res, next) => {
         try {
             const feed = req._feed;
-            if (typeof feed.fetchHistoricalPrices !== 'function') {
-                res.status(501).json({ success: false, error: `Feed '${req.params.feed}' does not support fetchHistoricalPrices` });
+            if (sendUnsupportedIfNeeded(req, res, 'fetchHistoricalPrices'))
                 return;
-            }
+            if (typeof feed.fetchHistoricalPrices !== 'function')
+                return sendUnsupported(res, getFeedParam(req), 'fetchHistoricalPrices');
             const symbol = req.query.symbol;
             if (typeof symbol !== 'string') {
                 res.status(400).json({ success: false, error: 'Missing required query parameter: symbol' });
@@ -178,3 +180,23 @@ function createFeedRouter() {
     });
     return router;
 }
+function getRequestFeed(req) {
+    return req._feed;
+}
+function sendUnsupportedIfNeeded(req, res, method) {
+    const feed = getRequestFeed(req);
+    if (feed.has?.[method] !== false)
+        return false;
+    sendUnsupported(res, feed.name || getFeedParam(req), method);
+    return true;
+}
+function sendUnsupported(res, feedName, method) {
+    res.status(501).json({
+        success: false,
+        error: `Feed '${feedName}' does not support ${method}`,
+    });
+}
+function getFeedParam(req) {
+    const value = req.params.feed;
+    return Array.isArray(value) ? value[0] ?? 'unknown' : value;
+}

package/dist/server/sql-route.d.ts

@@ -0,0 +1,2 @@
+import { Router } from "express";
+export declare function createSqlRouter(): Router;