spree_api 5.6.1 → 6.0.0.beta2

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

@@ -6,6 +6,7 @@ module Spree
           typelize name: :string, url: :string, code: :string, api_url: :string,
                    preferred_storefront_url: [:string, nullable: true],
                    default_currency: :string, default_locale: :string,
+                   default_country_code: [:string, nullable: true],
                    supported_currencies: [:string, multi: true],
                    supported_locales: [:string, multi: true],
                    available_locales: [:string, multi: true],
@@ -17,11 +18,39 @@ module Spree
                    preferred_send_consumer_transactional_emails: :boolean,
                    preferred_admin_locale: [:string, nullable: true],
                    preferred_timezone: :string,
-                   preferred_weight_unit: :string,
+                   preferred_weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS],
                    preferred_unit_system: :string,
                    preferred_storefront_access: :string,
                    preferred_guest_checkout: :boolean,
+                   preferred_always_include_confirm_step: :boolean,
+                   preferred_company_field_enabled: :boolean,
+                   preferred_address_requires_company: :boolean,
+                   preferred_address_requires_phone: :boolean,
+                   preferred_capture_method: :string,
+                   preferred_track_inventory_levels: :boolean,
+                   preferred_stock_reservations_enabled: :boolean,
+                   preferred_low_stock_threshold: :number,
+                   preferred_tax_using_ship_address: :boolean,
+                   preferred_track_price_history: :boolean,
+                   preferred_show_products_without_price: :boolean,
+                   preferred_disable_sku_validation: :boolean,
                    preferred_order_routing_strategy: :string,
+                   preferred_pricing_provider: :string,
+                   preferred_inventory_provider: :string,
+                   preferred_pricing_provider_failure_policy: :string,
+                   preferred_inventory_provider_failure_policy: :string,
+                   preferred_payout_provider: 'string | null',
+                   preferred_default_payouts_schedule_interval: :string,
+                   preferred_default_minimum_payout_amount: :number,
+                   preferred_document_number_format: :string,
+                   preferred_order_number_prefix: :string,
+                   preferred_order_number_suffix: :string,
+                   preferred_order_number_sequence_start: :number,
+                   order_number_sequence_started: :boolean,
+                   preferred_limit_digital_download_count: :boolean,
+                   preferred_digital_asset_authorized_clicks: :number,
+                   preferred_limit_digital_download_days: :boolean,
+                   preferred_digital_asset_authorized_days: :number,
                    metadata: 'Record<string, unknown>'
 
           attributes :metadata,
@@ -30,6 +59,7 @@ module Spree
                      :preferred_storefront_url,
                      :default_currency,
                      :default_locale,
+                     :default_country_code,
                      :mail_from_address,
                      :customer_support_email,
                      :new_order_notifications_email,
@@ -40,9 +70,43 @@ module Spree
                      :preferred_unit_system,
                      :preferred_storefront_access,
                      :preferred_guest_checkout,
+                     :preferred_always_include_confirm_step,
+                     :preferred_company_field_enabled,
+                     :preferred_address_requires_company,
+                     :preferred_address_requires_phone,
+                     :preferred_capture_method,
+                     :preferred_track_inventory_levels,
+                     :preferred_stock_reservations_enabled,
+                     :preferred_low_stock_threshold,
+                     :preferred_tax_using_ship_address,
+                     :preferred_track_price_history,
+                     :preferred_show_products_without_price,
+                     :preferred_disable_sku_validation,
                      :preferred_order_routing_strategy,
+                     :preferred_pricing_provider,
+                     :preferred_inventory_provider,
+                     :preferred_pricing_provider_failure_policy,
+                     :preferred_inventory_provider_failure_policy,
+                     :preferred_payout_provider,
+                     :preferred_default_payouts_schedule_interval,
+                     :preferred_default_minimum_payout_amount,
+                     :preferred_document_number_format,
+                     :preferred_order_number_prefix,
+                     :preferred_order_number_suffix,
+                     :preferred_order_number_sequence_start,
+                     :preferred_limit_digital_download_count,
+                     :preferred_digital_asset_authorized_clicks,
+                     :preferred_limit_digital_download_days,
+                     :preferred_digital_asset_authorized_days,
                      created_at: :iso8601, updated_at: :iso8601
 
