spree_api 6.0.0.rc7 → 6.0.1

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

@@ -0,0 +1,72 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::MaintenanceTaskRun} — the progress
+        # the dashboard polls while a task runs, and the audit trail it shows
+        # afterwards (docs/plans/6.0-maintenance-tasks.md).
+        #
+        # Admin-only by design: there is no store counterpart, because nothing
+        # about operator-run data work is customer-facing.
+        class MaintenanceTaskRunSerializer < BaseSerializer
+          typelize task_name: :string,
+                   status: [:string, enum: Spree::MaintenanceTaskRun.statuses, enum_type_name: 'MaintenanceTaskRunStatus'],
+                   dry_run: :boolean,
+                   initiated_via: :string,
+                   tick_count: :number,
+                   tick_total: [:number, nullable: true],
+                   duration: [:number, nullable: true],
+                   tallies: 'Record<string, number>',
+                   arguments: 'Record<string, unknown>',
+                   error_class: [:string, nullable: true],
+                   error_message: [:string, nullable: true],
+                   error_backtrace: [:string, nullable: true],
+                   active: :boolean,
+                   admin_user_id: [:string, nullable: true],
+                   started_at: [:string, nullable: true],
+                   ended_at: [:string, nullable: true]
+
+          attributes :status, :dry_run, :initiated_via,
+                     :tick_count, :tick_total, :error_class, :error_message,
+                     :started_at, :ended_at, :created_at, :updated_at
+
+          # The task's short name, as `GET /upgrade_steps` gives it.
+          attribute :task_name, &:task_api_type
+
+          # to_f before rounding: the column is a decimal, and a BigDecimal
+          # serializes as a quoted string — a client reading `duration` wants a
+          # number, and the schema says it gets one.
+          attribute :duration do |run|
+            run.duration&.to_f&.round(3)
+          end
+
+          attribute :tallies do |run|
+            run.tallies || {}
+          end
+
+          attribute :arguments do |run|
+            run.arguments || {}
+          end
+
+          # The failure detail an operator needs to fix the cause. Held back
+          # from read-only callers — a backtrace names internal paths and
+          # class names that a read scope has no business seeing.
+          attribute :error_backtrace do |run|
+            run.error_backtrace if params[:show_backtrace]
+          end
+
+          attribute :active, &:active?
+
+          attribute :admin_user_id do |run|
+            run.admin_user&.prefixed_id
+          end
+
+          # Who fired it. Pass `expand=admin_user` for the record itself.
+          one :admin_user,
+              resource: proc { Spree.api.admin_admin_user_serializer },
+              if: proc { expand?('admin_user') }
+        end
+      end
+    end
+  end
+end

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

