spree_uber_direct 0.1.4

data/app/services/spree_uber_direct/quote.rb

@@ -0,0 +1,97 @@
+module SpreeUberDirect
+  # Requests a live Uber Direct delivery-fee quote for an order — the
+  # storefront-facing half of this extension (called from
+  # Spree::Calculator::Shipping::UberDirectQuote during checkout, M3) and
+  # again at order.completed if the original quote expired (see
+  # DeliveryDispatcher, M4).
+  #
+  # `order.total` at whichever moment this is called is what's sent as
+  # manifest_total_value — Spree recalculates on every checkout step
+  # already, and Uber isn't in the money path (Spree's own payment method
+  # still charges the customer; Uber only uses this for delivery-fee/
+  # insurance math) — same rationale SpreeDoordash::Quote documents for its
+  # own order_value field.
+  class Quote
+    Result = Struct.new(:fee_cents, :currency, :external_quote_id, :expires_at, keyword_init: true)
+
+    def self.call(...) = new.call(...)
+
+    def call(order)
+      return nil unless order.ship_address
+      # Same real bug DoorDash's own Quote hit live: with no phone on the
+      # ship address, the request is doomed before it's even sent —
+      # Uber's own schema requires `^\+[0-9]+$` on both phone fields.
+      # Spree::Config[:address_requires_phone] (spree_host) should make
+      # this unreachable in the normal storefront checkout flow, but this
+      # guard stays as defense in depth for any other path that can create
+      # an order (admin, API, migrated data).
+      return nil if order.ship_address.phone.blank?
+
+      stock_location = pickup_location_for(order)
+      return nil unless stock_location&.phone.present?
+
+      client = SpreeUberDirect::Client.for_store(order.store || Spree::Store.default)
+      response = client.create_quote(build_payload(order, stock_location))
+      mapping = persist_quote!(order, response)
+
+      Result.new(
+        fee_cents: mapping.quoted_fee_cents,
+        currency: mapping.currency,
+        external_quote_id: mapping.external_quote_id,
+        expires_at: mapping.quote_expires_at
+      )
+    rescue SpreeUberDirect::Client::MissingCredentialsError, SpreeUberDirect::RequestError => e
+      # Unserviceable address, no credential connected, Uber-side rejection
+      # — none of these should ever raise into checkout. The calculator
+      # (M3) treats a nil Result as "this rate isn't available," Spree's
+      # normal shape for "can't quote this," same as
+      # Spree::Calculator::Shipping::DoordashQuote's own precedent.
+      Rails.logger.info("[SpreeUberDirect] quote skipped for order #{order.number}: #{e.message}")
+      nil
+    end
+
+    private
+
+    # Queried directly rather than `order.shipments.first` — same reasoning
+    # as SpreeDoordash::Quote#location_mapping_for: a shipment created by
+    # setting the FK directly (as spec factories and some checkout code
+    # paths do) doesn't invalidate an already-loaded `order` object's
+    # cached `shipments` association. No LocationMapping join needed here
+    # at all (unlike DoorDash) — Uber Direct has no separate store/location
+    # registration step; the pickup address is read straight off
+    # Spree::StockLocation.
+    def pickup_location_for(order)
+      Spree::Shipment.where(order_id: order.id).first&.stock_location ||
+        Spree::StockLocation.find_by(default: true)
+    end
+
+    def build_payload(order, stock_location)
+      {
+        pickup_address: AddressPayload.format_address(stock_location),
+        pickup_phone_number: AddressPayload.format_phone(stock_location.phone),
+        dropoff_address: AddressPayload.format_address(order.ship_address),
+        dropoff_phone_number: AddressPayload.format_phone(order.ship_address.phone),
+        manifest_total_value: (order.total * 100).to_i
+      }
+    end
+
+    def persist_quote!(order, response)
+      mapping = SpreeUberDirect::QuoteMapping.find_or_initialize_by(order: order)
+      mapping.update!(
+        external_quote_id: response['id'],
+        quoted_fee_cents: response['fee'],
+        currency: response['currency_type'] || 'USD',
+        quote_expires_at: parse_time(response['expires']),
+        duration_minutes_estimated: response['duration'],
+        pickup_duration_minutes_estimated: response['pickup_duration'],
+        dropoff_eta_estimated: parse_time(response['dropoff_eta']),
+        raw_response: response
+      )
+      mapping
+    end
+
+    def parse_time(value)
+      value.present? ? Time.iso8601(value) : nil
+    end
+  end
+end

