spree_api 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,86 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Applies/removes a discount code on a draft order — the admin
+          # counterpart of the storefront cart endpoint, with the same pending
+          # semantics: a real-but-not-yet-eligible code is kept and activates
+          # on the first recalculation where the order qualifies. Completed
+          # orders are frozen; their discounts change only through manual rows
+          # (see DiscountsController).
+          class DiscountCodesController < BaseController
+            skip_before_action :set_resource, raise: false
+
+            # POST /api/v3/admin/orders/:order_id/discount_codes
+            def create
+              with_order_lock do
+                return render_completed_order_error if @parent.completed?
+
+                @parent.coupon_code = permitted_params[:code]
+
+                coupon_handler.apply
+
+                if coupon_handler.successful? || pending_eligibility?
+                  @parent.save!(validate: false) if @parent.changed?
+                  render json: serialize_resource(@parent.reload), status: :created
+                else
+                  @parent.update_column(:coupon_code, nil) if @parent.read_attribute(:coupon_code).present?
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/discount_codes/:id
+            # :id is the discount code string.
+            def destroy
+              with_order_lock do
+                return render_completed_order_error if @parent.completed?
+
+                coupon_handler.remove(params[:id])
+
+                if coupon_handler.successful?
+                  render json: serialize_resource(@parent.reload)
+                else
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Order
+            end
+
+            def serializer_class
+              Spree.api.admin_order_serializer
+            end
+
+            private
+
+            def coupon_handler
+              @coupon_handler ||= Spree.coupon_handler.new(@parent, enable_gift_cards: false)
+            end
+
+            def pending_eligibility?
+              coupon_handler.status_code == :coupon_code_not_eligible
+            end
+
+            def render_completed_order_error
+              render_error(
+                code: ERROR_CODES[:discount_not_editable],
+                message: Spree.t('errors.messages.coupon_code_frozen_after_completion'),
+                status: :unprocessable_content
+              )
+            end
+
+            def permitted_params
+              params.permit(:code)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Typed Spree::Discount rows on an order. Manual rows have full CRUD;
+          # promotion-sourced rows are read-only (recalculation owns them) and
+          # respond 422 to update/destroy. Mutations re-sum the order totals —
+          # this is the sanctioned post-placement discount path and works on
+          # completed orders.
+          class DiscountsController < BaseController
+            scoped_resource :orders
+
+            # POST /api/v3/admin/orders/:order_id/discounts
+            def create
+              with_order_lock do
+                line_item = @parent.line_items.find_by_prefix_id!(params[:line_item_id]) if params[:line_item_id].present?
+
+                result = Spree.order_discount_create_service.call(
+                  order: @parent,
+                  label: params[:label],
+                  value: params[:value].presence || params[:amount],
+                  value_type: params[:value_type].presence || 'flat',
+                  line_item: line_item
+                )
+
+                if result.success?
+                  render json: { data: serialize_collection(result.value) }, status: :created
+                else
+                  render_error(code: ERROR_CODES[:validation_error], message: result.error.to_s, status: :unprocessable_entity)
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/discounts/:id
+            def update
+              with_order_lock do
+                result = Spree.order_discount_update_service.call(order: @parent, discount: @resource, attributes: permitted_params)
+
+                if result.success?
+                  render json: serialize_resource(@resource)
+                elsif result.error.value == :promotion_discount_not_editable
+                  render_promotion_row_error
+                else
+                  render_validation_error(@resource.errors)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/discounts/:id
+            def destroy
+              with_order_lock do
+                result = Spree.order_discount_destroy_service.call(order: @parent, discount: @resource)
+
+                if result.success?
+                  head :no_content
+                else
+                  render_promotion_row_error
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Discount
+            end
+
+            def serializer_class
+              Spree.api.admin_discount_serializer
+            end
+
+            def scope
+              @parent.discounts
+            end
+
+            def permitted_params
+              params.permit(:label, :amount)
+            end
+
+            def collection_includes
+              [:promotion, :line_item, :fulfillment]
+            end
+
+            private
+
+            def render_promotion_row_error
+              render_error(
+                code: ERROR_CODES[:discount_not_editable],
+                message: Spree.t('errors.messages.promotion_discount_not_editable'),
+                status: :unprocessable_entity
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Exchanges on a completed order. Each status change is its own
+          # member action, because each carries different arguments.
+          class ExchangesController < BaseController
+            include Spree::Api::V3::Orders::ExchangeActions
+
+            # Exchanges are a subject of the `orders` catalog resource, so
+            # `read_orders`/`write_orders` gate these endpoints. `:exchanges`
+            # would name a key no catalog knows.
+            scoped_resource :orders
+
+            before_action :set_resource, only: [:show, :update, :approve, :receive, :fulfill, :cancel]
+
+            # PATCH /api/v3/admin/orders/:order_id/exchanges/: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_exchange_serializer
+            end
+
+            def collection_includes
+              [:reason, :stock_location, { exchange_line_items: [:original_variant, :new_variant] }]
+            end
+
+            def permitted_params
+              params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+            end
+
+            private
+
+            # The whole store's catalogue, and any warehouse the caller may
+            # see: an operator exchanges into anything the store sells.
+            def replacement_variant_for(variant_id)
+              current_store.variants.find_by_prefix_id!(variant_id)
+            end
+
+            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/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