spree_api 6.0.0.beta4 → 6.0.0.rc1

data/app/controllers/concerns/spree/api/v3/storefront_gating.rb

@@ -41,12 +41,18 @@ module Spree
         end
 
         # Renders a 401 with the shared +authentication_required+ error code.
-        # @param message_key [String] i18n key for the error message
-        # @param default_message [String] fallback when the key is missing
-        def render_authentication_required(message_key, default_message)
+        # @param message [String] translated error message
+        # @param legacy_default [String, nil] deprecated: the two-argument form
+        #   (key under +spree.+, fallback text) is removed in Spree 6.1
+        def render_authentication_required(message, legacy_default = nil)
+          unless legacy_default.nil?
+            Spree::Deprecation.warn('render_authentication_required(key, default) is deprecated and will be removed in Spree 6.1. Pass the translated message instead.')
+            message = I18n.t("spree.#{message}", default: legacy_default)
+          end
+
           render_error(
             code: ErrorHandler::ERROR_CODES[:authentication_required],
-            message: Spree.t(message_key, default: default_message),
+            message: message,
             status: :unauthorized
           )
         end
@@ -57,7 +63,7 @@ module Spree
           return if try_spree_current_user.present?
           return unless current_channel&.storefront_login_required?
 
-          render_authentication_required('api.errors.storefront_login_required', 'Authentication required to access this store')
+          render_authentication_required(I18n.t('spree.api.errors.storefront_login_required'))
         end
       end
     end

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

@@ -14,11 +14,6 @@ module Spree
           # grantable separately from store configuration (6.0-admin-rbac.md).
           scoped_resource :staff
 
-          # POST is not exposed — staff are created via invitations.
-          def create
-            head :method_not_allowed
-          end
-
           # DELETE /api/v3/admin/admin_users/:id
           # Removes role assignments for the current store rather than deleting
           # the account globally. The user keeps access to any other stores.

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

@@ -64,7 +64,7 @@ module Spree
             unless current_api_key
               return render_error(
                 code: ERROR_CODES[:record_not_found],
-                message: Spree.t(:api_key_no_current_key),
+                message: I18n.t('spree.api_key_no_current_key'),
                 status: :not_found
               )
             end

data/app/controllers/spree/api/v3/admin/catalogs/order_minimums_controller.rb

@@ -9,7 +9,6 @@ module Spree
           class OrderMinimumsController < BaseController
             before_action :authorize_parent_access!
 
-
             protected
 
             def model_class
@@ -24,14 +23,9 @@ module Spree
               @parent.order_minimums
             end
 
-            def parent_association
-              :order_minimums
-            end
-
             def permitted_params
               params.permit(:currency, :amount)
             end
-
           end
         end
       end

data/app/controllers/spree/api/v3/admin/catalogs/quantity_rules_controller.rb

@@ -52,10 +52,6 @@ module Spree
               @catalog.quantity_rules
             end
 
-            def parent_association
-              :quantity_rules
-            end
-
             private
 
             # Products resolve through this store, so an id belonging to

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

@@ -22,7 +22,7 @@ module Spree
             if @resource.price_list.nil?
               return render_error(
                 code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                message: Spree.t('catalogs.no_price_list_to_import'),
+                message: I18n.t('spree.catalogs.no_price_list_to_import'),
                 status: :unprocessable_content
               )
             end

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

