spree_api 5.4.3 → 5.5.0.rc2

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

@@ -0,0 +1,136 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # See `docs/plans/5.5-admin-spa-csv-export.md`.
+        #
+        # There is no standalone exports scope: an export is a bulk read of
+        # the records it contains, so each export type is gated by the read
+        # scope of the exported resource (Spree::Exports::Customers =>
+        # `read_customers`; see Spree::Export.required_scope), and the index
+        # is filtered to the types the key can read.
+        class ExportsController < ResourceController
+          include ActiveStorage::SetCurrent
+
+          # The index spans many export types — `scope` filters it to the
+          # readable ones instead of gating on a single scope.
+          skip_scope_check! only: :index
+
+          # 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 scope
+            collection = super
+            return collection unless scope_limited_principal?
+
+            collection.where(type: readable_export_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
+
+          # Exports never mutate commerce data; creating or downloading one
+          # is a bulk read, so every action maps to the read-level scope.
+          def action_kind
+            'read'
+          end
+
+          # Unresolvable types (blank/unknown `type` on create) fall back to
+          # `:all`, so only `read_all`/`write_all` keys reach the model's own
+          # validation.
+          def scoped_resource_name
+            export_class&.required_scope || :all
+          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
+
+          private
+
+          def export_class
+            action_name == 'create' ? resolve_export_type(params[:type]) : find_resource.class
+          end
+
+          def readable_export_types
+            Spree::Export.available_types.select do |type|
+              required = type.required_scope
+              required ? current_api_key.has_scope?("read_#{required}") : current_api_key.has_scope?('read_all')
+            end.map(&:to_s)
+          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

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

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin CRUD for `Spree::GiftCard`. Scoped to the current store via
+        # the model's `SingleStoreResource` include — the base controller's
+        # `scope` already applies `model_class.for_store(current_store)`.
+        #
+        # `store` and `created_by` are auto-stamped by `build_resource` in
+        # `Spree::Api::V3::ResourceController`, so create requests only need
+        # to include user-facing attributes (amount, currency, expires_at,
+        # optional code, optional user_id).
+        class GiftCardsController < ResourceController
+          scoped_resource :gift_cards
+
+          protected
+
+          def model_class
+            Spree::GiftCard
+          end
+
+          def serializer_class
+            Spree.api.admin_gift_card_serializer
+          end
+
+          def permitted_params
+            params.permit(:code, :amount, :expires_at, :user_id, :currency)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Public invitation acceptance — mounted under `/api/v3/admin/auth/...`
+        # so the issued refresh-token cookie's path matches `/auth/refresh`.
+        class InvitationAcceptancesController < BaseController
+          include Spree::Api::V3::Admin::AuthCookies
+
+          skip_scope_check!
+          skip_before_action :authenticate_admin!, only: [:lookup, :accept]
+
+          rate_limit to: Spree::Api::Config[:rate_limit_login],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     only: [:lookup, :accept],
+                     with: RATE_LIMIT_RESPONSE
+
+          # GET /api/v3/admin/auth/invitations/:id/lookup?token=:token
+          def lookup
+            return unless load_invitation
+
+            render json: Spree.api.admin_invitation_serializer.new(@invitation).serializable_hash
+          end
+
+          # POST /api/v3/admin/auth/invitations/:id/accept?token=:token
+          # Body: { password?, password_confirmation?, first_name?, last_name? }
+          def accept
+            return unless load_invitation
+
+            user = resolve_or_create_invitee(@invitation)
+            return if performed?
+
+            @invitation.invitee = user
+            @invitation.accept!
+
+            refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+            set_refresh_cookie(refresh_token)
+            render json: auth_response(user)
+          rescue ActiveRecord::RecordInvalid => e
+            render_validation_error(e.record.errors)
+          end
+
+          private
+
+          # Token mismatch is treated identically to "not found" to avoid
+          # leaking whether an ID exists.
+          def load_invitation
+            decoded_id = Spree::Invitation.decode_prefixed_id(params[:id])
+            @invitation = Spree::Invitation.pending.not_expired.find_by(id: decoded_id, token: params[:token])
+
+            unless @invitation
+              render_error(
+                code: ERROR_CODES[:record_not_found],
+                message: 'Invitation not found, expired, or already accepted',
+                status: :not_found
+              )
+              return false
+            end
+
+            true
+          end
+
+          # Email match between the invitation and any existing account is
+          # implicit: we look the user up by `invitation.email`, never by a
+          # client-supplied email. The token is the credential.
+          def resolve_or_create_invitee(invitation)
+            existing = Spree.admin_user_class.find_by(email: invitation.email)
+            return authenticate_existing(existing) if existing
+
+            create_new_invitee(invitation)
+          end
+
+          def authenticate_existing(user)
+            return user if user.valid_password?(params[:password].to_s)
+
+            render_error(
+              code: ERROR_CODES[:authentication_failed],
+              message: 'Invalid password',
+              status: :unauthorized
+            )
+            nil
+          end
+
+          def create_new_invitee(invitation)
+            if params[:password].blank?
+              render_error(
+                code: ERROR_CODES[:parameter_missing],
+                message: 'Password is required to create your account',
+                status: :unprocessable_content
+              )
+              return nil
+            end
+
+            Spree.admin_user_class.create!(signup_params(invitation))
+          end
+
+          def signup_params(invitation)
+            params.permit(:password, :password_confirmation, :first_name, :last_name).
+              merge(email: invitation.email)
+          end
+
+          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: @invitation&.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
+
+          def jwt_expiration
+            Spree::Api::Config[:admin_jwt_expiration]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Manages staff invitations for the current store. Each invitation
+        # carries an email + role; on accept, a `Spree::RoleUser` is created
+        # via the invitation's `after_accept` callback and the invitee
+        # becomes a member of the staff list for this store.
+        class InvitationsController < ResourceController
+          include Spree::Api::V3::Admin::RoleGrantGuard
+
+          scoped_resource :settings
+
+          # POST /api/v3/admin/invitations
+          # Guards against inviting a new staff member straight into the admin
+          # super-role unless the inviter already holds it.
+          def create
+            return if reject_unauthorized_role_grant!(Array(permitted_params[:role_id]))
+
+            super
+          end
+
+          # PATCH /api/v3/admin/invitations/:id/resend
+          # Issues a fresh token + email for an existing pending invitation.
+          # The model's `resend!` is responsible for resetting `expires_at`
+          # and dispatching the mailer.
+          def resend
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            @resource.resend!
+            render json: serialize_resource(@resource)
+          end
+
+          # Invitations are immutable post-create — UI calls `resend` for
+          # token rotation, `destroy` to revoke. Clearing the action set
+          # keeps the surface honest if a client ever fires PATCH directly.
+          def update
+            head :method_not_allowed
+          end
+
+          protected
+
+          def model_class
+            Spree::Invitation
+          end
+
+          def serializer_class
+            Spree.api.admin_invitation_serializer
+          end
+
+          def collection_includes
+            [:role, :inviter]
+          end
+
+          def scope
+            Spree::Invitation.
+              where(resource: current_store).
+              accessible_by(current_ability, :show)
+          end
+
+          def build_resource
+            scope.new(permitted_params).tap do |invitation|
+              invitation.resource = current_store
+              invitation.inviter = try_spree_current_user
+            end
+          end
+
+          # `email` and `role_id` are flat — `role_id` accepts a prefixed ID.
+          def permitted_params
+            attrs = params.permit(:email, :role_id)
+            if attrs[:role_id].present? && Spree::PrefixedId.prefixed_id?(attrs[:role_id])
+              attrs[:role_id] = Spree::PrefixedId.decode_prefixed_id(attrs[:role_id])
+            end
+            attrs
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin Markets surface. Markets are store-scoped (`store_id` column +
+        # `acts_as_list scope: :store_id`), so the base ResourceController's
+        # `scope` chain narrows appropriately when we restrict to
+        # `current_store.markets`.
+        #
+        # `country_isos` and `supported_locales` are accepted as arrays on the
+        # wire and translated by model setters (`Spree::Market#country_isos=`,
+        # `#supported_locales=`).
+        class MarketsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::Market
+          end
+
+          def serializer_class
+            Spree.api.admin_market_serializer
+          end
+
+          def collection_includes
+            [:countries]
+          end
+
+          def permitted_params
+            normalize_params(
+              params.permit(
+                :name, :currency, :default_locale, :tax_inclusive,
+                :default, :position, supported_locales: [], country_isos: []
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class MeController < Admin::BaseController
+          skip_scope_check!
+
+          # 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
+          # the permissions list to decide which UI elements to show or hide.
+          # The actual authorization check is still enforced server-side by
+          # CanCanCan — the SPA list is purely for UX.
+          def show
+            render json: {
+              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
+          #   CanCanCan's "last matching rule wins" semantics.
+          # - Per-record conditions are NOT serialized (they often reference
+          #   scopes or blocks that don't translate to JSON). The frontend
+          #   receives `has_conditions: true` as a hint that the action might
+          #   be denied at the per-record level — in practice the SPA shows
+          #   the action optimistically and handles 403 from the API.
+          def serialize_permissions(ability)
+            ability.send(:rules).map do |rule|
+              {
+                allow: rule.base_behavior,
+                actions: Array(rule.actions).map(&:to_s),
+                subjects: Array(rule.subjects).map { |s| s.is_a?(Class) ? s.name : s.to_s },
+                has_conditions: rule_has_conditions?(rule)
+              }
+            end
+          end
+
+          def rule_has_conditions?(rule)
+            return true if rule.block.present?
+            conditions = rule.conditions
+            return false if conditions.nil?
+            return !conditions.empty? if conditions.respond_to?(:empty?)
+
+            true
+          end
+
+          def admin_user_serializer
+            Spree.api.admin_admin_user_serializer
+          end
+
+          def serializer_params
+            {
+              store: current_store,
+              locale: current_locale,
+              currency: current_currency,
+              user: current_user,
+              includes: []
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class MediaController < ResourceController
+          scoped_resource :products
+
+          def create
+            if permitted_params[:url].present?
+              create_from_url
+            elsif permitted_params[:signed_id].present?
+              create_from_signed_id
+            else
+              @resource = build_resource
+              authorize_resource!(@resource, :create)
+
+              if @resource.save
+                render json: serialize_resource(@resource), status: :created
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::Asset
+          end
+
+          def serializer_class
+            Spree.api.admin_media_serializer
+          end
+
+          def set_parent
+            @product = current_store.products.find_by_prefix_id!(params[:product_id])
+            authorize!(:show, @product)
+
+            @parent = if params[:variant_id].present?
+                        @product.variants_including_master.find_by_prefix_id!(params[:variant_id])
+                      else
+                        @product
+                      end
+          end
+
+          # Variants store assets via the polymorphic `images` association; products own
+          # their gallery via `media`. Both resolve to `Spree::Asset` rows with different
+          # `viewable_type` values.
+          def parent_association
+            params[:variant_id].present? ? :images : :media
+          end
+
+          # For product-scoped listings we surface BOTH product-level assets and any
+          # legacy master-pinned assets, so existing data keeps showing up while
+          # merchants migrate. New uploads land on `Spree::Product` (see #set_parent).
+          def scope
+            return super if params[:variant_id].present?
+
+            Spree::Asset.where(
+              viewable_type: 'Spree::Product', viewable_id: @product.id
+            ).or(
+              Spree::Asset.where(
+                viewable_type: 'Spree::Variant', viewable_id: @product.master&.id
+              )
+            ).order(:position)
+          end
+
+          ALLOWED_MEDIA_TYPES = -> { [Spree::Asset, *Spree::Asset.descendants].map(&:name).to_set.freeze }
+
+          def build_resource
+            media_type = permitted_params[:type] || 'Spree::Image'
+
+            unless ALLOWED_MEDIA_TYPES.call.include?(media_type)
+              raise ArgumentError, "Invalid media type: #{media_type}"
+            end
+
+            media = @parent.send(parent_association).build(permitted_params.except(:type, :url, :signed_id))
+            media.type = media_type
+
+            media
+          end
+
+          def permitted_params
+            params.permit(:type, :alt, :position, :attachment, :url, :signed_id, variant_ids: [])
+          end
+
+          def create_from_url
+            authorize!(:create, Spree::Asset)
+
+            url = permitted_params[:url]
+            position = permitted_params[:position]
+
+            Spree::Images::SaveFromUrlJob.perform_later(
+              @parent.id,
+              @parent.class.name,
+              url,
+              nil,
+              position
+            )
+
+            head :accepted
+          end
+
+          def create_from_signed_id
+            @resource = build_resource
+            @resource.attachment.attach(permitted_params[:signed_id])
+            authorize_resource!(@resource, :create)
+
+            if @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class OptionTypesController < ResourceController
+          scoped_resource :products
+
+          protected
+
+          def model_class
+            Spree::OptionType
+          end
+
+          def serializer_class
+            Spree.api.admin_option_type_serializer
+          end
+
+          def scope_includes
+            [:option_values]
+          end
+
+          def permitted_params
+            params.permit(
+              :name, :label, :position, :filterable, :kind,
+              option_values: [
+                :id, :name, :label, :position, :color_code, :image
+              ]
+            )
+          end
+        end
+      end
+    end
+  end
+end