kingsplaybook

The official TypeScript / JavaScript SDK for the KingsPlaybook Developer API — confirmed lineups, raw player projections, canonical game lines, and a pick-history archive for NBA, MLB, and NHL.

It's a thin, fully typed wrapper over the public /v1 REST API: one client class, one method per endpoint, typed responses throughout. Zero runtime dependencies — it uses the native fetch built into Node 18+.

Install

npm install kingsplaybook

Get an API key

Sign up at kingsplaybook.org/devs. Your key looks like kp_live_…. The Free tier covers lineups; paid tiers add projections, lines, and history.

Quick start

import { KingsPlaybook } from "kingsplaybook";

const kp = new KingsPlaybook({ apiKey: "kp_live_…" });

// Confirmed lineups (Free tier)
const lineups = await kp.lineups({ league: "nba", date: "2026-05-21" });
for (const game of lineups.data) {
  console.log(game.away_team?.abbreviation, "@", game.home_team?.abbreviation);
}

// Player projections (Starter tier and up)
const { data: projections } = await kp.projections({
  league: "nba",
  date: "2026-05-21",
});
console.log(`${projections.length} projections`);

The apiKey option falls back to the KINGSPLAYBOOK_API_KEY environment variable, so new KingsPlaybook() works when that is set.

Methods

| Method | Endpoint | Min. tier | |---|---|---| | kp.health() | GET /v1/health | none | | kp.freshness() | GET /v1/meta/freshness | Free | | kp.lineups({ league, date }) | GET /v1/lineups | Free | | kp.projections({ league, date }) | GET /v1/projections | Starter | | kp.lines({ league, date }) | GET /v1/lines | Pro | | kp.history({ date, type?, sport? }) | GET /v1/history/picks | Premium |

league is "nba" | "mlb" | "nhl". date is an ISO-8601 string (YYYY-MM-DD). For history, type is "game" | "prop" (omit for both).

Every method returns a fully typed response — the response interfaces (LineupsResponse, ProjectionsResponse, …) are exported from the package root.

Error handling

Every failure throws a KingsPlaybookError or a subclass. The subclass tells you what went wrong without parsing a message:

import {
  KingsPlaybook,
  AuthenticationError,
  TierError,
  RateLimitError,
} from "kingsplaybook";

try {
  await kp.lines({ league: "mlb", date: "2026-05-21" });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401 — key missing, invalid, or revoked
  } else if (err instanceof TierError) {
    // 403 — your plan does not include this endpoint
  } else if (err instanceof RateLimitError) {
    // 429 — back off and retry
  } else if (err instanceof KingsPlaybookError) {
    // anything else (transport, 404, 5xx) — err.status has the code
  }
}

Configuration

new KingsPlaybook({
  apiKey: "kp_live_…",        // or KINGSPLAYBOOK_API_KEY
  baseUrl: "https://api.kingsplaybook.org", // or KINGSPLAYBOOK_API_URL
  timeoutMs: 30000,           // per-request timeout
  fetch: customFetch,         // override the fetch implementation
});

License

MIT