spree_api 5.5.3 → 5.6.0.rc1

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

@@ -0,0 +1,274 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # See `docs/plans/5.6-admin-spa-csv-import.md`.
+        #
+        # There is no standalone imports scope: an import is a bulk write of
+        # the records it creates, so every action — including reads, which
+        # expose the uploaded data — maps to the write scope of the imported
+        # resource (Spree::Imports::Customers => `write_customers`; see
+        # Spree::Import.required_scope). The index is filtered to the types
+        # the key can write.
+        class ImportsController < ResourceController
+          include ActiveStorage::SetCurrent
+
+          # The index spans many import types — `scope` filters it to the
+          # writable ones instead of gating on a single scope.
+          skip_scope_check! only: :index
+
+          # POST /api/v3/admin/imports
+          #
+          # `attachment` is an ActiveStorage signed blob id obtained from
+          # POST /api/v3/admin/direct_uploads. On success the import advances
+          # straight into `mapping` (auto-assigning file columns from the CSV
+          # headers), so the response already carries the mapping payload.
+          def create
+            @resource = build_resource
+            authorize_resource!(@resource, :create)
+
+            if @resource.save
+              begin
+                @resource.start_mapping!
+              rescue ::CSV::MalformedCSVError, EncodingError => e
+                @resource.update_columns(status: 'failed', processing_errors: e.message, updated_at: Time.current)
+                return render_error(
+                  code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                  message: "Could not parse CSV: #{e.message}",
+                  status: :unprocessable_content
+                )
+              end
+
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_errors(@resource.errors)
+            end
+          rescue ActiveSupport::MessageVerifier::InvalidSignature
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+              message: 'Invalid attachment signed id',
+              status: :unprocessable_content
+            )
+          end
+
+          # PATCH /api/v3/admin/imports/:id/complete_mapping
+          #
+          # Applies the submitted mappings atomically, then transitions out of
+          # mapping (which enqueues row creation + processing). 422 when
+          # required schema fields remain unmapped or a file column is
+          # assigned twice.
+          def complete_mapping
+            @resource = find_resource
+            authorize_resource!(@resource, :update)
+
+            unless @resource.mapping?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Import is not in the mapping state',
+                status: :unprocessable_content
+              )
+            end
+
+            apply_mappings!(@resource)
+
+            if @resource.mapping_done?
+              @resource.complete_mapping!
+              render json: serialize_resource(@resource)
+            else
+              missing = @resource.required_fields - @resource.mappings.mapped.pluck(:schema_field)
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: "Required fields are not mapped: #{missing.join(', ')}",
+                status: :unprocessable_content,
+                details: { missing_required_fields: missing }
+              )
+            end
+          rescue ActiveRecord::RecordInvalid => e
+            render_validation_error(e.record.errors)
+          end
+
+          # PATCH /api/v3/admin/imports/:id/retry_failed_rows
+          #
+          # Re-dispatches processing over the rows still `failed` (the
+          # dispatcher's pending_and_failed scope picks them up). 422 unless
+          # the import is `completed` with failures.
+          def retry_failed_rows
+            @resource = find_resource
+            authorize_resource!(@resource, :update)
+
+            if @resource.retry_failed_rows
+              render json: serialize_resource(@resource)
+            else
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Import has no failed rows to retry',
+                status: :unprocessable_content
+              )
+            end
+          end
+
+          # GET /api/v3/admin/imports/:id/download
+          #
+          # Streams the originally uploaded CSV — the audit trail for what
+          # was actually imported. Same inline-streaming rationale as
+          # ExportsController#download: a signed ActiveStorage URL neither
+          # survives the SPA's `/api/*`-only dev proxy nor carries the JWT.
+          def download
+            @resource = find_resource
+            authorize_resource!(@resource, :show)
+
+            attachment = @resource.attachment
+            unless attachment.attached?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Import has no attached file',
+                status: :unprocessable_content
+              )
+            end
+
+            send_data(
+              attachment.download,
+              filename: attachment.filename.to_s,
+              type: attachment.content_type || 'text/csv',
+              disposition: 'attachment'
+            )
+          end
+
+          # GET /api/v3/admin/imports/template?type=Spree::Imports::Products
+          #
+          # CSV header row for the type's schema (including the metafield
+          # columns available for the model) — the "Download template" link
+          # in the admin dashboard.
+          def template
+            klass = resolve_import_type(params[:type])
+
+            unless klass
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Unknown import type',
+                status: :unprocessable_content
+              )
+            end
+
+            headers = klass.new.schema_fields.map { |field| field[:name] }
+            send_data ::CSV.generate_line(headers),
+                      filename: "#{klass.name.demodulize.underscore}_import_template.csv",
+                      type: 'text/csv',
+                      disposition: 'attachment'
+          end
+
+          protected
+
+          def model_class
+            Spree::Import
+          end
+
+          def serializer_class
+            Spree.api.admin_import_serializer
+          end
+
+          def scope_includes
+            [:user, :mappings, { attachment_attachment: :blob }]
+          end
+
+          def scope
+            collection = super
+            return collection unless scope_limited_principal?
+
+            collection.where(type: writable_import_types)
+          end
+
+          # Loaded by both the scope gate (before_action) and the member
+          # actions — memoize so the record is fetched once.
+          def find_resource
+            @find_resource ||= super
+          end
+
+          # Every action on an import maps to the write scope of the imported
+          # resource: creating is a bulk write, and status/rows expose the
+          # uploaded data, so read-only keys get nothing.
+          def action_kind
+            'write'
+          end
+
+          # Unresolvable types (blank/unknown `type` on create/template) fall
+          # back to `:all`, so only `write_all` keys reach the model's own
+          # validation.
+          def scoped_resource_name
+            import_class&.required_scope || :all
+          end
+
+          def build_resource
+            klass = resolve_import_type(permitted_params[:type]) || Spree::Import
+            attrs = permitted_params.except(:type).merge(
+              owner: current_store,
+              user: acting_admin_user
+            )
+            # The done email links back to results_url — allowed origins only.
+            attrs[:results_url] = validated_allowed_origin_url(attrs[:results_url])
+            klass.new(attrs)
+          end
+
+          def permitted_params
+            params.permit(:type, :attachment, :preferred_delimiter, :results_url)
+          end
+
+          # Returns the registered Import subclass matching `name`, or nil.
+          #
+          # The constantize target comes from `available_types` (a trusted
+          # in-process registry), not from the request — `name` is only used
+          # to *select* an entry in the allowlist (same pattern as
+          # ExportsController#resolve_export_type).
+          def resolve_import_type(name)
+            return nil if name.blank?
+
+            target = Spree::Import.available_types.map(&:to_s).find { |t| t == name.to_s }
+            target&.constantize
+          end
+
+          private
+
+          # Imports require a user: row processors resolve records through
+          # `import.current_ability`. JWT requests use the signed-in admin;
+          # API-key requests attribute to the key's creator when that is an
+          # admin user, otherwise the model's presence validation renders 422.
+          def acting_admin_user
+            return try_spree_current_user if try_spree_current_user
+
+            created_by = current_api_key&.created_by
+            created_by if created_by.is_a?(Spree.admin_user_class)
+          end
+
+          def import_class
+            case action_name
+            when 'create', 'template' then resolve_import_type(params[:type])
+            else find_resource.class
+            end
+          end
+
+          def writable_import_types
+            Spree::Import.available_types.select do |type|
+              required = type.required_scope
+              required ? current_api_key.has_scope?("write_#{required}") : current_api_key.has_scope?('write_all')
+            end.map(&:to_s)
+          end
+
+          def apply_mappings!(import)
+            submitted = params[:mappings]
+            return if submitted.blank?
+
+            ApplicationRecord.transaction do
+              submitted.each do |entry|
+                mapping = import.mappings.find_by(schema_field: entry[:schema_field])
+                next unless mapping
+
+                mapping.update!(file_column: entry[:file_column].presence)
+              end
+            end
+            import.mappings.reload
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Lists the locales a merchant can translate content into for the
+        # current store (its supported_locales_list), so the dashboard's locale
+        # switcher enumerates locales instead of hardcoding them.
+        class LocalesController < Admin::BaseController
+          scoped_resource :settings
+
+          # GET /api/v3/admin/locales
+          def index
+            render json: {
+              data: current_store.supported_locales.map do |locale|
+                Spree.api.locale_serializer.new(locale).to_h
+              end
+            }
+          end
+
+          private
+
+          def action_kind
+            'read'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,8 @@ module Spree
         class MeController < Admin::BaseController
           skip_scope_check!
 
