nhl-api-ts 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Angelle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,316 @@
-# Temporary Holding Version
+# nhl-api-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK **and** command line tool for the NHL API and NHL EDGE stats.
+
+Every SDK method is also available as a CLI command.
+
+- Zero runtime dependencies (uses the built-in `fetch`)
+- Node.js >= 24, ESM only
+- Fully typed: every response has a named interface you can [extend](docs/recipes/extending-response-types.md)
+
+## Documentation
+
+- [Concepts](docs/concepts.md): ID formats, the two NHL APIs, "now" redirects, pagination, retries
+- [Errors](docs/errors.md): every error, its cause and the fix
+- [Recipes](docs/recipes/): [filtered stats](docs/recipes/filter-skater-stats.md),
+  [pagination](docs/recipes/paginate-stats.md), [live scores](docs/recipes/live-scores.md),
+  [season-wide data](docs/recipes/season-wide-data.md), [retries](docs/recipes/retries.md),
+  [CLI + jq](docs/recipes/cli-and-jq.md), [testing](docs/recipes/testing.md),
+  [extending response types](docs/recipes/extending-response-types.md)
+- [Examples](examples/): runnable scripts
+- [API report](api-report.md): the full public TypeScript API
+- [OpenAPI](openapi.yaml): every HTTP path the SDK calls
+- [Migration guide](MIGRATION.md): breaking changes between versions
+- For LLMs and agents: [llms.txt](llms.txt), [llms-full.txt](llms-full.txt),
+  [Agent Skill](skills/nhl-api-ts/SKILL.md)
+
+## Installation
+
+```bash
+pnpm add nhl-api-ts      # SDK
+pnpm add -g nhl-api-ts   # CLI (`nhl-api-ts` on your PATH)
+# or run the CLI without installing:
+npx nhl-api-ts --help
+```
+
+## SDK quick start
+
+```ts
+import { createNHLClient } from 'nhl-api-ts';
+
+const client = createNHLClient();
+
+const teams = await client.teams.teams();
+const standings = await client.standings.leagueStandings();
+const games = await client.schedule.dailySchedule();
+```
+
+Every method is `async` and takes a single options object:
+
+```ts
+await client.gameCenter.boxscore({ gameId: '2023020280' });
+await client.edge.skaterDetail({ playerId: 8478402, season: 20232024 });
+await client.stats.teamSummary({ startSeason: 20202021, endSeason: 20232024 });
+```
+
+IDs and seasons accept either strings or numbers.
+
+## Configuration
+
+```ts
+const client = createNHLClient({
+  debug: true,           // log each request URL to stderr (default false)
+  timeout: 30,           // seconds (default 10)
+  followRedirects: true, // "/now" endpoints redirect to today's data (default true)
+});
+```
+
+## API modules
+
+All methods below live on `client.<module>`. Parameters in `[brackets]` are
+optional.
+
+### teams
+
+- `teams({ [date] })` — all teams with conference, division and `franchise_id`
+- `teamRoster({ teamAbbr, season })`
+- `franchises()`
+
+### standings
+
+- `leagueStandings({ [date], [season] })` — `season` uses that season's final standings
+- `seasonStandingManifest()`
+
+### schedule
+
+- `dailySchedule({ [date] })` — date is validated/normalized (`2024-10-9` → `2024-10-09`)
+- `weeklySchedule({ [date] })`
+- `teamMonthlySchedule({ teamAbbr, [month] })`
+- `teamWeeklySchedule({ teamAbbr, [date] })`
+- `teamSeasonSchedule({ teamAbbr, season })`
+- `calendarSchedule({ date })`
+- `playoffCarousel({ season })`
+- `playoffSeriesSchedule({ season, series })`
+- `playoffBracket({ year })`
+
+### gameCenter
+
+- `boxscore({ gameId })`
+- `playByPlay({ gameId })`
+- `matchUp({ gameId })`
+- `dailyScores({ [date] })`
+- `shiftChartData({ gameId, [excludes] })`
+- `seasonSeriesMatchup({ gameId })`
+- `gameStory({ gameId })`
+
+### stats
+
+- `gametypesPerSeasonDirectoryByTeam({ teamAbbr })`
+- `playerCareerStats({ playerId })`
+- `playerGameLog({ playerId, seasonId, gameType })`
+- `teamSummary({ startSeason, endSeason, [gameTypeId], [isGame], [isAggregate], [sortExpr], [start], [limit], [factCayenneExp], [defaultCayenneExp] })`
+- `skaterStatsSummary({ startSeason, endSeason, [franchiseId], [gameTypeId], [aggregate], [sortExpr], [start], [limit], [factCayenneExp], [defaultCayenneExp] })`
+- `skaterStatsWithQueryContext({ queryContext, reportType, [sortExpr], [aggregate], [start], [limit] })`
+- `goalieStatsSummary({ startSeason, [endSeason], [statsType], [gameTypeId], [franchiseId], [aggregate], [sortExpr], [start], [limit], [factCayenneExp], [defaultCayenneExp] })`
+
+### edge
+
+Every EDGE method takes `[season]` and `[gameType]` (2 = regular season, the
+default; 3 = playoffs). Without `season` the current season (`/now`) is used.
+
+- Skaters (`{ playerId }`): `skaterDetail`, `skaterShotSpeedDetail`,
+  `skaterSkatingSpeedDetail`, `skaterShotLocationDetail`,
+  `skaterSkatingDistanceDetail`, `skaterComparison`, `skaterZoneTime`,
+  `catSkaterDetail`
+- Goalies (`{ playerId }`): `goalieDetail`, `goalieShotLocationDetail`,
+  `goalie5v5Detail`, `goalieComparison`, `goalieSavePercentageDetail`,
+  `catGoalieDetail`
+- Teams (`{ teamId }`): `teamDetail`, `teamSkatingDistanceDetail`,
+  `teamZoneTimeDetails`, `teamShotLocationDetail`, `teamShotSpeedDetail`,
+  `teamSkatingSpeedDetail`
+- Landing pages (no id): `skaterLanding`, `goalieLanding`, `teamLanding`
+
+### players
+
+- `prospectsByTeam({ teamAbbr })`
+- `playersByTeam({ teamAbbr, season })`
+
+### misc
+
+- `glossary()`, `config()`, `countries()`, `seasonSpecificRulesAndInfo()`,
+  `draftYearAndRounds()`
+
+### helpers
+
+These make one or more requests per team and sleep `apiSleepRate` seconds
+between teams to avoid rate limiting.
+
+- `gameIdsBySeason({ season, [gameTypes], [apiSleepRate] })`
+- `allPlayers({ season, [apiSleepRate] })`
+- `allPlayersSummaryStatistics({ season, [apiSleepRate] })`
+
+## Query builder
+
+```ts
+import { createNHLClient, buildQuery, isValidQuery, filter, PositionTypes } from 'nhl-api-ts';
+
+const client = createNHLClient();
+
+const context = buildQuery([
+  filter.gameType('2'),
+  filter.season('20232024', '20232024'),
+  filter.position(PositionTypes.ALL_FORWARDS),
+  filter.draft('2015', '1'),
+]);
+
+if (!isValidQuery(context)) console.error(context.errors);
+
+const { data, total } = await client.stats.skaterStatsWithQueryContext({
+  queryContext: context,
+  reportType: 'summary',
+  aggregate: true,
+});
+```
+
+Available filters: `filter.decision`, `filter.draft`, `filter.experience`,
+`filter.franchise`, `filter.gameType`, `filter.homeRoad`,
+`filter.nationality`, `filter.opponent`, `filter.position`, `filter.season`,
+`filter.shootCatch`, `filter.status`.
+
+Skater report types: `summary`, `bios`, `faceoffpercentages`, `faceoffwins`,
+`goalsForAgainst`, `realtime`, `penalties`, `penaltykill`, `penaltyShots`,
+`powerplay`, `puckPossessions`, `summaryshooting`, `percentages`,
+`scoringRates`, `scoringpergame`, `shootout`, `shottype`, `timeonice`.
+
+## Extending the types
+
+Response types come from real API responses, and the NHL adds fields without
+notice. Every object type is an `interface`, so you can add what's missing with
+module augmentation:
+
+```ts
+declare module 'nhl-api-ts' {
+  interface Boxscore {
+    someNewField?: string;
+  }
+}
+```
+
+New play types and report types are added through registries (`PlayTypes`,
+`SkaterReportRows`, `GoalieReportRows`). See
+[Extending response types](docs/recipes/extending-response-types.md) for those
+and for the one-off cast.
+
+## Errors
+
+HTTP failures throw exceptions that all extend `NHLApiException`, which has
+`statusCode` and `errorCode`:
+
+| Status | Exception                    |
+| ------ | ---------------------------- |
+| 400    | `BadRequestException`        |
+| 401    | `UnauthorizedException`      |
+| 404    | `ResourceNotFoundException`  |
+| 429    | `RateLimitExceededException` |
+| 5xx    | `ServerErrorException`       |
+| other  | `NHLApiException`            |
+
+Invalid input (bad dates, unknown seasons) throws a `RangeError`.
+
+```ts
+import { ResourceNotFoundException } from 'nhl-api-ts';
+
+try {
+  await client.gameCenter.boxscore({ gameId: 1 });
+} catch (err) {
+  if (err instanceof ResourceNotFoundException) console.log(err.statusCode); // 404
+}
+```
+
+## CLI
+
+```
+nhl-api-ts <module> <command> [args] [options]
+```
+
+Modules and commands are the kebab-case names of the SDK modules and methods,
+and options are the kebab-case parameter names. Required parameters can be
+passed positionally, in order, or as flags. Results are printed to stdout as
+JSON.
+
+```bash
+nhl-api-ts --help                      # list modules
+nhl-api-ts edge --help                 # list a module's commands
+nhl-api-ts stats team-summary --help   # a command's arguments and options
+
+nhl-api-ts teams teams
+nhl-api-ts schedule daily-schedule --date 2024-10-09
+nhl-api-ts game-center boxscore 2023020280
+nhl-api-ts game-center shift-chart-data 2023020280 --excludes eventDetails,playerStats
+nhl-api-ts standings league-standings --season 20222023
+nhl-api-ts edge skater-detail 8478402 --season 20232024 --game-type 3
+nhl-api-ts stats team-summary 20202021 20232024 --game-type-id 3 --limit 5
+nhl-api-ts stats goalie-stats-summary 20232024 --stats-type advanced
+nhl-api-ts helpers game-ids-by-season 20232024 --game-types 2,3
+```
+
+The query builder is available through filter flags on
+`stats skater-stats-with-query-context`:
+
+```bash
+nhl-api-ts stats skater-stats-with-query-context summary \
+  --season-start 20232024 --position F --nationality SWE --rookie --limit 10
+```
+
+Filter flags: `--season-start`, `--season-end`, `--franchise-id`,
+`--game-type`, `--position` (F/C/L/R/D), `--nationality`, `--decision`
+(W/L/O), `--draft-year`, `--draft-round`, `--rookie` / `--no-rookie`,
+`--home-road` (H/R), `--opponent-franchise-id`, `--shoot-catch` (L/R),
+`--active`, `--hall-of-fame`.
+
+Global options:
+
+| Option                  | Description                       |
+| ----------------------- | --------------------------------- |
+| `--compact`             | Print JSON on a single line       |
+| `--debug`               | Log request URLs to stderr        |
+| `--timeout <seconds>`   | Request timeout (default 10)      |
+| `--no-follow-redirects` | Do not follow HTTP redirects      |
+| `-v`, `--version`       | Print the version                 |
+
+Exit codes: `0` success, `1` API or network error, `2` invalid usage.
+Progress and warning messages from `helpers` go to stderr, so stdout is always
+clean JSON.
+
+Pipe output to `jq` to slice it:
+
+```bash
+nhl-api-ts teams teams --compact | jq -r '.[].abbr'
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm test         # node:test, runs the TypeScript sources directly
+pnpm typecheck
+pnpm lint:check
+pnpm build        # emits dist/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full set of checks, and
+[AGENTS.md](AGENTS.md) for repository conventions.
+
+Try the CLI from source:
+
+```bash
+node --conditions=source src/cli.mts --help
+```
+
+## Credits
+
+Ported from [nhl-api-py](https://github.com/coreyjs/nhl-api-py).
+
+## License
+
+[MIT](LICENSE)

package/dist/api/edge.d.mts

@@ -0,0 +1,180 @@
+import type { Context } from '#src/context.mjs';
+import type { CatGoalieDetail, CatSkaterDetail, Goalie5v5Detail, GoalieComparison, GoalieDetail, GoalieLanding, GoalieSavePercentageDetail, GoalieShotLocationDetail, SkaterComparison, SkaterDetail, SkaterLanding, SkaterShotLocationDetail, SkaterShotSpeedDetail, SkaterSkatingDistanceDetail, SkaterSkatingSpeedDetail, SkaterZoneTime, TeamDetail, TeamLanding, TeamShotLocationDetail, TeamShotSpeedDetail, TeamSkatingDistanceDetail, TeamSkatingSpeedDetail, TeamZoneTimeDetails } from '#src/types/index.mjs';
+import type { Id } from '#src/utils.mjs';
+export interface EdgeSeasonParams {
+    /** Season in YYYYYYYY format, e.g. 20232024. Defaults to the current season ("now"). */
+    season?: Id;
+    /** 2=Regular season (default), 3=Playoffs. Ignored when `season` is omitted. */
+    gameType?: number;
+}
+export interface EdgePlayerParams extends EdgeSeasonParams {
+    /** NHL player id, e.g. 8478402 */
+    playerId: Id;
+}
+export interface EdgeTeamParams extends EdgeSeasonParams {
+    /** NHL team id, e.g. 10 */
+    teamId: Id;
+}
+/**
+ * Get NHL EDGE skater detail statistics for a specific player.
+ *
+ * @example await client.edge.skaterDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterDetail: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterDetail>;
+/**
+ * Get NHL EDGE shot speed details for a specific skater.
+ *
+ * @example await client.edge.skaterShotSpeedDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterShotSpeedDetail: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterShotSpeedDetail>;
+/**
+ * Get NHL EDGE skating speed details for a specific skater.
+ *
+ * @example await client.edge.skaterSkatingSpeedDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterSkatingSpeedDetail: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterSkatingSpeedDetail>;
+/**
+ * Get NHL EDGE shot location details for a specific skater.
+ *
+ * @example await client.edge.skaterShotLocationDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterShotLocationDetail: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterShotLocationDetail>;
+/**
+ * Get NHL EDGE skating distance details for a specific skater.
+ *
+ * @example await client.edge.skaterSkatingDistanceDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterSkatingDistanceDetail: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterSkatingDistanceDetail>;
+/**
+ * Get NHL EDGE comparison statistics for a specific skater.
+ *
+ * @example await client.edge.skaterComparison({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterComparison: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterComparison>;
+/**
+ * Get NHL EDGE zone time details for a specific skater.
+ *
+ * @example await client.edge.skaterZoneTime({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const skaterZoneTime: (ctx: Context, params: EdgePlayerParams) => Promise<SkaterZoneTime>;
+/**
+ * Get NHL EDGE skater landing page data.
+ *
+ * @example await client.edge.skaterLanding({ season: '20232024' })
+ */
+export declare const skaterLanding: (ctx: Context, params?: EdgeSeasonParams) => Promise<SkaterLanding>;
+/**
+ * Get NHL CAT (Catch All Tracking) EDGE skater details.
+ *
+ * @example await client.edge.catSkaterDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const catSkaterDetail: (ctx: Context, params: EdgePlayerParams) => Promise<CatSkaterDetail>;
+/**
+ * Get NHL EDGE goalie detail statistics for a specific player.
+ *
+ * @example await client.edge.goalieDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const goalieDetail: (ctx: Context, params: EdgePlayerParams) => Promise<GoalieDetail>;
+/**
+ * Get NHL EDGE shot location details for a specific goalie.
+ *
+ * @example await client.edge.goalieShotLocationDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const goalieShotLocationDetail: (ctx: Context, params: EdgePlayerParams) => Promise<GoalieShotLocationDetail>;
+/**
+ * Get NHL EDGE 5v5 performance details for a specific goalie.
+ *
+ * @example await client.edge.goalie5v5Detail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const goalie5v5Detail: (ctx: Context, params: EdgePlayerParams) => Promise<Goalie5v5Detail>;
+/**
+ * Get NHL EDGE comparison statistics for a specific goalie.
+ *
+ * @example await client.edge.goalieComparison({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const goalieComparison: (ctx: Context, params: EdgePlayerParams) => Promise<GoalieComparison>;
+/**
+ * Get NHL EDGE save percentage details for a specific goalie.
+ *
+ * @example await client.edge.goalieSavePercentageDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const goalieSavePercentageDetail: (ctx: Context, params: EdgePlayerParams) => Promise<GoalieSavePercentageDetail>;
+/**
+ * Get NHL EDGE goalie landing page data.
+ *
+ * @example await client.edge.goalieLanding({ season: '20232024' })
+ */
+export declare const goalieLanding: (ctx: Context, params?: EdgeSeasonParams) => Promise<GoalieLanding>;
+/**
+ * Get NHL CAT (Catch All Tracking) EDGE goalie details.
+ *
+ * @example await client.edge.catGoalieDetail({ playerId: 8478402, season: '20232024', gameType: 2 })
+ */
+export declare const catGoalieDetail: (ctx: Context, params: EdgePlayerParams) => Promise<CatGoalieDetail>;
+/**
+ * Get NHL EDGE team detail statistics for a specific team.
+ *
+ * @example await client.edge.teamDetail({ teamId: 10 })
+ */
+export declare const teamDetail: (ctx: Context, params: EdgeTeamParams) => Promise<TeamDetail>;
+/**
+ * Get NHL EDGE skating distance details for a specific team.
+ *
+ * @example await client.edge.teamSkatingDistanceDetail({ teamId: 10 })
+ */
+export declare const teamSkatingDistanceDetail: (ctx: Context, params: EdgeTeamParams) => Promise<TeamSkatingDistanceDetail>;
+/**
+ * Get NHL EDGE zone time details for a specific team.
+ *
+ * @example await client.edge.teamZoneTimeDetails({ teamId: 10 })
+ */
+export declare const teamZoneTimeDetails: (ctx: Context, params: EdgeTeamParams) => Promise<TeamZoneTimeDetails>;
+/**
+ * Get NHL EDGE shot location details for a specific team.
+ *
+ * @example await client.edge.teamShotLocationDetail({ teamId: 10 })
+ */
+export declare const teamShotLocationDetail: (ctx: Context, params: EdgeTeamParams) => Promise<TeamShotLocationDetail>;
+/**
+ * Get NHL EDGE team landing page data.
+ *
+ * @example await client.edge.teamLanding({ season: '20232024' })
+ */
+export declare const teamLanding: (ctx: Context, params?: EdgeSeasonParams) => Promise<TeamLanding>;
+/**
+ * Get NHL EDGE shot speed details for a specific team.
+ *
+ * @example await client.edge.teamShotSpeedDetail({ teamId: 10 })
+ */
+export declare const teamShotSpeedDetail: (ctx: Context, params: EdgeTeamParams) => Promise<TeamShotSpeedDetail>;
+/**
+ * Get NHL EDGE skating speed details for a specific team.
+ *
+ * @example await client.edge.teamSkatingSpeedDetail({ teamId: 10 })
+ */
+export declare const teamSkatingSpeedDetail: (ctx: Context, params: EdgeTeamParams) => Promise<TeamSkatingSpeedDetail>;
+export declare const edgeApi: {
+    readonly skaterDetail: typeof skaterDetail;
+    readonly skaterShotSpeedDetail: typeof skaterShotSpeedDetail;
+    readonly skaterSkatingSpeedDetail: typeof skaterSkatingSpeedDetail;
+    readonly skaterShotLocationDetail: typeof skaterShotLocationDetail;
+    readonly skaterSkatingDistanceDetail: typeof skaterSkatingDistanceDetail;
+    readonly skaterComparison: typeof skaterComparison;
+    readonly skaterZoneTime: typeof skaterZoneTime;
+    readonly skaterLanding: typeof skaterLanding;
+    readonly catSkaterDetail: typeof catSkaterDetail;
+    readonly goalieDetail: typeof goalieDetail;
+    readonly goalieShotLocationDetail: typeof goalieShotLocationDetail;
+    readonly goalie5v5Detail: typeof goalie5v5Detail;
+    readonly goalieComparison: typeof goalieComparison;
+    readonly goalieSavePercentageDetail: typeof goalieSavePercentageDetail;
+    readonly goalieLanding: typeof goalieLanding;
+    readonly catGoalieDetail: typeof catGoalieDetail;
+    readonly teamDetail: typeof teamDetail;
+    readonly teamSkatingDistanceDetail: typeof teamSkatingDistanceDetail;
+    readonly teamZoneTimeDetails: typeof teamZoneTimeDetails;
+    readonly teamShotLocationDetail: typeof teamShotLocationDetail;
+    readonly teamLanding: typeof teamLanding;
+    readonly teamShotSpeedDetail: typeof teamShotSpeedDetail;
+    readonly teamSkatingSpeedDetail: typeof teamSkatingSpeedDetail;
+};