spree_api 5.4.0.beta6 → 5.4.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 015d8b61445f8983f5115b89c0627059abde5700d4f37eecff29f61c88bed184
-  data.tar.gz: 4290e6bf4ebc74c4f7b3b4881ec50bf4d5a1d3a1af4258c3a3390aac2e3bddad
+  metadata.gz: 6f27a3d636c9e7fdac4e297ba4820d97f91831b4124a1b6aafcc734b4f3906bc
+  data.tar.gz: a436eac6eee920191894f256c587c12f852b5b86f3a978d6af43f032cff1908b
 SHA512:
-  metadata.gz: 9ecdb3552eb461f5cf6d0925b2e2f7b065a2c0578904bc003b1c988d6214dc218e9033e46137a7107a8a8ceb822a92bd9379b44a9f49864df75c4a1650f841e2
-  data.tar.gz: 7603e522eb68740a77f24dcecf5fe21a2081e446ac52d845dcc761c4b352e702c03aff6089d20ce1ed4e730a904abce750289e86afe5539ccc3cbb4cb0120327
+  metadata.gz: adce2c15462e5c368813c95419047c83e686254e93af752832e370a2ed19aa7f5893659ed8b79c982bbe37294695b245d87671d196d93e92d759b9d8fe79caa9
+  data.tar.gz: 1cdec354c04bd65e731b2ee0309170e597012047ede52184ca0cbe2f8323d9af4c0f5ed967cb13fade6c74c3a1206aa058a803992c983b1ae351fc887f77b934

data/README.md

@@ -82,10 +82,10 @@ curl -H "Authorization: Bearer spree_sk_xxx" \
 
 ### Guest Cart Token
 
-For guest checkout, use the `X-Spree-Order-Token` header:
+For guest checkout, use the `X-Spree-Token` header:
 
 ```bash
-curl -H "X-Spree-Order-Token: ORDER_TOKEN" \
+curl -H "X-Spree-Token: ORDER_TOKEN" \
   https://your-store.com/api/v3/cart
 ```
 
