spree_doordash 0.1.0

data/config/initializers/spree_admin_doordash_navigation.rb

@@ -0,0 +1,27 @@
+Rails.application.config.after_initialize do
+  # Positions 68-70 — right after spree_square's own entries (65-67), so the
+  # two extensions' nav items sit together without colliding.
+  Spree.admin.navigation.sidebar.add :doordash_credential,
+    label: 'DoorDash Connection',
+    url: :admin_doordash_credential_path,
+    icon: 'plug',
+    position: 68,
+    active: -> { controller_name == 'doordash_credentials' },
+    if: -> { can?(:manage, SpreeDoordash::Credential) }
+
+  Spree.admin.navigation.sidebar.add :doordash_delivery_mappings,
+    label: 'DoorDash Deliveries',
+    url: :admin_doordash_delivery_mappings_path,
+    icon: 'truck',
+    position: 69,
+    active: -> { controller_name == 'doordash_delivery_mappings' },
+    if: -> { can?(:manage, SpreeDoordash::DeliveryMapping) }
+
+  Spree.admin.navigation.sidebar.add :doordash_webhook_events,
+    label: 'DoorDash Webhooks',
+    url: :admin_doordash_webhook_events_path,
+    icon: 'webhook',
+    position: 70,
+    active: -> { controller_name == 'doordash_webhook_events' },
+    if: -> { can?(:manage, SpreeDoordash::WebhookEvent) }
+end

data/config/initializers/spree_admin_doordash_tables.rb

@@ -0,0 +1,120 @@
+Rails.application.config.after_initialize do
+  # new_resource: false — read-only support/diagnostic tables (no
+  # `:new`/`:create` route exists; only: [:index] in config/routes.rb). The
+  # default (true) crashes with a routing error the moment the table is
+  # ever empty — found live, not from spree_admin's own docs — because the
+  # "no resource found" empty-state partial builds a `new_object_url` link
+  # unconditionally unless told not to. Same latent exposure exists in
+  # spree_square's own admin tables (they don't set this either); flagged
+  # separately rather than silently fixed here since that's a different gem.
+  Spree.admin.tables.register(:doordash_delivery_mappings, model_class: SpreeDoordash::DeliveryMapping,
+                                                             search_param: :external_delivery_id_cont, new_resource: false)
+
+  Spree.admin.tables.doordash_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.doordash_delivery_mappings.add :external_delivery_id,
+    label: :external_delivery_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.doordash_delivery_mappings.add :last_status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.doordash_delivery_mappings.add :tracking_url,
+    label: :tracking_url,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.doordash_delivery_mappings.add :dasher_name,
+    label: :dasher,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 50
+
+  Spree.admin.tables.doordash_delivery_mappings.add :dispatch_error,
+    label: :dispatch_error,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 60
+
+  Spree.admin.tables.doordash_delivery_mappings.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 70
+
+  Spree.admin.tables.register(:doordash_webhook_events, model_class: SpreeDoordash::WebhookEvent,
+                                                          search_param: :event_name_cont, new_resource: false)
+
+  Spree.admin.tables.doordash_webhook_events.add :external_delivery_id,
+    label: :external_delivery_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.doordash_webhook_events.add :event_name,
+    label: :event_name,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.doordash_webhook_events.add :status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.doordash_webhook_events.add :processed_at,
+    label: :processed_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.doordash_webhook_events.add :error_message,
+    label: :error_message,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 50
+
+  Spree.admin.tables.doordash_webhook_events.add :created_at,
+    label: :received_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 60
+end

data/config/initializers/spree_doordash_calculators.rb

@@ -0,0 +1,13 @@
+# Spree::ShippingMethod.calculators reads from a hardcoded list
+# (Rails.application.config.spree.calculators.shipping_methods) that
+# spree_core itself populates via its own `config.after_initialize` block
+# (lib/spree/core/engine.rb) — NOT auto-discovery, despite
+# Spree::ShippingCalculator subclasses otherwise looking like a
+# convention-based extension point. spree_core's block does a full array
+# *reassignment* (`= [...]`), so this has to run after it (append, don't
+# replace) or the addition gets silently wiped — safe here because
+# spree_doordash loads after spree/spree_core in the Gemfile, and Rails
+# runs `after_initialize` blocks in engine-load order.
+Rails.application.config.after_initialize do
+  Rails.application.config.spree.calculators.shipping_methods << Spree::Calculator::Shipping::DoordashQuote
+end

