spree_api 6.0.0.beta3 → 6.0.0.rc1

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

@@ -9,21 +9,13 @@ module Spree
 
         attributes :status, :external_id, :external_client_secret, :external_data
 
-        attribute :payment_method_id do |session|
-          session.payment_method&.prefixed_id
-        end
-
-        attribute :payment_source_id do |session|
-          session.payment_source&.prefixed_id
-        end
+        prefixed_id_attributes :payment_method, :payment_source
 
         attribute :payment_source_type do |session|
-          session.payment_source_type
+          Spree::Base.polymorphic_api_type(session.payment_source_type)
         end
 
-        attribute :customer_id do |session|
-          session.customer&.prefixed_id
-        end
+        prefixed_id_attributes :customer
 
         one :payment_method, resource: proc { Spree.api.payment_method_serializer }
       end

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

@@ -11,9 +11,7 @@ module Spree
           Spree::RichTextHelper.to_plain_text(policy.body)
         end
 
-        attribute :body_html do |policy|
-          policy.body_html
-        end
+        attributes :body_html
 
         # The one timestamp a store serializer carries. When a legal document
         # last changed is what a shopper is entitled to see on the page —

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

@@ -12,9 +12,7 @@ module Spree
 
         attributes :amount, :amount_in_cents, :currency
 
-        attribute :display_amount do |price_history|
-          price_history.display_amount
-        end
+        attributes :display_amount
 
         attribute :recorded_at do |price_history|
           price_history.recorded_at&.iso8601

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

@@ -25,9 +25,7 @@ module Spree
           price.display_compare_at_amount&.to_s
         end
 
-        attribute :price_list_id do |price|
-          price.price_list&.prefixed_id
-        end
+        prefixed_id_attributes :price_list
       end
     end
   end

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

@@ -9,13 +9,7 @@ module Spree
 
         attributes published_at: :iso8601, unpublished_at: :iso8601
 
-        attribute :product_id do |publication|
-          publication.product&.prefixed_id
-        end
-
-        attribute :channel_id do |publication|
-          publication.channel&.prefixed_id
-        end
+        prefixed_id_attributes :product, :channel
       end
     end
   end

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

@@ -24,27 +24,17 @@ module Spree
                    :variant_count,
                    available_on: :iso8601, preorder_ships_at: :iso8601
 
-        attribute :purchasable do |product|
-          product.purchasable?
-        end
+        attribute :purchasable, &:purchasable?
 
         # True when this product is currently offered as a pre-order on the
         # requesting channel.
-        attribute :preorder do |product|
-          product.preorder?
-        end
+        attribute :preorder, &:preorder?
 
-        attribute :in_stock do |product|
-          product.in_stock?
-        end
+        attribute :in_stock, &:in_stock?
 
-        attribute :backorderable do |product|
-          product.backorderable?
-        end
+        attribute :backorderable, &:backorderable?
 
-        attribute :available do |product|
-          product.available?
-        end
+        attribute :available, &:available?
 
         attribute :description do |product|
           next if product.description.blank?
@@ -60,9 +50,7 @@ module Spree
         # buy-box winner: that moves with price and stock, and a client that
         # cached or linked this id must not find it pointing at a different
         # row tomorrow. On a single-seller catalog the two coincide anyway.
-        attribute :default_variant_id do |product|
-          product.default_variant&.prefixed_id
-        end
+        prefixed_id_attributes :default_variant
 
         # The offer a storefront should lead with when several sellers share
         # the listing — the buy-box winner in the request's currency. Nil when
@@ -109,9 +97,7 @@ module Spree
         # Nil on the marketplace's own first-party products. The id is always
         # present so a storefront can group or link by seller without paying
         # for the expand; `?expand=seller` adds the public profile.
-        attribute :seller_id do |product|
-          product.seller&.prefixed_id
-        end
+        prefixed_id_attributes :seller
 
         # Conditional associations
         one :seller,

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      # The marketplace's answer on a listing, as the seller sees it and as
+      # the `product_submission.*` webhook events carry it.
+      #
+      # The reviewer's identity is deliberately absent: a seller needs to
+      # know what to change, not which member of the marketplace's staff
+      # decided (docs/plans/6.0-seller-product-submission.md).
+      class ProductSubmissionSerializer < BaseSerializer
+        typelize status: [:string, enum: Spree::ProductSubmission.statuses, enum_type_name: 'ProductSubmissionStatus'],
+                 product_id: :string,
+                 review_note: [:string, nullable: true],
+                 reviewed_at: [:string, nullable: true]
+
+        attributes :status, :review_note,
+                   reviewed_at: :iso8601,
+                   created_at: :iso8601
+
+        # A subscriber holding only the submission id would otherwise have to
+        # fetch the row back to learn which product was decided on.
+        prefixed_id_attributes :product
+      end
+    end
+  end
+end

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

