spree_cm_commissioner 2.10.0 → 2.10.2.pre.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d59a44e1e25ec19ab8c634622f91006ea28bec265ea877dad8565cffa54bad3
-  data.tar.gz: 43415e8984f459f0387e110707963f4685c92251f589a2301342f82783c4e714
+  metadata.gz: e5552124388d0792051115573a9cc5e51044c8edcf7f8e89c6f03b43d2ebd0ab
+  data.tar.gz: '0694645f790079a03ebad09626ca155e7495c37ea8b45f83064a3c31b2aa6f75'
 SHA512:
-  metadata.gz: 1fbfc67d4bc18eb071d854b643ef3bfbaf1312b75f5c241020d58b09855ee234a58064ce08a104ee856b48dec25ce8547ad9c442cbd2648c83ad350c04fec3e1
-  data.tar.gz: 53317e748ac053ed6b60ec7e9accdd915266aa6b3e547692865191868d6051693dcad05dee73bed5e196b027fc27436e72fba2c62e05b3b33f806a7558618cf9
+  metadata.gz: 06b79003d8dee84088c17d6cd6f90b7d2b7d5eeca20b4045ca1775b467b3455b66898e72e47d33e9655a6b8b7c1b36dcef355b8b4ff5258daa066d87e8cdfb02
+  data.tar.gz: 386411dbfdd18ce5d25ade6d55e045b1bcaea788d3b8cb49437723789ab8e1e5e7e1b77e4cbece9ee962427f8b0c5c603c1cd1cdc091400ca8cf6e860dfd39a4

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.10.0)
+    spree_cm_commissioner (2.10.2.pre.pre1)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/controllers/spree/admin/vendor_authorized_users_controller.rb

@@ -14,6 +14,8 @@ module Spree
       end
 
       def update_telegram_chat
