spree_api 5.3.4 → 5.4.0.beta

data/app/serializers/spree/api/v3/variant_serializer.rb

@@ -0,0 +1,86 @@
+module Spree
+  module Api
+    module V3
+      # Store API Variant Serializer
+      # Customer-facing variant data with limited fields
+      class VariantSerializer < BaseSerializer
+        typelize product_id: :string, sku: [:string, nullable: true],
+                 is_master: :boolean, options_text: :string, track_inventory: :boolean, image_count: :number,
+                 thumbnail: [:string, nullable: true],
+                 purchasable: :boolean, in_stock: :boolean, backorderable: :boolean,
+                 weight: [:number, nullable: true], height: [:number, nullable: true], width: [:number, nullable: true], depth: [:number, nullable: true],
+                 price: 'StorePrice',
+                 original_price: ['StorePrice', nullable: true]
+
+        attribute :product_id do |variant|
+          variant.product&.prefixed_id
+        end
+
+        attributes :sku, :is_master, :options_text, :track_inventory, :image_count,
+                   created_at: :iso8601, updated_at: :iso8601
+
+        # Main variant image URL for listings (cached thumbnail)
+        attribute :thumbnail do |variant|
+          image_url_for(variant.thumbnail)
+        end
+
+        attribute :purchasable do |variant|
+          variant.purchasable?
+        end
+
+        attribute :in_stock do |variant|
+          variant.in_stock?
+        end
+
+        attribute :backorderable do |variant|
+          variant.backorderable?
+        end
+
+        attribute :weight do |variant|
+          variant.weight&.to_f
+        end
+
+        attribute :height do |variant|
+          variant.height&.to_f
+        end
+
+        attribute :width do |variant|
+          variant.width&.to_f
+        end
+
+        attribute :depth do |variant|
+          variant.depth&.to_f
+        end
+
+        # Price object - calculated price with price list resolution
+        attribute :price do |variant|
+          price = price_for(variant)
+          Spree.api.price_serializer.new(price, params: params).to_h if price.present?
+        end
+
+        # Original price - base price without price list resolution (for showing strikethrough)
+        # Returns null when same as calculated price, only populated when a price list discount is applied
+        attribute :original_price do |variant|
+          calculated = price_for(variant)
+          base = price_in(variant)
+
+          if calculated.present? && base.present? && calculated.id != base.id
+            Spree.api.price_serializer.new(base, params: params).to_h
+          end
+        end
+
+        # Conditional associations
+        many :images,
+             resource: Spree.api.image_serializer,
+             if: proc { params[:includes]&.include?('images') }
+
+        many :option_values, resource: Spree.api.option_value_serializer
+
+        many :public_metafields,
+             key: :metafields,
+             resource: Spree.api.metafield_serializer,
+             if: proc { params[:includes]&.include?('metafields') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/wished_item_serializer.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      class WishedItemSerializer < BaseSerializer
+        typelize variant_id: :string, wishlist_id: :string, quantity: :number
+
+        attribute :variant_id do |wished_item|
+          wished_item.variant&.prefixed_id
+        end
+
+        attribute :wishlist_id do |wished_item|
+          wished_item.wishlist&.prefixed_id
+        end
+
+        attributes :quantity,
+                   created_at: :iso8601, updated_at: :iso8601
+
+        one :variant, resource: Spree.api.variant_serializer
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/wishlist_serializer.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      class WishlistSerializer < BaseSerializer
+        typelize name: :string, token: :string, is_default: :boolean, is_private: :boolean
+
+        attributes :name, :token,
+                   created_at: :iso8601, updated_at: :iso8601
+
+        attribute :is_default do |wishlist|
+          wishlist.is_default?
+        end
+
+        attribute :is_private do |wishlist|
+          wishlist.is_private?
+        end
+
+        many :wished_items,
+             key: :items,
+             resource: Spree.api.wished_item_serializer,
+             if: proc { params[:includes]&.include?('items') }
+      end
+    end
+  end
+end

data/app/services/spree/api/v3/filters_aggregator.rb

@@ -0,0 +1,156 @@
+module Spree
+  module Api
+    module V3
+      class FiltersAggregator
+        SORT_OPTION_IDS = %w[
+          manual
+          best-selling
+          price-low-to-high
+          price-high-to-low
+          newest-first
+          oldest-first
+          name-a-z
+          name-z-a
+        ].freeze
+
+        # @param scope [ActiveRecord::Relation] Base product scope (already filtered by store, availability, taxon, etc.)
+        # @param currency [String] Currency for price range
+        # @param taxon [Spree::Taxon, nil] Optional taxon for default_sort and taxon filtering context
+        def initialize(scope:, currency:, taxon: nil)
+          @scope = scope
+          @currency = currency
+          @taxon = taxon
+        end
+
+        def call
+          {
+            filters: build_filters,
+            sort_options: sort_options,
+            default_sort: @taxon&.sort_order || 'manual',
+            total_count: @scope.distinct.count
+          }
+        end
+
+        private
+
+        def build_filters
+          [
+            price_filter,
+            availability_filter,
+            *option_type_filters,
+            taxon_filter
+          ].compact
+        end
+
+        def sort_options
+          SORT_OPTION_IDS.map do |id|
+            { id: id, label: Spree.t("products_sort_options.#{id.underscore}") }
+          end
+        end
+
+        def price_filter
+          # Remove ordering to avoid PostgreSQL DISTINCT + ORDER BY conflicts
+          prices = Spree::Price.for_products(@scope.reorder(''), @currency)
+          min = prices.minimum(:amount)
+          max = prices.maximum(:amount)
+          return nil if min.nil? || max.nil?
+
+          {
+            id: 'price',
+            type: 'price_range',
+            label: Spree.t(:price),
+            min: min.to_f,
+            max: max.to_f,
+            currency: @currency
+          }
+        end
+
+        def availability_filter
+          in_stock_count = @scope.in_stock.distinct.count
+          out_of_stock_count = @scope.out_of_stock.distinct.count
+
+          return nil if in_stock_count.zero? && out_of_stock_count.zero?
+
+          {
+            id: 'availability',
+            type: 'availability',
+            label: Spree.t(:availability),
+            options: [
+              { id: 'in_stock', label: Spree.t(:in_stock), count: in_stock_count },
+              { id: 'out_of_stock', label: Spree.t(:out_of_stock), count: out_of_stock_count }
+            ]
+          }
+        end
+
+        def option_type_filters
+          Spree::OptionType.filterable.includes(:option_values).order(:position).filter_map do |option_type|
+            values = option_type.option_values.for_products(@scope).distinct.order(:position)
+            next if values.empty?
+
+            {
+              id: option_type.prefixed_id,
+              type: 'option',
+              label: option_type.presentation,
+              name: option_type.name,
+              options: values.map { |ov| option_value_data(option_type, ov) }
+            }
+          end
+        end
+
+        def option_value_data(option_type, option_value)
+          # Count products in scope that have this option value
+          # We use a subquery approach to avoid GROUP BY conflicts when scope includes joins (like in_taxon)
+          # Join directly to option_value_variants for efficiency (skips joining through option_values table)
+          count = Spree::Product
+            .where(id: base_scope_product_ids)
+            .joins(:option_value_variants)
+            .where(Spree::OptionValueVariant.table_name => { option_value_id: option_value.id })
+            .distinct
+            .count
+
+          {
+            id: option_value.prefixed_id,
+            label: option_value.presentation,
+            name: option_value.name,
+            position: option_value.position,
+            count: count
+          }
+        end
+
+        def base_scope_product_ids
+          @base_scope_product_ids ||= @scope.reorder('').distinct.pluck(:id)
+        end
+
+        def taxon_filter
+          return nil if @taxon.nil?
+
+          # Get child taxons at the next depth level
+          child_taxons = @taxon.children.order(:lft).select do |child|
+            # Only include taxons that have products in the current scope
+            @scope.in_taxon(child).exists?
+          end
+
+          return nil if child_taxons.empty?
+
+          {
+            id: 'taxons',
+            type: 'taxon',
+            label: Spree.t(:category),
+            options: child_taxons.map { |t| taxon_option_data(t) }
+          }
+        end
+
+        def taxon_option_data(taxon)
+          count = @scope.in_taxon(taxon).distinct.count
+
+          {
+            id: taxon.prefixed_id,
+            label: taxon.name,
+            permalink: taxon.permalink,
+            count: count
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/api/v3/orders/update.rb

@@ -0,0 +1,103 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Clean API v3 order update service with modern conventions:
+        # - Flat parameter structure (no wrapping in "order" key)
+        # - snake_case field names without "_attributes" suffix
+        # - Automatic state management based on what's being updated
+        #
+        # @example Update shipping address
+        #   Spree::Api::V3::Orders::Update.call(
+        #     order: order,
+        #     params: {
+        #       email: "customer@example.com",
+        #       ship_address: {
+        #         firstname: "John",
+        #         lastname: "Doe",
+        #         address1: "123 Main St",
+        #         city: "New York",
+        #         zipcode: "10001",
+        #         country_iso: "US",
+        #         state_abbr: "NY"
+        #       }
+        #     }
+        #   )
+        #
+        class Update
+          prepend Spree::ServiceModule::Base
+
+          def call(order:, params:)
+            @order = order
+            @params = params.to_h.deep_symbolize_keys
+
+            ApplicationRecord.transaction do
+              assign_order_attributes
+              assign_address(:ship_address)
+              assign_address(:bill_address)
+
+              order.save!
+            end
+
+            success(order.reload)
+          rescue ActiveRecord::RecordInvalid => e
+            failure(order, e.record.errors.full_messages.to_sentence)
+          rescue StandardError => e
+            failure(order, e.message)
+          end
+
+          private
+
+          attr_reader :order, :params
+
+          def assign_order_attributes
+            order.email = params[:email] if params[:email].present?
+            order.special_instructions = params[:special_instructions] if params.key?(:special_instructions)
+            order.currency = params[:currency].upcase if params[:currency].present?
+          end
+
+          def assign_address(address_type)
+            address_id_param = params[:"#{address_type}_id"]
+            address_params = params[address_type]
+
+            # Priority 1: Direct address ID reference (ship_address_id / bill_address_id)
+            if address_id_param.present?
+              address_id = resolve_address_id(address_id_param)
+              order.public_send(:"#{address_type}_id=", address_id) if address_id
+              return
+            end
+
+            # Priority 2: Nested address params (ship_address / bill_address)
+            return unless address_params.is_a?(Hash)
+
+            if address_params[:id].present?
+              # Using existing address by ID within nested params
+              address_id = resolve_address_id(address_params[:id])
+              order.public_send(:"#{address_type}_id=", address_id) if address_id
+            else
+              # Creating/updating address with provided attributes
+              revert_to_address_state if order.has_checkout_step?('address')
+              order.public_send(:"#{address_type}_attributes=", address_params)
+            end
+          end
+
+          # Translate prefixed ID to internal id
+          def resolve_address_id(prefixed_id)
+            return unless order.user
+
+            decoded = Spree::Address.decode_prefixed_id(prefixed_id)
+            decoded ? order.user.addresses.find_by(id: decoded)&.id : nil
+          end
+
+          # Revert order state to 'address' when address changes
+          # This ensures shipments are recreated when transitioning back to delivery
+          def revert_to_address_state
+            return if ['cart', 'address'].include?(order.state)
+
+            order.state = 'address'
+          end
+        end
+      end
+    end
+  end
+end

data/config/initializers/alba.rb

@@ -0,0 +1,5 @@
+Alba.backend = :oj
+Alba.inflector = :active_support
+
+# Custom types
+Alba.register_type :iso8601, converter: ->(time) { time&.iso8601(3) }, auto_convert: true

data/config/initializers/pagy.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Pagy initializer for API v3
+# https://ddnexus.github.io/pagy/docs/api/pagy/
+
+# Default page size for API responses
+Pagy.options[:limit] = 25
+
+# Maximum number of items per page
+Pagy.options[:limit_max] = 100

data/config/initializers/typelizer.rb

@@ -0,0 +1,25 @@
+# Disable automatic type generation on boot — types are generated manually
+# via `bundle exec rake typelizer:generate`. Set ENABLE_TYPELIZER=1 to enable.
+ENV["DISABLE_TYPELIZER"] ||= "true" unless ENV["ENABLE_TYPELIZER"]
+
+Typelizer.configure do |config|
+  api_root = Spree::Api::Engine.root
+
+  config.dirs = [
+    api_root.join('app/serializers/spree/api/v3'),
+    api_root.join('app/serializers/spree/api/v3/admin')
+  ]
+  config.output_dir = api_root.join('../../packages/sdk/src/types/generated')
+  config.comments = true
+
+  # Type names: StoreProduct, AdminProduct, etc.
+  config.serializer_name_mapper = ->(serializer) {
+    name = serializer.name.to_s
+      .sub(/\ASpree::Api::V3::Admin::/, 'Admin')
+      .sub(/\ASpree::Api::V3::/, 'Store')
+      .sub(/Serializer\z/, '')
+    name
+  }
+
+  config.listen = false # https://github.com/skryukov/typelizer?tab=readme-ov-file#automatic-generation-in-development
+end

data/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.