spree_api 5.6.1 → 6.0.0.beta2

data/app/controllers/spree/api/v3/admin/concerns/external_references.rb

@@ -0,0 +1,166 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Concerns
+          # Lets a connector address records by the identity its own system
+          # knows, rather than by Spree's prefixed id.
+          #
+          # Two halves:
+          #
+          # * **write** — `external_references` in the payload records the
+          #   caller's key for the record it just wrote. Systems the payload
+          #   does not mention keep their references, so a PIM sync never
+          #   erases the ERP's key.
+          # * **read** — a member path may carry `external:<system>:<id>` in
+          #   place of the prefixed id, so a connector that only ever learned
+          #   the ERP's key can read, update and delete without first asking
+          #   Spree for its id.
+          #
+          # A create carrying an `external_references` entry that already
+          # matches a record **updates that record** instead of failing on the
+          # unique index — the upsert a nightly feed needs, since a feed cannot
+          # know whether Spree has seen a row before.
+          #
+          # The write hangs off +serialize_resource+ rather than overriding
+          # +create+/+update+: several admin controllers implement those
+          # themselves (products and orders route through workflows), and every
+          # one of them reaches serialization with the saved record. Rendering
+          # is the one place they all agree on.
+          module ExternalReferences
+            extend ActiveSupport::Concern
+
+            # Raised when a payload's external id already names a different
+            # record in this store.
+            class ConflictingReference < StandardError; end
+
+            included do
+              before_action :update_instead_when_external_id_known, only: :create
+
+              rescue_from ConflictingReference do |error|
+                render_error(
+                  code: 'conflicting_external_reference',
+                  message: error.message,
+                  status: :unprocessable_content
+                )
+              end
+            end
+
+            protected
+
+            # A create whose payload names an external id Spree already knows
+            # becomes an update of that record. Without this a re-run of the
+            # same feed 422s on the unique index — after persisting a duplicate
+            # on controllers whose +create+ builds through a workflow rather
+            # than +build_resource+ — which reads to a connector author as "the
+            # sync is broken" rather than "already imported".
+            #
+            # A before_action rather than a +build_resource+ override because
+            # products and orders create through workflows and never call
+            # +build_resource+; rendering from here halts the action, so every
+            # controller's +create+ gets the same upsert.
+            #
+            # Dispatches into the controller's own +update+, which is the only
+            # action that knows how to write that resource (orders update
+            # through a service, products through a workflow).
+            #
+            # A controller whose two actions permit different keys would
+            # silently drop a payload key the update action does not name.
+            # +normalize_upsert_params!+ is where such a controller reconciles
+            # them, and where one prepares state its update path expects; the
+            # default is a no-op.
+            def update_instead_when_external_id_known
+              existing = find_by_external_reference_params
+              return if existing.blank?
+
+              @resource = existing
+              authorize_resource!(@resource, :update)
+              normalize_upsert_params!
+              update
+            end
+
+            # Rewrites create-shaped keys into the ones this controller's
+            # +update+ accepts. A no-op unless the two actions disagree.
+            def normalize_upsert_params!; end
+
+            # `external_references` lives in its own table, so it must not
+            # reach the model's attribute writer.
+            def permitted_params
+              super.except(:external_references)
+            end
+
+            # Accepts both the `{ system => external_id }` map the serializer
+            # renders — so a client can send back exactly what it read — and
+            # the `[{ system:, external_id: }]` list a feed finds natural.
+            def external_reference_params
+              return @external_reference_params if defined?(@external_reference_params)
+
+              raw = params[:external_references]
+              raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+              @external_reference_params = Spree::ExternalReference.normalize_references(raw)
+            end
+
+            # A member path may address the record by an external identity
+            # instead of its prefixed id, written `external:<system>:<id>` —
+            # e.g. `/admin/products/external:erp:MAT-100`. A connector that
+            # only ever learned the ERP's key can then read, update and delete
+            # without first querying Spree for its id.
+            #
+            # It resolves through the controller's own +scope+, so store
+            # scoping and authorization are exactly as they are for a prefixed
+            # id, and a key belonging to another store is a 404.
+            EXTERNAL_ID_PREFIX = 'external:'.freeze
+
+            def find_resource
+              return super unless external_id_lookup?
+
+              _prefix, system, external_id = params[:id].split(':', 3)
+              scope.with_external_id(system, external_id).take!
+            end
+
+            def external_id_lookup?
+              params[:id].to_s.start_with?(EXTERNAL_ID_PREFIX) &&
+                model_class.respond_to?(:with_external_id) &&
+                params[:id].to_s.split(':', 3).length == 3
+            end
+
+            def find_by_external_reference_params
+              return if external_reference_params.blank?
+              return unless model_class.respond_to?(:with_external_id)
+
+              external_reference_params.each do |entry|
+                match = scope.with_external_id(entry[:system], entry[:external_id]).take
+                return match if match.present?
+              end
+
+              nil
+            end
+
+            def serialize_resource(resource, **options)
+              write_external_references(resource)
+              super
+            end
+
+            def write_external_references(resource)
+              # Cheapest guard first: a GET must not even parse the params.
+              return unless request.post? || request.patch? || request.put?
+              return if external_reference_params.blank?
+              return unless resource.respond_to?(:assign_external_references)
+              return unless resource.persisted?
+
+              # No reload needed: set_external_id resets the association, so
+              # the serializer's read fetches the fresh rows.
+              resource.assign_external_references(external_reference_params)
+            rescue ActiveRecord::RecordInvalid => e
+              # The key already names a different record in this store. The
+              # resource itself is written by now, so this reports what could
+              # not be recorded rather than pretending the write failed.
+              raise Spree::Api::V3::Admin::Concerns::ExternalReferences::ConflictingReference,
+                    e.record.errors.full_messages.to_sentence
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/consent_records_controller.rb

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The evidence trail behind a customer's consent state — what was
+        # agreed, when, from where, and which document version was shown.
+        #
+        # Read-only. GDPR Art. 7(1) asks the controller to demonstrate that
+        # consent was given, and a record an operator can edit demonstrates
+        # nothing.
+        class ConsentRecordsController < ResourceController
+          scoped_resource :customers
+
+          protected
+
+          def model_class
+            Spree::ConsentRecord
+          end
+
+          def serializer_class
+            Spree.api.admin_consent_record_serializer
+          end
+
+          def scope
+            super.recent_first
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/countries_controller.rb

