pmxtjs 2.48.6 → 2.49.0

package/pmxt/errors.ts

@@ -116,6 +116,12 @@ export class ExchangeNotAvailable extends PmxtError {
     }
 }
 
+export class NotSupported extends PmxtError {
+    constructor(message: string, exchange?: string) {
+        super(message, "NOT_SUPPORTED", false, exchange);
+    }
+}
+
 // Error code to class mapping
 const ERROR_CODE_MAP: Record<string, new (...args: any[]) => PmxtError> = {
     BAD_REQUEST: BadRequest,
@@ -162,3 +168,8 @@ export function fromServerError(errorData: unknown): PmxtError {
 
     return new PmxtError(message, code, retryable, exchange);
 }
+
+// Hosted error classes live in ./hosted-errors. Re-exported from index.ts
+// at the package root, NOT here — re-exporting from errors.ts creates a
+// circular dependency (hosted-errors imports PmxtError from errors.ts)
+// that crashes tsx/CJS module loaders even though tsc and ts-jest tolerate it.

package/pmxt/escrow.ts

@@ -0,0 +1,93 @@
+/**
+ * Hosted-mode escrow namespace.
+ *
+ * Exposes the `/v0/escrow/*` endpoints of the pmxt hosted trading API as a
+ * small ergonomic helper class. Each method returns the raw upstream JSON
+ * payload as `unknown` — typed mappers can be layered on later without
+ * breaking the wire shape.
+ *
+ * Mirrors `sdks/python/pmxt/escrow.py`.
+ */
+
+import {
+    _tradingRequest,
+    formatRoutePath,
+    HOSTED_METHOD_ROUTES,
+    HostedClientLike,
+    resolveWalletAddress,
+} from "./hosted-routing";
+
+export class Escrow {
+    constructor(private readonly client: HostedClientLike) {}
+
+    /**
+     * Build an unsigned approve transaction for a given ERC-20 `token`. When
+     * `amountWei` is omitted, the server returns an unlimited approval.
+     */
+    async approveTx(token: string, amountWei?: bigint): Promise<unknown> {
+        const route = HOSTED_METHOD_ROUTES.get("escrowApproveTx")!;
+        return _tradingRequest(this.client, {
+            method: route.method,
+            path: route.path,
+            body: {
+                token,
+                amount_wei: amountWei === undefined ? null : amountWei.toString(),
+            },
+        });
+    }
+
+    /**
+     * Build an unsigned deposit transaction for `amount` (USDC, 6-decimal
+     * grid). Accepts number, decimal string, or BigInt in micro-units.
+     */
+    async depositTx(amount: number | string | bigint): Promise<unknown> {
+        const route = HOSTED_METHOD_ROUTES.get("escrowDepositTx")!;
+        return _tradingRequest(this.client, {
+            method: route.method,
+            path: route.path,
+            body: {
+                amount: typeof amount === "bigint" ? amount.toString() : amount,
+            },
+        });
+    }
+
+    /**
+     * Build an unsigned withdraw transaction. `action` selects the stage of
+     * the withdrawal lifecycle: `request` initiates, `claim` finalizes after
+     * the timelock, `cancel` aborts a pending request.
+     */
+    async withdrawTx(
+        action: "request" | "claim" | "cancel",
+        amount?: number | string | bigint,
+    ): Promise<unknown> {
+        const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawTx")!;
+        const normalizedAmount =
+            amount === undefined
+                ? null
+                : typeof amount === "bigint"
+                  ? amount.toString()
+                  : amount;
+        return _tradingRequest(this.client, {
+            method: route.method,
+            path: route.path,
+            body: { action, amount: normalizedAmount },
+        });
+    }
+
+    /**
+     * List the user's withdrawal records. `include` is forwarded verbatim and
+     * defaults to `"pending,events"` to match the Python SDK.
+     */
+    async withdrawals(
+        opts: { include?: string; address?: string } = {},
+    ): Promise<unknown> {
+        const address = resolveWalletAddress(this.client, opts.address);
+        const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawals")!;
+        const path = formatRoutePath(route, { address });
+        return _tradingRequest(this.client, {
+            method: route.method,
+            path,
+            params: { include: opts.include ?? "pending,events" },
+        });
+    }
+}

package/pmxt/feed-client.ts

@@ -80,6 +80,10 @@ export class FeedClient {
         };
     }
 
