nhl-api-ts 0.2.1 → 0.3.0

package/dist/api/stats.mjs

@@ -1,7 +1,17 @@
 import { DEFAULT_FACT_QUERY, } from '#src/api/query/builder.mjs';
 import { goalieStatsSorts } from '#src/api/query/sorting/goalie-sorts.mjs';
-import { defaultSortForReport, } from '#src/api/query/sorting/sorting-options.mjs';
+import { defaultSortForReport, defaultSortForSkaterStatsSummary, defaultSortForTeamSummary, } from '#src/api/query/sorting/sorting-options.mjs';
 import { Endpoint } from '#src/http-client.mjs';
+/**
+ * "<season>/<gameType>", or the API's current-season segment when no season is
+ * given. Most endpoints take `now`; the stats-leaders ones only take `current`.
+ */
+function seasonGameTypeSegments(season, gameType, current) {
+    if (season === undefined || season === null) {
+        return current;
+    }
+    return `${season}/${gameType}`;
+}
 /** Skater reports whose rows have no `gamesPlayed`, so the API rejects the default fact filter. */
 const REPORTS_WITHOUT_GAMES_PLAYED = [
     'shootout',
@@ -26,37 +36,72 @@ export async function playerCareerStats(ctx, { playerId }) {
     return (await ctx.get(Endpoint.API_WEB_V1, `player/${playerId}/landing`)).json();
 }
 /**
- * Gets a player's game log for a specific season and game type.
+ * Gets a player's game log for a season and game type.
  *
  * @param params.playerId NHL player id, e.g. 8481528
- * @param params.seasonId Season in YYYYYYYY format, e.g. 20232024
- * @param params.gameType 1=Preseason, 2=Regular season, 3=Playoffs
+ * @param params.seasonId Season in YYYYYYYY format, e.g. 20232024. Defaults to the current season ("now").
+ * @param params.gameType 1=Preseason, 2=Regular season (default), 3=Playoffs. Ignored when `seasonId` is omitted.
  * @example https://api-web.nhle.com/v1/player/8481528/game-log/20232024/2
  */
-export async function playerGameLog(ctx, { playerId, seasonId, gameType, }) {
-    const data = await (await ctx.get(Endpoint.API_WEB_V1, `player/${playerId}/game-log/${seasonId}/${gameType}`)).json();
+export async function playerGameLog(ctx, { playerId, seasonId, gameType = 2, }) {
+    const data = await (await ctx.get(Endpoint.API_WEB_V1, `player/${playerId}/game-log/${seasonGameTypeSegments(seasonId, gameType, 'now')}`)).json();
     return data.gameLog ?? [];
 }
+function statsLeadersQuery({ categories, limit, }) {
+    const query = {};
+    if (categories && categories.length > 0) {
+        query.categories = categories.join(',');
+    }
+    if (limit !== undefined) {
+        query.limit = limit;
+    }
+    return query;
+}
+/**
+ * Gets the skater stats leaders for a season, keyed by category.
+ *
+ * @param params.season Season in YYYYYYYY format. Defaults to the current season.
+ * @param params.gameType 2=Regular season (default), 3=Playoffs. Ignored when `season` is omitted.
+ * @param params.categories Categories to include, e.g. ['goals', 'points']. Defaults to all.
+ * @param params.limit Rows per category. The API defaults to 5; -1 returns every player.
+ * @example https://api-web.nhle.com/v1/skater-stats-leaders/20232024/2?categories=goals,points&limit=10
+ */
+export async function skaterStatsLeaders(ctx, params = {}) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `skater-stats-leaders/${seasonGameTypeSegments(params.season, params.gameType ?? 2, 'current')}`, statsLeadersQuery(params))).json();
+}
+/**
+ * Gets the goalie stats leaders for a season, keyed by category.
+ *
+ * @param params.season Season in YYYYYYYY format. Defaults to the current season.
+ * @param params.gameType 2=Regular season (default), 3=Playoffs. Ignored when `season` is omitted.
+ * @param params.categories Categories to include, e.g. ['wins', 'savePctg']. Defaults to all.
+ * @param params.limit Rows per category. The API defaults to 5; -1 returns every goalie.
+ * @example https://api-web.nhle.com/v1/goalie-stats-leaders/20232024/2?categories=wins&limit=10
+ */
+export async function goalieStatsLeaders(ctx, params = {}) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `goalie-stats-leaders/${seasonGameTypeSegments(params.season, params.gameType ?? 2, 'current')}`, statsLeadersQuery(params))).json();
+}
+/**
+ * Gets a team's skater and goalie stats for a season and game type.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024. Defaults to the current season ("now").
+ * @param params.gameType 2=Regular season (default), 3=Playoffs. Ignored when `season` is omitted.
+ * @example https://api-web.nhle.com/v1/club-stats/TOR/20232024/2
+ */
+export async function clubStats(ctx, { teamAbbr, season, gameType = 2, }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `club-stats/${teamAbbr}/${seasonGameTypeSegments(season, gameType, 'now')}`)).json();
+}
 /**
  * Retrieves team summary statistics across one or more seasons.
  *
  * @example await client.stats.teamSummary({ startSeason: '20232024', endSeason: '20232024' })
  */
 export async function teamSummary(ctx, { startSeason, endSeason, gameTypeId = 2, isGame = false, isAggregate = false, sortExpr, start = 0, limit = 50, factCayenneExp = 'gamesPlayed>1', defaultCayenneExp, }) {
-    const effectiveSortExpr = sortExpr && sortExpr.length > 0
-        ? sortExpr
-        : [
-            { property: 'points', direction: 'DESC' },
-            { property: 'wins', direction: 'DESC' },
-            // aggregated rows span seasons, so they have no teamId
-            {
-                property: isAggregate ? 'franchiseId' : 'teamId',
-                direction: 'ASC',
-            },
-        ];
+    const effectiveSortExpr = defaultSortForTeamSummary(sortExpr, isAggregate);
     const effectiveCayenneExp = defaultCayenneExp ??
         `gameTypeId=${gameTypeId} and seasonId<=${endSeason} and seasonId>=${startSeason}`;
-    const qParams = {
+    const queryParams = {
         isAggregate,
         isGame,
         start,
@@ -65,7 +110,7 @@ export async function teamSummary(ctx, { startSeason, endSeason, gameTypeId = 2,
         sort: JSON.stringify(effectiveSortExpr),
         cayenneExp: effectiveCayenneExp,
     };
-    const response = await (await ctx.get(Endpoint.API_STATS, 'en/team/summary', qParams)).json();
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/team/summary', queryParams)).json();
     return response.data;
 }
 /**
@@ -75,19 +120,13 @@ export async function teamSummary(ctx, { startSeason, endSeason, gameTypeId = 2,
  * @example await client.stats.skaterStatsSummary({ startSeason: '20232024', endSeason: '20232024', franchiseId: 10 })
  */
 export async function skaterStatsSummary(ctx, { startSeason, endSeason, franchiseId, gameTypeId = 2, aggregate = false, sortExpr, start = 0, limit = 25, factCayenneExp = 'gamesPlayed>=1', defaultCayenneExp, }) {
-    const effectiveSortExpr = sortExpr && sortExpr.length > 0
-        ? sortExpr
-        : [
-            { property: 'points', direction: 'DESC' },
-            { property: 'gamesPlayed', direction: 'ASC' },
-            { property: 'playerId', direction: 'ASC' },
-        ];
+    const effectiveSortExpr = defaultSortForSkaterStatsSummary(sortExpr);
     const baseCayenneExp = defaultCayenneExp ??
         `gameTypeId=${gameTypeId} and seasonId<=${endSeason} and seasonId>=${startSeason}`;
     const effectiveCayenneExp = !defaultCayenneExp && franchiseId
         ? `franchiseId=${franchiseId} and ${baseCayenneExp}`
         : baseCayenneExp;
-    const qParams = {
+    const queryParams = {
         isAggregate: aggregate,
         isGame: false,
         start,
@@ -96,7 +135,7 @@ export async function skaterStatsSummary(ctx, { startSeason, endSeason, franchis
         sort: JSON.stringify(effectiveSortExpr),
         cayenneExp: effectiveCayenneExp,
     };
-    const response = await (await ctx.get(Endpoint.API_STATS, 'en/skater/summary', qParams)).json();
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/skater/summary', queryParams)).json();
     return response.data;
 }
 /**
@@ -147,7 +186,7 @@ export async function goalieStatsSummary(ctx, { startSeason, endSeason, statsTyp
     const effectiveCayenneExp = franchiseId
         ? `franchiseId=${franchiseId} and ${baseCayenneExp}`
         : baseCayenneExp;
-    const qParams = {
+    const queryParams = {
         isAggregate: aggregate,
         isGame: false,
         start,
@@ -156,15 +195,76 @@ export async function goalieStatsSummary(ctx, { startSeason, endSeason, statsTyp
         sort: JSON.stringify(effectiveSortExpr),
         cayenneExp: effectiveCayenneExp,
     };
-    const response = await (await ctx.get(Endpoint.API_STATS, `en/goalie/${report}`, qParams)).json();
+    const response = await (await ctx.get(Endpoint.API_STATS, `en/goalie/${report}`, queryParams)).json();
+    return response.data ?? [];
+}
+async function getStatsData(ctx, resource, queryParams) {
+    const response = await (await ctx.get(Endpoint.API_STATS, resource, queryParams)).json();
     return response.data ?? [];
 }
+/**
+ * The leaders endpoints only filter on `season` (`seasonId`, `gameTypeId` and
+ * the other report columns are a 400), so the SDK builds the filter itself.
+ */
+function getStatsLeaders(ctx, group, { attribute, season }) {
+    return getStatsData(ctx, `en/leaders/${group}/${attribute}`, season === undefined || season === null
+        ? undefined
+        : { cayenneExp: `season=${season}` });
+}
+/**
+ * Gets the top 10 single-season skater records for an attribute, e.g.
+ * Gretzky's 215 points, or the top 10 of one season.
+ *
+ * @param params.attribute points, goals, assists or gamesPlayed (case-sensitive)
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024. Defaults to every season.
+ * @example https://api.nhle.com/stats/rest/en/leaders/skaters/points?cayenneExp=season=20232024
+ */
+export async function skaterLeaders(ctx, params) {
+    return getStatsLeaders(ctx, 'skaters', params);
+}
+/**
+ * Gets the top 10 single-season goalie records for an attribute, or the top
+ * 10 of one season. There is no minimum games played, so `gaa` / `savePctg`
+ * leaders are goalies with a few minutes.
+ *
+ * @param params.attribute gaa, savePctg, shutouts, timeOnIce or gamesPlayed (case-sensitive)
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024. Defaults to every season.
+ * @example https://api.nhle.com/stats/rest/en/leaders/goalies/gaa?cayenneExp=season=20232024
+ */
+export async function goalieLeaders(ctx, params) {
+    return getStatsLeaders(ctx, 'goalies', params);
+}
+/**
+ * Gets the career milestones active skaters are closing in on (e.g. 200
+ * assists, 50 playoff points).
+ *
+ * @example https://api.nhle.com/stats/rest/en/milestones/skaters
+ */
+export async function skaterMilestones(ctx) {
+    return getStatsData(ctx, 'en/milestones/skaters');
+}
+/**
+ * Gets the career milestones active goalies are closing in on (e.g. 30
+ * shutouts, 50 playoff games).
+ *
+ * @example https://api.nhle.com/stats/rest/en/milestones/goalies
+ */
+export async function goalieMilestones(ctx) {
+    return getStatsData(ctx, 'en/milestones/goalies');
+}
 export const statsApi = {
     gametypesPerSeasonDirectoryByTeam,
     playerCareerStats,
     playerGameLog,
+    skaterStatsLeaders,
+    goalieStatsLeaders,
+    clubStats,
     teamSummary,
     skaterStatsSummary,
     skaterStatsWithQueryContext,
     goalieStatsSummary,
+    skaterLeaders,
+    goalieLeaders,
+    skaterMilestones,
+    goalieMilestones,
 };

package/dist/api/teams.d.mts

@@ -1,5 +1,5 @@
 import type { Context } from '#src/context.mjs';
-import type { Franchise, Roster, StandingsEntry } from '#src/types/index.mjs';
+import type { Franchise, Roster, SeasonId, StandingsEntry, StatsTeam, TeamScoreboard } from '#src/types/index.mjs';
 import type { Id } from '#src/utils.mjs';
 export interface Team {
     conference: {
@@ -39,21 +39,61 @@ export declare function teams(ctx: Context, { date }?: {
  * Get the roster for the given team and season.
  *
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
- * @param params.season Season in YYYYYYYY format, e.g. 20232024
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024. Defaults to
+ *   the current season (`current`; this endpoint has no `now` alias).
  * @example https://api-web.nhle.com/v1/roster/BUF/20232024
  */
 export declare function teamRoster(ctx: Context, { teamAbbr, season }: {
     teamAbbr: string;
-    season: Id;
+    season?: Id;
 }): Promise<Roster>;
+/**
+ * Get every season a team has a roster for.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @example https://api-web.nhle.com/v1/roster-season/TOR
+ */
+export declare function rosterSeasons(ctx: Context, { teamAbbr }: {
+    teamAbbr: string;
+}): Promise<SeasonId[]>;
+/**
+ * Get a team's recent and upcoming games, grouped by date.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @example https://api-web.nhle.com/v1/scoreboard/TOR/now
+ */
+export declare function teamScoreboard(ctx: Context, { teamAbbr }: {
+    teamAbbr: string;
+}): Promise<TeamScoreboard>;
 /**
  * Get a list of all past and current NHL franchises.
  *
  * @example https://api.nhle.com/stats/rest/en/franchise
  */
 export declare function franchises(ctx: Context): Promise<Franchise[]>;
+/**
+ * Get every team in the stats API, past and present (62 rows), with its
+ * franchise id and tricode. Unlike `teams()`, this is the raw stats API row.
+ *
+ * @example https://api.nhle.com/stats/rest/en/team
+ */
+export declare function statsTeams(ctx: Context): Promise<StatsTeam[]>;
+/**
+ * Get one team from the stats API by its team id. An unknown id throws
+ * `ResourceNotFoundException`.
+ *
+ * @param params.teamId NHL team id, e.g. 10
+ * @example https://api.nhle.com/stats/rest/en/team/id/10
+ */
+export declare function teamById(ctx: Context, { teamId }: {
+    teamId: Id;
+}): Promise<StatsTeam>;
 export declare const teamsApi: {
     readonly teams: typeof teams;
     readonly teamRoster: typeof teamRoster;
+    readonly rosterSeasons: typeof rosterSeasons;
+    readonly teamScoreboard: typeof teamScoreboard;
     readonly franchises: typeof franchises;
+    readonly statsTeams: typeof statsTeams;
+    readonly teamById: typeof teamById;
 };

package/dist/api/teams.mjs

@@ -77,11 +77,30 @@ export async function teams(ctx, { date = 'now' } = {}) {
  * Get the roster for the given team and season.
  *
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
- * @param params.season Season in YYYYYYYY format, e.g. 20232024
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024. Defaults to
+ *   the current season (`current`; this endpoint has no `now` alias).
  * @example https://api-web.nhle.com/v1/roster/BUF/20232024
  */
 export async function teamRoster(ctx, { teamAbbr, season }) {
-    return (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season}`)).json();
+    return (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season ?? 'current'}`)).json();
+}
+/**
+ * Get every season a team has a roster for.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @example https://api-web.nhle.com/v1/roster-season/TOR
+ */
+export async function rosterSeasons(ctx, { teamAbbr }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `roster-season/${teamAbbr}`)).json();
+}
+/**
+ * Get a team's recent and upcoming games, grouped by date.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @example https://api-web.nhle.com/v1/scoreboard/TOR/now
+ */
+export async function teamScoreboard(ctx, { teamAbbr }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `scoreboard/${teamAbbr}/now`)).json();
 }
 /**
  * Get a list of all past and current NHL franchises.
@@ -92,4 +111,33 @@ export async function franchises(ctx) {
     const response = await (await ctx.get(Endpoint.API_STATS, 'en/franchise')).json();
     return response.data ?? [];
 }
-export const teamsApi = { teams, teamRoster, franchises };
+/**
+ * Get every team in the stats API, past and present (62 rows), with its
+ * franchise id and tricode. Unlike `teams()`, this is the raw stats API row.
+ *
+ * @example https://api.nhle.com/stats/rest/en/team
+ */
+export async function statsTeams(ctx) {
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/team')).json();
+    return response.data ?? [];
+}
+/**
+ * Get one team from the stats API by its team id. An unknown id throws
+ * `ResourceNotFoundException`.
+ *
+ * @param params.teamId NHL team id, e.g. 10
+ * @example https://api.nhle.com/stats/rest/en/team/id/10
+ */
+export async function teamById(ctx, { teamId }) {
+    const response = await (await ctx.get(Endpoint.API_STATS, `en/team/id/${teamId}`)).json();
+    return response.data[0];
+}
+export const teamsApi = {
+    teams,
+    teamRoster,
+    rosterSeasons,
+    teamScoreboard,
+    franchises,
+    statsTeams,
+    teamById,
+};