nhl-api-ts 0.0.0-stage → 0.1.0

package/dist/api/stats.mjs

@@ -0,0 +1,148 @@
+import { goalieStatsSorts } from '#src/api/query/sorting/goalie-sorts.mjs';
+import { defaultSortForReport, } from '#src/api/query/sorting/sorting-options.mjs';
+import { Endpoint } from '#src/http-client.mjs';
+/**
+ * Gets all game types played by a team throughout their history.
+ *
+ * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
+ * @example https://api-web.nhle.com/v1/club-stats-season/TOR
+ */
+export const gametypesPerSeasonDirectoryByTeam = async (ctx, { teamAbbr }) => (await ctx.get(Endpoint.API_WEB_V1, `club-stats-season/${teamAbbr}`)).json();
+/**
+ * Gets a player's career statistics and biographical information.
+ *
+ * @param params.playerId NHL player id, e.g. 8481528
+ * @example https://api-web.nhle.com/v1/player/8481528/landing
+ */
+export const playerCareerStats = async (ctx, { playerId }) => (await ctx.get(Endpoint.API_WEB_V1, `player/${playerId}/landing`)).json();
+/**
+ * Gets a player's game log for a specific 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
+ * @example https://api-web.nhle.com/v1/player/8481528/game-log/20232024/2
+ */
+export const playerGameLog = async (ctx, { playerId, seasonId, gameType, }) => {
+    const data = await (await ctx.get(Endpoint.API_WEB_V1, `player/${playerId}/game-log/${seasonId}/${gameType}`)).json();
+    return data.gameLog ?? [];
+};
+/**
+ * Retrieves team summary statistics across one or more seasons.
+ *
+ * @example await client.stats.teamSummary({ startSeason: '20232024', endSeason: '20232024' })
+ */
+export const teamSummary = async (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' },
+            { property: 'teamId', direction: 'ASC' },
+        ];
+    const effectiveCayenneExp = defaultCayenneExp ??
+        `gameTypeId=${gameTypeId} and seasonId<=${endSeason} and seasonId>=${startSeason}`;
+    const qParams = {
+        isAggregate,
+        isGame,
+        start,
+        limit,
+        factCayenneExp,
+        sort: JSON.stringify(effectiveSortExpr),
+        cayenneExp: effectiveCayenneExp,
+    };
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/team/summary', qParams)).json();
+    return response.data;
+};
+/**
+ * Gets simplified skater statistics summary for specified seasons and
+ * franchises.
+ *
+ * @example await client.stats.skaterStatsSummary({ startSeason: '20232024', endSeason: '20232024', franchiseId: 10 })
+ */
+export const skaterStatsSummary = async (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 baseCayenneExp = defaultCayenneExp ??
+        `gameTypeId=${gameTypeId} and seasonId<=${endSeason} and seasonId>=${startSeason}`;
+    const effectiveCayenneExp = !defaultCayenneExp && franchiseId
+        ? `franchiseId=${franchiseId} and ${baseCayenneExp}`
+        : baseCayenneExp;
+    const qParams = {
+        isAggregate: aggregate,
+        isGame: false,
+        start,
+        limit,
+        factCayenneExp,
+        sort: JSON.stringify(effectiveSortExpr),
+        cayenneExp: effectiveCayenneExp,
+    };
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/skater/summary', qParams)).json();
+    return response.data;
+};
+/**
+ * Retrieves skater statistics using a query context and specified report
+ * type. Returns the full response (`{ data, total }`).
+ *
+ * @example
+ * const context = buildQuery([
+ *   filter.season('20232024', '20232024'),
+ *   filter.position(PositionTypes.CENTER),
+ * ]);
+ * await client.stats.skaterStatsWithQueryContext({ queryContext: context, reportType: 'summary' });
+ */
+export const skaterStatsWithQueryContext = async (ctx, { queryContext, reportType, sortExpr, aggregate = false, start = 0, limit = 25, }) => {
+    const effectiveSortExpr = sortExpr && sortExpr.length > 0
+        ? sortExpr
+        : defaultSortForReport(reportType);
+    const qParams = {
+        isAggregate: aggregate,
+        isGame: false,
+        start,
+        limit,
+        factCayenneExp: queryContext.factQuery,
+        sort: JSON.stringify(effectiveSortExpr),
+        cayenneExp: queryContext.query,
+    };
+    return (await ctx.get(Endpoint.API_STATS, `en/skater/${reportType}`, qParams)).json();
+};
+/**
+ * Retrieves goalie statistics with various filtering and aggregation
+ * options.
+ *
+ * @example await client.stats.goalieStatsSummary({ startSeason: '20232024', statsType: 'advanced' })
+ */
+export const goalieStatsSummary = async (ctx, { startSeason, endSeason, statsType = 'summary', gameTypeId = 2, franchiseId, aggregate = false, sortExpr, start = 0, limit = 25, factCayenneExp, defaultCayenneExp, }) => {
+    const effectiveEndSeason = endSeason === undefined || endSeason === null ? startSeason : endSeason;
+    const effectiveSortExpr = sortExpr && sortExpr.length > 0 ? sortExpr : goalieStatsSorts(statsType);
+    const baseCayenneExp = defaultCayenneExp ??
+        `gameTypeId=${gameTypeId} and seasonId<=${effectiveEndSeason} and seasonId>=${startSeason}`;
+    const effectiveCayenneExp = franchiseId
+        ? `franchiseId=${franchiseId} and ${baseCayenneExp}`
+        : baseCayenneExp;
+    const qParams = {
+        isAggregate: aggregate,
+        isGame: false,
+        start,
+        limit,
+        factCayenneExp,
+        sort: JSON.stringify(effectiveSortExpr),
+        cayenneExp: effectiveCayenneExp,
+    };
+    const response = await (await ctx.get(Endpoint.API_STATS, `en/goalie/${statsType}`, qParams)).json();
+    return response.data ?? [];
+};
+export const statsApi = {
+    gametypesPerSeasonDirectoryByTeam,
+    playerCareerStats,
+    playerGameLog,
+    teamSummary,
+    skaterStatsSummary,
+    skaterStatsWithQueryContext,
+    goalieStatsSummary,
+};

