spree_uber_direct 0.1.4

data/app/models/spree/calculator/shipping/uber_direct_quote.rb

@@ -0,0 +1,62 @@
+require_dependency 'spree/shipping_calculator'
+
+module Spree
+  # Compact `module Calculator::Shipping` — same reasoning as
+  # Spree::Calculator::Shipping::DoordashQuote's own docstring:
+  # Spree::Calculator is already a class in spree_core, not a module;
+  # nesting it the "obvious" way raises TypeError.
+  module Calculator::Shipping
+    # Prices an "Uber Direct Delivery" shipping method against a real,
+    # live Uber Direct quote rather than a flat/configured rate. Same
+    # zero-registration mechanism as DoordashQuote — any
+    # < Spree::ShippingCalculator subclass is auto-discovered by
+    # Spree::Stock::Estimator, confirmed directly against spree_core's own
+    # shipping_method.rb.
+    class UberDirectQuote < ShippingCalculator
+      def self.description
+        'Uber Direct (live quote)'
+      end
+
+      def compute_package(package)
+        result = SpreeUberDirect::Quote.call(package.order)
+        if result.nil?
+          # Same object-identity bridge DoordashQuote's own compute_package
+          # needs, for the identical reason: `package.order` is not the
+          # same in-memory object `create_proposed_shipments` holds as
+          # `self` (spree_core's InventoryUnitBuilder deliberately defers
+          # loading that association) — a direct
+          # `package.order.warnings |= [...]` here would silently mutate a
+          # throwaway copy discarded the instant this method returns. See
+          # SpreeUberDirect::OrderDecorator for the merge-back half of this
+          # bridge, and spree_doordash's own CHANGELOG (0.1.3) for the full
+          # story of how this was originally found live.
+          self.class.mark_unavailable(package.order.id)
+          return nil
+        end
+
+        result.fee_cents / 100.0
+      end
+
+      def self.mark_unavailable(order_id)
+        (Thread.current[:spree_uber_direct_quote_unavailable_order_ids] ||= []) << order_id
+      end
+
+      def self.unavailable?(order_id)
+        Thread.current[:spree_uber_direct_quote_unavailable_order_ids]&.include?(order_id) || false
+      end
+
+      def self.clear_unavailable(order_id)
+        Thread.current[:spree_uber_direct_quote_unavailable_order_ids]&.delete(order_id)
+      end
+
+      # Called by Estimator to filter which shipping methods even attempt
+      # a compute_package call. Skips the Uber Direct API round-trip
+      # entirely for an order with no ship address yet — the real "can
+      # Uber Direct serve this address" check still happens inside
+      # SpreeUberDirect::Quote itself.
+      def available?(package)
+        package.order.ship_address.present?
+      end
+    end
+  end
+end

data/app/models/spree_uber_direct/credential.rb

@@ -0,0 +1,33 @@
+module SpreeUberDirect
+  # A Direct account's OAuth client_credentials + Customer ID for one
+  # Spree::Store, plus a cached access token. Unlike SpreeDoordash::Credential
+  # (a static access key that signs a fresh short-lived JWT per call, nothing
+  # to cache), Uber Direct's OAuth2 client_credentials grant issues a genuine
+  # bearer token that outlives a single request — SpreeUberDirect::Client
+  # caches it here and refreshes it proactively before it actually expires,
+  # rather than fetching a fresh one on every call.
+  class Credential < Spree.base_class
+    self.table_name = 'spree_uber_direct_credentials'
+
+    belongs_to :store, class_name: 'Spree::Store'
+
+    encrypts :client_id, :client_secret, :customer_id, :access_token, :webhook_signing_secret
+
+    validates :store, presence: true, uniqueness: true
+    validates :client_id, :client_secret, :customer_id, presence: true
+
+    def sandbox?
+      uber_environment == 'sandbox'
+    end
+
+    # A short margin before the token's real expiry, not right up against
+    # it — avoids a request racing the token's actual expiration mid-flight.
+    # Mirrors SpreeSquare::Credential's own needs_refresh? margin rationale.
+    REFRESH_MARGIN = 60 # seconds
+
+    def needs_refresh?
+      access_token.blank? || access_token_expires_at.blank? ||
+        access_token_expires_at <= REFRESH_MARGIN.seconds.from_now
+    end
+  end
+end

