spree_cm_commissioner 2.4.2 → 2.5.0.pre.pre1

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/polling/sync_zones.rb

@@ -0,0 +1,215 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Polling
+    class SyncZones
+      def initialize(client:, integration:, sync_result:)
+        @client = client
+        @integration = integration
+        @sync_result = sync_result
+      end
+
+      def call(external_match_id:)
+        raise SpreeCmCommissioner::Integrations::SyncError, 'external_match_id is required' if external_match_id.nil?
+
+        match_mapping = Spree::Taxon.find_integration_mapping(integration_id: @integration.id, external_id: external_match_id)
+        raise SpreeCmCommissioner::Integrations::SyncError, "Match not found: #{external_match_id}" if match_mapping.blank?
+
+        synced_zone_mappings = sync_zones!(match_mapping)
+        cleanup_stale_mappings!(match_mapping, synced_zone_mappings)
+      end
+
+      # Sync zones for a specific club and match
+      def sync_zones!(match_mapping)
+        external_club_id = match_mapping.external_payload&.dig('club_id')
+        raise SpreeCmCommissioner::Integrations::SyncError, 'club_id is required' if external_club_id.blank?
+
+        external_zones = begin
+          @sync_result.track_api_call('get_zones') { @client.get_zones!(club_id: external_club_id, match_id: match_mapping.external_id) }
+        rescue SpreeCmCommissioner::Integrations::ExternalClientError => e
+          raise SpreeCmCommissioner::Integrations::SyncError, "Failed to sync zones match #{match_mapping.external_id}: #{e.message}"
+        end
+
+        # match ID is not returned by API, but it is important info when creating tickets in the external system
+        # We need to set it manually on each zone object so that it can be used when creating tickets.
+        # This is a temporary workaround until the API returns the match ID
+        external_zones.each do |zone|
+          zone.set_match_id(match_mapping.external_id)
+        end
+
+        taxon_match_section = match_mapping.internal.children.first_or_create! { |s| s.name = 'Zones' }
+        synced_zone_mappings = external_zones.map do |external_zone|
+          sync_zone!(external_zone, match_mapping.internal, taxon_match_section)
+        end
+
+        CmAppLogger.log(
+          label: 'SyncZones#sync_zones! Zones synced for match',
+          data: { external_match_id: match_mapping.external_id }
+        )
+
+        synced_zone_mappings
+      end
+
+      private
+
+      def sync_zone!(external_zone, internal_match, taxon_match_section)
+        Spree::Product.transaction do
+          product_mapping = Spree::Product.find_or_initialize_integration_mapping(integration_id: @integration.id, external_id: external_zone._id)
+          product = product_mapping.internal
+
+          zone_option_type = Spree::OptionType.ticket_type
+          color_option_type = external_zone.color_brand.present? ? Spree::OptionType.color : nil
+
+          # Track zone sync
+          @sync_result.track(:zone, product) do |tracker|
+            product.assign_attributes(
+              status: :active,
+              tenant: @integration.tenant,
+              vendor: @integration.vendor,
+              product_type: :ecommerce,
+              event: internal_match,
+              taxons: [taxon_match_section],
+              name: external_zone.title.strip,
+              price: external_zone.online_price,
+              available_on: external_zone.start_datetime,
+              discontinue_on: external_zone.end_datetime,
+              option_types: [zone_option_type, color_option_type].compact,
+              shipping_category: Spree::ShippingCategory.first,
+              stores: [Spree::Store.default]
+            )
+            tracker.save_if_changed!(product)
+          end
+
+          product_mapping.mark_as_active!(external_payload: external_zone.to_h)
+
+          ensure_variant_with_zone_option_value!(product, external_zone, zone_option_type, color_option_type)
+          ensure_inventory!(product.variants[0], external_zone)
+
+          product_mapping
+        end
+      rescue ActiveRecord::RecordInvalid => e
+        CmAppLogger.error(
+          label: 'SyncZones#sync_zone Failed to save zone',
+          data: { zone_id: external_zone._id, error: e.message, backtrace: e.backtrace }
+        )
+        raise SpreeCmCommissioner::Integrations::SyncError, "Failed to save zone #{external_zone.title}: #{e.message}"
+      end
+
+      def ensure_variant_with_zone_option_value!(product, external_zone, zone_option_type, color_option_type)
+        option_values = [Spree::OptionValue.find_or_create_by_name!(zone_option_type, external_zone.title)]
+
+        if color_option_type.present? && external_zone.color_brand.present?
+          option_values << Spree::OptionValue.find_or_create_by_name!(color_option_type, external_zone.color_brand)
+        end
+
+        variant = product.variants.first_or_initialize
+
+        # Track variant sync
+        @sync_result.track(:variant, variant) do |tracker|
+          variant.assign_attributes(
+            vendor: @integration.vendor,
+            track_inventory: true,
+            product_type: :ecommerce,
+            price: external_zone.online_price,
+            discontinue_on: external_zone.end_datetime,
+            option_values: option_values
+          )
+          tracker.save_if_changed!(variant)
+        end
+      end
+
+      # Synchronize variant inventory with external StadiumX API
+      # Calculates the difference between external available seats and system inventory,
+      # then creates a stock movement to align system inventory with the external source.
+      #
+      # EXECUTION FLOW:
+      # 1. Calculate quantity difference between external and system inventory
+      # 2. Create StockMovement via StockMovementCreator (if difference != 0)
+      # 3. StockMovement.save triggers after_create callback → update_stock_item_quantity
+      # 4. StockItem.adjust_count_on_hand(quantity) updates count_on_hand
+      # 5. StockItem.save triggers after_commit callback → create_inventory_items (on first create)
+      # 6. InventoryItemsGeneratorJob → InventoryItemsGenerator → create_default_non_permanent_inventory_item!
+      # 7. Creates InventoryItem with quantity_available = stock_item.count_on_hand
+      # 8. StockMovementCreator enqueues InventoryItemsAdjusterJob (async)
+      # 9. InventoryItemsAdjuster.adjust_quantity!(quantity) updates existing inventory_items
+      # 10. Updates both DB (quantity_available, max_capacity) and Redis cache
+      #
+      # IMPORTANT: Inventory items are created AFTER stock item is saved (via callback).
+      # On first sync, the flow is: StockMovement → StockItem → InventoryItem creation → InventoryItem adjustment.
+      # On subsequent syncs: StockMovement → StockItem → InventoryItem adjustment only.
+      #
+      # Examples:
+      #
+      # 1. First sync (no inventory items yet):
+      #    - External available seats: 50
+      #    - System inventory: 0 (no inventory_items created)
+      #    - Stock movement created: +50 (initialize system to 50)
+      #    - Flow: StockMovement(+50) → StockItem.count_on_hand=50 → InventoryItem created with quantity=50 → Adjuster adjusts by +50
+      #
+      # 2. System has more inventory than external:
+      #    - External available seats: 20
+      #    - System inventory: 30
+      #    - Stock movement created: -10 (adjust system down to 20)
+      #    - Flow: StockMovement(-10) → StockItem.count_on_hand=20 → Adjuster adjusts inventory_item by -10
+      #
+      # 3. System has less inventory than external:
+      #    - External available seats: 50
+      #    - System inventory: 30
+      #    - Stock movement created: +20 (adjust system up to 50)
+      #    - Flow: StockMovement(+20) → StockItem.count_on_hand=50 → Adjuster adjusts inventory_item by +20
+      #
+      # 4. Already in sync:
+      #    - External available seats: 25
+      #    - System inventory: 25
+      #    - Stock movement created: 0 (no change needed)
+      #    - Flow: Early return, no operations performed
+      def ensure_inventory!(variant, external_zone)
+        raise ArgumentError, 'variant cannot be nil' if variant.nil? || variant.id.blank?
+        raise ArgumentError, 'external_zone cannot be nil' if external_zone.nil?
+
+        # NOTE: StadiumX zones have no permanent stock or date-based inventory, so we expect
+        # only one inventory item (index 0) per variant. Uses safe navigation to handle cases
+        # where inventory items haven't been created yet (first sync).
+        stock_location = variant.vendor.stock_locations.first || variant.vendor.send(:create_stock_location)
+        system_quantity = variant.inventory_items.active[0]&.quantity_in_redis || 0
+        external_quantity = external_zone.available_seats || 0
+
+        quantity_difference = external_quantity - system_quantity
+        return if quantity_difference.zero?
+
+        context = SpreeCmCommissioner::Stock::StockMovementCreator.call(
+          variant_id: variant.id,
+          stock_location_id: stock_location.id,
+          current_store: Spree::Store.default,
+          stock_movement_params: { quantity: quantity_difference }
+        )
+
+        return unless context.success?
+
+        @sync_result.increment_metric(:inventory, :adjusted, quantity_difference.abs)
+      end
+
+      # Archive stale zone mappings that are no longer in the external API
+      # Finds all active zone mappings for this integration and archives any
+      # that weren't included in the latest API response.
+      def cleanup_stale_mappings!(match_mapping, synced_zone_mappings)
+        synced_external_zone_ids = synced_zone_mappings.map(&:external_id)
+
+        # Find all active zone mappings for this integration and match
+        active_zone_mappings = SpreeCmCommissioner::IntegrationMapping.where(
+          integration_id: @integration.id,
+          internal_type: 'Spree::Product',
+          status: :active
+        ).where(internal_id: Spree::Product.where(event_id: match_mapping.internal_id).select(:id))
+
+        # Archive zones that are no longer in the API response
+        active_zone_mappings.find_each do |mapping|
+          next if synced_external_zone_ids.include?(mapping.external_id)
+
+          mapping.internal.discontinue!
+
+          mapping.mark_as_archived!
+          @sync_result.increment_metric(:zone, :discontinued)
+        end
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/base.rb

