nhl-api-ts 0.2.0 → 0.3.0

package/dist/api/players.mjs

@@ -1,3 +1,5 @@
+import { andClauses, cayenneString } from '#src/api/query/cayenne.mjs';
+import { filter, toQuery, } from '#src/api/query/filters.mjs';
 import { Endpoint } from '#src/http-client.mjs';
 /**
  * Gets prospects for a specific team, grouped by position.
@@ -5,14 +7,93 @@ import { Endpoint } from '#src/http-client.mjs';
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
  * @example https://api-web.nhle.com/v1/prospects/BUF
  */
-export const prospectsByTeam = async (ctx, { teamAbbr }) => (await ctx.get(Endpoint.API_WEB_V1, `prospects/${teamAbbr}`)).json();
+export async function prospectsByTeam(ctx, { teamAbbr }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `prospects/${teamAbbr}`)).json();
+}
 /**
  * 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 const playersByTeam = async (ctx, { teamAbbr, season }) => (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season}`)).json();
-export const playersApi = { prospectsByTeam, playersByTeam };
+export async function playersByTeam(ctx, { teamAbbr, season }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season ?? 'current'}`)).json();
+}
+/**
+ * Gets the players featured in the nhl.com player spotlight.
+ *
+ * @example https://api-web.nhle.com/v1/player-spotlight
+ */
+export async function playerSpotlight(ctx) {
+    return (await ctx.get(Endpoint.API_WEB_V1, 'player-spotlight')).json();
+}
+function playerSearchClauses({ name, teamId, position, cayenneExp, }) {
+    const clauses = [];
+    if (name?.trim()) {
+        clauses.push(`fullName likeIgnoreCase ${cayenneString(`%${name.trim()}%`)}`);
+    }
+    if (teamId !== undefined && teamId !== null) {
+        clauses.push(`currentTeamId=${teamId}`);
+    }
+    if (position !== undefined) {
+        clauses.push(position === 'G'
+            ? "positionCode='G'"
+            : toQuery(filter.position(position)));
+    }
+    if (cayenneExp?.trim()) {
+        clauses.push(cayenneExp);
+    }
+    return clauses;
+}
+/**
+ * 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 async function playerSearch(ctx, params) {
+    const { sort, dir, start, include, exclude } = params;
+    const clauses = playerSearchClauses(params);
+    if (clauses.length === 0) {
+        throw new RangeError('Missing filter. Pass name, teamId, position or cayenneExp.');
+    }
+    const query = {
+        cayenneExp: andClauses(clauses),
+    };
+    if (sort !== undefined) {
+        query.sort = sort;
+    }
+    if (dir !== undefined) {
+        query.dir = dir;
+    }
+    if (start !== undefined) {
+        query.start = start;
+    }
+    if (include && include.length > 0) {
+        query.include = include;
+    }
+    if (exclude && exclude.length > 0) {
+        query.exclude = exclude;
+    }
+    return (await ctx.get(Endpoint.API_STATS, 'en/players', query)).json();
+}
+export const playersApi = {
+    prospectsByTeam,
+    playersByTeam,
+    playerSpotlight,
+    playerSearch,
+};

package/dist/api/query/cayenne.d.mts

@@ -0,0 +1,4 @@
+/** Quotes a value as a cayenne string literal, backslash-escaping `\` and `'`. */
+export declare function cayenneString(value: string): string;
+/** Joins clauses with `and`, parenthesizing each when there is more than one. */
+export declare function andClauses(clauses: readonly string[]): string;

package/dist/api/query/cayenne.mjs

@@ -0,0 +1,13 @@
+// Internal helpers for SDK methods that build their own `cayenneExp`. Not
+// exported from the package: `buildQuery` / `filter` cover the report filters.
+/** Quotes a value as a cayenne string literal, backslash-escaping `\` and `'`. */
+export function cayenneString(value) {
+    return `'${value.replace(/[\\']/g, (char) => `\\${char}`)}'`;
+}
+/** Joins clauses with `and`, parenthesizing each when there is more than one. */
+export function andClauses(clauses) {
+    if (clauses.length === 1) {
+        return clauses[0];
+    }
+    return clauses.map((clause) => `(${clause})`).join(' and ');
+}

package/dist/api/query/sorting/sorting-options.d.mts

