spree_cm_commissioner 2.5.0.pre.pre2 → 2.5.0.pre.pre4

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/inventory/unstock_inventory.rb

@@ -0,0 +1,83 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Inventory
+    class UnstockInventory
+      prepend ::Spree::ServiceModule::Base
+
+      def call(integration:, order:, line_items:)
+        ApplicationRecord.transaction do
+          line_items.each do |line_item|
+            raise SpreeCmCommissioner::Integrations::SyncError, 'Invalid guests' if line_item.guests.size != line_item.quantity
+
+            sync_line_item!(integration, order, line_item)
+          end
+
+          success(order: order, line_items: line_items)
+        end
+      rescue SpreeCmCommissioner::Integrations::SyncError,
+             SpreeCmCommissioner::Integrations::ExternalClientError => e
+        failure(nil, e.message)
+      end
+
+      def sync_line_item!(integration, order, line_item)
+        zone_mapping = line_item.product.integration_mappings.find_by(integration_id: integration.id)
+        raise SpreeCmCommissioner::Integrations::SyncError, 'Integration mapping not found for product' if zone_mapping.nil?
+
+        external_zone_id = zone_mapping.external_id
+        raise SpreeCmCommissioner::Integrations::SyncError, 'zone_id is required' if external_zone_id.blank?
+
+        external_match_id = zone_mapping.external_payload&.dig('match_id')
+        raise SpreeCmCommissioner::Integrations::SyncError, 'match_id is required' if external_match_id.blank?
+
+        external_club_id = zone_mapping.external_payload&.dig('club_id')
+        raise SpreeCmCommissioner::Integrations::SyncError, 'club_id is required' if external_club_id.blank?
+
+        tickets = integration.client.create_tickets!(
+          match_id: external_match_id,
+          user_id: order.number,
+          club_id: external_club_id,
+          zone_id: external_zone_id,
+          quantity: line_item.quantity
+        )
+
+        # External system did not create the correct number of tickets, we cannot proceed as it would lead to data inconsistency between systems.
+        # We raise an error to rollback the transaction & we can manually investigate the issue.
+        if tickets.size != line_item.quantity
+          raise SpreeCmCommissioner::Integrations::SyncError,
+                "Created tickets count (#{tickets.size}) does not match line item quantity (#{line_item.quantity})"
+        end
+
+        sync_guests!(line_item.guests, tickets, integration)
+
+        line_item_mapping = line_item.integration_mappings.find_or_initialize_by(
+          integration: integration,
+          external_id: tickets.map(&:_id).sort.join(',')
+        )
+        line_item_mapping.external_qr_data = group_ticket_qr_data(tickets)
+        line_item_mapping.mark_as_active!(external_payload: {})
+      end
+
+      def sync_guests!(guests, tickets, integration)
+        guests.each_with_index do |guest, index|
+          ticket = tickets[index]
+          next if ticket.blank?
+
+          guest_mapping = guest.integration_mappings.find_or_initialize_by(
+            external_id: ticket._id,
+            integration: integration
+          )
+
+          guest_mapping.external_qr_data = ticket._id
+          guest_mapping.mark_as_active!(external_payload: ticket.to_h)
+        end
+      end
+
+      def group_ticket_qr_data(tickets)
+        {
+          match_id: tickets.first.match_id,
+          ticket_ids: tickets.map(&:_id).sort,
+          is_online: true
+        }.to_json
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module Polling
+    class SyncMatches
+      def initialize(client:, integration:, sync_result: nil)
+        @client = client
+        @integration = integration
+        @sync_result = sync_result || SpreeCmCommissioner::Integrations::Base::SyncResult.new
+      end
+
+      def call
+        synced_match_mappings = sync_matches!
+        cleanup_stale_mappings!(synced_match_mappings)
+      end
+
+      # Sync all available matches from the API and create them as events
+      def sync_matches!
+        external_matches = begin
+          @sync_result.track_api_call('get_matches') { @client.get_matches! }
+        rescue SpreeCmCommissioner::Integrations::ExternalClientError => e
+          raise SpreeCmCommissioner::Integrations::SyncError, "Failed to sync matches: #{e.message}"
+        end
+
+        external_matches.map do |external_match|
+          sync_match!(external_match)
+        end
+      end
+
+      # Sync a single match and create it as an event taxon under events/
+      # Match data might be incomplete in the matches list, so we fetch full details
+      def sync_match!(external_match)
+        external_match = begin
+          @sync_result.track_api_call('get_match_details') { @client.get_match!(id: external_match._id) }
+        rescue SpreeCmCommissioner::Integrations::ExternalClientError => e
+          raise SpreeCmCommissioner::Integrations::SyncError, "Failed to sync matches: #{e.message}"
+        end
+
+        match_mapping = Spree::Taxon.find_or_initialize_integration_mapping(integration_id: @integration.id, external_id: external_match._id)
+        match_taxon = match_mapping.internal
+
+        # Track match sync and create event taxon directly under events/
+        @sync_result.track(:match, match_taxon) do |tracker|
+          match_taxon.assign_attributes(
+            vendor: @integration.vendor,
+            parent: events_root_taxon,
+            taxonomy: events_taxonomy,
+            name: "#{external_match.home_name} vs #{external_match.away_name}",
+            kind: :event,
+            from_date: external_match.match_datetime,
+            to_date: external_match.match_datetime + 120.minutes,
+
+            # seo
+            meta_title: external_match.meta_title,
+            meta_description: external_match.meta_description,
+
+            # Sync common match fields for cross-integration compatibility
+            # Only include fields that other integrations typically provide to avoid data gaps.
+            public_metadata: {
+              home_name: external_match.home_name,
+              home_score: external_match.home_score,
+              home_logo_url: external_match.home_logo,
+              away_name: external_match.away_name,
+              away_score: external_match.away_score,
+              away_logo_url: external_match.away_logo,
+              stadium: external_match.stadium,
+              league_name: external_match.league&.name,
+              league_logo_url: external_match.league&.logo
+            }
+          )
+          tracker.save_if_changed!(match_taxon)
+        end
+
+        match_mapping.mark_as_active!(external_payload: external_match.to_h)
+        match_mapping
+      end
+
+      # Archive stale match mappings that are no longer in the external API
+      # Finds all active event taxon mappings for this integration and archives any
+      # that weren't included in the latest API response
+      def cleanup_stale_mappings!(synced_match_mappings)
+        synced_external_match_ids = synced_match_mappings.map(&:external_id)
+
+        # Find all active match mappings (event taxons) for this integration
+        active_match_mappings = SpreeCmCommissioner::IntegrationMapping.where(
+          integration_id: @integration.id,
+          internal_type: 'Spree::Taxon',
+          status: :active
+        ).where(internal_id: Spree::Taxon.where(kind: :event).select(:id))
+
+        # Archive matches that are no longer in the API response
+        active_match_mappings.find_each do |mapping|
+          next if synced_external_match_ids.include?(mapping.external_id)
+
+          # Discontinue all products associated with this match
+          mapping.internal.event_products.find_each do |product|
+            product.discontinue!
+            @sync_result.increment_metric(:zone, :discontinued)
+          end
+
+          mapping.mark_as_archived!
+          @sync_result.increment_metric(:match, :archived)
+        end
+      end
+
+      def events_root_taxon
+        events_taxonomy.root
+      end
+
+      def events_taxonomy
+        @events_taxonomy ||= Spree::Taxonomy.events
+      end
+    end
+  end
+end

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