spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One product's contribution to the rollup: how many units, the
+        # cartons they fill and how those were measured.
+        #
+        # Back-office only. A buyer is told what their shipment costs and how
+        # big it is; which SKU accounts for which part of it is the
+        # warehouse's business.
+        class FreightSummaryLineSerializer < BaseSerializer
+          # A value object, not a record — it has no id of its own.
+          _attributes.delete(:id)
+
+          typelize variant_id: [:string, nullable: true],
+                   sku: [:string, nullable: true],
+                   name: [:string, nullable: true],
+                   units: :number,
+                   cartons: ['number | null'],
+                   pallets: ['number | null'],
+                   units_per_carton: ['number | null'],
+                   cartons_per_pallet: ['number | null'],
+                   weight_per_carton: [:string, nullable: true],
+                   volume: :string,
+                   weight: :string,
+                   complete: :boolean
+
+          attributes :variant_id, :sku, :name, :units, :cartons, :pallets,
+                     :units_per_carton, :cartons_per_pallet, :complete
+
+          attribute :weight_per_carton do |line|
+            decimal_string(line.weight_per_carton)
+          end
+
+          attribute :volume do |line|
+            decimal_string(line.volume)
+          end
+
+          attribute :weight do |line|
+            decimal_string(line.weight)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The store's rollup plus what each product contributes to it — the
+        # breakdown a merchant checks a forwarder's quote against, and the
+        # reason the store shape carries totals alone.
+        class FreightSummarySerializer < V3::FreightSummarySerializer
+          typelize lines: [:FreightSummaryLine, multi: true]
+
+          many :lines, resource: proc { Spree.api.admin_freight_summary_line_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A fulfilled unit. Admin-only: it exists so the dashboard can offer
+        # what is actually returnable or exchangeable — a return is against a
+        # shipped unit, not against a line item.
+        class FulfillmentItemSerializer < BaseSerializer
+          typelize quantity: :number,
+                   status: [:string, enum: Spree::FulfillmentItem.statuses, enum_type_name: 'FulfillmentItemStatus'],
+                   variant_id: [:string, nullable: true],
+                   line_item_id: [:string, nullable: true],
+                   name: [:string, nullable: true],
+                   options_text: [:string, nullable: true]
+
+          attributes :quantity, :status
+
+          attribute :variant_id do |item|
+            item.variant&.prefixed_id
+          end
+
+          attribute :line_item_id do |item|
+            item.line_item&.prefixed_id
+          end
+
+          attribute :name do |item|
+            item.variant&.product&.name
+          end
+
+          attribute :options_text do |item|
+            item.variant&.options_text
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -13,6 +13,8 @@ module Spree
                    tax_total: [:string, nullable: false], display_tax_total: [:string, nullable: false]
 
           typelize metadata: 'Record<string, unknown>',
+                   documents: "Array<{ kind: string; url: string }>",
+                   provider_generates_labels: :boolean,
                    order_id: [:string, nullable: true],
                    stock_location_id: [:string, nullable: true],
                    adjustment_total: :string,
@@ -21,26 +23,46 @@ module Spree
           attributes :metadata, :adjustment_total, :pre_tax_amount,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :order_id do |shipment|
-            shipment.order&.prefixed_id
+          attribute :order_id do |fulfillment|
+            fulfillment.order&.prefixed_id
           end
 
-          attribute :stock_location_id do |shipment|
-            shipment.stock_location&.prefixed_id
+          attribute :stock_location_id do |fulfillment|
+            fulfillment.stock_location&.prefixed_id
+          end
+
+          # Customs forms and other paperwork the provider produced beside the
+          # label; the labels themselves are listed under +labels+.
+          attribute :documents do |fulfillment|
+            fulfillment.provider.documents(fulfillment).map(&:as_json)
+          end
+
+          # Every label bought or uploaded for this parcel, refunded ones
+          # included — the postage history of the box.
+          many :shipping_labels, key: :labels, resource: proc { Spree.api.admin_shipping_label_serializer }
+
+          # Whether the buy-label step applies to this parcel's provider.
+          attribute :provider_generates_labels do |fulfillment|
+            fulfillment.provider.class.generates_labels?
           end
 
           # Override inherited associations to use admin serializers
-          one :shipping_method, key: :delivery_method, resource: proc { Spree.api.admin_delivery_method_serializer }, if: proc { expand?('delivery_method') }
+          many :deliveries, resource: proc { Spree.api.admin_delivery_serializer }
+          one :delivery_method, resource: proc { Spree.api.admin_delivery_method_serializer }, if: proc { expand?('delivery_method') }
           one :stock_location, resource: proc { Spree.api.admin_stock_location_serializer }, if: proc { expand?('stock_location') }
-          many :shipping_rates, key: :delivery_rates, resource: proc { Spree.api.admin_delivery_rate_serializer }, if: proc { expand?('delivery_rates') }
+          many :delivery_rates, resource: proc { Spree.api.admin_delivery_rate_serializer }, if: proc { expand?('delivery_rates') }
+          many :tax_lines, resource: proc { Spree.api.admin_tax_line_serializer }, if: proc { expand?('tax_lines') }
+
+          # The units in this fulfillment — the dashboard needs them to offer
+          # what can actually be returned or exchanged.
+          many :fulfillment_items,
+               resource: proc { Spree.api.admin_fulfillment_item_serializer },
+               if: proc { expand?('fulfillment_items') }
 
           one :order,
               resource: proc { Spree.api.admin_order_serializer },
               if: proc { expand?('order') }
 
-          many :adjustments,
-               resource: proc { Spree.api.admin_adjustment_serializer },
-               if: proc { expand?('adjustments') }
         end
       end
     end

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

@@ -19,7 +19,7 @@ module Spree
           attributes created_at: :iso8601, updated_at: :iso8601
 
           attribute :customer_id do |gift_card|
-            gift_card.user&.prefixed_id
+            gift_card.customer&.prefixed_id
           end
 
           attribute :created_by_id do |gift_card|
@@ -29,8 +29,7 @@ module Spree
           # Customer the card was issued to. Gated behind `expand?` to keep
           # the list payload thin — the SPA's list view passes
           # `expand=customer,created_by` to populate the row chips.
-          one :user,
-              key: :customer,
+          one :customer,
               resource: proc { Spree.api.admin_customer_serializer },
               if: proc { expand?('customer') }
 

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

@@ -5,7 +5,8 @@ module Spree
         # Admin API serializer for {Spree::Import} — drives the SPA import
         # wizard: mapping payload while `mapping`, poll counters afterwards.
         class ImportSerializer < V3::ImportSerializer
-          typelize completed_rows_count: :number,
+          typelize seller_name: [:string, nullable: true],
+                   completed_rows_count: :number,
                    failed_rows_count: :number,
                    processing_errors: [:string, nullable: true],
                    preferred_delimiter: :string,
@@ -14,10 +15,22 @@ module Spree
                    sample_row: 'Record<string, string | null>',
                    original_filename: [:string, nullable: true],
                    original_byte_size: [:number, nullable: true],
-                   original_file_url: [:string, nullable: true]
+                   original_file_url: [:string, nullable: true],
+                   price_list_id: [:string, nullable: true]
 
           attributes :processing_errors, :preferred_delimiter
 
+          # The list a price-list import writes into; nil for every other type.
+          attribute :price_list_id do |import|
+            import.try(:price_list_prefixed_id)
+          end
+
+          # Who ran it, for the operator's list — `seller_id` is on the base,
+          # and the name rides along so the column needs no second request.
+          attribute :seller_name do |import|
+            import.seller&.name
+          end
+
           # The originally uploaded file — the audit trail. `original_file_url`
           # is our own streaming endpoint (JWT-authenticated), not a signed
           # ActiveStorage URL; see ExportSerializer#download_url.

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

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only — credentials never have a storefront surface. Secrets
+        # are `:password` preferences, masked by `serialized_preferences`.
+        class IntegrationSerializer < V3::BaseSerializer
+          typelize type: [:string, comment: 'Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none.'],
+                   name: :string,
+                   group: [:string, nullable: true],
+                   active: :boolean,
+                   preferences: 'Record<string, unknown>',
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
+
+          attributes :name, :active,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :type do |integration|
+            integration.class.api_type
+          end
+
+          attribute :group do |integration|
+            integration.class.integration_group
+          end
+
+          attribute :preferences, &:serialized_preferences
+          attribute :preference_schema, &:serialized_preference_schema
+        end
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module Spree
         # email-only — the full polymorphic identities aren't useful to the UI.
         class InvitationSerializer < V3::BaseSerializer
           typelize email: :string,
-                   status: :string,
+                   status: [:string, enum: Spree::Invitation.statuses, enum_type_name: 'InvitationStatus'],
                    role_id: :string,
                    role_name: :string,
                    inviter_email: :string,
@@ -34,10 +34,10 @@ module Spree
             invitation.inviter.email
           end
 
-          # Absolute URL when `Spree::Config[:admin_url]` is set, otherwise
-          # the path so the SPA can prepend `window.location.origin`.
+          # Absolute URL when a dashboard origin is configured, otherwise the
+          # path so the SPA can prepend `window.location.origin`.
           attribute :acceptance_url do |invitation|
-            if Spree::Config[:admin_url].present?
+            if Spree::Config[:dashboard_url].present?
               Rails.application.routes.url_helpers.admin_invitation_acceptance_url(invitation)
             else
               "/accept-invitation/#{invitation.prefixed_id}?token=#{invitation.token}"

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

@@ -18,11 +18,21 @@ module Spree
 
           typelize metadata: 'Record<string, unknown>',
                    cost_price: [:string, nullable: true],
-                   tax_category_id: [:string, nullable: true]
+                   tax_category_id: [:string, nullable: true],
+                   price_source: [:string, nullable: true],
+                   catalog_price: [:string, nullable: true]
 
-          attributes :metadata,
+          # price_source is operational provenance — admin-only, never on the
+          # store serializer.
+          attributes :metadata, :price_source,
                      created_at: :iso8601, updated_at: :iso8601
 
+          # Base price, not resolved: resolving would call the pricing provider
+          # once per line on a read path that must stay provider-free.
+          attribute :catalog_price do |line_item|
+            line_item.variant&.amount_in(line_item.currency)&.to_s
+          end
+
           attribute :cost_price do |line_item|
             line_item.cost_price&.to_s
           end
@@ -34,6 +44,13 @@ module Spree
           # Override inherited associations to use admin serializers
           many :option_values, resource: proc { Spree.api.admin_option_value_serializer }
           many :digital_links, resource: proc { Spree.api.admin_digital_link_serializer }
+          many :tax_lines, resource: proc { Spree.api.admin_tax_line_serializer }, if: proc { expand?('tax_lines') }
+
+          # `seller_id` comes from the store serializer; the expand resolves
+          # to the operator's view of the seller rather than the public one.
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') }
 
           one :variant,
               resource: proc { Spree.api.admin_variant_serializer },
@@ -43,9 +60,6 @@ module Spree
               resource: proc { Spree.api.admin_tax_category_serializer },
               if: proc { expand?('tax_category') }
 
-          many :adjustments,
-               resource: proc { Spree.api.admin_adjustment_serializer },
-               if: proc { expand?('adjustments') }
         end
       end
     end

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

@@ -3,7 +3,11 @@ module Spree
     module V3
       module Admin
         class MarketSerializer < V3::MarketSerializer
-          attributes created_at: :iso8601, updated_at: :iso8601
+          typelize tax_provider: [:string, nullable: true]
+
+          # Which tax engine computes for this market. Nil means the store-wide
+          # default; the selectable values come from /admin/tax_providers.
+          attributes :tax_provider, created_at: :iso8601, updated_at: :iso8601
 
           many :countries,
                resource: proc { Spree.api.admin_country_serializer },

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

@@ -3,12 +3,60 @@ module Spree
     module V3
       module Admin
         class MediaSerializer < V3::MediaSerializer
-          typelize viewable_type: :string, viewable_id: :string,
+          include Concerns::ExternalReferencesAttribute
+
+          # Both are null for a library file that has not been placed yet.
+          typelize viewable_type: [:string, nullable: true],
+                   viewable_id: [:string, nullable: true],
                    metadata: 'Record<string, unknown>',
-                   download_url: [:string, nullable: true]
+                   download_url: [:string, nullable: true],
+                   embed_url: [:string, nullable: true],
+                   filename: [:string, nullable: true],
+                   content_type: [:string, nullable: true],
+                   byte_size: [:number, nullable: true],
+                   signed_id: [:string, nullable: true],
+                   attached: :boolean
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
+          # Whether this file is placed on a product, or sitting in the library
+          # waiting to be used.
+          attribute :attached do |asset|
+            asset.viewable_id.present?
+          end
+
+          # File facts the library grid and detail panel show. Read from the
+          # blob rather than the legacy attachment_* columns, which are only
+          # populated on pre-6.0 rows.
+          attribute :filename do |asset|
+            asset.attachment_blob&.filename&.to_s
+          end
+
+          attribute :content_type do |asset|
+            asset.attachment_blob&.content_type
+          end
+
+          attribute :byte_size do |asset|
+            asset.attachment_blob&.byte_size
+          end
+
+          # The rendition rich text embeds point at: bounded to a sane width,
+          # never cropped, so a size chart or diagram keeps its proportions.
+          attribute :embed_url do |asset|
+            next nil unless asset.image? && asset.attachment.attached?
+
+            Rails.application.routes.url_helpers.cdn_image_url(asset.attachment.variant(:embed))
+          end
+
+          # The file's own signed id, which is what a plain attachment field
+          # (a category image, a store logo) accepts on write. Handing it over
+          # lets those fields adopt a library file, sharing the blob instead of
+          # uploading a second copy — the same economics as placing media on a
+          # product, through endpoints that need no change.
+          attribute :signed_id do |asset|
+            asset.attachment_blob&.signed_id
+          end
+
           attribute :viewable_id do |asset|
             asset.viewable&.prefixed_id
           end

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A product as a curating parent's membership card reads it: the row's
+        # name and thumbnail, and nothing else.
+        #
+        # Deliberately not a subclass of the admin product serializer. These
+        # endpoints feed one card and the picker's exclusion list, neither of
+        # which reads a product's status, media, categories, publications,
+        # channels or custom fields — and the pages render a variant row per
+        # product, so a full product payload per row is the difference between
+        # a card that opens and one that crawls. A field a card starts needing
+        # is one line in the subclass that needs it
+        # (docs/plans/6.0-volume-pricing.md).
+        class MembershipProductSerializer < V3::BaseSerializer
+          typelize name: :string, thumbnail_url: [:string, nullable: true]
+
+          attributes :name
+
+          # The card's row image.
+          attribute :thumbnail_url do |product|
+            image_url_for(product.primary_media)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: reasons are back-office vocabulary and have no Store API
+        # controller, so there is no store serializer to extend.
+        #
+        # The reason serializers are deliberately parallel rather than sharing
+        # a base class: Typelizer emits one TS type per serializer, so a shared
+        # parent would publish an abstract `Reason` type into the admin SDK
+        # that no endpoint returns.
+        class OrderCancellationReasonSerializer < V3::BaseSerializer
+          typelize name: :string, active: :boolean, can_be_deleted: :boolean
+
+          attributes :name, :active,
+                     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/order_group_serializer.rb

@@ -0,0 +1,50 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::OrderGroup for the back office — the checkout that
+        # produced several orders, and what ties them together.
+        #
+        # Extends the store serializer, so what a customer sees stays in one
+        # place and this adds only what an operator needs on top: the payment
+        # shares, and the timestamps every admin surface carries.
+        class OrderGroupSerializer < V3::OrderGroupSerializer
+          typelize customer_id: 'string | null',
+                   cart_id: 'string | null',
+                   seller_count: :number,
+                   includes_first_party: :boolean,
+                   created_at: :string, updated_at: :string
+
+          attribute :customer_id do |group|
+            group.customer&.prefixed_id
+          end
+
+          attribute :cart_id do |group|
+            Spree::Cart.prefixed_id_for(group.cart_id)
+          end
+
+          # How many sellers this checkout reached — the operator's headline
+          # question about a group, and cheaper than counting the orders client
+          # side once a group is large.
+          attribute :seller_count do |group|
+            group.seller_count
+          end
+
+          attribute :includes_first_party do |group|
+            group.includes_first_party?
+          end
+
+          attributes :created_at, :updated_at
+
+          # Re-declared against the admin serializers. Inheriting the store
+          # ones would render a customer-facing record inside a back-office
+          # response, which is the one thing an admin serializer must never do.
+          one :billing_address, resource: proc { Spree.api.admin_address_serializer }
+          one :shipping_address, resource: proc { Spree.api.admin_address_serializer }
+          many :orders, resource: proc { Spree.api.admin_order_serializer }
+          many :payments, resource: proc { Spree.api.admin_payment_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -8,14 +8,12 @@ module Spree
         # per-channel routing-rules editor. Same shape as PromotionRule so the
         # frontend renders both with the same schema-driven preference form.
         class OrderRoutingRuleSerializer < BaseSerializer
-          typelize type: :string,
+          typelize type: [:string, comment: 'Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more.'],
                    channel_id: :string,
                    position: :number,
                    active: :boolean,
                    preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown }>",
-                   label: :string,
-                   description: :string
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
 
           attributes :position, :active
           attributes created_at: :iso8601, updated_at: :iso8601
@@ -31,8 +29,6 @@ module Spree
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema
 
-          attribute :label, &:human_name
-          attribute :description, &:human_description
         end
       end
     end