package/dist/api/teams.d.mts

@@ -0,0 +1,58 @@
+import type { Context } from '#src/context.mjs';
+import type { Id, JsonObject } from '#src/utils.mjs';
+export interface Team {
+    conference: {
+        abbr: string;
+        name: string;
+    };
+    division: {
+        abbr: string;
+        name: string;
+    };
+    name: string;
+    common_name: string;
+    abbr: string;
+    logo: string;
+    franchise_id?: number;
+}
+/** Converts a raw standings entry into a `Team`. */
+export declare function toTeam(teamData: JsonObject): Team;
+/**
+ * Adds a `franchise_id` to each team that has a matching franchise. Teams
+ * without a match are returned unchanged (no `franchise_id` key).
+ */
+export declare function withFranchiseIds(teams: readonly Team[], franchises: readonly JsonObject[]): Team[];
+/**
+ * Get a list of all NHL teams with conference, division, and franchise info.
+ *
+ * Team list is derived from the standings for the given date, then enriched
+ * with franchise ids.
+ *
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
+ * @example await client.teams.teams()
+ */
+export declare const teams: (ctx: Context, { date }?: {
+    date?: string;
+}) => Promise<Team[]>;
+/**
+ * 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
+ * @example https://api-web.nhle.com/v1/roster/BUF/20232024
+ */
+export declare const teamRoster: (ctx: Context, { teamAbbr, season }: {
+    teamAbbr: string;
+    season: Id;
+}) => Promise<JsonObject>;
+/**
+ * Get a list of all past and current NHL franchises.
+ *
+ * @example https://api.nhle.com/stats/rest/en/franchise
+ */
+export declare const franchises: (ctx: Context) => Promise<JsonObject[]>;
+export declare const teamsApi: {
+    readonly teams: typeof teams;
+    readonly teamRoster: typeof teamRoster;
+    readonly franchises: typeof franchises;
+};

package/dist/api/teams.mjs

