spree_api 5.6.1 → 6.0.0.beta2

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

@@ -43,12 +43,23 @@ module Spree
             Spree.api.admin_payment_method_serializer
           end
 
-          # Explicit allowlist per the v3 convention — flat params, no
-          # reach into the global `Spree::PermittedAttributes` registry
-          # (which is the legacy Rails admin's surface). `type` and
+          # Explicit allowlist per the v3 convention — flat params. `type` and
           # `preferences` are added by `SubclassedResource` on top.
+          # Deliberately NOT routed through `normalize_params`: gateway
+          # `preferences` are opaque provider values, and prefixed-ID resolution
+          # recurses into nested hashes — a Stripe `webhook_endpoint_id` like
+          # `we_1MqJ8b...` matches the prefixed-ID shape and would be decoded to
+          # an integer. `type` and `preferences` are added by `SubclassedResource`.
           def permitted_params
-            params.permit(:name, :description, :active, :storefront_visible, :auto_capture, :position, metadata: {}, preferences: {})
+            params.permit(
+              :name, :description, :active, :storefront_visible, :auto_capture, :capture_method, :position,
+              *model_additional_permitted_attributes,
+              metadata: {}, preferences: {}
+            )
+          end
+
+          def scope
+            super.ordered
           end
 
           # `types` is read-only discovery — maps to the read scope + :show ability.

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

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # How this installation can pay its sellers, and which of those a store
+        # could use today.
+        #
+        # Discovery rather than CRUD: providers are classes registered in code,
+        # not rows — so there is no serializer, and each class describes itself
+        # (`to_api_hash`), the same shape `/tax_providers` uses.
+        #
+        # Whether a provider needs sellers to hold an account with it is the
+        # part worth surfacing at selection time: choosing one changes what a
+        # marketplace has to ask of its sellers before it can pay them, which
+        # is better known before the choice than after.
+        class PayoutProvidersController < BaseController
+          scoped_resource :settings
+
+          # GET /api/v3/admin/payout_providers
+          def index
+            render json: { data: Spree.payout_providers.map { |provider| provider.to_api_hash(current_store) } }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The permission catalog discovery endpoint — the vocabulary the role
+        # editor and the API-key scope picker render. It is vocabulary, not
+        # data, so any authenticated admin credential may read it (same class
+        # of exemption as `/tags`).
+        #
+        # Staff keys only. Both surfaces this feeds build something owned by
+        # the store — a store role, a secret key — and a key another audience
+        # holds (a seller's own profile or books) would render as an option
+        # that fails validation the moment it is picked.
+        class PermissionsController < Admin::BaseController
+          skip_scope_check!
+
+          # GET /api/v3/admin/permissions
+          def index
+            entries = Spree.permissions.entries
+
+            render json: {
+              data: entries.map { |entry| Spree.api.admin_permission_serializer.new(entry).to_h },
+              meta: { count: entries.size }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The store's own legal documents. A seller's policies belong to the
+        # seller and are managed on the seller branch — this controller never
+        # reaches them, since its scope is the store's own association.
+        class PoliciesController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::Policy
+          end
+
+          def serializer_class
+            Spree.api.admin_policy_serializer
+          end
+
+          def resource_permitted_attributes
+            [:name, :slug, :body]
+          end
+
+          # Accept slug (e.g. returns-policy) or prefixed ID (e.g. pol_abc123),
+          # matching the storefront's lookup.
+          def find_resource
+            if params[:id].to_s.start_with?('pol_')
+              scope.find_by_prefix_id!(params[:id])
+            else
+              scope.friendly.find(params[:id])
+            end
+          end
+
+          def scope
+            super.order(:name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module PriceLists
+          # The products a price list covers — the uniform nested membership
+          # surface (see Spree::Api::V3::Admin::ProductMembership). Membership
+          # is derived from the list's price rows: adding a product
+          # materializes a placeholder price for every variant × store
+          # currency (the spreadsheet's empty cells), removing hard-deletes
+          # its price rows. Unordered — a price list prices, it never
+          # merchandises — so listing is by name.
+          class ProductsController < ResourceController
+            include Spree::Api::V3::Admin::ProductMembership
+
+            # Price lists ride the products scope like their parent
+            # controller — no separate read_price_lists scope.
+            scoped_resource :products
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_price_list_product_serializer
+            end
+
+            # The resolver rides along in the serializer params, preloaded
+            # with this page's variants — one query for the page rather than
+            # one per row (see Catalogs::ProductsController, the same shape).
+            def serializer_params
+              return super unless expanded_keys.include?('price_list_price')
+
+              super.merge(price_list_price_resolver: price_list_price_resolver)
+            end
+
+            # The list read as it stands, draft or not: this is its editor.
+            def price_list_price_resolver
+              @price_list_price_resolver ||=
+                Spree::Catalogs::ResolvePrices.new(price_list: @price_list, currency: current_currency).
+                tap { |resolver| resolver.preload(priced_variants) }
+            end
+
+            def priced_variants
+              Array(@collection).flat_map { |product| product.variants.to_a }
+            end
+
+            # Every row lists its variants and prices each of them, so what
+            # the rows read comes down with the page: the prices the resolver
+            # picks from, the option values that name the variant, the stock
+            # levels behind the flags. `default_variant` separately, since it
+            # is its own belongs_to with a cache of its own.
+            # 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 — the serializer
+            # here is not the admin product serializer and never asks for them.
+            def collection_includes
+              [
+                :primary_media,
+                { variants: [:prices, { option_values: :option_type }] }
+              ]
+            end
+
+            # DISTINCT (the base default): a product joins once per
+            # variant × currency price row.
+            def scope
+              product_scope.
+                joins(variants: :prices).
+                where(Spree::Price.table_name => { price_list_id: @price_list.id }).
+                order(:name)
+            end
+
+            def add_member_products(products)
+              @price_list.add_products(products.map(&:id))
+            end
+
+            def remove_member_products(products)
+              @price_list.remove_products(products.map(&:id))
+            end
+
+            def set_parent
+              @price_list = current_store.price_lists.
+                            accessible_by(current_ability, parent_ability_action).
+                            find_by_prefix_id!(params[:price_list_id])
+              authorize_parent!(@price_list)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,13 +6,12 @@ module Spree
         # (`activate` / `deactivate`) and the spreadsheet's data feed
         # (`prices`).
         #
-        # Everything writable on the list — name, schedule, match policy,
-        # product membership (`product_ids: [...]`), nested rules
-        # (`rules: [...]`), and individual price overrides
-        # (`prices: [...]`) — flows through the regular PATCH payload, so
-        # the SPA saves the entire editor in one round-trip. No separate
-        # add_products / remove_products / add_rule / bulk_update_prices
-        # endpoints.
+        # Everything writable on the list itself — name, schedule, match
+        # policy, nested rules (`rules: [...]`), and individual price
+        # overrides (`prices: [...]`) — flows through the regular PATCH
+        # payload. Product membership lives on the uniform nested surface
+        # (PriceLists::ProductsController), the same protocol categories,
+        # collections and catalogs use.
         #
         # Scoped under the `products` API-key scope — price lists are a
         # product/pricing concern; we don't introduce a separate
@@ -43,17 +42,17 @@ module Spree
 
           # PATCH /api/v3/admin/price_lists/:id/activate
           #
-          # State transition: draft|inactive → active (or → scheduled when
-          # `starts_at` is in the future). Mirrors the old Rails admin's
-          # "Activate" button which automatically scheduled future lists.
+          # draft|inactive → active, or → scheduled when `starts_at` is in the
+          # future. The workflow decides which, so a caller never has to.
           def activate
             authorize! :update, @resource
-            event = @resource.starts_at.present? && @resource.starts_at.future? ? :schedule : :activate
 
-            if @resource.send(event)
+            result = Spree.price_list_activate_workflow.call(price_list: @resource)
+
+            if result.success?
               render json: serialize_resource(@resource)
             else
-              render_validation_error(@resource.errors)
+              render_service_error(result.error)
             end
           end
 
@@ -61,10 +60,12 @@ module Spree
           def deactivate
             authorize! :update, @resource
 
-            if @resource.deactivate
+            result = Spree.price_list_deactivate_workflow.call(price_list: @resource)
+
+            if result.success?
               render json: serialize_resource(@resource)
             else
-              render_validation_error(@resource.errors)
+              render_service_error(result.error)
             end
           end
 
@@ -83,6 +84,7 @@ module Spree
                               .joins(variant: :product)
                               .order(Arel.sql("#{Spree::Product.table_name}.name ASC"))
                               .order(Arel.sql("#{Spree::Variant.table_name}.position ASC"))
+                              .order(min_quantity: :asc)
 
             render json: {
               data: prices.map { |p| serialize_price(p) },
@@ -100,8 +102,23 @@ module Spree
             Spree.api.admin_price_list_serializer
           end
 
+          def create_workflow
+            Spree.price_list_create_workflow
+          end
+
+          def update_workflow
+            Spree.price_list_update_workflow
+          end
+
           def scope
-            super.for_store(current_store)
+            super.ordered
+          end
+
+          # The serializer always renders a list's bands — the pricing card
+          # cannot show a percentage without them — so the index preloads them
+          # rather than paying a query per row.
+          def collection_includes
+            [:price_adjustment_tiers]
           end
 
           def permitted_params
@@ -109,24 +126,20 @@ module Spree
               params.permit(
                 :name, :description, :position,
                 :starts_at, :ends_at, :match_policy,
-                product_ids: [],
+                :price_adjustment_percentage, :adjust_compare_at,
                 rules: [:id, :type, { preferences: {} }],
-                prices: [:id, :variant_id, :currency, :amount, :compare_at_amount]
+                price_adjustment_tiers: [:min_quantity, :percentage],
+                prices: [:id, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount]
               )
             )
-            reject_foreign_membership(attrs)
+            reject_foreign_variants(attrs)
           end
 
-          # The PriceList model setters (`product_ids=`, `prices=`) resolve
-          # member ids with no store scoping, so a list in this store could
-          # otherwise be populated with another store's products/variants.
-          # Drop any id that isn't in the current store before assignment.
-          def reject_foreign_membership(attrs)
-            if attrs[:product_ids].present?
-              store_product_ids = current_store.products.where(id: attrs[:product_ids]).pluck(:id).map(&:to_s).to_set
-              attrs[:product_ids] = Array(attrs[:product_ids]).select { |id| store_product_ids.include?(id.to_s) }
-            end
-
+          # The price rows resolve variant ids with no store scoping, so a
+          # list in this store could otherwise be populated with another
+          # store's variants. Drop any id that isn't in the current store
+          # before assignment.
+          def reject_foreign_variants(attrs)
             if attrs[:prices].present?
               incoming = Array(attrs[:prices])
               store_variant_ids = current_store.variants.where(id: incoming.map { |r| r[:variant_id] }.compact).
@@ -167,6 +180,7 @@ module Spree
               variant_label: variant.options_text.presence,
               sku: variant.sku,
               currency: price.currency,
+              min_quantity: price.min_quantity,
               amount: price.amount&.to_s,
               compare_at_amount: price.compare_at_amount&.to_s
             }

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

@@ -13,8 +13,9 @@ module Spree
           before_action :require_ids!, only: [:bulk_destroy]
           before_action :require_prices!, only: [:bulk_upsert]
 
-          # Bulk-upserts prices on the unique-key triple
-          # `(variant_id, currency, price_list_id)`.
+          # Bulk-upserts prices on the unique key
+          # `(variant_id, currency, price_list_id, min_quantity)` — one row per
+          # rung of a variant's ladder (docs/plans/6.0-volume-pricing.md).
           #
           # @return [void]
           def bulk_upsert
@@ -52,6 +53,41 @@ module Spree
             end
 
             result = Spree::Prices::BulkUpsert.call(rows: rows)
+            # The quantity check and the cap both live in the service, since
+            # every write path reaches it and none of them run model
+            # validations (docs/plans/6.0-volume-pricing.md). Each branch is
+            # guarded on the key its own failure carries, so a failure mode the
+            # service grows later is not reported under one of these names.
+            if (invalid = result.error&.value.try(:[], :invalid_quantities))
+              return render_error(
+                code: 'invalid_min_quantity',
+                message: 'Each quantity break must start at a whole number of units.',
+                status: :unprocessable_content,
+                details: { rows: invalid }
+              )
+            end
+
+            if (negative = result.error&.value.try(:[], :invalid_amounts))
+              return render_error(
+                code: 'invalid_amount',
+                message: Spree.t('activerecord.errors.models.spree/price_list.attributes.base.negative_price').upcase_first,
+                status: :unprocessable_content,
+                details: { rows: negative }
+              )
+            end
+
+            if (over_cap = result.error&.value.try(:[], :over_cap))
+              return render_error(
+                code: 'too_many_breaks',
+                message: Spree.t(
+                  'activerecord.errors.models.spree/price.attributes.min_quantity.too_many_breaks',
+                  count: Spree::Price::MAXIMUM_BREAKS_PER_VARIANT
+                ).upcase_first,
+                status: :unprocessable_content,
+                details: { ladders: over_cap }
+              )
+            end
+
             render json: result.value
           end
 
@@ -84,7 +120,7 @@ module Spree
                 :prices,
                 product: :tax_category,
                 option_values: :option_type,
-                stock_items: [:stock_location, :active_stock_reservations]
+                stock_levels: [:stock_location, :active_stock_reservations]
               ]
             }
           end