+    async listFeeds(): Promise<string[]> {
+        return this.getRoot<string[]>();
+    }
+
     async loadMarkets(): Promise<Record<string, Market>> {
         return this.get<Record<string, Market>>('loadMarkets', {});
     }
@@ -118,14 +122,22 @@ export class FeedClient {
     }
 
     private async get<T>(method: string, params: Record<string, unknown>): Promise<T> {
+        return this.request<T>(`${this.baseUrl}/api/feeds/${this.feedName}/${method}`, params);
+    }
+
+    private async getRoot<T>(params: Record<string, unknown> = {}): Promise<T> {
+        return this.request<T>(`${this.baseUrl}/api/feeds/`, params);
+    }
+
+    private async request<T>(url: string, params: Record<string, unknown>): Promise<T> {
         const qs = Object.entries(params)
             .filter(([, v]) => v !== undefined && v !== null)
             .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
             .join('&');
 
-        const url = `${this.baseUrl}/api/feeds/${this.feedName}/${method}${qs ? '?' + qs : ''}`;
+        const requestUrl = `${url}${qs ? '?' + qs : ''}`;
 
-        const response = await fetch(url, {
+        const response = await fetch(requestUrl, {
             headers: this.headers,
             signal: AbortSignal.timeout(30_000),
         });

package/pmxt/hosted-errors.ts

@@ -0,0 +1,216 @@
+/**
+ * Hosted trading error hierarchy and upstream response mapping.
+ *
+ * Mirrors the Python implementation in `pmxt/_hosted_errors.py`. TypeScript
+ * does not support multiple inheritance, so each hosted error class extends
+ * the semantically-closest legacy parent (e.g. `InsufficientEscrowBalance`
+ * extends `InsufficientFunds`) so existing `instanceof` checks continue to
+ * match. The `static isHostedError = true` flag and the {@link isHostedError}
+ * helper provide a structural alternative for callers that want to detect
+ * hosted-mode failures regardless of the concrete subclass.
+ */
+
+import {
+    AuthenticationError,
+    ExchangeNotAvailable,
+    InsufficientFunds,
+    InvalidOrder,
+    NotFoundError,
+    PmxtError,
+    ValidationError,
+} from "./errors";
+
+export class HostedTradingError extends PmxtError {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class InsufficientEscrowBalance extends InsufficientFunds {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class OrderSizeTooSmall extends InvalidOrder {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class InvalidApiKey extends AuthenticationError {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class OutcomeNotFound extends NotFoundError {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class CatalogUnavailable extends ExchangeNotAvailable {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class BuiltOrderExpired extends InvalidOrder {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class InvalidSignature extends AuthenticationError {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+export class NoLiquidity extends InvalidOrder {
+    static readonly isHostedError = true;
+    readonly status: number;
+    readonly detail: string;
+
+    constructor(status: number, detail: string) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = this.constructor.name;
+    }
+}
+
+/**
+ * Local validation failure. Not a hosted-mode upstream error, so does NOT
+ * carry the `isHostedError` flag.
+ */
+export class MissingWalletAddress extends ValidationError {
+    constructor(message: string) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+/**
+ * Returns true if `e` is a hosted trading error — either an instance of
+ * {@link HostedTradingError} or any subclass that carries the
+ * `static isHostedError = true` marker.
+ */
+export function isHostedError(e: unknown): boolean {
+    if (e instanceof HostedTradingError) return true;
+    const ctor = (e as { constructor?: { isHostedError?: boolean } } | null)?.constructor;
+    return ctor != null && ctor.isHostedError === true;
+}
+
+/**
+ * Read an upstream `Response` and throw the matching hosted trading error.
+ * Always throws — return type is `never`.
+ */
+export async function raiseFromResponse(response: Response): Promise<never> {
+    const status = response.status;
+    let detail = "";
+
+    try {
+        const body = await response.json();
+        if (body != null && typeof body === "object") {
+            const record = body as Record<string, unknown>;
+            const candidate =
+                (typeof record.detail === "string" ? record.detail : undefined) ||
+                (typeof record.message === "string" ? record.message : undefined) ||
+                (typeof record.error === "string" ? record.error : undefined);
+            detail = candidate || JSON.stringify(body);
+        } else {
+            detail = typeof body === "string" ? body : JSON.stringify(body);
+        }
+    } catch {
+        try {
+            detail = await response.text();
+        } catch {
+            detail = `HTTP ${status}`;
+        }
+    }
+
+    if (status === 401) {
+        throw new InvalidApiKey(status, detail);
+    }
+    if (detail.startsWith("Insufficient escrow balance")) {
+        throw new InsufficientEscrowBalance(status, detail);
+    }
+    if (detail.includes("below the minimum")) {
+        throw new OrderSizeTooSmall(status, detail);
+    }
+    if (detail.includes("catalog: no outcome")) {
+        throw new OutcomeNotFound(status, detail);
+    }
+    if (detail.startsWith("catalog:")) {
+        throw new CatalogUnavailable(status, detail);
+    }
+    if (detail.includes("built_order_id expired") || detail.includes("cancel_id expired")) {
+        throw new BuiltOrderExpired(status, detail);
+    }
+    if (detail.includes("Invalid signature")) {
+        throw new InvalidSignature(status, detail);
+    }
+    if (detail.includes("book has no resting asks") || detail.includes("book has no resting bids")) {
+        throw new NoLiquidity(status, detail);
+    }
+
+    throw new HostedTradingError(status, detail);
+}

package/pmxt/hosted-mappers.ts

@@ -0,0 +1,312 @@
+/**
+ * Hosted trading v0 response mappers.
+ *
+ * The hosted trading API exposes explicit `/v0/*` JSON shapes. These helpers
+ * translate those wire dictionaries to the SDK TypeScript interfaces.
+ *
+ * Mirrors `sdks/python/pmxt/_hosted_mappers.py`.
+ */
+
+import { InvalidOrder } from "./errors";
+import { Balance, Order, Position, UserTrade } from "./models";
+
+// ---------------------------------------------------------------------------
+// Precision helper
+// ---------------------------------------------------------------------------
+
+const SIX_DEC_SCALE = 1_000_000n;
+
+/**
+ * Convert a decimal amount to integer micro-units (6-decimal grid).
+ *
+ * Rejects amounts whose fractional part has more than 6 digits. Pure integer
+ * math via BigInt — no float rounding involved.
+ */
+export function to6dec(amount: number | string | bigint): bigint {
+    const str = typeof amount === "bigint" ? `${amount}` : String(amount);
+    const negative = str.startsWith("-");
+    const cleaned = negative ? str.slice(1) : str;
+    const [intPart, fracPart = ""] = cleaned.split(".");
+    if (fracPart.length > 6) {
+        throw new InvalidOrder(`amount precision exceeds 6 decimals: ${amount}`);
+    }
+    if (!/^\d*$/.test(intPart) || !/^\d*$/.test(fracPart)) {
+        throw new InvalidOrder(`invalid amount: ${amount}`);
+    }
+    const padded = (fracPart + "000000").slice(0, 6);
+    const intMag = BigInt(intPart || "0");
+    const scaled = intMag * SIX_DEC_SCALE + BigInt(padded);
+    return negative ? -scaled : scaled;
+}
+
+// ---------------------------------------------------------------------------
+// Order mappers
+// ---------------------------------------------------------------------------
+
+/** Map an `OrderV0` JSON object to {@link Order}. */
+export function orderFromV0(payload: Record<string, unknown>): Order {
+    const id = strOrEmpty(payload["id"]);
+    const marketId = strOrEmpty(payload["market_id"] ?? payload["marketId"]);
+    const outcomeId = strOrEmpty(payload["outcome_id"] ?? payload["outcomeId"]);
+    const status = strOrEmpty(payload["status"]);
+    const sideRaw = payload["side"];
+    const side: Order["side"] = sideRaw === "sell" ? "sell" : "buy";
+    const typeRaw = payload["type"];
+    const type: Order["type"] = typeRaw === "limit" ? "limit" : "market";
+
+    const order: Order = {
+        id,
+        marketId,
+        outcomeId,
+        side,
+        type,
+        amount: floatOrZero(payload["amount"]),
+        status,
+        filled: floatOrZero(payload["filled"]),
+        remaining: floatOrZero(payload["remaining"]),
+        timestamp: timestampToMs(payload["timestamp"]),
+    };
+
+    const price = floatOrUndefined(payload["price"]);
+    if (price !== undefined) order.price = price;
+
+    const fee = floatOrUndefined(payload["fee"]);
+    if (fee !== undefined) order.fee = fee;
+
+    return order;
+}
+
+/** Map an {@link Order} back to an `OrderV0` JSON object. */
+export function orderToV0(order: Order): Record<string, unknown> {
+    const out: Record<string, unknown> = {
+        id: order.id,
+        market_id: order.marketId,
+        outcome_id: order.outcomeId,
+        side: order.side,
+        type: order.type,
+        amount: order.amount,
+        status: order.status,
+        filled: order.filled,
+        remaining: order.remaining,
+        timestamp: msToTimestamp(order.timestamp),
+    };
+    if (order.price !== undefined) out["price"] = order.price;
+    if (order.fee !== undefined) out["fee"] = order.fee;
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// UserTrade mappers
+// ---------------------------------------------------------------------------
+
+/** Map a `UserTradeV0` JSON object to {@link UserTrade}. */
+export function userTradeFromV0(payload: Record<string, unknown>): UserTrade {
+    const sideRaw = payload["side"];
+    const side: UserTrade["side"] =
+        sideRaw === "buy" || sideRaw === "sell" ? sideRaw : "unknown";
+
+    const trade: UserTrade = {
+        id: strOrEmpty(payload["id"]),
+        price: floatOrZero(payload["price"]),
+        amount: floatOrZero(payload["amount"]),
+        side,
+        timestamp: timestampToMs(payload["timestamp"]),
+    };
+
+    const orderId = strOrUndefined(payload["order_id"] ?? payload["orderId"]);
+    if (orderId !== undefined) trade.orderId = orderId;
+
+    const outcomeId = strOrUndefined(payload["outcome_id"] ?? payload["outcomeId"]);
+    if (outcomeId !== undefined) trade.outcomeId = outcomeId;
+
+    const marketId = strOrUndefined(payload["market_id"] ?? payload["marketId"]);
+    if (marketId !== undefined) trade.marketId = marketId;
+
+    return trade;
+}
+
+/** Map a {@link UserTrade} back to a `UserTradeV0` JSON object. */
+export function userTradeToV0(trade: UserTrade): Record<string, unknown> {
+    const out: Record<string, unknown> = {
+        id: trade.id,
+        side: trade.side,
+        amount: trade.amount,
+        price: trade.price,
+        timestamp: msToTimestamp(trade.timestamp),
+    };
+    if (trade.orderId !== undefined) out["order_id"] = trade.orderId;
+    if (trade.outcomeId !== undefined) out["outcome_id"] = trade.outcomeId;
+    if (trade.marketId !== undefined) out["market_id"] = trade.marketId;
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Position mappers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a `PositionV0` JSON object to {@link Position}.
+ *
+ * Optional fields (`outcomeLabel`, `entryPrice`, `currentPrice`,
+ * `unrealizedPnL`, `realizedPnL`) surface as `undefined` when missing —
+ * **never** a fake `0` or `""`. This keeps the SDK honest about which data
+ * the server actually provided.
+ */
+export function positionFromV0(payload: Record<string, unknown>): Position {
+    const size = floatOrZero(payload["shares"] ?? payload["size"]);
+    const entryPrice = floatOrUndefined(payload["entry_price"] ?? payload["entryPrice"]);
+    const currentPrice = floatOrUndefined(
+        payload["current_price"] ?? payload["currentPrice"],
+    );
+
+    let unrealizedPnL = floatOrUndefined(
+        payload["unrealized_pnl"] ?? payload["unrealizedPnl"] ?? payload["unrealizedPnL"],
+    );
+    if (
+        unrealizedPnL === undefined &&
+        entryPrice !== undefined &&
+        currentPrice !== undefined
+    ) {
+        unrealizedPnL = (currentPrice - entryPrice) * size;
+    }
+
+    // Position requires marketId/outcomeId/outcomeLabel/entryPrice/currentPrice/unrealizedPnL
+    // in the current interface. We construct with safe defaults and only override
+    // when present. Per plan v5: the SDK should NOT fabricate financial data —
+    // when the server didn't supply entryPrice/currentPrice/outcomeLabel, we mark
+    // them via undefined (cast through a partial since the existing Position type
+    // hasn't yet been widened to Optional in this parallel-agent change).
+    const position = {
+        marketId: strOrEmpty(payload["market_id"] ?? payload["marketId"]),
+        outcomeId: strOrEmpty(payload["outcome_id"] ?? payload["outcomeId"]),
+        outcomeLabel:
+            strOrUndefined(payload["outcome_label"] ?? payload["outcomeLabel"]) as
+                | string
+                | undefined,
+        size,
+        entryPrice: entryPrice as number | undefined,
+        currentPrice: currentPrice as number | undefined,
+        unrealizedPnL: unrealizedPnL as number | undefined,
+        realizedPnL: floatOrUndefined(
+            payload["realized_pnl"] ?? payload["realizedPnl"] ?? payload["realizedPnL"],
+        ),
+    } as unknown as Position;
+
+    return position;
+}
+
+/** Map a {@link Position} back to a `PositionV0` JSON object. */
+export function positionToV0(position: Position): Record<string, unknown> {
+    const out: Record<string, unknown> = {
+        market_id: position.marketId,
+        outcome_id: position.outcomeId,
+        shares: position.size,
+    };
+    if (position.outcomeLabel !== undefined && position.outcomeLabel !== "") {
+        out["outcome_label"] = position.outcomeLabel;
+    }
+    if (position.entryPrice !== undefined) out["entry_price"] = position.entryPrice;
+    if (position.currentPrice !== undefined) out["current_price"] = position.currentPrice;
+    if (position.unrealizedPnL !== undefined) out["unrealized_pnl"] = position.unrealizedPnL;
+    if (position.realizedPnL !== undefined) out["realized_pnl"] = position.realizedPnL;
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Balance mappers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a `BalanceV0` JSON object to {@link Balance}.
+ *
+ * Hosted-mode semantic: PreFundedEscrow doesn't reserve funds for resting
+ * orders, so `available = total` and `locked = 0`. Concurrent limit orders
+ * may fail at fill time if cumulative cost exceeds the escrow balance.
+ */
+export function balanceFromV0(payload: Record<string, unknown>): Balance {
+    const total = floatOrZero(payload["amount"] ?? payload["total"]);
+    const currency = strOrUndefined(payload["currency"]) ?? "USDC";
+    return {
+        currency,
+        total,
+        available: total,
+        locked: 0,
+    };
+}
+
+/** Map a {@link Balance} back to a `BalanceV0` JSON object. */
+export function balanceToV0(balance: Balance): Record<string, unknown> {
+    return {
+        currency: balance.currency,
+        amount: balance.total,
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function strOrUndefined(value: unknown): string | undefined {
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === "string") return value || undefined;
+    return String(value);
+}
+
+function strOrEmpty(value: unknown): string {
+    if (value === null || value === undefined) return "";
+    if (typeof value === "string") return value;
+    return String(value);
+}
+
+function floatOrUndefined(value: unknown): number | undefined {
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "bigint") return Number(value);
+    if (typeof value === "string") {
+        if (!value) return undefined;
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+
+function floatOrZero(value: unknown): number {
+    const converted = floatOrUndefined(value);
+    return converted !== undefined ? converted : 0;
+}
+
+/**
+ * Parse an ISO-8601 string (or numeric) timestamp to milliseconds since epoch.
+ * Returns `0` if the input is null/undefined/empty/unparseable.
+ */
+function timestampToMs(value: unknown): number {
+    if (value === null || value === undefined) return 0;
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? Math.trunc(value) : 0;
+    }
+    if (typeof value === "bigint") return Number(value);
+    if (typeof value === "string") {
+        if (!value) return 0;
+        const normalized = value.endsWith("Z")
+            ? value
+            : /[+-]\d{2}:?\d{2}$/.test(value)
+              ? value
+              : value + "Z";
+        const ms = Date.parse(normalized);
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    return 0;
+}
+
+/** Convert milliseconds-since-epoch back to an ISO-8601 string. */
+function msToTimestamp(value: unknown): string | undefined {
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === "string") return value;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return new Date(value).toISOString();
+    }
+    if (typeof value === "bigint") {
+        return new Date(Number(value)).toISOString();
+    }
+    return undefined;
+}