@@ -0,0 +1,20 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class Base
+      class << self
+        def from_collection(data)
+          return [] unless data['data'].is_a?(Array)
+
+          data['data'].map { |item| new(item) }
+        end
+      end
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          setter = "#{key}="
+          send(setter, value) if respond_to?(setter)
+        end
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/league.rb

@@ -0,0 +1,19 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class League < Base
+      attr_accessor :_id, :name, :logo
+
+      def initialize(attributes = {})
+        super(attributes)
+      end
+
+      def to_h
+        {
+          _id: _id,
+          name: name,
+          logo: logo
+        }.compact
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/match.rb

@@ -0,0 +1,95 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class Match < Base
+      attr_accessor :_id,
+                    :home_name,
+                    :home_logo,
+                    :away_name,
+                    :away_logo,
+                    :home_score,
+                    :away_score,
+                    :date,
+                    :time,
+                    :stadium,
+                    :week,
+                    :league_id,
+                    :club_id,
+                    :discount_ticket,
+                    :on_sale,
+                    :is_ended,
+                    :allow_predition,
+                    :file,
+                    :created_by,
+                    :updated_by,
+                    :zones,
+                    :promotion,
+                    :poster,
+                    :league
+
+      def initialize(attributes = {})
+        super(attributes)
+
+        @on_sale = attributes['on_sale'] != false
+        @is_ended = attributes['is_ended'] == true || attributes['is_ended'] == 'true'
+        @allow_predition = attributes['allow_predition'] == true || attributes['allow_predition'] == 'true'
+        @league = League.new(attributes['league']) if attributes['league'].is_a?(Hash)
+      end
+
+      def meta_title
+        return nil if home_name.blank? || away_name.blank?
+
+        "#{home_name} vs #{away_name} - #{display_match_datetime}"
+      end
+
+      def meta_description
+        return nil if home_name.blank? || away_name.blank?
+
+        location = stadium.present? ? " at #{stadium}" : ''
+        league_info = league&.name.present? ? " - #{league.name}" : ''
+
+        "#{home_name} vs #{away_name}#{league_info} on #{display_match_datetime}#{location}. Book tickets now!"
+      end
+
+      def display_match_datetime
+        match_datetime&.strftime('%B %d, %Y at %I:%M %p')
+      end
+
+      def match_datetime
+        return nil unless @date && @time
+
+        Time.zone.parse("#{@date} #{@time}")
+      rescue StandardError
+        nil
+      end
+
+      def to_h
+        {
+          _id: _id,
+          home_name: home_name,
+          home_logo: home_logo,
+          away_name: away_name,
+          away_logo: away_logo,
+          home_score: home_score,
+          away_score: away_score,
+          date: date,
+          time: time,
+          stadium: stadium,
+          week: week,
+          league_id: league_id,
+          club_id: club_id,
+          discount_ticket: discount_ticket,
+          on_sale: on_sale,
+          is_ended: is_ended,
+          allow_predition: allow_predition,
+          file: file,
+          created_by: created_by,
+          updated_by: updated_by,
+          zones: zones&.map(&:to_h),
+          promotion: promotion,
+          poster: poster,
+          league: league&.to_h
+        }.compact
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/ticket.rb

