spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,54 @@
+module Spree
+  module Api
+    module V3
+      # The `items` list a request names, for the endpoints that take one:
+      # receiving a return, an exchange, a claim, a stock transfer or a
+      # purchase order, and opening any of them.
+      #
+      # The distinction all of them need is between *omitted* and *empty*. An
+      # omitted `items` means "all of it, as recorded" — receive the whole
+      # return, the whole delivery. An empty list, or an explicit `null`, means
+      # the caller named nothing, and must not fall through to that default.
+      module ItemsPayload
+        extend ActiveSupport::Concern
+
+        # A payload whose `items` is not a list. Raised out of the params
+        # helper so it cannot be mistaken for a workflow rejection, and
+        # answered as the client mistake it is rather than a 500.
+        class InvalidItems < StandardError; end
+
+        included do
+          rescue_from InvalidItems, with: :render_invalid_items
+        end
+
+        protected
+
+        # @param keys [Array<Symbol>] the per-item keys to permit
+        # @return [Array<ActionController::Parameters>, nil] nil when the
+        #   payload said nothing about items
+        def items_payload(keys)
+          return nil unless params.key?(:items)
+
+          raw = params[:items]
+          return [] if raw.nil?
+          # Checked before `permit`, which silently drops a scalar `items` —
+          # leaving a client typo indistinguishable from "named nothing".
+          raise InvalidItems unless raw.is_a?(Array)
+
+          params.permit(items: keys)[:items] || []
+        end
+
+        # Reported against `:base`, not `:items`. The payload is malformed
+        # rather than a field being wrong, and ActiveModel reads the named
+        # attribute off the record to interpolate a message — which raises for
+        # every record whose lines are not called `items` (a return's are
+        # `return_line_items`).
+        def render_invalid_items
+          errors = ActiveModel::Errors.new(@resource || model_class.new)
+          errors.add(:base, :invalid_items, message: Spree.t('errors.messages.items_not_a_list'))
+          render_validation_error(errors)
+        end
+      end
+    end
+  end
+end

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

@@ -11,6 +11,11 @@ module Spree
 
         JWT_AUDIENCE_STORE = 'store_api'.freeze
         JWT_AUDIENCE_ADMIN = 'admin_api'.freeze
+        # Marketplace sellers share the admin user class, so the audience — not
+        # the principal — is what keeps a seller's token off the admin API and
+        # an admin's off the seller panel. Enforced at decode, before any store
+        # or seller is resolved.
+        JWT_AUDIENCE_SELLER = 'seller_api'.freeze
         JWT_ISSUER = 'spree'.freeze
 
         included do
@@ -67,8 +72,12 @@ module Spree
           header = request.headers['Authorization']
           return header.split(' ').last if header.present? && header.start_with?('Bearer ')
 
-          # Restricted fallback: only for digital download endpoints
-          params[:token] if controller_name == 'digitals'
+          # Restricted fallback: only the storefront tokenized download
+          # endpoint, which carries its link token in the query string. The
+          # customer library and admin grant endpoints share the controller
+          # name but authenticate by header, so matching on the name alone
+          # would let their bearer JWTs travel in the URL (logs, history).
+          params[:token] if controller_path == 'spree/api/v3/store/digital_links'
         end
 
         def decode_jwt(token)
@@ -104,10 +113,21 @@ module Spree
           when USER_TYPE_ADMIN
             Spree.admin_user_class.find(user_id)
           else
-            Spree.user_class.find(user_id)
+            customer_from(user_id)
           end
         end
 
