spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,83 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Typed Spree::Fee rows (surcharge, handling, gift wrap, COD).
+          # Full CRUD — all fee rows are admin-managed. Order-level when no
+          # line_item/fulfillment target is given. Mutations re-sum the order
+          # totals and work on completed orders (sanctioned post-placement
+          # edit path).
+          class FeesController < BaseController
+            scoped_resource :orders
+
+            # POST /api/v3/admin/orders/:order_id/fees
+            def create
+              with_order_lock do
+                result = Spree.order_fee_create_service.call(order: @parent, attributes: permitted_params.merge(target_attributes))
+
+                if result.success?
+                  render json: serialize_resource(result.value), status: :created
+                else
+                  render_validation_error(result.value.errors)
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/fees/:id
+            def update
+              with_order_lock do
+                result = Spree.order_fee_update_service.call(order: @parent, fee: @resource, attributes: permitted_params)
+
+                if result.success?
+                  render json: serialize_resource(@resource)
+                else
+                  render_validation_error(@resource.errors)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/fees/:id
+            def destroy
+              with_order_lock do
+                Spree.order_fee_destroy_service.call(order: @parent, fee: @resource)
+                head :no_content
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Fee
+            end
+
+            def serializer_class
+              Spree.api.admin_fee_serializer
+            end
+
+            def scope
+              @parent.fees
+            end
+
+            def permitted_params
+              params.permit(:label, :amount, :kind)
+            end
+
+            def collection_includes
+              [:line_item, :fulfillment]
+            end
+
+            private
+
+            def target_attributes
+              attributes = {}
+              attributes[:line_item] = @parent.line_items.find_by_prefix_id!(params[:line_item_id]) if params[:line_item_id].present?
+              attributes[:fulfillment] = @parent.fulfillments.find_by_prefix_id!(params[:fulfillment_id]) if params[:fulfillment_id].present?
+              attributes
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,10 +3,18 @@ module Spree
     module V3
       module Admin
         module Orders
+          # The parcels owed on an order.
+          #
+          # Shipping, cancelling and splitting live in the shared concern;
+          # what is here is what makes them the operator's — the store-wide
+          # scope every id in a payload resolves through, and the two actions
+          # only an operator has.
           class FulfillmentsController < BaseController
+            include Spree::Api::V3::Orders::FulfillmentActions
+
             scoped_resource :fulfillments
 
-            before_action :set_resource, only: [:show, :update, :fulfill, :cancel, :resume, :split]
+            before_action :set_resource, only: [:show, :update, :fulfill, :mark_delivered, :cancel, :split]
 
             # POST /api/v3/admin/orders/:order_id/fulfillments
             #
@@ -20,7 +28,7 @@ module Spree
               authorize!(:create, Spree::Shipment)
 
               with_order_lock do
