spree_api 6.0.0.rc3 → 6.0.0.rc4

data/app/controllers/spree/api/v3/admin/translations/batches_controller.rb

@@ -20,9 +20,10 @@ module Spree
           # authorization, and rendering.
           class BatchesController < Admin::BaseController
             # The batch spans heterogeneous resource types, so a single static
-            # scope can't gate it. We verify the API key holds the matching
-            # write_<resource> scope for EVERY entry (see require_batch_scopes!),
-            # which is stricter than the static check and keeps the audit model.
+            # scope can't gate it. We verify the caller holds the matching
+            # write_<resource> permission for EVERY entry (see
+            # require_batch_scopes!), which is stricter than the static check
+            # and keeps the audit model.
             skip_scope_check!
 
             request_params 'TranslationBatchParams' do |body|
@@ -63,19 +64,24 @@ module Spree
 
             private
 
-            # For API-key callers, require write_<resource> for every distinct
-            # resource type in the batch. JWT callers bypass (current_api_key is
-            # nil) and rely on the per-record authorize!(:update, record) above.
-            # Returns false (and renders 403) when a scope is missing.
+            # Require write_<resource> for every distinct resource type in the
+            # batch.
+            #
+            # Asked of the caller rather than of a secret key, because there
+            # are three principals and only one of them carries scopes on a
+            # key. An OAuth token resolves as a staff user with no key, so
+            # reading `current_api_key` here waved it through and the ceiling
+            # the merchant consented to went unenforced on the one write this
+            # controller performs — `holds_permission?` answers for all three.
+            #
+            # Returns false (and renders 403) when a permission is missing.
             def require_batch_scopes!(batch)
-              return true unless current_api_key
-
-              missing = batch.required_scopes.reject { |scope| current_api_key.has_scope?(scope) }
+              missing = batch.required_scopes.reject { |scope| holds_permission?(scope) }
               return true if missing.empty?
 
               render_error(
                 code: ERROR_CODES[:access_denied],
-                message: "API key lacks scope(s): #{missing.join(', ')}",
+                message: "You do not have permission to #{missing.map { |key| key.tr('_', ' ') }.to_sentence}.",
                 status: :forbidden,
                 details: { required_scopes: missing }
               )

data/app/controllers/spree/api/v3/oauth/authorizations_controller.rb