data/app/models/spree_uber_direct/delivery_mapping.rb

@@ -0,0 +1,27 @@
+module SpreeUberDirect
+  # Maps a Spree::Order to the Uber Direct delivery it was dispatched to on
+  # acceptance — the Uber Direct analog of SpreeDoordash::DeliveryMapping.
+  # Unlike DoorDash (which reuses the accepted quote's own id for the
+  # delivery's whole lifecycle), Uber mints a genuinely separate
+  # `del_`-prefixed id on POST /deliveries (confirmed directly against the
+  # real CreateDeliveryResp schema) — external_delivery_id here is always
+  # that new id, never the quote's `dqt_...` id.
+  class DeliveryMapping < Spree.base_class
+    self.table_name = 'spree_uber_direct_delivery_mappings'
+
+    belongs_to :order, class_name: 'Spree::Order'
+
+    validates :order, presence: true, uniqueness: true
+    # No presence requirement, allow_nil on uniqueness — same rationale as
+    # SpreeDoordash::DeliveryMapping's own external_delivery_id: a dispatch
+    # can fail before Uber ever returns a delivery id at all (e.g. the
+    # underlying quote itself failed), and DeliveryDispatchJob's
+    # dead-letter block still needs to record that failure on a row with
+    # no id yet.
+    validates :external_delivery_id, uniqueness: true, allow_nil: true
+
+    def mark_failed!(error)
+      update!(dispatch_error: error.to_s.truncate(2000))
+    end
+  end
+end

data/app/models/spree_uber_direct/order_decorator.rb

@@ -0,0 +1,42 @@
+module SpreeUberDirect
+  # Bridges Spree::Calculator::Shipping::UberDirectQuote#compute_package's
+  # uber_direct_quote_unavailable warning back onto the real order object —
+  # same object-identity bridge and same rationale as spree_doordash's own
+  # Spree::OrderDecorator (see that file's docstring for the full
+  # root-cause story: package.order is a distinct in-memory object from
+  # the order create_proposed_shipments holds, so a direct
+  # `package.order.warnings |= [...]` silently mutates a throwaway copy).
+  #
+  # Deliberately namespaced `SpreeUberDirect::OrderDecorator`, NOT the bare
+  # `Spree::OrderDecorator` spree_doordash already defines — both gems
+  # prepend a module onto Spree::Order, and reusing the *same* module name
+  # would reopen spree_doordash's module and silently overwrite its method
+  # instead of creating a second link in Order's prepend chain. Distinct
+  # module objects chain correctly via `super`; this is why `super` is
+  # called here even though it looks like it "does nothing" locally — it's
+  # what lets spree_doordash's own create_proposed_shipments override
+  # still run too, regardless of which gem's initializer loads its
+  # decorator first.
+  module OrderDecorator
+    def create_proposed_shipments
+      Spree::Calculator::Shipping::UberDirectQuote.clear_unavailable(id)
+      result = super
+      merge_uber_direct_quote_warning!
+      result
+    end
+
+    private
+
+    def merge_uber_direct_quote_warning!
+      return unless Spree::Calculator::Shipping::UberDirectQuote.unavailable?(id)
+
+      Spree::Calculator::Shipping::UberDirectQuote.clear_unavailable(id)
+      self.warnings |= [{
+        code: 'uber_direct_quote_unavailable',
+        message: 'We could not get an Uber Direct delivery quote for this address.'
+      }]
+    end
+  end
+
+  Spree::Order.prepend OrderDecorator
+end

data/app/models/spree_uber_direct/quote_mapping.rb

