spree_api 5.6.1 → 6.0.0.beta1

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

@@ -6,18 +6,51 @@ module Spree
         # Full product data including admin-only fields
         # Extends the store serializer with additional attributes
         class ProductSerializer < V3::ProductSerializer
+          include Concerns::ExternalReferencesAttribute
+
           include Spree::Api::V3::Admin::Translatable
 
-          typelize status: :string,
+          typelize status: [:string, enum: Spree::Product.statuses, enum_type_name: 'ProductStatus'],
                    tax_category_id: [:string, nullable: true],
+                   product_type_id: [:string, nullable: true],
+                   delivery_profile_id: [:string, nullable: true],
+                   seller_name: [:string, nullable: true],
                    price: ['Price', nullable: true],
                    deleted_at: [:string, nullable: true],
-                   metadata: 'Record<string, unknown>'
+                   metadata: 'Record<string, unknown>',
+                   submission: ['ProductSubmission', nullable: true]
 
           attributes :status,
                      :metadata, deleted_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
+          attribute :delivery_profile_id do |product|
+            product.delivery_profile&.prefixed_id
+          end
+
+          # The live row in the review trail: who submitted, who decided,
+          # when, and what the seller was told. Expanded rather than always
+          # sent — it is a per-product query that the index has no use for.
+          one :latest_submission,
+              key: :submission,
+              resource: proc { Spree.api.admin_product_submission_serializer },
+              if: proc { expand?('submission') }
+
+          # `seller_id` comes from the store serializer. The name rides along
+          # so the products list can show who sells a row without expanding —
+          # the full profile is `?expand=seller`.
+          attribute :seller_name do |product|
+            product.seller&.name
+          end
+
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') }
+
+          attribute :product_type_id do |product|
+            product.product_type&.prefixed_id
+          end
+
           attribute :tax_category_id do |product|
             product.tax_category&.prefixed_id
           end
@@ -55,6 +88,12 @@ module Spree
                resource: proc { Spree.api.admin_media_serializer },
                if: proc { expand?('media') }
 
+          # Read/write symmetry: the product accepts inline `digital_assets` on
+          # create, so it exposes them (opt-in via ?expand=digital_assets).
+          many :digital_assets,
+               resource: proc { Spree.api.admin_digital_asset_serializer },
+               if: proc { expand?('digital_assets') }
+
           many :option_types,
                resource: proc { Spree.api.admin_option_type_serializer },
                if: proc { expand?('option_types') }
@@ -63,16 +102,19 @@ module Spree
                resource: proc { Spree.api.admin_option_value_serializer },
                if: proc { expand?('option_values') }
 