+          before_action :require_current_user!
+
           # GET /api/v3/admin/me
           # Returns the current admin user along with a serialized representation
           # of their permissions (derived from CanCanCan rules). The SPA uses
@@ -21,22 +23,50 @@ module Spree
           # a 500 from serializing a nil user — mirroring how #current 404s for
           # a JWT principal that has no single key.
           def show
-            unless current_user
-              return render_error(
-                code: ERROR_CODES[:record_not_found],
-                message: Spree.t(:me_no_current_user),
-                status: :not_found
-              )
+            render json: me_response
+          end
+
+          # PATCH /api/v3/admin/me
+          # Self-service update of the signed-in admin's own profile (display
+          # name, admin UI language, and avatar) — it operates on `current_user`
+          # directly, so it needs no per-record authorization. Distinct from
+          # PATCH /admin_users/:id, which is store-scoped staff management of
+          # *other* users. `avatar` accepts an ActiveStorage direct-upload
+          # signed id to set the photo, or `null` to remove it.
+          def update
+            if current_user.update(permitted_params)
+              render json: me_response
+            else
+              render_validation_error(current_user.errors)
             end
+          end
+
+          private
+
+          # A request authenticated by a secret API key has no Spree user to
+          # describe/update, so it gets a 404 pointing at the key endpoint
+          # rather than a 500 from a nil user — mirroring ApiKeysController#current.
+          def require_current_user!
+            return if current_user
 
