spree_api 5.6.1 → 6.0.0.beta2

data/app/controllers/concerns/spree/api/v3/orders/fulfillment_actions.rb

@@ -0,0 +1,157 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Dispatching what is owed on an order: shipping a parcel, cancelling
+        # one, and splitting goods that leave separately.
+        #
+        # Shared by the operator's branch and the seller's, which run the same
+        # workflows. What differs is only *whose records a payload may name*,
+        # and that stays in the including controller: this concern never
+        # fetches an order, a variant or a stock location. `@order` and
+        # `@resource` arrive already fetched and authorized — through
+        # `current_store` on one branch, `current_seller_orders` on the other
+        # — and this code never learns which.
+        module FulfillmentActions
+          extend ActiveSupport::Concern
+
+          # PATCH .../fulfillments/:id
+          def update
+            with_order_lock do
+              result = Spree.fulfillment_update_workflow.call(
+                fulfillment: @resource, fulfillment_attributes: update_attributes
+              )
+
+              if result.success?
+                render json: serialize_resource(@resource.reload)
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # PATCH .../fulfillments/:id/fulfill
+          #
+          # Ships the parcel. `items` narrows it to part of what the
+          # fulfillment holds, which splits the rest onto a new one.
+          def fulfill
+            with_order_lock do
+              result = Spree.fulfillment_fulfill_workflow.call(
+                fulfillment: @resource,
+                items: items_for_fulfill,
+                tracking: fulfill_params[:tracking],
+                tracking_carrier: fulfill_params[:tracking_carrier],
+                notify_customer: notify_customer?(fulfill_params[:notify_customer]),
+                **fulfill_workflow_options
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # PATCH .../fulfillments/:id/cancel
+          #
+          # Restocking and standing the carrier down happen in the workflow.
+          def cancel
+            with_order_lock do
+              result = Spree.fulfillment_cancel_workflow.call(fulfillment: @resource)
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # PATCH .../fulfillments/:id/split
+          #
+          # Moves part of what this parcel holds onto one of its own, for
+          # goods leaving separately. Answers with every fulfillment on the
+          # order, since splitting rewrites more than one.
+          def split
+            with_order_lock do
+              changer = @resource.transfer_to_location(
+                variant_for_split, params[:quantity].to_i, stock_location_for_split
+              )
+
+              if changer.run!
+                render json: {
+                  data: @order.reload.fulfillments.map { |fulfillment| serialize_resource(fulfillment) }
+                }
+              else
+                render_validation_error(changer.errors)
+              end
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::Fulfillment
+          end
+
+          def parent_association
+            :fulfillments
+          end
+
+          private
+
+          def fulfill_params
+            @fulfill_params ||= params.permit(*fulfill_permitted_keys)
+          end
+
+          def fulfill_permitted_keys
+            [:tracking, :tracking_carrier, :notify_customer, { items: [:item_id, :quantity] }]
+          end
+
+          # Extra keywords the branch's own fulfil accepts — forcing past a
+          # guard is the operator's call, so the seller adds nothing.
+          def fulfill_workflow_options
+            {}
+          end
+
+          # The workflow addresses what to ship by line item, and the lookup
+          # runs through the order so an id from elsewhere cannot be shipped.
+          def items_for_fulfill
+            return if fulfill_params[:items].nil?
+
+            fulfill_params[:items].map do |item|
+              {
+                line_item: @order.line_items.find_by_prefix_id!(item[:item_id]),
+                quantity: Integer(item[:quantity].to_s, exception: false)
+              }
+            end
+          end
+
+          # Only an explicit false suppresses the email; an omitted flag keeps
+          # sending it.
+          def notify_customer?(value)
+            !ActiveModel::Type::Boolean.new.cast(value).equal?(false)
+          end
+
+          # The attributes handed to the update workflow. The workflow assigns
+          # ids raw, so a branch that must narrow one resolves it here first.
+          def update_attributes
+            permitted_params.to_h
+          end
+
+          # What may be split out of this parcel, and where the split half
+          # ships from. Both are left to the including controller: they decide
+          # whose catalogue and whose shelves are reachable.
+          def variant_for_split
+            raise NotImplementedError, "#{self.class} must implement #variant_for_split"
+          end
+
+          def stock_location_for_split
+            raise NotImplementedError, "#{self.class} must implement #stock_location_for_split"
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/orders/post_sale_actions.rb

@@ -0,0 +1,76 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # What every post-sale record on an order has in common: it is opened
+        # against the order, and then moved through its statuses one named
+        # action at a time.
+        #
+        # Shared by the operator's branch and the seller's, which run the same
+        # workflows with the same arguments. What differs between them is only
+        # *whose records a payload may name*, and that stays in the including
+        # controller: this concern never fetches an order, a variant or a
+        # stock location, so including it cannot widen what a caller reaches.
+        # `@order` and `@resource` arrive already fetched and authorized —
+        # through `current_store` on one branch, `current_seller_orders` on
+        # the other — and this code never learns which.
+        module PostSaleActions
+          extend ActiveSupport::Concern
+          include Spree::Api::V3::ItemsPayload
+
+          protected
+
+          # Runs one of the record's status workflows and renders the result.
+          #
+          # The keyword the workflow expects for the record itself differs per
+          # entity (+return_record:+, +exchange:+, +claim:+), so each concern
+          # names its own.
+          def run_workflow(workflow, **arguments)
+            result = workflow.call(workflow_record_key => @resource, **arguments)
+
+            if result.success?
+              render json: serialize_resource(result.value)
+            else
+              render_result_error(result)
+            end
+          end
+
+          # @return [Symbol] the keyword this entity's workflows take it under
+          def workflow_record_key
+            raise NotImplementedError, "#{self.class} must implement #workflow_record_key"
+          end
+
+          # The units a receive request named, or nil when it named none.
+          # See {Spree::Api::V3::ItemsPayload} for what omitted and empty mean.
+          #
+          # @param keys [Array<Symbol>] the per-item keys to permit
+          # @return [Array<ActionController::Parameters>, nil]
+          def received_items(keys)
+            items_payload(keys)
+          end
+
+          # Opens the record against the order, through the entity's create
+          # workflow.
+          def create_post_sale_record(workflow, subject, **arguments)
+            authorize!(:create, subject)
+
+            result = workflow.call(
+              order: @order,
+              items: items_for_create,
+              reason: reason_for_create,
+              memo: create_params[:memo],
+              created_by: current_actor,
+              **arguments
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value), status: :created
+            else
+              render_result_error(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/orders/return_actions.rb

@@ -0,0 +1,116 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Goods coming back on an order: opening the return, and the four
+        # moves that settle it.
+        #
+        # See {PostSaleActions} for why the lookups a payload's ids resolve
+        # through are deliberately left to the including controller.
+        module ReturnActions
+          extend ActiveSupport::Concern
+          include PostSaleActions
+
+          # POST .../returns
+          def create
+            create_post_sale_record(
+              Spree.return_create_workflow, Spree::Return,
+              stock_location: stock_location_for_create
+            )
+          end
+
+          # PATCH .../returns/:id/approve
+          def approve
+            run_workflow(Spree.return_approve_workflow, approver: current_actor)
+          end
+
+          # PATCH .../returns/:id/receive — what the warehouse actually counted.
+          def receive
+            run_workflow(Spree.return_receive_workflow,
+                         items: items_for_receive,
+                         received_by: current_actor)
+          end
+
+          # PATCH .../returns/:id/refund
+          def refund
+            run_workflow(Spree.return_refund_workflow,
+                         amount: params[:amount],
+                         refund_method: params[:refund_method] || 'original_payment',
+                         refunder: current_actor)
+          end
+
+          # PATCH .../returns/:id/cancel
+          def cancel
+            run_workflow(Spree.return_cancel_workflow, reason: params[:reason])
+          end
+
+          protected
+
+          def model_class
+            Spree::Return
+          end
+
+          def parent_association
+            :returns
+          end
+
+          def workflow_record_key
+            :return_record
+          end
+
+          private
+
+          def create_params
+            @create_params ||= params.permit(
+              :memo, :reason_id, :stock_location_id,
+              items: [:fulfillment_item_id, :quantity]
+            )
+          end
+
+          # The units coming back, resolved through the order itself, so a
+          # fulfillment item from another order cannot be returned against
+          # this one.
+          def items_for_create
+            Array(create_params[:items]).map do |item|
+              {
+                fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+                quantity: item[:quantity].to_i
+              }
+            end
+          end
+
+          # What the warehouse counted, resolved through the return itself.
+          def items_for_receive
+            sent = received_items([:return_line_item_id, :quantity, :resellable])
+            return nil if sent.nil?
+
+            sent.map do |item|
+              {
+                return_line_item: @resource.return_line_items.find_by_prefix_id!(item[:return_line_item_id]),
+                quantity: item[:quantity].to_i,
+                resellable: item.key?(:resellable) ? item[:resellable].to_b : true
+              }
+            end
+          end
+
+          # The merchant's own vocabulary either way: a seller picks a reason,
+          # the operator decides what the reasons are.
+          def reason_for_create
+            return nil if create_params[:reason_id].blank?
+
+            current_store.return_reasons.find_by_prefix_id!(create_params[:reason_id])
+          end
+
+          # The shelf the goods go back to — the store's warehouses for an
+          # operator, only their own for a seller. Left to the including
+          # controller because it decides whose stock this restocks.
+          #
+          # @return [Spree::StockLocation, nil]
+          def stock_location_for_create
+            raise NotImplementedError, "#{self.class} must implement #stock_location_for_create"
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb

@@ -0,0 +1,128 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # The postage on a parcel: recording a label, printing it back, and
+        # removing one that was uploaded by mistake.
+        #
+        # Shared by the operator's branch and the seller's. Buying a label is
+        # NOT here: it needs a carrier account, which is the operator's, so
+        # that action lives on the admin controller alone.
+        #
+        # `@parent` (the label's owner) and `@resource` arrive already fetched
+        # and authorized, so including this concern cannot widen what a caller
+        # reaches.
+        module ShippingLabelActions
+          extend ActiveSupport::Concern
+
+          included do
+            include ActiveStorage::SetCurrent
+            include Spree::Api::V3::StreamsShippingLabel
+
+            rescue_from ActiveSupport::MessageVerifier::InvalidSignature,
+                        with: :render_invalid_signature
+          end
+
+          # GET .../labels/:id/download
+          #
+          # Streamed rather than redirected to storage, so the credentials
+          # that reached the action are what protects the file.
+          def download
+            stream_shipping_label(@resource) do
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: Spree.t('shipping_labels.errors.no_file_url'),
+                status: :unprocessable_content
+              )
+            end
+          end
+
+          # DELETE .../labels/:id
+          #
+          # Only an uploaded label: a purchased one has postage to refund, so
+          # it goes through the refund action instead.
+          def destroy
+            unless @resource.uploaded?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: Spree.t('shipping_labels.errors.purchased_not_deletable'),
+                status: :unprocessable_content
+              )
+            end
+
+            with_order_lock do
+              # The consignment goes with the label only while the parcel
+              # never moved — a journey that happened is a fact. Once it has,
+              # the delivery stays and is simply unlinked, so a wrong PDF can
+              # still be removed and replaced.
+              @resource.release_unmoved_delivery
+              @resource.destroy!
+              head :no_content
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::ShippingLabel
+          end
+
+          def parent_association
+            :shipping_labels
+          end
+
+          def collection_includes
+            [{ file_attachment: :blob }]
+          end
+
+          # Downloading is reading, so it must not demand write access to the
+          # parcel the label belongs to.
+          def read_actions
+            %w[index show download]
+          end
+
+          private
+
+          def label_permitted_keys
+            [:file, :tracking_number, :carrier, :service,
+             :cost, :currency, :file_format, :tracking_url]
+          end
+
+          def label_params
+            @label_params ||= params.permit(*label_permitted_keys)
+          end
+
+          # Records a label bought outside Spree.
+          #
+          # Every key is passed whether or not the request carried it, so the
+          # workflow sees a missing tracking number as a blank one to reject
+          # rather than a keyword it was never given.
+          def record_uploaded_label
+            with_order_lock do
+              result = Spree.shipping_label_record_workflow.call(
+                owner: @parent,
+                **label_permitted_keys.index_with { |key| label_params[key] }
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value), status: :created
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # A tampered or expired direct-upload signature is a bad parameter,
+          # not a server fault.
+          def render_invalid_signature
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:parameter_invalid],
+              message: Spree.t('shipping_labels.errors.file_required'),
+              status: :unprocessable_content
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,12 +6,15 @@ module Spree
       # 1. **Prefixed ID resolution** — decodes Stripe-style prefixed IDs (e.g. "prod_86Rf07xd4z")
       #    to integer primary keys for any param ending in `_id` or `_ids`.
       #
