nhl-api-ts 0.2.0 → 0.3.0

package/dist/api/game-center.mjs

@@ -9,7 +9,9 @@ async function getWeb(ctx, resource) {
  * @param params.gameId Game id, e.g. 2023020280
  * @example https://api-web.nhle.com/v1/gamecenter/2023020280/boxscore
  */
-export const boxscore = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${gameId}/boxscore`);
+export async function boxscore(ctx, { gameId }) {
+    return getWeb(ctx, `gamecenter/${gameId}/boxscore`);
+}
 /**
  * Get the full play-by-play feed for a specific NHL game, containing every
  * recorded event (shots, hits, faceoffs, goals, penalties...).
@@ -17,7 +19,9 @@ export const boxscore = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${gam
  * @param params.gameId Game id, e.g. 2023020280
  * @example https://api-web.nhle.com/v1/gamecenter/2023020280/play-by-play
  */
-export const playByPlay = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${gameId}/play-by-play`);
+export async function playByPlay(ctx, { gameId }) {
+    return getWeb(ctx, `gamecenter/${gameId}/play-by-play`);
+}
 /**
  * Get the landing-page summary for a specific NHL game, including scoring by
  * period, three stars and penalties.
@@ -25,7 +29,9 @@ export const playByPlay = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${g
  * @param params.gameId Game id, e.g. 2023020280
  * @example https://api-web.nhle.com/v1/gamecenter/2023020280/landing
  */