@@ -0,0 +1,25 @@
+module SpreeUberDirect
+  # Tracks the most recent Uber Direct quote requested for an order,
+  # generated as checkout progresses (see Spree::Calculator::Shipping::
+  # UberDirectQuote, M3) and consulted again at order.completed to decide
+  # whether to accept it as-is or re-quote (see DeliveryDispatcher, M4) —
+  # same role as SpreeDoordash::QuoteMapping, checkout can easily outlast a
+  # quote's validity window.
+  #
+  # Unlike DoorDash's 5-minute rule (undocumented on the response itself,
+  # just DoorDash's own stated policy), `expired?` here checks Uber's own
+  # returned `quote_expires_at` — always accurate to what Uber will
+  # actually honor, never a guessed/hardcoded window.
+  class QuoteMapping < Spree.base_class
+    self.table_name = 'spree_uber_direct_quote_mappings'
+
+    belongs_to :order, class_name: 'Spree::Order'
+
+    validates :order, presence: true, uniqueness: true
+    validates :external_quote_id, presence: true, uniqueness: true
+
+    def expired?
+      quote_expires_at.blank? || quote_expires_at <= Time.current
+    end
+  end
+end

data/app/models/spree_uber_direct/refund_event.rb

@@ -0,0 +1,34 @@
+module SpreeUberDirect
+  # Durable, unprocessed record of an inbound `event.refund_request`
+  # webhook. Uber Direct's refund-request payloads carry no top-level
+  # `status`, so WebhooksController can't build a WebhookEvent from one
+  # (see that model's own comment) — before this, they were acked and
+  # silently dropped alongside genuinely-disposable courier_update pings,
+  # even though refund data (data.id, currency_code,
+  # total_partner_refund, total_uber_refund, refund_fees,
+  # refund_order_items) can't be recovered later once thrown away.
+  #
+  # Intentionally does none of WebhookEvent's processing-state tracking
+  # (processing_status/processed_at/error_message) — there's no consumer
+  # for this data yet. It exists purely so refund reconciliation admin UI
+  # or accounting sync has something real to read from whenever it's
+  # built.
+  #
+  # Does keep WebhookEvent's idempotency-key shape though (delivery_id +
+  # a digest of the raw body) — Uber's webhook delivery is at-least-once,
+  # and a retried refund_request shouldn't silently become two rows for
+  # the same refund.
+  class RefundEvent < Spree.base_class
+    self.table_name = 'spree_uber_direct_refund_events'
+
+    attribute :payload, default: -> { {} }
+
+    validates :delivery_id, presence: true
+    validates :payload, presence: true
+    validates :payload_digest, presence: true, uniqueness: { scope: :delivery_id }
+
+    def self.digest(raw_body)
+      Digest::SHA256.hexdigest(raw_body)
+    end
+  end
+end

data/app/models/spree_uber_direct/webhook_event.rb

@@ -0,0 +1,34 @@
+module SpreeUberDirect
+  # Idempotency + audit log for inbound Uber Direct webhook notifications.
+  #
+  # Column named `status` on this table is Uber's own delivery status value
+  # (pending/pickup/pickup_complete/dropoff/delivered/canceled/returned/
+  # shopping_completed) — this model's *own* pending/processed/failed
+  # processing state lives in the separate `processing_status` column, to
+  # avoid the two genuinely different meanings colliding on one name
+  # (DoorDash's own WebhookEvent didn't need this distinction since its
+  # payload field is called event_name, not status).
+  class WebhookEvent < Spree.base_class
+    self.table_name = 'spree_uber_direct_webhook_events'
+
+    attribute :payload, default: -> { {} }
+
+    validates :delivery_id, presence: true
+    validates :status, presence: true
+    validates :payload_digest, presence: true, uniqueness: { scope: %i[delivery_id status] }
+
+    scope :pending, -> { where(processing_status: 'pending') }
+
+    def self.digest(raw_body)
+      Digest::SHA256.hexdigest(raw_body)
+    end
+
+    def mark_processed!
+      update!(processing_status: 'processed', processed_at: Time.current)
+    end
+
+    def mark_failed!(error)
+      update!(processing_status: 'failed', processed_at: Time.current, error_message: error.to_s.truncate(1000))
+    end
+  end
+end

data/app/services/spree_uber_direct/address_payload.rb

