spree_cm_commissioner 2.15.2 → 2.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5538af5130244a626ceca3f818410469c93ea7975f5cbc51b212b7536361b8e
-  data.tar.gz: 4e272e66836c76b1296aad6a65488cd17e3ef9517a4a8112594047875de4a185
+  metadata.gz: 32502c54cc175c2fc2c4d6c86d97385fe1c02192ddfa240e6ac28b043fc923c3
+  data.tar.gz: be2a8f37d0f078acd74e6e16155928065a2915b868525c01ae01232dcc8d9e39
 SHA512:
-  metadata.gz: 80bc600859e7bdf199590d0a5e7982b9b03bbef4ddc9b19e03fbbbe6be76ceca11817687b1d358db20be3b9b7665154d9a05db59412e690448982cf70f543e4d
-  data.tar.gz: 646dea4a475811f6452137087b603d3bb36b6832bd6550339713b84a82f7ee0c71054b81632aebd4ddd041eef14ceca479402e679b0ab49fbf40d87f0e69ec15
+  metadata.gz: eddc350347e96f820443be5e8e9524cab22623c8c1f1cd16241a86d5d1e851e206e264328d1c9734b427243682f8bffcdacb1215fb0647b472071d2c5484429b
+  data.tar.gz: 767d8e127f3cd3ddb498e0fe3237571acb753b6481480531d4094500b4d58e5f60d360184475f951c75217d6c2eb91b2b1e3862fd83b2ba140dcc35de81e880e

data/.env.example

@@ -94,3 +94,6 @@ PRE_INVENTORY_DAYS_TRANSIT=180  # How many days ahead inventory items are pre-ge
 PRE_INVENTORY_DAYS_ACCOMMODATION=365  # How many days ahead inventory items are pre-generated for accommodation variants
 PRE_INVENTORY_DAYS_SERVICE=180  # How many days ahead inventory items are pre-generated for service variants
 PAYMENT_BASE_URL=http://localhost:4000
+
+# See: app/services/spree_cm_commissioner/integrations/call_limiter.rb
+BOOKMEBUS_MAX_CALLS_PER_MINUTE=60  # Most calls a minute BookMe+ sends to BookMeBus, shared by all vendors (checkout is never limited); lower it to protect their server, raise it only after agreeing a limit with them

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.15.2)
+    spree_cm_commissioner (2.15.3)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront
@@ -886,7 +886,7 @@ GEM
       spree_backend (>= 4.3.0.rc1)
       spree_emails (>= 4.3.0.rc1)
       spree_extension
-    spree_vpago (2.4.6)
+    spree_vpago (2.4.7)
       faraday
       google-cloud-firestore
       spree_api (>= 4.5)

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

@@ -4,12 +4,7 @@ module Spree
       def index
         authorize! :manage, SpreeCmCommissioner::InventoryHold
 
-        q = params.fetch(:q, {})
-        q = q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h.deep_dup : q.deep_dup
-        q['s'] ||= 'created_at desc'
-        q['created_at_gt'] = parse_time_or_nil(q['created_at_gt'], :beginning_of_day) if q['created_at_gt'].present?
-        q['created_at_lt'] = parse_time_or_nil(q['created_at_lt'], :end_of_day) if q['created_at_lt'].present?
-        normalize_enum_filters!(q)
+        q = search_query
 
         @search = scope.ransack(q)
         result_scope = @search.result(distinct: true)
@@ -26,6 +21,27 @@ module Spree
                               .reorder(nil).group(:status).count
       end
 
+      # Same filters as the table; without a start date it covers the last 24h so the GROUP BYs stay cheap.
+      def overview
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        q = search_query
+        @overview_from = q['created_at_gt'].presence || 24.hours.ago
+        q['created_at_gt'] = @overview_from
+        @overview = SpreeCmCommissioner::InventoryHoldOverviewQuery.new(holds: scope.ransack(q).result).call
+
+        render partial: 'overview', layout: false
+      end
+
+      def insights
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        hold = scope.includes(:user, order: :user).find(params[:id])
+        @insights = SpreeCmCommissioner::InventoryHoldInsightsQuery.new(hold: hold).call
+
+        render partial: 'insights', layout: false
+      end
+
       def release
         authorize! :manage, SpreeCmCommissioner::InventoryHold
 