data/config/routes.rb

@@ -0,0 +1,25 @@
+Spree::Core::Engine.add_routes do
+  # `isolate_namespace Spree` in the engine means a normal `namespace
+  # :spree_doordash do ... end` block would resolve controllers as
+  # `Spree::SpreeDoordash::...` (the isolated module gets prepended). The
+  # leading `/` on the controller path makes it absolute, resolving to the
+  # actual `SpreeDoordash::WebhooksController` while keeping the URL prefix
+  # — same pattern as spree_square's webhook route.
+  post 'spree_doordash/webhooks/doordash', to: '/spree_doordash/webhooks#create'
+
+  namespace :admin do
+    # Plain credential-entry form (developer_id/key_id/signing_secret/webhook
+    # Basic Auth token), not an OAuth connect/disconnect flow — DoorDash has
+    # no refresh-token dance the way Square's OAuth does. Explicit named
+    # routes rather than `resource :doordash_credential` since there's no
+    # `new`/`create` — just show the one row for the current store and
+    # update it in place, `find_or_initialize_by(store:)` style.
+    get 'doordash_credential' => 'doordash_credentials#show', as: :doordash_credential
+    patch 'doordash_credential' => 'doordash_credentials#update'
+
+    # M5 — admin support/diagnostic pages, same read-only shape as
+    # spree_square's own (:index only).
+    resources :doordash_delivery_mappings, only: [:index]
+    resources :doordash_webhook_events, only: [:index]
+  end
+end

data/db/migrate/20260813000001_create_spree_doordash_credentials.rb

@@ -0,0 +1,28 @@
+class CreateSpreeDoordashCredentials < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_doordash_credentials do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: { unique: true }
+
+      # No OAuth/refresh flow — DoorDash Drive auth is a JWT signed
+      # client-side per request from a static access key (developer_id +
+      # key_id + signing_secret), created once in DoorDash's Developer
+      # Portal. All three encrypted at the application layer (see
+      # SpreeDoordash::Credential) even though developer_id/key_id aren't
+      # secret on their own, for consistency with signing_secret (which is).
+      t.text :developer_id
+      t.text :key_id
+      t.text :signing_secret
+
+      # The static Authorization header value configured as this store's
+      # webhook Basic Auth in DoorDash's dashboard — DoorDash echoes it back
+      # on every webhook call; SpreeDoordash::WebhookVerifier compares
+      # against this rather than an HMAC signature (DoorDash has no
+      # signing scheme the way Square does).
+      t.text :webhook_basic_auth_token
+
+      t.string :doordash_environment, null: false, default: 'sandbox'
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260813000002_create_spree_doordash_location_mappings.rb

@@ -0,0 +1,22 @@
+class CreateSpreeDoordashLocationMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_doordash_location_mappings do |t|
+      t.references :stock_location, null: false, foreign_key: { to_table: :spree_stock_locations }, index: { unique: true }
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+
+      # DoorDash's own Business/Store hierarchy — a Business owns multiple
+      # Stores, each a physical pickup location. Structural twin of
+      # SpreeSquare::LocationMapping (one row per external-system concept,
+      # unique index on the external id, no shared/polymorphic mapping
+      # table), except this one carries spree_store_id from day one —
+      # SpreeSquare's own mapping tables don't, which its README flags as a
+      # gap before real multi-store use. Cheap to not repeat here.
+      t.string :doordash_store_id, null: false
+      t.string :doordash_business_id
+
+      t.timestamps
+    end
+
+    add_index :spree_doordash_location_mappings, :doordash_store_id, unique: true
+  end
+end

