nba 0.1.1 → 0.2.0

data/lib/nba/video_detail.rb

@@ -0,0 +1,103 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a video detail for a play
+  class VideoDetail < Shale::Mapper
+    include Equalizer.new(:video_id)
+
+    # @!attribute [rw] video_id
+    #   Returns the video ID
+    #   @api public
+    #   @example
+    #     video.video_id #=> "abc123"
+    #   @return [String] the video ID
+    attribute :video_id, Shale::Type::String
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     video.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_event_id
+    #   Returns the game event ID
+    #   @api public
+    #   @example
+    #     video.game_event_id #=> 10
+    #   @return [Integer] the event ID
+    attribute :game_event_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     video.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     video.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] description
+    #   Returns the play description
+    #   @api public
+    #   @example
+    #     video.description #=> "Curry 3PT Jump Shot"
+    #   @return [String] the play description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] video_urls
+    #   Returns the video URLs
+    #   @api public
+    #   @example
+    #     video.video_urls #=> "{\"720p\": \"url1\", \"1080p\": \"url2\"}"
+    #   @return [String] the video URLs JSON string
+    attribute :video_urls, Shale::Type::String
+
+    # @!attribute [rw] video_available
+    #   Returns the video availability flag
+    #   @api public
+    #   @example
+    #     video.video_available #=> 1
+    #   @return [Integer] 1 if available, 0 if not
+    attribute :video_available, Shale::Type::Integer
+
+    # Returns whether the video is available
+    #
+    # @api public
+    # @example
+    #   video.available? #=> true
+    # @return [Boolean] true if video is available
+    def available?
+      video_available.eql?(1)
+    end
+
+    # Returns the player object for this video
+    #
+    # @api public
+    # @example
+    #   video.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object for this video
+    #
+    # @api public
+    # @example
+    #   video.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/video_details.rb