@@ -49,6 +65,16 @@ module Spree
 
       private
 
+      def search_query
+        q = params.fetch(:q, {})
+        q = q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h.deep_dup : q.deep_dup
+        q['s'] ||= 'created_at desc'
+        q['created_at_gt'] = parse_time_or_nil(q['created_at_gt'], :beginning_of_day) if q['created_at_gt'].present?
+        q['created_at_lt'] = parse_time_or_nil(q['created_at_lt'], :end_of_day) if q['created_at_lt'].present?
+        normalize_enum_filters!(q)
+        q
+      end
+
       # `status` and `release_reason` are integer-backed enums. Ransack casts a string
       # value for an integer column with String#to_i, so "payment_locked" becomes 0
       # (== :pending) and every label silently filters to the wrong status. Translate

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

@@ -0,0 +1,28 @@
+module SpreeCmCommissioner::Integrations
+  # The partner answered 429 (or CallLimiter refused the call). Sync code stops at the first one instead of
+  # retrying. An ExternalClientError, so checkout handles it like any other failed call.
+  class RateLimitedError < ExternalClientError
+    DEFAULT_RETRY_AFTER = 60.seconds
+    MAX_RETRY_AFTER = 2.hours
+
+    attr_reader :retry_after
+
+    # @param retry_after [Integer, nil] seconds to wait (the Retry-After header)
+    def initialize(message, retry_after: nil)
+      super(message, 429)
+      @retry_after = (retry_after || DEFAULT_RETRY_AFTER).to_i.clamp(DEFAULT_RETRY_AFTER.to_i, MAX_RETRY_AFTER.to_i)
+    end
+
+    # Retry-After is a number of seconds or an HTTP date; anything else is nil.
+    def self.parse_retry_after(header)
+      value = header.to_s.strip
+      return nil if value.empty?
+      return value.to_i if value.match?(/\A\d+\z/)
+
+      seconds = (Time.httpdate(value) - Time.current).ceil
+      seconds.positive? ? seconds : nil
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/integrations/book_me_bus_v1/sync_route_job.rb

