spree_api 5.6.1 → 6.0.0.beta2

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

@@ -5,10 +5,14 @@ module Spree
         typelize position: :number, alt: [:string, nullable: true],
                  product_id: [:string, nullable: true],
                  variant_ids: [:string, multi: true],
-                 media_type: :string,
+                 media_type: [:string, enum: Spree::Media::MEDIA_TYPES],
                  focal_point_x: [:number, nullable: true],
                  focal_point_y: [:number, nullable: true],
                  external_video_url: [:string, nullable: true],
+                 video_provider: [:string, nullable: true],
+                 video_embed_url: [:string, nullable: true],
+                 video_url: [:string, nullable: true],
+                 poster_url: [:string, nullable: true],
                  original_url: [:string, nullable: true], mini_url: [:string, nullable: true],
                  small_url: [:string, nullable: true], medium_url: [:string, nullable: true],
                  large_url: [:string, nullable: true], xlarge_url: [:string, nullable: true],
@@ -33,7 +37,36 @@ module Spree
         attributes :position, :alt, :media_type,
                    :focal_point_x, :focal_point_y, :external_video_url
 
+        # Spree parses the YouTube/Vimeo link once, here, so no storefront has
+        # to reimplement it. Nil on anything that isn't an external video.
+        attribute :video_provider do |asset|
+          asset.external_video&.provider
+        end
+
+        attribute :video_embed_url do |asset|
+          asset.external_video&.embed_url
+        end
+
+        # The uploaded video file itself. Served as-is — Spree does not
+        # transcode.
+        attribute :video_url do |asset|
+          next nil unless asset.video? && asset.attachment.attached?
+
+          url_helpers.cdn_image_url(asset.attachment)
+        end
+
+        # Still frame for a video tile: the merchant's upload when there is one,
+        # otherwise the provider's own thumbnail.
+        attribute :poster_url do |asset|
+          next nil unless asset.playable_video?
+
+          still_url(asset)
+        end
+
+        # Nil for video rows — there is no image to size.
         attribute :original_url do |asset|
+          next nil if asset.playable_video?
+
           image_url_for(asset)
         end
 
@@ -42,18 +75,26 @@ module Spree
         # (e.g., mini, small, medium, large, xlarge)
         Spree::Config.product_image_variant_sizes.each_key do |variant_name|
           attribute :"#{variant_name}_url" do |asset|
-            variant_url(asset, variant_name)
+            still_url(asset, variant_name)
           end
         end
 
         private
 
-        def variant_url(asset, variant_name)
-          return nil unless asset&.attachment&.attached?
+        # The row's still frame, sized when it's an attachment we control — an
+        # image's own file, or a video's poster, so a gallery that only knows
+        # how to draw an image still renders the right picture. A provider's
+        # thumbnail is served as-is: it isn't ours to resize, so every size
+        # resolves to the same URL.
+        def still_url(asset, variant_name = nil)
+          source = asset&.still_image
+          return asset&.provider_still_url if source.nil?
+
+          url_helpers.cdn_image_url(variant_name ? source.variant(variant_name) : source)
+        end
 
-          Rails.application.routes.url_helpers.cdn_image_url(
-            asset.attachment.variant(variant_name)
-          )
+        def url_helpers
+          Rails.application.routes.url_helpers
         end
       end
     end

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

@@ -19,7 +19,7 @@ module Spree
         end
 
         attribute :customer_id do |subscriber|
-          subscriber.user&.prefixed_id
+          subscriber.customer&.prefixed_id
         end
       end
     end

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

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class OptionTypeSerializer < BaseSerializer
-        typelize name: :string, label: :string, position: :number, kind: :string
+        typelize name: :string, label: :string, position: :number, kind: [:string, enum: Spree::OptionType::KINDS]
 
         attributes :name, :label, :position, :kind
       end

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