@@ -60,10 +60,6 @@ module Spree
             Spree.api.admin_channel_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           def permitted_params
             params.permit(*model_additional_permitted_attributes, :name, :code, :active, :default, :preferred_order_routing_strategy,
                           :preferred_storefront_access, :preferred_guest_checkout,

data/app/controllers/spree/api/v3/admin/collections/products_controller.rb

@@ -80,8 +80,7 @@ module Spree
 
               render_error(
                 code: ERROR_CODES[:validation_error],
-                message: Spree.t('api.errors.automatic_collection_curation',
-                                 default: "Products of an automatic collection are managed by its rules and can't be curated manually"),
+                message: I18n.t('spree.api.errors.automatic_collection_curation'),
                 status: :unprocessable_content
               )
             end

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

@@ -26,7 +26,7 @@ module Spree
               {
                 type: klass.api_type,
                 name: klass.human_name,
-                description: klass.description,
+                description: klass.human_description,
                 preference_schema: klass.serialized_preference_schema,
                 # Config a rule takes beyond its preferences — a catalog-scale
                 # reference list lives in its own table, not the blob, and an
@@ -139,7 +139,7 @@ module Spree
             errors = ActiveModel::Errors.new(Spree::CommissionRate.new)
             unknown.each do |type|
               errors.add(:rules, :invalid_commission_rule_type, type: type,
-                         message: Spree.t('errors.messages.invalid_commission_rule_type', type: type))
+                         message: I18n.t('spree.errors.messages.invalid_commission_rule_type', type: type))
             end
             render_validation_error(errors)
 

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

@@ -53,10 +53,6 @@ module Spree
             def scope
               @parent.addresses
             end
-
-            def parent_association
-              :addresses
-            end
           end
         end
       end

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

@@ -17,7 +17,7 @@ module Spree
               else
                 render_error(
                   code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                  message: Spree.t('company_invitations.not_pending'),
+                  message: I18n.t('spree.company_invitations.not_pending'),
                   status: :unprocessable_content
                 )
               end
@@ -44,10 +44,6 @@ module Spree
             def scope
               action_name == 'index' ? @parent.invitations.pending : @parent.invitations
             end
-
-            def parent_association
-              :invitations
-            end
           end
         end
       end

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

@@ -47,10 +47,6 @@ module Spree
               @parent.memberships
             end
 
-            def parent_association
-              :memberships
-            end
-
             def collection_includes
               [:customer]
             end

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

@@ -24,11 +24,7 @@ module Spree
                 verified_by: try_spree_current_user
               )
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
 
             # PATCH .../:id/revoke — withdrawing evidence that was accepted.
@@ -88,10 +84,6 @@ module Spree
               @parent.tax_exemption_certificates
             end
 
-            def parent_association
-              :tax_exemption_certificates
-            end
-
             def collection_includes
               [{ document_attachment: :blob }]
             end

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

@@ -31,10 +31,6 @@ module Spree
               @parent.tax_identifiers
             end
 
-            def parent_association
-              :tax_identifiers
-            end
-
             def permitted_params
               params.permit(:kind, :value)
             end

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

@@ -22,10 +22,6 @@ module Spree
             Spree.api.admin_company_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           def collection_includes
             [:children, :memberships, :external_references]
           end

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

@@ -11,7 +11,7 @@ module Spree
 
           # 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.
+          # client_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

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

@@ -22,10 +22,6 @@ module Spree
             @parent = current_store.promotions.accessible_by(current_ability, :show)
                                    .find_by_prefix_id!(params[:promotion_id])
           end
-
-          def parent_association
-            :coupon_codes
-          end
         end
       end
     end

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

@@ -4,7 +4,7 @@ module Spree
       module Admin
         # Schema-side metadata for custom fields. Definitions are per resource
         # *type* (every Spree::Product shares the same definitions), so this is
-        # a flat top-level endpoint. Filter by `?resource_type=Spree::Product`
+        # a flat top-level endpoint. Filter by `q[resource_type_eq]=product`
         # (or any other registered custom-field-bearing resource) to scope the
         # list to one parent type.
         class CustomFieldDefinitionsController < ResourceController
@@ -39,6 +39,14 @@ module Spree
                           :searchable, :sortable)
           end
 
+          # `resource_type` is a plain column rather than a polymorphic
+          # association, so its filter goes through the model's own normalizer.
+          def api_type_resolver(attribute)
+            return super unless attribute == 'resource_type'
+
+            ->(api_type) { model_class.normalize_value_for(:resource_type, api_type) }
+          end
+
           # Pure registry discovery — maps to the read scope.
           def read_actions
             super + %w[resource_types]

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

@@ -43,10 +43,6 @@ module Spree
             Spree.api.admin_custom_field_serializer
           end
 
-          def parent_association
-            :custom_fields
-          end
-
           def set_parent
             # Routes always mount this controller under a recognized parent, so
             # `parent_lookup` matches in normal flows. The explicit raise is a

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

