spree_api 5.4.3 → 5.5.0.rc1

data/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb

@@ -0,0 +1,75 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API for outbound webhook endpoints — CRUD plus the three
+        # endpoint-scoped actions the legacy admin had (send_test, enable,
+        # disable).
+        class WebhookEndpointsController < ResourceController
+          scoped_resource :settings
+
+          # POST /api/v3/admin/webhook_endpoints/:id/send_test
+          #
+          # Fires a synthetic `webhook.test` delivery so admins can verify the
+          # endpoint is reachable + their signature-verification code works.
+          #
+          # @return [Hash] the serialized {Spree::WebhookDelivery}, HTTP 201.
+          def send_test
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            delivery = @resource.send_test!
+            render json: Spree.api.admin_webhook_delivery_serializer.new(delivery).to_h, status: :created
+          end
+
+          # PATCH /api/v3/admin/webhook_endpoints/:id/enable
+          #
+          # Re-enables an endpoint that was auto-disabled after repeated failures.
+          #
+          # @return [Hash] the serialized {Spree::WebhookEndpoint}.
+          def enable
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            @resource.enable!
+            render json: serialize_resource(@resource)
+          end
+
+          # PATCH /api/v3/admin/webhook_endpoints/:id/disable
+          #
+          # Manual disable — separate from the auto-disable threshold so the
+          # caller can pause an endpoint without waiting for failures.
+          #
+          # @param reason [String] optional human-readable reason; defaults to
+          #   `"Manually disabled"` when blank.
+          # @return [Hash] the serialized {Spree::WebhookEndpoint}.
+          def disable
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            @resource.disable!(reason: params[:reason].presence || 'Manually disabled', notify: false)
+            render json: serialize_resource(@resource)
+          end
+
+          protected
+
+          def model_class
+            Spree::WebhookEndpoint
+          end
+
+          def serializer_class
+            Spree.api.admin_webhook_endpoint_serializer
+          end
+
+          def scope
+            current_store.webhook_endpoints.accessible_by(current_ability, :show)
+          end
+
+          def permitted_params
+            params.permit(:name, :url, :active, subscriptions: [])
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -2,6 +2,11 @@ module Spree
   module Api
     module V3
       class ResourceController < BaseController
+        include Spree::Api::V3::ParamsNormalizer
+
+        # Must run before +set_resource+: +scope+'s +accessible_by+ depends on
+        # the post-authentication +current_ability+.
+        before_action :authenticate_request!
         before_action :set_parent
         before_action :set_resource, only: [:show, :update, :destroy]
 
@@ -48,13 +53,36 @@ module Spree
         end
 
         # DELETE /api/v3/resource/:id
+        # Domain rules like "redeemed gift cards cannot be deleted" live on
+        # the model via `can_be_deleted?` and apply to all callers (JWT and
+        # API key). When `can_be_deleted?` returns false we render 422
+        # (resource state forbids the request) rather than 403, since the
+        # caller is authorized — it's the resource's state that's blocking
+        # the operation. Models that prefer CanCan-gated destroy can opt in
+        # via their ability (e.g. `can :destroy, Spree::Order, &:can_be_deleted?`),
+        # which raises before the controller hook fires and yields 403.
         def destroy
-          @resource.destroy
+          if @resource.respond_to?(:can_be_deleted?) && !@resource.can_be_deleted?
+            message = Spree.t(:cannot_delete, scope: 'api', model: @resource.class.model_name.human)
+            return render_error(
+              code: ERROR_CODES[:validation_error],
+              message: message,
+              status: :unprocessable_content
+            )
+          end
+
+          @resource.destroy!
           head :no_content
+        rescue ActiveRecord::RecordNotDestroyed => e
+          render_validation_error(e.record.errors.presence || e.message)
         end
 
         protected
 