@@ -3,13 +3,21 @@ module Spree
     module V3
       module Admin
         class CountriesController < ResourceController
-          scoped_resource :settings
+          # Public reference data (the storefront serves the same list) — exempt
+          # from the key gate like `/tags`, so address forms work for any staff
+          # member or key. CanCanCan still applies for JWT principals via the
+          # staff baseline's Country read grant.
+          skip_scope_check!
 
           # Override base index to skip pagination — there are ~250 countries
           # and address-form dropdowns need them all at once. Pagy's global
           # max_limit (100) prevents using the paginated path for this.
+          #
+          # Countries are reference data rather than records, so this reads
+          # from the registry and needs no authorization beyond the admin
+          # credential the base controller already checked: the list is the
+          # same for every store and carries nothing store-specific.
           def index
-            authorize!(:read, model_class)
             @collection = scope
             render json: { data: serialize_collection(@collection), meta: { count: @collection.size } }
           end
@@ -25,11 +33,11 @@ module Spree
           end
 
           def scope
-            Spree::Country.all.order(:name).preload_associations_lazily
+            Spree::Country.all.sort_by(&:name)
           end
 
           def find_resource
-            scope.find_by!(iso: params[:id].upcase)
+            Spree::Country.find_by_iso!(params[:id])
           end
         end
       end

data/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb

@@ -10,6 +10,19 @@ module Spree
         class CustomFieldDefinitionsController < ResourceController
           scoped_resource :settings
 
+          # GET /api/v3/admin/custom_field_definitions/resource_types
+          #
+          # What a definition can be attached to, from
+          # `Spree.custom_fields.enabled_resources` — so a resource an
+          # extension registers is offered without the dashboard shipping a
+          # new list, and a merchant is never shown a type the server would
+          # then refuse.
+          def resource_types
+            authorize! :create, model_class
+
+            render json: { data: Spree::CustomFieldDefinition.enabled_resource_types }
+          end
+
           protected
 
           def model_class
@@ -20,14 +33,16 @@ module Spree
             Spree.api.admin_custom_field_definition_serializer
           end
 
-          # `label`, `field_type`, `storefront_visible` are model-side aliases
-          # (alias_attribute / accessors) on Spree::CustomFieldDefinition. The
-          # API → DB column rename lands in 6.0 and this controller stays flat.
           def permitted_params
-            params.permit(:namespace, :key, :label, :field_type,
+            params.permit(*model_additional_permitted_attributes, :namespace, :key, :label, :field_type,
                           :resource_type, :storefront_visible,
                           :searchable, :sortable)
           end
+
+          # Pure registry discovery — maps to the read scope.
+          def read_actions
+            super + %w[resource_types]
+          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/custom_fields_controller.rb

@@ -9,7 +9,7 @@ module Spree
         class CustomFieldsController < ResourceController
           # POST /api/v3/admin/<parent>/<parent_id>/custom_fields
           def create
-            @resource = @parent.metafields.new(permitted_params)
+            @resource = @parent.custom_fields.new(permitted_params)
             authorize_resource!(@resource, :create)
 
             if @resource.save
@@ -44,7 +44,7 @@ module Spree
           end
 
           def parent_association
-            :metafields
+            :custom_fields
           end
 
           def set_parent
@@ -86,7 +86,7 @@ module Spree
           # `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
           # AR resolves the prefixed-ID and the alias to the canonical FK on assign.
           def permitted_params
-            params.permit(:custom_field_definition_id, :value)
+            params.permit(*model_additional_permitted_attributes, :custom_field_definition_id, :value)
           end
 
           def update_permitted_params
@@ -104,9 +104,9 @@ module Spree
           # and `'category'` because the routes expose taxons as categories
           # (5.5 rename) while the model's element is still `'taxon'`.
           def parent_route_map
-            @parent_route_map ||= Spree.metafields.enabled_resources.each_with_object({}) do |klass, m|
+            @parent_route_map ||= Spree.custom_fields.enabled_resources.each_with_object({}) do |klass, m|
               m[klass.model_name.element.to_s] = klass.name
-            end.merge('customer' => Spree.user_class.name, 'category' => 'Spree::Taxon')
+            end.merge('customer' => Spree.customer_class.name, 'category' => 'Spree::Category')
           end
 
           # Returns the first segment whose `<segment>_id` is present in params,

data/app/controllers/spree/api/v3/admin/customer_groups_controller.rb

@@ -22,7 +22,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:name, :description, customer_ids: [])
+            params.permit(*model_additional_permitted_attributes, :name, :description, customer_ids: [])
           end
         end
       end

data/app/controllers/spree/api/v3/admin/customers/addresses_controller.rb

@@ -7,7 +7,7 @@ module Spree
 
             # POST /api/v3/admin/customers/:customer_id/addresses
             def create