-                result = Spree.fulfillment_create_service.call(
+                result = Spree.fulfillment_create_workflow.call(
                   order: @order,
                   stock_location: stock_location_for_create,
                   items: items_for_create,
@@ -39,101 +47,71 @@ module Spree
               end
             end
 
-            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id
-            def update
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/mark_delivered
+            #
+            # Staff confirming the parcel arrived. Deliberately the operator's
+            # alone: that goods arrived is the buyer's word, not the sender's.
+            def mark_delivered
               with_order_lock do
-                result = Spree.shipment_update_service.call(
-                  shipment: @resource,
-                  shipment_attributes: permitted_params.to_h
+                result = Spree.fulfillment_mark_delivered_workflow.call(
+                  fulfillment: @resource,
+                  delivered_at: mark_delivered_params[:delivered_at],
+                  notify_customer: notify_customer?(mark_delivered_params[:notify_customer])
                 )
 
                 if result.success?
-                  render json: serialize_resource(@resource.reload)
+                  render json: serialize_resource(result.value)
                 else
                   render_result_error(result)
                 end
               end
             end
 
-            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/fulfill
-            def fulfill
-              with_order_lock do
-                @resource.ship!
-                render json: serialize_resource(@resource.reload)
-              rescue StateMachines::InvalidTransition => e
-                render_service_error(e.message)
-              end
-            end
+            protected
 
-            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/cancel
-            def cancel
-              with_order_lock do
-                @resource.cancel!
-                render json: serialize_resource(@resource.reload)
-              rescue StateMachines::InvalidTransition => e
-                render_service_error(e.message)
-              end
+            def serializer_class
+              Spree.api.admin_fulfillment_serializer
             end
 
-            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/resume
-            def resume
-              with_order_lock do
-                @resource.resume!
-                render json: serialize_resource(@resource.reload)
-              rescue StateMachines::InvalidTransition => e
-                render_service_error(e.message)
-              end
+            def collection_includes
+              [:deliveries, { shipping_labels: { file_attachment: :blob } }]
             end
 
-            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/split
-            def split
-              with_order_lock do
-                variant = current_store.variants.find_by_prefix_id!(params[:variant_id])
-                quantity = params[:quantity].to_i
-
-                stock_location = if params[:stock_location_id].present?
-                                   find_stock_location!(params[:stock_location_id])
-                                 else
-                                   @resource.stock_location
-                                 end
-
-                fulfilment_changer = @resource.transfer_to_location(variant, quantity, stock_location)
-
-                if fulfilment_changer.run!
-                  fulfillments = @order.reload.shipments
-                  render json: {
-                    data: fulfillments.map { |s| serialize_resource(s) }
-                  }
-                else
-                  render_validation_error(fulfilment_changer.errors)
-                end
-              end
+            def permitted_params
+              params.permit(:tracking, :tracking_carrier, :selected_delivery_rate_id, :stock_location_id)
             end
 
-            protected
+            private
 
-            def model_class
-              Spree::Shipment
+            # Forcing past a stock or payment guard is the operator's call.
+            def fulfill_permitted_keys
+              super + [:force]
             end
 
-            def serializer_class
-              Spree.api.admin_fulfillment_serializer
+            def fulfill_workflow_options
+              { force: fulfill_params[:force].to_b }
             end
 
-            def parent_association
-              :shipments
+            # The whole catalogue, and any warehouse this staff member may
+            # see: an operator ships anything the store sells.
+            def variant_for_split
+              current_store.variants.find_by_prefix_id!(params[:variant_id])
             end
 
-            # State changes go through the dedicated `fulfill`/`cancel`/`resume`
-            # member actions, not mass assignment.
-            def permitted_params
-              params.permit(:tracking, :selected_delivery_rate_id, :stock_location_id)
+            def stock_location_for_split
+              return @resource.stock_location if params[:stock_location_id].blank?
+
+              find_stock_location!(params[:stock_location_id])
             end
 
             def create_params
               @create_params ||= params.permit(:stock_location_id, :tracking, :delivery_method_id, :cost, :status, metadata: {}, items: [:item_id, :quantity])
             end
 
+            def mark_delivered_params
+              @mark_delivered_params ||= params.permit(:delivered_at, :notify_customer)
+            end
+
             def find_stock_location!(id)
               Spree::StockLocation.accessible_by(current_ability, :show).find_by_prefix_id!(id)
             end

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

@@ -7,17 +7,18 @@ module Spree
             # POST /api/v3/admin/orders/:order_id/items
             def create
               with_order_lock do
-                result = Spree.cart_add_item_service.call(
+                result = Spree.order_add_item_service.call(
                   order: @parent,
                   variant: variant,
                   quantity: permitted_params[:quantity] || 1,
-                  options: permitted_params[:options] || {}
+                  options: permitted_params[:options] || {},
+                  **manual_price_arguments
                 )
 
                 if result.success?
                   render json: serialize_resource(result.value), status: :created
                 else
-                  render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+                  render_order_item_error(result, default_code: ERROR_CODES[:insufficient_stock])
                 end
               end
             end
@@ -25,24 +26,18 @@ module Spree
             # PATCH /api/v3/admin/orders/:order_id/items/:id
             def update
               with_order_lock do
-                if permitted_params[:quantity].present?
-                  result = Spree.cart_set_item_quantity_service.call(
-                    order: @parent,
-                    line_item: @resource,
-                    quantity: permitted_params[:quantity]
-                  )
-
-                  if result.success?
-                    render json: serialize_resource(@resource.reload)
-                  else
-                    render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
-                  end
+                result = Spree.order_update_item_service.call(
+                  order: @parent,
+                  line_item: @resource,
+                  quantity: permitted_params[:quantity],
+                  metadata: permitted_params[:metadata]&.to_h,
+                  **manual_price_arguments
+                )
+
+                if result.success?
+                  render json: serialize_resource(@resource.reload)
                 else
-                  if @resource.update(permitted_params.except(:variant_id, :quantity))
-                    render json: serialize_resource(@resource)
-                  else
-                    render_errors(@resource.errors)
-                  end
+                  render_order_item_error(result, default_code: ERROR_CODES[:invalid_quantity])
                 end
               end
             end
@@ -50,7 +45,7 @@ module Spree
             # DELETE /api/v3/admin/orders/:order_id/items/:id
             def destroy
               with_order_lock do
-                Spree.cart_remove_line_item_service.call(
+                Spree.order_remove_line_item_service.call(
                   order: @parent,
                   line_item: @resource
                 )
@@ -74,14 +69,37 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:variant_id, :quantity, metadata: {}, options: {})
+              params.permit(:variant_id, :quantity, :price, metadata: {}, options: {})
             end
 
             private
 
+            # price is tri-state — absent leaves pricing alone, an amount
+            # negotiates the line, an explicit null reverts to catalog
+            # pricing — so it is forwarded only when the request carried the
+            # key, which also keeps custom services without the keyword
+            # working for every other request.
+            def manual_price_arguments
+              return {} unless params.key?(:price)
+
+              { price: permitted_params[:price] }
+            end
+
             def variant
               @variant ||= current_store.variants.find_by_prefix_id!(permitted_params[:variant_id])
             end
+
+            # Renders a failed add/update with a code inferred from symbolic errors.
+            #
+            # @param result [Spree::ServiceModule::Result] failed service outcome
+            # @param default_code [String] fallback when the error carries no symbol
+            def render_order_item_error(result, default_code:)
+              error = result.error
+              errors = error.respond_to?(:value) ? error.value : error
+              code = infer_line_item_error_code(errors, default: default_code)
+
+              render_service_error(error, code: code)
+            end
           end
         end
       end

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

@@ -0,0 +1,75 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # The postage on a parcel or a return.
+          #
+          # Recording, printing and deleting live in the shared concern. What
+          # is here is what needs the operator's carrier account: buying a
+          # label, and refunding one that was bought and not used.
+          class LabelsController < BaseController
+            include Spree::Api::V3::Orders::ShippingLabelActions
+
+            before_action :set_resource, only: [:show, :download, :refund, :destroy]
+
+            # POST .../labels
+            #
+            # Buys the label through the parcel's provider, or — when a `file`
+            # is given — records one the merchant bought elsewhere.
+            def create
+              authorize!(:create, Spree::ShippingLabel)
+
+              return record_uploaded_label if label_params[:file].present?
+
+              with_order_lock do
+                result = Spree.shipping_label_purchase_workflow.call(owner: @parent)
+
+                if result.success?
+                  render json: serialize_resource(result.value), status: :created
+                else
+                  render_result_error(result)
+                end
+              end
+            end
+
+            # PATCH .../labels/:id/refund — a transition, so a member action.
+            def refund
+              with_order_lock do
+                result = Spree.shipping_label_refund_workflow.call(shipping_label: @resource)
+
+                if result.success?
+                  render json: serialize_resource(result.value)
+                else
+                  render_result_error(result)
+                end
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_shipping_label_serializer
+            end
+
+            def collection_includes
+              [:integration, :delivery, { file_attachment: :blob }]
+            end
+
+            # The owner — fulfillment or return — is the parent the labels
+            # hang off; the base fetches the order first, so an owner id from
+            # another order can never resolve.
+            def set_parent
+              super
+              @parent = if params[:return_id].present?
+                          @order.returns.find_by_prefix_id!(params[:return_id])
+                        else
+                          @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+                        end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -27,32 +27,50 @@ module Spree
 
                 authorize_resource!(@resource, :create)
 
-                if @resource.save
-                  render json: serialize_resource(@resource), status: :created
-                else
-                  render_validation_error(@resource.errors)
-                end
+                render_validation_error(@resource.errors) unless @resource.save
+              end
+              return if performed?
+
+              # Gateway I/O — outside the order lock. A source that cannot be
+              # profiled must not linger on a half-created payment; the old
+              # after_save callback rolled the whole save back.
+              begin
+                @resource.create_payment_profile if @resource.profiles_supported?
+              rescue Spree::Core::GatewayError => e
+                @resource.destroy
+                return render_service_error(e.message)
               end
+
+              render json: serialize_resource(@resource), status: :created
             end
 
             # PATCH /api/v3/admin/orders/:order_id/payments/:id/capture
+            #
+            # Capture and void deliberately skip with_order_lock: the workflows
+            # call the gateway from an external_step, and holding a row lock
+            # across a network round trip is exactly what that boundary exists
+            # to prevent. Both flows are idempotent on replay — an
+            # already-captured or already-void payment returns success.
             def capture
-              with_order_lock do
-                amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
-                @resource.capture!(amount)
-                render json: serialize_resource(@resource.reload)
-              rescue Spree::Core::GatewayError => e
-                render_service_error(e.message)
+              amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
+
+              result = Spree.payment_capture_workflow.call(payment: @resource, amount: amount)
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
               end
             end
 
             # PATCH /api/v3/admin/orders/:order_id/payments/:id/void
             def void
-              with_order_lock do
-                @resource.void_transaction!
-                render json: serialize_resource(@resource.reload)
-              rescue Spree::Core::GatewayError => e
-                render_service_error(e.message)
+              result = Spree.payment_void_workflow.call(payment: @resource)
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
               end
             end
 
@@ -78,9 +96,9 @@ module Spree
             # to that customer to prevent attaching customer A's card to
             # customer B's order. Refuse if no customer is assigned.
             def find_source!(payment_method, source_id)
-              raise ActiveRecord::RecordNotFound unless @parent.user
+              raise ActiveRecord::RecordNotFound unless @parent.customer
 
-              @parent.user.credit_cards.find_by_prefix_id!(source_id)
+              @parent.customer.credit_cards.find_by_prefix_id!(source_id)
             end
           end
         end

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