spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # The registration the order was taxed against, frozen at completion.
+          # Read-only because the row is: staff investigating why an invoice was
+          # zero-rated need to see the number and the verdict behind it, not
+          # change what the invoice already says.
+          class TaxIdentifiersController < BaseController
+            # A singular nested resource: there is no :id to look up, and the
+            # inherited lookup would reach for a plural association that does
+            # not exist. Mirrors Orders::StoreCreditsController.
+            skip_before_action :set_resource, raise: false
+
+            scoped_resource :orders
+
+            # GET /api/v3/admin/orders/:order_id/tax_identifier
+            def show
+              return head :not_found if @parent.tax_identifier.nil?
+
+              authorize_resource!(@parent.tax_identifier, :show)
+
+              render json: serialize_resource(@parent.tax_identifier)
+            end
+
+            protected
+
+            def model_class
+              Spree::TaxIdentifier
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_identifier_serializer
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/orders/tax_lines_controller.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Read-only: tax lines are written exclusively by the tax provider.
+          class TaxLinesController < BaseController
+            scoped_resource :orders
+
+            protected
+
+            def model_class
+              Spree::TaxLine
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_line_serializer
+            end
+
+            def scope
+              @parent.tax_lines
+            end
+
+            def collection_includes
+              [:tax_rate, :line_item, :fulfillment, :fee]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,8 +7,14 @@ module Spree
 
           scoped_resource :orders
 
+          # The order accepts a `po_document` signed blob id and streams it back.
+          include ActiveStorage::SetCurrent
+
+          # A tampered signed id would otherwise surface as a 500.
+          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document
+
           skip_before_action :set_resource, only: [:index, :create]
-          before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resume, :resend_confirmation]
+          before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resend_confirmation, :resend_digital_links, :po_document]
 
           # POST /api/v3/admin/orders
           def create
@@ -16,7 +22,8 @@ module Spree
 
             result = Spree.order_create_service.call(
               store: current_store,
-              user: resolve_user,
+              customer: resolve_customer,
+              created_by: try_spree_current_user,
               params: order_create_params
             )
 
@@ -49,7 +56,7 @@ module Spree
             with_order_lock do
               result = Spree.order_complete_service.call(
                 order: @resource,
-                payment_pending: ActiveModel::Type::Boolean.new.cast(params[:payment_pending]),
+                payment_pending: params[:payment_pending].to_b,
                 notify_customer: ActiveModel::Type::Boolean.new.cast(params[:notify_customer])
               )
 
@@ -64,8 +71,21 @@ module Spree
           # PATCH /api/v3/admin/orders/:id/cancel
           def cancel
             with_order_lock do
-              @resource.canceled_by(try_spree_current_user)
-              render json: serialize_resource(@resource.reload)
+              result = Spree.order_cancel_workflow.call(
+                order: @resource,
+                canceler: try_spree_current_user,
+                reason: cancel_reason,
+                note: params[:cancel_note].presence,
+                refund_payments: params[:refund_payments].to_b,
+                refund_amount: params[:refund_amount].presence,
+                notify_customer: params[:notify_customer].to_b
+              )
+
+              if result.success?
+                render json: serialize_resource(@resource.reload)
+              else
+                render_service_error(@resource.errors.presence || result.error)
+              end
             end
           end
 
@@ -77,22 +97,50 @@ module Spree
             end
           end
 
-          # PATCH /api/v3/admin/orders/:id/resume
-          def resume
-            with_order_lock do
-              @resource.resume!
-              render json: serialize_resource(@resource.reload)
-            end
-          end
-
           # POST /api/v3/admin/orders/:id/resend_confirmation
           def resend_confirmation
-            @resource.publish_event('order.completed')
+            @resource.publish_event('order.resend_confirmation_email')
             render json: serialize_resource(@resource)
           end
 
+          # POST /api/v3/admin/orders/:id/resend_digital_links
+          def resend_digital_links
+            @resource.publish_event('order.resend_digital_links_email')
+            render json: serialize_resource(@resource)
+          end
+
+          # GET /api/v3/admin/orders/:id/po_document
+          #
+          # The buyer's purchase order, streamed rather than redirected so the
+          # document is never reachable without admin credentials.
+          def po_document
+            unless @resource.po_document.attached?
+              return render_error(
+                code: ERROR_CODES[:validation_error],
+                message: Spree.t(:po_document_missing),
+                status: :unprocessable_content
+              )
+            end
+
+            send_data(
+              @resource.po_document.download,
+              filename: @resource.po_document.filename.to_s,
+              type: @resource.po_document.content_type || 'application/octet-stream',
+              disposition: 'attachment'
+            )
+          end
+
           protected
 