@@ -0,0 +1,81 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class Ticket < Base
+      attr_accessor :_id,
+                    :match_id,
+                    :uid,
+                    :first_uid,
+                    :generated_by,
+                    :club_id,
+                    :zone_id,
+                    :league_id,
+                    :token_id,
+                    :payment_method,
+                    :ticket_type,
+                    :remark,
+                    :is_used,
+                    :is_online,
+                    :used_at,
+                    :is_expired,
+                    :created_at,
+                    :updated_at,
+                    :cashback,
+                    :__v
+
+      def initialize(attributes = {})
+        super(attributes)
+
+        @is_used = attributes['is_used'] == true || attributes['is_used'] == 'true'
+        @is_online = attributes['is_online'] != false
+        @is_expired = attributes['is_expired'] == true || attributes['is_expired'] == 'true'
+        @created_at = parse_timestamp(attributes['created_at'])
+        @updated_at = parse_timestamp(attributes['updated_at'])
+        @used_at = parse_timestamp(attributes['used_at'])
+      end
+
+      def to_h
+        {
+          _id: _id,
+          match_id: match_id,
+          uid: uid,
+          first_uid: first_uid,
+          generated_by: generated_by,
+          club_id: club_id,
+          zone_id: zone_id,
+          league_id: league_id,
+          token_id: token_id,
+          payment_method: payment_method,
+          ticket_type: ticket_type,
+          remark: remark,
+          is_used: is_used,
+          is_online: is_online,
+          used_at: used_at&.iso8601,
+          is_expired: is_expired,
+          created_at: created_at&.iso8601,
+          updated_at: updated_at&.iso8601,
+          cashback: cashback,
+          __v: __v
+        }.compact
+      end
+
+      private
+
+      # Parses timestamp values from the Stadium X API response.
+      # The API returns timestamps in two formats:
+      # 1. Hash format with 'low' and 'high' properties (Long type from backend): {"low"=>239159874, "high"=>411, "unsigned"=>false}
+      # 2. Numeric format (milliseconds since epoch): 1702353644000
+      # Converts millisecond timestamps to Time objects in the application's timezone.
+      # Returns nil if the value is blank or in an unsupported format.
+      def parse_timestamp(value)
+        return nil if value.blank?
+
+        if value.is_a?(Hash)
+          timestamp_ms = (value['high'].to_i << 32) | value['low'].to_i
+          Time.zone.at(timestamp_ms / 1000)
+        elsif value.is_a?(Numeric)
+          Time.zone.at(value / 1000)
+        end
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/ticket_image.rb

