dino-markets 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,298 @@
+/**
+ * Types for the dino.markets /v2 REST API. Mirrors the server's serialization
+ * in v2shape.to_market: type-stable (kalshi/polymarket prices are always
+ * number|null, never a fabricated 0), with several fields present only on
+ * certain market shapes (documented per-field below).
+ */
+/** Kalshi book for one outcome. Present only with include=depth. */
+interface KalshiBook {
+    ask: number | null;
+    bid: number | null;
+    depth: number | null;
+    ticker?: string | null;
+}
+/** Polymarket book for one outcome. Present only with include=depth. */
+interface PolymarketBook {
+    ask: number | null;
+    bid: number | null;
+    depth: number | null;
+    token_id?: string | null;
+}
+interface Outcome {
+    key: string;
+    name: string;
+    /** Kalshi best ask, 0-1 probability. Null when Kalshi has no price for this outcome. */
+    kalshi: number | null;
+    /** Polymarket best ask, 0-1 probability. Null when Polymarket has no price for this outcome. */
+    polymarket: number | null;
+    /** Which venue is cheaper right now, or null if either price is missing. */
+    cheaper: "kalshi" | "polymarket" | null;
+    /** Present only when the outcome has a captured team/option logo. */
+    logo?: string;
+    /** Sibling depth book, present only with include=depth. Never replaces `kalshi`/`polymarket`. */
+    kalshi_book?: KalshiBook | null;
+    polymarket_book?: PolymarketBook | null;
+    /** Ladder markets only (e.g. weather_high): whether this bucket is an exact Kalshi match or a span. */
+    relation?: "EXACT" | "OVERLAPS";
+    /** Ladder markets only, present when relation is "OVERLAPS". */
+    kalshi_span?: string[];
+}
+interface MarketResult {
+    venues_agree: boolean;
+    void: boolean;
+    settled_at: string | null;
+}
+interface MarketLinks {
+    kalshi: string | null;
+    polymarket: string | null;
+}
+/** One bucket of a ladder market's full Kalshi axis (e.g. weather_high). */
+interface KalshiLadderBucket {
+    label: string;
+    kalshi: number | null;
+}
+/** Native venue identifiers. Present only with include=ids. */
+interface VenueIds {
+    kalshi?: Record<string, unknown> | null;
+    polymarket?: Record<string, unknown> | null;
+}
+/** Match confidence scores. Present only with include=ids. */
+interface Confidence {
+    entity?: number | null;
+    resolution?: number | null;
+}
+/** Settlement disclosure. Present only with include=settlement. */
+interface Settlement {
+    parity?: boolean;
+    risks?: Record<string, unknown>[];
+    kalshi_text?: string | null;
+    poly_text?: string | null;
+    verdict?: string | null;
+}
+type MarketStatus = "open" | "resolving" | "closed" | "settled";
+type MarketSignal = "arb" | "spread";
+/**
+ * The canonical v2 market object, as returned by /v2/markets, /v2/pairs/{id},
+ * and streamed on the markets:* WebSocket channels ("market" frames).
+ */
+interface Market {
+    /** "dino_" + uuid. */
+    id: string;
+    slug: string | null;
+    sport: string | null;
+    league: string | null;
+    title: string | null;
+    /** Deferred server-side; always null today. */
+    home: string | null;
+    /** Deferred server-side; always null today. */
+    away: string | null;
+    start_time: string | null;
+    status: MarketStatus;
+    /** Match confidence tier. Currently always "high_confidence". */
+    match: string;
+    signal: MarketSignal;
+    /** Max cross-venue gap in percentage points, or null if any price is missing. */
+    spread_pts: number | null;
+    /** Gross ask-to-ask arbitrage percent, only set when signal is "arb". */
+    potential_arb_pct: number | null;
+    coverage: {
+        kalshi: boolean;
+        polymarket: boolean;
+    };
+    outcomes: Outcome[];
+    /** Verdict-only settlement result, present only once status is "settled". */
+    result: MarketResult | null;
+    expires_at: string | null;
+    updated_at: string | null;
+    priced_at: string | null;
+    links: MarketLinks;
+    /** Native venue identifiers, present only with include=ids. */
+    venues?: VenueIds;
+    /** Match confidence scores, present only with include=ids. */
+    confidence?: Confidence;
+    /** Settlement disclosure, present only with include=settlement. */
+    settlement?: Settlement;
+    /** Present only on total/spread/team_total/advance/weather_high rows (never on moneyline/outright). */
+    market_type?: string;
+    /** Present only on total/spread/team_total/advance rows. */
+    line?: number | null;
+    /** Present on total/spread/team_total/advance and weather_high (ladder) rows. */
+    basis?: string | null;
+    /** Present only on total/spread/team_total/advance rows: the anchor market's id for this game. */
+    game_id?: string | null;
+    /** Present only on ladder rows (e.g. weather_high): the full Kalshi bucket axis. */
+    kalshi_ladder?: KalshiLadderBucket[];
+}
+interface MarketsResponse {
+    count: number;
+    sport: string | null;
+    has_more: boolean;
+    markets: Market[];
+}
+interface HistoryPoint {
+    /** Epoch milliseconds. */
+    t: number;
+    k: number | null;
+    p: number | null;
+}
+interface HistorySeries {
+    outcome: string;
+    points: HistoryPoint[];
+}
+interface HistoryResponse {
+    id: string;
+    series: HistorySeries[];
+}
+interface LeagueSummary {
+    sport: string;
+    leagues: string[];
+    count: number;
+    open: number;
+    live: number;
+    settled: number;
+}
+interface LeaguesResponse {
+    sports: LeagueSummary[];
+}
+interface StreamTokenResponse {
+    ticket: string;
+    ws_url: string;
+    expires_in: number;
+    allowed: {
+        channels: string[];
+        max_conns: number;
+    };
+}
+/** Body for reportBadArb. At least one field is required. */
+interface ReportBadArbBody {
+    opp_id?: string;
+    reason?: string;
+    sport?: string;
+    market?: string;
+    detail?: string;
+}
+interface ReportBadArbResponse {
+    status: string;
+}
+/** Query options for Dino#markets(). */
+interface MarketsOptions {
+    sport?: string;
+    league?: string;
+    /** Comma-separated: open,live,resolving,closed,settled. Server default: open,live. */
+    status?: string;
+    signal?: "spread" | "arb" | "candidates";
+    /** "start_time" (default) | "-spread_pts". */
+    sort?: string;
+    /** Comma-separated opt-in blocks: ids,depth,settlement. */
+    include?: string;
+    /** Comma-separated: moneyline,outright,total,spread,team_total,advance,weather_high,all. */
+    market_type?: string;
+    game_id?: string;
+    /** 1-1000, server default 500. */
+    limit?: number;
+}
+/** Query options for Dino#findArbitrage(). Same as MarketsOptions minus signal (fixed to "arb"). */
+type FindArbitrageOptions = Omit<MarketsOptions, "signal">;
+
+type FetchLike = typeof fetch;
+interface DinoOptions {
+    /** API key. Falls back to process.env.DINO_API_KEY when process is available. */
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injectable fetch implementation, mainly for tests. Defaults to the global fetch. */
+    fetchImpl?: FetchLike;
+}
+declare class Dino {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(opts?: DinoOptions);
+    /** Matched cross-venue catalog. See MarketsOptions for filters. */
+    markets(opts?: MarketsOptions): Promise<MarketsResponse>;
+    /** One canonical market object. Accepts a "dino_<uuid>" id or a bare uuid. */
+    market(marketId: string): Promise<Market>;
+    /** Per-outcome Kalshi/Polymarket price history for one market. */
+    history(marketId: string): Promise<HistoryResponse>;
+    /** Sports and leagues currently in season, with lifecycle counts. */
+    leagues(): Promise<LeaguesResponse>;
+    /** Sugar for markets({ ...opts, signal: "arb" }). */
+    findArbitrage(opts?: FindArbitrageOptions): Promise<MarketsResponse>;
+    /** Flag a bad or incorrect arbitrage signal. At least one field of body is required. */
+    reportBadArb(body: ReportBadArbBody): Promise<ReportBadArbResponse>;
+    /**
+     * Mint a short-lived WebSocket connect ticket (Basic/Pro only; 402 on Free).
+     * See stream.ts's `watch()` helper to consume it directly.
+     */
+    streamToken(): Promise<StreamTokenResponse>;
+    private request;
+}
+
+/**
+ * A market/price frame published on the markets:* channels. Frames are flat
+ * and self-describing (type discriminator, no wrapper) - see the WebSocket
+ * docs at https://dino.markets/docs/websocket. This SDK does not parse the
+ * frame further; it is passed through as-is.
+ */
+type StreamFrame = Record<string, unknown>;
+interface WatchOptions {
+    /** Called for every publication received on the subscribed channels. */
+    onFrame: (frame: StreamFrame, channel: string) => void;
+    /** Called on a connection error. Optional. */
+    onError?: (error: unknown) => void;
+}
+interface WatchHandle {
+    /** Disconnect the stream. */
+    close: () => void;
+}
+/**
+ * Connect to the dino.markets real-time stream and forward publications to
+ * onFrame. Requires a Basic or Pro plan; a Free key's streamToken() call
+ * throws a PlanError (402).
+ *
+ * Requires the optional "centrifuge" peer dependency: `npm install centrifuge`.
+ */
+declare function watch(client: Dino, opts: WatchOptions): Promise<WatchHandle>;
+
+/**
+ * Error types raised by the dino-markets client.
+ *
+ * Every non-2xx HTTP response from the API is mapped to one of these via
+ * `mapError`. `body` is the parsed JSON response body when available (the
+ * API returns `{ error: string, ... }` on failures), or `null` if the body
+ * could not be parsed as JSON.
+ */
+declare class DinoError extends Error {
+    /** HTTP status code of the failed response. */
+    status: number;
+    /** Parsed JSON response body, or null if unavailable/unparseable. */
+    body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 401 - missing, malformed, or revoked API key. */
+declare class AuthenticationError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 402 - subscription inactive, or the endpoint needs a paid plan (e.g. streaming on Free). */
+declare class PlanError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 429 - rate limit exceeded. `retryAfter` is in seconds when the server reports one. */
+declare class RateLimitError extends DinoError {
+    retryAfter?: number;
+    constructor(message: string, status: number, body?: unknown, retryAfter?: number);
+}
+/** 5xx - server-side failure. */
+declare class ServerError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Map an HTTP response's status/body to a DinoError subclass. status must be
+ * a non-2xx code; headers is optional and only used to read Retry-After.
+ */
+declare function mapError(status: number, body: unknown, headers?: Headers): DinoError;
+
+export { AuthenticationError, type Confidence, Dino, DinoError, type DinoOptions, type FetchLike, type FindArbitrageOptions, type HistoryPoint, type HistoryResponse, type HistorySeries, type KalshiBook, type KalshiLadderBucket, type LeagueSummary, type LeaguesResponse, type Market, type MarketLinks, type MarketResult, type MarketSignal, type MarketStatus, type MarketsOptions, type MarketsResponse, type Outcome, PlanError, type PolymarketBook, RateLimitError, type ReportBadArbBody, type ReportBadArbResponse, ServerError, type Settlement, type StreamFrame, type StreamTokenResponse, type VenueIds, type WatchHandle, type WatchOptions, mapError, watch };

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Types for the dino.markets /v2 REST API. Mirrors the server's serialization
+ * in v2shape.to_market: type-stable (kalshi/polymarket prices are always
+ * number|null, never a fabricated 0), with several fields present only on
+ * certain market shapes (documented per-field below).
+ */
+/** Kalshi book for one outcome. Present only with include=depth. */
+interface KalshiBook {
+    ask: number | null;
+    bid: number | null;
+    depth: number | null;
+    ticker?: string | null;
+}
+/** Polymarket book for one outcome. Present only with include=depth. */
+interface PolymarketBook {
+    ask: number | null;
+    bid: number | null;
+    depth: number | null;
+    token_id?: string | null;
+}
+interface Outcome {
+    key: string;
+    name: string;
+    /** Kalshi best ask, 0-1 probability. Null when Kalshi has no price for this outcome. */
+    kalshi: number | null;
+    /** Polymarket best ask, 0-1 probability. Null when Polymarket has no price for this outcome. */
+    polymarket: number | null;
+    /** Which venue is cheaper right now, or null if either price is missing. */
+    cheaper: "kalshi" | "polymarket" | null;
+    /** Present only when the outcome has a captured team/option logo. */
+    logo?: string;
+    /** Sibling depth book, present only with include=depth. Never replaces `kalshi`/`polymarket`. */
+    kalshi_book?: KalshiBook | null;
+    polymarket_book?: PolymarketBook | null;
+    /** Ladder markets only (e.g. weather_high): whether this bucket is an exact Kalshi match or a span. */
+    relation?: "EXACT" | "OVERLAPS";
+    /** Ladder markets only, present when relation is "OVERLAPS". */
+    kalshi_span?: string[];
+}
+interface MarketResult {
+    venues_agree: boolean;
+    void: boolean;
+    settled_at: string | null;
+}
+interface MarketLinks {
+    kalshi: string | null;
+    polymarket: string | null;
+}
+/** One bucket of a ladder market's full Kalshi axis (e.g. weather_high). */
+interface KalshiLadderBucket {
+    label: string;
+    kalshi: number | null;
+}
+/** Native venue identifiers. Present only with include=ids. */
+interface VenueIds {
+    kalshi?: Record<string, unknown> | null;
+    polymarket?: Record<string, unknown> | null;
+}
+/** Match confidence scores. Present only with include=ids. */
+interface Confidence {
+    entity?: number | null;
+    resolution?: number | null;
+}
+/** Settlement disclosure. Present only with include=settlement. */
+interface Settlement {
+    parity?: boolean;
+    risks?: Record<string, unknown>[];
+    kalshi_text?: string | null;
+    poly_text?: string | null;
+    verdict?: string | null;
+}
+type MarketStatus = "open" | "resolving" | "closed" | "settled";
+type MarketSignal = "arb" | "spread";
+/**
+ * The canonical v2 market object, as returned by /v2/markets, /v2/pairs/{id},
+ * and streamed on the markets:* WebSocket channels ("market" frames).
+ */
+interface Market {
+    /** "dino_" + uuid. */
+    id: string;
+    slug: string | null;
+    sport: string | null;
+    league: string | null;
+    title: string | null;
+    /** Deferred server-side; always null today. */
+    home: string | null;
+    /** Deferred server-side; always null today. */
+    away: string | null;
+    start_time: string | null;
+    status: MarketStatus;
+    /** Match confidence tier. Currently always "high_confidence". */
+    match: string;
+    signal: MarketSignal;
+    /** Max cross-venue gap in percentage points, or null if any price is missing. */
+    spread_pts: number | null;
+    /** Gross ask-to-ask arbitrage percent, only set when signal is "arb". */
+    potential_arb_pct: number | null;
+    coverage: {
+        kalshi: boolean;
+        polymarket: boolean;
+    };
+    outcomes: Outcome[];
+    /** Verdict-only settlement result, present only once status is "settled". */
+    result: MarketResult | null;
+    expires_at: string | null;
+    updated_at: string | null;
+    priced_at: string | null;
+    links: MarketLinks;
+    /** Native venue identifiers, present only with include=ids. */
+    venues?: VenueIds;
+    /** Match confidence scores, present only with include=ids. */
+    confidence?: Confidence;
+    /** Settlement disclosure, present only with include=settlement. */
+    settlement?: Settlement;
+    /** Present only on total/spread/team_total/advance/weather_high rows (never on moneyline/outright). */
+    market_type?: string;
+    /** Present only on total/spread/team_total/advance rows. */
+    line?: number | null;
+    /** Present on total/spread/team_total/advance and weather_high (ladder) rows. */
+    basis?: string | null;
+    /** Present only on total/spread/team_total/advance rows: the anchor market's id for this game. */
+    game_id?: string | null;
+    /** Present only on ladder rows (e.g. weather_high): the full Kalshi bucket axis. */
+    kalshi_ladder?: KalshiLadderBucket[];
+}
+interface MarketsResponse {
+    count: number;
+    sport: string | null;
+    has_more: boolean;
+    markets: Market[];
+}
+interface HistoryPoint {
+    /** Epoch milliseconds. */
+    t: number;
+    k: number | null;
+    p: number | null;
+}
+interface HistorySeries {
+    outcome: string;
+    points: HistoryPoint[];
+}
+interface HistoryResponse {
+    id: string;
+    series: HistorySeries[];
+}
+interface LeagueSummary {
+    sport: string;
+    leagues: string[];
+    count: number;
+    open: number;
+    live: number;
+    settled: number;
+}
+interface LeaguesResponse {
+    sports: LeagueSummary[];
+}
+interface StreamTokenResponse {
+    ticket: string;
+    ws_url: string;
+    expires_in: number;
+    allowed: {
+        channels: string[];
+        max_conns: number;
+    };
+}
+/** Body for reportBadArb. At least one field is required. */
+interface ReportBadArbBody {
+    opp_id?: string;
+    reason?: string;
+    sport?: string;
+    market?: string;
+    detail?: string;
+}
+interface ReportBadArbResponse {
+    status: string;
+}
+/** Query options for Dino#markets(). */
+interface MarketsOptions {
+    sport?: string;
+    league?: string;
+    /** Comma-separated: open,live,resolving,closed,settled. Server default: open,live. */
+    status?: string;
+    signal?: "spread" | "arb" | "candidates";
+    /** "start_time" (default) | "-spread_pts". */
+    sort?: string;
+    /** Comma-separated opt-in blocks: ids,depth,settlement. */
+    include?: string;
+    /** Comma-separated: moneyline,outright,total,spread,team_total,advance,weather_high,all. */
+    market_type?: string;
+    game_id?: string;
+    /** 1-1000, server default 500. */
+    limit?: number;
+}
+/** Query options for Dino#findArbitrage(). Same as MarketsOptions minus signal (fixed to "arb"). */
+type FindArbitrageOptions = Omit<MarketsOptions, "signal">;
+
+type FetchLike = typeof fetch;
+interface DinoOptions {
+    /** API key. Falls back to process.env.DINO_API_KEY when process is available. */
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injectable fetch implementation, mainly for tests. Defaults to the global fetch. */
+    fetchImpl?: FetchLike;
+}
+declare class Dino {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(opts?: DinoOptions);
+    /** Matched cross-venue catalog. See MarketsOptions for filters. */
+    markets(opts?: MarketsOptions): Promise<MarketsResponse>;
+    /** One canonical market object. Accepts a "dino_<uuid>" id or a bare uuid. */
+    market(marketId: string): Promise<Market>;
+    /** Per-outcome Kalshi/Polymarket price history for one market. */
+    history(marketId: string): Promise<HistoryResponse>;
+    /** Sports and leagues currently in season, with lifecycle counts. */
+    leagues(): Promise<LeaguesResponse>;
+    /** Sugar for markets({ ...opts, signal: "arb" }). */
+    findArbitrage(opts?: FindArbitrageOptions): Promise<MarketsResponse>;
+    /** Flag a bad or incorrect arbitrage signal. At least one field of body is required. */
+    reportBadArb(body: ReportBadArbBody): Promise<ReportBadArbResponse>;
+    /**
+     * Mint a short-lived WebSocket connect ticket (Basic/Pro only; 402 on Free).
+     * See stream.ts's `watch()` helper to consume it directly.
+     */
+    streamToken(): Promise<StreamTokenResponse>;
+    private request;
+}
+
+/**
+ * A market/price frame published on the markets:* channels. Frames are flat
+ * and self-describing (type discriminator, no wrapper) - see the WebSocket
+ * docs at https://dino.markets/docs/websocket. This SDK does not parse the
+ * frame further; it is passed through as-is.
+ */
+type StreamFrame = Record<string, unknown>;
+interface WatchOptions {
+    /** Called for every publication received on the subscribed channels. */
+    onFrame: (frame: StreamFrame, channel: string) => void;
+    /** Called on a connection error. Optional. */
+    onError?: (error: unknown) => void;
+}
+interface WatchHandle {
+    /** Disconnect the stream. */
+    close: () => void;
+}
+/**
+ * Connect to the dino.markets real-time stream and forward publications to
+ * onFrame. Requires a Basic or Pro plan; a Free key's streamToken() call
+ * throws a PlanError (402).
+ *
+ * Requires the optional "centrifuge" peer dependency: `npm install centrifuge`.
+ */
+declare function watch(client: Dino, opts: WatchOptions): Promise<WatchHandle>;
+
+/**
+ * Error types raised by the dino-markets client.
+ *
+ * Every non-2xx HTTP response from the API is mapped to one of these via
+ * `mapError`. `body` is the parsed JSON response body when available (the
+ * API returns `{ error: string, ... }` on failures), or `null` if the body
+ * could not be parsed as JSON.
+ */
+declare class DinoError extends Error {
+    /** HTTP status code of the failed response. */
+    status: number;
+    /** Parsed JSON response body, or null if unavailable/unparseable. */
+    body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 401 - missing, malformed, or revoked API key. */
+declare class AuthenticationError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 402 - subscription inactive, or the endpoint needs a paid plan (e.g. streaming on Free). */
+declare class PlanError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 429 - rate limit exceeded. `retryAfter` is in seconds when the server reports one. */
+declare class RateLimitError extends DinoError {
+    retryAfter?: number;
+    constructor(message: string, status: number, body?: unknown, retryAfter?: number);
+}
+/** 5xx - server-side failure. */
+declare class ServerError extends DinoError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Map an HTTP response's status/body to a DinoError subclass. status must be
+ * a non-2xx code; headers is optional and only used to read Retry-After.
+ */
+declare function mapError(status: number, body: unknown, headers?: Headers): DinoError;
+
+export { AuthenticationError, type Confidence, Dino, DinoError, type DinoOptions, type FetchLike, type FindArbitrageOptions, type HistoryPoint, type HistoryResponse, type HistorySeries, type KalshiBook, type KalshiLadderBucket, type LeagueSummary, type LeaguesResponse, type Market, type MarketLinks, type MarketResult, type MarketSignal, type MarketStatus, type MarketsOptions, type MarketsResponse, type Outcome, PlanError, type PolymarketBook, RateLimitError, type ReportBadArbBody, type ReportBadArbResponse, ServerError, type Settlement, type StreamFrame, type StreamTokenResponse, type VenueIds, type WatchHandle, type WatchOptions, mapError, watch };