spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class ExchangeLineItemSerializer < BaseSerializer
+        typelize quantity: :number,
+                 received_quantity: :number,
+                 resellable: :boolean,
+                 original_price: :string,
+                 new_variant_price: :string,
+                 price_difference: :string,
+                 original_variant_id: [:string, nullable: true],
+                 new_variant_id: [:string, nullable: true],
+                 line_item_id: [:string, nullable: true],
+                 fulfillment_item_id: [:string, nullable: true]
+
+        attributes :quantity, :received_quantity, :resellable
+
+        attribute :original_price do |line|
+          line.original_price.to_s
+        end
+
+        attribute :new_variant_price do |line|
+          line.new_variant_price.to_s
+        end
+
+        attribute :price_difference do |line|
+          line.price_difference.to_s
+        end
+
+        attribute :original_variant_id do |line|
+          line.original_variant&.prefixed_id
+        end
+
+        attribute :new_variant_id do |line|
+          line.new_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 :original_variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('original_variant') }
+        one :new_variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('new_variant') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Customer-facing view of an exchange.
+      class ExchangeSerializer < BaseSerializer
+        typelize number: :string,
+                 status: [:string, enum: Spree::Exchange.statuses, enum_type_name: 'ExchangeStatus'],
+                 order_id: [:string, nullable: true],
+                 reason_id: [:string, nullable: true],
+                 price_difference: :string,
+                 display_price_difference: :string,
+                 approved_at: [:string, nullable: true],
+                 received_at: [:string, nullable: true],
+                 fulfilled_at: [:string, nullable: true],
+                 canceled_at: [:string, nullable: true]
+
+        attributes :number, :status
+
+        attribute :order_id do |exchange|
+          exchange.order&.prefixed_id
+        end
+
+        attribute :reason_id do |exchange|
+          exchange.reason&.prefixed_id
+        end
+
+        attribute :price_difference do |exchange|
+          exchange.price_difference.to_s
+        end
+
+        attribute :display_price_difference do |exchange|
+          exchange.display_price_difference.to_s
+        end
+
+        attribute :approved_at do |exchange|
+          exchange.approved_at&.iso8601
+        end
+
+        attribute :received_at do |exchange|
+          exchange.received_at&.iso8601
+        end
+
+        attribute :fulfilled_at do |exchange|
+          exchange.fulfilled_at&.iso8601
+        end
+
+        attribute :canceled_at do |exchange|
+          exchange.canceled_at&.iso8601
+        end
+
+        one :reason, resource: proc { Spree.api.return_reason_serializer }, if: proc { expand?('reason') }
+
+        many :exchange_line_items,
+             resource: proc { Spree.api.exchange_line_item_serializer },
+             if: proc { expand?('exchange_line_items') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      # An extensible charge (typed row): surcharge, handling, gift wrap, COD.
+      # Order-level when both adjustable IDs are null.
+      class FeeSerializer < BaseSerializer
+        typelize label: :string,
+                 kind: [:string, enum: Spree::Fee::KINDS, enum_type_name: 'FeeKind',
+                        comment: 'What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds.'],
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true],
+                 line_item_id: [:string, nullable: true], fulfillment_id: [:string, nullable: true]
+
+        attributes :label, :kind
+
+        attribute :line_item_id do |record|
+          record.line_item&.prefixed_id
+        end
+
+        attribute :fulfillment_id do |record|
+          record.fulfillment&.prefixed_id
+        end
+
+        money_attributes :amount, :display_amount
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      # A shipment as a freight forwarder reads it: units, the cartons they
+      # fill, the pallets those stack onto, cubic meters and gross weight.
+      #
+      # +complete+ is false when part of the catalog carries no carton data.
+      # The figures are still the best available, but they are a minimum
+      # rather than a total, and a surface quoting from them should say so.
+      #
+      # Totals only. What each product contributes is a warehouse's business,
+      # so the per-line breakdown lives on the admin twin.
+      class FreightSummarySerializer < BaseSerializer
+        # A value object, not a record — it has no id of its own.
+        _attributes.delete(:id)
+
+        typelize total_units: :number,
+                 total_cartons: :number,
+                 total_pallets: ['number | null'],
+                 total_volume: :string,
+                 total_weight: :string,
+                 complete: :boolean
+
+        attributes :total_units, :total_cartons, :total_pallets
+
+        attribute :total_volume do |summary|
+          decimal_string(summary.total_volume)
+        end
+
+        attribute :total_weight do |summary|
+          decimal_string(summary.total_weight)
+        end
+
+        attribute :complete, &:complete?
+      end
+    end
+  end
+end

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

@@ -2,21 +2,32 @@ module Spree
   module Api
     module V3
       class FulfillmentSerializer < BaseSerializer
-        typelize number: :string, status: :string, fulfillment_type: :string,
+        typelize number: :string, status: [:string, enum: Spree::Fulfillment.statuses, enum_type_name: 'FulfillmentStatus'],
+                 fulfillment_type: [:string, enum: %w[shipping digital pickup pickup_point]],
                  tracking: [:string, nullable: true],
                  tracking_url: [:string, nullable: true], fulfilled_at: [:string, nullable: true],