-            render json: {
+            render_error(
+              code: ERROR_CODES[:record_not_found],
+              message: Spree.t(:me_no_current_user),
+              status: :not_found
+            )
+          end
+
+          def permitted_params
+            params.permit(:selected_locale, :first_name, :last_name, :avatar)
+          end
+
+          def me_response
+            {
               user: admin_user_serializer.new(current_user, params: serializer_params).to_h,
               permissions: serialize_permissions(current_ability)
             }
           end
 
-          private
-
           # Serializes CanCanCan's rules into a flat, JSON-safe list of permission rules.
           #
           # - Rule order is preserved so the frontend matcher can apply

data/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb

@@ -8,6 +8,37 @@ module Spree
 
             before_action :set_resource, only: [:show, :update, :fulfill, :cancel, :resume, :split]
 
+            # POST /api/v3/admin/orders/:order_id/fulfillments
+            #
+            # Manually registers a fulfillment on a completed order (external
+            # carrier / 3PL sync), bypassing order routing. Moves the requested
+            # line item quantities out of their routed fulfillments; when
+            # `items` is omitted, everything not yet shipped is moved. An
+            # explicit `cost` persists only with `status: 'shipped'` — pending
+            # fulfillments are re-priced by the rate engine.
+            def create
+              authorize!(:create, Spree::Shipment)
+
+              with_order_lock do
+                result = Spree.fulfillment_create_service.call(
+                  order: @order,
+                  stock_location: stock_location_for_create,
+                  items: items_for_create,
+                  tracking: create_params[:tracking],
+                  delivery_method: delivery_method_for_create,
+                  cost: create_params[:cost],
+                  status: create_params[:status],
+                  metadata: create_params[:metadata]&.to_h
+                )
+
+                if result.success?
+                  render json: serialize_resource(result.value), status: :created
+                else
+                  render_result_error(result)
+                end
+              end
+            end
+
             # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id
             def update
               with_order_lock do
@@ -61,7 +92,7 @@ module Spree
                 quantity = params[:quantity].to_i
 
                 stock_location = if params[:stock_location_id].present?
-                                   Spree::StockLocation.accessible_by(current_ability, :show).find_by_prefix_id!(params[:stock_location_id])
+                                   find_stock_location!(params[:stock_location_id])
                                  else
                                    @resource.stock_location
                                  end
@@ -96,7 +127,36 @@ module Spree
             # State changes go through the dedicated `fulfill`/`cancel`/`resume`
             # member actions, not mass assignment.
             def permitted_params
-              params.permit(:tracking, :selected_shipping_rate_id, :stock_location_id)
+              params.permit(:tracking, :selected_delivery_rate_id, :stock_location_id)
+            end
+
+            def create_params
+              @create_params ||= params.permit(:stock_location_id, :tracking, :delivery_method_id, :cost, :status, metadata: {}, items: [:item_id, :quantity])
+            end
+
+            def find_stock_location!(id)
+              Spree::StockLocation.accessible_by(current_ability, :show).find_by_prefix_id!(id)
+            end
+
+            def stock_location_for_create
+              find_stock_location!(create_params.require(:stock_location_id))
+            end
+
+            def delivery_method_for_create
+              return if create_params[:delivery_method_id].blank?
+
+              Spree::ShippingMethod.accessible_by(current_ability, :show).find_by_prefix_id!(create_params[:delivery_method_id])
+            end
+
+            def items_for_create
+              return if create_params[:items].nil?
+
+              create_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
           end
         end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        class PasswordResetsController < Admin::BaseController
+          include Spree::Api::V3::Admin::AuthCookies
+
+          skip_scope_check!
+          rate_limit to: Spree::Api::Config[:rate_limit_password_reset],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     with: RATE_LIMIT_RESPONSE
+
+          skip_before_action :authenticate_admin!
+
+          # POST /api/v3/admin/password_resets
+          def create
+            redirect_url = params[:redirect_url]
+
+            # Validate redirect_url against allowed origins (secure by default).
+            # If no allowed origins are configured, redirect_url is silently ignored
+            # to prevent open redirect / token exfiltration attacks.
+            if redirect_url.present?
+              unless current_store.allowed_origins.exists? && current_store.allowed_origin?(redirect_url)
+                redirect_url = nil
+              end
+            end
+
+            user = Spree.admin_user_class.find_by(email: params[:email])
+
+            if user
+              token = user.generate_token_for(:password_reset)
+              event_payload = { reset_token: token, email: user.email, store_id: current_store.prefixed_id }
+              event_payload[:redirect_url] = redirect_url if redirect_url.present?
+              user.publish_event('admin_user.password_reset_requested', event_payload)
+            end
+
+            # Always return 202 to prevent email enumeration
+            render json: { message: Spree.t(:password_reset_requested, scope: :api) }, status: :accepted
+          end
+
+          # PATCH /api/v3/admin/password_resets/:id
+          def update
+            user = Spree.admin_user_class.find_by_password_reset_token(params[:id])
+
+            unless user
+              return render_error(
+                code: ERROR_CODES[:password_reset_token_invalid],
+                message: Spree.t(:password_reset_token_invalid, scope: :api),
+                status: :unprocessable_content
+              )
+            end
+
+            if user.update(password: params[:password], password_confirmation: params[:password_confirmation])
+              user.publish_event('admin_user.password_reset')
+              # A password reset must kill every existing session — a stolen
+              # refresh token must not survive the victim resetting their
+              # password. Revoke first, then mint the fresh token for this
+              # browser (the auto-sign-in below).
+              Spree::RefreshToken.revoke_all_for(user)
+              refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+              set_refresh_cookie(refresh_token)
+
+              render json: auth_response(user)
+            else
+              render_errors(user.errors)
+            end
+          end
+
+          private
+
+          def auth_response(user)
+            {
+              token: generate_jwt(user, audience: JWT_AUDIENCE_ADMIN),
+              user: admin_user_serializer.new(user, params: serializer_params).to_h
+            }
+          end
+
+          def serializer_params
+            {
+              store: current_store,
+              locale: current_locale,
+              currency: current_currency,
+              user: nil,
+              includes: []
+            }
+          end
+
+          def admin_user_serializer
+            Spree.api.admin_admin_user_serializer
+          end
+
+          def request_env_for_token
+            {
+              ip_address: request.remote_ip,
+              user_agent: request.user_agent&.truncate(255)
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -22,14 +22,7 @@ module Spree
           def types
             authorize! :create, model_class
 
-            # Query via direct join rather than `current_store.payment_methods`
-            # — the has_many-through association can cache stale results when
-            # `current_store` was loaded earlier in the request (e.g. by the
-            # auth layer).
-            installed_class_names = Spree::PaymentMethod
-                                      .joins(:store_payment_methods)
-                                      .where(spree_payment_methods_stores: { store_id: current_store.id })
-                                      .pluck(:type)
+            installed_class_names = current_store.payment_methods.pluck(:type)
             installed_shorthands = installed_class_names.filter_map do |name|
               name.safe_constantize&.api_type
             end

data/app/controllers/spree/api/v3/admin/products/variants_controller.rb

@@ -34,7 +34,7 @@ module Spree
                 :sku, :barcode,
                 :cost_price, :cost_currency,
                 :weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
-                :track_inventory, :tax_category_id, :position,
+                :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
                 options: [:name, :value],
                 prices: [:amount, :compare_at_amount, :currency],
                 stock_items: [:stock_location_id, :count_on_hand, :backorderable]

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

@@ -171,11 +171,11 @@ module Spree
               prices: [:amount, :compare_at_amount, :currency],
               # Inline custom field values keyed by definition id. The model
               # setter (`Spree::Metafields#custom_fields=`) validates each
-              # entry against its definition. We permit `value` as both a
-              # scalar AND `value: {}` (any-shape Hash/Array) — Strong
-              # Parameters merges them so JSON metafields can ship parsed
-              # objects while text/number/boolean ship scalars.
-              custom_fields: [:id, :custom_field_definition_id, :value, value: {}],
+              # entry against its definition. We permit `value` as a scalar AND
+              # as `value: []` / `value: {}` so JSON metafields round-trip
+              # whether the parsed payload is an array or an object, while
+              # text/number/boolean ship scalars.
+              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }],
               # Inline media. Entries with `id` patch an existing asset
               # (alt, position, variant_ids). Entries with `signed_id` create
               # + attach a fresh upload. Lets the dashboard ship media changes