@@ -133,4 +133,12 @@ export declare const SKATER_REPORT_TYPES: string[];
  * summary sort for unknown report types.
  */
 export declare function defaultSortForReport(report: string): SortExpr[];
+/**
+ * Default sort criteria for a team summary. Falls back to points and wins.
+ */
+export declare function defaultSortForTeamSummary(expr: SortExpr[] | undefined, isAggregate: boolean): SortExpr[];
+/**
+ * Default sort criteria for a skater stats summary. Falls back to points
+ */
+export declare function defaultSortForSkaterStatsSummary(expr: SortExpr[] | undefined): SortExpr[];
 export {};

package/dist/api/query/sorting/sorting-options.mjs

@@ -92,3 +92,33 @@ export function defaultSortForReport(report) {
         ? sortingLookup[report]
         : undefined) ?? skaterSummaryDefaultSorting);
 }
+/**
+ * Default sort criteria for a team summary. Falls back to points and wins.
+ */
+export function defaultSortForTeamSummary(expr, isAggregate) {
+    if (expr && expr.length > 0) {
+        return expr;
+    }
+    return [
+        { property: 'points', direction: 'DESC' },
+        { property: 'wins', direction: 'DESC' },
+        // aggregated rows span seasons, so they have no teamId
+        {
+            property: isAggregate ? 'franchiseId' : 'teamId',
+            direction: 'ASC',
+        },
+    ];
+}
+/**
+ * Default sort criteria for a skater stats summary. Falls back to points
+ */
+export function defaultSortForSkaterStatsSummary(expr) {
+    if (expr && expr.length > 0) {
+        return expr;
+    }
+    return [
+        { property: 'points', direction: 'DESC' },
+        { property: 'gamesPlayed', direction: 'ASC' },
+        { property: 'playerId', direction: 'ASC' },
+    ];
+}

package/dist/api/schedule.d.mts

@@ -1,5 +1,5 @@
 import type { Context } from '#src/context.mjs';
-import type { CalendarSchedule, ClubScheduleGame, OddsPartner, PlayoffBracket, PlayoffCarousel, PlayoffSeriesSchedule, ScheduleGame, TeamSeasonSchedule, WeeklySchedule } from '#src/types/index.mjs';
+import type { CalendarSchedule, ClubScheduleGame, OddsPartner, PlayoffBracket, PlayoffCarousel, PlayoffSeriesMeta, PlayoffSeriesSchedule, ScheduleGame, TeamSeasonSchedule, WeeklySchedule } from '#src/types/index.mjs';
 import type { Id } from '#src/utils.mjs';
 /**
  * Parses and normalizes a YYYY-MM-DD date: single-digit months/days are
@@ -21,18 +21,18 @@ export interface DailySchedule {
  * @throws RangeError If the date is not a valid YYYY-MM-DD date
  * @example await client.schedule.dailySchedule({ date: '2024-10-09' })
  */
-export declare const dailySchedule: (ctx: Context, { date }?: {
+export declare function dailySchedule(ctx: Context, { date }?: {
     date?: string;
-}) => Promise<DailySchedule>;
+}): Promise<DailySchedule>;
 /**
  * Gets NHL schedule for a week starting from the specified date.
  *
  * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/schedule/2024-10-09
  */
-export declare const weeklySchedule: (ctx: Context, { date }?: {
+export declare function weeklySchedule(ctx: Context, { date }?: {
     date?: string;
-}) => Promise<WeeklySchedule>;
+}): Promise<WeeklySchedule>;
 /**
  * Gets monthly schedule for a specified team.
  *
@@ -40,10 +40,10 @@ export declare const weeklySchedule: (ctx: Context, { date }?: {
  * @param params.month Month in YYYY-MM format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/club-schedule/BUF/month/2023-11
  */
-export declare const teamMonthlySchedule: (ctx: Context, { teamAbbr, month }: {
+export declare function teamMonthlySchedule(ctx: Context, { teamAbbr, month }: {
     teamAbbr: string;
     month?: string;
-}) => Promise<ClubScheduleGame[]>;
+}): Promise<ClubScheduleGame[]>;
 /**
  * Gets weekly schedule for a specified team.
  *
@@ -51,39 +51,39 @@ export declare const teamMonthlySchedule: (ctx: Context, { teamAbbr, month }: {
  * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/club-schedule/BUF/week/2024-02-10
  */