@@ -0,0 +1,19 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class TicketImage < Base
+      attr_accessor :zone_id,
+                    :ticket_image
+
+      def initialize(attributes = {})
+        super(attributes)
+      end
+
+      def to_h
+        {
+          zone_id: zone_id,
+          ticket_image: ticket_image
+        }.compact
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/resources/zone.rb

@@ -0,0 +1,90 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Resources
+    class Zone < Base
+      attr_accessor :_id,
+                    :title,
+                    :color_brand,
+                    :total_seats,
+                    :online_price,
+                    :walkin_price,
+                    :match_id,
+                    :club_id,
+                    :is_active,
+                    :created_by,
+                    :updated_by,
+                    :created_at,
+                    :updated_at,
+                    :end_datetime,
+                    :is_earlybird,
+                    :start_datetime,
+                    :available_seats,
+                    :ticket_image
+
+      def initialize(attributes = {})
+        super(attributes)
+
+        @total_seats = attributes['total_seats'].to_i
+        @available_seats = attributes['available_seats'].to_i
+        @online_price = attributes['online_price'].to_f
+        @walkin_price = attributes['walkin_price'].to_f
+        @is_active = attributes['is_active'] != false
+        @color_brand = valid_hex_color?(attributes['color_brand']) ? attributes['color_brand'].upcase : nil
+
+        @created_at = Time.zone.at(attributes['created_at'] / 1000) if attributes['created_at'].present?
+        @updated_at = Time.zone.at(attributes['updated_at'] / 1000) if attributes['updated_at'].present?
+
+        @start_datetime = Time.zone.parse(attributes['start_datetime']) if attributes['start_datetime'].present?
+        @end_datetime = Time.zone.parse(attributes['end_datetime']) if attributes['end_datetime'].present?
+        @ticket_image = TicketImage.new(attributes['ticket_image']) if attributes['ticket_image'].is_a?(Hash)
+      end
+
+      # Manually set the match_id on the zone object.
+      # This is needed because the API does not return match_id but it's required for ticket creation.
+      # This is a temporary workaround until the API returns the match_id.
+      def set_match_id(match_id) # rubocop:disable Naming/AccessorMethodName
+        @match_id = match_id
+      end
+
+      def to_hash
+        hash = {
+          '_id' => _id,
+          'title' => title,
+          'color_brand' => color_brand,
+          'total_seats' => total_seats,
+          'online_price' => online_price,
+          'walkin_price' => walkin_price,
+          'match_id' => match_id,
+          'club_id' => club_id,
+          'is_active' => is_active,
+          'created_by' => created_by,
+          'updated_by' => updated_by,
+          'created_at' => created_at&.iso8601,
+          'updated_at' => updated_at&.iso8601,
+          'end_datetime' => end_datetime&.iso8601,
+          'is_earlybird' => is_earlybird,
+          'start_datetime' => start_datetime&.iso8601,
+          'available_seats' => available_seats,
+          'ticket_image' => ticket_image&.to_h
+        }.compact
+
+        hash['ticket_image'] = hash['ticket_image'].transform_keys(&:to_s) if hash['ticket_image']
+
+        hash
+      end
+
+      alias to_h to_hash
+
+      private
+
+      # Validates if a color value is a valid hex color code.
+      # Accepts formats: #RRGGBB, #RRGGBBAA, RRGGBB, RRGGBBAA (with or without # prefix)
+      # Returns true only if the value is a valid hex color, false otherwise.
+      def valid_hex_color?(value)
+        return false if value.blank?
+
+        hex_pattern = /\A#?([0-9a-fA-F]{6}|[0-9a-fA-F]{8})\z/
+        hex_pattern.match?(value.to_s)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/sync_manager.rb