+          # Fetching the document is a read of the order, so it takes the read
+          # scope rather than being classed as a write for not being index or
+          # show.
+          READ_ACTIONS = %w[index show po_document].freeze
+
+          def read_actions
+            READ_ACTIONS
+          end
+
           def model_class
             Spree::Order
           end
@@ -101,13 +149,25 @@ module Spree
             Spree.api.admin_order_serializer
           end
 
-          # Override scope — Order uses SingleStoreResource (for_store)
+          # Override scope — Order uses SingleStoreResource (for_store).
+          # Variant prices are preloaded here rather than via scope_includes,
+          # which this override bypasses; the serializer reads them per row.
           def scope
-            current_store.orders.accessible_by(current_ability, :show).preload_associations_lazily
+            base = current_store.orders.accessible_by(current_ability, :show).
+                   includes(line_items: { variant: :prices }).preload_associations_lazily
+
+            # Transient completion drafts (status draft + cart_id set) belong
+            # to in-flight checkouts, never to the admin. Admin drafts are the
+            # cart-less ones.
+            base.where(cart_id: nil).or(base.where.not(status: 'draft'))
           end
 
+          # Through find_resource, not find_by_prefix_id! directly, so the
+          # external:<system>:<id> addressing the concern provides reaches
+          # orders — an ERP that pushed its order number wants to read the
+          # order back by it.
           def set_resource
-            @resource = scope.find_by_prefix_id!(params[:id])
+            @resource = find_resource
             @order = @resource # needed for OrderLock
             authorize_resource!(@resource)
           end
@@ -115,35 +175,81 @@ module Spree
           # Map state transition actions to :update permission
           def authorize_resource!(resource = @resource, action = action_name.to_sym)
             mapped_action = case action
-                            when :complete, :cancel, :approve, :resume, :resend_confirmation
+                            when :complete, :cancel, :approve, :resend_confirmation, :resend_digital_links
                               :update
+                            when :po_document
+                              :show
                             else
                               action
                             end
             authorize!(mapped_action, resource)
           end
 
+          # seller is preloaded because its id is read on every row and an
+          # expanded list renders the whole profile; order_group is not, since
+          # only its id is reported and that comes off the order's own column.
+          # Variant prices ride along because the admin line-item serializer
+          # reads the base catalog price for every row (the negotiated-price
+          # comparison); without it each line costs its own price query.
           def collection_includes
-            [:line_items, :user, :channel, :rich_text_internal_note]
+            # `market` is the withdrawal deadline's other input. Fulfillments
+            # are loaded with their selected rate because the freight summary
+            # reads it — otherwise a page of orders costs a query per
+            # fulfillment for a field that is nil on every parcel order.
+            [:customer, :channel, :seller, :external_references, :cancel_reason,
+             :market, { fulfillments: :selected_delivery_rate },
+             { line_items: { variant: :prices } }, { po_document_attachment: :blob }]
+          end
+
+          # Read through the store's own vocabulary, so a reason belonging to
+          # another store is a 404 rather than a silent mislabel.
+          def cancel_reason
+            id = params[:cancel_reason_id].presence
+            return if id.nil?
+
+            current_store.order_cancellation_reasons.find_by_prefix_id!(id)
           end
 
           private
 
-          def resolve_user
-            customer_param = params[:customer_id].presence || params[:user_id].presence
+          def render_invalid_po_document
+            render_error(
+              code: ERROR_CODES[:validation_error],
+              message: Spree.t(:po_document_invalid_signed_id),
+              status: :unprocessable_content
+            )
+          end
+
+          def resolve_customer
+            customer_param = params[:customer_id].presence
             return unless customer_param
 
-            Spree.user_class.find_by_param!(customer_param)
+            Spree.customer_class.
+              accessible_by(current_ability, :show).
+              find_by_prefix_id!(customer_param)
+          end
+
+          # An upsert arrives on the create action, so addresses come in under
+          # the create names. Translate them to the ones update accepts, or a
+          # replayed feed row would silently lose the address it sent.
+          def normalize_upsert_params!
+            # update runs under with_order_lock, which reads @order — normally
+            # set by set_resource, which the create path never runs.
+            @order = @resource
           end
 
           def order_create_params