@@ -101,7 +137,7 @@ module Spree
           # scopes so a foreign or unknown id 404s instead of binding the
           # price to another store's record.
           def permitted_params
-            permitted = params.permit(:variant_id, :currency, :amount, :compare_at_amount, :price_list_id)
+            permitted = params.permit(*model_additional_permitted_attributes, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount, :price_list_id)
             permitted[:variant_id] = store_variants.find_by_prefix_id!(permitted[:variant_id]).id if permitted[:variant_id].present?
             permitted[:price_list_id] = store_price_lists.find_by_prefix_id!(permitted[:price_list_id]).id if permitted[:price_list_id].present?
             permitted
@@ -140,6 +176,7 @@ module Spree
               variant_id: decode_id(row[:variant_id]),
               price_list_id: row.key?(:price_list_id) ? decode_id(row[:price_list_id]) : nil,
               currency: row[:currency],
+              min_quantity: row[:min_quantity],
               amount: row[:amount],
               compare_at_amount: row[:compare_at_amount]
             }.compact

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

@@ -0,0 +1,93 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Product types are back-office only — there is no Store API counterpart.
+        #
+        # Editing a type never mutates existing products: option types and
+        # categories seed onto products when the type is attached, and the
+        # custom field list is read live when a product form renders. The one
+        # path from a type edit to existing products is `apply_to_products`.
+        class ProductTypesController < ResourceController
+          scoped_resource :product_types
+
+          # Backfills this type's option types and categories onto the products
+          # that already carry it. Additive and idempotent — nothing is removed.
+          def apply_to_products
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            Spree::ProductTypes::ApplyToProductsJob.perform_later(@resource.id)
+
+            render json: { products_count: @resource.products_count.to_i }, status: :accepted
+          end
+
+          protected
+
+          def model_class
+            Spree::ProductType
+          end
+
+          def serializer_class
+            Spree.api.admin_product_type_serializer
+          end
+
+          # The join tables, not the targets — the serializer reports association
+          # ids, so loading the option types and categories themselves would pay
+          # for records nothing reads.
+          def collection_includes
+            [
+              :option_type_product_types,
+              :product_type_categories,
+              { product_type_custom_field_definitions: :custom_field_definition }
+            ]
+          end
+
+          # Single-resource actions need the same eager-loading; without it every
+          # custom field row re-queries its definition.
+          def find_resource
+            scope.includes(collection_includes).find_by_prefix_id!(params[:id])
+          end
+
+          def permitted_params
+            attrs = params.permit(
+              *model_additional_permitted_attributes,
+              :name,
+              :delivery_profile_id,
+              option_type_ids: [],
+              category_ids: [],
+              custom_field_definitions: [:id, :required, :sort_order]
+            )
+            attrs = scope_delivery_profile(attrs)
+            scope_category_ids(attrs)
+          end
+
+          # The template profile must belong to this store — a cross-store id
+          # 404s instead of silently linking.
+          def scope_delivery_profile(attrs)
+            return attrs unless params.key?(:delivery_profile_id)
+
+            attrs[:delivery_profile] = if params[:delivery_profile_id].present?
+                                            current_store.delivery_profiles.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_profile_id])
+                                          end
+            attrs.except(:delivery_profile_id)
+          end
+
+          # `category_ids=` resolves prefixed ids with no store scoping, so a
+          # type in this store could otherwise be pointed at another store's
+          # categories. Mirrors ProductsController#apply_categories.
+          # (OptionType is global — nothing to scope there.)
+          def scope_category_ids(attrs)
+            return attrs if attrs[:category_ids].blank?
+
+            category_ids = decode_ids(attrs[:category_ids], Spree::Category)
+            attrs[:category_ids] = current_store.categories.
+                                   accessible_by(current_ability, :update).
+                                   where(id: category_ids).pluck(:id)
+            attrs
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/products/digital_assets_controller.rb