-      # 2. **Nested attributes normalization** — converts flat arrays (e.g. `taxon_rules: [...]`)
-      #    to Rails `_attributes` format (e.g. `taxon_rules_attributes: [...]`) based on
+      # 2. **Nested attributes normalization** — converts flat arrays (e.g. `variants: [...]`)
+      #    to Rails `_attributes` format (e.g. `variants_attributes: [...]`) based on
       #    the model's `accepts_nested_attributes_for` declarations.
       #
-      # Uses `prepend` so it always wraps `permitted_params` regardless of which
-      # controller in the hierarchy defines it — no manual calls needed.
+      # `normalize_params` is called explicitly by a controller's
+      # `permitted_params`. It is deliberately NOT applied to every write: it
+      # recurses into nested hashes decoding anything shaped like a prefixed ID,
+      # which would corrupt opaque provider values (see
+      # Admin::PaymentMethodsController).
       module ParamsNormalizer
         extend ActiveSupport::Concern
 

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      # Turns a CanCanCan ability into the flat, JSON-safe shape the panels'
+      # `<Can>` reads. Shared by every `/me` endpoint — the admin and seller
+      # branches answer different audiences, but the frontend permission model
+      # is one implementation, so its input has to be too.
+      #
+      # - Rule order is preserved so the frontend matcher can apply
+      #   CanCanCan's "last matching rule wins" semantics.
+      # - Per-record conditions are NOT serialized (they often reference
+      #   scopes or blocks that don't translate to JSON). The frontend
+      #   receives `has_conditions: true` as a hint that the action might be
+      #   denied at the per-record level — in practice the SPA shows the
+      #   action optimistically and handles 403 from the API.
+      module PermissionSerialization
+        extend ActiveSupport::Concern
+
+        private
+
+        def serialize_permissions(ability)
+          ability.send(:rules).map do |rule|
+            {
+              allow: rule.base_behavior,
+              actions: Array(rule.actions).map(&:to_s),
+              subjects: Array(rule.subjects).map { |subject| subject.is_a?(Class) ? subject.name : subject.to_s },
+              has_conditions: rule_has_conditions?(rule)
+            }
+          end
+        end
+
+        def serialize_permission_keys(ability)
+          ability.respond_to?(:permission_keys) ? ability.permission_keys : []
+        end
+
+        def rule_has_conditions?(rule)
+          rule.block.present? || rule.conditions.present?
+        end
+      end
+    end
+  end
+end

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