-          many :taxons,
-               proc { |taxons, params|
-                 taxons.select { |t| t.taxonomy.store_id == params[:store].id }
+          many :categories,
+               proc { |categories, params|
+                 store_id = params[:store].id
+                 categories.select { |c| c.store_id == store_id }
                },
-               key: :categories,
                resource: proc { Spree.api.admin_category_serializer },
                if: proc { expand?('categories') }
 
-          many :metafields,
-               key: :custom_fields,
+          many :collections,
+               resource: proc { Spree.api.admin_collection_serializer },
+               if: proc { expand?('collections') }
+
+          many :custom_fields,
                resource: proc { Spree.api.admin_custom_field_serializer },
                if: proc { expand?('custom_fields') }
 
@@ -83,6 +125,10 @@ module Spree
           many :channels,
                resource: proc { Spree.api.admin_channel_serializer },
                if: proc { expand?('channels') }
+
+          one :product_type,
+              resource: proc { Spree.api.admin_product_type_serializer },
+              if: proc { expand?('product_type') }
         end
       end
     end

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A seller's request to put a product on sale, and what the
+        # marketplace made of it. Extends the seller's own view with who
+        # decided — the part only the operator sees.
+        class ProductSubmissionSerializer < V3::Seller::ProductSubmissionSerializer
+          typelize submitted_by_id: [:string, nullable: true],
+                   reviewed_by_id: [:string, nullable: true],
+                   reviewed_by_name: [:string, nullable: true],
+                   auto_approved: :boolean,
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :metadata, updated_at: :iso8601
+
+          attribute :submitted_by_id do |submission|
+            submission.submitted_by&.prefixed_id
+          end
+
+          attribute :reviewed_by_id do |submission|
+            submission.reviewed_by&.prefixed_id
+          end
+
+          # An operator reading the trail wants a name, not an id to resolve.
+          attribute :reviewed_by_name do |submission|
+            submission.reviewed_by&.name
+          end
+
+          # Distinguishes "the store approves listings automatically" from a
+          # decision whose author we failed to record.
+          attribute :auto_approved do |submission|
+            submission.auto_approved?
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/product_type_custom_field_definition_serializer.rb

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A custom field definition as used by one product type: the definition's
+        # own schema fields, plus how this type uses it (required, sort order).
+        #
+        # `id` is the definition's prefixed id (`cfdef_…`), not the join row's —
+        # that is what clients send back on PATCH.
+        class ProductTypeCustomFieldDefinitionSerializer < BaseSerializer
+          typelize id: :string,
+                   key: :string,
+                   namespace: :string,
+                   label: :string,
+                   field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
+                   required: :boolean,
+                   sort_order: :number
+
+          attribute :id do |join|
+            join.custom_field_definition.prefixed_id
+          end
+
+          attribute :key do |join|
+            join.custom_field_definition.key
+          end
+
+          attribute :namespace do |join|
+            join.custom_field_definition.namespace
+          end
+
+          attribute :label do |join|
+            join.custom_field_definition.label
+          end
+
+          attribute :field_type do |join|
+            join.custom_field_definition.field_type
+          end
+
+          attributes :required, :sort_order
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ProductTypeSerializer < V3::ProductTypeSerializer
+          include Spree::Api::V3::Admin::Translatable
+
+          typelize delivery_profile_id: [:string, nullable: true],
+                   products_count: :number,
+                   option_type_ids: [:string, multi: true],
+                   category_ids: [:string, multi: true]
+
+          attributes :products_count,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # The creation-time template: stamped onto products at creation,
+          # never synced afterwards.
+          attribute :delivery_profile_id do |record|
+            record.delivery_profile&.prefixed_id
+          end
+
+          # Prefixed ids of the option types and categories this type seeds onto
+          # new products — the same payload the client sends back on PATCH.
+          attribute :option_type_ids, &:option_type_prefixed_ids
+          attribute :category_ids, &:category_prefixed_ids
+
+          many :product_type_custom_field_definitions,
+               key: :custom_field_definitions,
+               resource: proc { Spree.api.admin_product_type_custom_field_definition_serializer }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/promotion_action_serializer.rb

@@ -9,12 +9,11 @@ module Spree
         # single component can render any subclass — `preferences` is the
         # current value hash, `preference_schema` describes its fields.
         class PromotionActionSerializer < BaseSerializer
-          typelize type: :string,
+          typelize type: [:string, comment: 'Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more.'],
                    promotion_id: :string,
                    preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown }>",
-                   label: :string,
-                   calculator: "{ type: string; label: string; preferences: Record<string, unknown>; preference_schema: Array<{ key: string; type: string; default: unknown }> } | null",
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>",
+                   calculator: "{ type: string; preferences: Record<string, unknown>; preference_schema: Array<{ key: string; type: string; default: unknown }> } | null",
                    line_items: 'Array<{ variant_id: string; quantity: number }> | null'
 
           attributes created_at: :iso8601, updated_at: :iso8601
@@ -30,22 +29,17 @@ module Spree
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema
 
-          attribute :label do |action|
-            action.respond_to?(:human_name) ? action.human_name : action.type.to_s.demodulize
-          end
-
           # Calculator is exposed as a nested object so the SPA can render
           # the calculator picker + its own preference fields. Null for
-          # actions that don't include CalculatedAdjustments. The SPA
-          # formats the row summary itself off `label` + `preferences` —
-          # see the action-summary helper in the admin promotion editor.
+          # actions that don't include CalculatedAdjustments. The SPA names
+          # the calculator from its `type` and formats the row summary off
+          # `preferences` — see the action-summary helper in the promotion editor.
           attribute :calculator do |action|
             next nil unless action.respond_to?(:calculator) && action.calculator
 
             calc = action.calculator
             {
               type: calc.class.api_type,
-              label: calc.class.respond_to?(:description) ? calc.class.description : calc.class.to_s.demodulize.titleize,
               preferences: calc.serialized_preferences,
               preference_schema: calc.serialized_preference_schema
             }

