spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -4,24 +4,13 @@ module Spree
       class StoreCreditEventSerializer < BaseSerializer
         typelize action: :string,
                  display_action: [:string, nullable: true],
-                 amount: :string,
-                 display_amount: :string,
                  authorization_code: [:string, nullable: true]
 
         attributes :action, :authorization_code
 
-        attribute :display_action do |event|
-          event.display_action
-        end
-
-        attribute :amount do |event|
-          event.amount.to_s
-        end
-
-        attribute :display_amount do |event|
-          event.display_amount.to_s
-        end
+        attributes :display_action
 
+        money_attributes :amount, :display_amount
         attributes created_at: :iso8601
       end
     end

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

@@ -2,34 +2,10 @@ module Spree
   module Api
     module V3
       class StoreCreditSerializer < BaseSerializer
-        typelize amount: :string, amount_used: :string, amount_remaining: :string,
-                 display_amount: :string, display_amount_used: :string, display_amount_remaining: :string,
-                 currency: :string
-
-        attribute :amount do |store_credit|
-          store_credit.amount.to_s
-        end
-
-        attribute :amount_used do |store_credit|
-          store_credit.amount_used.to_s
-        end
-
-        attribute :amount_remaining do |store_credit|
-          store_credit.amount_remaining.to_s
-        end
-
-        attribute :display_amount do |store_credit|
-          store_credit.display_amount.to_s
-        end
-
-        attribute :display_amount_used do |store_credit|
-          store_credit.display_amount_used.to_s
-        end
-
-        attribute :display_amount_remaining do |store_credit|
-          store_credit.display_amount_remaining.to_s
-        end
+        typelize currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode']
 
+        money_attributes :amount, :amount_used, :amount_remaining, :display_amount,
+                         :display_amount_used, :display_amount_remaining
         attributes :currency
       end
     end

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

@@ -1,10 +1,12 @@
 module Spree
   module Api
     module V3
-      # Payload of the supplier.* events. Suppliers have no storefront
-      # serializer — a customer never sees who the merchant buys from — so the
-      # event shape is declared here rather than found by convention.
-      class SupplierEventSerializer < Admin::SupplierSerializer
+      # Payload of the supplier.* events. A supplier's contact details stay
+      # behind the Admin API.
+      class SupplierEventSerializer < BaseSerializer
+        typelize name: :string
+
+        attributes :name, created_at: :iso8601, updated_at: :iso8601
       end
     end
   end

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

@@ -1,34 +1,22 @@
 module Spree
   module Api
     module V3
-      # A single tax charge (typed row) on a line item, fulfillment or fee.
+      # A single tax charge (typed row) on a line item, fulfillment or fee —
+      # or, after the sale, the tax a return, claim or exchange line gives
+      # back (`credit`) or charges on an exchange's replacement.
       class TaxLineSerializer < BaseSerializer
-        typelize label: :string, rate: :string, included: :boolean,
-                 amount: [:string, nullable: true], display_amount: [:string, nullable: true],
+        typelize label: :string, included: :boolean, credit: :boolean,
                  tax_rate_id: [:string, nullable: true], line_item_id: [:string, nullable: true],
-                 fulfillment_id: [:string, nullable: true], fee_id: [:string, nullable: true]
+                 fulfillment_id: [:string, nullable: true], fee_id: [:string, nullable: true],
+                 return_line_item_id: [:string, nullable: true], claim_line_item_id: [:string, nullable: true],
+                 exchange_line_item_id: [:string, nullable: true]
 
-        attributes :label, :included
+        attributes :label, :included, :credit
 
-        attribute :rate do |record|
-          record.rate&.to_s
-        end
+        rate_attributes :rate
 
-        attribute :tax_rate_id do |record|
-          record.tax_rate&.prefixed_id
-        end
-
-        attribute :line_item_id do |record|
-          record.line_item&.prefixed_id
-        end
-
-        attribute :fulfillment_id do |record|
-          record.fulfillment&.prefixed_id
-        end
-
-        attribute :fee_id do |record|
-          record.fee&.prefixed_id
-        end
+        prefixed_id_attributes :tax_rate, :line_item, :fulfillment, :fee, :return_line_item, :claim_line_item,
+                               :exchange_line_item
 
         money_attributes :amount, :display_amount
       end

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

