espn_pub 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4dee5305666108de85913d5ef82a426b3e43c7c011833c4f9f0be06d9ebb6ae6
+  data.tar.gz: aa60cb29dbfe5abba1e77b75bc96fe4b4bb6cb90c00318ff59934b5171528898
+SHA512:
+  metadata.gz: ca5aeb78fe7c56960d27a55e58e4763652527dece17663cf02e5847fd73349f9aa7d1293db8d8b7751c0d250d3a4b065ee1c3e98a8774f73719829fd1a36e87a
+  data.tar.gz: a5dc7c9b283be22e3d2813955e122fd0916a9fec69821f551016957a139ce55f1fd55b6cbb745773857b4f1216ed5d49080200472102c6360e4bc4aa6b26ab6f

data/README.md

@@ -0,0 +1 @@
+# espn-pub-rb

data/espn_pub.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/espn_pub/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'espn_pub'
+  spec.version = EspnPub::VERSION
+  spec.authors = ['Jeffrey Bowman']
+  spec.email   = ['bowmanjeffrey12@gmail.com']
+  spec.summary     = 'A Ruby client for the public ESPN API'
+  spec.description = "Fetch sports data from ESPN's public API — teams, athletes, scoreboards, and more."
+  spec.homepage    = 'https://github.com/bowmanje/espn-pub-rb'
+  spec.license     = 'MIT'
+  spec.required_ruby_version = '>= 3.3.0'
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage
+  }
+
+  spec.files = Dir.glob('{lib,sig}/**/*', File::FNM_DOTMATCH)
+                  .reject { |f| File.directory?(f) } +
+               %w[espn_pub.gemspec README.md]
+
+  spec.require_paths = ['lib']
+  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'
+  spec.add_development_dependency 'rubocop-rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.23'
+end

data/lib/espn_pub/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module EspnPub
+  # Client for making requests to the ESPN public API.
+  class Client
+    # Raised when the API returns an unexpected HTTP response code.
+    class UnexpectedResponseCodeError < StandardError; end
+
+    BASE_URI = 'https://site.api.espn.com/'
+    API_VERSION = 'v2'
+
+    attr_reader :uri, :version
+
+    # Initialize a new Client.
+    #
+    # @param base_uri [String] The base URI for ESPN API requests.
+    # @param version [String] The API version string.
+    def initialize(base_uri:, version:)
+      @uri = get_uri(base_uri)
+      @version = version
+    end
+
+    # Send a GET request to the specified API path.
+    #
+    # @param path [String] The request path to fetch from ESPN.
+    # @return [Hash] The parsed JSON response.
+    # @raise [UnexpectedResponseCodeError] if the response status is not 200.
+    def send_request(path)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+        http.request_get path
+      end
+
+      raise UnexpectedResponseCodeError, "Unexpected response code: #{response.code}" unless response.code.to_i == 200
+
+      JSON.parse response.body
+    end
+
+    private
+
+    # Parse a string into a URI object.
+    #
+    # @param uri [String] The URI string to parse.
+    # @return [URI]
+    def get_uri(uri)
+      URI uri
+    end
+  end
+end

data/lib/espn_pub/entities/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module EspnPub
+  module Entities
+    # Base entity that holds a shared ESPN API client.
+    class Base
+      attr_reader :client
+
+      # Initialize the base entity and create the shared client.
+      #
+      # @return [void]
+      def initialize
+        @client = init_client
+      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,
+        )
+      end
+    end
+  end
+end

data/lib/espn_pub/entities/game.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module EspnPub
+  module Entities
+    # Represents a game between two teams.
+    class Game < Base
+      attr_reader :id, :home_team_id, :away_team_id, :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 date [DateTime] The scheduled game date.
+      def initialize(id:, home_team_id:, away_team_id:, date:)
+        @id = id
+        @home_team_id = home_team_id
+        @away_team_id = away_team_id
+        @date = date
+        super()
+      end
+    end
+  end
+end

