propline 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,446 @@
+/**
+ * Response shape definitions for PropLine API.
+ *
+ * These mirror the JSON returned by api.prop-line.com and are intentionally
+ * loose — every interface allows extra fields so adding a column server-side
+ * never breaks consumers. Use them as guides, not contracts.
+ */
+interface Sport {
+    key: string;
+    title: string;
+    active: boolean;
+    [k: string]: unknown;
+}
+interface Event {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    commence_time: string;
+    [k: string]: unknown;
+}
+interface Outcome {
+    name: string;
+    description?: string | null;
+    price: number;
+    point?: number | null;
+    [k: string]: unknown;
+}
+interface ResolvedOutcome extends Outcome {
+    resolution: "won" | "lost" | "push" | "void" | null;
+    actual_value: number | null;
+    resolved_at: string | null;
+    redacted?: boolean;
+}
+interface Market {
+    key: string;
+    outcomes: Outcome[];
+    [k: string]: unknown;
+}
+interface Bookmaker {
+    key: string;
+    title: string;
+    markets: Market[];
+    [k: string]: unknown;
+}
+interface OddsResponse {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    commence_time: string;
+    bookmakers: Bookmaker[];
+    [k: string]: unknown;
+}
+interface MarketSummary {
+    key: string;
+    outcomes_count: number;
+    [k: string]: unknown;
+}
+interface OutcomeSnapshot {
+    recorded_at: string;
+    price: number;
+    point?: number | null;
+    [k: string]: unknown;
+}
+interface OddsHistoryOutcome {
+    name: string;
+    description?: string | null;
+    snapshots: OutcomeSnapshot[];
+    snapshots_available?: number;
+    redacted?: boolean;
+    [k: string]: unknown;
+}
+interface OddsHistoryMarket {
+    key: string;
+    outcomes: OddsHistoryOutcome[];
+    [k: string]: unknown;
+}
+interface OddsHistoryResponse {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    commence_time: string;
+    markets: OddsHistoryMarket[];
+    upgrade_url?: string;
+    [k: string]: unknown;
+}
+interface ScoreEvent {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    commence_time: string;
+    status: "upcoming" | "in_progress" | "final" | string;
+    home_score: number | null;
+    away_score: number | null;
+    [k: string]: unknown;
+}
+interface PlayerStat {
+    player_name: string;
+    team_abbr: string;
+    stat_type: string;
+    stat_value: number;
+    [k: string]: unknown;
+}
+interface StatsResponse {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    status: string;
+    home_score: number | null;
+    away_score: number | null;
+    stats: PlayerStat[];
+    [k: string]: unknown;
+}
+interface ResultsMarket {
+    key: string;
+    outcomes: ResolvedOutcome[];
+    [k: string]: unknown;
+}
+interface ResultsResponse {
+    id: number | string;
+    sport_key: string;
+    home_team: string;
+    away_team: string;
+    status: string;
+    home_score: number | null;
+    away_score: number | null;
+    markets: ResultsMarket[];
+    upgrade_url?: string;
+    [k: string]: unknown;
+}
+interface PlayerHistoryEntry {
+    event_id: number | string;
+    commence_time: string;
+    home_team: string;
+    away_team: string;
+    bookmaker: string;
+    bookmaker_title: string;
+    line: number | null;
+    over_price: number | null;
+    under_price: number | null;
+    actual_value: number | null;
+    over_result: "won" | "lost" | "push" | "void" | null;
+    under_result: "won" | "lost" | "push" | "void" | null;
+    resolved_at: string | null;
+    redacted?: boolean;
+    [k: string]: unknown;
+}
+interface PlayerHistoryResponse {
+    player_name: string;
+    sport_key: string;
+    market: string;
+    entries: PlayerHistoryEntry[];
+    upgrade_url?: string;
+    [k: string]: unknown;
+}
+interface Webhook {
+    id: number;
+    url: string;
+    secret: string;
+    active: boolean;
+    events: string[];
+    filter_sport_key: string | null;
+    filter_event_id: number | null;
+    filter_market_key: string | null;
+    filter_player_name: string | null;
+    min_price_change_pct: number | null;
+    created_at: string;
+    [k: string]: unknown;
+}
+interface WebhookDelivery {
+    id: number;
+    webhook_id: number;
+    status: "pending" | "success" | "failed" | string;
+    response_code: number | null;
+    attempts: number;
+    delivered_at: string | null;
+    payload: Record<string, unknown>;
+    [k: string]: unknown;
+}
+
+/** Base error for all PropLine API failures. */
+declare class PropLineError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    constructor(statusCode: number, detail: string);
+}
+/** Thrown when the API key is missing or invalid (HTTP 401). */
+declare class AuthError extends PropLineError {
+    constructor(detail?: string);
+}
+/** Thrown when the daily request limit is exceeded (HTTP 429). */
+declare class RateLimitError extends PropLineError {
+    constructor(detail?: string);
+}
+interface PropLineOptions {
+    /** API base URL. Default: `https://api.prop-line.com/v1`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 15000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation. Defaults to global `fetch` (Node 18+). */
+    fetch?: typeof fetch;
+}
+interface GetOddsOptions {
+    /** Specific event ID to get odds (with player props) for. Omit for bulk odds. */
+    eventId?: number | string;
+    /** Market keys to filter by. */
+    markets?: string[];
+}
+interface GetOddsHistoryOptions {
+    markets?: string[];
+}
+interface GetScoresOptions {
+    /** Days back to include (default 3). */
+    daysFrom?: number;
+}
+interface GetStatsOptions {
+    /** Stat types to filter by (e.g. `["strikeouts", "hits"]`). */
+    statType?: string[];
+}
+interface GetResultsOptions {
+    markets?: string[];
+}
+interface GetPlayerHistoryOptions {
+    /** Market key (e.g. `"pitcher_strikeouts"`). Required. */
+    market: string;
+    /** Restrict to a single bookmaker (e.g. `"draftkings"`). */
+    bookmaker?: string;
+    /** Max entries (1-100). Default 20. */
+    limit?: number;
+}
+interface ExportResolvedPropsOptions {
+    /** Sport key (e.g. `"baseball_mlb"`). Required. */
+    sport: string;
+    /** Optional market filter. */
+    market?: string;
+    /** Optional bookmaker filter. */
+    bookmaker?: string;
+    /** ISO datetime lower bound on `resolved_at`. */
+    since?: string;
+    /** ISO datetime upper bound on `resolved_at`. */
+    until?: string;
+    /** If set, stream the CSV to this path and resolve to the path. Otherwise resolve to the CSV bytes. */
+    outPath?: string;
+}
+interface CreateWebhookOptions {
+    /** HTTPS endpoint to receive POSTed events. Required. */
+    url: string;
+    /** Event types to subscribe to. Default: all. */
+    events?: Array<"line_movement" | "resolution">;
+    filterSportKey?: string;
+    filterEventId?: number;
+    filterMarketKey?: string;
+    filterPlayerName?: string;
+    /** Minimum % change in American odds to fire a line_movement. Point-only shifts always pass. */
+    minPriceChangePct?: number;
+}
+interface UpdateWebhookOptions {
+    url?: string;
+    events?: Array<"line_movement" | "resolution">;
+    filterSportKey?: string;
+    filterEventId?: number;
+    filterMarketKey?: string;
+    filterPlayerName?: string;
+    minPriceChangePct?: number;
+    active?: boolean;
+}
+interface ListWebhookDeliveriesOptions {
+    /** Max deliveries to return. Default 50. */
+    limit?: number;
+}
+interface VerifySignatureOptions {
+    /** Webhook signing secret (returned once from `createWebhook`). */
+    secret: string;
+    /** Value of the `X-PropLine-Timestamp` header. */
+    timestamp: string;
+    /** Raw request body. */
+    body: Uint8Array | Buffer | string;
+    /** Value of the `X-PropLine-Signature` header. */
+    signature: string;
+}
+/**
+ * Client for the PropLine player props API.
+ *
+ * @example
+ * ```ts
+ * import { PropLine } from "propline";
+ *
+ * const client = new PropLine("your_api_key");
+ * const sports = await client.getSports();
+ * ```
+ */
+declare class PropLine {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    private readonly _fetch;
+    constructor(apiKey: string, options?: PropLineOptions);
+    private _buildUrl;
+    private _request;
+    /** List all available sports. */
+    getSports(): Promise<Sport[]>;
+    /** List upcoming events for a sport. */
+    getEvents(sport: string): Promise<Event[]>;
+    /**
+     * Get current odds. With `eventId`, returns single-event odds (including
+     * player props). Without, returns bulk odds for all upcoming events.
+     *
+     * Each response carries a `bookmakers` array — iterate it to compare
+     * lines across Bovada, DraftKings, FanDuel, Pinnacle, Unibet, and
+     * PrizePicks (coverage varies by sport).
+     */
+    getOdds(sport: string, options: GetOddsOptions & {
+        eventId: number | string;
+    }): Promise<OddsResponse>;
+    getOdds(sport: string, options?: Omit<GetOddsOptions, "eventId"> & {
+        eventId?: undefined;
+    }): Promise<OddsResponse[]>;
+    /** List the available market types for an event. */
+    getMarkets(sport: string, eventId: number | string): Promise<MarketSummary[]>;
+    /**
+     * Get historical odds movement for an event.
+     *
+     * Pro tier: full snapshots. Free tier: redacted (snapshot counts only).
+     */
+    getOddsHistory(sport: string, eventId: number | string, options?: GetOddsHistoryOptions): Promise<OddsHistoryResponse>;
+    /** Get game scores and status (free tier). */
+    getScores(sport: string, options?: GetScoresOptions): Promise<ScoreEvent[]>;
+    /**
+     * Get raw player/team box-score stats (book-agnostic, free tier).
+     *
+     * Returns actual stat values decoupled from any bookmaker's lines.
+     */
+    getStats(sport: string, eventId: number | string, options?: GetStatsOptions): Promise<StatsResponse>;
+    /**
+     * Get resolved prop outcomes with actual player stats.
+     *
+     * Pro tier: full data. Free tier: redacted (resolution + actual nulled).
+     */
+    getResults(sport: string, eventId: number | string, options?: GetResultsOptions): Promise<ResultsResponse>;
+    /**
+     * Recent resolved prop history for a player on a market.
+     *
+     * One entry per (event, bookmaker) pair. Pro: full. Free: redacted.
+     */
+    getPlayerHistory(sport: string, playerName: string, options: GetPlayerHistoryOptions): Promise<PlayerHistoryResponse>;
+    /**
+     * Bulk CSV export of resolved prop outcomes (Pro+ tier).
+     *
+     * If `outPath` is provided, streams the CSV to disk and resolves to the
+     * path. Otherwise resolves to the full CSV bytes as a `Uint8Array`.
+     *
+     * @example
+     * ```ts
+     * await client.exportResolvedProps({
+     *   sport: "baseball_mlb",
+     *   market: "pitcher_strikeouts",
+     *   since: "2026-04-01T00:00:00Z",
+     *   outPath: "./mlb-strikeouts.csv",
+     * });
+     * ```
+     */
+    exportResolvedProps(options: ExportResolvedPropsOptions & {
+        outPath: string;
+    }): Promise<string>;
+    exportResolvedProps(options: ExportResolvedPropsOptions & {
+        outPath?: undefined;
+    }): Promise<Uint8Array>;
+    /**
+     * Register a webhook subscription. Streaming tier only.
+     *
+     * The returned object includes the full signing `secret` — this is the
+     * ONLY time it's revealed. Store it securely.
+     */
+    createWebhook(options: CreateWebhookOptions): Promise<Webhook>;
+    /** List your webhook subscriptions. Secrets are masked. */
+    listWebhooks(): Promise<Webhook[]>;
+    /** Get a single webhook subscription. Secret is masked. */
+    getWebhook(webhookId: number): Promise<Webhook>;
+    /** Update fields on a webhook. Only supplied fields are changed. */
+    updateWebhook(webhookId: number, options: UpdateWebhookOptions): Promise<Webhook>;
+    /** Delete a webhook (cascades its delivery history). */
+    deleteWebhook(webhookId: number): Promise<{
+        ok: boolean;
+    } | unknown>;
+    /** Queue a sample `test` payload to the webhook's URL. */
+    testWebhook(webhookId: number): Promise<unknown>;
+    /** Last 50 (default) delivery attempts for a webhook. */
+    listWebhookDeliveries(webhookId: number, options?: ListWebhookDeliveriesOptions): Promise<WebhookDelivery[]>;
+    /**
+     * Verify that an inbound webhook delivery was signed by PropLine.
+     *
+     * Compares HMAC-SHA256(secret, `${timestamp}.` + body) against the
+     * `X-PropLine-Signature` header in constant time.
+     *
+     * @example
+     * ```ts
+     * import { PropLine } from "propline";
+     *
+     * app.post("/hooks/propline", express.raw({ type: "*\/*" }), (req, res) => {
+     *   const ok = PropLine.verifySignature({
+     *     secret: process.env.WEBHOOK_SECRET!,
+     *     timestamp: req.header("X-PropLine-Timestamp")!,
+     *     body: req.body, // raw Buffer
+     *     signature: req.header("X-PropLine-Signature")!,
+     *   });
+     *   if (!ok) return res.status(401).end();
+     *   // ...
+     * });
+     * ```
+     */
+    static verifySignature(options: VerifySignatureOptions): boolean;
+}
+
+/**
+ * PropLine — Node/TypeScript SDK for the PropLine player props API.
+ *
+ * @example
+ * ```ts
+ * import { PropLine } from "propline";
+ *
+ * const client = new PropLine("your_api_key");
+ * const events = await client.getEvents("basketball_nba");
+ * const odds = await client.getOdds("basketball_nba", {
+ *   eventId: events[0].id,
+ *   markets: ["player_points", "player_rebounds"],
+ * });
+ * ```
+ */
+
+/** String constants for bookmaker keys in odds responses. */
+declare const Bookmakers: {
+    readonly BOVADA: "bovada";
+    readonly DRAFTKINGS: "draftkings";
+    readonly FANDUEL: "fanduel";
+    readonly PINNACLE: "pinnacle";
+    readonly PRIZEPICKS: "prizepicks";
+    readonly UNIBET: "unibet";
+};
+type BookmakerKey = (typeof Bookmakers)[keyof typeof Bookmakers];
+declare const VERSION = "0.1.0";
+
+export { AuthError, type Bookmaker, type BookmakerKey, Bookmakers, type CreateWebhookOptions, type Event, type ExportResolvedPropsOptions, type GetOddsHistoryOptions, type GetOddsOptions, type GetPlayerHistoryOptions, type GetResultsOptions, type GetScoresOptions, type GetStatsOptions, type ListWebhookDeliveriesOptions, type Market, type MarketSummary, type OddsHistoryMarket, type OddsHistoryOutcome, type OddsHistoryResponse, type OddsResponse, type Outcome, type OutcomeSnapshot, type PlayerHistoryEntry, type PlayerHistoryResponse, type PlayerStat, PropLine, PropLineError, type PropLineOptions, RateLimitError, type ResolvedOutcome, type ResultsMarket, type ResultsResponse, type ScoreEvent, type Sport, type StatsResponse, type UpdateWebhookOptions, VERSION, type VerifySignatureOptions, type Webhook, type WebhookDelivery };