+          # Once the counter has issued a number the starting value no longer
+          # applies, so the settings page can say that instead of accepting a
+          # value that does nothing.
+          attribute :order_number_sequence_started do |store|
+            Spree::NumberSequence.started?(store: store)
+          end
+
           attribute :url, &:storefront_url
 
           # The backend's own public URL — what a headless client sets as its

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: who the merchant buys from is never a storefront
+        # concern.
+        class SupplierSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   contact_name: 'string | null',
+                   email: 'string | null',
+                   phone: 'string | null',
+                   notes: 'string | null',
+                   address1: 'string | null',
+                   address2: 'string | null',
+                   city: 'string | null',
+                   state_name: 'string | null',
+                   state_code: 'string | null',
+                   country_code: 'string | null',
+                   postal_code: 'string | null',
+                   purchase_orders_count: :number,
+                   can_be_deleted: :boolean,
+                   deleted_at: 'string | null',
+                   metadata: 'Record<string, unknown>'
+
+          attributes :name, :contact_name, :email, :phone, :notes,
+                     :address1, :address2, :city, :state_name, :state_code,
+                     :country_code, :postal_code, :purchase_orders_count, :metadata,
+                     created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
+
+          # Lets the dashboard hide the delete control rather than offer one
+          # the model will refuse.
+          attribute :can_be_deleted do |supplier|
+            supplier.can_be_deleted?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: certificates are back-office evidence with no storefront
+        # surface, so there is no store serializer to extend.
+        class TaxExemptionCertificateSerializer < V3::BaseSerializer
+          typelize certificate_number: :string, reason_code: :string, status: [:string, enum: Spree::TaxExemptionCertificate.statuses, enum_type_name: 'TaxExemptionCertificateStatus'],
+                   issuing_authority: [:string, nullable: true],
+                   company_id: :string,
+                   country_code: [:string, nullable: true], state_code: [:string, nullable: true],
+                   active: :boolean, lapsed: :boolean, can_be_deleted: :boolean,
+                   document_filename: [:string, nullable: true],
+                   document_byte_size: ['number | null'],
+                   document_url: [:string, nullable: true],
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :certificate_number, :reason_code, :status, :issuing_authority, :metadata,
+                     issued_at: :iso8601, expires_at: :iso8601, verified_at: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :company_id do |certificate|
+            certificate.company&.prefixed_id
+          end
+
+          # The jurisdiction the certificate holds in, in the same vocabulary the
+          # tax lines use.
+          attributes :country_code, :state_code
+
+          # Whether it counts right now — the status alone can't say, since a
+          # verified certificate stops counting once its date passes.
+          attribute :active do |certificate|
+            certificate.verified? && !certificate.lapsed?
+          end
+
+          attribute :lapsed do |certificate|
+            certificate.lapsed?
+          end
+
+          # Lets the dashboard hide a delete the model will refuse.
+          attribute :can_be_deleted do |certificate|
+            certificate.can_be_deleted?
+          end
+
+          attribute :document_filename do |certificate|
+            certificate.document.blob&.filename&.to_s if certificate.document.attached?
+          end
+
+          attribute :document_byte_size do |certificate|
+            certificate.document.blob&.byte_size if certificate.document.attached?
+          end
+
+          # Our own endpoint rather than a pre-signed URL: the controller streams
+          # the bytes, so admin auth runs on every download of a confidential
+          # document.
+          attribute :document_url do |certificate|
+            next nil unless certificate.document.attached?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_admin_company_tax_exemption_certificate_path(
+              company_id: certificate.company.prefixed_id, id: certificate.prefixed_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TaxIdentifierSerializer < V3::TaxIdentifierSerializer
+          typelize validation_status: [:string, nullable: true, enum: Spree::TaxIdentifier::VALIDATION_STATUSES],
+                   validated_at: [:string, nullable: true],
+                   validation_evidence: ['Record<string, unknown>', nullable: true],
+                   source: [:string, nullable: true, enum: Spree::TaxIdentifier::SOURCES],
+                   validatable: :boolean,
+                   customer_id: [:string, nullable: true],
+                   cart_id: [:string, nullable: true],
+                   order_id: [:string, nullable: true]
+
+          attributes :validation_status, :validation_evidence, :source,
+                     validated_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          # Whether this installation can check a number of this kind at all —
+          # what tells a nil verdict "not checked yet" apart from "nothing here
+          # knows how to ask".
+          attribute :validatable do |tax_identifier|
+            tax_identifier.validatable?
+          end
+
+          # The owner, reported under the name of what it is, so a client can
+          # tell a customer's durable registration from a cart override or an
+          # order's snapshot without reading a type string.
+          attribute :customer_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree.customer_class)
+          end
+
+          attribute :cart_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree::Cart)
+          end
+
+          attribute :order_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree::Order)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TaxLineSerializer < V3::TaxLineSerializer
+          typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false],
+                   provider_id: [:string, nullable: true], metadata: ['Record<string, unknown>', nullable: true],
+                   taxability_reason: [:string, nullable: true], country_code: [:string, nullable: true],
+                   state_code: [:string, nullable: true], data: ['Record<string, unknown>', nullable: true]
+
+          # The treatment and its jurisdiction stay admin-only: no surveyed
+          # platform shows a buyer a machine-readable tax reason, and `label`
+          # already covers what they need. `data` carries the provider's own
+          # breakdown, which is what an e-invoicing integration reads.
+          attributes :provider_id, :metadata, :taxability_reason, :country_code, :state_code, :data,
+                     created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: tax rates are the internal provider's configuration, never
+        # customer-facing. What the customer sees is the label on a tax line.
+        class TaxRateSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   amount: :string,
+                   amount_percentage: [:number, nullable: true],
+                   included_in_price: :boolean,
+                   show_rate_in_label: :boolean,
+                   tax_category_id: [:string, nullable: true],
+                   store_id: [:string, nullable: true],
+                   country_code: [:string, nullable: true],
+                   state_code: [:string, nullable: true],
+                   metadata: ['Record<string, unknown>', nullable: true],
+                   deleted_at: [:string, nullable: true]
+
+          attributes :name, :included_in_price, :show_rate_in_label, :metadata,
+                     created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
+
+          attribute :amount do |tax_rate|
+            tax_rate.amount&.to_s
+          end
+
+          # A real number, unlike the money-style `amount` string — this is a
+          # percentage for display, not an amount to round-trip exactly.
+          attribute :amount_percentage do |tax_rate|
+            tax_rate.amount_percentage&.to_f
+          end
+
+          attribute :tax_category_id do |tax_rate|
+            tax_rate.tax_category&.prefixed_id
+          end
+
+          attribute :store_id do |tax_rate|
+            tax_rate.store&.prefixed_id
+          end
+
+          # The jurisdiction the rate taxes, as codes: a null country means every
+          # country, and a country with no state means the whole country. Read
+          # and written under the same two names.
+          attributes :country_code, :state_code
+        end
+      end
+    end
+  end
+end

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

