spree_api 5.4.3 → 5.5.0.rc1

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

@@ -0,0 +1,108 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Custom field values for any parent that includes the custom-fields
+        # concern. Mounted via the `:custom_fieldable` route concern; the parent
+        # class is inferred from whichever `<segment>_id` route param matches a
+        # registered owner.
+        class CustomFieldsController < ResourceController
+          # POST /api/v3/admin/<parent>/<parent_id>/custom_fields
+          def create
+            @resource = @parent.metafields.new(permitted_params)
+            authorize_resource!(@resource, :create)
+
+            if @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          # PATCH /api/v3/admin/<parent>/<parent_id>/custom_fields/:id
+          # Only `value` is mutable. Switching the linked definition is a
+          # delete-and-create — the model rejects it (definition + resource
+          # uniqueness) and the type wouldn't match.
+          def update
+            authorize_resource!(@resource)
+
+            if @resource.update(update_permitted_params)
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::CustomField
+          end
+
+          def serializer_class
+            Spree.api.admin_custom_field_serializer
+          end
+
+          def parent_association
+            :metafields
+          end
+
+          def set_parent
+            # Routes always mount this controller under a recognized parent, so
+            # `parent_lookup` matches in normal flows. The explicit raise is a
+            # defensive guard against a future route nesting that doesn't.
+            raise ActiveRecord::RecordNotFound, 'Parent resource not found' unless parent_lookup
+
+            @parent = parent_lookup.klass.find_by_prefix_id!(parent_lookup.value)
+          end
+
+          # Per-parent scope check: a key holding `write_products` may write a
+          # product's custom fields, `write_orders` may write an order's, etc.
+          # Resolves the parent at request time rather than via the static
+          # `scoped_resource` declaration.
+          def scoped_resource_name
+            parent_lookup&.segment&.pluralize&.to_sym
+          end
+
+          # `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
+          # AR resolves the prefixed-ID and the alias to the canonical FK on assign.
+          def permitted_params
+            params.permit(:custom_field_definition_id, :value)
+          end
+
+          def update_permitted_params
+            params.permit(:value)
+          end
+
+          private
+
+          ParentLookup = Struct.new(:klass, :value, :segment)
+
+          # Stores class names (not class objects) so the map survives dev-mode
+          # code reloads — `enabled_resources` is captured at boot and its
+          # class references go stale. Aliases `'customer'` because the route
+          # uses `customer_id` while user_class.model_name.element is `'user'`.
+          def parent_route_map
+            @parent_route_map ||= Spree.metafields.enabled_resources.each_with_object({}) do |klass, m|
+              m[klass.model_name.element.to_s] = klass.name
+            end.merge('customer' => Spree.user_class.name)
+          end
+
+          # Returns the first segment whose `<segment>_id` is present in params,
+          # paired with its class and the raw id value, or nil. Memoized — read
+          # by both `set_parent` and `scoped_resource_name`.
+          def parent_lookup
+            return @parent_lookup if defined?(@parent_lookup)
+
+            match = parent_route_map.find { |segment, _| params[:"#{segment}_id"].present? }
+            @parent_lookup =
+              if match
+                segment, klass_name = match
+                ParentLookup.new(klass_name.constantize, params[:"#{segment}_id"], segment)
+              end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin CRUD for `Spree::CustomerGroup`. Scoped to the current
+        # store so groups from sibling stores don't leak into pickers.
+        class CustomerGroupsController < ResourceController
+          scoped_resource :customers
+
+          protected
+
+          def model_class
+            Spree::CustomerGroup
+          end
+
+          def serializer_class
+            Spree.api.admin_customer_group_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          def permitted_params
+            params.permit(:name, :description, customer_ids: [])
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/customers/addresses_controller.rb

