propline 0.22.1 → 0.24.0

package/dist/index.d.cts

@@ -653,19 +653,53 @@ interface GetDfsPayoutsOptions {
      */
     legWinProb?: number;
 }
+/**
+ * Structured error body returned by gated/throttled endpoints
+ * (see https://prop-line.com/docs#errors). Branch on `error` — the
+ * codes are stable — and follow the URLs instead of parsing prose.
+ */
+interface PropLineErrorInfo {
+    /** Stable machine-readable code, e.g. "upgrade_required", "daily_limit_exceeded". */
+    error?: string;
+    /** Human-readable sentence. */
+    message?: string;
+    /** Cheapest tier that unlocks a gated feature (403s). */
+    required_tier?: string;
+    /** Where to unlock it — pre-filled one-click URL on daily-cap 429s. */
+    upgrade_url?: string;
+    docs_url?: string;
+    signup_url?: string;
+    backfill_url?: string;
+    /** Burst-limit backoff hint (429s). */
+    retry_after_seconds?: number;
+    /** Daily-cap 429s: recommended next plan incl. its own upgrade_url. */
+    recommended?: {
+        plan?: string;
+        upgrade_url?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 /** Base error for all PropLine API failures. */
 declare class PropLineError extends Error {
     readonly statusCode: number;
+    /** Human-readable detail message. */
     readonly detail: string;
-    constructor(statusCode: number, detail: string);
+    /** Structured error body, when the API returned one. */
+    readonly info?: PropLineErrorInfo;
+    constructor(statusCode: number, detail: string, info?: PropLineErrorInfo);
+    /** Stable machine-readable code (e.g. "upgrade_required"), if present. */
+    get errorCode(): string | undefined;
+    /** The URL that unlocks a gated feature or lifts a cap, if present. */
+    get upgradeUrl(): string | undefined;
 }
 /** Thrown when the API key is missing or invalid (HTTP 401). */
 declare class AuthError extends PropLineError {
-    constructor(detail?: string);
+    constructor(detail?: string, info?: PropLineErrorInfo);
 }
 /** Thrown when the daily request limit is exceeded (HTTP 429). */
 declare class RateLimitError extends PropLineError {
-    constructor(detail?: string);
+    constructor(detail?: string, info?: PropLineErrorInfo);
 }
 interface PropLineOptions {
     /** API base URL. Default: `https://api.prop-line.com/v1`. */
@@ -886,6 +920,22 @@ interface VerifySignatureOptions {
     /** Value of the `X-PropLine-Signature` header. */
     signature: string;
 }
+/**
+ * Live daily-quota state, parsed from the `X-Daily-*` headers the API
+ * returns on every authenticated response.
+ */
+interface QuotaStatus {
+    /** Your tier's daily request cap. */
+    limit: number;
+    /** Requests used today (including the request that produced this). */
+    used: number;
+    /** Requests left before the cap. */
+    remaining: number;
+    /** Unix seconds when the quota resets (00:00 UTC — a hard reset, not a rolling window). */
+    resetEpoch: number;
+    /** Quota reset time as a `Date`. */
+    resetAt: Date;
+}
 /**
  * Client for the PropLine player props API.
  *
@@ -901,9 +951,24 @@ declare class PropLine {
     readonly apiKey: string;
     readonly baseUrl: string;
     readonly timeoutMs: number;
+    /**
+     * Daily-quota state from the most recent API response, or `null` before
+     * the first request. Updated on every call (including 429s):
+     *
+     * ```ts
+     * await client.getSports();
+     * console.log(client.lastQuota?.remaining); // 999
+     * ```
+     */
+    lastQuota: QuotaStatus | null;
     private readonly _fetch;
     constructor(apiKey: string, options?: PropLineOptions);
     private _buildUrl;
+    /**
+     * Record the X-Daily-* quota headers when present (absent on
+     * unauthenticated errors, e.g. an invalid key's 401).
+     */
+    private _captureQuota;
     private _request;
     /** List all available sports. */
     getSports(): Promise<Sport[]>;
@@ -1264,6 +1329,6 @@ declare const Bookmakers: {
     readonly PRIZEPICKS: "prizepicks";
 };
 type BookmakerKey = (typeof Bookmakers)[keyof typeof Bookmakers];
-declare const VERSION = "0.22.1";
+declare const VERSION = "0.24.0";
 
-export { AuthError, type BestLine, type BestLineSide, type BestPrice, type Bookmaker, type BookmakerKey, Bookmakers, type CalcEventEvOptions, type ClosingBookmaker, type ClosingMarket, type ClosingOutcome, type ContextResponse, type CreateWebhookOptions, type DfsPayoutTier, type DfsPayoutsResponse, type DfsPlayPayout, type EvLine, type EvOutcome, type Event, type EventBestLineResponse, type EventEvCalcResponse, type EventEvResponse, type ExportOddsHistoryOptions, type ExportResolvedPropsOptions, type FuturesEvent, type FuturesMarket, type FuturesOutcome, type GetDfsPayoutsOptions, type GetEventBestLineOptions, type GetEventEvOptions, type GetMlbGrandSalamiOptions, type GetNhlDailyGoalsTotalOptions, type GetOddsClosingOptions, type GetOddsHistoryOptions, type GetOddsOptions, type GetPlayerHistoryOptions, type GetPlayerTrendsOptions, type GetResultsOptions, type GetScoresOptions, type GetStatsOptions, type HitRateSplit, type ListWebhookDeliveriesOptions, type Market, type MarketSummary, type MlbGrandSalamiBook, type MlbGrandSalamiResponse, type MovementBookmaker, type MovementMarket, type MovementOutcome, type MovementResponse, type NhlDailyGoalsTotalBook, type NhlDailyGoalsTotalResponse, type OddsClosingResponse, type OddsHistoryBookmaker, type OddsHistoryMarket, type OddsHistoryOutcome, type OddsHistoryResponse, type OddsResponse, type Outcome, type OutcomeSnapshot, type PeriodFilter, type PlayerHistoryEntry, type PlayerHistoryResponse, type PlayerMarketTrend, type PlayerStat, type PlayerTrends, PropLine, PropLineError, type PropLineOptions, RateLimitError, type ResolutionSummary, type ResolutionSummaryMarket, type ResolutionSummarySport, type ResolvedOutcome, type ResultsMarket, type ResultsResponse, type ScoreEvent, type Sport, type StatsResponse, type SteamMove, type TrendLastGame, type TrendStreak, type UpdateWebhookOptions, VERSION, type VerifySignatureOptions, type WeatherInfo, type Webhook, type WebhookDelivery, type WebhookEventType };
+export { AuthError, type BestLine, type BestLineSide, type BestPrice, type Bookmaker, type BookmakerKey, Bookmakers, type CalcEventEvOptions, type ClosingBookmaker, type ClosingMarket, type ClosingOutcome, type ContextResponse, type CreateWebhookOptions, type DfsPayoutTier, type DfsPayoutsResponse, type DfsPlayPayout, type EvLine, type EvOutcome, type Event, type EventBestLineResponse, type EventEvCalcResponse, type EventEvResponse, type ExportOddsHistoryOptions, type ExportResolvedPropsOptions, type FuturesEvent, type FuturesMarket, type FuturesOutcome, type GetDfsPayoutsOptions, type GetEventBestLineOptions, type GetEventEvOptions, type GetMlbGrandSalamiOptions, type GetNhlDailyGoalsTotalOptions, type GetOddsClosingOptions, type GetOddsHistoryOptions, type GetOddsOptions, type GetPlayerHistoryOptions, type GetPlayerTrendsOptions, type GetResultsOptions, type GetScoresOptions, type GetStatsOptions, type HitRateSplit, type ListWebhookDeliveriesOptions, type Market, type MarketSummary, type MlbGrandSalamiBook, type MlbGrandSalamiResponse, type MovementBookmaker, type MovementMarket, type MovementOutcome, type MovementResponse, type NhlDailyGoalsTotalBook, type NhlDailyGoalsTotalResponse, type OddsClosingResponse, type OddsHistoryBookmaker, type OddsHistoryMarket, type OddsHistoryOutcome, type OddsHistoryResponse, type OddsResponse, type Outcome, type OutcomeSnapshot, type PeriodFilter, type PlayerHistoryEntry, type PlayerHistoryResponse, type PlayerMarketTrend, type PlayerStat, type PlayerTrends, PropLine, PropLineError, type PropLineErrorInfo, type PropLineOptions, type QuotaStatus, RateLimitError, type ResolutionSummary, type ResolutionSummaryMarket, type ResolutionSummarySport, type ResolvedOutcome, type ResultsMarket, type ResultsResponse, type ScoreEvent, type Sport, type StatsResponse, type SteamMove, type TrendLastGame, type TrendStreak, type UpdateWebhookOptions, VERSION, type VerifySignatureOptions, type WeatherInfo, type Webhook, type WebhookDelivery, type WebhookEventType };

package/dist/index.d.ts

@@ -653,19 +653,53 @@ interface GetDfsPayoutsOptions {
      */
     legWinProb?: number;
 }
+/**
+ * Structured error body returned by gated/throttled endpoints
+ * (see https://prop-line.com/docs#errors). Branch on `error` — the
+ * codes are stable — and follow the URLs instead of parsing prose.
+ */
+interface PropLineErrorInfo {
+    /** Stable machine-readable code, e.g. "upgrade_required", "daily_limit_exceeded". */
+    error?: string;
+    /** Human-readable sentence. */
+    message?: string;
+    /** Cheapest tier that unlocks a gated feature (403s). */
+    required_tier?: string;
+    /** Where to unlock it — pre-filled one-click URL on daily-cap 429s. */
+    upgrade_url?: string;
+    docs_url?: string;
+    signup_url?: string;
+    backfill_url?: string;
+    /** Burst-limit backoff hint (429s). */
+    retry_after_seconds?: number;
+    /** Daily-cap 429s: recommended next plan incl. its own upgrade_url. */
+    recommended?: {
+        plan?: string;
+        upgrade_url?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 /** Base error for all PropLine API failures. */
 declare class PropLineError extends Error {
     readonly statusCode: number;
+    /** Human-readable detail message. */
     readonly detail: string;
-    constructor(statusCode: number, detail: string);
+    /** Structured error body, when the API returned one. */
+    readonly info?: PropLineErrorInfo;
+    constructor(statusCode: number, detail: string, info?: PropLineErrorInfo);
+    /** Stable machine-readable code (e.g. "upgrade_required"), if present. */
+    get errorCode(): string | undefined;
+    /** The URL that unlocks a gated feature or lifts a cap, if present. */
+    get upgradeUrl(): string | undefined;
 }
 /** Thrown when the API key is missing or invalid (HTTP 401). */
 declare class AuthError extends PropLineError {
-    constructor(detail?: string);
+    constructor(detail?: string, info?: PropLineErrorInfo);
 }
 /** Thrown when the daily request limit is exceeded (HTTP 429). */
 declare class RateLimitError extends PropLineError {
-    constructor(detail?: string);
+    constructor(detail?: string, info?: PropLineErrorInfo);
 }
 interface PropLineOptions {
     /** API base URL. Default: `https://api.prop-line.com/v1`. */
@@ -886,6 +920,22 @@ interface VerifySignatureOptions {
     /** Value of the `X-PropLine-Signature` header. */
     signature: string;
 }
+/**
+ * Live daily-quota state, parsed from the `X-Daily-*` headers the API
+ * returns on every authenticated response.
+ */
+interface QuotaStatus {
+    /** Your tier's daily request cap. */
+    limit: number;
+    /** Requests used today (including the request that produced this). */
+    used: number;
+    /** Requests left before the cap. */
+    remaining: number;
+    /** Unix seconds when the quota resets (00:00 UTC — a hard reset, not a rolling window). */
+    resetEpoch: number;
+    /** Quota reset time as a `Date`. */
+    resetAt: Date;
+}
 /**
  * Client for the PropLine player props API.
  *
@@ -901,9 +951,24 @@ declare class PropLine {
     readonly apiKey: string;
     readonly baseUrl: string;
     readonly timeoutMs: number;
+    /**
+     * Daily-quota state from the most recent API response, or `null` before
+     * the first request. Updated on every call (including 429s):
+     *
+     * ```ts
+     * await client.getSports();
+     * console.log(client.lastQuota?.remaining); // 999
+     * ```
+     */
+    lastQuota: QuotaStatus | null;
     private readonly _fetch;
     constructor(apiKey: string, options?: PropLineOptions);
     private _buildUrl;
+    /**
+     * Record the X-Daily-* quota headers when present (absent on
+     * unauthenticated errors, e.g. an invalid key's 401).
+     */
+    private _captureQuota;
     private _request;
     /** List all available sports. */
     getSports(): Promise<Sport[]>;
@@ -1264,6 +1329,6 @@ declare const Bookmakers: {
     readonly PRIZEPICKS: "prizepicks";
 };
 type BookmakerKey = (typeof Bookmakers)[keyof typeof Bookmakers];
-declare const VERSION = "0.22.1";
+declare const VERSION = "0.24.0";
 
-export { AuthError, type BestLine, type BestLineSide, type BestPrice, type Bookmaker, type BookmakerKey, Bookmakers, type CalcEventEvOptions, type ClosingBookmaker, type ClosingMarket, type ClosingOutcome, type ContextResponse, type CreateWebhookOptions, type DfsPayoutTier, type DfsPayoutsResponse, type DfsPlayPayout, type EvLine, type EvOutcome, type Event, type EventBestLineResponse, type EventEvCalcResponse, type EventEvResponse, type ExportOddsHistoryOptions, type ExportResolvedPropsOptions, type FuturesEvent, type FuturesMarket, type FuturesOutcome, type GetDfsPayoutsOptions, type GetEventBestLineOptions, type GetEventEvOptions, type GetMlbGrandSalamiOptions, type GetNhlDailyGoalsTotalOptions, type GetOddsClosingOptions, type GetOddsHistoryOptions, type GetOddsOptions, type GetPlayerHistoryOptions, type GetPlayerTrendsOptions, type GetResultsOptions, type GetScoresOptions, type GetStatsOptions, type HitRateSplit, type ListWebhookDeliveriesOptions, type Market, type MarketSummary, type MlbGrandSalamiBook, type MlbGrandSalamiResponse, type MovementBookmaker, type MovementMarket, type MovementOutcome, type MovementResponse, type NhlDailyGoalsTotalBook, type NhlDailyGoalsTotalResponse, type OddsClosingResponse, type OddsHistoryBookmaker, type OddsHistoryMarket, type OddsHistoryOutcome, type OddsHistoryResponse, type OddsResponse, type Outcome, type OutcomeSnapshot, type PeriodFilter, type PlayerHistoryEntry, type PlayerHistoryResponse, type PlayerMarketTrend, type PlayerStat, type PlayerTrends, PropLine, PropLineError, type PropLineOptions, RateLimitError, type ResolutionSummary, type ResolutionSummaryMarket, type ResolutionSummarySport, type ResolvedOutcome, type ResultsMarket, type ResultsResponse, type ScoreEvent, type Sport, type StatsResponse, type SteamMove, type TrendLastGame, type TrendStreak, type UpdateWebhookOptions, VERSION, type VerifySignatureOptions, type WeatherInfo, type Webhook, type WebhookDelivery, type WebhookEventType };
+export { AuthError, type BestLine, type BestLineSide, type BestPrice, type Bookmaker, type BookmakerKey, Bookmakers, type CalcEventEvOptions, type ClosingBookmaker, type ClosingMarket, type ClosingOutcome, type ContextResponse, type CreateWebhookOptions, type DfsPayoutTier, type DfsPayoutsResponse, type DfsPlayPayout, type EvLine, type EvOutcome, type Event, type EventBestLineResponse, type EventEvCalcResponse, type EventEvResponse, type ExportOddsHistoryOptions, type ExportResolvedPropsOptions, type FuturesEvent, type FuturesMarket, type FuturesOutcome, type GetDfsPayoutsOptions, type GetEventBestLineOptions, type GetEventEvOptions, type GetMlbGrandSalamiOptions, type GetNhlDailyGoalsTotalOptions, type GetOddsClosingOptions, type GetOddsHistoryOptions, type GetOddsOptions, type GetPlayerHistoryOptions, type GetPlayerTrendsOptions, type GetResultsOptions, type GetScoresOptions, type GetStatsOptions, type HitRateSplit, type ListWebhookDeliveriesOptions, type Market, type MarketSummary, type MlbGrandSalamiBook, type MlbGrandSalamiResponse, type MovementBookmaker, type MovementMarket, type MovementOutcome, type MovementResponse, type NhlDailyGoalsTotalBook, type NhlDailyGoalsTotalResponse, type OddsClosingResponse, type OddsHistoryBookmaker, type OddsHistoryMarket, type OddsHistoryOutcome, type OddsHistoryResponse, type OddsResponse, type Outcome, type OutcomeSnapshot, type PeriodFilter, type PlayerHistoryEntry, type PlayerHistoryResponse, type PlayerMarketTrend, type PlayerStat, type PlayerTrends, PropLine, PropLineError, type PropLineErrorInfo, type PropLineOptions, type QuotaStatus, RateLimitError, type ResolutionSummary, type ResolutionSummaryMarket, type ResolutionSummarySport, type ResolvedOutcome, type ResultsMarket, type ResultsResponse, type ScoreEvent, type Sport, type StatsResponse, type SteamMove, type TrendLastGame, type TrendStreak, type UpdateWebhookOptions, VERSION, type VerifySignatureOptions, type WeatherInfo, type Webhook, type WebhookDelivery, type WebhookEventType };

package/dist/index.js

@@ -3,25 +3,37 @@ import { createHmac, timingSafeEqual } from "crypto";
 import { writeFile } from "fs/promises";
 var PropLineError = class extends Error {
   statusCode;
+  /** Human-readable detail message. */
   detail;
-  constructor(statusCode, detail) {
+  /** Structured error body, when the API returned one. */
+  info;
+  constructor(statusCode, detail, info) {
     super(`[${statusCode}] ${detail}`);
     this.name = "PropLineError";
     this.statusCode = statusCode;
     this.detail = detail;
+    this.info = info;
     Object.setPrototypeOf(this, new.target.prototype);
   }
+  /** Stable machine-readable code (e.g. "upgrade_required"), if present. */
+  get errorCode() {
+    return this.info?.error;
+  }
+  /** The URL that unlocks a gated feature or lifts a cap, if present. */
+  get upgradeUrl() {
+    return this.info?.upgrade_url ?? this.info?.recommended?.upgrade_url;
+  }
 };
 var AuthError = class extends PropLineError {
-  constructor(detail = "Invalid API key") {
-    super(401, detail);
+  constructor(detail = "Invalid API key", info) {
+    super(401, detail, info);
     this.name = "AuthError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 var RateLimitError = class extends PropLineError {
-  constructor(detail = "Rate limit exceeded") {
-    super(429, detail);
+  constructor(detail = "Rate limit exceeded", info) {
+    super(429, detail, info);
     this.name = "RateLimitError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
@@ -40,6 +52,16 @@ var PropLine = class {
   apiKey;
   baseUrl;
   timeoutMs;
+  /**
+   * Daily-quota state from the most recent API response, or `null` before
+   * the first request. Updated on every call (including 429s):
+   *
+   * ```ts
+   * await client.getSports();
+   * console.log(client.lastQuota?.remaining); // 999
+   * ```
+   */
+  lastQuota = null;
   _fetch;
   constructor(apiKey, options = {}) {
     if (!apiKey) {
@@ -69,6 +91,25 @@ var PropLine = class {
     }
     return url.toString();
   }
+  /**
+   * Record the X-Daily-* quota headers when present (absent on
+   * unauthenticated errors, e.g. an invalid key's 401).
+   */
+  _captureQuota(resp) {
+    const limit = Number(resp.headers.get("X-Daily-Limit"));
+    const used = Number(resp.headers.get("X-Daily-Used"));
+    const remaining = Number(resp.headers.get("X-Daily-Remaining"));
+    const resetEpoch = Number(resp.headers.get("X-Daily-Reset"));
+    if (resp.headers.has("X-Daily-Limit") && Number.isFinite(limit) && Number.isFinite(used) && Number.isFinite(remaining) && Number.isFinite(resetEpoch)) {
+      this.lastQuota = {
+        limit,
+        used,
+        remaining,
+        resetEpoch,
+        resetAt: new Date(resetEpoch * 1e3)
+      };
+    }
+  }
   async _request(method, path, init = {}) {
     const url = this._buildUrl(path, init.params);
     const controller = new AbortController();
@@ -87,14 +128,18 @@ var PropLine = class {
     } finally {
       clearTimeout(timer);
     }
+    this._captureQuota(resp);
     if (resp.status === 401) {
-      throw new AuthError(await readDetail(resp, "Invalid API key"));
+      const d = await readDetail(resp, "Invalid API key");
+      throw new AuthError(d.message, d.info);
     }
     if (resp.status === 429) {
-      throw new RateLimitError(await readDetail(resp, "Rate limit exceeded"));
+      const d = await readDetail(resp, "Rate limit exceeded");
+      throw new RateLimitError(d.message, d.info);
     }
     if (resp.status >= 400) {
-      throw new PropLineError(resp.status, await readDetail(resp, resp.statusText));
+      const d = await readDetail(resp, resp.statusText);
+      throw new PropLineError(resp.status, d.message, d.info);
     }
     if (resp.status === 204) {
       return void 0;
@@ -541,14 +586,17 @@ var PropLine = class {
     } finally {
       clearTimeout(timer);
     }
+    this._captureQuota(resp);
     if (resp.status === 401) {
       throw new AuthError();
     }
     if (resp.status === 403) {
-      throw new PropLineError(403, await readDetail(resp, "Pro tier required"));
+      const d = await readDetail(resp, "Pro tier required");
+      throw new PropLineError(403, d.message, d.info);
     }
     if (resp.status >= 400) {
-      throw new PropLineError(resp.status, await readDetail(resp, resp.statusText));
+      const d = await readDetail(resp, resp.statusText);
+      throw new PropLineError(resp.status, d.message, d.info);
     }
     const buf = new Uint8Array(await resp.arrayBuffer());
     if (options.outPath) {
@@ -576,17 +624,20 @@ var PropLine = class {
     } finally {
       clearTimeout(timer);
     }
+    this._captureQuota(resp);
     if (resp.status === 401) {
       throw new AuthError();
     }
     if (resp.status === 403) {
-      throw new PropLineError(
-        403,
-        await readDetail(resp, "Historical Backfill pass or Enterprise required")
+      const d = await readDetail(
+        resp,
+        "Historical Backfill pass or Enterprise required"
       );
+      throw new PropLineError(403, d.message, d.info);
     }
     if (resp.status >= 400) {
-      throw new PropLineError(resp.status, await readDetail(resp, resp.statusText));
+      const d = await readDetail(resp, resp.statusText);
+      throw new PropLineError(resp.status, d.message, d.info);
     }
     const buf = new Uint8Array(await resp.arrayBuffer());
     if (options.outPath) {
@@ -696,15 +747,22 @@ function webhookBody(options) {
 async function readDetail(resp, fallback) {
   try {
     const text = await resp.text();
-    if (!text) return fallback;
+    if (!text) return { message: fallback };
     try {
       const json = JSON.parse(text);
-      if (typeof json.detail === "string") return json.detail;
+      if (typeof json.detail === "string") return { message: json.detail };
+      if (json.detail && typeof json.detail === "object") {
+        const info = json.detail;
+        return {
+          message: typeof info.message === "string" ? info.message : text,
+          info
+        };
+      }
     } catch {
     }
-    return text || fallback;
+    return { message: text || fallback };
   } catch {
-    return fallback;
+    return { message: fallback };
   }
 }
 
@@ -720,7 +778,7 @@ var Bookmakers = {
   POLYMARKET: "polymarket",
   PRIZEPICKS: "prizepicks"
 };
-var VERSION = "0.22.1";
+var VERSION = "0.24.0";
 export {
   AuthError,
   Bookmakers,