spree_cm_commissioner 2.4.2 → 2.5.0.pre.pre1

data/app/services/spree_cm_commissioner/integrations/base/sync_result.rb

@@ -0,0 +1,183 @@
+module SpreeCmCommissioner::Integrations::Base
+  # Base class for sync results
+  # Provides standardized tracking methods for API calls and record changes
+  #
+  # Persists to database as JSONB in CmIntegrationSyncSession#sync_result column
+  # Enables comprehensive sync monitoring and debugging:
+  #   - Track success/failure status
+  #   - Monitor API call counts and patterns
+  #   - Audit record creation/update counts
+  #   - Capture error details with automatic error codes
+  #   - Generate sync performance reports
+  #   - Identify patterns in failed syncs
+  #
+  # Example persisted results:
+  #
+  # Success:
+  #   {
+  #     "metrics": { "match": { "created": 2, "updated": 1, "total": 3 } },
+  #     "api_calls": { "get_matches": 1, "get_match_details": 3 }
+  #   }
+  #
+  # Failure:
+  #   {
+  #     "metrics": { "match": { "created": 1, "total": 1 } },
+  #     "api_calls": { "get_matches": 1 },
+  #     "error": { "message": "Failed to sync matches: Connection timeout", "code": "ExternalClientError" }
+  #   }
+  class SyncResult
+    def initialize
+      @metrics = {}
+      @api_calls = {}
+      @error = nil
+    end
+
+    # Track API call with block
+    # Automatically increments the call count and executes the block
+    # Failed calls (exceptions) are not counted
+    #
+    # @param call_name [String] Name of the API call (e.g., 'get_matches', 'get_zones')
+    # @yield Block containing the API call
+    # @return Result of the block
+    #
+    # Example:
+    #   external_matches = track_api_call('get_matches') { @client.get_matches! }
+    def track_api_call(call_name)
+      @api_calls[call_name] = (@api_calls[call_name] || 0) + 1
+      yield
+    end
+
+    # Track synced record with block
+    # Automatically detects if record was created or updated based on new_record? and saved_changes
+    #
+    # @param type [Symbol, String] Type of record (e.g., :match, :zone)
+    # @param record [Object] The record being synced (must respond to new_record? and saved_changes)
+    # @yield Block containing the save/update logic
+    # @return Result of the block
+    #
+    # Example:
+    #   track_synced_record(:match, match_taxon) do
+    #     match_taxon.assign_attributes(name: 'ISI Dangkorsenchey FC vs ANGKOR TIGER FC')
+    #     match_taxon.save!
+    #   end
+    def track_synced_record(type, record)
+      was_new = record.new_record?
+      result = yield
+
+      if was_new
+        increment_metric(type, :created)
+      elsif record.saved_changes.any?
+        increment_metric(type, :updated)
+      end
+
+      result
+    end
+
+    # Track and sync record with explicit tracker object
+    # Provides a tracker object with helper methods for explicit save/tracking operations
+    #
+    # @param type [Symbol, String] Type of record (e.g., :league, :match, :zone, :variant)
+    # @param record [Object] The record being synced (must respond to new_record? and saved_changes)
+    # @yield Block receiving tracker object for explicit operations
+    # @return Result of the block
+    #
+    # Example:
+    #   track(:zone, product) do |tracker|
+    #     product.assign_attributes(name: 'Zone A', price: 100)
+    #     tracker.save_if_changed!(product)
+    #   end
+    def track(type, record)
+      tracker = RecordTracker.new(self, type, record)
+      yield tracker
+      tracker
+    end
+
+    # Helper class for explicit record tracking and saving
+    class RecordTracker
+      def initialize(sync_result, type, record)
+        @sync_result = sync_result
+        @type = type
+        @record = record
+        @was_new = record.new_record?
+      end
+
+      # Save record if it's new or has changes, and track the operation
+      # Automatically detects create vs update based on initial state
+      #
+      # @param record [Object] The record to save (defaults to the tracked record)
+      def save_if_changed!(record = @record)
+        return unless record.new_record? || record.changed?
+
+        record.save!
+
+        # Track based on initial state
+        if @was_new
+          @sync_result.increment_metric(@type, :created)
+        else
+          @sync_result.increment_metric(@type, :updated)
+        end
+      end
+    end
+
+    # Increment a metric counter
+    # Useful for tracking actions that don't fit the created/updated pattern
+    #
+    # @param type [Symbol, String] Type of metric (e.g., :match, :inventory)
+    # @param action [Symbol, String] Action performed (e.g., :archived, :adjustments)
+    # @param amount [Integer] Amount to increment by (default: 1)
+    #
+    # Example:
+    #   increment_metric(:match, :archived)                              # increment by 1
+    #   increment_metric(:inventory, :total_quantity_adjusted, 50)       # increment by 50
+    def increment_metric(type, action, amount = 1)
+      @metrics[type.to_sym] ||= {}
+      @metrics[type.to_sym][action.to_sym] ||= 0
+      @metrics[type.to_sym][action.to_sym] += amount
+
+      update_metric_total(type)
+    end
+
+    # Record error
+    # @param error [StandardError] The error that occurred
+    def record_error(error)
+      @error = {
+        message: error.message,
+        code: error.class.name.split('::').last
+      }
+    end
+
+    # Check if sync was successful
+    # @return [Boolean] True if no error, false otherwise
+    def success?
+      @error.nil?
+    end
+
+    # Serialize to hash for JSONB persistence
+    # @return [Hash] Serialized representation
+    def to_h
+      {
+        metrics: @metrics,
+        api_calls: @api_calls,
+        error: @error
+      }.tap do |hash|
+        hash.delete(:error) if @error.nil?
+        hash.delete(:metrics) if @metrics.empty?
+        hash.delete(:api_calls) if @api_calls.empty?
+      end
+    end
+
+    private
+
+    # Update total for a metric type
+    # Sums all numeric values in the metric hash
+    def update_metric_total(type)
+      metric = @metrics[type.to_sym]
+      return unless metric.is_a?(Hash)
+
+      # Calculate total from numeric values only
+      numeric_values = metric.select { |k, v| v.is_a?(Integer) && k != :total }
+      total = numeric_values.values.sum
+      metric[:total] = total if total.positive?
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module SpreeCmCommissioner
+  module Integrations
+    class Polling
+      def call(integration:, sync_type:, event_type: nil, event_data: nil)
+        sync_manager = integration.sync_manager
+
+        case sync_type.to_sym
+        when :full
+          perform_full_sync!(sync_manager, integration)
+        when :incremental
+          perform_incremental_sync!(sync_manager, integration)
+        when :webhook_triggered
+          perform_webhook_sync!(sync_manager, integration, event_type, event_data)
+        else
+          raise ArgumentError, "Unknown sync type: #{sync_type}"
+        end
+      end
+
+      private
+
+      # Perform a full sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      def perform_full_sync!(sync_manager, integration)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_full_sync! Starting full sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name
+          }
+        ) do
+          sync_manager.sync_full!
+        end
+      end
+
+      # Perform an incremental sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      def perform_incremental_sync!(sync_manager, integration)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_incremental_sync! Starting incremental sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name
+          }
+        ) do
+          sync_manager.sync_incremental!
+        end
+      end
+
+      # Perform a webhook-triggered sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      # @param event_type [String] The event type
+      # @param event_data [Hash] The event data
+      def perform_webhook_sync!(sync_manager, integration, event_type, event_data)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_webhook_sync! Starting webhook sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name,
+            event_type: event_type
+          }
+        ) do
+          sync_manager.sync_webhook!(event_type: event_type, event_data: event_data)
+        end
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/polling_scheduler.rb