@@ -5,21 +5,38 @@ module Spree
         # Admin API Variant Serializer
         # Full variant data including admin-only fields
         class VariantSerializer < V3::VariantSerializer
+          include Concerns::ExternalReferencesAttribute
+
 
           typelize product_name: :string,
                    position: :number, tax_category_id: [:string, nullable: true],
                    cost_price: [:string, nullable: true], cost_currency: [:string, nullable: true],
                    barcode: [:string, nullable: true],
-                   weight_unit: [:string, nullable: true], dimensions_unit: [:string, nullable: true],
                    available_stock: [:number, nullable: true],
                    reserved_quantity: :number, total_on_hand: [:number, nullable: true],
                    preorderable: :boolean, preorder_ships_at: [:string, nullable: true],
                    backorder_limit: [:number, nullable: true],
+                   hs_code: [:string, nullable: true],
+                   country_of_origin: [:string, nullable: true],
+                   customs_description: [:string, nullable: true],
                    deleted_at: [:string, nullable: true],
+                   delivery_profile_id: [:string, nullable: true],
+                   minimum_order_quantity: ['number | null'], order_multiple: ['number | null'],
+                   purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS],
+                   carton_package_type_id: [:string, nullable: true],
+                   carton_weight: [:string, nullable: true],
+                   cartons_per_pallet: ['number | null'],
+                   units_per_pallet: ['number | null'],
                    metadata: 'Record<string, unknown>'
 