@@ -0,0 +1,91 @@
+import { Endpoint } from '#src/http-client.mjs';
+async function fetchStandingsData(ctx, date) {
+    const response = await (await ctx.get(Endpoint.API_WEB_V1, `standings/${date}`)).json();
+    return response.standings ?? [];
+}
+/** Converts a raw standings entry into a `Team`. */
+export function toTeam(teamData) {
+    const nestedDefault = (key) => teamData[key]?.default ?? '';
+    return {
+        conference: {
+            abbr: teamData.conferenceAbbrev ?? '',
+            name: teamData.conferenceName ?? '',
+        },
+        division: {
+            abbr: teamData.divisionAbbrev ?? '',
+            name: teamData.divisionName ?? '',
+        },
+        name: nestedDefault('teamName'),
+        common_name: nestedDefault('teamCommonName'),
+        abbr: nestedDefault('teamAbbrev'),
+        logo: teamData.teamLogo ?? '',
+    };
+}
+/** Find franchise ID for a team name, with fallbacks for known name mismatches. */
+function findFranchiseId(teamName, lookup) {
+    if (lookup.has(teamName)) {
+        return lookup.get(teamName);
+    }
+    // "Montreal Canadiens" vs "Montréal Canadiens", Utah's renames, etc.
+    for (const partial of ['Canadiens', 'Utah']) {
+        if (teamName.includes(partial)) {
+            for (const [franchiseName, franchiseId] of lookup) {
+                if (franchiseName.includes(partial)) {
+                    return franchiseId;
+                }
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Adds a `franchise_id` to each team that has a matching franchise. Teams
+ * without a match are returned unchanged (no `franchise_id` key).
+ */
+export function withFranchiseIds(teams, franchises) {
+    const lookup = new Map();
+    for (const franchise of franchises) {
+        const fullName = franchise.fullName ?? '';
+        const franchiseId = franchise.id;
+        if (fullName && franchiseId) {
+            lookup.set(fullName, franchiseId);
+        }
+    }
+    return teams.map((team) => {
+        const franchiseId = findFranchiseId(team.name ?? '', lookup);
+        return franchiseId ? { ...team, franchise_id: franchiseId } : { ...team };
+    });
+}
+/**
+ * Get a list of all NHL teams with conference, division, and franchise info.
+ *
+ * Team list is derived from the standings for the given date, then enriched
+ * with franchise ids.
+ *
+ * @param params.date Date in YYYY-MM-DD format. Defaults to "now".
+ * @example await client.teams.teams()
+ */
+export const teams = async (ctx, { date = 'now' } = {}) => {
+    const standingsData = await fetchStandingsData(ctx, date);
+    const franchiseData = await franchises(ctx);
+    return withFranchiseIds(standingsData.map(toTeam), franchiseData);
+};
+/**
+ * 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
+ * @example https://api-web.nhle.com/v1/roster/BUF/20232024
+ */
+export const teamRoster = async (ctx, { teamAbbr, season }) => (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season}`)).json();
+/**
+ * Get a list of all past and current NHL franchises.
+ *
+ * @example https://api.nhle.com/stats/rest/en/franchise
+ */
+export const franchises = async (ctx) => {
+    const response = await (await ctx.get(Endpoint.API_STATS, 'en/franchise')).json();
+    return response.data ?? [];
+};
+export const teamsApi = { teams, teamRoster, franchises };

package/dist/cli/colors.d.mts

@@ -0,0 +1,14 @@
+import { styleText } from 'node:util';
+export type Style = Parameters<typeof styleText>[0];
+export declare const toStdout: (format: Style) => (text: string) => string;
+export declare const toStderr: (format: Style) => (text: string) => string;
+export declare const colors: {
+    dim: (text: string) => string;
+    pass: (text: string) => string;
+    fail: (text: string) => string;
+    ok: (text: string) => string;
+    success: (text: string) => string;
+    error: (text: string) => string;
+    warn: (text: string) => string;
+    bold: (text: string) => string;
+};

package/dist/cli/colors.mjs

@@ -0,0 +1,13 @@
+import { styleText } from 'node:util';
+export const toStdout = (format) => (text) => styleText(format, text, { stream: process.stdout });
+export const toStderr = (format) => (text) => styleText(format, text, { stream: process.stderr });
+export const colors = {
+    dim: toStdout('dim'),
+    pass: toStdout(['bold', 'green']),
+    fail: toStdout(['bold', 'red']),
+    ok: toStdout('green'),
+    success: toStdout(['bold', 'green']),
+    error: toStderr('red'),
+    warn: toStderr('yellow'),
+    bold: toStderr('bold'),
+};

package/dist/cli/commands.d.mts

@@ -0,0 +1,27 @@
+import type { NHLClient } from '#src/nhl-client.mjs';
+export type ArgType = 'string' | 'int' | 'number' | 'boolean' | 'list' | 'int-list' | 'json';
+export interface ArgSpec {
+    /** SDK parameter name (camelCase). The CLI flag is its kebab-case form. */
+    name: string;
+    type: ArgType;
+    description: string;
+    required?: boolean;
+    /** Shown in help only; the SDK applies its own defaults. */
+    default?: string;
+    choices?: readonly string[];
+}
+export interface CommandSpec {
+    name: string;
+    description: string;
+    args: ArgSpec[];
+    run: (client: NHLClient, values: any) => Promise<unknown>;
+}
+export interface ModuleSpec {
+    name: string;
+    description: string;
+    commands: CommandSpec[];
+}
+/** Thrown for invalid command-line input (exit code 2). */
+export declare class UsageError extends Error {
+}
+export declare const MODULES: ModuleSpec[];