people.go

package mlb

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	"github.com/pmurley/go-mlb/models"
)

// PeopleService provides methods for accessing people-related endpoints
// of the MLB Stats API.
type PeopleService struct {
	client *internalClient
}

// Get returns the person with the given personID.
// It wraps GET /api/v1/people/{personId}.
//
// Returns nil, nil if the API returns an empty people array for the given ID.
// Common options: WithHydrate, WithAccent, WithFields.
func (s *PeopleService) Get(ctx context.Context, personID int, opts ...RequestOption) (*models.Person, error) {
	body, err := s.client.do(ctx, http.MethodGet, fmt.Sprintf("v1/people/%d", personID), opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PeopleResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people response: %w", err)
	}

	if len(resp.People) == 0 {
		return nil, nil
	}

	return &resp.People[0], nil
}

// List returns biographical data for multiple people by their IDs.
// It wraps GET /api/v1/people?personIds=...
//
// Common options: WithHydrate, WithAccent, WithFields.
func (s *PeopleService) List(ctx context.Context, personIDs []int, opts ...RequestOption) ([]models.Person, error) {
	opts = append([]RequestOption{WithPersonIDs(personIDs...)}, opts...)
	body, err := s.client.do(ctx, http.MethodGet, "v1/people", opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PeopleResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people response: %w", err)
	}

	return resp.People, nil
}

// Search searches for people by name and filters. Returns at most 50 results
// (hard API cap). It wraps GET /api/v1/people/search.
//
// Common options: WithNames, WithActiveStatus, WithSportID, WithTeamID,
// WithSeasons, WithLimit, WithHydrate, WithAccent, WithFields.
func (s *PeopleService) Search(ctx context.Context, opts ...RequestOption) ([]models.Person, error) {
	body, err := s.client.do(ctx, http.MethodGet, "v1/people/search", opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PeopleResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people search response: %w", err)
	}

	return resp.People, nil
}

// Stats returns statistical data for the given person. The stats request option
// is required by the API — use WithStatType to specify which stat types to retrieve.
// It wraps GET /api/v1/people/{personId}/stats.
//
// Common options: WithStatType (required), WithStatGroup, WithSeason, WithSeasons,
// WithGameType, WithStartDate, WithEndDate, WithDaysBack, WithGamesBack,
// WithOpposingTeamID, WithOpposingPlayerID, WithSitCodes, WithLimit,
// WithGroupBy, WithHydrate, WithFields.
func (s *PeopleService) Stats(ctx context.Context, personID int, opts ...RequestOption) ([]models.PersonStat, error) {
	body, err := s.client.do(ctx, http.MethodGet, fmt.Sprintf("v1/people/%d/stats", personID), opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PersonStatsResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people stats response: %w", err)
	}

	return resp.Stats, nil
}

// GameStats returns a person's stats for a specific game.
// It wraps GET /api/v1/people/{personId}/stats/game/{gamePk}.
//
// Common options: WithStatGroup, WithFields.
func (s *PeopleService) GameStats(ctx context.Context, personID int, gamePk int, opts ...RequestOption) ([]models.PersonStat, error) {
	body, err := s.client.do(ctx, http.MethodGet, fmt.Sprintf("v1/people/%d/stats/game/%d", personID, gamePk), opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PersonStatsResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people game stats response: %w", err)
	}

	return resp.Stats, nil
}

// Awards returns all awards for the given person.
// It wraps GET /api/v1/people/{personId}/awards.
//
// Returns an empty slice (not an error) if the person has no awards or doesn't exist.
// Common options: WithFields.
func (s *PeopleService) Awards(ctx context.Context, personID int, opts ...RequestOption) ([]models.Award, error) {
	body, err := s.client.do(ctx, http.MethodGet, fmt.Sprintf("v1/people/%d/awards", personID), opts...)
	if err != nil {
		return nil, err
	}

	var resp models.AwardsResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling awards response: %w", err)
	}

	return resp.Awards, nil
}

// FreeAgents returns free agent signings and declarations for the given season.
// It wraps GET /api/v1/people/freeAgents.
//
// Common options: WithOrder, WithAccent, WithFields.
func (s *PeopleService) FreeAgents(ctx context.Context, season int, opts ...RequestOption) ([]models.FreeAgent, error) {
	opts = append([]RequestOption{WithSeason(season)}, opts...)
	body, err := s.client.do(ctx, http.MethodGet, "v1/people/freeAgents", opts...)
	if err != nil {
		return nil, err
	}

	var resp models.FreeAgentsResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling free agents response: %w", err)
	}

	return resp.FreeAgents, nil
}

// Changes returns a change log of updated person records since the given timestamp.
// It wraps GET /api/v1/people/changes.
//
// Common options: WithLimit, WithOffset, WithAccent, WithFields.
func (s *PeopleService) Changes(ctx context.Context, updatedSince time.Time, opts ...RequestOption) ([]models.Person, error) {
	opts = append([]RequestOption{WithQueryParam("updatedSince", updatedSince.Format(time.RFC3339))}, opts...)
	body, err := s.client.do(ctx, http.MethodGet, "v1/people/changes", opts...)
	if err != nil {
		return nil, err
	}

	var resp models.PeopleResponse
	if err := json.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("mlb: unmarshaling people changes response: %w", err)
	}

	return resp.People, nil
}