espn_pub 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dee5305666108de85913d5ef82a426b3e43c7c011833c4f9f0be06d9ebb6ae6
-  data.tar.gz: aa60cb29dbfe5abba1e77b75bc96fe4b4bb6cb90c00318ff59934b5171528898
+  metadata.gz: 39ccc2c710cc3da7638c7b0471a14a091007afe60eb54d9c7ff82c4c2cebdff2
+  data.tar.gz: 3fc94b08470f001ac7bf59ef5d44910c3f981e8a6934eddfa49ba68633a80e7a
 SHA512:
-  metadata.gz: ca5aeb78fe7c56960d27a55e58e4763652527dece17663cf02e5847fd73349f9aa7d1293db8d8b7751c0d250d3a4b065ee1c3e98a8774f73719829fd1a36e87a
-  data.tar.gz: a5dc7c9b283be22e3d2813955e122fd0916a9fec69821f551016957a139ce55f1fd55b6cbb745773857b4f1216ed5d49080200472102c6360e4bc4aa6b26ab6f
+  metadata.gz: e1888c3976d0013fb1f8ed12013ca16e320a46135c3666324870cd3ab4d2913223b6f2c536f571067deb660e924a2bdddae5f67da440b9007743112ad447e736
+  data.tar.gz: 983e4c30d6e86a00a7ddab38cf56b905abb7e9b7fdbfb2e9ea9bdb5f59c3391e3ad2c3938d70645aadddbae7094f4e6c7c3a6bb111e308bc1a3fe4105f834197

data/README.md

@@ -1 +1,116 @@
-# espn-pub-rb
+# espn-pub-rb
+
+`espn_pub` is a lightweight Ruby client for the public ESPN API. It provides a simple interface for fetching league teams, team rosters, players, and game scoreboards.
+
+## Features
+
+- Fetch NBA and NFL teams
+- Retrieve team rosters and player metadata
+- Query league scoreboards for a specific date
+- Wraps ESPN public API endpoints with Ruby objects
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'espn_pub'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly with:
+
+```bash
+gem install espn_pub
+```
+
+## Requirements
+
+- Ruby `>= 3.3.0`
+
+## Usage
+
+Require the gem and instantiate entities directly:
+
+```ruby
+require 'espn_pub'
+
+league = EspnPub::Entities::League.new(EspnPub::Entities::League::NAME::NBA)
+```
+
+### Fetch teams for a league
+
+```ruby
+teams = league.teams
+puts teams.map(&:name)
+```
+
+### Fetch a team's roster
+
+```ruby
+team = teams.first
+players = team.players
+players.each do |player|
+  puts "#{player.full_name} (#{player.position})"
+end
+```
+
+### Fetch games for a league
+
+```ruby
+require 'date'
+
+games = league.games(date: Date.today)
+games.each do |game|
+  puts "Game ID: #{game.id} | Home: #{game.home_team_id} | Away: #{game.away_team_id} | Date: #{game.date}"
+end
+```
+
+### Use the raw client directly
+
+```ruby
+client = EspnPub::Client.new(
+  base_uri: EspnPub::Client::BASE_URI,
+  version: EspnPub::Client::API_VERSION
+)
+
+response = client.send_request('/apis/site/v2/sports/basketball/nba/teams')
+puts response['sports'][0]['leagues'][0]['teams'].map { |team| team.dig('team', 'name') }
+```
+
+## Error handling
+
+The client raises `EspnPub::Client::UnexpectedResponseCodeError` when the API response status is not `200`.
+
+```ruby
+begin
+  client.send_request('/invalid/path')
+rescue EspnPub::Client::UnexpectedResponseCodeError => e
+  warn "API request failed: #{e.message}"
+end
+```
+
+## Development
+
+Clone the repository and install development dependencies:
+
+```bash
+git clone https://github.com/bowmanje/espn-pub-rb.git
+cd espn-pub-rb
+bundle install
+```
+
+Run the test suite with:
+
+```bash
+bundle exec rspec
+```
+
+## License
+
+`espn_pub` is licensed under the MIT License.

