spree_api 5.3.4 → 5.4.0.beta

data/config/routes.rb

@@ -1,220 +1,87 @@
-spree_path = Rails.application.routes.url_helpers.try(:spree_path, trailing_slash: true) || '/'
-
-Rails.application.routes.draw do
-  use_doorkeeper scope: "#{spree_path}/spree_oauth"
-end
-
 Spree::Core::Engine.add_routes do
   namespace :api, defaults: { format: 'json' } do
-    namespace :v2 do
-      namespace :storefront do
-        resource :cart, controller: :cart, only: %i[show create destroy] do
-          post   :add_item
-          patch  :empty
-          delete 'remove_line_item/:line_item_id', to: 'cart#remove_line_item', as: :cart_remove_line_item
-          patch  :set_quantity
-          patch  :apply_coupon_code
-          delete 'remove_coupon_code/:coupon_code', to: 'cart#remove_coupon_code', as: :cart_remove_coupon_code, constraints: { coupon_code: /[^\/]+/ }
-          delete 'remove_coupon_code', to: 'cart#remove_coupon_code', as: :cart_remove_coupon_code_without_code
-          get :estimate_shipping_rates
-          patch :associate
-          patch :change_currency
-        end
-
-        resource :checkout, controller: :checkout, only: %i[update] do
-          patch :next
-          patch :advance
-          patch :complete
-          post :create_payment
-          post :add_store_credit
-          post :remove_store_credit
-          get :payment_methods
-          get :shipping_rates
-          patch :select_shipping_method
-          post :validate_order_for_payment
-        end
-
-        resource :account, controller: :account, only: %i[show create update]
-
-        namespace :account do
-          resources :addresses, controller: :addresses
-          resources :credit_cards, controller: :credit_cards, only: %i[index show destroy]
-          resources :orders, controller: :orders, only: %i[index show]
-        end
-
-        resources :countries, only: %i[index]
-        get '/countries/:iso', to: 'countries#show', as: :country
-        get '/order_status/:number', to: 'order_status#show', as: :order_status
-        resources :products, only: %i[index show]
-        get '/products/:id/variants', to: 'variants#index', as: :product_variants
-        resources :taxons,   only: %i[index show], id: /.+/
-        get '/stores/:code', to: 'stores#show', as: :store
-        get '/store', to: 'stores#current', as: :current_store
-
-        resources :menus, only: %i[index show]
-        resources :cms_pages, only: %i[index show]
-        resources :policies, only: %i[index show]
-
-        resources :wishlists do
-          get :default, on: :collection
+    namespace :v3 do
+      namespace :store do
+        # Authentication
+        post 'auth/login', to: 'auth#create'
+        post 'auth/register', to: 'auth#register'
+        post 'auth/refresh', to: 'auth#refresh'
+        post 'auth/oauth/callback', to: 'auth#oauth_callback'
+
+        # Store
+        resource :store, only: [:show]
+
+        # Countries, Currencies, Locales (flat, market-aware)
+        resources :countries, only: [:index, :show]
+        resources :currencies, only: [:index]
+        resources :locales, only: [:index]
 
-          member do
-            post :add_item
-            patch 'set_item_quantity/:item_id', to: 'wishlists#set_item_quantity', as: :set_item_quantity
-            delete 'remove_item/:item_id', to: 'wishlists#remove_item', as: :remove_item
-            post :add_items
-            delete :remove_items
+        # Catalog
+        resources :products, only: [:index, :show] do
+          collection do
+            get :filters, to: 'products/filters#index'
           end
         end
-
-        resources :posts, only: %i[index show]
-        resources :post_categories, only: %i[index show]
-
-        get '/digitals/:token', to: 'digitals#download', as: 'digital'
-      end
-
-      namespace :platform do
-        # Promotions API
-        resources :promotions
-        resources :promotion_actions
-        resources :promotion_categories
-        resources :promotion_rules
-
-        # Returns API
-        resources :customer_returns
-        resources :reimbursements
-        resources :return_authorizations do
-          member do
-            patch :add
-            patch :cancel
-            patch :receive
-          end
+        resources :taxonomies, only: [:index, :show]
+        resources :taxons, only: [:index, :show], id: /.+/ do
+          resources :products, only: [:index], controller: 'taxons/products'
         end
 
