spree_api 5.3.4 → 5.4.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8103cf9477d203a505f580a267a96ad940babc92b4dd09814d86dba03e330300
-  data.tar.gz: 98f44fdc93e9c4cad74c52ccb58b2b82d62064c53dc9f7fa9d963ca78ed37b41
+  metadata.gz: 5e2afbf0958129824507229d5994a8cf37076727f77f7c8a9cebade0a59c237b
+  data.tar.gz: ca64a94e5e43b4bbc4e0bbc02123102c0e1c49f03381f41d9021596e4b2fe013
 SHA512:
-  metadata.gz: 8b63700e0591ed1aa8f55837aec0f9492016f7cd35ccf3b202e8dcb764a35d82188cb7fc2cac64ff99c1f0a07b05142b59c48be48b01629810dfe4a2bd0cecaa
-  data.tar.gz: 5d8809fcfe387e374449bb285df5c10df363a2e972e8b3c0fba5c2d7644841e437e70b166bd981765801390c706361bdcb2423c2922a0c7e588735a5d9adf2f9
+  metadata.gz: 56393e0ac09195448b830d59283804af1634734c656961fbe07ec21b1ae7f752cdc2a6c0cabd19f5a48a26a548d6ae616cfc5744b823734f3928369d4e201588
+  data.tar.gz: 21477917637463a37f0c3085c497974adc26aa3228b7b5665cc0f3da5051f459c5681b853e739fe44f6e4171d0be71a702baadf141dd450a437ffe1ce15cc6fd

data/README.md

@@ -8,55 +8,76 @@ Spree API provides RESTful API endpoints for building custom storefronts, mobile
 
 This gem includes:
 
-- **Storefront API** - Customer-facing endpoints for cart, checkout, products, and accounts
-- **Platform API** - Administrative endpoints for managing orders, products, and store settings
+- **Store API v3** - Customer-facing endpoints for cart, checkout, products, and accounts
+- **Admin API v3** - Administrative endpoints for managing orders, products, and store settings
 - **Webhooks** - Event-driven notifications to external systems
-- **OAuth2 Authentication** - Token-based authentication via Doorkeeper
-- **JSONAPI Serializers** - Standardized API responses
+- **API Key Authentication** - Secure token-based authentication with scopes
+- **Alba Serializers** - Fast, flexible JSON serialization with TypeScript type generation
 
 ## Installation
 
 This gem is included in every Spree installation. No additional steps are required.
 
-## API Endpoints
+## API v3 Endpoints
 
-### Storefront API (v2)
+### Store API
 
-The Storefront API is designed for building custom frontends:
+The Store API is designed for building custom storefronts:
 
 ```
-GET    /api/v2/storefront/products
-GET    /api/v2/storefront/products/:id
-GET    /api/v2/storefront/taxons
-POST   /api/v2/storefront/cart
-PATCH  /api/v2/storefront/cart/add_item
-PATCH  /api/v2/storefront/checkout
-POST   /api/v2/storefront/account
+GET    /api/v3/products
+GET    /api/v3/products/:id
+GET    /api/v3/taxons
+GET    /api/v3/taxonomies
+POST   /api/v3/cart
+PATCH  /api/v3/cart/add_item
+PATCH  /api/v3/checkout
+GET    /api/v3/account
 ```
 
-### Platform API
+### Admin API
 
-The Platform API provides administrative access:
+The Admin API provides full administrative access:
 
 ```
-GET    /api/v2/platform/orders
-POST   /api/v2/platform/products
-PATCH  /api/v2/platform/variants/:id
-DELETE /api/v2/platform/line_items/:id
+GET    /api/v3/admin/orders
+POST   /api/v3/admin/products
+PATCH  /api/v3/admin/variants/:id
+DELETE /api/v3/admin/line_items/:id
 ```
 
 ## Authentication
 