-              authorize_resource!(Spree::Address.new(user_id: @parent.id), :create)
+              authorize_resource!(Spree::Address.new(owner: @parent), :create)
 
               result = Spree.address_create_service.call(
                 address_params: address_attrs,
@@ -68,18 +68,18 @@ module Spree
               params.permit(
                 :firstname, :lastname, :first_name, :last_name,
                 :address1, :address2, :city,
-                :country_iso, :state_abbr, :country_id, :state_id,
+                :country_code, :state_code,
                 :zipcode, :postal_code, :phone, :alternative_phone,
                 :state_name, :company, :label, :quick_checkout
               )
             end
 
             def default_billing_flag
-              ActiveModel::Type::Boolean.new.cast(params[:is_default_billing])
+              params[:is_default_billing].to_b
             end
 
             def default_shipping_flag
-              ActiveModel::Type::Boolean.new.cast(params[:is_default_shipping])
+              params[:is_default_shipping].to_b
             end
           end
         end

data/app/controllers/spree/api/v3/admin/customers/base_controller.rb

@@ -21,7 +21,7 @@ module Spree
             # global in Spree (`User.for_store` is a no-op), so the ability is
             # the only boundary here.
             def set_parent
-              @parent = Spree.user_class.
+              @parent = Spree.customer_class.
                         accessible_by(current_ability, parent_ability_action).
                         find_by_prefix_id!(params[:customer_id])
             end

data/app/controllers/spree/api/v3/admin/customers/store_credits_controller.rb

@@ -14,7 +14,6 @@ module Spree
               @resource = @parent.store_credits.new(create_attrs)
               @resource.created_by = try_spree_current_user
               @resource.store ||= current_store
-              @resource.category ||= Spree::StoreCreditCategory.first
               authorize_resource!(@resource, :create)
 
               if @resource.save
@@ -84,11 +83,11 @@ module Spree
             private
 
             def create_attrs
-              params.permit(:amount, :currency, :category_id, :memo).to_h
+              params.permit(:amount, :currency, :memo).to_h
             end
 
             def update_attrs
-              params.permit(:memo, :category_id, :amount).to_h
+              params.permit(:memo, :amount).to_h
             end
           end
         end

data/app/controllers/spree/api/v3/admin/customers/tax_identifiers_controller.rb

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class TaxIdentifiersController < BaseController
+            scoped_resource :customers
+
+            include Spree::Api::V3::TaxIdentifierValidation
+
+            # Re-declaring the filter replaces the inherited options, so the
+            # standard actions have to be listed alongside the custom one.
+            before_action :set_resource, only: [:show, :update, :destroy, :validate]
+
+            # POST /api/v3/admin/customers/:customer_id/tax_identifiers/:id/validate
+            #
+            # Re-asks the registry. Manual because a registry answers only "valid
+            # now": a number verified last year may have been deregistered since,
+            # and staff need a way to check without editing the row.
+
+            protected
+
+            def model_class
+              Spree::TaxIdentifier
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_identifier_serializer
+            end
+
+            def scope
+              @parent.tax_identifiers
+            end
+
+            def permitted_params
+              params.permit(:kind, :value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/customers_controller.rb

@@ -7,17 +7,18 @@ module Spree
 
           scoped_resource :customers
 
+          # Re-declaring a `before_action` for the same method REPLACES the
+          # inherited registration rather than adding to it, so the inherited
+          # actions have to be repeated here or show/update/destroy silently
+          # lose their record.
+          before_action :set_resource, only: [:show, :update, :destroy, :export, :anonymize]
           before_action :require_ids!, only: [:bulk_add_to_groups, :bulk_remove_from_groups]
 
           def create
-            @resource = Spree.user_class.new(permitted_params)
-            # Admin-created customers don't pick a password upfront — they
-            # claim the account via password reset later.
-            # `Spree::UserMethods` exposes `skip_password_validation` so
-            # Devise's `:validatable` lets a nil credential through on this
-            # code path. Storefront registration never sets the flag, so
-            # customer self-signup still requires a password.
-            @resource.skip_password_validation = true if @resource.password.blank?
+            @resource = Spree.customer_class.new(permitted_params)
+            # Admin-created customers may be created without a password; they
+            # claim the account via password reset later (the model does not
+            # enforce password presence).
             authorize!(:create, @resource)
 
             if @resource.save
@@ -30,6 +31,12 @@ module Spree
           def update
             authorize_resource!(@resource)
 
+            # A staff member is making this change, so a marketing-consent flip
+            # is recorded as theirs. Left unset it would stamp `account`, which
+            # says the person changed their own permission — evidence of a
+            # gesture they never made.
+            @resource.consent_source = Spree::ConsentRecord::ADMIN
+
             if @resource.update(permitted_params)
               render json: serialize_resource(@resource.reload)
             else
@@ -49,6 +56,88 @@ module Spree
             )
           end
 
+          # POST /api/v3/admin/customers/:id/anonymize
+          #
+          # Erases the customer's personal data while leaving the financial
+          # record intact. This is what a merchant runs when an erasure request
+          # arrives by email — which is how most of them arrive, from people
+          # who often can no longer sign in.
+          #
+          # Irreversible, so it is its own action rather than a flag on update.
+          def anonymize
+            authorize_resource!(@resource)
+
+            # Recorded like the export beside it. The erasure itself is the
+            # obligation and runs whatever happens to the record, but a
+            # merchant answering an emailed request should not have to
+            # remember they did — the request log is what an Art. 30 enquiry
+            # reads, and an erasure that left only an event was invisible to it.
+            data_request = open_erasure_record
+
+            # Through the dependency, not the class: a host app that swaps the
+            # anonymizer in — for a legal hold, or to reach its own tables —
+            # must get the same erasure whoever asked for it. Naming the class
+            # here would apply their override to a customer's own request and
+            # skip it when staff answer the same request from the admin.
+            result = Spree.customer_anonymize_workflow.call(
+              customer: @resource,
+              store: current_store,
+              requested_by: try_spree_current_user
+            )
+
+            unless result.success?
+              data_request&.update(status: 'failed', error_message: result.error.to_s.first(1000))
+              return render_result_error(result)
+            end
+
+            data_request&.update(status: 'completed', completed_at: Time.current)
+
+            render json: serialize_resource(@resource.reload)
+          end
+
+          # GET /api/v3/admin/customers/:id/export
+          #
+          # The customer's data as JSON, for answering a subject access request
+          # the merchant received directly. Rendered inline rather than queued:
+          # a staff member is waiting on it, and unlike the storefront path
+          # there is no unauthenticated caller to rate-limit.
+          def export
+            authorize_resource!(@resource)
+            return unless authorized_for_export?
+
+            if @resource.anonymized?
+              return render_error(
+                code: ERROR_CODES[:validation_error],
+                message: Spree.t('data_request_errors.already_anonymized'),
+                status: :unprocessable_content
+              )
+            end
+
+            # Its own record, never an existing one. `DataRequests::Create`
+            # returns whatever request is in flight for this customer, and
+            # completing that here would close their request without ever
+            # delivering their file — the queued job would then refuse it as no
+            # longer pending. Its `requested_by_id: nil` filter does not help:
+            # it scopes to rows the customer opened, which is exactly the row
+            # that must be left alone.
+            data_request = Spree::DataRequest.create!(
+              store: current_store,
+              customer: @resource,
+              kind: Spree::DataRequest::ACCESS,
+              email: @resource.email,
+              requested_by: try_spree_current_user
+            )
+
+            # The request row is opened first: an Art. 15 response should leave
+            # the same trace whoever produced it, and building through the
+            # workflow is what runs the `extend_payload` hook a host app relies
+            # on to complete the document.
+            payload = Spree::DataRequests::Fulfill.payload_for(data_request)
+            data_request.update(status: 'completed', completed_at: Time.current)
+
+            render json: payload
+          end
+
           # Bulk add the given customers to the given groups. Idempotent —
           # customers already in a group are skipped at the model layer.
           def bulk_add_to_groups
@@ -63,7 +152,7 @@ module Spree
           protected
 
           def model_class
-            Spree.user_class
+            Spree.customer_class
           end
 
           def serializer_class
@@ -74,10 +163,99 @@ module Spree
             super.with_order_aggregates
           end
 
+          # Producing the export reads the customer, so it is a read for the
+          # key gate and for CanCanCan alike. The latter needs saying twice:
+          # `read_actions` settles the required API-key scope, while
+          # `authorize_resource!` below maps the action onto an ability a role
+          # actually grants — CanCanCan's `:read` alias covers only index and
+          # show, so a staffer with read access would otherwise be refused.
+          def read_actions
+            super + ['export']
+          end
+
+          # Its own row rather than one the customer has in flight, for the
+          # same reason the export opens its own: completing theirs here would
+          # close a request whose file was never delivered.
+          #
+          # @return [Spree::DataRequest, nil] nil when the record cannot be
+          #   written — the erasure is the obligation and still runs
+          def open_erasure_record
+            Spree::DataRequest.create(
+              store: current_store,
+              customer: @resource,
+              kind: Spree::DataRequest::ERASURE,
+              email: @resource.email,
+              requested_by: try_spree_current_user,
+              status: 'processing'
+            ).presence
+          rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+            Rails.logger.warn { "[Spree] Could not record erasure request: #{e.message}" }
+            nil
+          end
+
+          # A subject access export carries the customer's order history, which
+          # is otherwise gated on `read_orders`. The controller's own scope only
+          # covers `read_customers`, so aggregating the two behind one key would
+          # hand order data to a role that was never granted it.
+          #
+          # @return [Boolean] false when the response has already been rendered
+          # Everything the subject access response gathers, and the permission
+          # that guards it elsewhere in the API. Seeing a customer's name is not
+          # the same as downloading their order history, their saved cards and
+          # their balances in one file, so the export asks for each of them.
+          EXPORT_PERMISSIONS = %w[
+            read_orders
+            read_payments
+            read_store_credits
+            read_gift_cards
+          ].freeze
+
+          def authorized_for_export?
+            missing = EXPORT_PERMISSIONS.reject { |permission| holds_permission?(permission) }
+            return true if missing.empty?
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+              message: "Missing permission: #{missing.first}",
+              status: :forbidden,
+              details: { required_permission: missing.first }
+            )
+            false
+          end
+
+          # Mirrors the key gate's two principals: a secret key carries scopes,
+          # a signed-in staffer carries their roles' catalog keys.
+          #
+          # @param key [String]
+          # @return [Boolean]
+          def holds_permission?(key)
+            return current_api_key.has_scope?(key) if scope_limited_principal?
+
+            ability = current_ability
+            return true unless ability.respond_to?(:permission_keys)
+
+            ability.permission_keys.include?(key)
+          end
+
+          # `export` maps to `:show`; `anonymize` is a destructive write, so it
+          # maps to `:destroy` rather than `:update` — a role that may correct
+          # a customer's name should not thereby be able to erase their history.
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            mapped = case action
+                     when :export then :show
+                     when :anonymize then :destroy
+                     else action
+                     end
+
+            authorize!(mapped, resource || model_class)
+          end
+
           # `customer_groups` is preloaded because the serializer's always-on
-          # `customer_group_ids` attribute reads it for every row.
+          # `customer_group_ids` attribute reads it for every row. `companies`
+          # is not: it only renders behind `?expand=companies`, where
+          # ar_lazy_preload already batches it into one query for the page.
           def collection_includes
-            [:rich_text_internal_note, :customer_groups, taggings: :tag]
+            [:customer_groups, taggings: :tag]
           end
 
           private
@@ -95,6 +273,7 @@ module Spree
 
           def permitted_params
             params.permit(
+              *model_additional_permitted_attributes,
               :email, :first_name, :last_name, :phone,
               :password, :password_confirmation, :selected_locale,
               :avatar, :accepts_email_marketing, :internal_note,