+        # An erased account stops answering to its old tokens. Clearing the
+        # password blocks a fresh sign-in, but a JWT issued before the erasure
+        # would otherwise keep working until it expired — long enough to write
+        # a name and phone back onto the record, after which a second erasure
+        # is refused as already done.
+        def customer_from(user_id)
+          customer = Spree.customer_class.find(user_id)
+
+          customer.respond_to?(:anonymized?) && customer.anonymized? ? nil : customer
+        end
+
         def determine_user_type(user)
           if user.is_a?(Spree.admin_user_class)
             USER_TYPE_ADMIN

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      # Store API store context: the publishable key selects the store (the
+      # key belongs to exactly one store) — the request host is never
+      # consulted. See docs/plans/6.0-store-context-and-first-run-setup.md.
+      #
+      # Included in both Store API branch anchors (Store::BaseController and
+      # Store::ResourceController) alongside ApiKeyAuthentication, whose
+      # memoized +publishable_api_key+ lookup this reads — pre-authentication
+      # callbacks (channel resolution, locale fallbacks) resolve the same key
+      # row authentication later verifies.
+      module KeyStoreContext
+        extend ActiveSupport::Concern
+
+        included do
+          # An invalid or missing key must render 401 from
+          # +authenticate_api_key!+ — without this skip the store-presence
+          # guard would 404 first on the ResourceController branch, where it
+          # runs ahead of authentication.
+          skip_before_action :raise_record_not_found_if_store_is_not_found
+        end
+
+        # @return [Spree::Store, nil]
+        def current_store
+          @current_store ||= publishable_api_key&.store
+        end
+      end
+    end
+  end
+end

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

@@ -171,10 +171,10 @@ module Spree
         # When a matching market is found, it is set on +Spree::Current.market+,
         # which influences the default locale and currency fallbacks.
         def set_market_from_country
-          country_iso = request.headers['x-spree-country'].presence || params[:country].presence
-          return unless country_iso
+          country_code = request.headers['x-spree-country'].presence || params[:country].presence
+          return unless country_code
 
-          country = Spree::Country.find_by(iso: country_iso.upcase)
+          country = Spree::Country.by_iso(country_code)
           return unless country
 
           market = current_store&.market_for_country(country)

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

@@ -15,15 +15,34 @@ module Spree
           order = @order || @parent || @cart
 
           order.with_lock do
+            # Completed carts are readonly — nothing left to version-bump;
+            # the row lock alone still serializes the idempotent paths.
+            next yield if order.readonly?
+
+            # A completion attempt fixed this cart's totals under the lock and
+            # is now off at the gateway — mutating the cart mid-window would
+            # complete it with different totals than the ones being charged.
+            # The completion claim excludes mutations for exactly that window;
+            # checked after acquiring the lock so it cannot race the claim
+            # being written. The TTL matches guard_concurrent_completion — a
+            # crashed completion must not brick its cart.
+            if order.is_a?(Spree::Cart) && order.completion_claimed?
+              next render_error(
+                code: 'completion_in_progress',
+                message: Spree.t(:cart_completion_in_progress),
+                status: :conflict
+              )
+            end
+
             # Persist increment within the transaction so reloads inside yield see the new version
-            new_version = order.state_lock_version + 1
-            order.update_column(:state_lock_version, new_version)
+            new_version = order.lock_version + 1
+            order.update_column(:lock_version, new_version)
 
             yield
 
             if performed? && response.status >= 400
               # Operation failed — revert the increment
-              order.update_column(:state_lock_version, new_version - 1)
+              order.update_column(:lock_version, new_version - 1)
             end
           end
         end

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

