spree_api 6.0.0.beta4 → 6.0.0.rc1

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

@@ -9,15 +9,19 @@ module Spree
                    key: :string,
                    label: :string,
                    field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
-                   resource_type: [:string, comment: 'Class name of the resource the field attaches to, for example Spree::Product, Spree::Order or Spree::Customer. Extensions may register more.'],
+                   resource_type: [:string, comment: 'Shorthand of the resource the field attaches to, for example product, variant, order, customer or category. Discover the full list from the resource_types endpoint; extensions may register more.'],
                    storefront_visible: :boolean,
                    searchable: :boolean,
                    sortable: :boolean,
                    filter_key: :string
 
-          attributes :namespace, :key, :label, :field_type, :resource_type, :storefront_visible,
+          attributes :namespace, :key, :label, :field_type, :storefront_visible,
                      :searchable, :sortable, :filter_key,
                      created_at: :iso8601, updated_at: :iso8601
+
+          attribute :resource_type do |definition|
+            Spree::Base.polymorphic_api_type(definition.resource_type)
+          end
         end
       end
     end

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

@@ -28,9 +28,7 @@ module Spree
             user.anonymized_at&.iso8601
           end
 
-          attribute :anonymized do |user|
-            user.anonymized?
-          end
+          attribute :anonymized, &:anonymized?
 
           attribute :tags do |user|
             user.tags.map(&:name) # not pluck as we preload tags
@@ -44,13 +42,7 @@ module Spree
             user.respond_to?(:internal_note) ? user.internal_note.presence : nil
           end
 
-          attribute :default_billing_address_id do |user|
-            user.bill_address&.prefixed_id
-          end
-
-          attribute :default_shipping_address_id do |user|
-            user.ship_address&.prefixed_id
-          end
+          prefixed_id_attributes default_billing_address_id: :bill_address, default_shipping_address_id: :ship_address
 
           # Order aggregates: prefer attributes precomputed on the scope (see
           # CustomersController#scope) to avoid N+1 on list endpoints. Fall

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

@@ -19,14 +19,10 @@ module Spree
 
           attributes :email, :error_message, created_at: :iso8601, updated_at: :iso8601
 
-          attribute :customer_id do |data_request|
-            data_request.customer&.prefixed_id
-          end
+          prefixed_id_attributes :customer
 
           # Null when the subject asked for it themselves.
-          attribute :requested_by_id do |data_request|
-            data_request.requested_by&.prefixed_id
-          end
+          prefixed_id_attributes :requested_by
 
           one :customer, resource: proc { Spree.api.admin_customer_serializer }, if: proc { expand?('customer') }
         end

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

@@ -4,8 +4,9 @@ module Spree
       module Admin
         class DeliveryMethodSerializer < V3::DeliveryMethodSerializer
           typelize admin_name: [:string, nullable: true],
-                   fulfillment_provider: :string, pickup_point_provider: [:string, nullable: true],
-                   rate_provider: [:string, nullable: true],
+                   fulfillment_provider: [:string, comment: 'Fulfillment provider. Built-in: manual, digital, pickup, pickup_point. Provider gems register more (e.g. easy_post).'],
+                   pickup_point_provider: [:string, nullable: true, comment: 'Pickup point network. None built in; provider gems register them.'],
+                   rate_provider: [:string, nullable: true, comment: 'Rate provider; null prices through the calculator. Built-in: internal, freight. Provider gems register more (e.g. easy_post).'],
                    storefront_visible: :boolean, tracking_url: [:string, nullable: true],
                    tax_category_id: [:string, nullable: true],
                    delivery_profile_id: :string,
@@ -20,17 +21,14 @@ module Spree
                    seller_id: [:string, nullable: true],
                    seller_name: [:string, nullable: true]
 
-          attributes :admin_name, :fulfillment_provider, :pickup_point_provider,
-                     :rate_provider, :storefront_visible, :tracking_url,
+          attributes :admin_name, :storefront_visible, :tracking_url,
                      :markup_flat, :markup_percent, :available_to_sellers,
                      created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
 
           # Which seller runs this method, so the operator's list can say
           # whose it is. Null is the marketplace's own
           # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
