spree_api 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      # One consignment's carrier journey — the customer's "where is my
+      # parcel" answer, so it sits on the public serializer beside the
+      # fulfillment's tracking summary.
+      class DeliverySerializer < BaseSerializer
+        typelize tracking_number: :string,
+                 tracking_url: [:string, nullable: true],
+                 carrier: [:string, nullable: true],
+                 carrier_name: [:string, nullable: true],
+                 service: [:string, nullable: true],
+                 status: [:string, enum: Spree::Delivery::STATUSES],
+                 estimated_delivery_at: [:string, nullable: true],
+                 delivered_at: [:string, nullable: true]
+
+        attributes :tracking_number, :carrier, :carrier_name, :service, :status
+
+        # The best link for this consignment: the one stored on the row, or
+        # the one derived from its carrier and number.
+        attribute :tracking_url do |delivery|
+          delivery.resolved_tracking_url
+        end
+
+        attributes estimated_delivery_at: :iso8601, delivered_at: :iso8601
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      class DeliveryZoneMemberSerializer < BaseSerializer
+        typelize member_type: [:string, enum: Spree::DeliveryZoneMember::MEMBER_TYPES], country_code: [:string, nullable: true],
+                 country_name: [:string, nullable: true],
+                 state_code: [:string, nullable: true], state_name: [:string, nullable: true],
+                 postal_code_prefix: [:string, nullable: true],
+                 postal_code_from: [:string, nullable: true],
+                 postal_code_to: [:string, nullable: true]
+
+        attributes :member_type, :country_code, :state_code,
+                   :postal_code_prefix, :postal_code_from, :postal_code_to
+
+        # Admin zone summaries list countries by name; without this every
+        # client would have to carry its own ISO-to-name table.
+        attribute :country_name do |record|
+          record.country&.name
+        end
+
+        # The subdivision's name is reference data rather than something the
+        # member stores, so it is looked up from its country and code.
+        attribute :state_name do |record|
+          Spree::IsoData.subdivision_name(record.country_code, record.state_code) if record.state_code.present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Spree
+  module Api
+    module V3
+      class DeliveryZoneSerializer < BaseSerializer
+        typelize name: :string, description: [:string, nullable: true]
+
+        attributes :name, :description
+
+        many :members, resource: proc { Spree.api.delivery_zone_member_serializer }, if: proc { expand?('members') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class DigitalAssetSerializer < BaseSerializer
+        typelize variant_id: [:string, nullable: true],
+                 filename: [:string, nullable: true],
+                 content_type: [:string, nullable: true]
+
+        attribute :variant_id do |digital_asset|
+          digital_asset.variant&.prefixed_id
+        end
+
+        attribute :filename do |digital_asset|
+          digital_asset.filename&.to_s
+        end
+
+        attributes :content_type
+      end
+    end
+  end
+end

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

@@ -3,13 +3,17 @@ module Spree
     module V3
       class DigitalLinkSerializer < BaseSerializer
         typelize access_counter: :number, filename: :string, content_type: :string,
-                 download_url: :string,
+                 download_url: :string, expires_at: [:string, nullable: true],
                  authorizable: :boolean, expired: :boolean, access_limit_exceeded: :boolean
 
         attributes :access_counter, :filename, :content_type
 
         attribute :download_url do |digital_link|
-          Spree::Core::Engine.routes.url_helpers.api_v3_store_digital_download_path(token: digital_link.token)
+          Spree::Api::DigitalLinkUrls.download_path(digital_link)
+        end
+
+        attribute :expires_at do |digital_link|
+          digital_link.expires_at&.iso8601
         end
 
         attribute :authorizable do |digital_link|

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

@@ -1,20 +1,34 @@
 module Spree
   module Api
     module V3
-      # Unified discount serializer for applied promotions on Cart and Order.
-      # Replaces CartPromotionSerializer and OrderPromotionSerializer.
+      # A typed Spree::Discount money row (promotion-sourced or manual) on a
+      # line item or fulfillment. The embedded `discounts` key on Cart/Order
+      # stays the applied-promotion summary — see AppliedPromotionSerializer.
       class DiscountSerializer < BaseSerializer
-        typelize name: :string, description: [:string, nullable: true], code: [:string, nullable: true],
-                 amount: [:string, nullable: true], display_amount: [:string, nullable: true], promotion_id: :string
+        typelize label: :string, kind: [:string, enum: Spree::Discount::KINDS], code: [:string, nullable: true],
+                 value: [:string, nullable: true], value_type: [:string, nullable: true],
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true],
+                 promotion_id: [:string, nullable: true], line_item_id: [:string, nullable: true],
+                 fulfillment_id: [:string, nullable: true]
+
+        attributes :label, :kind, :code, :value_type
+
+        attribute :value do |record|
+          record.value&.to_s
+        end
 
         attribute :promotion_id do |record|
           record.promotion&.prefixed_id
         end
 
-        attributes :name, :description, :code
+        attribute :line_item_id do |record|
+          record.line_item&.prefixed_id
+        end
+
+        attribute :fulfillment_id do |record|
+          record.fulfillment&.prefixed_id
+        end
 
-        # Nulled for gated (prices_hidden) guests so an applied discount can't
-        # leak the amount the cart/order totals already withhold.
         money_attributes :amount, :display_amount
       end
     end

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]