@@ -134,4 +134,4 @@ bundle exec rspec
 ## Documentation
 
 - [API Reference](https://docs.spreecommerce.org/api)
-- [Authentication Guide](https://docs.spreecommerce.org/developer/api/authentication)
+- [Authentication Guide](https://docs.spreecommerce.org/developer/api/authentication)

data/app/controllers/concerns/spree/api/v3/cart_resolvable.rb

@@ -0,0 +1,45 @@
+module Spree
+  module Api
+    module V3
+      module CartResolvable
+        extend ActiveSupport::Concern
+
+        protected
+
+        # Find cart by prefixed ID and authorize access via CanCanCan.
+        # @return [Spree::Order]
+        def find_cart
+          cart_id = params[:cart_id] || params[:id]
+          @cart = current_store.carts.find_by_prefix_id!(cart_id)
+          authorize!(:show, @cart, cart_token)
+          @cart
+        end
+
+        # Find the cart and authorize it for update.
+        # @return [Spree::Order]
+        def find_cart!
+          cart_id = params[:cart_id] || params[:id]
+          @cart = current_store.carts.find_by_prefix_id!(cart_id)
+          authorize!(:update, @cart, cart_token)
+          @cart
+        end
+
+        # Render the cart as JSON using the cart serializer.
+        def render_cart(status: :ok)
+          render json: Spree.api.cart_serializer.new(@cart.reload, params: serializer_params).to_h, status: status
+        end
+
+        # Render the order as JSON using the order serializer (for complete action).
+        def render_order(status: :ok)
+          render json: Spree.api.order_serializer.new(@cart.reload, params: serializer_params).to_h, status: status
+        end
+
+        # Return the cart token from the request headers.
+        # @return [String, nil]
+        def cart_token
+          request.headers['x-spree-token']
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/error_handler.rb

@@ -18,13 +18,16 @@ module Spree
           record_not_found: 'record_not_found',
           resource_invalid: 'resource_invalid',
 
+          # Cart errors
+          cart_not_found: 'cart_not_found',
+          cart_cannot_transition: 'cart_cannot_transition',
+          cart_empty: 'cart_empty',
+          cart_invalid_state: 'cart_invalid_state',
+          cart_already_updated: 'cart_already_updated',
+          cart_cannot_complete: 'cart_cannot_complete',
+
           # Order errors
           order_not_found: 'order_not_found',
-          order_already_completed: 'order_already_completed',
-          order_cannot_transition: 'order_cannot_transition',
-          order_empty: 'order_empty',
-          order_invalid_state: 'order_invalid_state',
-          order_already_updated: 'order_already_updated',
 
           # Line item errors
           line_item_not_found: 'line_item_not_found',
@@ -191,7 +194,7 @@ module Spree
         def handle_invalid_transition(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           render_error(
-            code: ERROR_CODES[:order_cannot_transition],
+            code: ERROR_CODES[:cart_cannot_transition],
             message: exception.message,
             status: :unprocessable_content
           )
@@ -229,7 +232,7 @@ module Spree
 
           case model_name
           when 'order'
-            ERROR_CODES[:order_not_found]
+            request.path.include?('/carts') ? ERROR_CODES[:cart_not_found] : ERROR_CODES[:order_not_found]
           when 'line_item'
             ERROR_CODES[:line_item_not_found]
           when 'variant'
@@ -240,15 +243,17 @@ module Spree
         end
 
         # Generate human-readable not found message
-        # Uses the exception's own message when it contains useful context (e.g. prefixed ID),
-        # otherwise falls back to a generic "[Model] not found" translation.
         def generate_not_found_message(exception)
-          if exception.id.present?
-            exception.message
-          else
-            model_name = extract_model_name(exception)
-            Spree.t(:record_not_found, scope: 'api', model: model_name&.humanize || 'record')
-          end
+          model_name = extract_model_name(exception)
+
+          # Use "Cart" for order models in cart context
+          label = if model_name == 'order' && request.path.include?('/carts')
+                    'Cart'
+                  else
+                    model_name&.humanize || 'record'
+                  end
+
+          Spree.t(:record_not_found, scope: 'api', model: label)
         end
 
         # Extract clean model name from exception

data/app/controllers/concerns/spree/api/v3/order_lock.rb

@@ -12,7 +12,7 @@ module Spree
         private
 
         def with_order_lock
-          order = @order || @parent
+          order = @order || @parent || @cart
 
           order.with_lock do
             # Persist increment within the transaction so reloads inside yield see the new version
@@ -29,10 +29,10 @@ module Spree
         end
 
         def handle_order_lock_conflict(exception)
-          Rails.error.report(exception, context: { order_id: (@order || @parent)&.id }, source: 'spree.api.v3')
+          Rails.error.report(exception, context: { order_id: (@order || @parent || @cart)&.id }, source: 'spree.api.v3')
           render_error(
-            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:order_already_updated],
-            message: Spree.t(:order_already_updated),
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:cart_already_updated],
+            message: Spree.t(:cart_already_updated),
             status: :conflict
           )
         end

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

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Carts
+          class CouponCodesController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
+            include Spree::Api::V3::OrderLock
+
+            before_action :find_cart!
+
+            # POST  /api/v3/store/carts/:cart_id/coupon_codes
+            # Apply a coupon code to the cart
+            def create
+              with_order_lock do
+                @cart.coupon_code = permitted_params[:code]
+
+                coupon_handler.apply
+
+                if coupon_handler.successful?
+                  render_cart(status: :created)
+                else
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            # DELETE  /api/v3/store/carts/:cart_id/coupon_codes/:id
+            # Remove a coupon code from the cart
+            # :id is the coupon code string (e.g., SAVE10)
+            def destroy
+              with_order_lock do
+                coupon_handler.remove(params[:id])
+
+                if coupon_handler.successful?
+                  render_cart
+                else
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            private
+
+            def coupon_handler
+              @coupon_handler ||= Spree.coupon_handler.new(@cart)
+            end
+
+            def permitted_params
+              params.permit(:code)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/{orders/line_items_controller.rb → carts/items_controller.rb}

@@ -2,19 +2,18 @@ module Spree
   module Api
     module V3
       module Store
-        module Orders
-          class LineItemsController < ResourceController
-            include Spree::Api::V3::OrderConcern
+        module Carts
+          class ItemsController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
             include Spree::Api::V3::OrderLock
 
-            skip_before_action :set_resource
-            before_action :authorize_order_access!
+            before_action :find_cart!
 
-            # POST  /api/v3/store/orders/:order_id/line_items
+            # POST  /api/v3/store/carts/:cart_id/items
             def create
               with_order_lock do
                 result = Spree.cart_add_item_service.call(
-                  order: @parent,
+                  order: @cart,
                   variant: variant,
                   quantity: permitted_params[:quantity] || 1,
                   metadata: permitted_params[:metadata] || {},
@@ -22,73 +21,61 @@ module Spree
                 )
 
                 if result.success?
-                  render_order(status: :created)
+                  render_cart(status: :created)
                 else
                   render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
                 end
               end
             end
 
-            # PATCH  /api/v3/store/orders/:order_id/line_items/:id
+            # PATCH  /api/v3/store/carts/:cart_id/items/:id
             def update
               with_order_lock do
-                @line_item = scope.find_by_prefix_id!(params[:id])
+                @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: @parent,
+                    order: @cart,
                     line_item: @line_item,
                     quantity: permitted_params[:quantity]
                   )
 
                   if result.success?
-                    render_order
+                    render_cart
                   else
                     render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
                   end
                 elsif @line_item.changed?
                   @line_item.save!
-                  render_order
+                  render_cart
                 else
-                  render_order
+                  render_cart
                 end
               end
             end
 
-            # DELETE  /api/v3/store/orders/:order_id/line_items/:id
+            # DELETE  /api/v3/store/carts/:cart_id/items/:id
             def destroy
               with_order_lock do
-                @line_item = scope.find_by_prefix_id!(params[:id])
+                @line_item = @cart.line_items.find_by_prefix_id!(params[:id])
 
                 Spree.cart_remove_line_item_service.call(
-                  order: @parent,
+                  order: @cart,
                   line_item: @line_item
                 )
 
-                render_order
+                render_cart
               end
             end
 
-            protected
-
-            def parent_association
-              :line_items
-            end
+            private
 
             def variant
               @variant ||= current_store.variants.accessible_by(current_ability).find_by_prefix_id!(permitted_params[:variant_id])
             end
 
-            def model_class
-              Spree::LineItem
-            end
-
-            def serializer_class
-              Spree.api.line_item_serializer
-            end
-
             def permitted_params
               params.permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
             end

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

@@ -0,0 +1,24 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Carts
+          class PaymentMethodsController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
+
+            before_action :find_cart!
+
+            # GET /api/v3/store/carts/:cart_id/payment_methods
+            def index
+              methods = @cart.collect_frontend_payment_methods
+              render json: {
+                data: methods.map { |m| Spree.api.payment_method_serializer.new(m, params: serializer_params).to_h },
+                meta: { count: methods.size }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/{orders → carts}/payment_sessions_controller.rb

@@ -2,20 +2,19 @@ module Spree
   module Api
     module V3
       module Store
-        module Orders
-          class PaymentSessionsController < ResourceController
-            include Spree::Api::V3::OrderConcern
+        module Carts
+          class PaymentSessionsController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
 
-            skip_before_action :set_resource
-            before_action :authorize_order_access!
+            before_action :find_cart!
             before_action :set_payment_session, only: [:show, :update, :complete]
 
-            # POST /api/v3/store/orders/:order_id/payment_sessions
+            # POST /api/v3/store/carts/:cart_id/payment_sessions
             def create
               payment_method = current_store.payment_methods.find_by_prefix_id!(permitted_params[:payment_method_id])
 
               @payment_session = payment_method.create_payment_session(
-                order: @parent,
+                order: @cart,
                 amount: permitted_params[:amount],
                 external_data: permitted_params[:external_data] || {}
               )
@@ -27,12 +26,12 @@ module Spree
               end
             end
 
-            # GET /api/v3/store/orders/:order_id/payment_sessions/:id
+            # GET /api/v3/store/carts/:cart_id/payment_sessions/:id
             def show
               render json: serialize_resource(@payment_session)
             end
 
-            # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id
+            # PATCH /api/v3/store/carts/:cart_id/payment_sessions/:id
             def update
               @payment_session.payment_method.update_payment_session(
                 payment_session: @payment_session,
@@ -47,7 +46,7 @@ module Spree
               end
             end
 
-            # PATCH /api/v3/store/orders/:order_id/payment_sessions/:id/complete
+            # PATCH /api/v3/store/carts/:cart_id/payment_sessions/:id/complete
             def complete
               @payment_session.payment_method.complete_payment_session(
                 payment_session: @payment_session,
@@ -63,14 +62,6 @@ module Spree
 
             protected
 
-            def parent_association
-              :payment_sessions
-            end
-
-            def model_class
-              Spree::PaymentSession
-            end
-
             def serializer_class
               Spree.api.payment_session_serializer
             end
@@ -86,7 +77,11 @@ module Spree
             private
 
             def set_payment_session
-              @payment_session = @parent.payment_sessions.find_by_prefix_id!(params[:id])
+              @payment_session = @cart.payment_sessions.find_by_prefix_id!(params[:id])
+            end
+
+            def serialize_resource(resource)
+              serializer_class.new(resource, params: serializer_params).to_h
             end
           end
         end

data/app/controllers/spree/api/v3/store/{orders → carts}/payments_controller.rb

@@ -2,29 +2,11 @@ module Spree
   module Api
     module V3
       module Store
-        module Orders
-          class PaymentsController < Store::BaseController
-            include Spree::Api::V3::OrderConcern
-            include Spree::Api::V3::ResourceSerializer
+        module Carts
+          class PaymentsController < Store::ResourceController
+            include Spree::Api::V3::CartResolvable
 
-            before_action :set_parent
-            before_action :set_payment, only: [:show]
-
-            # GET /api/v3/store/orders/:order_id/payments
-            def index
-              payments = @parent.payments.includes(:payment_method)
-              render json: {
-                data: serialize_payments(payments),
-                meta: {}
-              }
-            end
-
-            # GET /api/v3/store/orders/:order_id/payments/:id
-            def show
-              render json: serialize_resource(@payment)
-            end
-
-            # POST /api/v3/store/orders/:order_id/payments
+            # POST /api/v3/store/carts/:cart_id/payments
             # Creates a payment for non-session payment methods (e.g. Check, Cash on Delivery, Bank Transfer)
             def create
               payment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])
@@ -53,8 +35,6 @@ module Spree
                 metadata: params[:metadata].present? ? params[:metadata].to_unsafe_h : {}
               )
 
-              authorize!(:update, @parent, order_token)
-
               if @payment.save
                 render json: serialize_resource(@payment), status: :created
               else
@@ -62,18 +42,27 @@ module Spree
               end
             end
 
-            private
+            protected
+
+            def set_parent
+              find_cart!
+              @parent = @cart
+            end
+
+            def parent_association
+              :payments
+            end
 
-            def set_payment
-              @payment = @parent.payments.find_by_prefix_id!(params[:id])
+            def model_class
+              Spree::Payment
             end
 
             def serializer_class
               Spree.api.payment_serializer
             end
 
-            def serialize_payments(payments)
-              payments.map { |p| serializer_class.new(p, params: serializer_params).to_h }
+            # Authorization is handled by find_cart! in set_parent
+            def authorize_resource!(*)
             end
           end
         end

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

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Carts
+          class ShipmentsController < Store::BaseController
+            include Spree::Api::V3::CartResolvable
+            include Spree::Api::V3::OrderLock
+
+            before_action :find_cart!
+
+            # GET /api/v3/store/carts/:cart_id/shipments
+            def index
+              shipments = @cart.shipments.includes(shipping_rates: :shipping_method)
+              render json: {
+                data: shipments.map { |s| Spree.api.shipment_serializer.new(s, params: serializer_params).to_h },
+                meta: { count: shipments.size }
+              }
+            end
+
+            # PATCH /api/v3/store/carts/:cart_id/shipments/:id
+            # Select a shipping rate for a specific shipment
+            def update
+              with_order_lock do
+                shipment = @cart.shipments.find_by_prefix_id!(params[:id])
+
+                if permitted_params[:selected_shipping_rate_id].present?
+                  shipping_rate = shipment.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
+                  shipment.selected_shipping_rate_id = shipping_rate.id
+                  shipment.save!
+                end
+
+                # Auto-advance (e.g. delivery → payment) after rate selection.
+                # Temporary — Spree 6 removes the checkout state machine.
+                try_advance
+
+                render_cart
+              end
+            end
+
+            private
+
+            def permitted_params
+              params.permit(:selected_shipping_rate_id)
+            end
+
+            # Temporary — Spree 6 removes the checkout state machine.
+            def try_advance
+              return if @cart.complete? || @cart.canceled?
+
+              loop do
+                break unless @cart.next
+                break if @cart.confirm? || @cart.complete?
+              end
+            rescue StandardError => e
+              Rails.error.report(e, context: { order_id: @cart.id, state: @cart.state }, source: 'spree.checkout')
+            ensure
+              @cart.reload
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/{orders → carts}/store_credits_controller.rb

@@ -2,38 +2,37 @@ module Spree
   module Api
     module V3
       module Store
-        module Orders
+        module Carts
           class StoreCreditsController < Store::BaseController
-            include Spree::Api::V3::OrderConcern
+            include Spree::Api::V3::CartResolvable
             include Spree::Api::V3::OrderLock
 
             before_action :require_authentication!
-            before_action :set_parent
-            before_action :authorize_order_access!
+            before_action :find_cart!
 
-            # POST /api/v3/store/orders/:order_id/store_credits
+            # POST /api/v3/store/carts/:cart_id/store_credits
             def create
               with_order_lock do
                 result = Spree.checkout_add_store_credit_service.call(
-                  order: @parent,
+                  order: @cart,
                   amount: params[:amount].try(:to_f)
                 )
 
                 if result.success?
-                  render_order
+                  render_cart
                 else
                   render_service_error(result.error)
                 end
               end
             end
 
-            # DELETE /api/v3/store/orders/:order_id/store_credits
+            # DELETE /api/v3/store/carts/:cart_id/store_credits
             def destroy
               with_order_lock do
-                result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+                result = Spree.checkout_remove_store_credit_service.call(order: @cart)
 
                 if result.success?
-                  render_order
+                  render_cart
                 else
                   render_service_error(result.error)
                 end