spree_api 5.6.1 → 6.0.0.beta1

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

@@ -4,6 +4,7 @@ module Spree
       module Admin
         class ProductsController < ResourceController
           include Spree::Api::V3::BulkOperations
+          include Spree::Api::V3::Admin::ProductListing
 
           scoped_resource :products
 
@@ -11,6 +12,8 @@ module Spree
             :bulk_status_update,
             :bulk_add_to_categories,
             :bulk_remove_from_categories,
+            :bulk_add_to_collections,
+            :bulk_remove_from_collections,
             :bulk_add_to_channels,
             :bulk_remove_from_channels,
             :bulk_destroy
@@ -29,6 +32,20 @@ module Spree
             end
           end
 
+          # PATCH /api/v3/admin/products/:id/approve
+          #
+          # Accepting a product a seller submitted, putting it on sale.
+          def approve
+            run_review_workflow(Spree.product_approve_workflow)
+          end
+
+          # PATCH /api/v3/admin/products/:id/reject
+          #
+          # Turning a submission down. The reason goes back to the seller.
+          def reject
+            run_review_workflow(Spree.product_reject_workflow, reason: params[:reason])
+          end
+
           # POST /api/v3/admin/products/bulk_status_update
           # Body: { ids: [...], status: 'draft' | 'active' | 'archived' }
           def bulk_status_update
@@ -42,23 +59,47 @@ module Spree
               )
             end
 
-            count = bulk_collection.update_all(status: params[:status], updated_at: Time.current)
+            # Products in review are excluded rather than refused: a bulk
+            # activate over a mixed selection should still do the plain ones,
+            # and moving the rest is `approve`/`reject`, which records who
+            # decided (docs/plans/6.0-seller-product-submission.md).
+            movable = bulk_collection.where.not(status: Spree::Product::REVIEW_STATUSES)
+            skipped = bulk_collection.where(status: Spree::Product::REVIEW_STATUSES).count
+
+            count = movable.update_all(status: params[:status], updated_at: Time.current)
             # `update_all` skips `after_commit`, so the search index won't refresh on its own.
-            bulk_collection.each(&:enqueue_search_index)
+            movable.each(&:enqueue_search_index)
+
+            payload = { product_count: count, status: params[:status] }
+            # Only when it happened: a key on every response would say
+            # "nothing was skipped" to clients that never skip anything.
+            payload[:skipped_in_review_count] = skipped if skipped.positive?
 
-            render json: { product_count: count, status: params[:status] }
+            render json: payload
           end
 
           # POST /api/v3/admin/products/bulk_add_to_categories
           # Body: { ids: [...], category_ids: [...] }
           def bulk_add_to_categories
-            apply_categories(Spree::Taxons::AddProducts)
+            apply_categories(Spree::Categories::AddProducts)
           end
 
           # POST /api/v3/admin/products/bulk_remove_from_categories
           # Body: { ids: [...], category_ids: [...] }
           def bulk_remove_from_categories
-            apply_categories(Spree::Taxons::RemoveProducts)
+            apply_categories(Spree::Categories::RemoveProducts)
+          end
+
+          # POST /api/v3/admin/products/bulk_add_to_collections
+          # Body: { ids: [...], collection_ids: [...] }
+          def bulk_add_to_collections
+            apply_collections(Spree::Collections::AddProducts)
+          end
+
+          # POST /api/v3/admin/products/bulk_remove_from_collections
+          # Body: { ids: [...], collection_ids: [...] }
+          def bulk_remove_from_collections
+            apply_collections(Spree::Collections::RemoveProducts)
           end
 
           # POST /api/v3/admin/products/bulk_add_to_channels
@@ -101,6 +142,17 @@ module Spree
             render json: { product_count: destroyed }
           end
 
+          # DELETE /api/v3/admin/products/:id
+          def destroy
+            result = Spree.product_destroy_workflow.call(product: @resource)
+
+            if result.success?
+              head :no_content
+            else
+              render_result_error(result)
+            end
+          end
+
           protected
 
           def model_class