@@ -17,9 +17,7 @@ module Spree
                  purchase_unit: [:string, enum: Spree::Variant::PURCHASE_UNITS], units_per_carton: ['number | null'],
                  seller_id: [:string, nullable: true]
 
-        attribute :product_id do |variant|
-          variant.product&.prefixed_id
-        end
+        prefixed_id_attributes :product
 
         attributes :sku, :options_text, :track_inventory, :media_count
 
@@ -34,21 +32,13 @@ module Spree
           image_url_for(variant.primary_media)
         end
 
-        attribute :purchasable do |variant|
-          variant.purchasable?
-        end
+        attribute :purchasable, &:purchasable?
 
-        attribute :in_stock do |variant|
-          variant.in_stock?
-        end
+        attribute :in_stock, &:in_stock?
 
-        attribute :backorderable do |variant|
-          variant.backorderable?
-        end
+        attribute :backorderable, &:backorderable?
 
-        attribute :preorder do |variant|
-          variant.preorder?
-        end
+        attribute :preorder, &:preorder?
 
         attribute :weight do |variant|
           variant.weight&.to_f
@@ -93,14 +83,12 @@ module Spree
           variant.purchase_unit.presence || 'unit'
         end
 
-        attribute :units_per_carton do |variant|
-          variant.units_per_carton
-        end
+        attributes :units_per_carton
 
         # 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?
+          price_serializer.new(price, params: params).to_h if price.present?
         end
 
         # Original price - base price without price list resolution (for showing strikethrough)
@@ -110,7 +98,7 @@ module Spree
           base = price_in(variant)
 
           if calculated.present? && base.present? && calculated.id != base.id
-            Spree.api.price_serializer.new(base, params: params).to_h
+            price_serializer.new(base, params: params).to_h
           end
         end
 
@@ -119,9 +107,7 @@ module Spree
         # listing) or the row itself (a master shared by several sellers). Nil
         # is first-party. Shoppers comparing offers on one page group by this,
         # so it is a plain attribute rather than an expand.
-        attribute :seller_id do |variant|
-          variant.resolved_seller&.prefixed_id
-        end
+        prefixed_id_attributes seller_id: :resolved_seller
 
         one :seller,
             resource: proc { Spree.api.seller_serializer },
@@ -151,7 +137,7 @@ module Spree
         attribute :prior_price,
                   if: proc { expand?('prior_price') } do |variant|
           record = price_in(variant)&.prior_price
-          Spree.api.price_history_serializer.new(record, params: params).to_h if record
+          price_history_serializer.new(record, params: params).to_h if record
         end
       end
     end

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

@@ -5,17 +5,7 @@ module Spree
         typelize variant_id: :string, wishlist_id: :string, quantity: :number,
                  product_id: :string
 
-        attribute :variant_id do |wishlist_item|
-          wishlist_item.variant&.prefixed_id
-        end
-
-        attribute :product_id do |wishlist_item|
-          wishlist_item.product&.prefixed_id
-        end
-
-        attribute :wishlist_id do |wishlist_item|
-          wishlist_item.wishlist&.prefixed_id
-        end
+        prefixed_id_attributes :variant, :product, :wishlist
 
         attributes :quantity
 

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

@@ -6,13 +6,9 @@ module Spree
 
         attributes :name, :token
 
-        attribute :is_default do |wishlist|
-          wishlist.is_default?
-        end
+        attribute :is_default, &:is_default?
 