@@ -0,0 +1,35 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  class SyncManager < ::SpreeCmCommissioner::Integrations::Base::SyncManager
+    # override
+    def sync_full!
+      run_execution(:full) do
+        SyncStrategies::FullSyncStrategy.new(
+          client: @client,
+          integration: @integration
+        ).call
+      end
+    end
+
+    # override
+    def sync_incremental!
+      run_execution(:incremental) do
+        SyncStrategies::IncrementalSyncStrategy.new(
+          client: @client,
+          integration: @integration
+        ).call
+      end
+    end
+
+    # override
+    def sync_webhook!(event_type:, event_data:)
+      run_execution(:webhook) do
+        SyncStrategies::WebhookSyncStrategy.new(
+          client: @client,
+          integration: @integration,
+          event_type: event_type,
+          event_data: event_data
+        ).call
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/sync_strategies/full_sync_strategy.rb

@@ -0,0 +1,38 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module SyncStrategies
+    # Full sync strategy - syncs all matches from external system.
+    #
+    # Runs on a schedule (e.g., daily) to fetch and update all matches from Stadium X V1 API.
+    # After full sync, IncrementalSyncStrategy will sync zone data one match at a time.
+    #
+    # Example flow:
+    #   1. Full sync runs at 2:00 AM
+    #      - Fetches all matches from Stadium X V1
+    #      - Creates/updates match records
+    #      - Creates integration mappings
+    #   2. Incremental sync runs every 10 seconds
+    #      - Syncs zone data for one match per interval
+    #      - Keeps data fresh without overwhelming the system
+    class FullSyncStrategy
+      def initialize(client:, integration:)
+        @client = client
+        @integration = integration
+        @sync_result = ::SpreeCmCommissioner::Integrations::Base::SyncResult.new
+      end
+
+      def call
+        begin
+          Polling::SyncMatches.new(
+            client: @client,
+            integration: @integration,
+            sync_result: @sync_result
+          ).call
+        rescue StandardError => e
+          @sync_result.record_error(e)
+        end
+
+        @sync_result
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/sync_strategies/incremental_sync_strategy.rb