@@ -0,0 +1,61 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # The authorization endpoint a client sends the browser to.
+        #
+        # It renders nothing itself: consent belongs in the dashboard, where
+        # the merchant is already signed in and the screen matches the rest of
+        # the admin. This hands the request over with its parameters intact,
+        # and the dashboard reads them back through the JSON endpoints under
+        # /api/v3/admin/oauth.
+        #
+        # It is a real route rather than a skipped one because RFC 8414
+        # requires the metadata document to name an `authorization_endpoint`,
+        # and a consumer client refuses a document that advertises the
+        # authorization-code flow without one.
+        class AuthorizationsController < ActionController::Base
+          include Spree::Core::ControllerHelpers::Store
+
+          # The authorization endpoint is reached by a cross-site GET on
+          # purpose — a client sends the browser here — and forgery
+          # protection never applies to a GET, so `:exception` costs nothing
+          # while leaving the endpoint reachable. Nothing is granted here
+          # either way: the action only redirects, and consent is submitted
+          # to the Admin API under the merchant's own session.
+          protect_from_forgery with: :exception
+
+          # Carried across to the dashboard. Everything else is dropped, so a
+          # crafted link cannot smuggle extra parameters into the consent page.
+          FORWARDED_PARAMETERS = %w[
+            client_id redirect_uri response_type scope state
+            code_challenge code_challenge_method resource
+          ].freeze
+
+          def new
+            redirect_to consent_url, allow_other_host: true
+          end
+
+          private
+
+          # The client id names the store, not the hostname. An installation
+          # serving several stores from one API origin would otherwise send
+          # every consent to whichever store that host happens to resolve as,
+          # and the merchant would approve on the wrong one.
+          def consent_url
+            query = params.permit(*FORWARDED_PARAMETERS).to_h.compact_blank.to_query
+            base = Spree::Stores::DashboardUrl.call(store: consent_store)
+
+            "#{base}/#{consent_store.prefixed_id}/oauth/authorize?#{query}"
+          end
+
+          # @return [Spree::Store]
+          def consent_store
+            @consent_store ||=
+              Spree::OauthApplication.find_by(uid: params[:client_id])&.store || current_store
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/oauth/metadata_controller.rb

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # RFC 9728 Protected Resource Metadata — the one discovery document
+        # Doorkeeper does not ship (it serves RFC 8414 authorization-server
+        # metadata itself).
+        #
+        # A client reads this to learn which authorization server guards a
+        # resource. It is deliberately unauthenticated: a client has no
+        # credential at the point it asks.
+        class MetadataController < ActionController::API
+
+          # A public discovery document, read before any credential exists.
+          # The module has to be included because `ActionController::API`
+          # carries none of it; `:exception` is free here because the only
+          # action is a GET, which forgery protection never applies to.
+          include ActionController::RequestForgeryProtection
+          protect_from_forgery with: :exception
+
+          # The `resource` value must equal the URL the client was pointed at,
+          # path and all, or a consumer client refuses to continue — so it is
+          # built from this request's own origin rather than from anything
+          # configured elsewhere.
+          def show
+            resource = Spree::Api::Oauth.resource_identifier(params[:resource_key], request.base_url)
+            return head :not_found if resource.blank?
+
+            document = Spree::OauthProtectedResource.new(
+              resource: resource,
+              authorization_servers: [issuer],
+              # Exactly what the authorization server will accept.
+              #
+              # The spec tells a client with no scope challenge to request
+              # everything advertised here, and Doorkeeper refuses a request
+              # naming a scope it does not know — so advertising one more
+              # than it accepts turns every connection into "The requested
+              # scope is invalid".
+              scopes_supported: Spree::Api::Oauth.staff_scope_keys,
+              resource_documentation: 'https://spreecommerce.org/docs/developer/mcp/overview'
+            )
+
+            render json: Spree.api.admin_oauth_protected_resource_serializer.new(document).to_h
+          end
+
+          private
+
+          # The authorization server's own origin. This request reached it, so
+          # the origin it arrived on is the one a client can use.
+          def issuer
+            ::Doorkeeper.config.issuer.presence || request.base_url
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/oauth/server_metadata_controller.rb

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # RFC 8414 Authorization Server Metadata.
+        #
+        # The document itself is entirely Doorkeeper's. Only URL generation is
+        # Spree's problem: Doorkeeper asks for each endpoint by controller name
+        # anchored at the application root, and these routes are drawn inside
+        # an isolated engine, which cannot generate from such a name. The
+        # injected resolver answers from the engine's own router instead.
+        class ServerMetadataController < ::Doorkeeper::MetadataController
+          private
+
+          def metadata_response
+            @metadata_response ||= ::Doorkeeper::OAuth::MetadataResponse.new(
+              request.base_url,
+              ->(**arguments) { resolve_endpoint(**arguments) }
+            )
+          end
+
+          # Doorkeeper hands over a controller name anchored at the
+          # application root (`/api/v3/…`), while the engine's router knows
+          # its own controllers by their engine-qualified names
+          # (`spree/api/v3/…`). Doorkeeper's own controllers are already
+          # absolute and generate from the application router unchanged.
+          def resolve_endpoint(**arguments)
+            # Doorkeeper prepends a slash to whatever the route mapping
+            # held, so a name configured as "/doorkeeper/tokens" arrives
+            # doubled.
+            name = arguments[:controller].to_s.sub(%r{\A/+}, '')
+
+            if name.start_with?('doorkeeper/')
+              return Spree::Core::Engine.routes.url_for(
+                **arguments.except(:controller),
+                controller: "/#{name}",
+                only_path: false,
+                host: request.host,
+                protocol: request.protocol,
+                port: request.optional_port
+              )
+            end
+
+            Spree::Core::Engine.routes.url_for(
+              **arguments.except(:controller),
+              controller: "spree/#{name}",
+              only_path: false,
+              host: request.host,
+              protocol: request.protocol,
+              port: request.optional_port
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -268,6 +268,7 @@ module Spree
                     preload_associations_lazily.
                     ransack(ransack_params, auth_object: ransack_auth_object)
           result = @search.result(distinct: collection_distinct?)
+          result = result.with_translation_fallback_order if model_class.include?(Spree::TranslatableResource)
           pagy_options = { limit: limit, page: page }
           result = apply_collection_sort(result)
           @pagy, @collection = pagy(result, **pagy_options)

data/app/controllers/spree/api/v3/store/carts_controller.rb

@@ -123,7 +123,7 @@ module Spree
                 sweep_unavailable_coupon_code!
                 render_cart
               else
-                render_service_error(result.error, code: ERROR_CODES[:validation_error])
+                render_result_failure(result, code: ERROR_CODES[:validation_error])
               end
             end
           end
@@ -181,11 +181,10 @@ module Spree
             if result.success?
               @cart = result.value
               render_order
+            elsif result.error.to_s.present?
+              render_result_failure(result, code: ERROR_CODES[:cart_cannot_complete])
             else
-              render_service_error(
-                result.error.to_s.presence || 'Could not complete checkout',
-                code: ERROR_CODES[:cart_cannot_complete]
-              )
+              render_service_error('Could not complete checkout', code: ERROR_CODES[:cart_cannot_complete])
             end
           rescue ActiveRecord::RecordNotFound
             # Gateway-race retry with the id the client got back: the webhook

data/app/request_schemas/spree/api/v3/admin/email_template_preview_request_schema.rb

@@ -25,6 +25,10 @@ module Spree
             Spree::Emails::Branding::COLORS.each { |name| branding.attribute name, :string, nullable: true }
             branding.attribute :font, :string, nullable: true, choices: Spree::Emails::Branding::FONTS.keys
           end
+          attribute :mailer_logo_signed_id, :string,
+            nullable: true,
+            permit: false,
+            description: 'An unsaved email logo: the signed id of an uploaded image, or null to preview without one.'
         end
       end
     end

data/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb

@@ -3,6 +3,8 @@ module Spree
     module V3
       module Admin
         class FulfillmentSerializer < V3::FulfillmentSerializer
+          include Concerns::ExternalReferencesAttribute
+
           without_formatted_money
 
           # The Admin API has no guest gating — money fields inherited from the

data/app/serializers/spree/api/v3/admin/line_item_serializer.rb

@@ -5,6 +5,8 @@ module Spree
         # Admin API Line Item Serializer
         # Extends the store serializer with metadata visibility
         class LineItemSerializer < V3::LineItemSerializer
+          include Concerns::ExternalReferencesAttribute
+
           without_formatted_money
 
           # The Admin API has no guest gating — money fields inherited from the

data/app/serializers/spree/api/v3/admin/oauth_access_token_serializer.rb

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One person's live access through a connected client.
+        #
+        # The token itself is never serialized: it is a bearer credential, and
+        # the screen that lists connections only needs to say whose access it
+        # is and what that person approved.
+        class OauthAccessTokenSerializer < V3::BaseSerializer
+          typelize owner_id: [:string, nullable: true],
+                   owner_type: [:string, nullable: true],
+                   scopes: [:string, multi: true],
+                   expired: :boolean
+
+          attributes created_at: :iso8601
+
+          # Who connected, without expanding: the id and the kind, so a
+          # client can render a reference or follow it.
+          attribute :owner_id do |token|
+            token.resource_owner.try(:prefixed_id)
+          end
+
+          attribute :owner_type do |token|
+            Spree::Base.polymorphic_api_type(token.resource_owner_type)
+          end
+
+          # Who connected, as the record itself rather than a summary of it,
+          # so the dashboard shows a person the way it does everywhere else:
+          # a name over an email, with an avatar.
+          #
+          # The serializer follows the record's kind, because a grant's owner
+          # is polymorphic — an admin today, a customer when a storefront
+          # client needs one. Alba hands the proc the object for exactly this.
+          one :resource_owner,
+              key: :owner,
+              resource: proc { |owner| owner_serializer_for(owner) },
+              if: proc { expand?('owner') }
+
+          # @param owner [Object] the grant's resource owner
+          # @return [Class] the serializer for that kind of owner
+          def self.owner_serializer_for(owner)
+            case Spree::Base.polymorphic_api_type(owner.class.name)
+            when 'customer' then Spree.api.admin_customer_serializer
+            else Spree.api.admin_admin_user_serializer
+            end.to_s.constantize
+          end
+
+          # What this person approved, as permission keys.
+          attribute :scopes do |token|
+            token.scopes.to_a
+          end
+
+          # Whether the current access token has lapsed. The connection is
+          # still live — a refresh mints another — but a merchant reading the
+          # list deserves to know which agents hold access right now.
+          attribute :expired, &:expired?
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/oauth_application_serializer.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::OauthApplication}.
+        #
+        # Exposes `client_id` but never `secret`. The id is public by
+        # design — it is what a merchant pastes into a connector — while the
+        # secret is null here anyway, because every MCP client is a public
+        # client that proves itself with PKCE instead.
+        #
+        # `scopes` and `last_authorized_at` come from the live tokens rather than
+        # the registration — a client is registered once and granted per
+        # consent, so what the merchant approved lives on the token.
+        class OauthApplicationSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   client_id: :string,
+                   connected: :boolean,
+                   scopes: [:string, multi: true],
+                   last_authorized_at: [:string, nullable: true],
+                   authorized_at: [:string, nullable: true],
+                   authorized_by: [:string, nullable: true],
+                   redirect_uri: [:string, nullable: true]
+
+          attributes :name, :redirect_uri, created_at: :iso8601, updated_at: :iso8601
+
+          attribute :client_id, &:uid
+
+          # A registration nobody has connected and one whose access was
+          # revoked both carry no scopes, so the list alone cannot tell them
+          # apart — and a merchant pressing Revoke has to see that it worked.
+          attribute :connected, &:connected?
+
+          attribute :scopes do |application|
+            application.live_token_scopes
+          end
+
+          attribute :last_authorized_at do |application|
+            application.last_authorized_at&.iso8601
+          end
+
+          attribute :authorized_at do |application|
+            application.authorized_at&.iso8601
+          end
+
+          # Who allowed this, in the words a person is known by. On the screen
+          # that decides whether to revoke, the permission alone is half the
+          # story.
+          attribute :authorized_by do |application|
+            application.authorized_by.try(:actor_label)
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/oauth_consent_request_serializer.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::OauthConsentRequest}.
+        #
+        # Alba directly rather than through {BaseSerializer}: a consent
+        # request is a computed view with no id to expose, and inheriting one
+        # would put a null `id` in every response.
+        class OauthConsentRequestSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize client_name: :string,
+                   scopes: [:string, multi: true],
+                   grantable_scopes: [:string, multi: true],
+                   resource: [:string, nullable: true],
+                   redirect_uri: :string
+
+          attributes :client_name, :scopes, :grantable_scopes, :resource, :redirect_uri
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/oauth_protected_resource_serializer.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializer for {Spree::OauthProtectedResource}, the RFC 9728
+        # document a client reads to find the authorization server.
+        #
+        # Alba directly rather than through {BaseSerializer}: the document is
+        # a computed view with no id, and inheriting one would put a null
+        # `id` in a document the spec defines exactly.
+        class OauthProtectedResourceSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize resource: :string,
+                   authorization_servers: [:string, multi: true],
+                   scopes_supported: [:string, multi: true],
+                   bearer_methods_supported: [:string, multi: true],
+                   resource_documentation: :string
+
+          attributes :resource, :authorization_servers, :scopes_supported,
+                     :bearer_methods_supported, :resource_documentation
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/oauth_redirect_serializer.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::OauthRedirect}.
+        class OauthRedirectSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize redirect_uri: :string
+
+          attributes :redirect_uri
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/payment_capture_event_serializer.rb

