jumbotron 0.1.7 → 0.2.0

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Jumbotron
+  module Adapters
+    module Sandbox
+      module NflHelpers
+        class Scoreboard
+          def self.call(payload, observed_at:)
+            data = payload.symbolize_keys
+            resolved = resolve_observation(data.fetch(:game_id), observed_at)
+            Canonical::SyncInput.new(
+              observed_at: observed_at,
+              games: [game_input(data, resolved)],
+              teams: []
+            )
+          rescue ArgumentError, KeyError, TypeError => e
+            raise TransformError, "invalid sandbox scoreboard observation: #{e.message}"
+          end
+
+          def self.resolve_observation(game_id, observed_at)
+            resolved = Jumbotron::Services::Sandbox::ResolveGameObservation.call(
+              game_id: game_id,
+              observed_at: observed_at
+            )
+            return resolved.data if resolved.success?
+
+            error = Array(resolved.errors).first
+            raise TransformError, error.respond_to?(:message) ? error.message : "sandbox observation failed"
+          end
+          private_class_method :resolve_observation
+
+          def self.game_input(data, resolved)
+            event_id = data.fetch(:event_id).to_s
+            competition_id = data[:competition_id].presence || event_id
+            Canonical::GameInput.new(**game_attributes(data, event_id, competition_id, resolved))
+          end
+          private_class_method :game_input
+
+          def self.game_attributes(data, event_id, competition_id, resolved) # rubocop:disable Metrics/MethodLength
+            observation = resolved.fetch(:observation)
+            {
+              provider_identities: game_identities(event_id, competition_id),
+              scheduled_at: resolved.fetch(:scheduled_at),
+              lifecycle: observation.lifecycle,
+              neutral_site: false,
+              season_year: season_identity(data.fetch(:season_year)),
+              season_phase_key: data.fetch(:season_phase_key).to_s,
+              schedule_group: schedule_group(data.fetch(:week_number)),
+              venue: nil,
+              participants: %i[home away].map do |role|
+                participant(data.fetch(role), role, observation)
+              end,
+              progress: observation.progress
+            }
+          end
+          private_class_method :game_attributes
+
+          def self.season_identity(value)
+            Integer(value, exception: false) || value.to_s
+          end
+          private_class_method :season_identity
+
+          def self.game_identities(event_id, competition_id)
+            [
+              Canonical::ProviderIdentityRef.new(provider: "sandbox", namespace: "event", id: event_id),
+              Canonical::ProviderIdentityRef.new(
+                provider: "sandbox",
+                namespace: "competition",
+                id: competition_id.to_s
+              )
+            ].uniq
+          end
+          private_class_method :game_identities
+
+          def self.schedule_group(number)
+            week = Integer(number)
+            Canonical::ScheduleGroupInput.new(kind: "week", number: week, name: "Week #{week}")
+          end
+          private_class_method :schedule_group
+
+          def self.participant(raw, role, observation)
+            data = raw.symbolize_keys
+            Canonical::ParticipantInput.new(**participant_attributes(data, role, observation))
+          end
+          private_class_method :participant
+
+          def self.participant_attributes(data, role, observation)
+            {
+              provider_identities: [team_identity(data.fetch(:provider_id))],
+              team_name: data.fetch(:name).to_s,
+              team_nickname: data[:nickname].presence,
+              team_abbreviation: data[:abbreviation].presence,
+              role: role.to_s,
+              score: observation.public_send("#{role}_score"),
+              result: observation.public_send("#{role}_result"),
+              record_summary: nil
+            }
+          end
+          private_class_method :participant_attributes
+
+          def self.team_identity(provider_id)
+            Canonical::ProviderIdentityRef.new(
+              provider: "espn",
+              namespace: "team",
+              id: provider_id.to_s
+            )
+          end
+          private_class_method :team_identity
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/sandbox/nfl_helpers/synthetic_observation.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Sandbox
+      module NflHelpers
+        module SyntheticObservation
+          Current = Data.define(:lifecycle, :progress, :home_score, :away_score)
+          Observation = Data.define(
+            :lifecycle,
+            :progress,
+            :home_score,
+            :away_score,
+            :home_result,
+            :away_result
+          )
+
+          QUARTER_SECONDS = TimelineObservation::QUARTER_SECONDS
+          HALFTIME_SECONDS = TimelineObservation::HALFTIME_SECONDS
+          TOTAL_SECONDS = TimelineObservation::TOTAL_SECONDS
+
+          module_function
+
+          def call(now:, kickoff:, plan:, current:)
+            proposed = TimelineObservation.call(now: now, kickoff: kickoff, plan: plan)
+            MonotonicObservation.call(proposed: proposed, current: current, plan: plan)
+          end
+        end
+      end
+    end
+  end
+end