-export const matchUp = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${gameId}/landing`);
+export async function matchUp(ctx, { gameId }) {
+    return getWeb(ctx, `gamecenter/${gameId}/landing`);
+}
 /**
  * Get scores and game states for all NHL games on a given date. Returns the
  * current day's scores when no date is supplied.
@@ -33,7 +39,9 @@ export const matchUp = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${game
  * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/score/2023-10-15
  */
-export const dailyScores = async (ctx, { date } = {}) => getWeb(ctx, `score/${date ? date : 'now'}`);
+export async function dailyScores(ctx, { date } = {}) {
+    return getWeb(ctx, `score/${date ? date : 'now'}`);
+}
 /**
  * Get individual player shift data for a specific game, including start/end
  * times and durations.
@@ -42,11 +50,11 @@ export const dailyScores = async (ctx, { date } = {}) => getWeb(ctx, `score/${da
  * @param params.excludes Fields to exclude from the response. Defaults to ["eventDetails"].
  * @example https://api.nhle.com/stats/rest/en/shiftcharts?cayenneExp=gameId=2023020280 and ...
  */
-export const shiftChartData = async (ctx, { gameId, excludes = ['eventDetails'] }) => {
+export async function shiftChartData(ctx, { gameId, excludes = ['eventDetails'] }) {
     const excludeP = excludes.join(',');
     const exprP = `gameId=${gameId} and ((duration != '00:00' and typeCode = 517) or typeCode != 517 )`;
     return (await ctx.get(Endpoint.API_STATS, `en/shiftcharts?cayenneExp=${exprP}&exclude=${excludeP}`)).json();
-};
+}
 /**
  * Get the season-series record and contextual stats for a specific game,
  * including team season stats and last games.
@@ -54,7 +62,9 @@ export const shiftChartData = async (ctx, { gameId, excludes = ['eventDetails']
  * @param params.gameId Game id, e.g. 2023020280
  * @example https://api-web.nhle.com/v1/gamecenter/2023020280/right-rail
  */
-export const seasonSeriesMatchup = async (ctx, { gameId }) => getWeb(ctx, `gamecenter/${gameId}/right-rail`);
+export async function seasonSeriesMatchup(ctx, { gameId }) {
+    return getWeb(ctx, `gamecenter/${gameId}/right-rail`);
+}
 /**
  * Get the narrative game story for a specific game, including scoring
  * summaries, three stars and team game stats.
@@ -62,7 +72,52 @@ export const seasonSeriesMatchup = async (ctx, { gameId }) => getWeb(ctx, `gamec
  * @param params.gameId Game id, e.g. 2023020280
  * @example https://api-web.nhle.com/v1/wsc/game-story/2023020280
  */
-export const gameStory = async (ctx, { gameId }) => getWeb(ctx, `wsc/game-story/${gameId}`);
+export async function gameStory(ctx, { gameId }) {
+    return getWeb(ctx, `wsc/game-story/${gameId}`);
+}
+/**
+ * Get the league scoreboard: every game in the week around a date, grouped by
+ * date. Returns the week around today when no date is supplied.
+ *
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
+ * @example https://api-web.nhle.com/v1/scoreboard/2023-10-15
+ */
+export async function scoreboard(ctx, { date } = {}) {
+    return getWeb(ctx, `scoreboard/${date ?? 'now'}`);
+}
+/**
+ * Get the play-by-play feed nhl.com's game story widget uses. A bare array of
+ * plays, with a different play shape from `playByPlay`.
+ *
+ * @param params.gameId Game id, e.g. 2023020280
+ * @example https://api-web.nhle.com/v1/wsc/play-by-play/2023020280
+ */
+export async function wscPlayByPlay(ctx, { gameId }) {
+    return getWeb(ctx, `wsc/play-by-play/${gameId}`);
+}
+/**
+ * Get the replay card for one play-by-play event: the game header, plus a
+ * `goal` object (scorer, assists, highlight clip and the `pptReplayUrl`
+ * puck-and-player-tracking link) when the event is a goal. Any event id works.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @param params.gameId Game id, e.g. 2023020280
+ * @param params.eventNumber The play's `eventId` from `playByPlay`, e.g. 193
+ * @example https://api-web.nhle.com/v1/ppt-replay/2023020280/193
+ */
+export async function playReplay(ctx, { gameId, eventNumber }) {
+    return getWeb(ctx, `ppt-replay/${gameId}/${eventNumber}`);
+}
+/**
+ * Get the metadata nhl.com uses to render a game page: the two teams, the
+ * season state and the game state.
+ *
+ * @param params.gameId Game id, e.g. 2023020280
+ * @example https://api-web.nhle.com/v1/meta/game/2023020280
+ */
+export async function gameMeta(ctx, { gameId }) {
+    return getWeb(ctx, `meta/game/${gameId}`);
+}
 export const gameCenterApi = {
     boxscore,
     playByPlay,
@@ -71,4 +126,8 @@ export const gameCenterApi = {
     shiftChartData,
     seasonSeriesMatchup,
     gameStory,
+    scoreboard,
+    wscPlayByPlay,
+    playReplay,
+    gameMeta,
 };

package/dist/api/helpers.d.mts

@@ -10,11 +10,11 @@ import type { Id } from '#src/utils.mjs';
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.gameIdsBySeason({ season: '20232024', gameTypes: [2] })
  */
-export declare const gameIdsBySeason: (ctx: Context, { season, gameTypes, apiSleepRate, }: {
+export declare function gameIdsBySeason(ctx: Context, { season, gameTypes, apiSleepRate, }: {
     season: Id;
     gameTypes?: number[];
     apiSleepRate?: number;
-}) => Promise<number[]>;
+}): Promise<number[]>;
 /**
  * Gets every rostered player across all NHL teams for a given season. Each
  * player gets a `team` abbreviation and flattened `firstName` / `lastName`.
@@ -23,10 +23,10 @@ export declare const gameIdsBySeason: (ctx: Context, { season, gameTypes, apiSle
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 0.5.
  * @example await client.helpers.allPlayers({ season: '20232024' })
  */
-export declare const allPlayers: (ctx: Context, { season, apiSleepRate }: {
+export declare function allPlayers(ctx: Context, { season, apiSleepRate }: {
     season: Id;
     apiSleepRate?: number;
-}) => Promise<AllPlayersEntry[]>;
+}): Promise<AllPlayersEntry[]>;
 /**
  * Gets summary statistics for every skater in a given season, merged with
  * the roster info from `allPlayers` (stat fields win on key collisions).
@@ -36,10 +36,10 @@ export declare const allPlayers: (ctx: Context, { season, apiSleepRate }: {
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.allPlayersSummaryStatistics({ season: '20232024' })
  */
-export declare const allPlayersSummaryStatistics: (ctx: Context, { season, apiSleepRate }: {
+export declare function allPlayersSummaryStatistics(ctx: Context, { season, apiSleepRate }: {
     season: Id;
     apiSleepRate?: number;
-}) => Promise<PlayerSummaryStatistics[]>;
+}): Promise<PlayerSummaryStatistics[]>;
 export declare const helpersApi: {
     readonly gameIdsBySeason: typeof gameIdsBySeason;
     readonly allPlayers: typeof allPlayers;

package/dist/api/helpers.mjs

@@ -12,7 +12,7 @@ import { teams as fetchTeams, teamRoster } from '#src/api/teams.mjs';
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.gameIdsBySeason({ season: '20232024', gameTypes: [2] })
  */
-export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1, }) => {
+export async function gameIdsBySeason(ctx, { season, gameTypes, apiSleepRate = 1, }) {
     const teams = await fetchTeams(ctx);
     const gameIds = [];
     for (const team of teams) {
@@ -33,7 +33,7 @@ export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1
         }
     }
     return gameIds;
-};
+}
 /**
  * Gets every rostered player across all NHL teams for a given season. Each
  * player gets a `team` abbreviation and flattened `firstName` / `lastName`.
@@ -42,7 +42,7 @@ export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 0.5.
  * @example await client.helpers.allPlayers({ season: '20232024' })
  */