data/app/serializers/spree/api/v3/admin/promotion_rule_serializer.rb

@@ -8,14 +8,14 @@ module Spree
         # admin promotion editor. Same shape as PromotionAction so the
         # frontend renders both with the same generic component.
         class PromotionRuleSerializer < BaseSerializer
-          typelize type: :string,
+          typelize type: [:string, comment: 'Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more.'],
                    promotion_id: :string,
                    preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown }>",
-                   label: :string,
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>",
                    product_ids: 'Array<string> | null',
                    category_ids: 'Array<string> | null',
-                   customer_ids: 'Array<string> | null'
+                   customer_ids: 'Array<string> | null',
+                   option_value_ids: 'Array<string> | null'
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
@@ -30,10 +30,6 @@ module Spree
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema
 
-          attribute :label do |rule|
-            rule.respond_to?(:human_name) ? rule.human_name : rule.class.to_s.demodulize
-          end
-
           # Association IDs for rules that wire products/taxons/users through
           # join tables. Returned as prefixed IDs to match the rest of the
           # API; null on rules that don't have the association. The matching
@@ -45,13 +41,17 @@ module Spree
           end
 
           attribute :category_ids do |rule|
-            rule.taxons.map(&:prefixed_id) if rule.respond_to?(:taxons)
+            rule.categories.map(&:prefixed_id) if rule.respond_to?(:categories)
           end
 
           attribute :customer_ids do |rule|
             rule.users.map(&:prefixed_id) if rule.respond_to?(:users)
           end
 
+          attribute :option_value_ids do |rule|
+            rule.option_values.map(&:prefixed_id) if rule.respond_to?(:option_values)
+          end
+
           # Embed the related records so promotion-row summaries can render
           # names + extra info without a separate fetch. Rules that don't
           # carry a given collection (e.g. an ItemTotal rule has no
@@ -61,15 +61,13 @@ module Spree
                resource: proc { Spree.api.admin_product_serializer },
                if: proc { |rule| rule.respond_to?(:products) }
 
-          many :taxons,
-               key: :categories,
+          many :categories,
                resource: proc { Spree.api.admin_category_serializer },
-               if: proc { |rule| rule.respond_to?(:taxons) }
+               if: proc { |rule| rule.respond_to?(:categories) }
 
-          many :users,
-               key: :customers,
+          many :customers,
                resource: proc { Spree.api.admin_customer_serializer },
-               if: proc { |rule| rule.respond_to?(:users) }
+               if: proc { |rule| rule.respond_to?(:customers) }
 
           many :customer_groups,
                resource: proc { Spree.api.admin_customer_group_serializer },
@@ -86,6 +84,10 @@ module Spree
           many :markets,
                resource: Spree.api.admin_market_serializer,
                if: proc { |rule| rule.respond_to?(:markets) }
+
+          many :option_values,
+               resource: proc { Spree.api.admin_option_value_serializer },
+               if: proc { |rule| rule.respond_to?(:option_values) }
         end
       end
     end

data/app/serializers/spree/api/v3/admin/purchase_order_item_serializer.rb