+          # The last three override the store serializer's buyer-resolved
+          # values with the variant's OWN: a merchant edits what is stored on
+          # the row, not what some catalog resolves to for a buyer they are not.
           attributes :metadata, :position, :cost_price, :cost_currency,
-                     :barcode, :weight_unit, :dimensions_unit, :backorder_limit,
+                     :barcode, :backorder_limit,
+                     :hs_code, :country_of_origin, :customs_description,
+                     :minimum_order_quantity, :order_multiple, :purchase_unit,
+                     :carton_weight, :cartons_per_pallet,
                      preorder_ships_at: :iso8601, deleted_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
@@ -31,8 +48,18 @@ module Spree
             variant.tax_category&.prefixed_id
           end
 
+          # Encoded from the foreign key: loading the carton row just to
+          # re-encode its id is a query per variant on the product listing.
+          attribute :carton_package_type_id do |variant|
+            Spree::PackageType.prefixed_id_for(variant.carton_package_type_id)
+          end
+
+          # How many units a full pallet holds — the far end of the packing
+          # chain, derived so a merchant sees it without doing the arithmetic.
+          attribute :units_per_pallet, &:units_per_pallet
+
           # Physical pool minus already-allocated units. In 5.5 allocated_count
-          # is always 0, so this equals SUM(stock_items.count_on_hand).
+          # is always 0, so this equals SUM(stock_levels.count_on_hand).
           attribute :available_stock do |variant|
             variant.available_stock.to_i if variant.should_track_inventory?
           end
@@ -50,6 +77,21 @@ module Spree
             variant.product&.name
           end
 
+          # How this variant ships — one answer, resolved on the model the same
+          # way the seller is. Writable: on a master product it names how this
+          # seller's row ships; on an owned product the write is a no-op, since
+          # every variant ships as the product does. The dashboard need not
+          # know which.
+          attribute :delivery_profile_id do |variant|
+            variant.resolved_delivery_profile&.prefixed_id
+          end
+
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') } do |variant|
+            variant.resolved_seller
+          end
+
           # Override inherited associations to use admin serializers
           one :primary_media,
               resource: proc { Spree.api.admin_media_serializer },
@@ -67,14 +109,13 @@ module Spree
                resource: proc { Spree.api.admin_price_serializer },
                if: proc { expand?('prices') }
 
-          many :metafields,
-               key: :custom_fields,
+          many :custom_fields,
                resource: proc { Spree.api.admin_custom_field_serializer },
                if: proc { expand?('custom_fields') }
 
-          many :stock_items,
-               resource: proc { Spree.api.admin_stock_item_serializer },
-               if: proc { expand?('stock_items') }
+          many :stock_levels,
+               resource: proc { Spree.api.admin_stock_level_serializer },
+               if: proc { expand?('stock_levels') }
         end
       end
     end

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

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      # Summary of promotions applied to a Cart or Order (serves the embedded
+      # `discounts` key). Distinct from DiscountSerializer, which serializes
+      # the typed Spree::Discount money rows.
+      class AppliedPromotionSerializer < BaseSerializer
+        typelize name: :string, description: [:string, nullable: true], code: [:string, nullable: true],
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true], promotion_id: :string
+
+        attribute :promotion_id do |record|
+          record.promotion&.prefixed_id
+        end
+
+        attributes :name, :description, :code
+
+        # Nulled for gated (prices_hidden) guests so an applied discount can't
+        # leak the amount the cart/order totals already withhold.
+        money_attributes :amount, :display_amount
+      end
+    end
+  end
+end

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