-export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
+export async function allPlayers(ctx, { season, apiSleepRate = 0.5 }) {
     const teams = await fetchTeams(ctx);
     console.error('Fetching all player base stats. This may take a while...');
     const outData = [];
@@ -63,7 +63,7 @@ export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
         }
     }
     return outData;
-};
+}
 /**
  * Gets summary statistics for every skater in a given season, merged with
  * the roster info from `allPlayers` (stat fields win on key collisions).
@@ -73,7 +73,7 @@ export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.allPlayersSummaryStatistics({ season: '20232024' })
  */
-export const allPlayersSummaryStatistics = async (ctx, { season, apiSleepRate = 1 }) => {
+export async function allPlayersSummaryStatistics(ctx, { season, apiSleepRate = 1 }) {
     console.error('WARNING: This method will take a while to run.  In the event of rate limiting, you may need to increase the api_sleep_rate.');
     const players = await allPlayers(ctx, { season, apiSleepRate });
     const teams = await fetchTeams(ctx);
@@ -98,7 +98,7 @@ export const allPlayersSummaryStatistics = async (ctx, { season, apiSleepRate =
             : undefined;
         return player ? { ...player, ...statEntry } : statEntry;
     });
-};
+}
 export const helpersApi = {
     gameIdsBySeason,
     allPlayers,

package/dist/api/misc.d.mts

@@ -1,40 +1,154 @@
 import type { Context } from '#src/context.mjs';
-import type { Country, DraftYear, GlossaryEntry, SeasonRules, StatsConfig } from '#src/types/index.mjs';
+import type { ComponentSeason, Country, DraftYear, GeoLocation, GlossaryEntry, Meta, PartnerGameOdds, PostalLookupTeam, SeasonId, SeasonRules, StatsConfig, StatsGame, TvSchedule } from '#src/types/index.mjs';
+import type { Id } from '#src/utils.mjs';
 /**
  * Gets the full NHL glossary of statistical terms and abbreviations.
  *
  * @example https://api.nhle.com/stats/rest/en/glossary?sort=fullName
  */
-export declare const glossary: (ctx: Context) => Promise<GlossaryEntry[]>;
+export declare function glossary(ctx: Context): Promise<GlossaryEntry[]>;
 /**
  * Gets the stats API configuration, including available report types and
  * filters.
  *
  * @example https://api.nhle.com/stats/rest/en/config
  */
-export declare const config: (ctx: Context) => Promise<StatsConfig>;
+export declare function config(ctx: Context): Promise<StatsConfig>;
 /**
  * Gets the list of countries recognized by the NHL.
  *
  * @example https://api.nhle.com/stats/rest/en/country
  */
-export declare const countries: (ctx: Context) => Promise<Country[]>;
+export declare function countries(ctx: Context): Promise<Country[]>;
 /**
  * Gets rules and metadata for every NHL season on record.
  *
  * @example https://api.nhle.com/stats/rest/en/season
  */
-export declare const seasonSpecificRulesAndInfo: (ctx: Context) => Promise<SeasonRules[]>;
+export declare function seasonSpecificRulesAndInfo(ctx: Context): Promise<SeasonRules[]>;
 /**
  * Gets the number of rounds for each NHL draft year.
  *
  * @example https://api.nhle.com/stats/rest/en/draft
  */
-export declare const draftYearAndRounds: (ctx: Context) => Promise<DraftYear[]>;
+export declare function draftYearAndRounds(ctx: Context): Promise<DraftYear[]>;
+/**
+ * Gets the season and game type the stats API currently serves by default.
+ *
+ * @example https://api.nhle.com/stats/rest/en/componentSeason
+ */
+export declare function componentSeasons(ctx: Context): Promise<ComponentSeason[]>;
+export interface GamesParams {
+    /** Season in YYYYYYYY format, e.g. 20232024 (about 1,500 games). */
+    season?: Id;
+    /** 1=Preseason, 2=Regular season, 3=Playoffs. */
+    gameType?: number;
+    /** NHL team id, home or away, e.g. 10. */
+    teamId?: Id;
+    /** First game date, YYYY-MM-DD (inclusive). */
+    startDate?: string;
+    /** Last game date, YYYY-MM-DD (inclusive). */
+    endDate?: string;
+    /**
+     * Extra filter expression, joined to the others with `and`. Only the row
+     * fields (`season`, `gameType`, `gameDate`, `homeTeamId`, ...) can be
+     * filtered; report columns like `seasonId` are a 400.
+     */
+    cayenneExp?: string;
+}
+/**
+ * Gets games from the stats API. At least one filter is required:
+ * unfiltered, the API sends every game ever played (about 19 MB).
+ *
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024
+ * @param params.gameType 1=Preseason, 2=Regular season, 3=Playoffs
+ * @param params.teamId NHL team id, home or away, e.g. 10
+ * @param params.startDate First game date, YYYY-MM-DD
+ * @param params.endDate Last game date, YYYY-MM-DD
+ * @param params.cayenneExp Extra filter expression, e.g. "homeScore>=7"
+ * @throws RangeError When no filter is given, or a date is not YYYY-MM-DD
+ * @example await client.misc.games({ season: 20232024, teamId: 10, gameType: 3 })
+ */
+export declare function games(ctx: Context, params: GamesParams): Promise<StatsGame[]>;
+/**
+ * Gets the national TV schedule for the week around a date, grouped by date.
+ *
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
+ * @example https://api-web.nhle.com/v1/network/tv-schedule/2023-10-15
+ */
+export declare function tvSchedule(ctx: Context, { date }?: {
+    date?: string;
+}): Promise<TvSchedule>;
+/**
+ * Gets betting odds for today's games from the NHL's odds partner in a
+ * country.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @param params.countryCode Two-letter country code, e.g. US, CA
+ * @example https://api-web.nhle.com/v1/partner-game/US/now
+ */
+export declare function partnerGameOdds(ctx: Context, { countryCode }: {
+    countryCode: string;
+}): Promise<PartnerGameOdds>;
+/**
+ * Gets every NHL season id, oldest first.
+ *
+ * @example https://api-web.nhle.com/v1/season
+ */
+export declare function seasonIds(ctx: Context): Promise<SeasonId[]>;
+/**
+ * Gets display metadata (names, headshots, logos) for players and teams.
+ * Lists you leave out or pass empty come back empty.
+ *
+ * @param params.players Player ids, e.g. [8478402]
+ * @param params.teams Team abbreviations, e.g. ['TOR', 'BUF']
+ * @example https://api-web.nhle.com/v1/meta?players=8478402&teams=TOR,BUF
+ */
+export declare function meta(ctx: Context, { players, teams }?: {
+    players?: Id[];
+    teams?: string[];
+}): Promise<Meta>;
+/**
+ * Gets the caller's country, looked up from their IP address. The answer
+ * depends on where the request comes from.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @example https://api-web.nhle.com/v1/location
+ */
+export declare function location(ctx: Context): Promise<GeoLocation>;
+/**
+ * Gets the teams whose local broadcast market covers a postal code. Empty
+ * for codes outside every market.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @param params.postalCode Postal or ZIP code, e.g. 90210 or "M5V 3L9"
+ * @example https://api-web.nhle.com/v1/postal-lookup/90210
+ */
+export declare function postalLookup(ctx: Context, { postalCode }: {
+    postalCode: string;
+}): Promise<PostalLookupTeam[]>;
+/**
+ * Checks that the stats API is up. Resolves `true` on success; it never
+ * resolves `false`, since any failure throws an `NHLApiException` subclass
+ * (or a network error).
+ *
+ * @throws ServerErrorException When the stats API answers 5xx
+ * @example https://api.nhle.com/stats/rest/ping
+ */
+export declare function ping(ctx: Context): Promise<true>;
 export declare const miscApi: {
     readonly glossary: typeof glossary;
     readonly config: typeof config;
     readonly countries: typeof countries;
     readonly seasonSpecificRulesAndInfo: typeof seasonSpecificRulesAndInfo;
     readonly draftYearAndRounds: typeof draftYearAndRounds;
+    readonly componentSeasons: typeof componentSeasons;
+    readonly games: typeof games;
+    readonly tvSchedule: typeof tvSchedule;
+    readonly partnerGameOdds: typeof partnerGameOdds;
+    readonly seasonIds: typeof seasonIds;
+    readonly meta: typeof meta;
+    readonly location: typeof location;
+    readonly postalLookup: typeof postalLookup;
+    readonly ping: typeof ping;
 };

package/dist/api/misc.mjs

@@ -1,43 +1,198 @@
+import { andClauses, cayenneString } from '#src/api/query/cayenne.mjs';
+import { normalizeDate } from '#src/api/schedule.mjs';
 import { Endpoint } from '#src/http-client.mjs';
-async function getData(ctx, resource) {
-    const response = await (await ctx.get(Endpoint.API_CORE, resource)).json();
+async function getData(ctx, resource, queryParams) {
+    const response = await (await ctx.get(Endpoint.API_CORE, resource, queryParams)).json();
     return response.data ?? [];
 }
+async function getWeb(ctx, resource) {
+    return (await ctx.get(Endpoint.API_WEB_V1, resource)).json();
+}
 /**
  * Gets the full NHL glossary of statistical terms and abbreviations.
  *
  * @example https://api.nhle.com/stats/rest/en/glossary?sort=fullName
  */
-export const glossary = async (ctx) => getData(ctx, 'stats/rest/en/glossary?sort=fullName');
+export async function glossary(ctx) {
+    return getData(ctx, 'stats/rest/en/glossary?sort=fullName');
+}
 /**
  * Gets the stats API configuration, including available report types and
  * filters.
  *
  * @example https://api.nhle.com/stats/rest/en/config
  */
-export const config = async (ctx) => (await ctx.get(Endpoint.API_CORE, 'stats/rest/en/config')).json();
+export async function config(ctx) {
+    return (await ctx.get(Endpoint.API_CORE, 'stats/rest/en/config')).json();
+}
 /**
  * Gets the list of countries recognized by the NHL.
  *
  * @example https://api.nhle.com/stats/rest/en/country
  */
-export const countries = async (ctx) => getData(ctx, 'stats/rest/en/country');
+export async function countries(ctx) {
+    return getData(ctx, 'stats/rest/en/country');
+}
 /**
  * Gets rules and metadata for every NHL season on record.
  *
  * @example https://api.nhle.com/stats/rest/en/season
  */
-export const seasonSpecificRulesAndInfo = async (ctx) => getData(ctx, 'stats/rest/en/season');
+export async function seasonSpecificRulesAndInfo(ctx) {
+    return getData(ctx, 'stats/rest/en/season');
+}
 /**
  * Gets the number of rounds for each NHL draft year.
  *
  * @example https://api.nhle.com/stats/rest/en/draft
  */
-export const draftYearAndRounds = async (ctx) => getData(ctx, 'stats/rest/en/draft');
+export async function draftYearAndRounds(ctx) {
+    return getData(ctx, 'stats/rest/en/draft');
+}
+/**
+ * Gets the season and game type the stats API currently serves by default.
+ *
+ * @example https://api.nhle.com/stats/rest/en/componentSeason
+ */
+export async function componentSeasons(ctx) {
+    return getData(ctx, 'stats/rest/en/componentSeason');
+}
+function gamesClauses({ season, gameType, teamId, startDate, endDate, cayenneExp, }) {
+    const clauses = [];
+    if (season !== undefined && season !== null) {
+        clauses.push(`season=${season}`);
+    }
+    if (gameType !== undefined) {
+        clauses.push(`gameType=${gameType}`);
+    }
+    if (teamId !== undefined && teamId !== null) {
+        clauses.push(`homeTeamId=${teamId} or visitingTeamId=${teamId}`);
+    }
+    if (startDate !== undefined) {
+        clauses.push(`gameDate>=${cayenneString(normalizeDate(startDate))}`);
+    }
+    if (endDate !== undefined) {
+        clauses.push(`gameDate<=${cayenneString(normalizeDate(endDate))}`);
+    }
+    if (cayenneExp?.trim()) {
+        clauses.push(cayenneExp);
+    }
+    return clauses;
+}
+/**
+ * Gets games from the stats API. At least one filter is required:
+ * unfiltered, the API sends every game ever played (about 19 MB).
+ *
+ * @param params.season Season in YYYYYYYY format, e.g. 20232024
+ * @param params.gameType 1=Preseason, 2=Regular season, 3=Playoffs
+ * @param params.teamId NHL team id, home or away, e.g. 10
+ * @param params.startDate First game date, YYYY-MM-DD
+ * @param params.endDate Last game date, YYYY-MM-DD
+ * @param params.cayenneExp Extra filter expression, e.g. "homeScore>=7"
+ * @throws RangeError When no filter is given, or a date is not YYYY-MM-DD
+ * @example await client.misc.games({ season: 20232024, teamId: 10, gameType: 3 })
+ */
+export async function games(ctx, params) {
+    const clauses = gamesClauses(params);
+    if (clauses.length === 0) {
+        throw new RangeError('Missing filter. Pass season, gameType, teamId, a date or cayenneExp.');
+    }
+    return getData(ctx, 'stats/rest/en/game', {
+        cayenneExp: andClauses(clauses),
+    });
+}
+/**
+ * Gets the national TV schedule for the week around a date, grouped by date.
+ *
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
+ * @example https://api-web.nhle.com/v1/network/tv-schedule/2023-10-15
+ */
+export async function tvSchedule(ctx, { date } = {}) {
+    return getWeb(ctx, `network/tv-schedule/${date ?? 'now'}`);
+}
+/**
+ * Gets betting odds for today's games from the NHL's odds partner in a
+ * country.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @param params.countryCode Two-letter country code, e.g. US, CA
+ * @example https://api-web.nhle.com/v1/partner-game/US/now
+ */
+export async function partnerGameOdds(ctx, { countryCode }) {
+    return getWeb(ctx, `partner-game/${countryCode}/now`);
+}
+/**
+ * Gets every NHL season id, oldest first.
+ *
+ * @example https://api-web.nhle.com/v1/season
+ */
+export async function seasonIds(ctx) {
+    return getWeb(ctx, 'season');
+}
+/**
+ * Gets display metadata (names, headshots, logos) for players and teams.
+ * Lists you leave out or pass empty come back empty.
+ *
+ * @param params.players Player ids, e.g. [8478402]
+ * @param params.teams Team abbreviations, e.g. ['TOR', 'BUF']
+ * @example https://api-web.nhle.com/v1/meta?players=8478402&teams=TOR,BUF
+ */
+export async function meta(ctx, { players = [], teams = [] } = {}) {
+    const query = {};
+    if (players.length > 0) {
+        query.players = players.join(',');
+    }
+    if (teams.length > 0) {
+        query.teams = teams.join(',');
+    }
+    return (await ctx.get(Endpoint.API_WEB_V1, 'meta', query)).json();
+}
+/**
+ * Gets the caller's country, looked up from their IP address. The answer
+ * depends on where the request comes from.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @example https://api-web.nhle.com/v1/location
+ */
+export async function location(ctx) {
+    return getWeb(ctx, 'location');
+}
+/**
+ * Gets the teams whose local broadcast market covers a postal code. Empty
+ * for codes outside every market.
+ *
+ * @experimental Feeds an nhl.com widget; the shape may change without notice.
+ * @param params.postalCode Postal or ZIP code, e.g. 90210 or "M5V 3L9"
+ * @example https://api-web.nhle.com/v1/postal-lookup/90210
+ */
+export async function postalLookup(ctx, { postalCode }) {
+    return getWeb(ctx, `postal-lookup/${encodeURIComponent(postalCode)}`);
+}
+/**
+ * Checks that the stats API is up. Resolves `true` on success; it never
+ * resolves `false`, since any failure throws an `NHLApiException` subclass
+ * (or a network error).
+ *
+ * @throws ServerErrorException When the stats API answers 5xx
+ * @example https://api.nhle.com/stats/rest/ping
+ */
+export async function ping(ctx) {
+    await ctx.get(Endpoint.API_CORE, 'stats/rest/ping');
+    return true;
+}
 export const miscApi = {
     glossary,
     config,
     countries,
     seasonSpecificRulesAndInfo,
     draftYearAndRounds,
+    componentSeasons,
+    games,
+    tvSchedule,
+    partnerGameOdds,
+    seasonIds,
+    meta,
+    location,
+    postalLookup,
+    ping,
 };

package/dist/api/players.d.mts

@@ -1,5 +1,6 @@
+import { type PositionTypes } from '#src/api/query/filters.mjs';
 import type { Context } from '#src/context.mjs';
-import type { Prospects, Roster } from '#src/types/index.mjs';
+import type { PlayerSpotlight, Prospects, Roster, StatsApiPage, StatsPlayer } from '#src/types/index.mjs';
 import type { Id } from '#src/utils.mjs';
 /**
  * Gets prospects for a specific team, grouped by position.
@@ -7,22 +8,73 @@ import type { Id } from '#src/utils.mjs';
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
  * @example https://api-web.nhle.com/v1/prospects/BUF
  */
-export declare const prospectsByTeam: (ctx: Context, { teamAbbr }: {
+export declare function prospectsByTeam(ctx: Context, { teamAbbr }: {
     teamAbbr: string;
-}) => Promise<Prospects>;
+}): Promise<Prospects>;
 /**
  * Gets the roster for a given team and season, grouped by position
  * (forwards, defensemen, goalies). Same data as `teams.teamRoster`.
  *
  * @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 const playersByTeam: (ctx: Context, { teamAbbr, season }: {
+export declare function playersByTeam(ctx: Context, { teamAbbr, season }: {
     teamAbbr: string;
-    season: Id;
-}) => Promise<Roster>;
+    season?: Id;
+}): Promise<Roster>;
+/**
+ * Gets the players featured in the nhl.com player spotlight.
+ *
+ * @example https://api-web.nhle.com/v1/player-spotlight
+ */
+export declare function playerSpotlight(ctx: Context): Promise<PlayerSpotlight[]>;
+export interface PlayerSearchParams {
+    /** Case-insensitive part of the full name, e.g. "matth" or "Ryan O'Reilly". */
+    name?: string;
+    /** NHL team id of the player's current team, e.g. 10. */
+    teamId?: Id;
+    /** Position. `F` matches every forward (C, L, R). */
+    position?: PositionTypes | 'G';
+    /**
+     * Extra filter expression, joined to the others with `and`. Only the row
+     * fields (`id`, `firstName`, `lastName`, `fullName`, `currentTeamId`,
+     * `positionCode`, `sweaterNumber`) can be filtered; anything else is a 400.
+     */
+    cayenneExp?: string;
+    /** Field to sort by, e.g. "lastName". */
+    sort?: string;
+    /** Sort direction for `sort`. */
+    dir?: 'ASC' | 'DESC';
+    /** Pagination offset. The API returns at most 5 rows per request. */
+    start?: number;
+    /** Only return these fields. Rows then hold just these keys. */
+    include?: readonly string[];
+    /** Leave out these fields. */
+    exclude?: readonly string[];
+}
+/**
+ * Searches every player on record, past and present. Returns the full page
+ * (`{ data, total }`): the API sends **at most 5 rows** per request, whatever
+ * the limit, so page with `start` until you have `total` rows.
+ *
+ * @param params.name Case-insensitive part of the full name, e.g. "matth"
+ * @param params.teamId NHL team id of the current team, e.g. 10
+ * @param params.position C, L, R, D, G, or F for every forward
+ * @param params.cayenneExp Extra filter expression, e.g. "sweaterNumber=34"
+ * @param params.sort Field to sort by, e.g. "lastName"
+ * @param params.dir ASC or DESC
+ * @param params.start Pagination offset
+ * @param params.include Only return these fields, e.g. ['id', 'fullName']
+ * @param params.exclude Leave out these fields
+ * @throws RangeError When no filter is given (the API would return no rows)
+ * @example await client.players.playerSearch({ name: 'matthews', position: 'C' })
+ */
+export declare function playerSearch(ctx: Context, params: PlayerSearchParams): Promise<StatsApiPage<StatsPlayer>>;
 export declare const playersApi: {
     readonly prospectsByTeam: typeof prospectsByTeam;
     readonly playersByTeam: typeof playersByTeam;
+    readonly playerSpotlight: typeof playerSpotlight;
+    readonly playerSearch: typeof playerSearch;
 };