spree_cm_commissioner 2.13.2 → 2.13.3.pre.pre2

data/app/services/spree_cm_commissioner/integrations/book_me_bus_v1/inventory/unstock_inventory.rb

@@ -0,0 +1,188 @@
+class SpreeCmCommissioner::Integrations::BookMeBusV1::Inventory::UnstockInventory
+  prepend ::Spree::ServiceModule::Base
+
+  # No enclosing DB transaction here (deliberately - see sync_line_item!): BookMeBus has no
+  # reservation-cancellation API in production, so once create_reservation! succeeds there is a
+  # real, un-undoable external side effect. Wrapping the loop in one transaction used to let a
+  # later failure (a different line item, or payment confirmation) roll back the local mapping
+  # that recorded an *earlier* line item's already-created BookMeBus reservation - on retry,
+  # sync_line_item! would then create a second, duplicate reservation for the same seats.
+  def call(integration:, order:, line_items:)
+    line_items.each do |line_item|
+      raise SpreeCmCommissioner::Integrations::SyncError, 'Invalid guests' if line_item.guests.size != line_item.quantity
+
+      sync_line_item!(integration, order, line_item)
+    end
+
+    success(order: order, line_items: line_items)
+  rescue SpreeCmCommissioner::Integrations::SyncError,
+         SpreeCmCommissioner::Integrations::ExternalClientError => e
+    failure(nil, e.message)
+  end
+
+  # Sync a single line item with BookMeBus
+  def sync_line_item!(integration, order, line_item) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    existing_mapping = line_item.integration_mappings.find_by(integration_id: integration.id, status: :active)
+
+    if existing_mapping
+      return if existing_mapping.external_payload&.dig('payment_confirmed')
+
+      # A BookMeBus reservation already exists from a prior attempt (recorded durably, see
+      # above), but payment was never confirmed - e.g. confirm_wallet_payment! failed last time
+      # and this got retried. We can't safely retry create_reservation! (would duplicate the
+      # reservation) and can't cancel the existing one (no API for it), so this needs a human,
+      # not another automatic attempt.
+      raise SpreeCmCommissioner::Integrations::SyncError,
+            "BookMeBus reservation #{existing_mapping.external_id} already exists for line item " \
+            "##{line_item.id} but payment was never confirmed - needs manual reconciliation, not an automatic retry"
+    end
+
+    internal_trip_id = line_item.trip_id
+    raise SpreeCmCommissioner::Integrations::SyncError, 'trip_id missing from line item metadata' if internal_trip_id.blank?
+
+    trip_mapping = SpreeCmCommissioner::IntegrationMapping.find_by(
+      integration_id: integration.id,
+      internal_type: 'SpreeCmCommissioner::Trip',
+      internal_id: internal_trip_id,
+      status: :active
+    )
+    raise SpreeCmCommissioner::Integrations::SyncError, "Integration mapping not found for trip ##{internal_trip_id}" if trip_mapping.nil?
+
+    external_trip_id = trip_mapping.external_id
+    raise SpreeCmCommissioner::Integrations::SyncError, 'External trip_id missing from mapping' if external_trip_id.blank?
+
+    boarding_mapping = find_trip_stop_mapping(integration, line_item.boarding_trip_stop_id)
+    drop_off_mapping = find_trip_stop_mapping(integration, line_item.drop_off_trip_stop_id)
+
+    from_stop_id = boarding_mapping&.external_payload&.dig('stop', 'id') || trip_mapping.external_payload&.dig('from_stop_id')
+    to_stop_id = drop_off_mapping&.external_payload&.dig('stop', 'id') || trip_mapping.external_payload&.dig('to_stop_id')
+    raise SpreeCmCommissioner::Integrations::SyncError, 'from_stop_id/to_stop_id missing for line item' if from_stop_id.blank? || to_stop_id.blank?
+
+    from_stop_time_id = boarding_mapping&.external_payload&.dig('id')
+    to_stop_time_id = drop_off_mapping&.external_payload&.dig('id')
+
+    address = order.bill_address || order.ship_address
+
+    reservation_cart = integration.client.create_reservation!(
+      {
+        trip_id: external_trip_id.to_i,
+        from_stop_id: from_stop_id.to_i,
+        to_stop_id: to_stop_id.to_i,
+        from_stop_time_id: from_stop_time_id,
+        to_stop_time_id: to_stop_time_id,
+        departure_date: line_item.from_date.to_date.strftime('%Y-%m-%d'),
+        reserved_seats: build_reserved_seats(line_item, from_stop_id, integration),
+        contact_name: address&.full_name.presence || order.email,
+        contact_email: order.email,
+        contact_phone: address&.phone.presence || order.user&.phone,
+        internal_order: order
+      }
+    )
+
+    # Persist immediately, before anything that can still fail (sync_guests!, confirm_payment!) -
+    # this reservation now exists on BookMeBus for real and must be recorded regardless of what
+    # happens next (see the no-transaction note on #call).
+    line_item_mapping = line_item.integration_mappings.find_or_initialize_by(
+      integration: integration,
+      external_id: reservation_cart.id
+    )
+    line_item_mapping.mark_as_active!(external_payload: reservation_cart.to_h)
+
+    sync_guests!(line_item.guests, reservation_cart, integration)
+    confirm_payment!(integration, reservation_cart, order)
+
+    line_item_mapping.mark_as_active!(external_payload: reservation_cart.to_h.merge('payment_confirmed' => true))
+  end
+
+  # Creates guest mappings and stores QR codes for check-in
+  def sync_guests!(guests, reservation_cart, integration)
+    reservation = reservation_cart.first_reservation
+    return unless reservation
+
+    guests.each do |guest|
+      guest_mapping = guest.integration_mappings.find_or_initialize_by(
+        integration: integration,
+        external_id: reservation.id
+      )
+
+      guest_mapping.external_qr_data = reservation.reservation_qr_code_url
+      guest_mapping.mark_as_active!(external_payload: reservation.to_h)
+    end
+  end
+
+  # Create and confirm wallet payment for the reservation
+  def confirm_payment!(integration, reservation_cart, order)
+    wallet_payment = integration.client.create_wallet_payment!(
+      cart_id: reservation_cart.id,
+      internal_order: order
+    )
+
+    confirmed_payment = integration.client.confirm_wallet_payment!(
+      payment_id: wallet_payment.id,
+      internal_order: order
+    )
+
+    raise SpreeCmCommissioner::Integrations::SyncError, 'Payment confirmation failed' unless confirmed_payment.paid?
+  end
+
+  # Find active trip stop mapping for integration
+  def find_trip_stop_mapping(integration, trip_stop_id)
+    return nil if trip_stop_id.blank?
+
+    SpreeCmCommissioner::IntegrationMapping.find_by(
+      integration_id: integration.id,
+      internal_type: 'SpreeCmCommissioner::TripStop',
+      internal_id: trip_stop_id,
+      status: :active
+    )
+  end
+
+  # Build reserved seats hash for BookMeBus API
+  #
+  # Trips where BookMeBus auto-assigns the seat (Trip#allow_seat_selection false, synced from
+  # their auto_assigned_seat flag) never give guests a block - that's expected, not an error.
+  # Avocado's own reservation flow (Transit::PassengerSeatCreator/ThirdParty::AutoAssignSeat)
+  # expects a full passenger list with label/layer nil in that case, not an empty payload, so it
+  # can assign real seats server-side - dropping those guests entirely would undercount
+  # number_of_seats and reserve fewer seats than the order was actually paid for.
+  def build_reserved_seats(line_item, from_stop_id, integration) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    seats = line_item.guests.map do |guest|
+      seat_label = guest.block&.label
+
+      if seat_label.blank? && line_item.required_seat_selection?
+        raise SpreeCmCommissioner::Integrations::SyncError, "Guest ##{guest.id} on line item ##{line_item.id} has no assigned seat"
+      end
+
+      name = [guest.first_name, guest.last_name].compact.join(' ')
+      name = "Guest #{guest.id}" if name.blank?
+
+      block_type = guest.block&.block_type&.to_s
+
+      {
+        name: name,
+        label: seat_label,
+        seat_type: block_type == 'seat' || block_type.blank? ? 'normal' : block_type,
+        layer: seat_label.present? ? (guest.block&.seat_section&.name || 'BUS') : nil,
+        nationality: guest_nationality_code(guest, integration)
+      }
+    end
+
+    seats.empty? ? {} : { from_stop_id.to_s => seats }
+  end
+
+  # Mirrors PricingModels::GuestContext's own fallback order (nationality_id, then
+  # guest.nationality_group, then guest.saved_guest.nationality_group) so the reservation actually
+  # sent to BookMeBus agrees with whatever nationality pricing already used to price the guest.
+  # Without this, a guest identified only via nationality_group (e.g. staff selecting it directly
+  # in the sell-ticket dashboard, which never sets nationality_id at all) was always reported as
+  # 'other' here regardless of what was actually selected.
+  def guest_nationality_code(guest, integration)
+    code = guest.nationality&.subtitle
+    return code.downcase if code.present?
+
+    group = guest.nationality_group || guest.saved_guest&.nationality_group
+    return (integration.vendor.service_origin&.subtitle || 'other').downcase if group == 'local'
+
+    'other'
+  end
+end

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