@@ -0,0 +1,148 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Products
+          class DigitalAssetsController < ResourceController
+            scoped_resource :products
+
+            # PATCH /api/v3/admin/products/:product_id/digital_assets/:id
+            #
+            # Replacing the file keeps every already-issued link working, since
+            # links resolve through the asset rather than the blob.
+            def update
+              return render_private_storage_error unless uploaded_blob_private?
+
+              # The asset already exists, so attaching a replacement blob writes
+              # to the database immediately, while the update below renders a 422
+              # without raising when it fails. Wrap both so a failed update rolls
+              # the new attachment back rather than leaving the file swapped but
+              # the record unchanged.
+              model_class.transaction do
+                @resource.variant = requested_variant if params[:variant_id].present?
+                attach_uploaded_file(@resource)
+
+                super
+
+                raise ActiveRecord::Rollback if @resource.errors.any?
+              end
+            end
+
+            # POST /api/v3/admin/products/:product_id/digital_assets
+            def create
+              return render_private_storage_error unless uploaded_blob_private?
+
+              super
+            end
+
+            # GET /api/v3/admin/products/:product_id/digital_assets/providers
+            #
+            # The sources a merchant can pick for a new asset: the uploaded-file
+            # default plus any host-registered provider. Drives the dashboard's
+            # source selector; a host with only the default sees just "upload".
+            def providers
+              authorize! :create, model_class
+
+              data = Spree.digital_asset_providers.map do |provider_class|
+                {
+                  type: provider_class.to_s,
+                  name: provider_class.provider_name,
+                  requires_attachment: provider_class.requires_attachment?,
+                  settings_schema: provider_class.settings_schema
+                }
+              end
+
+              render json: { data: data }
+            end
+
+            protected
+
+            def model_class
+              Spree::DigitalAsset
+            end
+
+            def serializer_class
+              Spree.api.admin_digital_asset_serializer
+            end
+
+            def set_parent
+              @parent = current_store.products.find_by_prefix_id!(params[:product_id])
+              authorize!(:show, @parent)
+            end
+
+            def parent_association
+              :digital_assets
+            end
+
+            # The parent association reaches assets through `variants`, which
+            # carries an ORDER BY on the variants table. Combined with the
+            # collection's DISTINCT, PostgreSQL rejects the query outright
+            # (ordering columns must appear in the select list), so order by
+            # the assets' own table instead. SQLite accepts either form, so
+            # this only fails on a real deployment.
+            def scope
+              super.reorder(created_at: :asc)
+            end
+
+            def scope_includes
+              [:variant, { attachment_attachment: :blob }]
+            end
+
+            # variant_id is resolved through the parent rather than assigned:
+            # mass-assigning it would let a caller point an asset at a variant
+            # of any product, in any store. signed_id likewise names a blob
+            # rather than a column, so it is attached separately.
+            # provider_type is mass-assignable: the model validates it names a
+            # registered provider, so an unknown value is a 422, not a hazard.
+            # provider_settings is an open hash — its keys are declared by the
+            # provider, not fixed here — so it is permitted as arbitrary scalars
+            # and lands verbatim under one key in the asset's metadata.
+            def permitted_params
+              params.permit(:authorized_clicks, :authorized_days, :provider_type, provider_settings: {})
+            end
+
+            private
+
+            # A product without explicit variants keeps its file on the default
+            # variant, mirroring how the rest of the admin treats such products.
+            def build_resource
+              digital_asset = super
+              digital_asset.variant = requested_variant || @parent.default_variant
+              attach_uploaded_file(digital_asset)
+              digital_asset
+            end
+
+            # Scoped to the parent, not merely to the store: an asset reached
+            # through a product's route has no business pointing at another
+            # product's variant. An id from anywhere else is a 404.
+            def requested_variant
+              return if params[:variant_id].blank?
+
+              @parent.variants.find_by_prefix_id!(params[:variant_id])
+            end
+
+            def attach_uploaded_file(digital_asset)
+              return if params[:signed_id].blank?
+
+              digital_asset.attachment.attach(params[:signed_id])
+            end
+
+            # Attaching never moves a blob between storage services, so a file
+            # uploaded to the public bucket would stay publicly readable while
+            # looking attached. Refuse it rather than storing it wrongly.
+            def uploaded_blob_private?
+              return true if params[:signed_id].blank?
+
+              blob = ActiveStorage::Blob.find_signed(params[:signed_id])
+              blob.present? && blob.service_name.to_s == Spree.private_storage_service_name.to_s
+            end
+
+            def render_private_storage_error
+              render_validation_error(Spree.t(:digital_assets_attachment_must_be_private))
+            end
+          end
+        end
+      end
+    end
+  end
+end