jumbotron 0.1.1

data/app/adapters/jumbotron/adapters/espn/nfl_helpers/progress.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        module Progress
+          NIL_LIFECYCLES = %w[scheduled postponed cancelled].freeze
+          INTERMISSION_PATTERN = /halftime/i
+
+          module_function
+
+          def call(status, lifecycle:)
+            return if NIL_LIFECYCLES.include?(lifecycle.to_s)
+            return quarter_intermission if intermission?(status)
+
+            period = status.period
+            return if period.nil? || period < 1
+
+            kind = period <= 4 ? "quarter" : "overtime"
+            number = period <= 4 ? period : period - 4
+            build(state: "active", kind: kind, number: number, clock: clock_for(status))
+          end
+
+          def intermission?(status)
+            [status.type_name, status.type_description, status.type_detail, status.type_short_detail]
+              .compact
+              .any? { |value| INTERMISSION_PATTERN.match?(value) }
+          end
+
+          def quarter_intermission
+            build(state: "intermission", kind: "quarter", number: 2, clock: nil)
+          end
+
+          def clock_for(status)
+            seconds = status.clock.is_a?(Integer) ? status.clock : nil
+            display = status.display_clock.presence
+            return if seconds.nil? && display.nil?
+
+            Canonical::GameClock.new(mode: "remaining", seconds: seconds, display: display)
+          end
+
+          def build(state:, kind:, number:, clock:)
+            Canonical::GameProgress.new(
+              state: state,
+              segment: Canonical::GameSegment.new(kind: kind, number: number),
+              clock: clock
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/espn/nfl_helpers/scoreboard.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        class Scoreboard
+          def self.call(board, observed_at:)
+            events = board.respond_to?(:events) ? board.events : Array(board)
+            Canonical::SyncInput.new(
+              observed_at: observed_at,
+              games: events.map { |event| transform_event(event) },
+              teams: []
+            )
+          end
+
+          def self.transform_event(event)
+            competition = event.competitions&.first
+            raise TransformError, "event #{event.id} missing competition" if competition.nil?
+
+            status = competition.status || event.status
+            raise TransformError, "event #{event.id} missing status" if status.nil?
+
+            lifecycle = Lifecycle.call(status.type_name)
+            season = event.season
+            if season.nil? || season.year.nil? || season.type.nil?
+              raise TransformError,
+                    "event #{event.id} missing season"
+            end
+
+            participants = Array(competition.competitors)
+            raise TransformError, "event #{event.id} requires exactly 2 competitors" unless participants.length == 2
+
+            Canonical::GameInput.new(
+              provider_identities: identities_for(event, competition),
+              scheduled_at: parse_time(event.date.presence || competition.date.presence || competition.start_date),
+              lifecycle: lifecycle,
+              neutral_site: competition.neutral_site,
+              season_year: season.year.to_i,
+              season_phase_key: SeasonPhase.call(season.type),
+              schedule_group: schedule_group_for(event),
+              venue: transform_venue(competition.venue),
+              participants: participants.map { |c| transform_participant(c, lifecycle) },
+              progress: Progress.call(status, lifecycle: lifecycle)
+            )
+          end
+          private_class_method :transform_event
+
+          def self.schedule_group_for(event)
+            number = event.week&.number
+            return if number.nil?
+
+            Canonical::ScheduleGroupInput.new(
+              kind: "week",
+              number: number,
+              name: "Week #{number}"
+            )
+          end
+          private_class_method :schedule_group_for
+
+          def self.identities_for(event, competition)
+            ids = []
+            if event.id.present?
+              ids << Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "event", id: event.id.to_s)
+            end
+            if competition.id.present?
+              ids << Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "competition",
+                                                        id: competition.id.to_s)
+            end
+            raise TransformError, "event/competition provider id required" if ids.empty?
+
+            ids.uniq
+          end
+          private_class_method :identities_for
+
+          def self.transform_venue(venue)
+            return nil if venue.nil?
+            raise TransformError, "venue id required" if venue.id.blank?
+            raise TransformError, "venue name required" if venue.full_name.blank?
+
+            Canonical::VenueInput.new(
+              provider_identities: [
+                Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "venue", id: venue.id.to_s)
+              ],
+              name: venue.full_name.to_s
+            )
+          end
+          private_class_method :transform_venue
+
+          def self.transform_participant(competitor, lifecycle)
+            team = competitor.team
+            raise TransformError, "competitor missing team" if team.nil?
+            raise TransformError, "team id required" if team.id.blank?
+
+            name = team.display_name.presence || team.name
+            raise TransformError, "team name required" if name.blank?
+            raise TransformError, "home_away required" if competitor.home_away.blank?
+
+            Canonical::ParticipantInput.new(
+              provider_identities: [
+                Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "team", id: team.id.to_s)
+              ],
+              team_name: name.to_s,
+              role: competitor.home_away.to_s,
+              score: coerce_score(competitor.score),
+              result: coerce_result(competitor.winner, lifecycle)
+            )
+          end
+          private_class_method :transform_participant
+
+          def self.coerce_score(raw)
+            return nil if raw.nil? || raw == ""
+
+            Integer(raw)
+          rescue ArgumentError, TypeError
+            raise TransformError, "invalid score: #{raw.inspect}"
+          end
+          private_class_method :coerce_score
+
+          def self.coerce_result(winner, lifecycle)
+            return nil unless lifecycle == "completed"
+            return nil if winner.nil?
+
+            winner ? "win" : "loss"
+          end
+          private_class_method :coerce_result
+
+          def self.parse_time(raw)
+            raise TransformError, "scheduled_at missing" if raw.blank?
+
+            Time.iso8601(raw.to_s)
+          rescue ArgumentError, TypeError
+            begin
+              Time.zone.parse(raw.to_s) || (raise ArgumentError)
+            rescue ArgumentError, TypeError
+              raise TransformError, "scheduled_at unparseable: #{raw.inspect}"
+            end
+          end
+          private_class_method :parse_time
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/espn/nfl_helpers/season_phase.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        module SeasonPhase
+          MAP = {
+            1 => "preseason",
+            2 => "regular_season",
+            3 => "postseason",
+            4 => "offseason"
+          }.freeze
+
+          module_function
+
+          def call(season_type)
+            mapped = MAP[season_type.to_i]
+            raise TransformError, "unsupported ESPN season.type: #{season_type.inspect}" if mapped.nil?
+
+            mapped
+          end
+
+          def espn_season_type(phase_key)
+            return if phase_key.nil?
+
+            MAP.key(phase_key.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/espn/nfl_helpers/teams.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        class Teams
+          def self.call(teams, observed_at:)
+            list = Array(teams)
+            Canonical::SyncInput.new(
+              observed_at: observed_at,
+              games: [],
+              teams: list.map { |team| transform_team(team) }
+            )
+          end
+
+          def self.transform_team(team)
+            raise TransformError, "team id is required" if team.id.nil? || team.id.to_s.empty?
+
+            name = team.display_name.presence || team.name
+            raise TransformError, "team name is required for #{team.id}" if name.nil? || name.to_s.empty?
+
+            Canonical::TeamInput.new(
+              provider_identities: [
+                Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "team", id: team.id.to_s)
+              ],
+              name: name.to_s
+            )
+          end
+          private_class_method :transform_team
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/line_acquisition.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module LineAcquisition
+      def line_acquisition_scope_for(_game)
+        nil
+      end
+
+      def acquire_line_odds(_acquisition)
+        raise ConfigurationError, "#{name} must implement acquire_line_odds"
+      end
+
+      def translate_line_odds(*)
+        raise ConfigurationError, "#{name} must implement translate_line_odds"
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/operation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    class Operation
+      attr_reader :adapter, :resource, :transformer
+
+      def initialize(adapter:, resource:, transformer:)
+        @adapter = adapter
+        @resource = resource
+        @transformer = transformer
+      end
+
+      def acquire(**query)
+        resource.acquire(adapter: adapter, **query)
+      end
+
+      def transform(typed_payload, observed_at:)
+        transformer.call(typed_payload, observed_at: observed_at)
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/policy_definition.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    # Frozen registry entry for one adapter-declared update policy. Not a Policy base class.
+    PolicyDefinition = Data.define(:id, :type, :cadence, :eligible) do
+      def eligible?(game, now:)
+        raise ::Jumbotron::Adapters::ConfigurationError, "policy #{id} has no eligible predicate" if eligible.nil?
+
+        eligible.call(game, now: now)
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/registry.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Jumbotron
+  module Adapters
+    module Registry
+      module_function
+
+      # Stores the adapter class reference (not a config snapshot).
+      # Top-of-class register! is safe: identity is the class, not registry_key.
+      def register(adapter_class)
+        classes[adapter_class.name] = adapter_class
+        adapter_class
+      end
+
+      def registered
+        classes.values
+      end
+
+      def registered?(adapter_class)
+        classes[adapter_class.name] == adapter_class
+      end
+
+      # Adapter classes register via load-time `register!`. In non-eager-load
+      # processes (e.g. Solid Queue workers), nothing may have constantized them
+      # yet when jobs resolve by adapter_id string — load them first.
+      # If classes are already loaded but the in-memory registry was cleared,
+      # re-register Base subclasses (constantize alone does not re-run file side effects).
+      def ensure_loaded!
+        Dir[Jumbotron::Engine.root.join("app/adapters/jumbotron/adapters/**/*.rb")].each do |path|
+          relative = Pathname.new(path).relative_path_from(Jumbotron::Engine.root.join("app/adapters")).to_s
+          klass = relative.chomp(".rb").camelize.constantize
+          next unless klass.is_a?(Class)
+          next unless klass < Base
+          next if klass == Base
+
+          klass.register! unless registered?(klass)
+        end
+      end
+
+      def find(adapter_id)
+        id = adapter_id.to_s
+        registered.find do |adapter|
+          adapter.adapter_id == id
+        rescue ConfigurationError
+          false
+        end
+      end
+
+      def reset!
+        @classes = {}
+      end
+
+      # Raises if two different registered classes share the same registry_key.
+      def assert_unique_keys!
+        grouped = registered.group_by do |adapter|
+          adapter.registry_key
+        rescue ConfigurationError
+          :incomplete
+        end
+        grouped.each do |key, adapters|
+          next if key == :incomplete
+          next if adapters.uniq.size <= 1
+
+          raise RegistrationError,
+                "conflicting adapter registration for #{key.inspect}: " \
+                "#{adapters.map(&:name).join(' vs ')}"
+        end
+      end
+
+      def classes
+        @classes ||= {}
+      end
+      private_class_method :classes
+    end
+  end
+end