@@ -111,14 +163,12 @@ module Spree
             Spree.api.admin_product_serializer
           end
 
-          def scope_includes
-            [
-              :tax_category,
-              product_publications: :channel,
-              primary_media: [attachment_attachment: :blob],
-              master: [:prices, stock_items: [:stock_location, :active_stock_reservations]],
-              variants: [:prices, stock_items: [:stock_location, :active_stock_reservations]]
-            ]
+          def create_workflow
+            Spree.product_create_workflow
+          end
+
+          def update_workflow
+            Spree.product_update_workflow
           end
 
           # Use SearchProvider::Database for collection to handle price/best_selling
@@ -157,56 +207,108 @@ module Spree
             # docs/plans/6.0-remove-master-variant.md.
             #
             # Top-level `prices` is a convenience for simple (no-options)
-            # products: the merchant doesn't need to know the master variant
-            # exists, so they ship prices alongside name/status and the
-            # `Spree::Product#prices=` setter forwards them to the master.
+            # products: the merchant doesn't need to know about the default
+            # variant, so they ship prices alongside name/status and the
+            # `Spree::Product#prices=` setter forwards them to it.
             params.permit(
+              *model_additional_permitted_attributes,
               :name, :description, :slug, :status,
               :meta_title, :meta_description, :meta_keywords,
-              :tax_category_id,
-              :promotionable, :digital,
+              :tax_category_id, :product_type_id, :delivery_profile_id,
+              :promotionable,
               tags: [],
               category_ids: [],
+              # Manual collection membership only — the model setter ignores
+              # incoming automatic collections and preserves the product's
+              # existing ones, since those are materialized from their rules.
+              #
+              # Deliberately reachable with `write_products` rather than
+              # `write_collections`: filing a product into its groupings is part
+              # of maintaining the product, which is why `category_ids` and the
+              # bulk membership endpoints have always worked this way too.
+              # Creating or configuring a collection still needs
+              # `write_collections`.
+              collection_ids: [],
               metadata: {},
               prices: [:amount, :compare_at_amount, :currency],
               # Inline custom field values keyed by definition id. The model
-              # setter (`Spree::Metafields#custom_fields=`) validates each
+              # setter (`Spree::HasCustomFields#custom_fields=`) validates each
               # entry against its definition. We permit `value` as a scalar AND
-              # as `value: []` / `value: {}` so JSON metafields round-trip
+              # as `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: {} }],
-              # Inline media. Entries with `id` patch an existing asset
-              # (alt, position, variant_ids). Entries with `signed_id` create
-              # + attach a fresh upload. Lets the dashboard ship media changes
-              # alongside the rest of the product form. See
-              # `Spree::Product#media=`.
-              media: [:id, :signed_id, :alt, :position, :type, variant_ids: []],
+              # Inline media. Entries with `id` patch an existing asset.
+              # Entries with `signed_id` create + attach a fresh upload; an
+              # external video creates with a URL and no file. Lets the
+              # dashboard ship media changes alongside the rest of the product
+              # form. See `Spree::Products::NestedAttributes`.
+              #
+              # `external_url` is deliberately not permitted here: it makes the
+              # server fetch a URL the caller chose, so it belongs to trusted
+              # importers rather than to a request body.
+              media: [*Spree::Media::WRITABLE_ATTRIBUTES, :id, :signed_id, :source_media_id, { variant_ids: [] }],
+              # Inline digital files, so a new product ships its downloadable
+              # files in the same request. Additive: an entry carries a
+              # `signed_id` (uploaded file) or a `provider_type` (provider-backed
+              # asset), and an `id` patches that asset in place rather than
+              # building a duplicate — so replaying a product's list on update
+              # does not accumulate copies. Removal uses the nested
+              # digital_assets endpoint. See `Spree::Product#digital_assets=`.
+              digital_assets: [:id, :signed_id, :variant_id, :provider_type, :authorized_clicks, :authorized_days, provider_settings: {}],
               product_publications: [:id, :channel_id, :published_at, :unpublished_at],
               variants: [
                 :id, :sku, :barcode,
                 :cost_price, :cost_currency,
                 :weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
+                :hs_code, :country_of_origin, :customs_description,
+                :minimum_order_quantity, :order_multiple, :purchase_unit, :units_per_carton,
+                :carton_package_type_id, :carton_weight, :cartons_per_pallet,
+                :seller_id, :delivery_profile_id,
                 :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
                 options: [:name, :value],
                 prices: [:amount, :compare_at_amount, :currency],
-                stock_items: [:id, :stock_location_id, :count_on_hand, :backorderable]
+                stock_levels: [:id, :stock_location_id, :count_on_hand, :backorderable]
               ]
-            )
+            ).tap { |attrs| attrs.delete(:status) if review_status?(attrs[:status]) }
+          end
+
+          # A review status is an outcome, not a value to assign: `proposed`
+          # means a seller asked, and `rejected` means somebody decided. Both
+          # are reached through the workflows behind `approve`/`reject`, so a
+          # status naming one here is dropped rather than written — the same
+          # reason `bulk_status_update` validates against `STATUSES` and not
+          # the full list (docs/plans/6.0-seller-product-submission.md).
+          def review_status?(status)
+            status.present? && Spree::Product::REVIEW_STATUSES.include?(status.to_s)
           end
 
           private
 