data/app/adapters/jumbotron/adapters/sandbox/nfl_helpers/timeline_observation.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Sandbox
+      module NflHelpers
+        module TimelineObservation
+          QUARTER_SECONDS = 27.5.minutes.to_i
+          HALFTIME_SECONDS = 10.minutes.to_i
+          ACTIVE_SECONDS = QUARTER_SECONDS * 4
+          TOTAL_SECONDS = ACTIVE_SECONDS + HALFTIME_SECONDS
+          GAME_CLOCK_SECONDS = 15.minutes.to_i
+          STAGES = [
+            [QUARTER_SECONDS, :q1],
+            [QUARTER_SECONDS * 2, :q2],
+            [(QUARTER_SECONDS * 2) + HALFTIME_SECONDS, :halftime],
+            [(QUARTER_SECONDS * 3) + HALFTIME_SECONDS, :q3],
+            [TOTAL_SECONDS, :q4]
+          ].freeze
+
+          module_function
+
+          def call(now:, kickoff:, plan:)
+            elapsed = elapsed_seconds(now, kickoff)
+            return scheduled_observation if elapsed.negative?
+            return completed_observation(plan) if elapsed >= TOTAL_SECONDS
+
+            stage_observation(stage_for(elapsed), elapsed, plan)
+          end
+
+          def elapsed_seconds(now, kickoff)
+            now.to_time.to_f - kickoff.to_time.to_f
+          rescue ArgumentError, NoMethodError, TypeError
+            raise ArgumentError, "sandbox observation requires valid now and kickoff times"
+          end
+          private_class_method :elapsed_seconds
+
+          def stage_for(elapsed)
+            STAGES.find { |ending, _stage| elapsed < ending }.last
+          end
+          private_class_method :stage_for
+
+          def stage_observation(stage, elapsed, plan)
+            return halftime_observation(plan) if stage == :halftime
+
+            quarter = { q1: 1, q2: 2, q3: 3, q4: 4 }.fetch(stage)
+            local = local_elapsed(stage, elapsed)
+            active_observation(quarter, local, active_elapsed(stage, local), plan)
+          end
+          private_class_method :stage_observation
+
+          def local_elapsed(stage, elapsed)
+            offsets = {
+              q1: 0,
+              q2: QUARTER_SECONDS,
+              q3: (QUARTER_SECONDS * 2) + HALFTIME_SECONDS,
+              q4: (QUARTER_SECONDS * 3) + HALFTIME_SECONDS
+            }
+            elapsed - offsets.fetch(stage)
+          end
+          private_class_method :local_elapsed
+
+          def active_elapsed(stage, local)
+            completed_quarters = { q1: 0, q2: 1, q3: 2, q4: 3 }.fetch(stage)
+            (completed_quarters * QUARTER_SECONDS) + local
+          end
+          private_class_method :active_elapsed
+
+          def scheduled_observation
+            ObservationValues.observation(lifecycle: "scheduled")
+          end
+          private_class_method :scheduled_observation
+
+          def active_observation(quarter, local, active_elapsed, plan)
+            fraction = active_elapsed / ACTIVE_SECONDS.to_f
+            ObservationValues.observation(
+              lifecycle: "in_progress",
+              progress: ObservationValues.progress(state: "active", quarter: quarter, clock: clock(local)),
+              home_score: ObservationValues.score_at(plan.home_score, fraction),
+              away_score: ObservationValues.score_at(plan.away_score, fraction)
+            )
+          end
+          private_class_method :active_observation
+
+          def halftime_observation(plan)
+            ObservationValues.observation(
+              lifecycle: "in_progress",
+              progress: ObservationValues.progress(state: "intermission", quarter: 2),
+              home_score: ObservationValues.score_at(plan.home_score, 0.5),
+              away_score: ObservationValues.score_at(plan.away_score, 0.5)
+            )
+          end
+          private_class_method :halftime_observation
+
+          def completed_observation(plan)
+            home_result, away_result = ObservationValues.results(plan.home_score, plan.away_score)
+            ObservationValues.observation(
+              lifecycle: "completed",
+              home_score: plan.home_score,
+              away_score: plan.away_score,
+              home_result: home_result,
+              away_result: away_result
+            )
+          end
+          private_class_method :completed_observation
+
+          def clock(local_seconds)
+            ObservationValues.clock(
+              local_seconds: local_seconds,
+              quarter_seconds: QUARTER_SECONDS,
+              game_clock_seconds: GAME_CLOCK_SECONDS
+            )
+          end
+          private_class_method :clock
+        end
+      end
+    end
+  end
+end