data/espn_pub.gemspec

@@ -14,7 +14,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.3.0'
   spec.metadata = {
     'homepage_uri' => spec.homepage,
-    'source_code_uri' => spec.homepage
+    'source_code_uri' => spec.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/espn_pub'
   }
 
   spec.files = Dir.glob('{lib,sig}/**/*', File::FNM_DOTMATCH)
@@ -22,10 +23,10 @@ Gem::Specification.new do |spec|
                %w[espn_pub.gemspec README.md]
 
   spec.require_paths = ['lib']
+  spec.add_dependency 'date', '~> 3.3'
   spec.add_dependency 'json', '~> 2.6'
   spec.add_dependency 'net-http', '~> 0.3'
   spec.add_dependency 'uri', '~> 0.11'
-  spec.add_dependency 'date', '~> 3.3'
   spec.add_development_dependency 'rake',      '~> 13.0'
   spec.add_development_dependency 'rspec',     '~> 3.13'
   spec.add_development_dependency 'rubocop',   '~> 1.65'

data/lib/espn_pub/client.rb

@@ -18,7 +18,7 @@ module EspnPub
     #
     # @param base_uri [String] The base URI for ESPN API requests.
     # @param version [String] The API version string.
-    def initialize(base_uri:, version:)
+    def initialize(base_uri: BASE_URI, version: API_VERSION)
       @uri = get_uri(base_uri)
       @version = version
     end

data/lib/espn_pub/entities/base.rb

@@ -14,15 +14,16 @@ module EspnPub
       end
 
       private
+
       # Build a new EspnPub::Client for API requests.
       #
       # @return [EspnPub::Client]
       def init_client
         EspnPub::Client.new(
           base_uri: Client::BASE_URI,
-          version: Client::API_VERSION,
+          version: Client::API_VERSION
         )
       end
     end
   end
-end
+end

data/lib/espn_pub/entities/game.rb

@@ -4,21 +4,21 @@ module EspnPub
   module Entities
     # Represents a game between two teams.
     class Game < Base
-      attr_reader :id, :home_team_id, :away_team_id, :date
+      attr_reader :id, :home_team, :away_team, :date
 
       # Initialize a Game entity.
       #
       # @param id [String] The game identifier.
-      # @param home_team_id [String] The home team identifier.
-      # @param away_team_id [String] The away team identifier.
+      # @param home_team [EspnPub::Entities::Team] The home team.
+      # @param away_team [EspnPub::Entities::Team] The away team.
       # @param date [DateTime] The scheduled game date.
-      def initialize(id:, home_team_id:, away_team_id:, date:)
+      def initialize(id:, home_team:, away_team:, date:)
         @id = id
-        @home_team_id = home_team_id
-        @away_team_id = away_team_id
+        @home_team = home_team
+        @away_team = away_team
         @date = date
         super()
       end
     end
   end
-end
+end

data/lib/espn_pub/entities/league.rb

@@ -36,7 +36,7 @@ module EspnPub
       def teams
         unless defined?(@teams)
           begin
