nhl-api-ts 0.2.0 → 0.3.0

package/README.md

@@ -73,8 +73,12 @@ optional.
 ### teams
 
 - `teams({ [date] })` — all teams with conference, division and `franchise_id`
-- `teamRoster({ teamAbbr, season })`
+- `teamRoster({ teamAbbr, [season] })` — no `season` → current roster
+- `rosterSeasons({ teamAbbr })` — every season the team has a roster for
+- `teamScoreboard({ teamAbbr })` — recent and upcoming games
 - `franchises()`
+- `statsTeams()` — every team in the stats API, past and present (raw rows with `franchiseId`, `triCode`)
+- `teamById({ teamId })` — one stats API team row; an unknown id throws `ResourceNotFoundException`
 
 ### standings
 
@@ -87,10 +91,11 @@ optional.
 - `weeklySchedule({ [date] })`
 - `teamMonthlySchedule({ teamAbbr, [month] })`
 - `teamWeeklySchedule({ teamAbbr, [date] })`
-- `teamSeasonSchedule({ teamAbbr, season })`
-- `calendarSchedule({ date })`
+- `teamSeasonSchedule({ teamAbbr, [season] })`
+- `calendarSchedule({ [date] })`
 - `playoffCarousel({ season })`
 - `playoffSeriesSchedule({ season, series })`
+- `playoffSeriesMeta({ year, series })` — round title and the two seeded teams
 - `playoffBracket({ year })`
 
 ### gameCenter
@@ -102,16 +107,26 @@ optional.
 - `shiftChartData({ gameId, [excludes] })`
 - `seasonSeriesMatchup({ gameId })`
 - `gameStory({ gameId })`
+- `scoreboard({ [date] })` — every game in the week around a date, grouped by date
+- `wscPlayByPlay({ gameId })` — flat play array (a different shape from `playByPlay`)
+- `playReplay({ gameId, eventNumber })` — replay card for one event; `goal` only for goals (experimental)
+- `gameMeta({ gameId })` — teams, season state and game state
 
 ### stats
 
 - `gametypesPerSeasonDirectoryByTeam({ teamAbbr })`
 - `playerCareerStats({ playerId })`
-- `playerGameLog({ playerId, seasonId, gameType })`
+- `playerGameLog({ playerId, [seasonId], [gameType] })`
+- `skaterStatsLeaders({ [season], [gameType], [categories], [limit] })` — leaders keyed by category (`goals`, `points`, `toi`, ...); `limit: -1` returns every player
+- `goalieStatsLeaders({ [season], [gameType], [categories], [limit] })` — `wins`, `shutouts`, `savePctg`, `goalsAgainstAverage`
+- `clubStats({ teamAbbr, [season], [gameType] })` — a team's skater and goalie stats
 - `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] })`
+- `skaterLeaders({ attribute, [season] })` — top 10 single-season records, all time or for one `season`; `attribute` is `points`, `goals`, `assists` or `gamesPlayed`
+- `goalieLeaders({ attribute, [season] })` — same, for `gaa`, `savePctg`, `shutouts`, `timeOnIce` or `gamesPlayed`. `gaa` / `savePctg` have no minimum games, so the top rows are goalies with a few minutes played (all-time `gaa` is `null`)
+- `skaterMilestones()`, `goalieMilestones()` — career milestones active players are approaching
 
 ### edge
 
@@ -129,16 +144,68 @@ default; 3 = playoffs). Without `season` the current season (`/now`) is used.
   `teamZoneTimeDetails`, `teamShotLocationDetail`, `teamShotSpeedDetail`,
   `teamSkatingSpeedDetail`
 - Landing pages (no id): `skaterLanding`, `goalieLanding`, `teamLanding`