+        def authenticate_request!
+          raise NotImplementedError, "#{self.class} must implement authenticate_request!"
+        end
+
         # No-op HTTP caching methods. Include Spree::Api::V3::HttpCaching
         # in specific controllers to enable HTTP caching for their actions.
         def cache_collection(_collection, **_options)
@@ -80,11 +108,16 @@ module Spree
 
         # Builds a new resource, using parent association when @parent is set
         def build_resource
-          if @parent.present?
-            @parent.send(parent_association).build(permitted_params)
-          else
-            model_class.new(permitted_params)
-          end
+          resource = if @parent.present?
+                       @parent.send(parent_association).build(permitted_params)
+                     else
+                       model_class.new(permitted_params)
+                     end
+          resource.store = current_store if resource.respond_to?(:store_id) && resource.store_id.blank?
+          # very ugly code we need to still support for promotion/payment_method until we migrate them into single store in spree 6.0
+          resource.store_ids = [current_store.id] if resource.respond_to?(:store_ids) && resource.store_ids.blank? && !resource.respond_to?(:store_id)
+          resource.created_by = try_spree_current_user if resource.respond_to?(:created_by_id)
+          resource
         end
 
         # Finds a single resource within scope using prefixed ID
@@ -133,8 +166,11 @@ module Spree
         # Ransack query parameters with sort translation.
         # Translates `-field` notation (JSON:API standard) to Ransack `s` format.
         # e.g., sort=-price,name → s=price desc,name asc
+        # Also decodes Stripe-style prefixed IDs found in keys like `*_id_eq`,
+        # `*_id_in`, `*_id_not_eq`, etc. so SPA filters can pass prefixed IDs.
         def ransack_params
           rp = params[:q]&.to_unsafe_h || params[:q] || {}
+          rp = decode_prefixed_id_predicates(rp)
           sort_value = sort_param
 
           if sort_value.present?
@@ -151,6 +187,37 @@ module Spree
           rp
         end
 
+        def decode_prefixed_id_predicates(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            result[key] = if ransack_id_predicate?(key)
+                            Array(value).map { |v| Spree::PrefixedId.prefixed_id?(v) ? Spree::PrefixedId.decode_prefixed_id(v) || v : v }.then { |arr|
+                              value.is_a?(Array) ? arr : arr.first
+                            }
+                          elsif value.is_a?(Hash)
+                            decode_prefixed_id_predicates(value)
+                          else
+                            value
+                          end
+          end
+        end
+
+        # Matches both prefixed-FK predicates (`product_id_in`, `tax_category_id_eq`)
+        # and the bare-`id` predicates (`id_in`, `id_eq`) on the resource's
+        # primary key. Without the bare-id branch, `q[id_in][]=prod_x` would
+        # be passed to Ransack verbatim and never match any row.
+        #
+        # Requires a Ransack-predicate suffix (`_eq`, `_in`, ...) — bare
+        # `_id`/`_ids` keys without a suffix are scope names, not predicates
+        # (e.g. `with_option_value_ids` is a custom scope that handles its
+        # own decoding). Decoding those would double-strip prefixes and
+        # break downstream filter code.
+        RANSACK_ID_PREDICATE_RE = /(?:\A|_)id(?:s)?_(?:eq|not_eq|in|not_in|lt|lteq|gt|gteq)\z/.freeze
+        def ransack_id_predicate?(key)
+          RANSACK_ID_PREDICATE_RE.match?(key.to_s)
+        end
+
         # Sort parameter from the request
         def sort_param
           params[:sort]
@@ -194,7 +261,22 @@ module Spree
                        else
                          model_class.for_store(current_store)
                        end
-          base_scope = base_scope.accessible_by(current_ability, :show) unless @parent.present?
+          unless @parent.present?
+            action_name = case request.method
+                          when 'GET', 'HEAD'
+                            :show
+                          when 'POST'
+                            :create
+                          when 'PATCH', 'PUT'
+                            :update
+                          when 'DELETE'
+                            :destroy
+                          else
+                            raise ActionController::MethodNotAllowed, request.method
+                          end
+
+            base_scope = base_scope.accessible_by(current_ability, action_name)
+          end
           base_scope = base_scope.includes(scope_includes) if scope_includes.any?
           base_scope = base_scope.preload_associations_lazily
           model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
@@ -228,7 +310,7 @@ module Spree
         #
         # Override in subclass for custom parameter handling
         def permitted_params
-          params.permit(permitted_attributes)
+          normalize_params(params.permit(permitted_attributes))
         end
 
         # Returns the permitted attributes list for the model

data/app/controllers/spree/api/v3/store/auth_controller.rb

@@ -6,10 +6,9 @@ module Spree
           # Tighter rate limits for auth endpoints (per IP to prevent brute force)
           rate_limit to: Spree::Api::Config[:rate_limit_login], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
           rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_oauth], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :oauth_callback, with: RATE_LIMIT_RESPONSE
           rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :logout, with: RATE_LIMIT_RESPONSE
 