data/app/deserializers/jumbotron/deserializers/public/register_sandbox_projection.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Deserializers
+    module Public
+      class RegisterSandboxProjection < CommandTower::Deserializers::ApplicationDeserializer
+        FIELDS = %i[sport league season season_phase].freeze
+
+        def call(params)
+          name = unwrap(require_string(unwrap(fetch_param(params, :name)), field: "name"))
+          return name if deserializer_result?(name)
+
+          source = unwrap(fetch_param(params, :source))
+          return source if deserializer_result?(source)
+          return invalid("source must be a hash") unless source.is_a?(Hash)
+
+          selector = parse_selector(source)
+          return selector if deserializer_result?(selector)
+
+          success(Jumbotron::Public::RegisterSandboxProjectionRequest.new(name: name, source: selector))
+        end
+
+        private
+
+        def parse_selector(source)
+          values = FIELDS.to_h do |field|
+            value = source[field] || source[field.to_s]
+            parsed = unwrap(require_string(value, field: "source.#{field}"))
+            return parsed if deserializer_result?(parsed)
+
+            [field, parsed]
+          end
+          Jumbotron::Public::SandboxScheduleSelector.new(**values)
+        end
+
+        def invalid(message)
+          failure(errors: [{ code: "invalid_request", message: message }])
+        end
+      end
+    end
+  end
+end

data/app/deserializers/jumbotron/deserializers/public/reset_sandbox_projection.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Jumbotron
+  module Deserializers
+    module Public
+      class ResetSandboxProjection < CommandTower::Deserializers::ApplicationDeserializer
+        def call(params)
+          sandbox = unwrap(require_string(unwrap(fetch_param(params, :sandbox)), field: "sandbox"))
+          return sandbox if deserializer_result?(sandbox)
+
+          start_week = positive_integer(params, :start_week)
+          return start_week if deserializer_result?(start_week)
+
+          anchor_day = positive_integer(params, :anchor_day)
+          return anchor_day if deserializer_result?(anchor_day)
+
+          now = parse_time(unwrap(fetch_param(params, :now)))
+          return now if deserializer_result?(now)
+
+          success(
+            Jumbotron::Public::ResetSandboxProjectionRequest.new(
+              sandbox: sandbox,
+              start_week: start_week,
+              anchor_day: anchor_day,
+              now: now
+            )
+          )
+        end
+
+        private
+
+        def positive_integer(params, field)
+          raw = unwrap(fetch_param(params, field))
+          return raw if deserializer_result?(raw)
+
+          unwrap(require_integer(raw, field: field.to_s, min: 1))
+        end
+
+        def parse_time(raw)
+          return raw if raw.is_a?(Time) || raw.is_a?(ActiveSupport::TimeWithZone)
+
+          Time.iso8601(raw.to_s)
+        rescue ArgumentError, TypeError
+          failure(errors: [{ code: "invalid_request", message: "now must be an ISO8601 time" }])
+        end
+      end
+    end
+  end
+end

data/app/errors/jumbotron/error.rb

@@ -2,5 +2,12 @@
 
 module Jumbotron
   class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(message = nil, code: "internal_error", details: {})
+      @code = code.to_s
+      @details = details || {}
+      super(message)
+    end
   end
 end

data/app/errors/jumbotron/errors/sandbox.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Errors
+    module Sandbox
+      class InvalidGameError < CommandTower::Errors::ApplicationError
+        def code
+          "invalid_sandbox_game"
+        end
+
+        def message
+          "game is not an eligible sandbox game"
+        end
+      end
+
+      class OutcomeLineUnavailableError < CommandTower::Errors::ApplicationError
+        def code
+          "sandbox_outcome_line_unavailable"
+        end
+
+        def message
+          "sandbox outcome requires current home spread and over total lines"
+        end
+      end
+
+      class InvalidProgressionStateError < CommandTower::Errors::ApplicationError
+        def code
+          "invalid_sandbox_progression_state"
+        end
+
+        def message
+          details.is_a?(Hash) && details[:message].present? ? details[:message].to_s : "sandbox state cannot progress"
+        end
+      end
+
+      class ProjectionNotFoundError < CommandTower::Errors::ApplicationError
+        def code
+          "sandbox_not_found"
+        end
+
+        def message
+          "sandbox projection was not found"
+        end
+      end
+
+      class ProjectionConflictError < CommandTower::Errors::ApplicationError
+        def code
+          "sandbox_projection_conflict"
+        end
+
+        def message
+          "sandbox projection conflicts with its registered source"
+        end
+      end
+
+      class ProjectionRejectedError < CommandTower::Errors::ApplicationError
+        def code
+          details.is_a?(Hash) && details[:code].present? ? details[:code].to_s : "sandbox_projection_incomplete"
+        end
+
+        def message
+          details.is_a?(Hash) && details[:message].present? ? details[:message].to_s : "sandbox projection was rejected"
+        end
+      end
+    end
+  end
+end