+- Team comparison (`{ teamId }`): `teamComparison`
+- League highlights: `byTheNumbers({ [season], [gameType] })`. Without `season`
+  it covers the latest game night; with one, the season bests
+- Leaderboards (top 10, no id). Each returns a bare array of 10 rows that carry
+  every metric of that leaderboard; `sortBy` (required) only picks the order.
+  `positions` (`'all'`, `'forwards'`, `'defense'`; see `EdgePositions`),
+  `strength` (`'all'`, `'es'`, `'pp'`, `'pk'`; see `EdgeStrengths`) and the
+  shot-location `category` (`'all'`, `'high'`, `'mid'`, `'long'`) default to
+  `'all'`:
+  - Skaters: `skaterDistanceTop10({ [positions], [strength], sortBy })`,
+    `skaterSpeedTop10({ [positions], sortBy })`,
+    `skaterZoneTimeTop10({ [positions], [strength], sortBy })`,
+    `skaterShotSpeedTop10({ [positions], sortBy })`,
+    `skaterShotLocationTop10({ [positions], sortBy, [category] })`
+  - Goalies: `goalie5v5Top10({ sortBy })`,
+    `goalieShotLocationTop10({ sortBy, [category] })`,
+    `goalieSavePercentageTop10({ sortBy })`
+  - Teams: `teamSkatingDistanceTop10({ [positions], [strength], sortBy })`,
+    `teamSkatingSpeedTop10({ [positions], sortBy })`,
+    `teamZoneTimeTop10({ [strength], sortBy })`,
+    `teamShotSpeedTop10({ [positions], sortBy })`,
+    `teamShotLocationTop10({ [positions], sortBy, [category] })`
+  - Zone-time `sortBy` is the zone (`EdgeZones`: `'offensive'`, `'neutral'`,
+    `'defensive'`); the other `sortBy` values are typed per method (e.g.
+    `EdgeSkatingDistanceSortBy`: `'total'`, `'per-60'`, `'max-game'`,
+    `'max-period'`)
 
 ### players
 
 - `prospectsByTeam({ teamAbbr })`
-- `playersByTeam({ teamAbbr, season })`
+- `playersByTeam({ teamAbbr, [season] })`
+- `playerSpotlight()`
+- `playerSearch({ [name], [teamId], [position], [cayenneExp], [sort], [dir], [start], [include], [exclude] })` — search every player on record, e.g. `{ name: 'matth', position: 'C' }`. `name` is a case-insensitive part of the full name; `position: 'F'` matches every forward; at least one filter is required. Returns `{ data, total }`; the API sends **at most 5 rows** per request, so page with `start`
+
+### draft
+
+Draft years are **YYYY** (`2023`), not `YYYYYYYY`. Without `season` the
+current draft (`/now`) is used.
+
+- `rankings({ [season], [category] })` — Central Scouting rankings.
+  `category` is a `ProspectCategory` (1 NA skater, the default; 2 Intl skater;
+  3 NA goalie; 4 Intl goalie)
+- `tracker()` — the live draft tracker for the current draft
+- `picks({ [season], [round] })` — picks for round `1`-`7` or `'all'` (the
+  default). `picks()` without a season returns round **1** of the current
+  draft, since the API redirects `draft/picks/now` there
+
+Rounds per draft year live in `misc.draftYearAndRounds()`.
 
 ### misc
 
 - `glossary()`, `config()`, `countries()`, `seasonSpecificRulesAndInfo()`,
   `draftYearAndRounds()`
+- `componentSeasons()` — the season and game type the stats API serves by default
+- `games({ [season], [gameType], [teamId], [startDate], [endDate], [cayenneExp] })` — stats API games, e.g. `{ season: 20232024, teamId: 10 }`. At least one filter is required (unfiltered is every game ever, about 19 MB)
+- `ping()` — stats API health check; resolves `true`, and throws on any failure (it never returns `false`)
+- `seasonIds()` — every season id (`19171918` ... current)
+- `tvSchedule({ [date] })` — national TV broadcasts for the week around a date
+- `meta({ [players], [teams] })` — display metadata (names, slugs, headshots) for player ids and team abbreviations
+- `partnerGameOdds({ countryCode })` — today's betting odds (experimental)
+- `location()` — the caller's country from their IP (experimental)
+- `postalLookup({ postalCode })` — teams whose broadcast market covers a postal code (experimental)
 
 ### helpers
 
