spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A return on one of this seller's orders.
+        #
+        # Built on the shared V3 serializer rather than the admin one, which
+        # expands the order and the customer behind it — a seller reads their
+        # own order's goods coming back, never the buyer's record.
+        #
+        # What it adds over the shared one is the pair of figures a seller
+        # needs to settle: what has already gone back, and what may still.
+        class ReturnSerializer < V3::ReturnSerializer
+          typelize memo: [:string, nullable: true],
+                   stock_location_id: [:string, nullable: true],
+                   refunded_total: :string,
+                   refundable_total: :string,
+                   display_refunded_total: :string
+
+          attributes :memo
+
+          attribute :stock_location_id do |return_record|
+            return_record.stock_location&.prefixed_id
+          end
+
+          attribute :refunded_total do |return_record|
+            return_record.refunded_total.to_s
+          end
+
+          # What the refund dialog opens on — never more than this may be
+          # given back, whatever amount is typed.
+          attribute :refundable_total do |return_record|
+            return_record.refundable_total.to_s
+          end
+
+          attribute :display_refunded_total do |return_record|
+            return_record.display_refunded_total.to_s
+          end
+
+          many :return_line_items,
+               resource: proc { Spree.api.seller_return_line_item_serializer },
+               if: proc { expand?('return_line_items') }
+
+          one :reason, resource: proc { Spree.api.seller_reason_serializer }, if: proc { expand?('reason') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The seller's view of a label on one of their parcels — the same
+        # facts the operator sees, downloaded through the seller branch.
+        class ShippingLabelSerializer < Admin::ShippingLabelSerializer
+          attribute :download_url do |shipping_label|
+            next nil unless shipping_label.file.attached? || shipping_label.file_pending?
+
+            next nil if shipping_label.owner.order.nil?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_seller_order_fulfillment_label_path(
+              order_id: shipping_label.owner.order.prefixed_id,
+              fulfillment_id: shipping_label.owner.prefixed_id,
+              id: shipping_label.prefixed_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What a seller holds of one variant at one of their locations.
+        class StockLevelSerializer < V3::StockLevelSerializer
+          typelize allocated_count: :number, available_count: :number
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          # Units promised to placed orders but not yet dispatched.
+          attribute :allocated_count do |stock_level|
+            stock_level.allocated_count.to_i
+          end
+
+          attribute :available_count do |stock_level|
+            stock_level.available_count.to_i
+          end
+
+          one :stock_location,
+              resource: proc { Spree.api.seller_stock_location_serializer },
+              if: proc { expand?('stock_location') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class StockLocationSerializer < V3::StockLocationSerializer
+          typelize address2: [:string, nullable: true], state_name: [:string, nullable: true],
+                   phone: [:string, nullable: true], company: [:string, nullable: true],
+                   active: :boolean, default: :boolean, kind: [:string, enum: Spree::StockLocation::KINDS, enum_type_name: 'StockLocationKind'],
+                   returns_enabled: :boolean
+
+          attributes :address2, :state_name, :phone, :company, :active, :default, :kind,
+                     :returns_enabled, created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class TaxIdentifierSerializer < V3::BaseSerializer
+          typelize kind: [:string, comment: 'Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more.'], value: :string,
+                   validation_status: [:string, nullable: true, enum: Spree::TaxIdentifier::VALIDATION_STATUSES],
+                   validated_at: [:string, nullable: true]
+
+          attributes :kind, :value, :validation_status, validated_at: :iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class TeamMemberSerializer < V3::BaseSerializer
+          typelize email: :string,
+                   first_name: [:string, nullable: true],
+                   last_name: [:string, nullable: true],
+                   full_name: [:string, nullable: true],
+                   avatar_url: [:string, nullable: true]
+
+          attributes :email, :first_name, :last_name, :full_name,
+                     created_at: :iso8601
+
+          attribute :avatar_url do |user|
+            image_url_for(user.avatar)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What one of this seller's orders earned them, as the seller reads it.
+        #
+        # Declared from the base rather than the admin serializer so nothing
+        # leaks by inheritance: the provider's metadata and the refund behind a
+        # reversal are the marketplace's, and there is one seller in play so
+        # naming them on every row would only repeat the header.
+        class TransferSerializer < V3::BaseSerializer
+          typelize kind: :string,
+                   status: :string,
+                   currency: :string,
+                   provider: :string,
+                   amount: :string,
+                   settled_amount: 'string | null',
+                   settled_currency: 'string | null',
+                   converted: :boolean,
+                   display_amount: :string,
+                   reference: 'string | null',
+                   order_id: 'string | null',
+                   order_number: 'string | null',
+                   payout_id: 'string | null',
+                   reversed_from_id: 'string | null'
+
+          attributes :kind, :status, :currency, :provider, :reference,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # A string, so the figure a seller is paid round-trips exactly.
+          attribute(:amount) { |transfer| transfer.amount&.to_s }
+          attribute(:display_amount) { |transfer| transfer.display_amount.to_s }
+
+          # What this seller's account received, when the provider converted
+          # on the way in. Null when it settled in the currency of the sale.
+          attribute(:settled_amount) { |transfer| transfer.settled_amount&.to_s }
+          attribute(:settled_currency) { |transfer| transfer.settled_currency }
+          attribute(:converted) { |transfer| transfer.converted? }
+
+          %i[order payout reversed_from].each do |association|
+            attribute(:"#{association}_id") { |transfer| transfer.public_send(association)&.prefixed_id }
+          end
+
+          attribute(:order_number) { |transfer| transfer.order&.number }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One variant of a seller's own product.
+        #
+        # Carries what a seller manages: the SKU and barcode, what it cost
+        # them, its weight and dimensions, its customs classification and what
+        # is on the shelf. No `tax_category_id` or `delivery_profile_id` —
+        # those are marketplace configuration and the seller cannot write them,
+        # so showing them would invite an edit that silently does nothing.
+        class VariantSerializer < V3::VariantSerializer
+          typelize position: :number,
+                   cost_price: [:string, nullable: true],
+                   cost_currency: [:string, nullable: true],
+                   barcode: [:string, nullable: true],
+                   available_stock: [:number, nullable: true],
+                   total_on_hand: [:number, nullable: true],
+                   preorderable: :boolean,
+                   preorder_ships_at: [:string, nullable: true],
+                   backorder_limit: [:number, nullable: true],
+                   hs_code: [:string, nullable: true],
+                   country_of_origin: [:string, nullable: true],
+                   customs_description: [:string, nullable: true],
+                   minimum_order_quantity: ['number | null'], order_multiple: ['number | null'],
+                   purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS],
+                   metadata: 'Record<string, unknown>'
+
+          attributes :metadata, :position, :cost_price, :cost_currency,
+                     :barcode, :backorder_limit,
+                     :hs_code, :country_of_origin, :customs_description,
+                     preorder_ships_at: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # The variant's own stored rules, not a buyer's resolved ones — a
+          # seller edits the row.
+          attribute :minimum_order_quantity, &:minimum_order_quantity
+          attribute :order_multiple, &:order_multiple
+          attribute :purchase_unit, &:purchase_unit
+
+          attribute :preorderable, &:preorderable?
+
+          attribute :available_stock do |variant|
+            variant.available_stock.to_i if variant.should_track_inventory?
+          end
+
+          attribute :total_on_hand do |variant|
+            variant.total_on_hand.to_i if variant.should_track_inventory?
+          end
+
+          one :primary_media,
+              resource: proc { Spree.api.seller_media_serializer },
+              if: proc { expand?('primary_media') }
+
+          many :gallery_media,
+               key: :media,
+               resource: proc { Spree.api.seller_media_serializer },
+               if: proc { expand?('media') }
+
+          many :prices,
+               resource: proc { Spree.api.price_serializer },
+               if: proc { expand?('prices') }
+
+          many :stock_levels,
+               resource: proc { Spree.api.seller_stock_level_serializer },
+               if: proc { expand?('stock_levels') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Spree
+  module Api
+    module V3
+      # A seller as a shopper sees them: who they are and what they look like,
+      # nothing about how the marketplace runs them.
+      #
+      # Deliberately excluded, because none of it is the customer's business:
+      # `status` and `sellable` (operational state — a seller a shopper can
+      # reach is by definition sellable), the settlement and tax configuration,
+      # billing and contact addresses, team size, and every timestamp.
+      class SellerSerializer < BaseSerializer
+        typelize name: :string, slug: :string,
+                 about: :string, about_html: :string,
+                 logo_url: [:string, nullable: true],
+                 square_logo_url: [:string, nullable: true],
+                 cover_photo_url: [:string, nullable: true]
+
+        attributes :name, :slug
+
+        attribute :about do |seller|
+          Spree::RichTextHelper.to_plain_text(seller.about)
+        end
+
+        attribute :about_html do |seller|
+          seller.about_html
+        end
+
+        attribute :logo_url do |seller|
+          image_url_for(seller.logo)
+        end
+
+        attribute :square_logo_url do |seller|
+          image_url_for(seller.square_logo)
+        end
+
+        attribute :cover_photo_url do |seller|
+          image_url_for(seller.cover_photo)
+        end
+
+        # The seller's published policies, on request. Behind the expand guard
+        # because a policy body is a whole legal document: a marketplace's
+        # seller listing would otherwise carry every seller's full text on
+        # every page. A product page reaches them as `expand=seller.policies`.
+        many :policies,
+             resource: proc { Spree.api.policy_serializer },
+             if: proc { expand?('policies') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      # Payload of the shipping_label.* events. Labels have no storefront
+      # serializer — a customer never sees one — so the event shape is
+      # declared here rather than found by convention.
+      class ShippingLabelEventSerializer < Admin::ShippingLabelSerializer
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/{stock_item_serializer.rb → stock_level_serializer.rb}

@@ -3,18 +3,18 @@
 module Spree
   module Api
     module V3
-      class StockItemSerializer < BaseSerializer
+      class StockLevelSerializer < BaseSerializer
         typelize count_on_hand: :number, backorderable: :boolean,
                  stock_location_id: [:string, nullable: true], variant_id: [:string, nullable: true]
 
         attributes :count_on_hand, :backorderable
 
-        attribute :stock_location_id do |stock_item|
-          stock_item.stock_location&.prefixed_id
+        attribute :stock_location_id do |stock_level|
+          stock_level.stock_location&.prefixed_id
         end
 
-        attribute :variant_id do |stock_item|
-          stock_item.variant&.prefixed_id
+        attribute :variant_id do |stock_level|
+          stock_level.variant&.prefixed_id
         end
       end
     end

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

@@ -3,15 +3,19 @@ module Spree
     module V3
       class StockLocationSerializer < BaseSerializer
         typelize name: :string, address1: [:string, nullable: true], city: [:string, nullable: true],
-                 zipcode: [:string, nullable: true], country_iso: [:string, nullable: true],
-                 country_name: [:string, nullable: true], state_abbr: [:string, nullable: true],
-                 state_text: [:string, nullable: true]
+                 zipcode: [:string, nullable: true], country_code: [:string, nullable: true],
+                 country_name: [:string, nullable: true], state_code: [:string, nullable: true],
+                 state_text: [:string, nullable: true],
+                 pickup_ready_in_minutes: [:number, nullable: true],
+                 pickup_instructions: [:string, nullable: true]
 
-        attribute :state_abbr do |stock_location|
-          stock_location.state&.abbr
-        end
+        attributes :name, :address1, :city, :zipcode, :country_code, :country_name, :state_code, :state_text
 
-        attributes :name, :address1, :city, :zipcode, :country_iso, :country_name, :state_text
+        # Collection details the customer needs when choosing a counter: how
+        # long until the order is ready, and where to go. This serializer
+        # backs the pickup-locations endpoint, so without them the two
+        # merchant-configured fields would never reach the buyer.
+        attributes :pickup_ready_in_minutes, :pickup_instructions
       end
     end
   end

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

@@ -4,24 +4,17 @@ module Spree
   module Api
     module V3
       class StockMovementSerializer < BaseSerializer
-        typelize quantity: :number, action: [:string, nullable: true],
-                 originator_type: [:string, nullable: true], originator_id: [:string, nullable: true],
-                 stock_item_id: [:string, nullable: true]
+        # `kind` is nullable for the lifetime of 6.0: a legacy row on an
+        # install that has not run spree:migrate_stock_movements_to_typed_rows
+        # has no kind yet.
+        typelize quantity: :number, kind: [:string, nullable: true, enum: Spree::StockMovement::KINDS],
+                 reason: [:string, nullable: true], stock_level_id: [:string, nullable: true]
 
-        attributes :quantity, :action,
+        attributes :quantity, :kind, :reason,
                    created_at: :iso8601, updated_at: :iso8601
 
-        # `"shipment"` / `"stock_transfer"`, not the polymorphic class name.
-        attribute :originator_type do |movement|
-          Spree::Base.polymorphic_api_type(movement.originator_type)
-        end
-
-        attribute :originator_id do |movement|
-          movement.originator&.prefixed_id
-        end
-
-        attribute :stock_item_id do |movement|
-          movement.stock_item&.prefixed_id
+        attribute :stock_level_id do |movement|
+          movement.stock_level&.prefixed_id
         end
       end
     end

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

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      # Payload of the stock_receipt.* events. Stock receipts have no
+      # storefront serializer, so the event shape is declared here rather than
+      # found by convention.
+      class StockReceiptEventSerializer < Admin::StockReceiptSerializer
+      end
+    end
+  end
+end

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

@@ -4,13 +4,13 @@ module Spree
   module Api
     module V3
       class StockTransferSerializer < BaseSerializer
-        # `type` is not exposed: Spree::StockTransfer has no STI subclasses, so
-        # the column is a legacy vestige that is always nil. The admin
-        # serializer already omits it.
-        typelize number: [:string, nullable: true],
+        # Both warehouses are required now: receiving from a supplier is a
+        # Spree::PurchaseOrder, not a transfer with a missing source
+        # (docs/plans/6.0-inventory-operations.md).
+        typelize number: :string,
                  reference: [:string, nullable: true],
-                 source_location_id: [:string, nullable: true],
-                 destination_location_id: [:string, nullable: true]
+                 source_location_id: :string,
+                 destination_location_id: :string
 
         attributes :number, :reference,
                    created_at: :iso8601, updated_at: :iso8601

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      class StoreCreditEventSerializer < BaseSerializer
+        typelize action: :string,
+                 display_action: [:string, nullable: true],
+                 amount: :string,
+                 display_amount: :string,
+                 authorization_code: [:string, nullable: true]
+
+        attributes :action, :authorization_code
+
+        attribute :display_action do |event|
+          event.display_action
+        end
+
+        attribute :amount do |event|
+          event.amount.to_s
+        end
+
+        attribute :display_amount do |event|
+          event.display_amount.to_s
+        end
+
+        attributes created_at: :iso8601
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      # Payload of the supplier.* events. Suppliers have no storefront
+      # serializer — a customer never sees who the merchant buys from — so the
+      # event shape is declared here rather than found by convention.
+      class SupplierEventSerializer < Admin::SupplierSerializer
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      # The buyer's own tax registration. Deliberately just the kind and the
+      # number: the validation verdict is the platform's bookkeeping, and showing
+      # a customer that their number came back unverified invites support
+      # tickets about a check they cannot influence.
+      class TaxIdentifierSerializer < BaseSerializer
+        typelize kind: [:string, comment: 'Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more.'], value: :string
+
+        attributes :kind, :value
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      # A single tax charge (typed row) on a line item, fulfillment or fee.
+      class TaxLineSerializer < BaseSerializer
+        typelize label: :string, rate: :string, included: :boolean,
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true],
+                 tax_rate_id: [:string, nullable: true], line_item_id: [:string, nullable: true],
+                 fulfillment_id: [:string, nullable: true], fee_id: [:string, nullable: true]
+
+        attributes :label, :included
+
+        attribute :rate do |record|
+          record.rate&.to_s
+        end
+
+        attribute :tax_rate_id do |record|
+          record.tax_rate&.prefixed_id
+        end
+
+        attribute :line_item_id do |record|
+          record.line_item&.prefixed_id
+        end
+
+        attribute :fulfillment_id do |record|
+          record.fulfillment&.prefixed_id
+        end
+
+        attribute :fee_id do |record|
+          record.fee&.prefixed_id
+        end
+
+        money_attributes :amount, :display_amount
+      end
+    end
+  end
+end

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

@@ -10,8 +10,12 @@ module Spree
                  purchasable: :boolean, in_stock: :boolean, backorderable: :boolean, preorder: :boolean,
                  preorder_ships_at: [:string, nullable: true],
                  weight: [:number, nullable: true], height: [:number, nullable: true], width: [:number, nullable: true], depth: [:number, nullable: true],
+                 weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS], dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS],
                  price: 'Price',
-                 original_price: ['Price', nullable: true]
+                 original_price: ['Price', nullable: true],
+                 minimum_order_quantity: :number, order_multiple: :number,
+                 purchase_unit: [:string, enum: Spree::Variant::PURCHASE_UNITS], units_per_carton: ['number | null'],
+                 seller_id: [:string, nullable: true]
 
         attribute :product_id do |variant|
           variant.product&.prefixed_id
@@ -62,6 +66,37 @@ module Spree
           variant.depth&.to_f
         end
 
+        # Resolved, not the raw columns: a variant that states no unit of its
+        # own is measured in the store's, so the numbers above are meaningless
+        # without this. Always present for the same reason the quantity rules
+        # below are — a caller should not have to fetch the store to read a
+        # weight.
+        attribute :weight_unit, &:weight_unit
+
+        attribute :dimensions_unit, &:dimensions_unit
+
+        # The buyer's RESOLVED rules — their catalog terms over the variant's
+        # base — so a storefront draws the right stepper without knowing
+        # which of the two answered. Always present: an unrestricted variant
+        # reads 1 and 1, which is a valid stepper rather than a special case.
+        attribute :minimum_order_quantity do |variant|
+          quantity_rule_for(variant).minimum
+        end
+
+        attribute :order_multiple do |variant|
+          quantity_rule_for(variant).multiple
+        end
+
+        # What the buyer is quoted in. Stored quantities stay units at every
+        # level; this only says how to present them.
+        attribute :purchase_unit do |variant|
+          variant.purchase_unit.presence || 'unit'
+        end
+
+        attribute :units_per_carton do |variant|
+          variant.units_per_carton
+        end
+
         # Price object - calculated price with price list resolution
         attribute :price do |variant|
           price = price_for(variant)
@@ -79,6 +114,21 @@ module Spree
           end
         end
 
+        # Who sells this variant — one answer, resolved on the model, so a
+        # storefront never learns whether it came from the product (an owned
+        # listing) or the row itself (a master shared by several sellers). Nil
+        # is first-party. Shoppers comparing offers on one page group by this,
+        # so it is a plain attribute rather than an expand.
+        attribute :seller_id do |variant|
+          variant.resolved_seller&.prefixed_id
+        end
+
+        one :seller,
+            resource: proc { Spree.api.seller_serializer },
+            if: proc { expand?('seller') } do |variant|
+          variant.resolved_seller
+        end
+
         # Conditional associations
         one :primary_media,
             resource: proc { Spree.api.media_serializer },
@@ -91,7 +141,7 @@ module Spree
 
         many :option_values, resource: proc { Spree.api.option_value_serializer }
 
-        many :public_metafields,
+        many :storefront_custom_fields,
              key: :custom_fields,
              resource: proc { Spree.api.custom_field_serializer },
              if: proc { expand?('custom_fields') }