spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb

@@ -10,16 +10,23 @@ module Spree
             before_action :find_cart!
 
             # POST  /api/v3/store/carts/:cart_id/discount_codes
-            # Apply a discount code to the cart
+            # Applies a discount code. A real-but-not-yet-eligible code is
+            # accepted and persisted — recalculation activates the discount
+            # the moment the cart qualifies (Shopify-parity). Unknown/expired
+            # codes are rejected and never persisted.
             def create
               with_order_lock do
                 @cart.coupon_code = permitted_params[:code]
 
                 coupon_handler.apply
 
-                if coupon_handler.successful?
+                if coupon_handler.successful? || pending_eligibility?
+                  @cart.save!(validate: false) if @cart.changed?
+                  @cart.reload
+                  attach_pending_coupon_warning if pending_eligibility?
                   render_cart(status: :created)
                 else
+                  @cart.update_column(:coupon_code, nil) if @cart.read_attribute(:coupon_code).present?
                   render_errors(coupon_handler.error)
                 end
               end
@@ -46,6 +53,21 @@ module Spree
               @coupon_handler ||= Spree.coupon_handler.new(@cart, enable_gift_cards: false)
             end
 
+            # A real code on a cart that doesn't qualify yet: the code is
+            # kept and recalculation activates it later.
+            def pending_eligibility?
+              coupon_handler.status_code == :coupon_code_not_eligible
+            end
+
+            # The code is kept for Shopify-parity retry-on-recalculation, but
+            # the shopper still needs to hear why nothing applied yet.
+            def attach_pending_coupon_warning
+              @cart.warnings |= [{
+                code: coupon_handler.status_code.to_s,
+                message: coupon_handler.error.presence || Spree.t(:coupon_code_not_eligible)
+              }]
+            end
+
             def permitted_params
               params.permit(:code)
             end

data/app/controllers/spree/api/v3/store/carts/fulfillments_controller.rb

@@ -11,7 +11,7 @@ module Spree
 
             # GET /api/v3/store/carts/:cart_id/fulfillments
             def index