@@ -27,6 +27,39 @@ module Spree
           end
         end
 
+        # Declares the wire form of an `acted_by` association: the actor's
+        # prefixed id, the kind of actor it is, and the expansion. Both
+        # halves read off the columns, so naming an actor costs no query and
+        # the id and the kind always describe the same row (see
+        # docs/plans/6.0-action-actors.md).
+        #
+        # Declare the matching `typelize` entries alongside, as with any
+        # other attribute.
+        def self.actor_attributes(*names)
+          names.each do |name|
+            attribute(:"#{name}_id") { |object| object.acted_by_prefixed_id(name) }
+
+            attribute(:"#{name}_type") do |object|
+              Spree::Base.polymorphic_api_type(object.acted_by_type(name))
+            end
+
+            one name,
+                resource: proc { Spree.api.admin_actor_serializer },
+                if: proc { expand?(name.to_s) }
+          end
+        end
+
+        # Plain decimal notation. BigDecimal renders 0.06 as "0.6e-1", which
+        # is what a client would otherwise print beside a unit.
+        #
+        # @param value [BigDecimal, Numeric, nil]
+        # @return [String, nil]
+        def decimal_string(value)
+          return if value.nil?
+
+          BigDecimal(value.to_s).to_s('F')
+        end
+
         # Context accessors
         def current_store
           params[:store]
@@ -83,6 +116,13 @@ module Spree
           end
         end
 
+        # The variant a product leads with in the request's currency: the buy
+        # box winner, else the default variant. Resolved in the same currency
+        # `price_for` prices in, so the two never describe different rows.
+        def featured_variant(product)
+          product.featured_variant(currency: current_currency)
+        end
+
         # Returns price for a variant using full Price List resolution
         # This may return a price from a price list if applicable
         # Memoized per variant to avoid duplicate queries
@@ -102,6 +142,25 @@ module Spree
           )
         end
 
+        # The buyer's effective purchasing rules for a variant — their
+        # catalogs' commercial terms resolved over the variant's own base
+        # rules. Read from the request context the same way price_for does,
+        # so a storefront gets the stepper matching the price it is quoted.
+        #
+        # The resolver is request-scoped, not instance-scoped: Alba builds a
+        # fresh serializer for every element of a collection, so a memo held
+        # here would reload each catalog's override rows once per row on the
+        # page. Resolving without the buyer's company would also answer from
+        # a different agreement than the one pricing the same page.
+        def quantity_rule_for(variant)
+          return Spree::QuantityRule.new if current_store.nil?
+
+          Spree::Current.quantity_rules_resolver_for(
+            company: Spree::Current.standing_company_for(current_user),
+            user: current_user
+          ).call(variant)
+        end
+
         # Returns the base price for a variant without Price List resolution
         # This is the "original" price before any price list discounts
         # Memoized per variant to avoid duplicate queries
@@ -119,9 +178,9 @@ module Spree
           return nil if image.nil?
           return nil unless image.respond_to?(:attached?) && image.attached?
 
-          # Handle Spree::Asset models (like Spree::Image) which have attachment inside
+          # Handle Spree::Media rows, which keep the file in `attachment`
           # vs direct ActiveStorage attachments (like taxon.image)
-          attachment = image.is_a?(Spree::Asset) ? image.attachment : image
+          attachment = image.is_a?(Spree::Media) ? image.attachment : image
           Rails.application.routes.url_helpers.cdn_image_url(attachment)
         end
       end