@@ -0,0 +1,70 @@
+# Syncs the trips of one route for the next `sync_days` days. The daily full sync queues one per route, so a failing
+# route only fails itself, a deploy redoes one route (seconds, not minutes), and a rerun skips routes done today.
+class SpreeCmCommissioner::Integrations::BookMeBusV1::SyncRouteJob < SpreeCmCommissioner::ApplicationUniqueJob
+  queue_as :integration
+
+  MAX_ATTEMPTS = 3
+  RETRY_DELAY = 15.minutes
+  MIN_PAUSE = 1.minute # the call limit refills every minute
+
+  # @param options [Hash] :integration_id, :route_id, :attempt (1 for the first run, set by the retries)
+  def perform(options)
+    integration = SpreeCmCommissioner::Integration.find_by(id: options[:integration_id])
+    route = SpreeCmCommissioner::Route.find_by(id: options[:route_id])
+    return unless integration&.active? && route
+
+    # While BookMeBus is paused after a 429, don't call it: retry after the pause.
+    limiter = SpreeCmCommissioner::Integrations::CallLimiter.new(base_url: integration.base_url)
+    return retry_after_pause(options, limiter.paused_for) if limiter.paused?
+
+    sync_result = SpreeCmCommissioner::Integrations::Base::SyncResult.new
+    sync(integration, route, sync_result)
+
+    # Told to wait (our call limit or a 429): nothing wrong with the route, so no outcome is recorded.
+    return retry_after_pause(options, sync_result.to_h.dig(:error, :retry_after)) if sync_result.rate_limited?
+
+    record_outcome(integration, route, sync_result)
+    retry_later(options) unless sync_result.success?
+  end
+
+  private
+
+  def sync(integration, route, sync_result)
+    SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncTrips.new(
+      integration: integration, sync_result: sync_result, route: route
+    ).call(on_dates: integration.sync_dates)
+  rescue StandardError => e
+    sync_result.record_error(e)
+  end
+
+  # Kept on the route's mapping: `full_synced_on` (the next full sync skips it) or `last_error`.
+  def record_outcome(integration, route, sync_result)
+    mapping = SpreeCmCommissioner::IntegrationMapping.active_routes_of(integration).find_by(internal_id: route.id)
+    return unless mapping
+
+    outcome = sync_result.success? ? { 'full_synced_on' => Date.current.iso8601 } : { 'last_error' => sync_result.to_h.dig(:error, :message) }
+
+    # The incremental sync stamps the same column: the lock (which reloads first) keeps either from erasing the other's key.
+    mapping.with_lock do
+      mapping.update!(private_metadata: (mapping.private_metadata || {}).except('last_error', 'full_synced_on').merge(outcome))
+    end
+  end
+
+  # A real failure: tries again a few times today (15 min, then 30), then leaves it to the next full sync.
+  def retry_later(options)
+    attempt = (options[:attempt] || 1).to_i
+    return if attempt >= MAX_ATTEMPTS
+
+    self.class.set(wait: RETRY_DELAY * attempt).perform_later(options.merge(attempt: attempt + 1))
+  end
+
+  # Waits out the pause (at least a minute) and tries again as the same attempt: a large vendor queues all its routes
+  # at once, and the ones the call limit turns away must not use up their attempts just by waiting in line.
+  #
+  # `waits` changes the arguments on purpose: ApplicationUniqueJob drops a job whose arguments match one that is still
+  # running (`unique :until_executed`), and this job is still running while it queues its own retry. Without it the
+  # retry is dropped silently and the route is never synced.
+  def retry_after_pause(options, wait)
+    self.class.set(wait: [wait.to_i.seconds, MIN_PAUSE].max).perform_later(options.merge(waits: options[:waits].to_i + 1))
+  end
+end

data/app/models/spree_cm_commissioner/block.rb

@@ -60,6 +60,22 @@ module SpreeCmCommissioner
       self.class.sellable?(block_type)
     end
 
+    # The ReservedBlock row currently making this seat unbookable (reserved, on_hold, or
+    # operator-locked and not expired) — nil when the seat is open for sale. Reads off the
+    # already-loaded all_reserved_blocks association rather than querying, so a caller that
+    # preloads it (e.g. the organizer seat status view, rendering every block on a layout) does
+    # not pay a query per block.
+    #
+    # Only meaningful for a block with a single relevant InventoryItem, e.g. an Event
+    # session-variant's undated item. A Transit block spans one InventoryItem per departure date, so
+    # all_reserved_blocks can hold several simultaneously-active rows (locked on one date, sold on
+    # another) and this returns an arbitrary one of them, not "the" status for any particular date.
+    # Do not call this for a date-scoped seat map — use Seats::LockState instead, which resolves
+    # status per (block, date).
+    def current_reserved_block
+      all_reserved_blocks.detect(&:unavailable?)
+    end
+
     def assign_layout_from_section
       self.seat_layout = seat_section.seat_layout
     end

data/app/models/spree_cm_commissioner/integration_mapping.rb

@@ -6,6 +6,8 @@ module SpreeCmCommissioner
 
     enum status: { active: 0, archived: 1 }
 
+    scope :active_routes_of, -> (integration) { active.where(integration_id: integration.id, internal_type: 'SpreeCmCommissioner::Route') }
+
     # 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
@@ -32,6 +34,12 @@ module SpreeCmCommissioner
       save!
     end
 
+    # True when `new_payload` differs from the stored one only in `ignoring` keys (at any depth), i.e. nothing the
+    # rest of the sync reads back has changed. Does not write anything.
+    def payload_unchanged?(new_payload, ignoring: [])
+      persisted? && active? && stable_payload(new_payload.as_json, ignoring) == stable_payload(external_payload.as_json, ignoring)
+    end
+
     # For polling, which confirms the same mappings every few seconds. last_synced_at is indexed, so each save rewrites
     # every index on this table; this skips the save while nothing a reader uses has changed. `ignoring` lists payload
     # keys that move on every poll (seats, for one), at any depth.

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