data/app/services/spree_uber_direct/webhook_verifier.rb

@@ -0,0 +1,17 @@
+module SpreeUberDirect
+  # Verifies inbound Uber Direct webhooks. Architecturally different from
+  # SpreeDoordash::WebhookVerifier's Basic-Auth string-echo scheme: Uber
+  # Direct signs with a real HMAC — confirmed directly against
+  # developer.uber.com's webhook guide, not assumed: the `x-uber-signature`
+  # header is a lowercase-hex HMAC-SHA256 of the raw request body, keyed by
+  # a dedicated webhook signing secret configured per-webhook in the Direct
+  # dashboard (NOT the OAuth client_secret — a separate value entirely).
+  class WebhookVerifier
+    def self.valid?(signature_header:, raw_body:, signing_secret:)
+      return false if signature_header.blank? || signing_secret.blank?
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', signing_secret, raw_body.to_s)
+      ActiveSupport::SecurityUtils.secure_compare(signature_header, expected)
+    end
+  end
+end

data/app/subscribers/spree_uber_direct/order_completed_subscriber.rb

@@ -0,0 +1,30 @@
+module SpreeUberDirect
+  # Events & Subscribers is the preferred pattern for this kind of side
+  # effect (per this app's own CLAUDE.md conventions) — react to
+  # order.completed without touching Spree::Order itself. Mirrors
+  # SpreeDoordash::OrderCompletedSubscriber's shape exactly; independent of
+  # it and of spree_square's own subscriber on the same event — Spree's
+  # Events system already fires all three separately for every order
+  # (confirmed live earlier in this project: each shows up as its own
+  # Spree::Events::SubscriberJob entry for the same event).
+  class OrderCompletedSubscriber < Spree::Subscriber
+    subscribes_to 'order.completed'
+
+    def handle(event)
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
+      return unless order
+      return unless uber_direct_delivery?(order)
+
+      SpreeUberDirect::DeliveryDispatchJob.perform_later(order.id)
+    end
+
+    private
+
+    # Only dispatch orders actually fulfilled via an "Uber Direct Delivery"
+    # shipping method — pickup/DoorDash/other-carrier orders should never
+    # reach Uber Direct at all.
+    def uber_direct_delivery?(order)
+      order.shipments.any? { |shipment| shipment.shipping_method&.calculator.is_a?(Spree::Calculator::Shipping::UberDirectQuote) }
+    end
+  end
+end

data/app/views/spree/admin/uber_direct_credentials/show.html.erb

@@ -0,0 +1,55 @@
+<% content_for :page_title do %>
+  Uber Direct Connection
+<% end %>
+
+<div class="card w-full max-w-2xl">
+  <div class="card-header flex items-center justify-between <%= 'bg-green-50' if @credential.persisted? %>">
+    <span class="font-medium">Uber Direct</span>
+    <% if @credential.persisted? %>
+      <span class="inline-flex items-center text-xs font-medium text-green-700">
+        <span class="w-1.5 h-1.5 rounded-full bg-green-500 mr-1"></span>
+        Configured
+      </span>
+    <% else %>
+      <span class="inline-flex items-center text-xs font-medium text-gray-500">
+        <span class="w-1.5 h-1.5 rounded-full bg-gray-400 mr-1"></span>
+        Not configured
+      </span>
+    <% end %>
+  </div>
+
+  <%= form_for @credential, url: admin_uber_direct_credential_path, method: :patch,
+        as: :spree_uber_direct_credential, html: { class: 'card-body space-y-4' } do |f| %>
+    <p class="text-sm text-gray-600">
+      Create a Direct account at
+      <a href="https://direct.uber.com" target="_blank" rel="noopener" class="text-blue-600 underline">direct.uber.com</a>,
+      open the Developer tab under Management, and paste its three values below. Stored encrypted.
+    </p>
+
+    <div>
+      <%= f.label :uber_environment, 'Environment', class: 'label' %>
+      <%= f.select :uber_environment, %w[sandbox production], {}, class: 'select' %>
+    </div>
+    <div>
+      <%= f.label :client_id, 'Client ID', class: 'label' %>
+      <%= f.text_field :client_id, class: 'form-control' %>
+    </div>
+    <div>
+      <%= f.label :client_secret, 'Client Secret', class: 'label' %>
+      <%= f.password_field :client_secret, value: '', placeholder: (@credential.persisted? ? '••••••••  (leave blank to keep current)' : nil), class: 'form-control' %>
+    </div>
+    <div>
+      <%= f.label :customer_id, 'Customer ID', class: 'label' %>
+      <%= f.text_field :customer_id, class: 'form-control' %>
+    </div>
+    <div>
+      <%= f.label :webhook_signing_secret, 'Webhook Signing Key', class: 'label' %>
+      <%= f.password_field :webhook_signing_secret, value: '', placeholder: (@credential.webhook_signing_secret.present? ? '••••••••  (leave blank to keep current)' : 'from the webhook entry\'s Edit menu'), class: 'form-control' %>
+      <p class="text-xs text-gray-500 mt-1">The signing key shown when editing this store's webhook entry in the Direct dashboard — verifies the x-uber-signature header.</p>
+    </div>
+
+    <div class="card-footer -mx-4 -mb-4">
+      <%= f.submit 'Save', class: 'btn btn-primary' %>
+    </div>
+  <% end %>
+</div>

