spree_api 5.6.1 → 6.0.0.beta1

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

@@ -5,6 +5,14 @@ module Spree
         # Admin API Order Serializer
         # Full order data including admin-only fields
         class OrderSerializer < V3::OrderSerializer
+          include Concerns::ExternalReferencesAttribute
+
+
+          typelize company_id: [:string, nullable: true],
+                   company_name: [:string, nullable: true],
+                   seller_id: [:string, nullable: true],
+                   po_document_url: [:string, nullable: true],
+                   order_group_id: [:string, nullable: true]
 
           # The Admin API has no guest gating — money fields inherited from the
           # store serializer are always present, so override their nullability.
@@ -17,18 +25,37 @@ module Spree
                    additional_tax_total: [:string, nullable: false], display_additional_tax_total: [:string, nullable: false],
                    store_credit_total: [:string, nullable: false], display_store_credit_total: [:string, nullable: false],
                    gift_card_total: [:string, nullable: false], display_gift_card_total: [:string, nullable: false],
+                   fee_total: [:string, nullable: false], display_fee_total: [:string, nullable: false],
                    total: [:string, nullable: false], display_total: [:string, nullable: false],
                    amount_due: [:string, nullable: false], display_amount_due: [:string, nullable: false]
 
-          typelize status: :string,
+          # Back-office only: what the marketplace earned on this sale — the fee,
+          # the tax charged on it, and the two together. Never on the store
+          # serializer: a commission settles between the platform and the
+          # seller, and the shopper does not pay it.
+          #
+          # The tax stands on its own because it is separately reportable —
+          # the platform files it as output tax on a B2B supply to the seller.
+          typelize commission_amount_total: [:string, nullable: false],
+                   display_commission_amount_total: [:string, nullable: false],
+                   commission_tax_total: [:string, nullable: false],
+                   display_commission_tax_total: [:string, nullable: false],
+                   commission_total: [:string, nullable: false],
+                   display_commission_total: [:string, nullable: false]
+
+          typelize status: [:string, enum: Spree::Order::STATUSES],
                    last_ip_address: [:string, nullable: true],
                    considered_risky: :boolean, confirmation_delivered: :boolean,
                    store_owner_notification_delivered: :boolean,
-                   internal_note: [:string, nullable: true], approver_id: [:string, nullable: true],
+                   internal_note: [:string, nullable: true], internal_note_html: [:string, nullable: true],
+                   approver_id: [:string, nullable: true],
                    canceler_id: [:string, nullable: true], created_by_id: [:string, nullable: true],
                    customer_id: [:string, nullable: true],
                    preferred_stock_location_id: [:string, nullable: true],
                    canceled_at: [:string, nullable: true], approved_at: [:string, nullable: true],
+                   cancel_reason_id: [:string, nullable: true],
+                   cancel_reason_name: [:string, nullable: true],
+                   cancel_note: [:string, nullable: true],
                    payment_total: :string, display_payment_total: :string,
                    tags: [:string, multi: true],
                    metadata: 'Record<string, unknown>'
@@ -37,6 +64,10 @@ module Spree
           attributes :status, :last_ip_address, :considered_risky,
                      :confirmation_delivered, :store_owner_notification_delivered,
                      :payment_total, :display_payment_total, :metadata,
+                     :cancel_note,
+                     :commission_amount_total, :display_commission_amount_total,
+                     :commission_tax_total, :display_commission_tax_total,
+                     :commission_total, :display_commission_total,
                      canceled_at: :iso8601, approved_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
@@ -44,12 +75,57 @@ module Spree
             order.preferred_stock_location&.prefixed_id
           end
 