@@ -0,0 +1,35 @@
+module SpreeUberDirect
+  # Shared address/phone formatting between Quote (create_quote) and
+  # DeliveryDispatcher (create_delivery) — both build a payload from the
+  # same order + fulfilling StockLocation shape, and Uber's schema uses
+  # the identical JSON-string-address / E.164-phone conventions on both
+  # endpoints (confirmed directly against the real openapi.yaml).
+  module AddressPayload
+    module_function
+
+    # Same E.164 normalization as SpreeDoordash::Quote#format_phone
+    # (Uber's own schema pattern, `^\+[0-9]+$`, is the same shape DoorDash
+    # rejects anything else against) — US-only, matching the rest of this
+    # demo.
+    def format_phone(raw)
+      digits = raw.to_s.gsub(/\D/, '')
+      digits = "1#{digits}" if digits.length == 10
+      "+#{digits}"
+    end
+
+    # Uber wants a JSON *string* per address field — structured, not
+    # DoorDash's flat comma-joined string. Spree::StockLocation and
+    # Spree::Address share the same field shape (address1/address2/city/
+    # state/zipcode/country) even though they're unrelated classes.
+    def format_address(record)
+      street = [record.address1, record.try(:address2)].compact_blank
+      {
+        street_address: street,
+        city: record.city,
+        state: record.state&.abbr || record.state_name,
+        zip_code: record.zipcode,
+        country: record.country&.iso
+      }.compact.to_json
+    end
+  end
+end

data/app/services/spree_uber_direct/alerting.rb

@@ -0,0 +1,18 @@
+module SpreeUberDirect
+  # One place for "this needs a human" — used when a job exhausts its
+  # retries. A standalone copy of the same pattern SpreeSquare::Alerting
+  # and SpreeDoordash::Alerting each already carry, not a dependency on
+  # either sibling gem — spree_uber_direct stays independently installable
+  # on its own.
+  class Alerting
+    def self.capture(error, context: {})
+      context = { source: 'spree_uber_direct' }.merge(context.is_a?(String) ? { area: context } : context)
+
+      Rails.logger.error("[SpreeUberDirect] #{context[:area] || 'error'}: #{error.class}: #{error.message}")
+
+      return unless defined?(Sentry)
+
+      Sentry.capture_exception(error, extra: context)
+    end
+  end
+end

data/app/services/spree_uber_direct/client.rb

