pmxt-core 2.24.0 → 2.25.1

package/dist/exchanges/polymarket_us/normalizer.js

@@ -0,0 +1,385 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolymarketUSNormalizer = void 0;
+const market_utils_1 = require("../../utils/market-utils");
+const price_1 = require("./price");
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+const POLYMARKET_US_BASE_URL = 'https://polymarket.us';
+function buildMarketUrl(slug) {
+    return `${POLYMARKET_US_BASE_URL}/market/${slug}`;
+}
+function buildEventUrl(slug) {
+    return `${POLYMARKET_US_BASE_URL}/event/${slug}`;
+}
+/**
+ * Parse a stringified price from the gateway. Returns `undefined` when
+ * the input is missing, empty, or non-numeric so downstream logic can
+ * distinguish "no quote" from a legitimate 0.
+ */
+function parsePriceString(value) {
+    if (value == null || value === '')
+        return undefined;
+    const n = parseFloat(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function buildBinaryOutcomes(slug, longPrice, shortPrice) {
+    return [
+        {
+            outcomeId: `${slug}:long`,
+            marketId: slug,
+            label: 'long',
+            price: longPrice,
+        },
+        {
+            outcomeId: `${slug}:short`,
+            marketId: slug,
+            label: 'short',
+            price: shortPrice,
+        },
+    ];
+}
+/**
+ * Build binary outcomes from the gateway's `marketSides[]` array. The side
+ * ordering is normalized to [long, short] regardless of input order. Human
+ * labels from `description` (e.g. team names) are stashed under
+ * `metadata.sideDescription`; `label` is kept canonical ("long" / "short")
+ * so downstream helpers like `addBinaryOutcomes` continue to work.
+ *
+ * Prices are sourced with this precedence:
+ *   1. `marketSides[i].price` (per-side price on the gateway payload)
+ *   2. `outcomePrices[0|1]` (legacy 2-element fallback)
+ *   3. 0 (no quote available)
+ *
+ * The short-side price is derived as `1 - longPrice` when only the long
+ * side is quoted (and vice versa), since Polymarket US is fully binary.
+ */
+function buildOutcomes(slug, sides, outcomePrices) {
+    let longPrice;
+    let shortPrice;
+    let longDescription;
+    let shortDescription;
+    if (sides && sides.length > 0) {
+        const longSide = sides.find(s => s.long === true);
+        const shortSide = sides.find(s => s.long === false);
+        if (longSide) {
+            longPrice = parsePriceString(longSide.price);
+            longDescription = longSide.description;
+        }
+        if (shortSide) {
+            shortPrice = parsePriceString(shortSide.price);
+            shortDescription = shortSide.description;
+        }
+    }
+    if (longPrice === undefined && outcomePrices && outcomePrices.length >= 1) {
+        longPrice = parsePriceString(outcomePrices[0]);
+    }
+    if (shortPrice === undefined && outcomePrices && outcomePrices.length >= 2) {
+        shortPrice = parsePriceString(outcomePrices[1]);
+    }
+    // Fill in the complementary side from the binary identity when only
+    // one side was quoted.
+    if (longPrice !== undefined && shortPrice === undefined) {
+        shortPrice = 1 - longPrice;
+    }
+    if (shortPrice !== undefined && longPrice === undefined) {
+        longPrice = 1 - shortPrice;
+    }
+    const outcomes = buildBinaryOutcomes(slug, longPrice ?? 0, shortPrice ?? 0);
+    if (longDescription) {
+        outcomes[0].metadata = { sideDescription: longDescription };
+    }
+    if (shortDescription) {
+        outcomes[1].metadata = { sideDescription: shortDescription };
+    }
+    return outcomes;
+}
+/**
+ * Accepts the `tags` field in whatever shape the gateway returns it
+ * (string[], array of {label|name|slug} objects, or undefined) and
+ * produces a flat `string[]`.
+ */
+function coerceTags(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (typeof item === 'string') {
+            if (item)
+                out.push(item);
+        }
+        else if (item && typeof item === 'object') {
+            const obj = item;
+            const label = (typeof obj.label === 'string' && obj.label) ||
+                (typeof obj.name === 'string' && obj.name) ||
+                (typeof obj.slug === 'string' && obj.slug) ||
+                '';
+            if (label)
+                out.push(label);
+        }
+    }
+    return out;
+}
+function parseTimeToMs(value) {
+    if (!value)
+        return 0;
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : 0;
+}
+function intentToSide(intent) {
+    switch (intent) {
+        case 'ORDER_INTENT_BUY_LONG':
+        case 'ORDER_INTENT_BUY_SHORT':
+            return 'buy';
+        case 'ORDER_INTENT_SELL_LONG':
+        case 'ORDER_INTENT_SELL_SHORT':
+            return 'sell';
+        default:
+            return 'buy';
+    }
+}
+function intentToOutcomeId(intent, slug) {
+    switch (intent) {
+        case 'ORDER_INTENT_BUY_LONG':
+        case 'ORDER_INTENT_SELL_LONG':
+            return `${slug}:long`;
+        case 'ORDER_INTENT_BUY_SHORT':
+        case 'ORDER_INTENT_SELL_SHORT':
+            return `${slug}:short`;
+        default:
+            return `${slug}:long`;
+    }
+}
+function mapOrderType(type) {
+    return type === 'ORDER_TYPE_MARKET' ? 'market' : 'limit';
+}
+// PMXT Order.status values: 'pending' | 'open' | 'filled' | 'cancelled' | 'rejected'
+// Note: PMXT has no 'expired' status; expired orders are mapped to 'cancelled'.
+function mapOrderStatus(state) {
+    switch (state) {
+        case 'ORDER_STATE_FILLED':
+            return 'filled';
+        case 'ORDER_STATE_CANCELED':
+        case 'ORDER_STATE_EXPIRED':
+            return 'cancelled';
+        case 'ORDER_STATE_REJECTED':
+            return 'rejected';
+        case 'ORDER_STATE_NEW':
+        case 'ORDER_STATE_PENDING_NEW':
+        case 'ORDER_STATE_PENDING_REPLACE':
+        case 'ORDER_STATE_PENDING_CANCEL':
+        case 'ORDER_STATE_PENDING_RISK':
+        case 'ORDER_STATE_PARTIALLY_FILLED':
+        case 'ORDER_STATE_REPLACED':
+        default:
+            return 'open';
+    }
+}
+// ----------------------------------------------------------------------------
+// Normalizer
+// ----------------------------------------------------------------------------
+class PolymarketUSNormalizer {
+    /**
+     * Normalize a single MarketDetail into a UnifiedMarket.
+     * The slug is the canonical PMXT marketId for Polymarket US.
+     */
+    normalizeMarket(detail) {
+        const real = detail;
+        return this.buildUnifiedMarket(real);
+    }
+    /**
+     * Flatten an SDK Event's markets into UnifiedMarkets.
+     * Each market inherits the parent event's metadata.
+     */
+    normalizeMarketsFromEvent(event) {
+        const realEvent = event;
+        const nested = realEvent.markets;
+        if (!nested)
+            return [];
+        const parentTags = coerceTags(realEvent.tags);
+        const parentCategory = realEvent.category || (parentTags.length > 0 ? parentTags[0] : '');
+        const parentEndDate = realEvent.endDate || realEvent.endTime;
+        return nested.map(m => this.buildUnifiedMarket(m, {
+            eventSlug: realEvent.slug,
+            category: parentCategory,
+            tags: parentTags,
+            endDate: parentEndDate,
+        }));
+    }
+    /**
+     * Normalize an SDK Event into a UnifiedEvent.
+     */
+    normalizeEvent(event) {
+        const real = event;
+        const markets = this.normalizeMarketsFromEvent(event);
+        const tags = coerceTags(real.tags);
+        const category = real.category || (tags.length > 0 ? tags[0] : '');
+        return {
+            id: real.slug,
+            title: real.title || '',
+            description: real.description || '',
+            slug: real.slug,
+            markets,
+            volume24h: 0,
+            volume: real.volume,
+            url: buildEventUrl(real.slug),
+            category,
+            tags,
+        };
+    }
+    /**
+     * Internal helper that builds a UnifiedMarket from the gateway's real
+     * runtime shape. Handles inheritance from a parent event when the market
+     * is nested (fields like category/tags/endDate fall back to the parent).
+     */
+    buildUnifiedMarket(market, parent) {
+        const slug = market.slug;
+        const title = market.question || market.title || slug;
+        const tags = coerceTags(market.tags);
+        const effectiveTags = tags.length > 0 ? tags : (parent?.tags || []);
+        const category = market.category || parent?.category || (effectiveTags.length > 0 ? effectiveTags[0] : '');
+        const endDate = market.endDate || parent?.endDate;
+        const resolutionDate = endDate ? new Date(endDate) : new Date(0);
+        const outcomes = buildOutcomes(slug, market.marketSides, market.outcomePrices);
+        const um = {
+            marketId: slug,
+            eventId: market.eventSlug || parent?.eventSlug,
+            title,
+            description: market.description || '',
+            slug,
+            outcomes,
+            resolutionDate,
+            volume24h: 0,
+            volume: market.volume,
+            liquidity: market.liquidity ?? 0,
+            url: buildMarketUrl(slug),
+            category,
+            tags: [...effectiveTags],
+            tickSize: typeof market.orderPriceMinTickSize === 'number'
+                ? market.orderPriceMinTickSize
+                : undefined,
+        };
+        (0, market_utils_1.addBinaryOutcomes)(um);
+        return um;
+    }
+    /**
+     * Normalize a MarketBook into a PMXT OrderBook.
+     *
+     * IMPORTANT: Polymarket US books are quoted in long-side prices. PMXT
+     * exposes the book as the LONG side directly:
+     *   - bids: levels where someone is bidding to BUY LONG (price = fromAmount(level.px))
+     *   - asks: levels where someone is offering to SELL LONG (price = fromAmount(level.px))
+     * The implicit short-side book is `1 - longPrice` for each level. Callers
+     * needing the short-side view must invert prices themselves.
+     */
+    normalizeOrderBook(book, _marketId) {
+        const bids = (book.bids || []).map(level => ({
+            price: (0, price_1.fromAmount)(level.px),
+            size: parseFloat(level.qty || '0'),
+        }));
+        const asks = (book.offers || []).map(level => ({
+            price: (0, price_1.fromAmount)(level.px),
+            size: parseFloat(level.qty || '0'),
+        }));
+        return {
+            bids,
+            asks,
+            timestamp: parseTimeToMs(book.transactTime) || Date.now(),
+        };
+    }
+    /**
+     * Normalize an SDK Order into a PMXT Order.
+     * Prices are converted from long-side to user-facing using the order's intent.
+     */
+    normalizeOrder(order) {
+        const slug = order.marketSlug;
+        const longPrice = (0, price_1.fromAmount)(order.price);
+        const userFacingPrice = (0, price_1.fromLongSidePrice)(order.intent, longPrice);
+        const fee = order.commissionNotionalTotalCollected
+            ? (0, price_1.fromAmount)(order.commissionNotionalTotalCollected)
+            : undefined;
+        const timestamp = parseTimeToMs(order.createTime) || parseTimeToMs(order.insertTime);
+        return {
+            id: order.id,
+            marketId: slug,
+            outcomeId: intentToOutcomeId(order.intent, slug),
+            side: intentToSide(order.intent),
+            type: mapOrderType(order.type),
+            price: userFacingPrice,
+            amount: order.quantity,
+            status: mapOrderStatus(order.state),
+            filled: order.cumQuantity,
+            remaining: order.leavesQuantity,
+            timestamp,
+            fee,
+        };
+    }
+    /**
+     * Normalize the SDK's positions map into an array of PMXT Positions.
+     * Positive netPosition -> long outcome; negative -> short outcome.
+     */
+    normalizePositions(positions) {
+        const results = [];
+        for (const slug of Object.keys(positions)) {
+            const pos = positions[slug];
+            if (!pos)
+                continue;
+            const net = parseFloat(pos.netPosition || '0');
+            const isLong = net >= 0;
+            const size = Math.abs(net);
+            // Approximate cost basis per share. The SDK does not expose a
+            // running average price; we derive it from total cost / size.
+            const totalCost = (0, price_1.fromAmount)(pos.cost);
+            const entryPrice = size > 0 ? Math.abs(totalCost) / size : 0;
+            results.push({
+                marketId: slug,
+                outcomeId: isLong ? `${slug}:long` : `${slug}:short`,
+                outcomeLabel: isLong ? 'long' : 'short',
+                size,
+                entryPrice,
+                // SDK does not expose live mark on the position object.
+                // Callers must enrich with current price if needed.
+                currentPrice: 0,
+                unrealizedPnL: 0,
+                realizedPnL: (0, price_1.fromAmount)(pos.realized),
+            });
+        }
+        return results;
+    }
+    /**
+     * Normalize a UserBalance into PMXT Balance[].
+     * Locked = total - available (clamped to >= 0).
+     */
+    normalizeBalance(balance) {
+        const total = balance.currentBalance;
+        const available = balance.buyingPower;
+        const locked = Math.max(0, total - available);
+        return [{
+                currency: 'USD',
+                total,
+                available,
+                locked,
+            }];
+    }
+    /**
+     * Normalize a single Activity into a UserTrade.
+     * Returns null for non-trade activities.
+     */
+    normalizeUserTradeFromActivity(activity, _index) {
+        if (activity.type !== 'ACTIVITY_TYPE_TRADE')
+            return null;
+        const trade = activity.trade;
+        if (!trade)
+            return null;
+        return {
+            id: trade.id,
+            timestamp: parseTimeToMs(trade.createTime),
+            price: (0, price_1.fromAmount)(trade.price),
+            amount: parseFloat(trade.qty || '0'),
+            side: 'unknown',
+            outcomeId: undefined,
+        };
+    }
+}
+exports.PolymarketUSNormalizer = PolymarketUSNormalizer;

package/dist/exchanges/polymarket_us/normalizer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/exchanges/polymarket_us/normalizer.test.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Mock the price helpers so this test does not depend on price.ts being
+// implemented yet (it is created in parallel by another agent).
+jest.mock('./price', () => ({
+    fromAmount: (a) => a ? parseFloat(a.value) : 0,
+    fromLongSidePrice: (intent, longPrice) => intent.endsWith('SHORT') ? 1 - longPrice : longPrice,
+    toAmount: (p) => ({ value: p.toFixed(2), currency: 'USD' }),
+}));
+const normalizer_1 = require("./normalizer");
+function makeOrder(overrides = {}) {
+    return {
+        id: 'order-1',
+        marketSlug: 'btc-100k',
+        side: 'ORDER_SIDE_BUY',
+        type: 'ORDER_TYPE_LIMIT',
+        price: { value: '0.55', currency: 'USD' },
+        quantity: 10,
+        cumQuantity: 0,
+        leavesQuantity: 10,
+        tif: 'TIME_IN_FORCE_GOOD_TILL_CANCEL',
+        intent: 'ORDER_INTENT_BUY_LONG',
+        state: 'ORDER_STATE_NEW',
+        createTime: '2026-01-01T00:00:00.000Z',
+        ...overrides,
+    };
+}
+describe('PolymarketUSNormalizer', () => {
+    const normalizer = new normalizer_1.PolymarketUSNormalizer();
+    describe('normalizeMarket', () => {
+        it('uses the slug as marketId and synthesizes long/short outcomes', () => {
+            const detail = {
+                id: 1,
+                slug: 'btc-100k',
+                title: 'BTC reaches $100k',
+                outcome: 'yes',
+                description: 'Will BTC hit 100k by year end?',
+                active: true,
+                closed: false,
+                liquidity: 5000,
+                volume: 12345,
+                eventSlug: 'btc-events',
+            };
+            const um = normalizer.normalizeMarket(detail);
+            expect(um.marketId).toBe('btc-100k');
+            expect(um.slug).toBe('btc-100k');
+            expect(um.title).toBe('BTC reaches $100k');
+            expect(um.description).toBe('Will BTC hit 100k by year end?');
+            expect(um.outcomes).toHaveLength(2);
+            expect(um.outcomes[0].outcomeId).toBe('btc-100k:long');
+            expect(um.outcomes[0].label).toBe('long');
+            expect(um.outcomes[1].outcomeId).toBe('btc-100k:short');
+            expect(um.outcomes[1].label).toBe('short');
+            expect(um.liquidity).toBe(5000);
+            expect(um.volume).toBe(12345);
+        });
+        it('populates outcome prices from marketSides[].price and tickSize from orderPriceMinTickSize', () => {
+            const detail = {
+                slug: 'nfl-sf-at-kc',
+                question: 'SF at KC',
+                marketSides: [
+                    { description: 'Kansas City Chiefs', long: true, price: '0.864' },
+                    { description: 'San Francisco 49ers', long: false, price: '0.136' },
+                ],
+                orderPriceMinTickSize: 0.001,
+            };
+            const um = normalizer.normalizeMarket(detail);
+            expect(um.outcomes[0].price).toBeCloseTo(0.864);
+            expect(um.outcomes[0].metadata?.sideDescription).toBe('Kansas City Chiefs');
+            expect(um.outcomes[1].price).toBeCloseTo(0.136);
+            expect(um.outcomes[1].metadata?.sideDescription).toBe('San Francisco 49ers');
+            expect(um.tickSize).toBe(0.001);
+        });
+        it('derives the short-side price from 1 - longPrice when only the long side is quoted', () => {
+            const detail = {
+                slug: 'btc-100k',
+                question: 'BTC 100k',
+                marketSides: [
+                    { long: true, price: '0.72' },
+                    { long: false },
+                ],
+            };
+            const um = normalizer.normalizeMarket(detail);
+            expect(um.outcomes[0].price).toBeCloseTo(0.72);
+            expect(um.outcomes[1].price).toBeCloseTo(0.28);
+        });
+        it('falls back to outcomePrices[] when marketSides is missing', () => {
+            const detail = {
+                slug: 'eth-5k',
+                question: 'ETH 5k',
+                outcomePrices: ['0.30', '0.70'],
+            };
+            const um = normalizer.normalizeMarket(detail);
+            expect(um.outcomes[0].price).toBeCloseTo(0.30);
+            expect(um.outcomes[1].price).toBeCloseTo(0.70);
+        });
+    });
+    describe('normalizeOrderBook', () => {
+        it('preserves bid/offer levels with parsed numeric prices', () => {
+            const book = {
+                marketSlug: 'btc-100k',
+                bids: [
+                    { px: { value: '0.55', currency: 'USD' }, qty: '100' },
+                    { px: { value: '0.54', currency: 'USD' }, qty: '50' },
+                ],
+                offers: [
+                    { px: { value: '0.56', currency: 'USD' }, qty: '75' },
+                    { px: { value: '0.57', currency: 'USD' }, qty: '25' },
+                ],
+                state: 'MARKET_STATE_OPEN',
+            };
+            const ob = normalizer.normalizeOrderBook(book, 'btc-100k');
+            expect(ob.bids).toEqual([
+                { price: 0.55, size: 100 },
+                { price: 0.54, size: 50 },
+            ]);
+            expect(ob.asks).toEqual([
+                { price: 0.56, size: 75 },
+                { price: 0.57, size: 25 },
+            ]);
+            expect(typeof ob.timestamp).toBe('number');
+        });
+    });
+    describe('normalizeOrder - intent mapping', () => {
+        const cases = [
+            { intent: 'ORDER_INTENT_BUY_LONG', expectedSide: 'buy', expectedOutcomeSuffix: ':long' },
+            { intent: 'ORDER_INTENT_SELL_LONG', expectedSide: 'sell', expectedOutcomeSuffix: ':long' },
+            { intent: 'ORDER_INTENT_BUY_SHORT', expectedSide: 'buy', expectedOutcomeSuffix: ':short' },
+            { intent: 'ORDER_INTENT_SELL_SHORT', expectedSide: 'sell', expectedOutcomeSuffix: ':short' },
+        ];
+        for (const { intent, expectedSide, expectedOutcomeSuffix } of cases) {
+            it(`maps ${intent} to side=${expectedSide} and outcomeId ending in ${expectedOutcomeSuffix}`, () => {
+                const order = normalizer.normalizeOrder(makeOrder({ intent }));
+                expect(order.side).toBe(expectedSide);
+                expect(order.outcomeId.endsWith(expectedOutcomeSuffix)).toBe(true);
+                expect(order.marketId).toBe('btc-100k');
+            });
+        }
+        it('keeps long-side price unchanged for BUY_LONG', () => {
+            const order = normalizer.normalizeOrder(makeOrder({
+                intent: 'ORDER_INTENT_BUY_LONG',
+                price: { value: '0.60', currency: 'USD' },
+            }));
+            expect(order.price).toBeCloseTo(0.60);
+        });
+        it('flips long-side price to short-side for BUY_SHORT', () => {
+            const order = normalizer.normalizeOrder(makeOrder({
+                intent: 'ORDER_INTENT_BUY_SHORT',
+                price: { value: '0.60', currency: 'USD' },
+            }));
+            expect(order.price).toBeCloseTo(0.40);
+        });
+    });
+    describe('normalizeOrder - state mapping', () => {
+        const cases = [
+            { state: 'ORDER_STATE_NEW', expected: 'open' },
+            { state: 'ORDER_STATE_PARTIALLY_FILLED', expected: 'open' },
+            { state: 'ORDER_STATE_FILLED', expected: 'filled' },
+            { state: 'ORDER_STATE_CANCELED', expected: 'cancelled' },
+            { state: 'ORDER_STATE_REJECTED', expected: 'rejected' },
+            { state: 'ORDER_STATE_EXPIRED', expected: 'cancelled' },
+        ];
+        for (const { state, expected } of cases) {
+            it(`maps ${state} to ${expected}`, () => {
+                const order = normalizer.normalizeOrder(makeOrder({ state }));
+                expect(order.status).toBe(expected);
+            });
+        }
+    });
+    describe('normalizePositions', () => {
+        it('maps positive netPosition to long and negative to short with absolute sizes', () => {
+            const positions = {
+                'btc-100k': {
+                    netPosition: '15',
+                    qtyBought: '20',
+                    qtySold: '5',
+                    cost: { value: '7.50', currency: 'USD' },
+                    realized: { value: '0.00', currency: 'USD' },
+                    bodPosition: '0',
+                    expired: false,
+                },
+                'eth-5k': {
+                    netPosition: '-8',
+                    qtyBought: '2',
+                    qtySold: '10',
+                    cost: { value: '4.00', currency: 'USD' },
+                    realized: { value: '1.25', currency: 'USD' },
+                    bodPosition: '0',
+                    expired: false,
+                },
+            };
+            const result = normalizer.normalizePositions(positions);
+            expect(result).toHaveLength(2);
+            const btc = result.find(p => p.marketId === 'btc-100k');
+            expect(btc.outcomeId).toBe('btc-100k:long');
+            expect(btc.outcomeLabel).toBe('long');
+            expect(btc.size).toBe(15);
+            expect(btc.entryPrice).toBeCloseTo(0.5);
+            const eth = result.find(p => p.marketId === 'eth-5k');
+            expect(eth.outcomeId).toBe('eth-5k:short');
+            expect(eth.outcomeLabel).toBe('short');
+            expect(eth.size).toBe(8);
+            expect(eth.entryPrice).toBeCloseTo(0.5);
+            expect(eth.realizedPnL).toBeCloseTo(1.25);
+        });
+    });
+    describe('normalizeBalance', () => {
+        it('maps current/buyingPower to total/available/locked', () => {
+            const balance = {
+                currentBalance: 1000,
+                currency: 'USD',
+                buyingPower: 800,
+            };
+            const result = normalizer.normalizeBalance(balance);
+            expect(result).toHaveLength(1);
+            expect(result[0]).toEqual({
+                currency: 'USD',
+                total: 1000,
+                available: 800,
+                locked: 200,
+            });
+        });
+    });
+});