-### OAuth2 Token Authentication
+### API Key Authentication
+
+Create API keys with appropriate scopes:
+
+```ruby
+# Store API key (customer-facing)
+api_key = Spree::ApiKey.create!(
+  name: 'My Storefront',
+  scope: 'store',
+  store: current_store
+)
+
+# Admin API key (full access)
+admin_key = Spree::ApiKey.create!(
+  name: 'Admin Integration',
+  scope: 'admin',
+  store: current_store
+)
+```
+
+Use the API key in requests:
 
 ```bash
-# Request access token
-curl -X POST https://your-store.com/spree_oauth/token \
-  -d "grant_type=password&username=user@example.com&password=secret"
+# Store API
+curl -H "Authorization: Bearer spree_pk_xxx" \
+  https://your-store.com/api/v3/products
 
-# Use token in requests
-curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-  https://your-store.com/api/v2/storefront/account
+# Admin API
+curl -H "Authorization: Bearer spree_sk_xxx" \
+  https://your-store.com/api/v3/admin/orders
 ```
 
 ### Guest Cart Token
@@ -65,25 +86,43 @@ For guest checkout, use the `X-Spree-Order-Token` header:
 
 ```bash
 curl -H "X-Spree-Order-Token: ORDER_TOKEN" \
-  https://your-store.com/api/v2/storefront/cart
+  https://your-store.com/api/v3/cart
 ```
 
 ## Serializers
 
-API responses use JSONAPI format. Customize serializers by creating your own:
+API v3 uses Alba serializers for fast JSON serialization. Serializers are organized by scope:
+
+- `app/serializers/spree/api/v3/` - Store API serializers
+- `app/serializers/spree/api/v3/admin/` - Admin API serializers
+
+Customize serializers by creating your own:
 
 ```ruby
 # app/serializers/my_app/product_serializer.rb
 module MyApp
-  class ProductSerializer < Spree::V2::Storefront::ProductSerializer
+  class ProductSerializer < Spree::Api::V3::ProductSerializer
     attribute :custom_field
   end
 end
 
 # Configure in initializer
-Spree.api.storefront_product_serializer = 'MyApp::ProductSerializer'
+Spree.api.product_serializer = 'MyApp::ProductSerializer'
 ```
 
