jumbotron 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 727d9ee2cecff54934b335484762a677ebfa7ee2bfe4a7f7dc408e04b0f7f6b0
-  data.tar.gz: 3c16c45a725c58a7fc654172819752a9c4e69fd06f554353f51c8e127feb7eca
+  metadata.gz: 71a38ed750f1392e528a1039b2dd5cb33383581951da87f8261602d8fc20618c
+  data.tar.gz: b4d80cc8bbeeb0260f133838dd53d48f92315515be6f7e860e8c0ffb3d8526cd
 SHA512:
-  metadata.gz: c7334f554705bccc4937c73975a77defce7bf08f0aeb23d984652eaa05cc4e43ddcecb0d1f3414a25f0e970f0dc34573e0adbbfdbc489252aeee6156b2e69a78
-  data.tar.gz: a02bd5b23d138019d874124ac178652a8a8a936e238a1d1d9f2d54939903d03ea26accda1e72c90ba6899652f0fe41c73fd9593377b8b01ed0a8ef9889fb3654
+  metadata.gz: 9b5cdcb6ff223603581417cb047916d47675843b2758305240539dd596be15b20be07bf2c8056d4c46bb683b69bc3554f7b28f29e98f3cf4affbab401eddc6b4
+  data.tar.gz: '09e5f5b8f0edd4eae5c12a6443841193ad669d87736ac360cc63c37e1c5f02b0aa40eeeda25a224f7c1b45884602f721464bfb7b312b65667700a00869c61939'

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

@@ -51,7 +51,7 @@ module Jumbotron
 
         policy :live,
                type: :live_game_update,