@@ -0,0 +1,118 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+require_relative "video_detail"
+
+module NBA
+  # Provides methods to retrieve video details
+  module VideoDetails
+    # Result set name for video details
+    # @return [String] the result set name
+    RESULT_SET_NAME = "VideoDetails".freeze
+
+    # Retrieves video details for plays
+    #
+    # @api public
+    # @example
+    #   videos = NBA::VideoDetails.find(player: 201939, team: Team::GSW, season: 2023)
+    #   videos.each { |v| puts "#{v.description}: #{v.available?}" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer] the season year
+    # @param context_measure [String] the context measure (default: "FGA")
+    # @param season_type [String] the season type (default: "Regular Season")
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of video details
+    def self.find(player:, team:, season:, context_measure: "FGA", season_type: "Regular Season", league: League::NBA,
+      client: CLIENT)
+      player_id = Utils.extract_id(player)
+      team_id = Utils.extract_id(team)
+      league_id = Utils.extract_league_id(league)
+      path = "videodetails?PlayerID=#{player_id}&TeamID=#{team_id}&Season=#{Utils.format_season(season)}" \
+             "&ContextMeasure=#{context_measure}&SeasonType=#{season_type}&LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of video details
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      videos = rows.map { |row| build_video_detail(headers, row) }
+      Collection.new(videos)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(RESULT_SET_NAME) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a video detail from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [VideoDetail] the video detail object
+    def self.build_video_detail(headers, row)
+      data = headers.zip(row).to_h
+      VideoDetail.new(**video_attributes(data))
+    end
+    private_class_method :build_video_detail
+
+    # Extracts video attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the video row data
+    # @return [Hash] the video attributes
+    def self.video_attributes(data)
+      identity_attributes(data).merge(video_info_attributes(data))
+    end
+    private_class_method :video_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the video data
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data)
+      {video_id: data["VIDEO_ID"], game_id: data["GAME_ID"],
+       game_event_id: data["GAME_EVENT_ID"], player_id: data["PLAYER_ID"],
+       team_id: data["TEAM_ID"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts video information attributes
+    #
+    # @api private
+    # @param data [Hash] the video data
+    # @return [Hash] the video information attributes
+    def self.video_info_attributes(data)
+      {description: data["DESCRIPTION"], video_urls: data["VIDEO_URLS"],
+       video_available: data["VIDEO_AVAILABLE"]}
+    end
+    private_class_method :video_info_attributes
+  end
+end

data/lib/nba/video_details_asset.rb

@@ -0,0 +1,115 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+require_relative "video_details_asset_entry"
+
+module NBA
+  # Provides methods to retrieve video details asset data
+  module VideoDetailsAsset
+    # Result set name
+    # @return [String] the result set name
+    RESULTS = "VideoDetailsAsset".freeze
+
+    # Retrieves video details assets for a player
+    #
+    # @api public
+    # @example
+    #   entries = NBA::VideoDetailsAsset.find(player: 201939, team: 1610612744, season: 2023)
+    #   entries.each { |e| puts "#{e.video_description}: #{e.available?}" }
+    # @param player [Integer, String, Player] the player ID or Player object
+    # @param team [Integer, String, Team] the team ID or Team object
+    # @param season [Integer] the season year
+    # @param context_measure [String] the context measure (default "FGA")
+    # @param season_type [String] the season type (default "Regular Season")
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of video details asset entries
+    def self.find(player:, team:, season:, context_measure: "FGA", season_type: "Regular Season", league: League::NBA,
+      client: CLIENT)
+      player_id = Utils.extract_id(player)
+      team_id = Utils.extract_id(team)
+      league_id = Utils.extract_league_id(league)
+      season_param = Utils.format_season(season)
+      params = {player_id: player_id, team_id: team_id, season: season_param, context_measure: context_measure,
+                season_type: season_type, league_id: league_id}
+      path = build_path(params)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(params)
+      "videodetailsasset?PlayerID=#{params[:player_id]}&TeamID=#{params[:team_id]}&Season=#{params[:season]}" \
+        "&ContextMeasure=#{params[:context_measure]}&SeasonType=#{params[:season_type]}&LeagueID=#{params[:league_id]}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into entry objects
+    # @api private
+    # @return [Collection] collection of entries
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      entries = rows.map { |row| build_entry(headers, row) }
+      Collection.new(entries)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(RESULTS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a VideoDetailsAssetEntry object from raw data
+    # @api private
+    # @return [VideoDetailsAssetEntry] the entry object
+    def self.build_entry(headers, row)
+      data = headers.zip(row).to_h
+      VideoDetailsAssetEntry.new(**entry_attributes(data))
+    end
+    private_class_method :build_entry
+
+    # Extracts entry attributes from data
+    # @api private
+    # @return [Hash] the entry attributes
+    def self.entry_attributes(data)
+      identifier_attributes(data).merge(video_attributes(data))
+    end
+    private_class_method :entry_attributes
+
+    # Extracts identifier attributes
+    # @api private
+    # @return [Hash] the identifier attributes
+    def self.identifier_attributes(data)
+      {uuid: data["UUID"], game_id: data["GAME_ID"], game_event_id: data["GAME_EVENT_ID"]}
+    end
+    private_class_method :identifier_attributes
+
+    # Extracts video attributes
+    # @api private
+    # @return [Hash] the video attributes
+    def self.video_attributes(data)
+      {video_available: data["VIDEO_AVAILABLE"], video_url: data["VIDEO_URL"],
+       file_size: data["FILE_SIZE"], aspect_ratio: data["ASPECT_RATIO"],
+       video_duration: data["VIDEO_DURATION"], video_description: data["VIDEO_DESCRIPTION"]}
+    end
+    private_class_method :video_attributes
+  end
+end

data/lib/nba/video_details_asset_entry.rb

@@ -0,0 +1,91 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a video details asset entry
+  class VideoDetailsAssetEntry < Shale::Mapper
+    include Equalizer.new(:uuid)
+
+    # @!attribute [rw] uuid
+    #   Returns the unique identifier
+    #   @api public
+    #   @example
+    #     entry.uuid #=> "abc123def456"
+    #   @return [String] the unique identifier
+    attribute :uuid, Shale::Type::String
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     entry.game_id #=> "0022300001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_event_id
+    #   Returns the game event ID
+    #   @api public
+    #   @example
+    #     entry.game_event_id #=> 1
+    #   @return [Integer] the game event ID
+    attribute :game_event_id, Shale::Type::Integer
+
+    # @!attribute [rw] video_available
+    #   Returns the video availability flag
+    #   @api public
+    #   @example
+    #     entry.video_available #=> 1
+    #   @return [Integer] the video availability flag
+    attribute :video_available, Shale::Type::Integer
+
+    # @!attribute [rw] video_url
+    #   Returns the video URL
+    #   @api public
+    #   @example
+    #     entry.video_url #=> "https://videos.nba.com/video.mp4"
+    #   @return [String] the video URL
+    attribute :video_url, Shale::Type::String
+
+    # @!attribute [rw] file_size
+    #   Returns the file size in bytes
+    #   @api public
+    #   @example
+    #     entry.file_size #=> 1024000
+    #   @return [Integer] the file size in bytes
+    attribute :file_size, Shale::Type::Integer
+
+    # @!attribute [rw] aspect_ratio
+    #   Returns the aspect ratio
+    #   @api public
+    #   @example
+    #     entry.aspect_ratio #=> "16:9"
+    #   @return [String] the aspect ratio
+    attribute :aspect_ratio, Shale::Type::String
+
+    # @!attribute [rw] video_duration
+    #   Returns the video duration in seconds
+    #   @api public
+    #   @example
+    #     entry.video_duration #=> 12.5
+    #   @return [Float] the video duration in seconds
+    attribute :video_duration, Shale::Type::Float
+
+    # @!attribute [rw] video_description
+    #   Returns the video description
+    #   @api public
+    #   @example
+    #     entry.video_description #=> "3PT Jump Shot by Player"
+    #   @return [String] the video description
+    attribute :video_description, Shale::Type::String
+
+    # Returns whether video is available
+    #
+    # @api public
+    # @example
+    #   entry.available? #=> true
+    # @return [Boolean] true if video is available
+    def available?
+      video_available.eql?(1)
+    end
+  end
+end

data/lib/nba/video_event.rb

@@ -0,0 +1,83 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a video event
+  class VideoEvent < Shale::Mapper
+    include Equalizer.new(:uuid)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     event.game_id #=> "0022300001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_event_id
+    #   Returns the game event ID
+    #   @api public
+    #   @example
+    #     event.game_event_id #=> 1
+    #   @return [Integer] the game event ID
+    attribute :game_event_id, Shale::Type::Integer
+
+    # @!attribute [rw] video_available
+    #   Returns the video availability flag
+    #   @api public
+    #   @example
+    #     event.video_available #=> 1
+    #   @return [Integer] the video availability flag
+    attribute :video_available, Shale::Type::Integer
+
+    # @!attribute [rw] video_url
+    #   Returns the video URL
+    #   @api public
+    #   @example
+    #     event.video_url #=> "https://videos.nba.com/..."
+    #   @return [String] the video URL
+    attribute :video_url, Shale::Type::String
+
+    # @!attribute [rw] video_description
+    #   Returns the video description
+    #   @api public
+    #   @example
+    #     event.video_description #=> "Curry makes 3-pt jump shot"
+    #   @return [String] the video description
+    attribute :video_description, Shale::Type::String
+
+    # @!attribute [rw] video_category
+    #   Returns the video category
+    #   @api public
+    #   @example
+    #     event.video_category #=> "Made Shot"
+    #   @return [String] the video category
+    attribute :video_category, Shale::Type::String
+
+    # @!attribute [rw] uuid
+    #   Returns the unique identifier
+    #   @api public
+    #   @example
+    #     event.uuid #=> "abc123"
+    #   @return [String] the unique identifier
+    attribute :uuid, Shale::Type::String
+
+    # @!attribute [rw] title
+    #   Returns the video title
+    #   @api public
+    #   @example
+    #     event.title #=> "Curry 3PT"
+    #   @return [String] the video title
+    attribute :title, Shale::Type::String
+
+    # Returns whether video is available
+    #
+    # @api public
+    # @example
+    #   event.video_available? #=> true
+    # @return [Boolean] true if video is available
+    def video_available?
+      video_available.eql?(1)
+    end
+  end
+end

data/lib/nba/video_event_asset.rb

@@ -0,0 +1,91 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a video event asset with additional asset information
+  class VideoEventAsset < Shale::Mapper
+    include Equalizer.new(:uuid)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     asset.game_id #=> "0022300001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_event_id
+    #   Returns the game event ID
+    #   @api public
+    #   @example
+    #     asset.game_event_id #=> 1
+    #   @return [Integer] the game event ID
+    attribute :game_event_id, Shale::Type::Integer
+
+    # @!attribute [rw] video_available
+    #   Returns the video availability flag
+    #   @api public
+    #   @example
+    #     asset.video_available #=> 1
+    #   @return [Integer] the video availability flag
+    attribute :video_available, Shale::Type::Integer
+
+    # @!attribute [rw] video_url
+    #   Returns the video URL
+    #   @api public
+    #   @example
+    #     asset.video_url #=> "https://videos.nba.com/..."
+    #   @return [String] the video URL
+    attribute :video_url, Shale::Type::String
+
+    # @!attribute [rw] video_description
+    #   Returns the video description
+    #   @api public
+    #   @example
+    #     asset.video_description #=> "Curry makes 3-pt jump shot"
+    #   @return [String] the video description
+    attribute :video_description, Shale::Type::String
+
+    # @!attribute [rw] uuid
+    #   Returns the unique identifier
+    #   @api public
+    #   @example
+    #     asset.uuid #=> "abc123"
+    #   @return [String] the unique identifier
+    attribute :uuid, Shale::Type::String
+
+    # @!attribute [rw] file_size
+    #   Returns the file size in bytes
+    #   @api public
+    #   @example
+    #     asset.file_size #=> 1024000
+    #   @return [Integer] the file size
+    attribute :file_size, Shale::Type::Integer
+
+    # @!attribute [rw] aspect_ratio
+    #   Returns the video aspect ratio
+    #   @api public
+    #   @example
+    #     asset.aspect_ratio #=> "16:9"
+    #   @return [String] the aspect ratio
+    attribute :aspect_ratio, Shale::Type::String
+
+    # @!attribute [rw] video_duration
+    #   Returns the video duration in seconds
+    #   @api public
+    #   @example
+    #     asset.video_duration #=> 15
+    #   @return [Integer] the video duration
+    attribute :video_duration, Shale::Type::Integer
+
+    # Returns whether video is available
+    #
+    # @api public
+    # @example
+    #   asset.video_available? #=> true
+    # @return [Boolean] true if video is available
+    def video_available?
+      video_available.eql?(1)
+    end
+  end
+end