nhl-api-ts 0.0.0-stage → 0.2.0

package/dist/cli/run.d.mts

@@ -0,0 +1,9 @@
+import type { ClientOptions } from '#src/config.mjs';
+import { type NHLClient } from '#src/nhl-client.mjs';
+export interface CliIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    createClient?: (options: ClientOptions) => NHLClient;
+}
+/** Runs the CLI and resolves with the process exit code. */
+export declare function runCli(argv: string[], io: CliIO): Promise<number>;

package/dist/cli/run.mjs

@@ -0,0 +1,313 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { colors } from '#src/cli/colors.mjs';
+import { MODULES, UsageError, } from '#src/cli/commands.mjs';
+import { NHLApiException } from '#src/errors.mjs';
+import { createNHLClient } from '#src/nhl-client.mjs';
+const BIN = 'nhl-api-ts';
+const kebab = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+const GLOBAL_OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    debug: { type: 'boolean' },
+    timeout: { type: 'string' },
+    'follow-redirects': { type: 'boolean' },
+    compact: { type: 'boolean' },
+};
+const GLOBAL_HELP = `Global options:
+  -h, --help               Show help (also per module / command)
+  -v, --version            Show version
+      --compact            Print JSON on a single line
+      --debug              Log requests to stderr
+      --timeout <seconds>  Request timeout (default: 10)
+      --no-follow-redirects  Do not follow HTTP redirects`;
+function version() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+// ---- Help -------------------------------------------------------------------
+function table(rows, indent = 2) {
+    const width = Math.max(0, ...rows.map(([label]) => label.length));
+    return rows
+        .map(([label, description]) => `${' '.repeat(indent)}${label.padEnd(width)}  ${description}`)
+        .join('\n');
+}
+function rootHelp() {
+    return `Usage: ${BIN} ${colors.pass('<module> <command>')} [args] [options]
+
+Command line access to the NHL API and NHL EDGE stats. Results are printed
+as JSON on stdout.
+
+Modules:
+${table(MODULES.map((moduleSpec) => [moduleSpec.name, moduleSpec.description]))}
+
+${GLOBAL_HELP}
+
+Examples:
+  ${BIN} schedule daily-schedule --date 2024-10-09
+  ${BIN} game-center boxscore 2023020280
+  ${BIN} stats skater-stats-with-query-context summary --season-start 20232024 --position C
+
+Run '${BIN} <module> --help' to list a module's commands.`;
+}
+function moduleHelp(mod) {
+    return `Usage: ${BIN} ${mod.name} ${colors.pass('<command>')} [args] [options]
+
+${mod.description}
+
+Commands:
+${table(mod.commands.map((command) => [command.name, command.description]))}
+
+Run '${BIN} ${mod.name} <command> --help' for command options.`;
+}
+function argLabel(arg) {
+    const flag = `--${kebab(arg.name)}`;
+    if (arg.type === 'boolean') {
+        return flag;
+    }
+    return `${flag} <${kebab(arg.name)}>`;
+}
+function commandHelp(mod, cmd) {
+    const required = cmd.args.filter((arg) => arg.required);
+    const optional = cmd.args.filter((arg) => !arg.required);
+    const usage = [
+        BIN,
+        mod.name,
+        cmd.name,
+        ...required.map((arg) => colors.pass(`<${kebab(arg.name)}>`)),
+        optional.length ? '[options]' : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const describe = (arg) => {
+        const extras = [
+            arg.choices ? `one of: ${arg.choices.join(', ')}` : '',
+            arg.default !== undefined ? `default: ${arg.default}` : '',
+        ].filter(Boolean);
+        return extras.length
+            ? `${arg.description} (${extras.join('; ')})`
+            : arg.description;
+    };
+    const sections = [`Usage: ${usage}`, cmd.description];
+    if (required.length) {
+        sections.push(`Arguments (positional, or as flags):\n${table(required.map((arg) => [
+            `<${kebab(arg.name)}>, ${argLabel(arg)}`,
+            describe(arg),
+        ]))}`);
+    }
+    if (optional.length) {
+        sections.push(`Options:\n${table(optional.map((arg) => [argLabel(arg), describe(arg)]))}`);
+    }
+    sections.push(GLOBAL_HELP);
+    return sections.join('\n\n');
+}
+// ---- Parsing ----------------------------------------------------------------
+/** First two non-option tokens are the module and command names. */
+function findTargets(argv) {
+    const targets = [];
+    for (let index = 0; index < argv.length && targets.length < 2; index++) {
+        const token = argv[index];
+        if (token === '--') {
+            break;
+        }
+        if (token === '--timeout') {
+            index++;
+            continue;
+        }
+        if (!token.startsWith('-')) {
+            targets.push(token);
+        }
+    }
+    return targets;
+}
+function convert(arg, raw) {
+    const flag = `--${kebab(arg.name)}`;
+    if (arg.type === 'boolean') {
+        return raw;
+    }
+    const value = String(raw);
+    if (arg.choices && !arg.choices.includes(value)) {
+        throw new UsageError(`${flag} must be one of: ${arg.choices.join(', ')} (got '${value}')`);
+    }
+    switch (arg.type) {
+        case 'int': {
+            if (!/^-?\d+$/.test(value)) {
+                throw new UsageError(`${flag} must be an integer (got '${value}')`);
+            }
+            return Number(value);
+        }
+        case 'number': {
+            const parsed = Number(value);
+            if (value.trim() === '' || Number.isNaN(parsed)) {
+                throw new UsageError(`${flag} must be a number (got '${value}')`);
+            }
+            return parsed;
+        }
+        case 'list':
+            return value
+                .split(',')
+                .map((part) => part.trim())
+                .filter(Boolean);
+        case 'int-list':
+            return value
+                .split(',')
+                .map((part) => part.trim())
+                .filter(Boolean)
+                .map((part) => {
+                if (!/^-?\d+$/.test(part)) {
+                    throw new UsageError(`${flag} must be comma-separated integers`);
+                }
+                return Number(part);
+            });
+        case 'json':
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                throw new UsageError(`${flag} must be valid JSON`);
+            }
+        default:
+            return value;
+    }
+}
+function parseCommand(argv, cmd) {
+    const commandOptions = {};
+    for (const arg of cmd?.args ?? []) {
+        commandOptions[kebab(arg.name)] = {
+            type: arg.type === 'boolean' ? 'boolean' : 'string',
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            allowNegative: true,
+            strict: true,
+            options: { ...GLOBAL_OPTIONS, ...commandOptions },
+        });
+    }
+    catch (err) {
+        throw new UsageError(err.message);
+    }
+    const raw = parsed.values;
+    const globals = {};
+    for (const key of Object.keys(GLOBAL_OPTIONS)) {
+        globals[key] = raw[key];
+    }
+    if (globals.help || !cmd) {
+        return { globals, values: {} };
+    }
+    // Drop the module and command names; the rest fill required args in order.
+    const extra = parsed.positionals.slice(2);
+    const values = {};
+    for (const arg of cmd.args) {
+        const flagValue = raw[kebab(arg.name)];
+        if (flagValue !== undefined) {
+            values[arg.name] = convert(arg, flagValue);
+        }
+        else if (arg.required && extra.length > 0) {
+            values[arg.name] = convert(arg, extra.shift());
+        }
+    }
+    if (extra.length > 0) {
+        throw new UsageError(`unexpected argument '${extra[0]}'`);
+    }
+    const missing = cmd.args.filter((arg) => arg.required && values[arg.name] === undefined);
+    if (missing.length > 0) {
+        throw new UsageError(`missing required argument${missing.length > 1 ? 's' : ''}: ${missing
+            .map((arg) => `<${kebab(arg.name)}>`)
+            .join(', ')}`);
+    }
+    return { globals, values };
+}
+function clientOptions(globals) {
+    const options = {};
+    if (globals.debug) {
+        options.debug = true;
+    }
+    if (globals['follow-redirects'] === false) {
+        options.followRedirects = false;
+    }
+    if (globals.timeout !== undefined) {
+        const timeout = Number(globals.timeout);
+        if (!(timeout > 0)) {
+            throw new UsageError(`--timeout must be a positive number of seconds (got '${globals.timeout}')`);
+        }
+        options.timeout = timeout;
+    }
+    return options;
+}
+// ---- Entry ------------------------------------------------------------------
+/** Runs the CLI and resolves with the process exit code. */
+export async function runCli(argv, io) {
+    const createClient = io.createClient ?? createNHLClient;
+    const [moduleName, commandName] = findTargets(argv);
+    const mod = MODULES.find((moduleSpec) => moduleSpec.name === moduleName);
+    const cmd = mod?.commands.find((command) => command.name === commandName);
+    const usageError = (message, help) => {
+        io.stderr(`${colors.error(`error: ${message}`)}\n\n${help}`);
+        return 2;
+    };
+    let parsed;
+    try {
+        parsed = parseCommand(argv, cmd);
+    }
+    catch (err) {
+        const help = cmd && mod ? commandHelp(mod, cmd) : mod ? moduleHelp(mod) : rootHelp();
+        return usageError(err.message, help);
+    }
+    const { globals, values } = parsed;
+    if (globals.version) {
+        io.stdout(version());
+        return 0;
+    }
+    if (!moduleName) {
+        if (globals.help) {
+            io.stdout(rootHelp());
+            return 0;
+        }
+        return usageError('missing <module>', rootHelp());
+    }
+    if (!mod) {
+        return usageError(`unknown module '${moduleName}'`, rootHelp());
+    }
+    if (!commandName) {
+        if (globals.help) {
+            io.stdout(moduleHelp(mod));
+            return 0;
+        }
+        return usageError('missing <command>', moduleHelp(mod));
+    }
+    if (!cmd) {
+        return usageError(`unknown command '${commandName}' for module '${mod.name}'`, moduleHelp(mod));
+    }
+    if (globals.help) {
+        io.stdout(commandHelp(mod, cmd));
+        return 0;
+    }
+    try {
+        const client = createClient(clientOptions(globals));
+        const result = await cmd.run(client, values);
+        io.stdout(globals.compact
+            ? JSON.stringify(result)
+            : JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof UsageError || err instanceof RangeError) {
+            return usageError(err.message, commandHelp(mod, cmd));
+        }
+        if (err instanceof NHLApiException) {
+            io.stderr(colors.error(`error: ${err.message} (HTTP ${err.statusCode})`));
+            return 1;
+        }
+        io.stderr(colors.error(`error: ${err?.message ?? String(err)}`));
+        return 1;
+    }
+}

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runCli } from '#src/cli/run.mjs';
+// Exit quietly when the reader goes away (e.g. `nhl-api-ts ... | head`).
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        process.exit(0);
+    }
+    throw err;
+});
+process.exitCode = await runCli(process.argv.slice(2), {
+    stdout: (text) => process.stdout.write(`${text}\n`),
+    stderr: (text) => process.stderr.write(`${text}\n`),
+});