@@ -0,0 +1,44 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module SyncStrategies
+    # Incremental sync strategy - syncs zones one match at a time.
+    #
+    # Runs every 10 seconds to sync zone data incrementally. Instead of syncing all matches
+    # at once (which would be slow), we sync one match per interval in round-robin order.
+    #
+    # Example with 3 matches:
+    #   10:00:00 - Sync zones for Match #1 (oldest last_synced_at)
+    #   10:00:10 - Sync zones for Match #2
+    #   10:00:20 - Sync zones for Match #3
+    #   10:00:30 - Sync zones for Match #1 again (cycle repeats)
+    #
+    # This ensures all matches get synced regularly without overwhelming the system.
+    class IncrementalSyncStrategy
+      def initialize(client:, integration:)
+        @client = client
+        @integration = integration
+        @sync_result = ::SpreeCmCommissioner::Integrations::Base::SyncResult.new
+      end
+
+      def call
+        begin
+          oldest_sync_mapping = Spree::Taxon.find_oldest_active_mapping(integration_id: @integration.id)
+          return @sync_result if oldest_sync_mapping.nil?
+
+          @sync_result.increment_metric(:match, :synced)
+
+          Polling::SyncZones.new(
+            integration: @integration,
+            client: @integration.client,
+            sync_result: @sync_result
+          ).call(external_match_id: oldest_sync_mapping.external_id)
+
+          oldest_sync_mapping.update!(last_synced_at: Time.current)
+        rescue StandardError => e
+          @sync_result.record_error(e)
+        end
+
+        @sync_result
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/sync_strategies/webhook_sync_strategy.rb

@@ -0,0 +1,16 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module SyncStrategies
+    class WebhookSyncStrategy
+      def initialize(client:, integration:, event_type:, event_data:)
+        @client = client
+        @integration = integration
+        @event_type = event_type
+        @event_data = event_data
+      end
+
+      def call
+        # TODO: Implement webhook sync logic
+      end
+    end
+  end
+end