spree_cm_commissioner 2.5.0.pre.pre1 → 2.5.0.pre.pre2

data/app/controllers/spree/api/v2/storefront/event_matches_controller.rb

@@ -1,15 +0,0 @@
-module Spree
-  module Api
-    module V2
-      module Storefront
-        class EventMatchesController < TaxonsController
-          private
-
-          def collection_finder
-            SpreeCmCommissioner::Events::FindMatches
-          end
-        end
-      end
-    end
-  end
-end

data/app/errors/spree_cm_commissioner/integrations/external_client_error.rb

@@ -1,10 +0,0 @@
-module SpreeCmCommissioner::Integrations
-  class ExternalClientError < StandardError
-    attr_reader :status_code
-
-    def initialize(message, status_code = nil)
-      super(message)
-      @status_code = status_code
-    end
-  end
-end

data/app/errors/spree_cm_commissioner/integrations/sync_error.rb

@@ -1,4 +0,0 @@
-module SpreeCmCommissioner::Integrations
-  class SyncError < StandardError
-  end
-end

data/app/finders/spree_cm_commissioner/events/find_matches.rb

@@ -1,15 +0,0 @@
-module SpreeCmCommissioner
-  module Events
-    class FindMatches < ::Spree::BaseFinder
-      # currently, there is no way to determine if an event is a match yet.
-      # this finder returns all events that have active integration mappings (synced from external systems like StadiumX)
-      # as a temporary workaround to filter out non-match events.
-      def execute
-        scope.joins(:integration_mappings).where(
-          kind: :event,
-          integration_mappings: { status: :active }
-        ).distinct
-      end
-    end
-  end
-end

data/app/helpers/spree_cm_commissioner/external_integrations_helper.rb

@@ -1,58 +0,0 @@
-module SpreeCmCommissioner
-  module ExternalIntegrationsHelper
-    def integration_status_badge(status)
-      badge_class = case status.to_s
-                    when 'active' then 'badge-success'
-                    when 'paused' then 'badge-warning'
-                    else 'badge-secondary'
-                    end
-
-      content_tag(:span, status.to_s.humanize, class: "badge badge-pill #{badge_class}")
-    end
-
-    def integration_conflict_strategy_badge(strategy)
-      content_tag(:span, strategy.to_s.humanize, class: 'badge badge-pill badge-secondary')
-    end
-
-    def integration_interval_badge(value, unit)
-      content_tag(:span, "#{value}#{unit}", class: 'badge badge-pill badge-info')
-    end
-
-    def integration_base_url_link(url)
-      if url.present?
-        link_to url, url, target: '_blank', rel: 'noopener', class: 'text-decoration-underline'
-      else
-        content_tag(:span, '—', class: 'text-muted')
-      end
-    end
-
-    def integration_mapping_internal_link(mapping)
-      return mapping.internal_id if mapping.internal.blank?
-
-      begin
-        case mapping.internal_type
-        when 'Spree::Taxon'
-          taxon = mapping.internal
-          taxonomy_id = taxon.taxonomy_id || taxon.taxonomy&.id
-          if taxonomy_id
-            link_to mapping.internal_id,
-                    edit_admin_taxonomy_taxon_path(taxonomy_id, taxon.id),
-                    class: 'text-primary'
-          end
-        when 'Spree::Product'
-          link_to mapping.internal_id, edit_admin_product_path(mapping.internal), class: 'text-primary'
-        when 'Spree::Variant'
-          link_to mapping.internal_id, edit_admin_product_variant_path(mapping.internal.product_id, mapping.internal), class: 'text-primary'
-        when 'Spree::Vendor'
-          link_to mapping.internal_id, edit_admin_vendor_path(mapping.internal), class: 'text-primary'
-        else
-          # Try polymorphic route as fallback
-          link_to mapping.internal_id, [:edit, :admin, mapping.internal], class: 'text-primary'
-        end
-      rescue StandardError => e
-        Rails.logger.warn("Failed to generate link for mapping #{mapping.id}: #{e.message}")
-        mapping.internal_id
-      end
-    end
-  end
-end

