espn_pub 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dee5305666108de85913d5ef82a426b3e43c7c011833c4f9f0be06d9ebb6ae6
-  data.tar.gz: aa60cb29dbfe5abba1e77b75bc96fe4b4bb6cb90c00318ff59934b5171528898
+  metadata.gz: 4bce533b327d0ad217ebdce3abf887f7960ddc5c275a93063aae8df8918af0af
+  data.tar.gz: cc6468fbbcdc9f8d27fdaf8481bb2f9b9591266c700f10f18ac0708f038cd0eb
 SHA512:
-  metadata.gz: ca5aeb78fe7c56960d27a55e58e4763652527dece17663cf02e5847fd73349f9aa7d1293db8d8b7751c0d250d3a4b065ee1c3e98a8774f73719829fd1a36e87a
-  data.tar.gz: a5dc7c9b283be22e3d2813955e122fd0916a9fec69821f551016957a139ce55f1fd55b6cbb745773857b4f1216ed5d49080200472102c6360e4bc4aa6b26ab6f
+  metadata.gz: 84196f6df201cfacf81b1239506694468d570a46e98c31f41c08e0dcf4c2b1ef8a757e7185d35c4e1478d2673f1ecd330942b62e3d2e176e312bbf062036246e
+  data.tar.gz: 7f8534155c22dcee1271fc9357254f636325c7dab6bf6528360bb4bae6f4f522a9fcabf974984b61cfc8d59c29223b394d10b4aa40ec2157251c864a9e4513d3

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)

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/game.rb

@@ -4,18 +4,18 @@ 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

data/lib/espn_pub/entities/league.rb

@@ -69,8 +69,16 @@ module EspnPub
           (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'),
+              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

data/lib/espn_pub/entities/player.rb

@@ -36,7 +36,7 @@ module EspnPub
       #
       # @return [String] The player's full name.
       def full_name
-        @full_name ||= first_name + ' ' + last_name
+        @full_name ||= "#{first_name} #{last_name}"
       end
     end
   end

data/lib/espn_pub/entities/team.rb

@@ -5,6 +5,7 @@ module EspnPub
     # 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,
@@ -32,6 +33,28 @@ module EspnPub
         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).dig('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
+        )
+      end
+
       # Fetch the roster for this team.
       #
       # @return [Array<EspnPub::Entities::Player>]
@@ -59,6 +82,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

data/lib/espn_pub/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: espn_pub
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jeffrey Bowman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -160,6 +160,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: