spree_api 5.6.1 → 6.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4feafcfd958681a7548cc9a2e043d7748e98d40fb34426c2aac5cbdc17599472
-  data.tar.gz: fce6786a2b4f6a41c32a26c34510172032ad9d57095058729261ea90cfc28f1f
+  metadata.gz: cd13b5167236c50754b03e48d4e7ab4ff5f1c24cdfd13b5a1ea45ff7a2961dd7
+  data.tar.gz: 77ab648d62775d22902a30ff8dbb4927fd0dab1b93668caad957c99a88bcd1fa
 SHA512:
-  metadata.gz: 975ceabf8977c54e813177f08cf270e8688dc64e6e446d176e46310696ffc8672dcfb940c19eb0f4c7eace5b765e5883932eca08d973c432e4389539b27709af
-  data.tar.gz: 9c0ad20112afb852ff2cedd8421f6853a5ce098b0feb435d6346ca015d1190ac891ac38138f98e526bfc973e6f16afb27aadc0917065c236d33ea4023fe34f30
+  metadata.gz: 36a716f02b07837cf6360d19cb914ef28a1de1e5cef02b0d6cb503bcc11d89afa6f00f36bd1613d0e9de6962197af6830c8068d03963ca257ac6f59c7ab2fa95
+  data.tar.gz: 388abb4801575690aa02e55a907a1851a1d88570a55681c60dc870f693a784024ed7d352e8fcedf493666bd2999269822e9d7abb579d13f3b8345ea9bb340ae2

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026-present, Vendo Sp. z o.o., Vendo Connect Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -37,7 +37,7 @@ namespace :rswag do
       require 'spree/api/openapi/path_sorter'
 
       docs = File.expand_path('../../docs/api-reference', __dir__)
-      %w[admin.yaml store.yaml].each do |name|
+      %w[admin.yaml store.yaml seller.yaml].each do |name|
         path = File.join(docs, name)
         next unless File.exist?(path)
 

data/app/controllers/concerns/spree/api/v3/address_params.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      # The writable attributes of a nested address.
+      #
+      # One list rather than one per controller: an address is the same record
+      # wherever it hangs, so a column added on one write path but missed on
+      # another is dropped silently.
+      module AddressParams
+        ADDRESS_KEYS = [
+          :first_name, :last_name, :company, :address1, :address2, :city,
+          :postal_code, :zipcode, :phone, :country_code, :state_code, :state_name, :label
+        ].freeze
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/product_listing.rb

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Preloads for any controller that serializes products through
+        # `Spree.api.admin_product_serializer` — the products index itself and
+        # the nested membership listings (a category's or a collection's
+        # products).
+        #
+        # The serializer walks variants, prices, stock items and media for every
+        # row, so a listing without these preloads issues a few hundred queries
+        # per page instead of a flat couple of dozen.
+        module ProductListing
+          extend ActiveSupport::Concern
+
+          protected
+
+          # Applied to the paginated index. The search provider builds its own
+          # relation, so `ProductsController` passes this to it explicitly.
+          def collection_includes
+            product_listing_includes
+          end
+
+          # Applied to the single-resource lookup by the base controller.
+          def scope_includes
+            product_listing_includes
+          end
+
+          private
+
+          def product_listing_includes
+            [
+              :tax_category,
+              :product_type,
+              :external_references,
+              { product_publications: :channel },
+              { primary_media: [attachment_attachment: :blob, poster_attachment: :blob] },
+              { default_variant: [:prices, { stock_levels: [:stock_location, :active_stock_reservations] }] },
+              { variants: [:prices, { stock_levels: [:stock_location, :active_stock_reservations] }] }
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/product_membership.rb

@@ -0,0 +1,110 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The uniform nested products surface every product-curating parent
+        # exposes — categories, collections, catalogs and price lists all
+        # speak the same protocol:
+        #
+        #   GET    /{parents}/:parent_id/products                — paginated members
+        #   POST   /{parents}/:parent_id/products                — { product_ids: [...] } → 201 { added_count }
+        #   DELETE /{parents}/:parent_id/products                — { product_ids: [...] } → 200 { removed_count }
+        #   PATCH  /{parents}/:parent_id/products/:id/reposition — positioned parents only
+        #
+        # Both writes are bulk: one request adds or removes any number of
+        # products. Ids that don't resolve to a product in the current store
+        # are silently dropped, already-present ids don't fail an add, and
+        # non-member ids don't fail a remove — the counts report what actually
+        # changed. Declared in routes through the +:product_membership+
+        # routing concern.
+        #
+        # A host controller implements:
+        #   +set_parent+              — load + authorize the parent record
+        #   +scope+                   — the parent's member products
+        #   +add_member_products+     — persist membership for the given products
+        #   +remove_member_products+  — remove membership for the given products
+        module ProductMembership
+          extend ActiveSupport::Concern
+
+          included do
+            include Spree::Api::V3::Admin::ProductListing
+
+            # Membership actions resolve products themselves; the base
+            # single-resource load has nothing to look up.
+            skip_before_action :set_resource
+          end
+
+          # POST /{parents}/:parent_id/products
+          def create
+            products = requested_products(product_scope)
+            existing_ids = scope.where(id: products.map(&:id)).pluck(:id).to_set
+            new_products = products.reject { |product| existing_ids.include?(product.id) }
+
+            # Counted by re-reading membership rather than trusting the check
+            # above: a concurrent request can claim one of these rows in
+            # between, and the caller is told what actually changed.
+            added = 0
+            if new_products.any?
+              add_member_products(new_products)
+              added = scope.where(id: new_products.map(&:id)).reorder(nil).distinct.count
+            end
+
+            render json: { added_count: added }, status: :created
+          end
+
+          # DELETE /{parents}/:parent_id/products
+          def destroy
+            products = requested_products(scope)
+
+            removed = 0
+            if products.any?
+              remove_member_products(products)
+              # Counted from what is left, for the same reason as `create`.
+              still_members = scope.where(id: products.map(&:id)).reorder(nil).distinct.count
+              removed = products.size - still_members
+            end
+
+            render json: { removed_count: removed }
+          end
+
+          protected
+
+          def model_class
+            Spree::Product
+          end
+
+          def serializer_class
+            Spree.api.admin_product_serializer
+          end
+
+          # @abstract Persist membership for products verified as new members.
+          def add_member_products(_products)
+            raise NotImplementedError
+          end
+
+          # @abstract Remove membership for products verified as members.
+          def remove_member_products(_products)
+            raise NotImplementedError
+          end
+
+          # Products the caller may act on, regardless of membership.
+          def product_scope
+            current_store.products.accessible_by(current_ability, :show)
+          end
+
+          private
+
+          # Resolves the request's `product_ids` against the given relation.
+          # Reordered: a positioned membership scope orders by a join-table
+          # column, which PostgreSQL rejects under the DISTINCT needed here —
+          # a derived scope (a price list's products through its price rows)
+          # can join a product several times.
+          def requested_products(relation)
+            ids = decode_prefixed_ids(Array(params.require(:product_ids)))
+            relation.reorder(nil).where(id: ids).distinct.to_a
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/receivable_actions.rb

@@ -0,0 +1,68 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What a stock transfer and a purchase order have in common as
+        # endpoints: resolving the lines, warehouses and variants a flat
+        # payload names (docs/plans/6.0-inventory-operations.md). The status
+        # workflows themselves are run by the actions, which is where the
+        # keyword each one takes the document under stays visible.
+        #
+        # Every id a payload names is resolved through the store — or through
+        # the document itself, for its own lines — so an id belonging to
+        # another tenant answers 404 rather than being acted on. That is also
+        # why nothing here assigns a `*_id` from the payload, and why the lines
+        # come from the raw payload rather than `permitted_params`: the latter
+        # decodes prefixed ids into primary keys, and a decoded key carries no
+        # evidence of whose record it is.
+        module ReceivableActions
+          extend ActiveSupport::Concern
+          include Spree::Api::V3::ItemsPayload
+
+          protected
+
+          # What rendering a line actually reads: the variant, the product it
+          # belongs to — for the name and the link — and whichever image the
+          # thumbnail falls back to, with the blobs the URL helper needs.
+          def line_includes
+            media = { primary_media: [attachment_attachment: :blob, poster_attachment: :blob] }
+            { items: { variant: [media, { product: media }] } }
+          end
+
+          # The lines a create or update named, or nil when the payload said
+          # nothing about them — which on an update means "leave them alone".
+          #
+          # @param attribute_keys [Array<Symbol>] the per-line attributes this
+          #   document accepts beyond the variant (`:quantity_shipped`,
+          #   `:quantity_ordered`, `:unit_cost`)
+          # @return [Array<Hash>, nil]
+          def items_from_params(*attribute_keys)
+            sent = items_payload([:variant_id, *attribute_keys])
+            return nil if sent.nil?
+
+            sent.map do |item|
+              attributes = { variant: variants_scope.find_by_prefix_id!(item[:variant_id]) }
+              attribute_keys.each { |key| attributes[key] = item[key] if item.key?(key.to_s) }
+              attributes
+            end
+          end
+
+          # Any of the store's warehouses the caller may see, or nil when the
+          # payload did not name one.
+          #
+          # @return [Spree::StockLocation, nil]
+          def stock_location_from(key)
+            id = params[key]
+            return nil if id.blank?
+
+            current_store.stock_locations.accessible_by(current_ability, :show).find_by_prefix_id!(id)
+          end
+
+          def variants_scope
+            current_store.variants.accessible_by(current_ability, :show)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/reporting_authorization.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Per-member authorization for the reporting vocabulary. Metrics,
+        # dimensions and counters all declare a `subject` (checked for JWT
+        # staff through CanCanCan) paired with a `key_scope` (checked for
+        # secret keys), so one predicate answers for every member and every
+        # surface that lists them — the schema, a query, the home screen's
+        # counters — filters by the same rule.
+        module ReportingAuthorization
+          extend ActiveSupport::Concern
+
+          private
+
+          def member_allowed?(member)
+            if current_api_key.present?
+              member.key_scope.blank? || current_api_key.has_scope?(member.key_scope)
+            else
+              member.subject.nil? || can?(:read, member.subject.call)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/role_grant_guard.rb

@@ -2,18 +2,15 @@ module Spree
   module Api
     module V3
       module Admin
-        # Shared guard for staff role grants (admin_users#update and
-        # invitations#create). A grant is rejected when, in order:
+        # Shared anti-amplification guards for everything that hands out
+        # authority: role grants (admin_users#update, invitations#create),
+        # role permission edits (roles#create/#update), and API-key minting.
         #
-        #   1. (opt-in) the caller can't `:create` a Spree::RoleUser — i.e. lacks
-        #      the RoleManagement permission set;
-        #   2. it includes the literal `admin` role and the caller does not hold
-        #      it on the current store;
-        #   3. it includes any role whose permission sets exceed the caller's own
-        #      (catches SuperUser-equivalent custom roles the name check misses).
-        #
-        # API-key principals hold no roles, so they can grant only roles that
-        # activate no permission sets.
+        # The common rule: a caller may only grant authority they effectively
+        # hold, compared as expanded catalog keys. A JWT staffer's grant is the
+        # union of their store-scoped roles' keys; a secret key's grant is its
+        # scopes. Admin-role holders are unbounded; the literal `admin` role is
+        # additionally grantable only by admins.
         module RoleGrantGuard
           extend ActiveSupport::Concern
 
@@ -34,7 +31,7 @@ module Spree
             # past a caller without role-management authority.
             return true if require_role_management && reject_without_role_management!
 
-            roles = Spree::Role.where(id: role_ids.map(&:to_s)).to_a
+            roles = current_store.roles.where(id: role_ids.map(&:to_s)).to_a
             return false if roles.empty?
 
             return true if reject_admin_role_grant!(roles)
@@ -43,6 +40,32 @@ module Spree
             false
           end
 
+          # Rejects granting permission keys beyond the caller's own — used by
+          # roles#create/#update on the requested `permissions` array.
+          #
+          # @param keys [Array<String>]
+          # @return [Boolean] true if the request was rejected
+          def reject_unauthorized_permission_grant!(keys)
+            excess = excess_permission_keys(keys)
+            return false if excess.empty?
+
+            deny_role_grant!(
+              "You cannot grant permissions beyond your own: #{excess.join(', ')}",
+              details: { excess_permissions: excess }
+            )
+          end
+
+          # The requested keys (expanded) the caller does not hold. Empty when
+          # the caller is unbounded.
+          #
+          # @param keys [Array<String>]
+          # @return [Array<String>]
+          def excess_permission_keys(keys)
+            return [] if caller_holds_admin_role?
+
+            Spree.permissions.expand_keys(keys) - caller_permission_keys
+          end
+
           # For API-key principals CanCanCan is permissive (ScopedAuthorization is
           # their gate), so this only constrains JWT admins.
           def reject_without_role_management!
@@ -53,55 +76,68 @@ module Spree
           end
 
           def reject_admin_role_grant!(roles)
-            return false unless roles.any? { |role| role.name == Spree::Role::ADMIN_ROLE }
+            return false unless roles.any?(&:admin?)
             return false if caller_holds_admin_role?
 
             deny_role_grant!('You cannot grant the admin role.')
           end
 
-          # A caller holding the admin role bounds nothing; the literal admin role
-          # is already gated by reject_admin_role_grant!.
+          # A role is grantable when the caller holds every key it carries.
           def reject_privilege_escalating_grant!(roles)
             return false if caller_holds_admin_role?
 
-            caller_sets = Spree.permissions.permission_sets_for_roles(caller_role_names)
-            escalating = roles.reject { |role| grantable_within?(role, caller_sets) }
+            escalating = roles.reject { |role| excess_permission_keys(role.permissions).empty? }
             return false if escalating.empty?
 
             deny_role_grant!("You cannot grant roles beyond your own privileges: #{escalating.map(&:name).join(', ')}")
           end
 
-          # A role is grantable when every permission set it activates is one the
-          # caller already holds.
-          def grantable_within?(role, caller_sets)
-            (Spree.permissions.permission_sets_for(role.name) - caller_sets).empty?
+          # The caller's effective grant as expanded catalog keys. A JWT
+          # staffer contributes their store-scoped roles' keys; a secret-key
+          # principal contributes its scopes (aliases expand against the
+          # catalog).
+          #
+          # @return [Array<String>]
+          def caller_permission_keys
+            @caller_permission_keys ||=
+              if scope_limited_principal?
+                Spree.permissions.expand_keys(current_api_key.scopes)
+              else
+                Spree.permissions.expand_keys(caller_roles.flat_map(&:permissions))
+              end
           end
 
-          # The caller's store-scoped role names, fetched once per request.
-          # Scoped by store_id so the caller's own privileges are recognized even
-          # when their role is held on a non-store resource bound to this store.
-          def caller_role_names
-            return @caller_role_names if defined?(@caller_role_names)
+          # The caller's roles on this store, fetched once per request,
+          # mirroring `Spree::Ability#staff_roles`: a role owned by another
+          # resource (a marketplace seller) confers no store-admin authority
+          # and must not widen what the caller may grant.
+          #
+          # @return [Array<Spree::Role>]
+          def caller_roles
+            return @caller_roles if defined?(@caller_roles)
 
             user = try_spree_current_user
-            @caller_role_names =
-              if user.respond_to?(:role_users)
-                user.role_users.where(store: current_store).joins(:role).
-                  pluck("#{Spree::Role.table_name}.name")
+            @caller_roles =
+              if user.respond_to?(:spree_roles)
+                user.spree_roles.for_resource(current_store).to_a
               else
                 []
               end
           end
 
           def caller_holds_admin_role?
-            caller_role_names.include?(Spree::Role::ADMIN_ROLE)
+            return current_api_key.has_scope?('write_all') if scope_limited_principal?
+
+            caller_roles.any?(&:admin?) ||
+              try_spree_current_user.try(:spree_admin?, current_store)
           end
 
-          def deny_role_grant!(message)
+          def deny_role_grant!(message, details: nil)
             render_error(
               code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
               message: message,
-              status: :forbidden
+              status: :forbidden,
+              details: details
             )
             true
           end

data/app/controllers/concerns/spree/api/v3/admin/stock_receipt_actions.rb

@@ -0,0 +1,86 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The deliveries nested under a purchase order or a transfer. Listing
+        # and showing come from the base controller; recording one runs the
+        # document's receive workflow, which the including controller names
+        # along with the keyword it takes the document under.
+        #
+        # Every line a payload names is resolved through the document itself,
+        # so a line from another order or transfer cannot be received here.
+        module StockReceiptActions
+          extend ActiveSupport::Concern
+          include Spree::Api::V3::ItemsPayload
+
+          included do
+            before_action :authorize_parent_access!
+          end
+
+          protected
+
+          def model_class
+            Spree::StockReceipt
+          end
+
+          def serializer_class
+            Spree.api.admin_stock_receipt_serializer
+          end
+
+          def parent_association
+            :stock_receipts
+          end
+
+          def scope
+            @parent.stock_receipts
+          end
+
+          def collection_includes
+            [items: :line]
+          end
+
+          def resource_permitted_attributes
+            [:received_at, :reference, :notes]
+          end
+
+          def create_workflow_arguments
+            {
+              receivable_keyword => @parent,
+              items: items_for_receipt,
+              received_at: params[:received_at],
+              reference: params[:reference],
+              notes: params[:notes],
+              received_by: try_spree_current_user
+            }
+          end
+
+          # What this delivery brought, per line. An omitted `items` means
+          # "everything still outstanding arrived intact"; an explicit list —
+          # even an empty one — is what the dock counted, and nothing more.
+          #
+          # @return [Array<Hash>, nil]
+          def items_for_receipt
+            sent = items_payload(%i[id quantity_accepted quantity_rejected rejection_reason notes])
+            return nil if sent.nil?
+
+            sent.map do |item|
+              {
+                item: @parent.items.find_by_prefix_id!(item[:id]),
+                quantity_accepted: item[:quantity_accepted],
+                quantity_rejected: item[:quantity_rejected],
+                rejection_reason: item[:rejection_reason],
+                notes: item[:notes]
+              }
+            end
+          end
+
+          # Reading receipts needs only to see the document; booking one is a
+          # change to it.
+          def authorize_parent_access!
+            authorize_parent!(@parent)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/store_context.rb

@@ -0,0 +1,97 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API store context (docs/plans/6.0-store-context-and-first-run-setup.md):
+        # a secret key selects its bound store; JWT staff sessions select via
+        # the +X-Spree-Store-Id+ header (the admin SDK sends it on every
+        # request) and are membership-checked against the store resolved here
+        # by AdminAuthentication#require_store_membership!. The request host
+        # is never consulted.
+        #
+        # Included in both Admin API branch anchors (Admin::BaseController and
+        # Admin::ResourceController) alongside AdminAuthentication.
+        module StoreContext
+          extend ActiveSupport::Concern
+
+          STORE_HEADER = 'X-Spree-Store-Id'.freeze
+
+          included do
+            # Prepended so Spree::Current.store reflects the requested store
+            # before any other callback (locale/currency fallbacks, resource
+            # lookups) reads it. The store-presence guard 404s an unknown
+            # header ID right after this runs.
+            prepend_before_action :set_current_store_context
+
+            # Once-per-process latch for the missing-header notice.
+            class_attribute :missing_store_header_warned, default: false, instance_accessor: false
+          end
+
+          # Resolution order: the secret key's bound store, then the header,
+          # then the default store — deprecated for JWT requests; the header
+          # becomes required in 6.1.
+          #
+          # @return [Spree::Store, nil]
+          def current_store
+            return @current_store if defined?(@current_store)
+
+            @current_store = resolve_admin_store
+          end
+
+          private
+
+          def set_current_store_context
+            if secret_api_key && store_id_header && secret_api_key.store&.prefixed_id != store_id_header
+              render_error(
+                code: ErrorHandler::ERROR_CODES[:access_denied],
+                message: Spree.t('api.errors.store_mismatch', default: 'The requested store does not match the store this API key belongs to.'),
+                status: :forbidden
+              )
+              return
+            end
+
+            # Assigned even when nil: an unknown store id renders 404 further
+            # down the chain, and leaving Spree::Current.store holding the
+            # previous request's value on this thread would expose another
+            # store to anything reading it before that 404 lands.
+            Spree::Current.store = current_store
+          end
+
+          def resolve_admin_store
+            return secret_api_key.store if secret_api_key
+
+            if store_id_header
+              Spree::Store.find_by_prefix_id(store_id_header)
+            else
+              # Only warn for authenticated staff traffic — credential-less
+              # requests (login, refresh, invitation acceptance) are
+              # store-agnostic and legitimately send no header.
+              warn_missing_store_header if request.authorization.present?
+              Spree::Store.default
+            end
+          end
+
+          def store_id_header
+            request.headers[STORE_HEADER].presence
+          end
+
+          # A plain once-per-process log line, deliberately NOT
+          # Spree::Deprecation: some endpoints structurally cannot carry the
+          # header (`/me` runs before any store is selected — it is how the
+          # dashboard discovers the user's stores), so a per-request
+          # deprecation would be pure noise and would 500 every login
+          # bootstrap for apps running deprecations-as-errors.
+          def warn_missing_store_header
+            return if self.class.missing_store_header_warned
+            self.class.missing_store_header_warned = true
+
+            Rails.logger&.info(
+              "Admin API v3 requests without an #{STORE_HEADER} header fall back to the default store. " \
+              'Multi-store clients should send the header; store-agnostic endpoints (/me, auth) are exempt.'
+            )
+          end
+        end
+      end
+    end
+  end
+end