-          attribute :seller_id do |record|
-            record.seller&.prefixed_id
-          end
+          prefixed_id_attributes :seller
 
           attribute :seller_name do |record|
             record.seller&.name
@@ -42,26 +40,14 @@ module Spree
           # eligibility without a request per method.
           many :delivery_method_rules, key: :rules, resource: proc { Spree.api.admin_delivery_method_rule_serializer }
 
-          attribute :tax_category_id do |record|
-            record.tax_category&.prefixed_id
-          end
-
-          attribute :delivery_profile_id do |record|
-            record.delivery_profile&.prefixed_id
-          end
-
-          attribute :delivery_origin_group_id do |record|
-            record.delivery_origin_group&.prefixed_id
-          end
-
-          attribute :delivery_zone_id do |record|
-            record.delivery_zone&.prefixed_id
-          end
+          prefixed_id_attributes :tax_category, :delivery_profile, :delivery_origin_group, :delivery_zone
 
           attribute :stock_location_ids do |record|
             record.pickup_locations.map(&:prefixed_id)
           end
 
+          api_type_attributes :fulfillment_provider, :pickup_point_provider, :rate_provider
+
           attribute :calculator_type do |record|
             record.calculator&.class&.api_type
           end

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

@@ -11,9 +11,7 @@ module Spree
           attributes :name, :position,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :delivery_profile_id do |record|
-            record.delivery_profile&.prefixed_id
-          end
+          prefixed_id_attributes :delivery_profile
 
           # Empty means every store location.
           attribute :stock_location_ids do |record|

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

@@ -10,9 +10,7 @@ module Spree
           # Operational detail, so admin-only.
           attributes :details, created_at: :iso8601, updated_at: :iso8601
 
-          attribute :shipping_label_id do |delivery|
-            delivery.shipping_label&.prefixed_id
-          end
+          prefixed_id_attributes :shipping_label
         end
       end
     end

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

@@ -9,13 +9,7 @@ module Spree
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
-          attribute :delivery_profile_id do |record|
-            record.delivery_profile&.prefixed_id
-          end
-
-          attribute :delivery_origin_group_id do |record|
-            record.delivery_origin_group&.prefixed_id
-          end
+          prefixed_id_attributes :delivery_profile, :delivery_origin_group
 
           attribute :delivery_method_ids do |record|
             record.delivery_methods.map(&:prefixed_id)

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

@@ -10,14 +10,16 @@ module Spree
                    authorized_days: [:number, nullable: true],
                    effective_authorized_clicks: :number,
                    effective_authorized_days: :number,
-                   provider_type: [:string, nullable: true],
+                   provider_type: [:string, nullable: true, comment: 'Digital asset provider; null is an uploaded file. Built-in: file. Extensions may register more.'],
                    provider_name: [:string, comment: 'Digital asset provider name. Built-in: File. Extensions may register more.'],
                    provider_settings: 'Record<string, unknown>',
                    download_url: [:string, nullable: true]
 
-          attributes :authorized_clicks, :authorized_days, :byte_size, :provider_type, :provider_settings
+          attributes :authorized_clicks, :authorized_days, :byte_size, :provider_settings
           attributes created_at: :iso8601, updated_at: :iso8601
 
+          api_type_attributes :provider_type
+
           # Human-readable source for the admin listing. Blank provider_type is
           # the uploaded-file default, so this reads "File" there.
           attribute :provider_name do |digital_asset|

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

