spree_api 6.0.0.rc3 → 6.0.0.rc5

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

@@ -25,6 +25,17 @@ module Spree
           boolean: 'boolean'
         }.freeze
 
+        # Columns holding a value from one of the closed code lists the API
+        # publishes as a shared type, matched by name (`locale`,
+        # `default_locale`, `cost_currency`), so clients filter with that type,
+        # not free text.
+        CODE_TYPES = {
+          'locale' => 'LocaleCode',
+          'currency' => 'CurrencyCode',
+          'country_code' => 'CountryCode',
+          'country_of_origin' => 'CountryCode'
+        }.freeze
+
         # Raised when an endpoint's table cannot be described — a column of a
         # kind the contract has no predicates for, or two models sharing a name.
         class Error < StandardError; end
@@ -124,8 +135,9 @@ module Spree
           self.class.name_for(model)
         end
 
-        # @return [Hash{String => String, Hash}] attribute => value kind, or
-        #   `{ 'enum' => [values] }` for a status
+        # @return [Hash{String => String, Hash}] attribute => value kind,
+        #   `{ 'enum' => [values] }` for a status, or `{ 'code' => type }` for
+        #   a value from a shared code list
         def attributes
           @attributes ||= kinds.reject { |_, kind| kind == :unclassified }.compact
         end
@@ -210,6 +222,10 @@ module Spree
         #   attribute the model does not have (`position` on a table without
         #   one), `:unclassified` for one the contract cannot describe
         def attribute_kind(attribute)
+          if (code_type = code_type(attribute))
+            return { 'code' => code_type }
+          end
+
           aliased = model._ransack_aliases[attribute] || model.attribute_aliases[attribute]
           return attribute_kind(aliased) if aliased
           return ransacker_kind(model._ransackers[attribute]) if model._ransackers.key?(attribute)
@@ -220,7 +236,6 @@ module Spree
           if (values = inclusion_values(attribute))
             return { 'enum' => values }
           end
-
           column = model.columns_hash[attribute]
           return COLUMN_KINDS.fetch(column.type, :unclassified) if column
           return 'text' if translated_attribute?(attribute)
@@ -229,6 +244,10 @@ module Spree
           :unclassified
         end
 
+        def code_type(attribute)
+          CODE_TYPES.find { |name, _| attribute == name || attribute.end_with?("_#{name}") }&.last
+        end
+
         # The fixed list an inclusion validation allows, for a column that
         # holds one of a known set of values (`payment_status`, `kind`).
         def inclusion_values(attribute)

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

@@ -40,20 +40,24 @@ module Spree
           datetime: { type: :string, format: :'date-time' },
           id: { type: :string },
           any: {},
-          # ISO codes, from the closed lists below.
+          # Codes from the closed lists below.
           country: { type: :string },
           currency: { type: :string },
-          locale: { type: :string }
+          locale: { type: :string },
+          weight_unit: { type: :string },
+          dimension_unit: { type: :string }
         }.freeze
 
-        # The ISO lists a `country` or `currency` field takes, published once
-        # per API as a named component — the same `CountryCode` and
-        # `CurrencyCode` types the serializers declare, so a value read from
-        # a response is the type a request takes.
+        # 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.
         CODE_LISTS = {
           country: ['CountryCode', -> { Spree::IsoData.country_codes }],
           currency: ['CurrencyCode', -> { Spree::Money::Rounding::CURRENCY_CODES }],
-          locale: ['LocaleCode', -> { Spree::Locales::ALL }]
+          locale: ['LocaleCode', -> { Spree::Locales::ALL }],
+          weight_unit: ['WeightUnit', -> { Spree::Variant::WEIGHT_UNITS }],
+          dimension_unit: ['DimensionUnit', -> { Spree::Variant::DIMENSION_UNITS }]
         }.freeze
 
         ACTIONS = %i[create update].freeze
@@ -119,7 +123,7 @@ module Spree
           end
         end
 
-        attr_reader :name, :fields
+        attr_reader :name, :fields, :base
 
         # The types an attribute takes: the scalars above, plus `:hash` (any
         # keys), `:object` (a block or a `shape:`) and `:array` (`of:` a type
@@ -172,7 +176,7 @@ module Spree
             value.is_a?(Class) ? value.definition : value
           end
 
-          %i[attribute include_attributes require_attributes external_references].each do |method|
+          %i[attribute extends include_attributes require_attributes external_references].each do |method|
             define_method(method) { |*args, **options, &block| definition.public_send(method, *args, **options, &block) }
           end
         end
@@ -229,6 +233,19 @@ module Spree
           TEXT
         end
 
+        # Builds on a published shape: the body accepts all of its attributes,
+        # and the published type is that shape's type plus what this schema
+        # adds, so clients write one type wherever the shape is accepted.
+        #
+        # @param other [RequestSchema, Class] a shape with a published name
+        def extends(other)
+          parent = RequestSchema.resolve(other)
+          raise ArgumentError, "#{parent.class.name} has no published name to extend" unless shape?(parent)
+
+          include_attributes(parent)
+          @base = parent
+        end
+
         # Adds the attributes of another schema, for endpoints that extend a
         # shared set.
         #
@@ -253,6 +270,19 @@ module Spree
           @permit_lists = nil
         end
 
+        # Replaces the description of an attribute this schema took from
+        # another, for an endpoint where it behaves differently.
+        #
+        # @param name [Symbol]
+        # @param description [String]
+        # @return [void]
+        def describe_attribute(name, description)
+          field = fields.fetch(name) { raise ArgumentError, "#{name} is not an attribute of this schema" }
+          copy = field.dup
+          copy.instance_variable_set(:@description, description)
+          fields[name] = copy
+        end
+
         # The `params.permit` list for an action.
         #
         # @param action [Symbol, String, nil] `create` or `update`; nil
@@ -269,12 +299,21 @@ module Spree
         # @return [Hash]
         def json_schema(action = nil)
           action = action&.to_sym
-          fields = fields_for(action)
-          required = fields.select { |field| field.required_on?(action) }.map { |field| field.name.to_s }
+          # A base field this action does not take would still reach clients
+          # through the base's type, so such a body is published in full.
+          unless base && base.fields.each_value.all? { |field| field.accepted_on?(action) }
+            return object_schema(fields_for(action), action)
+          end
 
-          schema = { type: :object, properties: fields.to_h { |field| [field.name, property_schema(field)] } }
-          schema[:required] = required if required.any?
-          schema
+          # Attributes the base describes the same way for this action are
+          # left to its type.
+          own = fields_for(action).reject do |field|
+            inherited = base.fields[field.name]
+            inherited && inherited.required_on?(action) == field.required_on?(action) &&
+              property_schema(inherited) == property_schema(field)
+          end
+          reference = { '$ref': "#/components/schemas/#{base.name}" }
+          own.any? ? { allOf: [reference, object_schema(own, action)] } : reference
         end
 
         # The component name published for an action.
@@ -291,15 +330,15 @@ module Spree
         #
         # @return [Array<RequestSchema>]
         def shapes
-          fields.each_value.flat_map do |field|
+          (base ? [base, *base.shapes] : []).concat(fields.each_value.flat_map do |field|
             next [] unless field.schema
 
             nested = field.schema.shapes
             shape?(field.schema) ? [field.schema, *nested] : nested
-          end.uniq
+          end).uniq
         end
 
-        # The ISO code lists this schema's fields reach, nested ones included,
+        # The code lists this schema's fields reach, nested ones included,
         # as the components they publish.
         #
         # @return [Hash{String => Hash}]
@@ -374,6 +413,14 @@ module Spree
         end
 
 
+        def object_schema(fields, action)
+          required = fields.select { |field| field.required_on?(action) }.map { |field| field.name.to_s }
+
+          schema = { type: :object, properties: fields.to_h { |field| [field.name, property_schema(field)] } }
+          schema[:required] = required if required.any?
+          schema
+        end
+
         def fields_for(action)
           fields.values.select { |field| field.accepted_on?(action) }
         end

data/config/locales/en.yml

@@ -14,6 +14,7 @@ en:
         media_in_use: This file is still in use (%{places}). Pass detach=true to remove it everywhere and delete it, or clear those places first.
         media_not_deleted: The file could not be deleted. Nothing was changed.
         media_url_import_requires_product: Importing media from a URL needs a product to import it into. Upload the file instead, or post it to a product's media.
+        order_sales_context_exclusive: An order already fixes its sales context, so order_id cannot be combined with %{params}.
         store_mismatch: The requested store does not match the store this API key belongs to.
         storefront_login_required: Authentication required to access this store.
         unsupported_export_type: 'Unsupported export type. Supported types: %{types}'

data/config/routes.rb

@@ -43,6 +43,7 @@ Spree::Core::Engine.add_routes do
             patch :associate
             post :complete
           end
+          resources :addresses, only: [:index], controller: 'carts/addresses'
           resources :items, only: [:create, :update, :destroy], controller: 'carts/items'
           resources :discount_codes, only: [:create, :destroy], controller: 'carts/discount_codes'
           resources :gift_cards, only: [:create, :destroy], controller: 'carts/gift_cards'
@@ -154,6 +155,10 @@ Spree::Core::Engine.add_routes do
         # Token-addressed so the emailed link works from a device that was
         # never signed in.
         get 'data_requests/:token/download', to: 'data_request_downloads#show', as: :data_request_download
+        # Addressed by the confirmation token emailed to the address a
+        # customer's own request names, for the same reason.
+        get 'data_requests/:token', to: 'data_requests#show', as: :data_request
+        post 'data_requests/:token/confirmation', to: 'data_request_confirmations#create', as: :data_request_confirmation
         # Legacy path — emailed and bookmarked URLs outlive the rename. Removed in 6.1.
         get 'digitals/:token', to: 'digital_links#show', as: :digital_download
 
@@ -238,6 +243,27 @@ Spree::Core::Engine.add_routes do
         post 'auth/password_resets', to: 'password_resets#create'
         patch 'auth/password_resets/:id', to: 'password_resets#update'
 
+        # OAuth 2.1 consent, read and decided by the dashboard. The admin's
+        # own session authorizes it: a secret key may authenticate here but
+        # can never grant authority on a person's behalf.
+        namespace :oauth do
+          get 'authorize', to: 'authorizations#show'
+          post 'authorize', to: 'authorizations#create'
+          delete 'authorize', to: 'authorizations#destroy'
+
+          # The OAuth clients registered against this store. Deleting one
+          # removes the registration; revoking a connection is the nested
+          # `tokens` resource, because that is what revoking deletes.
+          #
+          # Tokens are plural and addressable: a store registers a client once
+          # and every staff member connects to that same registration, so the
+          # live tokens are who is connected. Revoking one has to cut off that
+          # person and leave their colleagues working.
+          resources :applications, except: :show do
+            resources :tokens, only: %i[index destroy], controller: 'application_tokens'
+          end
+        end
+
         # Semantic reporting (docs/plans/6.0-analytics-semantic-layer.md)
         namespace :reporting do
           post :query
@@ -261,6 +287,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
+        # parent. The controller only ever resolves the current store.
+        resources :stores, only: [], concerns: :custom_fieldable
 
         # Staff & access (invitations, admin users, roles, API keys)
         resources :admin_users, only: [:index, :show, :update, :destroy]
@@ -324,7 +353,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Products
-        resources :product_types do
+        resources :product_types, concerns: :custom_fieldable do
           post :apply_to_products, on: :member
         end
         resources :products, concerns: [:custom_fieldable, :translatable] do
@@ -366,7 +395,7 @@ Spree::Core::Engine.add_routes do
         # Media library — every file in the store, placed or not. Files are put
         # ON a product through the nested media routes above; this is where they
         # are uploaded, browsed and deleted.
-        resources :media, controller: 'media_library', only: [:index, :show, :create, :update, :destroy] do
+        resources :media, controller: 'media_library', only: [:index, :show, :create, :update, :destroy], concerns: :custom_fieldable do
           get :usage, on: :member
         end
 
@@ -401,7 +430,7 @@ Spree::Core::Engine.add_routes do
         resources :tax_categories
 
         # Tax Rates — the internal tax provider's configuration
-        resources :tax_rates
+        resources :tax_rates, concerns: :custom_fieldable
 
         # Selectable tax engines and their declared limits (discovery only)
         resources :tax_providers, only: [:index]
@@ -409,11 +438,12 @@ Spree::Core::Engine.add_routes do
         # preference, so there is nothing here to create.
         resources :payout_providers, only: [:index]
 
-        # Return / claim / refund / cancellation reasons (dropdowns + settings management)
+        # Return / claim / refund / cancellation / tax exemption reasons (dropdowns + settings management)
         resources :return_reasons
         resources :claim_reasons
         resources :refund_reasons
         resources :order_cancellation_reasons
+        resources :tax_exemption_reasons
 
         # Markets
         resources :markets
@@ -425,7 +455,7 @@ Spree::Core::Engine.add_routes do
           post :bulk_upsert, on: :collection
         end
         resources :stock_movements, only: [:index, :show]
-        resources :stock_transfers do
+        resources :stock_transfers, concerns: :custom_fieldable do
           member do
             patch :mark_ready
             patch :mark_in_transit
@@ -438,7 +468,7 @@ Spree::Core::Engine.add_routes do
 
         # Purchasing
         resources :suppliers
-        resources :purchase_orders do
+        resources :purchase_orders, concerns: :custom_fieldable do
           member do
             patch :mark_ordered
             patch :mark_draft
@@ -449,7 +479,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Payment Methods
-        resources :delivery_methods do
+        resources :delivery_methods, concerns: :custom_fieldable do
           collection do
             get :calculators
             get :fulfillment_providers
@@ -470,7 +500,7 @@ Spree::Core::Engine.add_routes do
                                     only: [:index, :show, :create, :update, :destroy]
         end
 
-        resources :payment_methods do
+        resources :payment_methods, concerns: :custom_fieldable do
           get :types, on: :collection
         end
 
@@ -480,7 +510,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Promotions, with nested actions/rules/coupon codes.
-        resources :promotions do
+        resources :promotions, concerns: :custom_fieldable do
           resources :promotion_actions, only: [:index, :show, :create, :update, :destroy]
           resources :promotion_rules, only: [:index, :show, :create, :update, :destroy]
           resources :coupon_codes, only: [:index, :show]
@@ -613,7 +643,7 @@ Spree::Core::Engine.add_routes do
         # Business customers — a tree of company nodes. Nested collections are
         # listed and created under their node and then addressed directly, so
         # a caller holding an entry id does not have to know its company.
-        resources :companies do
+        resources :companies, concerns: :custom_fieldable do
           # The node's address book.
           resources :addresses, controller: 'companies/addresses'
 
@@ -698,12 +728,12 @@ Spree::Core::Engine.add_routes do
         end
 
         # Gift cards
-        resources :gift_cards
+        resources :gift_cards, concerns: :custom_fieldable
         resources :gift_card_batches, only: [:index, :show, :create]
 
         # Store credits across all customers. Read-only: issuing, editing and
         # deleting a credit stays nested under the customer that holds it.
-        resources :store_credits, only: [:index, :show] do
+        resources :store_credits, only: [:index, :show], concerns: :custom_fieldable do
           resources :events, only: [:index], controller: 'store_credits/events'
         end
 
@@ -1052,6 +1082,14 @@ Spree::Core::Engine.add_routes do
         end
       end
 
+      # RFC 9728 Protected Resource Metadata. One document per protected
+      # resource, named by the surface that registered it, so a client
+      # discovers which authorization server guards the URL it was given.
+      # Unauthenticated: a client has no credential at the point it asks.
+      get 'oauth/protected-resource/:resource_key',
+          to: 'oauth/metadata#show',
+          as: :oauth_protected_resource
+
       # Webhooks (outside of store namespace — no API key authentication)
       namespace :webhooks do
         post 'payments/:payment_method_id', to: 'payments#create', as: :payment_webhook
@@ -1066,4 +1104,34 @@ Spree::Core::Engine.add_routes do
       end
     end
   end
+
+  # The authorization server's own endpoints: /oauth/authorize, /oauth/token,
+  # /oauth/revoke and RFC 8414 metadata. Outside the versioned API namespace —
+  # the OAuth protocol is not a Spree API resource and its paths are fixed by
+  # the spec and by what clients expect to find.
+  #
+  # `authorizations` is NOT skipped. Skipping it would leave the metadata
+  # document without an `authorization_endpoint`, which is required for the
+  # code flow, so a consumer client would have nowhere to send the browser.
+  # The controller is Spree's own and redirects to the dashboard's consent
+  # screen instead of rendering Doorkeeper's HTML.
+  #
+  # The application-management controllers stay skipped: connected apps are
+  # managed through /api/v3/admin/oauth/applications, under the Admin API's
+  # own authentication.
+  # `controllers` is a block method, not an option to `use_doorkeeper`.
+  #
+  # Doorkeeper's own controllers need a leading slash because these routes are
+  # drawn inside Spree::Core::Engine, which isolates the namespace — a bare
+  # `doorkeeper/tokens` resolves as `Spree::Doorkeeper::Tokens` and fails on
+  # the first request. Spree's own authorizations controller is named from the
+  # application root WITHOUT a slash, because the metadata document builds its
+  # URL with `url_for(controller: "/#{name}")` and adds the slash itself.
+  use_doorkeeper scope: 'oauth' do
+    controllers authorizations: 'api/v3/oauth/authorizations',
+                tokens: '/doorkeeper/tokens',
+                token_info: '/doorkeeper/token_info',
+                metadata: '/spree/api/v3/oauth/server_metadata'
+    skip_controllers :applications, :authorized_applications
+  end
 end

data/lib/spree/api/agent_membership_map.rb

@@ -0,0 +1,73 @@
+module Spree
+  module Api
+    # Which parents an agent may curate products into, derived from the
+    # controllers that adopt `Spree::Api::V3::Admin::ProductMembership`.
+    #
+    # Read off the controllers for the same reason {AgentResourceMap} is: a
+    # parent that adopts the concern later is curated without anyone editing
+    # this file, and one that drops it stops being offered.
+    module AgentMembershipMap
+      class << self
+        # @param map [Module]
+        # @return [Integer] how many parents were registered
+        def install(map: Spree::AgentTools::MembershipMap)
+          map.reset!
+
+          curating_controllers.each do |controller|
+            target = target_for(controller)
+            next if target.blank?
+
+            # Addressing a parent an agent cannot otherwise read would hand it
+            # a write with no matching read, and no way to name what it changed.
+            entry = Spree::AgentTools::ResourceMap.find(target.pluralize)
+            next if entry.nil?
+
+            map.register(
+              target: target,
+              permission: write_permission_for(entry),
+              api_path: membership_path_for(controller)
+            )
+          end
+
+          map.all.size
+        end
+
+        private
+
+        # Where this parent's products are added and removed, read from the
+        # routes. The nested path carries the parent's id, which a tool fills
+        # in from the parent it was given.
+        def membership_path_for(controller)
+          route = Spree::Core::Engine.routes.routes.find do |candidate|
+            candidate.defaults[:controller] == controller.controller_path &&
+              candidate.defaults[:action] == 'create'
+          end
+
+          route&.path&.spec.to_s.sub('(.:format)', '').presence
+        end
+
+        def curating_controllers
+          Rails.application.eager_load! unless Rails.application.config.eager_load
+
+          Spree::Api::V3::Admin::ResourceController.descendants.
+            select { |controller| controller.include?(Spree::Api::V3::Admin::ProductMembership) }.
+            sort_by(&:name)
+        end
+
+        # Curating is a write to the parent, so it is gated on the parent's
+        # own write scope — a price list rides `write_products`, a category
+        # `write_categories`, exactly as their controllers do.
+        def write_permission_for(entry)
+          entry.write_permission.presence || "write_#{entry.permission.to_s.sub(/\Aread_/, '')}"
+        end
+
+        # `Admin::Categories::ProductsController` curates a category. The
+        # parent is the namespace the nested controller sits in, which is how
+        # the routes name it too.
+        def target_for(controller)
+          controller.name.to_s.split('::')[-2]&.underscore&.singularize
+        end
+      end
+    end
+  end
+end