@@ -17,10 +17,6 @@ module Spree
             Spree.api.admin_customer_group_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           def permitted_params
             params.permit(*model_additional_permitted_attributes, :name, :description, customer_ids: [])
           end

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

@@ -50,10 +50,6 @@ module Spree
 
             protected
 
-            def parent_association
-              :addresses
-            end
-
             def model_class
               Spree::Address
             end

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

@@ -6,10 +6,6 @@ module Spree
           class CreditCardsController < BaseController
             protected
 
-            def parent_association
-              :credit_cards
-            end
-
             # Customers are global; a saved card belongs to the store-scoped
             # payment method it was created against, so the nested collection is
             # bound to the current store's payment methods.

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

@@ -62,10 +62,6 @@ module Spree
 
             protected
 
-            def parent_association
-              :store_credits
-            end
-
             # Customers are global; store credits belong to a store, so the
             # nested collection is bound to the current store.
             def scope

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

@@ -51,7 +51,7 @@ module Spree
           rescue Spree::Core::DestroyWithOrdersError => e
             render_error(
               code: 'customer_has_orders',
-              message: e.message.presence || Spree.t(:error_user_destroy_with_orders),
+              message: e.message.presence || I18n.t('spree.error_user_destroy_with_orders'),
               status: :unprocessable_content
             )
           end
@@ -108,7 +108,7 @@ module Spree
             if @resource.anonymized?
               return render_error(
                 code: ERROR_CODES[:validation_error],
-                message: Spree.t('data_request_errors.already_anonymized'),
+                message: I18n.t('spree.data_request_errors.already_anonymized'),
                 status: :unprocessable_content
               )
             end

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

@@ -16,7 +16,7 @@ module Spree
               if rule_class.nil?
                 return render_error(
                   code: ERROR_CODES[:validation_error],
-                  message: Spree.t('errors.messages.invalid_delivery_method_rule'),
+                  message: I18n.t('spree.errors.messages.invalid_delivery_method_rule'),
                   status: :unprocessable_entity
                 )
               end

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