@@ -0,0 +1,19 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class EmailTemplateDraftSerializer < V3::BaseSerializer
+          typelize subject: [:string, nullable: true],
+                   body: :string,
+                   lock_version: :number,
+                   updated_by_id: [:string, nullable: true],
+                   updated_by_type: [:string, nullable: true, enum: Spree::Actor::BUILT_IN_KINDS, enum_type_name: 'ActorKind']
+
+          attributes :subject, :body, :lock_version, created_at: :iso8601, updated_at: :iso8601
+
+          actor_attributes :updated_by
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A rendered preview of an email template, with the variables it was
+        # rendered with, as example values for the editor.
+        class EmailTemplatePreviewSerializer < V3::BaseSerializer
+          typelize id: [:string, nullable: true],
+                   subject: :string,
+                   html: :string,
+                   text: :string,
+                   email_key: :string,
+                   variables: 'Record<string, unknown>'
+
+          attribute :subject do |preview|
+            preview.rendered.subject
+          end
+
+          attribute :html do |preview|
+            preview.rendered.html
+          end
+
+          attribute :text do |preview|
+            preview.rendered.text
+          end
+
+          # The email the preview renders: the template itself, or for the
+          # layout and partials, the email shown around them.
+          attribute :email_key do |preview|
+            preview.email.key.tr('/', '.')
+          end
+
+          attribute :variables, &:variables
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class EmailTemplateRevisionSerializer < V3::BaseSerializer
+          typelize subject: [:string, nullable: true],
+                   body: :string,
+                   published_by_id: [:string, nullable: true],
+                   published_by_type: [:string, nullable: true, enum: Spree::Actor::BUILT_IN_KINDS, enum_type_name: 'ActorKind']
+
+          attributes :subject, :body, created_at: :iso8601
+
+          actor_attributes :published_by
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class EmailTemplateSampleRecordSerializer < V3::BaseSerializer
+          typelize label: :string, created_at: :string
+
+          attributes :label, created_at: :iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # An editable email template for one language: what customers receive
+        # now (the store's published version, else Spree's default), Spree's
+        # default, and the draft in progress.
+        class EmailTemplateSerializer < V3::BaseSerializer
+          typelize key: :string,
+                   kind: [:string, enum: Spree::Emails::EditableTemplates::KINDS.map(&:to_s)],
+                   language: :string,
+                   customized: :boolean,
+                   customized_languages: [:string, multi: true],
+                   subject: [:string, nullable: true],
+                   body: :string,
+                   published_at: [:string, nullable: true],
+                   published_language: [:string, nullable: true],
+                   default_subject: [:string, nullable: true],
+                   default_body: :string,
+                   default_changed: :boolean,
+                   base_subject: [:string, nullable: true],
+                   base_body: [:string, nullable: true],
+                   draft: ['EmailTemplateDraft', nullable: true]
+
+          attributes :key, :subject, :body
+
+          # A language code, or `any` for the version every language uses.
+          attribute :language, &:locale
+
+          attribute :customized_languages, &:customized_locales
+
+          attribute :kind do |entry|
+            entry.kind.to_s
+          end
+
+          attribute :customized, &:customized?
+
+          attribute :published_at do |entry|
+            entry.published&.published_at&.iso8601
+          end
+
+          attributes :default_subject, :default_body
+
+          # `any` when this language has no version of its own and customers
+          # receive the one for every language.
+          attribute :published_language, &:published_locale
+
+          attribute :default_changed do |entry|
+            entry.outdated_version.present?
+          end
+
+          # The default the store's version started from, when Spree's default
+          # has changed since: compare it with `default_body` to see what changed.
+          attributes :base_subject, :base_body
+
+          one :draft, resource: proc { Spree.api.admin_email_template_draft_serializer }
+        end
+      end
+    end
+  end
+end

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

@@ -13,9 +13,7 @@ module Spree
 
           attributes :memo, :metadata, created_at: :iso8601, updated_at: :iso8601
 
-          attribute :stock_location_id do |exchange|
-            exchange.stock_location&.prefixed_id
-          end
+          prefixed_id_attributes :stock_location
 
           actor_attributes :created_by
 

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

@@ -23,13 +23,7 @@ module Spree
           # it — whose it is. A null `seller_id` means the operator's own.
           # The name rides along so the list can show who without a second
           # request per row.
-          attribute :store_id do |export|
-            export.store&.prefixed_id
-          end
-
-          attribute :seller_id do |export|
-            export.seller&.prefixed_id
-          end
+          prefixed_id_attributes :store, :seller
 
           attribute :seller_name do |export|
             export.seller&.name

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

@@ -17,13 +17,7 @@ module Spree
 
           attributes :quantity, :status
 
