nhl

Documentation

Overview

Package nhl is the library behind the nhl command line: the HTTP client, request shaping, and the typed data models for the NHL API.

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, url string) ([]byte, error)
  • func (c *Client) GetPlayer(ctx context.Context, id string) (*Player, error)
  • func (c *Client) GetRoster(ctx context.Context, team, season string) ([]*RosterPlayer, error)
  • func (c *Client) GetSchedule(ctx context.Context, date string) ([]*Game, error)
  • func (c *Client) GetStandings(ctx context.Context, date string) ([]*Standing, error)
• type Config
  • func DefaultConfig() Config
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Game
• type Player
• type RosterPlayer
• type Standing

Constants

const BaseURL = "https://api-web.nhle.com/v1"

BaseURL is the root every request is built from.

const DefaultUserAgent = "nhl-cli/dev (+https://github.com/tamnd/nhl-cli)"

DefaultUserAgent identifies the client to the NHL API. A real, honest User-Agent is both polite and the thing most likely to keep you unblocked.

const Host = "api-web.nhle.com"

Host is the site this client talks to, and the host the URI driver in domain.go claims.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to the NHL API over HTTP.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults.

func (*Client) Get

func (c *Client) Get(ctx context.Context, url string) ([]byte, error)

Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.

func (*Client) GetPlayer

func (c *Client) GetPlayer(ctx context.Context, id string) (*Player, error)

GetPlayer fetches the player landing page by player ID.

func (*Client) GetRoster

func (c *Client) GetRoster(ctx context.Context, team, season string) ([]*RosterPlayer, error)

GetRoster fetches the NHL roster for the given team and season.

func (*Client) GetSchedule

func (c *Client) GetSchedule(ctx context.Context, date string) ([]*Game, error)

GetSchedule fetches the NHL schedule for the week containing the given date.

func (*Client) GetStandings

func (c *Client) GetStandings(ctx context.Context, date string) ([]*Standing, error)

GetStandings fetches the NHL standings for the given date (YYYY-MM-DD).

type Config

type Config struct {
	UserAgent string
	Rate      time.Duration
	Retries   int
	Timeout   time.Duration
}

Config holds per-client tunables.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults: a 30s timeout, a 200ms minimum gap between requests, and five retries on transient errors.

type Domain

type Domain struct{}

Domain is the NHL driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id).

• 3-letter uppercase team code → ("team", code)
• numeric string → ("player", id)
• date-like YYYY-MM-DD → ("date", date)
• otherwise → ("player", input)

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Game

type Game struct {
	ID        int    `kit:"id" json:"id"`
	Date      string `json:"date"`
	HomeTeam  string `json:"home_team"`
	AwayTeam  string `json:"away_team"`
	HomeScore int    `json:"home_score"`
	AwayScore int    `json:"away_score"`
	State     string `json:"state"`
	Venue     string `json:"venue"`
}

Game is a single scheduled game or score result.

type Player

type Player struct {
	ID       int    `kit:"id" json:"id"`
	Name     string `json:"name"`
	Number   int    `json:"number"`
	Position string `json:"position"`
	Team     string `json:"team"`
	GP       int    `json:"games_played"`
	Goals    int    `json:"goals"`
	Assists  int    `json:"assists"`
	Points   int    `json:"points"`
}

Player is a single player's full profile with career stats.

type RosterPlayer

type RosterPlayer struct {
	ID           int    `kit:"id" json:"id"`
	Name         string `json:"name"` // firstName.default + " " + lastName.default
	Number       int    `json:"number"`
	Position     string `json:"position"`
	HeightIn     int    `json:"height_in"`
	WeightLbs    int    `json:"weight_lbs"`
	BirthDate    string `json:"birth_date"`
	BirthCountry string `json:"birth_country"`
}

RosterPlayer is a single player in a team's roster.

type Standing

type Standing struct {
	TeamName     string `kit:"id" json:"team_name"`
	Abbrev       string `json:"abbrev"`
	GP           int    `json:"games_played"`
	Wins         int    `json:"wins"`
	Losses       int    `json:"losses"`
	OTLosses     int    `json:"ot_losses"`
	Points       int    `json:"points"`
	GoalsFor     int    `json:"goals_for"`
	GoalsAgainst int    `json:"goals_against"`
	Clinch       string `json:"clinch"` // clinchIndicator e.g. "x", "y", or ""
}

Standing is one team's row in the NHL standings.