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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f64a6d2661d4c1deb862d020b44eca3748d001e0376731881b47de3c1e4965c
-  data.tar.gz: 4a11c037dd432001d56d379c73e1cad574971f2a1cd8cc5ef3cbb1585b297c3b
+  metadata.gz: ba91dacd894816a0b4105c032a0550371aeab884b3f344ebe554758c3556a0a0
+  data.tar.gz: 077d13272adb0ced0f246dc9d48d5d3b9ae56a95beaa74a6d2cd6fc7f134f7e1
 SHA512:
-  metadata.gz: 1e3de7556ebafefc89a00bbf454f2cb70700ef9dc56b8131b103f9f26f7e3af8341fcf0bc4c0b757a372128fbf56d6ecf967682ba46f97f0b117f0b0319ee979
-  data.tar.gz: ea662f3962d01be3d39e11ba4d86611fcc3713c03061ab8e0131c2063acfdb70ade45b77f821a616ad3320637d2ba547389a91a5f14bbe05530d26ac40c692fd
+  metadata.gz: 8a990d42d6cf09c9304971a41efb74525761de29ee6cefe04e1a7b0dbe2831e9ad40f52f229ca463ee905ed1e039b1562daa2eace5307c4dd3eb6f725488e671
+  data.tar.gz: 309280aeb9987456b2788be11cdad59095da58b2b258e294477cfb5edb63323b4ee6d3fd8ae03f845fd79db0d0186ff54d64f6cb406567c2a284dc26454446f8

data/.github/workflows/test_and_build_gem.yml

@@ -10,7 +10,7 @@ on:
       - reopened
     branches:
       - develop
-      - milestone-77-scalable-design
+      - 3114-external-integration-milestone
   push:
     tags:
       - "*"

data/.tool-versions

@@ -1 +1 @@
-ruby 3.3.5
+ruby 3.2.0

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.5.0.pre.pre2)
+    spree_cm_commissioner (2.5.0.pre.pre4)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/controllers/spree/admin/integration_mappings_controller.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Admin
+    class IntegrationMappingsController < Spree::Admin::BaseController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_integration
+
+      def index
+        @mappings = @integration.integration_mappings
+                                .order(updated_at: :desc)
+                                .page(params[:page])
+                                .per(params[:per_page] || 25)
+      end
+
+      private
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:integration_id])
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/integration_sessions_controller.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Admin
+    class IntegrationSessionsController < Spree::Admin::BaseController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_integration
+
+      def index
+        @sync_sessions = @integration.integration_sync_sessions
+                                     .order(created_at: :desc)
+                                     .page(params[:page])
+                                     .per(params[:per_page] || 25)
+      end
+
+      private
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:integration_id])
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/integrations_controller.rb

@@ -0,0 +1,83 @@
+module Spree
+  module Admin
+    class IntegrationsController < Spree::Admin::ResourceController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_form_collections, only: %i[new create edit update]
+      before_action :load_integration, only: %i[enqueue_polling]
+
+      def index
+        @integrations = model_class.all
+      end
+
+      def enqueue_polling
+        sync_type = params[:sync_type].presence || :full
+
+        if @integration.active?
+          SpreeCmCommissioner::Integrations::PollingJob.perform_later(
+            integration_id: @integration.id,
+            sync_type: sync_type
+          )
+          flash[:success] = Spree.t('admin.integration_sync_enqueued')
+        else
+          flash[:error] = Spree.t('admin.integration_inactive')
+        end
+
+        redirect_to admin_integration_sessions_path(@integration)
+      end
+
+      # override
+      def model_class
+        SpreeCmCommissioner::Integration
+      end
+
+      # override
+      def collection_url(options = {})
+        admin_integrations_url(options)
+      end
+
+      private
+
+      def permitted_resource_params
+        params.require(:spree_cm_commissioner_integration).permit(
+          :name,
+          :type,
+          :status,
+          :conflict_strategy,
+          :incremental_sync_interval_seconds,
+          :full_sync_interval_hours,
+          :tenant_id,
+          :vendor_id,
+          public_metadata: {},
+          private_metadata: {}
+        )
+      end
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:id])
+      end
+
+      def load_form_collections
+        @integration_type_options ||= integration_type_options
+        @status_options ||= enum_to_options(SpreeCmCommissioner::Integration.statuses)
+        @conflict_strategy_options ||= enum_to_options(SpreeCmCommissioner::Integration.conflict_strategies)
+        @tenants ||= SpreeCmCommissioner::Tenant.select(:id, :name).order(:name)
+        @vendors ||= Spree::Vendor.select(:id, :name).order(:name)
+      end
+
+      def enum_to_options(enum_hash)
+        enum_hash.keys.map { |key| [key.humanize, key] }
+      end
+
+      def integration_type_options
+        files = Dir[SpreeCmCommissioner::Engine.root.join('app/models/spree_cm_commissioner/integrations/*.rb')]
+
+        return [[Spree.t(:type), 'SpreeCmCommissioner::Integration']] if files.blank?
+
+        files.map do |path|
+          class_name = "SpreeCmCommissioner::Integrations::#{File.basename(path, '.rb').camelize}"
+          [class_name, class_name]
+        end.sort_by(&:first)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+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/controllers/spree/api/v2/storefront/popular_route_places_controller.rb

