spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -1,10 +1,29 @@
 module Spree
   module Api
     module V3
-      # Payload of the purchase_order.* events. Purchase orders have no
-      # storefront serializer, so the event shape is declared here rather than
-      # found by convention.
-      class PurchaseOrderEventSerializer < Admin::PurchaseOrderSerializer
+      # Payload of the purchase_order.* events. What was bought and what it
+      # costs stay behind the Admin API: an integration reads them there with
+      # a key scoped to purchasing.
+      class PurchaseOrderEventSerializer < BaseSerializer
+        typelize number: :string,
+                 status: :string,
+                 supplier_id: [:string, nullable: true],
+                 destination_location_id: [:string, nullable: true],
+                 ordered_at: [:string, nullable: true],
+                 received_at: [:string, nullable: true],
+                 closed_short_at: [:string, nullable: true]
+
+        attributes :number, :status,
+                   ordered_at: :iso8601, received_at: :iso8601, closed_short_at: :iso8601,
+                   created_at: :iso8601, updated_at: :iso8601
+
+        attribute :supplier_id do |purchase_order|
+          purchase_order.supplier&.prefixed_id
+        end
+
+        attribute :destination_location_id do |purchase_order|
+          purchase_order.destination_location&.prefixed_id
+        end
       end
     end
   end

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

@@ -4,33 +4,28 @@ module Spree
   module Api
     module V3
       class RefundSerializer < BaseSerializer
-        typelize amount: [:string, nullable: true], transaction_id: [:string, nullable: true],
+        typelize transaction_id: [:string, nullable: true],
                  payment_id: [:string, nullable: true], refund_reason_id: [:string, nullable: true],
-                 originator_id: [:string, nullable: true], originator_type: [:string, nullable: true]
+                 originator_id: [:string, nullable: true], originator_type: [:string, nullable: true],
+                 reimbursement_id: [:string, nullable: true, deprecated: 'Always null: reimbursements are gone. Use `originator_id`. Removed in 6.1.']
 
         attributes :transaction_id
 
-        attribute :amount do |refund|
-          refund.amount&.to_s
-        end
-
-        attribute :payment_id do |refund|
-          refund.payment&.prefixed_id
-        end
+        money_attributes :amount
 
-        attribute :refund_reason_id do |refund|
-          refund.reason&.prefixed_id
-        end
+        prefixed_id_attributes :payment, refund_reason_id: :reason
 
         # What triggered this refund — a Return, Exchange or Claim; nil for a
         # manual refund.
-        attribute :originator_id do |refund|
-          refund.originator&.prefixed_id
-        end
+        prefixed_id_attributes :originator
 
         attribute :originator_type do |refund|
-          refund.originator_type
+          Spree::Base.polymorphic_api_type(refund.originator_type)
         end
+
+        # @deprecated Reimbursements were folded into returns, which a refund
+        #   names as its +originator+. Removed in 6.1.
+        attribute(:reimbursement_id) { nil }
       end
     end
   end

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

@@ -7,33 +7,18 @@ module Spree
         typelize quantity: :number,
                  received_quantity: :number,
                  resellable: :boolean,
-                 pre_tax_amount: :string,
-                 display_pre_tax_amount: :string,
                  variant_id: [:string, nullable: true],
                  line_item_id: [:string, nullable: true],
                  fulfillment_item_id: [:string, nullable: true]
 
         attributes :quantity, :received_quantity, :resellable
 
-        attribute :pre_tax_amount do |line|
-          line.pre_tax_amount.to_s
-        end
-
-        attribute :display_pre_tax_amount do |line|
-          line.display_pre_tax_amount.to_s
-        end
-
-        attribute :variant_id do |line|
-          line.variant&.prefixed_id
-        end
-
-        attribute :line_item_id do |line|
-          line.line_item&.prefixed_id
-        end
-
-        attribute :fulfillment_item_id do |line|
-          line.fulfillment_item&.prefixed_id
-        end
+        money_attributes :pre_tax_amount, :display_pre_tax_amount, :included_tax_total,
+                         :additional_tax_total, :tax_total, :display_tax_total
+        # What the line refunds, tax included — for the units that arrived
+        # once the warehouse has counted.
+        money_attributes :refund_amount, :display_refund_amount
+        prefixed_id_attributes :variant, :line_item, :fulfillment_item
 
         one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
       end

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