-export declare const teamWeeklySchedule: (ctx: Context, { teamAbbr, date }: {
+export declare function teamWeeklySchedule(ctx: Context, { teamAbbr, date }: {
     teamAbbr: string;
     date?: string;
-}) => Promise<ClubScheduleGame[]>;
+}): Promise<ClubScheduleGame[]>;
 /**
  * Gets the full season schedule for a specified team.
  *
  * @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 "now".
  * @example https://api-web.nhle.com/v1/club-schedule-season/BUF/20232024
  */
-export declare const teamSeasonSchedule: (ctx: Context, { teamAbbr, season }: {
+export declare function teamSeasonSchedule(ctx: Context, { teamAbbr, season }: {
     teamAbbr: string;
-    season: Id;
-}) => Promise<TeamSeasonSchedule>;
+    season?: Id;
+}): Promise<TeamSeasonSchedule>;
 /**
  * Gets the schedule in calendar format for a specified date.
  *
- * @param params.date Date in YYYY-MM-DD format
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/schedule-calendar/2023-11-08
  */
-export declare const calendarSchedule: (ctx: Context, { date }: {
-    date: string;
-}) => Promise<CalendarSchedule>;
+export declare function calendarSchedule(ctx: Context, { date }?: {
+    date?: string;
+}): Promise<CalendarSchedule>;
 /**
  * Gets all playoff series information up to the current round.
  *
  * @param params.season Season in YYYYYYYY format, e.g. 20232024
  * @example https://api-web.nhle.com/v1/playoff-series/carousel/20232024
  */
-export declare const playoffCarousel: (ctx: Context, { season }: {
+export declare function playoffCarousel(ctx: Context, { season }: {
     season: Id;
-}) => Promise<PlayoffCarousel>;
+}): Promise<PlayoffCarousel>;
 /**
  * Returns the schedule and results for a specified playoff series matchup.
  *
@@ -91,19 +91,31 @@ export declare const playoffCarousel: (ctx: Context, { season }: {
  * @param params.series Series letter, e.g. "a" (first round) through "o" (final)
  * @example https://api-web.nhle.com/v1/schedule/playoff-series/20232024/a
  */
-export declare const playoffSeriesSchedule: (ctx: Context, { season, series }: {
+export declare function playoffSeriesSchedule(ctx: Context, { season, series }: {
     season: Id;
     series: string;
-}) => Promise<PlayoffSeriesSchedule>;
+}): Promise<PlayoffSeriesSchedule>;
+/**
+ * Returns the metadata nhl.com uses to render a playoff series page: the
+ * round title and the two seeded teams.
+ *
+ * @param params.year Year the playoffs took place, e.g. 2024
+ * @param params.series Series letter, e.g. "a" (first round) through "o" (final). Case-insensitive.
+ * @example https://api-web.nhle.com/v1/meta/playoff-series/2024/a
+ */
+export declare function playoffSeriesMeta(ctx: Context, { year, series }: {
+    year: Id;
+    series: string;
+}): Promise<PlayoffSeriesMeta>;
 /**
  * Returns the full playoff bracket for a given year.
  *
  * @param params.year Year the playoffs took place, e.g. 2024
  * @example https://api-web.nhle.com/v1/playoff-bracket/2024
  */