data/app/errors/jumbotron/sandbox_reset_rejected_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class SandboxResetRejectedError < Error
+  end
+end

data/app/models/jumbotron/game.rb

@@ -34,6 +34,17 @@ module Jumbotron
     has_many :teams, through: :game_participants
     has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
     has_many :line_observations, inverse_of: :game, dependent: :restrict_with_exception
+    has_one :sandbox_game_plan, inverse_of: :game, dependent: :restrict_with_exception
+    has_many :source_sandbox_game_mappings,
+             class_name: "Jumbotron::SandboxGameMapping",
+             foreign_key: :source_game_id,
+             inverse_of: :source_game,
+             dependent: :restrict_with_exception
+    has_one :sandbox_game_mapping,
+            class_name: "Jumbotron::SandboxGameMapping",
+            foreign_key: :sandbox_game_id,
+            inverse_of: :sandbox_game,
+            dependent: :restrict_with_exception
 
     attribute :lifecycle, :string, default: "scheduled"
     attribute :neutral_site, :boolean, default: false

data/app/models/jumbotron/public/translate_outcome.rb

@@ -10,6 +10,7 @@ module Jumbotron
         season_not_found
         season_phase_not_found
         schedule_group_not_found
+        sandbox_not_found
       ].freeze
 
       module_function
@@ -25,29 +26,34 @@ module Jumbotron
       end
 
       def public_error_for(result)
-        code, message = error_code_and_message(result)
+        code, message, details = error_code_message_and_details(result)
         klass = exception_class_for(code)
-        klass.new(message)
+        klass.new(message, code: code, details: details)
       end
       module_function :public_error_for
 
-      def error_code_and_message(result)
+      def error_code_message_and_details(result) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         error = Array(result.errors).first
         case error
         when CommandTower::Errors::ApplicationError
-          [error.code.to_s, error.message]
+          [error.code.to_s, error.message, error.details || {}]
         when Hash
-          [(error[:code] || error["code"]).to_s, (error[:message] || error["message"]).to_s]
+          [
+            (error[:code] || error["code"]).to_s,
+            (error[:message] || error["message"]).to_s,
+            error[:details] || error["details"] || {}
+          ]
         else
-          ["internal_error", error.to_s]
+          ["internal_error", error.to_s, {}]
         end
       end
-      module_function :error_code_and_message
+      module_function :error_code_message_and_details
 
       def exception_class_for(code)
         return Jumbotron::NotFoundError if NOT_FOUND_CODES.include?(code)
         return Jumbotron::InvalidRequestError if code == "invalid_request"
         return Jumbotron::UnsupportedCapabilityError if code == "unsupported"
+        return Jumbotron::SandboxResetRejectedError if code.start_with?("sandbox_", "source_", "anchor_")
 
         Jumbotron::Error
       end

data/app/models/jumbotron/public.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jumbotron
-  module Public
+  module Public # rubocop:disable Metrics/ModuleLength
     ALLOWED_INCLUDES = %i[consensus current_lines consensus_constituents].freeze
 
     Sport = Data.define(:id, :name)
@@ -10,6 +10,23 @@ module Jumbotron
     SeasonPhase = Data.define(:id, :name)
     ScheduleGroup = Data.define(:id, :kind, :number, :name)
     ScheduleGroupEnumeration = Data.define(:groups, :completeness)