@@ -0,0 +1,155 @@
+require 'faraday'
+
+module SpreeUberDirect
+  # Thin wrapper around the Uber Direct API (`api.uber.com/v1/customers/
+  # {customer_id}/...`). All Direct API access in this extension goes
+  # through here.
+  #
+  # Auth is fundamentally different from SpreeDoordash::Client: Uber Direct
+  # uses OAuth2 client_credentials (`auth.uber.com/oauth/v2/token`), which
+  # issues a genuine bearer token that outlives a single request — unlike
+  # DoorDash's per-request-signed 5-minute JWT, there's a real token to
+  # cache and refresh here. The cache lives on the Credential row itself
+  # (see SpreeUberDirect::Credential#needs_refresh?) rather than
+  # Rails.cache — no extra infrastructure, and naturally picks up a
+  # rotated client_secret on the very next call since a fresh
+  # `Credential.find_by` is re-resolved per client instance (not memoized —
+  # same rationale as SpreeSquare::Client and SpreeDoordash::Client: an
+  # admin can edit the credential mid-process).
+  class Client
+    class MissingCredentialsError < StandardError; end
+
+    SANDBOX_BASE_URL = 'https://api.uber.com'.freeze
+    AUTH_URL = 'https://auth.uber.com/oauth/v2/token'.freeze
+    SCOPE = 'eats.deliveries'.freeze
+
+    def self.instance
+      for_store
+    end
+
+    def self.for_store(store = Spree::Store.default)
+      new(credential: SpreeUberDirect::Credential.find_by(store: store))
+    end
+
+    def initialize(credential: nil)
+      @credential = credential
+      raise MissingCredentialsError, 'No Uber Direct credential connected and UBER_DIRECT_CLIENT_ID is not set' if client_id.blank?
+    end
+
+    def sandbox?
+      @credential ? @credential.sandbox? : ENV.fetch('UBER_DIRECT_ENVIRONMENT', 'sandbox') == 'sandbox'
+    end
+
+    # Create Quote — validates coverage/pricing before formally creating a
+    # delivery, same "quote first" recommended flow as DoorDash's Drive API.
+    def create_quote(payload)
+      request(:post, "/v1/customers/#{customer_id}/delivery_quotes", payload)
+    end
+
+    # Create Delivery — formally dispatches from a still-open quote_id.
+    def create_delivery(payload)
+      request(:post, "/v1/customers/#{customer_id}/deliveries", payload)
+    end
+
+    def get_delivery(delivery_id)
+      request(:get, "/v1/customers/#{customer_id}/deliveries/#{delivery_id}")
+    end
+
+    def cancel_delivery(delivery_id)
+      request(:post, "/v1/customers/#{customer_id}/deliveries/#{delivery_id}/cancel")
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      response = connection.send(method) do |req|
+        req.url path
+        req.headers['Authorization'] = "Bearer #{access_token}"
+        req.headers['Content-Type'] = 'application/json'
+        req.body = body.to_json if body
+      end
+      handle_response(response)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: SANDBOX_BASE_URL)
+    end
+
+    def handle_response(response)
+      parsed = response.body.present? ? JSON.parse(response.body) : {}
+      return parsed if response.status.between?(200, 299)
+
+      raise RequestError.new("Uber Direct API error (#{response.status}): #{parsed.inspect}", status: response.status, body: parsed)
+    end
+
+    def customer_id
+      fetch_secret(:customer_id, env_key: 'UBER_DIRECT_CUSTOMER_ID')
+    end
+
+    def client_id
+      fetch_secret(:client_id, env_key: 'UBER_DIRECT_CLIENT_ID')
+    end
+
+    def client_secret
+      fetch_secret(:client_secret, env_key: 'UBER_DIRECT_CLIENT_SECRET')
+    end
+
+    # Credential first, ENV fallback second — same dual-path convention
+    # SpreeSquare::Client's own `fetch` uses, kept for the same reason: a
+    # one-off admin/dev rake task (mirroring spree_square's
+    # `setup_demo_tax`) can run against a broader sandbox credential
+    # without needing a Credential row set up first.
+    def fetch_secret(key, env_key:)
+      (@credential && @credential.public_send(key).presence) || ENV[env_key].presence
+    end
+
+    def access_token
+      return fetch_token!['access_token'] unless @credential
+
+      refresh_if_needed!
+      @credential.access_token
+    end
+
+    def refresh_if_needed!
+      return unless @credential.needs_refresh?
+
+      token_data = fetch_token!
+      @credential.update!(
+        access_token: token_data['access_token'],
+        access_token_expires_at: token_data['expires_in'].to_i.seconds.from_now
+      )
+    end
+
+    # No caching on the credential-less (ENV-only) path — deliberately
+    # simple: that path only exists for occasional ad-hoc scripting, not a
+    # hot request path, so re-fetching a token every call costs nothing
+    # worth optimizing for.
+    def fetch_token!
+      response = Faraday.post(AUTH_URL) do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+        req.body = URI.encode_www_form(
+          client_id: client_id,
+          client_secret: client_secret,
+          grant_type: 'client_credentials',
+          scope: SCOPE
+        )
+      end
+      parsed = JSON.parse(response.body)
+      unless response.status.between?(200, 299)
+        raise RequestError.new("Uber Direct OAuth error (#{response.status}): #{parsed.inspect}", status: response.status, body: parsed)
+      end
+
+      parsed
+    end
+  end
+
+  class RequestError < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status:, body:)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end

data/app/services/spree_uber_direct/delivery_dispatcher.rb