+          # Our own endpoint rather than a pre-signed storage URL: the
+          # controller streams the bytes, so admin auth runs on every download
+          # of the buyer's purchase order.
+          attribute :po_document_url do |order|
+            next nil unless order.po_document.attached?
+
+            Spree::Core::Engine.routes.url_helpers.po_document_api_v3_admin_order_path(id: order.prefixed_id)
+          end
+
+          # Which company node the order is for, so the dashboard can show and
+          # change it. Read back from the column rather than #resolved_company:
+          # a placed order must report what it was stamped with.
+          attribute :company_id do |order|
+            order.company&.prefixed_id
+          end
+
+          attribute :company_name do |order|
+            order.company&.name
+          end
+
+          # Whose sale this is — nil on the operator's own goods. The full
+          # profile is `?expand=seller`.
+          attribute :seller_id do |order|
+            order.seller&.prefixed_id
+          end
+
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') }
+
+          # The checkout this order was placed in, when it was placed alongside
+          # others.
+          #
+          # Deliberately an id and no expand: the group serializer renders the
+          # orders it holds, so expanding it from an order would render this
+          # order again inside itself. A client wanting the group fetches
+          # /order_groups/:id, which is what that endpoint is for.
+          attribute :order_group_id do |order|
+            Spree::OrderGroup.prefixed_id_for(order.order_group_id)
+          end
+
           attribute :tags do |order|
             order.tags.map(&:name) # not pluck as we preload tags
           end
 
           attribute :internal_note do |order|
-            order.internal_note&.to_plain_text.presence
+            Spree::RichTextHelper.to_plain_text(order.internal_note).presence
+          end
+
+          attribute :internal_note_html do |order|
+            order.internal_note.presence
           end
 
           attribute :approver_id do |order|
@@ -60,23 +136,47 @@ module Spree
             order.canceler&.prefixed_id
           end
 
+          attribute :cancel_reason_id do |order|
+            order.cancel_reason&.prefixed_id
+          end
+
+          # The reason's name alongside its id, so an order list can show why
+          # each canceled order was called off without expanding a record per
+          # row.
+          attribute :cancel_reason_name do |order|
+            order.cancel_reason&.name
+          end
+
           attribute :created_by_id do |order|
             order.created_by&.prefixed_id
           end
 
           attribute :customer_id do |order|
-            order.user&.prefixed_id
+            order.customer&.prefixed_id
           end
 
           # Override inherited associations to use admin serializers
-          many :discounts, resource: proc { Spree.api.admin_discount_serializer }, if: proc { expand?('discounts') }
+          # Renamed from the store's `discounts` key: on the admin surface that
+          # word means the typed money rows (/orders/:id/discounts), so the
+          # promotion summaries carry their real name here. The inherited
+          # store-keyed declaration is dropped, not shadowed.
+          _attributes.delete(:discounts)
+          # Fees reach the admin through their own `/orders/:id/fees` endpoint,
+          # which is also the write path — embedding them here would ship the
+          # same rows twice, through a store serializer.
+          _attributes.delete(:fees)
+          many :order_promotions, key: :applied_promotions, resource: proc { Spree.api.admin_applied_promotion_serializer }, if: proc { expand?('applied_promotions') }
           many :line_items, key: :items, resource: proc { Spree.api.admin_line_item_serializer }, if: proc { expand?('items') }
           many :fulfillments, resource: proc { Spree.api.admin_fulfillment_serializer }, if: proc { expand?('fulfillments') }
           many :payments, resource: proc { Spree.api.admin_payment_serializer }, if: proc { expand?('payments') }
+          # An order from a split checkout has no payments of its own; what it
+          # has is a share of each payment made against its group.
+          many :payment_splits, resource: proc { Spree.api.admin_payment_split_serializer }, if: proc { expand?('payment_splits') }
 
           one :billing_address, resource: proc { Spree.api.admin_address_serializer }, if: proc { expand?('billing_address') }
           one :shipping_address, resource: proc { Spree.api.admin_address_serializer }, if: proc { expand?('shipping_address') }
           one :gift_card, resource: proc { Spree.api.admin_gift_card_serializer }
+          one :cart, resource: proc { Spree.api.admin_cart_serializer }, if: proc { expand?('cart') }
           one :market, resource: proc { Spree.api.admin_market_serializer }
           one :channel, resource: proc { Spree.api.admin_channel_serializer }, if: proc { expand?('channel') }
           one :preferred_stock_location,
@@ -85,34 +185,46 @@ module Spree
 
           many :payment_methods, resource: proc { Spree.api.admin_payment_method_serializer }, if: proc { expand?('payment_methods') }
 
-          one :user,
-              key: :customer,
+          one :customer,
               resource: proc { Spree.api.admin_customer_serializer },
               if: proc { expand?('customer') }
 
+          # Staff actors, not customers — these point at Spree.admin_user_class.
           one :approver,