+    SandboxScheduleSelector = Data.define(:sport, :league, :season, :season_phase)
+    RegisterSandboxProjectionRequest = Data.define(:name, :source)
+    ResetSandboxProjectionRequest = Data.define(:sandbox, :start_week, :anchor_day, :now)
+    SandboxProjection = Data.define(:name, :source, :sandbox)
+    SandboxProjectionReset = Data.define(
+      :projection,
+      :source_anchor_date,
+      :target_anchor_date,
+      :date_shift_days,
+      :projected_game_count,
+      :added_game_count,
+      :updated_game_count,
+      :removed_game_count,
+      :start_week_game_count,
+      :naturally_locked_game_count,
+      :reset_at
+    )
     ScheduleGroupsRequest = Data.define(
       :league_id,
       :sport,

data/app/models/jumbotron/sandbox_game_mapping.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class SandboxGameMapping < ApplicationRecord
+    belongs_to :sandbox_projection, inverse_of: :sandbox_game_mappings
+    belongs_to :source_game, class_name: "Jumbotron::Game", inverse_of: :source_sandbox_game_mappings
+    belongs_to :sandbox_game, class_name: "Jumbotron::Game", inverse_of: :sandbox_game_mapping
+
+    validates :source_game_id, uniqueness: { scope: :sandbox_projection_id }
+    validates :sandbox_game_id, uniqueness: true
+    validates :home_spread, :total, numericality: true
+    validates :line_fingerprint, presence: true
+    validate :games_are_in_expected_worlds
+
+    private
+
+    def games_are_in_expected_worlds
+      return if source_game.nil? || sandbox_game.nil?
+      return if source_game.league.name != "nfl-sandbox" && sandbox_game.league.name == "nfl-sandbox"
+
+      errors.add(:base, "mapping requires live source and sandbox target games")
+    end
+  end
+end

data/app/models/jumbotron/sandbox_game_plan.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class SandboxGamePlan < ApplicationRecord
+    IMMUTABLE_ATTRIBUTES = %w[game_id home_score away_score selected_at].freeze
+
+    belongs_to :game, inverse_of: :sandbox_game_plan
+
+    validates :game_id, uniqueness: true
+    validates :home_score, :away_score,
+              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validates :selected_at, presence: true
+    validate :selected_outcome_is_immutable, on: :update
+
+    private
+
+    def selected_outcome_is_immutable
+      return unless IMMUTABLE_ATTRIBUTES.any? { |attribute| will_save_change_to_attribute?(attribute) }
+
+      errors.add(:base, "selected sandbox outcome is immutable")
+    end
+  end
+end

data/app/models/jumbotron/sandbox_projection.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class SandboxProjection < ApplicationRecord
+    belongs_to :source_season, class_name: "Jumbotron::Season", inverse_of: :source_sandbox_projections
+    belongs_to :source_anchor_phase, class_name: "Jumbotron::SeasonPhase"
+    belongs_to :sandbox_season, class_name: "Jumbotron::Season", inverse_of: :sandbox_projection
+    has_many :sandbox_game_mappings, inverse_of: :sandbox_projection, dependent: :restrict_with_exception
+
+    validates :name, presence: true, uniqueness: true, format: { with: /\A[a-z0-9][a-z0-9-]*\z/ }
+    validates :adapter_id, inclusion: { in: %w[sandbox_nfl] }
+    validates :calendar_time_zone, inclusion: { in: ActiveSupport::TimeZone.all.map(&:tzinfo).map(&:name) }
+    validate :anchor_phase_belongs_to_source
+    validate :source_and_sandbox_are_distinct
+
+    private
+
+    def anchor_phase_belongs_to_source
+      return if source_anchor_phase.nil? || source_anchor_phase.season_id == source_season_id
+
+      errors.add(:source_anchor_phase, "must belong to source season")
+    end
+
+    def source_and_sandbox_are_distinct
+      return unless source_season_id == sandbox_season_id
+
+      errors.add(:sandbox_season, "must differ from source season")
+    end
+  end
+end

data/app/models/jumbotron/sandbox_projection_data.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module SandboxProjectionData
+    Team = Data.define(:provider_id, :name, :nickname, :abbreviation)
+    Game = Data.define(
+      :source_game_id,
+      :event_id,
+      :competition_id,
+      :scheduled_at,
+      :season,
+      :season_phase,
+      :week_number,
+      :week_name,
+      :neutral_site,
+      :home,
+      :away,
+      :home_spread,
+      :total,
+      :line_fingerprint,
+      :line_source
+    )
+    Snapshot = Data.define(
+      :games,
+      :source_anchor_date,
+      :target_anchor_date,
+      :date_shift_days,
+      :fingerprint,
+      :start_week
+    )
+  end
+end

data/app/models/jumbotron/season.rb

@@ -7,6 +7,16 @@ module Jumbotron
     has_many :schedule_groups, inverse_of: :season, dependent: :restrict_with_exception
     has_many :games, inverse_of: :season, dependent: :restrict_with_exception
     has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+    has_many :source_sandbox_projections,
+             class_name: "Jumbotron::SandboxProjection",
+             foreign_key: :source_season_id,
+             inverse_of: :source_season,
+             dependent: :restrict_with_exception
+    has_one :sandbox_projection,
+            class_name: "Jumbotron::SandboxProjection",
+            foreign_key: :sandbox_season_id,
+            inverse_of: :sandbox_season,
+            dependent: :restrict_with_exception
 
     validates :name, presence: true
   end