Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

REST API v3 PoC

Damian Legawieca3951d475aa7
diff --git a/api/.claude/settings.local.json b/api/.claude/settings.local.json
new file mode 100644
index 0000000000..f4b2128360
--- /dev/null
+++ b/api/.claude/settings.local.json
@@ -0,0 +1,9 @@
+{
+ "permissions": {
+ "allow": [
+ "Read(//Users/damian/github/spree/**)"
+ ],
+ "deny": [],
+ "ask": []
+ }
+}
diff --git a/api/app/controllers/concerns/spree/api/v3/authentication.rb b/api/app/controllers/concerns/spree/api/v3/authentication.rb
new file mode 100644
index 0000000000..802a1c8c3a
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/authentication.rb
@@ -0,0 +1,56 @@
+module Spree
+ module Api
+ module V3
+ module Authentication
+ extend ActiveSupport::Concern
+
+ include Spree::Api::V3::ErrorHandler
+
+ included do
+ attr_reader :current_user
+ end
+
+ # Optional authentication - doesn't fail if no token
+ def authenticate_user
+ token = extract_token
+ return unless token.present?
+
+ payload = decode_jwt(token)
+ @current_user = Spree.user_class.find(payload['user_id'])
+ rescue JWT::DecodeError, JWT::ExpiredSignature, ActiveRecord::RecordNotFound => e
+ Rails.logger.debug { "JWT authentication failed: #{e.message}" }
+ @current_user = nil
+ end
+
+ # Required authentication - fails if no valid token
+ def require_authentication!
+ authenticate_user
+
+ unless current_user
+ render_error(code: ErrorHandler::ERROR_CODES[:authentication_required], message: 'Authentication required', status: :unauthorized)
+ return false
+ end
+ end
+
+ private
+
+ def extract_token
+ # Check Authorization header first
+ header = request.headers['Authorization']
+ return header.split(' ').last if header.present? && header.start_with?('Bearer ')
+
+ # Fallback to query param for special cases (e.g., digital downloads)
+ params[:token]
+ end
+
+ def decode_jwt(token)
+ JWT.decode(token, jwt_secret, true, algorithm: 'HS256').first
+ end
+
+ def jwt_secret
+ Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/concerns/spree/api/v3/error_handler.rb b/api/app/controllers/concerns/spree/api/v3/error_handler.rb
new file mode 100644
index 0000000000..7e7d63cf27
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/error_handler.rb
@@ -0,0 +1,259 @@
+module Spree
+ module Api
+ module V3
+ module ErrorHandler
+ extend ActiveSupport::Concern
+
+ # Stripe-style error codes for consistent API error responses
+ ERROR_CODES = {
+ # Authentication errors
+ authentication_required: 'authentication_required',
+ authentication_failed: 'authentication_failed',
+
+ # 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',
+
+ # Authentication & authorization errors
+ authentication_required: 'authentication_required',
+ authentication_failed: 'authentication_failed',
+ access_denied: 'access_denied',
+ invalid_token: 'invalid_token',
+ invalid_provider: 'invalid_provider',
+
+ # 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',
+
+ # 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_entity,
+ details: details
+ )
+ end
+
+ # Convenience method for service result errors
+ def render_service_error(error, code: ERROR_CODES[:processing_error], status: :unprocessable_entity)
+ 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_entity)
+ 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_entity
+ )
+ 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_entity
+ )
+ 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_entity
+ 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)
+ 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
diff --git a/api/app/controllers/concerns/spree/api/v3/expandable_resources.rb b/api/app/controllers/concerns/spree/api/v3/expandable_resources.rb
new file mode 100644
index 0000000000..920d37a226
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/expandable_resources.rb
@@ -0,0 +1,46 @@
+module Spree
+ module Api
+ module V3
+ # Provides support for expanding nested resources in serializers
+ # Similar to Stripe's expand parameter: https://docs.stripe.com/api/expanding_objects
+ #
+ # Usage:
+ # GET /api/v3/storefront/products/1?include=variants,images,taxons
+ # GET /api/v3/storefront/products/1?include=variants.images,variants.option_values
+ module ExpandableResources
+ extend ActiveSupport::Concern
+
+ protected
+
+ # Returns list of associations to include based on query params
+ # @return [Array<String>] List of associations to expand
+ def requested_includes
+ return [] unless params[:include].present?
+
+ # Split by comma, remove whitespace
+ params[:include].to_s.split(',').map(&:strip).reject(&:blank?)
+ end
+
+ # Check if a specific association should be included
+ # @param association [String, Symbol] The association name
+ # @return [Boolean]
+ def include?(association)
+ requested_includes.include?(association.to_s)
+ end
+
+ # Get nested includes for an association
+ # For example, if params[:include] = 'variants.images,variants.option_values'
+ # Then nested_includes_for('variants') returns ['images', 'option_values']
+ #
+ # @param parent [String, Symbol] The parent association
+ # @return [Array<String>]
+ def nested_includes_for(parent)
+ prefix = "#{parent}."
+ requested_includes
+ .select { |inc| inc.start_with?(prefix) }
+ .map { |inc| inc.sub(prefix, '') }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/concerns/spree/api/v3/order_concern.rb b/api/app/controllers/concerns/spree/api/v3/order_concern.rb
new file mode 100644
index 0000000000..1ded95360b
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/order_concern.rb
@@ -0,0 +1,48 @@
+module Spree
+ module Api
+ module V3
+ module OrderConcern
+ extend ActiveSupport::Concern
+
+ # Allow access to order via order token for guests or authenticated users
+ def authorize_order_access!
+ # Allow if user is authenticated and owns the order
+ return if current_user && @order.user == current_user
+
+ # Allow guest access via order token
+ order_token = extract_order_token
+
+ unless order_token.present? && @order.token == order_token
+ render_error(
+ code: ERROR_CODES[:access_denied],
+ message: 'Access denied',
+ status: :forbidden
+ )
+ return false
+ end
+ end
+
+ protected
+
+ # Finds order by number from params
+ # Uses params[:order_id] for nested resources (line items, payments, etc.)
+ # Uses params[:id] for order resource endpoints
+ def set_order
+ order_param = params[:order_id].presence || params[:id]
+ @order = current_store.orders.incomplete.friendly.find(order_param)
+ end
+
+ private
+
+ def extract_order_token
+ # Check X-Spree-Order-Token header first
+ header = request.headers['X-Spree-Order-Token']
+ return header if header.present?
+
+ # Fallback to query param
+ params[:order_token]
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb b/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb
new file mode 100644
index 0000000000..026e27628a
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb
@@ -0,0 +1,21 @@
+module Spree
+ module Api
+ module V3
+ module ResourceSerializer
+ extend ActiveSupport::Concern
+
+ protected
+
+ # Serialize a single resource
+ def serialize_resource(resource)
+ serializer_class.new(resource, serializer_context).as_json
+ end
+
+ # Serialize a collection of resources
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/concerns/spree/api/v3/storefront/authentication.rb b/api/app/controllers/concerns/spree/api/v3/storefront/authentication.rb
new file mode 100644
index 0000000000..7c24466747
--- /dev/null
+++ b/api/app/controllers/concerns/spree/api/v3/storefront/authentication.rb
@@ -0,0 +1,33 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ # This concern provides helper methods for generating JWT tokens
+ # For authentication verification, see Spree::Api::V3::Authentication
+ module Authentication
+ extend ActiveSupport::Concern
+
+ protected
+
+ # Generate a JWT token for a user
+ # @param user [Spree.user_class] The user to generate a token for
+ # @param expiration [Integer] Time in seconds until expiration (default 24 hours)
+ # @return [String] The JWT token
+ def generate_jwt(user, expiration: 24.hours.to_i)
+ payload = {
+ user_id: user.id,
+ exp: Time.current.to_i + expiration
+ }
+ JWT.encode(payload, jwt_secret, 'HS256')
+ end
+
+ private
+
+ def jwt_secret
+ Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/base_controller.rb b/api/app/controllers/spree/api/v3/base_controller.rb
new file mode 100644
index 0000000000..3fb53f82f8
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/base_controller.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Api
+ module V3
+ class BaseController < ActionController::API
+ include ActiveStorage::SetCurrent
+ include CanCan::ControllerAdditions
+ include Spree::Core::ControllerHelpers::StrongParameters
+ include Spree::Core::ControllerHelpers::Store
+ include Spree::Core::ControllerHelpers::Locale
+ include Spree::Core::ControllerHelpers::Currency
+ include Spree::Api::V3::Authentication
+ include Spree::Api::V3::ExpandableResources
+ include Spree::Api::V3::ErrorHandler
+
+ # Optional authentication by default
+ before_action :authenticate_user
+
+ protected
+
+ # Override to use current_user from JWT authentication
+ def spree_current_user
+ current_user
+ end
+
+ alias try_spree_current_user spree_current_user
+
+ # CanCanCan ability
+ def current_ability
+ @current_ability ||= Spree::Ability.new(current_user, ability_options)
+ end
+
+ def ability_options
+ { store: current_store }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/resource_controller.rb b/api/app/controllers/spree/api/v3/resource_controller.rb
new file mode 100644
index 0000000000..2b16a6e10b
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/resource_controller.rb
@@ -0,0 +1,149 @@
+module Spree
+ module Api
+ module V3
+ class ResourceController < ::Spree::Api::V3::BaseController
+ include Spree::Api::V3::ResourceSerializer
+ include Pagy::Method
+
+ before_action :set_resource, only: [:show, :update, :destroy]
+
+ # GET /api/v3/resource
+ def index
+ @collection = collection
+
+ render json: {
+ data: serialize_collection(@collection),
+ meta: collection_meta(@collection)
+ }
+ end
+
+ # GET /api/v3/resource/:id
+ def show
+ render json: serialize_resource(@resource)
+ end
+
+ # POST /api/v3/resource
+ def create
+ @resource = model_class.new(permitted_params)
+ authorize_resource!(@resource, :create)
+
+ if @resource.save
+ render json: serialize_resource(@resource), status: :created
+ else
+ render_errors(@resource.errors)
+ end
+ end
+
+ # PATCH /api/v3/resource/:id
+ def update
+ if @resource.update(permitted_params)
+ render json: serialize_resource(@resource)
+ else
+ render_errors(@resource.errors)
+ end
+ end
+
+ # DELETE /api/v3/resource/:id
+ def destroy
+ @resource.destroy
+ head :no_content
+ end
+
+ protected
+
+ # Sets the resource for show, update, destroy actions
+ def set_resource
+ @resource = scope.find(params[:id])
+ authorize_resource!(@resource)
+ end
+
+ # Authorize resource with CanCanCan
+ def authorize_resource!(resource = @resource, action = action_name.to_sym)
+ authorize!(action, resource)
+ end
+
+ # Returns ransack-filtered, sorted and paginated collection
+ # @return [ActiveRecord::Relation]
+ def collection
+ return @collection if @collection.present?
+
+ @search = scope.ransack(ransack_params)
+ result = @search.result(distinct: true)
+ @pagy, records = pagy(result, limit: limit, page: page)
+ records
+ end
+
+ # Ransack query parameters
+ def ransack_params
+ params[:q] || {}
+ end
+
+ # Pagination parameters
+ def page
+ params[:page]&.to_i || 1
+ end
+
+ def limit
+ limit_param = params[:per_page]&.to_i || params[:limit]&.to_i || 25
+ [limit_param, 100].min # Max 100 per page
+ end
+
+ # Metadata for collection responses
+ def collection_meta(_collection)
+ return {} unless @pagy
+
+ {
+ page: @pagy.page,
+ limit: @pagy.limit,
+ count: @pagy.count,
+ pages: @pagy.pages,
+ from: @pagy.from,
+ to: @pagy.to,
+ in: @pagy.in,
+ previous: @pagy.previous,
+ next: @pagy.next
+ }
+ end
+
+ # Base scope with store, ability, and includes
+ def scope
+ base_scope = model_class.for_store(current_store)
+ base_scope = base_scope.accessible_by(current_ability, :show)
+ base_scope = base_scope.includes(scope_includes) if scope_includes.any?
+ model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
+ end
+
+ # Override in subclass to eager load associations
+ def scope_includes
+ []
+ end
+
+ # Override in subclass to define the model
+ def model_class
+ raise NotImplementedError, 'Subclass must implement model_class'
+ end
+
+ # Override in subclass to define the serializer
+ def serializer_class
+ raise NotImplementedError, 'Subclass must implement serializer_class'
+ end
+
+ # Override in subclass to permit parameters
+ def permitted_params
+ raise NotImplementedError, 'Subclass must implement permitted_params'
+ end
+
+ # Context passed to serializers
+ def serializer_context
+ {
+ currency: current_currency,
+ store: current_store,
+ user: current_user,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/addresses_controller.rb b/api/app/controllers/spree/api/v3/storefront/addresses_controller.rb
new file mode 100644
index 0000000000..372acac24a
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/addresses_controller.rb
@@ -0,0 +1,29 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class AddressesController < ResourceController
+ before_action :require_authentication!
+
+ protected
+
+ def scope
+ current_user.addresses
+ end
+
+ def model_class
+ Spree::Address
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_address_serializer.constantize
+ end
+
+ def permitted_params
+ params.require(:address).permit(Spree::PermittedAttributes.address_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/auth_controller.rb b/api/app/controllers/spree/api/v3/storefront/auth_controller.rb
new file mode 100644
index 0000000000..9cdc93ee37
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/auth_controller.rb
@@ -0,0 +1,72 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class AuthController < BaseController
+ include Spree::Api::V3::Storefront::Authentication
+
+ skip_before_action :authenticate_user, only: [:create, :register]
+ before_action :require_authentication!, only: [:refresh]
+
+ # POST /api/v3/storefront/auth/login
+ def create
+ user = Spree.user_class.find_by(email: params[:email])
+
+ if user&.valid_password?(params[:password])
+ token = generate_jwt(user)
+ render json: {
+ token: token,
+ user: user_serializer.new(user, serializer_context).as_json
+ }
+ else
+ render json: { error: 'Invalid email or password' }, status: :unauthorized
+ end
+ end
+
+ # POST /api/v3/storefront/auth/register
+ def register
+ user = Spree.user_class.new(registration_params)
+
+ if user.save
+ token = generate_jwt(user)
+ render json: {
+ token: token,
+ user: user_serializer.new(user, serializer_context).as_json
+ }, status: :created
+ else
+ render_errors(user.errors)
+ end
+ end
+
+ # POST /api/v3/storefront/auth/refresh
+ def refresh
+ token = generate_jwt(current_user)
+ render json: {
+ token: token,
+ user: user_serializer.new(current_user, serializer_context).as_json
+ }
+ end
+
+ protected
+
+ def serializer_context
+ {
+ store: current_store,
+ locale: current_locale
+ }
+ end
+
+ private
+
+ def registration_params
+ params.require(:user).permit(:email, :password, :password_confirmation, :first_name, :last_name)
+ end
+
+ def user_serializer
+ Spree::Api::Dependencies.v3_storefront_user_serializer.constantize
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/base_controller.rb b/api/app/controllers/spree/api/v3/storefront/base_controller.rb
new file mode 100644
index 0000000000..928989a785
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/base_controller.rb
@@ -0,0 +1,10 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class BaseController < ::Spree::Api::V3::BaseController
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/countries_controller.rb b/api/app/controllers/spree/api/v3/storefront/countries_controller.rb
new file mode 100644
index 0000000000..e5524ddfaf
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/countries_controller.rb
@@ -0,0 +1,30 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class CountriesController < ResourceController
+ # Public endpoint - no authentication required
+
+ protected
+
+ def scope
+ Spree::Country.accessible_by(current_ability, :show)
+ end
+
+ def model_class
+ Spree::Country
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_country_serializer.constantize
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/coupon_codes_controller.rb b/api/app/controllers/spree/api/v3/storefront/coupon_codes_controller.rb
new file mode 100644
index 0000000000..8ae44f0791
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/coupon_codes_controller.rb
@@ -0,0 +1,56 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class CouponCodesController < BaseController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+
+ # POST /api/v3/storefront/orders/:order_id/coupon_codes
+ def create
+ @order.coupon_code = params[:coupon_code]
+
+ if @order.save
+ render json: serialize_order, status: :created
+ else
+ render_errors(@order.errors)
+ end
+ end
+
+ # DELETE /api/v3/storefront/orders/:order_id/coupon_codes/:id
+ def destroy
+ @order.coupon_code = nil
+
+ if @order.save
+ head :no_content
+ else
+ render_errors(@order.errors)
+ end
+ end
+
+ protected
+
+ def serialize_order
+ serializer_class.new(@order, serializer_context).as_json
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_order_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ currency: current_currency,
+ store: current_store,
+ user: current_user,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/customers_controller.rb b/api/app/controllers/spree/api/v3/storefront/customers_controller.rb
new file mode 100644
index 0000000000..efd4689f46
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/customers_controller.rb
@@ -0,0 +1,47 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class CustomersController < BaseController
+ before_action :require_authentication!
+
+ # GET /api/v3/storefront/customers/me
+ def show
+ render json: serialize_resource(current_user)
+ end
+
+ # PATCH /api/v3/storefront/customers/me
+ def update
+ if current_user.update(customer_params)
+ render json: serialize_resource(current_user)
+ else
+ render_errors(current_user.errors)
+ end
+ end
+
+ protected
+
+ def serialize_resource(resource)
+ serializer_class.new(resource, serializer_context).as_json
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_user_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ store: current_store,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+
+ def customer_params
+ params.require(:customer).permit(Spree::PermittedAttributes.user_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/digitals_controller.rb b/api/app/controllers/spree/api/v3/storefront/digitals_controller.rb
new file mode 100644
index 0000000000..8a83e8ccc3
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/digitals_controller.rb
@@ -0,0 +1,26 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class DigitalsController < BaseController
+ # Public endpoint - access via token
+
+ # GET /api/v3/storefront/digitals/:token
+ def download
+ digital_link = Spree::DigitalLink.find_by!(token: params[:token])
+
+ if digital_link.authorize!
+ send_file digital_link.digital.attachment.path,
+ filename: digital_link.digital.attachment.filename.to_s,
+ type: digital_link.digital.attachment.content_type
+ else
+ render json: { error: 'Download link expired or invalid' }, status: :forbidden
+ end
+ rescue ActiveRecord::RecordNotFound
+ render json: { error: 'Digital download not found' }, status: :not_found
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/line_items_controller.rb b/api/app/controllers/spree/api/v3/storefront/line_items_controller.rb
new file mode 100644
index 0000000000..83553865bf
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/line_items_controller.rb
@@ -0,0 +1,112 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class LineItemsController < ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+ skip_before_action :set_resource
+
+ # GET /api/v3/storefront/orders/:order_id/line_items
+ def index
+ render json: {
+ data: serialize_collection(@order.line_items)
+ }
+ end
+
+ # POST /api/v3/storefront/orders/:order_id/line_items
+ def create
+ result = add_item_service.call(
+ order: @order,
+ variant: variant,
+ quantity: line_item_params[:quantity] || 1,
+ options: line_item_params[:options] || {}
+ )
+
+ if result.success?
+ @line_item = result.value
+ render json: serialize_resource(@line_item), status: :created
+ else
+ render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+ end
+ end
+
+ # GET /api/v3/storefront/orders/:order_id/line_items/:id
+ def show
+ @line_item = @order.line_items.find(params[:id])
+ render json: serialize_resource(@line_item)
+ end
+
+ # PATCH /api/v3/storefront/orders/:order_id/line_items/:id
+ def update
+ @line_item = @order.line_items.find(params[:id])
+
+ if line_item_params[:quantity].present?
+ result = set_item_quantity_service.call(
+ order: @order,
+ line_item: @line_item,
+ quantity: line_item_params[:quantity]
+ )
+
+ if result.success?
+ render json: serialize_resource(@line_item)
+ else
+ render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+ end
+ else
+ render json: serialize_resource(@line_item)
+ end
+ end
+
+ # DELETE /api/v3/storefront/orders/:order_id/line_items/:id
+ def destroy
+ @line_item = @order.line_items.find(params[:id])
+
+ remove_line_item_service.call(
+ order: @order,
+ line_item: @line_item
+ )
+
+ head :no_content
+ end
+
+ protected
+
+ def variant
+ Spree::Variant.find(line_item_params[:variant_id])
+ end
+
+ def model_class
+ Spree::LineItem
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_line_item_serializer.constantize
+ end
+
+ def permitted_params
+ line_item_params
+ end
+
+ def line_item_params
+ params.require(:line_item).permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
+ end
+
+ def add_item_service
+ Spree::Api::Dependencies.storefront_cart_add_item_service.constantize
+ end
+
+ def set_item_quantity_service
+ Spree::Api::Dependencies.storefront_cart_set_item_quantity_service.constantize
+ end
+
+ def remove_line_item_service
+ Spree::Api::Dependencies.storefront_cart_remove_line_item_service.constantize
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/order_addresses_controller.rb b/api/app/controllers/spree/api/v3/storefront/order_addresses_controller.rb
new file mode 100644
index 0000000000..0d246a5f00
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/order_addresses_controller.rb
@@ -0,0 +1,76 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class OrderAddressesController < BaseController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+
+ # GET /api/v3/storefront/orders/:order_id/billing_address
+ # GET /api/v3/storefront/orders/:order_id/shipping_address
+ def show
+ address = address_type == 'billing' ? @order.bill_address : @order.ship_address
+
+ if address
+ render json: serialize_address(address)
+ else
+ render json: { error: 'Address not found' }, status: :not_found
+ end
+ end
+
+ # PATCH /api/v3/storefront/orders/:order_id/billing_address
+ # PATCH /api/v3/storefront/orders/:order_id/shipping_address
+ def update
+ address = address_type == 'billing' ? @order.bill_address : @order.ship_address
+
+ if address.nil?
+ # Create new address
+ address = Spree::Address.new(address_params)
+ if address_type == 'billing'
+ @order.bill_address = address
+ else
+ @order.ship_address = address
+ end
+ else
+ # Update existing address
+ address.assign_attributes(address_params)
+ end
+
+ if @order.save
+ render json: serialize_address(address)
+ else
+ render_errors(address.errors.any? ? address.errors : @order.errors)
+ end
+ end
+
+ protected
+
+ def address_type
+ params[:address_type]
+ end
+
+ def serialize_address(address)
+ serializer_class.new(address, serializer_context).as_json
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_address_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ store: current_store,
+ locale: current_locale
+ }
+ end
+
+ def address_params
+ params.require(:address).permit(Spree::PermittedAttributes.address_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/orders_controller.rb b/api/app/controllers/spree/api/v3/storefront/orders_controller.rb
new file mode 100644
index 0000000000..1cc116647a
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/orders_controller.rb
@@ -0,0 +1,135 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class OrdersController < ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ # Override authorization for orders
+ skip_before_action :set_resource, only: [:index, :create]
+ before_action :require_authentication!, only: [:index]
+ before_action :set_order, only: [:show, :update, :destroy, :next, :advance, :complete, :cancel]
+ before_action :authorize_order_access!, only: [:show, :update, :destroy, :next, :advance, :complete, :cancel]
+
+ # POST /api/v3/storefront/orders (public - guest checkout)
+ def create
+ @resource = Spree::Order.create!(
+ store: current_store,
+ currency: current_currency,
+ user: current_user # nil for guests
+ )
+
+ render json: serialize_resource(@resource).merge(
+ order_token: @resource.token # Return token for guest access
+ ), status: :created
+ end
+
+ # GET /api/v3/storefront/orders/:id
+ def show
+ render json: serialize_resource(@order)
+ end
+
+ # PATCH /api/v3/storefront/orders/:id
+ def update
+ result = update_service.call(
+ order: @order,
+ params: params,
+ permitted_attributes: permitted_params,
+ request_env: request.headers.env
+ )
+
+ if result.success?
+ render json: serialize_resource(@order)
+ else
+ render_service_error(result.error)
+ end
+ end
+
+ # PATCH /api/v3/storefront/orders/:id/next
+ def next
+ result = next_service.call(order: @order)
+
+ if result.success?
+ render json: serialize_resource(@order)
+ else
+ render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
+ end
+ end
+
+ # PATCH /api/v3/storefront/orders/:id/advance
+ def advance
+ result = advance_service.call(order: @order)
+
+ if result.success?
+ render json: serialize_resource(@order)
+ else
+ render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
+ end
+ end
+
+ # PATCH /api/v3/storefront/orders/:id/complete
+ def complete
+ result = complete_service.call(order: @order)
+
+ if result.success?
+ render json: serialize_resource(@order)
+ else
+ render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
+ end
+ end
+
+ # PATCH /api/v3/storefront/orders/:id/cancel
+ def cancel
+ @order.cancel!
+ render json: serialize_resource(@order)
+ end
+
+ protected
+
+ def load_order
+ # for show action we need to find any order by id, not only incomplete orders
+ if action_name == 'show'
+ @order = current_store.orders.friendly.find(params[:id])
+ else
+ super
+ end
+ end
+
+ def scope
+ return Spree::Order.none unless current_user
+
+ current_user.orders.for_store(current_store)
+ end
+
+ def model_class
+ Spree::Order
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_order_serializer.constantize
+ end
+
+ def permitted_params
+ params.require(:order).permit(Spree::PermittedAttributes.checkout_attributes)
+ end
+
+ def update_service
+ Spree::Api::Dependencies.storefront_checkout_update_service.constantize
+ end
+
+ def next_service
+ Spree::Api::Dependencies.storefront_checkout_next_service.constantize
+ end
+
+ def advance_service
+ Spree::Api::Dependencies.storefront_checkout_advance_service.constantize
+ end
+
+ def complete_service
+ Spree::Api::Dependencies.storefront_checkout_complete_service.constantize
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/pages_controller.rb b/api/app/controllers/spree/api/v3/storefront/pages_controller.rb
new file mode 100644
index 0000000000..cba651d178
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/pages_controller.rb
@@ -0,0 +1,30 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PagesController < ResourceController
+ # Public endpoint - no authentication required
+
+ protected
+
+ def scope
+ super.without_previews.where(pageable: current_store)
+ end
+
+ def model_class
+ Spree::Page
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_page_serializer.constantize
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/payment_methods_controller.rb b/api/app/controllers/spree/api/v3/storefront/payment_methods_controller.rb
new file mode 100644
index 0000000000..e8564925fd
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/payment_methods_controller.rb
@@ -0,0 +1,46 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PaymentMethodsController < BaseController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+
+ # GET /api/v3/storefront/orders/:order_id/payment_methods
+ def index
+ @payment_methods = available_payment_methods
+
+ render json: {
+ data: serialize_collection(@payment_methods)
+ }
+ end
+
+ protected
+
+ def available_payment_methods
+ @order.available_payment_methods
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_payment_method_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ currency: current_currency,
+ store: current_store,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/payment_sources_controller.rb b/api/app/controllers/spree/api/v3/storefront/payment_sources_controller.rb
new file mode 100644
index 0000000000..ca8cd1f4ab
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/payment_sources_controller.rb
@@ -0,0 +1,75 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PaymentSourcesController < BaseController
+ before_action :require_authentication!
+ before_action :set_payment_source, only: [:show, :destroy]
+
+ # GET /api/v3/storefront/customers/me/payment_sources
+ def index
+ @payment_sources = current_user.credit_cards
+
+ render json: {
+ data: serialize_collection(@payment_sources)
+ }
+ end
+
+ # GET /api/v3/storefront/customers/me/payment_sources/:id
+ def show
+ render json: serialize_resource(@payment_source)
+ end
+
+ # DELETE /api/v3/storefront/customers/me/payment_sources/:id
+ def destroy
+ @payment_source.destroy
+ head :no_content
+ end
+
+ protected
+
+ def set_payment_source
+ @payment_source = current_user.credit_cards.find(params[:id])
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+
+ def serialize_resource(resource)
+ serializer_class.new(resource, serializer_context).as_json
+ end
+
+ def serializer_class
+ # Using a simple inline serializer for credit cards to avoid exposing sensitive data
+ Class.new do
+ attr_reader :resource
+
+ def initialize(resource, context = {})
+ @resource = resource
+ end
+
+ def as_json
+ {
+ id: resource.id,
+ cc_type: resource.cc_type,
+ last_digits: resource.last_digits,
+ month: resource.month,
+ year: resource.year,
+ name: resource.name
+ }
+ end
+ end
+ end
+
+ def serializer_context
+ {
+ store: current_store,
+ locale: current_locale
+ }
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/payments_controller.rb b/api/app/controllers/spree/api/v3/storefront/payments_controller.rb
new file mode 100644
index 0000000000..0f678d20c9
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/payments_controller.rb
@@ -0,0 +1,57 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PaymentsController < ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+ before_action :set_payment, only: [:show]
+
+ # GET /api/v3/storefront/orders/:order_id/payments
+ def index
+ render json: {
+ data: serialize_collection(@order.payments.valid)
+ }
+ end
+
+ # GET /api/v3/storefront/orders/:order_id/payments/:id
+ def show
+ render json: serialize_resource(@payment)
+ end
+
+ # POST /api/v3/storefront/orders/:order_id/payments
+ def create
+ @payment = @order.payments.build(payment_params)
+ authorize_resource!(@payment, :create)
+
+ if @payment.save
+ render json: serialize_resource(@payment), status: :created
+ else
+ render_errors(@payment.errors)
+ end
+ end
+
+ protected
+
+ def set_payment
+ @payment = @order.payments.valid.find(params[:id])
+ end
+
+ def model_class
+ Spree::Payment
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_payment_serializer.constantize
+ end
+
+ def permitted_params
+ params.require(:payment).permit(Spree::PermittedAttributes.payment_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/policies_controller.rb b/api/app/controllers/spree/api/v3/storefront/policies_controller.rb
new file mode 100644
index 0000000000..1ad851f76f
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/policies_controller.rb
@@ -0,0 +1,48 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PoliciesController < ResourceController
+ # Public endpoint - no authentication required
+
+ protected
+
+ def scope
+ Spree::Policy.active.for_store(current_store).accessible_by(current_ability, :show)
+ end
+
+ def model_class
+ Spree::Policy
+ end
+
+ def serializer_class
+ # Simple inline serializer for policies
+ Class.new do
+ attr_reader :resource
+
+ def initialize(resource, context = {})
+ @resource = resource
+ end
+
+ def as_json
+ {
+ id: resource.id,
+ title: resource.title,
+ slug: resource.slug,
+ content: resource.content,
+ created_at: resource.created_at,
+ updated_at: resource.updated_at
+ }
+ end
+ end
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/posts_controller.rb b/api/app/controllers/spree/api/v3/storefront/posts_controller.rb
new file mode 100644
index 0000000000..c0328c532a
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/posts_controller.rb
@@ -0,0 +1,49 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class PostsController < ResourceController
+ # Public endpoint - no authentication required
+
+ protected
+
+ def scope
+ Spree::Post.published.for_store(current_store).accessible_by(current_ability, :show)
+ end
+
+ def model_class
+ Spree::Post
+ end
+
+ def serializer_class
+ # Simple inline serializer for posts
+ Class.new do
+ attr_reader :resource
+
+ def initialize(resource, context = {})
+ @resource = resource
+ end
+
+ def as_json
+ {
+ id: resource.id,
+ title: resource.title,
+ slug: resource.slug,
+ content: resource.content,
+ published_at: resource.published_at,
+ created_at: resource.created_at,
+ updated_at: resource.updated_at
+ }
+ end
+ end
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/products_controller.rb b/api/app/controllers/spree/api/v3/storefront/products_controller.rb
new file mode 100644
index 0000000000..08a19816c9
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/products_controller.rb
@@ -0,0 +1,47 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class ProductsController < ResourceController
+ include Spree::Api::V2::ProductListIncludes
+
+ protected
+
+ def model_class
+ Spree::Product
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_product_serializer.constantize
+ end
+
+ def scope
+ super.available
+ end
+
+ def scope_includes
+ [
+ :prices_including_master,
+ :variant_images,
+ :option_types,
+ :option_values,
+ :taxons,
+ { taggings: [:tag] },
+ { master: [:images, :prices, :stock_items, :stock_locations, { stock_items: :stock_location }],
+ variants: [
+ :images, :prices, :option_values, :stock_items, :stock_locations,
+ { option_values: :option_type, stock_items: :stock_location }
+ ],
+ }
+ ]
+ end
+
+ # Not needed for index/show, but required by ResourceController
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/sections_controller.rb b/api/app/controllers/spree/api/v3/storefront/sections_controller.rb
new file mode 100644
index 0000000000..45b3a5205f
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/sections_controller.rb
@@ -0,0 +1,52 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class SectionsController < BaseController
+ before_action :set_page
+
+ # GET /api/v3/storefront/pages/:page_id/sections
+ def index
+ @sections = @page.sections.ordered
+
+ render json: {
+ data: serialize_collection(@sections)
+ }
+ end
+
+ # GET /api/v3/storefront/pages/:page_id/sections/:id
+ def show
+ @section = @page.sections.find(params[:id])
+ render json: serialize_resource(@section)
+ end
+
+ protected
+
+ def set_page
+ @page = Spree::Page.visible.for_store(current_store).find(params[:page_id])
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+
+ def serialize_resource(resource)
+ serializer_class.new(resource, serializer_context).as_json
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_section_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ store: current_store,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/shipments_controller.rb b/api/app/controllers/spree/api/v3/storefront/shipments_controller.rb
new file mode 100644
index 0000000000..698e68f7bd
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/shipments_controller.rb
@@ -0,0 +1,55 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class ShipmentsController < ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+ before_action :set_shipment, only: [:show, :update]
+
+ # GET /api/v3/storefront/orders/:order_id/shipments
+ def index
+ render json: {
+ data: serialize_collection(@order.shipments)
+ }
+ end
+
+ # GET /api/v3/storefront/orders/:order_id/shipments/:id
+ def show
+ render json: serialize_resource(@shipment)
+ end
+
+ # PATCH /api/v3/storefront/orders/:order_id/shipments/:id
+ def update
+ if permitted_params[:selected_shipping_rate_id].present?
+ @shipment.selected_shipping_rate_id = permitted_params[:selected_shipping_rate_id]
+ @shipment.save
+ end
+
+ render json: serialize_resource(@shipment)
+ end
+
+ protected
+
+ def set_shipment
+ @shipment = @order.shipments.find(params[:id])
+ end
+
+ def model_class
+ Spree::Shipment
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_shipment_serializer.constantize
+ end
+
+ def permitted_params
+ params.require(:shipment).permit(Spree::PermittedAttributes.shipment_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/shipping_methods_controller.rb b/api/app/controllers/spree/api/v3/storefront/shipping_methods_controller.rb
new file mode 100644
index 0000000000..4037fbc2f1
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/shipping_methods_controller.rb
@@ -0,0 +1,46 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class ShippingMethodsController < BaseController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order
+ before_action :authorize_order_access!
+
+ # GET /api/v3/storefront/orders/:order_id/shipping_methods
+ def index
+ @shipping_methods = available_shipping_methods
+
+ render json: {
+ data: serialize_collection(@shipping_methods)
+ }
+ end
+
+ protected
+
+ def available_shipping_methods
+ @order.available_shipping_methods
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_shipping_method_serializer.constantize
+ end
+
+ def serializer_context
+ {
+ currency: current_currency,
+ store: current_store,
+ locale: current_locale,
+ includes: requested_includes
+ }
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/states_controller.rb b/api/app/controllers/spree/api/v3/storefront/states_controller.rb
new file mode 100644
index 0000000000..043aaa87c8
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/states_controller.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class StatesController < ResourceController
+ # Public endpoint - no authentication required
+
+ before_action :set_country, if: -> { params[:country_id].present? }
+
+ protected
+
+ def set_country
+ @country = Spree::Country.find(params[:country_id])
+ end
+
+ def scope
+ base_scope = @country ? @country.states : Spree::State
+ base_scope.accessible_by(current_ability, :show)
+ end
+
+ def model_class
+ Spree::State
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_state_serializer.constantize
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/stores_controller.rb b/api/app/controllers/spree/api/v3/storefront/stores_controller.rb
new file mode 100644
index 0000000000..da99bae4ee
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/stores_controller.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class StoresController < ResourceController
+ # Public endpoint - no authentication required
+
+ # GET /api/v3/storefront/store
+ def current
+ @store = current_store
+ render json: serialize_resource(@store)
+ end
+
+ # GET /api/v3/storefront/stores/:code
+ def show
+ @resource = Spree::Store.find_by!(code: params[:id])
+ render json: serialize_resource(@resource)
+ end
+
+ protected
+
+ def model_class
+ Spree::Store
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_store_serializer.constantize
+ end
+
+ # Not needed for show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/taxons_controller.rb b/api/app/controllers/spree/api/v3/storefront/taxons_controller.rb
new file mode 100644
index 0000000000..4605d9ca0b
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/taxons_controller.rb
@@ -0,0 +1,36 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class TaxonsController < ResourceController
+ # Public endpoint - no authentication required
+
+ protected
+
+ def model_class
+ Spree::Taxon
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_taxon_serializer.constantize
+ end
+
+ def scope
+ Spree::Taxon
+ .for_store(current_store)
+ .includes(scope_includes)
+ end
+
+ def scope_includes
+ [:taxonomy, :parent, :children]
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/variants_controller.rb b/api/app/controllers/spree/api/v3/storefront/variants_controller.rb
new file mode 100644
index 0000000000..b3ded9d9ee
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/variants_controller.rb
@@ -0,0 +1,49 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class VariantsController < ResourceController
+ before_action :set_product
+
+ # GET /api/v3/storefront/products/:product_id/variants/:id
+ def show
+ @resource = @product.variants.find(params[:id])
+ render json: serialize_resource(@resource)
+ end
+
+ protected
+
+ def set_product
+ @product = Spree::Product.available.for_store(current_store).find(params[:product_id])
+ end
+
+ def scope
+ @product.variants
+ .accessible_by(current_ability, :show)
+ .includes(scope_includes)
+ end
+
+ def scope_includes
+ [
+ :images, :prices, :option_values, :stock_items, :stock_locations,
+ { option_values: :option_type, stock_items: :stock_location }
+ ]
+ end
+
+ def model_class
+ Spree::Variant
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_variant_serializer.constantize
+ end
+
+ # Not needed for index/show
+ def permitted_params
+ {}
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/wishlist_items_controller.rb b/api/app/controllers/spree/api/v3/storefront/wishlist_items_controller.rb
new file mode 100644
index 0000000000..9b9519283d
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/wishlist_items_controller.rb
@@ -0,0 +1,84 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class WishlistItemsController < ResourceController
+ before_action :require_authentication!
+ before_action :set_wishlist
+
+ # GET /api/v3/storefront/wishlists/:wishlist_id/items
+ def index
+ render json: {
+ data: serialize_collection(@wishlist.wished_items)
+ }
+ end
+
+ # POST /api/v3/storefront/wishlists/:wishlist_id/items
+ def create
+ @item = @wishlist.wished_items.build(item_params)
+
+ if @item.save
+ render json: serialize_resource(@item), status: :created
+ else
+ render_errors(@item.errors)
+ end
+ end
+
+ # GET /api/v3/storefront/wishlists/:wishlist_id/items/:id
+ def show
+ @item = @wishlist.wished_items.find(params[:id])
+ render json: serialize_resource(@item)
+ end
+
+ # PATCH /api/v3/storefront/wishlists/:wishlist_id/items/:id
+ def update
+ @item = @wishlist.wished_items.find(params[:id])
+
+ if @item.update(item_params)
+ render json: serialize_resource(@item)
+ else
+ render_errors(@item.errors)
+ end
+ end
+
+ # DELETE /api/v3/storefront/wishlists/:wishlist_id/items/:id
+ def destroy
+ @item = @wishlist.wished_items.find(params[:id])
+ @item.destroy
+ head :no_content
+ end
+
+ protected
+
+ def set_wishlist
+ @wishlist = current_user.wishlists.find(params[:wishlist_id])
+ end
+
+ def model_class
+ Spree::WishedItem
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_wished_item_serializer.constantize
+ end
+
+ def permitted_params
+ item_params
+ end
+
+ def item_params
+ params.require(:item).permit(Spree::PermittedAttributes.wished_item_attributes)
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, serializer_context).as_json }
+ end
+
+ def serialize_resource(resource)
+ serializer_class.new(resource, serializer_context).as_json
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/storefront/wishlists_controller.rb b/api/app/controllers/spree/api/v3/storefront/wishlists_controller.rb
new file mode 100644
index 0000000000..47d780a782
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/storefront/wishlists_controller.rb
@@ -0,0 +1,40 @@
+module Spree
+ module Api
+ module V3
+ module Storefront
+ class WishlistsController < ResourceController
+ before_action :require_authentication!
+
+ # GET /api/v3/storefront/wishlists/default
+ def default
+ @wishlist = current_user.wishlists.default.first_or_create!(
+ name: 'Default',
+ is_default: true,
+ store: current_store
+ )
+
+ render json: serialize_resource(@wishlist)
+ end
+
+ protected
+
+ def scope
+ current_user.wishlists.for_store(current_store)
+ end
+
+ def model_class
+ Spree::Wishlist
+ end
+
+ def serializer_class
+ Spree::Api::Dependencies.v3_storefront_wishlist_serializer.constantize
+ end
+
+ def permitted_params
+ params.require(:wishlist).permit(Spree::PermittedAttributes.wishlist_attributes)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/address_serializer.rb b/api/app/serializers/spree/api/v3/address_serializer.rb
new file mode 100644
index 0000000000..f93c67cce3
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/address_serializer.rb
@@ -0,0 +1,30 @@
+module Spree
+ module Api
+ module V3
+ class AddressSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ firstname: resource.firstname,
+ lastname: resource.lastname,
+ full_name: resource.full_name,
+ address1: resource.address1,
+ address2: resource.address2,
+ city: resource.city,
+ zipcode: resource.zipcode,
+ phone: resource.phone,
+ company: resource.company,
+ state_id: resource.state_id,
+ state_name: resource.state_name,
+ state_text: resource.state_text,
+ country_id: resource.country_id,
+ country_name: resource.country&.name,
+ country_iso: resource.country&.iso,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/base_serializer.rb b/api/app/serializers/spree/api/v3/base_serializer.rb
new file mode 100644
index 0000000000..211ba8f835
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/base_serializer.rb
@@ -0,0 +1,105 @@
+module Spree
+ module Api
+ module V3
+ class BaseSerializer
+ attr_reader :resource, :context, :includes
+
+ def initialize(resource, context = {})
+ @resource = resource
+ @context = context
+ @includes = Array(context[:includes] || [])
+ end
+
+ # Main serialization method
+ def as_json
+ attributes
+ end
+
+ protected
+
+ # Override in subclasses to define attributes
+ def attributes
+ {
+ id: resource.id
+ }
+ end
+
+ # Check if an association should be included
+ # @param association [String, Symbol] The association name
+ # @return [Boolean]
+ def include?(association)
+ includes.include?(association.to_s)
+ end
+
+ # Get nested includes for a parent association
+ # @param parent [String, Symbol] The parent association
+ # @return [Array<String>]
+ def nested_includes_for(parent)
+ prefix = "#{parent}."
+ includes
+ .select { |inc| inc.start_with?(prefix) }
+ .map { |inc| inc.sub(prefix, '') }
+ end
+
+ # Context for nested serializers
+ # @param parent [String, Symbol] The parent association name
+ # @return [Hash]
+ def nested_context(parent = nil)
+ ctx = context.dup
+ ctx[:includes] = parent ? nested_includes_for(parent) : []
+ ctx
+ end
+
+ # Context helpers
+ def currency
+ context[:currency]
+ end
+
+ def store
+ context[:store]
+ end
+
+ def user
+ context[:user]
+ end
+
+ def locale
+ context[:locale]
+ end
+
+ # Price helpers
+ def money_to_hash(money)
+ return nil unless money
+
+ {
+ amount: money.to_f,
+ currency: money.currency.iso_code,
+ formatted: money.to_s
+ }
+ end
+
+ def price_in_currency(priceable)
+ return nil unless priceable.respond_to?(:price_in)
+
+ priceable.price_in(currency)
+ end
+
+ # Image URL helper
+ def image_url(image, size: nil)
+ return nil unless image&.attached?
+
+ url_helpers.cdn_image_url(image.attachment)
+ end
+
+ def url_helpers
+ Rails.application.routes.url_helpers
+ end
+
+ # Timestamp helper
+ def timestamp(time)
+ time&.iso8601
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/country_serializer.rb b/api/app/serializers/spree/api/v3/country_serializer.rb
new file mode 100644
index 0000000000..f936d9a9d1
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/country_serializer.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ class CountrySerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ iso: resource.iso,
+ iso3: resource.iso3,
+ iso_name: resource.iso_name,
+ name: resource.name,
+ states_required: resource.states_required,
+ zipcode_required: resource.zipcode_required
+ }
+
+ # Conditionally include states
+ base_attrs[:states] = serialize_states if include?('states')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_states
+ resource.states.map do |state|
+ state_serializer.new(state, nested_context('states')).as_json
+ end
+ end
+
+ # Serializer dependencies
+ def state_serializer
+ Spree::Api::Dependencies.v3_storefront_state_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/image_serializer.rb b/api/app/serializers/spree/api/v3/image_serializer.rb
new file mode 100644
index 0000000000..09eac27151
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/image_serializer.rb
@@ -0,0 +1,20 @@
+module Spree
+ module Api
+ module V3
+ class ImageSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ position: resource.position,
+ alt: resource.alt,
+ original_url: image_url(resource),
+ large_url: image_url(resource, size: [1200, 1200]),
+ medium_url: image_url(resource, size: [600, 600]),
+ small_url: image_url(resource, size: [300, 300]),
+ thumbnail_url: image_url(resource, size: [150, 150])
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/line_item_serializer.rb b/api/app/serializers/spree/api/v3/line_item_serializer.rb
new file mode 100644
index 0000000000..0436b38fad
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/line_item_serializer.rb
@@ -0,0 +1,61 @@
+module Spree
+ module Api
+ module V3
+ class LineItemSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ quantity: resource.quantity,
+ price: resource.price.to_f,
+ display_price: resource.display_price.to_s,
+
+ total: resource.total.to_f,
+ display_total: resource.display_total.to_s,
+
+ adjustment_total: resource.adjustment_total.to_f,
+ display_adjustment_total: resource.display_adjustment_total.to_s,
+
+ promo_total: resource.promo_total.to_f,
+ display_promo_total: resource.display_promo_total.to_s,
+
+ included_tax_total: resource.included_tax_total.to_f,
+ display_included_tax_total: resource.display_included_tax_total.to_s,
+
+ additional_tax_total: resource.additional_tax_total.to_f,
+ display_additional_tax_total: resource.display_additional_tax_total.to_s,
+
+ pre_tax_amount: resource.pre_tax_amount.to_f,
+ display_pre_tax_amount: resource.display_pre_tax_amount.to_s,
+
+ compare_at_amount: resource.compare_at_amount.to_f,
+ display_compare_at_amount: resource.display_compare_at_amount.to_s,
+
+ discounted_amount: resource.discounted_amount.to_f,
+ display_discounted_amount: resource.display_discounted_amount.to_s,
+
+ name: resource.name,
+ slug: resource.slug,
+ options_text: resource.options_text,
+ currency: resource.currency
+ }
+
+ # Conditionally include variant
+ base_attrs[:variant] = serialize_variant if include?('variant')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_variant
+ variant_serializer.new(resource.variant, nested_context('variant')).as_json if resource.variant
+ end
+
+ # Serializer dependencies
+ def variant_serializer
+ Spree::Api::Dependencies.v3_storefront_variant_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/option_type_serializer.rb b/api/app/serializers/spree/api/v3/option_type_serializer.rb
new file mode 100644
index 0000000000..4323e649e8
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/option_type_serializer.rb
@@ -0,0 +1,34 @@
+module Spree
+ module Api
+ module V3
+ class OptionTypeSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ name: resource.name,
+ presentation: resource.presentation,
+ position: resource.position
+ }
+
+ # Conditionally include option_values
+ base_attrs[:option_values] = serialize_option_values if include?('option_values')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_option_values
+ resource.option_values.map do |option_value|
+ option_value_serializer.new(option_value, nested_context('option_values')).as_json
+ end
+ end
+
+ # Serializer dependencies
+ def option_value_serializer
+ Spree::Api::Dependencies.v3_storefront_option_value_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/option_value_serializer.rb b/api/app/serializers/spree/api/v3/option_value_serializer.rb
new file mode 100644
index 0000000000..5c375f0355
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/option_value_serializer.rb
@@ -0,0 +1,18 @@
+module Spree
+ module Api
+ module V3
+ class OptionValueSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ presentation: resource.presentation,
+ position: resource.position,
+ option_type_id: resource.option_type_id,
+ option_type_name: resource.option_type.name
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/order_serializer.rb b/api/app/serializers/spree/api/v3/order_serializer.rb
new file mode 100644
index 0000000000..0f1c2d32c2
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -0,0 +1,108 @@
+module Spree
+ module Api
+ module V3
+ class OrderSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ number: resource.number,
+ state: resource.state,
+ token: resource.token,
+ email: resource.email,
+ special_instructions: resource.special_instructions,
+ currency: resource.currency,
+ item_count: resource.item_count,
+
+ # Totals
+ item_total: resource.item_total.to_f,
+ display_item_total: resource.display_item_total.to_s,
+
+ ship_total: resource.ship_total.to_f,
+ display_ship_total: resource.display_ship_total.to_s,
+
+ adjustment_total: resource.adjustment_total.to_f,
+ display_adjustment_total: resource.display_adjustment_total.to_s,
+
+ promo_total: resource.promo_total.to_f,
+ display_promo_total: resource.display_promo_total.to_s,
+
+ tax_total: resource.tax_total.to_f,
+ display_tax_total: resource.display_tax_total.to_s,
+
+ included_tax_total: resource.included_tax_total.to_f,
+ display_included_tax_total: resource.display_included_tax_total.to_s,
+
+ additional_tax_total: resource.additional_tax_total.to_f,
+ display_additional_tax_total: resource.display_additional_tax_total.to_s,
+
+ total: resource.total.to_f,
+ display_total: resource.display_total.to_s,
+
+ # States
+ shipment_state: resource.shipment_state,
+ payment_state: resource.payment_state,
+
+ # Timestamps
+ completed_at: timestamp(resource.completed_at),
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+
+ # Conditionally include associations
+ base_attrs[:line_items] = serialize_line_items if include?('line_items')
+ base_attrs[:payments] = serialize_payments if include?('payments')
+ base_attrs[:shipments] = serialize_shipments if include?('shipments')
+ base_attrs[:billing_address] = serialize_billing_address if include?('billing_address')
+ base_attrs[:shipping_address] = serialize_shipping_address if include?('shipping_address')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_line_items
+ resource.line_items.map do |line_item|
+ line_item_serializer.new(line_item, nested_context('line_items')).as_json
+ end
+ end
+
+ def serialize_payments
+ resource.payments.valid.map do |payment|
+ payment_serializer.new(payment, nested_context('payments')).as_json
+ end
+ end
+
+ def serialize_shipments
+ resource.shipments.map do |shipment|
+ shipment_serializer.new(shipment, nested_context('shipments')).as_json
+ end
+ end
+
+ def serialize_billing_address
+ address_serializer.new(resource.bill_address, nested_context('billing_address')).as_json if resource.bill_address
+ end
+
+ def serialize_shipping_address
+ address_serializer.new(resource.ship_address, nested_context('shipping_address')).as_json if resource.ship_address
+ end
+
+ # Serializer dependencies
+ def line_item_serializer
+ Spree::Api::Dependencies.v3_storefront_line_item_serializer.constantize
+ end
+
+ def payment_serializer
+ Spree::Api::Dependencies.v3_storefront_payment_serializer.constantize
+ end
+
+ def shipment_serializer
+ Spree::Api::Dependencies.v3_storefront_shipment_serializer.constantize
+ end
+
+ def address_serializer
+ Spree::Api::Dependencies.v3_storefront_address_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/payment_method_serializer.rb b/api/app/serializers/spree/api/v3/payment_method_serializer.rb
new file mode 100644
index 0000000000..38c77b77c9
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/payment_method_serializer.rb
@@ -0,0 +1,19 @@
+module Spree
+ module Api
+ module V3
+ class PaymentMethodSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ description: resource.description,
+ type: resource.type,
+ active: resource.active,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/payment_serializer.rb b/api/app/serializers/spree/api/v3/payment_serializer.rb
new file mode 100644
index 0000000000..7f16e1a284
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/payment_serializer.rb
@@ -0,0 +1,24 @@
+module Spree
+ module Api
+ module V3
+ class PaymentSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ amount: resource.amount.to_f,
+ display_amount: resource.display_amount.to_s,
+ state: resource.state,
+ payment_method_id: resource.payment_method_id,
+ payment_method_name: resource.payment_method&.name,
+ response_code: resource.response_code,
+ number: resource.number,
+ cvv_response_code: resource.cvv_response_code,
+ cvv_response_message: resource.cvv_response_message,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/product_serializer.rb b/api/app/serializers/spree/api/v3/product_serializer.rb
new file mode 100644
index 0000000000..8ef6f4fead
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/product_serializer.rb
@@ -0,0 +1,116 @@
+module Spree
+ module Api
+ module V3
+ class ProductSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ name: resource.name,
+ description: resource.description,
+ slug: resource.slug,
+ sku: resource.sku,
+ barcode: resource.barcode,
+ available_on: timestamp(resource.available_on),
+ meta_description: resource.meta_description,
+ meta_keywords: resource.meta_keywords,
+ purchasable: resource.purchasable?,
+ in_stock: resource.in_stock?,
+ backorderable: resource.backorderable?,
+ available: resource.available?,
+ currency: currency,
+ price: price_value,
+ display_price: display_price_value,
+ compare_at_price: compare_at_price_value,
+ display_compare_at_price: display_compare_at_price_value,
+ tags: resource.taggings.map(&:tag),
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+
+ # Conditionally include associations based on include parameter
+ base_attrs[:images] = serialize_images if include?('images')
+ base_attrs[:variants] = serialize_variants if include?('variants')
+ base_attrs[:default_variant] = serialize_default_variant if include?('default_variant')
+ base_attrs[:master_variant] = serialize_master_variant if include?('master_variant')
+ base_attrs[:option_types] = serialize_option_types if include?('option_types')
+ base_attrs[:taxons] = serialize_taxons if include?('taxons')
+
+ base_attrs
+ end
+
+ private
+
+ def price_value
+ price = price_in_currency(resource)
+ price&.amount&.to_f
+ end
+
+ def display_price_value
+ price = price_in_currency(resource)
+ price&.display_price&.to_s
+ end
+
+ def compare_at_price_value
+ price = price_in_currency(resource)
+ price&.compare_at_amount&.to_f
+ end
+
+ def display_compare_at_price_value
+ price = price_in_currency(resource)
+ return nil unless price&.compare_at_amount
+
+ Spree::Money.new(price.compare_at_amount, currency: currency).to_s
+ end
+
+ def serialize_images
+ resource.variant_images.map do |image|
+ image_serializer.new(image, nested_context('images')).as_json
+ end
+ end
+
+ def serialize_variants
+ resource.variants.map do |variant|
+ variant_serializer.new(variant, nested_context('variants')).as_json
+ end
+ end
+
+ def serialize_default_variant
+ variant_serializer.new(resource.default_variant, nested_context('default_variant')).as_json if resource.default_variant
+ end
+
+ def serialize_master_variant
+ variant_serializer.new(resource.master, nested_context('master_variant')).as_json if resource.master
+ end
+
+ def serialize_option_types
+ resource.option_types.map do |option_type|
+ option_type_serializer.new(option_type, nested_context('option_types')).as_json
+ end
+ end
+
+ def serialize_taxons
+ resource.taxons_for_store(store).map do |taxon|
+ taxon_serializer.new(taxon, nested_context('taxons')).as_json
+ end
+ end
+
+ # Serializer dependencies
+ def image_serializer
+ Spree::Api::Dependencies.v3_storefront_image_serializer.constantize
+ end
+
+ def variant_serializer
+ Spree::Api::Dependencies.v3_storefront_variant_serializer.constantize
+ end
+
+ def option_type_serializer
+ Spree::Api::Dependencies.v3_storefront_option_type_serializer.constantize
+ end
+
+ def taxon_serializer
+ Spree::Api::Dependencies.v3_storefront_taxon_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/shipment_serializer.rb b/api/app/serializers/spree/api/v3/shipment_serializer.rb
new file mode 100644
index 0000000000..aeb954da7e
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/shipment_serializer.rb
@@ -0,0 +1,60 @@
+module Spree
+ module Api
+ module V3
+ class ShipmentSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ number: resource.number,
+ state: resource.state,
+ tracking: resource.tracking,
+ cost: resource.cost.to_f,
+ display_cost: resource.display_cost.to_s,
+ shipped_at: timestamp(resource.shipped_at),
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at),
+ shipping_method: serialize_shipping_method,
+ stock_location: serialize_stock_location
+ }
+
+ # Conditionally include associations
+ base_attrs[:shipping_rates] = serialize_shipping_rates if include?('shipping_rates')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_shipping_method
+ return unless resource.shipping_method
+
+ {
+ id: resource.shipping_method.id,
+ name: resource.shipping_method.name,
+ code: resource.shipping_method.code
+ }
+ end
+
+ def serialize_stock_location
+ return unless resource.stock_location
+
+ {
+ id: resource.stock_location.id,
+ name: resource.stock_location.name
+ }
+ end
+
+ def serialize_shipping_rates
+ resource.shipping_rates.map do |shipping_rate|
+ shipping_rate_serializer.new(shipping_rate, nested_context('shipping_rates')).as_json
+ end
+ end
+
+ # Serializer dependencies
+ def shipping_rate_serializer
+ Spree::Api::Dependencies.v3_storefront_shipping_rate_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/shipping_method_serializer.rb b/api/app/serializers/spree/api/v3/shipping_method_serializer.rb
new file mode 100644
index 0000000000..3f05c7bd6a
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/shipping_method_serializer.rb
@@ -0,0 +1,19 @@
+module Spree
+ module Api
+ module V3
+ class ShippingMethodSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ code: resource.code,
+ tracking_url: resource.tracking_url,
+ admin_name: resource.admin_name,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/shipping_rate_serializer.rb b/api/app/serializers/spree/api/v3/shipping_rate_serializer.rb
new file mode 100644
index 0000000000..ba5fd1904d
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/shipping_rate_serializer.rb
@@ -0,0 +1,21 @@
+module Spree
+ module Api
+ module V3
+ class ShippingRateSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ cost: resource.cost.to_f,
+ display_cost: resource.display_cost.to_s,
+ selected: resource.selected,
+ shipping_method_id: resource.shipping_method_id,
+ shipping_method_code: resource.shipping_method&.code,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/state_serializer.rb b/api/app/serializers/spree/api/v3/state_serializer.rb
new file mode 100644
index 0000000000..0f0f6bfc7b
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/state_serializer.rb
@@ -0,0 +1,16 @@
+module Spree
+ module Api
+ module V3
+ class StateSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ abbr: resource.abbr,
+ country_id: resource.country_id
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/store_serializer.rb b/api/app/serializers/spree/api/v3/store_serializer.rb
new file mode 100644
index 0000000000..19b54f8991
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/store_serializer.rb
@@ -0,0 +1,30 @@
+module Spree
+ module Api
+ module V3
+ class StoreSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ url: resource.url,
+ meta_description: resource.meta_description,
+ meta_keywords: resource.meta_keywords,
+ seo_title: resource.seo_title,
+ default_currency: resource.default_currency,
+ code: resource.code,
+ default: resource.default,
+ supported_currencies: resource.supported_currencies_list.map(&:iso_code),
+ facebook: resource.facebook,
+ twitter: resource.twitter,
+ instagram: resource.instagram,
+ customer_support_email: resource.customer_support_email,
+ default_locale: resource.default_locale,
+ supported_locales: resource.supported_locales_list,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/taxon_serializer.rb b/api/app/serializers/spree/api/v3/taxon_serializer.rb
new file mode 100644
index 0000000000..90442613d6
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/taxon_serializer.rb
@@ -0,0 +1,66 @@
+module Spree
+ module Api
+ module V3
+ class TaxonSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ name: resource.name,
+ description: resource.description.to_plain_text,
+ description_html: resource.description.to_s,
+ image_url: image_url(resource.image),
+ square_image_url: image_url(resource.square_image),
+ has_products: resource.active_products_with_descendants.exists?,
+ is_root: resource.root?,
+ is_child: resource.child?,
+ is_leaf: resource.leaf?,
+ permalink: resource.permalink,
+ position: resource.position,
+ lft: resource.lft,
+ rgt: resource.rgt,
+ depth: resource.depth,
+ meta_title: resource.meta_title,
+ meta_description: resource.meta_description,
+ meta_keywords: resource.meta_keywords,
+ parent_id: resource.parent_id,
+ taxonomy_id: resource.taxonomy_id,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+
+ # Conditionally include children
+ base_attrs[:parent] = serialize_parent if include?('parent')
+ base_attrs[:children] = serialize_children if include?('children')
+ base_attrs[:taxonomy] = serialize_taxonomy if include?('taxonomy')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_parent
+ taxon_serializer.new(resource.parent, nested_context('parent')).as_json
+ end
+
+ def serialize_children
+ resource.children.map do |child|
+ taxon_serializer.new(child, nested_context('children')).as_json
+ end
+ end
+
+ def serialize_taxonomy
+ taxonomy_serializer.new(resource.taxonomy, nested_context('taxonomy')).as_json
+ end
+
+ # Serializer dependencies
+ def taxon_serializer
+ Spree::Api::Dependencies.v3_storefront_taxon_serializer.constantize
+ end
+
+ def taxonomy_serializer
+ Spree::Api::Dependencies.v3_storefront_taxonomy_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/taxonomy_serializer.rb b/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
new file mode 100644
index 0000000000..8e99a386da
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ class TaxonomySerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ name: resource.name,
+ }
+
+ base_attrs[:root] = serialize_root if include?('root')
+ base_attrs[:taxons] = serialize_taxons if include?('taxons')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_root
+ root_serializer.new(resource.root, nested_context('root')).as_json
+ end
+
+ def root_serializer
+ Spree::Api::Dependencies.v3_storefront_taxon_serializer.constantize
+ end
+
+ def serialize_taxons
+ taxons_serializer.new(resource.taxons, nested_context('taxons')).as_json
+ end
+
+ def taxons_serializer
+ Spree::Api::Dependencies.v3_storefront_taxon_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/user_serializer.rb b/api/app/serializers/spree/api/v3/user_serializer.rb
new file mode 100644
index 0000000000..96a8ee2e40
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/user_serializer.rb
@@ -0,0 +1,18 @@
+module Spree
+ module Api
+ module V3
+ class UserSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ email: resource.email,
+ first_name: resource.first_name,
+ last_name: resource.last_name,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/variant_serializer.rb b/api/app/serializers/spree/api/v3/variant_serializer.rb
new file mode 100644
index 0000000000..b68b2b2907
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/variant_serializer.rb
@@ -0,0 +1,90 @@
+module Spree
+ module Api
+ module V3
+ class VariantSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ name: resource.name,
+ sku: resource.sku,
+ barcode: resource.barcode,
+ weight: resource.weight&.to_f,
+ height: resource.height&.to_f,
+ width: resource.width&.to_f,
+ depth: resource.depth&.to_f,
+ is_master: resource.is_master,
+ options_text: resource.options_text,
+ purchasable: resource.purchasable?,
+ in_stock: resource.in_stock?,
+ backorderable: resource.backorderable?,
+ currency: currency,
+ price: price_value,
+ display_price: display_price_value,
+ compare_at_price: compare_at_price_value,
+ display_compare_at_price: display_compare_at_price_value
+ }
+
+ # Conditionally include associations
+ base_attrs[:images] = serialize_images if include?('images')
+ base_attrs[:option_values] = serialize_option_values if include?('option_values')
+ base_attrs[:product] = serialize_product if include?('product')
+
+ base_attrs
+ end
+
+ private
+
+ def price_value
+ price = price_in_currency(resource)
+ price&.amount&.to_f
+ end
+
+ def display_price_value
+ price = price_in_currency(resource)
+ price&.display_price&.to_s
+ end
+
+ def compare_at_price_value
+ price = price_in_currency(resource)
+ price&.compare_at_amount&.to_f
+ end
+
+ def display_compare_at_price_value
+ price = price_in_currency(resource)
+ return nil unless price&.compare_at_amount
+
+ Spree::Money.new(price.compare_at_amount, currency: currency).to_s
+ end
+
+ def serialize_images
+ resource.images.map do |image|
+ image_serializer.new(image, nested_context('images')).as_json
+ end
+ end
+
+ def serialize_option_values
+ resource.option_values.map do |option_value|
+ option_value_serializer.new(option_value, nested_context('option_values')).as_json
+ end
+ end
+
+ def serialize_product
+ product_serializer.new(resource.product, nested_context('product')).as_json if resource.product
+ end
+
+ # Serializer dependencies
+ def image_serializer
+ Spree::Api::Dependencies.v3_storefront_image_serializer.constantize
+ end
+
+ def option_value_serializer
+ Spree::Api::Dependencies.v3_storefront_option_value_serializer.constantize
+ end
+
+ def product_serializer
+ Spree::Api::Dependencies.v3_storefront_product_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/wished_item_serializer.rb b/api/app/serializers/spree/api/v3/wished_item_serializer.rb
new file mode 100644
index 0000000000..515428db76
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/wished_item_serializer.rb
@@ -0,0 +1,32 @@
+module Spree
+ module Api
+ module V3
+ class WishedItemSerializer < BaseSerializer
+ def attributes
+ base_attrs = {
+ id: resource.id,
+ quantity: resource.quantity,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+
+ # Conditionally include variant
+ base_attrs[:variant] = serialize_variant if include?('variant')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_variant
+ variant_serializer.new(resource.variant, nested_context('variant')).as_json if resource.variant
+ end
+
+ # Serializer dependencies
+ def variant_serializer
+ Spree::Api::Dependencies.v3_storefront_variant_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v3/wishlist_serializer.rb b/api/app/serializers/spree/api/v3/wishlist_serializer.rb
new file mode 100644
index 0000000000..137af8b145
--- /dev/null
+++ b/api/app/serializers/spree/api/v3/wishlist_serializer.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ class WishlistSerializer < BaseSerializer
+ def attributes
+ {
+ id: resource.id,
+ name: resource.name,
+ is_default: resource.is_default?,
+ is_private: resource.is_private?,
+ token: resource.token,
+ created_at: timestamp(resource.created_at),
+ updated_at: timestamp(resource.updated_at)
+ }
+
+ # Conditionally include items
+ base_attrs[:items] = serialize_items if include?('items')
+
+ base_attrs
+ end
+
+ private
+
+ def serialize_items
+ resource.wished_items.map do |item|
+ wished_item_serializer.new(item, nested_context('items')).as_json
+ end
+ end
+
+ # Serializer dependencies
+ def wished_item_serializer
+ Spree::Api::Dependencies.v3_storefront_wished_item_serializer.constantize
+ end
+ end
+ end
+ end
+end
diff --git a/api/config/initializers/pagy.rb b/api/config/initializers/pagy.rb
new file mode 100644
index 0000000000..ff41021c2e
--- /dev/null
+++ b/api/config/initializers/pagy.rb
@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Pagy initializer for API v3
+# https://ddnexus.github.io/pagy/docs/api/pagy/
+
+# Default page size for API responses
+Pagy.options[:limit] = 25
+
+# Maximum number of items per page
+Pagy.options[:limit_max] = 100
diff --git a/api/config/locales/en.yml b/api/config/locales/en.yml
index f47a3a923b..44ee4a534d 100644
--- a/api/config/locales/en.yml
+++ b/api/config/locales/en.yml
@@ -15,6 +15,7 @@ en:
payment:
credit_over_limit: This payment can only be credited up to %{limit}. Please specify an amount less than or equal to this number.
update_forbidden: This payment cannot be updated because it is %{state}.
+ record_not_found: '%{model} not found'
resource_not_found: The resource you were looking for could not be found.
shipment:
cannot_ready: Cannot ready shipment.
diff --git a/api/config/routes.rb b/api/config/routes.rb
index e85d1f5bef..3352398f40 100644
--- a/api/config/routes.rb
+++ b/api/config/routes.rb
@@ -217,5 +217,89 @@ Spree::Core::Engine.add_routes do
get '/google/:slug', to: 'google#rss_feed'
end
end
+
+ namespace :v3 do
+ namespace :storefront do
+ # ===== AUTHENTICATION =====
+ # Public endpoints for login/register, JWT required for refresh
+ post 'auth/login', to: 'auth#create'
+ post 'auth/register', to: 'auth#register'
+ post 'auth/refresh', to: 'auth#refresh'
+
+ # ===== STORE & CONFIGURATION (Public) =====
+ get 'store', to: 'stores#current'
+ resources :stores, only: [:show], param: :code
+
+ # Geography
+ resources :countries, only: [:index, :show] do
+ resources :states, only: [:index, :show]
+ end
+
+ # ===== CATALOG (Public) =====
+ # Products with Ransack filtering
+ # GET /products?q[name_cont]=shirt&q[s]=price+asc
+ resources :products, only: [:index, :show] do
+ resources :variants, only: [:index, :show]
+ end
+
+ # Taxons (categories)
+ resources :taxons, only: [:index, :show]
+
+ # ===== ORDERS (Public create, token or JWT for access) =====
+ # POST /orders - Create order (returns order_token for guests)
+ # Access via X-Order-Token header OR JWT
+ resources :orders do
+ # State transitions
+ member do
+ patch :next # Move to next checkout step
+ patch :advance # Advance through all steps
+ patch :complete # Complete the order
+ patch :cancel # Cancel the order
+ end
+
+ # Nested resources - all require order access
+ resources :line_items, only: [:index, :create, :show, :update, :destroy]
+ resources :payments, only: [:index, :create, :show]
+ resources :shipments, only: [:index, :show, :update]
+ resources :coupon_codes, only: [:create, :destroy]
+
+ # Available methods for order
+ resources :shipping_methods, only: [:index]
+ resources :payment_methods, only: [:index]
+
+ # Addresses as nested resources
+ resource :billing_address, only: [:show, :update], controller: 'order_addresses', defaults: { address_type: 'billing' }
+ resource :shipping_address, only: [:show, :update], controller: 'order_addresses', defaults: { address_type: 'shipping' }
+ end
+
+ # ===== CUSTOMER (JWT Required) =====
+ get 'customers/me', to: 'customers#show'
+ patch 'customers/me', to: 'customers#update'
+
+ resources :addresses, only: [:index, :show, :create, :update, :destroy], path: 'customers/me/addresses'
+ resources :payment_sources, only: [:index, :show, :destroy], path: 'customers/me/payment_sources'
+
+ # ===== WISHLISTS (JWT Required) =====
+ resources :wishlists do
+ get :default, on: :collection # Get or create default wishlist
+
+ # Wishlist items as nested resource
+ resources :items, only: [:index, :create, :update, :destroy], controller: 'wishlist_items'
+ end
+
+ # ===== CMS & CONTENT (Public) =====
+ resources :posts, only: [:index, :show]
+ resources :policies, only: [:index, :show]
+
+ # Pages (new page builder)
+ resources :pages, only: [:index, :show] do
+ resources :sections, only: [:index, :show]
+ end
+
+ # ===== DIGITAL DOWNLOADS =====
+ # Access via token in URL
+ get 'digitals/:token', to: 'digitals#download', as: :digital_download
+ end
+ end
end
end
diff --git a/api/lib/spree/api/dependencies.rb b/api/lib/spree/api/dependencies.rb
index 0d486d723c..3fadac57a9 100644
--- a/api/lib/spree/api/dependencies.rb
+++ b/api/lib/spree/api/dependencies.rb
@@ -90,6 +90,28 @@ module Spree
storefront_wished_item_serializer: 'Spree::V2::Storefront::WishedItemSerializer',
storefront_metafield_serializer: 'Spree::V2::Storefront::MetafieldSerializer',
+ # v3 storefront serializers
+ v3_storefront_product_serializer: 'Spree::Api::V3::ProductSerializer',
+ v3_storefront_variant_serializer: 'Spree::Api::V3::VariantSerializer',
+ v3_storefront_image_serializer: 'Spree::Api::V3::ImageSerializer',
+ v3_storefront_taxon_serializer: 'Spree::Api::V3::TaxonSerializer',
+ v3_storefront_option_type_serializer: 'Spree::Api::V3::OptionTypeSerializer',
+ v3_storefront_option_value_serializer: 'Spree::Api::V3::OptionValueSerializer',
+ v3_storefront_order_serializer: 'Spree::Api::V3::OrderSerializer',
+ v3_storefront_line_item_serializer: 'Spree::Api::V3::LineItemSerializer',
+ v3_storefront_payment_serializer: 'Spree::Api::V3::PaymentSerializer',
+ v3_storefront_shipment_serializer: 'Spree::Api::V3::ShipmentSerializer',
+ v3_storefront_address_serializer: 'Spree::Api::V3::AddressSerializer',
+ v3_storefront_user_serializer: 'Spree::Api::V3::UserSerializer',
+ v3_storefront_country_serializer: 'Spree::Api::V3::CountrySerializer',
+ v3_storefront_state_serializer: 'Spree::Api::V3::StateSerializer',
+ v3_storefront_store_serializer: 'Spree::Api::V3::StoreSerializer',
+ v3_storefront_wishlist_serializer: 'Spree::Api::V3::WishlistSerializer',
+ v3_storefront_wished_item_serializer: 'Spree::Api::V3::WishedItemSerializer',
+ v3_storefront_payment_method_serializer: 'Spree::Api::V3::PaymentMethodSerializer',
+ v3_storefront_shipping_method_serializer: 'Spree::Api::V3::ShippingMethodSerializer',
+ v3_storefront_shipping_rate_serializer: 'Spree::Api::V3::ShippingRateSerializer',
+ v3_storefront_taxonomy_serializer: 'Spree::Api::V3::TaxonomySerializer',
# platform serializers
platform_metafield_serializer: 'Spree::Api::V2::Platform::MetafieldSerializer',
diff --git a/api/spec/controllers/spree/api/v3/resource_controller_spec.rb b/api/spec/controllers/spree/api/v3/resource_controller_spec.rb
new file mode 100644
index 0000000000..6dbe03207e
--- /dev/null
+++ b/api/spec/controllers/spree/api/v3/resource_controller_spec.rb
@@ -0,0 +1,182 @@
+require 'spec_helper'
+
+class ApiV3DummyController < Spree::Api::V3::ResourceController
+ private
+
+ def model_class
+ Spree::Product
+ end
+
+ def serializer_class
+ Spree::Api::V3::ProductSerializer
+ end
+
+ def permitted_params
+ {}
+ end
+end
+
+describe Spree::Api::V3::ResourceController, type: :controller do
+ let(:dummy_controller) { ApiV3DummyController.new }
+ let(:store) { @default_store }
+ let!(:products) { create_list(:product, 30, stores: [store]) }
+
+ before do
+ request = double('request').as_null_object
+ allow(request).to receive(:base_url).and_return('http://example.com')
+ allow(request).to receive(:path).and_return('/api/v3/products')
+ allow(request).to receive(:query_string).and_return('')
+ allow(request).to receive(:GET).and_return({})
+ allow(request).to receive(:POST).and_return({})
+ allow(request).to receive(:cookies).and_return({})
+
+ allow(dummy_controller).to receive(:current_store).and_return(store)
+ allow(dummy_controller).to receive(:current_ability).and_return(Spree::Ability.new(nil))
+ allow(dummy_controller).to receive(:params).and_return(ActionController::Parameters.new(params))
+ allow(dummy_controller).to receive(:request).and_return(request)
+ end
+
+ describe '#collection' do
+ context 'with default pagination' do
+ let(:params) { {} }
+
+ it 'paginates with default limit of 25' do
+ collection = dummy_controller.send(:collection)
+ expect(collection.size).to eq(25)
+ end
+
+ it 'sets pagy instance variable' do
+ dummy_controller.send(:collection)
+ pagy = dummy_controller.instance_variable_get(:@pagy)
+ expect(pagy).to be_a(Pagy)
+ expect(pagy.limit).to eq(25)
+ expect(pagy.page).to eq(1)
+ expect(pagy.count).to eq(30)
+ end
+ end
+
+ context 'with custom per_page parameter' do
+ let(:params) { { per_page: 10 } }
+
+ it 'paginates with specified limit' do
+ collection = dummy_controller.send(:collection)
+ expect(collection.size).to eq(10)
+ end
+
+ it 'sets correct pagy metadata' do
+ dummy_controller.send(:collection)
+ pagy = dummy_controller.instance_variable_get(:@pagy)
+ expect(pagy.limit).to eq(10)
+ expect(pagy.pages).to eq(3)
+ end
+ end
+
+ context 'with custom limit parameter' do
+ let(:params) { { limit: 15 } }
+
+ it 'paginates with specified limit' do
+ collection = dummy_controller.send(:collection)
+ expect(collection.size).to eq(15)
+ end
+ end
+
+ context 'with page parameter' do
+ let(:params) { { page: 2, per_page: 10 } }
+
+ it 'returns correct page' do
+ collection = dummy_controller.send(:collection)
+ expect(collection.size).to eq(10)
+ pagy = dummy_controller.instance_variable_get(:@pagy)
+ expect(pagy.page).to eq(2)
+ end
+ end
+
+ context 'with limit exceeding maximum' do
+ let(:params) { { per_page: 200 } }
+
+ it 'caps at maximum of 100' do
+ collection = dummy_controller.send(:collection)
+ pagy = dummy_controller.instance_variable_get(:@pagy)
+ expect(pagy.limit).to eq(100)
+ end
+ end
+ end
+
+ describe '#collection_meta' do
+ let(:params) { { page: 1, per_page: 10 } }
+
+ before do
+ dummy_controller.send(:collection)
+ end
+
+ it 'returns data_hash with pagination metadata' do
+ meta = dummy_controller.send(:collection_meta, nil)
+ expect(meta).to be_a(Hash)
+ expect(meta[:count]).to eq(30)
+ expect(meta[:pages]).to eq(3)
+ expect(meta[:page]).to eq(1)
+ expect(meta[:limit]).to eq(10)
+ expect(meta[:from]).to eq(1)
+ expect(meta[:to]).to eq(10)
+ expect(meta[:in]).to eq(10)
+ end
+
+ context 'on last page' do
+ let(:params) { { page: 3, per_page: 10 } }
+
+ it 'returns correct metadata for last page' do
+ dummy_controller.send(:collection)
+ meta = dummy_controller.send(:collection_meta, nil)
+ expect(meta[:count]).to eq(30)
+ expect(meta[:pages]).to eq(3)
+ expect(meta[:page]).to eq(3)
+ expect(meta[:limit]).to eq(10)
+ expect(meta[:from]).to eq(21)
+ expect(meta[:to]).to eq(30)
+ expect(meta[:in]).to eq(10)
+ end
+ end
+ end
+
+ describe '#limit' do
+ context 'with per_page parameter' do
+ let(:params) { { per_page: 50 } }
+
+ it 'returns the per_page value' do
+ expect(dummy_controller.send(:limit)).to eq(50)
+ end
+ end
+
+ context 'with limit parameter' do
+ let(:params) { { limit: 30 } }
+
+ it 'returns the limit value' do
+ expect(dummy_controller.send(:limit)).to eq(30)
+ end
+ end
+
+ context 'with both per_page and limit parameters' do
+ let(:params) { { per_page: 20, limit: 30 } }
+
+ it 'prefers per_page over limit' do
+ expect(dummy_controller.send(:limit)).to eq(20)
+ end
+ end
+
+ context 'without parameters' do
+ let(:params) { {} }
+
+ it 'returns default limit of 25' do
+ expect(dummy_controller.send(:limit)).to eq(25)
+ end
+ end
+
+ context 'with limit exceeding maximum' do
+ let(:params) { { per_page: 150 } }
+
+ it 'caps at 100' do
+ expect(dummy_controller.send(:limit)).to eq(100)
+ end
+ end
+ end
+end