-export declare const playoffBracket: (ctx: Context, { year }: {
+export declare function playoffBracket(ctx: Context, { year }: {
     year: Id;
-}) => Promise<PlayoffBracket>;
+}): Promise<PlayoffBracket>;
 export declare const scheduleApi: {
     readonly dailySchedule: typeof dailySchedule;
     readonly weeklySchedule: typeof weeklySchedule;
@@ -113,5 +125,6 @@ export declare const scheduleApi: {
     readonly calendarSchedule: typeof calendarSchedule;
     readonly playoffCarousel: typeof playoffCarousel;
     readonly playoffSeriesSchedule: typeof playoffSeriesSchedule;
+    readonly playoffSeriesMeta: typeof playoffSeriesMeta;
     readonly playoffBracket: typeof playoffBracket;
 };

package/dist/api/schedule.mjs

@@ -1,5 +1,7 @@
 import { Endpoint } from '#src/http-client.mjs';
-const pad = (value, width = 2) => String(value).padStart(width, '0');
+function pad(value, width = 2) {
+    return String(value).padStart(width, '0');
+}
 /** Today's date (local time) as YYYY-MM-DD. */
 function today() {
     const now = new Date();
@@ -29,7 +31,7 @@ export function normalizeDate(date) {
  * @throws RangeError If the date is not a valid YYYY-MM-DD date
  * @example await client.schedule.dailySchedule({ date: '2024-10-09' })
  */
-export const dailySchedule = async (ctx, { date } = {}) => {
+export async function dailySchedule(ctx, { date } = {}) {
     const resolvedDate = date ? normalizeDate(date) : today();
     const scheduleData = await (await ctx.get(Endpoint.API_WEB_V1, `schedule/${resolvedDate}`)).json();
     const responsePayload = {
@@ -46,17 +48,17 @@ export const dailySchedule = async (ctx, { date } = {}) => {
         responsePayload.numberOfGames = games.length;
     }
     return responsePayload;
-};
+}
 /**
  * Gets NHL schedule for a week starting from the specified date.
  *
  * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/schedule/2024-10-09
  */
-export const weeklySchedule = async (ctx, { date } = {}) => {
+export async function weeklySchedule(ctx, { date } = {}) {
     const res = date ? date : 'now';
     return (await ctx.get(Endpoint.API_WEB_V1, `schedule/${res}`)).json();
-};
+}
 /**
  * Gets monthly schedule for a specified team.
  *
@@ -64,11 +66,11 @@ export const weeklySchedule = async (ctx, { date } = {}) => {
  * @param params.month Month in YYYY-MM format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/club-schedule/BUF/month/2023-11
  */
-export const teamMonthlySchedule = async (ctx, { teamAbbr, month }) => {
+export async function teamMonthlySchedule(ctx, { teamAbbr, month }) {
     const resource = `club-schedule/${teamAbbr}/month/${month ? month : 'now'}`;
     const response = await (await ctx.get(Endpoint.API_WEB_V1, resource)).json();
     return response.games ?? [];
-};
+}
 /**
  * Gets weekly schedule for a specified team.
  *
@@ -76,33 +78,39 @@ export const teamMonthlySchedule = async (ctx, { teamAbbr, month }) => {
  * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/club-schedule/BUF/week/2024-02-10
  */
-export const teamWeeklySchedule = async (ctx, { teamAbbr, date }) => {
+export async function teamWeeklySchedule(ctx, { teamAbbr, date }) {
     const resource = `club-schedule/${teamAbbr}/week/${date ? date : 'now'}`;
     const response = await (await ctx.get(Endpoint.API_WEB_V1, resource)).json();
     return response.games ?? [];
-};
+}
 /**
  * Gets the full season schedule for a specified team.
  *
  * @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 "now".
  * @example https://api-web.nhle.com/v1/club-schedule-season/BUF/20232024
  */
-export const teamSeasonSchedule = async (ctx, { teamAbbr, season }) => (await ctx.get(Endpoint.API_WEB_V1, `club-schedule-season/${teamAbbr}/${season}`)).json();
+export async function teamSeasonSchedule(ctx, { teamAbbr, season }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `club-schedule-season/${teamAbbr}/${season ?? 'now'}`)).json();
+}
 /**
  * Gets the schedule in calendar format for a specified date.
  *
- * @param params.date Date in YYYY-MM-DD format
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
  * @example https://api-web.nhle.com/v1/schedule-calendar/2023-11-08
  */
-export const calendarSchedule = async (ctx, { date }) => (await ctx.get(Endpoint.API_WEB_V1, `schedule-calendar/${date}`)).json();
+export async function calendarSchedule(ctx, { date } = {}) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `schedule-calendar/${date ?? 'now'}`)).json();
+}
 /**
  * Gets all playoff series information up to the current round.
  *
  * @param params.season Season in YYYYYYYY format, e.g. 20232024
  * @example https://api-web.nhle.com/v1/playoff-series/carousel/20232024
  */
-export const playoffCarousel = async (ctx, { season }) => (await ctx.get(Endpoint.API_WEB_V1, `playoff-series/carousel/${season}`)).json();
+export async function playoffCarousel(ctx, { season }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `playoff-series/carousel/${season}`)).json();
+}
 /**
  * Returns the schedule and results for a specified playoff series matchup.
  *
@@ -110,14 +118,29 @@ export const playoffCarousel = async (ctx, { season }) => (await ctx.get(Endpoin
  * @param params.series Series letter, e.g. "a" (first round) through "o" (final)
  * @example https://api-web.nhle.com/v1/schedule/playoff-series/20232024/a
  */
