spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,119 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # An order placed with this seller.
+        #
+        # Built from the base rather than the store serializer: that one is
+        # written for the shopper who placed the order, and carries payments —
+        # how the customer paid the marketplace is not the seller's business.
+        # What they are owed overall is still the commission ledger; this
+        # carries only what this one sale was charged.
+        #
+        # The addresses are here because the seller is merchant of record for
+        # their child order (docs/plans/6.0-multi-vendor-marketplace.md): the
+        # shipping address to post the parcel, the billing address because the
+        # invoice for that sale is theirs to issue. Both marketplace platforms
+        # we surveyed give a seller the same two.
+        #
+        # The buyer's email is not. A seller reaching the customer about a
+        # delivery has the phone on the shipping address; an email address is
+        # the one contact detail that lets a marketplace's customer be taken
+        # off it, and it is not needed to pack, post or invoice.
+        class OrderSerializer < V3::BaseSerializer
+          typelize number: :string,
+                   customer_note: [:string, nullable: true],
+                   currency: :string,
+                   total_quantity: :number,
+                   fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
+                   payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
+                   status: [:string, enum: Spree::Order::STATUSES],
+                   item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
+                   delivery_total: [:string, nullable: true], display_delivery_total: [:string, nullable: true],
+                   discount_total: [:string, nullable: true], display_discount_total: [:string, nullable: true],
+                   adjustment_total: [:string, nullable: true], display_adjustment_total: [:string, nullable: true],
+                   included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
+                   additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
+                   tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
+                   total: [:string, nullable: true], display_total: [:string, nullable: true],
+                   payment_total: [:string, nullable: true], display_payment_total: [:string, nullable: true],
+                   amount_due: [:string, nullable: true], display_amount_due: [:string, nullable: true],
+                   commission_amount_total: [:string, nullable: true],
+                   display_commission_amount_total: [:string, nullable: true],
+                   commission_tax_total: [:string, nullable: true],
+                   display_commission_tax_total: [:string, nullable: true],
+                   commission_total: [:string, nullable: true],
+                   display_commission_total: [:string, nullable: true],
+                   canceled_at: [:string, nullable: true],
+                   cancel_reason_name: [:string, nullable: true],
+                   cancel_note: [:string, nullable: true],
+                   internal_note: [:string, nullable: true],
+                   internal_note_html: [:string, nullable: true]
+
+          attributes :number, :customer_note, :currency, :total_quantity,
+                     :status, :fulfillment_status, :payment_status,
+                     completed_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          # The seller's own working note. A marketplace basket is split into
+          # one order per seller, so this row — and the note on it — is theirs
+          # alone; it is never the operator's note about the whole sale.
+          attribute :internal_note do |order|
+            Spree::RichTextHelper.to_plain_text(order.internal_note).presence
+          end
+
+          attribute :internal_note_html do |order|
+            order.internal_note.presence
+          end
+
+          # What this seller is owed for the goods, and what the buyer paid for
+          # them. Deliberately not the whole money surface: gift cards, store
+          # credit and the payment breakdown belong to the marketplace.
+          money_attributes :item_total, :display_item_total,
+                           :delivery_total, :display_delivery_total,
+                           :discount_total, :display_discount_total,
+                           :adjustment_total, :display_adjustment_total,
+                           :included_tax_total, :display_included_tax_total,
+                           :additional_tax_total, :display_additional_tax_total,
+                           :tax_total, :display_tax_total,
+                           :total, :display_total,
+                           :payment_total, :display_payment_total,
+                           :amount_due, :display_amount_due
+
+          # What the marketplace charged the seller on this sale, and the tax
+          # on that charge. The ledger remains where a seller sees what they
+          # are owed overall, but the tax belongs on the order itself: the
+          # commission is a B2B supply from the platform, so this is the
+          # seller's input tax to reclaim, and it has to be attributable to
+          # the sale that produced it.
+          money_attributes :commission_amount_total, :display_commission_amount_total,
+                           :commission_tax_total, :display_commission_tax_total,
+                           :commission_total, :display_commission_total
+
+          # Why the sale was called off, when it was. The reason is the
+          # marketplace's vocabulary, so it is rendered as a name rather than
+          # an id a seller has nothing else to do with.
+          attribute :canceled_at do |order|
+            order.canceled_at&.iso8601
+          end
+
+          attribute :cancel_reason_name do |order|
+            order.cancel_reason&.name
+          end
+
+          attributes :cancel_note
+
+          many :line_items, key: :items, resource: proc { Spree.api.seller_order_line_item_serializer }
+          # This order's share of the basket's payment, on request: the order
+          # page reads it, the list never does. Empty on an order that did not
+          # split — a single-seller basket keeps the payment on the order
+          # itself, and that payment stays the marketplace's.
+          many :payment_splits, resource: proc { Spree.api.seller_payment_split_serializer },
+                                if: proc { expand?('payment_splits') }
+          many :fulfillments, resource: proc { Spree.api.seller_fulfillment_serializer }
+          one :shipping_address, resource: proc { Spree.api.address_serializer }
+          one :billing_address, resource: proc { Spree.api.address_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What a seller packs their goods into: their own boxes, cartons and
+        # pallets, and the marketplace's shared packaging they may also use.
+        #
+        # Declared on `BaseSerializer` rather than on a store twin because
+        # there is none — a shopper never picks their packaging, so package
+        # types exist on the back-office surfaces only.
+        #
+        # `editable` is what the panel renders a marketplace row read-only by,
+        # mirroring the seller's delivery method serializer: a seller sees the
+        # operator's cartons so they know what they can pack into, and the API
+        # refuses to write them (docs/plans/6.0-seller-package-types.md).
+        class PackageTypeSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   kind: [:string, enum: Spree::PackageType::KINDS],
+                   length: [:string, nullable: true],
+                   width: [:string, nullable: true],
+                   height: [:string, nullable: true],
+                   dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS],
+                   weight: [:string, nullable: true],
+                   max_weight: [:string, nullable: true],
+                   weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS],
+                   volume: [:string, nullable: true],
+                   default: :boolean,
+                   editable: :boolean,
+                   metadata: ['Record<string, unknown> | null']
+
+          attributes :name, :kind, :length, :width, :height, :weight, :max_weight,
+                     :default, :metadata
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          # Both units read through their fallbacks, so a row that never set
+          # one still tells the seller what its numbers mean.
+          attribute :dimensions_unit, &:dimensions_unit
+          attribute :weight_unit, &:weight_unit
+
+          attribute :volume, &:volume
+
+          # False for a marketplace row: listed so the seller knows what they
+          # can pack into, and not theirs to change.
+          attribute :editable do |package_type|
+            package_type.seller_id.present?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # This order's share of the payment the buyer made for the whole
+        # basket (Spree::PaymentSplit), as the seller reads it.
+        #
+        # Amounts only. Which payment it is a share of, how the buyer paid and
+        # what the gateway said are the marketplace's — the seller's question
+        # is how much of their order was captured, refunded, and can still be
+        # refunded.
+        class PaymentSplitSerializer < V3::BaseSerializer
+          AMOUNTS = %i[authorized_amount captured_amount refunded_amount claimed_amount
+                       net_captured_amount refundable_amount].freeze
+
+          typelize currency: :string,
+                   authorized_amount: :string, display_authorized_amount: :string,
+                   captured_amount: :string, display_captured_amount: :string,
+                   refunded_amount: :string, display_refunded_amount: :string,
+                   claimed_amount: :string, display_claimed_amount: :string,
+                   net_captured_amount: :string, display_net_captured_amount: :string,
+                   refundable_amount: :string, display_refundable_amount: :string
+
+          attributes :currency, created_at: :iso8601
+
+          AMOUNTS.each do |amount|
+            attribute(amount) { |split| split.public_send(amount).to_s }
+            attribute(:"display_#{amount}") { |split| split.public_send(:"display_#{amount}").to_s }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One settlement to this seller, as the seller reads it.
+        class PayoutSerializer < V3::BaseSerializer
+          typelize status: :string,
+                   currency: :string,
+                   provider: :string,
+                   amount: :string,
+                   display_amount: :string,
+                   reference: 'string | null',
+                   period_start: 'string | null',
+                   period_end: 'string | null',
+                   transfers_count: :number
+
+          attributes :status, :currency, :provider, :reference,
+                     period_start: :iso8601, period_end: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute(:amount) { |payout| payout.amount&.to_s }
+          attribute(:display_amount) { |payout| payout.display_amount.to_s }
+
+          # How many earnings this settlement covers. Read from a count the
+          # controller made for the whole page when there is one; a single
+          # payout read falls back to asking for its own.
+          attribute(:transfers_count) do |payout, params|
+            counts = params && params[:transfer_counts]
+
+            counts ? counts.fetch(payout.id, 0) : payout.transfers.count
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class PolicySerializer < V3::PolicySerializer
+          attributes created_at: :iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A seller's own product.
+        #
+        # Read and write have to name the same fields: the panel loads a
+        # product into a form and sends it back, so anything the controller
+        # accepts but this withholds would be blanked on save. The reverse
+        # matters too — how a product is filed (categories, collections, tags)
+        # is the marketplace's own merchandising, so it is neither written nor
+        # read here. The type and the delivery profile are: a seller picks
+        # both from the marketplace's list
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        class ProductSerializer < V3::ProductSerializer
+          typelize status: [:string, enum: Spree::Product.statuses, enum_type_name: 'ProductStatus'], metadata: 'Record<string, unknown>',
+                   product_type_id: [:string, nullable: true],
+                   delivery_profile_id: [:string, nullable: true],
+                   submission: ['ProductSubmission', nullable: true]
+
+          attributes :status, :metadata, created_at: :iso8601, updated_at: :iso8601
+
+          attribute :product_type_id do |product|
+            product.product_type&.prefixed_id
+          end
+
+          attribute :delivery_profile_id do |product|
+            product.delivery_profile&.prefixed_id
+          end
+
+          many :variants,
+               resource: proc { Spree.api.seller_variant_serializer },
+               if: proc { expand?('variants') }
+
+          one :default_variant,
+              resource: proc { Spree.api.seller_variant_serializer },
+              if: proc { expand?('default_variant') }
+
+          many :gallery_media,
+               key: :media,
+               resource: proc { Spree.api.seller_media_serializer },
+               if: proc { expand?('media') }
+
+          many :option_types,
+               resource: proc { Spree.api.option_type_serializer },
+               if: proc { expand?('option_types') }
+
+          # Why the marketplace sent this back, so the panel can show it
+          # against a rejected listing without a second request. Expanded
+          # rather than always sent — it is a per-product query, and the
+          # products list has no use for it.
+          one :latest_submission,
+              key: :submission,
+              resource: proc { Spree.api.product_submission_serializer },
+              if: proc { expand?('submission') }
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A product type as a seller sees it: something to list against, and
+        # what picking it will bring.
+        #
+        # The option types are carried as **labels**, not as ids the client
+        # then resolves. The operator's form looks them up against the option
+        # types page it already loads, but a seller manages no option-type
+        # vocabulary and has no such endpoint — sending ids alone would leave
+        # the form unable to name them, and the warning it exists to show
+        # would silently never appear.
+        #
+        # No `category_ids` (filing is the operator's, so a seller would be
+        # shown a consequence they never see) and no `products_count` or
+        # custom field schema, which describe how the operator maintains the
+        # type rather than what listing against it does.
+        class ProductTypeSerializer < V3::ProductTypeSerializer
+          typelize option_type_labels: [:string, multi: true]
+
+          attribute :option_type_labels do |product_type|
+            product_type.option_types.map { |option_type| option_type.label.presence || option_type.name }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class ProfileSerializer < V3::SellerSerializer
+          typelize status: [:string, enum: Spree::Seller.statuses, enum_type_name: 'SellerStatus'],
+                   legal_name: [:string, nullable: true],
+                   registration_number: [:string, nullable: true],
+                   contact_email: [:string, nullable: true],
+                   billing_email: [:string, nullable: true],
+                   tax_remittance: :string,
+                   payouts_schedule_interval: [:string, nullable: true],
+                   minimum_payout_amount: [:string, nullable: true],
+                   holiday_mode_until: [:string, nullable: true],
+                   terms_accepted_at: [:string, nullable: true],
+                   on_holiday: :boolean, sellable: :boolean,
+                   products_count: :number,
+                   default_currency: :string,
+                   supported_currencies: [:string, multi: true],
+                   preferred_timezone: [:string, nullable: true]
+
+          attributes :preferred_timezone,
+                     :status, :legal_name, :registration_number,
+                     :contact_email, :billing_email,
+                     :tax_remittance, :payouts_schedule_interval,
+                     holiday_mode_until: :iso8601,
+                     terms_accepted_at: :iso8601,
+                     created_at: :iso8601
+
+          attribute :minimum_payout_amount do |seller|
+            seller.minimum_payout_amount&.to_s
+          end
+
+          # Rebound from the inherited store declaration to this branch's own
+          # serializer: a seller reading their own profile gets the seller
+          # shape of a policy (with `created_at`), which is what the seller
+          # SDK's generated type and this branch's OpenAPI schema promise.
+          _attributes.delete(:policies)
+          many :policies,
+               resource: proc { Spree.api.seller_policy_serializer },
+               if: proc { expand?('policies') }
+
+          attribute :on_holiday do |seller|
+            seller.on_holiday?
+          end
+
+          attribute :sellable do |seller|
+            seller.sellable?
+          end
+
+          # What this seller prices in. Theirs by way of the marketplace: a
+          # seller has no currency of their own, so the store's is the answer
+          # to "what does this amount mean".
+          attribute :default_currency do |seller|
+            seller.store&.default_currency
+          end
+
+          attribute :supported_currencies do |seller|
+            seller.store&.supported_currencies_list&.map(&:iso_code) || []
+          end
+
+          attribute :products_count do |seller|
+            seller.products.count
+          end
+
+          one :billing_address,
+              resource: proc { Spree.api.address_serializer },
+              if: proc { |seller| seller.billing_address.present? }
+
+          one :returns_address,
+              resource: proc { Spree.api.address_serializer },
+              if: proc { |seller| seller.returns_address.present? }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One entry of a marketplace-owned vocabulary — why goods came back,
+        # or what went wrong with a delivery.
+        #
+        # One serializer for both, unlike the store and admin branches, which
+        # keep ReturnReason and ClaimReason apart so Typelizer emits a concrete
+        # type per endpoint. Here the two endpoints answer the same shape — a
+        # name and whether it is still offered — and the panel renders them
+        # through one picker, so a single `Reason` type is what the client
+        # actually wants. Read-only, so nothing here is writable.
+        class ReasonSerializer < V3::BaseSerializer
+          typelize name: :string, active: :boolean
+
+          attributes :name, :active
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class RequirementCustomFieldSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize id: :string, key: :string, label: :string,
+                   field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
+                   value: :any
+
+          attribute :id do |pair|
+            pair[:definition].prefixed_id
+          end
+
+          attribute :key do |pair|
+            pair[:definition].full_key
+          end
+
+          attribute :label do |pair|
+            pair[:definition].label
+          end
+
+          attribute :field_type do |pair|
+            pair[:definition].field_type
+          end
+
+          attribute :value do |pair|
+            pair[:custom_field]&.serialize_value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class RequirementStatusSerializer
+          include Alba::Resource
+          include Typelizer::DSL
+
+          typelize id: :string, kind: [:string, comment: 'Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more.'], name: :string,
+                   description: [:string, nullable: true],
+                   required: :boolean, position: :number, status: [:string, enum: Spree::SellerRequirementStatus::STATUSES],
+                   blocking: :boolean, action_url: [:string, nullable: true],
+                   blocker: ['{ state: string; message: string | null } | null'],
+                   accepts_submissions: :boolean, requires_file: :boolean,
+                   accepted_content_types: [:string, multi: true],
+                   required_policy_name: [:string, nullable: true],
+                   terms_html: [:string, nullable: true]
+
+          attributes :id, :kind, :name, :description, :required, :position, :status, :action_url, :blocker
+
+          attribute :blocking do |status|
+            status.blocking?
+          end
+
+          attribute :accepts_submissions do |status|
+            status.requirement.class.accepts_submissions?
+          end
+
+          attribute :requires_file do |status|
+            status.requirement.class.requires_file?
+          end
+
+          attribute :accepted_content_types do |status|
+            status.requirement.accepted_content_types
+          end
+
+          # The document this line asks for, so the panel can offer to create
+          # exactly that policy. Null for every other kind.
+          attribute :required_policy_name do |status|
+            status.required_policy_name
+          end
+
+          # The marketplace terms this line asks the seller to accept. Null
+          # for every other kind, and null while nothing has been written.
+          attribute :terms_html do |status|
+            status.terms_html
+          end
+
+          one :submission,
+              resource: proc { Spree.api.seller_requirement_submission_serializer },
+              if: proc { |status| status.submission.present? }
+
+          many :custom_fields,
+               resource: proc { Spree.api.seller_requirement_custom_field_serializer },
+               if: proc { |status| status.custom_fields.any? } do |status|
+            status.custom_fields
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class RequirementSubmissionSerializer < V3::BaseSerializer
+          typelize status: [:string, enum: Spree::SellerRequirementSubmission.statuses, enum_type_name: 'SellerRequirementSubmissionStatus'], note: [:string, nullable: true],
+                   review_note: [:string, nullable: true],
+                   reference: [:string, nullable: true],
+                   reviewed_at: [:string, nullable: true],
+                   file_url: [:string, nullable: true],
+                   file_name: [:string, nullable: true]
+
+          attributes :status, :note, :review_note, :reference,
+                     reviewed_at: :iso8601,
+                     created_at: :iso8601,
+                     updated_at: :iso8601
+
+          attribute :file_url do |submission|
+            next nil unless submission.file.attached?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_seller_requirement_submission_path(
+              id: submission.prefixed_id
+            )
+          end
+
+          attribute :file_name do |submission|
+            submission.file.attached? ? submission.file.filename.to_s : nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One line of a return.
+        #
+        # Names what came back on the line itself: a variant carries a SKU and
+        # its option values but no product name, so a card built from the
+        # variant alone would show a bare id for anything unSKU'd.
+        class ReturnLineItemSerializer < V3::ReturnLineItemSerializer
+          typelize name: [:string, nullable: true]
+
+          attribute :name do |line|
+            line.line_item&.name || line.variant&.name
+          end
+
+          one :variant, resource: proc { Spree.api.seller_variant_serializer }, if: proc { expand?('variant') }
+        end
+      end
+    end
+  end
+end