spree_api 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Customer-facing view of a return. No timestamps, no internal notes,
+      # no staff attribution — see the serializer rules in CLAUDE.md.
+      class ReturnSerializer < BaseSerializer
+        typelize number: :string,
+                 status: [:string, enum: Spree::Return.statuses, enum_type_name: 'ReturnStatus'],
+                 order_id: [:string, nullable: true],
+                 reason_id: [:string, nullable: true],
+                 refund_total: :string,
+                 display_refund_total: :string,
+                 approved_at: [:string, nullable: true],
+                 received_at: [:string, nullable: true],
+                 refunded_at: [:string, nullable: true],
+                 canceled_at: [:string, nullable: true]
+
+        attributes :number, :status
+
+        attribute :order_id do |return_record|
+          return_record.order&.prefixed_id
+        end
+
+        attribute :reason_id do |return_record|
+          return_record.reason&.prefixed_id
+        end
+
+        attribute :refund_total do |return_record|
+          return_record.refund_total.to_s
+        end
+
+        attribute :display_refund_total do |return_record|
+          return_record.display_refund_total.to_s
+        end
+
+        attribute :approved_at do |return_record|
+          return_record.approved_at&.iso8601
+        end
+
+        attribute :received_at do |return_record|
+          return_record.received_at&.iso8601
+        end
+
+        attribute :refunded_at do |return_record|
+          return_record.refunded_at&.iso8601
+        end
+
+        attribute :canceled_at do |return_record|
+          return_record.canceled_at&.iso8601
+        end
+
+        one :reason, resource: proc { Spree.api.return_reason_serializer }, if: proc { expand?('reason') }
+
+        many :return_line_items,
+             resource: proc { Spree.api.return_line_item_serializer },
+             if: proc { expand?('return_line_items') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # This seller's position in one currency (Spree::SellerBalance).
+        #
+        # A computed value rather than a record, so it carries no id.
+        class BalanceSerializer < V3::BaseSerializer
+          typelize currency: :string,
+                   settlement_currency: :string,
+                   converted: :boolean,
+                   earned: :string, display_earned: :string,
+                   payable: :string, display_payable: :string,
+                   paid: :string, display_paid: :string,
+                   balance: :string, display_balance: :string,
+                   pending: :string, display_pending: :string
+
+          _attributes.delete(:id)
+
+          # Two sides when the account settles in another currency: what the
+          # sales were worth, and what the account received once the provider
+          # converted. Never added together.
+          attributes :currency, :settlement_currency
+
+          attribute(:converted) { |balance| balance.converted? }
+
+          %i[earned payable paid balance pending].each do |figure|
+            attribute(figure) { |balance| balance.public_send(figure).to_s }
+            attribute(:"display_#{figure}") { |balance| balance.public_send(:"display_#{figure}").to_s }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One line of a claim — what went wrong, and what is being sent or
+        # refunded to put it right.
+        class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+          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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A claim 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.
+        class ClaimSerializer < V3::ClaimSerializer
+          typelize memo: [:string, nullable: true]
+
+          attributes :memo
+
+          many :claim_line_items,
+               resource: proc { Spree.api.seller_claim_line_item_serializer },
+               if: proc { expand?('claim_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/delivery_method_rule_serializer.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One condition on a seller's delivery method — "orders over $50",
+        # "under 20kg".
+        #
+        # Declared rather than subclassed from the admin serializer, like
+        # every serializer on this branch. `product_ids` is absent: the rules
+        # a seller may use are preference-only (see the seller delivery
+        # methods controller), so no rule here carries an association.
+        class DeliveryMethodRuleSerializer < BaseSerializer
+          typelize type: [:string, comment: 'Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more.'],
+                   active: :boolean,
+                   preferences: 'Record<string, unknown>',
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
+
+          attributes :active
+
+          # Wire shorthand (e.g. `item_total_rule`), matching the types
+          # discovery endpoint.
+          attribute :type do |rule|
+            rule.class.api_type
+          end
+
+          attribute :preferences, &:serialized_preferences
+          attribute :preference_schema, &:serialized_preference_schema
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One of the seller's own ways to ship, or a marketplace method the
+        # operator shares with them.
+        #
+        # Declared on top of the store serializer rather than subclassed from
+        # the admin one, like every serializer on this branch. What it leaves
+        # out is deliberate: `rate_provider`, `fulfillment_provider` and
+        # `pickup_point_provider` are fixed for a seller's method
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13), so a
+        # seller neither sets them nor needs to read them.
+        #
+        # `editable` is what the panel renders a shared marketplace method
+        # read-only by — a seller sees the operator's method so they know what
+        # their goods can already ship with, and cannot change it.
+        class DeliveryMethodSerializer < V3::DeliveryMethodSerializer
+          typelize admin_name: [:string, nullable: true],
+                   storefront_visible: :boolean,
+                   tracking_url: [:string, nullable: true],
+                   editable: :boolean,
+                   delivery_profile_id: [:string, nullable: true],
+                   delivery_zone_id: [:string, nullable: true],
+                   calculator_type: [:string, nullable: true],
+                   calculator_preferences: ['Record<string, unknown>', nullable: true]
+
+          attributes :admin_name, :storefront_visible, :tracking_url,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          many :delivery_method_rules, key: :rules, resource: proc { Spree.api.seller_delivery_method_rule_serializer }
+
+          # False for a marketplace method the operator shares — it is listed
+          # here so the seller can see what already ships their goods, and the
+          # API refuses to write it.
+          attribute :editable do |record|
+            record.seller_id.present?
+          end
+
+          attribute :delivery_profile_id do |record|
+            record.delivery_profile&.prefixed_id
+          end
+
+          attribute :delivery_zone_id do |record|
+            record.delivery_zone&.prefixed_id
+          end
+
+          attribute :calculator_type do |record|
+            record.calculator&.class&.api_type
+          end
+
+          attribute :calculator_preferences do |record|
+            record.calculator.respond_to?(:serialized_preferences) ? record.calculator.serialized_preferences : record.calculator&.preferences
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A delivery profile as a seller picks it: a name, and whether it is
+        # the one a product lands on when they pick none.
+        #
+        # Declared rather than subclassed from the admin serializer, like every
+        # serializer on this branch: which warehouses and methods sit behind a
+        # profile is the marketplace's configuration, not a seller's to read.
+        class DeliveryProfileSerializer < BaseSerializer
+          typelize name: :string, default: :boolean, digital: :boolean
+
+          attributes :name, :default
+
+          # Whether this profile's goods are delivered digitally. A seller's
+          # own method ships by hand, so a digital profile can carry a product
+          # but never one of their methods — the method form filters its
+          # picker on this rather than letting the save fail on a provider
+          # field the seller cannot see.
+          attribute :digital, &:digital?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A priced service one of this seller's parcels could be carried by.
+        #
+        # Declared rather than subclassed from the store's rate, which expands
+        # the delivery method in full: a seller picks between quotes by name
+        # and price, and the method behind one is the operator's arrangement.
+        class DeliveryRateSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   selected: :boolean,
+                   cost: :string,
+                   display_cost: :string,
+                   total: :string,
+                   display_total: :string,
+                   carrier: [:string, nullable: true],
+                   service_level: [:string, nullable: true],
+                   estimated_delivery_date: [:string, nullable: true]
+
+          attributes :name, :selected, :cost, :total,
+                     :carrier, :service_level, :estimated_delivery_date
+
+          attribute :display_cost do |delivery_rate|
+            delivery_rate.display_cost.to_s
+          end
+
+          attribute :display_total do |delivery_rate|
+            delivery_rate.display_total.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class DeliverySerializer < V3::DeliverySerializer
+          typelize shipping_label_id: [:string, nullable: true]
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          attribute :shipping_label_id do |delivery|
+            delivery.shipping_label&.prefixed_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A destination a seller can narrow their own method to.
+        #
+        # Declared rather than subclassed, like every serializer on this
+        # branch. No members: the picker names the zone the marketplace drew,
+        # and which countries and postal ranges make it up is the
+        # marketplace's own configuration.
+        class DeliveryZoneSerializer < BaseSerializer
+          typelize name: :string, description: [:string, nullable: true],
+                   delivery_profile_id: :string
+
+          attributes :name, :description
+
+          # What the panel filters the picker by, so a zone is only offered
+          # under the profile it belongs to.
+          attribute :delivery_profile_id do |record|
+            record.delivery_profile&.prefixed_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One line of an exchange — what came back and what goes out in its
+        # place. Both variants expand through the seller's own serializer.
+        class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+          typelize name: [:string, nullable: true],
+                   new_variant_name: [:string, nullable: true]
+
+          attribute :name do |line|
+            line.line_item&.name || line.original_variant&.name
+          end
+
+          attribute :new_variant_name do |line|
+            line.new_variant&.name
+          end
+
+          one :original_variant, resource: proc { Spree.api.seller_variant_serializer },
+                                 if: proc { expand?('original_variant') }
+          one :new_variant, resource: proc { Spree.api.seller_variant_serializer },
+                            if: proc { expand?('new_variant') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # An exchange 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.
+        class ExchangeSerializer < V3::ExchangeSerializer
+          typelize memo: [:string, nullable: true],
+                   stock_location_id: [:string, nullable: true]
+
+          attributes :memo
+
+          attribute :stock_location_id do |exchange|
+            exchange.stock_location&.prefixed_id
+          end
+
+          many :exchange_line_items,
+               resource: proc { Spree.api.seller_exchange_line_item_serializer },
+               if: proc { expand?('exchange_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/export_serializer.rb

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Seller API serializer for {Spree::Export}.
+        #
+        # Mirrors the operator's, pointed at the seller branch's own download
+        # endpoint: the bytes are streamed by that action rather than handed
+        # over as a pre-signed ActiveStorage URL, so the seller's own session
+        # is what authorizes every download.
+        #
+        # `user_id` is inherited but names the seller's own staff member, and
+        # the marketplace's `results_url` is not exposed — a seller reads the
+        # file, not the operator's bookkeeping about it.
+        class ExportSerializer < V3::ExportSerializer
+          typelize done: :boolean,
+                   download_url: [:string, nullable: true],
+                   filename: [:string, nullable: true],
+                   byte_size: [:number, nullable: true]
+
+          attribute(:done) { |export| export.done? }
+
+          # Safe-nav on `blob` — `attachment.attached?` can stay true while a
+          # background job purges the underlying blob (e.g. retention sweeps).
+          attribute :filename do |export|
+            export.attachment.blob&.filename&.to_s if export.done?
+          end
+
+          attribute :byte_size do |export|
+            export.attachment.blob&.byte_size if export.done?
+          end
+
+          attribute :download_url do |export|
+            next nil unless export.done?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_seller_export_path(
+              id: export.prefixed_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One line inside a parcel: what to pick and how many.
+        #
+        # Two ids, because the two things a seller does with a parcel address
+        # its contents differently: a partial dispatch names line items, and
+        # splitting names the variant being moved.
+        class FulfillmentItemSerializer < V3::BaseSerializer
+          typelize quantity: :number,
+                   line_item_id: [:string, nullable: true],
+                   variant_id: [:string, nullable: true],
+                   name: [:string, nullable: true],
+                   sku: [:string, nullable: true],
+                   options_text: [:string, nullable: true]
+
+          attributes :quantity
+
+          attribute :line_item_id do |item|
+            item.line_item&.prefixed_id
+          end
+
+          attribute :variant_id do |item|
+            item.variant&.prefixed_id
+          end
+
+          attribute :name do |item|
+            item.line_item&.name
+          end
+
+          attribute :sku do |item|
+            item.variant&.sku
+          end
+
+          attribute :options_text do |item|
+            item.line_item&.options_text
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A parcel this seller owes on one of their orders.
+        #
+        # Declared rather than subclassed from the store's fulfillment, whose
+        # stock location serializer is the store's own — the location a seller
+        # cares about is their own shelf, named here rather than expanded.
+        #
+        # The delivery rates quoted for this parcel are here, because a seller
+        # picking from a different shelf needs to see what that origin can be
+        # carried by. A rate carries only its name and its price, so nothing
+        # about the operator's arrangements comes with it.
+        class FulfillmentSerializer < V3::BaseSerializer
+          typelize number: :string,
+                   status: [:string, enum: Spree::Fulfillment.statuses, enum_type_name: 'FulfillmentStatus'],
+                   tracking: [:string, nullable: true],
+                   tracking_url: [:string, nullable: true],
+                   fulfillment_type: [:string, nullable: true],
+                   delivery_method_name: [:string, nullable: true],
+                   stock_location_name: [:string, nullable: true],
+                   stock_location_id: [:string, nullable: true],
+                   selected_delivery_rate_id: [:string, nullable: true]
+
+          attributes :number, :status, :tracking, :tracking_url,
+                     fulfilled_at: :iso8601, delivered_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          typelize delivered_at: [:string, nullable: true]
+
+          # Null until the parcel actually ships, which is most of its life.
+          typelize fulfilled_at: [:string, nullable: true]
+
+          attribute :fulfillment_type do |fulfillment|
+            fulfillment.fulfillment_type.presence || (fulfillment.digital? ? 'digital' : 'shipping')
+          end
+
+          # How it travels and where it leaves from, as names rather than
+          # expanded records: a seller reads them, never edits them here.
+          attribute :delivery_method_name do |fulfillment|
+            fulfillment.delivery_method&.name
+          end
+
+          attribute :stock_location_name do |fulfillment|
+            fulfillment.stock_location&.name
+          end
+
+          # The id as well as the name, so a seller moving the parcel to
+          # another of their shelves can see which one it is on now.
+          attribute :stock_location_id do |fulfillment|
+            fulfillment.stock_location&.prefixed_id
+          end
+
+          # Deliberately not `items`: the store's fulfillment answers with a
+          # manifest under that name, and the shared OpenAPI patch rewrites it
+          # to that shape — a seller's rows would be documented as somebody
+          # else's. These are the persisted fulfillment items, so they say so.
+          many :fulfillment_items,
+               resource: proc { Spree.api.seller_fulfillment_item_serializer }
+
+          # The consignments and labels on this parcel — what a seller adds
+          # when they ship it themselves.
+          attribute :selected_delivery_rate_id do |fulfillment|
+            fulfillment.selected_delivery_rate&.prefixed_id
+          end
+
+          # What this parcel could be carried by from where it currently sits.
+          many :delivery_rates, resource: proc { Spree.api.seller_delivery_rate_serializer }
+
+          many :deliveries, resource: proc { Spree.api.seller_delivery_serializer }
+          many :shipping_labels, key: :labels, resource: proc { Spree.api.seller_shipping_label_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # How one schema field of a seller's import maps onto a column of
+        # their CSV. The `complete_mapping` endpoint accepts exactly these
+        # attribute names back (read/write symmetry).
+        class ImportMappingSerializer < V3::BaseSerializer
+          typelize schema_field: :string,
+                   file_column: [:string, nullable: true],
+                   required: :boolean
+
+          attributes :schema_field, :file_column
+
+          attribute :required, &:required?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One row of a seller's import. Adds the raw CSV row (`data`) so the
+        # failure report can show the values that were rejected.
+        class ImportRowSerializer < V3::ImportRowSerializer
+          typelize data: 'Record<string, string | null>'
+
+          attribute :data do |row|
+            row.data_json
+          end
+        end
+      end
+    end
+  end
+end