-export const playoffSeriesSchedule = async (ctx, { season, series }) => (await ctx.get(Endpoint.API_WEB_V1, `schedule/playoff-series/${season}/${series}`)).json();
+export async function playoffSeriesSchedule(ctx, { season, series }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `schedule/playoff-series/${season}/${series}`)).json();
+}
+/**
+ * Returns the metadata nhl.com uses to render a playoff series page: the
+ * round title and the two seeded teams.
+ *
+ * @param params.year Year the playoffs took place, e.g. 2024
+ * @param params.series Series letter, e.g. "a" (first round) through "o" (final). Case-insensitive.
+ * @example https://api-web.nhle.com/v1/meta/playoff-series/2024/a
+ */
+export async function playoffSeriesMeta(ctx, { year, series }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `meta/playoff-series/${year}/${series}`)).json();
+}
 /**
  * Returns the full playoff bracket for a given year.
  *
  * @param params.year Year the playoffs took place, e.g. 2024
  * @example https://api-web.nhle.com/v1/playoff-bracket/2024
  */
-export const playoffBracket = async (ctx, { year }) => (await ctx.get(Endpoint.API_WEB_V1, `playoff-bracket/${year}`)).json();
+export async function playoffBracket(ctx, { year }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `playoff-bracket/${year}`)).json();
+}
 export const scheduleApi = {
     dailySchedule,
     weeklySchedule,
@@ -127,5 +150,6 @@ export const scheduleApi = {
     calendarSchedule,
     playoffCarousel,
     playoffSeriesSchedule,
+    playoffSeriesMeta,
     playoffBracket,
 };

package/dist/api/standings.d.mts

@@ -12,17 +12,17 @@ import type { Id } from '#src/utils.mjs';
  * @throws RangeError If the season id is not found in the standings manifest
  * @example await client.standings.leagueStandings({ season: '20222023' })
  */
-export declare const leagueStandings: (ctx: Context, { date, season }?: {
+export declare function leagueStandings(ctx: Context, { date, season }?: {
     date?: string;
     season?: Id;
-}) => Promise<LeagueStandings>;
+}): Promise<LeagueStandings>;
 /**
  * Gets metadata for every historical NHL season: start/end dates and which
  * standings rules (conferences, divisions, wildcard, ties...) were in use.
  *
  * @example https://api-web.nhle.com/v1/standings-season
  */
-export declare const seasonStandingManifest: (ctx: Context) => Promise<StandingsSeason[]>;
+export declare function seasonStandingManifest(ctx: Context): Promise<StandingsSeason[]>;
 export declare const standingsApi: {
     readonly leagueStandings: typeof leagueStandings;
     readonly seasonStandingManifest: typeof seasonStandingManifest;

package/dist/api/standings.mjs

@@ -10,7 +10,7 @@ import { Endpoint } from '#src/http-client.mjs';
  * @throws RangeError If the season id is not found in the standings manifest
  * @example await client.standings.leagueStandings({ season: '20222023' })
  */
-export const leagueStandings = async (ctx, { date, season } = {}) => {
+export async function leagueStandings(ctx, { date, season } = {}) {
     if (season) {
         const seasons = await seasonStandingManifest(ctx);
         const seasonData = seasons.find((seasonEntry) => seasonEntry.id === Number(season));
@@ -21,17 +21,17 @@ export const leagueStandings = async (ctx, { date, season } = {}) => {
     }
     const res = date ? date : 'now';
     return (await ctx.get(Endpoint.API_WEB_V1, `standings/${res}`)).json();
-};
+}
 /**
  * Gets metadata for every historical NHL season: start/end dates and which
  * standings rules (conferences, divisions, wildcard, ties...) were in use.
  *
  * @example https://api-web.nhle.com/v1/standings-season
  */
-export const seasonStandingManifest = async (ctx) => {
+export async function seasonStandingManifest(ctx) {
     const response = await (await ctx.get(Endpoint.API_WEB_V1, 'standings-season')).json();
     return response.seasons ?? [];
-};
+}
 export const standingsApi = {
     leagueStandings,
     seasonStandingManifest,