data/app/views/spree/admin/uber_direct_delivery_mappings/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Uber Direct Deliveries
+<% end %>
+
+<%= render_table @collection, :uber_direct_delivery_mappings %>

data/app/views/spree/admin/uber_direct_webhook_events/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Uber Direct Webhooks
+<% end %>
+
+<%= render_table @collection, :uber_direct_webhook_events %>

data/config/initializers/spree.rb

@@ -0,0 +1,14 @@
+# Registers this extension's event subscriber with Spree's event system.
+#
+# Spree::Subscriber's own docstring says subscribers are "automatically
+# registered during Rails initialization" — that's not what actually
+# happens in spree_core 5.6.1: Spree::Events.register_subscribers! only
+# ever iterates the explicit Spree.subscribers array. Without this file,
+# SpreeUberDirect::OrderCompletedSubscriber is a real, loadable class (so
+# specs calling it directly always pass) but is never actually wired to
+# the 'order.completed' event in the running app — this exact gap was
+# found live in spree_doordash before it carried this same fix. Mirrors
+# spree_doordash's and spree_square's own identical registration.
+Rails.application.config.after_initialize do
+  Spree.subscribers << SpreeUberDirect::OrderCompletedSubscriber
+end

data/config/initializers/spree_admin_uber_direct_navigation.rb

@@ -0,0 +1,30 @@
+Rails.application.config.after_initialize do
+  # Position 76 — confirmed the next free slot at time of writing (highest
+  # in use across every extension's own nav initializer was 75, spree_loyalty's
+  # admin_square_modifier_lists_navigation.rb before that at 73). 77-78 are
+  # the M5 Deliveries/Webhooks admin index pages below, mirroring
+  # spree_doordash's 68-70 layout (credential + 2 read-only tables).
+  Spree.admin.navigation.sidebar.add :uber_direct_credential,
+    label: 'Uber Direct Connection',
+    url: :admin_uber_direct_credential_path,
+    icon: 'plug',
+    position: 76,
+    active: -> { controller_name == 'uber_direct_credentials' },
+    if: -> { can?(:manage, SpreeUberDirect::Credential) }
+
+  Spree.admin.navigation.sidebar.add :uber_direct_delivery_mappings,
+    label: 'Uber Direct Deliveries',
+    url: :admin_uber_direct_delivery_mappings_path,
+    icon: 'truck',
+    position: 77,
+    active: -> { controller_name == 'uber_direct_delivery_mappings' },
+    if: -> { can?(:manage, SpreeUberDirect::DeliveryMapping) }
+
+  Spree.admin.navigation.sidebar.add :uber_direct_webhook_events,
+    label: 'Uber Direct Webhooks',
+    url: :admin_uber_direct_webhook_events_path,
+    icon: 'webhook',
+    position: 78,
+    active: -> { controller_name == 'uber_direct_webhook_events' },
+    if: -> { can?(:manage, SpreeUberDirect::WebhookEvent) }
+end

data/config/initializers/spree_admin_uber_direct_tables.rb