@@ -8,6 +8,11 @@ class SpreeCmCommissioner::Integrations::BookMeBusV1 < SpreeCmCommissioner::Inte
   store_private_metadata :operator_id, :string
   store_private_metadata :sync_days, :integer, default: 7
   # override
+  # The dates a full sync covers: today and the next sync_days - 1 days.
+  def sync_dates
+    (0...sync_days).map { |ahead| (Date.current + ahead).iso8601 }
+  end
+
   def sync_manager
     SpreeCmCommissioner::Integrations::BookMeBusV1::SyncManager.new(integration: self)
   end

data/app/models/spree_cm_commissioner/reserved_block.rb

@@ -5,7 +5,12 @@ module SpreeCmCommissioner
     has_paper_trail
 
     # Why a seat was taken off sale by an operator. Stored in private_metadata rather than as a
-    # typed column, so it cannot be an ActiveRecord enum — the constant is the source of truth.
+    # typed column, so it cannot be an ActiveRecord enum.
+    #
+    # Suggested options for a picklist-style UI (Transit's "Lock Seats" drawer) -- NOT a validation
+    # allowlist. `lock_reason` itself accepts any free text (see the presence/length validations
+    # below): the Organizer "Manage Hold Seats" screen lets the operator type their own reason, so
+    # enforcing this list at the model would reject a perfectly legitimate custom reason.
     #
     # `gender_balance` is deliberately absent: female-only seating is driven by the `gender` column,
     # and a locked row has no gender, so a lock structurally cannot express it.
@@ -25,19 +30,24 @@ module SpreeCmCommissioner
 
     enum gender: { :other => 0, :male => 1, :female => 2 }
 
+    # Every status in which a seat cannot be sold. Single source of truth for the `unavailable`
+    # scope (SQL) and `#unavailable?` (in-memory, for a caller that already preloaded the rows and
+    # cannot afford one query per row) -- kept as one list so a future status addition cannot update
+    # one and silently miss the other.
+    UNAVAILABLE_STATUSES = %w[reserved on_hold locked].freeze
+
     store_private_metadata :lock_reason, :string
     store_private_metadata :lock_note, :text
 
     validates :status, presence: true
     validates :expired_at, presence: true, if: -> { on_hold? }
-    validates :lock_reason, inclusion: { in: LOCK_REASONS }, allow_nil: true
     validates :lock_reason, presence: true, if: -> { locked? }
     validate :locked_rows_have_no_guest, if: -> { locked? }
 
     scope :reserved_or_on_hold, -> { where(status: %i[reserved on_hold]).where('expired_at IS NULL OR expired_at > ?', Time.current) }
     # Every state in which a seat cannot be sold. `reserved_or_on_hold` is kept as-is because other
     # callers depend on its narrower meaning.
-    scope :unavailable, -> { where(status: %i[reserved on_hold locked]).where('expired_at IS NULL OR expired_at > ?', Time.current) }
+    scope :unavailable, -> { where(status: UNAVAILABLE_STATUSES).where('expired_at IS NULL OR expired_at > ?', Time.current) }
     scope :active_on_hold, -> { on_hold.where('expired_at IS NULL OR expired_at > ?', Time.current) }
     scope :active, -> { where('expired_at IS NULL OR expired_at > ?', Time.current) }
 
@@ -49,6 +59,12 @@ module SpreeCmCommissioner
       on_hold? && !expired?
     end
 
+    # In-memory equivalent of the `unavailable` scope, for a caller iterating a preloaded
+    # association rather than querying -- see Block#current_reserved_block.
+    def unavailable?
+      status.in?(UNAVAILABLE_STATUSES) && !expired?
+    end
+
     def payment_locked?
       payment_locked_at.present?
     end

data/app/queries/spree_cm_commissioner/inventory_hold_insights_query.rb

