nhle-api 0.5.4 → 0.6.0

package/lib/toolkit.d.ts

@@ -0,0 +1,502 @@
+import { T as TeamsEnum } from './nhl-B7Hg7iMB.js';
+export { a as CayenneCondition, c as CayenneExpression, d as CayenneGroup, C as CayenneQueryBuilder, n as NHL, b as buildCayenneExp, e as createCayenneQuery } from './nhl-B7Hg7iMB.js';
+
+/**
+ * NHL season and date utilities.
+ *
+ * These helpers define the calendar semantics used by NHL API parameters.
+ * Calendar values are evaluated in the NHL's eastern time zone
+ * (`America/New_York`), regardless of the process's local time zone. Use
+ * `getDate` and `getMonth` when converting `Date` values for API calls.
+ */
+/** Canonical timezone for NHL calendar dates and API date parameters. */
+declare const NHL_TIMEZONE = "America/New_York";
+/**
+ * Formats a date as the NHL API's `YYYY-MM-DD` calendar parameter.
+ *
+ * The calendar date is resolved in {@link NHL_TIMEZONE}, not UTC.
+ * @param date - A valid date to format.
+ * @returns The date formatted as `YYYY-MM-DD`.
+ * @throws RangeError If `date` is invalid.
+ */
+declare const getNHLDate: (date: Date) => string;
+/**
+ * Returns the current date as `YYYY-MM-DD` in the NHL eastern time zone.
+ * @returns The current date formatted as `YYYY-MM-DD`.
+ */
+declare const getCurrentNHLDate: () => string;
+/**
+ * Formats a date as the NHL API's `YYYY-MM` calendar parameter.
+ *
+ * The calendar month is resolved in {@link NHL_TIMEZONE}, not UTC.
+ * @param date - A valid date to format.
+ * @returns The month formatted as `YYYY-MM`.
+ * @throws RangeError If `date` is invalid.
+ */
+declare const getNHLMonth: (date: Date) => string;
+/**
+ * Returns the current month as `YYYY-MM` in the NHL eastern time zone.
+ * @returns The current month formatted as `YYYY-MM`.
+ */
+declare const getCurrentNHLMonth: () => string;
+/**
+ * Formats a date as `YYYY` in the NHL eastern time zone.
+ * @param date - A valid date to format.
+ * @returns The year formatted as `YYYY`.
+ * @throws RangeError If `date` is invalid.
+ */
+declare const getYear: (date: Date) => string;
+/**
+ * Returns the current year as `YYYY` in the NHL eastern time zone.
+ * @returns The current year formatted as `YYYY`.
+ */
+declare const getCurrentNHLYear: () => string;
+/**
+ * Returns the NHL season label associated with a date as `yyyyYYYY` (for
+ * example, `20232024`). The season label starts on July 1: dates from
+ * January through June belong to the season that started in the previous
+ * calendar year, while dates from July through December belong to the season
+ * starting in the current calendar year.
+ *
+ * The month is resolved in {@link NHL_TIMEZONE}.
+ * @param date - A valid `Date` or a date string accepted by the `Date` constructor.
+ * @returns The season formatted as `yyyyYYYY`.
+ * @throws RangeError If the date is invalid.
+ */
+declare const getSeason: (date: string | Date) => string;
+/**
+ * Returns the current NHL season as `yyyyYYYY` in the NHL eastern time zone.
+ * @returns The current season formatted as `yyyyYYYY`.
+ */
+declare const getCurrentSeason: () => string;
+/** Lower bound used when validating NHL API date ranges. */
+declare const NHL_START_DATE: Date;
+/**
+ * Upper bound for the current NHL season, set to June 30 of its ending year.
+ */
+declare const NHL_END_DATE: Date;
+
+declare const normalizeAbbrev: (abbrev: string) => string;
+
+/** A CSS-compatible hexadecimal team colour. */
+type TeamColor = `#${string}`;
+/** The supported NHL logo treatments. */
+type TeamLogoTheme = 'light' | 'dark';
+/** Options for building an official NHL team logo URL. */
+interface TeamLogoOptions {
+    theme?: TeamLogoTheme;
+    secondary?: boolean;
+}
+/** Current colours and identity metadata for an NHL team. */
+interface TeamBranding {
+    name: string;
+    primaryColor: TeamColor;
+    colors: Readonly<Record<string, TeamColor>>;
+}
+/** Historical colour set for a team or franchise. */
+interface HistoricalTeamColors {
+    period: string;
+    colors: Readonly<Record<string, TeamColor>>;
+}
+type ActiveTeamAbbreviation = keyof typeof TeamsEnum;
+/**
+ * Current NHL team colours.
+ *
+ * Values are based on the local NHL colour-code research dataset. The first
+ * value in each `colors` object is the team's primary brand colour.
+ */
+declare const TEAM_BRANDING: {
+    readonly ANA: {
+        readonly name: "Anaheim Ducks";
+        readonly primaryColor: "#F47A38";
+        readonly colors: {
+            readonly orange: "#F47A38";
+            readonly metallicGold: "#B9975B";
+            readonly silver: "#C1C6C8";
+            readonly black: "#000000";
+        };
+    };
+    readonly BOS: {
+        readonly name: "Boston Bruins";
+        readonly primaryColor: "#FFB81C";
+        readonly colors: {
+            readonly gold: "#FFB81C";
+            readonly black: "#000000";
+        };
+    };
+    readonly BUF: {
+        readonly name: "Buffalo Sabres";
+        readonly primaryColor: "#003087";
+        readonly colors: {
+            readonly royalBlue: "#003087";
+            readonly gold: "#FFB81C";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly CGY: {
+        readonly name: "Calgary Flames";
+        readonly primaryColor: "#D2001C";
+        readonly colors: {
+            readonly red: "#D2001C";
+            readonly yellow: "#FAAF19";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly CAR: {
+        readonly name: "Carolina Hurricanes";
+        readonly primaryColor: "#CE1126";
+        readonly colors: {
+            readonly red: "#CE1126";
+            readonly white: "#FFFFFF";
+            readonly gray: "#A4A9AD";
+            readonly black: "#000000";
+        };
+    };
+    readonly CHI: {
+        readonly name: "Chicago Blackhawks";
+        readonly primaryColor: "#CF0A2C";
+        readonly colors: {
+            readonly red: "#CF0A2C";
+            readonly orange: "#FF671B";
+            readonly green: "#00833E";
+            readonly yellow: "#FFD100";
+            readonly tan: "#D18A00";
+            readonly blue: "#001970";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly COL: {
+        readonly name: "Colorado Avalanche";
+        readonly primaryColor: "#6F263D";
+        readonly colors: {
+            readonly burgundy: "#6F263D";
+            readonly blue: "#236192";
+            readonly silver: "#A2AAAD";
+            readonly black: "#000000";
+        };
+    };
+    readonly CBJ: {
+        readonly name: "Columbus Blue Jackets";
+        readonly primaryColor: "#002654";
+        readonly colors: {
+            readonly unionBlue: "#002654";
+            readonly goalRed: "#CE1126";
+            readonly capitalSilver: "#A4A9AD";
+        };
+    };
+    readonly DAL: {
+        readonly name: "Dallas Stars";
+        readonly primaryColor: "#006847";
+        readonly colors: {
+            readonly victoryGreen: "#006847";
+            readonly silver: "#8F8F8C";
+            readonly black: "#111111";
+        };
+    };
+    readonly DET: {
+        readonly name: "Detroit Red Wings";
+        readonly primaryColor: "#CE1126";
+        readonly colors: {
+            readonly red: "#CE1126";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly EDM: {
+        readonly name: "Edmonton Oilers";
+        readonly primaryColor: "#041E42";
+        readonly colors: {
+            readonly blue: "#041E42";
+            readonly orange: "#FF4C00";
+        };
+    };
+    readonly FLA: {
+        readonly name: "Florida Panthers";
+        readonly primaryColor: "#041E42";
+        readonly colors: {
+            readonly navy: "#041E42";
+            readonly red: "#C8102E";
+            readonly tan: "#B9975B";
+        };
+    };
+    readonly LAK: {
+        readonly name: "Los Angeles Kings";
+        readonly primaryColor: "#111111";
+        readonly colors: {
+            readonly black: "#111111";
+            readonly silver: "#A2AAAD";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly MIN: {
+        readonly name: "Minnesota Wild";
+        readonly primaryColor: "#A6192E";
+        readonly colors: {
+            readonly ironRangeRed: "#A6192E";
+            readonly forestGreen: "#154734";
+            readonly gold: "#EAAA00";
+            readonly minnesotaWheat: "#DDCBA4";
+        };
+    };
+    readonly MTL: {
+        readonly name: "Montreal Canadiens";
+        readonly primaryColor: "#AF1E2D";
+        readonly colors: {
+            readonly red: "#AF1E2D";
+            readonly blue: "#192168";
+        };
+    };
+    readonly NJD: {
+        readonly name: "New Jersey Devils";
+        readonly primaryColor: "#CE1126";
+        readonly colors: {
+            readonly red: "#CE1126";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly NSH: {
+        readonly name: "Nashville Predators";
+        readonly primaryColor: "#FFB81C";
+        readonly colors: {
+            readonly gold: "#FFB81C";
+            readonly navyBlue: "#041E42";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly NYI: {
+        readonly name: "New York Islanders";
+        readonly primaryColor: "#00539B";
+        readonly colors: {
+            readonly blue: "#00539B";
+            readonly orange: "#F47D30";
+        };
+    };
+    readonly NYR: {
+        readonly name: "New York Rangers";
+        readonly primaryColor: "#0038A8";
+        readonly colors: {
+            readonly blue: "#0038A8";
+            readonly red: "#CE1126";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly OTT: {
+        readonly name: "Ottawa Senators";
+        readonly primaryColor: "#000000";
+        readonly colors: {
+            readonly black: "#000000";
+            readonly red: "#DA1A32";
+            readonly gold: "#B79257";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly PHI: {
+        readonly name: "Philadelphia Flyers";
+        readonly primaryColor: "#F74902";
+        readonly colors: {
+            readonly flyersOrange: "#F74902";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly PIT: {
+        readonly name: "Pittsburgh Penguins";
+        readonly primaryColor: "#000000";
+        readonly colors: {
+            readonly black: "#000000";
+            readonly gold: "#CFC493";
+            readonly yellow: "#FCB514";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly SJS: {
+        readonly name: "San Jose Sharks";
+        readonly primaryColor: "#006D75";
+        readonly colors: {
+            readonly teal: "#006D75";
+            readonly orange: "#EA7200";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly SEA: {
+        readonly name: "Seattle Kraken";
+        readonly primaryColor: "#001628";
+        readonly colors: {
+            readonly deepSeaBlue: "#001628";
+            readonly iceBlue: "#99D9D9";
+            readonly boundlessBlue: "#355464";
+            readonly shadowBlue: "#68A2B9";
+            readonly redAlert: "#E9072B";
+        };
+    };
+    readonly STL: {
+        readonly name: "St. Louis Blues";
+        readonly primaryColor: "#002F87";
+        readonly colors: {
+            readonly blue: "#002F87";
+            readonly yellow: "#FCB514";
+            readonly navyBlue: "#041E42";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly TBL: {
+        readonly name: "Tampa Bay Lightning";
+        readonly primaryColor: "#002868";
+        readonly colors: {
+            readonly blue: "#002868";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly TOR: {
+        readonly name: "Toronto Maple Leafs";
+        readonly primaryColor: "#00205B";
+        readonly colors: {
+            readonly blue: "#00205B";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly UTA: {
+        readonly name: "Utah Mammoth";
+        readonly primaryColor: "#69B3E7";
+        readonly colors: {
+            readonly mountainBlue: "#69B3E7";
+            readonly rockBlack: "#010101";
+            readonly saltWhite: "#FFFFFF";
+        };
+    };
+    readonly VAN: {
+        readonly name: "Vancouver Canucks";
+        readonly primaryColor: "#00205B";
+        readonly colors: {
+            readonly blue: "#00205B";
+            readonly green: "#00843D";
+            readonly darkBlue: "#041C2C";
+            readonly gray: "#99999A";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly VGK: {
+        readonly name: "Vegas Golden Knights";
+        readonly primaryColor: "#B4975A";
+        readonly colors: {
+            readonly gold: "#B4975A";
+            readonly steelGray: "#333F42";
+            readonly red: "#C8102E";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly WSH: {
+        readonly name: "Washington Capitals";
+        readonly primaryColor: "#041E42";
+        readonly colors: {
+            readonly navy: "#041E42";
+            readonly red: "#C8102E";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly WPG: {
+        readonly name: "Winnipeg Jets";
+        readonly primaryColor: "#041E42";
+        readonly colors: {
+            readonly navy: "#041E42";
+            readonly blue: "#004C97";
+            readonly red: "#AC162C";
+            readonly maroon: "#7B303E";
+            readonly darkGray: "#55565A";
+            readonly silver: "#8E9090";
+            readonly white: "#FFFFFF";
+        };
+    };
+};
+/** Historical colour palettes included in the local research dataset. */
+declare const HISTORICAL_TEAM_COLORS: {
+    readonly ANA: {
+        readonly period: "1993-2006";
+        readonly colors: {
+            readonly green: "#00685E";
+            readonly purple: "#532A44";
+            readonly yellow: "#FCC72C";
+            readonly black: "#241E24";
+        };
+    };
+    readonly ARI: {
+        readonly period: "1996-2014";
+        readonly colors: {
+            readonly brickRed: "#8C2633";
+            readonly green: "#154734";
+            readonly desertSand: "#DDCBA4";
+            readonly brown: "#A9431E";
+            readonly purple: "#5F259F";
+        };
+    };
+    readonly BUF: {
+        readonly period: "2006-2020";
+        readonly colors: {
+            readonly navyBlue: "#002654";
+            readonly yellow: "#FCB514";
+            readonly silver: "#ADAFAA";
+            readonly red: "#C8102E";
+        };
+    };
+    readonly CGY: {
+        readonly period: "1994-2020";
+        readonly colors: {
+            readonly red: "#C8102E";
+            readonly gold: "#F1BE48";
+            readonly black: "#111111";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly LAK: {
+        readonly period: "1967-1988";
+        readonly colors: {
+            readonly purple: "#572A84";
+            readonly goldenYellow: "#FFC80C";
+            readonly white: "#FFFFFF";
+        };
+    };
+    readonly OTT: {
+        readonly period: "2007-2020";
+        readonly colors: {
+            readonly red: "#C52032";
+            readonly gold: "#C2912C";
+            readonly black: "#000000";
+            readonly white: "#FFFFFF";
+        };
+    };
+};
+/**
+ * Returns current branding for an active team abbreviation.
+ *
+ * Alternate abbreviations such as `TB`, `LA`, and `UTAH` are normalized before
+ * lookup. Returns `undefined` for unknown or inactive abbreviations.
+ */
+declare function getTeamBranding(abbreviation: string): (typeof TEAM_BRANDING)[ActiveTeamAbbreviation] | undefined;
+/**
+ * Builds an official NHL SVG logo URL for an active team.
+ *
+ * @throws {RangeError} If `abbreviation` is not an active NHL team.
+ */
+declare function getTeamLogoUrl(abbreviation: string, options?: TeamLogoOptions): string;
+
+/**
+ * Resolves a path template by replacing placeholders with actual values from the params object.
+ * Placeholders in the template should be in the format `{key}` where `key` corresponds to a key in the params object.
+ * If a value in params is undefined, the placeholder will not be replaced.
+ *
+ * @param template - The path template containing placeholders (e.g., '/teams/{team}/stats')
+ * @param params - An object mapping placeholder keys to their replacement values (e.g., { team: 'TOR' })
+ * @returns The resolved path with placeholders replaced by actual values (e.g., '/teams/TOR/stats')
+ *
+ * @example
+ * const pathTemplate = '/teams/{team}/stats';
+ * const params = { team: 'TOR' };
+ * const resolvedPath = resolvePath(pathTemplate, params);
+ * console.log(resolvedPath); // Output: '/teams/TOR/stats'
+ */
+declare function resolvePath(template: string, params: Record<string, string | number | undefined>): string;
+
+export { HISTORICAL_TEAM_COLORS, type HistoricalTeamColors, NHL_END_DATE, NHL_START_DATE, NHL_TIMEZONE, TEAM_BRANDING, type TeamBranding, type TeamColor, type TeamLogoOptions, type TeamLogoTheme, getCurrentNHLDate, getCurrentNHLMonth, getCurrentNHLYear, getCurrentSeason, getNHLDate, getNHLMonth, getSeason, getTeamBranding, getTeamLogoUrl, getYear, normalizeAbbrev, resolvePath };