@@ -0,0 +1,16 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::PaymentCaptureEvent — one capture of money a
+        # payment had authorized. A payment captured in parts has one per part.
+        class PaymentCaptureEventSerializer < V3::BaseSerializer
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          money_attributes :amount
+          typelize amount: [:string, nullable: false]
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/payment_serializer.rb

@@ -13,11 +13,18 @@ module Spree
                    order_id: [:string, nullable: true],
                    avs_response: [:string, nullable: true],
                    cvv_response_code: [:string, nullable: true],
-                   cvv_response_message: [:string, nullable: true]
+                   cvv_response_message: [:string, nullable: true],
+                   gateway_dashboard_payment_url: [:string, nullable: true],
+                   avs_risky: [:boolean, comment: 'Whether the card issuer reported that the billing address did not match.'],
+                   cvv_risky: [:boolean, comment: 'Whether the card issuer reported that the security code did not match.']
 
           attributes :metadata, :avs_response, :cvv_response_code, :cvv_response_message,
+                     :gateway_dashboard_payment_url,
                      created_at: :iso8601, updated_at: :iso8601
 
+          attribute(:avs_risky, &:is_avs_risky?)
+          attribute(:cvv_risky, &:is_cvv_risky?)
+
           money_attributes :captured_amount
           typelize captured_amount: [:string, nullable: false]
 