+                 delivered_at: [:string, nullable: true],
                  cost: [:string, nullable: true], display_cost: [:string, nullable: true],
+                 unpriced: :boolean,
                  total: [:string, nullable: true], display_total: [:string, nullable: true],
                  discount_total: [:string, nullable: true], display_discount_total: [:string, nullable: true],
                  additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
                  included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
                  tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
-                 items: 'Array<{ item_id: string; variant_id: string; quantity: number }>'
+                 items: 'Array<{ item_id: string; variant_id: string; quantity: number }>',
+                 pickup_point_data: ['Record<string, unknown>', nullable: true],
+                 selected_delivery_rate_id: [:string, nullable: true]
 
-        attributes :number, :tracking, :tracking_url
+        # +tracking+ and +tracking_url+ summarize the primary delivery; every
+        # consignment is listed under +deliveries+.
+        attributes :number, :tracking, :tracking_url, :pickup_point_data, :selected_delivery_rate_id
 
         # Nulled for gated (prices_hidden) guests so a fulfillment can't leak the
         # shipping/tax amounts the cart/order totals already withhold.
+        # Says the shipping price is still to come, so a client need not
+        # infer it from a zero cost. Not price-gated — a flag, not an amount.
+        attribute :unpriced, &:unpriced?
+
         money_attributes :cost, :display_cost,
                          :total, :display_total,
                          :discount_total, :display_discount_total,
@@ -24,22 +35,20 @@ module Spree
                          :included_tax_total, :display_included_tax_total,
                          :tax_total, :display_tax_total
 
-        attribute :status do |shipment|
-          shipment.state
-        end
+        attributes :status
 
-        attribute :fulfillment_type do |shipment|
-          shipment.digital? ? 'digital' : 'shipping'
+        # Column-backed since 6.0; the fallback covers rows created before the
+        # fulfillment_type backfill ran.
+        attribute :fulfillment_type do |fulfillment|
+          fulfillment.fulfillment_type.presence || (fulfillment.digital? ? 'digital' : 'shipping')
         end
 
-        attribute :fulfilled_at do |shipment|
-          shipment.shipped_at&.iso8601
-        end
+        attributes fulfilled_at: :iso8601, delivered_at: :iso8601
 
         # Which items (and how many) are in this fulfillment.
         # A line item can be split across fulfillments with different quantities.