-        attribute :is_private do |wishlist|
-          wishlist.is_private?
-        end
+        attribute :is_private, &:is_private?
 
         many :wishlist_items,
              key: :items,

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      # The Ransack predicates the v3 API accepts, per kind of value. Ransack
+      # itself would take far more; this is the published contract, so a
+      # non-Ruby implementation needs to support exactly these.
+      module FilterPredicates
+        EQUALITY = %w[eq not_eq in not_in].freeze
+        NULLITY = %w[null not_null].freeze
+        RANGE = (EQUALITY + %w[lt lteq gt gteq] + NULLITY).freeze
+        IDENTITY = (EQUALITY + NULLITY).freeze
+
+        BY_KIND = {
+          'text' => (EQUALITY + %w[cont i_cont not_cont start end] + NULLITY + %w[present blank]).freeze,
+          'decimal' => RANGE,
+          'integer' => RANGE,
+          'date' => RANGE,
+          'datetime' => RANGE,
+          'enum' => IDENTITY,
+          'id' => IDENTITY,
+          'type' => IDENTITY,
+          'boolean' => (EQUALITY + %w[true false null]).freeze
+        }.freeze
+
+        KINDS = BY_KIND.keys.freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,337 @@
+module Spree
+  module Api
+    module V3
+      # What one model may be filtered and sorted on by one audience, read
+      # from the model's Ransack allowlists (see Spree::RansackableAttributes)
+      # and its columns. Nothing here declares a filter: the allowlists stay
+      # the only source, and this turns them into the published contract that
+      # the OpenAPI specs carry and the SDK filter types are generated from.
+      #
+      #   Spree::Api::V3::FilterTable.for_model(Spree::Order, nil).to_h
+      #   # => { 'attributes' => { 'number' => 'text', 'total' => 'decimal', ... },
+      #   #      'associations' => { 'line_items' => 'LineItem' },
+      #   #      'scopes' => { 'complete' => 'boolean', 'search' => 'text' },
+      #   #      'sortable' => ['number', 'total', ...] }
+      class FilterTable
+        # Associations deeper than this are not part of the contract.
+        MAX_DEPTH = 2
+
+        COLUMN_KINDS = {
+          string: 'text', text: 'text', citext: 'text', uuid: 'text',
+          integer: 'integer', bigint: 'integer',
+          decimal: 'decimal', float: 'decimal',
+          date: 'date',
+          datetime: 'datetime', timestamp: 'datetime', timestamptz: 'datetime',
+          boolean: 'boolean'
+        }.freeze
+
+        # Raised when an endpoint's table cannot be described — a column of a
+        # kind the contract has no predicates for, or two models sharing a name.
+        class Error < StandardError; end
+
+        attr_reader :model, :audience
+
+        class << self
+          # @param model [Class] an ActiveRecord model
+          # @param audience [Symbol, nil] the Ransack auth object: nil for the
+          #   back office, `:store` or `:seller`
+          # @return [FilterTable]
+          def for_model(model, audience)
+            cache[[model.name, audience]] ||= new(model, audience)
+          end
+
+          # @param controller_class [Class] a Spree::Api::V3::ResourceController
+          # @return [Endpoint]
+          def for(controller_class)
+            Endpoint.new(controller_class)
+          end
+
+          # Forgets every computed table, for when the allowlists change at
+          # runtime (extensions in `to_prepare`, specs).
+          def reset!
+            @cache = {}
+          end
+
+          # Every list endpoint the routes serve, as `[api, path, Endpoint]`
+          # with the path in OpenAPI form (`/api/v3/admin/orders/{order_id}/items`).
+          #
+          # @return [Array<Array(String, String, Endpoint)>]
+          def endpoints
+            Spree::Core::Engine.routes.routes.filter_map do |route|
+              defaults = route.defaults
+              next unless defaults[:action] == 'index' && defaults[:controller].to_s.start_with?('spree/api/v3/')
+
+              controller = "#{defaults[:controller]}_controller".camelize.safe_constantize
+              next unless controller && controller < Spree::Api::V3::ResourceController
+
+              api = defaults[:controller].to_s.split('/')[3]
+              path = route.path.spec.to_s.delete_suffix('(.:format)').gsub(/:(\w+)/, '{\\1}')
+              [api, path, self.for(controller)]
+            end.uniq { |api, path, _| [api, path] }
+          end
+
+          # One API's filters in the shape its OpenAPI spec carries them —
+          # `paths.<path>.get.x-spree-filters` and the components' tables and
+          # predicates — read from the allowlists this app has right now, so an
+          # app's own filters are included.
+          #
+          # @param api [String] `store`, `admin` or `seller`
+          # @return [Hash]
+          def spec_for(api)
+            paths = {}
+            tables = {}
+            endpoints.each do |endpoint_api, path, endpoint|
+              next unless endpoint_api == api && endpoint.filterable?
+
+              paths[path] = { 'get' => { 'x-spree-filters' => endpoint.to_h } }
+              endpoint.tables.each { |name, table| tables[name] ||= table.to_h }
+            end
+
+            {
+              'paths' => paths.sort.to_h,
+              'components' => {
+                'x-spree-filter-tables' => tables.sort.to_h,
+                'x-spree-filter-predicates' => FilterPredicates::BY_KIND
+              }
+            }
+          end
+
+          # The name a table goes by in the contract: the model's API short
+          # name, camelized — `Order`, `LineItem`, `Customer`.
+          #
+          # @param model [Class]
+          # @return [String]
+          def name_for(model)
+            Spree::Base.polymorphic_api_type(model.name).camelize
+          end
+
+          private
+
+          def cache
+            @cache ||= {}
+          end
+        end
+
+        # @param model [Class]
+        # @param audience [Symbol, nil]
+        def initialize(model, audience)
+          @model = model
+          @audience = audience
+        end
+
+        # @return [String]
+        def name
+          self.class.name_for(model)
+        end
+
+        # @return [Hash{String => String, Hash}] attribute => value kind, or
+        #   `{ 'enum' => [values] }` for a status
+        def attributes
+          @attributes ||= kinds.reject { |_, kind| kind == :unclassified }.compact
+        end
+
+        # Declared attributes whose value kind could not be determined; a
+        # non-empty list fails the filter table spec.
+        #
+        # @return [Array<String>]
+        def unclassified_attributes
+          kinds.select { |_, kind| kind == :unclassified }.keys
+        end
+
+        # Renamed columns kept under their old name (`payment_state`, through
+        # `alias_attribute`), published until they are removed but left out of
+        # the reference. A `ransack_alias` is a deliberate public name and stays.
+        #
+        # @return [Array<String>]
+        def aliased_attributes
+          attributes.keys.select { |attribute| model.attribute_aliases.key?(attribute) }
+        end
+
+        # @return [Hash{String => FilterTable}]
+        def associations
+          @associations ||= model.ransackable_associations(audience).sort.each_with_object({}) do |name, tables|
+            reflection = model.reflect_on_association(name.to_sym)
+            next if reflection.nil? || reflection.polymorphic?
+
+            tables[name.to_s] = self.class.for_model(reflection.klass, audience)
+          end
+        end
+
+        # @return [Hash{String => String, Array, Hash}] scope => argument type:
+        #   one kind, a list of kinds (positional arguments), or
+        #   `{ 'list' => kind }` for any number of arguments
+        def scopes
+          @scopes ||= begin
+            declared = (model.respond_to?(:ransackable_scope_types) ? model.ransackable_scope_types : {}).
+                       merge(Spree.ransack.custom_scope_types_for(model)).stringify_keys
+            model.ransackable_scopes(audience).map(&:to_s).sort.index_with do |scope|
+              normalize_scope_type(declared.fetch(scope) { inferred_scope_type(scope) })
+            end
+          end
+        end
+
+        # @return [Array<String>]
+        def sortable
+          @sortable ||= model.ransortable_attributes(audience).map(&:to_s).select { |attribute| attributes.key?(attribute) }.sort
+        end
+
+        # Every table reachable from this one within {MAX_DEPTH} hops,
+        # including this one.
+        #
+        # @return [Hash{String => FilterTable}]
+        def reachable(depth = 0, found = {})
+          if found.key?(name) && found[name].model != model
+            raise Error, "#{found[name].model.name} and #{model.name} are both published as #{name}; give one a distinct api_type"
+          end
+
+          found[name] ||= self
+          return found if depth >= MAX_DEPTH
+
+          associations.each_value { |table| table.reachable(depth + 1, found) }
+          found
+        end
+
+        # @return [Hash]
+        def to_h
+          {
+            'attributes' => attributes,
+            'associations' => associations.transform_values(&:name),
+            'scopes' => scopes
+          }
+        end
+
+        private
+
+        def kinds
+          @kinds ||= model.ransackable_attributes(audience).map(&:to_s).uniq.sort.index_with { |attribute| attribute_kind(attribute) }
+        end
+
+        # @return [String, Hash, Symbol, nil] the kind; nil for a default
+        #   attribute the model does not have (`position` on a table without
+        #   one), `:unclassified` for one the contract cannot describe
+        def attribute_kind(attribute)
+          aliased = model._ransack_aliases[attribute] || model.attribute_aliases[attribute]
+          return attribute_kind(aliased) if aliased
+          return ransacker_kind(model._ransackers[attribute]) if model._ransackers.key?(attribute)
+          return 'id' if id_attribute?(attribute)
+          return 'type' if type_attribute?(attribute)
+          return { 'enum' => model.statuses } if attribute == 'status' && model.respond_to?(:statuses)
+          return { 'enum' => model.defined_enums[attribute].keys } if model.defined_enums.key?(attribute)
+          if (values = inclusion_values(attribute))
+            return { 'enum' => values }
+          end
+
+          column = model.columns_hash[attribute]
+          return COLUMN_KINDS.fetch(column.type, :unclassified) if column
+          return 'text' if translated_attribute?(attribute)
+          return nil if model.default_ransackable_attributes.include?(attribute)
+
+          :unclassified
+        end
+
+        # The fixed list an inclusion validation allows, for a column that
+        # holds one of a known set of values (`payment_status`, `kind`).
+        def inclusion_values(attribute)
+          validator = model.validators_on(attribute.to_sym).find { |candidate| candidate.is_a?(ActiveModel::Validations::InclusionValidator) }
+          values = validator&.options&.[](:in)
+          values.map(&:to_s).uniq if values.is_a?(Array) && values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) }
+        end
+
+        def ransacker_kind(ransacker)
+          COLUMN_KINDS.fetch(ransacker.type.to_sym, :unclassified)
+        end
+
+        def id_attribute?(attribute)
+          attribute == model.primary_key ||
+            model.reflect_on_all_associations(:belongs_to).any? { |reflection| reflection.foreign_key.to_s == attribute }
+        end
+
+        def type_attribute?(attribute)
+          model.respond_to?(:api_type_resolver) && model.api_type_resolver(attribute).present?
+        end
+
+        def translated_attribute?(attribute)
+          model.respond_to?(:translatable_fields) && model.translatable_fields.map(&:to_s).include?(attribute)
+        end
+
+        # What a class method's signature says about its arguments. A `scope`
+        # lambda hides its signature behind `(*args, **)`, so an undeclared one
+        # is published as taking one text value.
+        def inferred_scope_type(scope)
+          parameters = model.method(scope).parameters
+          return 'text' if parameters.any? { |type, _| type == :keyrest }
+          return { 'list' => 'text' } if parameters.any? { |type, _| type == :rest }
+
+          required = parameters.count { |type, _| type == :req }
+          case required
+          when 0 then 'boolean'
+          when 1 then 'text'
+          else Array.new(required, 'text')
+          end
+        end
+
+        def normalize_scope_type(type)
+          case type
+          when Hash then { 'list' => validate_kind(type.stringify_keys.fetch('list')) }
+          when Array then type.map { |kind| validate_kind(kind) }
+          else validate_kind(type)
+          end
+        end
+
+        def validate_kind(kind)
+          kind = kind.to_s
+          return kind if FilterPredicates::KINDS.include?(kind)
+
+          raise Error, "#{model.name}.ransackable_scope_types names an unknown kind #{kind.inspect}"
+        end
+
+        # One list endpoint: the table its model has for the controller's
+        # audience, plus what the controller accepts beyond it.
+        class Endpoint
+          attr_reader :controller_class
+
+          # @param controller_class [Class]
+          def initialize(controller_class)
+            @controller_class = controller_class
+          end
+
+          # @return [Boolean]
+          def filterable?
+            controller.send(:filterable?)
+          end
+
+          # @return [FilterTable]
+          def table
+            @table ||= FilterTable.for_model(controller.send(:model_class), controller.send(:ransack_auth_object))
+          end
+
+          # @return [Array<String>]
+          def sortable
+            (table.sortable | controller.send(:additional_sort_fields).map(&:to_s)).sort
+          end
+
+          # @return [Hash{String => FilterTable}] the tables this endpoint's
+          #   filters reach, keyed by name
+          def tables
+            table.reachable
+          end
+
+          # The `x-spree-filters` extension of the endpoint's OpenAPI operation.
+          #
+          # @return [Hash]
+          def to_h
+            extension = { 'table' => table.name, 'sortable' => sortable }
+            extension['custom_fields'] = true if controller.send(:custom_field_filters?)
+            extension
+          end
+
+          private
+
+          def controller
+            @controller ||= controller_class.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -63,8 +63,8 @@ module Spree
           {
             id: 'price',
             type: 'price_range',
-            min: min.to_f,
-            max: max.to_f,
+            min: min,
+            max: max,
             currency: @currency
           }
         end