spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb

@@ -0,0 +1,137 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # A company's exemption evidence. Accepting one is a decision, so it
+          # runs through the verify workflow rather than a status write, and a
+          # verified certificate is revoked rather than deleted.
+          class TaxExemptionCertificatesController < BaseController
+            include ActiveStorage::SetCurrent
+
+            before_action :authorize_parent_access!
+            # Re-declaring the filter replaces the inherited options, so the
+            # standard actions have to be listed alongside the custom ones.
+            before_action :set_resource, only: [:show, :update, :destroy, :verify, :revoke, :download]
+
+            # A tampered signed id would otherwise surface as a 500.
+            rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature
+
+            # PATCH /api/v3/admin/companies/:company_id/tax_exemption_certificates/:id/verify
+            def verify
+              result = Spree.tax_exemption_certificate_verify_workflow.call(
+                certificate: @resource,
+                verified_by: try_spree_current_user
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
+              end
+            end
+
+            # PATCH .../:id/revoke — withdrawing evidence that was accepted.
+            def revoke
+              if @resource.update(status: 'revoked')
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            # GET .../:id/download — streamed rather than redirected, so the
+            # document is never reachable without admin credentials.
+            def download
+
+              unless @resource.document.attached?
+                return render_error(
+                  code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                  message: 'Certificate has no attached document',
+                  status: :unprocessable_content
+                )
+              end
+
+              send_data(
+                @resource.document.download,
+                filename: @resource.document.filename.to_s,
+                type: @resource.document.content_type || 'application/octet-stream',
+                disposition: 'attachment'
+              )
+            end
+
+            protected
+
+            # Fetching the document is a read of the certificate, so it takes the
+            # read scope and the :show ability rather than being classed as a
+            # write because it isn't index or show. Without this a key holding
+            # read_customers is refused its own certificate.
+            READ_ACTIONS = %w[index show download].freeze
+
+            def read_actions
+              READ_ACTIONS
+            end
+
+            def action_kind
+              READ_ACTIONS.include?(action_name) ? 'read' : 'write'
+            end
+
+            def model_class
+              Spree::TaxExemptionCertificate
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_exemption_certificate_serializer
+            end
+
+            def scope
+              @parent.tax_exemption_certificates
+            end
+
+            def parent_association
+              :tax_exemption_certificates
+            end
+
+            def collection_includes
+              [{ document_attachment: :blob }]
+            end
+
+            # `document` is an ActiveStorage signed blob id from
+            # POST /api/v3/admin/direct_uploads.
+            def permitted_params
+              params.permit(:certificate_number, :reason_code, :issuing_authority,
+                            :issued_at, :expires_at, :country_code, :state_code, :document,
+                            metadata: {})
+            end
+
+            def build_resource
+              super.tap { |certificate| certificate.status ||= 'pending' }
+            end
+
+            # The custom actions are not permissions of their own: accepting or
+            # withdrawing is updating, fetching the document is reading.
+            def authorize_resource!(resource = @resource, action = action_name.to_sym)
+              mapped = case action
+                       when :verify, :revoke then :update
+                       when :download then :show
+                       else action
+                       end
+
+              authorize!(mapped, resource)
+            end
+
+            private
+
+            def render_invalid_signature
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Invalid document signed id',
+                status: :unprocessable_content
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # A business's own tax registration — the number that goes on its
+          # invoices, which outranks the buyer's own when the two differ.
+          #
+          # Mirrors the customer registrations endpoint, including manual
+          # re-validation: a registry answers only "valid now", so a number
+          # verified last year may have been deregistered since.
+          class TaxIdentifiersController < BaseController
+            include Spree::Api::V3::TaxIdentifierValidation
+
+            before_action :authorize_parent_access!
+            # 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]
+
+            protected
+
+            def model_class
+              Spree::TaxIdentifier
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_identifier_serializer
+            end
+
+            def scope
+              @parent.tax_identifiers
+            end
+
+            def parent_association
+              :tax_identifiers
+            end
+
+            def permitted_params
+              params.permit(:kind, :value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Company nodes — tree-aware CRUD. A company is a customer record, so
+        # it answers to the customer scopes rather than earning one of its own.
+        #
+        # The tree is driven by Ransack: `?q[parent_id_null]=1` lists roots,
+        # `?q[parent_id_eq]=` a node's children. Deleting a node destroys its
+        # subtree. Re-parenting is an ordinary update — the model revalidates
+        # depth, cycle and store.
+        class CompaniesController < ResourceController
+          scoped_resource :customers
+
+          protected
+
+          def model_class
+            Spree::Company
+          end
+
+          def serializer_class
+            Spree.api.admin_company_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          def collection_includes
+            [:children, :memberships, :external_references]
+          end
+
+          def permitted_params
+            permitted = params.permit(*model_additional_permitted_attributes,
+                                      :name, :kind, :parent_id, :po_number_required, metadata: {})
+            resolve_parent_param(permitted)
+          end
+
+          private
+
+          # The parent is an incidental lookup like any other: resolved through
+          # the store so another tenant's node 404s rather than becoming this
+          # node's parent.
+          def resolve_parent_param(permitted)
+            return permitted unless permitted.key?(:parent_id)
+
+            permitted[:parent_id] =
+              if permitted[:parent_id].present?
+                current_store.companies.find_by_prefix_id!(permitted[:parent_id]).id
+              else
+                nil
+              end
+            permitted
+          end
+        end
+      end
+    end
+  end
+end

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