-              resource: proc { Spree.api.admin_customer_serializer },
+              resource: proc { Spree.api.admin_admin_user_serializer },
               if: proc { expand?('approver') }
 
           one :canceler,
-              resource: proc { Spree.api.admin_customer_serializer },
+              resource: proc { Spree.api.admin_admin_user_serializer },
               if: proc { expand?('canceler') }
 
+          one :cancel_reason,
+              resource: proc { Spree.api.admin_order_cancellation_reason_serializer },
+              if: proc { expand?('cancel_reason') }
+
           one :created_by,
-              resource: proc { Spree.api.admin_customer_serializer },
+              resource: proc { Spree.api.admin_admin_user_serializer },
               if: proc { expand?('created_by') }
 
-          many :adjustments,
-               resource: proc { Spree.api.admin_adjustment_serializer },
-               if: proc { expand?('adjustments') }
 
-          many :return_authorizations,
-               resource: proc { Spree.api.admin_return_authorization_serializer },
-               if: proc { expand?('return_authorizations') }
+          many :returns,
+               resource: proc { Spree.api.admin_return_serializer },
+               if: proc { expand?('returns') }
+
+          many :exchanges,
+               resource: proc { Spree.api.admin_exchange_serializer },
+               if: proc { expand?('exchanges') }
+
+          many :claims,
+               resource: proc { Spree.api.admin_claim_serializer },
+               if: proc { expand?('claims') }
+
+          # What the forwarder quoted against, frozen onto the rates this
+          # order shipped under. Back-office only: a buyer is told what their
+          # shipment costs, not how the warehouse packed it.
+          typelize freight_summary: [:FreightSummary, nullable: true]
 
-          many :reimbursements,
-               resource: proc { Spree.api.admin_reimbursement_serializer },
-               if: proc { expand?('reimbursements') }
+          one :freight_summary, resource: proc { Spree.api.admin_freight_summary_serializer }
         end
       end
     end

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

@@ -0,0 +1,53 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A store's packaging: the box it ships parcels in, and the cartons,
+        # pallets and containers a wholesale order leaves on. Back-office
+        # only — a shopper never picks their packaging.
+        class PackageTypeSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   kind: [:string, enum: Spree::PackageType::KINDS],
+                   length: [:string, nullable: true],
+                   width: [:string, nullable: true],
+                   height: [:string, nullable: true],
+                   dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS],
+                   weight: [:string, nullable: true],
+                   max_weight: [:string, nullable: true],
+                   weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS],
+                   volume: [:string, nullable: true],
+                   default: :boolean,
+                   seller_id: [:string, nullable: true],
+                   seller_name: [:string, nullable: true],
+                   metadata: ['Record<string, unknown> | null']
+
+          attributes :name, :kind, :length, :width, :height, :weight, :max_weight,
+                     :default, :metadata
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          # Both units read through their fallbacks, so a row that never set
+          # one still tells the merchant what its numbers mean.
+          attribute :dimensions_unit, &:dimensions_unit
+          attribute :weight_unit, &:weight_unit
+
+          # Cubic meters, so a merchant configuring volume tiers can read the
+          # figure their rules are compared against. Null until every side is
+          # measured.
+          attribute :volume, &:volume
+
+          # Whose packaging this is: a seller's own, or (null) the
+          # marketplace's shared vocabulary
+          # (docs/plans/6.0-seller-package-types.md).
+          attribute :seller_id do |package_type|
+            package_type.seller&.prefixed_id
+          end
+
+          attribute :seller_name do |package_type|
+            package_type.seller&.name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,13 +5,19 @@ module Spree
         class PaymentMethodSerializer < V3::PaymentMethodSerializer
           typelize active: :boolean,
                    auto_capture: [:boolean, nullable: true],
+                   capture_method: "'checkout' | 'on_dispatch' | 'manual' | null",
+                   resolved_capture_method: "'checkout' | 'on_dispatch' | 'manual'",
                    storefront_visible: :boolean,
                    position: :number,
                    metadata: 'Record<string, unknown>',
                    preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown }>"
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
 
-          attributes :metadata, :active, :auto_capture, :storefront_visible, :position,
+          # Null capture_method means the method inherits from its store;
+          # resolved_capture_method is what actually applies, so the dashboard
+          # can show the inherited value.
+          attributes :metadata, :active, :auto_capture, :capture_method, :resolved_capture_method,
+                     :storefront_visible, :position,
                      created_at: :iso8601, updated_at: :iso8601
 
           attribute :preferences, &:serialized_preferences

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