+          # Approving and rejecting are edits to the catalog, so they answer to
+          # the same key as any other product write.
+          def run_review_workflow(workflow, **arguments)
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            result = workflow.call(product: @resource, reviewer: try_spree_current_user, **arguments)
+
+            if result.success?
+              render json: serialize_resource(@resource.reload)
+            else
+              render_service_error(@resource.errors.presence || result.error)
+            end
+          end
+
           def search_provider
             @search_provider ||= Spree::SearchProvider::Database.new(current_store)
           end
 
-          # Mirrors `Spree::Admin::ProductsController#after_bulk_tags_change`:
-          # tag changes can flip automatic-taxon matches, and `Tags::Bulk*`
+          # Tag changes can flip automatic-collection matches, and `Tags::Bulk*`
           # touch records via `touch_all` (which skips `after_commit`), so the
           # search index needs an explicit kick.
           def after_bulk_tags_change
-            Spree::Product.bulk_auto_match_taxons(current_store, bulk_collection.ids)
+            Spree::Product.bulk_auto_match_collections(current_store, bulk_collection.ids)
             bulk_collection.each(&:enqueue_search_index)
           end
 
@@ -221,12 +323,26 @@ module Spree
             categories = current_store.categories.
                          accessible_by(current_ability, :update).where(id: category_ids)
 
-            service.call(taxons: categories, products: bulk_collection)
-            Spree::Product.bulk_auto_match_taxons(current_store, bulk_collection.ids)
+            service.call(categories: categories, products: bulk_collection)
 
             render json: { product_count: bulk_collection.size, category_count: categories.size }
           end
 
+          def apply_collections(service)
+            authorize! :update, model_class
+
+            # Only manual collections accept curation — automatic membership is
+            # rebuilt from rules, so a manual add/remove would be lost on the next
+            # regeneration (mirrors apply_categories, whose association is manual).
+            collection_ids = decode_ids(params[:collection_ids])
+            collections = current_store.collections.manual.
+                          accessible_by(current_ability, :update).where(id: collection_ids)
+
+            service.call(collections: collections, products: bulk_collection)
+
+            render json: { product_count: bulk_collection.size, collection_count: collections.size }
+          end
+
           def scoped_channels
             channel_ids = decode_ids(params[:channel_ids])
             current_store.channels.accessible_by(current_ability, :manage).where(id: channel_ids)

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

@@ -30,9 +30,13 @@ module Spree
             klass = resolve_subclass(params[:type])
             return render_unknown_type unless klass && klass.respond_to?(:calculators)
 