@@ -0,0 +1,60 @@
+module Spree
+  module Api
+    module V3
+      # Store API Order Group Serializer
+      #
+      # What the customer bought in one checkout, when it was fulfilled by more
+      # than one seller. They made one purchase and paid once, so this is what
+      # their order history shows them — with the per-seller orders nested
+      # inside it, each carrying its own items, delivery and tracking.
+      class OrderGroupSerializer < BaseSerializer
+        typelize number: :string, email: [:string, nullable: true], currency: :string,
+                 total: [:string, nullable: true], display_total: [:string, nullable: true],
+                 item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
+                 fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
+                 payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
+                 completed_at: [:string, nullable: true],
+                 billing_address: { nullable: true }, shipping_address: { nullable: true }
+
+        attributes :number, :email, :currency
+
+        attribute :total do |group|
+          group.total.to_s
+        end
+
+        attribute :display_total do |group|
+          group.display_total.to_s
+        end
+
+        attribute :item_total do |group|
+          group.item_total.to_s
+        end
+
+        attribute :display_item_total do |group|
+          group.display_item_total.to_s
+        end
+
+        # Rolled up across the children rather than stored, so it can never
+        # disagree with the orders it describes.
+        attribute :fulfillment_status do |group|
+          group.fulfillment_status
+        end
+
+        attribute :payment_status do |group|
+          group.payment_status
+        end
+
+        attribute :completed_at do |group|
+          group.created_at
+        end
+
+        one :billing_address, resource: proc { Spree.api.address_serializer }
+        one :shipping_address, resource: proc { Spree.api.address_serializer }
+
+        # The whole point of the group: the customer sees one purchase, and the
+        # seller orders inside it are how it will arrive.
+        many :orders, resource: proc { Spree.api.order_serializer }
+      end
+    end
+  end
+end

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

@@ -4,11 +4,18 @@ module Spree
       # Store API Order Serializer
       # Post-purchase order data (completed orders)
       class OrderSerializer < BaseSerializer
-        typelize number: :string, email: :string,
+        typelize cart_id: [:string, nullable: true],
+                 number: :string, email: :string,
                  customer_note: [:string, nullable: true],
                  market_id: [:string, nullable: true], channel_id: [:string, nullable: true],
+                 company_id: [:string, nullable: true], company_name: [:string, nullable: true],
+                 po_number: [:string, nullable: true],
+                 po_document_filename: [:string, nullable: true],
+                 po_document_byte_size: ['number | null'],
                  currency: :string, locale: [:string, nullable: true], total_quantity: :number,
-                 fulfillment_status: [:string, nullable: true], payment_status: [:string, nullable: true],
+                 coupon_code: [:string, nullable: true],
+                 fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
+                 payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
                  item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
                  delivery_total: [:string, nullable: true], display_delivery_total: [:string, nullable: true],
                  adjustment_total: [:string, nullable: true], display_adjustment_total: [:string, nullable: true],
@@ -16,12 +23,15 @@ module Spree
                  tax_total: [:string, nullable: true], display_tax_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],
+                 fee_total: [:string, nullable: true], display_fee_total: [:string, nullable: true],
                  store_credit_total: [:string, nullable: true], display_store_credit_total: [:string, nullable: true],
                  gift_card_total: [:string, nullable: true], display_gift_card_total: [:string, nullable: true],
                  covered_by_store_credit: :boolean,
                  total: [:string, nullable: true], display_total: [:string, nullable: true],
                  amount_due: [:string, nullable: true], display_amount_due: [:string, nullable: true],
                  completed_at: [:string, nullable: true],
+                 withdrawal_period_ends_at: [:string, nullable: true],
+                 within_withdrawal_period: :boolean,
                  billing_address: { nullable: true }, shipping_address: { nullable: true },
                  gift_card: { nullable: true }, market: { nullable: true }
 
@@ -29,12 +39,50 @@ module Spree
           order.market&.prefixed_id
         end
 
+        # The EU cooling-off deadline. Customer-facing by design: a buyer
+        # deciding whether they can still send something back should not have
+        # to work the date out from a policy page.
+        attribute :withdrawal_period_ends_at do |order|
+          order.withdrawal_period_ends_at&.iso8601
+        end
+
+        attribute :within_withdrawal_period do |order|
+          order.within_withdrawal_period?
+        end
+
+        # The checkout handle this order was born from (nil for admin drafts).
+        # Lets abandonment tooling match cart.* events to the conversion.
+        # Encoded from the FK — loading the cart row just for its id would be
+        # an N+1 on order lists.
+        attribute :cart_id do |order|
+          Spree::Cart.prefixed_id_for(order.cart_id)
+        end
+
         attribute :channel_id do |order|
           order.channel&.prefixed_id
         end
 
