spree_api 5.4.0.beta5 → 5.4.0.beta7

data/lib/spree/api/openapi/schema_helper.rb

@@ -84,6 +84,15 @@ module Spree
                 user: { '$ref' => '#/components/schemas/Customer' }
               },
               required: %w[token user]
+            },
+            CheckoutRequirement: {
+              type: :object,
+              properties: {
+                step: { type: :string, description: 'Checkout step this requirement belongs to', example: 'payment' },
+                field: { type: :string, description: 'Field that needs to be satisfied', example: 'payment' },
+                message: { type: :string, description: 'Human-readable requirement message', example: 'Add a payment method' }
+              },
+              required: %w[step field message]
             }
           }
         end
@@ -110,10 +119,29 @@ module Spree
               s[:'x-typelizer'] = true
               strip_null_from_enums(s)
             end
+            patch_cart_schema(schemas)
             schemas
           end
         end
 
+        # Typelizer cannot represent Array<{...}> inline object types in OpenAPI,
+        # so we patch them to reference manually-defined component schemas.
+        def patch_cart_schema(schemas)
+          cart = schemas['Cart'] || schemas[:Cart]
+          return unless cart
+
+          props = cart[:properties]
+          return unless props
+
+          req_key = props.key?('requirements') ? 'requirements' : :requirements
+          if props[req_key]
+            props[req_key] = {
+              type: :array,
+              items: { '$ref' => '#/components/schemas/CheckoutRequirement' }
+            }
+          end
+        end
+
         # Typelizer adds nil to enum arrays for nullable fields.
         # OpenAPI 3.0 handles nullability via `nullable: true`, so the nil entry is redundant
         # and causes issues with code generators.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spree_api
 version: !ruby/object:Gem::Version
-  version: 5.4.0.beta5
+  version: 5.4.0.beta7
 platform: ruby
 authors:
 - Vendo Connect Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-10 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rswag-specs
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta5
+        version: 5.4.0.beta7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta5
+        version: 5.4.0.beta7
 description: Spree's API
 email:
 - hello@spreecommerce.org
@@ -104,12 +104,12 @@ files:
 - README.md
 - Rakefile
 - app/controllers/concerns/spree/api/v3/api_key_authentication.rb
+- app/controllers/concerns/spree/api/v3/cart_resolvable.rb
 - app/controllers/concerns/spree/api/v3/error_handler.rb
 - app/controllers/concerns/spree/api/v3/http_caching.rb
 - app/controllers/concerns/spree/api/v3/idempotent.rb
 - app/controllers/concerns/spree/api/v3/jwt_authentication.rb
 - app/controllers/concerns/spree/api/v3/locale_and_currency.rb
-- app/controllers/concerns/spree/api/v3/order_concern.rb
 - app/controllers/concerns/spree/api/v3/order_lock.rb
 - app/controllers/concerns/spree/api/v3/rate_limit_headers.rb
 - app/controllers/concerns/spree/api/v3/resource_serializer.rb
@@ -120,7 +120,14 @@ files:
 - app/controllers/spree/api/v3/resource_controller.rb
 - app/controllers/spree/api/v3/store/auth_controller.rb
 - app/controllers/spree/api/v3/store/base_controller.rb
-- app/controllers/spree/api/v3/store/cart_controller.rb
+- app/controllers/spree/api/v3/store/carts/coupon_codes_controller.rb
+- app/controllers/spree/api/v3/store/carts/items_controller.rb
+- app/controllers/spree/api/v3/store/carts/payment_methods_controller.rb
+- app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb
+- app/controllers/spree/api/v3/store/carts/payments_controller.rb
+- app/controllers/spree/api/v3/store/carts/shipments_controller.rb
+- app/controllers/spree/api/v3/store/carts/store_credits_controller.rb
+- app/controllers/spree/api/v3/store/carts_controller.rb
 - app/controllers/spree/api/v3/store/categories/products_controller.rb
 - app/controllers/spree/api/v3/store/categories_controller.rb
 - app/controllers/spree/api/v3/store/countries_controller.rb
@@ -135,19 +142,13 @@ files:
 - app/controllers/spree/api/v3/store/locales_controller.rb
 - app/controllers/spree/api/v3/store/markets/countries_controller.rb
 - app/controllers/spree/api/v3/store/markets_controller.rb