@@ -290,21 +357,26 @@ nhl-api-ts teams teams --compact | jq -r '.[].abbr'
 
 ## Development
 
+This package lives in a pnpm workspace. Run these from the
+[repository root](https://github.com/andrewangelle/nhl-api-ts):
+
 ```bash
 pnpm install
 pnpm test         # node:test, runs the TypeScript sources directly
 pnpm typecheck
 pnpm lint:check
-pnpm build        # emits dist/
+pnpm build        # emits packages/nhl-api-ts/dist/
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full set of checks, and
-[AGENTS.md](AGENTS.md) for repository conventions.
+See [CONTRIBUTING.md](https://github.com/andrewangelle/nhl-api-ts/blob/main/CONTRIBUTING.md)
+for the full set of checks, and
+[AGENTS.md](https://github.com/andrewangelle/nhl-api-ts/blob/main/AGENTS.md) for
+repository conventions.
 
 Try the CLI from source:
 
 ```bash
-node --conditions=source src/cli.mts --help
+node --conditions=source packages/nhl-api-ts/src/cli.mts --help
 ```
 
 ## Credits

package/dist/api/draft.d.mts

@@ -0,0 +1,61 @@
+import type { Context } from '#src/context.mjs';
+import type { DraftPicks, DraftRankings, DraftTracker } from '#src/types/index.mjs';
+import type { Id } from '#src/utils.mjs';
+/** Prospect list of the NHL Central Scouting draft rankings. */
+export declare const ProspectCategory: {
+    readonly NORTH_AMERICAN_SKATER: 1;
+    readonly INTERNATIONAL_SKATER: 2;
+    readonly NORTH_AMERICAN_GOALIE: 3;
+    readonly INTERNATIONAL_GOALIE: 4;
+};
+export type ProspectCategory = (typeof ProspectCategory)[keyof typeof ProspectCategory];
+/** Draft round 1-7, or 'all' for every round. */
+export type DraftRound = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 'all';
+export interface DraftRankingsParams {
+    /** Draft year in YYYY format, e.g. 2023. Defaults to the current draft ("now"). */
+    season?: Id;
+    /** 1=NA skater (default), 2=Intl skater, 3=NA goalie, 4=Intl goalie. Ignored when `season` is omitted. */
+    category?: ProspectCategory;
+}
+export interface DraftPicksParams {
+    /** Draft year in YYYY format, e.g. 2023. Defaults to the current draft ("now"). */
+    season?: Id;
+    /** Round 1-7 or 'all' (default). Ignored when `season` is omitted. */
+    round?: DraftRound;
+}
+/**
+ * Gets the NHL Central Scouting rankings for one prospect category. The API
+ * has no season-only route, so `category` defaults to 1 when `season` is
+ * given; without `season` the current draft's North American skaters come
+ * back and `category` is ignored.
+ *
+ * @param params.season Draft year in YYYY format (not YYYYYYYY), e.g. 2023. Defaults to "now".
+ * @param params.category 1=NA skater, 2=Intl skater, 3=NA goalie, 4=Intl goalie. See `ProspectCategory`.
+ * @throws RangeError If `category` is not 1-4
+ * @example https://api-web.nhle.com/v1/draft/rankings/2023/1
+ */
+export declare function rankings(ctx: Context, { season, category, }?: DraftRankingsParams): Promise<DraftRankings>;
+/**
+ * Gets the live draft tracker: the current draft's broadcast info, state
+ * and the picks of the round in progress (or the last round, once the draft
+ * is over).
+ *
+ * @example https://api-web.nhle.com/v1/draft-tracker/picks/now
+ */
+export declare function tracker(ctx: Context): Promise<DraftTracker>;
+/**
+ * Gets the picks of a draft. Note the defaults differ: `picks()` hits
+ * `draft/picks/now`, which the API redirects to round **1** of the current
+ * draft, while `picks({ season })` returns every round.
+ *
+ * @param params.season Draft year in YYYY format (not YYYYYYYY), e.g. 2023. Defaults to "now".
+ * @param params.round Round 1-7 or 'all'. Defaults to 'all' when `season` is given.
+ * @throws RangeError If `round` is not 1-7 or 'all'
+ * @example https://api-web.nhle.com/v1/draft/picks/2023/all
+ */
+export declare function picks(ctx: Context, { season, round }?: DraftPicksParams): Promise<DraftPicks>;
+export declare const draftApi: {
+    readonly rankings: typeof rankings;
+    readonly tracker: typeof tracker;
+    readonly picks: typeof picks;
+};

package/dist/api/draft.mjs

@@ -0,0 +1,68 @@
+import { Endpoint } from '#src/http-client.mjs';
+/** Prospect list of the NHL Central Scouting draft rankings. */
+export const ProspectCategory = {
+    NORTH_AMERICAN_SKATER: 1,
+    INTERNATIONAL_SKATER: 2,
+    NORTH_AMERICAN_GOALIE: 3,
+    INTERNATIONAL_GOALIE: 4,
+};
+function inRange(value, min, max) {
+    return (Number.isInteger(value) && Number(value) >= min && Number(value) <= max);
+}
+async function getWeb(ctx, resource) {
+    return (await ctx.get(Endpoint.API_WEB_V1, resource)).json();
+}
+/**
+ * Gets the NHL Central Scouting rankings for one prospect category. The API
+ * has no season-only route, so `category` defaults to 1 when `season` is
+ * given; without `season` the current draft's North American skaters come
+ * back and `category` is ignored.
+ *
+ * @param params.season Draft year in YYYY format (not YYYYYYYY), e.g. 2023. Defaults to "now".
+ * @param params.category 1=NA skater, 2=Intl skater, 3=NA goalie, 4=Intl goalie. See `ProspectCategory`.
+ * @throws RangeError If `category` is not 1-4
+ * @example https://api-web.nhle.com/v1/draft/rankings/2023/1
+ */
+export async function rankings(ctx, { season, category = ProspectCategory.NORTH_AMERICAN_SKATER, } = {}) {
+    if (!inRange(category, 1, 4)) {
+        throw new RangeError(`Invalid prospect category ${category}. Use 1-4 (see ProspectCategory).`);
+    }
+    if (season === undefined || season === null) {
+        return getWeb(ctx, 'draft/rankings/now');
+    }
+    return getWeb(ctx, `draft/rankings/${season}/${category}`);
+}
+/**
+ * Gets the live draft tracker: the current draft's broadcast info, state
+ * and the picks of the round in progress (or the last round, once the draft
+ * is over).
+ *
+ * @example https://api-web.nhle.com/v1/draft-tracker/picks/now
+ */
+export async function tracker(ctx) {
+    return getWeb(ctx, 'draft-tracker/picks/now');
+}
+/**
+ * Gets the picks of a draft. Note the defaults differ: `picks()` hits
+ * `draft/picks/now`, which the API redirects to round **1** of the current
+ * draft, while `picks({ season })` returns every round.
+ *
+ * @param params.season Draft year in YYYY format (not YYYYYYYY), e.g. 2023. Defaults to "now".
+ * @param params.round Round 1-7 or 'all'. Defaults to 'all' when `season` is given.
+ * @throws RangeError If `round` is not 1-7 or 'all'
+ * @example https://api-web.nhle.com/v1/draft/picks/2023/all
+ */
+export async function picks(ctx, { season, round = 'all' } = {}) {
+    if (round !== 'all' && !inRange(round, 1, 7)) {
+        throw new RangeError(`Invalid draft round ${round}. Use 1-7 or 'all'.`);
+    }
+    if (season === undefined || season === null) {
+        return getWeb(ctx, 'draft/picks/now');
+    }
+    return getWeb(ctx, `draft/picks/${season}/${round}`);
+}
+export const draftApi = {
+    rankings,
+    tracker,
+    picks,
+};