@@ -0,0 +1,79 @@
+module SpreeCmCommissioner::Integrations::BookMeBusV1::Polling
+  # SyncInventory handles inventory synchronization for BookMeBus trips
+  #
+  # This service is responsible for:
+  # - Creating or updating StockItem records
+  # - Adjusting inventory counts based on external seat availability
+  # - Managing stock locations for vendors
+  #
+  # Usage:
+  #   sync_service = SyncInventory.new(sync_result: sync_result, vendor: vendor)
+  #   sync_service.call(variant: variant, external_trip: external_trip)
+  #
+  class SyncInventory
+    def initialize(sync_result:, vendor:)
+      @sync_result = sync_result
+      @vendor = vendor
+    end
+
+    def call(variant:, external_trip:)
+      return unless variant&.persisted?
+
+      stock_location = find_or_create_stock_location
+      stock_item = find_or_create_stock_item(variant, stock_location)
+
+      adjust_inventory_if_needed(stock_item, external_trip)
+    end
+
+    private
+
+    def find_or_create_stock_location
+      @vendor.stock_locations.first || @vendor.send(:create_stock_location)
+    end
+
+    def find_or_create_stock_item(variant, stock_location)
+      variant.stock_items.find_or_create_by!(stock_location: stock_location) do |item|
+        item.count_on_hand = 0
+      end
+    end
+
+    def adjust_inventory_if_needed(stock_item, external_trip)
+      available_seats = external_trip.available_seats
+      return if available_seats.nil? # unknown, not zero - don't zero out real inventory
+
+      current_stock = stock_item.count_on_hand.to_i
+      difference = available_seats.to_i - current_stock
+      return if difference.zero?
+
+      @sync_result.track(:stock_item, stock_item) do
+        stock_item.adjust_count_on_hand(difference)
+        @sync_result.increment_metric(:inventory, :adjusted, difference.abs)
+      end
+
+      adjust_inventory_item_for_date(stock_item.variant, external_trip, difference)
+    end
+
+    # StockItem.count_on_hand isn't date-aware and isn't read for real availability checks
+    # (see docs/concepts/inventory-system.md) - apply the same delta to the specific date's
+    # InventoryItem so ongoing BookMeBus availability changes actually reach bookable inventory.
+    # If it doesn't exist yet, PermanentInventoryItemsGeneratorJob will seed it later from
+    # count_on_hand, so there's nothing to adjust yet.
+    def adjust_inventory_item_for_date(variant, external_trip, difference)
+      trip_date = parse_trip_date(external_trip.on_date)
+      return unless trip_date
+
+      inventory_item = variant.inventory_items.find_by(inventory_date: trip_date)
+      return unless inventory_item
+
+      inventory_item.adjust_quantity!(difference)
+    end
+
+    def parse_trip_date(date_string)
+      return nil if date_string.blank?
+
+      Date.parse(date_string.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,354 @@
+module SpreeCmCommissioner::Integrations::BookMeBusV1::Polling
+  # SyncItemAvailability syncs pricing and reserved blocks from BookMeBus API
+  #
+  # BookMeBus trips have an `is_selectable` flag that determines sync behavior:
+  # - is_selectable == true: Sync reserved blocks (booked seats)
+  # - is_selectable == false: Only update seats_remaining count
+  #
+  # Usage:
+  #   SyncItemAvailability.new(integration: integration, sync_result: sync_result)
+  #     .call(trip_id: 1, on_date: '2026-04-06')
+  class SyncItemAvailability # rubocop:disable Metrics/ClassLength
+    include SpreeCmCommissioner::Integrations::InventorySyncCachable
+
+    # Sentinel returned by fetch_external_trip to mean "we got a real, successful response from
+    # BookMeBus, and this trip is confirmed absent/unbookable for this date" - distinct from a
+    # plain nil, which means we couldn't determine that (missing local mapping, or the API call
+    # itself failed) and must leave existing inventory alone rather than guess.
+    UNAVAILABLE = :unavailable
+    private_constant :UNAVAILABLE
+
+    def initialize(integration:, sync_result: nil)
+      @integration = integration
+      @sync_result = sync_result || SpreeCmCommissioner::Integrations::Base::SyncResult.new
+    end
+
+    def call(trip_id:, on_date:)
+      trip = find_trip(trip_id)
+      return @sync_result unless trip
+
+      inventory_items = find_inventory_items_for_trip(trip, on_date)
+      return @sync_result if inventory_items.empty?
+
+      inventory_items.each do |inventory_item|
+        sync_item(trip, on_date, inventory_item)
+      end
+      # return the most recent last_synced_at from the inventory item mappings for this trip and date
+      @sync_result.last_synced_at =
+        inventory_items.last
+                       &.integration_mappings
+                       &.maximum(:last_synced_at)
+
+      @sync_result
+    rescue StandardError => e
+      @sync_result.record_error(e)
+      CmAppLogger.error(label: '[BookMeBusV1::SyncItemAvailability] sync failed', data: { error: e.message })
+      @sync_result
+    end
+
+    def sync_item(trip, on_date, inventory_item)
+      inventory_item_mapping = find_or_initialize_item_mapping(inventory_item)
+
+      return unless should_sync_item?(inventory_item_mapping)
+
+      ActiveRecord::Base.transaction do
+        external_trip = fetch_external_trip(trip, on_date)
+
+        case external_trip
+        when UNAVAILABLE
+          # A confirmed response (not a failed/ambiguous lookup - see fetch_external_trip) shows
+          # this trip is absent or no longer bookable for this specific date, while an
+          # already-synced InventoryItem here may still show real seats from a previous sync.
+          # Zero it out so BookMe+ stops selling a date BookMeBus has pulled, rather than only
+          # discovering that at the very end of checkout, after payment has been taken.
+          zero_out_inventory!(inventory_item)
+        when nil
+          return # rubocop:disable Rails/TransactionExitStatement -- couldn't determine (missing mapping data) - leave existing inventory untouched rather than guess
+        else
+          sync_price(inventory_item, external_trip)
+
+          # Sync strategy depends on trip type and seat availability
+          if should_sync_reserved_blocks?(external_trip)
+            sync_reserved_blocks(external_trip, on_date, inventory_item)
+          else
+            sync_stock_item(inventory_item, external_trip)
+          end
+
+          restore_inventory_if_previously_zeroed!(inventory_item, external_trip)
+        end
+
+        update_last_sync_at(inventory_item_mapping)
+      end
+    rescue StandardError => e
+      @sync_result.record_error(e)
+      CmAppLogger.error(label: '[BookMeBusV1::SyncItemAvailability] error', data: { inventory_item_id: inventory_item.id, error: e.message })
+    end
+
+    private
+
+    def client
+      @client ||= @integration.client
+    end
+
+    def find_trip(trip_id)
+      SpreeCmCommissioner::Trip.find_by(id: trip_id)
+    end
+
+    def should_sync_item?(mapping)
+      mapping.new_record? || mapping.last_synced_at.nil? || mapping.last_synced_at < sync_cache_ttl.ago
+    end
+
+    def should_sync_reserved_blocks?(external_trip)
+      # is_selectable is the field this class's own doc comment describes, but it was never
+      # actually wired up as an accessor - this used to fall back to a route_type heuristic that
+      # doesn't capture the real thing we need to know (whether BookMeBus exposes per-seat status
+      # for this trip at all, e.g. false for auto-assigned-seat trips). Keep the private_taxi
+      # exclusion too, defensively, since seat layouts don't apply there either.
+      external_trip.is_selectable && external_trip.route_type != 'private_taxi'
+    end
+
+    def find_inventory_items_for_trip(trip, on_date)
+      SpreeCmCommissioner::InventoryItem
+        .joins(variant: :product)
+        .where(spree_products: { id: trip.product_id })
+        .where(cm_inventory_items: { inventory_date: on_date })
+    end
+
+    def find_or_initialize_item_mapping(inventory_item)
+      SpreeCmCommissioner::IntegrationMapping.find_or_initialize_by(
+        integration_id: @integration.id,
+        internal_type: 'SpreeCmCommissioner::InventoryItem',
+        internal_id: inventory_item.id,
+        external_id: "#{inventory_item.id}-#{inventory_item.inventory_date}"
+      )
+    end
+
+    def trip_mapping_data(trip)
+      # Retrieves BookMeBus API identifiers (trip_id) from the integration mapping
+      # These are required to query the BookMeBus API for seat availability
+      mapping = SpreeCmCommissioner::IntegrationMapping.find_by(
+        integration_id: @integration.id,
+        internal_type: 'SpreeCmCommissioner::Trip',
+        internal_id: trip.id,
+        status: :active
+      )
+      return unless mapping
+
+      trip_id = mapping.external_payload&.dig('trip_id')
+      return unless trip_id
+
+      { trip_id: trip_id }
+    end
+
+    def fetch_external_trip(trip, on_date)
+      data = trip_mapping_data(trip)
+      return unless data # can't determine - no local trip mapping to look up
+
+      origin_id = find_external_location_id(trip.origin_place)
+      destination_id = find_external_location_id(trip.destination_place)
+      return unless origin_id && destination_id # can't determine - location mapping missing
+
+      # A real ExternalClientError now propagates out of fetch_external_trips (rather than being
+      # swallowed into an indistinguishable []) up to sync_item's own rescue, which correctly
+      # leaves inventory untouched - only a genuinely successful, possibly-empty response reaches
+      # the line below, so an empty result here is a confirmed "not available", not a guess.
+      external_trips = fetch_external_trips(origin_id, destination_id, on_date)
+      found = external_trips.find { |t| t.trip_id == data[:trip_id] }
+
+      return UNAVAILABLE if found.nil? || !found.bookable?
+
+      found
+    end
+
+    def find_external_location_id(place)
+      return unless place
+
+      vendor_place = SpreeCmCommissioner::VendorPlace.location.find_by(place_id: place.id, vendor_id: @integration.vendor.id)
+      return unless vendor_place
+
+      vendor_place.integration_mappings.find_by(integration_id: @integration.id, status: :active)&.external_id
+    end
+
+    def fetch_external_trips(origin_id, destination_id, on_date)
+      # No rescue here - a real ExternalClientError must propagate up to sync_item's own rescue
+      # (which records/logs it and leaves inventory untouched), not collapse into the same []
+      # a genuinely successful-but-empty response produces. Conflating the two would mean a
+      # transient API failure gets treated as BookMeBus confirming the trip is unavailable,
+      # incorrectly zeroing out real inventory.
+      @sync_result.track_api_call('search_trips') do
+        client.search_trips!(
+          origin_id: origin_id,
+          destination_id: destination_id,
+          on_date: on_date
+        ) || []
+      end
+    end
+
+    # Correct a stale-positive InventoryItem for a date BookMeBus has confirmed is no longer
+    # available (see fetch_external_trip's UNAVAILABLE sentinel) - without this, a date that was
+    # available on a previous sync stays sellable on BookMe+ indefinitely even after BookMeBus
+    # pulls it, since nothing else ever corrects an already-synced InventoryItem back down.
+    def zero_out_inventory!(inventory_item)
+      inventory_item.with_lock do
+        next if inventory_item.quantity_available.to_i.zero?
+
+        set_quantity_available_with_redis_sync!(inventory_item, 0)
+        @sync_result.increment_metric(:inventory, :zeroed_unavailable_date)
+      end
+    end
+
+    # If a previous sync zeroed this date out (zero_out_inventory!, because the trip was confirmed
+    # unavailable then) and BookMeBus now confirms it's bookable again with real seats, restore
+    # it. sync_stock_item alone can't be relied on for this: its delta is computed against
+    # StockItem#count_on_hand (a date-independent aggregate zero_out_inventory! never touches -
+    # deliberately, since it's not specific to this one date), so once available_seats matches
+    # that unrelated baseline again the delta comes back 0 and this InventoryItem would otherwise
+    # stay stuck at the 0 we forced it to, even though the date is genuinely bookable again.
+    def restore_inventory_if_previously_zeroed!(inventory_item, external_trip)
+      available_seats = external_trip.available_seats
+      return if available_seats.to_i.zero?
+
+      inventory_item.with_lock do
+        next unless inventory_item.quantity_available.to_i.zero?
+
+        set_quantity_available_with_redis_sync!(inventory_item, available_seats.to_i)
+        @sync_result.increment_metric(:inventory, :restored_after_unavailable_date)
+      end
+    end
+
+    # The real checkout-time availability check (Stock::AvailabilityChecker ->
+    # RedisStock::VariantCachedInventoryItemsBuilder) reads Redis, not the DB row directly - a
+    # plain `inventory_item.update!(quantity_available: ...)` looked correct here but left Redis
+    # stale, so checkout kept rejecting real purchases even after the DB value was fixed
+    # (confirmed live). `adjust_quantity!` is the sanctioned path that keeps both in sync via
+    # adjust_quantity_in_redis - but it also shifts max_capacity by the same delta, which isn't
+    # wanted here (max_capacity is the seat ceiling for whenever the trip runs, not something
+    # that should shrink/grow because today's availability changed), so restore it right after.
+    def set_quantity_available_with_redis_sync!(inventory_item, target_quantity)
+      original_max_capacity = inventory_item.max_capacity
+      delta = target_quantity - inventory_item.quantity_available
+      return if delta.zero?
+
+      inventory_item.adjust_quantity!(delta)
+      inventory_item.update_column(:max_capacity, original_max_capacity) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    def sync_price(inventory_item, external_trip)
+      price_amount = external_trip.sellable_price
+      return if price_amount.nil?
+
+      price = inventory_item.prices.find_or_initialize_by(currency: Spree::Store.default.default_currency)
+
+      @sync_result.track(:price, price) do |tracker|
+        price.assign_attributes(
+          amount: price_amount,
+          variant_id: inventory_item.variant_id,
+          inventory_item_id: inventory_item.id
+        )
+
+        tracker.save_if_changed!(price)
+      end
+
+      sync_nationality_pricing(inventory_item, external_trip)
+    end
+
+    # Keeps the vendor's local/non-local discount PricingModel current every time this trip's
+    # price is refreshed - additive to sellable_price above (which stays the base everyone pays
+    # by default), not a replacement for it. Never lets a pricing-model hiccup break the
+    # availability/price sync it's piggybacking on.
+    def sync_nationality_pricing(inventory_item, external_trip)
+      trip = inventory_item.variant&.trip
+      return unless trip&.route
+
+      SyncNationalityPricing.new(
+        route: trip.route,
+        vendor: @integration.vendor,
+        local_price: external_trip.local_price,
+        non_local_price: external_trip.non_local_price
+      ).call
+    rescue StandardError => e
+      @sync_result.record_error(e)
+      CmAppLogger.error(label: '[BookMeBusV1::SyncItemAvailability] nationality pricing sync failed', data: { error: e.message })
+    end
+
+    def sync_stock_item(inventory_item, external_trip)
+      sync_inventory = SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncInventory.new(
+        sync_result: @sync_result,
+        vendor: inventory_item.variant.vendor
+      )
+      sync_inventory.call(variant: inventory_item.variant, external_trip: external_trip)
+    end
+
+    def sync_reserved_blocks(external_trip, _on_date, inventory_item)
+      external_seat_layout = fetch_external_seat_layout(external_trip)
+      return unless external_seat_layout
+
+      trip_seat_layout = inventory_item.variant.trip&.seat_layout
+      return unless trip_seat_layout
+
+      sync_reserved_blocks_from_layout(trip_seat_layout, external_seat_layout, inventory_item)
+    end
+
+    def fetch_external_seat_layout(external_trip)
+      @sync_result.track_api_call('get_seat_layout') do
+        client.get_seat_layout!(
+          trip_id: external_trip.id,
+          from_stop_id: external_trip.from_stop_id,
+          to_stop_id: external_trip.to_stop_id,
+          on_date: external_trip.on_date || Time.zone.today.to_s
+        )
+      end
+    rescue SpreeCmCommissioner::Integrations::ExternalClientError => e
+      CmAppLogger.error(label: '[BookMeBusV1::SyncItemAvailability] get_seat_layout failed', data: { error: e.message })
+      @sync_result.record_error(e)
+      nil
+    end
+
+    def sync_reserved_blocks_from_layout(seat_layout, external_seat_layout, inventory_item)
+      external_seats_by_label = external_seat_layout.seats.index_by(&:label)
+
+      seat_layout.blocks.each do |block|
+        next unless block.sellable?
+
+        external_seat = external_seats_by_label[block.label]
+        next unless external_seat
+
+        reserved_block = SpreeCmCommissioner::ReservedBlock.find_or_initialize_by(
+          inventory_item: inventory_item,
+          block: block
+        )
+
+        if external_seat.booked?
+          next if reserved_block.reserved?
+
+          @sync_result.track(:reserved_block, reserved_block) do |tracker|
+            reserved_block.assign_attributes(
+              status: :reserved,
+              expired_at: nil,
+              inventory_date: inventory_item.inventory_date,
+              guest: nil,
+              updated_by: nil
+            )
+            tracker.save_if_changed!(reserved_block)
+          end
+        elsif reserved_block.persisted?
+          # Locked, and guest_id re-checked after acquiring the lock, so a real customer hold
+          # being created concurrently on this exact block can't be destroyed out from under them.
+          reserved_block.with_lock do
+            next unless reserved_block.guest_id.nil?
+
+            @sync_result.track(:reserved_block, reserved_block) do |_tracker|
+              reserved_block.destroy!
+              @sync_result.increment_metric(:reserved_block, :deleted)
+            end
+          end
+        end
+      end
+    end
+
+    def update_last_sync_at(mapping)
+      mapping.last_synced_at = Time.current
+      mapping.save! if mapping.changed?
+    end
+  end
+end