+## TypeScript Types
+
+TypeScript types are automatically generated from serializers using [typelizer](https://github.com/skryukov/typelizer):
+
+```bash
+# Generate TypeScript types
+bundle exec rake typelizer:generate
+```
+
+Types are output to `sdk/src/types/generated/` with naming:
+- Store types: `StoreProduct`, `StoreOrder`, etc.
+- Admin types: `AdminProduct`, `AdminOrder`, etc.
+
 ## Testing
 
 ```bash
@@ -94,6 +133,5 @@ bundle exec rspec
 
 ## Documentation
 
-- [Storefront API Reference](https://docs.spreecommerce.org/api/storefront)
-- [Platform API Reference](https://docs.spreecommerce.org/api/platform)
+- [API Reference](https://docs.spreecommerce.org/api)
 - [Authentication Guide](https://docs.spreecommerce.org/developer/api/authentication)

data/Rakefile

@@ -23,7 +23,32 @@ namespace :rswag do
         'spec/integration/**/*_spec.rb'
       )
 
+      # OPENAPI env var prevents spec_helper from overriding --order defined with :random
+      ENV['OPENAPI'] = 'true'
       t.rspec_opts = ['--format Rswag::Specs::SwaggerFormatter', '--order defined']
     end
   end
 end
+
+namespace :typelizer do
+  desc 'Generate TypeScript types from Alba serializers'
+  task :generate do
+    ENV['RAILS_ENV'] ||= 'test'
+    ENV['DISABLE_TYPELIZER'] = 'false'
+
+    require File.expand_path('spec/dummy/config/environment', __dir__)
+
+    # Eager load serializers so typelizer can find them
+    serializers_path = File.expand_path('app/serializers/spree/api/v3', __dir__)
+    Rails.autoloaders.main.eager_load_dir(serializers_path)
+
+    require 'typelizer/generator'
+    serializers = Typelizer::Generator.call(force: true)
+
+    puts "Generated TypeScript types for #{serializers.size} serializers"
+    puts "Output: #{Typelizer.configuration.writer_config.output_dir}"
+  end
+
+  desc 'Clean and regenerate TypeScript types'
+  task refresh: :generate
+end

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

@@ -0,0 +1,76 @@
+module Spree
+  module Api
+    module V3
+      module ApiKeyAuthentication
+        extend ActiveSupport::Concern
+
+        included do
+          # @!attribute [r] current_api_key
+          #   The authenticated API key for the current request.
+          #   @return [Spree::ApiKey, nil]
+          attr_reader :current_api_key
+        end
+
+        # Authenticates a publishable API key (pk_*) for Store API requests.
+        # Looks up the key by plaintext token scoped to the current store.
+        #
+        # @return [Boolean] true if authentication succeeded, false otherwise
+        def authenticate_api_key!
+          @current_api_key = current_store.api_keys.active.publishable.find_by(token: extract_api_key)
+
+          unless @current_api_key
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:invalid_token],
+              message: 'Valid API key required',
+              status: :unauthorized
+            )
+            return false
+          end
+
+          touch_api_key_if_needed(@current_api_key)
+          true
+        end
+
+        # Authenticates a secret API key (sk_*) for Admin API requests.
+        # Computes the HMAC-SHA256 digest of the provided token and looks up
+        # by +token_digest+, then verifies it belongs to the current store.
+        #
+        # @return [Boolean] true if authentication succeeded, false otherwise
+        def authenticate_secret_key!
+          @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
+          @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
+
+          unless @current_api_key
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:invalid_token],
+              message: 'Valid secret API key required',
+              status: :unauthorized
+            )
+            return false
+          end
+
+          touch_api_key_if_needed(@current_api_key)
+          true
+        end
+
+        private
+
+        # Marks the API key as used at most once per hour
+        # to avoid unnecessary DB writes and job queue pressure on every request.
+        # This follows the same approach as GitHub's personal access tokens.
+        def touch_api_key_if_needed(api_key)
+          return if api_key.last_used_at.present? && api_key.last_used_at > 1.hour.ago
+
+          Spree::ApiKeys::MarkAsUsed.perform_later(api_key.id, Time.current)
+        end
+
+        # Extracts the API key from the request headers or params.
+        #
+        # @return [String, nil] the API key token
+        def extract_api_key
+          request.headers['X-Spree-Api-Key'].presence || params[:api_key]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,261 @@
+module Spree
+  module Api
+    module V3
+      module ErrorHandler
+        extend ActiveSupport::Concern
+
+        # Stripe-style error codes for consistent API error responses
+        ERROR_CODES = {
+          # Authentication & authorization errors
+          authentication_required: 'authentication_required',
+          authentication_failed: 'authentication_failed',
+          access_denied: 'access_denied',
+          invalid_token: 'invalid_token',
+          invalid_provider: 'invalid_provider',
+
+          # Resource errors
+          record_not_found: 'record_not_found',
+          resource_invalid: 'resource_invalid',
+
+          # 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',
+
+          # Line item errors
+          line_item_not_found: 'line_item_not_found',
+          variant_not_found: 'variant_not_found',
+          insufficient_stock: 'insufficient_stock',
+          invalid_quantity: 'invalid_quantity',
+
+          # Validation errors
+          validation_error: 'validation_error',
+          parameter_missing: 'parameter_missing',
+          parameter_invalid: 'parameter_invalid',
+
+          # Payment errors
+          payment_failed: 'payment_failed',
+          payment_processing_error: 'payment_processing_error',
+          gateway_error: 'gateway_error',
+
+          # Digital download errors
+          attachment_missing: 'attachment_missing',
+          download_unauthorized: 'download_unauthorized',
+          digital_link_expired: 'digital_link_expired',
+          download_limit_exceeded: 'download_limit_exceeded',
+
+          # Rate limiting errors
+          rate_limit_exceeded: 'rate_limit_exceeded',
+
+          # Request errors
+          request_too_large: 'request_too_large',
+
+          # General errors
+          processing_error: 'processing_error',
+          invalid_request: 'invalid_request'
+        }.freeze
+
+        included do
+          # Override base controller error handlers
+          rescue_from ActiveRecord::RecordNotFound, with: :handle_record_not_found
+          rescue_from CanCan::AccessDenied, with: :handle_access_denied
+          rescue_from Spree::Core::GatewayError, with: :handle_gateway_error
+          rescue_from ActionController::ParameterMissing, with: :handle_parameter_missing
+          rescue_from ActiveRecord::RecordInvalid, with: :handle_record_invalid
+          rescue_from ArgumentError, with: :handle_argument_error
+          rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_parse_error
+          rescue_from StateMachines::InvalidTransition, with: :handle_invalid_transition
+        end
+
+        protected
+
+        # Main error rendering method with Stripe-style structure
+        def render_error(code:, message:, status:, details: nil)
+          error_response = {
+            error: {
+              code: code,
+              message: message
+            }
+          }
+
+          error_response[:error][:details] = details if details.present?
+
+          render json: error_response, status: status
+        end
+
+        # Convenience method for validation errors with ActiveModel::Errors
+        def render_validation_error(errors, code: ERROR_CODES[:validation_error])
+          details = errors.is_a?(ActiveModel::Errors) ? format_validation_details(errors) : nil
+          message = errors.is_a?(ActiveModel::Errors) ? errors.full_messages.to_sentence : errors.to_s
+
+          render_error(
+            code: code,
+            message: message,
+            status: :unprocessable_content,
+            details: details
+          )
+        end
+
+        # Convenience method for service result errors
+        def render_service_error(error, code: ERROR_CODES[:processing_error], status: :unprocessable_content)
+          if error.is_a?(ActiveModel::Errors)
+            render_validation_error(error, code: code)
+          elsif error.is_a?(String)
+            render_error(code: code, message: error, status: status)
+          else
+            render_error(code: code, message: error.to_s, status: status)
+          end
+        end
+
+        # Legacy support - redirect to new error handling
+        def render_errors(errors, status = :unprocessable_content)
+          code = infer_error_code(errors, status)
+
+          if errors.is_a?(ActiveModel::Errors)
+            render_validation_error(errors, code: code)
+          else
+            message = errors.is_a?(String) ? errors : errors.to_s
+            render_error(code: code, message: message, status: status)
+          end
+        end
+
+        # Exception handlers
+        def handle_record_not_found(exception)
+          code = determine_not_found_code(exception)
+          message = generate_not_found_message(exception)
+
+          render_error(
+            code: code,
+            message: message,
+            status: :not_found
+          )
+        end
+
+        def handle_access_denied(exception)
+          render_error(
+            code: ERROR_CODES[:access_denied],
+            message: exception.message,
+            status: :forbidden
+          )
+        end
+
+        def handle_gateway_error(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          render_error(
+            code: ERROR_CODES[:gateway_error],
+            message: exception.message,
+            status: :unprocessable_content
+          )
+        end
+
+        def handle_parameter_missing(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          render_error(
+            code: ERROR_CODES[:parameter_missing],
+            message: exception.message,
+            status: :bad_request
+          )
+        end
+
+        def handle_record_invalid(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          render_validation_error(exception.record.errors)
+        end
+
+        def handle_argument_error(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          render_error(
+            code: ERROR_CODES[:invalid_request],
+            message: exception.message,
+            status: :bad_request
+          )
+        end
+
+        def handle_parse_error(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          message = exception.respond_to?(:original_message) ? exception.original_message : exception.message
+          render_error(
+            code: ERROR_CODES[:invalid_request],
+            message: message,
+            status: :bad_request
+          )
+        end
+
+        def handle_invalid_transition(exception)
+          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
+          render_error(
+            code: ERROR_CODES[:order_cannot_transition],
+            message: exception.message,
+            status: :unprocessable_content
+          )
+        end
+
+        private
+
+        # Format validation errors for details field
+        def format_validation_details(errors)
+          errors.messages.transform_values do |messages|
+            messages.map { |msg| msg }
+          end
+        end
+
+        # Infer error code from context
+        def infer_error_code(errors, status)
+          case status
+          when :not_found
+            ERROR_CODES[:record_not_found]
+          when :forbidden
+            ERROR_CODES[:access_denied]
+          when :bad_request
+            ERROR_CODES[:invalid_request]
+          when :unprocessable_content
+            errors.is_a?(ActiveModel::Errors) ? ERROR_CODES[:validation_error] : ERROR_CODES[:processing_error]
+          else
+            ERROR_CODES[:processing_error]
+          end
+        end
+
+        # Determine specific not found code based on model
+        def determine_not_found_code(exception)
+          model_name = extract_model_name(exception)
+
+          case model_name
+          when 'order'
+            ERROR_CODES[:order_not_found]
+          when 'line_item'
+            ERROR_CODES[:line_item_not_found]
+          when 'variant'
+            ERROR_CODES[:variant_not_found]
+          else
+            ERROR_CODES[:record_not_found]
+          end
+        end
+
+        # Generate human-readable not found message
+        def generate_not_found_message(exception)
+          model_name = extract_model_name(exception)
+          Spree.t(:record_not_found, scope: 'api', model: model_name&.humanize || 'record')
+        end
+
+        # Extract clean model name from exception
+        def extract_model_name(exception)
+          return nil unless exception.model
+
+          # Remove Spree:: namespace and convert to underscore
+          exception.model.to_s.demodulize.underscore
+        end
+
+        # Error reporting context
+        def error_context
+          {
+            user_id: current_user&.id,
+            store_id: current_store&.id,
+            request_id: request.request_id
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module Spree
+  module Api
+    module V3
+      # Provides HTTP caching support for API v3 controllers
+      #
+      # Strategy:
+      # - Guest users: Public HTTP caching with CDN support (5-15 min TTL)
+      # - Authenticated users: Private, no-store (no caching)
+      #
+      # Uses ETag and Last-Modified headers for cache validation.
+      module HttpCaching
+        extend ActiveSupport::Concern
+
+        included do
+          before_action :set_vary_headers
+        end
+
+        protected
+
+        # Check if the current user is a guest (no authentication)
+        def guest_user?
+          current_user.nil?
+        end
+
+        # Set Vary headers to ensure proper CDN caching by currency/locale
+        def set_vary_headers
+          if guest_user?
+            response.headers['Vary'] = 'Accept, x-spree-currency, x-spree-locale'
+          else
+            response.headers['Cache-Control'] = 'private, no-store'
+          end
+        end
+
+        # Apply HTTP caching for a collection (index actions)
+        # Only caches for guest users
+        #
+        # @param collection [ActiveRecord::Relation] The collection to cache
+        # @param expires_in [ActiveSupport::Duration] Cache TTL (default: 5 minutes)
+        # @param stale_while_revalidate [ActiveSupport::Duration] Allow stale responses while revalidating
+        # @return [Boolean] true if response should be rendered, false if 304 Not Modified
+        def cache_collection(collection, expires_in: 5.minutes, stale_while_revalidate: 30.seconds)
+          return true unless guest_user?
+
+          expires_in expires_in, public: true, stale_while_revalidate: stale_while_revalidate
+
+          # Use collection's cache key for ETag
+          cache_key = collection_cache_key(collection)
+          response.headers['ETag'] = %("#{Digest::MD5.hexdigest(cache_key)}")
+
+          # Return false if client has fresh cache (304 Not Modified)
+          !request.fresh?(response)
+        end
+
+        # Apply HTTP caching for a single resource (show actions)
+        # Only caches for guest users
+        #
+        # @param resource [ActiveRecord::Base] The resource to cache
+        # @param expires_in [ActiveSupport::Duration] Cache TTL (default: 5 minutes)
+        # @return [Boolean] true if response should be rendered, false if 304 Not Modified
+        def cache_resource(resource, expires_in: 5.minutes)
+          return true unless guest_user?
+
+          expires_in expires_in, public: true
+
+          # Use Rails' stale? which handles ETag and Last-Modified
+          stale?(resource, public: true)
+        end
+
+        private
+
+        # Build a cache key for a collection
+        # Includes: query params, pagination, includes, currency, locale
+        # Strips order to avoid PostgreSQL errors with DISTINCT + subquery ORDER BY expressions
+        def collection_cache_key(collection)
+          parts = [
+            collection.reorder(nil).cache_key_with_version,
+            params[:include],
+            params[:q],
+            params[:page],
+            params[:per_page],
+            current_currency,
+            current_locale
+          ]
+
+          parts.compact.join('/')
+        end
+      end
+    end
+  end
+end