@@ -0,0 +1,151 @@
+module SpreeCmCommissioner
+  # Test/abandon/fraud signals for one hold, shown in the admin inventory holds drawer. Every
+  # section is a single aggregate (COUNT ... FILTER) or a LIMITed pluck, so the query count is
+  # fixed no matter how many orders/holds the user or IP has.
+  class InventoryHoldInsightsQuery
+    RECENT_LIMIT = 10
+    # Shared with InventoryHoldOverviewQuery as a Postgres `~*` pattern, so keep it POSIX-compatible.
+    TEST_EMAIL_SOURCE = '(\+test|test@|@example\.com|@bookme\.local)'.freeze
+    TEST_EMAIL_PATTERN = Regexp.new(TEST_EMAIL_SOURCE, Regexp::IGNORECASE)
+
+    IP_BURST_5M = 5
+    IP_DISTINCT_USERS_24H = 3
+    USER_CONCURRENT_HOLDS = 2
+    USER_ABANDONED_NO_CONVERT = 3
+    LARGE_QUANTITY = 10
+
+    # Highest-severity flag kind wins the drawer's headline verdict.
+    VERDICT_ORDER = %i[fraud test abandon].freeze
+
+    def initialize(hold:)
+      @hold = hold
+      @order = hold.order
+      @user = hold.user || hold.order&.user
+    end
+
+    def call
+      result = {
+        hold: hold,
+        order: order,
+        user: user,
+        roles: roles,
+        user_orders: user_order_stats,
+        recent_orders: recent_orders,
+        user_holds: hold_stats(:user_id, user&.id),
+        ip_holds: hold_stats(:ip_address, hold.ip_address, distinct_users: true),
+        ip_recent_holds: ip_recent_holds
+      }
+      flags = flags(result)
+      result.merge(flags: flags, verdict: VERDICT_ORDER.find { |kind| flags[kind].any? } || :normal)
+    end
+
+    private
+
+    attr_reader :hold, :order, :user
+
+    def roles
+      return [] unless user
+
+      Spree::Role.joins(:role_users).where(spree_role_users: { user_id: user.id }).pluck(:name)
+    end
+
+    def user_order_stats
+      empty = { completed: 0, incomplete: 0, last_completed_at: nil }
+      return empty unless user
+
+      completed, incomplete, last_completed_at = Spree::Order.where(user_id: user.id).pick(
+        Arel.sql('COUNT(*) FILTER (WHERE completed_at IS NOT NULL)'),
+        Arel.sql('COUNT(*) FILTER (WHERE completed_at IS NULL)'),
+        Arel.sql('MAX(completed_at)')
+      )
+      { completed: completed.to_i, incomplete: incomplete.to_i, last_completed_at: last_completed_at }
+    end
+
+    def recent_orders
+      return [] unless user
+
+      Spree::Order.where(user_id: user.id).order(created_at: :desc).limit(RECENT_LIMIT)
+                  .pluck(:number, :state, :payment_state, :total, :currency, :created_at, :completed_at)
+                  .map { |row| %i[number state payment_state total currency created_at completed_at].zip(row).to_h }
+    end
+
+    # Burst windows end at this hold's created_at so an old hold shows the burst it was part of.
+    def hold_stats(column, value, distinct_users: false)
+      keys = %i[total converted concurrent abandoned in_3m in_5m]
+      return keys.index_with(0).merge(distinct_users: 0, distinct_users_24h: 0) if value.blank?
+
+      relation = InventoryHold.where(column => value)
+
+      at = hold.created_at
+      selects = [
+        'COUNT(*)',
+        "COUNT(*) FILTER (WHERE status = #{InventoryHold.statuses[:converted]})",
+        "COUNT(*) FILTER (WHERE status IN (#{InventoryHold.statuses.values_at(:active, :payment_locked).join(',')}))",
+        "COUNT(*) FILTER (WHERE release_reason IN (#{InventoryHold.release_reasons.values_at(:hold_expired, :payment_timeout).join(',')}))",
+        window_count(at - 3.minutes, at),
+        window_count(at - 5.minutes, at)
+      ]
+      if distinct_users
+        keys += %i[distinct_users distinct_users_24h]
+        selects << 'COUNT(DISTINCT user_id)'
+        selects << sanitize('COUNT(DISTINCT user_id) FILTER (WHERE created_at BETWEEN ? AND ?)', at - 24.hours, at)
+      end
+
+      keys.zip(relation.pick(*selects.map { |sql| Arel.sql(sql) }).map(&:to_i)).to_h
+    end
+
+    def window_count(from, to)
+      sanitize('COUNT(*) FILTER (WHERE created_at BETWEEN ? AND ?)', from, to)
+    end
+
+    def sanitize(sql, *binds)
+      InventoryHold.sanitize_sql_array([sql, *binds])
+    end
+
+    def ip_recent_holds
+      return [] if hold.ip_address.blank?
+
+      InventoryHold.where(ip_address: hold.ip_address).where.not(id: hold.id)
+                   .left_joins(:order, :user).order(created_at: :desc).limit(RECENT_LIMIT)
+                   .pluck(:id, :status, :created_at, 'spree_orders.number', 'spree_orders.state', 'spree_orders.payment_state', 'spree_users.email')
+                   .map { |row| %i[id status created_at order_number order_state payment_state email].zip(row).to_h }
+    end
+
+    def flags(result)
+      { test: test_flags(result[:roles]), abandon: abandon_flags(result), fraud: fraud_flags(result) }
+    end
+
+    def test_flags(roles)
+      email = user&.email.presence || order&.email.to_s
+      [
+        ('Test-like email' if email.match?(TEST_EMAIL_PATTERN)),
+        ("Staff role: #{roles.join(', ')}" if roles.any?),
+        ('Zero total order' if order&.total.to_d.zero?),
+        ('Created by another user (dashboard)' if created_by_other_user?)
+      ].compact
+    end
+
+    def created_by_other_user?
+      order&.created_by_id.present? && order.created_by_id != order.user_id
+    end
+
+    def abandon_flags(result)
+      holds = result[:user_holds]
+      orders = result[:user_orders]
+      [
+        ("#{holds[:abandoned]} abandoned holds, 0 converted" if holds[:abandoned] >= USER_ABANDONED_NO_CONVERT && holds[:converted].zero?),
+        ("#{orders[:incomplete]} incomplete orders, 0 completed" if orders[:incomplete].positive? && orders[:completed].zero?)
+      ].compact
+    end
+
+    def fraud_flags(result)
+      ip = result[:ip_holds]
+      [
+        ("IP burst: #{ip[:in_5m]} holds in 5m" if ip[:in_5m] >= IP_BURST_5M),
+        ("#{ip[:distinct_users_24h]} different users on this IP in 24h" if ip[:distinct_users_24h] >= IP_DISTINCT_USERS_24H),
+        ("#{result[:user_holds][:concurrent]} holds open at once" if result[:user_holds][:concurrent] >= USER_CONCURRENT_HOLDS),
+        ("Large hold: #{hold.total_quantity_on_hold} items" if hold.total_quantity_on_hold.to_i >= LARGE_QUANTITY)
+      ].compact
+    end
+  end
+end

