spree_api 5.6.1 → 6.0.0.beta2

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

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