@@ -50,6 +50,12 @@ module Spree
           many :refunds,
                resource: proc { Spree.api.admin_refund_serializer },
                if: proc { expand?('refunds') }
+
+          # How a payment made against an order group is shared between the
+          # orders in it; empty on a payment made against a single order.
+          many :payment_splits,
+               resource: proc { Spree.api.admin_payment_split_serializer },
+               if: proc { expand?('payment_splits') }
         end
       end
     end

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

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::PaymentSplit — one child order's share of a payment
+        # made against its order group.
+        #
+        # Read-only: the shares are written by the split at checkout and kept
+        # current by the payment and refund subscribers.
+        class PaymentSplitSerializer < V3::BaseSerializer
+          AMOUNTS = %i[authorized_amount captured_amount refunded_amount claimed_amount
+                       net_captured_amount refundable_amount].freeze
+
+          typelize currency: :string,
+                   payment_id: :string,
+                   payment_number: 'string | null',
+                   order_id: :string,
+                   order_number: 'string | null',
+                   authorized_amount: :string, display_authorized_amount: :string,
+                   captured_amount: :string, display_captured_amount: :string,
+                   refunded_amount: :string, display_refunded_amount: :string,
+                   claimed_amount: :string, display_claimed_amount: :string,
+                   net_captured_amount: :string, display_net_captured_amount: :string,
+                   refundable_amount: :string, display_refundable_amount: :string
+
+          attributes :currency, created_at: :iso8601, updated_at: :iso8601
+
+          AMOUNTS.each do |amount|
+            attribute(amount) { |split| split.public_send(amount).to_s }
+            attribute(:"display_#{amount}") { |split| split.public_send(:"display_#{amount}").to_s }
+          end
+
+          attribute(:payment_id) { |split| split.payment&.prefixed_id }
+          attribute(:payment_number) { |split| split.payment&.number }
+          attribute(:order_id) { |split| split.order&.prefixed_id }
+          attribute(:order_number) { |split| split.order&.number }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes one permission catalog entry
+        # (Spree::PermissionConfiguration::Entry) for the discovery endpoint.
+        # Labels and descriptions resolve through Spree.t so backend extensions
+        # localize without shipping dashboard translations.
+        class PermissionSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize key: :string, resource: :string, kind: [:string, enum: %w[read write]], group: :string,
+                   group_label: :string, label: :string, description: :string
+
+          attributes :key
+
+          attribute(:resource) { |entry| entry.scope.name.to_s }
+          attribute(:kind) { |entry| entry.kind.to_s }
+          attribute(:group) { |entry| entry.scope.group.to_s }
+
+          attribute(:group_label) do |entry|
+            Spree.t("permissions_catalog.groups.#{entry.scope.group}",
+                    default: entry.scope.group.to_s.humanize)
+          end
+
+          attribute(:label) do |entry|
+            Spree.t("permissions_catalog.resources.#{entry.scope.name}.label",
+                    default: entry.scope.name.to_s.humanize)
+          end
+
+          attribute(:description) do |entry|
+            Spree.t("permissions_catalog.resources.#{entry.scope.name}.description", default: '')
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One band of a price list's percentage adjustment. Admin-only, like
+        # the list itself — the storefront sees resolved prices, never the
+        # arithmetic behind them.
+        class PriceAdjustmentTierSerializer < V3::BaseSerializer
+          typelize min_quantity: :number, percentage: :string
+
+          attributes :min_quantity
+
+          # A decimal as a string, like every other money-shaped value on the
+          # wire — a float would round the merchant's own figure.
+          attribute :percentage do |tier|
+            tier.percentage&.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A product as the price list's own page reads it: what the membership
+        # card renders, plus what the list charges for it per variant — a
+        # ladder shown where it is edited and not only where it is sold
+        # (docs/plans/6.0-volume-pricing.md).
+        #
+        # The rows are expanded rather than always sent, because resolving
+        # them costs a query per page that the picker has no use for. There is
+        # deliberately no product-level price: the card prices variants, and a
+        # figure on the product row would have to pick one variant to speak
+        # for the rest (docs/plans/6.0-volume-pricing.md).
+        class PriceListProductSerializer < Admin::MembershipProductSerializer
+          # Every variant with what this list charges for it, each with its
+          # own ladder. `source:` rather than an association: the rows are
+          # resolved per request against the list, which the serializer
+          # receives in params.
+          many :price_list_variants,
+               resource: proc { Spree.api.admin_catalog_price_serializer },
+               if: proc { expand?('price_list_price') },
+               source: lambda { |params|
+                 resolver = params[:price_list_price_resolver]
+
+                 variants.filter_map { |variant| resolver&.call(variant) }
+               }
+        end
+      end
+    end
+  end
+end

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

