spree_api 5.6.1 → 6.0.0.beta1

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,

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

@@ -2,23 +2,31 @@ module Spree
   module Api
     module V3
       module Admin
+        # Point-in-time counts registered on Spree.reporting: what needs the
+        # merchant's attention right now, for the home screen's card and the
+        # sidebar's badges. Time-series analytics live in the semantic
+        # reporting endpoint (ReportingController).
         class DashboardController < Admin::BaseController
-          scoped_resource :dashboard
+          include ReportingAuthorization
 
-          # GET /api/v3/admin/dashboard/analytics
-          def analytics
-            date_from = (params[:date_from] || 30.days.ago).to_time.beginning_of_day
-            date_to = (params[:date_to] || Time.current).to_time.end_of_day
-            currency = params[:currency] || current_store.default_currency
+          scoped_resource :dashboard
 
-            serializer = DashboardAnalyticsSerializer.new(
+          # GET /api/v3/admin/dashboard/counters
+          #
+          # Filtered to the counters this caller may read, so a limited role
+          # gets a shorter list rather than a refused card.
+          def counters
+            channel = requested_channel
+            evaluated = Spree::Reporting::Counters.new(
               store: current_store,
-              currency: currency,
-              time_range: date_from..date_to,
-              params: serializer_params
+              channel: channel,
+              allowed: ->(counter) { member_allowed?(counter) }
             )
 
-            render json: serializer.to_h
+            render json: {
+              channel_id: channel&.prefixed_id,
+              counters: DashboardCounterSerializer.new(evaluated.to_a).serializable_hash
+            }
           end
 
           private
@@ -27,15 +35,11 @@ module Spree
             'read'
           end
 
-          def serializer_params
-            {
-              store: current_store,
-              locale: current_locale,
-              currency: current_currency,
-              user: current_user,
-              includes: [],
-              expand: []
-            }
+          # Optional channel scoping — omitted means all channels.
+          def requested_channel
+            return if params[:channel_id].blank?
+
+            current_store.channels.find_by_prefix_id!(params[:channel_id])
           end
         end
       end

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

@@ -0,0 +1,60 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The store's log of GDPR data subject requests — what was asked for,
+        # by whom, and whether it was answered.
+        #
+        # Read-only plus create. A request is a record of something that
+        # happened, so editing one would falsify the audit trail the record
+        # exists to provide; erasing the log of an erasure is worse still.
+        class DataRequestsController < ResourceController
+          scoped_resource :customers
+
+          def create
+            authorize! :create, Spree::DataRequest
+
+            result = Spree::DataRequests::Create.call(
+              store: current_store,
+              customer: customer,
+              kind: params[:kind],
+              requested_by: try_spree_current_user
+            )
+
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value), status: :accepted
+          end
+
+          protected
+
+          def model_class
+            Spree::DataRequest
+          end
+
+          def serializer_class
+            Spree.api.admin_data_request_serializer
+          end
+
+          def scope
+            super.recent_first
+          end
+
+          def collection_includes
+            [:customer]
+          end
+
+          private
+
+          # Customers are global in Spree — they shop across a multi-store
+          # installation on one account — so there is no store association to
+          # narrow this through. `authorize!` above is what gates the caller,
+          # and the request records which store it was raised at.
+          def customer
+            @customer ||= Spree.customer_class.find_by_prefix_id!(params[:customer_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DeliveryMethodRulesController < ResourceController
+          scoped_resource :delivery_methods
+
+          # GET /api/v3/admin/delivery_method_rules/types
+          # Registered rule kinds with preference schemas for admin pickers.
+          def types
+            authorize! :create, Spree::DeliveryMethodRule
+
+            data = Spree.delivery_method_rules.map do |klass|
+              {
+                type: klass.api_type,
+                name: klass.human_name,
+                description: klass.human_description,
+                preference_schema: klass.serialized_preference_schema,
+                # Association-backed config (e.g. `product_ids`) a rule accepts
+                # beyond its preferences, so admin UIs can render the right
+                # editor without hardcoding rule types.
+                association_fields: association_fields_for(klass)
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          protected
+
+          def model_class
+            Spree::DeliveryMethodRule
+          end
+
+          def serializer_class
+            Spree.api.admin_delivery_method_rule_serializer
+          end
+
+          private
+
+          # `additional_permitted_attributes` entries are either bare symbols
+          # or `{ product_ids: [] }`-style hashes; both reduce to field names.
+          def association_fields_for(klass)
+            return [] unless klass.respond_to?(:additional_permitted_attributes)
+
+            klass.additional_permitted_attributes.flat_map do |attribute|
+              attribute.is_a?(Hash) ? attribute.keys : attribute
+            end.map(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/delivery_methods/rules_controller.rb

@@ -0,0 +1,114 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module DeliveryMethods
+          # Eligibility rules nested under a delivery method. `type` is the
+          # wire shorthand from GET /delivery_method_rules/types.
+          class RulesController < ResourceController
+            scoped_resource :delivery_methods
+
+            def create
+              rule_class = Spree.delivery_method_rules.detect do |klass|
+                klass.api_type == params[:type].to_s
+              end
+
+              if rule_class.nil?
+                return render_error(
+                  code: ERROR_CODES[:validation_error],
+                  message: Spree.t('errors.messages.invalid_delivery_method_rule'),
+                  status: :unprocessable_entity
+                )
+              end
+
+              @resource = rule_class.new(delivery_method: parent, active: active_param)
+              assign_rule_preferences(@resource)
+              assign_rule_products(@resource)
+              assign_extension_attributes(@resource)
+              authorize_resource!(@resource, :create)
+
+              if @resource.save
+                render json: serialize_resource(@resource), status: :created
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            def update
+              @resource.active = active_param unless params[:active].nil?
+              assign_rule_preferences(@resource)
+              assign_rule_products(@resource)
+              assign_extension_attributes(@resource)
+
+              if @resource.save
+                render json: serialize_resource(@resource)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::DeliveryMethodRule
+            end
+
+            def serializer_class
+              Spree.api.admin_delivery_method_rule_serializer
+            end
+
+            def scope
+              parent.delivery_method_rules
+            end
+
+            def permitted_params
+              params.permit(*model_additional_permitted_attributes, :type, :active, preferences: {}, product_ids: [])
+            end
+
+            private
+
+            def parent
+              @parent ||= current_store.delivery_methods.accessible_by(current_ability, :update).find_by_prefix_id!(params[:delivery_method_id])
+            end
+
+            def active_param
+              params[:active].nil? ? true : params[:active].to_b
+            end
+
+            # This controller assigns each field by hand rather than mass-assigning,
+            # so attributes an extension contributed have to be forwarded too or
+            # permitting them would have no effect.
+            def assign_extension_attributes(rule)
+              keys = model_additional_permitted_attributes.flat_map { |a| a.is_a?(Hash) ? a.keys : a }
+              return if keys.empty?
+
+              rule.assign_attributes(permitted_params.to_h.slice(*keys.map(&:to_s)))
+            end
+
+            def assign_rule_preferences(rule)
+              (permitted_params[:preferences] || {}).each do |key, value|
+                next unless rule.has_preference?(key)
+
+                rule.set_preference(key, value)
+              end
+            end
+
+            # Association-backed rule config (ExcludedProductsRule). Products are
+            # looked up within the rule's store and through the caller's ability;
+            # ids that resolve to nothing are dropped rather than failing the
+            # save, since an unreachable product cannot become an exclusion. A
+            # nil param leaves the selection untouched; an empty array clears it.
+            def assign_rule_products(rule)
+              ids = permitted_params[:product_ids]
+              return if ids.nil? || !rule.respond_to?(:products)
+
+              rule.products = rule.store.products.
+                              accessible_by(current_ability, :show).
+                              where(id: decode_prefixed_ids(ids))
+            end
+          end
+        end
+      end
+    end
+  end
+end