@@ -14,22 +14,14 @@ module Spree
           refund.amount&.to_s
         end
 
-        attribute :payment_id do |refund|
-          refund.payment&.prefixed_id
-        end
-
-        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
       end
     end

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

@@ -9,31 +9,24 @@ module Spree
                  resellable: :boolean,
                  pre_tax_amount: :string,
                  display_pre_tax_amount: :string,
+                 included_tax_total: :string,
+                 additional_tax_total: :string,
+                 tax_total: :string,
+                 display_tax_total: :string,
+                 refund_amount: :string,
+                 display_refund_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
+        attributes pre_tax_amount: :string, display_pre_tax_amount: :string, included_tax_total: :string,
+                   additional_tax_total: :string, tax_total: :string, display_tax_total: :string
+        # What the line refunds, tax included — for the units that arrived
+        # once the warehouse has counted.
+        attributes refund_amount: :string, display_refund_amount: :string
+        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

@@ -12,6 +12,8 @@ module Spree
                  reason_id: [:string, nullable: true],
                  refund_total: :string,
                  display_refund_total: :string,
+                 refund_tax_total: :string,
+                 display_refund_tax_total: :string,
                  approved_at: [:string, nullable: true],
                  received_at: [:string, nullable: true],
                  refunded_at: [:string, nullable: true],
@@ -19,22 +21,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
-
-        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
+        prefixed_id_attributes :order, :reason
 
+        attributes refund_total: :string, display_refund_total: :string
+        # The tax inside refund_total.
+        attributes refund_tax_total: :string, display_refund_tax_total: :string
         attribute :approved_at do |return_record|
           return_record.approved_at&.iso8601
         end

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/delivery_method_serializer.rb

@@ -37,13 +37,7 @@ 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
+          prefixed_id_attributes :delivery_profile, :delivery_zone
 
           attribute :calculator_type do |record|
             record.calculator&.class&.api_type

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

@@ -21,13 +21,7 @@ module Spree
           attributes :name, :selected, :cost, :total,
                      :carrier, :service_level, :estimated_delivery_date
 
-          attribute :display_cost do |delivery_rate|
-            delivery_rate.display_cost.to_s
-          end
-
-          attribute :display_total do |delivery_rate|
-            delivery_rate.display_total.to_s
-          end
+          attributes display_cost: :string, display_total: :string
         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_serializer.rb

@@ -14,9 +14,7 @@ module Spree
 
           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/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/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/order_line_item_serializer.rb

@@ -11,23 +11,17 @@ 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, 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, :display_price, :discounted_amount, :display_discounted_amount,
+                           :additional_tax_total, :total, :display_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|

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

@@ -21,34 +21,13 @@ module Spree
         # the one contact detail that lets a marketplace's customer be taken
         # off it, and it is not needed to pack, post or invoice.
         class OrderSerializer < V3::BaseSerializer
-          typelize number: :string,
-                   customer_note: [:string, nullable: true],
-                   currency: :string,
+          typelize number: :string, customer_note: [:string, nullable: true], currency: :string,
                    total_quantity: :number,
                    fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
                    payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
-                   status: [:string, enum: Spree::Order::STATUSES],
-                   item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
-                   delivery_total: [:string, nullable: true], display_delivery_total: [:string, nullable: true],
-                   discount_total: [:string, nullable: true], display_discount_total: [:string, nullable: true],
-                   adjustment_total: [:string, nullable: true], display_adjustment_total: [:string, nullable: true],
-                   included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
-                   additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
-                   tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
-                   total: [:string, nullable: true], display_total: [:string, nullable: true],
-                   payment_total: [:string, nullable: true], display_payment_total: [:string, nullable: true],
-                   amount_due: [:string, nullable: true], display_amount_due: [:string, nullable: true],
-                   commission_amount_total: [:string, nullable: true],
-                   display_commission_amount_total: [:string, nullable: true],
-                   commission_tax_total: [:string, nullable: true],
-                   display_commission_tax_total: [:string, nullable: true],
-                   commission_total: [:string, nullable: true],
-                   display_commission_total: [:string, nullable: true],
-                   canceled_at: [:string, nullable: true],
-                   cancel_reason_name: [:string, nullable: true],
-                   cancel_note: [:string, nullable: true],
-                   internal_note: [:string, nullable: true],
-                   internal_note_html: [:string, nullable: true]
+                   status: [:string, enum: Spree::Order::STATUSES], canceled_at: [:string, nullable: true],
+                   cancel_reason_name: [:string, nullable: true], cancel_note: [:string, nullable: true],
+                   internal_note: [:string, nullable: true], internal_note_html: [:string, nullable: true]
 
           attributes :number, :customer_note, :currency, :total_quantity,
                      :status, :fulfillment_status, :payment_status,

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