-        # Product Catalog API
-        resources :products
-        resources :taxonomies
-        resources :taxons do
-          member do
-            patch :reposition
-          end
+        # Cart
+        resource :cart, only: [:show, :create], controller: 'cart' do
+          patch :associate
         end
-        resources :classifications
-        resources :images
-        resources :variants
-        resources :properties
-        resources :product_properties
-        resources :option_types
-        resources :option_values
 
-        # Order API
-        resources :orders do
+        # Orders - individual order management and checkout
+        resources :orders, only: [:show, :update] do
           member do
-            patch :next
-            patch :advance
-            patch :approve
-            patch :cancel
-            patch :empty
-            patch :apply_coupon_code
-            patch :complete
-            patch :use_store_credit
-            patch :cancel
-            patch :approve
+            # State transitions
+            patch :next       # Move to next checkout step
+            patch :advance    # Advance through all steps
+            patch :complete   # Complete the order
           end
-        end
-        resources :line_items
-        resources :adjustments
-
-        # Payments API
-        resources :payments do
-          # TODO: support custom actions
-          # member do
-          #   patch :authorize
-          #   patch :capture
-          #   patch :purchase
-          #   patch :void
-          #   patch :credit
-          # end
-        end
-
-        # Store Credit API
-        resources :store_credits
-        resources :store_credit_categories
-        resources :store_credit_types
-
-        # Geo API
-        resources :zones
-        resources :countries, only: [:index, :show]
-        resources :states, only: [:index, :show]
 
-        # Shipment API
-        resources :shipments do
-          member do
-            %w[ready ship cancel resume pend].each do |state|
-              patch state.to_sym
+          # Nested resources - all require order access
+          resource :store_credits, only: [:create, :destroy], controller: 'orders/store_credits'
+          resources :line_items, only: [:create, :update, :destroy], controller: 'orders/line_items'
+          resources :coupon_codes, only: [:create, :destroy], controller: 'orders/coupon_codes'
+          resources :payments, only: [:index, :show], controller: 'orders/payments'
+          resources :payment_methods, only: [:index], controller: 'orders/payment_methods'
+          resources :payment_sessions, only: [:create, :show, :update], controller: 'orders/payment_sessions' do
+            member do
+              patch :complete
             end
-            patch :add_item
-            patch :remove_item
-            patch :transfer_to_location
-            patch :transfer_to_shipment
           end
+          resources :shipments, only: [:index, :show, :update], controller: 'orders/shipments'
         end
 
-        # Tax API
-        resources :tax_rates
-        resources :tax_categories
-
-        # Inventory API
-        resources :inventory_units
-        resources :stock_items
-        resources :stock_locations
-        resources :stock_movements
-
-        # User API
-        resources :users
-        resources :credit_cards
-        resources :addresses
-
-        resources :roles
-
-        # CMS
-        resources :cms_pages
-        resources :cms_sections
-
-        # Wishlists API
-        resources :wishlists
-        resources :wished_items
-
-        # Digitals API
-        resources :digitals
-        resources :digital_links do
-          member do
-            patch :reset
+        # Customer
+        namespace :customer, path: 'customer' do
+          get '/', to: 'account#show'
+          patch '/', to: 'account#update'
+          resources :addresses, only: [:index, :show, :create, :update, :destroy] do
+            member do
+              patch :mark_as_default
+            end
+          end
+          resources :orders, only: [:index]
+          resources :credit_cards, only: [:index, :show, :destroy]
+          resources :gift_cards, only: [:index, :show]
+          resources :payment_setup_sessions, only: [:create, :show] do
+            member do
+              patch :complete
+            end
           end
         end
 