data/app/queries/spree_cm_commissioner/inventory_hold_overview_query.rb

@@ -0,0 +1,79 @@
+module SpreeCmCommissioner
+  # Aggregate test/abandon/fraud signals across a filtered set of holds, for the admin holds
+  # "Overall insights" drawer. Six grouped queries, each LIMITed, regardless of how many holds match.
+  class InventoryHoldOverviewQuery
+    TOP_LIMIT = 10
+    BURST_BINS = { '3m' => 180, '5m' => 300 }.freeze
+
+    # `holds` may carry ransack joins; wrapping it as an id subquery keeps the raw SQL below unambiguous.
+    def initialize(holds:)
+      @holds = InventoryHold.where(id: holds.reorder(nil).select(:id))
+    end
+
+    def call
+      {
+        funnel: funnel,
+        top_ips: top_ips,
+        bursts: BURST_BINS.transform_values { |seconds| bursts(seconds) },
+        abandoners: abandoners,
+        test_accounts: test_accounts
+      }
+    end
+
+    private
+
+    attr_reader :holds
+
+    def funnel
+      statuses = InventoryHold.statuses
+      reasons = InventoryHold.release_reasons
+      keys = %i[total converted open cart_abandoned payment_abandoned user_canceled cart_changed]
+      row = holds.pick(
+        Arel.sql('COUNT(*)'),
+        Arel.sql("COUNT(*) FILTER (WHERE status = #{statuses[:converted]})"),
+        Arel.sql("COUNT(*) FILTER (WHERE status IN (#{statuses.values_at(:pending, :active, :payment_locked).join(',')}))"),
+        *reasons.values_at(:hold_expired, :payment_timeout, :user_canceled, :cart_changed)
+                .map { |value| Arel.sql("COUNT(*) FILTER (WHERE release_reason = #{value})") }
+      )
+      result = keys.zip(row.map(&:to_i)).to_h
+      result.merge(conversion_rate: result[:total].zero? ? 0 : (100.0 * result[:converted] / result[:total]).round(1))
+    end
+
+    def top_ips
+      holds.where.not(ip_address: [nil, '']).group(:ip_address)
+           .order(Arel.sql('COUNT(*) DESC')).limit(TOP_LIMIT)
+           .pluck(:ip_address, Arel.sql('COUNT(*)'), Arel.sql('COUNT(DISTINCT user_id)'),
+                  Arel.sql("COUNT(*) FILTER (WHERE status = #{InventoryHold.statuses[:converted]})")
+           )
+           .map { |row| %i[ip_address holds users converted].zip(row).to_h }
+    end
+
+    # Fixed-width time buckets per IP; the busiest buckets are the bursts worth checking.
+    def bursts(seconds)
+      bucket = "to_timestamp(floor(extract(epoch FROM created_at) / #{seconds.to_i}) * #{seconds.to_i})"
+      holds.where.not(ip_address: [nil, '']).group(:ip_address, Arel.sql(bucket))
+           .having('COUNT(*) > 1').order(Arel.sql('COUNT(*) DESC')).limit(TOP_LIMIT)
+           .pluck(:ip_address, Arel.sql(bucket), Arel.sql('COUNT(*)'), Arel.sql('COUNT(DISTINCT user_id)'))
+           .map { |ip, started_at, count, users| { ip_address: ip, started_at: started_at&.in_time_zone, holds: count, users: users } }
+    end
+
+    def abandoners
+      reasons = InventoryHold.release_reasons.values_at(:hold_expired, :payment_timeout).join(',')
+      abandoned = "COUNT(*) FILTER (WHERE cm_inventory_holds.release_reason IN (#{reasons}))"
+      holds.joins(:user).group(:user_id, 'spree_users.email')
+           .having("#{abandoned} > 0 AND COUNT(*) FILTER (WHERE cm_inventory_holds.status = #{InventoryHold.statuses[:converted]}) = 0")
+           .order(Arel.sql("#{abandoned} DESC")).limit(TOP_LIMIT)
+           .pluck(:user_id, 'spree_users.email', Arel.sql(abandoned), Arel.sql('COUNT(*)'))
+           .map { |row| %i[user_id email abandoned holds].zip(row).to_h }
+    end
+
+    def test_accounts
+      staff = 'EXISTS (SELECT 1 FROM spree_role_users ru WHERE ru.user_id = spree_users.id)'
+      holds.joins(:user)
+           .where("spree_users.email ~* ? OR #{staff}", InventoryHoldInsightsQuery::TEST_EMAIL_SOURCE)
+           .group(:user_id, 'spree_users.email').order(Arel.sql('COUNT(*) DESC')).limit(TOP_LIMIT)
+           .pluck(:user_id, 'spree_users.email', Arel.sql('COUNT(*)'), Arel.sql("bool_or(#{staff})"))
+           .map { |row| %i[user_id email holds staff].zip(row).to_h }
+    end
+  end
+end

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