data/db/migrate/20260813000003_create_spree_doordash_quote_mappings.rb

@@ -0,0 +1,47 @@
+class CreateSpreeDoordashQuoteMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_doordash_quote_mappings do |t|
+      t.references :order, null: false, foreign_key: { to_table: :spree_orders }, index: { unique: true }
+
+      # Ours — "spree-doordash-#{order.number}-#{random suffix}" (see
+      # SpreeDoordash::Quote; the random suffix is required — DoorDash
+      # rejects a second /drive/v2/quotes call reusing the same id with 409
+      # duplicate_delivery_id, confirmed against a real Sandbox re-quote).
+      # The join key DoorDash's own webhooks and the accept-quote/
+      # get-delivery calls all key off, same role as square_order_id plays
+      # for spree_square's OrderMapping.
+      t.string :external_delivery_id, null: false
+
+      t.integer :quoted_fee_cents
+      t.string :currency, default: 'USD'
+
+      # A quote is only valid 5 minutes (DoorDash's own limit) — checked by
+      # SpreeDoordash::DeliveryDispatcher (M4) to decide whether to accept
+      # this quote as-is or re-quote fresh before accepting.
+      t.datetime :quote_expires_at
+
+      t.datetime :pickup_time_estimated
+      t.datetime :dropoff_time_estimated
+
+      # Full response, for debugging/support visibility — same rationale as
+      # WebhookEvent#payload elsewhere in this codebase. jsonb on Postgres,
+      # json on SQLite — same `respond_to?(:jsonb)` branch spree_core's own
+      # migrations use (e.g. add_metadata_to_spree_orders), since SQLite (the
+      # dummy app used for specs) has no jsonb type at all. Plain `json`
+      # alone is wrong on Postgres specifically: it has no equality
+      # operator, which breaks the `SELECT DISTINCT` an admin table listing
+      # issues — confirmed live, not hypothetical (spree_host's own
+      # /admin/doordash_delivery_mappings page 500'd on exactly this before
+      # this fix).
+      if t.respond_to?(:jsonb)
+        t.jsonb :raw_response
+      else
+        t.json :raw_response
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_doordash_quote_mappings, :external_delivery_id, unique: true
+  end
+end

data/db/migrate/20260813180001_create_spree_doordash_delivery_mappings.rb

@@ -0,0 +1,47 @@
+class CreateSpreeDoordashDeliveryMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_doordash_delivery_mappings do |t|
+      t.references :order, null: false, foreign_key: { to_table: :spree_orders }, index: { unique: true }
+
+      # The external_delivery_id of the quote that was accepted — becomes
+      # the real delivery's own id once accept succeeds (DoorDash doesn't
+      # issue a separate "delivery id"; the quote's external_delivery_id is
+      # reused for the whole lifecycle, confirmed via
+      # POST /drive/v2/quotes/{external_delivery_id}/accept in DoorDash's
+      # own docs).
+      # Nullable, unlike QuoteMapping's own external_delivery_id — a
+      # DeliveryMapping row can legitimately exist before one is known (see
+      # DeliveryDispatchJob's dead-letter block: a dispatch can fail before
+      # ever reaching DoorDash's accept endpoint, e.g. no LocationMapping,
+      # matching SpreeSquare::OrderMapping#square_order_id's own nullable
+      # precedent for the same reason).
+      t.string :external_delivery_id
+
+      # DoorDash's own event_name vocabulary (DASHER_CONFIRMED,
+      # DASHER_PICKED_UP, DASHER_DROPPED_OFF, DELIVERY_CANCELLED, ...) —
+      # stored verbatim rather than mapped to a smaller enum, same
+      # last_status rationale as SpreeSquare::OrderMapping.
+      t.string :last_status
+
+      t.string :tracking_url
+      t.string :dasher_name
+      t.string :dasher_phone
+      t.text :dispatch_error
+
+      # Full response from the accept call, for debugging/support
+      # visibility — same rationale as QuoteMapping#raw_response (see that
+      # migration for why this is jsonb-on-Postgres/json-on-SQLite rather
+      # than plain json — confirmed live via a real 500 on this table's own
+      # admin listing page before the fix).
+      if t.respond_to?(:jsonb)
+        t.jsonb :raw_response
+      else
+        t.json :raw_response
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_doordash_delivery_mappings, :external_delivery_id, unique: true
+  end
+end