-        attributes :number, :email, :customer_note,
-                   :currency, :locale, :total_quantity,
+        # Which company node the order was placed for — frozen at completion.
+        attribute :company_id do |order|
+          order.company&.prefixed_id
+        end
+
+        attribute :company_name do |order|
+          order.company&.name
+        end
+
+        # The buyer's own purchase-order reference, carried from the cart. Their
+        # accounting reconciles against it, so it stays on the order forever.
+        attribute :po_document_filename do |order|
+          order.po_document.blob&.filename&.to_s if order.po_document.attached?
+        end
+
+        attribute :po_document_byte_size do |order|
+          order.po_document.blob&.byte_size if order.po_document.attached?
+        end
+
+        attributes :number, :email, :customer_note, :po_number,
+                   :currency, :locale, :total_quantity, :coupon_code,
                    :fulfillment_status, :payment_status,
                    completed_at: :iso8601
 
@@ -47,7 +95,8 @@ module Spree
                          :additional_tax_total, :display_additional_tax_total, :total, :display_total,
                          :gift_card_total, :display_gift_card_total,
                          :amount_due, :display_amount_due,
-                         :delivery_total, :display_delivery_total
+                         :delivery_total, :display_delivery_total,
+                         :fee_total, :display_fee_total
 
         attribute :store_credit_total do |order|
           order.total_applied_store_credit.to_s unless params[:hide_prices]
@@ -61,7 +110,10 @@ module Spree
           order.covered_by_store_credit?
         end
 
-        many :discounts, resource: proc { Spree.api.discount_serializer }
+        many :order_promotions, key: :discounts, resource: proc { Spree.api.applied_promotion_serializer }
+        # Itemized charges (duties, surcharges, COD, handling) — see the cart
+        # serializer; the order keeps them visible after placement.
+        many :fees, resource: proc { Spree.api.fee_serializer }
         many :line_items, key: :items, resource: proc { Spree.api.line_item_serializer }
         many :fulfillments, resource: proc { Spree.api.fulfillment_serializer }
         many :payments, resource: proc { Spree.api.payment_serializer }

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

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentMethodSerializer < BaseSerializer
-        typelize name: :string, description: [:string, nullable: true], type: :string,
+        typelize name: :string, description: [:string, nullable: true], type: [:string, comment: 'Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe.'],
                  session_required: :boolean, source_required: :boolean
 
         attributes :name, :description

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

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentSerializer < BaseSerializer
-        typelize status: :string, payment_method_id: :string, response_code: [:string, nullable: true],
+        typelize status: [:string, enum: Spree::Payment.statuses, enum_type_name: 'PaymentStatus'], payment_method_id: :string, response_code: [:string, nullable: true],
                  number: :string, amount: [:string, nullable: true], display_amount: [:string, nullable: true],
                  source_type: [:string, nullable: true, enum: %w[credit_card store_credit payment_source]],
                  source_id: [:string, nullable: true],
@@ -12,16 +12,12 @@ module Spree
           payment.payment_method&.prefixed_id
         end
 
-        attributes :response_code, :number
+        attributes :response_code, :number, :status
 
         # Nulled for gated (prices_hidden) guests so a payment can't leak the
         # amount the cart/order totals already withhold.
         money_attributes :amount, :display_amount
 
-        attribute :status do |payment|
-          payment.state
-        end
-
         attribute :source_type do |payment|
           case payment.source_type
           when 'Spree::CreditCard'

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

@@ -2,10 +2,11 @@ module Spree
   module Api
     module V3
       class PaymentSessionSerializer < BaseSerializer
-        typelize status: :string, amount: :string, currency: :string,
+        typelize status: [:string, enum: Spree::PaymentSession.statuses, enum_type_name: 'PaymentSessionStatus'], amount: :string, currency: :string,
                  external_id: :string, external_data: 'Record<string, unknown>',
                  expires_at: [:string, nullable: true], customer_external_id: [:string, nullable: true],