data/lib/espn_pub/entities/league.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module EspnPub
+  module Entities
+    # Represents a sports league, eg. NBA, NFL, etc.
+    class League < Base
+      # Supported league names.
+      module NAME
+        NBA = 'nba'
+        NFL = 'nfl'
+      end
+
+      TEAMS_PATH = '/apis/site/%s/sports/%s/%s/teams'
+      GAMES_PATH = '/apis/site/%s/sports/%s/%s/scoreboard'
+
+      NAME_TO_SPORT = {
+        'nba' => 'basketball',
+        'nfl' => 'football'
+      }.freeze
+
+      attr_reader :name
+
+      # Initialize a League instance.
+      #
+      # @param name [String] The league identifier string.
+      def initialize(name)
+        @name = name
+        super()
+      end
+
+      # Fetch the teams for this league.
+      #
+      # @return [Array<EspnPub::Entities::Team>]
+      def teams
+        unless defined?(@teams)
+          begin
+            path = format TEAMS_PATH, client.version, self.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(
+                id: team_data.dig('team', 'id'),
+                name: team_data.dig('team', 'name'),
+                location: team_data.dig('team', 'location'),
+                abbreviation: team_data.dig('team', 'abbreviation'),
+                sport: sport,
+                league: name
+              )
+            end
+          rescue Client::UnexpectedResponseCodeError => e
+            warn "Failed to fetch teams for league #{name}: #{e.message}"
+            return []
+          end
+        end
+
+        @teams
+      end
+
+      # Fetch games for this league.
+      #
+      # @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 []
+        end
+      end
+
+      # Return the sport name for this league.
+      #
+      # @return [String, nil] The sport name or nil when unknown.
+      def sport
+        NAME_TO_SPORT[name]
+      end
+    end
+  end
+end

data/lib/espn_pub/entities/player.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module EspnPub
+  module Entities
+    # Represents a player on a team.
+    class Player < Base
+      attr_reader :id,
+                  :sport,
+                  :league,
+                  :first_name,
+                  :last_name,
+                  :position,
+                  :team_id
+
+      # Initialize a Player entity.
+      #
+      # @param id [String] The player identifier.
+      # @param sport [String] The sport name.
+      # @param league [String] The league identifier.
+      # @param first_name [String, nil] The player's first name.
+      # @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)
+        @id = id
+        @sport = sport
+        @league = league
+        @first_name = first_name
+        @last_name = last_name
+        @position = position
+        @team_id = team_id
+        super()
+      end
+
+      # Return the player's full name.
+      #
+      # @return [String] The player's full name.
+      def full_name
+        @full_name ||= first_name + ' ' + last_name
+      end
+    end
+  end
+end

data/lib/espn_pub/entities/team.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EspnPub
+  module Entities
+    # Represents a sports team, eg. Miami Heat, New England Patriots, etc.
+    class Team < Base
+
+      ROSTER_PATH = '/apis/site/%s/sports/%s/%s/teams/%s/roster'
+
+      attr_reader :id,
+                  :name,
+                  :location,
+                  :abbreviation,
+                  :sport,
+                  :league
+
+      # Initialize a Team entity.
+      #
+      # @param id [String] The team identifier.
+      # @param name [String] The team name.
+      # @param location [String] The team location.
+      # @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:)
+        @id = id
+        @name = name
+        @location = location
+        @abbreviation = abbreviation
+        @sport = sport
+        @league = league
+        super()
+      end
+
+      # Fetch the roster for this team.
+      #
+      # @return [Array<EspnPub::Entities::Player>]
+      def players
+        unless defined?(@roster)
+          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(
+                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
+              )
+            end
+          rescue Client::UnexpectedResponseCodeError => e
+            warn "Failed to fetch roster for team #{name} (#{id}): #{e.message}"
+            return []
+          end
+        end
+
+        @roster
+      end
+    end
+  end
+end

data/lib/espn_pub/version.rb

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

data/lib/espn_pub.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Namespace for the ESPN public API client library.
+#
+# This gem exposes entities and a client for fetching leagues, teams,
+# players, and games from ESPN's public API.
+
+require_relative 'espn_pub/version'
+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/player'
+require_relative 'espn_pub/entities/game'
+
+module EspnPub
+end
+# --- IGNORE ---

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: espn_pub
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeffrey Bowman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: date
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Fetch sports data from ESPN's public API — teams, athletes, scoreboards,
+  and more.
+email:
+- bowmanjeffrey12@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- espn_pub.gemspec
+- lib/espn_pub.rb
+- lib/espn_pub/client.rb
+- lib/espn_pub/entities/base.rb
+- lib/espn_pub/entities/game.rb
+- lib/espn_pub/entities/league.rb
+- lib/espn_pub/entities/player.rb
+- lib/espn_pub/entities/team.rb
+- lib/espn_pub/version.rb
+homepage: https://github.com/bowmanje/espn-pub-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bowmanje/espn-pub-rb
+  source_code_uri: https://github.com/bowmanje/espn-pub-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: A Ruby client for the public ESPN API
+test_files: []