@@ -0,0 +1,101 @@
+Rails.application.config.after_initialize do
+  # new_resource: false is required — omitting it is a real bug both
+  # sibling extensions (spree_square, spree_doordash) hit and fixed on
+  # their first real Postgres run: without it, Spree.admin's table
+  # renderer assumes a "New" action exists and 500s. Avoided here by
+  # copying the already-fixed pattern instead of rediscovering it.
+  Spree.admin.tables.register(:uber_direct_delivery_mappings, model_class: SpreeUberDirect::DeliveryMapping,
+                                                                search_param: :external_delivery_id_cont, new_resource: false)
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :order_number,
+    label: :order,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 10,
+    method: ->(mapping) { mapping.order&.number }
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :external_delivery_id,
+    label: :external_delivery_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :last_status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :tracking_url,
+    label: :tracking_url,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :dispatch_error,
+    label: :dispatch_error,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 50
+
+  Spree.admin.tables.uber_direct_delivery_mappings.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 60
+
+  Spree.admin.tables.register(:uber_direct_webhook_events, model_class: SpreeUberDirect::WebhookEvent,
+                                                             search_param: :delivery_id_cont, new_resource: false)
+
+  Spree.admin.tables.uber_direct_webhook_events.add :delivery_id,
+    label: :delivery_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.uber_direct_webhook_events.add :status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.uber_direct_webhook_events.add :processing_status,
+    label: :processing_status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.uber_direct_webhook_events.add :error_message,
+    label: :error_message,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.uber_direct_webhook_events.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
+end

data/config/routes.rb

@@ -0,0 +1,22 @@
+Spree::Core::Engine.add_routes do
+  # Same absolute-path pattern as spree_doordash's own webhook route —
+  # isolate_namespace Spree means a plain `namespace :spree_uber_direct`
+  # would resolve to Spree::SpreeUberDirect::..., not the real
+  # SpreeUberDirect::WebhooksController; the leading `/` makes the
+  # controller path absolute while keeping the URL prefix.
+  post 'spree_uber_direct/webhooks/uber_direct', to: '/spree_uber_direct/webhooks#create'
+
+  namespace :admin do
+    # Plain credential-entry form (client_id/client_secret/customer_id/
+    # webhook signing key) — same explicit named-route shape as
+    # spree_doordash's own doordash_credential, not `resource :...` since
+    # there's no `new`/`create`, just `find_or_initialize_by(store:)`.
+    get 'uber_direct_credential' => 'uber_direct_credentials#show', as: :uber_direct_credential
+    patch 'uber_direct_credential' => 'uber_direct_credentials#update'
+
+    # M5 — admin support/diagnostic pages, same read-only shape as every
+    # sibling extension's own (:index only).
+    resources :uber_direct_delivery_mappings, only: [:index]
+    resources :uber_direct_webhook_events, only: [:index]
+  end
+end

data/db/migrate/20260821000001_create_spree_uber_direct_credentials.rb

@@ -0,0 +1,36 @@
+class CreateSpreeUberDirectCredentials < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_uber_direct_credentials do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: { unique: true }
+
+      # OAuth2 client_credentials — unlike spree_doordash's static
+      # developer_id/key_id/signing_secret (which sign a fresh JWT
+      # per-request, nothing to cache), Uber Direct issues an access token
+      # from these that genuinely outlives a single request. All three
+      # encrypted at the application layer regardless (see
+      # SpreeUberDirect::Credential), matching every credential this
+      # project stores.
+      t.text :client_id
+      t.text :client_secret
+      t.text :customer_id
+
+      # Cached OAuth access token + its real expiry, so SpreeUberDirect::Client
+      # doesn't fetch a fresh token on every call the way DoorDash's
+      # per-request JWT signing does — this is the one genuinely different
+      # piece from spree_doordash's Credential. access_token is encrypted;
+      # access_token_expires_at is a plain timestamp (not secret, needed for
+      # a cheap needs_refresh? comparison).
+      t.text :access_token
+      t.datetime :access_token_expires_at
+
+      # The dedicated webhook signing secret configured per-webhook in the
+      # Direct dashboard (Edit → signing key) — verifies the x-uber-signature
+      # header via HMAC-SHA256. Not the same value as client_secret.
+      t.text :webhook_signing_secret
+
+      t.string :uber_environment, null: false, default: 'sandbox'
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260821030001_create_spree_uber_direct_quote_mappings.rb