+        @vendor.update(preferred_telegram_alert_channels: submitted_alert_channels_mask)
+
         context = ::SpreeCmCommissioner::TelegramChatsFinder.call(
           telegram_chat_name: params['vendor']['preferred_telegram_chat_name'],
           telegram_chat_type: params['vendor']['preferred_telegram_chat_type']
@@ -34,6 +36,19 @@ module Spree
         redirect_to collection_url(@vendor)
       end
 
+      # OR the bits, never sum them. Sum is not idempotent: if the same bit arrives twice
+      # (duplicated checkbox, double-submit, hand-crafted post) 1 + 1 = 2, which silently means
+      # google_form instead of spree. ["0","1","1","16"].sum => 18 => [google_form, offline_sell];
+      # the same input OR'd => 17 => [spree, offline_sell].
+      #
+      # Masking against the known bits also drops junk from a crafted post (999 => 7).
+      def submitted_alert_channels_mask
+        known = SpreeCmCommissioner::OrderChannelBitwise::CHANNEL_ALERT_BITS.values.reduce(:|)
+
+        Array(params.dig(:vendor, :telegram_alert_channels))
+          .reduce(0) { |acc, value| acc | value.to_i } & known
+      end
+
       # @overrided
       def model_class
         Spree::User

data/app/controllers/spree/admin/vendors_controller_decorator.rb

@@ -5,10 +5,17 @@ module Spree
         base.before_action :build_logo, only: %i[create update]
         base.before_action :build_payment_qrcode, only: %i[create update]
         base.before_action :contruct_nearby_place, only: %i[create update]
+        base.before_action :compact_sellable_product_types, only: %i[create update]
       end
 
       private
 
+      def compact_sellable_product_types
+        return unless permitted_resource_params.key?(:sellable_product_types)
+
+        permitted_resource_params[:sellable_product_types] = permitted_resource_params[:sellable_product_types].compact_blank
+      end
+
       def contruct_nearby_place
         return unless permitted_resource_params.key?(:nearby_places_attributes)
 

data/app/errors/spree_cm_commissioner/reserved_blocks/locked_by_operator_error.rb

@@ -0,0 +1,25 @@
+module SpreeCmCommissioner
+  module ReservedBlocks
+    # Raised when a customer tries to hold or reserve a seat an operator has taken off sale.
+    #
+    # The customer-facing message deliberately says only "not available" — it must not leak the
+    # operator's reason (e.g. "held for staff"), which lives in private_metadata.
+    class LockedByOperatorError < StandardError
+      attr_reader :block_label
+
+      def initialize(block_label = nil)
+        @block_label = block_label
+        super()
+      end
+
+      # override
+      def message
+        if block_label.present?
+          I18n.t('line_item.validation.blocks_are_locked_by_operator_with_label', label: block_label)
+        else
+          I18n.t('line_item.validation.blocks_are_locked_by_operator')
+        end
+      end
+    end
+  end
+end

data/app/finders/spree_cm_commissioner/accommodations/find_variant.rb

@@ -15,8 +15,8 @@ module SpreeCmCommissioner
           .joins(:inventory_items)
           .where(vendor_id: vendor_id)
           .where(inventory_items: { inventory_date: stay_dates })
-          .where('CAST(public_metadata->\'cm_options\'->>\'number-of-adults\' AS INTEGER) +
-                  CAST(public_metadata->\'cm_options\'->>\'number-of-kids\' AS INTEGER) >= ?', number_of_guests
+          .where('CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-adults\' AS INTEGER) +
+                  CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-kids\' AS INTEGER) >= ?', number_of_guests
           )
           .where('inventory_items.quantity_available > 0')
           .distinct

data/app/jobs/spree_cm_commissioner/async_operation_job.rb

@@ -0,0 +1,27 @@
+module SpreeCmCommissioner
+  # Runs any AsyncOperation subclass. Same shape as ExportJob: load the record, call the one method the
+  # subclass implements.
+  #
+  # ApplicationJob, not ApplicationUniqueJob: `unique :until_executed` keys on the job arguments, and
+  # those carry a per-record id, so uniqueness could never collide -- it would buy a Redis lock for
+  # nothing. The in_progress? guard below is what actually makes a duplicate enqueue a no-op.
+  class AsyncOperationJob < ApplicationJob
+    queue_as :default
+
+    def perform(options = {})
+      operation = SpreeCmCommissioner::AsyncOperation.find_by(id: options[:async_operation_id])
+      return if operation.blank?
+
+      # Guard on `done` only, not on "not in progress". An exception below marks the operation failed and
+      # re-raises so Sidekiq retries -- guarding on in_progress? would make every one of those retries
+      # return here immediately, which is the opposite of retrying. Completed work is the thing that must
+      # never run twice; a failed operation is exactly what a retry is for.
+      return if operation.done?
+
+      operation.process!
+    rescue StandardError => e
+      operation&.fail!(e.message)
+      raise # ApplicationJob logs it; Sidekiq retries; Sentry captures.
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/ticket_transfers/expire_job.rb

@@ -0,0 +1,29 @@
+module SpreeCmCommissioner
+  module TicketTransfers
+    class ExpireJob < ApplicationJob
+      # Same window as OrderHolds::LockForPayment — gives an in-flight gateway
+      # redirect/webhook (e.g. PayWay, ACLEDA) room to resolve before we retry.
+      RETRY_DELAY = ENV.fetch('PAYMENT_LOCK_MIN_DURATION_IN_MINUTES', '5').to_i.minutes
+      MAX_RETRIES = 1
+      UNRESOLVED_PAYMENT_STATES = %w[checkout pending processing].freeze
+
+      def perform(transfer_id, attempt = 0)
+        ticket_transfer = SpreeCmCommissioner::TicketTransfer.find_by(id: transfer_id)
+        return unless ticket_transfer
+
+        if payment_in_progress?(ticket_transfer) && attempt < MAX_RETRIES
+          self.class.set(wait: RETRY_DELAY).perform_later(transfer_id, attempt + 1)
+          return
+        end
+
+        SpreeCmCommissioner::TicketTransfers::Expire.call(ticket_transfer: ticket_transfer)
+      end
+
+      private
+
+      def payment_in_progress?(ticket_transfer)
+        ticket_transfer.order&.payments&.where(state: UNRESOLVED_PAYMENT_STATES)&.exists? || false
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/voting_session_auto_close_job.rb

@@ -0,0 +1,22 @@
+module SpreeCmCommissioner
+  # Flips the Firestore `state` to closed once a manually-started vote window elapses.
+  #
+  # Enqueued by VotingSessionTimingConcern#start_vote! with wait_until: vote_close_at. Vote
+  # rejection does not depend on this job — can_vote? already gates on the persisted
+  # vote_close_at — so a missed run costs a stale label in the app, never an accepted late vote.
+  class VotingSessionAutoCloseJob < ApplicationJob
+    queue_as :default
+
+    def perform(voting_session_id)
+      voting_session = SpreeCmCommissioner::VotingSession.find_by(id: voting_session_id)
+      return if voting_session.nil?
+
+      # vote_close_at may have moved since this was scheduled (a restart, or the organizer
+      # pressing Stop Vote and starting a new window). Only publish once the window has genuinely
+      # elapsed; otherwise the run that matches the new vote_close_at will handle it.
+      return if voting_session.vote_close_at.present? && Time.current < voting_session.vote_close_at
+
+      SpreeCmCommissioner::VotingSessions::PublishToFirestore.call(voting_session: voting_session)
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/voting_session_firestore_publish_job.rb

@@ -0,0 +1,18 @@
+module SpreeCmCommissioner
+  # Pushes a voting session's live state to Firestore off the request cycle, so an organizer
+  # pressing "Start Vote" never waits on a Firestore round-trip.
+  #
+  # Takes an id rather than the record so a retry publishes the state as it is *now*, not as it
+  # was when the job was enqueued — a rapid start/pause/stop sequence must not have a stale
+  # retry overwrite the current state.
+  class VotingSessionFirestorePublishJob < ApplicationJob
+    queue_as :default
+
+    def perform(voting_session_id)
+      voting_session = SpreeCmCommissioner::VotingSession.find_by(id: voting_session_id)
+      return if voting_session.nil?
+
+      SpreeCmCommissioner::VotingSessions::PublishToFirestore.call(voting_session: voting_session)
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/firestore_connection.rb

@@ -0,0 +1,27 @@
+require 'google/cloud/firestore'
+
+module SpreeCmCommissioner
+  # Shared Cloud Firestore client construction.
+  #
+  # The waiting-room services each inline this same pair (see WaitingGuestsCaller#firestore);
+  # this concern is the extracted version for new writers, plus a #firestore_available? guard so
+  # environments without the credential (dev, test, CI) no-op instead of raising on connect.
+  module FirestoreConnection
+    extend ActiveSupport::Concern
+
+    def firestore_available?
+      service_account.present?
+    end
+
+    def firestore
+      @firestore ||= Google::Cloud::Firestore.new(
+        project_id: service_account[:project_id],
+        credentials: service_account
+      )
+    end
+
+    def service_account
+      @service_account ||= Rails.application.credentials.cloud_firestore_service_account
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/order_channel_bitwise.rb

@@ -0,0 +1,70 @@
+# Owns everything about an order's `channel`: the allowed values, how a stored value
+# resolves back to one of them, and the bitmask vendors use to choose which channels
+# may alert their Telegram group.
+#
+# `channel` is validated by PREFIX, not equality, because the CSV importer stores
+# "google_form-<import_order_id>-<slug>". Always compare via #channel_key, never `==`.
+module SpreeCmCommissioner
+  module OrderChannelBitwise
+    extend ActiveSupport::Concern
+
+    SPREE_CHANNEL = 'spree'.freeze
+    GOOGLE_FORM_CHANNEL = 'google_form'.freeze
+    TELEGRAM_CHANNEL = 'telegram'.freeze
+    TICKET_TRANSFER_CHANNEL = 'ticket_transfer'.freeze
+    OFFLINE_SELL_CHANNEL = 'offline_sell'.freeze
+
+    ALLOWED_CHANNEL_PREFIXES = [
+      SPREE_CHANNEL, GOOGLE_FORM_CHANNEL, TELEGRAM_CHANNEL, TICKET_TRANSFER_CHANNEL, OFFLINE_SELL_CHANNEL
+    ].freeze
+
+    # Matched longest-first so a future 'spree_x' can never be swallowed by 'spree'.
+    SORTED_CHANNEL_PREFIXES = ALLOWED_CHANNEL_PREFIXES.sort_by { |prefix| -prefix.length }.freeze
+
+    # Bit values are PERSISTED in vendor preferences and are a permanent contract.
+    # Never renumber, reorder, or reuse a bit. To retire a channel, leave its bit
+    # burned and take the next free power of two.
+    #
+    # Deliberately literal, never derived from ALLOWED_CHANNEL_PREFIXES.index —
+    # reordering that array would silently remap every vendor's saved setting.
+    CHANNEL_ALERT_BITS = {
+      SPREE_CHANNEL => 1,            # 1 << 0
+      GOOGLE_FORM_CHANNEL => 2,      # 1 << 1
+      TELEGRAM_CHANNEL => 4,         # 1 << 2
+      TICKET_TRANSFER_CHANNEL => 8,  # 1 << 3
+      OFFLINE_SELL_CHANNEL => 16     # 1 << 4
+    }.freeze
+
+    # Every bit currently in use, for masking untrusted input down to known channels.
+    KNOWN_CHANNEL_ALERT_BITS = CHANNEL_ALERT_BITS.values.reduce(:|).freeze
+
+    # Only online orders alert by default. google_form & ticket_transfer set the state column
+    # directly instead of firing the state machine, so they have never sent an alert; this
+    # default therefore encodes today's real behaviour rather than changing it.
+    DEFAULT_TELEGRAM_ALERT_CHANNELS = CHANNEL_ALERT_BITS[SPREE_CHANNEL]
+
+    included do
+      validate :validate_channel_prefix, if: :channel_changed?
+    end
+
+    # The stored channel may carry a suffix — the importer writes
+    # "google_form-<import_order_id>-<slug>" — so the prefix, not the whole
+    # string, is the channel's identity. Returns nil for an unrecognized channel.
+    def channel_key
+      SORTED_CHANNEL_PREFIXES.find { |prefix| channel&.start_with?(prefix) }
+    end
+
+    # Order was created by an operator through the back-office Sell Ticket console.
+    def offline_sell?
+      channel_key == OFFLINE_SELL_CHANNEL
+    end
+
+    private
+
+    def validate_channel_prefix
+      return if channel_key.present?
+
+      errors.add(:channel, "must start with one of the following: #{ALLOWED_CHANNEL_PREFIXES.join(', ')}")
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/order_state_machine.rb

@@ -1,7 +1,7 @@
 # Make sure to put this concern below other concern or methods that generating additional order info like guests, seat number, etc.
 # This will ensure that when each notification is sent with neccessary data.
 module SpreeCmCommissioner
-  module OrderStateMachine
+  module OrderStateMachine # rubocop:disable Metrics/ModuleLength
     extend ActiveSupport::Concern
 
     included do # rubocop:disable Metrics/BlockLength
@@ -271,15 +271,30 @@ module SpreeCmCommissioner
       return unless telegram_alert_enabled?
 
       vendor_list.each do |vendor|
-        title = '🎫 --- [NEW ORDER FROM BOOKME+] ---'
+        # `next`, not `return`: the mask is per-vendor, so one opted-out vendor on a
+        # multi-vendor order must not suppress the others.
+        next unless vendor.alerts_telegram_for_channel?(channel_key)
+
         chat_id = vendor.preferred_telegram_chat_id
-        if chat_id.present?
-          factory = OrderTelegramMessageFactory.new(title: title, order: self, vendor: vendor)
-          TelegramNotificationSenderJob.perform_later(chat_id: chat_id, message: factory.message, parse_mode: factory.parse_mode)
-        end
+        next if chat_id.blank?
+
+        factory = OrderTelegramMessageFactory.new(title: vendor_alert_title(vendor), order: self, vendor: vendor)
+        TelegramNotificationSenderJob.perform_later(chat_id: chat_id, message: factory.message, parse_mode: factory.parse_mode)
       end
     end
 
+    # White-label vendors announce their own brand; platform vendors stay BookMe+.
+    #
+    # vendor.name is operator-supplied data interpolated into an HTML parse_mode message
+    # (TelegramMessageFactory#header wraps the title in <b>), so it MUST be escaped —
+    # Telegram rejects unescaped &, < and > with "400 can't parse entities", and
+    # TelegramNotificationSender swallows that error, so the alert would vanish silently.
+    def vendor_alert_title(vendor)
+      return '🎫 --- [NEW ORDER FROM BOOKME+] ---' unless vendor.tenant_present?
+
+      "🎫 --- [NEW ORDER FROM #{CGI.escapeHTML(vendor.name.to_s)}] ---"
+    end
+
     def notify_order_complete_app_notification_to_user
       return if products.all?(&:vote_package?) # disable app push notification for vote package orders
 

data/app/models/concerns/spree_cm_commissioner/ticket_transferable.rb

@@ -5,11 +5,22 @@ module SpreeCmCommissioner
     included do
       has_one :ticket_transfer, class_name: 'SpreeCmCommissioner::TicketTransfer'
 
-      scope :not_ticket_transfer, -> { where.not(channel: SpreeCmCommissioner::OrderDecorator::TICKET_TRANSFER_CHANNEL) }
+      scope :not_ticket_transfer, -> { where.not(channel: SpreeCmCommissioner::OrderChannelBitwise::TICKET_TRANSFER_CHANNEL) }
     end
 
     def ticket_transfer?
-      channel == SpreeCmCommissioner::OrderDecorator::TICKET_TRANSFER_CHANNEL
+      channel == SpreeCmCommissioner::OrderChannelBitwise::TICKET_TRANSFER_CHANNEL
+    end
+
+    # Completes an accepted ticket transfer for this order. Called from
+    # Spree::Payment#after_completed, so the buyer's payment is already captured.
+    def complete_ticket_transfer_if_ready
+      return unless ticket_transfer?
+
+      transfer = ticket_transfer
+      return if transfer.blank? || !transfer.accepted?
+
+      SpreeCmCommissioner::TicketTransfers::Complete.call(ticket_transfer: transfer)
     end
   end
 end

data/app/models/concerns/spree_cm_commissioner/vendor_preference.rb

@@ -8,6 +8,25 @@ module SpreeCmCommissioner
       preference :telegram_chat_id, :string
       preference :telegram_chat_name, :string
       preference :telegram_chat_type, :string
+      preference :telegram_alert_channels, :integer, default: 1
+    end
+
+    # Should this vendor's Telegram group be alerted for an order on this channel?
+    # An unmapped channel alerts — a stray message is a better failure than silence.
+    def alerts_telegram_for_channel?(channel_key)
+      bit = SpreeCmCommissioner::OrderChannelBitwise::CHANNEL_ALERT_BITS[channel_key]
+      return true if bit.nil?
+
+      telegram_alert_channels_mask.anybits?(bit)
+    end
+
+    # Spree's getter is `preferences.fetch(name) { default }`, which falls back only when the
+    # key is ABSENT. A key present with a nil value returns nil, and nil.to_i == 0 would mute
+    # EVERY channel silently. Fall back to the default instead; a deliberate 0 survives
+    # because 0 is truthy in Ruby.
+    def telegram_alert_channels_mask
+      (preferred_telegram_alert_channels ||
+        SpreeCmCommissioner::OrderChannelBitwise::DEFAULT_TELEGRAM_ALERT_CHANNELS).to_i
     end
   end
 end

data/app/models/concerns/spree_cm_commissioner/voting_session_config_concern.rb

@@ -0,0 +1,87 @@
+module SpreeCmCommissioner
+  # The fraud_config/voting_config JSON stores and their derived, show-inheriting accessors.
+  # Extracted purely to keep VotingSession under RuboCop's Metrics/ClassLength — no behavior
+  # here depends on anything else in the concern split (unlike VotingSessionTimingConcern, whose
+  # enum/predicate ordering matters).
+  module VotingSessionConfigConcern
+    extend ActiveSupport::Concern
+
+    included do
+      store_accessor :fraud_config,
+                     :max_votes_per_minute_per_user,
+                     :max_votes_per_minute_per_ip,
+                     :max_accounts_per_device,
+                     :block_vpn,
+                     :max_votes_per_contestant_per_user
+
+      store_accessor :voting_config,
+                     :free_vote_limit,
+                     :free_vote_limit_type,
+                     :allow_user_to_get_free_vote,
+                     :paid_vote_enabled,
+                     :max_paid_votes_per_session,
+                     :sms_vote_enabled,
+                     :sms_vote_cost_usd,
+                     :operator_vote_enabled,
+                     :votes_weight,
+                     :voters_weight,
+                     :suggestion_top_n,
+                     :pre_vote_weight
+
+      validate :weights_present_for_weighted_sum
+    end
+
+    DEFAULT_SUGGESTION_TOP_N = 1
+
+    def effective_suggestion_top_n
+      suggestion_top_n&.to_i&.positive? ? suggestion_top_n.to_i : DEFAULT_SUGGESTION_TOP_N
+    end
+
+    def effective_voting_config
+      return {} unless show
+
+      config = parse_json_config(voting_config)
+      show_config = show.effective_voting_config
+      config.reverse_merge(show_config || {})
+    end
+
+    def effective_fraud_config
+      return {} unless show
+
+      config = parse_json_config(fraud_config)
+      show_config = show.effective_fraud_config
+      config.reverse_merge(show_config || {})
+    end
+
+    def max_votes_per_user
+      effective_voting_config['max_votes_per_user'] || 10
+    end
+
+    def rate_limit_window
+      effective_voting_config['rate_limit_window'] || 60
+    end
+
+    def rate_limit_max_votes
+      effective_voting_config['rate_limit_max_votes'] || 5
+    end
+
+    private
+
+    def weights_present_for_weighted_sum
+      return unless weighted_sum?
+
+      config = effective_voting_config
+      errors.add(:votes_weight, :blank) if config['votes_weight'].blank?
+      errors.add(:voters_weight, :blank) if config['voters_weight'].blank?
+    end
+
+    def parse_json_config(value)
+      return {} if value.nil? || value == ''
+      return value if value.is_a?(Hash)
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/voting_session_timing_concern.rb

@@ -0,0 +1,137 @@
+module SpreeCmCommissioner
+  # How a voting session's vote window (vote_open_at/vote_close_at) gets its values, kept
+  # deliberately separate from opens_at/closes_at — the show's own time slot within its episode
+  # (an episode can span many voting sessions, e.g. one per day of a week-long run), which has
+  # nothing to do with when voting is actually open.
+  #
+  # There is no mode flag: the presence of vote_open_at/vote_close_at is the signal.
+  #
+  #   Pre-set at creation  — auto-activates: once #activate flips status to enabled, can_vote?
+  #                          just compares Time.current against the already-real timestamps.
+  #   Left blank           — #start_vote! rewrites them to now / now + vote_duration_seconds the
+  #                          moment the organizer presses it, live during the broadcast.
+  #
+  # Both paths start at status: archived and reach enabled through one of two routes:
+  #
+  #   archived --(check "Visible")--> on_air --#start_vote!--> enabled  (progressive reveal, then vote)
+  #   archived ------------------------------#start_vote!--> enabled     (reveal and vote in one click)
+  #
+  # There is no separate "reveal" action: setting visible: true while archived (from the organizer
+  # dashboard's edit form) *is* the reveal — see #promote_from_archived_when_made_visible, which
+  # auto-transitions status to on_air in the same write rather than rejecting the attempt. on_air
+  # exists specifically so a session can show its contestants one by one — in sync with a live
+  # performance — before voting opens; it is visible but never votable (status isn't enabled, so
+  # can_vote? is false regardless of vote_open_at).
+  module VotingSessionTimingConcern
+    extend ActiveSupport::Concern
+
+    included do
+      validates :vote_duration_seconds, numericality: { greater_than: 0 }, allow_nil: true
+      validate :vote_closes_after_vote_opens
+
+      # before_update, not before_save: the `visible` column defaults to true at the DB level, so
+      # a brand-new record saved with the default status: archived (see
+      # ParamsConcern#force_archived_status_on_create, which explicitly sets visible: false too)
+      # must never auto-promote itself on its first save just because it hasn't touched `visible`
+      # yet — "reveal" is something an organizer does to an *existing* archived session.
+      before_update :promote_from_archived_when_made_visible
+      after_commit :publish_live_state_to_firestore, on: %i[create update], if: :live_state_changed?
+
+      scope :visible, -> { where(visible: true) }
+    end
+
+    # Columns the show screen renders. `display` is included because hiding a session should
+    # disappear from the app as promptly as opening one appears.
+    LIVE_STATE_COLUMNS = %w[status opens_at closes_at vote_open_at vote_close_at display visible].freeze
+
+    # Opens the vote window *now* rather than at a pre-set time, overriding whatever vote_open_at
+    # already held (a live show running early is exactly when this gets pressed). visible: true is
+    # set explicitly so this also works when called directly from archived — revealing and opening
+    # voting in one click, without going through on_air first.
+    def start_vote!
+      now = Time.current
+      update!(
+        vote_open_at: now,
+        vote_close_at: now + vote_duration_seconds.to_i.seconds,
+        status: :enabled,
+        visible: true
+      )
+
+      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
+    end
+
+    # Ends the vote window immediately and moves to closed. status: closed (not just a rewritten
+    # vote_close_at) matters for two reasons: votes are rejected the instant this runs, since
+    # can_vote? short-circuits on enabled? before ever comparing timestamps — no dependency on the
+    # inclusive Time#between? boundary at vote_close_at; and it's what triggers
+    # schedule_counter_reconciliation (only fires on saved_change_to_status?(enabled -> closed)),
+    # which would otherwise only run via the separate "Close" action, never on a manual stop.
+    #
+    # vote_close_at clamped to vote_open_at + 1s: an organizer who starts and immediately stops
+    # would otherwise produce vote_close_at == vote_open_at, which the closes-after-opens
+    # validation rejects — a validation error on what is a legitimate "cancel that" action.
+    def stop_vote!
+      opened_at = vote_open_at || Time.current
+      update!(status: :closed, vote_close_at: [Time.current, opened_at + 1.second].max)
+    end
+
+    # True when voting hasn't opened yet — either vote_open_at was never set, it's set but its
+    # time hasn't arrived, or status is on_air. The on_air check matters on its own: on_air can be
+    # revisited after a prior round already closed (an organizer reverting status by hand to
+    # re-reveal), in which case vote_open_at/vote_close_at are still populated from that earlier
+    # round and both in the past — without this, the timestamp check alone would say the window
+    # isn't pending, and Firestore's state_for would wrongly report 'closed' for a session that's
+    # actually on_air right now. Covers "never started," "pre-scheduled but not live yet," and
+    # "on_air again after a previous round" identically, since none of them is votable nor has a
+    # real countdown to show.
+    def vote_window_pending?
+      on_air? || vote_open_at.blank? || Time.current < vote_open_at
+    end
+
+    # Shifts vote_close_at by `seconds` (organizer-chosen at the moment, not necessarily
+    # vote_duration_seconds) without touching vote_open_at — distinct from #start_vote!, which
+    # would discard the time already elapsed by resetting the window to start now.
+    #
+    # Extends from max(vote_close_at, Time.current), not from the raw stored value: the
+    # controller also offers this once a window has already lapsed (status still enabled, nothing
+    # auto-flipped it to closed yet) specifically to reopen it. Adding straight to a stale
+    # vote_close_at sitting hours in the past would land the new value in the past too — "+10
+    # minutes" on a session that closed last night must mean 10 minutes from now, not 10 minutes
+    # from when it closed.
+    #
+    # `seconds` may be negative to cut a currently-open window short without a full Stop Vote;
+    # going negative enough to land at or before vote_open_at raises via the closes-after-opens
+    # validation.
+    def extend_vote!(seconds)
+      update!(vote_close_at: [vote_close_at, Time.current].max + seconds.to_i.seconds)
+
+      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
+    end
+
+    private
+
+    # archived sessions are prepped privately by default (visible starts false), but the organizer
+    # controls visibility directly from the edit form — checking "Visible to Viewers" while
+    # archived is the reveal action, not a separate button. Rather than rejecting that write, treat
+    # it as intent: promote status to on_air in the same save, so the session actually becomes
+    # reachable via the `current` scope (which never includes plain `archived`, regardless of
+    # `visible`). Setting visible: false while archived is a no-op — status simply stays archived.
+    def promote_from_archived_when_made_visible
+      self.status = 'on_air' if archived? && visible?
+    end
+
+    def vote_closes_after_vote_opens
+      return unless vote_open_at && vote_close_at
+
+      errors.add(:vote_close_at, :must_be_after_vote_opens_at) if vote_close_at <= vote_open_at
+    end
+
+    def live_state_changed?
+      LIVE_STATE_COLUMNS.any? { |column| saved_change_to_attribute?(column) }
+    end
+
+    def publish_live_state_to_firestore
+      SpreeCmCommissioner::VotingSessionFirestorePublishJob.perform_later(id)
+    end
+  end
+end