spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Catalogs
+          # Anything nested under a catalog. The parent resolves through the
+          # store, so a catalog belonging to another tenant is a 404 rather
+          # than a readable record.
+          class BaseController < ResourceController
+            scoped_resource :products
+
+            protected
+
+            def set_parent
+              @parent = current_store.catalogs.
+                        accessible_by(current_ability, parent_ability_action).
+                        find_by_prefix_id!(params[:catalog_id])
+              @catalog = @parent
+            end
+
+            def authorize_parent_access!
+              authorize_parent!(@parent)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Catalogs
+          # The least a whole order must come to under a catalog's agreement.
+          # One row per currency — never one amount with a currency beside
+          # it, because Spree holds no exchange rates.
+          class OrderMinimumsController < BaseController
+            before_action :authorize_parent_access!
+
+
+            protected
+
+            def model_class
+              Spree::CatalogOrderMinimum
+            end
+
+            def serializer_class
+              Spree.api.admin_catalog_order_minimum_serializer
+            end
+
+            def scope
+              @parent.order_minimums
+            end
+
+            def parent_association
+              :order_minimums
+            end
+
+            def permitted_params
+              params.permit(:currency, :amount)
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Catalogs
+          # The products curated into a catalog's assortment — the uniform
+          # nested membership surface (see
+          # Spree::Api::V3::Admin::ProductMembership). A catalog decides what
+          # a buyer sees, never the order they see it in, so membership
+          # carries no position and listing is ordered by name.
+          class ProductsController < BaseController
+            include Spree::Api::V3::Admin::ProductMembership
+
+            before_action :authorize_parent_access!
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_catalog_product_serializer
+            end
+
+            # The resolver rides along in the serializer params, preloaded
+            # with this page's variants: resolving row by row would be a query
+            # per product, and the answer is the same for every row on the
+            # page.
+            # `expanded_keys` is the same dot-notation matching the serializer's
+            # own `expand?` does, so the attribute never renders without the
+            # resolver that fills it.
+            def serializer_params
+              params = super
+              params = params.merge(catalog_price_resolver: catalog_price_resolver) if expanded_keys.include?('catalog_price')
+              params = params.merge(catalog_quantity_rules: quantity_rules_by_product) if expanded_keys.include?('quantity_rule')
+              params
+            end
+
+            # The page's quantity rules in one query, keyed by product. The
+            # rows are stored per variant and read per product, which is the
+            # roll-up the serializer does — on variants this page has already
+            # loaded (docs/plans/6.0-volume-pricing.md).
+            def quantity_rules_by_product
+              @quantity_rules_by_product ||= begin
+                variant_ids = priced_variants.map(&:id)
+                rules = variant_ids.any? ? @catalog.quantity_rules.where(variant_id: variant_ids).to_a : []
+                product_by_variant = priced_variants.to_h { |variant| [variant.id, variant.product_id] }
+
+                rules.group_by { |rule| product_by_variant[rule.variant_id] }
+              end
+            end
+
+            # Preloaded with every variant the page renders — each row now
+            # prices its variants individually, so preloading only the buy-box
+            # winner would leave the rest falling through to a query apiece
+            # (docs/plans/6.0-volume-pricing.md).
+            def catalog_price_resolver
+              @catalog_price_resolver ||=
+                Spree::Catalogs::ResolvePrices.new(catalog: @catalog, currency: current_currency).
+                tap { |resolver| resolver.preload(priced_variants) }
+            end
+
+            def priced_variants
+              Array(@collection).flat_map { |product| product.variants.to_a }
+            end
+
+            # Only what this page reads: the card's thumbnail, and every
+            # variant with the rows and option values the resolver and the
+            # variant rows need. `default_variant` is deliberately absent —
+            # it is a separate `belongs_to` with a cache of its own, so
+            # reading it here would re-query option values per row. Publications, stock levels and the default
+            # variant's own prices are deliberately absent — this endpoint
+            # serializes the membership shape, not a full admin product
+            # (docs/plans/6.0-volume-pricing.md).
+            def collection_includes
+              [
+                :primary_media,
+                { variants: [:prices, { option_values: :option_type }] }
+              ]
+            end
+
+            def scope
+              product_scope.
+                joins(:catalog_products).
+                where(Spree::CatalogProduct.table_name => { catalog_id: @catalog.id }).
+                order(:name)
+            end
+
+            # A product is curated at most once per catalog (unique
+            # [catalog_id, product_id]), so the join can't duplicate rows and
+            # DISTINCT is unnecessary.
+            def collection_distinct?
+              false
+            end
+
+            def add_member_products(products)
+              @catalog.add_products(products.map(&:id))
+            end
+
+            # Through the model, so an owned price list drops the rows it
+            # held for these products along with them.
+            def remove_member_products(products)
+              @catalog.remove_products(products.map(&:id))
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Catalogs
+          # A catalog's quantity terms — the narrowest of the three levels a
+          # buyer's rules resolve through. The catalog-wide default is a pair
+          # of fields on the catalog itself, so this surface is strictly the
+          # overrides.
+          #
+          # Rows are stored per variant and written as a whole set, because
+          # that is the grain a merchant states them at ("minimum 48 of this
+          # product") and the dashboard stages every edit behind the catalog's
+          # Save — a partial application would leave an agreement half-changed.
+          #
+          # There is no read action: the rules are read back on the assortment
+          # rows (`expand=quantity_rule` on this catalog's products), which
+          # already hold the variants they roll up
+          # (docs/plans/6.0-volume-pricing.md).
+          class QuantityRulesController < BaseController
+            before_action :authorize_parent_access!
+
+            # PUT /api/v3/admin/catalogs/:catalog_id/quantity_rules
+            #
+            # { terms: { "prod_abc": { minimum_order_quantity: 48,
+            #                          order_multiple: 24 } } }
+            #
+            # A product whose pair is both null has its terms cleared.
+            def upsert
+              authorize! :update, @catalog
+
+              result = Spree::Catalogs::SetProductTerms.call(catalog: @catalog, terms: resolved_terms)
+
+              if result.success?
+                head :no_content
+              else
+                render_service_error(result)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::CatalogQuantityRule
+            end
+
+            def serializer_class
+              Spree.api.admin_catalog_quantity_rule_serializer
+            end
+
+            def scope
+              @catalog.quantity_rules
+            end
+
+            def parent_association
+              :quantity_rules
+            end
+
+            private
+
+            # Products resolve through this store, so an id belonging to
+            # another tenant is a 404 rather than a term written against a
+            # product the merchant does not sell.
+            def resolved_terms
+              params.require(:terms).to_unsafe_h.to_h do |product_id, values|
+                product = current_store.products.find_by_prefix_id!(product_id)
+                [product, values.to_h.symbolize_keys.slice(:minimum_order_quantity, :order_multiple)]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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