@@ -9,21 +9,32 @@ module Spree
         class PriceListSerializer < V3::BaseSerializer
           typelize name: :string,
                    description: 'string | null',
-                   status: :string,
+                   status: [:string, enum: Spree::PriceList.statuses, enum_type_name: 'PriceListStatus'],
                    position: :number,
                    starts_at: 'string | null',
                    ends_at: 'string | null',
                    deleted_at: 'string | null',
-                   match_policy: :string,
+                   match_policy: [:string, enum: Spree::PriceList::MATCH_POLICIES],
+                   price_adjustment_percentage: 'string | null',
+                   adjust_compare_at: :boolean,
+                   automatic_pricing: :boolean,
                    currently_active: :boolean,
                    products_count: :number,
-                   prices_count: :number,
-                   product_ids: [:string, multi: true]
+                   prices_count: :number
 
           attributes :name, :description, :status, :position, :match_policy,
+                     :adjust_compare_at,
                      starts_at: :iso8601, ends_at: :iso8601, deleted_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
+          # A decimal as a string, like every other money-shaped value on the
+          # wire — a float would round the merchant's own figure.
+          attribute :price_adjustment_percentage do |price_list|
+            price_list.price_adjustment_percentage&.to_s
+          end
+
+          attribute :automatic_pricing, &:automatic_pricing?
+
           attribute :currently_active, &:currently_active?
 
           # Cheap counts so the index can render "12 products / 36 prices"
@@ -36,10 +47,11 @@ module Spree
             pl.prices.count
           end
 
-          # Prefixed product ids in the list — drives the SPA's
-          # Products picker pre-fill, and is the same payload the
-          # client ships back on PATCH to reconcile membership.
-          attribute :product_ids, &:product_prefixed_ids
+          # Always expanded: a list's bands are the rest of the sentence its
+          # percentage starts, and the pricing card cannot render one without
+          # the other.
+          many :price_adjustment_tiers,
+               resource: proc { Spree.api.admin_price_adjustment_tier_serializer }
 
           many :price_rules,
                resource: proc { Spree.api.admin_price_rule_serializer },

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

@@ -6,12 +6,10 @@ module Spree
         # Same shape as PromotionRuleSerializer so the SPA can drive both
         # editors from one generic preference-form component.
         class PriceRuleSerializer < V3::BaseSerializer
-          typelize type: :string,
+          typelize type: [:string, comment: 'Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more.'],
                    price_list_id: :string,
                    preferences: 'Record<string, unknown>',
-                   preference_schema: 'Array<{ key: string; type: string; default: unknown }>',
-                   label: :string,
-                   description: 'string | null'
+                   preference_schema: 'Array<{ key: string; type: string; default: unknown }>'
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
@@ -26,14 +24,6 @@ module Spree
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema
 
-          attribute :label do |rule|
-            rule.class.respond_to?(:human_name) ? rule.class.human_name : rule.class.to_s.demodulize
-          end
-
-          attribute :description do |rule|
-            rule.class.respond_to?(:description) ? rule.class.description : nil
-          end
-
           # Embeds skip rules that don't carry the association (e.g.
           # VolumeRule has no markets/customers — the keys are omitted).
           many :markets,

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

@@ -6,9 +6,12 @@ module Spree
         # Extends Store Price Serializer with admin-only fields
         class PriceSerializer < V3::PriceSerializer
           typelize variant_id: [:string, nullable: true],
+                   min_quantity: :number,
                    created_at: :string,
                    updated_at: :string
 
+          attributes :min_quantity
+
           attribute :variant_id do |price|
             price&.variant&.prefixed_id
           end