@@ -0,0 +1,48 @@
+class CreateSpreeUberDirectQuoteMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_uber_direct_quote_mappings do |t|
+      t.references :order, null: false, foreign_key: { to_table: :spree_orders }, index: { unique: true }
+
+      # Uber's own — returned as `id` on the DeliveryQuoteResp (always
+      # prefixed `dqt_`). Unlike SpreeDoordash::QuoteMapping's
+      # external_delivery_id (client-generated, sent in the *request*,
+      # which is why DoorDash needed a random suffix per attempt to dodge
+      # its own 409 duplicate_delivery_id), Uber mints this server-side and
+      # returns a fresh one on every /delivery_quotes call — no collision
+      # risk to guard against, re-quoting is always safe.
+      t.string :external_quote_id, null: false
+
+      t.integer :quoted_fee_cents
+      # currency_type (uppercase ISO), not the deprecated lowercase
+      # `currency` field DeliveryQuoteResp also returns — see
+      # SpreeUberDirect::Quote.
+      t.string :currency, default: 'USD'
+
+      # Uber returns its own real expiry (`expires`) on every quote — no
+      # need to hardcode a documented window the way DoorDash's 5-minute
+      # rule required (SpreeDoordash::QuoteMapping had no `expires` field
+      # to read at all).
+      t.datetime :quote_expires_at
+
+      # `duration`/`pickup_duration` on DeliveryQuoteResp are estimates in
+      # minutes, not timestamps — `dropoff_eta` is the one real (RFC 3339)
+      # timestamp field.
+      t.integer :duration_minutes_estimated
+      t.integer :pickup_duration_minutes_estimated
+      t.datetime :dropoff_eta_estimated
+
+      # Full response, for debugging/support visibility — same rationale
+      # (and same jsonb/json Postgres-vs-SQLite branch) as
+      # SpreeDoordash::QuoteMapping#raw_response.
+      if t.respond_to?(:jsonb)
+        t.jsonb :raw_response
+      else
+        t.json :raw_response
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_uber_direct_quote_mappings, :external_quote_id, unique: true
+  end
+end

data/db/migrate/20260821040001_create_spree_uber_direct_delivery_mappings.rb

@@ -0,0 +1,42 @@
+class CreateSpreeUberDirectDeliveryMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_uber_direct_delivery_mappings do |t|
+      t.references :order, null: false, foreign_key: { to_table: :spree_orders }, index: { unique: true }
+
+      # Uber's own delivery id (prefixed `del_`), returned by
+      # POST /deliveries once the quote is accepted — a genuinely separate
+      # id from the quote's own `dqt_`-prefixed id, unlike DoorDash (which
+      # reuses the accepted quote's external_delivery_id as the delivery's
+      # id for its whole lifecycle). Nullable for the same reason
+      # SpreeDoordash::DeliveryMapping's own external_delivery_id is: a
+      # dispatch can fail before Uber ever returns one (e.g. the
+      # underlying quote itself failed) — DeliveryDispatchJob's dead-letter
+      # block does find_or_initialize_by(order:).mark_failed!(error) on
+      # exactly that path.
+      t.string :external_delivery_id
+
+      # Uber's own status vocabulary (pending, pickup, pickup_complete,
+      # dropoff, delivered, canceled, returned, shopping_completed) —
+      # stored verbatim, same last_status rationale as every sibling
+      # mapping table in this project.
+      t.string :last_status
+
+      t.string :tracking_url
+      t.string :courier_name
+      t.string :courier_phone
+      t.text :dispatch_error
+
+      # Full response, for debugging/support visibility — same
+      # jsonb/json Postgres-vs-SQLite branch as every sibling migration.
+      if t.respond_to?(:jsonb)
+        t.jsonb :raw_response
+      else
+        t.json :raw_response
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_uber_direct_delivery_mappings, :external_delivery_id, unique: true
+  end
+end

data/db/migrate/20260821040002_create_spree_uber_direct_webhook_events.rb

@@ -0,0 +1,37 @@
+class CreateSpreeUberDirectWebhookEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_uber_direct_webhook_events do |t|
+      # Uber Direct's webhook payload has a single event `kind`
+      # (event.delivery_status for every status change — confirmed
+      # directly against the real webhook reference, not assumed) rather
+      # than a distinct event id, same shape gap DoorDash's own webhooks
+      # have. The idempotency key is built the identical way
+      # SpreeDoordash::WebhookEvent's own migration explains: delivery_id +
+      # status (which transition this is) + a digest of the raw body
+      # (guards against two genuinely different payloads sharing those two
+      # fields).
+      t.string :delivery_id, null: false
+      t.string :status, null: false
+      t.string :payload_digest, null: false
+
+      # jsonb on Postgres, json on SQLite — same rationale (and the same
+      # real Postgres-only `SELECT DISTINCT` admin-listing bug this
+      # pattern was already found live for) as every sibling migration in
+      # this project.
+      if t.respond_to?(:jsonb)
+        t.jsonb :payload, null: false
+      else
+        t.json :payload, null: false
+      end
+      t.datetime :processed_at
+      t.string :processing_status, null: false, default: 'pending' # pending, processed, failed
+      t.text :error_message
+
+      t.timestamps
+    end
+
+    add_index :spree_uber_direct_webhook_events, %i[delivery_id status payload_digest],
+              unique: true, name: 'index_spree_uber_direct_webhook_events_on_idempotency_key'
+    add_index :spree_uber_direct_webhook_events, :status
+  end
+end