-          attribute :variant_id do |item|
-            item.variant&.prefixed_id
-          end
-
-          attribute :line_item_id do |item|
-            item.line_item&.prefixed_id
-          end
+          prefixed_id_attributes :variant, :line_item
 
           attribute :name do |item|
             item.variant&.product&.name

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

@@ -23,13 +23,7 @@ module Spree
           attributes :metadata, :adjustment_total, :pre_tax_amount,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :order_id do |fulfillment|
-            fulfillment.order&.prefixed_id
-          end
-
-          attribute :stock_location_id do |fulfillment|
-            fulfillment.stock_location&.prefixed_id
-          end
+          prefixed_id_attributes :order, :stock_location
 
           # Customs forms and other paperwork the provider produced beside the
           # label; the labels themselves are listed under +labels+.

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

@@ -24,13 +24,7 @@ module Spree
             params[:gift_card_codes] ? gift_card.display_code : gift_card.masked_code
           end
 
-          attribute :customer_id do |gift_card|
-            gift_card.customer&.prefixed_id
-          end
-
-          attribute :created_by_id do |gift_card|
-            gift_card.created_by&.prefixed_id
-          end
+          prefixed_id_attributes :customer, :created_by
 
           # Customer the card was issued to. Gated behind `expand?` to keep
           # the list payload thin — the SPA's list view passes

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

@@ -44,9 +44,7 @@ module Spree
           # Empty on a shop-price or hand-negotiated line. Names ride along
           # beside the ids so a page of lines does not cost a request each to
           # label, as `company_name` already does.
-          attribute :price_list_id do |line_item|
-            line_item.price_list&.prefixed_id
-          end
+          prefixed_id_attributes :price_list
 
           attribute :price_list_name do |line_item|
             line_item.price_list&.name
@@ -64,9 +62,7 @@ module Spree
             line_item.cost_price&.to_s
           end
 
-          attribute :tax_category_id do |line_item|
-            line_item.tax_category&.prefixed_id
-          end
+          prefixed_id_attributes :tax_category
 
           # Override inherited associations to use admin serializers
           many :option_values, resource: proc { Spree.api.admin_option_value_serializer }

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

@@ -3,11 +3,13 @@ module Spree
     module V3
       module Admin
         class MarketSerializer < V3::MarketSerializer
-          typelize tax_provider: [:string, nullable: true]
+          typelize tax_provider: [:string, nullable: true, comment: 'Tax provider; null uses the store default. Built-in: internal. Provider gems register more.']
+
+          attributes created_at: :iso8601, updated_at: :iso8601
 
           # Which tax engine computes for this market. Nil means the store-wide
           # default; the selectable values come from /admin/tax_providers.
-          attributes :tax_provider, created_at: :iso8601, updated_at: :iso8601
+          api_type_attributes :tax_provider
 
           many :countries,
                resource: proc { Spree.api.admin_country_serializer },

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

@@ -57,9 +57,7 @@ module Spree
             asset.attachment_blob&.signed_id
           end
 
-          attribute :viewable_id do |asset|
-            asset.viewable&.prefixed_id
-          end
+          prefixed_id_attributes :viewable
 
           # Forces Content-Disposition: attachment so admins downloading from
           # cloud storage (S3) get a save-as instead of an inline view. Mirrors

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

@@ -19,9 +19,7 @@ module Spree
 
           # 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
+          attribute :can_be_deleted, &:can_be_deleted?
         end
       end
     end

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

@@ -17,9 +17,7 @@ module Spree
                    store_owner_notification_delivered: :boolean,
                    created_at: :string, updated_at: :string
 
-          attribute :customer_id do |group|
-            group.customer&.prefixed_id
-          end
+          prefixed_id_attributes :customer
 
           attribute :cart_id do |group|
             Spree::Cart.prefixed_id_for(group.cart_id)
@@ -28,13 +26,9 @@ module Spree
           # How many sellers this checkout reached — the operator's headline
           # question about a group, and cheaper than counting the orders client
           # side once a group is large.
-          attribute :seller_count do |group|
-            group.seller_count
-          end
+          attributes :seller_count
 