-        attribute :items do |shipment|
-          shipment.manifest.filter_map do |item|
+        attribute :items do |fulfillment|
+          fulfillment.manifest.filter_map do |item|
             next unless item.line_item
 
             {
@@ -50,9 +59,13 @@ module Spree
           end
         end
 
-        one :shipping_method, key: :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
+        # Where each parcel is, as the carrier last reported it — the
+        # customer's question, so always embedded.
+        many :deliveries, resource: proc { Spree.api.delivery_serializer }
+        one :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
         one :stock_location, resource: proc { Spree.api.stock_location_serializer }
-        many :shipping_rates, key: :delivery_rates, resource: proc { Spree.api.delivery_rate_serializer }
+        many :delivery_rates, resource: proc { Spree.api.delivery_rate_serializer }
+        many :tax_lines, resource: proc { Spree.api.tax_line_serializer }, if: proc { expand?('tax_lines') }
       end
     end
   end

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

@@ -3,7 +3,7 @@ module Spree
     module V3
       class GiftCardSerializer < BaseSerializer
         typelize code: :string,
-                 status: :string,
+                 status: [:string, enum: Spree::GiftCard::DISPLAY_STATUSES, enum_type_name: 'GiftCardStatus'],
                  amount: [:string, nullable: true],
                  amount_used: [:string, nullable: true],
                  amount_authorized: [:string, nullable: true],
@@ -22,7 +22,7 @@ module Spree
         end
 
         attribute :status do |gift_card|
-          gift_card.display_state
+          gift_card.display_status
         end
 
         attributes :currency

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

@@ -5,7 +5,7 @@ module Spree
     module V3
       class ImportRowSerializer < BaseSerializer
         typelize import_id: [:string, nullable: true], row_number: :number,
-                 status: :string, validation_errors: [:string, nullable: true],
+                 status: [:string, enum: Spree::ImportRow.statuses, enum_type_name: 'ImportRowStatus'], validation_errors: [:string, nullable: true],
                  item_type: [:string, nullable: true], item_id: [:string, nullable: true]
 
         attributes :row_number, :status, :validation_errors,

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

@@ -4,8 +4,10 @@ module Spree
   module Api
     module V3
       class ImportSerializer < BaseSerializer
-        typelize number: :string, type: [:string, nullable: true], status: :string,
+        typelize number: :string,
+                 type: [:string, nullable: true, comment: 'Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more.'], status: [:string, enum: Spree::Import.statuses, enum_type_name: 'ImportStatus'],
                  owner_type: [:string, nullable: true], owner_id: [:string, nullable: true],
+                 store_id: [:string, nullable: true], seller_id: [:string, nullable: true],
                  user_id: [:string, nullable: true], rows_count: :number
 
         attributes :number, :rows_count,
@@ -23,13 +25,25 @@ module Spree
           import.status.to_s
         end
 
-        # `"store"` / `"vendor"`, not the polymorphic class name.
+        # Which marketplace this import belongs to, and — when a seller ran it —
+        # whose it is. A null `seller_id` means the operator's own.
+        attribute :store_id do |import|
+          import.store&.prefixed_id
+        end
+
+        attribute :seller_id do |import|
+          import.seller&.prefixed_id
+        end
+
+        # @deprecated Read `store_id` / `seller_id` — removed in 6.1. Emitted
+        #   from the pair above rather than the dropped columns, so a client
+        #   still reading them sees the same answer.
         attribute :owner_type do |import|
-          Spree::Base.polymorphic_api_type(import.owner_type)
+          Spree::Base.polymorphic_api_type(import.seller_id.present? ? 'Spree::Seller' : 'Spree::Store')
         end
 
         attribute :owner_id do |import|
-          import.owner&.prefixed_id
+          (import.seller || import.store)&.prefixed_id
         end
 
         attribute :user_id do |import|

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

@@ -4,7 +4,7 @@ module Spree
   module Api
     module V3
       class InvitationSerializer < BaseSerializer
-        typelize email: :string, status: :string,
+        typelize email: :string, status: [:string, enum: Spree::Invitation.statuses, enum_type_name: 'InvitationStatus'],
                  resource_type: [:string, nullable: true], resource_id: [:string, nullable: true],
                  inviter_type: [:string, nullable: true], inviter_id: [:string, nullable: true],
                  invitee_type: [:string, nullable: true], invitee_id: [:string, nullable: true],

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

@@ -14,12 +14,21 @@ module Spree
                  discounted_amount: [:string, nullable: true], display_discounted_amount: [:string, nullable: true],
                  compare_at_amount: [:string, nullable: true], display_compare_at_amount: [:string, nullable: true],
                  thumbnail_url: [:string, nullable: true],
-                 preorder: :boolean, preorder_ships_at: [:string, nullable: true]
+                 preorder: :boolean, preorder_ships_at: [:string, nullable: true],
+                 seller_id: [:string, nullable: true]
 
         attribute :variant_id do |line_item|
           line_item.variant&.prefixed_id
         end
 
+        # Which seller this line was bought from, snapshotted when it was
+        # added — nil is the operator's own first-party item. Always present
+        # so a storefront can group a multi-seller cart without paying for the
+        # expand; `?expand=seller` adds the public profile.
+        attribute :seller_id do |line_item|
+          line_item.seller&.prefixed_id
+        end
+
         # True when the line item's variant is currently a pre-order, so the
         # cart/checkout can flag it as shipping later.
         attribute :preorder do |line_item|
@@ -57,8 +66,16 @@ module Spree
           image_url_for(line_item.thumbnail)
         end
 
+        one :seller,
+            resource: proc { Spree.api.seller_serializer },
+            if: proc { expand?('seller') }
+
         many :option_values, resource: proc { Spree.api.option_value_serializer }
         many :digital_links, resource: proc { Spree.api.digital_link_serializer }
+        # Tax hangs off its adjustable, never off the cart or order: the
+        # exactly-one-adjustable rule makes the nested view complete, and the
+        # owner already carries the tax totals.
+        many :tax_lines, resource: proc { Spree.api.tax_line_serializer }, if: proc { expand?('tax_lines') }
       end
     end
   end

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

@@ -5,11 +5,11 @@ module Spree
         typelize name: :string, currency: :string,
                  default_locale: :string,
                  supported_locales: [:string, multi: true],
-                 country_isos: [:string, multi: true],
+                 country_codes: [:string, multi: true],
                  tax_inclusive: :boolean,
                  default: :boolean
 
-        attributes :name, :currency, :default_locale, :tax_inclusive, :default, :country_isos
+        attributes :name, :currency, :default_locale, :tax_inclusive, :default, :country_codes
 
         attribute :supported_locales do |market|
           market.supported_locales_list

data/app/serializers/spree/api/v3/{asset_serializer.rb → media_event_serializer.rb}

@@ -3,11 +3,11 @@
 module Spree
   module Api
     module V3
-      class AssetSerializer < BaseSerializer
-        # `type` is not exposed: Spree::Image/Spree::Video were collapsed into
-        # Spree::Asset, so the STI column is a legacy vestige with no subclasses
+      class MediaEventSerializer < BaseSerializer
+        # `type` is not exposed: the old Spree::Image/Spree::Video STI collapsed
+        # into one class, so the column is a legacy vestige with no subclasses
         # — `media_type` is the discriminator (see MediaSerializer).
-        typelize media_type: :string, viewable_type: :string,
+        typelize media_type: [:string, enum: Spree::Media::MEDIA_TYPES], viewable_type: :string,
                  viewable_id: :string, position: [:number, nullable: true],
                  alt: [:string, nullable: true]
 

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