-               cadence: Cadence.new(every: 1, unit: :minute),
+               cadence: Cadence.new(every: 30, unit: :second),
                eligible: lambda { |game, now:|
                  return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
                  return false if INTERRUPTED_LIFECYCLES.include?(game.lifecycle)

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

@@ -48,7 +48,7 @@ module Jumbotron
 
         policy :live,
                type: :live_game_update,
-               cadence: Cadence.new(every: 1, unit: :minute),
+               cadence: Cadence.new(every: 30, unit: :second),
                eligible: lambda { |game, now:|
                  return false if TERMINAL_LIFECYCLES.include?(game.lifecycle)
                  return false if INTERRUPTED_LIFECYCLES.include?(game.lifecycle)

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Deserializers
+    module Public
+      class Games < CommandTower::Deserializers::ApplicationDeserializer
+        def call(params)
+          raw = unwrap(fetch_param(params, :game_ids))
+          return raw if deserializer_result?(raw)
+          return failure(errors: [{ code: "invalid_request", message: "game_ids is required" }]) if raw.nil?
+          unless raw.is_a?(Array)
+            return failure(errors: [{ code: "invalid_request", message: "game_ids must be an array" }])
+          end
+
+          if raw.size > Jumbotron::Public::MAX_GAMES_IDS
+            return failure(
+              errors: [{
+                code: "invalid_request",
+                message: "game_ids exceeds maximum of #{Jumbotron::Public::MAX_GAMES_IDS}"
+              }]
+            )
+          end
+
+          ids = []
+          raw.each do |item|
+            coerced = unwrap(require_integer(item, field: "game_ids", min: 1))
+            return coerced if deserializer_result?(coerced)
+
+            ids << coerced
+          end
+
+          include_raw = unwrap(fetch_param(params, :include))
+          return include_raw if deserializer_result?(include_raw)
+
+          includes = unwrap(Includes.parse(include_raw))
+          return includes if deserializer_result?(includes)
+
+          success(Jumbotron::Public::GamesRequest.new(game_ids: ids.uniq, includes: includes))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Deserializers
+    module Public
+      class SandboxProjection < CommandTower::Deserializers::ApplicationDeserializer
+        def call(params)
+          name = unwrap(fetch_param(params, :name))
+          return name if deserializer_result?(name)
+          return failure(errors: [{ code: "invalid_request", message: "name is required" }]) if name.blank?
+
+          success(Jumbotron::Public::SandboxProjectionRequest.new(name: name.to_s))
+        end
+      end
+    end
+  end
+end

data/app/models/jumbotron/public.rb

@@ -13,7 +13,8 @@ module Jumbotron
     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)
+    SandboxProjectionRequest = Data.define(:name)
+    SandboxProjection = Data.define(:name, :source_label, :source, :sandbox)
     SandboxProjectionReset = Data.define(
       :projection,
       :source_anchor_date,
@@ -100,6 +101,10 @@ module Jumbotron
     )
     GameRequest = Data.define(:id, :includes)
     GameIdsRequest = Data.define(:game_ids)
+    # Bulk Game read — game_ids + optional includes (parity with #game / #schedule).
+    # Distinct from GameIdsRequest so consensus/current_lines stay include-free.
+    GamesRequest = Data.define(:game_ids, :includes)
+    MAX_GAMES_IDS = 64
     ScheduleRequest = Data.define(
       :league_id,
       :sport,

data/app/scheduling/jumbotron/scheduling/backends/sidekiq_cron.rb

@@ -10,8 +10,9 @@ module Jumbotron
 
         def materialize(schedules, **)
           klass = job_class
-          remove_stale(klass, schedules)
-          upsert_desired(klass, schedules)
+          applicable = sidekiq_expressible(schedules)
+          remove_stale(klass, applicable)
+          upsert_desired(klass, applicable)
         end
 
         def cron_string(cadence)
@@ -20,6 +21,15 @@ module Jumbotron
 
         private
 
+        # Five-field cron cannot express sub-minute cadences (Solid Queue / fugit can).
+        def sidekiq_expressible(schedules)
+          schedules.reject { |definition| second_unit?(definition.cadence.unit) }
+        end
+
+        def second_unit?(unit)
+          Clock.canonical_unit(unit) == :second
+        end
+
         def remove_stale(klass, schedules)
           desired_ids = schedules.map(&:id)
           Array(klass.all).each do |job|

data/app/services/jumbotron/services/public/assemble_sandbox_projection.rb

@@ -9,6 +9,7 @@ module Jumbotron
         def call
           context.public_projection = Jumbotron::Public::SandboxProjection.new(
             name: projection.name,
+            source_label: source_label,
             source: selector(projection.source_season, projection.source_anchor_phase.name),
             sandbox: selector(projection.sandbox_season, projection.source_anchor_phase.name)
           )
@@ -16,6 +17,14 @@ module Jumbotron
 
         private
 
+        def source_label
+          [
+            projection.source_season.league.name.upcase,
+            projection.source_season.name,
+            projection.source_anchor_phase.name.titleize
+          ].join(" ")
+        end
+
         def selector(season, phase_name)
           Jumbotron::Public::SandboxScheduleSelector.new(
             sport: season.league.sport.name,

data/app/services/jumbotron/services/public/assemble_sandbox_projection_reset.rb

@@ -30,11 +30,20 @@ module Jumbotron
         def projection_identity
           Jumbotron::Public::SandboxProjection.new(
             name: projection.name,
+            source_label: source_label,
             source: selector(projection.source_season, projection.source_anchor_phase.name),
             sandbox: selector(projection.sandbox_season, projection.source_anchor_phase.name)
           )
         end
 
+        def source_label
+          [
+            projection.source_season.league.name.upcase,
+            projection.source_season.name,
+            projection.source_anchor_phase.name.titleize
+          ].join(" ")
+        end
+
         def selector(season, phase_name)
           Jumbotron::Public::SandboxScheduleSelector.new(
             sport: season.league.sport.name,

data/app/services/jumbotron/services/public/read_sandbox_projection.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Services
+    module Public
+      class ReadSandboxProjection < CommandTower::Services::ApplicationService
+        validate :name, required: true
+
+        def call
+          projection = Jumbotron::SandboxProjection.includes(
+            :source_anchor_phase,
+            source_season: { league: :sport },
+            sandbox_season: { league: :sport }
+          ).find_by(name:)
+          return reject if projection.nil?
+
+          context.projection = projection
+        end
+
+        private
+
+        def reject
+          context.fail!(
+            application_error: Jumbotron::Errors::Public::NotFoundError.new(
+              details: { code: "sandbox_not_found", message: "sandbox projection was not found" }
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/workflows/jumbotron/workflows/read_games_workflow.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Workflows
+    class ReadGamesWorkflow < CommandTower::Workflows::ApplicationWorkflow
+      include PublicRead
+
+      retry_strategy :none
+
+      def call(**kwargs)
+        deserialized = Deserializers::Public::Games.call(kwargs)
+        return map_deserializer_failure(deserialized) unless deserialized.success?
+
+        request = deserialized.input
+        loaded = Services::Public::LoadGamesByIds.call(game_ids: request.game_ids)
+        return map_service_failure(loaded) unless loaded.success?
+
+        games = Array(loaded.data[:games])
+        included = Services::Public::LoadIncludedLines.call(games: games, includes: request.includes)
+        return map_service_failure(included) unless included.success?
+
+        public_games = games.map do |game|
+          assembled = Services::Public::AssemblePublicGame.call(
+            game: game,
+            includes: request.includes,
+            current_lines: included.data[:current_lines],
+            consensus_lines: included.data[:consensus_lines]
+          )
+          return map_service_failure(assembled) unless assembled.success?
+
+          assembled.data[:public_game]
+        end
+
+        success(payload: { games: public_games }, http_status: :ok)
+      end
+    end
+  end
+end

data/app/workflows/jumbotron/workflows/sandbox/read_projection_workflow.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Workflows
+    module Sandbox
+      class ReadProjectionWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        include Jumbotron::Workflows::PublicRead
+
+        retry_strategy :none
+
+        def call(**kwargs)
+          deserialized = Jumbotron::Deserializers::Public::SandboxProjection.call(kwargs)
+          return map_deserializer_failure(deserialized) unless deserialized.success?
+
+          read = Jumbotron::Services::Public::ReadSandboxProjection.call(name: deserialized.input.name)
+          return map_service_failure(read) unless read.success?
+
+          assembled = Jumbotron::Services::Public::AssembleSandboxProjection.call(
+            projection: read.data[:projection]
+          )
+          return map_service_failure(assembled) unless assembled.success?
+
+          success(payload: { sandbox_projection: assembled.data[:public_projection] }, http_status: :ok)
+        end
+      end
+    end
+  end
+end

data/docs/upgrades/0.3.0.md

@@ -0,0 +1,31 @@
+# Upgrade: Jumbotron 0.3.0
+
+**From:** `0.2.0`  
+**To:** `0.3.0`
+
+Minor release: additive public read access for named sandbox projections and stable source labeling for host administration.
+
+## Host-facing change
+
+| Change | Host impact |
+|--------|-------------|
+| `Jumbotron.client.sandbox_projection` | Reads a named sandbox projection through the public workflow/client boundary without exposing persistence. Unknown names return the existing structured public failure contract. |
+| `SandboxProjection#source_label` | Public projection DTOs, including register/Reset results, now include a host-ready source label such as `NFL 2026 Regular Season`. |
+| Public read validation | Named projection reads use the same deserializer/service/workflow architecture as existing public operations. |
+
+## Upgrade checklist
+
+1. Bump the gem to `0.3.0` (or `>= 0.3.0`).
+2. No new migration. Hosts already on `0.2.0` do not need to copy or run Jumbotron migrations for this release.
+3. Hosts may read the configured source before offering a destructive Reset:
+
+   ```ruby
+   projection = Jumbotron.client.sandbox_projection(name: "nfl-sandbox")
+   projection.source_label
+   ```
+
+## What is not in this release
+
+- No sandbox projection or Reset persistence change.
+- No ESPN public Game/Schedule/Consensus/CurrentLines contract change.
+- No Pick'em administration UI or competitive-domain behavior.

data/docs/upgrades/0.4.0.md

@@ -0,0 +1,31 @@
+# Upgrade: Jumbotron 0.4.0
+
+**From:** `0.3.0`  
+**To:** `0.4.0`
+
+Minor release: adds a bulk public Game read, tightens live-game polling cadence to 30 seconds, and keeps the Sidekiq Cron scheduling backend safe for sub-minute cadences.
+
+## Host-facing change
+
+| Change | Host impact |
+|--------|-------------|
+| `Jumbotron.client.games(game_ids:, include:)` | Bulk public Game read (parity with `#game` / `#schedule`). Accepts up to 64 `game_ids`, dedupes and preserves request order, silently omits unknown ids, and composes `current_lines` / `consensus_lines` through the same `include` contract as other public reads. Requesting more than 64 ids raises `Jumbotron::InvalidRequestError`. |
+| ESPN and Sandbox `:live` adapter cadence | Live-game polling moved from every 1 minute to every 30 seconds. Hosts running the ESPN or Sandbox NFL adapters will see more frequent live-update scheduling. |
+| Sidekiq Cron scheduling backend | Sub-minute (`:second`) cadences are now excluded from the five-field cron materialization (five-field cron cannot express sub-minute schedules). Hosts on the Sidekiq Cron backend for a 30-second-cadence adapter must run the Solid Queue backend (or another cadence-aware backend) for that schedule to actually fire; Sidekiq Cron silently skips it rather than erroring. |
+
+## Upgrade checklist
+
+1. Bump the gem to `0.4.0` (or `>= 0.4.0`).
+2. No new migration. Hosts already on `0.3.0` do not need to copy or run Jumbotron migrations for this release.
+3. Hosts using the Sidekiq Cron scheduling backend with the ESPN or Sandbox NFL adapter should confirm their live-game schedule is served by a backend that supports sub-minute cadence (e.g. Solid Queue), since Sidekiq Cron now omits it rather than materializing an incorrect once-per-minute job.
+4. Hosts may call the new bulk read directly:
+
+   ```ruby
+   games = Jumbotron.client.games(game_ids: [101, 102, 103], include: [:consensus])
+   ```
+
+## What is not in this release
+
+- No sandbox projection or Reset persistence change.
+- No ESPN public Schedule/CurrentLines contract change beyond the `:live` cadence value.
+- No Pick'em administration UI or competitive-domain behavior.

data/lib/jumbotron/client.rb

@@ -2,6 +2,13 @@
 
 module Jumbotron
   class Client
+    def sandbox_projection(**)
+      Public::TranslateOutcome.call(
+        Workflows::Sandbox::ReadProjectionWorkflow.call(**),
+        payload_key: :sandbox_projection
+      )
+    end
+
     def register_sandbox_projection(**)
       Public::TranslateOutcome.call(
         Workflows::Sandbox::RegisterProjectionWorkflow.call(**),
@@ -37,6 +44,13 @@ module Jumbotron
       )
     end
 
+    def games(**)
+      Public::TranslateOutcome.call(
+        Workflows::ReadGamesWorkflow.call(**),
+        payload_key: :games
+      )
+    end
+
     def consensus(**)
       Public::TranslateOutcome.call(
         Workflows::ReadConsensusWorkflow.call(**),

data/lib/jumbotron/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jumbotron
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jumbotron
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: command_tower
@@ -130,9 +130,11 @@ files:
 - app/deserializers/jumbotron/deserializers/clients/espn/week.rb
 - app/deserializers/jumbotron/deserializers/public/game.rb
 - app/deserializers/jumbotron/deserializers/public/game_ids.rb
+- app/deserializers/jumbotron/deserializers/public/games.rb
 - app/deserializers/jumbotron/deserializers/public/includes.rb
 - app/deserializers/jumbotron/deserializers/public/register_sandbox_projection.rb
 - app/deserializers/jumbotron/deserializers/public/reset_sandbox_projection.rb
+- app/deserializers/jumbotron/deserializers/public/sandbox_projection.rb
 - app/deserializers/jumbotron/deserializers/public/schedule.rb
 - app/deserializers/jumbotron/deserializers/public/schedule_groups.rb
 - app/errors/jumbotron/error.rb
@@ -227,6 +229,7 @@ files:
 - app/services/jumbotron/services/public/map_public_consensus_lines.rb
 - app/services/jumbotron/services/public/map_public_current_lines.rb
 - app/services/jumbotron/services/public/read_game.rb
+- app/services/jumbotron/services/public/read_sandbox_projection.rb
 - app/services/jumbotron/services/public/read_schedule.rb
 - app/services/jumbotron/services/public/read_schedule_groups.rb
 - app/services/jumbotron/services/public/resolve_current_lines_for_games.rb
@@ -247,8 +250,10 @@ files:
 - app/workflows/jumbotron/workflows/read_consensus_workflow.rb
 - app/workflows/jumbotron/workflows/read_current_lines_workflow.rb
 - app/workflows/jumbotron/workflows/read_game_workflow.rb
+- app/workflows/jumbotron/workflows/read_games_workflow.rb
 - app/workflows/jumbotron/workflows/read_schedule_groups_workflow.rb
 - app/workflows/jumbotron/workflows/read_schedule_workflow.rb
+- app/workflows/jumbotron/workflows/sandbox/read_projection_workflow.rb
 - app/workflows/jumbotron/workflows/sandbox/register_projection_workflow.rb
 - app/workflows/jumbotron/workflows/sandbox/reset_projection_workflow.rb
 - app/workflows/jumbotron/workflows/synchronize_adapter_workflow.rb
@@ -269,6 +274,8 @@ files:
 - docs/upgrades/0.1.3.md
 - docs/upgrades/0.1.4.md
 - docs/upgrades/0.2.0.md
+- docs/upgrades/0.3.0.md
+- docs/upgrades/0.4.0.md
 - lib/jumbotron.rb
 - lib/jumbotron/client.rb
 - lib/jumbotron/engine.rb