@@ -0,0 +1,88 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class AddressesController < ResourceController
+            scoped_resource :customers
+
+            # POST /api/v3/admin/customers/:customer_id/addresses
+            def create
+              @resource = @parent.addresses.new(address_attrs)
+              authorize_resource!(@resource, :create)
+
+              ApplicationRecord.transaction do
+                if @resource.save
+                  apply_default_flags(@resource)
+                  render json: serialize_resource(@resource.reload), status: :created
+                else
+                  render_validation_error(@resource.errors)
+                  raise ActiveRecord::Rollback
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/customers/:customer_id/addresses/:id
+            def update
+              authorize_resource!(@resource)
+
+              ApplicationRecord.transaction do
+                if @resource.update(address_attrs)
+                  apply_default_flags(@resource)
+                  render json: serialize_resource(@resource.reload)
+                else
+                  render_validation_error(@resource.errors)
+                  raise ActiveRecord::Rollback
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/customers/:customer_id/addresses/:id
+            def destroy
+              authorize_resource!(@resource)
+              @resource.destroy
+              head :no_content
+            end
+
+            protected
+
+            def set_parent
+              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
+            end
+
+            def parent_association
+              :addresses
+            end
+
+            def model_class
+              Spree::Address
+            end
+
+            def serializer_class
+              Spree.api.admin_address_serializer
+            end
+
+            private
+
+            def address_attrs
+              params.permit(
+                :firstname, :lastname, :first_name, :last_name,
+                :address1, :address2, :city,
+                :country_iso, :state_abbr, :country_id, :state_id,
+                :zipcode, :postal_code, :phone, :alternative_phone,
+                :state_name, :company, :label, :quick_checkout
+              )
+            end
+
+            def apply_default_flags(address)
+              updates = {}
+              updates[:bill_address_id] = address.id if ActiveModel::Type::Boolean.new.cast(params[:is_default_billing])
+              updates[:ship_address_id] = address.id if ActiveModel::Type::Boolean.new.cast(params[:is_default_shipping])
+              @parent.update!(updates) if updates.any?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/customers/credit_cards_controller.rb

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class CreditCardsController < ResourceController
+            scoped_resource :customers
+
+            protected
+
+            def set_parent
+              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
+            end
+
+            def parent_association
+              :credit_cards
+            end
+
+            def model_class
+              Spree::CreditCard
+            end
+
+            def serializer_class
+              Spree.api.admin_credit_card_serializer
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/customers/store_credits_controller.rb