+            # `api_type`, not the Ruby class name: it is what the action
+            # serializer reports for the calculator a record already has, and
+            # what a client matches against to find it in this list. The write
+            # path accepts either form.
             data = klass.calculators.map do |calc|
               {
-                type: calc.to_s,
+                type: calc.api_type,
                 label: calc.respond_to?(:description) ? calc.description : calc.to_s.demodulize.titleize,
                 preference_schema: calc.respond_to?(:serialized_preference_schema) ? calc.serialized_preference_schema : []
               }
@@ -52,7 +56,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:type, preferences: {})
+            params.permit(*model_additional_permitted_attributes, :type, preferences: {})
           end
 
           # `types`/`calculators` are read-only discovery — read scope + :show ability.

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

@@ -30,7 +30,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:type, preferences: {})
+            params.permit(*model_additional_permitted_attributes, :type, preferences: {})
           end
 
           # `types` is read-only discovery — maps to the read scope + :show ability.

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

@@ -29,11 +29,7 @@ module Spree
           # every built-in rule/action's expected keys. Plugin-defined
           # subclasses can add to it — see `additional_permitted_attributes`
           # below.
-          def permitted_params
-            normalize_params(params.permit(*permitted_attributes))
-          end
-
-          def permitted_attributes
+          def resource_permitted_attributes
             [
               :name, :description, :code, :path,
               :starts_at, :expires_at, :usage_limit, :match_policy,

data/app/controllers/spree/api/v3/admin/purchase_orders/stock_receipts_controller.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module PurchaseOrders
+          # The deliveries booked against one purchase order. Recording one
+          # is how the order is received: this is the moment purchased goods
+          # first count toward availability.
+          class StockReceiptsController < ResourceController
+            include Spree::Api::V3::Admin::StockReceiptActions
+
+            scoped_resource :purchasing
+
+            protected
+
+            def set_parent
+              @parent = current_store.purchase_orders.find_by_prefix_id!(params[:purchase_order_id])
+            end
+
+            def create_workflow
+              Spree.purchase_order_receive_workflow
+            end
+
+            def receivable_keyword
+              :purchase_order
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Goods bought from a supplier.
+        #
+        # Ordered units never count toward availability: nothing here touches
+        # `count_on_hand` until `receive` runs, because a merchant who has
+        # ordered stock does not have it.
+        #
+        # Each status change is its own member action rather than a PATCH that
+        # mass-assigns `status`, because receiving carries the quantities the
+        # warehouse counted.
+        class PurchaseOrdersController < ResourceController
+          include Spree::Api::V3::Admin::ReceivableActions
+
+          scoped_resource :purchasing
+
+          # The base registers this for show/update/destroy; a second
+          # `before_action :set_resource` replaces that registration rather than
+          # adding to it, so those three are listed again here.
+          before_action :set_resource, only: [:show, :update, :destroy, :mark_ordered, :mark_draft, :close, :cancel]
+
+          # DELETE /api/v3/admin/purchase_orders/:id
+          #
+          # Only a draft. Once the order has gone to the supplier it is a
+          # matter of record between two businesses, and is cancelled rather
+          # than deleted.
+          def destroy
+            return super if @resource.draft?
+
+            render_error(
+              code: 'invalid_status',
+              message: Spree.t('purchase_order.errors.only_draft_can_be_deleted'),
+              status: :unprocessable_content
+            )
+          end
+
+          # PATCH /api/v3/admin/purchase_orders/:id/mark_ordered
+          def mark_ordered
+            result = Spree.purchase_order_mark_ordered_workflow.call(purchase_order: @resource)
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/purchase_orders/:id/receive
+          # PATCH /api/v3/admin/purchase_orders/:id/mark_draft
+          def mark_draft
+            result = Spree.purchase_order_mark_draft_workflow.call(purchase_order: @resource)
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/purchase_orders/:id/close
+          #
+          # Deliveries are recorded through the nested stock receipts; this is
+          # for the balance that is not coming.
+          def close
+            result = Spree.purchase_order_close_workflow.call(purchase_order: @resource, reason: params[:reason])
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/purchase_orders/:id/cancel
+          def cancel
+            result = Spree.purchase_order_cancel_workflow.call(
+              purchase_order: @resource,
+              reason: params[:reason],
+              canceler: try_spree_current_user
+            )
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          protected
+
+          def model_class
+            Spree::PurchaseOrder
+          end
+
+          def serializer_class
+            Spree.api.admin_purchase_order_serializer
+          end
+
+          def collection_includes
+            [:supplier, :destination_location, line_includes]
+          end
+
+          def create_workflow
+            Spree.purchase_order_create_workflow
+          end
+
+          def update_workflow
+            Spree.purchase_order_update_workflow
+          end
+
+          def create_workflow_arguments
+            {
+              store: current_store,
+              supplier: supplier_from_params,
+              destination_location: stock_location_from(:destination_location_id),
+              items: items_from_params(:quantity_ordered, :unit_cost) || [],
+              currency: params[:currency],
+              expected_at: params[:expected_at],
+              cancel_by: params[:cancel_by],
+              reference: params[:reference],
+              notes: params[:notes],
+              created_by: try_spree_current_user
+            }
+          end
+
+          def update_workflow_arguments
+            {
+              purchase_order: @resource,
+              attributes: editable_attributes,
+              items: items_from_params(:quantity_ordered, :unit_cost)
+            }
+          end
+
+          # The supplier and the warehouse are resolved through the store
+          # instead, since an id the payload names has to be proved to belong
+          # here.
+          def resource_permitted_attributes
+            [:currency, :expected_at, :cancel_by, :reference, :notes, { metadata: {} }]
+          end
+
+          def editable_attributes
+            attributes = permitted_params.to_h.symbolize_keys
+            attributes[:supplier] = supplier_from_params if params.key?(:supplier_id)
+            if params.key?(:destination_location_id)
+              attributes[:destination_location] = stock_location_from(:destination_location_id)
+            end
+            attributes
+          end
+
+          def scope_includes
+            [line_includes]
+          end
+
+          private
+
+          # Read through `current_store` rather than the model constant: a
+          # supplier id belonging to another store must 404, which no ability
+          # check would catch.
+          #
+          # @return [Spree::Supplier, nil]
+          def supplier_from_params
+            return nil if params[:supplier_id].blank?
+
+            current_store.suppliers.accessible_by(current_ability, :show).
+              find_by_prefix_id!(params[:supplier_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class RefundReasonsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::RefundReason
+          end
+
+          def serializer_class
+            Spree.api.admin_refund_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/reporting/saved_reports_controller.rb

@@ -0,0 +1,45 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Reporting
+          # Store-wide saved reports (docs/plans/6.0-analytics-semantic-layer.md,
+          # Decision 12). Reads ride `read_reports`, mutations `write_reports`;
+          # the stored query is validated against the registry on save, and
+          # every viewer is re-authorized when the report is executed through
+          # the query endpoint.
+          class SavedReportsController < ResourceController
+            scoped_resource :reports
+
+            protected
+
+            def model_class
+              Spree::SavedReport
+            end
+
+            def serializer_class
+              Spree.api.admin_saved_report_serializer
+            end
+
+            def scope_includes
+              [:user]
+            end
+
+            # Deliberately NOT routed through `normalize_params`: the stored
+            # query carries filter values such as `cust_…`/`ch_…` prefixed ids
+            # inside a nested hash, and prefixed-ID resolution recurses into
+            # nested hashes — they would be decoded to integers on save and
+            # never resolve again. Extension attributes are splatted in.
+            def permitted_params
+              params.permit(:name, :description, *model_additional_permitted_attributes, query: {})
+            end
+
+            def build_resource
+              super.tap { |report| report.user = try_spree_current_user }
+            end
+          end
+        end
+      end
+    end
+  end
+end