-            path = format TEAMS_PATH, client.version, self.sport, name
+            path = format TEAMS_PATH, client.version, sport, name
             teams_resp = client.send_request(path)
             @teams = (teams_resp.dig('sports', 0, 'leagues', 0, 'teams') || []).map do |team_data|
               EspnPub::Entities::Team.new(
@@ -62,22 +62,28 @@ module EspnPub
       # @param date [Date, DateTime, nil] An optional date to filter games.
       # @return [Array<EspnPub::Entities::Game>]
       def games(date: nil)
-        begin
-          path = format GAMES_PATH, client.version, self.sport, name
-          path += "?dates=#{date.strftime('%Y%m%d')}" if date
-          games_resp = client.send_request(path)
-          (games_resp.dig('events') || []).map do |game_data|
-            EspnPub::Entities::Game.new(
-              id: game_data['id'],
-              home_team_id: game_data.dig('competitions', 0, 'competitors', 0, 'id'),
-              away_team_id: game_data.dig('competitions', 0, 'competitors', 1, 'id'),
-              date: DateTime.parse(game_data['date'])
-            )
-          end
-        rescue Client::UnexpectedResponseCodeError => e
-          warn "Failed to fetch games for league #{name}: #{e.message}"
-          return []
+        path = format GAMES_PATH, client.version, sport, name
+        path += "?dates=#{date.strftime('%Y%m%d')}" if date
+        games_resp = client.send_request(path)
+        (games_resp['events'] || []).map do |game_data|
+          EspnPub::Entities::Game.new(
+            id: game_data['id'],
+            home_team: EspnPub::Entities::Team.fetch_by_id(
+              id: game_data.dig('competitions', 0, 'competitors', 0, 'id'),
+              sport: sport,
+              league: name
+            ),
+            away_team: EspnPub::Entities::Team.fetch_by_id(
+              id: game_data.dig('competitions', 0, 'competitors', 1, 'id'),
+              sport: sport,
+              league: name
+            ),
+            date: DateTime.parse(game_data['date'])
+          )
         end
+      rescue Client::UnexpectedResponseCodeError => e
+        warn "Failed to fetch games for league #{name}: #{e.message}"
+        []
       end
 
       # Return the sport name for this league.

data/lib/espn_pub/entities/player.rb

@@ -1,16 +1,27 @@
 # frozen_string_literal: true
 
+require 'date'
+
 module EspnPub
   module Entities
     # Represents a player on a team.
     class Player < Base
+      ATHLETE_PATH = '/apis/common/v3/sports/%s/%s/athletes/%s'
+
       attr_reader :id,
                   :sport,
                   :league,
                   :first_name,
                   :last_name,
                   :position,
-                  :team_id
+                  :team_id,
+                  :date_of_birth,
+                  :birthCity,
+                  :birthState,
+                  :birthCountry,
+                  :height,
+                  :weight,
+                  :debut_year
 
       # Initialize a Player entity.
       #
@@ -21,7 +32,15 @@ module EspnPub
       # @param last_name [String, nil] The player's last name.
       # @param position [String, nil] The player's position abbreviation.
       # @param team_id [String, nil] The identifier of the player's team.
-      def initialize(id:, sport:, league:, first_name: nil, last_name: nil, position: nil, team_id: nil)
+      # @param date_of_birth [Date, nil] The player's date of birth.
+      # @param birthCity [String, nil] The player's birth city.
+      # @param birthState [String, nil] The player's birth state.
+      # @param birthCountry [String, nil] The player's birth country.
+      # @param height [String, nil] The player's listed height.
+      # @param weight [String, nil] The player's listed weight.
+      # @param debut_year [Integer, nil] The year the player made their debut.
+      def initialize(id:, sport:, league:, first_name: nil, last_name: nil, position: nil, team_id: nil,
+                     date_of_birth: nil, birthCity: nil, birthState: nil, birthCountry: nil, height: nil, weight: nil, debut_year: nil)
         @id = id
         @sport = sport
         @league = league
@@ -29,15 +48,70 @@ module EspnPub
         @last_name = last_name
         @position = position
         @team_id = team_id
+        @date_of_birth = self.class.parse_date_of_birth(date_of_birth)
+        @birthCity = birthCity
+        @birthState = birthState
+        @birthCountry = birthCountry
+        @height = height
+        @weight = weight
+        @debut_year = debut_year
         super()
       end
 
+      # Fetch a player by ID from the ESPN common v3 athlete endpoint.
+      #
+      # @param id [String] The player identifier.
+      # @param sport [String] The sport name.
+      # @param league [String] The league identifier.
+      # @return [Player, nil] The player, or nil when the request fails or data is missing.
+      def self.fetch_by_id(id:, sport:, league:)
+        client = EspnPub::Client.new
+        path = format ATHLETE_PATH, sport, league, id
+        begin
+          athlete_data = client.send_request(path)['athlete']
+        rescue Client::UnexpectedResponseCodeError => e
+          warn "Failed to fetch player data for #{id}: #{e.message}"
+          return nil
+        end
+
+        return nil unless athlete_data
+
+        new(
+          id: athlete_data['id'],
+          sport: sport,
+          league: league,
+          first_name: athlete_data['firstName'],
+          last_name: athlete_data['lastName'],
+          position: athlete_data.dig('position', 'abbreviation'),
+          team_id: athlete_data.dig('team', 'id'),
+          date_of_birth: parse_date_of_birth(athlete_data['dateOfBirth']),
+          birthCity: athlete_data.dig('birthPlace', 'city'),
+          birthState: athlete_data.dig('birthPlace', 'state'),
+          birthCountry: athlete_data.dig('birthPlace', 'country'),
+          height: athlete_data['displayHeight'],
+          weight: athlete_data['displayWeight'],
+          debut_year: athlete_data['debutYear']
+        )
+      end
+
       # Return the player's full name.
       #
       # @return [String] The player's full name.
       def full_name
-        @full_name ||= first_name + ' ' + last_name
+        @full_name ||= "#{first_name} #{last_name}"
+      end
+
+      # @param value [String, Date, nil]
+      # @return [Date, nil]
+      def self.parse_date_of_birth(value)
+        return nil unless value
+        return value if value.is_a?(Date)
+        return nil unless value.is_a?(String)
+
+        Date.parse(value)
+      rescue ArgumentError
+        nil
       end
     end
   end
-end
+end

data/lib/espn_pub/entities/team.rb

@@ -4,7 +4,7 @@ module EspnPub
   module Entities
     # Represents a sports team, eg. Miami Heat, New England Patriots, etc.
     class Team < Base
-
+      TEAM_PATH = '/apis/site/%s/sports/%s/%s/teams/%s'
       ROSTER_PATH = '/apis/site/%s/sports/%s/%s/teams/%s/roster'
 
       attr_reader :id,
@@ -12,7 +12,8 @@ module EspnPub
                   :location,
                   :abbreviation,
                   :sport,
-                  :league
+                  :league,
+                  :venue
 
       # Initialize a Team entity.
       #
@@ -22,16 +23,41 @@ module EspnPub
       # @param abbreviation [String] The team abbreviation.
       # @param sport [String] The sport name.
       # @param league [String] The league identifier.
-      def initialize(id:, name:, location:, abbreviation:, sport:, league:)
+      # @param venue [EspnPub::Entities::Venue, nil] The team's home venue.
+      def initialize(id:, name:, location:, abbreviation:, sport:, league:, venue: nil)
         @id = id
         @name = name
         @location = location
         @abbreviation = abbreviation
         @sport = sport
         @league = league
+        @venue = venue
         super()
       end
 
+      def self.fetch_by_id(id:, sport:, league:)
+        client = EspnPub::Client.new
+        path = format TEAM_PATH, client.version, sport, league, id
+        begin
+          team_data = client.send_request(path)['team']
+        rescue Client::UnexpectedResponseCodeError => e
+          warn "Failed to fetch team data for #{id}: #{e.message}"
+          return nil
+        end
+
+        return nil unless team_data
+
+        new(
+          id: team_data['id'],
+          name: team_data['name'],
+          location: team_data['location'],
+          abbreviation: team_data['abbreviation'],
+          sport: sport,
+          league: league,
+          venue: EspnPub::Entities::Venue.from_api(team_data.dig('franchise', 'venue'))
+        )
+      end
+
       # Fetch the roster for this team.
       #
       # @return [Array<EspnPub::Entities::Player>]
@@ -40,15 +66,22 @@ module EspnPub
           begin
             path = format ROSTER_PATH, client.version, sport, league, id
             roster_resp = client.send_request(path)
-            @roster = (roster_resp.dig('athletes') || []).map do |athlete_data|
-              player = EspnPub::Entities::Player.new(
+            @roster = (roster_resp['athletes'] || []).map do |athlete_data|
+              EspnPub::Entities::Player.new(
                 id: athlete_data['id'],
                 sport: sport,
                 league: league,
                 first_name: athlete_data['firstName'],
                 last_name: athlete_data['lastName'],
                 position: athlete_data['position']['abbreviation'],
-                team_id: id
+                team_id: id,
+                birthCity: athlete_data.dig('birthPlace', 'city'),
+                birthState: athlete_data.dig('birthPlace', 'state'),
+                birthCountry: athlete_data.dig('birthPlace', 'country'),
+                date_of_birth: athlete_data['dateOfBirth'],
+                height: athlete_data['height'],
+                weight: athlete_data['weight'],
+                debut_year: athlete_data['debutYear']
               )
             end
           rescue Client::UnexpectedResponseCodeError => e
@@ -59,6 +92,13 @@ module EspnPub
 
         @roster
       end
+
+      # Return the team's full name.
+      #
+      # @return [String] The team's full name.
+      def full_name
+        @full_name ||= "#{location} #{name}"
+      end
     end
   end
-end
+end

data/lib/espn_pub/entities/venue.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module EspnPub
+  module Entities
+    # Represents a team's home venue (stadium or arena).
+    class Venue < Base
+      attr_reader :id,
+                  :full_name,
+                  :short_name,
+                  :city,
+                  :state,
+                  :zip_code,
+                  :country,
+                  :indoor,
+                  :grass
+
+      # Initialize a Venue entity.
+      #
+      # @param id [String] The venue identifier.
+      # @param full_name [String, nil] The venue's full name.
+      # @param short_name [String, nil] The venue's short name.
+      # @param city [String, nil] The venue's city.
+      # @param state [String, nil] The venue's state or province.
+      # @param zip_code [String, nil] The venue's postal code.
+      # @param country [String, nil] The venue's country.
+      # @param indoor [Boolean, nil] Whether the venue is indoors.
+      # @param grass [Boolean, nil] Whether the venue has a grass surface.
+      def initialize(id:, full_name: nil, short_name: nil, city: nil, state: nil, zip_code: nil, country: nil,
+                     indoor: nil, grass: nil)
+        @id = id
+        @full_name = full_name
+        @short_name = short_name
+        @city = city
+        @state = state
+        @zip_code = zip_code
+        @country = country
+        @indoor = indoor
+        @grass = grass
+        super()
+      end
+
+      # Build a Venue from ESPN API venue data.
+      #
+      # @param data [Hash, nil] Raw venue data from the API.
+      # @return [Venue, nil] A Venue instance, or nil when data is absent.
+      def self.from_api(data)
+        return nil unless data
+
+        new(
+          id: data['id'],
+          full_name: data['fullName'],
+          short_name: data['shortName'],
+          city: data.dig('address', 'city'),
+          state: data.dig('address', 'state'),
+          zip_code: data.dig('address', 'zipCode'),
+          country: data.dig('address', 'country'),
+          indoor: data['indoor'],
+          grass: data['grass']
+        )
+      end
+    end
+  end
+end

data/lib/espn_pub/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EspnPub
-  VERSION = '0.1.0'
+  VERSION = '0.1.3'
 end

data/lib/espn_pub.rb

@@ -10,6 +10,7 @@ require_relative 'espn_pub/client'
 require_relative 'espn_pub/entities/base'
 require_relative 'espn_pub/entities/league'
 require_relative 'espn_pub/entities/team'
+require_relative 'espn_pub/entities/venue'
 require_relative 'espn_pub/entities/player'
 require_relative 'espn_pub/entities/game'
 

metadata

@@ -1,71 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: espn_pub
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Jeffrey Bowman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: json
+  name: date
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
-  name: net-http
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
-  name: uri
+  name: net-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
-  name: date
+  name: uri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -153,6 +153,7 @@ files:
 - lib/espn_pub/entities/league.rb
 - lib/espn_pub/entities/player.rb
 - lib/espn_pub/entities/team.rb
+- lib/espn_pub/entities/venue.rb
 - lib/espn_pub/version.rb
 homepage: https://github.com/bowmanje/espn-pub-rb
 licenses:
@@ -160,6 +161,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/bowmanje/espn-pub-rb
   source_code_uri: https://github.com/bowmanje/espn-pub-rb
+  documentation_uri: https://www.rubydoc.info/gems/espn_pub
 post_install_message:
 rdoc_options: []
 require_paths: