spree_api 6.0.0 → 6.0.2

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]
 

data/app/services/spree/api/v3/request_schema.rb

@@ -40,22 +40,25 @@ module Spree
           datetime: { type: :string, format: :'date-time' },
           id: { type: :string },
           any: {},
-          # Codes from the closed lists below.
+          # Codes from the lists below.
           country: { type: :string },
           currency: { type: :string },
           locale: { type: :string },
+          time_zone: { type: :string },
           weight_unit: { type: :string },
           dimension_unit: { type: :string }
         }.freeze
 
-        # The closed lists a code field takes, published once per API as a
-        # named component — the same `CountryCode`, `CurrencyCode` and
-        # `WeightUnit` types the serializers declare, so a value read from a
-        # response is the type a request takes.
+        # The lists a code field takes, published once per API as a named
+        # component — the same `CountryCode`, `CurrencyCode` and `WeightUnit`
+        # types the serializers declare, so a value read from a response is the
+        # type a request takes. A list `Typelizer::OpenEnums` does not close
+        # only suggests its values.
         CODE_LISTS = {
           country: ['CountryCode', -> { Spree::IsoData.country_codes }],
           currency: ['CurrencyCode', -> { Spree::Money::Rounding::CURRENCY_CODES }],
           locale: ['LocaleCode', -> { Spree::Locales::ALL }],
+          time_zone: ['TimeZone', -> { Spree::TimeZones::SUGGESTED }],
           weight_unit: ['WeightUnit', -> { Spree::Variant::WEIGHT_UNITS }],
           dimension_unit: ['DimensionUnit', -> { Spree::Variant::DIMENSION_UNITS }]
         }.freeze
@@ -348,7 +351,12 @@ module Spree
             next unless CODE_LISTS.key?(field.kind)
 
             name, values = CODE_LISTS[field.kind]
-            lists[name] = { type: :string, enum: values.call }
+            lists[name] = if Typelizer::OpenEnums.closed?(name)
+                            { type: :string, enum: values.call }
+                          else
+                            Typelizer::OpenEnums.open_schema({ type: :string }, values.call)
+                              .merge(description: Typelizer::OpenEnums.description(name)).compact
+                          end
           end
         end
 
@@ -469,7 +477,7 @@ module Spree
 
           # The same open list the serializers publish (`enum_type_name`):
           # clients autocomplete the built-in values and still accept any other.
-          { anyOf: [schema.merge(enum: field.enum), schema] }
+          Typelizer::OpenEnums.open_schema(schema, field.enum)
         end
       end
     end

data/config/routes.rb

@@ -22,6 +22,9 @@ Spree::Core::Engine.add_routes do
         # Current channel context (never a list — see Store::ChannelController)
         resource :channel, only: [:show], controller: 'channel'
 
+        # Current store context (name and default SEO metadata, localized)
+        resource :store, only: [:show], controller: 'store'
+
         # Catalog
         resources :products, only: [:index, :show] do
           collection do
@@ -287,9 +290,9 @@ Spree::Core::Engine.add_routes do
         resource :store, only: [:show, :update], controller: 'store' do
           get :data_sources
         end
-        # The store's own custom fields, addressed by its id like every other
+        # The store's own custom fields and translations, addressed by its id like every other
         # parent. The controller only ever resolves the current store.
-        resources :stores, only: [], concerns: :custom_fieldable
+        resources :stores, only: [], concerns: [:custom_fieldable, :translatable]
 
         # Staff & access (invitations, admin users, roles, API keys)
         resources :admin_users, only: [:index, :show, :update, :destroy]

data/lib/spree/api/agent_workflow_endpoints.rb

@@ -95,8 +95,8 @@ module Spree
           path.gsub(/:([a-z_]+)/) { "{#{Regexp.last_match(1)}}" }
         end
 
-        # A packaged installation has no docs/ directory, and a body the
-        # document does not describe is simply passed through unchecked.
+        # A body the document does not describe is simply passed through
+        # unchecked.
         #
         # `AgentWriteSchemas` already holds this file parsed, so it is read
         # through there rather than a second time: the document is nearly a

data/lib/spree/api/agent_write_schemas.rb

@@ -33,12 +33,14 @@ module Spree
           self.for(key).keys
         end
 
-        # Where the generated document lives, relative to this engine. Resolved
-        # lazily: the engine class does not exist yet while this file loads.
+        # Where the generated document lives: `docs/` in a source checkout,
+        # or the copy the release packs into the gem. Resolved lazily: the
+        # engine class does not exist yet while this file loads.
         #
         # @return [Pathname]
         def spec_path
-          Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+          source = Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+          source.exist? ? source : Spree::Api::Engine.root.join('openapi', 'admin.yaml')
         end
 
         # The parsed document, for a reader that needs more of it than the
@@ -63,9 +65,7 @@ module Spree
         end
 
         # A missing or unparseable document is not a boot failure: the generic
-        # write tools simply offer nothing, which is the safe direction. An
-        # installation running from the packaged gems has no docs/ directory at
-        # all.
+        # write tools simply offer nothing, which is the safe direction.
         def load_schemas
           path = spec_path
           return {} unless File.exist?(path)

data/lib/spree/api/dependencies.rb

@@ -18,7 +18,7 @@ module Spree
            product_filter_sort_option media_event return return_line_item exchange exchange_line_item claim
            claim_line_item return_reason claim_reason digital_asset export gift_card_batch import import_row
            invitation newsletter_subscriber promotion refund stock_level stock_movement stock_reservation
-           stock_transfer company company_membership company_invitation seller file_upload file_upload_target].freeze
+           stock_transfer company company_membership company_invitation seller file_upload file_upload_target store].freeze
 
       ADMIN_SERIALIZERS =
         %i[country state locale applied_promotion discount tax_line cart delivery_zone delivery_profile
@@ -32,7 +32,7 @@ module Spree
            exchange exchange_line_item claim claim_line_item package_type policy tax_category tax_rate
            tax_identifier company company_membership company_invitation catalog catalog_price catalog_price_tier
            catalog_product price_list_product catalog_assignment catalog_quantity_rule catalog_product_term
-           catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor seller_team_member product_submission
+           catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor session seller_team_member product_submission
            seller seller_requirement seller_requirement_submission seller_requirement_status commission_rate
            commission_rule commission_line seller_transfer seller_payout seller_balance payment_split payment_capture_event address address_owner
            channel order_routing_rule product_publication market delivery_method delivery_method_service

data/lib/spree/api/enum_types.rb

@@ -110,7 +110,8 @@ module Spree
           type = "export type #{name} = (typeof #{constant})[number] | (string & {})"
           type = "export type #{name} =\n  | (typeof #{constant})[number]\n  | (string & {})" if type.length > LINE_WIDTH
 
-          "\n/** The built-in values of `#{name}`. Extensions may add more. */\n#{line}\n#{type}\n"
+          summary = Typelizer::OpenEnums.description(name) || "The built-in values of `#{name}`. Extensions may add more."
+          "\n/** #{summary} */\n#{line}\n#{type}\n"
         end
       end
     end

data/lib/spree/api/oauth.rb

@@ -15,23 +15,11 @@ module Spree
     # which is why this lives in `spree_api` rather than in any one gem that
     # happens to need it.
     module Oauth
-      # Protected resources, each registered by the surface that owns it as a
-      # path relative to this application's own origin.
-      #
-      #   Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
-      #
-      # A path rather than a full URL because the identifier must equal the
-      # URL the client was actually pointed at: the origin comes from the
-      # request where there is one, and from the application's configured
-      # URL options otherwise. A store's own `url` column is deliberately not
-      # consulted — it describes the storefront, which is frequently neither
-      # the host nor the scheme the Admin API answers on.
-      # Whether a redirect URI points at the machine the client runs on.
+      # Whether a redirect URI points at the machine the client runs on, by IP
+      # literal (`127.0.0.1`, `[::1]`).
       #
       # Decided by parsing the host as an address, the same way Doorkeeper
-      # does when it ignores the port of a loopback redirect — so `localhost`
-      # is deliberately not loopback here either, and a registration must use
-      # the IP literal for an ephemeral port to match.
+      # does when it ignores the port of a loopback redirect.
       #
       # @param uri [URI, String]
       # @return [Boolean]
@@ -44,6 +32,37 @@ module Spree
         false
       end
 
+      # Whether a redirect URI may use plain http: an IP-literal loopback, or
+      # `localhost` with an explicit port.
+      #
+      # Claude Code only ever calls back on `http://localhost:<port>`. Doorkeeper
+      # compares a `localhost` callback exactly, so the host must be lowercase
+      # and the port explicit: anything else could never match an
+      # authorization.
+      #
+      # @param uri [URI, String]
+      # @return [Boolean]
+      def self.local_redirect_uri?(uri)
+        uri = URI.parse(uri.to_s) unless uri.respond_to?(:host)
+        return true if loopback_uri?(uri)
+
+        uri.host == 'localhost' &&
+          (1..65_535).cover?(uri.port) && uri.port != uri.default_port
+      rescue StandardError
+        false
+      end
+
+      # Protected resources, each registered by the surface that owns it as a
+      # path relative to this application's own origin.
+      #
+      #   Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
+      #
+      # A path rather than a full URL because the identifier must equal the
+      # URL the client was actually pointed at: the origin comes from the
+      # request where there is one, and from the application's configured
+      # URL options otherwise. A store's own `url` column is deliberately not
+      # consulted — it describes the storefront, which is frequently neither
+      # the host nor the scheme the Admin API answers on.
       mattr_accessor :resources, default: {}
 
       class << self
@@ -191,17 +210,18 @@ module Spree
 
             # A redirect URI is where authorization codes are delivered, so a
             # plain-http one hands them to anyone on the path — except a
-            # loopback one, which never leaves the machine. A terminal client
-            # listens on an ephemeral local port and has no certificate for
-            # it, so RFC 8252 §7.3 makes that the recommended shape, and
-            # refusing it would lock out Claude Code and Codex entirely.
+            # loopback or `localhost` one, which never leaves the machine. A
+            # terminal client listens on a local port and has no certificate
+            # for it. RFC 8252 §7.3 recommends the IP literal, but Claude Code
+            # only sends `localhost`, so refusing it would lock Claude Code
+            # out entirely.
             #
             # Passed as a callable so the exemption is per URI rather than
             # per environment: everything else still has to be https.
             force_ssl_in_redirect_uri do |uri|
               next false if Rails.env.development?
 
-              !Spree::Api::Oauth.loopback_uri?(uri)
+              !Spree::Api::Oauth.local_redirect_uri?(uri)
             end
 
             # RFC 8707. Registering the validator is what binds an audience