@@ -41,6 +48,10 @@ module Spree
             serializer.new(payment.source).to_h
           end
 
+          many :capture_events,
+               resource: proc { Spree.api.admin_payment_capture_event_serializer },
+               if: proc { expand?('capture_events') }
+
           one :order,
               resource: proc { Spree.api.admin_order_serializer },
               if: proc { expand?('order') }

data/app/serializers/spree/api/v3/admin/return_serializer.rb

@@ -5,6 +5,8 @@ module Spree
     module V3
       module Admin
         class ReturnSerializer < V3::ReturnSerializer
+          include Concerns::ExternalReferencesAttribute
+
           without_formatted_money
 
           typelize memo: [:string, nullable: true],

data/app/serializers/spree/api/v3/admin/tax_exemption_certificate_serializer.rb

@@ -5,7 +5,7 @@ module Spree
         # Admin-only: certificates are back-office evidence with no storefront
         # surface, so there is no store serializer to extend.
         class TaxExemptionCertificateSerializer < V3::BaseSerializer
-          typelize certificate_number: :string, reason_code: :string, status: [:string, enum: Spree::TaxExemptionCertificate.statuses, enum_type_name: 'TaxExemptionCertificateStatus'],
+          typelize certificate_number: :string, tax_exemption_reason_id: :string, status: [:string, enum: Spree::TaxExemptionCertificate.statuses, enum_type_name: 'TaxExemptionCertificateStatus'],
                    issuing_authority: [:string, nullable: true],
                    issued_at: [:string, nullable: true], expires_at: [:string, nullable: true],
                    verified_at: [:string, nullable: true],