data/db/migrate/20260813180002_create_spree_doordash_webhook_events.rb

@@ -0,0 +1,46 @@
+class CreateSpreeDoordashWebhookEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_doordash_webhook_events do |t|
+      # DoorDash's webhook payloads carry no single event id of their own
+      # (unlike Square's payload['event_id']) — DoorDash "sends each webhook
+      # event up to 3 times" on anything other than a 200 (its own docs),
+      # so the same body can arrive more than once. The idempotency key is
+      # built from what IS in the payload: external_delivery_id + event_name
+      # (which event this is) + a digest of the raw body (guards against two
+      # genuinely different payloads that happened to share those two
+      # fields, e.g. a future field DoorDash adds that changes between
+      # otherwise-identical redeliveries).
+      t.string :external_delivery_id, null: false
+      t.string :event_name, null: false
+      t.string :payload_digest, null: false
+
+      # jsonb on Postgres, json on SQLite (the dummy app used for specs has
+      # no jsonb type at all) — see CreateSpreeDoordashQuoteMappings for the
+      # full rationale. Plain `json` alone is wrong on Postgres: it has no
+      # equality operator, which broke this exact table's own admin listing
+      # page (`SELECT DISTINCT`) — found live, not hypothetical.
+      #
+      # No `default: {}` on either branch — MySQL rejects a literal DEFAULT
+      # on BLOB/TEXT/GEOMETRY/JSON columns outright, which would cancel
+      # every migration after this one on that adapter (found live via this
+      # exact bug in the sibling spree_square gem's own MySQL CI job — not
+      # yet hit here since this gem has no MySQL CI, but the same migration
+      # would fail identically). Default now lives on the model instead
+      # (see WebhookEvent's own `attribute :payload, default: -> { {} }`).
+      if t.respond_to?(:jsonb)
+        t.jsonb :payload, null: false
+      else
+        t.json :payload, null: false
+      end
+      t.datetime :processed_at
+      t.string :status, null: false, default: 'pending' # pending, processed, failed
+      t.text :error_message
+
+      t.timestamps
+    end
+
+    add_index :spree_doordash_webhook_events, %i[external_delivery_id event_name payload_digest],
+              unique: true, name: 'index_spree_doordash_webhook_events_on_idempotency_key'
+    add_index :spree_doordash_webhook_events, :event_name
+  end
+end

data/lib/generators/spree_doordash/install/install_generator.rb

@@ -0,0 +1,20 @@
+module SpreeDoordash
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      class_option :migrate, type: :boolean, default: true
+
+      def add_migrations
+        run 'bundle exec rake railties:install:migrations FROM=spree_doordash'
+      end
+
+      def run_migrations
+        run_migrations = options[:migrate] || ['', 'y', 'Y'].include?(ask('Would you like to run the migrations now? [Y/n]'))
+        if run_migrations
+          run 'bin/rails db:migrate'
+        else
+          puts 'Skipping rails db:migrate, don\'t forget to run it!'
+        end
+      end
+    end
+  end
+end

data/lib/spree_doordash/configuration.rb

@@ -0,0 +1,8 @@
+module SpreeDoordash
+  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_doordash/engine.rb

@@ -0,0 +1,44 @@
+module SpreeDoordash
+  class Engine < Rails::Engine
+    require 'spree/core'
+    isolate_namespace Spree
+    engine_name 'spree_doordash'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer 'spree_doordash.environment', before: :load_config_initializers do |_app|
+      SpreeDoordash::Config = SpreeDoordash::Configuration.new
+    end
+
+    # Same ordering requirement as spree_square'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 spree_square already sets up (one
+    # encryption key set per Rails app, not per extension).
+    initializer 'spree_doordash.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 engine does —
+    # not needed until this extension actually has a decorator (M3+), kept
+    # here from the start so adding one later doesn't require remembering
+    # this step. See spree_square/lib/spree_square/engine.rb for the full
+    # rationale (Zeitwerk 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