@@ -86,6 +86,8 @@ module Spree
           attribute :viewable_type do |asset|
             Spree::Base.polymorphic_api_type(asset.viewable_type)
           end
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -9,6 +9,8 @@ module Spree
         # customer-facing serializer so public fields stay in sync.
         class NewsletterSubscriberSerializer < V3::NewsletterSubscriberSerializer
           prefixed_id_attributes :customer
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -13,6 +13,8 @@ module Spree
           many :option_values,
                resource: proc { Spree.api.admin_option_value_serializer },
                if: proc { expand?('option_values') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -11,6 +11,8 @@ module Spree
           one :option_type,
               resource: proc { Spree.api.admin_option_type_serializer },
               if: proc { expand?('option_type') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -198,6 +198,8 @@ module Spree
           typelize freight_summary: [:FreightSummary, nullable: true]
 
           one :freight_summary, resource: proc { Spree.api.admin_freight_summary_serializer }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -25,6 +25,8 @@ module Spree
           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? }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -45,7 +45,7 @@ module Spree
                            Spree.api.admin_payment_source_serializer
                          end
 
-            serializer.new(payment.source).to_h
+            serializer.new(payment.source, params: nested_params('source')).to_h
           end
 
           many :capture_events,
@@ -65,6 +65,8 @@ module Spree
           many :payment_splits,
                resource: proc { Spree.api.admin_payment_split_serializer },
                if: proc { expand?('payment_splits') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -7,6 +7,8 @@ module Spree
 
           attributes :metadata,
                      created_at: :iso8601, updated_at: :iso8601
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -108,9 +108,7 @@ module Spree
                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') }
+          expandable_custom_fields admin: true
 
           many :product_publications,
                resource: proc { Spree.api.admin_product_publication_serializer },

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

@@ -49,6 +49,8 @@ module Spree
 
           # Where the inbound parcel is, as the carrier last reported it.
           many :deliveries, resource: proc { Spree.api.admin_delivery_serializer }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -17,7 +17,8 @@ module Spree
                    reference: 'string | null',
                    period_start: 'string | null',
                    period_end: 'string | null',
-                   transfers_count: :number
+                   transfers_count: :number,
+                   metadata: 'Record<string, unknown>'
 
           attributes :status, :currency, :reference, :metadata,
                      period_start: :iso8601, period_end: :iso8601,

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

@@ -6,6 +6,8 @@ module Spree
         # shopper also gets, plus the operational state and the settlement and
         # tax configuration only the operator sets.
         class SellerSerializer < V3::SellerSerializer
+          include Concerns::ExternalReferencesAttribute
+
           typelize status: [:string, enum: Spree::Seller.statuses, enum_type_name: 'SellerStatus'],
                    legal_name: [:string, nullable: true],
                    registration_number: [:string, nullable: true],
@@ -75,6 +77,8 @@ module Spree
           one :returns_address,
               resource: proc { Spree.api.admin_address_serializer },
               if: proc { |seller| seller.returns_address.present? }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -52,6 +52,8 @@ module Spree
           one :customer,
               resource: proc { Spree.api.admin_customer_serializer },
               if: proc { expand?('customer') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -2,10 +2,10 @@ module Spree
   module Api
     module V3
       module Admin
-        class StoreSerializer < V3::BaseSerializer
-          typelize name: :string, url: :string, code: :string, api_url: :string,
+        class StoreSerializer < V3::StoreSerializer
+          typelize url: :string, code: :string, api_url: :string,
                    default_currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'], default_locale: [:string, enum: Spree::Locales::ALL, enum_type_name: 'LocaleCode'],
-                   default_country_code: [:string, nullable: true],
+                   default_country_code: [:string, nullable: true, enum: Spree::IsoData.country_codes, enum_type_name: 'CountryCode'],
                    supported_currencies: [:string, multi: true, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
                    supported_locales: [:string, multi: true, enum: Spree::Locales::ALL, enum_type_name: 'LocaleCode'],
                    available_locales: [:string, multi: true, enum: Spree::Locales::ALL, enum_type_name: 'LocaleCode'],
@@ -20,7 +20,6 @@ module Spree
                    metadata: 'Record<string, unknown>'
 
           attributes :metadata,
-                     :name,
                      :code,
                      :default_currency,
                      :default_locale,

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

@@ -112,9 +112,7 @@ module Spree
                resource: proc { Spree.api.admin_price_serializer },
                if: proc { expand?('prices') }
 
-          many :custom_fields,
-               resource: proc { Spree.api.admin_custom_field_serializer },
-               if: proc { expand?('custom_fields') }
+          expandable_custom_fields admin: true
 
           many :stock_levels,
                resource: proc { Spree.api.admin_stock_level_serializer },

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

@@ -152,6 +152,12 @@ module Spree
         }.freeze
         private_constant :PREFERENCE_LIST_NAMES
 
+        # Settings declared with a code format share the code list request
+        # bodies take, so a value read back is the type a write takes.
+        FORMAT_CODE_LISTS = { 'iso-country' => :country, 'currency' => :currency, 'locale' => :locale,
+                              'timezone' => :time_zone }.freeze
+        private_constant :FORMAT_CODE_LISTS
+
         def self.preference_type_hint(schema, name)
           types = Array(schema['type'])
           options = {}
@@ -165,6 +171,9 @@ module Spree
           if schema['enum']
             options[:enum] = schema['enum'].compact
             options[:enum_type_name] = PREFERENCE_LIST_NAMES[name.to_sym] if PREFERENCE_LIST_NAMES.key?(name.to_sym)
+          elsif (code_list = FORMAT_CODE_LISTS[(schema['items'] || schema)['format']])
+            options[:enum_type_name], values = Spree::Api::V3::RequestSchema::CODE_LISTS.fetch(code_list)
+            options[:enum] = values.call
           end
           options.empty? ? hint : [hint, options]
         end
@@ -192,6 +201,25 @@ module Spree
           end
         end
 
+        # Declares the opt-in `custom_fields` expand. The Store API sends only
+        # values whose definition is storefront visible; Admin API serializers
+        # pass `admin: true` to send every value.
+        #
+        # @param admin [Boolean] whether to send every value rather than only storefront visible ones
+        # @return [void]
+        def self.expandable_custom_fields(admin: false)
+          if admin
+            many :custom_fields,
+                 resource: proc { Spree.api.admin_custom_field_serializer },
+                 if: proc { expand?('custom_fields') }
+          else
+            many :storefront_custom_fields,
+                 key: :custom_fields,
+                 resource: proc { Spree.api.custom_field_serializer },
+                 if: proc { expand?('custom_fields') }
+          end
+        end
+
         # Plain decimal notation. BigDecimal renders 0.06 as "0.6e-1", which
         # is what a client would otherwise print beside a unit.
         #

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

@@ -50,10 +50,7 @@ module Spree
              resource: proc { Spree.api.category_serializer },
              if: proc { expand?('ancestors') }
 
-        many :storefront_custom_fields,
-             key: :custom_fields,
-             resource: proc { Spree.api.custom_field_serializer },
-             if: proc { expand?('custom_fields') }
+        expandable_custom_fields
       end
     end
   end

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

@@ -42,6 +42,8 @@ module Spree
         many :claim_line_items,
              resource: proc { Spree.api.claim_line_item_serializer },
              if: proc { expand?('claim_line_items') }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -29,10 +29,7 @@ module Spree
           image_url_for(collection.square_image)
         end
 
-        many :storefront_custom_fields,
-             key: :custom_fields,
-             resource: proc { Spree.api.custom_field_serializer },
-             if: proc { expand?('custom_fields') }
+        expandable_custom_fields
       end
     end
   end

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

@@ -25,6 +25,8 @@ module Spree
             { 'id' => node.prefixed_id, 'name' => node.name, 'kind' => node.kind }
           end
         end
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -7,6 +7,8 @@ module Spree
                  gateway_payment_profile_id: [:string, nullable: true]
 
         attributes :brand, :last4, :month, :year, :name, :default, :gateway_payment_profile_id
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -54,6 +54,8 @@ module Spree
         many :customer_groups,
              proc { |groups, params| groups.for_store(params&.dig(:store) || Spree::Current.store) },
              resource: proc { Spree.api.customer_group_serializer }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -15,6 +15,8 @@ module Spree
         attribute :digital, &:digital?
         attribute :pickup, &:pickup?
         attribute :pickup_point, &:pickup_point?
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -59,6 +59,8 @@ module Spree
         one :stock_location, resource: proc { Spree.api.stock_location_serializer }
         many :delivery_rates, resource: proc { Spree.api.delivery_rate_serializer }
         many :tax_lines, resource: proc { Spree.api.tax_line_serializer }, if: proc { expand?('tax_lines') }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -51,6 +51,7 @@ module Spree
 
         attribute :active, &:active?
 
+        expandable_custom_fields
       end
     end
   end

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

@@ -73,6 +73,8 @@ module Spree
         # exactly-one-adjustable rule makes the nested view complete, and the
         # owner already carries the tax totals.
         many :tax_lines, resource: proc { Spree.api.tax_line_serializer }, if: proc { expand?('tax_lines') }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -99,6 +99,8 @@ module Spree
         def url_helpers
           Rails.application.routes.url_helpers
         end
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -21,6 +21,8 @@ module Spree
         attribute :customer_id do |subscriber|
           subscriber.customer&.prefixed_id if current_user && subscriber.customer_id == current_user.id
         end
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -5,6 +5,8 @@ module Spree
         typelize name: :string, label: :string, position: :number, kind: [:string, enum: Spree::OptionType::KINDS, enum_type_name: 'OptionTypeKind']
 
         attributes :name, :label, :position, :kind
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -21,6 +21,8 @@ module Spree
         attribute :image_url do |option_value|
           image_url_for(option_value.image)
         end
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -79,6 +79,8 @@ module Spree
         one :shipping_address, resource: proc { Spree.api.address_serializer }
         one :gift_card, resource: proc { Spree.api.gift_card_serializer }
         one :market, resource: proc { Spree.api.market_serializer }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -14,6 +14,8 @@ module Spree
         attribute :session_required, &:session_required?
 
         attribute :source_required, &:source_required?
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -42,10 +42,12 @@ module Spree
                          Spree.api.payment_source_serializer
                        end
 
-          serializer.new(payment.source).to_h
+          serializer.new(payment.source, params: nested_params('source')).to_h
         end
 
         one :payment_method, resource: proc { Spree.api.payment_method_serializer }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -5,6 +5,8 @@ module Spree
         typelize gateway_payment_profile_id: [:string, nullable: true]
 
         attributes :gateway_payment_profile_id
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -137,10 +137,7 @@ module Spree
              resource: proc { Spree.api.category_serializer },
              if: proc { expand?('categories') }
 
-        many :storefront_custom_fields,
-             key: :custom_fields,
-             resource: proc { Spree.api.custom_field_serializer },
-             if: proc { expand?('custom_fields') }
+        expandable_custom_fields
 
         typelize prior_price: ['PriceHistory', nullable: true],
                  seller_id: [:string, nullable: true]

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

@@ -44,6 +44,8 @@ module Spree
         many :return_line_items,
              resource: proc { Spree.api.return_line_item_serializer },
              if: proc { expand?('return_line_items') }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -5,12 +5,33 @@ module Spree
         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]
+                   accepted_at: [:string, nullable: true],
+                   inviter_email: :string,
+                   invitee_exists: [:boolean, optional: true],
+                   seller: '{ id: string; name: string }'
 
           attributes :email,
                      created_at: :iso8601, expires_at: :iso8601, accepted_at: :iso8601
 
           attributes status: :string
+
+          attribute :inviter_email do |invitation|
+            invitation.inviter.email
+          end
+
+          # Drives the acceptance page's sign-in vs sign-up branch, so only the
+          # public lookup carries it: whoever holds the emailed link already
+          # knows the address. A seller's team screen does not get to learn
+          # which addresses hold accounts elsewhere on the marketplace.
+          attribute :invitee_exists, if: proc { params[:acceptance] } do |invitation|
+            invitation.invitee_account.present?
+          end
+
+          # The smallest shape the acceptance page's title ("Join <seller>")
+          # needs; the page is public, so nothing more of the seller goes out.
+          attribute :seller do |invitation|
+            { id: invitation.resource.prefixed_id, name: invitation.resource.name }
+          end
         end
       end
     end

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

@@ -17,7 +17,7 @@ module Spree
                    products_count: :number,
                    default_currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
                    supported_currencies: [:string, multi: true, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
-                   timezone: [:string, nullable: true]
+                   timezone: [:string, nullable: true, enum: Spree::TimeZones::SUGGESTED, enum_type_name: 'TimeZone']
 
           attributes :timezone,
                      :status, :legal_name, :registration_number,

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

@@ -42,6 +42,8 @@ module Spree
         many :policies,
              resource: proc { Spree.api.policy_serializer },
              if: proc { expand?('policies') }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -7,6 +7,8 @@ module Spree
         money_attributes :amount, :amount_used, :amount_remaining, :display_amount,
                          :display_amount_used, :display_amount_remaining
         attributes :currency
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -0,0 +1,16 @@
+module Spree
+  module Api
+    module V3
+      # The current store's public identity and default SEO metadata, in the
+      # request's locale. Missing translations fall back to the store's default
+      # locale.
+      class StoreSerializer < BaseSerializer
+        typelize name: :string,
+                 seo_title: [:string, nullable: true],
+                 meta_description: [:string, nullable: true]
+
+        attributes :name, :seo_title, :meta_description
+      end
+    end
+  end
+end

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

@@ -127,10 +127,7 @@ module Spree
 
         many :option_values, resource: proc { Spree.api.option_value_serializer }
 
-        many :storefront_custom_fields,
-             key: :custom_fields,
-             resource: proc { Spree.api.custom_field_serializer },
-             if: proc { expand?('custom_fields') }
+        expandable_custom_fields
 
         typelize prior_price: ['PriceHistory', nullable: true]