spree_api 5.6.0 → 6.0.0.beta1

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

@@ -7,24 +7,36 @@ module Spree
             scoped_resource :refunds
 
             # POST /api/v3/admin/orders/:order_id/refunds
+            #
+            # Deliberately not wrapped in with_order_lock: the workflow calls
+            # the gateway from an external_step, and holding a row lock across
+            # a network round trip is exactly what that boundary exists to
+            # prevent. Refund#perform! is a no-op on a credited refund, so a
+            # double submit cannot credit twice.
             def create
-              with_order_lock do
-                payment = @parent.payments.accessible_by(current_ability, :update).find_by_prefix_id!(params[:payment_id])
-                reason = Spree::RefundReason.accessible_by(current_ability, :show).find_by_prefix_id!(params[:refund_reason_id]) if params[:refund_reason_id].present?
-                reason ||= Spree::RefundReason.accessible_by(current_ability, :show).first
-
-                @resource = payment.refunds.build(
-                  amount: params[:amount],
-                  reason: reason,
-                  transaction_id: nil
-                )
-                authorize_resource!(@resource, :create)
-
-                if @resource.save
-                  render json: serialize_resource(@resource), status: :created
-                else
-                  render_validation_error(@resource.errors)
-                end
+              payment = settlement_payments.accessible_by(current_ability, :update).find_by_prefix_id!(params[:payment_id])
+              # Scoped to the store, not just the ability — a reason id from
+              # another store must 404, not attach.
+              reason = current_store.refund_reasons.accessible_by(current_ability, :show).find_by_prefix_id!(params[:refund_reason_id]) if params[:refund_reason_id].present?
+              reason ||= current_store.refund_reasons.accessible_by(current_ability, :show).first
+
+              authorize_resource!(payment.refunds.build(amount: params[:amount], reason: reason), :create)
+
+              result = Spree.refund_create_workflow.call(
+                payment: payment,
+                amount: params[:amount],
+                reason: reason,
+                refunder: try_spree_current_user,
+                # Names which order is being refunded. Only matters when the
+                # payment is shared by a split checkout, where it covers several
+                # and the payment cannot say which one this is for.
+                order: @parent
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value), status: :created
+              else
+                render_result_error(result)
               end
             end
 
@@ -38,8 +50,17 @@ module Spree
               Spree.api.admin_refund_serializer
             end
 
+            # Every refund names the order it put right, so this reads the same
+            # for an ordinary order and for one placed in a split checkout,
+            # whose payments belong to its group rather than to itself.
             def scope
-              Spree::Refund.where(payment_id: @parent.payment_ids)
+              Spree::Refund.where(order_id: @parent.id)
+            end
+
+            # The payments that can settle this order — its own, or its group's
+            # when it was placed alongside others.
+            def settlement_payments
+              @parent.settlement_payments
             end
 
             def collection_includes

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

@@ -0,0 +1,70 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Returns on a completed order. Every status change goes through its
+          # own member action rather than mass assignment, because each one is
+          # a workflow with its own arguments — receiving carries the
+          # quantities the warehouse counted, refunding carries a method and
+          # an amount.
+          class ReturnsController < BaseController
+            include Spree::Api::V3::Orders::ReturnActions
+
+            # Returns are a subject of the `orders` catalog resource (see
+            # Spree::PermissionConfiguration), so `read_orders`/`write_orders`
+            # gate these endpoints — matching the cross-order ReturnsController.
+            # Declaring `:returns` here would name a key no catalog knows: the
+            # JWT gate would silently no-op and a `write_orders` secret key
+            # would be wrongly denied.
+            scoped_resource :orders
+
+            before_action :set_resource, only: [:show, :update, :approve, :receive, :refund, :cancel]
+
+            # PATCH /api/v3/admin/orders/:order_id/returns/:id
+            #
+            # Editable fields only — status moves through the member actions.
+            def update
+              if @resource.update(permitted_params)
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_return_serializer
+            end
+
+            # `documents` resolves the provider through the returned units and
+            # reads the labels it produced, so both are preloaded: without them
+            # a page of returns is a query per row.
+            def collection_includes
+              [
+                :reason, :stock_location, :deliveries,
+                { shipping_labels: { file_attachment: :blob } },
+                { return_line_items: [:variant, :line_item, { fulfillment_item: :fulfillment }] }
+              ]
+            end
+
+            def permitted_params
+              params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+            end
+
+            private
+
+            # Any of the store's warehouses the caller may see.
+            def stock_location_for_create
+              return nil if create_params[:stock_location_id].blank?
+
+              current_store.stock_locations.accessible_by(current_ability, :show).
+                find_by_prefix_id!(create_params[:stock_location_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Spree
             # credit up to the order total.
             def create
               with_order_lock do
-                result = Spree.checkout_add_store_credit_service.call(
+                result = Spree.store_credit_apply_service.call(
                   order: @parent,
                   amount: params[:amount].try(:to_f)
                 )
@@ -30,7 +30,7 @@ module Spree
             # DELETE /api/v3/admin/orders/:order_id/store_credits
             def destroy
               with_order_lock do
-                result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+                result = Spree.store_credit_remove_service.call(order: @parent)
 
                 if result.success?
                   head :no_content

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