@@ -0,0 +1,79 @@
+module SpreeCmCommissioner
+  module Integrations
+    class PollingScheduler
+      BATCH_SIZE = 10 # Process integrations in batches to avoid overwhelming the server
+
+      def call
+        SpreeCmCommissioner::Integration.active.find_each(batch_size: BATCH_SIZE) do |integration|
+          if should_run_full_sync?(integration)
+            schedule_full_sync(integration)
+          elsif should_run_incremental_sync?(integration)
+            schedule_incremental_sync(integration)
+          end
+        end
+      end
+
+      private
+
+      # Check if full sync should run
+      # Run full sync if:
+      # 1. No full sync is running or pending (excluding sessions older than 1 hour)
+      # 2. No previous full sync exists, OR
+      # 3. Last full sync was more than the configured interval ago (eg. 24 hours ago)
+      def should_run_full_sync?(integration)
+        return false if integration.integration_sync_sessions
+                                   .where(sync_type: %i[full], status: %i[in_progress pending])
+                                   .exists?(['created_at > ?', 1.hour.ago])
+
+        last_full_sync = integration.integration_sync_sessions
+                                    .where(sync_type: :full, status: :completed)
+                                    .order(created_at: :desc)
+                                    .first
+
+        return true if last_full_sync.blank?
+
+        full_sync_interval = integration.full_sync_interval_hours.hours
+        (Time.current - last_full_sync.created_at) > full_sync_interval
+      end
+
+      # Check if incremental sync should run
+      # Ignore sessions older than 1 hour to allow retry of stalled syncs
+      def should_run_incremental_sync?(integration)
+        return false if integration.integration_sync_sessions
+                                   .where(sync_type: %i[full incremental], status: %i[in_progress pending])
+                                   .exists?(['created_at > ?', 1.hour.ago])
+
+        last_incremental_sync = integration.integration_sync_sessions
+                                           .where(sync_type: :incremental, status: :completed)
+                                           .order(created_at: :desc)
+                                           .first
+
+        # Run incremental sync if:
+        # 1. No previous incremental sync exists, OR
+        # 2. Last incremental sync was more than the configured interval ago (eg. 10 seconds ago)
+        return true if last_incremental_sync.blank?
+
+        incremental_sync_interval = integration.incremental_sync_interval_seconds.seconds
+        (Time.current - last_incremental_sync.created_at) > incremental_sync_interval
+      end
+
+      def schedule_full_sync(integration)
+        CmAppLogger.log(
+          label: 'Integrations::PollingSchedulerJob#schedule_full_sync Enqueued full sync',
+          data: { integration_id: integration.id, integration_type: integration.class.name }
+        ) do
+          PollingJob.perform_later(integration_id: integration.id, sync_type: :full)
+        end
+      end
+
+      def schedule_incremental_sync(integration)
+        CmAppLogger.log(
+          label: 'Integrations::PollingSchedulerJob#schedule_incremental_sync Enqueued incremental sync',
+          data: { integration_id: integration.id, integration_type: integration.class.name }
+        ) do
+          PollingJob.perform_later(integration_id: integration.id, sync_type: :incremental)
+        end
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/stadium_x_v1/external_client/client.rb