-          skip_before_action :authenticate_user, only: [:create, :refresh, :oauth_callback]
+          skip_before_action :authenticate_user, only: [:create, :refresh, :logout]
 
           # POST  /api/v3/store/auth/login
           # Supports multiple authentication providers via :provider param
@@ -69,37 +68,17 @@ module Spree
 
           # POST  /api/v3/store/auth/logout
           # Accepts: { "refresh_token": "rt_xxx" }
-          # Revokes the refresh token
+          # Revokes the submitted refresh token. The token itself is the
+          # credential — no access JWT is required, so clients with an expired
+          # access token can still log out.
           def logout
             refresh_token_value = params[:refresh_token]
 
-            if refresh_token_value.present?
-              Spree::RefreshToken.find_by(token: refresh_token_value)&.destroy
-            end
+            Spree::RefreshToken.find_by(token: refresh_token_value)&.destroy if refresh_token_value.present?
 
             head :no_content
           end
 
-          # POST  /api/v3/store/auth/oauth/callback
-          # OAuth callback endpoint for server-side OAuth flows
-          def oauth_callback
-            strategy = authentication_strategy
-            return unless strategy # Error already rendered by determine_strategy
-
-            result = strategy.authenticate
-
-            if result.success?
-              user = result.value
-              render json: auth_response(user)
-            else
-              render_error(
-                code: ERROR_CODES[:authentication_failed],
-                message: result.error,
-                status: :unauthorized
-              )
-            end
-          end
-
           protected
 
           def serializer_params
@@ -133,6 +112,8 @@ module Spree
 
           def authentication_strategy
             strategy_class = determine_strategy