data/db/migrate/20260823010001_create_spree_uber_direct_refund_events.rb

@@ -0,0 +1,39 @@
+class CreateSpreeUberDirectRefundEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_uber_direct_refund_events do |t|
+      # `event.refund_request` webhooks carry no top-level `status` field
+      # (see WebhooksController's own comment on that), so this is
+      # deliberately a separate, simpler table rather than a WebhookEvent
+      # row with a null status — the whole point is that refund data has
+      # nowhere else to land and can't be recovered later if dropped.
+      # Nothing here processes it yet: this is just a durable record of
+      # what Uber actually sent (data.id, currency_code,
+      # total_partner_refund, total_uber_refund, refund_fees,
+      # refund_order_items — all captured for free inside `payload`), for
+      # whenever refund reconciliation admin UI or accounting sync
+      # actually needs it.
+      t.string :delivery_id, null: false
+
+      # Same idempotency-key shape as WebhookEvent (delivery_id + a digest
+      # of the raw body) — Uber's webhook delivery is at-least-once, and
+      # without this a retried refund_request would insert a second row
+      # for the identical refund.
+      t.string :payload_digest, null: false
+
+      # jsonb on Postgres, json on SQLite — same rationale as every
+      # sibling migration in this project (see WebhookEvent's own
+      # migration comment for the Postgres-only `SELECT DISTINCT` bug this
+      # pattern already avoided once).
+      if t.respond_to?(:jsonb)
+        t.jsonb :payload, null: false
+      else
+        t.json :payload, null: false
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_uber_direct_refund_events, %i[delivery_id payload_digest],
+              unique: true, name: 'index_spree_uber_direct_refund_events_on_idempotency_key'
+  end
+end

data/lib/spree_uber_direct/configuration.rb

@@ -0,0 +1,8 @@
+module SpreeUberDirect
+  class Configuration < Spree::Preferences::Configuration
+    # Some example preferences are shown below, for more information visit:
+    # https://docs.spreecommerce.org/developer/contributing/creating-an-extension
+
+    # preference :enabled, :boolean, default: true
+  end
+end

data/lib/spree_uber_direct/engine.rb

@@ -0,0 +1,45 @@
+module SpreeUberDirect
+  class Engine < Rails::Engine
+    require 'spree/core'
+    isolate_namespace Spree
+    engine_name 'spree_uber_direct'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer 'spree_uber_direct.environment', before: :load_config_initializers do |_app|
+      SpreeUberDirect::Config = SpreeUberDirect::Configuration.new
+    end
+
+    # Same ordering requirement as spree_square's and spree_doordash's
+    # identical initializer — must run before Active Record's own
+    # "active_record_encryption.configuration" initializer reads
+    # config.active_record.encryption, or Credential's encrypted columns
+    # fail with "Missing Active Record encryption credential" the first
+    # time they're touched. Shares the same ACTIVE_RECORD_ENCRYPTION_* keys
+    # the sibling extensions already set up (one encryption key set per
+    # Rails app, not per extension).
+    initializer 'spree_uber_direct.active_record_encryption', before: 'active_record_encryption.configuration' do |app|
+      next if ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY'].blank?
+
+      app.config.active_record.encryption.primary_key = ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY']
+      app.config.active_record.encryption.deterministic_key = ENV['ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY']
+      app.config.active_record.encryption.key_derivation_salt = ENV['ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT']
+    end
+
+    # Force-loads decorator files the same way spree_square's and
+    # spree_doordash's engines do — not needed until this extension
+    # actually has a decorator, kept here from the start so adding one
+    # later doesn't require remembering this step. Zeitwerk's lazy
+    # autoloading never triggers a decorator file's `prepend` line
+    # otherwise.
+    def self.activate
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.application.config.cache_classes ? require(c) : load(c)
+      end
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+  end
+end