@@ -6,7 +6,7 @@ module Spree
         class PayoutSerializer < V3::BaseSerializer
           typelize status: :string,
                    currency: :string,
-                   provider: :string,
+                   provider: [:string, comment: 'Payout provider. Built-in: system. Provider gems register more (e.g. stripe).'],
                    amount: :string,
                    display_amount: :string,
                    reference: 'string | null',
@@ -14,7 +14,7 @@ module Spree
                    period_end: 'string | null',
                    transfers_count: :number
 
-          attributes :status, :currency, :provider, :reference,
+          attributes :status, :currency, :reference,
                      period_start: :iso8601, period_end: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
@@ -29,6 +29,8 @@ module Spree
 
             counts ? counts.fetch(payout.id, 0) : payout.transfers.count
           end
+
+          api_type_attributes :provider
         end
       end
     end

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

@@ -20,13 +20,7 @@ module Spree
 
           attributes :status, :metadata, created_at: :iso8601, updated_at: :iso8601
 
-          attribute :product_type_id do |product|
-            product.product_type&.prefixed_id
-          end
-
-          attribute :delivery_profile_id do |product|
-            product.delivery_profile&.prefixed_id
-          end
+          prefixed_id_attributes :product_type, :delivery_profile
 
           many :variants,
                resource: proc { Spree.api.seller_variant_serializer },

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

@@ -2,27 +2,7 @@ module Spree
   module Api
     module V3
       module Seller
-        # The marketplace's answer on a listing, as the seller sees it.
-        #
-        # The reviewer's identity is deliberately absent: a seller needs to
-        # know what to change, not which member of the marketplace's staff
-        # decided (docs/plans/6.0-seller-product-submission.md).
-        class ProductSubmissionSerializer < BaseSerializer
-          typelize status: [:string, enum: Spree::ProductSubmission.statuses, enum_type_name: 'ProductSubmissionStatus'],
-                   product_id: :string,
-                   review_note: [:string, nullable: true],
-                   reviewed_at: [:string, nullable: true]
-
-          attributes :status, :review_note,
-                     reviewed_at: :iso8601,
-                     created_at: :iso8601
-
-          # Carried for the event payload, which is this serializer's other
-          # job: a subscriber holding only the submission id would have to
-          # fetch the row back to learn which product was decided on.
-          attribute :product_id do |submission|
-            submission.product&.prefixed_id
-          end
+        class ProductSubmissionSerializer < V3::ProductSubmissionSerializer
         end
       end
     end

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

@@ -40,13 +40,9 @@ module Spree
                resource: proc { Spree.api.seller_policy_serializer },
                if: proc { expand?('policies') }
 
-          attribute :on_holiday do |seller|
-            seller.on_holiday?
-          end
+          attribute :on_holiday, &:on_holiday?
 
-          attribute :sellable do |seller|
-            seller.sellable?
-          end
+          attribute :sellable, &:sellable?
 
           # What this seller prices in. Theirs by way of the marketplace: a
           # seller has no currency of their own, so the store's is the answer

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

@@ -18,9 +18,7 @@ module Spree
 
           attributes :id, :kind, :name, :description, :required, :position, :status, :action_url, :blocker
 
-          attribute :blocking do |status|
-            status.blocking?
-          end
+          attribute :blocking, &:blocking?
 
           attribute :accepts_submissions do |status|
             status.requirement.class.accepts_submissions?
@@ -36,15 +34,11 @@ module Spree
 
           # The document this line asks for, so the panel can offer to create
           # exactly that policy. Null for every other kind.
-          attribute :required_policy_name do |status|
-            status.required_policy_name
-          end
+          attributes :required_policy_name
 
           # The marketplace terms this line asks the seller to accept. Null
           # for every other kind, and null while nothing has been written.
-          attribute :terms_html do |status|
-            status.terms_html
-          end
+          attributes :terms_html
 
           one :submission,
               resource: proc { Spree.api.seller_requirement_submission_serializer },