@@ -0,0 +1,118 @@
+module SpreeUberDirect
+  # Dispatches a completed order to Uber Direct: creates the delivery
+  # against its already-open quote if one exists and hasn't expired, or
+  # requests a fresh quote and creates the delivery from that instead.
+  # Same accept-or-requote shape as SpreeDoordash::DeliveryDispatcher, for
+  # the identical reason — checkout can easily outlast a quote's validity
+  # window (Uber returns its own real `expires` per quote; see
+  # SpreeUberDirect::QuoteMapping#expired?).
+  #
+  # Architecturally bigger than DoorDash's own accept_quote (which only
+  # needs the external_delivery_id, DoorDash already has everything else
+  # from the original quote request) — confirmed live against a real
+  # Sandbox 400: Uber's POST /deliveries wants a *full* DeliveryReq body
+  # (pickup/dropoff name+address+phone, manifest_items,
+  # manifest_total_value) even when a quote_id is also provided. Reuses
+  # AddressPayload (shared with Quote) rather than duplicating the
+  # formatting logic.
+  class DeliveryDispatcher
+    def self.call(...) = new.call(...)
+
+    def call(order)
+      quote_mapping = quote_mapping_for(order)
+      return nil unless quote_mapping
+
+      stock_location = pickup_location_for(order)
+      return nil unless stock_location
+
+      client = SpreeUberDirect::Client.for_store(order.store || Spree::Store.default)
+      response = client.create_delivery(build_payload(order, stock_location, quote_mapping, robo_courier: robo_courier?(client)))
+
+      persist_delivery!(order, response)
+    rescue SpreeUberDirect::Client::MissingCredentialsError, SpreeUberDirect::RequestError => e
+      Rails.logger.error("[SpreeUberDirect] dispatch failed for order #{order.number}: #{e.message}")
+      SpreeUberDirect::DeliveryMapping.find_or_initialize_by(order: order).mark_failed!(e)
+      SpreeUberDirect::Alerting.capture(e, context: { area: 'dispatch', order_number: order.number })
+      nil
+    end
+
+    private
+
+    def quote_mapping_for(order)
+      existing = SpreeUberDirect::QuoteMapping.find_by(order: order)
+      return existing if existing && !existing.expired?
+
+      SpreeUberDirect::Quote.call(order)
+      SpreeUberDirect::QuoteMapping.find_by(order: order)
+    end
+
+    # Same lookup as SpreeUberDirect::Quote#pickup_location_for — queried
+    # directly rather than trusting an already-loaded `order.shipments`
+    # association, same reasoning.
+    def pickup_location_for(order)
+      Spree::Shipment.where(order_id: order.id).first&.stock_location ||
+        Spree::StockLocation.find_by(default: true)
+    end
+
+    # Gated on the credential's own sandbox flag only — deliberately, not
+    # also on Rails.env. An earlier version of this method also required
+    # !Rails.env.production?, reasoning that this project's live storefront
+    # runs real production Rails against a genuinely `uber_environment:
+    # sandbox` credential (Uber has not yet granted production API access),
+    # so the credential alone couldn't be trusted as "this is just a test".
+    # That's still true, but it was the wrong tradeoff for this specific
+    # project: the whole storefront is a demo running entirely on sandbox
+    # credentials end to end (Square, DoorDash, Uber alike) — showing a
+    # real visitor the full Uber Direct delivery lifecycle live is the
+    # intended demo experience here, not an accident to guard against.
+    # Explicit, informed decision, not a default: confirm this project's
+    # storefront is still demo-only before ever reusing this pattern
+    # somewhere real money/production access is actually on the line.
+    def robo_courier?(client)
+      client.sandbox?
+    end
+
+    def build_payload(order, stock_location, quote_mapping, robo_courier:)
+      payload = {
+        quote_id: quote_mapping.external_quote_id,
+        pickup_name: stock_location.name,
+        pickup_address: AddressPayload.format_address(stock_location),
+        pickup_phone_number: AddressPayload.format_phone(stock_location.phone),
+        dropoff_name: order.ship_address.full_name,
+        dropoff_address: AddressPayload.format_address(order.ship_address),
+        dropoff_phone_number: AddressPayload.format_phone(order.ship_address.phone),
+        manifest_items: manifest_items(order),
+        manifest_total_value: (order.total * 100).to_i
+      }
+      # Robo Courier: Uber Direct's sandbox-only test-automation feature —
+      # there is no dashboard "simulate delivery" UI the way DoorDash has
+      # one. Requesting `mode: 'auto'` here makes Uber's own courier bot
+      # walk the delivery through real status transitions (assigned →
+      # enroute → pickup imminent → picked up → dropoff imminent →
+      # delivered) at fixed 30s intervals, firing a real webhook at each
+      # stage.
+      payload[:test_specifications] = { robo_courier_specification: { mode: 'auto' } } if robo_courier
+      payload
+    end
+
+    def manifest_items(order)
+      order.line_items.map do |item|
+        { name: item.name, quantity: item.quantity }
+      end
+    end
+
+    def persist_delivery!(order, response)
+      courier = response['courier'] || {}
+      mapping = SpreeUberDirect::DeliveryMapping.find_or_initialize_by(order: order)
+      mapping.update!(
+        external_delivery_id: response['id'],
+        last_status: response['status'],
+        tracking_url: response['tracking_url'],
+        courier_name: courier['name'],
+        courier_phone: courier['phone_number'],
+        raw_response: response
+      )
+      mapping
+    end
+  end
+end