@@ -0,0 +1,93 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class StoreCreditsController < ResourceController
+            scoped_resource :store_credits
+
+            # POST /api/v3/admin/customers/:customer_id/store_credits
+            def create
+              @resource = @parent.store_credits.new(create_attrs)
+              @resource.created_by = try_spree_current_user
+              @resource.store ||= current_store
+              @resource.category ||= Spree::StoreCreditCategory.first
+              authorize_resource!(@resource, :create)
+
+              if @resource.save
+                render json: serialize_resource(@resource), status: :created
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            # PATCH /api/v3/admin/customers/:customer_id/store_credits/:id
+            def update
+              authorize_resource!(@resource)
+
+              if @resource.amount_used.positive? && update_attrs.key?(:amount)
+                render_error(
+                  code: 'store_credit_in_use',
+                  message: 'Cannot change amount on a store credit that has already been used',
+                  status: :unprocessable_content
+                )
+                return
+              end
+
+              if @resource.update(update_attrs)
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            # DELETE /api/v3/admin/customers/:customer_id/store_credits/:id
+            def destroy
+              authorize_resource!(@resource)
+
+              if @resource.amount_used.positive?
+                render_error(
+                  code: 'store_credit_in_use',
+                  message: 'Cannot delete a store credit that has already been used',
+                  status: :unprocessable_content
+                )
+                return
+              end
+
+              @resource.destroy
+              head :no_content
+            end
+
+            protected
+
+            def set_parent
+              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
+            end
+
+            def parent_association
+              :store_credits
+            end
+
+            def model_class
+              Spree::StoreCredit
+            end
+
+            def serializer_class
+              Spree.api.admin_store_credit_serializer
+            end
+
+            private
+
+            def create_attrs
+              params.permit(:amount, :currency, :category_id, :memo).to_h
+            end
+
+            def update_attrs
+              params.permit(:memo, :category_id, :amount).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CustomersController < ResourceController
+          include Spree::Api::V3::BulkOperations
+
+          scoped_resource :customers
+
+          before_action :require_ids!, only: [:bulk_add_to_groups, :bulk_remove_from_groups]
+
+          def create
+            @resource = Spree.user_class.new(permitted_params)
+            # Admin-created customers don't pick a password upfront — they
+            # claim the account via password reset later.
+            # `Spree::UserMethods` exposes `skip_password_validation` so
+            # Devise's `:validatable` lets a nil credential through on this
+            # code path. Storefront registration never sets the flag, so
+            # customer self-signup still requires a password.
+            @resource.skip_password_validation = true if @resource.password.blank?
+            authorize!(:create, @resource)
+
+            if @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            authorize_resource!(@resource)
+
+            if @resource.update(permitted_params)
+              render json: serialize_resource(@resource.reload)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def destroy
+            authorize_resource!(@resource)
+            @resource.destroy
+            head :no_content
+          rescue Spree::Core::DestroyWithOrdersError => e
+            render_error(
+              code: 'customer_has_orders',
+              message: e.message.presence || Spree.t(:error_user_destroy_with_orders),
+              status: :unprocessable_content
+            )
+          end
+
+          # Bulk add the given customers to the given groups. Idempotent —
+          # customers already in a group are skipped at the model layer.
+          def bulk_add_to_groups
+            apply_groups(:add_customers)
+          end
+
+          # Bulk remove the given customers from the given groups.
+          def bulk_remove_from_groups
+            apply_groups(:remove_customers)
+          end
+
+          protected
+
+          def model_class
+            Spree.user_class
+          end
+
+          def serializer_class
+            Spree.api.admin_customer_serializer
+          end
+
+          def scope
+            super.with_order_aggregates
+          end
+
+          def collection_includes
+            [:rich_text_internal_note, taggings: :tag]
+          end
+
+          private
+
+          # Mirrors the products controller's resource-named key so SPA toasts
+          # can substitute `{customer_count}` instead of the generic
+          # `{record_count}` shipped by `Spree::Api::V3::BulkOperations`.
+          def bulk_record_count_key
+            :customer_count
+          end
+
+          def permitted_params
+            params.permit(
+              :email, :first_name, :last_name, :phone,
+              :password, :password_confirmation, :selected_locale,
+              :avatar, :accepts_email_marketing, :internal_note,
+              metadata: {}, tags: []
+            )
+          end
+
+          # Authorises bulk group mutation, decodes prefixed IDs, then dispatches
+          # to `add_customers` / `remove_customers` per group. Returns the
+          # counts of records actually affected so the UI can show a toast.
+          def apply_groups(method)
+            authorize! :update, model_class
+
+            user_ids = decode_ids(params[:ids])
+            group_ids = decode_ids(params[:customer_group_ids])
+
+            scoped_user_ids = scope.where(id: user_ids).pluck(:id)
+            scoped_groups = Spree::CustomerGroup.for_store(current_store).where(id: group_ids)
+
+            scoped_groups.find_each { |group| group.public_send(method, scoped_user_ids) }
+
+            render json: { customer_count: scoped_user_ids.size, customer_group_count: scoped_groups.size }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DashboardController < Admin::BaseController
+          scoped_resource :dashboard
+
+          # GET /api/v3/admin/dashboard/analytics
+          def analytics
+            date_from = (params[:date_from] || 30.days.ago).to_time.beginning_of_day
+            date_to = (params[:date_to] || Time.current).to_time.end_of_day
+            currency = params[:currency] || current_store.default_currency
+
+            serializer = DashboardAnalyticsSerializer.new(
+              store: current_store,
+              currency: currency,
+              time_range: date_from..date_to,
+              params: serializer_params
+            )
+
+            render json: serializer.to_h
+          end
+
+          private
+
+          def action_kind
+            'read'
+          end
+
+          def serializer_params
+            {
+              store: current_store,
+              locale: current_locale,
+              currency: current_currency,
+              user: current_user,
+              includes: [],
+              expand: []
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DirectUploadsController < Admin::BaseController
+          # Direct uploads is a write-adjacent presigning helper: callers exchange
+          # blob metadata for an upload URL, then reference the resulting
+          # signed_id when creating/updating a resource (product media, customer
+          # avatar, etc). The narrowest scope it can map to is `write_products`
+          # since that covers the dominant upload flow (product/variant media).
+          # Other admin-write flows that take signed_ids (e.g. customer avatar)
+          # already require the relevant `write_<resource>` scope on the
+          # subsequent PATCH, so this gate is the floor, not the only check.
+          scoped_resource :products
+
+          skip_before_action :authenticate_user
+
+          # POST /api/v3/admin/direct_uploads
+          def create
+            blob = ActiveStorage::Blob.create_before_direct_upload!(**blob_params)
+
+            render json: {
+              direct_upload: {
+                url: blob.service_url_for_direct_upload,
+                headers: blob.service_headers_for_direct_upload
+              },
+              signed_id: blob.signed_id
+            }, status: :created
+          end
+
+          private
+
+          def blob_params
+            params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # See `docs/plans/5.5-admin-spa-csv-export.md`.
+        class ExportsController < ResourceController
+          include ActiveStorage::SetCurrent
+
+          scoped_resource :exports
+
+          # We stream the CSV inline rather than redirecting to ActiveStorage's
+          # signed-URL endpoint because the SPA's Vite proxy only forwards
+          # `/api/*`. A cross-origin redirect to `/rails/active_storage/...`
+          # strips the Authorization header and the download fails silently.
+          def download
+            @resource = find_resource
+            authorize_resource!(@resource, :show)
+
+            unless @resource.done?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:export_not_ready],
+                message: 'Export is not ready yet',
+                status: :unprocessable_content
+              )
+            end
+
+            attachment = @resource.attachment
+            send_data(
+              attachment.download,
+              filename: attachment.filename.to_s,
+              type: attachment.content_type || 'text/csv',
+              disposition: 'attachment'
+            )
+          end
+
+          protected
+
+          def model_class
+            Spree::Export
+          end
+
+          def serializer_class
+            Spree.api.admin_export_serializer
+          end
+
+          def scope_includes
+            [:user, { attachment_attachment: :blob }]
+          end
+
+          def build_resource
+            klass = resolve_export_type(permitted_params[:type]) || Spree::Export
+            attrs = permitted_params.except(:type).merge(
+              store: current_store,
+              user: try_spree_current_user
+            )
+            klass.new(attrs)
+          end
+
+          # `search_params` carries an arbitrary Ransack hash with nested
+          # groupings (`{ g: [{ name_cont: 'foo' }] }`). Rails' `permit(k: {})`
+          # rejects nested hashes, so we extract via `to_unsafe_h`. `:format`
+          # is intentionally dropped — only CSV is supported and Rails' request
+          # format would otherwise overwrite the model's enum.
+          def permitted_params
+            attrs = params.permit(:type, :record_selection)
+            raw = params[:search_params]
+            attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
+            attrs
+          end
+
+          # Returns the registered Export 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. This keeps the data flow
+          # from user input → trusted-string → `constantize` legible to
+          # static analyzers (CodeQL otherwise flags the inverse pattern of
+          # gating user input with `include?` before calling `constantize`).
+          def resolve_export_type(name)
+            return nil if name.blank?
+
+            target = Spree::Export.available_types.map(&:to_s).find { |t| t == name.to_s }
+            target&.constantize
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin bulk-issue endpoint for `Spree::GiftCardBatch`. Creating a
+        # batch synchronously generates the `codes_count` gift cards inline
+        # (or kicks off a background job when the count exceeds
+        # `Spree.config.gift_card_batch_web_limit`, default 500). Read-only
+        # access lives behind `list`/`show` so the SPA can surface batch
+        # context on the gift cards index (filter chip, batch chip on rows).
+        class GiftCardBatchesController < ResourceController
+          scoped_resource :gift_cards
+
+          protected
+
+          def model_class
+            Spree::GiftCardBatch
+          end
+
+          def serializer_class
+            Spree.api.admin_gift_card_batch_serializer
+          end
+
+          def permitted_params
+            params.permit(:prefix, :codes_count, :amount, :expires_at, :currency)
+          end
+        end
+      end
+    end
+  end
+end