data/app/adapters/jumbotron/adapters.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    class RegistrationError < StandardError; end
+    class TransformError < StandardError; end
+    class ConfigurationError < StandardError; end
+    class UnknownPolicyError < StandardError; end
+    class UnknownDiscoveryError < StandardError; end
+  end
+end

data/app/boot/jumbotron/boot/enqueue_discoveries.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Boot
+    module EnqueueDiscoveries
+      module_function
+
+      def call
+        return unless eligible?
+
+        enqueue!
+      end
+
+      def eligible?
+        return false unless Jumbotron::Engine.config.boot_discovery
+        return false if Rails.env.test?
+        return false if defined?(Rails::Console)
+        return false if rake_environment?
+
+        true
+      end
+
+      def enqueue!
+        Jumbotron::Scheduling::DesiredSchedules.ensure_adapters_loaded!
+        Jumbotron::Adapters::Registry.registered.each do |adapter|
+          adapter.discovery_ids.each do |discovery_id|
+            Jumbotron::DiscoveryJob.perform_later(
+              adapter_id: adapter.adapter_id,
+              discovery_id: discovery_id.to_s,
+              continuation_attempt: 1
+            )
+          end
+        end
+      end
+
+      def rake_environment?
+        defined?(Rake) && Rake.respond_to?(:application) && Array(Rake.application.top_level_tasks).any?
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/competition_odds/get.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module CompetitionOdds
+        class Get < CommandTower::Clients::EndpointBase
+          authentication :none
+          http_method :get
+          path do |input|
+            relative = [
+              "sports", input.sport, "leagues", input.league,
+              "events", input.event_id,
+              "competitions", input.competition_id,
+              "odds"
+            ].join("/")
+            CommandTower::Clients::Url.join(Jumbotron::Clients::Espn.core_base_url, relative)
+          end
+          input GetInput
+          request_serializer ::Jumbotron::Serializers::Clients::Espn::CompetitionOdds::Get
+          response_deserializer ::Jumbotron::Deserializers::Clients::Espn::CompetitionOdds::Get
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/competition_odds/get_input.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module CompetitionOdds
+        class GetInput < CommandTower::Clients::EndpointInput
+          attribute :sport, :string
+          attribute :league, :string
+          attribute :event_id, :string
+          attribute :competition_id, :string
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/scoreboard/get.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module Scoreboard
+        class Get < CommandTower::Clients::EndpointBase
+          authentication :none
+          http_method :get
+          path { |input| "#{input.sport}/#{input.league}/scoreboard" }
+          input GetInput
+          request_serializer ::Jumbotron::Serializers::Clients::Espn::Scoreboard::Get
+          response_deserializer ::Jumbotron::Deserializers::Clients::Espn::Scoreboard::Get
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/scoreboard/get_input.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module Scoreboard
+        class GetInput < CommandTower::Clients::EndpointInput
+          attribute :sport, :string
+          attribute :league, :string
+          attribute :season_type
+          attribute :week
+          attribute :dates
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/teams/get.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module Teams
+        class Get < CommandTower::Clients::EndpointBase
+          authentication :none
+          http_method :get
+          path { |input| "#{input.sport}/#{input.league}/teams" }
+          input GetInput
+          request_serializer ::Jumbotron::Serializers::Clients::Espn::Teams::Get
+          response_deserializer ::Jumbotron::Deserializers::Clients::Espn::Teams::Get
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn/teams/get_input.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Clients
+    class Espn
+      module Teams
+        class GetInput < CommandTower::Clients::EndpointInput
+          attribute :sport, :string
+          attribute :league, :string
+          attribute :limit
+        end
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients/espn.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Jumbotron
+  module Clients
+    class Espn < CommandTower::Clients::ClientBase
+      DEFAULT_BASE_URL = "https://site.api.espn.com/apis/site/v2/sports"
+      DEFAULT_CORE_BASE_URL = "https://sports.core.api.espn.com/v2"
+
+      def self.core_base_url
+        ENV.fetch("JUMBOTRON_ESPN_CORE_BASE_URL", DEFAULT_CORE_BASE_URL)
+      end
+
+      def decode_response(response)
+        CommandTower::Clients::DecodedResponse.new(
+          payload: parse_json(response.body),
+          provider_metadata: {}
+        )
+      end
+
+      protected
+
+      def base_url
+        ENV.fetch("JUMBOTRON_ESPN_SITE_BASE_URL", DEFAULT_BASE_URL)
+      end
+
+      def default_headers
+        { "Accept" => "application/json" }
+      end
+
+      private
+
+      def parse_json(body)
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError => e
+        raise CommandTower::Clients::Errors::DeserializationError.new(
+          message: "ESPN response body is not valid JSON: #{e.message}",
+          details: { path: "", expected: "JSON object", actual: "invalid_json", rule: "type", messages: [e.message] }
+        )
+      end
+    end
+  end
+end

data/app/clients/jumbotron/clients.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  # Product invocation: Jumbotron::Clients.espn.scoreboard.get(...)
+  module Clients
+    extend CommandTower::Clients::Invocation
+  end
+end