-              fulfillments = @cart.shipments.includes(shipping_rates: :shipping_method)
+              fulfillments = @cart.fulfillments.includes(delivery_rates: :delivery_method)
               render json: {
                 data: fulfillments.map { |s| Spree.api.fulfillment_serializer.new(s, params: serializer_params).to_h },
                 meta: { count: fulfillments.size }
@@ -19,18 +19,22 @@ module Spree
             end
 
             # PATCH /api/v3/store/carts/:cart_id/fulfillments/:id
-            # Select a delivery rate for a specific fulfillment
+            # Selects a delivery rate, and for pickup_point methods a concrete
+            # pickup point (validated against the provider, then frozen into
+            # pickup_point_data).
             def update
               with_order_lock do
-                fulfillment = @cart.shipments.find_by_prefix_id!(params[:id])
+                fulfillment = @cart.fulfillments.find_by_prefix_id!(params[:id])
 
                 if permitted_params[:selected_delivery_rate_id].present?
                   fulfillment.selected_delivery_rate_id = permitted_params[:selected_delivery_rate_id]
                 end
 
-                # Auto-advance (e.g. delivery → payment) after rate selection.
-                # Temporary — Spree 6 removes the checkout state machine.
-                try_advance
+                if permitted_params[:pickup_point_external_id].present?
+                  return unless assign_pickup_point(fulfillment, permitted_params[:pickup_point_external_id])
+                end
+
+                recalculate
 
                 render_cart
               end
@@ -39,22 +43,44 @@ module Spree
             private
 
             def permitted_params
-              params.permit(:selected_delivery_rate_id)
+              params.permit(:selected_delivery_rate_id, :pickup_point_external_id)
             end
 
-            # Temporary — Spree 6 removes the checkout state machine.
-            def try_advance
-              return if @cart.confirm? || @cart.complete? || @cart.canceled?
+            def recalculate
+              return if @cart.complete?
 
-              loop do
-                break if @cart.payment?
-                break unless @cart.next
-              end
+              @cart.recalculate_totals!
             rescue StandardError => e
-              Rails.error.report(e, context: { order_id: @cart.id, state: @cart.state }, source: 'spree.checkout')
+              Rails.error.report(e, context: { order_id: @cart.id }, source: 'spree.checkout')
             ensure
               @cart.reload
             end
+
+            # @return [Boolean] false when the response has already been rendered
+            def assign_pickup_point(fulfillment, external_id)
+              provider = fulfillment.delivery_method&.pickup_point_provider_instance
+              if provider.nil?
+                render_error(
+                  code: ERROR_CODES[:validation_error],
+                  message: Spree.t('errors.messages.no_pickup_point_provider'),
+                  status: :unprocessable_entity
+                )
+                return false
+              end
+
+              point = provider.find_by_external_id(external_id)
+              if point.nil?
+                render_error(
+                  code: ERROR_CODES[:record_not_found],
+                  message: Spree.t('errors.messages.pickup_point_not_found'),
+                  status: :not_found
+                )
+                return false
+              end
+
+              fulfillment.update!(pickup_point_data: point.to_pickup_point_data)
+              true
+            end
           end
         end
       end

data/app/controllers/spree/api/v3/store/carts/items_controller.rb

@@ -12,18 +12,18 @@ module Spree
             # POST  /api/v3/store/carts/:cart_id/items
             def create
               with_order_lock do
-                result = Spree.cart_add_item_service.call(
-                  order: @cart,
+                result = Spree.cart_add_item_workflow.call(
+                  cart: @cart,
                   variant: variant,
                   quantity: permitted_params[:quantity] || 1,
                   metadata: permitted_params[:metadata] || {},
-                  options: permitted_params[:options] || {}
+                  options: item_options
                 )
 
                 if result.success?
                   render_cart(status: :created)
                 else
-                  render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+                  render_result_error(result)
                 end
               end
             end
@@ -33,24 +33,40 @@ module Spree
               with_order_lock do
                 @line_item = @cart.line_items.find_by_prefix_id!(params[:id])
 
-                @line_item.metadata = @line_item.metadata.merge(permitted_params[:metadata].to_h) if permitted_params[:metadata].present?
-
                 if permitted_params[:quantity].present?
-                  result = Spree.cart_set_item_quantity_service.call(
-                    order: @cart,
-                    line_item: @line_item,
-                    quantity: permitted_params[:quantity]
+                  # Zero and negatives remove the row in the upsert vocabulary,
+                  # but this endpoint documents `quantity >= 1` and DELETE is
+                  # how a client removes an item. Deleting on a PATCH the
+                  # schema forbids would be a surprising 200.
+                  if permitted_params[:quantity].to_i < 1
+                    return render_error(
+                      code: ERROR_CODES[:invalid_quantity],
+                      message: Spree.t('cart_line_item.quantity_must_be_positive'),
+                      status: :unprocessable_content
+                    )
+                  end
+
+                  result = Spree.cart_upsert_items_workflow.call(
+                    cart: @cart,
+                    items: [{
+                      variant_id: @line_item.variant_id,
+                      quantity: permitted_params[:quantity],
+                      metadata: permitted_params[:metadata]
+                    }]
                   )
 
                   if result.success?
                     render_cart
                   else
-                    render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+                    render_result_error(result)
                   end
-                elsif @line_item.changed?
-                  @line_item.save!
-                  render_cart
                 else
+                  # Metadata-only edit — no quantity change, so no item rules
+                  # to run and nothing for the cart to recalculate.
+                  if permitted_params[:metadata].present?
+                    @line_item.update!(metadata: @line_item.metadata.merge(permitted_params[:metadata].to_h))
+                  end
+
                   render_cart
                 end
               end
@@ -61,23 +77,40 @@ module Spree
               with_order_lock do
                 @line_item = @cart.line_items.find_by_prefix_id!(params[:id])
 
-                Spree.cart_remove_line_item_service.call(
-                  order: @cart,
-                  line_item: @line_item
+                result = Spree.cart_upsert_items_workflow.call(
+                  cart: @cart,
+                  items: [{ variant_id: @line_item.variant_id, quantity: 0 }]
                 )
 
-                render_cart
+                if result.success?
+                  render_cart
+                else
+                  render_result_error(result)
+                end
               end
             end
 
             private
 
             def variant
-              @variant ||= current_store.variants.accessible_by(current_ability).find_by_prefix_id!(permitted_params[:variant_id])
+              @variant ||= current_store.variants.find_by_prefix_id!(permitted_params[:variant_id])
+            end
+
+            # Extension attributes ride in `options`, which is how AddItem
+            # forwards per-line-item values onto the record.
+            def item_options
+              keys = Spree::LineItem.additional_permitted_attributes.flat_map { |a| a.is_a?(Hash) ? a.keys : a }
+              extras = permitted_params.to_h.slice(*keys.map(&:to_s)).symbolize_keys
+
+              (permitted_params[:options] || {}).to_h.symbolize_keys.merge(extras)
             end
 
             def permitted_params
-              params.permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
+              params.permit(
+                :id, :variant_id, :quantity,
+                *Spree::LineItem.additional_permitted_attributes,
+                { metadata: {}, options: {} }
+              )
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb

@@ -54,25 +54,27 @@ module Spree
             end
 
             # PATCH /api/v3/store/carts/:cart_id/payment_sessions/:id/complete
+            #
+            # Deliberately not wrapped in with_order_lock: the workflow verifies
+            # the session with the gateway from an external_step, and holding a
+            # row lock across that round trip is what the boundary exists to
+            # prevent. Concurrency is enforced where the invariant lives —
+            # PaymentSession#settle_payment! takes the owner's row lock around
+            # the local settlement, so a confirm racing the webhook (or a
+            # double-submitted confirm) records the capture exactly once, and a
+            # replay on a completed session is an idempotent success.
             def complete
-              with_order_lock do
-                @payment_session.reload
-
-                if @payment_session.completed?
-                  render json: serialize_resource(@payment_session)
-                  return
-                end
-
-                @payment_session.payment_method.complete_payment_session(
-                  payment_session: @payment_session,
-                  params: complete_params
-                )
-
-                if @payment_session.errors.empty?
-                  render json: serialize_resource(@payment_session.reload)
-                else
-                  render_errors(@payment_session.errors)
-                end
+              result = Spree.payment_session_complete_workflow.call(
+                payment_session: @payment_session.reload,
+                params: complete_params
+              )
+
+              if result.success? && @payment_session.errors.empty?
+                render json: serialize_resource(result.value)
+              elsif result.success?
+                render_errors(@payment_session.errors)
+              else
+                render_result_error(result)
               end
             end
 
@@ -83,7 +85,11 @@ module Spree
             end
 
             def permitted_params
-              params.permit(Spree::PermittedAttributes.payment_session_attributes)
+              params.permit(
+                :amount, :payment_method_id,
+                *Spree::PaymentSession.additional_permitted_attributes,
+                { external_data: {} }
+              )
             end
 
             def complete_params
@@ -100,9 +106,19 @@ module Spree
             def serialize_resource(resource)
               serializer_class.new(resource, params: serializer_params).to_h
             end
+
+            protected
+
+            # Payment confirmation races cart completion (a webhook can finish
+            # checkout before the customer returns) — only the idempotent
+            # confirm replay resolves completed carts. Creating or updating a
+            # session on a finished checkout stays a 404.
+            def find_cart!
+              super(include_completed: action_name == 'complete')
+            end
           end
         end
       end
     end
   end
-end
+end

data/app/controllers/spree/api/v3/store/carts/po_documents_controller.rb

@@ -0,0 +1,111 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Carts
+          # The buyer's purchase-order document — the signed paperwork the
+          # `po_number` on the cart refers to
+          # (docs/plans/6.0-b2b-customer-po-numbers.md).
+          #
+          # Presigning is nested under the cart rather than offered as a general
+          # store upload endpoint: a publishable key is public, so an
+          # unconditional presigner would let anyone holding one mint blobs in
+          # the merchant's bucket. Reaching this action means holding the cart.
+          #
+          # Blobs are minted on private storage, because attaching a signed id
+          # never moves a blob between services and a purchase order carries the
+          # buyer's prices, terms and internal cost codes.
+          class PoDocumentsController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
+            include ActiveStorage::SetCurrent
+
+            before_action :find_cart!
+
+            # POST /api/v3/store/carts/:cart_id/po_document
+            #
+            # Exchanges blob metadata for an upload URL. The returned signed id
+            # is then sent back as `po_document` on a cart update, which is what
+            # actually attaches it.
+            #
+            # The declared size and type are checked here, before any URL is
+            # minted. A guest cart is self-service, so without this an
+            # anonymous caller could mint uploads for arbitrarily large files
+            # and fill the merchant's bucket — the attachment's own validation
+            # only runs once the bytes are already stored. It is a gate on the
+            # cheap lie, not a substitute: the attach-time check still reads
+            # the stored object, which is what catches an under-declared size.
+            def create
+              return render_po_document_invalid unless acceptable_upload?
+
+              blob = ActiveStorage::Blob.create_before_direct_upload!(
+                service_name: Spree.private_storage_service_name, **blob_params
+              )
+
+              render json: {
+                direct_upload: {
+                  url: blob.service_url_for_direct_upload,
+                  headers: blob.service_headers_for_direct_upload
+                },
+                signed_id: blob.signed_id
+              }, status: :created
+            end
+
+            # GET /api/v3/store/carts/:cart_id/po_document
+            #
+            # Streamed rather than redirected to storage, so the document stays
+            # reachable only by whoever holds the cart.
+            def show
+              return head :not_found unless @cart.po_document.attached?
+
+              send_data(
+                @cart.po_document.download,
+                filename: @cart.po_document.filename.to_s,
+                type: @cart.po_document.content_type || 'application/octet-stream',
+                disposition: 'attachment'
+              )
+            end
+
+            # DELETE /api/v3/store/carts/:cart_id/po_document
+            #
+            # Detaches rather than purges: completion attaches the same blob to
+            # the order, so destroying the bytes here would take the placed
+            # order's copy with them.
+            def destroy
+              return head :not_found unless @cart.po_document.attached?
+
+              @cart.po_document.detach
+              head :no_content
+            end
+
+            private
+
+            def blob_params
+              params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
+            end
+
+            def acceptable_upload?
+              declared_size = Integer(blob_params[:byte_size].to_s, exception: false)
+
+              declared_size&.positive? &&
+                declared_size <= Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE &&
+                Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES.include?(blob_params[:content_type])
+            end
+
+            def render_po_document_invalid
+              render_error(
+                code: ERROR_CODES[:parameter_invalid],
+                message: Spree.t(
+                  :po_document_invalid,
+                  size: ActiveSupport::NumberHelper.number_to_human_size(
+                    Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE
+                  )
+                ),
+                status: :unprocessable_content
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/carts/store_credits_controller.rb

@@ -13,7 +13,7 @@ module Spree
             # POST /api/v3/store/carts/:cart_id/store_credits
             def create
               with_order_lock do
-                result = Spree.checkout_add_store_credit_service.call(
+                result = Spree.store_credit_apply_service.call(
                   order: @cart,
                   amount: params[:amount].try(:to_f)
                 )
@@ -29,7 +29,7 @@ module Spree
             # DELETE /api/v3/store/carts/:cart_id/store_credits
             def destroy
               with_order_lock do
-                result = Spree.checkout_remove_store_credit_service.call(order: @cart)
+                result = Spree.store_credit_remove_service.call(order: @cart)
 
                 if result.success?
                   render_cart

data/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rb

@@ -0,0 +1,96 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Carts
+          # A registration entered during checkout, overriding whatever the
+          # customer's profile holds — the buyer paying through a different
+          # company than the one on their account.
+          #
+          # The override is a copy of the number, not a link: a cart row and a
+          # customer row cannot both own one identifier, so this takes `kind` and
+          # `value`. A buyer picking from their own registrations (see
+          # `GET /store/customers/me/tax_identifiers`) resends the number. The
+          # copy is therefore checked in its own right, and does not follow later
+          # corrections to the profile — deliberately, since a claim must not
+          # change under a sale in progress.
+          class TaxIdentifiersController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
+
+            before_action :find_cart!
+
+            # Both fields, every time. A PUT carrying only `kind` used to reuse
+            # the number already on the cart, relabelling it under a regime it
+            # was never issued for — and that claim then drives tax and is
+            # frozen onto the order at completion.
+            before_action :require_kind_and_value!, only: :update
+
+            # GET /api/v3/store/carts/:cart_id/tax_identifier
+            #
+            # The registration this cart will be taxed against — the override
+            # when one was entered, the customer's own otherwise. A checkout page
+            # asking what applies wants the answer the provider will get, not
+            # whether an override happens to exist.
+            def show
+              resolved = @cart.resolved_tax_identifier
+              return head :not_found if resolved.nil?
+
+              render json: serialize_resource(resolved)
+            end
+
+            # PUT /api/v3/store/carts/:cart_id/tax_identifier
+            def update
+              resource = @cart.tax_identifier || @cart.build_tax_identifier
+              resource.assign_attributes(permitted_params)
+
+              if resource.save
+                # Tax depends on the registration, so the cart has to be re-costed.
+                @cart.recalculate_totals!
+                render json: serialize_resource(resource), status: resource.previously_new_record? ? :created : :ok
+              else
+                render_validation_error(resource.errors)
+              end
+            end
+
+            # DELETE /api/v3/store/carts/:cart_id/tax_identifier
+            #
+            # Clears the override only. The customer's own registration is theirs
+            # to remove from their profile — a cleared checkout field must not
+            # delete it — so a cart with no override of its own reports nothing
+            # to delete even when GET returns an inherited one.
+            def destroy
+              return head :not_found if @cart.tax_identifier.nil?
+
+              @cart.tax_identifier.destroy!
+              @cart.reload.recalculate_totals!
+              head :no_content
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.tax_identifier_serializer
+            end
+
+            def permitted_params
+              params.permit(:kind, :value)
+            end
+
+            private
+
+            def require_kind_and_value!
+              missing = %i[kind value].select { |field| params[field].blank? }
+              return if missing.empty?
+
+              render_error(
+                code: ERROR_CODES[:parameter_missing],
+                message: "#{missing.join(' and ')} required — a registration is a kind and its number together",
+                status: :unprocessable_content
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end