@@ -166,6 +166,13 @@ module SpreeCmCommissioner::Integrations::Base
         message: error.message,
         code: error.class.name.split('::').last
       }
+      # The scheduler reads this to honour Retry-After.
+      @error[:retry_after] = error.retry_after if error.respond_to?(:retry_after) && error.retry_after
+    end
+
+    # True when the last recorded error is a 429 from the partner.
+    def rate_limited?
+      @error.present? && @error[:code] == 'RateLimitedError'
     end
 
     # Check if sync was successful

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

@@ -41,7 +41,8 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
     # @param destination_id [String] The destination location ID
     # @param on_date [String] The travel date (YYYY-MM-DD format)
     # @return [Array<SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::Trip>] Array of available trip objects
-    def search_trips!(origin_id:, destination_id:, on_date:)
+    # @param lane [Symbol] :customer when a customer is waiting for the answer (see CallLimiter)
+    def search_trips!(origin_id:, destination_id:, on_date:, lane: :background)
       params = {
         origin_id: origin_id,
         destination_id: destination_id,
@@ -53,7 +54,7 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
       }.compact
       endpoint = "#{BASE_PATH}/trip_availabilities"
 
-      response = get(endpoint, params)
+      response = get(endpoint, params, nil, lane: lane)
       handle_response(response, SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::Trip, collection: true)
     end
 