-                 payment_method_id: :string, order_id: :string
+                 payment_method_id: :string, order_id: [:string, nullable: true],
+                 cart_id: [:string, nullable: true]
 
         attributes :status, :currency, :external_id, :external_data,
                    :customer_external_id,
@@ -19,8 +20,14 @@ module Spree
           session.payment_method&.prefixed_id
         end
 
+        # Bridge: reports the owner (cart during checkout, order after
+        # completion) until clients migrate to cart_id/order_id.
         attribute :order_id do |session|
-          session.order&.prefixed_id
+          session.owner&.prefixed_id
+        end
+
+        attribute :cart_id do |session|
+          session.cart&.prefixed_id
         end
 
         one :payment_method, resource: proc { Spree.api.payment_method_serializer }

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

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentSetupSessionSerializer < BaseSerializer
-        typelize status: :string, external_id: [:string, nullable: true], external_client_secret: [:string, nullable: true],
+        typelize status: [:string, enum: Spree::PaymentSetupSession.statuses, enum_type_name: 'PaymentSetupSessionStatus'], external_id: [:string, nullable: true], external_client_secret: [:string, nullable: true],
                  external_data: 'Record<string, unknown>',
                  payment_method_id: [:string, nullable: true], payment_source_id: [:string, nullable: true],
                  payment_source_type: [:string, nullable: true], customer_id: [:string, nullable: true]

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

@@ -8,13 +8,18 @@ module Spree
         attributes :name, :slug
 
         attribute :body do |policy|
-          policy.body&.to_plain_text
+          Spree::RichTextHelper.to_plain_text(policy.body)
         end
 
         attribute :body_html do |policy|
-          policy.body&.body&.to_s.to_s
+          policy.body_html
         end
 
+        # The one timestamp a store serializer carries. When a legal document
+        # last changed is what a shopper is entitled to see on the page —
+        # "last updated" is the convention for policies — not operational
+        # detail. `created_at` stays admin-only.
+        attributes updated_at: :iso8601
       end
     end
   end

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

@@ -6,7 +6,7 @@ module Spree
                  type: "'option'",
                  name: :string,
                  label: :string,
-                 kind: :string,
+                 kind: [:string, enum: Spree::OptionType::KINDS],
                  options: [:ProductFilterOptionValue, multi: true]
 
         attributes :id, :type, :name, :label, :kind

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

@@ -9,6 +9,7 @@ module Spree
                  meta_description: [:string, nullable: true], meta_keywords: [:string, nullable: true],
                  variant_count: :number,
                  default_variant_id: :string,
+                 buy_box_variant_id: [:string, nullable: true],
                  thumbnail_url: [:string, nullable: true],
                  available_on: [:string, nullable: true],
                  preorder_ships_at: [:string, nullable: true],
@@ -55,10 +56,23 @@ module Spree
           product.description
         end
 
+        # The product's stable identity for add-to-cart. Deliberately NOT the
+        # 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
 
+        # The offer a storefront should lead with when several sellers share
+        # the listing — the buy-box winner in the request's currency. Nil when
+        # nothing wins. Separate from `default_variant_id` so a storefront opts
+        # into the marketplace behaviour without the identity field moving
+        # under it; storefronts that ignore it lose nothing.
+        attribute :buy_box_variant_id do |product|
+          product.buy_box_variant(currency: current_currency)&.prefixed_id
+        end
+
         # Main product image URL for listings (cached primary_media)
         attribute :thumbnail_url do |product|
           image_url_for(product.primary_media)
@@ -68,16 +82,22 @@ module Spree
           product.tags.map(&:name) # not pluck as we preload tags
         end
 
-        # Price object - calculated price with price list resolution
+        # Price object - calculated price with price list resolution.
+        #
+        # Priced off the buy-box winner, not `default_variant_id`. Price is a
+        # display fact that already moves with price lists and currency, so it
+        # is not an identity — and it must agree with `buy_box_variant_id`: the
+        # price a shopper sees is the price of the offer they are shown. On a
+        # single-seller catalog winner and default variant are the same row.
         attribute :price do |product|
