spree_cm_commissioner 2.5.0.pre.pre2 → 2.5.0.pre.pre3

data/app/models/spree_cm_commissioner/variant_decorator.rb

@@ -5,6 +5,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::ProductDelegation
       base.include SpreeCmCommissioner::VariantOptionsConcern
       base.include SpreeCmCommissioner::KycBitwise
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.after_commit :update_vendor_price
       base.validate     :validate_option_types
@@ -16,10 +17,6 @@ module SpreeCmCommissioner
       base.has_one :vehicle, class_name: 'SpreeCmCommissioner::Vehicle', through: :trip
 
       base.has_many :taxons, class_name: 'Spree::Taxon', through: :product
-      base.has_many :visible_option_values, lambda {
-                                              joins(:option_type).where(spree_option_types: { hidden: false })
-                                            }, through: :option_value_variants, source: :option_value
-
       base.has_many :video_on_demands, class_name: 'SpreeCmCommissioner::VideoOnDemand', dependent: :destroy
       base.has_many :complete_line_items, -> { complete }, class_name: 'Spree::LineItem'
 
@@ -42,6 +39,12 @@ module SpreeCmCommissioner
       base.before_validation -> { self.product_type = product.product_type }, if: -> { product_type.nil? }
     end
 
+    # Override variant.rb to return cached formatted options text, avoiding repeated database queries.
+    # Falls back to database queries & computing the format if preload data is unavailable.
+    def options_text
+      public_metadata[:preload_options_text].presence || Spree::Variants::VisibleOptionsPresenter.new(self).to_sentence
+    end
+
     def delivery_required?
       delivery_option == 'delivery'
     end

data/app/models/spree_cm_commissioner/vendor_decorator.rb

@@ -9,6 +9,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::VendorPreference
       base.include SpreeCmCommissioner::TenantUpdatable
       base.include SpreeCmCommissioner::StoreMetadata
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.attr_accessor :service_availabilities
 
@@ -39,6 +40,9 @@ module SpreeCmCommissioner
       base.has_many :vendor_kind_option_values,
                     through: :option_value_vendors, source: :option_value
 
+      # currently a vendor can have only one integration, but in future it can be many.
+      base.has_one :integration, class_name: 'SpreeCmCommissioner::Integration', dependent: :destroy, inverse_of: :vendor
+
       base.has_many :branches, -> { branch }, class_name: 'SpreeCmCommissioner::VendorPlace'
       base.has_many :stops, -> { stop }, class_name: 'SpreeCmCommissioner::VendorPlace'
       base.has_many :locations, -> { location }, class_name: 'SpreeCmCommissioner::VendorPlace'

data/app/overrides/spree/admin/shared/sub_menu/_integrations/external_integrations.html.erb.deface

@@ -0,0 +1,6 @@
+<!-- insert_bottom "[data-hook='admin_integrations']" -->
+
+<%= tab :integrations,
+        match_path: '/integrations',
+        label: Spree.t('admin.external_integrations_title'),
+        if: can?(:manage, SpreeCmCommissioner::Integration) %>

data/app/presenters/spree/variants/{visable_options_presenter.rb → visible_options_presenter.rb}

@@ -1,11 +1,9 @@
 module Spree
   module Variants
-    class VisableOptionsPresenter < OptionsPresenter
-      delegate :visible_option_values, to: :variant
-
+    class VisibleOptionsPresenter < OptionsPresenter
       # override
       def to_sentence
-        options = visible_option_values
+        options = variant.option_values.reject { |ov| ov.option_type.hidden? }
         options = sort_options(options)
         options = present_options(options)
 

data/app/request_schemas/spree_cm_commissioner/route_places_request_schema.rb

@@ -6,11 +6,6 @@ module SpreeCmCommissioner
       optional(:place_id).maybe(:integer)
       optional(:route_type).maybe(:string)
     end
-    route_types = SpreeCmCommissioner::RouteType::ROUTE_TYPES.map(&:to_s)
-
-    rule(:route_type) do
-      key.failure("Invalid route_type. Use #{route_types}") if value.present? && route_types.exclude?(value)
-    end
 
     rule(:place_type) do
       key.failure('Invalid place_type. Use origin or destination') unless %w[origin destination].include?(value)

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

@@ -0,0 +1,69 @@
+module SpreeCmCommissioner::Integrations::Base
+  class SyncManager
+    def initialize(integration:, client:)
+      @integration = integration
+      @client = client
+      @sync_session = nil
+    end
+
+    # Perform a full synchronization (initial setup or complete refresh)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails
+    def sync_full!
+      raise NotImplementedError, "#{self.class.name} must implement #sync_full!"
+    end
+
+    # Perform an incremental synchronization (delta updates)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails or not supported
+    def sync_incremental!
+      raise NotImplementedError, "#{self.class.name} must implement #sync_incremental!"
+    end
+
+    # Perform a webhook-triggered synchronization (real-time event)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @param event_type [String] The type of event (e.g., 'match.updated', 'ticket.created')
+    # @param event_data [Hash] The event payload
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails or not supported
+    def sync_webhook!(event_type:, event_data:)
+      raise NotImplementedError, "#{self.class.name} must implement #sync_webhook!"
+    end
+
+    protected
+
+    # Wrapper for sync execution that handles session creation and persistence
+    # Strategies handle errors internally and always return a SyncResult object
+    # This method never throws errors - it always returns a sync session
+    #
+    # @param sync_type [Symbol] The type of sync (:full, :incremental, :webhook_triggered)
+    # @yield Block containing the actual sync logic, must return a SyncResult object
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    def run_execution(sync_type)
+      @sync_session = create_sync_session(sync_type)
+      sync_result = yield
+
+      @sync_session.update!(
+        status: sync_result.success? ? :completed : :failed,
+        ended_at: Time.zone.now,
+        sync_result: sync_result.to_h
+      )
+
+      @sync_session
+    end
+
+    private
+
+    def create_sync_session(sync_type)
+      SpreeCmCommissioner::IntegrationSyncSession.create!(
+        integration: @integration,
+        tenant: @integration.tenant,
+        status: :in_progress,
+        started_at: Time.zone.now,
+        sync_type: sync_type
+      )
+    end
+  end
+end

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