@@ -66,7 +67,8 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
     # @param on_date [String] The travel date (YYYY-MM-DD format)
     # @param show_all_stops [Boolean] Whether to show all stops (default: false)
     # @return [SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::SeatLayout] Seat layout object
-    def get_seat_layout!(trip_id:, from_stop_id:, to_stop_id:, on_date:, show_all_stops: false)
+    # @param lane [Symbol] :customer when a customer is waiting for the answer (see CallLimiter)
+    def get_seat_layout!(trip_id:, from_stop_id:, to_stop_id:, on_date:, show_all_stops: false, lane: :background) # rubocop:disable Metrics/ParameterLists
       params = {
         trip_id: trip_id,
         from_stop_id: from_stop_id,
@@ -76,7 +78,7 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
       }
       endpoint = "#{BASE_PATH}/seat_layouts"
 
-      response = get(endpoint, params)
+      response = get(endpoint, params, nil, lane: lane)
       handle_response(response, SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::SeatLayout)
     end
 
@@ -125,7 +127,7 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
         request: { method: 'POST', endpoint: endpoint, body: body },
         auditable: params[:internal_order]
       ) do
-        response = post(endpoint, body)
+        response = post(endpoint, body, lane: :checkout)
         handle_response(response, SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::ReservationCart)
       end
     end
@@ -142,7 +144,7 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
         request: { method: 'POST', endpoint: endpoint, body: {} },
         auditable: internal_order
       ) do
-        response = post(endpoint, {})
+        response = post(endpoint, {}, lane: :checkout)
         handle_response(response, SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::WalletPayment)
       end
     end
@@ -158,7 +160,7 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
         request: { method: 'POST', endpoint: endpoint, body: {} },
         auditable: internal_order
       ) do
-        response = post(endpoint, {})
+        response = post(endpoint, {}, lane: :checkout)
         handle_response(response, SpreeCmCommissioner::Integrations::BookMeBusV1::Resources::WalletPayment)
       end
     end
@@ -216,6 +218,12 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
     end
 
     def raise_api_error(response)
+      raise_rate_limited(response) if response.status == 429
+
+      raise_failed_request(response)
+    end
+
+    def raise_failed_request(response)
       status = response.status
       body = response.body
 
@@ -237,5 +245,14 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::ExternalClient
 
       raise SpreeCmCommissioner::Integrations::ExternalClientError.new(message, status)
     end
+
+    def raise_rate_limited(response)
+      retry_after = SpreeCmCommissioner::Integrations::RateLimitedError.parse_retry_after(response.headers['Retry-After'])
+      error = SpreeCmCommissioner::Integrations::RateLimitedError.new('API request failed with status 429', retry_after: retry_after)
+
+      # Everything but checkout stops calling the partner until its Retry-After has passed.
+      call_limiter.pause!(error.retry_after)
+      raise error
+    end
   end
 end