data/lib/spree_doordash/factories.rb

@@ -0,0 +1,47 @@
+FactoryBot.define do
+  # Define your Spree extensions Factories within this file to enable applications, and other extensions to use and override them.
+  #
+  # Example adding this to your spec_helper will load these Factories for use:
+  # require 'spree_doordash/factories'
+
+  factory :doordash_credential, class: 'SpreeDoordash::Credential' do
+    store
+    developer_id { 'test-developer-id' }
+    key_id { 'test-key-id' }
+    # base64url, matching what SpreeDoordash::Client actually decodes with
+    # (Base64.urlsafe_decode64) — confirmed against a real DoorDash Sandbox
+    # 401 that standard base64 is the wrong alphabet.
+    signing_secret { Base64.urlsafe_encode64('test-signing-secret') }
+    doordash_environment { 'sandbox' }
+    webhook_basic_auth_token { 'Basic dGVzdDp0ZXN0' }
+  end
+
+  factory :doordash_location_mapping, class: 'SpreeDoordash::LocationMapping' do
+    stock_location
+    store
+    sequence(:doordash_store_id) { |i| "DDSTORE#{i}" }
+    doordash_business_id { 'default' }
+  end
+
+  factory :doordash_quote_mapping, class: 'SpreeDoordash::QuoteMapping' do
+    order
+    sequence(:external_delivery_id) { |i| "spree-doordash-R#{i}" }
+    quoted_fee_cents { 599 }
+    currency { 'USD' }
+    quote_expires_at { 5.minutes.from_now }
+  end
+
+  factory :doordash_delivery_mapping, class: 'SpreeDoordash::DeliveryMapping' do
+    order
+    sequence(:external_delivery_id) { |i| "spree-doordash-R#{i}-accepted" }
+    last_status { 'created' }
+    tracking_url { 'https://doordash.com/tracking?id=abc123' }
+  end
+
+  factory :doordash_webhook_event, class: 'SpreeDoordash::WebhookEvent' do
+    sequence(:external_delivery_id) { |i| "spree-doordash-R#{i}" }
+    event_name { 'DASHER_CONFIRMED' }
+    sequence(:payload_digest) { |i| "digest-#{i}" }
+    payload { { 'event_name' => 'DASHER_CONFIRMED', 'external_delivery_id' => 'spree-doordash-R1' } }
+  end
+end

data/lib/spree_doordash/version.rb

@@ -0,0 +1,7 @@
+module SpreeDoordash
+  VERSION = '0.1.0'.freeze
+
+  def gem_version
+    Gem::Version.new(VERSION)
+  end
+end

data/lib/spree_doordash.rb

@@ -0,0 +1,12 @@
+require 'spree'
+require 'spree_doordash/engine'
+require 'spree_doordash/version'
+require 'spree_doordash/configuration'
+
+module SpreeDoordash
+  mattr_accessor :queue
+
+  def self.queue
+    @@queue ||= Spree.queues.default
+  end
+end

data/lib/tasks/spree_doordash.rake