-            normalize_params(
+            permitted = normalize_params(
               params.permit(
-                :email, :customer_id, :user_id, :use_customer_default_address,
+                :email, :customer_id, :use_customer_default_address,
                 :currency, :market_id, :channel_id, :locale,
                 :customer_note, :internal_note,
+                # The buyer's own purchase-order reference, and the signed blob
+                # id of the document behind it — a PO arriving by email and
+                # keyed in is the draft-order flow plus these two fields.
+                :po_number, :po_document,
                 :shipping_address_id, :billing_address_id,
-                :preferred_stock_location_id,
+                :preferred_stock_location_id, :company_id,
                 :coupon_code,
                 metadata: {},
                 tags: [],
@@ -152,36 +258,55 @@ module Spree
                 items: item_permitted_keys
               )
             )
+            resolve_company_param(permitted)
           end
 
           def order_update_params
-            normalize_params(
+            permitted = normalize_params(
               params.permit(
-                :email, :customer_id, :user_id,
+                :email, :customer_id,
                 :customer_note, :internal_note,
+                :po_number, :po_document,
                 :currency, :locale, :market_id, :channel_id,
-                :preferred_stock_location_id,
+                :preferred_stock_location_id, :company_id,
                 metadata: {},
                 tags: [],
-                ship_address: address_permitted_keys,
-                bill_address: address_permitted_keys,
+                shipping_address: address_permitted_keys,
+                billing_address: address_permitted_keys,
                 items: item_permitted_keys
               )
             )
+            resolve_company_param(permitted)
+          end
+
+          # An incidental lookup like any other: resolved through the store so
+          # another tenant's node 404s instead of surfacing as a validation
+          # error (which would confirm the id exists). Reads the raw param —
+          # normalize_params has already decoded the prefixed id.
+          def resolve_company_param(permitted)
+            return permitted unless permitted.key?(:company_id)
+
+            permitted[:company_id] =
+              if params[:company_id].present?
+                current_store.companies.find_by_prefix_id!(params[:company_id]).id
+              else
+                nil
+              end
+            permitted
           end
 
           def address_permitted_keys
             [
               :firstname, :lastname, :first_name, :last_name,
               :address1, :address2, :city,
-              :country_iso, :state_abbr, :country_id, :state_id,
+              :country_code, :state_code,
               :zipcode, :postal_code, :phone, :alternative_phone,
               :state_name, :company, :label
             ]
           end
 
           def item_permitted_keys
-            [:variant_id, :quantity, { metadata: {} }]
+            [:variant_id, :quantity, :price, { metadata: {} }]
           end
         end
       end

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The store's packaging vocabulary. Marking one row default makes it
+        # the box the store's own parcel quotes are built on; the model
+        # demotes whichever row held the flag before.
+        #
+        # On a marketplace this lists every row in the store, the operator's
+        # and each seller's, so `q[seller_id_eq]` narrows it to one owner. A
+        # row the operator writes here is the marketplace's: `seller_id` is
+        # not writable, and a seller's own packaging is theirs to edit through
+        # the seller API (docs/plans/6.0-seller-package-types.md).
+        class PackageTypesController < ResourceController
+          scoped_resource :package_types
+
+          protected
+
+          def model_class
+            Spree::PackageType
+          end
+
+          def serializer_class
+            Spree.api.admin_package_type_serializer
+          end
+
+          def collection_includes
+            [:seller]
+          end
+
+          def resource_permitted_attributes
+            [:name, :kind, :length, :width, :height, :dimensions_unit,
+             :weight, :max_weight, :weight_unit, :default, { metadata: {} }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -60,7 +60,7 @@ module Spree
               # password. Revoke first, then mint the fresh token for this
               # browser (the auto-sign-in below).
               Spree::RefreshToken.revoke_all_for(user)
-              refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+              refresh_token = Spree::RefreshToken.create_for(user, audience: JWT_AUDIENCE_ADMIN, request_env: request_env_for_token)
               set_refresh_cookie(refresh_token)
 
               render json: auth_response(user)

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