data/app/services/spree_uber_direct/delivery_status_mapper.rb

@@ -0,0 +1,73 @@
+module SpreeUberDirect
+  # Applies an Uber Direct delivery-status webhook event to the mapped
+  # Spree order — the Uber Direct analog of SpreeDoordash::DeliveryStatusMapper.
+  #
+  # Uber's own status vocabulary (confirmed directly against the real
+  # openapi.yaml shipped in uber/uber-direct-sdk, not assumed): `pending`,
+  # `pickup` / `pickup_complete`, `dropoff`, `delivered`, `canceled`,
+  # `returned`, plus `shopping_completed` for Courier Pick & Pack orders
+  # (not used by this extension's own flow, but present in the schema).
+  #
+  # No version/sequence field in Uber's payload either, same "don't gate on
+  # ordering" posture as both DoorDash's and Square's own status mappers —
+  # safety against duplicate processing comes entirely from WebhookEvent's
+  # idempotency key and from the state-guarded, idempotent operations
+  # below. Uber's own webhook ordering behavior across concurrent workers
+  # is unverified until actually observed live — flagged here rather than
+  # assumed, same precedent as every sibling status mapper's own comment.
+  class DeliveryStatusMapper
+    SHIP_STATUSES = %w[delivered].freeze
+    CANCEL_STATUSES = %w[canceled returned].freeze
+    # Real Uber lifecycle statuses with no Spree shipment_state equivalent
+    # — recorded as a friendly last_status label only, same "label vs.
+    # state transition" split as every sibling status mapper.
+    LABEL_ONLY_STATUSES = %w[pending pickup pickup_complete dropoff shopping_completed].freeze
+
+    def self.call(...) = new.call(...)
+
+    def call(payload)
+      mapping = SpreeUberDirect::DeliveryMapping.find_by(external_delivery_id: payload['delivery_id'])
+      return unless mapping
+
+      status = payload['status']
+      order = mapping.order
+      data = payload['data'] || {}
+      courier = data['courier'] || {}
+
+      case status
+      when *SHIP_STATUSES
+        ship!(order)
+      when *CANCEL_STATUSES
+        cancel!(order)
+      when *LABEL_ONLY_STATUSES
+        # No Spree-side transition — last_status below is the only effect.
+      end
+
+      # tracking_url isn't confirmed present on the webhook payload itself
+      # (the real Delivery Status Webhook reference documents delivery_id/
+      # status/data.courier/data.pickup/data.dropoff/batch_id/
+      # courier_imminent — tracking_url is a top-level field on the fuller
+      # CreateDeliveryResp/GetDeliveryResp REST shapes, which webhooks
+      # often trim). `.presence || mapping.tracking_url` means a missing
+      # field here just keeps whatever DeliveryDispatcher already recorded
+      # from the create_delivery response, rather than clobbering it with
+      # nil — safe either way, verify the real key at M4's live test.
+      mapping.update!(
+        last_status: status || mapping.last_status,
+        tracking_url: data['tracking_url'].presence || mapping.tracking_url,
+        courier_name: courier['name'].presence || mapping.courier_name,
+        courier_phone: courier['phone_number'].presence || mapping.courier_phone
+      )
+    end
+
+    private
+
+    def ship!(order)
+      order.shipments.each { |shipment| shipment.ship! if shipment.ready? }
+    end
+
+    def cancel!(order)
+      order.cancel! unless order.canceled?
+    end
+  end
+end