spree_api 5.6.1 → 6.0.0.beta1

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

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

@@ -0,0 +1,77 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One of a seller's CSV imports, as their panel's wizard reads it: the
+        # mapping payload while `mapping`, the poll counters afterwards.
+        #
+        # Declared from the store base rather than the admin serializer, like
+        # every serializer on this branch — the two are parallel, and an admin
+        # serializer gaining an operator-only field would otherwise leak it
+        # here. The fields below are the wizard's own working data (what the
+        # seller uploaded, how its columns map, how many rows have landed), so
+        # they are restated rather than inherited.
+        class ImportSerializer < V3::ImportSerializer
+          typelize completed_rows_count: :number,
+                   failed_rows_count: :number,
+                   processing_errors: [:string, nullable: true],
+                   preferred_delimiter: :string,
+                   schema_fields: 'Array<{ name: string; label: string; required: boolean }>',
+                   csv_headers: [:string, multi: true],
+                   sample_row: 'Record<string, string | null>',
+                   original_filename: [:string, nullable: true],
+                   original_byte_size: [:number, nullable: true],
+                   original_file_url: [:string, nullable: true]
+
+          attributes :processing_errors, :preferred_delimiter
+
+          # The file the seller uploaded. `original_file_url` is this branch's
+          # own streaming endpoint (JWT-authenticated), not a signed
+          # ActiveStorage URL — the panel's `/api/*` proxy would not carry one.
+          attribute :original_filename do |import|
+            import.attachment.blob&.filename&.to_s if import.attachment.attached?
+          end
+
+          attribute :original_byte_size do |import|
+            import.attachment.blob&.byte_size if import.attachment.attached?
+          end
+
+          attribute :original_file_url do |import|
+            next nil unless import.attachment.attached?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_seller_import_path(
+              id: import.prefixed_id
+            )
+          end
+
+          attribute :completed_rows_count do |import|
+            import.rows_status_counts['completed'] || 0
+          end
+
+          attribute :failed_rows_count do |import|
+            import.rows_status_counts['failed'] || 0
+          end
+
+          attribute :schema_fields do |import|
+            import.schema_fields.map do |field|
+              { name: field[:name], label: field[:label], required: field[:required].present? }
+            end
+          end
+
+          # Mapping-state only: these read the attached blob, which the 2s
+          # processing poll must never do.
+          attribute :csv_headers do |import|
+            import.mapping? ? (import.csv_headers || []) : []
+          end
+
+          attribute :sample_row do |import|
+            import.mapping? ? import.sample_row : {}
+          end
+
+          many :mappings,
+               resource: proc { Spree.api.seller_import_mapping_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        class InvitationSerializer < V3::BaseSerializer
+          typelize email: :string, status: [:string, enum: Spree::Invitation.statuses, enum_type_name: 'InvitationStatus'],
+                   expires_at: [:string, nullable: true],
+                   accepted_at: [:string, nullable: true],
+                   acceptance_url: :string
+
+          attributes :email,
+                     created_at: :iso8601, expires_at: :iso8601, accepted_at: :iso8601
+
+          attribute :status do |invitation|
+            invitation.status.to_s
+          end
+
+          attribute :acceptance_url do |invitation|
+            if Spree::Config[:seller_panel_url].present? || Spree::Config[:dashboard_url].present?
+              Rails.application.routes.url_helpers.admin_invitation_acceptance_url(invitation)
+            else
+              "/accept-invitation/#{invitation.prefixed_id}?token=#{invitation.token}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A file on a seller's own product.
+        #
+        # Declared from the store base rather than the admin serializer, like
+        # every serializer on this branch. What a seller needs is the file, how
+        # it is cropped, and which variants it belongs to.
+        class MediaSerializer < V3::MediaSerializer
+          typelize position: :number,
+                   variant_ids: [:string, multi: true],
+                   focal_point_x: [:number, nullable: true],
+                   focal_point_y: [:number, nullable: true]
+
+          attributes :position, :focal_point_x, :focal_point_y,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :variant_ids do |media|
+            media.variants.map(&:prefixed_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A line on one of this seller's orders — what to pick, how many, and
+        # what it sold for.
+        #
+        # Declared rather than subclassed from the store's line item: that one
+        # carries the associations a storefront needs (digital links, tax
+        # lines, the seller's own public profile), none of which help someone
+        # packing a box, and each of which would pull another serializer into
+        # this branch's generated types.
+        class OrderLineItemSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   sku: [:string, nullable: true],
+                   options_text: [:string, nullable: true],
+                   quantity: :number,
+                   currency: :string,
+                   variant_id: [:string, nullable: true],
+                   thumbnail_url: [:string, nullable: true],
+                   price: [:string, nullable: true], display_price: [:string, nullable: true],
+                   total: [:string, nullable: true], display_total: [:string, nullable: true]
+
+          attributes :name, :options_text, :quantity, :currency
+
+          money_attributes :price, :display_price, :total, :display_total
+
+          attribute :variant_id do |line_item|
+            line_item.variant&.prefixed_id
+          end
+
+          # How a seller finds the item on their own shelf.
+          attribute :sku do |line_item|
+            line_item.variant&.sku
+          end
+
+          attribute :thumbnail_url do |line_item|
+            image_url_for(line_item.thumbnail)
+          end
+        end
+      end
+    end
+  end
+end