@@ -0,0 +1,94 @@
+namespace :spree_doordash do
+  # M1 verification: proves the JWT this extension signs is actually
+  # accepted by a real DoorDash Sandbox endpoint, not just shaped correctly
+  # per the documented recipe (already covered by spec/services/spree_doordash/client_spec.rb).
+  # Reads real credentials from .env.sandbox (gitignored, never committed —
+  # see that file's own comment) rather than the encrypted
+  # SpreeDoordash::Credential row, so this can run standalone against the
+  # gem's own dummy app without needing a full spree_host install first.
+  #
+  # Usage:
+  #   bin/rails spree_doordash:verify_connection
+  desc 'Verify DoorDash Sandbox credentials by requesting a real delivery quote'
+  task verify_connection: :environment do
+    env_path = File.expand_path('../../.env.sandbox', __dir__)
+    unless File.exist?(env_path)
+      abort "No .env.sandbox found at #{env_path} — see README.md's \"Connecting to DoorDash\" section."
+    end
+
+    require 'dotenv'
+    Dotenv.load(env_path)
+
+    %w[DOORDASH_DEVELOPER_ID DOORDASH_KEY_ID DOORDASH_SIGNING_SECRET].each do |key|
+      abort "#{key} is blank in .env.sandbox — fill in all three values first." if ENV[key].blank?
+    end
+
+    credential = SpreeDoordash::Credential.new(
+      developer_id: ENV['DOORDASH_DEVELOPER_ID'],
+      key_id: ENV['DOORDASH_KEY_ID'],
+      signing_secret: ENV['DOORDASH_SIGNING_SECRET'],
+      doordash_environment: 'sandbox'
+    )
+    client = SpreeDoordash::Client.new(credential: credential)
+
+    # A quote is the safest possible real call to verify against — DoorDash's
+    # own docs describe it as side-effect-light (no delivery is created,
+    # nothing to clean up afterward), and it's the same payload shape M2's
+    # SpreeDoordash::Quote service will build for real.
+    payload = {
+      external_delivery_id: "verify-#{SecureRandom.hex(4)}",
+      pickup_address: '901 Market Street 6th Floor San Francisco, CA 94103',
+      pickup_business_name: 'Spree Doordash Verification',
+      pickup_phone_number: '+16505555555',
+      dropoff_address: '901 Market Street 6th Floor San Francisco, CA 94103',
+      dropoff_phone_number: '+16505555555',
+      order_value: 1999
+    }
+
+    puts 'Requesting a Sandbox quote from DoorDash...'
+    begin
+      result = client.create_quote(payload)
+      puts '✅ Success — DoorDash accepted the JWT and returned a real quote:'
+      puts JSON.pretty_generate(result)
+    rescue SpreeDoordash::RequestError => e
+      puts "❌ DoorDash rejected the request (HTTP #{e.status}):"
+      puts JSON.pretty_generate(e.body)
+      exit 1
+    end
+  end
+
+  desc 'Map a Spree stock location to a DoorDash store (M5 — a rake task, not a full admin CRUD screen: restaurants have a handful of locations, not hundreds)'
+  task :map_location, %i[stock_location doordash_store_id doordash_business_id] => :environment do |_t, args|
+    unless args[:stock_location] && args[:doordash_store_id]
+      abort <<~USAGE
+        Usage:
+          bin/rails "spree_doordash:map_location[stock_location_id_or_name,doordash_store_id,doordash_business_id]"
+
+        doordash_business_id defaults to "default" — DoorDash Sandbox
+        auto-assigns a "default" business/store to every access key, so this
+        is normally all you need there. Only pass a real business id once
+        you've done full Business/Store API onboarding for production.
+      USAGE
+    end
+
+    stock_location = Spree::StockLocation.find_by(id: args[:stock_location]) ||
+                      Spree::StockLocation.find_by(name: args[:stock_location])
+    abort "No stock location found matching '#{args[:stock_location]}'" unless stock_location
+
+    # Spree::StockLocation has no store association of its own in this
+    # Spree version (confirmed by reading the model — stock locations
+    # aren't Store-scoped) — same single-default-store scope as the rest
+    # of this extension (see SpreeDoordash::Quote's own order.store ||
+    # Spree::Store.default).
+    store = Spree::Store.default
+    mapping = SpreeDoordash::LocationMapping.find_or_initialize_by(stock_location: stock_location)
+    mapping.assign_attributes(
+      store: store,
+      doordash_store_id: args[:doordash_store_id],
+      doordash_business_id: args[:doordash_business_id].presence || 'default'
+    )
+    mapping.save!
+
+    puts "✅ Mapped '#{stock_location.name}' -> DoorDash store #{mapping.doordash_store_id} (business #{mapping.doordash_business_id})"
+  end
+end