@@ -0,0 +1,152 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1
+  module ExternalClient
+    class Client
+      BASE_PATH = '/api/v1'.freeze
+      RATE_LIMIT = 100
+
+      def initialize(public_key:, private_key:, base_url:)
+        @public_key = public_key
+        @private_key = private_key
+        @base_url = base_url
+        @connection = build_connection
+      end
+
+      # Ticket Operations
+
+      # Get a specific ticket by ID
+      # @param id [String] The ticket ID
+      # @return [Resources::Ticket] The ticket object
+      def get_ticket!(id:)
+        response = @connection.get("#{BASE_PATH}/tickets/#{id}") do |req|
+          req.body = auth_params.to_json
+        end
+
+        handle_response(response, Resources::Ticket)
+      end
+
+      # Get all tickets for a specific user
+      # @param user_id [String] The user ID
+      # @return [Array<Resources::Ticket>] Array of ticket objects
+      def get_tickets_by_user!(user_id:)
+        response = @connection.get("#{BASE_PATH}/tickets/user/#{user_id}") do |req|
+          req.body = auth_params.merge(user_id: user_id).to_json
+        end
+
+        handle_response(response, Resources::Ticket, collection: true)
+      end
+
+      # Create a new ticket
+      # @param match_id [String] The match ID
+      # @param user_id [String] The user ID
+      # @param club_id [String] The club ID
+      # @param zone_id [String] The zone ID
+      # @param quantity [Integer] The quantity of tickets to create
+      # @return [Array<Resources::Ticket>] Array of created ticket objects
+      def create_tickets!(match_id:, user_id:, club_id:, zone_id:, quantity:)
+        params = {
+          match_id: match_id,
+          user_id: user_id,
+          club_id: club_id,
+          zone_id: zone_id,
+          quantity: quantity
+        }
+
+        response = @connection.post("#{BASE_PATH}/tickets") do |req|
+          req.body = auth_params.merge(params).to_json
+          req.headers['Content-Type'] = 'application/json'
+        end
+
+        handle_response(response, Resources::Ticket, collection: true)
+      end
+
+      # Match Operations
+
+      # Get all available matches
+      # @return [Array<Resources::Match>] Array of match objects
+      def get_matches! # rubocop:disable Naming/AccessorMethodName
+        response = @connection.get("#{BASE_PATH}/matches") do |req|
+          req.params = auth_params
+        end
+
+        handle_response(response, Resources::Match, collection: true)
+      end
+
+      # Get a specific match by ID
+      # @param id [String] The match ID
+      # @return [Resources::Match] The match object
+      def get_match!(id:)
+        response = @connection.get("#{BASE_PATH}/matches/#{id}") do |req|
+          req.params = auth_params
+        end
+
+        handle_response(response, Resources::Match)
+      end
+
+      # Zone Operations
+
+      # Get available zones for a club and match
+      # @param club_id [String] The club ID
+      # @param match_id [String] The match ID
+      # @return [Array<Resources::Zone>] Array of zone objects
+      def get_zones!(club_id:, match_id:)
+        response = @connection.get("#{BASE_PATH}/zones/club") do |req|
+          req.params = auth_params.merge(
+            club_id: club_id,
+            match_id: match_id
+          )
+        end
+
+        handle_response(response, Resources::Zone, collection: true)
+      end
+
+      private
+
+      def build_connection
+        Faraday.new(url: @base_url) do |faraday|
+          faraday.request :json
+          faraday.response :json, content_type: /\bjson$/
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def auth_params
+        {
+          public_key: @public_key,
+          private_key: @private_key
+        }
+      end
+
+      def handle_response(response, model_class, collection: false)
+        if response.success?
+          data = response.body
+          unless data['success']
+            raise SpreeCmCommissioner::Integrations::ExternalClientError.new(
+              "API request failed: #{data['error']}",
+              response.status
+            )
+          end
+
+          collection ? model_class.from_collection(data) : model_class.new(data['data'])
+        else
+          handle_error_response(response)
+        end
+      end
+
+      def handle_error_response(response)
+        error_message = "API request failed with status #{response.status}"
+
+        # Response body is already parsed by Faraday's JSON middleware
+        error_body = response.body
+
+        if error_body.is_a?(Hash)
+          error = error_body['error'] || error_body['message'] || error_body
+          error_message = error.is_a?(Hash) ? error.to_json : error.to_s
+        else
+          error_message = error_body.to_s.presence || error_message
+        end
+
+        raise SpreeCmCommissioner::Integrations::ExternalClientError.new(error_message, response.status)
+      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