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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
REST API v3 PoC
Damian Legawieca3951d475aa7
diff --git a/api/.claude/settings.local.json b/api/.claude/settings.local.jsonnew file mode 100644index 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.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/concerns/spree/api/v3/error_handler.rb b/api/app/controllers/concerns/spree/api/v3/error_handler.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/concerns/spree/api/v3/expandable_resources.rb b/api/app/controllers/concerns/spree/api/v3/expandable_resources.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/concerns/spree/api/v3/order_concern.rb b/api/app/controllers/concerns/spree/api/v3/order_concern.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb b/api/app/controllers/concerns/spree/api/v3/resource_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/concerns/spree/api/v3/storefront/authentication.rb b/api/app/controllers/concerns/spree/api/v3/storefront/authentication.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/base_controller.rb b/api/app/controllers/spree/api/v3/base_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/resource_controller.rb b/api/app/controllers/spree/api/v3/resource_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/addresses_controller.rb b/api/app/controllers/spree/api/v3/storefront/addresses_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/auth_controller.rb b/api/app/controllers/spree/api/v3/storefront/auth_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/base_controller.rb b/api/app/controllers/spree/api/v3/storefront/base_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/countries_controller.rb b/api/app/controllers/spree/api/v3/storefront/countries_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/coupon_codes_controller.rb b/api/app/controllers/spree/api/v3/storefront/coupon_codes_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/customers_controller.rb b/api/app/controllers/spree/api/v3/storefront/customers_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/digitals_controller.rb b/api/app/controllers/spree/api/v3/storefront/digitals_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/line_items_controller.rb b/api/app/controllers/spree/api/v3/storefront/line_items_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/order_addresses_controller.rb b/api/app/controllers/spree/api/v3/storefront/order_addresses_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/orders_controller.rb b/api/app/controllers/spree/api/v3/storefront/orders_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/pages_controller.rb b/api/app/controllers/spree/api/v3/storefront/pages_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/payment_methods_controller.rb b/api/app/controllers/spree/api/v3/storefront/payment_methods_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/payment_sources_controller.rb b/api/app/controllers/spree/api/v3/storefront/payment_sources_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/payments_controller.rb b/api/app/controllers/spree/api/v3/storefront/payments_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/policies_controller.rb b/api/app/controllers/spree/api/v3/storefront/policies_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/posts_controller.rb b/api/app/controllers/spree/api/v3/storefront/posts_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/products_controller.rb b/api/app/controllers/spree/api/v3/storefront/products_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/sections_controller.rb b/api/app/controllers/spree/api/v3/storefront/sections_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/shipments_controller.rb b/api/app/controllers/spree/api/v3/storefront/shipments_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/shipping_methods_controller.rb b/api/app/controllers/spree/api/v3/storefront/shipping_methods_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/states_controller.rb b/api/app/controllers/spree/api/v3/storefront/states_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/stores_controller.rb b/api/app/controllers/spree/api/v3/storefront/stores_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/taxons_controller.rb b/api/app/controllers/spree/api/v3/storefront/taxons_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/variants_controller.rb b/api/app/controllers/spree/api/v3/storefront/variants_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/wishlist_items_controller.rb b/api/app/controllers/spree/api/v3/storefront/wishlist_items_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/controllers/spree/api/v3/storefront/wishlists_controller.rb b/api/app/controllers/spree/api/v3/storefront/wishlists_controller.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/address_serializer.rb b/api/app/serializers/spree/api/v3/address_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/base_serializer.rb b/api/app/serializers/spree/api/v3/base_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/country_serializer.rb b/api/app/serializers/spree/api/v3/country_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/image_serializer.rb b/api/app/serializers/spree/api/v3/image_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/line_item_serializer.rb b/api/app/serializers/spree/api/v3/line_item_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/option_type_serializer.rb b/api/app/serializers/spree/api/v3/option_type_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/option_value_serializer.rb b/api/app/serializers/spree/api/v3/option_value_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/order_serializer.rb b/api/app/serializers/spree/api/v3/order_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/payment_method_serializer.rb b/api/app/serializers/spree/api/v3/payment_method_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/payment_serializer.rb b/api/app/serializers/spree/api/v3/payment_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/product_serializer.rb b/api/app/serializers/spree/api/v3/product_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/shipment_serializer.rb b/api/app/serializers/spree/api/v3/shipment_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/shipping_method_serializer.rb b/api/app/serializers/spree/api/v3/shipping_method_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/shipping_rate_serializer.rb b/api/app/serializers/spree/api/v3/shipping_rate_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/state_serializer.rb b/api/app/serializers/spree/api/v3/state_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/store_serializer.rb b/api/app/serializers/spree/api/v3/store_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/taxon_serializer.rb b/api/app/serializers/spree/api/v3/taxon_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/taxonomy_serializer.rb b/api/app/serializers/spree/api/v3/taxonomy_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/user_serializer.rb b/api/app/serializers/spree/api/v3/user_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/variant_serializer.rb b/api/app/serializers/spree/api/v3/variant_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/wished_item_serializer.rb b/api/app/serializers/spree/api/v3/wished_item_serializer.rbnew file mode 100644index 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+enddiff --git a/api/app/serializers/spree/api/v3/wishlist_serializer.rb b/api/app/serializers/spree/api/v3/wishlist_serializer.rbnew file mode 100644index 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+enddiff --git a/api/config/initializers/pagy.rb b/api/config/initializers/pagy.rbnew file mode 100644index 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] = 100diff --git a/api/config/locales/en.yml b/api/config/locales/en.ymlindex 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.rbindex e85d1f5bef..3352398f40 100644--- a/api/config/routes.rb+++ b/api/config/routes.rb@@ -217,5 +217,89 @@ Spree::Core::Engine.add_routes doget '/google/:slug', to: 'google#rss_feed'endend++ 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+ endendenddiff --git a/api/lib/spree/api/dependencies.rb b/api/lib/spree/api/dependencies.rbindex 0d486d723c..3fadac57a9 100644--- a/api/lib/spree/api/dependencies.rb+++ b/api/lib/spree/api/dependencies.rb@@ -90,6 +90,28 @@ module Spreestorefront_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 serializersplatform_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.rbnew file mode 100644index 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