@@ -10,8 +10,6 @@ module Spree
                  status: [:string, enum: Spree::Return.statuses, enum_type_name: 'ReturnStatus'],
                  order_id: [:string, nullable: true],
                  reason_id: [:string, nullable: true],
-                 refund_total: :string,
-                 display_refund_total: :string,
                  approved_at: [:string, nullable: true],
                  received_at: [:string, nullable: true],
                  refunded_at: [:string, nullable: true],
@@ -19,21 +17,11 @@ module Spree
 
         attributes :number, :status
 
-        attribute :order_id do |return_record|
-          return_record.order&.prefixed_id
-        end
-
-        attribute :reason_id do |return_record|
-          return_record.reason&.prefixed_id
-        end
+        prefixed_id_attributes :order, :reason
 
-        attribute :refund_total do |return_record|
-          return_record.refund_total.to_s
-        end
-
-        attribute :display_refund_total do |return_record|
-          return_record.display_refund_total.to_s
-        end
+        money_attributes :refund_total, :display_refund_total
+        # The tax inside refund_total.
+        money_attributes :refund_tax_total, :display_refund_tax_total
 
         attribute :approved_at do |return_record|
           return_record.approved_at&.iso8601

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

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      # The event shape for `saved_report.*`: the saved query and who owns it,
+      # without the author's name or email, which webhook payloads never carry.
+      class SavedReportEventSerializer < BaseSerializer
+        typelize name: :string,
+                 description: [:string, nullable: true],
+                 query: 'Record<string, unknown>',
+                 seeded: :boolean,
+                 user_id: [:string, nullable: true],
+                 created_at: :string,
+                 updated_at: :string
+
+        attributes :name, :description, :query, :seeded, :created_at, :updated_at
+
+        attribute :user_id do |report|
+          report.user&.prefixed_id
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/address_serializer.rb

@@ -0,0 +1,12 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class AddressSerializer < V3::AddressSerializer
+          # The Store API keeps these deprecated names until 6.1.
+          %i[state_abbr country_iso].each { |key| _attributes.delete(key) }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/balance_serializer.rb

@@ -6,14 +6,14 @@ module Spree
         #
         # A computed value rather than a record, so it carries no id.
         class BalanceSerializer < V3::BaseSerializer
-          typelize currency: :string,
-                   settlement_currency: :string,
+          typelize currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
+                   settlement_currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
                    converted: :boolean,
-                   earned: :string, display_earned: :string,
-                   payable: :string, display_payable: :string,
-                   paid: :string, display_paid: :string,
-                   balance: :string, display_balance: :string,
-                   pending: :string, display_pending: :string
+                   earned: :string,
+                   payable: :string,
+                   paid: :string,
+                   balance: :string,
+                   pending: :string
 
           _attributes.delete(:id)
 
@@ -24,9 +24,14 @@ module Spree
 
           attribute(:converted) { |balance| balance.converted? }
 
-          %i[earned payable paid balance pending].each do |figure|
-            attribute(figure) { |balance| balance.public_send(figure).to_s }
-            attribute(:"display_#{figure}") { |balance| balance.public_send(:"display_#{figure}").to_s }
+          # Earnings are in the currency the sales were priced in; what the
+          # account holds is in the one it settles in.
+          %i[earned pending].each do |figure|
+            attribute(figure) { |balance| Spree::Money::Rounding.format(balance.public_send(figure), balance.currency) }
+          end
+
+          %i[payable paid balance].each do |figure|
+            attribute(figure) { |balance| Spree::Money::Rounding.format(balance.public_send(figure), balance.settlement_currency) }
           end
         end
       end

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