@@ -19,8 +19,7 @@ module Spree
           # override
           def collection
             @collection ||= collection_finder.new.execute(
-              route_type: params[:route_type],
-              query: params[:query]
+              route_type: params[:route_type]
             )
           end
 
@@ -52,11 +51,6 @@ module Spree
             )
           end
 
-          # override
-          def required_schema
-            SpreeCmCommissioner::PopularRoutePlacesRequestSchema
-          end
-
           def include_vendors?
             resource_includes.include?(:vendors) || false
           end

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

@@ -3,22 +3,22 @@
 # GET /api/v2/storefront/route_places
 #
 # Finds places (origins or destinations) that are connected to a given place through existing routes.
-# Optionally filters results by query or route_type. Supports two modes:
+# Optionally filters results by keyword or route_type. Supports two modes:
 #
 # Usage 1: Connected places (requires place_id)
 #   - Finds places connected to a specific place via routes
 #   - Returns origins/destinations that have routes with the specified place
 #
-# Usage 2: query search (requires query, place_id optional)
-#   - Searches all route places by query
-#   - Returns all origins/destinations matching the query
+# Usage 2: Keyword search (requires query, place_id optional)
+#   - Searches all route places by keyword
+#   - Returns all origins/destinations matching the keyword
 #
 # Query Parameters:
 #   - place_type: [String] Required. Type of route place: 'origin' or 'destination'
 #     * 'origin': returns origins that have routes TO the specified place (if place_id provided)
 #     * 'destination': returns destinations that have routes FROM the specified place (if place_id provided)
 #   - place_id: [Integer] Optional. The place ID to find connected places for
-#   - query: [String] Optional. query to filter place names (case-insensitive)
+#   - query: [String] Optional. Keyword to filter place names (case-insensitive)
 #   - include: Optional comma-separated list (e.g., 'vendors,nearby_places')
 #
 # Response: Collection of places serialized with PlaceSerializer
@@ -27,15 +27,15 @@
 #   - Returns empty collection if place_type is invalid
 #   - If place_id provided: returns places connected to that place
 #   - If place_id blank: returns all origins/destinations
-#   - Filters results by query or route_type if provided
+#   - Filters results by keyword or route_type if provided
 #
 # @example Mode 1: Find destinations connected to origin place ID 123
 #   GET /api/v2/storefront/route_places?place_id=123&place_type=destination
 #
-# @example Mode 2: Search all destination places by query
+# @example Mode 2: Search all destination places by keyword
 #   GET /api/v2/storefront/route_places?place_type=destination&query=Phnom
 #
-# @example Combined: Find origins connected to place 456, filtered by query
+# @example Combined: Find origins connected to place 456, filtered by keyword
 #   GET /api/v2/storefront/route_places?place_id=456&place_type=origin&query=Siem
 module Spree
   module Api
@@ -49,7 +49,7 @@ module Spree
             @collection ||= collection_finder.new(
               place_type: params[:place_type],
               place_id: params[:place_id],
-              query: params[:query],
+              keyword: params[:query],
               route_type: params[:route_type]
             ).execute
           end

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

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

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

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

@@ -0,0 +1,15 @@
+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/finders/spree_cm_commissioner/places/find_with_route.rb

@@ -2,14 +2,14 @@
 #
 # @param place_type [String] Required. 'origin' or 'destination'
 # @param place_id [Integer] Optional. Filter by connected place ID
-# @param query [String] Optional. Filter by place name (case-insensitive)
+# @param keyword [String] Optional. Filter by place name (case-insensitive)
 # @param route_type [Symbol, String] Optional. Filter by route type from associated trips (e.g., :ferry, :bus)
 #
 # @return [ActiveRecord::Relation<SpreeCmCommissioner::Place>]
 #
 # Modes:
 #   - place_id only: returns connected places (origins TO or destinations FROM given place)
-#   - query only: filters by name
+#   - keyword only: filters by name
 #   - route_type only: filters by trip route types on those routes
 #   - combinations: connected places filtered by name and/or route type
 #   - neither: all origins/destinations in routes
@@ -17,17 +17,17 @@
 # @example Origins with ferry trips to place 123
 #   FindWithRoute.new(place_type: 'origin', place_id: 123, route_type: :ferry).execute
 #
-# @example Destinations filtered by query and route type
-#   FindWithRoute.new(place_type: 'destination', query: 'Phnom', route_type: :bus).execute
+# @example Destinations filtered by keyword and route type
+#   FindWithRoute.new(place_type: 'destination', keyword: 'Phnom', route_type: :bus).execute
 module SpreeCmCommissioner
   module Places
     class FindWithRoute