-- app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb
-- app/controllers/spree/api/v3/store/orders/line_items_controller.rb
-- app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
-- app/controllers/spree/api/v3/store/orders/payment_sessions_controller.rb
-- app/controllers/spree/api/v3/store/orders/payments_controller.rb
-- app/controllers/spree/api/v3/store/orders/shipments_controller.rb
-- app/controllers/spree/api/v3/store/orders/store_credits_controller.rb
 - app/controllers/spree/api/v3/store/orders_controller.rb
 - app/controllers/spree/api/v3/store/products/filters_controller.rb
 - app/controllers/spree/api/v3/store/products_controller.rb
 - app/controllers/spree/api/v3/store/resource_controller.rb
 - app/controllers/spree/api/v3/store/wishlist_items_controller.rb
 - app/controllers/spree/api/v3/store/wishlists_controller.rb
+- app/controllers/spree/api/v3/webhooks/payments_controller.rb
 - app/jobs/spree/api_keys/mark_as_used.rb
 - app/jobs/spree/webhook_delivery_job.rb
 - app/serializers/spree/api/v3/address_serializer.rb
@@ -185,6 +186,8 @@ files:
 - app/serializers/spree/api/v3/admin/variant_serializer.rb
 - app/serializers/spree/api/v3/asset_serializer.rb
 - app/serializers/spree/api/v3/base_serializer.rb
+- app/serializers/spree/api/v3/cart_promotion_serializer.rb
+- app/serializers/spree/api/v3/cart_serializer.rb
 - app/serializers/spree/api/v3/category_serializer.rb
 - app/serializers/spree/api/v3/country_serializer.rb
 - app/serializers/spree/api/v3/credit_card_serializer.rb
@@ -263,9 +266,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta5
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta7
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta5
+  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta7
 post_install_message:
 rdoc_options: []
 require_paths:

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

@@ -1,46 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module OrderConcern
-        extend ActiveSupport::Concern
-
-        # Allow access to order via order token for guests or authenticated users
-        # Expects @parent to be set to the order
-        def authorize_order_access!
-          authorize!(:update, @parent, order_token)
-        end
-
-        def set_parent
-          return if params[:order_id].blank?
-
-          @parent = order_scope.find_by_prefix_id!(params[:order_id])
-        end
-
-        def order_scope
-          base = current_store.orders
-          base = if current_user
-                   base.where(user: current_user)
-                 elsif order_token.present?
-                   base.where(token: order_token)
-                 else
-                   base.none
-                 end
-          base.preload_associations_lazily
-        end
-
-        protected
-
-        # Render the parent order as JSON using the order serializer.
-        # Use this when sub-resource mutations should return the updated order
-        # (e.g., line items, coupon codes, store credits).
-        def render_order(status: :ok)
-          render json: Spree.api.order_serializer.new(@parent.reload, params: serializer_params).to_h, status: status
-        end
-
-        def order_token
-          request.headers['x-spree-order-token']
-        end
-      end
-    end
-  end
-end

data/app/controllers/spree/api/v3/store/cart_controller.rb