@@ -0,0 +1,80 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One SKU on a purchase order, with the price the merchant agreed to.
+        class PurchaseOrderItemSerializer < V3::BaseSerializer
+          typelize quantity_ordered: :number,
+                   quantity_received: :number,
+                   quantity_rejected: :number,
+                   quantity_over: :number,
+                   outstanding: :number,
+                   unit_cost: :string,
+                   display_unit_cost: :string,
+                   total_cost: :string,
+                   display_total_cost: :string,
+                   currency: 'string | null',
+                   purchase_order_id: 'string | null',
+                   thumbnail_url: 'string | null',
+                   product_id: 'string | null',
+                   variant_id: 'string | null',
+                   variant_name: 'string | null',
+                   variant_sku: 'string | null',
+                   options_text: 'string | null'
+
+          attributes :quantity_ordered, :quantity_received, :quantity_rejected, :quantity_over,
+                     :outstanding, :currency,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # Money on the wire is a decimal string: a float would round the
+          # merchant's own figure.
+          attribute :unit_cost do |item|
+            item.unit_cost&.to_s
+          end
+
+          attribute :total_cost do |item|
+            item.total_cost.to_s
+          end
+
+          attribute :display_unit_cost do |item|
+            item.display_unit_cost.to_s
+          end
+
+          attribute :display_total_cost do |item|
+            item.display_total_cost.to_s
+          end
+
+          attribute :purchase_order_id do |item|
+            Spree::PurchaseOrder.prefixed_id_for(item.purchase_order_id)
+          end
+
+          attribute :variant_id do |item|
+            item.variant&.prefixed_id
+          end
+
+          # The product the line's variant belongs to, so a line can link
+          # straight to the screen where that SKU's stock lives.
+          attribute :product_id do |item|
+            item.variant&.product&.prefixed_id
+          end
+
+          attribute :variant_name do |item|
+            item.variant&.product&.name
+          end
+
+          attribute :variant_sku do |item|
+            item.variant&.sku
+          end
+
+          attribute :options_text do |item|
+            item.variant&.options_text
+          end
+
+          attribute :thumbnail_url do |item|
+            image_url_for(item.thumbnail)
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb

@@ -0,0 +1,94 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Goods bought from a supplier. Admin-only — a purchase order is what
+        # the merchant owes and expects, which no customer ever sees.
+        class PurchaseOrderSerializer < V3::BaseSerializer
+          typelize number: :string,
+                   status: :string,
+                   currency: :string,
+                   reference: 'string | null',
+                   notes: 'string | null',
+                   supplier_id: 'string | null',
+                   destination_location_id: 'string | null',
+                   expected_at: 'string | null',
+                   cancel_by: 'string | null',
+                   closed_short_at: 'string | null',
+                   close_reason: 'string | null',
+                   closed_short: :boolean,
+                   items_count: :number,
+                   quantity_rejected_total: :number,
+                   quantity_ordered_total: :number,
+                   quantity_received_total: :number,
+                   subtotal: :string,
+                   display_subtotal: :string,
+                   editable: :boolean,
+                   ordered_at: 'string | null',
+                   received_at: 'string | null',
+                   metadata: 'Record<string, unknown>'
+
+          attributes :number, :status, :currency, :reference, :notes, :metadata, :close_reason,
+                     :items_count, :quantity_received_total, :quantity_rejected_total,
+                     ordered_at: :iso8601, received_at: :iso8601, closed_short_at: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # A calendar date, not an instant: the day a supplier promised, which
+          # means the same day in every timezone. `yyyy-mm-dd`, which is what
+          # the dashboard's date-only picker both sends and reads. The
+          # `:iso8601` type is for instants and would ask a Date for
+          # millisecond precision it has no argument for.
+          attribute :expected_at do |purchase_order|
+            purchase_order.expected_at&.iso8601
+          end
+
+          # The day after which the merchant no longer wants the goods — a
+          # date for the same reason.
+          attribute :cancel_by do |purchase_order|
+            purchase_order.cancel_by&.iso8601
+          end
+
+          attribute :closed_short, &:closed_short?
+
+          # Named for the merchant's own vocabulary — a purchase order orders,
+          # a transfer ships — over the concern's neutral `quantity_expected`.
+          attribute :quantity_ordered_total, &:quantity_expected_total
+
+          attribute :editable, &:editable?
+
+          attribute :subtotal do |purchase_order|
+            purchase_order.subtotal.to_s
+          end
+
+          attribute :display_subtotal do |purchase_order|
+            purchase_order.display_subtotal.to_s
+          end
+
+          attribute :supplier_id do |purchase_order|
+            purchase_order.supplier&.prefixed_id
+          end
+
+          attribute :destination_location_id do |purchase_order|
+            purchase_order.destination_location&.prefixed_id
+          end
+
+          many :items,
+               resource: proc { Spree.api.admin_purchase_order_item_serializer },
+               if: proc { expand?('items') }
+
+          many :stock_receipts,
+               resource: proc { Spree.api.admin_stock_receipt_serializer },
+               if: proc { expand?('stock_receipts') }
+
+          one :supplier,
+              resource: proc { Spree.api.admin_supplier_serializer },
+              if: proc { expand?('supplier') }
+
+          one :destination_location,
+              resource: proc { Spree.api.admin_stock_location_serializer },
+              if: proc { expand?('destination_location') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/refund_reason_serializer.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: reasons are back-office vocabulary and have no Store API
+        # controller, so there is no store serializer to extend.
+        #
+        # The three reason serializers are deliberately parallel rather than
+        # sharing a base class: Typelizer emits one TS type per serializer, so
+        # a shared parent would publish an abstract `Reason` type into the
+        # admin SDK that no endpoint returns.
+        class RefundReasonSerializer < V3::BaseSerializer
+          typelize name: :string, active: :boolean, can_be_deleted: :boolean
+
+          attributes :name, :active,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # Lets the dashboard hide destructive controls instead of offering a
+          # delete that the model will refuse.
+          attribute :can_be_deleted do |reason|
+            reason.can_be_deleted?
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/refund_serializer.rb

@@ -5,7 +5,6 @@ module Spree
         class RefundSerializer < V3::RefundSerializer
           typelize payment_id: [:string, nullable: true],
                    refund_reason_id: [:string, nullable: true],
-                   reimbursement_id: [:string, nullable: true],
                    metadata: 'Record<string, unknown>'
 
           attributes :metadata,
@@ -14,10 +13,6 @@ module Spree
           one :payment,
               resource: proc { Spree.api.admin_payment_serializer },
               if: proc { expand?('payment') }
-
-          one :reimbursement,
-              resource: proc { Spree.api.admin_reimbursement_serializer },
-              if: proc { expand?('reimbursement') }
         end
       end
     end

data/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb

@@ -0,0 +1,72 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Decorates a Spree::Reporting::Result for the wire: money display
+        # strings, ISO ranges, and dimension hydration (raw group keys become
+        # { id, label, meta } display payloads — see Spree::Reporting::Hydration).
+        class ReportingResultSerializer
+          attr_reader :result, :store, :params
+
+          def initialize(result, store:, params: {})
+            @result = result
+            @store = store
+            @params = params
+          end
+
+          def to_h
+            {
+              meta: result.meta.merge(
+                time_range: iso_range(result.meta[:time_range]),
+                previous_time_range: iso_range(result.meta[:previous_time_range])
+              ),
+              totals: result.totals.to_h { |name, payload| [name, metric_payload(name, payload)] },
+              rows: result.rows.map do |row|
+                {
+                  dimensions: row[:dimensions].to_h { |name, raw| [name, dimension_value(name, raw)] },
+                  metrics: row[:metrics].to_h { |name, payload| [name, metric_payload(name, payload)] }
+                }
+              end
+            }
+          end
+
+          private
+
+          def iso_range(range)
+            return unless range
+
+            { since: range.first.iso8601, until: range.last.iso8601 }
+          end
+
+          def metric_payload(name, payload)
+            output = payload.dup
+            output[:display] = money(payload[:value]) if money_metrics.include?(name)
+            output
+          end
+
+          # Resolved once per response rather than per cell — a 1000-row report
+          # with five metrics would otherwise build 5000 Money objects.
+          def money_metrics
+            @money_metrics ||= result.meta[:metrics].select { |name| Spree.reporting.metrics[name]&.money? }.to_set
+          end
+
+          def currency
+            @currency ||= ::Money::Currency.find(result.meta[:currency])
+          end
+
+          def money(amount)
+            Spree::Money.new(amount, currency: currency).to_s
+          end
+
+          def dimension_value(name, raw)
+            hydration.value(name, raw)
+          end
+
+          def hydration
+            @hydration ||= Spree::Reporting::Hydration.new(result, store: store, params: params)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ReturnLineItemSerializer < V3::ReturnLineItemSerializer
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          one :variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('variant') }
+          one :line_item, resource: proc { Spree.api.admin_line_item_serializer }, if: proc { expand?('line_item') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/return_reason_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ReturnReasonSerializer < V3::ReturnReasonSerializer
+          typelize can_be_deleted: :boolean
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          # Lets the dashboard hide destructive controls instead of offering a
+          # delete that the model will refuse.
+          attribute :can_be_deleted do |reason|
+            reason.can_be_deleted?
+          end
+        end
+      end
+    end
+  end
+end