-      attr_reader :place_type, :place_id, :query, :route_type
+      attr_reader :place_type, :place_id, :keyword, :route_type
 
-      def initialize(place_type:, place_id: nil, query: nil, route_type: nil)
+      def initialize(place_type:, place_id: nil, keyword: nil, route_type: nil)
         @place_type = place_type
         @place_id = place_id
-        @query = query
+        @keyword = keyword
         @route_type = route_type
       end
 
@@ -36,7 +36,7 @@ module SpreeCmCommissioner
         return SpreeCmCommissioner::Place.none if place_id.present? && !SpreeCmCommissioner::Place.exists?(place_id)
 
         result = scope
-        result = apply_query_filter(result) if query.present?
+        result = apply_keyword_filter(result) if keyword.present?
         result = apply_route_type_filter(result) if route_type.present?
         result
       end
@@ -57,8 +57,8 @@ module SpreeCmCommissioner
         end
       end
 
-      def apply_query_filter(result)
-        result.where('cm_places.name ILIKE ?', "%#{query}%")
+      def apply_keyword_filter(result)
+        result.where('cm_places.name ILIKE ?', "%#{keyword}%")
       end
 
       def apply_route_type_filter(result)

data/app/finders/spree_cm_commissioner/routes/find_popular.rb

@@ -24,22 +24,26 @@
 module SpreeCmCommissioner
   module Routes
     class FindPopular
-      def execute(route_type: nil, query: nil)
-        scope(route_type: route_type, query: query)
+      def execute(route_type: nil)
+        scope(route_type: route_type)
       end
 
       private
 
-      def scope(route_type:, query:)
-        includes_associations = %i[origin_place destination_place]
-        includes_associations << :trips if route_type.present?
-        result = SpreeCmCommissioner::Route.includes(*includes_associations)
+      def scope(route_type: nil)
+        result = SpreeCmCommissioner::Route
+                 .includes(:origin_place, :destination_place)
 
-        result = result.joins(:trips).where(cm_trips: { route_type: route_type.to_sym }) if route_type.present?
+        if route_type.present?
+          # Filter routes that have trips with the specified route_type
+          route_scope = SpreeCmCommissioner::Route
+                        .joins(:trips)
+                        .where(cm_trips: { route_type: route_type.to_sym })
+          result = result.where(id: route_scope.select(:id))
+        end
 
-        result = result.where('cm_routes.route_name ILIKE ?', "%#{query}%") if query.present?
-
-        result.distinct.order(fulfilled_order_count: :desc, order_count: :desc)
+        result.order(Arel.sql('COALESCE(fulfilled_order_count, 0) DESC'))
+              .order(Arel.sql('COALESCE(order_count, 0) DESC'))
       end
     end
   end

data/app/helpers/spree_cm_commissioner/external_integrations_helper.rb

@@ -0,0 +1,58 @@
+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/interactors/spree_cm_commissioner/stock/inventory_item_resetter.rb

@@ -35,7 +35,7 @@ module SpreeCmCommissioner
       end
 
       def clear_inventory_cache
-        SpreeCmCommissioner.redis_pool.with do |redis|
+        SpreeCmCommissioner.inventory_redis_pool.with do |redis|
           redis.del(inventory_item.redis_key)
         end
       end

data/app/interactors/spree_cm_commissioner/stock/stock_movement_creator.rb

@@ -23,8 +23,9 @@ module SpreeCmCommissioner
       private
 
       def adjust_inventory_items_async(variant_id, quantity)
-        CmAppLogger.log(label: "#{self.class.name}#adjust_inventory_items_async", data: { variant_id: variant_id, quantity: quantity }) do
-          SpreeCmCommissioner::Stock::InventoryItemsAdjusterJob.perform_later(variant_id: variant_id, quantity: quantity)
+        args = { variant_id: variant_id, quantity: quantity }
+        CmAppLogger.log(label: "#{self.class.name}#adjust_inventory_items_async", data: args) do
+          SpreeCmCommissioner::Stock::InventoryItemsAdjusterJob.perform_later(**args)
         end
       end
     end

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

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

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

@@ -0,0 +1,30 @@
+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/stock/inventory_items_adjuster_job.rb

@@ -1,10 +1,13 @@
 module SpreeCmCommissioner
   module Stock
     class InventoryItemsAdjusterJob < ApplicationUniqueJob
-      def perform(variant_id:, quantity:)
-        variant = Spree::Variant.find(variant_id)
+      def perform(options = {})
+        variant = Spree::Variant.find_by(id: options[:variant_id])
 
-        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: quantity)
+        # potentially the variant was deleted during the job wait time, we just skip in that case.
+        return if variant.blank?
+
+        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: options[:quantity])
       end
     end
   end

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

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