spree_api 5.6.1 → 6.0.0.beta1

data/app/serializers/spree/api/v3/admin/catalog_product_term_serializer.rb

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One product's quantity terms under a catalog — the grain the
+        # agreement editor states them at, over rows stored per variant.
+        class CatalogProductTermSerializer < V3::BaseSerializer
+          typelize product_id: :string, product_name: 'string | null',
+                   minimum_order_quantity: ['number | null'],
+                   order_multiple: ['number | null'],
+                   mixed: :boolean
+
+          attribute :id do |term|
+            term.product.prefixed_id
+          end
+
+          attribute :product_id do |term|
+            term.product.prefixed_id
+          end
+
+          attribute :product_name do |term|
+            term.product.name
+          end
+
+          attribute :minimum_order_quantity, &:minimum_order_quantity
+          attribute :order_multiple, &:order_multiple
+
+          # True when the product's variants carry different terms, so the
+          # editor shows "mixed" rather than claiming one variant's pair is
+          # the product's.
+          attribute :mixed do |term|
+            term.mixed?
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_quantity_rule_serializer.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One catalog's quantity terms for one variant. Carries enough of the
+        # variant to render the row without a second request — a merchant
+        # reading a terms table needs to know which SKU each line is about.
+        class CatalogQuantityRuleSerializer < V3::BaseSerializer
+          typelize variant_id: 'string | null', variant_sku: 'string | null',
+                   product_name: 'string | null',
+                   options_text: 'string | null',
+                   minimum_order_quantity: ['number | null'],
+                   order_multiple: ['number | null']
+
+          attributes :minimum_order_quantity, :order_multiple,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :variant_id do |rule|
+            rule.variant&.prefixed_id
+          end
+
+          attribute :variant_sku do |rule|
+            rule.variant&.sku
+          end
+
+          attribute :product_name do |rule|
+            rule.variant&.name
+          end
+
+          attribute :options_text do |rule|
+            rule.variant&.options_text.presence
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_serializer.rb

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: catalogs are merchandising configuration with no
+        # storefront surface — buyers see their effects, never the record.
+        class CatalogSerializer < V3::BaseSerializer
+          typelize name: :string, description: 'string | null',
+                   active: :boolean, position: [:number, nullable: true],
+                   products_count: :number, pricing_strategy: :string,
+                   minimum_order_quantity: ['number | null'], order_multiple: ['number | null'],
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :name, :description, :active, :position, :metadata,
+                     :minimum_order_quantity, :order_multiple,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :products_count do |catalog|
+            catalog.catalog_products.size
+          end
+
+          # One word for how the agreement prices, so a listing can show it
+          # without expanding a price list for every row.
+          attributes :pricing_strategy
+
+          # Minimums are few (one per currency) and the card renders them
+          # inline, so they ride along rather than costing a second request.
+          many :order_minimums,
+               resource: proc { Spree.api.admin_catalog_order_minimum_serializer },
+               if: proc { expand?('order_minimums') }
+
+          # The owned list rides along so the agreement editor can render its
+          # pricing without a second request — the catalog page is where an
+          # owned list is edited (docs/plans/6.0-catalog-agreement-rework.md).
+          one :price_list,
+              resource: proc { Spree.api.admin_price_list_serializer },
+              if: proc { expand?('price_list') }
+
+          many :catalog_assignments, key: :assignments,
+               resource: proc { Spree.api.admin_catalog_assignment_serializer },
+               if: proc { expand?('assignments') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/category_serializer.rb

@@ -5,6 +5,8 @@ module Spree
         # Admin API Category Serializer
         # Full category data including admin-only fields
         class CategorySerializer < V3::CategorySerializer
+          include Concerns::ExternalReferencesAttribute
+
           include Spree::Api::V3::Admin::Translatable
 
           typelize pretty_name: :string, lft: :number, rgt: :number, products_count: :number,
@@ -26,8 +28,7 @@ module Spree
                resource: proc { Spree.api.admin_category_serializer },
                if: proc { expand?('ancestors') }
 
-          many :metafields,
-               key: :custom_fields,
+          many :custom_fields,
                resource: proc { Spree.api.admin_custom_field_serializer },
                if: proc { expand?('custom_fields') }
         end

data/app/serializers/spree/api/v3/admin/channel_serializer.rb

@@ -6,12 +6,26 @@ module Spree
           typelize store_id: :string,
                    preferred_order_routing_strategy: [:string, nullable: true],
                    preferred_storefront_access: [:string, nullable: true],
-                   preferred_guest_checkout: [:boolean, nullable: true]
+                   preferred_guest_checkout: [:boolean, nullable: true],
+                   stock_location_ids: [:string, multi: true],
+                   default_catalog_id: [:string, nullable: true]
 
           attributes :preferred_order_routing_strategy,
                      :preferred_storefront_access,
                      :preferred_guest_checkout,
                      created_at: :iso8601, updated_at: :iso8601
+
+          # Fulfillment-origin allowlist; empty means every store location
+          # serves this channel.
+          attribute :stock_location_ids do |record|
+            record.stock_locations.map(&:prefixed_id)
+          end
+
+          # When set, only the default catalog's products are visible on this
+          # channel; unset means every publication.
+          attribute :default_catalog_id do |record|
+            record.default_catalog&.prefixed_id
+          end
         end
       end
     end

data/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          one :variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('variant') }
+          one :replacement_variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('replacement_variant') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/claim_reason_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ClaimReasonSerializer < V3::ClaimReasonSerializer
+          typelize can_be_deleted: :boolean
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          # Lets the dashboard hide destructive controls instead of offering a
+          # delete that the model will refuse.
+          attribute :can_be_deleted do |reason|
+            reason.can_be_deleted?
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/claim_serializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ClaimSerializer < V3::ClaimSerializer
+          typelize memo: [:string, nullable: true],
+                   metadata: 'Record<string, unknown>',
+                   created_by_id: [:string, nullable: true]
+
+          attributes :memo, :metadata, created_at: :iso8601, updated_at: :iso8601
+
+          attribute :created_by_id do |claim|
+            claim.created_by&.prefixed_id
+          end
+
+          many :claim_line_items,
+               resource: proc { Spree.api.admin_claim_line_item_serializer },
+               if: proc { expand?('claim_line_items') }
+
+          one :reason, resource: proc { Spree.api.admin_claim_reason_serializer }, if: proc { expand?('reason') }
+          one :order, resource: proc { Spree.api.admin_order_serializer }, if: proc { expand?('order') }
+          many :refunds, resource: proc { Spree.api.admin_refund_serializer }, if: proc { expand?('refunds') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/collection_rule_serializer.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::CollectionRule (and its STI subclasses) for the
+        # admin collection editor's `rules` association. Admin-only — automatic
+        # collection rules are never exposed by the Store API. `type` is the
+        # wire shorthand (e.g. "tag"), matching every other typed-rule
+        # serializer and what the writer accepts.
+        class CollectionRuleSerializer < BaseSerializer
+          typelize type: [:string, comment: 'Rule type. Built-in: tag, available_on, sale. Extensions may register more.'], value: [:string, nullable: true], match_policy: [:string, enum: Spree::CollectionRule::MATCH_POLICIES]
+
+          attributes :value, :match_policy
+
+          attribute :type do |rule|
+            rule.class.api_type
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/collection_serializer.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API Collection serializer — extends the customer-facing serializer
+        # with the merchandising config (automatic / rules_match_policy / rules)
+        # and back-office fields (metadata, timestamps, admin custom fields).
+        class CollectionSerializer < V3::CollectionSerializer
+          include Spree::Api::V3::Admin::Translatable
+
+          typelize automatic: :boolean, rules_match_policy: [:string, enum: Spree::Collection::RULES_MATCH_POLICIES],
+                   metadata: 'Record<string, unknown>'
+
+          attributes :automatic, :rules_match_policy, :metadata,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          many :rules,
+               resource: proc { Spree.api.admin_collection_rule_serializer },
+               if: proc { expand?('rules') }
+
+          # Override inherited custom_fields to use the admin serializer.
+          many :custom_fields,
+               resource: proc { Spree.api.admin_custom_field_serializer },
+               if: proc { expand?('custom_fields') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/commission_line_serializer.rb

@@ -0,0 +1,67 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::CommissionLine — what one sale actually earned the
+        # marketplace, frozen at placement.
+        #
+        # Read-only everywhere: a commission line records something that
+        # already happened, so it is never written through the API.
+        #
+        # `amount` and `tax_amount` stay separate rather than being folded into
+        # `total`, because they are two different supplies: the fee, and the
+        # VAT the platform charges the seller on that fee. A seller's invoice
+        # has to show both.
+        class CommissionLineSerializer < V3::BaseSerializer
+          typelize order_id: :string,
+                   seller_id: :string,
+                   seller_name: 'string | null',
+                   line_item_id: 'string | null',
+                   fulfillment_id: 'string | null',
+                   commission_rate_id: 'string | null',
+                   kind: [:string, enum: Spree::CommissionRate::KINDS],
+                   rate: :string,
+                   tax_rate: :string,
+                   taxability_reason: 'string | null',
+                   country_code: 'string | null',
+                   state_code: 'string | null',
+                   amount: :string,
+                   tax_amount: :string,
+                   total: :string,
+                   currency: :string,
+                   display_amount: :string,
+                   display_tax_amount: :string,
+                   display_total: :string
+
+          # The treatment, in Spree::TaxLine's vocabulary — a seller's invoice
+          # has to explain why its fee was taxed the way it was, and the
+          # jurisdiction is the seller's own rather than the shopper's.
+          attributes :kind, :currency, :taxability_reason, :country_code, :state_code,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # Strings, so the figures a seller is invoiced round-trip exactly.
+          %i[rate tax_rate amount tax_amount total].each do |decimal|
+            attribute(decimal) { |line| line.public_send(decimal)&.to_s }
+          end
+
+          %i[display_amount display_tax_amount display_total].each do |formatted|
+            attribute(formatted) { |line| line.public_send(formatted).to_s }
+          end
+
+          %i[order seller line_item fulfillment commission_rate].each do |association|
+            attribute(:"#{association}_id") { |line| line.public_send(association)&.prefixed_id }
+          end
+
+          # The seller's name, so a commission table reads without expanding.
+          attribute :seller_name do |line|
+            line.seller&.name
+          end
+
+          one :commission_rate,
+              resource: proc { Spree.api.admin_commission_rate_serializer },
+              if: proc { expand?('commission_rate') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb

@@ -0,0 +1,69 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::CommissionRate — what the marketplace charges, as
+        # configuration.
+        #
+        # Admin-only: a rate is a term of business between the operator and its
+        # sellers, so it has no Store API counterpart. Sellers read what they
+        # were actually charged (Spree::CommissionLine) on their own branch,
+        # never the rules that produced it.
+        class CommissionRateSerializer < V3::BaseSerializer
+          # Decimals serialize as strings, like every other money-ish field on
+          # the admin API: a rate has to round-trip exactly, and a float does
+          # not promise that.
+          typelize name: :string,
+                   code: 'string | null',
+                   enabled: :boolean,
+                   position: :number,
+                   global: :boolean,
+                   kind: [:string, enum: Spree::CommissionRate::KINDS],
+                   value: :string,
+                   amounts: 'Record<string, string>',
+                   bounds: 'Record<string, { min_amount: string | null; max_amount: string | null }>',
+                   tax_inclusive: :boolean,
+                   include_shipping: :boolean,
+                   commission_tax_rate: 'string | null',
+                   metadata: 'Record<string, unknown> | null',
+                   deleted_at: 'string | null'
+
+          attributes :name, :code, :enabled, :position, :kind,
+                     :tax_inclusive, :include_shipping, :metadata,
+                     deleted_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          %i[value commission_tax_rate].each do |decimal|
+            attribute(decimal) { |rate| rate.public_send(decimal)&.to_s }
+          end
+
+          # What a flat fee charges, per currency. Empty on a percentage rate,
+          # which needs no amount of its own.
+          attribute :amounts do |rate|
+            rate.amounts.transform_values(&:to_s)
+          end
+
+          # The floor and cap a percentage charges within, per currency. Each
+          # holds only in its own currency, so a rate may bound some and leave
+          # others unbounded.
+          attribute :bounds do |rate|
+            rate.bounds.transform_values do |bound|
+              bound.transform_values { |amount| amount&.to_s }
+            end
+          end
+
+          # A rate that names nothing matches every sale, so everything below
+          # it in the list is unreachable. The dashboard needs to say so.
+          attribute :global, &:global?
+
+          # Always embedded rather than expand-gated: a rate without its
+          # targeting cannot be read (a rate with no rules means something
+          # entirely different from one whose rules were not loaded), and
+          # they are a handful of rows.
+          many :commission_rules,
+               key: :rules,
+               resource: proc { Spree.api.admin_commission_rule_serializer }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/commission_rule_serializer.rb

@@ -0,0 +1,61 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::CommissionRule — one condition on a rate.
+        #
+        # Admin-only, like everything commission: what a marketplace charges is
+        # between it and its sellers, so there is no Store API counterpart.
+        #
+        # Shaped like the price-rule serializer so one generic editor can drive
+        # both: the wire `type`, the values, and the schema describing them.
+        class CommissionRuleSerializer < V3::BaseSerializer
+          typelize type: [:string, comment: 'Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more.'],
+                   commission_rate_id: :string,
+                   preferences: 'Record<string, unknown>',
+                   preference_schema: 'Array<{ key: string; type: string; default: unknown }>',
+                   product_ids: 'Array<string> | null',
+                   seller_ids: 'Array<string> | null',
+                   category_ids: 'Array<string> | null'
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          attribute :type do |rule|
+            rule.class.api_type
+          end
+
+          attribute :commission_rate_id do |rule|
+            rule.commission_rate&.prefixed_id
+          end
+
+          attribute :preferences, &:serialized_preferences
+          attribute :preference_schema, &:serialized_preference_schema
+
+          # Reference lists are returned as prefixed IDs to match the rest of
+          # the API. Product ids are read through a join table; seller and
+          # category ids live in preferences server-side but are not exposed
+          # that way on the wire — the picker round-trips prefixed ids.
+          attribute :product_ids do |rule|
+            rule.product_prefixed_ids if rule.respond_to?(:product_prefixed_ids)
+          end
+
+          attribute :seller_ids do |rule|
+            rule.sellers.map(&:prefixed_id) if rule.respond_to?(:sellers)
+          end
+
+          attribute :category_ids do |rule|
+            rule.categories.map(&:prefixed_id) if rule.respond_to?(:categories)
+          end
+
+          many :sellers,
+               resource: proc { Spree.api.admin_seller_serializer },
+               if: proc { |rule| rule.respond_to?(:sellers) }
+
+          many :categories,
+               resource: proc { Spree.api.admin_category_serializer },
+               if: proc { |rule| rule.respond_to?(:categories) }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/company_invitation_serializer.rb

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CompanyInvitationSerializer < V3::CompanyInvitationSerializer
+          typelize accepted_at: [:string, nullable: true],
+                   revoked_at: [:string, nullable: true]
+
+          attributes accepted_at: :iso8601, revoked_at: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/company_membership_serializer.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CompanyMembershipSerializer < V3::CompanyMembershipSerializer
+          attributes created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/company_serializer.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CompanySerializer < V3::CompanySerializer
+          include Concerns::ExternalReferencesAttribute
+
+          typelize children_count: :number, members_count: :number,
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :metadata, created_at: :iso8601, updated_at: :iso8601
+
+          # Saves the dashboard a request per row just to render the tree
+          # expander and "3 members".
+          attribute :children_count do |company|
+            company.children.size
+          end
+
+          # The member count covers the node's whole subtree
+          attributes :members_count
+
+          many :children,
+               resource: proc { Spree.api.admin_company_serializer },
+               if: proc { expand?('children') }
+
+          many :addresses,
+               resource: proc { Spree.api.admin_address_serializer },
+               if: proc { expand?('addresses') }
+
+          many :memberships,
+               resource: proc { Spree.api.admin_company_membership_serializer },
+               if: proc { expand?('memberships') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/concerns/external_references_attribute.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Concerns
+          # Renders a record's identities in external systems as a flat
+          # `{ system => external_id }` map — the shape a connector reads, and
+          # the same shape the controllers accept on write.
+          #
+          # Admin-only: which ERP a merchant runs, and under what key a product
+          # lives there, is back-office information.
+          #
+          # Named for the attribute rather than the feature because the
+          # controller concern of the obvious name already sits in the sibling
+          # controller namespace, and Alba resolves the shorter constant to it.
+          module ExternalReferencesAttribute
+            def self.included(base)
+              base.class_eval do
+                typelize external_references: 'Record<string, string>'
+
+                attribute :external_references do |resource|
+                  resource.external_references.each_with_object({}) do |reference, result|
+                    result[reference.system] = reference.external_id
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/consent_record_serializer.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API Consent Record Serializer
+        # The evidence trail behind a customer's consent state.
+        class ConsentRecordSerializer < BaseSerializer
+          typelize purpose: :string, source: [:string, enum: Spree::ConsentRecord::SOURCES], accepted: :boolean,
+                   email: [:string, nullable: true],
+                   ip_address: [:string, nullable: true],
+                   recorded_at: [:string, nullable: true],
+                   documents: 'Array<Record<string, unknown>>'
+
+          attributes :purpose, :source, :accepted, :email, :ip_address,
+                     created_at: :iso8601
+
+          attribute :recorded_at do |record|
+            record.recorded_at&.iso8601
+          end
+
+          attribute :documents do |record|
+            record.documents_list
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/country_serializer.rb

@@ -2,9 +2,9 @@ module Spree
   module Api
     module V3
       module Admin
+        # No timestamps: countries are reference data supplied by the countries
+        # gem rather than records, so they have no created_at/updated_at.
         class CountrySerializer < V3::CountrySerializer
-          attributes created_at: :iso8601, updated_at: :iso8601
-
           many :states,
                resource: proc { Spree.api.admin_state_serializer },
                if: proc { params[:expand]&.include?('states') }

data/app/serializers/spree/api/v3/admin/credit_card_serializer.rb

@@ -8,7 +8,7 @@ module Spree
                    metadata: 'Record<string, unknown>'
 
           attribute :customer_id do |credit_card|
-            credit_card.user&.prefixed_id
+            credit_card.customer&.prefixed_id
           end
 
           attribute :payment_method_id do |credit_card|

data/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb

@@ -8,8 +8,8 @@ module Spree
           typelize namespace: :string,
                    key: :string,
                    label: :string,
-                   field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
-                   resource_type: :string,
+                   field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
+                   resource_type: [:string, comment: 'Class name of the resource the field attaches to, for example Spree::Product, Spree::Order or Spree::Customer. Extensions may register more.'],
                    storefront_visible: :boolean,
                    searchable: :boolean,
                    sortable: :boolean,