@@ -187,7 +187,7 @@ module Spree
                 :id, :sku, :barcode,
                 :cost_price, :cost_currency,
                 :weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
-                :track_inventory, :tax_category_id, :position,
+                :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
                 options: [:name, :value],
                 prices: [:amount, :compare_at_amount, :currency],
                 stock_items: [:id, :stock_location_id, :count_on_hand, :backorderable]
@@ -218,7 +218,8 @@ module Spree
             authorize! :update, model_class
 
             category_ids = decode_ids(params[:category_ids])
-            categories = current_store.taxons.accessible_by(current_ability, :update).where(id: category_ids)
+            categories = current_store.categories.
+                         accessible_by(current_ability, :update).where(id: category_ids)
 
             service.call(taxons: categories, products: bulk_collection)
             Spree::Product.bulk_auto_match_taxons(current_store, bulk_collection.ids)

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

@@ -69,7 +69,7 @@ module Spree
           private
 
           def promotion_includes
-            [:stores, :promotion_actions, :promotion_rules]
+            [:promotion_actions, :promotion_rules]
           end
         end
       end

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

@@ -39,6 +39,37 @@ module Spree
               Spree::PrefixedId.prefixed_id?(id) ? Spree::PrefixedId.decode_prefixed_id(id) : id
             end
           end
+
+          # Returns +url+ only when it matches one of the store's configured
+          # allowed origins — the gate for caller-provided URLs that later
+          # surface outside the request (e.g. the results_url the import/export
+          # done emails link back to). Anything else is silently dropped,
+          # mirroring the password-reset redirect_url behavior: no configured
+          # origins means no caller URLs are honored.
+          # @return [String, nil]
+          def validated_allowed_origin_url(url)
+            return if url.blank?
+            return unless current_store.allowed_origin?(url)
+
+            url
+          end
+
+          # Parses a strictly-integer param, returning nil for missing/blank/
+          # non-integer values (so callers can reject rather than coerce to 0).
+          # @return [Integer, nil]
+          def integer_param(name)
+            value = params[name]
+            Integer(value, exception: false) if value.is_a?(Integer) || value.to_s.match?(/\A-?\d+\z/)
+          end
+
+          # Renders a 422 for a missing/invalid +new_position+.
+          def render_invalid_position
+            render_error(
+              code: ERROR_CODES[:validation_error],
+              message: Spree.t('api.errors.invalid_position', default: 'new_position must be an integer'),
+              status: :unprocessable_content
+            )
+          end
         end
       end
     end