-          price = price_for(product.default_variant)
+          price = price_for(featured_variant(product))
           Spree.api.price_serializer.new(price, params: params).to_h if price.present?
         end
 
         # Original price - base price without price list resolution (for showing strikethrough)
         # Returns null when same as calculated price, only populated when a price list discount is applied
         attribute :original_price do |product|
-          variant = product.default_variant
+          variant = featured_variant(product)
           calculated = price_for(variant)
           base = price_in(variant)
 
@@ -86,7 +106,18 @@ module Spree
           end
         end
 
+        # 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
+
         # Conditional associations
+        one :seller,
+            resource: proc { Spree.api.seller_serializer },
+            if: proc { expand?('seller') }
+
         one :primary_media,
             resource: proc { Spree.api.media_serializer },
             if: proc { expand?('primary_media') }
@@ -112,24 +143,25 @@ module Spree
              resource: proc { Spree.api.option_value_serializer },
              if: proc { expand?('option_values') }
 
-        many :taxons,
-             proc { |taxons, params|
-               taxons.select { |t| t.taxonomy.store_id == params[:store].id }
+        many :categories,
+             proc { |categories, params|
+               store_id = params[:store].id
+               categories.select { |c| c.store_id == store_id }
              },
-             key: :categories,
              resource: proc { Spree.api.category_serializer },
              if: proc { expand?('categories') }
 
-        many :public_metafields,
+        many :storefront_custom_fields,
              key: :custom_fields,
              resource: proc { Spree.api.custom_field_serializer },
              if: proc { expand?('custom_fields') }
 
-        typelize prior_price: ['PriceHistory', nullable: true]
+        typelize prior_price: ['PriceHistory', nullable: true],
+                 seller_id: [:string, nullable: true]
 
         attribute :prior_price,
                   if: proc { expand?('prior_price') } do |product|
-          record = price_in(product.default_variant)&.prior_price
+          record = price_in(featured_variant(product))&.prior_price
           Spree.api.price_history_serializer.new(record, params: params).to_h if record
         end
       end

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

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      # Base Product Type Serializer.
+      #
+      # ProductType is back-office vocabulary and is NOT exposed on the Store
+      # API — no endpoint, no expand, no filter. This class exists solely as the
+      # parent of the Admin serializer, per the house convention that every
+      # admin serializer extends a store-namespace base.
+      class ProductTypeSerializer < BaseSerializer
+        typelize name: :string
+
+        attributes :name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+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
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module Spree
       class RefundSerializer < BaseSerializer
         typelize amount: [:string, nullable: true], transaction_id: [:string, nullable: true],
                  payment_id: [:string, nullable: true], refund_reason_id: [:string, nullable: true],
-                 reimbursement_id: [:string, nullable: true]
+                 originator_id: [:string, nullable: true], originator_type: [:string, nullable: true]
 
         attributes :transaction_id
 
@@ -22,8 +22,14 @@ module Spree
           refund.reason&.prefixed_id
         end
 
-        attribute :reimbursement_id do |refund|
-          refund.reimbursement&.prefixed_id
+        # What triggered this refund — a Return, Exchange or Claim; nil for a
+        # manual refund.
+        attribute :originator_id do |refund|
+          refund.originator&.prefixed_id
+        end
+
+        attribute :originator_type do |refund|
+          refund.originator_type
         end
       end
     end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class ReturnLineItemSerializer < BaseSerializer
+        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
+
+        one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Why a customer sent something back. Embedded in returns and exchanges
+      # so a customer sees the reason's name rather than only its id; the
+      # vocabulary itself has no Store API controller of its own.
+      #
+      # Parallel to ClaimReasonSerializer rather than sharing a base class:
+      # Typelizer emits one TS type per serializer, so a shared parent would
+      # publish an abstract `Reason` type that no endpoint returns.
+      class ReturnReasonSerializer < BaseSerializer
+        typelize name: :string, active: :boolean
+
+        attributes :name, :active
+      end
+    end
+  end
+end