@@ -17,11 +17,15 @@ module Spree
                    document_url: [:string, nullable: true],
                    metadata: 'Record<string, unknown> | null'
 
-          attributes :certificate_number, :reason_code, :status, :issuing_authority, :metadata,
+          attributes :certificate_number, :status, :issuing_authority, :metadata,
                      issued_at: :iso8601, expires_at: :iso8601, verified_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
-          prefixed_id_attributes :company
+          prefixed_id_attributes :company, :tax_exemption_reason
+
+          one :tax_exemption_reason,
+              resource: proc { Spree.api.admin_tax_exemption_reason_serializer },
+              if: proc { expand?('tax_exemption_reason') }
 
           # The jurisdiction the certificate holds in, in the same vocabulary the
           # tax lines use.

data/app/serializers/spree/api/v3/admin/tax_exemption_reason_serializer.rb

@@ -0,0 +1,20 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: exemption reasons are recorded on certificates, which are
+        # back-office evidence with no storefront surface.
+        class TaxExemptionReasonSerializer < V3::BaseSerializer
+          typelize name: :string, code: :string, active: :boolean, can_be_deleted: :boolean,
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :name, :code, :active, :metadata, created_at: :iso8601, updated_at: :iso8601
+
+          # Lets the dashboard hide destructive controls instead of offering a
+          # delete that the model will refuse.
+          attribute :can_be_deleted, &:can_be_deleted?
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb

@@ -6,7 +6,6 @@ module Spree
         # customer-facing. What the customer sees is the label on a tax line.
         class TaxRateSerializer < V3::BaseSerializer
           typelize name: :string,
-                   included_in_price: :boolean,
                    show_rate_in_label: :boolean,
                    tax_category_id: [:string, nullable: true],
                    store_id: [:string, nullable: true],
@@ -15,7 +14,7 @@ module Spree
                    metadata: ['Record<string, unknown>', nullable: true],
                    deleted_at: [:string, nullable: true]
 
-          attributes :name, :included_in_price, :show_rate_in_label, :metadata,
+          attributes :name, :show_rate_in_label, :metadata,
                      created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
 
           rate_attributes :rate, :rate_percent

data/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rb

@@ -32,8 +32,11 @@ module Spree
           # shipped still hold live credentials in the column. Null when the
           # caller cannot read the record the event is about.
           attribute :payload do |delivery|
+            # Fails closed: a reader that passes no gate gets nothing. The
+            # payload keeps the record body by design, so a caller holding
+            # `read_webhooks` alone must not see customer or payment data.
             visible = params[:payload_visible]
-            next nil if visible && !visible.call(delivery)
+            next nil unless visible&.call(delivery)
 
             Spree::WebhookPayloadRedaction.split(delivery.payload).first
           end

data/app/serializers/spree/api/v3/base_serializer.rb

@@ -224,6 +224,20 @@ module Spree
 
         private
 
+        # Adds the fields extensions registered for this class
+        # (Spree.api.extension_fields), read from the registry on every
+        # render as Spree.ransack is, so nothing is copied onto the class. A
+        # field never replaces an attribute the serializer writes itself.
+        def attributes_to_hash(object, hash)
+          super
+          Spree.api.extension_fields.for(self.class).each do |field|
+            next if @_attributes.key?(field.name)
+
+            set_key_and_attribute_body_from(object, field.name, field.reader, hash)
+          end
+          hash
+        end
+
         # Override Alba's fetch_attribute to automatically inject nested expand params
         # into child serializers via nested_params.
         # Uses `key` (the public API name, e.g. :categories) for expand lookup,