jumbotron 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0461cd6ea53300eaf51f0283060767da1ee18a74356d20906bb35f34a369061e
+  data.tar.gz: 89cf5eec83c074a338b5765225933ae5a3be7480853966239d437ac383f09d0b
+SHA512:
+  metadata.gz: de18ce2882fa4b4a450a6541cb7305456b2e820de3cc71d95dede9fbaec654bef2234c1896aaf16e79cd7fcbc7b11163e2d67634dcf83c8d0a8e9921f2ccbdf9
+  data.tar.gz: b54ecfe4c49d62510fc1ec0ea238858487585171b57d5313f3e297415f834511c74c89a50f05049199addd6c9374fbb8633614d4d95cacc4de7b380248cc5454

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matt-taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,5 @@
+# Jumbotron
+
+Jumbotron is a backend sports-truth Rails Engine.
+
+More information is coming later.

data/app/adapters/jumbotron/adapters/base.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    class Base
+      class << self
+        include LineAcquisition
+
+        def register!
+          Registry.register(self)
+        end
+
+        def registered?
+          Registry.registered?(self)
+        end
+
+        def adapter_id(value = nil)
+          if value.nil?
+            return @adapter_id if defined?(@adapter_id) && @adapter_id
+
+            raise ConfigurationError, "#{name} must declare adapter_id"
+          end
+
+          @adapter_id = value.to_s
+        end
+
+        def provider(value = nil)
+          return @provider || raise(ConfigurationError, "#{name} must declare provider") if value.nil?
+
+          @provider = value.to_s.downcase
+        end
+
+        def sport(value = nil)
+          return @sport || raise(ConfigurationError, "#{name} must declare sport") if value.nil?
+
+          @sport = value.to_s
+        end
+
+        def league(value = nil)
+          return @league || raise(ConfigurationError, "#{name} must declare league") if value.nil?
+
+          @league = value.to_s
+        end
+
+        def endpoint(name, resource:, transformer:)
+          endpoints[name.to_sym] = { resource: resource, transformer: transformer }
+        end
+
+        def endpoints
+          @endpoints ||= {}
+        end
+
+        # Declare: policy :id, type:, cadence: nil, eligible: nil
+        # Lookup:  policy(:id)
+        def policy(id, type: nil, cadence: nil, eligible: nil)
+          key = id.to_sym
+          declaring = !type.nil? || !cadence.nil? || !eligible.nil?
+
+          unless declaring
+            return policies.fetch(key) do
+              raise UnknownPolicyError, "#{name} has no policy :#{key}"
+            end
+          end
+
+          raise ConfigurationError, "#{name} policy :#{key} must declare type" if type.nil?
+
+          policies[key] = PolicyDefinition.new(
+            id: key,
+            type: type.to_sym,
+            cadence: cadence,
+            eligible: eligible
+          )
+        end
+
+        def policies
+          @policies ||= {}
+        end
+
+        def policy_ids
+          policies.keys
+        end
+
+        def discovery(id, endpoint: nil)
+          key = id.to_sym
+          if endpoint.nil?
+            return discoveries.fetch(key) do
+              raise UnknownDiscoveryError, "#{name} has no discovery :#{key}"
+            end
+          end
+
+          discoveries[key] = DiscoveryDefinition.new(id: key, endpoint: endpoint.to_sym)
+        end
+
+        def discoveries
+          @discoveries ||= {}
+        end
+
+        def discovery_ids
+          discoveries.keys
+        end
+
+        def operation(name)
+          Registry.assert_unique_keys!
+          definition = endpoints[name.to_sym]
+          raise ConfigurationError, "#{self.name} has no endpoint :#{name}" unless definition
+
+          Operation.new(
+            adapter: self,
+            resource: definition[:resource],
+            transformer: definition[:transformer]
+          )
+        end
+
+        def registry_key
+          [provider, sport, league]
+        end
+
+        def acquisition_scope_for(_game)
+          raise ConfigurationError, "#{name} must implement acquisition_scope_for"
+        end
+
+        def scopes_for_discovery(_definition)
+          raise ConfigurationError, "#{name} must implement scopes_for_discovery"
+        end
+
+        def provider_cooling_down?
+          false
+        end
+
+        def provider_retry_after
+          0
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/cadence.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    class Cadence
+      UNITS = {
+        second: 1,
+        seconds: 1,
+        minute: 60,
+        minutes: 60,
+        hour: 3600,
+        hours: 3600,
+        day: 86_400,
+        days: 86_400,
+        week: 604_800,
+        weeks: 604_800
+      }.freeze
+
+      attr_reader :every, :unit
+
+      def initialize(every:, unit:)
+        @every = Integer(every)
+        @unit = unit.to_sym
+        raise ArgumentError, "every must be positive" unless @every.positive?
+        raise ArgumentError, "unknown cadence unit: #{unit}" unless UNITS.key?(@unit)
+      end
+
+      def interval_seconds
+        every * UNITS.fetch(unit)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && every == other.every && unit == other.unit
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, every, unit].hash
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/discovery_definition.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    DiscoveryDefinition = Data.define(:id, :endpoint)
+  end
+end