@@ -1,97 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module Store
-        class CartController < Store::BaseController
-          include Spree::Api::V3::OrderConcern
-
-          before_action :require_authentication!, only: [:associate]
-
-          # POST /api/v3/store/cart
-          # Creates a new shopping cart (order)
-          # Can be created by guests or authenticated customers
-          def create
-            result = Spree.cart_create_service.call(
-              user: current_user,
-              store: current_store,
-              currency: current_currency,
-              locale: current_locale,
-              metadata: cart_params[:metadata] || {},
-              line_items: cart_params[:line_items] || []
-            )
-
-            if result.success?
-              @cart = result.value
-              render json: serialize_resource(@cart), status: :created
-            else
-              render_service_error(result.error.to_s)
-            end
-          end
-
-          # GET /api/v3/store/cart
-          # Returns current incomplete order (cart)
-          # Returns 404 if no cart exists - use POST /cart to create one
-          # Authorize via order_token param or JWT Bearer token
-          def show
-            @cart = find_cart
-
-            render json: serialize_resource(@cart)
-          end
-
-          # PATCH /api/v3/store/cart/associate
-          # Associates a guest cart with the currently authenticated user
-          # Requires: JWT authentication + order token (header or param)
-          def associate
-            @cart = find_cart_by_token
-
-            result = Spree.cart_associate_service.call(guest_order: @cart, user: current_user, guest_only: true)
-
-            if result.success?
-              render json: serialize_resource(@cart)
-            else
-              render_service_error(result.error.to_s)
-            end
-          end
-
-          protected
-
-          def serializer_class
-            Spree.api.order_serializer
-          end
-
-          private
-
-          def cart_params
-            params.permit(
-              metadata: {},
-              line_items: [:variant_id, :quantity, { metadata: {}, options: {} }]
-            )
-          end
-
-          # Find incomplete cart by order token for associate action
-          # Only finds guest carts (no user) or carts already owned by current user (idempotent)
-          def find_cart_by_token
-            current_store.orders.incomplete.where(user: [ nil, current_user ]).find_by!(token: order_token)
-          end
-
-          def find_cart
-            scope = current_store.orders.incomplete
-
-            # Try order_token first (guest checkout)
-            if order_token.present?
-              return scope.find_by!(token: order_token)
-            end
-
-            # Then try JWT authenticated user
-            if current_user.present?
-              cart = scope.where(user: current_user).order(created_at: :desc).first
-              return cart if cart
-            end
-
-            raise ActiveRecord::RecordNotFound.new(nil, 'Spree::Order')
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,73 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module Store
-        module Orders
-          class CouponCodesController < ResourceController
-            include Spree::Api::V3::OrderConcern
-            include Spree::Api::V3::OrderLock
-
-            before_action :authorize_order_access!
-            skip_before_action :set_resource
-
-            # POST  /api/v3/store/orders/:order_id/coupon_codes
-            # Apply a coupon code to the order
-            def create
-              with_order_lock do
-                @parent.coupon_code = permitted_params[:code]
-
-                coupon_handler.apply
-
-                if coupon_handler.successful?
-                  render_order(status: :created)
-                else
-                  render_errors(coupon_handler.error)
-                end
-              end
-            end
-
-            # DELETE  /api/v3/store/orders/:order_id/coupon_codes/:id
-            # Remove a coupon code from the order
-            # :id is the promotion prefix_id (e.g., promo_xxx)
-            def destroy
-              with_order_lock do
-                @resource = scope.find_by_prefix_id!(params[:id])
-                coupon_code = @resource.code.presence || @resource.name
-
-                coupon_handler.remove(coupon_code)
-
-                if coupon_handler.successful?
-                  render_order
-                else
-                  render_errors(coupon_handler.error)
-                end
-              end
-            end
-
-            protected
-
-            def parent_association
-              :order_promotions
-            end
-
-            def coupon_handler
-              @coupon_handler ||= Spree.coupon_handler.new(@parent)
-            end
-
-            def permitted_params
-              params.permit(:code)
-            end
-
-            def model_class
-              Spree::OrderPromotion
-            end
-
-            def serializer_class
-              Spree.api.order_promotion_serializer
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,43 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module Store
-        module Orders
-          class PaymentMethodsController < Store::BaseController
-            include Spree::Api::V3::OrderConcern
-
-            before_action :set_parent
-
-            # GET /api/v3/store/orders/:order_id/payment_methods
-            # Returns available payment methods for the current order
-            def index
-              payment_methods = @parent.collect_frontend_payment_methods
-              render json: {
-                data: serialize_collection(payment_methods),
-                meta: { count: payment_methods.size }
-              }
-            end
-
-            protected
-
-            def serializer_class
-              Spree.api.payment_method_serializer
-            end
-
-            def serialize_collection(collection)
-              collection.map { |item| serializer_class.new(item, params: serializer_params).to_h }
-            end
-
-            def serializer_params
-              {
-                currency: current_currency,
-                store: current_store,
-                user: current_user
-              }
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module Store
-        module Orders
-          class PaymentsController < Store::BaseController
-            include Spree::Api::V3::OrderConcern
-            include Spree::Api::V3::ResourceSerializer
-
-            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
-
-            private
-
-            def set_payment
-              @payment = @parent.payments.find_by_prefix_id!(params[:id])
-            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 }
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,56 +0,0 @@
-module Spree
-  module Api
-    module V3
-      module Store
-        module Orders
-          class ShipmentsController < ResourceController
-            include Spree::Api::V3::OrderConcern
-            include Spree::Api::V3::OrderLock
-
-            before_action :authorize_order_access!
-            skip_before_action :set_resource
-            before_action :set_shipment, only: [:show, :update]
-
-            # PATCH /api/v3/store/orders/:order_id/shipments/:id
-            def update
-              with_order_lock do
-                if permitted_params[:selected_shipping_rate_id].present?
-                  shipping_rate = @resource.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
-                  @resource.selected_shipping_rate_id = shipping_rate.id
-                  @resource.save!
-                end
-
-                render_order
-              end
-            end
-
-            protected
-
-            def parent_association
-              :shipments
-            end
-
-            def model_class
-              Spree::Shipment
-            end
-
-            def serializer_class
-              Spree.api.shipment_serializer
-            end
-
-            def permitted_params
-              params.permit(:selected_shipping_rate_id)
-            end
-
-            private
-
-            # Find shipment without additional authorization - order access already verified
-            def set_shipment
-              @resource = scope.find_by_prefix_id!(params[:id])
-            end
-          end
-        end
-      end
-    end
-  end
-end