+            return nil unless strategy_class
+
             strategy_class.new(
               params: params,
               request_env: request.headers.env,
@@ -142,10 +123,9 @@ module Spree
 
           def determine_strategy
             provider = params[:provider].presence || 'email'
-            provider_key = provider.to_sym
 
             # Retrieve pre-loaded strategy class from configuration
-            strategy_class = Rails.application.config.spree.store_authentication_strategies[provider_key]
+            strategy_class = Spree.store_authentication_strategies[provider]
 
             unless strategy_class
               render_error(

data/app/controllers/spree/api/v3/store/base_controller.rb

@@ -3,6 +3,12 @@ module Spree
     module V3
       module Store
         class BaseController < Spree::Api::V3::BaseController
+          # Channel resolution is a Store API concern — admin endpoints return
+          # data across all channels and filter via Ransack instead. Including
+          # this here keeps the +X-Spree-Channel+ header from accidentally
+          # narrowing admin queries.
+          include Spree::Api::V3::ChannelResolution
+
           # Require publishable API key for all Store API requests
           before_action :authenticate_api_key!
         end

data/app/controllers/spree/api/v3/store/carts_controller.rb

@@ -34,6 +34,7 @@ module Spree
               params: permitted_params.merge(
                 user: current_user,
                 store: current_store,
+                channel: current_channel,
                 currency: current_currency,
                 locale: current_locale
               )

data/app/controllers/spree/api/v3/store/customers_controller.rb

@@ -13,6 +13,7 @@ module Spree
             user = Spree.user_class.new(permitted_params.except(:current_password))
 
             if user.save
+              link_matching_newsletter_subscriber!(user)
               refresh_token = Spree::RefreshToken.create_for(user, request_env: {
                 ip_address: request.remote_ip,
                 user_agent: request.user_agent&.truncate(255)
@@ -94,6 +95,11 @@ module Spree
           def user_serializer
             Spree.api.customer_serializer
           end
+
+          def link_matching_newsletter_subscriber!(user)
+            subscriber = Spree::NewsletterSubscriber.find_by(email: user.email, store: current_store)
+            Spree::Newsletter::LinkUser.new(subscriber: subscriber, user: user).call
+          end
         end
       end
     end

data/app/controllers/spree/api/v3/store/newsletter_subscribers_controller.rb

@@ -0,0 +1,77 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        class NewsletterSubscribersController < Store::BaseController
+          rate_limit to: Spree::Api::Config[:rate_limit_register],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     only: [:create, :verify],
+                     with: RATE_LIMIT_RESPONSE
+
+          # POST /api/v3/store/newsletter_subscribers
+          def create
+            subscriber = Spree::NewsletterSubscriber.subscribe(
+              email: params[:email],
+              user: current_user,
+              store: current_store,
+              redirect_url: validated_redirect_url
+            )
+
+            if subscriber.errors.any?
+              render_errors(subscriber.errors)
+            else
+              render json: serialize_resource(subscriber), status: :created
+            end
+          end
+
+          # POST /api/v3/store/newsletter_subscribers/verify
+          def verify
+            token = params[:token]
+
+            if token.blank?
+              return render_error(
+                code: ERROR_CODES[:parameter_missing],
+                message: 'token is required',
+                status: :unprocessable_content
+              )
+            end
+
+            subscriber = Spree::NewsletterSubscriber.for_store(current_store).unverified.find_by(verification_token: token)
+
+            unless subscriber
+              return render_error(
+                code: ERROR_CODES[:invalid_token],
+                message: Spree.t(:newsletter_verification_token_invalid, scope: :api),
+                status: :unprocessable_content
+              )
+            end
+
+            Spree::Newsletter::Verify.new(subscriber: subscriber).call
+
+            render json: serialize_resource(subscriber)
+          end
+
+          protected
+
+          def serializer_class
+            Spree::Api::V3::NewsletterSubscriberSerializer
+          end
+
+          private
+
+          # Drop redirect_url when it isn't in the store's allow-list — secure-by-default,
+          # mirrors password_resets. Returning nil omits it from the webhook payload rather
+          # than rejecting the request, so callers can't probe the allow-list via 4xx errors.
+          def validated_redirect_url
+            redirect_url = params[:redirect_url]
+            return nil if redirect_url.blank?
+            return nil unless current_store.allowed_origin?(redirect_url)
+
+            redirect_url
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/products/filters_controller.rb

@@ -29,7 +29,7 @@ module Spree
 
             def filters_cache_key
               products_table = Spree::Product.table_name
-              stats = current_store.products.active(current_currency)
+              stats = current_store.products.available(Time.current, current_currency)
                         .pick(Arel.sql("MAX(#{products_table}.updated_at)"), Arel.sql("COUNT(DISTINCT #{products_table}.id)"))
               max_updated = stats&.first&.to_i
               product_count = stats&.last || 0
@@ -50,7 +50,7 @@ module Spree
             end
 
             def filters_scope
-              scope = current_store.products.active(current_currency)
+              scope = current_store.products.available(Time.current, current_currency)
               scope = scope.in_category(category) if category.present?
               scope.accessible_by(current_ability, :show)
             end

data/app/controllers/spree/api/v3/store/products_controller.rb

@@ -29,15 +29,15 @@ module Spree
           end
 
           def scope
-            super.active(Spree::Current.currency)
+            super.available(Time.current, Spree::Current.currency)
           end
 
           # these scopes are not automatically picked by ar_lazy_preload gem and we need to explicitly include them
           def scope_includes
             [
               primary_media: [attachment_attachment: :blob],
-              master: [:prices, stock_items: :stock_location],
-              variants: [:prices, stock_items: :stock_location]
+              master: [:prices, stock_items: [:stock_location, :active_stock_reservations]],
+              variants: [:prices, stock_items: [:stock_location, :active_stock_reservations]]
             ]
           end
 

data/app/controllers/spree/api/v3/store/resource_controller.rb

@@ -2,9 +2,17 @@ module Spree
   module Api
     module V3
       module Store
+        # Mirrors Store::BaseController's concerns. Both classes anchor parallel
+        # inheritance branches (V3::BaseController vs V3::ResourceController);
+        # any concern added here MUST also be added to Store::BaseController.
         class ResourceController < Spree::Api::V3::ResourceController
-          # Require publishable API key for all Store API requests
-          before_action :authenticate_api_key!
+          include Spree::Api::V3::ChannelResolution
+
+          protected
+
+          def authenticate_request!
+            authenticate_api_key!
+          end
         end
       end
     end

data/app/jobs/spree/webhook_delivery_job.rb

@@ -4,7 +4,12 @@ module Spree
   class WebhookDeliveryJob < Spree::BaseJob
     queue_as Spree.queues.webhooks
 
+    # Webhook delivery hits external endpoints; broad retry covers network timeouts,
+    # 5xx, DNS failures, etc.
     retry_on StandardError, wait: :polynomially_longer, attempts: 5
+    # Must come after `retry_on StandardError` so DeserializationError lands in discard
+    # (ActiveJob handler lookup is reverse-declaration-order).
+    discard_on ActiveJob::DeserializationError
 
     # Accept optional second argument for backward compatibility with jobs
     # enqueued before this change was deployed.

data/app/models/spree/api_key_ability.rb

@@ -0,0 +1,16 @@
+module Spree
+  # CanCanCan ability used for API-key-authenticated admin requests.
+  # Grants full access — authorization happens at the scope-check layer
+  # (Spree::Api::V3::ScopedAuthorization), not at the per-record CanCanCan
+  # layer. This exists so that `accessible_by(current_ability, :show)` in
+  # admin controllers returns the unrestricted scope (it would otherwise
+  # require a real Spree::Ability with role lookups, which doesn't apply
+  # to API key principals).
+  class ApiKeyAbility
+    include CanCan::Ability
+
+    def initialize(_options = {})
+      can :manage, :all
+    end
+  end
+end

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

@@ -5,18 +5,14 @@ module Spree
         class AddressSerializer < V3::AddressSerializer
           typelize label: [:string, nullable: true],
                    customer_id: [:string, nullable: true],
-                   metadata: 'Record<string, unknown> | null'
+                   metadata: 'Record<string, unknown>'
 
-          attributes :label,
+          attributes :label, :metadata,
                      created_at: :iso8601, updated_at: :iso8601
 
           attribute :customer_id do |address|
             address.user&.prefixed_id
           end
-
-          attribute :metadata do |address|
-            address.metadata.presence
-          end
         end
       end
     end

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

@@ -4,31 +4,19 @@ module Spree
       module Admin
         class AdjustmentSerializer < V3::BaseSerializer
           typelize label: :string, amount: :string, display_amount: :string,
-                   state: :string, eligible: :boolean, mandatory: :boolean, included: :boolean,
-                   source_type: [:string, nullable: true],
-                   adjustable_type: :string, adjustable_id: :string,
-                   order_id: [:string, nullable: true],
-                   source_id: [:string, nullable: true]
+                   included: :boolean,
+                   order_id: [:string, nullable: true]
 
-          attributes :label, :display_amount, :state, :eligible, :mandatory, :included,
-                     :source_type, :adjustable_type,
+          attributes :label, :display_amount, :included,
                      created_at: :iso8601, updated_at: :iso8601
 
           attribute :amount do |adjustment|
             adjustment.amount.to_s
           end
 
-          attribute :adjustable_id do |adjustment|
-            adjustment.adjustable&.prefixed_id
-          end
-
           attribute :order_id do |adjustment|
             adjustment.order&.prefixed_id
           end
-
-          attribute :source_id do |adjustment|
-            adjustment.source&.prefixed_id
-          end
         end
       end
     end

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

@@ -3,11 +3,27 @@ module Spree
     module V3
       module Admin
         class AdminUserSerializer < V3::BaseSerializer
-          typelize email: :string, first_name: [:string, nullable: true],
-                   last_name: [:string, nullable: true]
+          typelize email: :string,
+                   first_name: [:string, nullable: true],
+                   last_name: [:string, nullable: true],
+                   full_name: [:string, nullable: true],
+                   roles: 'Array<{ id: string; name: string }>'
 
-          attributes :email, :first_name, :last_name,
+          attributes :email, :first_name, :last_name, :full_name,
                      created_at: :iso8601, updated_at: :iso8601
+
+          # Roles assigned to this user *for the current store*. Each store
+          # gets its own role set via `Spree::RoleUser`, so this attribute is
+          # scoped against `current_store` rather than returning every role
+          # the user might have on other stores. Block receives `params`
+          # only when Alba passes it through the `serializer_params` hash —
+          # we fall back to `Spree::Current.store` if not.
+          attribute :roles do |user, params|
+            store = params&.dig(:store) || Spree::Current.store
+            scope = user.role_users
+            scope = scope.where(resource: store) if store
+            scope.includes(:role).map { |ru| { id: ru.role.prefixed_id, name: ru.role.name } }
+          end
         end
       end
     end

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

@@ -5,13 +5,9 @@ module Spree
     module V3
       module Admin
         class AllowedOriginSerializer < V3::BaseSerializer
-          typelize store_id: :string
+          typelize origin: :string
 
-          attributes :id, :origin, created_at: :iso8601, updated_at: :iso8601
-
-          attribute :store_id do |allowed_origin|
-            allowed_origin.store&.prefixed_id
-          end
+          attributes :origin, created_at: :iso8601, updated_at: :iso8601
         end
       end
     end

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::ApiKey}.
+        #
+        # Never exposes `token` or `token_digest` — only the 12-char
+        # `token_prefix` (e.g. `sk_abc123def`) so existing keys can be
+        # identified in the UI without leaking material that would let an
+        # attacker make requests. The full plaintext token is delivered
+        # exactly once, as the response body of `POST /api/v3/admin/api_keys`,
+        # via {#plaintext_token} below — it is `nil` everywhere else.
+        class ApiKeySerializer < V3::BaseSerializer
+          typelize name: :string,
+                   key_type: :string,
+                   token_prefix: [:string, nullable: true],
+                   plaintext_token: [:string, nullable: true],
+                   scopes: [:string, multi: true],
+                   revoked_at: [:string, nullable: true],
+                   last_used_at: [:string, nullable: true],
+                   created_by_email: [:string, nullable: true]
+
+          attributes :name, :key_type, :token_prefix, :scopes,
+                     created_at: :iso8601, updated_at: :iso8601,
+                     revoked_at: :iso8601, last_used_at: :iso8601
+
+          # Returned only on the create response — `plaintext_token` is held in
+          # memory on the model after `generate_token` and is never persisted
+          # for secret keys, so we serialize it whenever it's available rather
+          # than gating on the action.
+          attribute :plaintext_token do |key|
+            key.plaintext_token
+          end
+
+          attribute :created_by_email do |key|
+            key.created_by&.email
+          end
+        end
+      end
+    end
+  end
+end