@@ -1,22 +1,56 @@
 module Spree
   module Api
     module V3
-      # Sets X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers
-      # on every Store API response by reading the same cache counter that
-      # Rails' built-in `rate_limit` writes to.
+      # Owns the request-throttling identity shared by the `rate_limit`
+      # declarations in BaseController and the X-RateLimit-Limit /
+      # X-RateLimit-Remaining / Retry-After headers set on every v3 response:
+      # which bucket a request counts against and which ceiling applies.
+      #
+      # Secret keys (sk_*) are single server-to-server callers, so each key
+      # gets one bucket across the whole API. Publishable keys (pk_*) are
+      # shared by every storefront visitor, so their bucket includes the
+      # client IP — the limit is per visitor, never per storefront. Requests
+      # without an API key (admin JWT traffic) fall back to the client IP.
       module RateLimitHeaders
         extend ActiveSupport::Concern
 
+        # Shared `scope:` for the API-wide throttle — one bucket per caller
+        # across all v3 controllers, instead of Rails' default of one bucket
+        # per controller.
+        RATE_LIMIT_SCOPE = 'api_v3'.freeze
+
         included do
           after_action :set_rate_limit_headers
         end
 
         private
 
+        def rate_limit_ceiling
+          if secret_key_request?
+            Spree::Api::Config[:rate_limit_per_secret_key]
+          else
+            Spree::Api::Config[:rate_limit_per_key]
+          end
+        end
+
+        # Secret tokens are digested first — plaintext secrets must never
+        # become cache keys (Solid Cache persists them to the database, while
+        # the model itself stores only +token_digest+).
+        def rate_limit_bucket
+          api_key = extract_api_key
+
+          if secret_key_request?
+            Spree::ApiKey.compute_token_digest(api_key)
+          elsif api_key
+            "#{api_key}:#{request.remote_ip}"
+          else
+            request.remote_ip
+          end
+        end
+
         def set_rate_limit_headers
-          limit = Spree::Api::Config[:rate_limit_per_key]
-          by = request.headers['X-Spree-Api-Key'] || request.remote_ip
-          cache_key = ['rate-limit', controller_path, by].compact.join(':')
+          limit = rate_limit_ceiling
+          cache_key = ['rate-limit', RATE_LIMIT_SCOPE, rate_limit_bucket].join(':')
           count = Rails.cache.read(cache_key)
 
           return if count.nil?