@mostlyrightmd/markets 0.1.0-rc.7

package/dist/polymarket/index.d.ts

@@ -0,0 +1,317 @@
+import { TradewindsError } from '@mostlyrightmd/core';
+import { InternationalRow } from '@mostlyrightmd/core/discovery';
+
+/** Raw Gamma event payload — narrow shape we depend on. */
+interface PolymarketEventRaw {
+    id?: string;
+    slug?: string;
+    title?: string;
+    description?: string;
+    endDate?: string;
+    active?: boolean;
+    closed?: boolean;
+    archived?: boolean;
+    tags?: Array<string | {
+        label?: string;
+        slug?: string;
+    }>;
+    [key: string]: unknown;
+}
+interface FetchEventsOptions {
+    /** Politeness sleep between requests, in ms. Default 200 (0.2 s). Pass 0 to skip. */
+    readonly sleepBetweenMs?: number;
+    /** AbortSignal for the whole paginator. */
+    readonly signal?: AbortSignal;
+    /** Override fetch (for tests). Defaults to global fetch. */
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * Fetch every active weather event from Gamma, paginated by `offset` in
+ * `PAGE_SIZE` increments until either an empty page is returned or
+ * `MAX_EVENTS` is reached. Dedup by slug to defend against the rare case
+ * where pagination overlaps under concurrent edits on Gamma's side.
+ */
+declare function fetchEvents(opts?: FetchEventsOptions): Promise<PolymarketEventRaw[]>;
+/** Fetch a single event by id. Useful for the settle() flow when only an id is known. */
+declare function fetchEventById(eventId: string, opts?: FetchEventsOptions): Promise<PolymarketEventRaw | null>;
+
+/**
+ * Resolution-source netlocs we trust. Anything else throws
+ * PolymarketEventError. Mirrors Python `RESOLUTION_SOURCE_ALLOWLIST`.
+ */
+declare const RESOLUTION_SOURCE_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Per-netloc → enum value for the `resolutionSourceType` field on settlement
+ * records. `hko` / `cwa` are predeclared for v0.2 (HKO/CWA clients).
+ */
+declare const NETLOC_TO_RESOLUTION_TYPE: Readonly<Record<string, string>>;
+/** Enum values for the `resolutionSourceType` column. */
+declare const POLYMARKET_RESOLUTION_SOURCE_TYPES: readonly ["wunderground", "noaa_wrh", "hko", "cwa", "other"];
+type PolymarketResolutionSourceType = (typeof POLYMARKET_RESOLUTION_SOURCE_TYPES)[number];
+/**
+ * Event id pattern. Python widened this in codex iter-2 P1: real Gamma IDs
+ * are numeric strings (`"12345"`), but condition-tag UUIDs + slugs also
+ * appear in the wild. Wide enough to accept real Gamma payloads but narrow
+ * enough to defend against URL-path injection.
+ *
+ * The plan called this "UUID4 regex" but follows Python's actual behavior:
+ * the strict UUID4 form rejected every real Gamma event, breaking the
+ * discover → settle round-trip.
+ */
+declare const EVENT_ID_RE: RegExp;
+/**
+ * Max bytes of a Polymarket event description we'll parse. Polymarket
+ * descriptions are concise; oversized payloads indicate hostile input
+ * (ReDoS defense).
+ */
+declare const MAX_DESCRIPTION_BYTES: number;
+/**
+ * Per-resolution-source publication delay. Settlement refuses to settle
+ * until `now - settlementDate >= delay` to avoid settling on values the
+ * issuer hasn't published yet.
+ *
+ * Wunderground typically posts daily extremes ~6h after local midnight;
+ * NOAA WRH ~4h. "other" gets a conservative 24h fallback.
+ */
+declare const SETTLE_DELAY_HOURS: Readonly<Record<string, number>>;
+/**
+ * Slug date extractor. Polymarket weather slugs embed the resolution date
+ * (e.g. `will-nyc-be-above-80f-on-2026-05-23`). Used by `polymarketSettle`
+ * to derive the resolution date from the slug instead of `event.endDate`.
+ */
+declare const SLUG_DATE_RE: RegExp;
+/** Markets routed to v0.2 sources (CWA/HKO clients). */
+declare const DEFERRED_STATIONS: ReadonlySet<string>;
+/** Discovery row shape — one per active weather event. */
+interface PolymarketDiscoveryRow {
+    readonly eventId: string | null;
+    readonly slug: string | null;
+    readonly title: string | null;
+    readonly city: string | null;
+    readonly icao: string | null;
+    readonly measure: "high" | "low" | "default" | null;
+    readonly endTime: string | null;
+    readonly resolutionSourceType: PolymarketResolutionSourceType | null;
+}
+/**
+ * Native unit of the market's published settlement value. Codex iter-3 P2:
+ * international Polymarket markets publish in whole-°C, US in °F. The
+ * settle engine returns the resolved value in BOTH units so the caller's
+ * comparison against Polymarket's published value uses the matching unit.
+ */
+type SettlementUnit = "fahrenheit" | "celsius";
+/** Settlement result shape. */
+interface PolymarketSettlementResult {
+    readonly eventId: string;
+    readonly settlementDate: string;
+    readonly icao: string;
+    readonly measure: "high" | "low" | "default";
+    /**
+     * Resolved temperature in the unit the caller asked for (the `unit`
+     * option; defaults to the station's native unit — F for US-registry
+     * stations, C for international). Convenience pointer to `resolvedValueF`
+     * or `resolvedValueC`.
+     */
+    readonly resolvedValue: number;
+    readonly resolvedValueC: number;
+    readonly resolvedValueF: number;
+    /** Which unit `resolvedValue` carries. */
+    readonly unit: SettlementUnit;
+    readonly resolutionSourceType: PolymarketResolutionSourceType;
+    readonly dataQualityAlert: string | null;
+}
+/** Settlement options. */
+interface PolymarketSettleOptions {
+    /** Optional description override (live discovery normally supplies this). */
+    readonly description?: string;
+    /** Reference "now" for the finalization-delay check. Defaults to `new Date()`. */
+    readonly now?: Date;
+    /**
+     * Polymarket's published settlement value, if known. The comparison
+     * uses whichever unit `unit` is set to. ±1°F (or ±0.6°C) diff emits an
+     * alert; values outside that band don't throw.
+     */
+    readonly polymarketPublishedValue?: number;
+    /**
+     * Resolved-value unit. Defaults to the station's native unit:
+     * °F for the 20 US Kalshi cities; °C for international stations
+     * (matches Polymarket's published-bucket convention per
+     * .planning/research/INGEST-PLANNER-RESEARCH.md). Codex iter-3 P2.
+     */
+    readonly unit?: SettlementUnit;
+}
+
+/**
+ * Apply the 16 KB cap + netloc allowlist to a description string.
+ *
+ * @throws PayloadTooLargeError when the UTF-8 byte length exceeds 16 KB.
+ * @throws PolymarketEventError when any URL has a netloc outside the allowlist.
+ */
+declare function validateDescription(description: string): void;
+/**
+ * Classify a description's resolution source by the first allowlisted netloc
+ * found. Returns `"other"` when no allowlisted URL appears (the settlement
+ * engine falls back to the 24-hour delay for "other").
+ */
+declare function extractResolutionSourceType(description: string): PolymarketResolutionSourceType;
+
+/** Event payload is malformed (bad event id, oversized description, bad URL). */
+declare class PolymarketEventError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "POLYMARKET_EVENT_INVALID";
+}
+/** Settlement engine couldn't resolve an event to a value. */
+declare class PolymarketSettlementError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "POLYMARKET_SETTLEMENT_FAILED";
+}
+/**
+ * Settlement attempted before the resolution source's publication delay
+ * has elapsed. Carries `waitHours` so the caller can schedule a retry.
+ *
+ * Codex iter-1 P2: overrides `payload()` so `toDict()` (and any MCP
+ * serializer downstream) includes the structured retry metadata. The
+ * fields are otherwise only readable via the live JS error object.
+ */
+declare class TooEarlyToSettleError extends TradewindsError {
+    readonly waitHours: number;
+    readonly resolutionSourceType: string;
+    constructor(message: string, opts: {
+        waitHours: number;
+        resolutionSourceType: string;
+    });
+    static readonly defaultErrorCode = "POLYMARKET_TOO_EARLY";
+    protected payload(): Record<string, unknown>;
+}
+/**
+ * Description exceeded the 16 KB cap. Direct subclass of TradewindsError
+ * (rather than PolymarketEventError) because TS prevents narrowing a
+ * `static readonly` literal type in a subclass.
+ */
+declare class PayloadTooLargeError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "POLYMARKET_PAYLOAD_TOO_LARGE";
+}
+
+interface PolymarketDiscoverOptions extends FetchEventsOptions {
+    /**
+     * Sink for dropped events. Tests pass a recorder; production can pass
+     * console.info or omit. Receives `{slug, reason}` per skipped event.
+     */
+    onSkip?: (info: {
+        slug: string | null;
+        reason: string;
+    }) => void;
+}
+/**
+ * Discover active Polymarket weather events.
+ *
+ * Returns one row per resolvable event. Events the resolver can't match
+ * are dropped silently (with optional `onSkip` callback). Events that
+ * route to a deferred station (Taipei, HK-low) appear in the result with
+ * `icao: null` and `measure: null` so callers can SEE them.
+ */
+declare function polymarketDiscover(opts?: PolymarketDiscoverOptions): Promise<PolymarketDiscoveryRow[]>;
+
+declare const POLYMARKET_KNOWN_WRONG_STATIONS: Readonly<Record<string, ReadonlySet<string>>>;
+
+/**
+ * Detect whether the market resolves on the daily HIGH or LOW from
+ * keywords in the event title/slug/name. Distinct from the station-level
+ * measure: many cities have one airport for both, but the market still
+ * resolves on tmax XOR tmin.
+ */
+declare function detectMarketMeasure(event: PolymarketEventRaw): "high" | "low" | "default";
+/**
+ * Derive a city key from slug + title + tags. Lowercase substring match
+ * against the catalog; longest-first so multi-token cities outrank prefixes.
+ * Returns null when no match — caller decides whether to drop or surface.
+ */
+declare function deriveCity(event: PolymarketEventRaw): string | null;
+/**
+ * Extract the canonical Wunderground PWS / airport ICAO from `text`.
+ *
+ * Tier 1.5 of the resolver chain — runs between explicit `event.city`
+ * and slug-derive. When a Polymarket event embeds a Wunderground PWS
+ * URL, the URL IS the source of truth; no catalog lookup needed.
+ *
+ * Multi-URL disambiguation: when multiple canonical Wunderground URLs
+ * appear, ALL extracted ICAOs MUST agree. Disagreement returns null so
+ * the resolver falls through to Tier 2 city-derive (prevents an
+ * issuer-side citation URL from silently swapping the settlement station).
+ *
+ * Returns uppercase ICAO (4 chars, leading K) when a canonical URL is
+ * found AND any additional canonical URLs agree. Null otherwise —
+ * including the disagreement case.
+ */
+declare function extractIcaoFromResolutionSource(text: string | null | undefined): string | null;
+/**
+ * Resolve an event to `{icao, stationMeasure}` using the city catalog.
+ *
+ * Returns null when no city matches (caller drops the event).
+ * Raises DeferredMarketError when the resolution would route to a v0.2
+ * source (Taipei RCTP, Hong Kong VHHH for the low-extreme market).
+ */
+declare function resolveStationForEvent(event: PolymarketEventRaw, marketMeasure: "high" | "low" | "default"): {
+    city: string;
+    icao: string;
+    stationMeasure: "high" | "low" | "default";
+} | null;
+/**
+ * Parse the resolution date from a Polymarket weather slug. The LAST
+ * YYYY-MM-DD match wins because slugs may carry both a creation date and
+ * a resolution date (`created-2026-01-01-resolves-2026-05-23`) — the
+ * resolution date is typically rightmost in Polymarket's convention.
+ *
+ * Mirrors Python `_settlement_date_from_slug` architect iter-1 HIGH-4.
+ */
+declare function settlementDateFromSlug(slug: string): string;
+
+/**
+ * Loader contract for the resolution-source observation rows. Defaults to
+ * a no-op stub so the security/validation gates can be unit-tested without
+ * pulling live cache data; production callers wire the cache reader here.
+ *
+ * Returning an empty array signals "no rows available for this date" and
+ * surfaces as PolymarketSettlementError downstream.
+ */
+type ObservationLoader = (args: {
+    icao: string;
+    fromDate: string;
+    toDate: string;
+}) => Promise<ReadonlyArray<InternationalRow>>;
+interface PolymarketSettleArgs extends PolymarketSettleOptions {
+    /**
+     * The raw Gamma event payload. Required because the settle engine reads
+     * `slug` (for the resolution date), `description` (for the resolution
+     * source), and `title/slug/name` (for the measure). Callers can fetch
+     * via `fetchEventById` if they only have an id.
+     */
+    readonly event: PolymarketEventRaw;
+    /**
+     * Loader that returns observation rows for `[fromDate, toDate]`. Defaults
+     * to an in-memory empty loader so callers MUST wire this for production.
+     */
+    readonly loader?: ObservationLoader;
+}
+/**
+ * Settle a single Polymarket event.
+ *
+ * Validates the event id, description (16 KB cap, netloc allowlist),
+ * resolves the station via the city catalog, parses the resolution date
+ * from the slug, enforces the per-source publication-delay window, and
+ * pulls the daily extreme via `internationalDailyExtremes`.
+ *
+ * @throws PolymarketEventError on bad id / bad description / unsupported station.
+ * @throws PolymarketSettlementError when no rows resolve for the station/date.
+ * @throws TooEarlyToSettleError when the publication delay hasn't elapsed.
+ */
+declare function polymarketSettle(args: PolymarketSettleArgs): Promise<PolymarketSettlementResult>;
+/**
+ * Settle by event id alone. Fetches the event from Gamma first, then
+ * delegates to `polymarketSettle`. Useful when a caller only has the id
+ * (e.g. from a Kalshi-side cross-reference).
+ */
+declare function polymarketSettleById(eventId: string, args: Omit<PolymarketSettleArgs, "event">): Promise<PolymarketSettlementResult>;
+
+export { DEFERRED_STATIONS, EVENT_ID_RE, type FetchEventsOptions, MAX_DESCRIPTION_BYTES, NETLOC_TO_RESOLUTION_TYPE, type ObservationLoader, POLYMARKET_KNOWN_WRONG_STATIONS, POLYMARKET_RESOLUTION_SOURCE_TYPES, PayloadTooLargeError, type PolymarketDiscoverOptions, type PolymarketDiscoveryRow, PolymarketEventError, type PolymarketEventRaw, type PolymarketResolutionSourceType, type PolymarketSettleArgs, type PolymarketSettleOptions, PolymarketSettlementError, type PolymarketSettlementResult, RESOLUTION_SOURCE_ALLOWLIST, SETTLE_DELAY_HOURS, SLUG_DATE_RE, type SettlementUnit, TooEarlyToSettleError, deriveCity, detectMarketMeasure, extractIcaoFromResolutionSource, extractResolutionSourceType, fetchEventById, fetchEvents, polymarketDiscover, polymarketSettle, polymarketSettleById, resolveStationForEvent, settlementDateFromSlug, validateDescription };