-        # Store API
-        resources :stores
-
-        # Data Feeds API
-        resources :data_feeds
-
-        # Configurations API
-        resources :payment_methods
-        resources :shipping_categories
-        resources :shipping_methods
-
-        # Webhooks API
-        namespace :webhooks do
+        # Wishlists
+        resources :wishlists do
+          resources :items, only: [:create, :update, :destroy], controller: 'wishlist_items'
         end
 
-        # Gift Cards API
-        resources :gift_cards
-      end
-
-      namespace :data_feeds do
-        # google data feed API
-        get '/google/:slug', to: 'google#rss_feed'
+        # Digital Downloads
+        # Access via token in URL
+        get 'digitals/:token', to: 'digitals#show', as: :digital_download
       end
     end
   end

data/lib/spree/api/dependencies.rb

@@ -90,6 +90,74 @@ module Spree
         storefront_wished_item_serializer: 'Spree::V2::Storefront::WishedItemSerializer',
         storefront_metafield_serializer: 'Spree::V2::Storefront::MetafieldSerializer',
 
+        # v3 serializers (API v3)
+        credit_card_serializer: 'Spree::Api::V3::CreditCardSerializer',
+        price_serializer: 'Spree::Api::V3::PriceSerializer',
+        product_serializer: 'Spree::Api::V3::ProductSerializer',
+        variant_serializer: 'Spree::Api::V3::VariantSerializer',
+        image_serializer: 'Spree::Api::V3::ImageSerializer',
+        option_type_serializer: 'Spree::Api::V3::OptionTypeSerializer',
+        option_value_serializer: 'Spree::Api::V3::OptionValueSerializer',
+        order_serializer: 'Spree::Api::V3::OrderSerializer',
+        line_item_serializer: 'Spree::Api::V3::LineItemSerializer',
+        payment_serializer: 'Spree::Api::V3::PaymentSerializer',
+        payment_session_serializer: 'Spree::Api::V3::PaymentSessionSerializer',
+        payment_setup_session_serializer: 'Spree::Api::V3::PaymentSetupSessionSerializer',
+        payment_source_serializer: 'Spree::Api::V3::PaymentSourceSerializer',
+        store_credit_serializer: 'Spree::Api::V3::StoreCreditSerializer',
+        shipment_serializer: 'Spree::Api::V3::ShipmentSerializer',
+        address_serializer: 'Spree::Api::V3::AddressSerializer',
+        customer_serializer: 'Spree::Api::V3::CustomerSerializer',
+        country_serializer: 'Spree::Api::V3::CountrySerializer',
+        state_serializer: 'Spree::Api::V3::StateSerializer',
+        store_serializer: 'Spree::Api::V3::StoreSerializer',
+        wishlist_serializer: 'Spree::Api::V3::WishlistSerializer',
+        wished_item_serializer: 'Spree::Api::V3::WishedItemSerializer',
+        payment_method_serializer: 'Spree::Api::V3::PaymentMethodSerializer',
+        shipping_method_serializer: 'Spree::Api::V3::ShippingMethodSerializer',
+        shipping_rate_serializer: 'Spree::Api::V3::ShippingRateSerializer',
+        stock_location_serializer: 'Spree::Api::V3::StockLocationSerializer',
+        taxonomy_serializer: 'Spree::Api::V3::TaxonomySerializer',
+        taxon_serializer: 'Spree::Api::V3::TaxonSerializer',
+        order_promotion_serializer: 'Spree::Api::V3::OrderPromotionSerializer',
+        digital_link_serializer: 'Spree::Api::V3::DigitalLinkSerializer',
+        gift_card_serializer: 'Spree::Api::V3::GiftCardSerializer',
+        currency_serializer: 'Spree::Api::V3::CurrencySerializer',
+        locale_serializer: 'Spree::Api::V3::LocaleSerializer',
+        metafield_serializer: 'Spree::Api::V3::MetafieldSerializer',
+
+        # v3 event serializers (for models without Store API endpoints yet)
+        asset_serializer: 'Spree::Api::V3::AssetSerializer',
+        customer_return_serializer: 'Spree::Api::V3::CustomerReturnSerializer',
+        digital_serializer: 'Spree::Api::V3::DigitalSerializer',
+        export_serializer: 'Spree::Api::V3::ExportSerializer',
+        gift_card_batch_serializer: 'Spree::Api::V3::GiftCardBatchSerializer',
+        import_serializer: 'Spree::Api::V3::ImportSerializer',
+        import_row_serializer: 'Spree::Api::V3::ImportRowSerializer',
+        invitation_serializer: 'Spree::Api::V3::InvitationSerializer',
+        newsletter_subscriber_serializer: 'Spree::Api::V3::NewsletterSubscriberSerializer',
+        post_serializer: 'Spree::Api::V3::PostSerializer',
+        post_category_serializer: 'Spree::Api::V3::PostCategorySerializer',
+        promotion_serializer: 'Spree::Api::V3::PromotionSerializer',
+        refund_serializer: 'Spree::Api::V3::RefundSerializer',
+        reimbursement_serializer: 'Spree::Api::V3::ReimbursementSerializer',
+        report_serializer: 'Spree::Api::V3::ReportSerializer',
+        return_authorization_serializer: 'Spree::Api::V3::ReturnAuthorizationSerializer',
+        return_item_serializer: 'Spree::Api::V3::ReturnItemSerializer',
+        stock_item_serializer: 'Spree::Api::V3::StockItemSerializer',
+        stock_movement_serializer: 'Spree::Api::V3::StockMovementSerializer',
+        stock_transfer_serializer: 'Spree::Api::V3::StockTransferSerializer',
+
+        # v3 admin serializers (API v3 Admin)
+        admin_customer_serializer: 'Spree::Api::V3::Admin::CustomerSerializer',
+        admin_order_serializer: 'Spree::Api::V3::Admin::OrderSerializer',
+        admin_product_serializer: 'Spree::Api::V3::Admin::ProductSerializer',
+        admin_variant_serializer: 'Spree::Api::V3::Admin::VariantSerializer',
+        admin_price_serializer: 'Spree::Api::V3::Admin::PriceSerializer',
+        admin_metafield_serializer: 'Spree::Api::V3::Admin::MetafieldSerializer',
+        admin_taxon_serializer: 'Spree::Api::V3::Admin::TaxonSerializer',
+        admin_taxonomy_serializer: 'Spree::Api::V3::Admin::TaxonomySerializer',
+
         # platform serializers
         platform_metafield_serializer: 'Spree::Api::V2::Platform::MetafieldSerializer',
 