@@ -31,9 +31,8 @@ module Spree
 
             data = Spree.fulfillment_providers.map do |provider_class|
               {
-                type: provider_class.to_s,
+                type: provider_class.api_type,
                 name: provider_class.provider_name,
-                integration_class: provider_class.integration_class,
                 integration_type: integration_api_type(provider_class),
                 available: provider_class.available_for_store?(current_store),
                 digital: provider_class.digital?,
@@ -61,9 +60,8 @@ module Spree
               catalog = provider_class.service_catalog(integration)
 
               {
-                type: provider_class.to_s,
+                type: provider_class.api_type,
                 name: provider_class.provider_name,
-                integration_class: provider_class.integration_class,
                 integration_type: integration_api_type(provider_class),
                 available: provider_class.available_for_store?(current_store),
                 requires_address: provider_class.requires_address?,
@@ -76,7 +74,7 @@ module Spree
               }
             end
 
-            render json: { data: data, default: Spree::DeliveryMethod::DEFAULT_RATE_PROVIDER }
+            render json: { data: data, default: Spree::ApiTyped.api_type_for(Spree::DeliveryMethod::DEFAULT_RATE_PROVIDER) }
           end
 
           def create

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

@@ -15,12 +15,7 @@ module Spree
           def kinds
             authorize! :create, model_class
 
-            data = Spree.delivery_profile_types.map do |profile_class|
-              {
-                type: profile_class.to_s,
-                kind: profile_class.api_type
-              }
-            end
+            data = Spree.delivery_profile_types.map { |profile_class| { kind: profile_class.api_type } }
 
             render json: { data: data }
           end

data/app/controllers/spree/api/v3/admin/email_templates/drafts_controller.rb

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          # The draft of an editable email template: saved in any state, while
+          # customers keep receiving the published version.
+          class DraftsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            # PUT /api/v3/admin/email_templates/:email_template_id/draft
+            #
+            # Send the `lock_version` the draft was loaded with: a save made from
+            # an older copy is refused with 409, naming who saved last. `rebase`
+            # marks the draft as based on Spree's current default.
+            def update
+              authorize! :update, Spree::EmailTemplate
+
+              result = Spree.email_template_save_draft_workflow.call(
+                store: current_store, key: email_template.key, locale: language, actor: current_actor,
+                attributes: params.permit(:subject, :body, :lock_version, :rebase).to_h.symbolize_keys
+              )
+              render_email_template_result(result)
+            end
+
+            # DELETE /api/v3/admin/email_templates/:email_template_id/draft
+            def destroy
+              authorize! :update, Spree::EmailTemplate
+
+              result = Spree.email_template_discard_draft_workflow.call(
+                store: current_store, key: email_template.key, locale: language, lock_version: params[:lock_version].presence
+              )
+              render_email_template_result(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/previews_controller.rb

@@ -0,0 +1,30 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          class PreviewsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            before_action :authorize_sample_data!
+
+            # POST /api/v3/admin/email_templates/:email_template_id/preview
+            #
+            # Renders the template with sample data built from the store's latest
+            # matching record, or the one `record_id` names. An unsaved `subject`
+            # and `body` take the place of the current version. Returns the
+            # rendered email and the variables it was rendered with.
+            def create
+              authorize! :update, Spree::EmailTemplate
+
+              preview = build_preview
+              preview.call
+
+              render json: Spree.api.admin_email_template_preview_serializer.new(preview, params: serializer_params).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/publications_controller.rb

@@ -0,0 +1,30 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          class PublicationsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            before_action :authorize_sample_data!
+
+            # POST /api/v3/admin/email_templates/:email_template_id/publication
+            #
+            # Makes the draft live. A draft that does not render with sample data
+            # (for the layout or a partial: in any email using it) is refused with
+            # 422 and each problem's email and line.
+            def create
+              authorize! :update, Spree::EmailTemplate
+
+              result = Spree.email_template_publish_workflow.call(
+                store: current_store, key: email_template.key, locale: language, actor: current_actor,
+                lock_version: params[:lock_version].presence
+              )
+              render_email_template_result(result, status: :created)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/restorations_controller.rb

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          class RestorationsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            # POST /api/v3/admin/email_templates/:email_template_id/revisions/:revision_id/restoration
+            #
+            # Copies the revision into the language's draft, to be published
+            # like any change. A language without a version of its own can
+            # restore one of the version for every language its customers get.
+            def create
+              authorize! :update, Spree::EmailTemplate
+
+              revision = Spree::EmailTemplateRevision.where(
+                email_template: current_store.email_templates.where(
+                  key: email_template.key, locale: [language, Spree::EmailTemplate::ANY_LOCALE]
+                )
+              ).find_by_prefix_id!(params[:revision_id])
+
+              result = Spree.email_template_restore_revision_workflow.call(
+                revision: revision, actor: current_actor, locale: language,
+                draft_version: params.key?(:lock_version) ? { lock_version: params[:lock_version] } : {}
+              )
+              render_email_template_result(result, status: :created)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/revisions_controller.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          # The published versions of an email template in one language, newest
+          # first. Reverting keeps them, so they outlive the published version.
+          class RevisionsController < ResourceController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            before_action { authorize! :read, Spree::EmailTemplate }
+
+            protected
+
+            def model_class
+              Spree::EmailTemplateRevision
+            end
+
+            def serializer_class
+              Spree.api.admin_email_template_revision_serializer
+            end
+
+            def scope
+              email_template_revisions.order(created_at: :desc)
+            end
+
+            def collection_includes
+              [:published_by]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/sample_records_controller.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          class SampleRecordsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            before_action :authorize_sample_data!
+
+            # GET /api/v3/admin/email_templates/:email_template_id/sample_records
+            #
+            # The store's five latest records the template can be previewed
+            # with (for the layout and partials, those of the email `email_key`
+            # names). Empty for an email that needs no record.
+            def index
+              authorize! :update, Spree::EmailTemplate
+
+              records = build_preview.email.sample_class.new(store: current_store).recent_records
+              render json: { data: records.map { |record| serializer_class.new(record, params: serializer_params).to_h } }
+            end
+
+            private
+
+            def serializer_class
+              Spree.api.admin_email_template_sample_record_serializer
+            end
+          end
+        end
+      end
+    end
+  end
+end