data/app/adapters/jumbotron/adapters/espn/nfl.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      class Nfl < Base
+        TERMINAL_LIFECYCLES = %w[completed cancelled].freeze
+        INTERRUPTED_LIFECYCLES = %w[postponed suspended].freeze
+
+        adapter_id "espn_nfl"
+
+        provider :espn
+        sport "football"
+        league "nfl"
+
+        endpoint :teams,
+                 resource: Providers::Espn::Resources::Teams,
+                 transformer: NflHelpers::Teams
+
+        endpoint :scoreboard,
+                 resource: Providers::Espn::Resources::Scoreboard,
+                 transformer: NflHelpers::Scoreboard
+
+        policy :far_future,
+               type: :future_game_update,
+               cadence: Cadence.new(every: 1, unit: :week),
+               eligible: lambda { |game, now:|
+                 TERMINAL_LIFECYCLES.exclude?(game.lifecycle) &&
+                   game.scheduled_at > now + 6.weeks
+               }
+
+        policy :near_future,
+               type: :future_game_update,
+               cadence: Cadence.new(every: 1, unit: :day),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+
+                 scheduled = game.scheduled_at
+                 scheduled.between?(now + 2.weeks, now + 6.weeks)
+               }
+
+        policy :upcoming,
+               type: :future_game_update,
+               cadence: Cadence.new(every: 1, unit: :hour),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+
+                 scheduled = game.scheduled_at
+                 scheduled > now && scheduled < now + 2.weeks
+               }
+
+        policy :live,
+               type: :live_game_update,
+               cadence: Cadence.new(every: 2, unit: :minute),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+                 return false if INTERRUPTED_LIFECYCLES.include?(game.lifecycle)
+
+                 now >= game.scheduled_at
+               }
+
+        policy :interrupted,
+               type: :interrupted_game_update,
+               cadence: Cadence.new(every: 1, unit: :hour),
+               eligible: lambda { |game, **|
+                 INTERRUPTED_LIFECYCLES.include?(game.lifecycle)
+               }
+
+        policy :far_future_lines,
+               type: :future_line_update,
+               cadence: Cadence.new(every: 1, unit: :week),
+               eligible: lambda { |game, now:|
+                 TERMINAL_LIFECYCLES.exclude?(game.lifecycle) &&
+                   game.scheduled_at > now + 6.weeks
+               }
+
+        policy :near_future_lines,
+               type: :future_line_update,
+               cadence: Cadence.new(every: 1, unit: :day),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+
+                 scheduled = game.scheduled_at
+                 scheduled.between?(now + 2.weeks, now + 6.weeks)
+               }
+
+        policy :upcoming_lines,
+               type: :future_line_update,
+               cadence: Cadence.new(every: 1, unit: :hour),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+
+                 scheduled = game.scheduled_at
+                 scheduled > now && scheduled < now + 2.weeks
+               }
+
+        policy :in_progress_lines,
+               type: :live_line_update,
+               cadence: Cadence.new(every: 1, unit: :hour),
+               eligible: lambda { |game, now:|
+                 return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
+                 return false if INTERRUPTED_LIFECYCLES.include?(game.lifecycle)
+
+                 now >= game.scheduled_at
+               }
+
+        policy :interrupted_lines,
+               type: :interrupted_line_update,
+               cadence: Cadence.new(every: 1, unit: :hour),
+               eligible: lambda { |game, **|
+                 INTERRUPTED_LIFECYCLES.include?(game.lifecycle)
+               }
+
+        discovery :full_season, endpoint: :scoreboard
+
+        register!
+
+        def self.acquisition_scope_for(game)
+          NflHelpers::AcquisitionScope.call(game)
+        end
+
+        def self.line_acquisition_scope_for(game)
+          NflHelpers::LineAcquisitionScope.call(game)
+        end
+
+        def self.acquire_line_odds(acquisition)
+          parts = acquisition.respond_to?(:to_h) ? acquisition.to_h : {}
+          parts = parts.symbolize_keys
+          Providers::Espn::Resources::CompetitionOdds.acquire(
+            sport: sport,
+            league: league,
+            event_id: parts.fetch(:event_id),
+            competition_id: parts.fetch(:competition_id)
+          )
+        end
+
+        def self.translate_line_odds(odds, observed_at:, acquisition:)
+          parts = acquisition.respond_to?(:to_h) ? acquisition.to_h : {}
+          parts = parts.symbolize_keys
+          NflHelpers::CompetitionOdds.call(
+            odds,
+            observed_at: observed_at,
+            event_id: parts.fetch(:event_id),
+            competition_id: parts.fetch(:competition_id)
+          )
+        end
+
+        def self.provider_cooling_down?
+          Providers::Espn::Cooldown.new.cooling_down?
+        end
+
+        def self.provider_retry_after
+          Providers::Espn::Cooldown.new.retry_after
+        end
+
+        def self.scopes_for_discovery(definition)
+          unless definition.endpoint == :scoreboard
+            raise ConfigurationError, "#{name} discovery #{definition.id} uses unsupported endpoint"
+          end
+
+          Providers::Espn::Resources::Scoreboard.expand_full_season(
+            adapter: self,
+            season_year: Time.current.utc.year
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        module AcquisitionScope
+          module_function
+
+          def call(game)
+            group = game.schedule_group
+            return if group.nil? || group.kind != "week" || group.number.nil?
+
+            year = Integer(game.season.name)
+            season_type = SeasonPhase.espn_season_type(game.season_phase&.name)
+            return if season_type.nil?
+
+            {
+              endpoint: :scoreboard,
+              acquisition: { dates: year, season_type: season_type, week: group.number }
+            }
+          rescue ArgumentError, TypeError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        class CompetitionOdds
+          SOURCES = {
+            "observed" => :current,
+            "provider_open" => :open,
+            "provider_close" => :close
+          }.freeze
+
+          def self.call(odds, observed_at:, event_id:, competition_id:)
+            Canonical::LineIngestInput.new(
+              observed_at: observed_at,
+              provider: "espn",
+              adapter_scope: "espn_nfl",
+              game_identities: game_identities(event_id, competition_id),
+              observations: Array(odds.items).flat_map { |item| translate_item(item) }
+            )
+          end
+
+          def self.game_identities(event_id, competition_id)
+            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
+          end
+          private_class_method :game_identities
+
+          def self.translate_item(item)
+            listed = item.listed_provider
+            raise TransformError, "listed provider id required" if listed.nil? || listed.id.blank?
+
+            identity = Canonical::ProviderIdentityRef.new(
+              provider: "espn",
+              namespace: "bookmaker",
+              id: listed.id.to_s
+            )
+            name = listed.name.to_s.presence || listed.id.to_s
+
+            SOURCES.flat_map do |source, window|
+              observations_for_window(item, identity, name, source, window)
+            end
+          end
+          private_class_method :translate_item
+
+          def self.observations_for_window(item, identity, name, source, window)
+            [
+              *spread_rows(item, identity, name, source, window),
+              *total_rows(item, identity, name, source, window),
+              *moneyline_rows(item, identity, name, source, window)
+            ]
+          end
+          private_class_method :observations_for_window
+
+          def self.spread_rows(item, identity, name, source, window)
+            %i[home away].filter_map do |side|
+              quote = team_quote(item, side, window)
+              line = parse_line_value(quote&.point_spread&.american)
+              price = parse_american(quote&.spread&.american)
+              price ||= parse_american(item.public_send(:"#{side}_team_odds")&.spread_odds) if source == "observed"
+              next if line.nil? || price.nil?
+
+              Canonical::LineObservationInput.new(
+                bookmaker_identity: identity,
+                bookmaker_name: name,
+                market: "spread",
+                outcome: side.to_s,
+                source: source,
+                line_value: line,
+                price_american: price
+              )
+            end
+          end
+          private_class_method :spread_rows
+
+          def self.total_rows(item, identity, name, source, window)
+            market_window = item.public_send(window)
+            threshold = parse_line_value(market_window&.total&.american)
+            threshold ||= parse_line_value(item.over_under) if source == "observed"
+            return [] if threshold.nil?
+
+            %i[over under].filter_map do |side|
+              price = parse_american(market_window&.public_send(side)&.american)
+              price ||= parse_american(item.public_send(:"#{side}_odds")) if source == "observed"
+              next if price.nil?
+
+              Canonical::LineObservationInput.new(
+                bookmaker_identity: identity,
+                bookmaker_name: name,
+                market: "total",
+                outcome: side.to_s,
+                source: source,
+                line_value: threshold,
+                price_american: price
+              )
+            end
+          end
+          private_class_method :total_rows
+
+          def self.moneyline_rows(item, identity, name, source, window)
+            rows = %i[home away].filter_map do |side|
+              quote = team_quote(item, side, window)
+              price = parse_american(quote&.money_line&.american)
+              price ||= parse_american(item.public_send(:"#{side}_team_odds")&.money_line) if source == "observed"
+              next if price.nil?
+
+              Canonical::LineObservationInput.new(
+                bookmaker_identity: identity,
+                bookmaker_name: name,
+                market: "moneyline",
+                outcome: side.to_s,
+                source: source,
+                line_value: nil,
+                price_american: price
+              )
+            end
+
+            draw_price = parse_american(item.public_send(window)&.draw&.american)
+            draw_price ||= parse_american(item.draw_odds&.money_line) if source == "observed"
+            return rows if draw_price.nil?
+
+            rows + [
+              Canonical::LineObservationInput.new(
+                bookmaker_identity: identity,
+                bookmaker_name: name,
+                market: "moneyline",
+                outcome: "draw",
+                source: source,
+                line_value: nil,
+                price_american: draw_price
+              )
+            ]
+          end
+          private_class_method :moneyline_rows
+
+          def self.team_quote(item, side, window)
+            odds = item.public_send(:"#{side}_team_odds")
+            odds&.public_send(window)
+          end
+          private_class_method :team_quote
+
+          def self.parse_american(raw)
+            return nil if raw.nil? || raw == ""
+            return Integer(raw) if raw.is_a?(Integer)
+
+            if raw.is_a?(Float) || raw.is_a?(BigDecimal)
+              return nil unless raw == raw.to_i
+
+              return Integer(raw)
+            end
+
+            Integer(raw.to_s.delete("+"))
+          rescue ArgumentError, TypeError
+            nil
+          end
+          private_class_method :parse_american
+
+          def self.parse_line_value(raw)
+            return nil if raw.nil? || raw == ""
+
+            BigDecimal(raw.to_s.delete("+"))
+          rescue ArgumentError, TypeError
+            nil
+          end
+          private_class_method :parse_line_value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        module Lifecycle
+          MAP = {
+            "STATUS_SCHEDULED" => "scheduled",
+            "STATUS_IN_PROGRESS" => "in_progress",
+            "STATUS_FINAL" => "completed",
+            "STATUS_POSTPONED" => "postponed",
+            "STATUS_CANCELED" => "cancelled",
+            "STATUS_CANCELLED" => "cancelled"
+          }.freeze
+
+          module_function
+
+          def call(type_name)
+            key = type_name.to_s
+            mapped = MAP[key]
+            raise TransformError, "unsupported ESPN status: #{key.inspect}" if mapped.nil?
+
+            mapped
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        module LineAcquisitionScope
+          module_function
+
+          def call(game)
+            identities = Array(game.provider_identities)
+            event = identities.find { |identity| identity.object_namespace == "event" }
+            competition = identities.find { |identity| identity.object_namespace == "competition" }
+            return if event.nil? || event.provider_id.blank?
+
+            competition_id = competition&.provider_id.presence || event.provider_id
+            {
+              endpoint: :competition_odds,
+              acquisition: { event_id: event.provider_id, competition_id: competition_id }
+            }
+          end
+        end
+      end
+    end
+  end
+end