spree_api 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,191 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Catalogs — assortment + optional price list, shown to an audience
+        # through assignments. Merchandising data, so it answers to the
+        # products scopes.
+        class CatalogsController < ResourceController
+          scoped_resource :products
+
+          before_action :set_resource,
+                        only: [:show, :update, :destroy, :assign, :import_products,
+                               :activate, :deactivate]
+
+          # POST /api/v3/admin/catalogs/:id/import_products — copies the
+          # attached price list's products into the assortment. Explicit by
+          # design: an empty assortment is a pricing-only overlay, so making
+          # a catalog restrictive is a deliberate act.
+          def import_products
+            authorize! :update, @resource
+
+            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'),
+                status: :unprocessable_content
+              )
+            end
+
+            render json: { added_count: @resource.import_products_from_price_list }
+          end
+
+          # POST /api/v3/admin/catalogs/:id/assign — { assignable_type, assignable_id }
+          def assign
+            authorize! :update, @resource
+
+            assignment = @resource.catalog_assignments.new(assignable: find_assignable)
+
+            if assignment.save
+              render json: Spree.api.admin_catalog_assignment_serializer.new(
+                assignment, params: serializer_params
+              ).to_h, status: :created
+            else
+              render_validation_error(assignment.errors)
+            end
+          end
+
+          # PATCH /api/v3/admin/catalogs/:id/activate
+          def activate
+            run_status_workflow(Spree.catalog_activate_workflow)
+          end
+
+          # PATCH /api/v3/admin/catalogs/:id/deactivate
+          def deactivate
+            run_status_workflow(Spree.catalog_deactivate_workflow)
+          end
+
+          protected
+
+          def model_class
+            Spree::Catalog
+          end
+
+          def serializer_class
+            Spree.api.admin_catalog_serializer
+          end
+
+          def scope
+            super.ordered
+          end
+
+          def collection_includes
+            # The serializer reads each catalog's pricing strategy, which asks
+            # its list whether it carries bands — preloaded so an index does
+            # not pay a query per row.
+            [:catalog_products, :order_minimums, { price_list: :price_adjustment_tiers }]
+          end
+
+          def create_workflow
+            Spree.catalog_create_workflow
+          end
+
+          def update_workflow
+            Spree.catalog_update_workflow
+          end
+
+          def run_status_workflow(workflow)
+            authorize! :update, @resource
+
+            result = workflow.call(catalog: @resource)
+
+            if result.success?
+              render json: serialize_resource(@resource.reload)
+            else
+              render_service_error(result.error)
+            end
+          end
+
+          # `price_list` is an inline payload rather than a reference: a
+          # catalog and the list it prices through are stood up in one
+          # request (docs/plans/6.0-catalog-agreement-rework.md). Sending it
+          # as `null` detaches the list the catalog owns; omitting the key
+          # leaves it alone.
+          def permitted_params
+            permitted = params.permit(*model_additional_permitted_attributes,
+                                      :name, :description, :active, :position,
+                                      :minimum_order_quantity, :order_multiple,
+                                      metadata: {},
+                                      # Small bounded sets, saved with the
+                                      # catalog so the whole agreement lands
+                                      # in one transaction. Per-product terms
+                                      # stay their own endpoint — an
+                                      # agreement may name thousands of them.
+                                      assignments: [:assignable_type, :assignable_id],
+                                      order_minimums: [:currency, :amount],
+                                      price_list: [
+                                        :name, :description, :status, :match_policy,
+                                        :starts_at, :ends_at,
+                                        :price_adjustment_percentage, :adjust_compare_at,
+                                        # Contextual rules only in practice — a
+                                        # VolumeRule is what turns a percentage
+                                        # into automatic volume pricing. Audience
+                                        # rules on an owned list are inert, since
+                                        # the catalog assignment already decided
+                                        # the audience.
+                                        { rules: [:id, :type, { preferences: {} }] },
+                                        # An empty array clears the hand-entered
+                                        # amounts — what switching to a
+                                        # percentage sends.
+                                        { prices: [:id, :variant_id, :currency, :min_quantity,
+                                                   :amount, :compare_at_amount] },
+                                        # Quantity bands on the percentage. The
+                                        # payload is the whole ladder, so an
+                                        # empty array clears it.
+                                        { price_adjustment_tiers: [:min_quantity, :percentage] }
+                                      ])
+            # `permit` drops an explicit null, but detaching has to be
+            # distinguishable from saying nothing.
+            permitted[:price_list] = nil if params.key?(:price_list) && params[:price_list].nil?
+
+            # Resolved here rather than in the workflow: each audience goes
+            # through the store AND through what this caller may see, so a
+            # nested write cannot reach one the dedicated endpoint could not.
+            if permitted.key?(:assignments)
+              permitted[:assignables] = requested_assignables
+              permitted.delete(:assignments)
+            end
+
+            permitted
+          end
+
+          private
+
+          # The audience vocabulary is closed; each type resolves through the
+          # store so another tenant's record is a 404, never an assignment.
+          ASSIGNABLE_SCOPES = {
+            'company' => ->(store) { store.companies },
+            'customer_group' => ->(store) { Spree::CustomerGroup.for_store(store) }
+          }.freeze
+
+          # Scoped by the store AND by what this caller may see: a role that
+          # reaches only some companies must not be able to assign a catalog
+          # to one it cannot read, and an unreadable record is not-found
+          # rather than refused so its existence does not leak.
+          def find_assignable
+            resolve_assignable(params.require(:assignable_type), params.require(:assignable_id))
+          end
+
+          # Each entry resolves the same way a single assign does — through
+          # the store AND through what this caller may see — so a set write
+          # cannot reach an audience the one-at-a-time path could not.
+          def requested_assignables
+            Array(params[:assignments]).map do |entry|
+              permitted = entry.permit(:assignable_type, :assignable_id)
+              resolve_assignable(permitted.require(:assignable_type), permitted.require(:assignable_id))
+            end
+          end
+
+          def resolve_assignable(type, id)
+            scope_builder = ASSIGNABLE_SCOPES[type.to_s]
+            raise ActiveRecord::RecordNotFound if scope_builder.nil?
+
+            scope_builder.call(current_store).
+              accessible_by(current_ability, :show).
+              find_by_prefix_id!(id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,33 +3,17 @@ module Spree
     module V3
       module Admin
         module Categories
-          # Manages the products classified under a category — the manual
-          # membership half of the old Rails admin's taxon "Products" panel.
-          # Listing is ordered by the classification position so the merchant's
-          # manual ordering round-trips; +reposition+ persists a drag-to-reorder.
+          # The products classified under a category — the uniform nested
+          # membership surface (see Spree::Api::V3::Admin::ProductMembership),
+          # plus per-member reposition: listing is ordered by the
+          # classification position so the merchant's manual ordering
+          # round-trips.
           class ProductsController < ResourceController
-            scoped_resource :products
-
-            # Skip the base single-resource load — membership actions resolve
-            # the product against the category's scope themselves (set_product).
-            skip_before_action :set_resource
-            before_action :set_product, only: [:destroy, :reposition]
+            include Spree::Api::V3::Admin::ProductMembership
 
-            # POST /api/v3/admin/categories/:category_id/products
-            # Body: { product_id: 'prod_…' }
-            def create
-              product = product_scope.find_by_prefix_id!(params[:product_id])
-              Spree::Taxons::AddProducts.call(taxons: [@category], products: [product])
-              render json: serialize_resource(product), status: :created
-            end
+            scoped_resource :products
 
-            # DELETE /api/v3/admin/categories/:category_id/products/:id
-            # Bulk removal goes through the existing
-            # POST /products/bulk_remove_from_categories ({ ids, category_ids }).
-            def destroy
-              Spree::Taxons::RemoveProducts.call(taxons: [@category], products: [@product])
-              head :no_content
-            end
+            before_action :set_product, only: [:reposition]
 
             # PATCH /api/v3/admin/categories/:category_id/products/:id/reposition
             # Body: { new_position: 0 } — 0-based index among the category's products.
@@ -40,25 +24,20 @@ module Spree
               return render_invalid_position if position.nil?
 
               classification_for(@product).insert_at(position + 1)
+              # insert_at shifts sibling positions, so refresh every product in the
+              # category (manual sort reads position from the search index).
+              @category.products.find_each(&:enqueue_search_index)
               head :no_content
             end
 
             protected
 
-            def model_class
-              Spree::Product
-            end
-
-            def serializer_class
-              Spree.api.admin_product_serializer
-            end
-
             # The category's products, ordered by classification position.
             def scope
               product_scope.
-                joins(:classifications).
-                where(Spree::Classification.table_name => { taxon_id: @category.id }).
-                order(Spree::Classification.table_name => { position: :asc })
+                joins(:product_categories).
+                where(Spree::ProductCategory.table_name => { category_id: @category.id }).
+                order(Spree::ProductCategory.table_name => { position: :asc })
             end
 
             # A product is classified at most once per taxon (unique [taxon_id,
@@ -69,9 +48,21 @@ module Spree
               false
             end
 
+            def add_member_products(products)
+              Spree::Categories::AddProducts.call(categories: [@category], products: products)
+            end
+
+            def remove_member_products(products)
+              Spree::Categories::RemoveProducts.call(categories: [@category], products: products)
+            end
+
             # Loads the parent category (runs before the base set_resource).
+            # Scoped to +manual+ so automatic (rule-based) rows — hidden by the
+            # categories CRUD controller and migrating to Spree::Collection — can't
+            # have their membership listed or mutated through this endpoint.
             def set_parent
-              @category = Spree::Category.accessible_by(current_ability, :update).
+              @category = Spree::Category.manual.
+                          accessible_by(current_ability, parent_ability_action).
                           for_store(current_store).
                           find_by_prefix_id!(params[:category_id])
               authorize_parent!(@category)
@@ -83,12 +74,8 @@ module Spree
               @product = scope.find_by_prefix_id!(params[:id])
             end
 
-            def product_scope
-              current_store.products.accessible_by(current_ability, :show)
-            end
-
             def classification_for(product)
-              Spree::Classification.find_by(taxon_id: @category.id, product_id: product.id)
+              Spree::ProductCategory.find_by(category_id: @category.id, product_id: product.id)
             end
           end
         end

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

@@ -52,6 +52,13 @@ module Spree
             Spree.api.admin_category_serializer
           end
 
+          # Categories exclude automatic (rule-based) rows, which still live in
+          # spree_categories until the Phase 4 migration moves them to Collections.
+          # No-op after migration; the .manual scope is removed in 6.1.
+          def scope
+            super.manual
+          end
+
           # Category-half attributes only. Deliberately excludes the
           # collection-bound fields (automatic, sort_order, rules_match_policy,
           # taxon_rules) and taxonomy_id — those belong to Spree::Collection
@@ -60,13 +67,14 @@ module Spree
           # can't be targeted).
           def permitted_params
             permitted = params.permit(
+              *model_additional_permitted_attributes,
               :name, :description, :permalink,
               :meta_title, :meta_description, :meta_keywords,
-              :hide_from_nav, :image, :square_image,
+              :image, :square_image,
               # Inline custom field values keyed by definition id. The model
-              # setter (Spree::Metafields#custom_fields=) validates each entry
+              # setter (Spree::HasCustomFields#custom_fields=) validates each entry
               # against its definition. `value` is permitted as a scalar AND as
-              # `value: []` / `value: {}` so JSON metafields round-trip whether
+              # `value: []` / `value: {}` so JSON custom_fields round-trip whether
               # the parsed payload is an array or an object, while
               # text/number/boolean ship scalars.
               custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
@@ -103,10 +111,11 @@ module Spree
           end
 
           # Positions the node at +index+ among the store's root categories.
-          # awesome_nested_set's move_to_child_with_index(:root, ...) can't be
-          # used here: its +roots+ are global (every parentless taxon across all
-          # stores and taxonomies), whereas we order only this store's manual
-          # roots (the +scope+). So position relative to the target root sibling.
+          # Deliberately not move_to_child_with_index(:root, ...): that indexes
+          # into awesome_nested_set's class-level +roots+, which stays global
+          # across stores even though the set is scoped per store. Positioning
+          # relative to the target sibling keeps the index meaning what the
+          # caller computed it from — this store's roots.
           def move_to_root_at_index(node, index)
             others = scope.where(parent_id: nil).where.not(id: node.id).order(:lft).to_a
             target = others[index]

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

@@ -29,6 +29,27 @@ module Spree
             render json: { product_count: removed }
           end
 
+          def create
+            @resource = model_class.new(assignable_params.merge(store: current_store))
+            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.assign_attributes(assignable_params)
+
+            if @resource.save
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
           protected
 
           def model_class
@@ -44,8 +65,35 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:name, :code, :active, :default, :preferred_order_routing_strategy,
-                          :preferred_storefront_access, :preferred_guest_checkout)
+            params.permit(*model_additional_permitted_attributes, :name, :code, :active, :default, :preferred_order_routing_strategy,
+                          :preferred_storefront_access, :preferred_guest_checkout,
+                          :default_catalog_id,
+                          stock_location_ids: [])
+          end
+
+          # `stock_location_ids` replaces the channel's fulfillment-origin
+          # allowlist; empty clears it (= every location). Store-scoped
+          # resolution: a foreign location 404s.
+          def assignable_params
+            attributes = permitted_params.except(:stock_location_ids)
+
+            # An incidental lookup like any other: a foreign catalog 404s.
+            if attributes.key?(:default_catalog_id)
+              attributes[:default_catalog_id] =
+                if attributes[:default_catalog_id].present?
+                  current_store.catalogs.find_by_prefix_id!(attributes[:default_catalog_id]).id
+                else
+                  nil
+                end
+            end
+
+            if params.key?(:stock_location_ids)
+              attributes[:stock_locations] = Array(params[:stock_location_ids]).map do |id|
+                current_store.stock_locations.accessible_by(current_ability, :show).find_by_prefix_id!(id)
+              end
+            end
+
+            attributes
           end
 
           private

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ClaimReasonsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::ClaimReason
+          end
+
+          def serializer_class
+            Spree.api.admin_claim_reason_serializer
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :name, :active)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cross-order listing of claims — "what is awaiting resolution across
+        # the whole store". Read-only by route: opening a claim needs an
+        # order, so creation and the status transitions stay on the nested
+        # Orders::ClaimsController.
+        class ClaimsController < ResourceController
+          # Post-sale records are order data: a key that may read orders may
+          # read these, and nothing here writes.
+          scoped_resource :orders
+
+          protected
+
+          def model_class
+            Spree::Claim
+          end
+
+          def serializer_class
+            Spree.api.admin_claim_serializer
+          end
+
+          def collection_includes
+            [:order, :reason, { claim_line_items: :variant }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Discovery for `Spree::CollectionRule` STI subclasses, so the dashboard
+        # can offer every registered rule kind — including ones a plugin adds to
+        # `config.spree.collection_rules` — without hard-coding the list.
+        #
+        # Read-only by design: rules are written through the owning collection's
+        # `rules` sync setter (PATCH /collections/:id), not as a nested resource.
+        class CollectionRulesController < ResourceController
+          # Rule kinds are part of the collections surface — a key that can read
+          # collections can discover the rules it may configure on them.
+          scoped_resource :collections
+
+          def types
+            authorize! :read, model_class
+
+            render json: { data: model_class.subclasses_with_preference_schema }
+          end
+
+          protected
+
+          def model_class
+            Spree::CollectionRule
+          end
+
+          def serializer_class
+            Spree.api.admin_collection_rule_serializer
+          end
+
+          # `types` is read-only discovery — maps to the read scope + :show ability.
+          def read_actions
+            super + %w[types]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Collections
+          # The products curated under a collection — the uniform nested
+          # membership surface (see Spree::Api::V3::Admin::ProductMembership),
+          # plus per-member reposition: listing is ordered by the
+          # ProductCollection position so the merchant's manual ordering
+          # round-trips. Automatic (rule-based) membership is materialized by
+          # the rules, not managed here.
+          class ProductsController < ResourceController
+            include Spree::Api::V3::Admin::ProductMembership
+
+            scoped_resource :products
+
+            before_action :ensure_manual_collection, only: [:create, :destroy, :reposition]
+            before_action :set_product, only: [:reposition]
+
+            # PATCH /api/v3/admin/collections/:collection_id/products/:id/reposition
+            # Body: { new_position: 0 } — 0-based index among the collection's products.
+            # @product is already constrained to the collection's scope, so a
+            # ProductCollection always exists.
+            def reposition
+              position = integer_param(:new_position)
+              return render_invalid_position if position.nil?
+
+              product_collection_for(@product).insert_at(position + 1)
+              # insert_at shifts sibling positions, so refresh every product in the
+              # collection (manual sort reads position from the search index).
+              @parent_collection.products.find_each(&:enqueue_search_index)
+              head :no_content
+            end
+
+            protected
+
+            # The collection's products, ordered by membership position.
+            def scope
+              product_scope.
+                joins(:product_collections).
+                where(Spree::ProductCollection.table_name => { collection_id: @parent_collection.id }).
+                order(Spree::ProductCollection.table_name => { position: :asc })
+            end
+
+            # A product is curated at most once per collection (unique
+            # [collection_id, product_id]), so the join can't duplicate rows —
+            # DISTINCT is unnecessary and breaks Postgres ordering by position.
+            def collection_distinct?
+              false
+            end
+
+            def add_member_products(products)
+              Spree::Collections::AddProducts.call(collections: [@parent_collection], products: products)
+            end
+
+            def remove_member_products(products)
+              Spree::Collections::RemoveProducts.call(collections: [@parent_collection], products: products)
+            end
+
+            # Loads the parent collection (runs before the base set_resource).
+            # Any collection resolves — listing (index) an automatic collection's
+            # rule-materialized membership is valid. Manual-only curation is enforced
+            # separately by +ensure_manual_collection+ on the write actions.
+            def set_parent
+              @parent_collection = Spree::Collection.
+                            accessible_by(current_ability, parent_ability_action).
+                            for_store(current_store).
+                            find_by_prefix_id!(params[:collection_id])
+              authorize_parent!(@parent_collection)
+            end
+
+            private
+
+            # Manual curation (add/remove/reposition) is invalid on automatic
+            # collections: their membership is materialized from rules by
+            # RegenerateProducts, so a manual change would be wiped on the next
+            # regeneration. Listing (index) the materialized membership is fine.
+            def ensure_manual_collection
+              return if @parent_collection.manual?
+
+              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"),
+                status: :unprocessable_content
+              )
+            end
+
+            def set_product
+              @product = scope.find_by_prefix_id!(params[:id])
+            end
+
+            def product_collection_for(product)
+              Spree::ProductCollection.find_by(collection_id: @parent_collection.id, product_id: product.id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin CRUD for collections — the flat, merchandising half of today's
+        # dual-purpose Taxon. Both manual and automatic (rule-based) collections
+        # live here. Reordering is a plain +position+ update (acts_as_list
+        # reorders siblings on save), matching the SPA ResourceTable reorder
+        # convention, so there is no dedicated reposition action.
+        class CollectionsController < ResourceController
+          scoped_resource :collections
+
+          protected
+
+          def model_class
+            Spree::Collection
+          end
+
+          def serializer_class
+            Spree.api.admin_collection_serializer
+          end
+
+          # The serializer always renders the rule set — eager load it.
+          # Eager-loaded unconditionally (as PromotionsController does for its
+          # own rules): the write path reads the association through the `rules=`
+          # sync setter regardless of what the response expands.
+          def scope_includes
+            [:rules]
+          end
+
+          def scope
+            super.ordered
+          end
+
+          # Flat params. +rules+ is applied by the model's sync setter
+          # (Spree::Collection#rules=): the full desired rule set, prefixed
+          # +crule_+ ids update, missing ids build, omitted rules are removed —
+          # so normalize_params is deliberately NOT called (that would rewrite
+          # +rules+ to +rules_attributes+ and route past the setter).
+          def permitted_params
+            params.permit(
+              :name, :description, :permalink, :position,
+              :meta_title, :meta_description, :meta_keywords,
+              :image, :square_image,
+              :automatic, :rules_match_policy, :sort_order,
+              rules: [:id, :type, :value, :match_policy],
+              # Inline custom field values keyed by definition id (see
+              # CategoriesController#permitted_params for the value shapes).
+              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
+            )
+          end
+        end
+      end
+    end
+  end
+end