spree_api 5.4.3 → 5.5.0.rc2

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

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Read-only listing of coupon codes. Codes are generated server-side
+        # based on the parent promotion's `code_prefix` and `number_of_codes`,
+        # so this controller intentionally only exposes index/show.
+        class CouponCodesController < ResourceController
+          scoped_resource :promotions
+
+          protected
+
+          def model_class
+            Spree::CouponCode
+          end
+
+          def serializer_class
+            Spree.api.admin_coupon_code_serializer
+          end
+
+          def set_parent
+            @parent = Spree::Promotion.accessible_by(current_ability, :show)
+                                      .find_by_prefix_id!(params[:promotion_id])
+          end
+
+          def parent_association
+            :coupon_codes
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Schema-side metadata for custom fields. Definitions are per resource
+        # *type* (every Spree::Product shares the same definitions), so this is
+        # a flat top-level endpoint. Filter by `?resource_type=Spree::Product`
+        # (or any other registered custom-field-bearing resource) to scope the
+        # list to one parent type.
+        class CustomFieldDefinitionsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::CustomFieldDefinition
+          end
+
+          def serializer_class
+            Spree.api.admin_custom_field_definition_serializer
+          end
+
+          # `label`, `field_type`, `storefront_visible` are model-side aliases
+          # (alias_attribute / accessors) on Spree::CustomFieldDefinition. The
+          # API → DB column rename lands in 6.0 and this controller stays flat.
+          def permitted_params
+            params.permit(:namespace, :key, :label, :field_type,
+                          :resource_type, :storefront_visible)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+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_relation.find_by_prefix_id!(parent_lookup.value)
+            authorize!(:show, @parent)
+          end
+
+          # Resolves the parent within the current store so a token for one
+          # store can't read or write custom fields on another store's records.
+          # Users are intentionally global in Spree (`User.for_store` is a
+          # no-op), so the store boundary for customer parents is enforced by
+          # the `authorize!(:show, @parent)` ability check above.
+          def parent_relation
+            klass = parent_lookup.klass
+            klass.respond_to?(:for_store) ? klass.for_store(current_store) : klass
+          end
+
+          # Product-family parents have no scope pair of their own — their
+          # custom fields are catalog data, gated by `products` like the rest
+          # of the variant/option-type surface.
+          SCOPE_OVERRIDES = { 'option_type' => :products, 'variant' => :products }.freeze
+
+          # 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
+            segment = parent_lookup&.segment
+            return unless segment
+
+            SCOPE_OVERRIDES[segment] || 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'`,
+          # and `'category'` because the routes expose taxons as categories
+          # (5.5 rename) while the model's element is still `'taxon'`.
+          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, 'category' => 'Spree::Taxon')
+          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,83 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class AddressesController < BaseController
+
+            # 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 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/base_controller.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          # Shared base for resources nested under a customer
+          # (`/admin/customers/:customer_id/...`). Resolves the parent customer
+          # and authorizes it per action (`:show` for reads, `:update` for
+          # writes) so a role that can only view a customer can't mutate its
+          # nested collections. Mirrors `Orders::BaseController`.
+          class BaseController < ResourceController
+            scoped_resource :customers
+
+            protected
+
+            # Resolve the customer through the ability-scoped relation, using
+            # the action-appropriate ability on the parent (`:show` for reads,
+            # `:update` for writes — see `parent_ability_action`). A customer
+            # the caller can't access for the requested action is filtered out
+            # and 404s, rather than leaking its existence as a 403. Users are
+            # global in Spree (`User.for_store` is a no-op), so the ability is
+            # the only boundary here.
+            def set_parent
+              @parent = Spree.user_class.
+                        accessible_by(current_ability, parent_ability_action).
+                        find_by_prefix_id!(params[:customer_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class CreditCardsController < BaseController
+            protected
+
+            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,92 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          class StoreCreditsController < BaseController
+            # Store credits gate on their own scope rather than the parent's
+            # `:customers`, so a store-credit integration key doesn't need
+            # broad customer access.
+            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 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