@@ -7,6 +7,13 @@ module Spree
         # One line of a claim — what went wrong, and what is being sent or
         # refunded to put it right.
         class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+          without_formatted_money(:seller)
+
+          # No guest price gating here, so the inherited money fields are always present.
+          typelize refund_amount: [:string, nullable: false], paid_amount: [:string, nullable: false],
+                   pre_tax_amount: [:string, nullable: false], included_tax_total: [:string, nullable: false],
+                   additional_tax_total: [:string, nullable: false], tax_total: [:string, nullable: false]
+
           typelize name: [:string, nullable: true]
 
           attribute :name do |line|

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

@@ -9,6 +9,11 @@ module Spree
         # Built on the shared V3 serializer rather than the admin one, which
         # expands the order and the customer behind it.
         class ClaimSerializer < V3::ClaimSerializer
+          without_formatted_money(:seller)
+
+          # No guest price gating here, so the inherited money fields are always present.
+          typelize refund_total: [:string, nullable: false]
+
           typelize memo: [:string, nullable: true]
 
           attributes :memo

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

@@ -0,0 +1,19 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A country as the seller panel's address forms need it. The panel
+        # names countries with Intl.DisplayNames in the seller's own language,
+        # so the Seller API sends the ISO code alone.
+        class CountrySerializer < V3::CountrySerializer
+          _attributes.delete(:name)
+          _attributes.delete(:market)
+
+          many :states,
+               resource: proc { Spree.api.seller_state_serializer },
+               if: proc { params[:expand]&.include?('states') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/delivery_method_rule_serializer.rb

@@ -12,8 +12,7 @@ module Spree
         class DeliveryMethodRuleSerializer < BaseSerializer
           typelize type: [:string, comment: 'Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more.'],
                    active: :boolean,
-                   preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
+                   preferences: 'Record<string, unknown>'
 
           attributes :active
 
@@ -24,7 +23,6 @@ module Spree
           end
 
           attribute :preferences, &:serialized_preferences
-          attribute :preference_schema, &:serialized_preference_schema
         end
       end
     end

data/app/serializers/spree/api/v3/seller/delivery_method_serializer.rb

@@ -22,8 +22,7 @@ module Spree
                    editable: :boolean,
                    delivery_profile_id: [:string, nullable: true],
                    delivery_zone_id: [:string, nullable: true],
-                   calculator_type: [:string, nullable: true],
-                   calculator_preferences: ['Record<string, unknown>', nullable: true]
+                   calculator: 'TypedDeliveryCalculator | null'
 
           attributes :admin_name, :storefront_visible, :tracking_url,
                      created_at: :iso8601, updated_at: :iso8601
@@ -37,20 +36,11 @@ module Spree
             record.seller_id.present?
           end
 
-          attribute :delivery_profile_id do |record|
-            record.delivery_profile&.prefixed_id
-          end
-
-          attribute :delivery_zone_id do |record|
-            record.delivery_zone&.prefixed_id
-          end
-
-          attribute :calculator_type do |record|
-            record.calculator&.class&.api_type
-          end
+          prefixed_id_attributes :delivery_profile, :delivery_zone
 
-          attribute :calculator_preferences do |record|
-            record.calculator.respond_to?(:serialized_preferences) ? record.calculator.serialized_preferences : record.calculator&.preferences
+          attribute :calculator do |record|
+            calculator = record.calculator
+            { type: calculator.class.api_type, preferences: calculator.serialized_preferences } if calculator
           end
         end
       end

data/app/serializers/spree/api/v3/seller/delivery_rate_serializer.rb

@@ -10,24 +10,19 @@ module Spree
         class DeliveryRateSerializer < V3::BaseSerializer
           typelize name: :string,
                    selected: :boolean,
-                   cost: :string,
-                   display_cost: :string,
-                   total: :string,
-                   display_total: :string,
                    carrier: [:string, nullable: true],
                    service_level: [:string, nullable: true],
-                   estimated_delivery_date: [:string, nullable: true]
+                   estimated_delivery_date: [:string, nullable: true],
+                   unpriced: :boolean
 
-          attributes :name, :selected, :cost, :total,
-                     :carrier, :service_level, :estimated_delivery_date
+          attributes :name, :selected
 
-          attribute :display_cost do |delivery_rate|
-            delivery_rate.display_cost.to_s
-          end
+          money_attributes :cost, :total
 
-          attribute :display_total do |delivery_rate|
-            delivery_rate.display_total.to_s
-          end
+          attributes :carrier, :service_level, :estimated_delivery_date, :unpriced
+
+          typelize cost: [:string, nullable: false],
+                   total: [:string, nullable: false]
         end
       end
     end

data/app/serializers/spree/api/v3/seller/delivery_serializer.rb

@@ -7,9 +7,7 @@ module Spree
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
-          attribute :shipping_label_id do |delivery|
-            delivery.shipping_label&.prefixed_id
-          end
+          prefixed_id_attributes :shipping_label
         end
       end
     end

data/app/serializers/spree/api/v3/seller/delivery_zone_serializer.rb

@@ -16,9 +16,7 @@ module Spree
 
           # What the panel filters the picker by, so a zone is only offered
           # under the profile it belongs to.
-          attribute :delivery_profile_id do |record|
-            record.delivery_profile&.prefixed_id
-          end
+          prefixed_id_attributes :delivery_profile
         end
       end
     end

data/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb

@@ -7,6 +7,11 @@ module Spree
         # One line of an exchange — what came back and what goes out in its
         # place. Both variants expand through the seller's own serializer.
         class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+          # No guest price gating here, so the inherited money fields are always present.
+          typelize original_price: [:string, nullable: false], new_variant_price: [:string, nullable: false],
+                   price_difference: [:string, nullable: false], original_tax_total: [:string, nullable: false],
+                   new_tax_total: [:string, nullable: false]
+
           typelize name: [:string, nullable: true],
                    new_variant_name: [:string, nullable: true]
 

data/app/serializers/spree/api/v3/seller/exchange_serializer.rb

@@ -9,14 +9,17 @@ module Spree
         # Built on the shared V3 serializer rather than the admin one, which
         # expands the order and the customer behind it.
         class ExchangeSerializer < V3::ExchangeSerializer
+          without_formatted_money(:seller)
+
+          # No guest price gating here, so the inherited money fields are always present.
+          typelize price_difference: [:string, nullable: false]
+
           typelize memo: [:string, nullable: true],
                    stock_location_id: [:string, nullable: true]
 
           attributes :memo
 
-          attribute :stock_location_id do |exchange|
-            exchange.stock_location&.prefixed_id
-          end
+          prefixed_id_attributes :stock_location
 
           many :exchange_line_items,
                resource: proc { Spree.api.seller_exchange_line_item_serializer },

data/app/serializers/spree/api/v3/seller/file_upload_serializer.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class FileUploadSerializer < V3::FileUploadSerializer
+          one :upload_target, key: :upload, resource: proc { Spree.api.seller_file_upload_target_serializer }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/file_upload_target_serializer.rb

@@ -0,0 +1,10 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class FileUploadTargetSerializer < V3::FileUploadTargetSerializer
+        end
+      end
+    end
+  end
+end

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

@@ -17,13 +17,7 @@ module Spree
 
           attributes :quantity
 
-          attribute :line_item_id do |item|
-            item.line_item&.prefixed_id
-          end
-
-          attribute :variant_id do |item|
-            item.variant&.prefixed_id
-          end
+          prefixed_id_attributes :line_item, :variant
 
           attribute :name do |item|
             item.line_item&.name

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

@@ -47,9 +47,7 @@ module Spree
 
           # The id as well as the name, so a seller moving the parcel to
           # another of their shelves can see which one it is on now.
-          attribute :stock_location_id do |fulfillment|
-            fulfillment.stock_location&.prefixed_id
-          end
+          prefixed_id_attributes :stock_location
 
           # Deliberately not `items`: the store's fulfillment answers with a
           # manifest under that name, and the shared OpenAPI patch rewrites it
@@ -60,9 +58,7 @@ module Spree
 
           # The consignments and labels on this parcel — what a seller adds
           # when they ship it themselves.
-          attribute :selected_delivery_rate_id do |fulfillment|
-            fulfillment.selected_delivery_rate&.prefixed_id
-          end
+          prefixed_id_attributes :selected_delivery_rate
 
           # What this parcel could be carried by from where it currently sits.
           many :delivery_rates, resource: proc { Spree.api.seller_delivery_rate_serializer }

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

@@ -15,7 +15,7 @@ module Spree
           typelize completed_rows_count: :number,
                    failed_rows_count: :number,
                    processing_errors: [:string, nullable: true],
-                   preferred_delimiter: :string,
+                   delimiter: :string,
                    schema_fields: 'Array<{ name: string; label: string; required: boolean }>',
                    csv_headers: [:string, multi: true],
                    sample_row: 'Record<string, string | null>',
@@ -23,7 +23,7 @@ module Spree
                    original_byte_size: [:number, nullable: true],
                    original_file_url: [:string, nullable: true]
 
-          attributes :processing_errors, :preferred_delimiter
+          attributes :processing_errors, :delimiter
 
           # The file the seller uploaded. `original_file_url` is this branch's
           # own streaming endpoint (JWT-authenticated), not a signed

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

@@ -10,9 +10,7 @@ module Spree
           attributes :email,
                      created_at: :iso8601, expires_at: :iso8601, accepted_at: :iso8601
 
-          attribute :status do |invitation|
-            invitation.status.to_s
-          end
+          attributes status: :string
         end
       end
     end

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

@@ -9,12 +9,9 @@ module Spree
         # it is cropped, and which variants it belongs to.
         class MediaSerializer < V3::MediaSerializer
           typelize position: :number,
-                   variant_ids: [:string, multi: true],
-                   focal_point_x: [:number, nullable: true],
-                   focal_point_y: [:number, nullable: true]
+                   variant_ids: [:string, multi: true]
 
-          attributes :position, :focal_point_x, :focal_point_y,
-                     created_at: :iso8601, updated_at: :iso8601
+          attributes :position, created_at: :iso8601, updated_at: :iso8601
 
           attribute :variant_ids do |media|
             media.variants.map(&:prefixed_id)

data/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb

@@ -11,23 +11,18 @@ module Spree
         # packing a box, and each of which would pull another serializer into
         # this branch's generated types.
         class OrderLineItemSerializer < V3::BaseSerializer
-          typelize name: :string,
-                   sku: [:string, nullable: true],
-                   options_text: [:string, nullable: true],
-                   quantity: :number,
-                   currency: :string,
-                   variant_id: [:string, nullable: true],
-                   thumbnail_url: [:string, nullable: true],
-                   price: [:string, nullable: true], display_price: [:string, nullable: true],
-                   total: [:string, nullable: true], display_total: [:string, nullable: true]
+          typelize name: :string, sku: [:string, nullable: true], options_text: [:string, nullable: true],
+                   quantity: :number, currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'], variant_id: [:string, nullable: true],
+                   thumbnail_url: [:string, nullable: true]
 
           attributes :name, :options_text, :quantity, :currency
 
-          money_attributes :price, :display_price, :total, :display_total
+          # The tax charged on top is what a claim refunds beside the goods.
+          money_attributes :price, unit_price: true
+          money_attributes :discounted_amount,
+                           :additional_tax_total, :total
 
-          attribute :variant_id do |line_item|
-            line_item.variant&.prefixed_id
-          end
+          prefixed_id_attributes :variant
 
           # How a seller finds the item on their own shelf.
           attribute :sku do |line_item|