-          attribute :includes_first_party do |group|
-            group.includes_first_party?
-          end
+          attribute :includes_first_party, &:includes_first_party?
 
           # A split checkout is confirmed once, from here — every child order
           # places silently, so their own flags are false and only the group

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

@@ -22,9 +22,7 @@ module Spree
             rule.class.api_type
           end
 
-          attribute :channel_id do |rule|
-            rule.channel&.prefixed_id
-          end
+          prefixed_id_attributes :channel
 
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema

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

@@ -74,9 +74,7 @@ module Spree
                      canceled_at: :iso8601, approved_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :preferred_stock_location_id do |order|
-            order.preferred_stock_location&.prefixed_id
-          end
+          prefixed_id_attributes :preferred_stock_location
 
           # Our own endpoint rather than a pre-signed storage URL: the
           # controller streams the bytes, so admin auth runs on every download
@@ -90,9 +88,7 @@ module Spree
           # Which company node the order is for, so the dashboard can show and
           # change it. Read back from the column rather than #resolved_company:
           # a placed order must report what it was stamped with.
-          attribute :company_id do |order|
-            order.company&.prefixed_id
-          end
+          prefixed_id_attributes :company
 
           attribute :company_name do |order|
             order.company&.name
@@ -100,9 +96,7 @@ module Spree
 
           # Whose sale this is — nil on the operator's own goods. The full
           # profile is `?expand=seller`.
-          attribute :seller_id do |order|
-            order.seller&.prefixed_id
-          end
+          prefixed_id_attributes :seller
 
           one :seller,
               resource: proc { Spree.api.admin_seller_serializer },
@@ -136,9 +130,7 @@ module Spree
           # secret key names the key.
           actor_attributes :approver, :canceler, :created_by
 
-          attribute :cancel_reason_id do |order|
-            order.cancel_reason&.prefixed_id
-          end
+          prefixed_id_attributes :cancel_reason
 
           # The reason's name alongside its id, so an order list can show why
           # each canceled order was called off without expanding a record per
@@ -147,9 +139,7 @@ module Spree
             order.cancel_reason&.name
           end
 
-          attribute :customer_id do |order|
-            order.customer&.prefixed_id
-          end
+          prefixed_id_attributes :customer
 
           # Override inherited associations to use admin serializers
           # Renamed from the store's `discounts` key: on the admin surface that

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

@@ -39,9 +39,7 @@ module Spree
           # Whose packaging this is: a seller's own, or (null) the
           # marketplace's shared vocabulary
           # (docs/plans/6.0-seller-package-types.md).
-          attribute :seller_id do |package_type|
-            package_type.seller&.prefixed_id
-          end
+          prefixed_id_attributes :seller
 
           attribute :seller_name do |package_type|
             package_type.seller&.name

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

@@ -11,7 +11,10 @@ module Spree
                    position: :number,
                    metadata: 'Record<string, unknown>',
                    preferences: 'Record<string, unknown>',
-                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>",
+                   logo_url: [:string, nullable: true],
+                   docs_url: [:string, nullable: true],
+                   third_party: :boolean
 
           # Null capture_method means the method inherits from its store;
           # resolved_capture_method is what actually applies, so the dashboard
@@ -22,6 +25,9 @@ module Spree
 
           attribute :preferences, &:serialized_preferences
           attribute :preference_schema, &:serialized_preference_schema
+          attribute(:logo_url) { |payment_method| payment_method.class.logo_url }
+          attribute(:docs_url) { |payment_method| payment_method.class.docs_url }
+          attribute(:third_party) { |payment_method| payment_method.class.third_party? }
         end
       end
     end

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

@@ -17,13 +17,8 @@ module Spree
           attributes :metadata, :avs_response, :cvv_response_code, :cvv_response_message,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :captured_amount do |payment|
-            payment.captured_amount.to_s
-          end
-
-          attribute :order_id do |payment|
-            payment.order&.prefixed_id
-          end
+          attributes captured_amount: :string
+          prefixed_id_attributes :order
 
           # Override inherited associations to use admin serializers
           one :payment_method, resource: proc { Spree.api.admin_payment_method_serializer }, if: proc { expand?('payment_method') }