data/lib/spree/api/engine.rb

@@ -1,5 +1,4 @@
 require 'rails/engine'
-require 'pagy'
 
 require_relative 'dependencies'
 require_relative 'configuration'
@@ -15,10 +14,6 @@ module Spree
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
       end
 
-      initializer 'spree.api.checking_migrations' do
-        Migrations.new(config, engine_name).check unless Rails.env.test?
-      end
-
       # Add API event subscribers
       config.after_initialize do
         Spree.subscribers << Spree::WebhookEventSubscriber

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module OpenAPI
+      # Helper module to reference Typelizer-generated schemas in rswag specs
+      module SchemaHelper
+        extend self
+
+        # Reference a schema by name (e.g., 'StoreProduct', 'StoreOrder')
+        def ref(schema_name)
+          { '$ref' => "#/components/schemas/#{schema_name}" }
+        end
+
+        # Paginated response wrapper
+        def paginated(schema_name)
+          {
+            type: :object,
+            properties: {
+              data: {
+                type: :array,
+                items: ref(schema_name)
+              },
+              meta: ref('PaginationMeta')
+            },
+            required: %w[data meta]
+          }
+        end
+
+        # Error response schema
+        def error_response
+          ref('ErrorResponse')
+        end
+
+        # Common schemas that are not from serializers
+        def common_schemas
+          {
+            PaginationMeta: {
+              type: :object,
+              properties: {
+                page: { type: :integer, example: 1 },
+                limit: { type: :integer, example: 25 },
+                count: { type: :integer, example: 100 },
+                pages: { type: :integer, example: 4 }
+              },
+              required: %w[page limit count pages]
+            },
+            ErrorResponse: {
+              type: :object,
+              properties: {
+                error: {
+                  type: :object,
+                  properties: {
+                    code: { type: :string, example: 'record_not_found' },
+                    message: { type: :string, example: 'Record not found' },
+                    details: {
+                      type: :object,
+                      description: 'Field-specific validation errors',
+                      nullable: true,
+                      example: { name: ['is too short', 'is required'], email: ['is invalid'] }
+                    }
+                  },
+                  required: %w[code message]
+                }
+              },
+              required: %w[error],
+              example: {
+                error: {
+                  code: 'validation_error',
+                  message: 'Validation failed',
+                  details: { name: ['is too short'], email: ['is invalid'] }
+                }
+              }
+            },
+            AuthResponse: {
+              type: :object,
+              properties: {
+                token: { type: :string, description: 'JWT access token' },
+                user: { '$ref' => '#/components/schemas/StoreCustomer' }
+              },
+              required: %w[token user]
+            }
+          }
+        end
+
+        # Get all schemas (Typelizer + common)
+        def all_schemas
+          schemas = common_schemas
+
+          begin
+            schemas.merge!(typelizer_schemas)
+          rescue StandardError => e
+            Rails.logger.warn "Failed to load Typelizer schemas: #{e.message}"
+          end
+
+          schemas
+        end
+
+        private
+
+        def typelizer_schemas
+          with_typelizer_enabled do
+            schemas = Typelizer.openapi_schemas
+            schemas.each_value { |s| s[:'x-typelizer'] = true }
+            fix_refs(schemas)
+            schemas
+          end
+        end
+
+        # Typelizer's native OpenAPI generator treats unrecognized type strings
+        # as $ref to other schemas. This fixes three cases:
+        # 1. any → {type: :object}
+        # 2. Record<string, unknown> → {type: :object}
+        # 3. Union types (e.g., 'TypeA | TypeB | null') → proper anyOf schemas
+        def fix_refs(schemas)
+          schemas.each_value do |schema|
+            next unless schema[:properties]
+
+            schema[:properties].each do |key, prop|
+              schema[:properties][key] = fix_ref(prop)
+            end
+          end
+        end
+
+        def fix_ref(prop)
+          # Direct $ref
+          if (ref_value = prop['$ref'])
+            return resolve_ref(ref_value, prop)
+          end
+
+          # allOf wrapper (used for nullable refs)
+          if prop[:allOf]&.length == 1 && (ref_value = prop[:allOf][0]['$ref'])
+            resolved = resolve_ref(ref_value, {})
+            resolved[:nullable] = true if prop[:nullable]
+            return resolved
+          end
+
+          prop
+        end
+
+        def resolve_ref(ref_value, base)
+          ref_name = ref_value.sub('#/components/schemas/', '')
+
+          # any → {type: :object} (closest OpenAPI equivalent)
+          return base.except('$ref').merge(type: :object) if ref_name == 'any'
+
+          # Record<string, unknown> → {type: :object}
+          if ref_name.start_with?('Record<')
+            return base.except('$ref').merge(type: :object)
+          end
+
+          # Union types (e.g., 'TypeA | TypeB | null') → anyOf
+          if ref_name.include?(' | ')
+            types = ref_name.split(' | ').map(&:strip)
+            nullable = types.delete('null')
+            refs = types.map { |t| { '$ref' => "#/components/schemas/#{t}" } }
+            result = { anyOf: refs }
+            result[:nullable] = true if nullable
+            return result
+          end
+
+          base
+        end
+
+        # Typelizer is normally disabled in test/production, but we need it
+        # enabled to generate OpenAPI schemas from serializer type hints
+        def with_typelizer_enabled
+          original = ENV['DISABLE_TYPELIZER']
+          ENV['DISABLE_TYPELIZER'] = 'false'
+          yield
+        ensure
+          ENV['DISABLE_TYPELIZER'] = original
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/testing_support/factories.rb