@@ -0,0 +1,112 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Something went wrong with a delivery, and the merchant makes it
+        # right — money back, a replacement, or both — without necessarily
+        # asking for the goods back.
+        #
+        # See {PostSaleActions} for why the lookups a payload's ids resolve
+        # through are deliberately left to the including controller.
+        module ClaimActions
+          extend ActiveSupport::Concern
+          include PostSaleActions
+
+          # POST .../claims
+          def create
+            create_post_sale_record(Spree.claim_create_workflow, Spree::Claim)
+          end
+
+          # PATCH .../claims/:id/approve
+          def approve
+            run_workflow(Spree.claim_approve_workflow, approver: try_spree_current_user)
+          end
+
+          # PATCH .../claims/:id/resolve — a refund, a replacement, or both.
+          def resolve
+            run_workflow(Spree.claim_resolve_workflow,
+                         resolution: params[:resolution],
+                         refund_method: params[:refund_method] || 'store_credit',
+                         amount: params[:amount],
+                         replacement_line_item_ids: replacement_line_item_ids,
+                         resolver: try_spree_current_user)
+          end
+
+          # PATCH .../claims/:id/deny
+          def deny
+            run_workflow(Spree.claim_deny_workflow, reason: params[:reason])
+          end
+
+          # PATCH .../claims/:id/cancel
+          def cancel
+            run_workflow(Spree.claim_cancel_workflow, reason: params[:reason])
+          end
+
+          protected
+
+          def model_class
+            Spree::Claim
+          end
+
+          def parent_association
+            :claims
+          end
+
+          def workflow_record_key
+            :claim
+          end
+
+          private
+
+          def create_params
+            @create_params ||= params.permit(
+              :memo, :reason_id,
+              items: [:line_item_id, :quantity, :description, :send_replacement,
+                      :replacement_variant_id, :refund_amount]
+            )
+          end
+
+          # Every claimed line is resolved through the order itself, so a line
+          # item from another order cannot be claimed against this one.
+          def items_for_create
+            Array(create_params[:items]).map do |item|
+              {
+                line_item: @order.line_items.find_by_prefix_id!(item[:line_item_id]),
+                quantity: item[:quantity].to_i,
+                description: item[:description],
+                send_replacement: item[:send_replacement].to_b,
+                replacement_variant: replacement_variant_for(item[:replacement_variant_id]),
+                refund_amount: item[:refund_amount]
+              }
+            end
+          end
+
+          # Which lines to replace, decided at resolution time. Absent means
+          # "leave whatever the claim was opened with".
+          def replacement_line_item_ids
+            return nil unless params.key?(:replacement_line_item_ids)
+
+            Array(params[:replacement_line_item_ids]).map do |id|
+              @resource.claim_line_items.find_by_prefix_id!(id).id
+            end
+          end
+
+          def reason_for_create
+            return nil if create_params[:reason_id].blank?
+
+            current_store.claim_reasons.find_by_prefix_id!(create_params[:reason_id])
+          end
+
+          # The catalogue a replacement may be promised from. Left to the
+          # including controller precisely because getting it wrong would let
+          # one seller ship another's stock.
+          #
+          # @return [Spree::Variant, nil]
+          def replacement_variant_for(_variant_id)
+            raise NotImplementedError, "#{self.class} must implement #replacement_variant_for"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # The consignments of one fulfillment — a parcel each, or a freight
+        # PRO number covering several pallets.
+        #
+        # A delivery is born when a tracking number is attached, days before
+        # anything arrives, so POST means "this went out as another
+        # consignment"; arrival is a transition on an existing row.
+        #
+        # Shared by the operator's branch and the seller's. `@parent` (the
+        # fulfillment) and `@resource` arrive already fetched and authorized,
+        # so including this concern cannot widen what a caller reaches.
+        module DeliveryActions
+          extend ActiveSupport::Concern
+
+          # POST .../deliveries
+          def create
+            authorize!(:create, Spree::Delivery)
+
+            with_order_lock do
+              # Every key is passed whether or not the request carried it, so
+              # the service sees a missing tracking number as a blank one to
+              # reject rather than a keyword it was never given.
+              result = Spree.delivery_create_service.call(
+                owner: @parent,
+                **resource_permitted_attributes.index_with { |key| delivery_params[key] }
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value), status: :created
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # PATCH .../deliveries/:id — correcting the number, carrier or link.
+          #
+          # A corrected number is a different parcel as far as the carrier is
+          # concerned: its journey starts over, and the carrier and link that
+          # belonged to the old number go with it unless this request supplies
+          # new ones. A consignment that started over may also have been the
+          # one holding the fulfillment at delivered.
+          def update
+            with_order_lock do
+              if @resource.update(@resource.correction_attributes(delivery_params.to_h))
+                recalculate_fulfillment_delivery
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+          end
+
+          # DELETE .../deliveries/:id — 422 when a label minted it.
+          def destroy
+            with_order_lock do
+              result = Spree.delivery_destroy_service.call(delivery: @resource)
+
+              if result.success?
+                head :no_content
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::Delivery
+          end
+
+          def parent_association
+            :deliveries
+          end
+
+          def collection_includes
+            [:shipping_label]
+          end
+
+          def resource_permitted_attributes
+            [:tracking_number, :carrier, :service, :tracking_url]
+          end
+
+          private
+
+          def delivery_params
+            @delivery_params ||= params.permit(*resource_permitted_attributes)
+          end
+
+          # Deliveries can hang off something other than a fulfillment, which
+          # has no delivered state to roll up.
+          def recalculate_fulfillment_delivery
+            return unless @parent.is_a?(Spree::Fulfillment)
+
+            Spree.fulfillment_recalculate_delivery_service.call(fulfillment: @parent)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Swapping goods on an order — a different size, colour or product —
+        # 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 ExchangeActions
+          extend ActiveSupport::Concern
+          include PostSaleActions
+
+          # POST .../exchanges
+          def create
+            create_post_sale_record(
+              Spree.exchange_create_workflow, Spree::Exchange,
+              stock_location: stock_location_for_create
+            )
+          end
+
+          # PATCH .../exchanges/:id/approve
+          def approve
+            run_workflow(Spree.exchange_approve_workflow, approver: try_spree_current_user)
+          end
+
+          # PATCH .../exchanges/:id/receive
+          def receive
+            run_workflow(Spree.exchange_receive_workflow,
+                         items: items_for_receive,
+                         received_by: try_spree_current_user)
+          end
+
+          # PATCH .../exchanges/:id/fulfill — sends the replacement, settling
+          # any price difference, which is why it takes a refund method.
+          def fulfill
+            run_workflow(Spree.exchange_fulfill_workflow,
+                         refund_method: params[:refund_method] || 'store_credit',
+                         refunder: try_spree_current_user)
+          end
+
+          # PATCH .../exchanges/:id/cancel
+          def cancel
+            run_workflow(Spree.exchange_cancel_workflow, reason: params[:reason])
+          end
+
+          protected
+
+          def model_class
+            Spree::Exchange
+          end
+
+          def parent_association
+            :exchanges
+          end
+
+          def workflow_record_key
+            :exchange
+          end
+
+          private
+
+          def create_params
+            @create_params ||= params.permit(
+              :memo, :reason_id, :stock_location_id,
+              items: [:fulfillment_item_id, :new_variant_id, :quantity]
+            )
+          end
+
+          # The units going back are resolved through the order; what comes
+          # out instead is resolved through {#replacement_variant_for}.
+          def items_for_create
+            Array(create_params[:items]).map do |item|
+              {
+                fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+                new_variant: replacement_variant_for(item[:new_variant_id]),
+                quantity: item[:quantity].to_i
+              }
+            end
+          end
+
+          def items_for_receive
+            sent = received_items([:exchange_line_item_id, :quantity, :resellable])
+            return nil if sent.nil?
+
+            sent.map do |item|
+              {
+                exchange_line_item: @resource.exchange_line_items.find_by_prefix_id!(item[:exchange_line_item_id]),
+                quantity: item[:quantity].to_i,
+                resellable: item.key?(:resellable) ? item[:resellable].to_b : true
+              }
+            end
+          end
+
+          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 catalogue the replacement comes out of, and the shelf the
+          # returned goods go back to. Both are left to the including
+          # controller: an operator exchanges into the whole store, a seller
+          # only into their own goods, and getting this wrong would put one
+          # seller's stock on another's order.
+          def replacement_variant_for(_variant_id)
+            raise NotImplementedError, "#{self.class} must implement #replacement_variant_for"
+          end
+
+          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/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