data/app/jobs/spree_cm_commissioner/integrations/base_job.rb

@@ -1,39 +0,0 @@
-module SpreeCmCommissioner
-  module Integrations
-    # Base class for integration jobs
-    #
-    # Provides common error handling and alerting functionality for all integration jobs.
-    # Subclasses should implement their own perform logic and call the appropriate
-    # error handler methods.
-    class BaseJob < ApplicationJob
-      queue_as :integration
-
-      protected
-
-      # Handle error by logging and sending alert
-      # @param label [String] The error label for logging
-      # @param error [StandardError] The error that occurred
-      # @param data [Hash] Additional context data (e.g., sync_type, match_id, event_type)
-      def handle_error(label:, error:, data: {})
-        error_message = "#{error.class.name}: #{error.message}"
-
-        # Log the error with structured data
-        CmAppLogger.error(
-          label: label,
-          data: data.merge(
-            message: error_message,
-            backtrace: error.backtrace
-          )
-        )
-
-        # Send alert via Telegram
-        TelegramAlerts::IntegrationSyncFailureJob.perform_later(
-          error_message: error_message,
-          data: data
-        )
-
-        error_message
-      end
-    end
-  end
-end

data/app/jobs/spree_cm_commissioner/integrations/polling_job.rb

@@ -1,53 +0,0 @@
-module SpreeCmCommissioner
-  module Integrations
-    # Job that performs the actual polling (syncing) for a specific integration
-    #
-    # This job is enqueued by PollingSchedulerJob and handles:
-    # - Full syncs: Complete refresh of all data
-    # - Incremental syncs: Fetch only recent changes
-    # - Webhook syncs: Real-time event processing (triggered externally)
-    #
-    # Each integration type (StadiumXV1, LarrytaV1, etc.) must implement
-    # a sync_manager that responds to sync_full!, sync_incremental!, and sync_webhook!
-    class PollingJob < BaseJob
-      # Perform the integration pull
-      # @param integration_id [Integer] The integration ID
-      # @param sync_type [String] The sync type: 'full', 'incremental', or 'webhook_triggered'
-      # @param event_type [String] Optional event type for webhook syncs
-      # @param event_data [Hash] Optional event data for webhook syncs
-      def perform(options)
-        integration_id = options[:integration_id]
-        sync_type = options[:sync_type]
-        event_type = options[:event_type]
-        event_data = options[:event_data]
-        integration = SpreeCmCommissioner::Integration.find(integration_id)
-
-        # integration is no longer active, skip processing.
-        return unless integration.active?
-
-        SpreeCmCommissioner::Integrations::Polling.new.call(
-          integration: integration,
-          sync_type: sync_type,
-          event_type: event_type,
-          event_data: event_data
-        )
-      rescue StandardError => e
-        handle_sync_error(e, options)
-        raise
-      end
-
-      private
-
-      # Handle sync errors and alert
-      # @param error [StandardError] The error that occurred
-      # @param options [Hash] The options passed to perform
-      def handle_sync_error(error, options)
-        handle_error(
-          label: 'Integrations::IntegrationPullJob#perform Sync failed',
-          error: error,
-          data: options
-        )
-      end
-    end
-  end
-end

data/app/jobs/spree_cm_commissioner/integrations/polling_scheduler_job.rb

@@ -1,30 +0,0 @@
-module SpreeCmCommissioner
-  module Integrations
-    # Scheduler job that runs periodically to enqueue integration polling jobs
-    #
-    # This job is responsible for:
-    # - Running full syncs every 24 hours
-    # - Running incremental syncs every 10 seconds
-    # - Webhook syncs are triggered externally (not scheduled here)
-    #
-    # The job queries all active integrations and enqueues appropriate pull jobs
-    # based on their last sync time and sync type configuration.
-    class PollingSchedulerJob < BaseJob
-      def perform
-        SpreeCmCommissioner::Integrations::PollingScheduler.new.call
-      rescue StandardError => e
-        handle_scheduler_error(e)
-        raise
-      end
-
-      private
-
-      def handle_scheduler_error(error)
-        handle_error(
-          label: 'Integrations::PollingSchedulerJob#perform Error scheduling integration pulls',
-          error: error
-        )
-      end
-    end
-  end
-end

