jumbotron 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57d3fe24f637b7b9bcbc402ebe85a11fb860d2b2593bfe1f53f47a1d55d3b62a
-  data.tar.gz: 0d5e96cfe46ff8dad640a4ee9677e9deedaf32df7183868f13adf4a37a236c30
+  metadata.gz: 02e887f5ad4260dddda6dde8d391430ffbad31b7b7069dd851e9560cd6f92540
+  data.tar.gz: 1a18545151d81f504bc9bf208316ff2b1cf68086f062cf590d0953f9ca28e546
 SHA512:
-  metadata.gz: aa98921803b8d0223cc523ce9f344857a28d71ace7140df51e026df0db2163252dd5747e9dbd0f1a849e1f0f8d3b415b00527cfccf1dc50e6c1f01d0b198c20d
-  data.tar.gz: b70bbde319e59a5b16b6f6b1484037034fdbe68dd3a87e163b96862c93f763dc5cdd0041305ddd164236b255b786858bd73e398bfe5133d4e7abd6d3789f580b
+  metadata.gz: c20c23af5c011df7a9ea866a1923e37abf79b3eea2dfe82e47b561051f3ba6bc43dfb519def7288007e71c7a801020e9d5b32f3d2a76be82c6b85061c2f9bbe1
+  data.tar.gz: 5414a02d268f32a257752bc29e47b959c46a0dc9b6d680da58c789ff22bd6d76a56a4c264a0068bc32f91aef79a40827b4568a731807dedfcf975966a452d63c

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

@@ -103,6 +103,7 @@ module Jumbotron
                 Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "team", id: team.id.to_s)
               ],
               team_name: name.to_s,
+              team_nickname: TeamNickname.resolve(team),
               role: competitor.home_away.to_s,
               score: coerce_score(competitor.score),
               result: coerce_result(competitor.winner, lifecycle)

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Adapters
+    module Espn
+      module NflHelpers
+        # Maps ESPN team identity fields into canonical nickname without parsing display_name.
+        # Precedence: nickname → name → short_display_name (provider fields only).
+        module TeamNickname
+          def self.resolve(team)
+            return nil if team.nil?
+
+            team.nickname.presence || team.name.presence || team.short_display_name.presence
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -24,7 +24,8 @@ module Jumbotron
               provider_identities: [
                 Canonical::ProviderIdentityRef.new(provider: "espn", namespace: "team", id: team.id.to_s)
               ],
-              name: name.to_s
+              name: name.to_s,
+              nickname: TeamNickname.resolve(team)
             )
           end
           private_class_method :transform_team

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

@@ -12,6 +12,7 @@ module Jumbotron
             field :display_name, type: Support.types.string, required: true
             field :short_display_name, type: Support.types.string, nullable: true
             field :name, type: Support.types.string, nullable: true
+            field :nickname, type: Support.types.string, nullable: true
             field :location, type: Support.types.string, nullable: true
           end
 
@@ -25,6 +26,7 @@ module Jumbotron
               display_name: Support.payload.fetch(payload, "displayName"),
               short_display_name: Support.payload.fetch(payload, "shortDisplayName"),
               name: Support.payload.fetch(payload, "name"),
+              nickname: Support.payload.fetch(payload, "nickname"),
               location: Support.payload.fetch(payload, "location")
             )
           end

data/app/models/jumbotron/canonical.rb

@@ -4,7 +4,11 @@ module Jumbotron
   module Canonical
     ProviderIdentityRef = Data.define(:provider, :namespace, :id)
 
-    TeamInput = Data.define(:provider_identities, :name)
+    TeamInput = Data.define(:provider_identities, :name, :nickname) do
+      def initialize(provider_identities:, name:, nickname: nil)
+        super
+      end
+    end
 
     VenueInput = Data.define(:provider_identities, :name)
 
@@ -13,8 +17,13 @@ module Jumbotron
       :team_name,
       :role,
       :score,
-      :result
-    )
+      :result,
+      :team_nickname
+    ) do
+      def initialize(provider_identities:, team_name:, role:, score:, result:, team_nickname: nil)
+        super
+      end
+    end
 
     ScheduleGroupInput = Data.define(:kind, :number, :name)
 

