{"id":49521203,"url":"https://github.com/spiflicate/nhle-api","last_synced_at":"2026-05-01T23:41:29.840Z","repository":{"id":323552543,"uuid":"1093758759","full_name":"spiflicate/nhle-api","owner":"spiflicate","description":"TypeScript wrapper for the NHLe API with simple, composable functions and full type safety","archived":false,"fork":false,"pushed_at":"2026-03-08T01:02:49.000Z","size":362,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T04:50:21.788Z","etag":null,"topics":["gamecenter","live-game-stats","nhl","nhl-api","nhl-data","nhl-edge","nhl-edge-advanced","nhl-stats","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spiflicate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"jbrudev","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-11-10T19:57:01.000Z","updated_at":"2026-02-11T03:54:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spiflicate/nhle-api","commit_stats":null,"previous_names":["spiflicate/nhle-api"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/spiflicate/nhle-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiflicate%2Fnhle-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiflicate%2Fnhle-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiflicate%2Fnhle-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiflicate%2Fnhle-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spiflicate","download_url":"https://codeload.github.com/spiflicate/nhle-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiflicate%2Fnhle-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32517232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gamecenter","live-game-stats","nhl","nhl-api","nhl-data","nhl-edge","nhl-edge-advanced","nhl-stats","typescript"],"created_at":"2026-05-01T23:41:28.940Z","updated_at":"2026-05-01T23:41:29.824Z","avatar_url":"https://github.com/spiflicate.png","language":"TypeScript","funding_links":["https://ko-fi.com/jbrudev","https://ko-fi.com/R6R01DV0JD"],"categories":[],"sub_categories":[],"readme":"# NHLe API Library\r\n\r\n[![npm version](https://img.shields.io/npm/v/nhle-api.svg)](https://www.npmjs.com/package/nhle-api)\r\n[![npm downloads](https://img.shields.io/npm/dm/nhle-api.svg)](https://www.npmjs.com/package/nhle-api)\r\n[![license](https://img.shields.io/github/license/spiflicate/nhle-api.svg)](LICENSE)\r\n\r\nA modern TypeScript wrapper around the public NHL GameCenter and EdgeStats APIs with simple, composable functions and strong TypeScript typing.\r\n\r\n## Overview\r\n\r\nThe library exposes a small, functional surface over the NHL \"Game Center\" and related APIs and ships with rich response types for all Game Center endpoints.\r\n\r\n- Written in TypeScript and published as ESM/CJS\r\n- Thin functional wrappers over official NHL API routes\r\n- Fully-typed Game Center responses (game, team, player, draft, misc)\r\n- Simple environment-based configuration for timeouts, language and logging\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install nhle-api\r\n```\r\n\r\nThe package ships both ESM and CJS builds; use standard `import`/`require` according to your toolchain.\r\n\r\n## Quick Start\r\n\r\nThe primary entrypoint is the Game Center API namespace `gc`:\r\n\r\n```ts\r\nimport { gc } from 'nhle-api';\r\n\r\n// Get game landing page data\r\nconst gameInfo = await gc.game.landing(2023020001);\r\n\r\n// Get live play-by-play\r\nconst playByPlay = await gc.game.playByPlay(2023020001);\r\n\r\n// Get boxscore\r\nconst boxscore = await gc.game.boxscore(2023020001);\r\n\r\n// Get today's scores\r\nconst scores = await gc.score(new Date());\r\n\r\n// Get current scoreboard\r\nconst scoreboard = await gc.scoreboard();\r\n\r\n// Get team roster\r\nconst roster = await gc.team.roster('TOR');\r\n\r\n// Get player landing page (Connor McDavid)\r\nconst player = await gc.player.landing(8478402);\r\n```\r\n\r\n## Configuration\r\n\r\nBasic behavior is configured via environment variables and the exported `envConfig` helper from `config/env`:\r\n\r\n```bash\r\n# Request timeout in milliseconds (default: 5000)\r\nexport NHLE_API_TIMEOUT=10000\r\n\r\n# Language for responses (\"en\" or \"fr\", default: \"en\")\r\nexport NHLE_API_LANGUAGE=en\r\n\r\n# Logging level: silent | error | warn | info | debug (default: \"warn\")\r\nexport NHLE_API_LOGLEVEL=debug\r\n```\r\n\r\nYou can inspect the resolved configuration at runtime:\r\n\r\n```ts\r\nimport { envConfig, logEnvConfig } from 'nhle-api';\r\n\r\nconsole.log(envConfig.timeout, envConfig.language, envConfig.logLevel);\r\nlogEnvConfig(); // logs only variables that are explicitly set\r\n```\r\n\r\nSee `docs/ENVIRONMENT_CONFIG.md` for more details.\r\n\r\n## Top-Level Exports\r\n\r\nThe package root `nhle-api` re-exports the main API namespaces, configuration utilities, constants, and public types:\r\n\r\n```ts\r\n// Game Center API (fully typed)\r\nimport { gc } from 'nhle-api';\r\n\r\n// Edge Advanced stats (in progress, API surface may change)\r\nimport { adv } from 'nhle-api';\r\n\r\n// Environment configuration helpers\r\nimport { envConfig, logEnvConfig } from 'nhle-api';\r\n\r\n// Shared type exports (Game Center response types, parameter types, etc.)\r\nimport type { GameLandingResponse } from 'nhle-api';\r\n```\r\n\r\n### Notes on Edge APIs\r\n\r\n- `adv` (Edge Advanced) is available but still considered in development, but ready for preliminary use.\r\n- The `stats` (Edge Stats) namespace is not exported at the moment and will be introduced in a future release once implementation is ready.\r\n\r\n## Game Center API (`gc`)\r\n\r\n`gc` is the primary namespace for accessing live and historical NHL data.\r\n\r\n### `gc.game` – Game Data\r\n\r\n- `playByPlay(gameId)` – Full live play-by-play event stream\r\n- `boxscore(gameId)` – Boxscore and team/player stats for a game\r\n- `landing(gameId)` – Game landing page data (summary, lines, etc.)\r\n- `reports(gameId)` – Game reports / right-rail data\r\n- `schedule(date?)` – Schedule for a given date (defaults to today)\r\n- `scheduleCalendar(date?)` – Calendar-style schedule for a date\r\n- `playoffBracket(year?)` – Playoff bracket for a given year\r\n- `playoffSeries(season?)` – Playoff series information for a season\r\n- `playoffSeriesSchedule(season, seriesLetter)` – Schedule for a playoff series\r\n- `whereToWatch()` – Regional broadcast / streaming info\r\n- `networkTVSchedule(date?)` – National TV schedule\r\n- `wsc.gameStory(gameId)` – Game story from the web service collection\r\n- `wsc.playByPlay(gameId)` – Play-by-play from the web service collection\r\n- `pptReplay.goal(gameId, eventId)` – Goal replay data for a specific event\r\n- `pptReplay.event(date?)` – Replay events for a given date (does not appear to be functional at this time)\r\n\r\n### `gc.score` – Scores \u0026 Scoreboards\r\n\r\n- `score(date?)` – Scores for a given date (defaults to today)\r\n- `scoreboard()` – Current live scoreboard\r\n\r\n### `gc.team` – Team Data\r\n\r\n- `roster(teamCode, season?)` – Team roster for a given season\r\n- `rosterSeasons(teamCode)` – Available roster seasons for a team\r\n- `prospects(teamCode)` – Team prospects\r\n- `clubStats(teamCode, season?)` – Club stats for a team/season\r\n- `clubStatsSeason(teamCode)` – Season-level club stats\r\n- `standings(date?)` – Standings for a given date\r\n- `standingsSeason()` – Season standings\r\n- `schedule.now(teamCode)` – Current schedule segment for a team\r\n- `schedule.month(teamCode, month)` – Team schedule for a given month\r\n- `schedule.season(teamCode, season)` – Full season schedule for a team\r\n\r\n### `gc.player` – Player Data\r\n\r\n- `landing(playerId)` – Player landing page data\r\n- `gameLog(playerId, season?, gameType?)` – Game log for a player\r\n- `spotlight()` – Featured players (spotlight carousel)\r\n- `search(query)` – Player search\r\n- `statsLeaders.season(season?, gameType?, category?, limit?)` – Season stat leaders\r\n- `statsLeaders.current(gameType?, category?, limit?)` – Current stat leaders\r\n\r\n### `gc.draft` – Draft Data\r\n\r\n- `picks(year?)` – Draft picks for a given year\r\n- `tracker()` – Draft tracker\r\n- `rankings(year?)` – Draft rankings (all, NA/International, skaters/goalies)\r\n\r\n### `gc.misc` – Miscellaneous\r\n\r\n- `seasons()` – All NHL seasons\r\n- `meta.game(gameId)` – Game metadata\r\n- `meta.gameVideo(gameId)` – Game video metadata\r\n- `postalLookup(postalCode)` – Postal/ZIP lookup (location info)\r\n- `location()` – Location info for current context\r\n- `partnerGame(country, date?)` – Partner game information\r\n\r\n## Types\r\n\r\nThe library exports strongly-typed response shapes and parameter types for all Game Center endpoints from the `types` bundle:\r\n\r\n- Response types for `gc.game.*`, `gc.team.*`, `gc.player.*`, `gc.draft.*`, `gc.misc.*`\r\n- Common enums and helper types (position codes, team codes, schedule state, etc.)\r\n\r\n\r\n\r\n### Error Handling and `NHLError`\r\n\r\nUnder the hood, low-level HTTP requests use a shared `NHLClient` and `ErrorHandler` which normalize HTTP/network failures into a single `NHLError` shape.\r\n\r\n- All non-2xx responses and network/timeout failures are converted to an `NHLError` instance.\r\n- Errors are categorized (client/server/network) with optional context (endpoint, method, status code).\r\n- High-level helpers expose these via the `APIResponse\u003cT\u003e` union so you can safely branch on `status` without catching exceptions.\r\n\r\nTypical usage pattern:\r\n\r\n```ts\r\nimport { gc } from 'nhle-api';\r\nimport type { APIResponse, GamecenterLanding } from 'nhle-api';\r\n\r\nconst result: APIResponse\u003cGamecenterLanding\u003e = await gc.game.landing(2023020001);\r\n\r\nif (result.success) {\r\n   console.log(result.data);\r\n} else {\r\n   // NHLError instance with rich metadata\r\n   console.error(result.error.message);\r\n}\r\n```\r\n\r\n## Roadmap / Status\r\n\r\n- ✅ Game Center endpoints fully wired with response types\r\n- ✅ Environment configuration utilities (`envConfig`, `logEnvConfig`)\r\n- ✅ Error handling via `NHLError` and structured error responses internally\r\n- 🚧 Edge Advanced (`adv`) API surface and types are in development\r\n- ⏳ Edge Stats (`stats`) API will be added in a future minor release\r\n\r\nFor a detailed list of changes and recent work on response types and endpoint coverage, see `CHANGELOG.md`.\r\n\r\n## Docs\r\n\r\n- [Environment Configuration](docs/ENVIRONMENT_CONFIG.md) - Environment configuration and default values\r\n- [Query Builder Guide](docs/QUERY_BUILDER_GUIDE.md) - Cayenne query builder for stats APIs\r\n\r\n## Contributing\r\n\r\nThis project is still evolving and feedback is very welcome.\r\n\r\n- **Bug reports / issues:** If an endpoint returns unexpected data, response parsing fails, or types don’t match the real API, please open a GitHub issue with the endpoint, parameters, and (sanitized) sample payloads if possible.\r\n- **Type improvements:** PRs or issues that improve response coverage, fix missing/incorrect fields, or refine enums and unions are particularly helpful.\r\n- **JSDoc / docs:** Additions or corrections to JSDoc on public types and functions, or clarifications to the guides in `docs/`, are also very much appreciated.\r\n\r\nBefore filing an issue, check the `CHANGELOG.md` for recent changes and breaking notes, and include the library version you’re using.\r\n\r\n## Support\r\n\r\nIf you find this library helpful, consider supporting its development:\r\n\r\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/R6R01DV0JD)\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiflicate%2Fnhle-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspiflicate%2Fnhle-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiflicate%2Fnhle-api/lists"}