@@ -1,3 +1 @@
-Dir["#{File.dirname(__FILE__)}/factories/**"].each do |f|
-  load File.expand_path(f)
-end
+# No factories in api, gem, keeping for backwards compatibility

data/lib/spree/api/testing_support/v3/base.rb

@@ -0,0 +1,118 @@
+# Helper module for generating JWT tokens in tests
+module Spree
+  module Api
+    module V3
+      module TestingSupport
+        def self.generate_jwt(user, expiration: 24.hours.to_i)
+          user_type = user.is_a?(Spree.admin_user_class) ? 'admin' : 'customer'
+          payload = {
+            user_id: user.id,
+            user_type: user_type,
+            exp: Time.current.to_i + expiration
+          }
+          secret = Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
+          JWT.encode(payload, secret, 'HS256')
+        end
+      end
+    end
+  end
+end
+
+shared_context 'API v3 Store' do
+  let(:store) { @default_store || create(:store, default: true) }
+  let(:api_key) { create(:api_key, :publishable, store: store) }
+  let(:api_key_headers) { { 'x-spree-api-key' => api_key.token } }
+
+  let(:user) { create(:user_with_addresses) }
+  let(:jwt_token) { Spree::Api::V3::TestingSupport.generate_jwt(user) }
+  let(:bearer_headers) { api_key_headers.merge('Authorization' => "Bearer #{jwt_token}") }
+
+  before do
+    allow_any_instance_of(Spree::Api::V3::BaseController).to receive(:current_store).and_return(store)
+  end
+end
+
+shared_context 'API v3 Store authenticated' do
+  include_context 'API v3 Store'
+
+  let(:headers) { bearer_headers }
+end
+
+shared_context 'API v3 Store guest' do
+  include_context 'API v3 Store'
+
+  let(:headers) { api_key_headers }
+end
+
+# Shared examples for common response patterns
+shared_examples 'returns 200 OK' do
+  it 'returns 200 status' do
+    subject
+    expect(response).to have_http_status(:ok)
+  end
+end
+
+shared_examples 'returns 201 Created' do
+  it 'returns 201 status' do
+    subject
+    expect(response).to have_http_status(:created)
+  end
+end
+
+shared_examples 'returns 204 No Content' do
+  it 'returns 204 status' do
+    subject
+    expect(response).to have_http_status(:no_content)
+  end
+end
+
+shared_examples 'returns 401 Unauthorized' do
+  it 'returns 401 status' do
+    subject
+    expect(response).to have_http_status(:unauthorized)
+  end
+end
+
+shared_examples 'returns 403 Forbidden' do
+  it 'returns 403 status' do
+    subject
+    expect(response).to have_http_status(:forbidden)
+  end
+end
+
+shared_examples 'returns 404 Not Found' do
+  it 'returns 404 status' do
+    subject
+    expect(response).to have_http_status(:not_found)
+  end
+end
+
+shared_examples 'returns 422 Unprocessable Entity' do
+  it 'returns 422 status' do
+    subject
+    expect(response).to have_http_status(:unprocessable_content)
+  end
+end
+
+shared_examples 'requires API key' do
+  context 'without API key' do
+    let(:headers) { {} }
+
+    it 'returns 401 unauthorized' do
+      subject
+      expect(response).to have_http_status(:unauthorized)
+      expect(json_response[:error]).to include('API key')
+    end
+  end
+end
+
+shared_examples 'requires authentication' do
+  context 'without JWT token' do
+    let(:headers) { api_key_headers }
+
+    it 'returns 401 unauthorized' do
+      subject
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+end