data/app/models/jumbotron/public.rb

@@ -19,7 +19,11 @@ module Jumbotron
       :season_phase,
       :kind
     )
-    Team = Data.define(:id, :name)
+    Team = Data.define(:id, :name, :nickname, :key) do
+      def initialize(id:, name:, key:, nickname: nil)
+        super(id:, name:, nickname:, key:)
+      end
+    end
     Venue = Data.define(:id, :name)
     Participant = Data.define(:role, :score, :result, :team)
     GameSegment = Data.define(:kind, :number)

data/app/models/jumbotron/team.rb

@@ -7,5 +7,16 @@ module Jumbotron
     has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
 
     validates :name, presence: true
+    validates :key, presence: true, uniqueness: true
+    validate :key_format_must_be_semantic
+
+    private
+
+    def key_format_must_be_semantic
+      return if key.blank?
+      return if Jumbotron::TeamKey.valid_format?(key)
+
+      errors.add(:key, "must be a lowercase kebab-case semantic key")
+    end
   end
 end

data/app/services/jumbotron/services/canonical/upsert_game_participant.rb

@@ -13,7 +13,8 @@ module Jumbotron
           team_result = UpsertTeam.call(
             team_input: Jumbotron::Canonical::TeamInput.new(
               provider_identities: participant_input.provider_identities,
-              name: participant_input.team_name
+              name: participant_input.team_name,
+              nickname: participant_input.team_nickname
             ),
             observed_at: observed_at,
             change_set: change_set

data/app/services/jumbotron/services/canonical/upsert_team.rb

@@ -57,6 +57,8 @@ module Jumbotron
             team.name = team_input.name
             team.changed_at = observed_at
           end
+          apply_nickname!(team)
+          # key is immutable after assignment — never regenerate from name or provider id
           team.observed_at = observed_at
           team.save!
           team
@@ -65,13 +67,51 @@ module Jumbotron
         def create_new!
           team = Team.create!(
             name: team_input.name,
+            nickname: team_input.nickname,
+            key: allocate_key!(team_input.name),
             observed_at: observed_at,
             changed_at: observed_at
           )
           change_set.record(subject: team, attribute: "name", previous: nil, new_value: team.name)
+          change_set.record(subject: team, attribute: "key", previous: nil, new_value: team.key)
+          if team.nickname.present?
+            change_set.record(
+              subject: team,
+              attribute: "nickname",
+              previous: nil,
+              new_value: team.nickname
+            )
+          end
           team
         end
 
+        def apply_nickname!(team)
+          return if team_input.nickname.nil?
+          return if team.nickname == team_input.nickname
+
+          change_set.record(
+            subject: team,
+            attribute: "nickname",
+            previous: team.nickname,
+            new_value: team_input.nickname
+          )
+          team.nickname = team_input.nickname
+          team.changed_at = observed_at
+        end
+
+        def allocate_key!(name)
+          base = Jumbotron::TeamKey.normalize(name)
+          return base unless Team.exists?(key: base)
+
+          suffix = 2
+          loop do
+            candidate = "#{base}-#{suffix}"
+            return candidate unless Team.exists?(key: candidate)
+
+            suffix += 1
+          end
+        end
+
         def recover_after_race!
           ref = team_input.provider_identities.first
           identity = ProviderIdentity.find_by!(

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

@@ -69,7 +69,12 @@ module Jumbotron
             role: participant.role,
             score: participant.score,
             result: participant.result,
-            team: Jumbotron::Public::Team.new(id: participant.team.id, name: participant.team.name)
+            team: Jumbotron::Public::Team.new(
+              id: participant.team.id,
+              name: participant.team.name,
+              nickname: participant.team.nickname,
+              key: participant.team.key
+            )
           )
         end
 

data/db/migrate/20260827150001_add_key_to_jumbotron_teams.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class AddKeyToJumbotronTeams < ActiveRecord::Migration[8.1]
+  def up
+    add_column :jumbotron_teams, :key, :string, limit: 191
+    backfill_keys!
+    change_column_null :jumbotron_teams, :key, false
+    add_index :jumbotron_teams, :key, unique: true, name: "index_jumbotron_teams_on_key"
+  end
+
+  def down
+    remove_index :jumbotron_teams, name: "index_jumbotron_teams_on_key"
+    remove_column :jumbotron_teams, :key
+  end
+
+  private
+
+  def backfill_keys!
+    say_with_time "backfill jumbotron_teams.key" do
+      taken = {}
+      connection.select_all("SELECT id, name FROM jumbotron_teams ORDER BY id").each do |row|
+        key = allocate_key(normalize_name(row["name"]), taken)
+        taken[key] = true
+        connection.execute(
+          "UPDATE jumbotron_teams SET `key` = #{connection.quote(key)} WHERE id = #{row['id'].to_i}"
+        )
+      end
+    end
+  end
+
+  def normalize_name(name)
+    slug = name.to_s.unicode_normalize(:nfc).downcase
+    slug = slug.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    slug = "team" if slug.blank?
+    slug
+  end
+
+  def allocate_key(base, taken)
+    return base unless taken[base]
+
+    suffix = 2
+    loop do
+      candidate = "#{base}-#{suffix}"
+      return candidate unless taken[candidate]
+
+      suffix += 1
+    end
+  end
+end

data/db/migrate/20260828180001_add_nickname_to_jumbotron_teams.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddNicknameToJumbotronTeams < ActiveRecord::Migration[8.0]
+  def change
+    add_column :jumbotron_teams, :nickname, :string
+  end
+end

data/lib/jumbotron/team_key.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  # Immutable semantic public team identity helper.
+  # Derives a kebab-case slug once at assignment; callers must not re-run on rename.
+  module TeamKey
+    FORMAT = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+    module_function
+
+    def normalize(name)
+      slug = name.to_s.unicode_normalize(:nfc).downcase
+      slug = slug.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      slug = "team" if slug.blank?
+      slug
+    end
+
+    def valid_format?(key)
+      key.to_s.match?(FORMAT)
+    end
+  end
+end

data/lib/jumbotron/version.rb

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

data/lib/jumbotron.rb

@@ -3,6 +3,7 @@
 require "rails"
 require "command_tower"
 require "jumbotron/version"
+require "jumbotron/team_key"
 require "jumbotron/engine"
 require "jumbotron/client"
 

data/spec/factories/jumbotron/team.rb

@@ -5,5 +5,11 @@ FactoryBot.define do
     sequence(:name) { |n| "Team #{n}" }
     observed_at { Time.current }
     changed_at { Time.current }
+
+    after(:build) do |team|
+      next if team.key.present?
+
+      team.key = Jumbotron::TeamKey.normalize(team.name)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jumbotron
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: command_tower
@@ -65,6 +65,7 @@ files:
 - app/adapters/jumbotron/adapters/espn/nfl_helpers/progress.rb
 - app/adapters/jumbotron/adapters/espn/nfl_helpers/scoreboard.rb
 - app/adapters/jumbotron/adapters/espn/nfl_helpers/season_phase.rb
+- app/adapters/jumbotron/adapters/espn/nfl_helpers/team_nickname.rb
 - app/adapters/jumbotron/adapters/espn/nfl_helpers/teams.rb
 - app/adapters/jumbotron/adapters/line_acquisition.rb
 - app/adapters/jumbotron/adapters/operation.rb
@@ -205,6 +206,8 @@ files:
 - db/migrate/20260813000001_create_jumbotron_schedule_groups.rb
 - db/migrate/20260814000001_create_jumbotron_line_observations.rb
 - db/migrate/20260820000001_add_progress_to_jumbotron_games.rb
+- db/migrate/20260827150001_add_key_to_jumbotron_teams.rb
+- db/migrate/20260828180001_add_nickname_to_jumbotron_teams.rb
 - docs/testing.md
 - docs/upgrades/0.1.2.md
 - docs/upgrades/0.1.3.md
@@ -212,6 +215,7 @@ files:
 - lib/jumbotron.rb
 - lib/jumbotron/client.rb
 - lib/jumbotron/engine.rb
+- lib/jumbotron/team_key.rb
 - lib/jumbotron/testing.rb
 - lib/jumbotron/version.rb
 - lib/tasks/jumbotron_schedules.rake