data/app/jobs/spree_cm_commissioner/telegram_alerts/integration_sync_failure_job.rb

@@ -1,17 +0,0 @@
-module SpreeCmCommissioner
-  module TelegramAlerts
-    class IntegrationSyncFailureJob < ApplicationJob
-      queue_as :telegram_bot
-
-      # Handle error by logging and sending alert
-      # @param error_message [String] The error message
-      # @param data [Hash] Additional context data (e.g., sync_type, match_id, event_type)
-      def perform(options)
-        SpreeCmCommissioner::TelegramAlerts::IntegrationSyncFailure.call(
-          error_message: options[:error_message],
-          data: options[:data] || {}
-        )
-      end
-    end
-  end
-end

data/app/models/concerns/spree_cm_commissioner/integrations/integration_mappable.rb

@@ -1,58 +0,0 @@
-module SpreeCmCommissioner
-  module Integrations
-    # IntegrationMappable provides a polymorphic mapping layer between internal records and external integration IDs.
-    #
-    # Design Rationale: Why use a separate mapping table instead of adding external_id columns directly?
-    #
-    # 1. **No Schema Changes Required**: Adding a new integration doesn't require migrations to add columns to every table.
-    #    The mapping table is reusable across all models that include this concern.
-    #
-    # 2. **Polymorphic Scalability**: A single mapping table handles multiple record types (Spree::Product, Spree::Taxon,
-    #    SeatLayout, etc.) without duplicating external_id columns across the schema.
-    #
-    # 3. **Multiple Source Support**: Records can have mappings to multiple integrations simultaneously. A single product
-    #    might be synced from StadiumXV1, LarrytaV1, and other sources. Direct columns would require one per integration.
-    #
-    # 4. **Acceptable Performance Trade-off**: While joins are slightly slower than direct column lookups, the performance
-    #    impact is negligible in practice because:
-    #    - Lookups occur primarily during background jobs (async, not blocking user requests)
-    #    - Integration sync operations (incremental, full, webhook)
-    #    - Occasional user-triggered operations (not on every page load)
-    #    The flexibility and maintainability gains far outweigh the minimal performance cost.
-    module IntegrationMappable
-      extend ActiveSupport::Concern
-
-      included do
-        has_many :integration_mappings, as: :internal, class_name: 'SpreeCmCommissioner::IntegrationMapping', dependent: :destroy
-      end
-
-      class_methods do
-        def find_or_initialize_integration_mapping(integration_id:, external_id:)
-          IntegrationMapping.includes(:internal).find_or_initialize_by(
-            integration_id: integration_id,
-            internal_type: name,
-            external_id: external_id
-          ) do |mapping|
-            mapping.internal = new
-            mapping.external_id = external_id
-          end
-        end
-
-        def find_integration_mapping(integration_id:, external_id:)
-          IntegrationMapping.includes(:internal).find_by(
-            integration_id: integration_id,
-            internal_type: name,
-            external_id: external_id
-          )
-        end
-
-        def find_oldest_active_mapping(integration_id:)
-          IntegrationMapping.where(
-            integration_id: integration_id,
-            internal_type: name
-          ).active.order(:last_synced_at).first
-        end
-      end
-    end
-  end
-end

data/app/models/spree_cm_commissioner/integration.rb