package/dist/config.d.mts

@@ -0,0 +1,20 @@
+export interface ClientOptions {
+    /** Set to true for extra logging (written to stderr). Defaults to false. */
+    debug?: boolean;
+    /** Request timeout in seconds. Defaults to 10. */
+    timeout?: number;
+    /**
+     * Some endpoints use redirects. This is the case when using endpoints that
+     * use "/now" in them, which redirect to today's data. Defaults to true.
+     */
+    followRedirects?: boolean;
+    /** Overrides the fetch implementation used for requests. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface Config {
+    readonly debug: boolean;
+    readonly timeout: number;
+    readonly followRedirects: boolean;
+    readonly fetch?: typeof fetch;
+}
+export declare function resolveConfig(options?: ClientOptions): Readonly<Config>;

package/dist/config.mjs

@@ -0,0 +1,4 @@
+export function resolveConfig(options = {}) {
+    const { debug = false, timeout = 10, followRedirects = true, fetch, } = options;
+    return { debug, timeout, followRedirects, fetch };
+}

package/dist/context.d.mts

@@ -0,0 +1,6 @@
+import type { Endpoint, QueryParams } from '#src/http-client.mjs';
+export type Get = (endpoint: Endpoint, resource: string, params?: QueryParams) => Promise<Response>;
+export interface Context {
+    get: Get;
+    sleep: (seconds: number) => Promise<void>;
+}

package/dist/context.mjs

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.mts

@@ -0,0 +1,35 @@
+/** NHL API specific error codes. */
+export declare const NHLApiErrorCode: {
+    readonly RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND';
+    readonly RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED';
+    readonly SERVER_ERROR: 'SERVER_ERROR';
+    readonly BAD_REQUEST: 'BAD_REQUEST';
+    readonly UNAUTHORIZED: 'UNAUTHORIZED';
+};
+export type NHLApiErrorCode = (typeof NHLApiErrorCode)[keyof typeof NHLApiErrorCode];
+/** Base exception for NHL API errors. */
+export declare class NHLApiException extends Error {
+    readonly statusCode: number;
+    readonly errorCode?: NHLApiErrorCode;
+    constructor(message: string, statusCode: number, errorCode?: NHLApiErrorCode);
+}
+/** Raised when a resource is not found (404). */
+export declare class ResourceNotFoundException extends NHLApiException {
+    constructor(message: string, statusCode?: number);
+}
+/** Raised when rate limit is exceeded (429). */
+export declare class RateLimitExceededException extends NHLApiException {
+    constructor(message: string, statusCode?: number);
+}
+/** Raised for server errors (5xx). */
+export declare class ServerErrorException extends NHLApiException {
+    constructor(message: string, statusCode: number);
+}
+/** Raised for client errors (400). */
+export declare class BadRequestException extends NHLApiException {
+    constructor(message: string, statusCode?: number);
+}
+/** Raised for authentication errors (401). */
+export declare class UnauthorizedException extends NHLApiException {
+    constructor(message: string, statusCode?: number);
+}

package/dist/errors.mjs

@@ -0,0 +1,49 @@
+/** NHL API specific error codes. */
+export const NHLApiErrorCode = {
+    RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
+    RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+    SERVER_ERROR: 'SERVER_ERROR',
+    BAD_REQUEST: 'BAD_REQUEST',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+};
+/** Base exception for NHL API errors. */
+export class NHLApiException extends Error {
+    statusCode;
+    errorCode;
+    constructor(message, statusCode, errorCode) {
+        super(message);
+        this.name = new.target.name;
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+    }
+}
+/** Raised when a resource is not found (404). */
+export class ResourceNotFoundException extends NHLApiException {
+    constructor(message, statusCode = 404) {
+        super(message, statusCode, NHLApiErrorCode.RESOURCE_NOT_FOUND);
+    }
+}
+/** Raised when rate limit is exceeded (429). */
+export class RateLimitExceededException extends NHLApiException {
+    constructor(message, statusCode = 429) {
+        super(message, statusCode, NHLApiErrorCode.RATE_LIMIT_EXCEEDED);
+    }
+}
+/** Raised for server errors (5xx). */
+export class ServerErrorException extends NHLApiException {
+    constructor(message, statusCode) {
+        super(message, statusCode, NHLApiErrorCode.SERVER_ERROR);
+    }
+}
+/** Raised for client errors (400). */
+export class BadRequestException extends NHLApiException {
+    constructor(message, statusCode = 400) {
+        super(message, statusCode, NHLApiErrorCode.BAD_REQUEST);
+    }
+}
+/** Raised for authentication errors (401). */
+export class UnauthorizedException extends NHLApiException {
+    constructor(message, statusCode = 401) {
+        super(message, statusCode, NHLApiErrorCode.UNAUTHORIZED);
+    }
+}

package/dist/http-client.d.mts

@@ -0,0 +1,27 @@
+import type { Config } from '#src/config.mjs';
+import type { Get } from '#src/context.mjs';
+import { NHLApiException } from '#src/errors.mjs';
+export declare const Endpoint: {
+    readonly API_WEB_V1: 'https://api-web.nhle.com/v1/';
+    readonly API_CORE: 'https://api.nhle.com/';
+    readonly API_STATS: 'https://api.nhle.com/stats/rest/';
+};
+export type Endpoint = (typeof Endpoint)[keyof typeof Endpoint];
+export type QueryParamValue = string | number | boolean | null | undefined;
+export type QueryParams = Record<string, QueryParamValue>;
+export declare function buildUrl(endpoint: Endpoint, resource: string, queryParams?: QueryParams): string;
+/** Maps a non-2xx HTTP status to the matching NHLApiException subclass. */
+export declare function errorForStatus(status: number, message: string): NHLApiException;
+/** Builds the error message for a non-2xx response, sniffing a JSON `message` field. */
+export declare function readErrorMessage(response: Response, url: string): Promise<string>;
+/**
+ * Builds a `Get` function bound to the given config.
+ *
+ * @throws ResourceNotFoundException When the resource is not found
+ * @throws RateLimitExceededException When rate limit is exceeded
+ * @throws ServerErrorException When server returns 5xx error
+ * @throws BadRequestException When request is malformed
+ * @throws UnauthorizedException When authentication fails
+ * @throws NHLApiException For other unexpected errors
+ */
+export declare function createGet(config: Config): Get;

package/dist/http-client.mjs

@@ -0,0 +1,95 @@
+import { BadRequestException, NHLApiException, RateLimitExceededException, ResourceNotFoundException, ServerErrorException, UnauthorizedException, } from '#src/errors.mjs';
+export const Endpoint = {
+    API_WEB_V1: 'https://api-web.nhle.com/v1/',
+    API_CORE: 'https://api.nhle.com/',
+    API_STATS: 'https://api.nhle.com/stats/rest/',
+};
+/** Converts a query param value the same way httpx does (True -> "true", None -> ""). */
+function paramToString(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    return String(value);
+}
+export function buildUrl(endpoint, resource, queryParams) {
+    const url = `${endpoint}${resource}`;
+    if (!queryParams) {
+        return url;
+    }
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+        search.append(key, paramToString(value));
+    }
+    const qs = search.toString();
+    if (!qs) {
+        return url;
+    }
+    return `${url}${url.includes('?') ? '&' : '?'}${qs}`;
+}
+/** Maps a non-2xx HTTP status to the matching NHLApiException subclass. */
+export function errorForStatus(status, message) {
+    if (status === 404) {
+        return new ResourceNotFoundException(message);
+    }
+    if (status === 429) {
+        return new RateLimitExceededException(message);
+    }
+    if (status === 400) {
+        return new BadRequestException(message);
+    }
+    if (status === 401) {
+        return new UnauthorizedException(message);
+    }
+    if (status >= 500 && status < 600) {
+        return new ServerErrorException(message, status);
+    }
+    return new NHLApiException(`Unexpected error: ${message}`, status);
+}
+/** Builds the error message for a non-2xx response, sniffing a JSON `message` field. */
+export async function readErrorMessage(response, url) {
+    let errorMessage = `Request to ${url} failed`;
+    try {
+        const json = await response.json();
+        if (json !== null && typeof json === 'object' && !Array.isArray(json)) {
+            const detail = json.message;
+            if (detail) {
+                errorMessage = `${errorMessage}: ${detail}`;
+            }
+        }
+    }
+    catch {
+        // Response isn't JSON or doesn't have a message field
+    }
+    return errorMessage;
+}
+/**
+ * Builds a `Get` function bound to the given config.
+ *
+ * @throws ResourceNotFoundException When the resource is not found
+ * @throws RateLimitExceededException When rate limit is exceeded
+ * @throws ServerErrorException When server returns 5xx error
+ * @throws BadRequestException When request is malformed
+ * @throws UnauthorizedException When authentication fails
+ * @throws NHLApiException For other unexpected errors
+ */
+export function createGet(config) {
+    const debug = (message) => {
+        if (config.debug) {
+            console.error(`nhl-api-ts.http_client - DEBUG - ${message}`);
+        }
+    };
+    return async (endpoint, resource, queryParams) => {
+        const fullUrl = buildUrl(endpoint, resource, queryParams);
+        debug(`GET: ${fullUrl}`);
+        const doFetch = config.fetch ?? globalThis.fetch;
+        const response = await doFetch(fullUrl, {
+            signal: AbortSignal.timeout(config.timeout * 1000),
+            redirect: config.followRedirects ? 'follow' : 'manual',
+        });
+        if (!response.ok) {
+            const message = await readErrorMessage(response, resource);
+            throw errorForStatus(response.status, message);
+        }
+        return response;
+    };
+}

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+export type { EdgePlayerParams, EdgeSeasonParams, EdgeTeamParams, } from '#src/api/edge.mjs';
+export * as edge from '#src/api/edge.mjs';
+export * as gameCenter from '#src/api/game-center.mjs';
+export * as helpers from '#src/api/helpers.mjs';
+export * as misc from '#src/api/misc.mjs';
+export * as players from '#src/api/players.mjs';
+export * from '#src/api/query/index.mjs';
+export type { DailySchedule } from '#src/api/schedule.mjs';
+export * as schedule from '#src/api/schedule.mjs';
+export { normalizeDate } from '#src/api/schedule.mjs';
+export * as standings from '#src/api/standings.mjs';
+export type { GoalieStatsSummaryParams, SkaterStatsSummaryParams, SkaterStatsWithQueryContextParams, TeamSummaryParams, } from '#src/api/stats.mjs';
+export * as stats from '#src/api/stats.mjs';
+export type { Team } from '#src/api/teams.mjs';
+export * as teams from '#src/api/teams.mjs';
+export * from '#src/config.mjs';
+export type { Context, Get } from '#src/context.mjs';
+export * from '#src/errors.mjs';
+export { buildUrl, createGet, Endpoint, type QueryParams, type QueryParamValue, } from '#src/http-client.mjs';
+export { createNHLClient, type NHLClient } from '#src/nhl-client.mjs';
+export type * from '#src/types/index.mjs';
+export type { Id } from '#src/utils.mjs';

package/dist/index.mjs

@@ -0,0 +1,15 @@
+export * as edge from '#src/api/edge.mjs';
+export * as gameCenter from '#src/api/game-center.mjs';
+export * as helpers from '#src/api/helpers.mjs';
+export * as misc from '#src/api/misc.mjs';
+export * as players from '#src/api/players.mjs';
+export * from '#src/api/query/index.mjs';
+export * as schedule from '#src/api/schedule.mjs';
+export { normalizeDate } from '#src/api/schedule.mjs';
+export * as standings from '#src/api/standings.mjs';
+export * as stats from '#src/api/stats.mjs';
+export * as teams from '#src/api/teams.mjs';
+export * from '#src/config.mjs';
+export * from '#src/errors.mjs';
+export { buildUrl, createGet, Endpoint, } from '#src/http-client.mjs';
+export { createNHLClient } from '#src/nhl-client.mjs';