@@ -1,21 +0,0 @@
-module SpreeCmCommissioner
-  class Integration < Base
-    include StoreMetadata
-
-    enum status: { inactive: 0, active: 1, paused: 2 }
-    enum conflict_strategy: { newest_wins: 0, internal_wins: 1, external_wins: 2, manual_resolution: 3 }
-
-    belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant', optional: true
-    belongs_to :vendor, class_name: 'Spree::Vendor', optional: false
-
-    has_many :integration_mappings, class_name: 'SpreeCmCommissioner::IntegrationMapping', dependent: :destroy, inverse_of: :integration
-    has_many :integration_sync_sessions, class_name: 'SpreeCmCommissioner::IntegrationSyncSession', dependent: :destroy, inverse_of: :integration
-
-    validates :incremental_sync_interval_seconds, presence: true, numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 3600 }
-    validates :full_sync_interval_hours, presence: true, numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 168 }
-
-    def sync_manager
-      raise NotImplementedError, 'Subclasses must implement the sync_manager method'
-    end
-  end
-end

data/app/models/spree_cm_commissioner/integration_mapping.rb

@@ -1,37 +0,0 @@
-module SpreeCmCommissioner
-  class IntegrationMapping < Base
-    include StoreMetadata
-
-    enum status: { active: 0, archived: 1 }
-
-    # polymorphic (Spree::Taxon, Spree::Product, Spree::Variant, Spree::Vendor)
-    belongs_to :internal, polymorphic: true, optional: false
-    belongs_to :integration, class_name: 'SpreeCmCommissioner::Integration', inverse_of: :integration_mappings, optional: false
-
-    validates :external_id, presence: true, uniqueness: { scope: %i[integration_id internal_type internal_id date] }
-    validate :validate_internal_exists, if: -> { internal_type.present? && internal_id.present? }
-
-    def mark_as_archived!
-      self.status = :archived
-      self.last_synced_at = Time.zone.now
-
-      save!
-    end
-
-    def mark_as_active!(external_payload:)
-      self.external_payload = external_payload
-      self.last_synced_at = Time.zone.now
-      self.status = :active
-
-      save!
-    end
-
-    private
-
-    def validate_internal_exists
-      return if internal_type.safe_constantize&.exists?(id: internal_id)
-
-      errors.add(:internal, "record (#{internal_type}##{internal_id}) does not exist")
-    end
-  end
-end

data/app/models/spree_cm_commissioner/integration_sync_session.rb

@@ -1,15 +0,0 @@
-module SpreeCmCommissioner
-  class IntegrationSyncSession < Base
-    include StoreMetadata
-
-    enum status: { pending: 0, in_progress: 1, completed: 2, failed: 3, canceled: 4 }
-    enum :sync_type, {
-      full: 0, # on initial setup or periodic complete refresh
-      incremental: 1, # on scheduled intervals to fetch recent changes
-      webhook_triggered: 2 # immediately when an external webhook event is received
-    }, prefix: true
-
-    belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant', optional: true
-    belongs_to :integration, class_name: 'SpreeCmCommissioner::Integration', inverse_of: :integration_sync_sessions, optional: false
-  end
-end

data/app/models/spree_cm_commissioner/integrations/stadium_x_v1.rb

@@ -1,21 +0,0 @@
-class SpreeCmCommissioner::Integrations::StadiumXV1 < SpreeCmCommissioner::Integration
-  store_private_metadata :public_key, :string
-  store_private_metadata :private_key, :string
-  store_private_metadata :base_url, :string # e.g. 'https://api.stadiumx.com'
-
-  # override
-  def sync_manager
-    SpreeCmCommissioner::Integrations::StadiumXV1::SyncManager.new(
-      integration: self,
-      client: client
-    )
-  end
-
-  def client
-    SpreeCmCommissioner::Integrations::StadiumXV1::ExternalClient::Client.new(
-      public_key: public_key,
-      private_key: private_key,
-      base_url: base_url
-    )
-  end
-end

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

@@ -1,6 +0,0 @@
-<!-- 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/services/spree_cm_commissioner/integrations/base/sync_manager.rb

@@ -1,69 +0,0 @@
-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

@@ -1,183 +0,0 @@
-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