spree_api 5.4.3 → 5.5.0.rc1

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,70 @@
+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
+          scoped_resource :settings
+
+          # 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

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

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class AdjustmentsController < BaseController
+            scoped_resource :orders
+
+            protected
+
+            def model_class
+              Spree::Adjustment
+            end
+
+            def serializer_class
+              Spree.api.admin_adjustment_serializer
+            end
+
+            def parent_association
+              :adjustments
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class BaseController < ResourceController
+            include Spree::Api::V3::OrderLock
+
+            before_action :authorize_order_access!
+
+            protected
+
+            def set_parent
+              @parent = current_store.orders.find_by_prefix_id!(params[:order_id])
+              @order = @parent
+            end
+
+            def authorize_order_access!
+              authorize!(:show, @parent)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class FulfillmentsController < BaseController
+            scoped_resource :fulfillments
+
+            before_action :set_resource, only: [:show, :update, :fulfill, :cancel, :resume, :split]
+
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id
+            def update
+              with_order_lock do
+                result = Spree.shipment_update_service.call(
+                  shipment: @resource,
+                  shipment_attributes: permitted_params.to_h
+                )
+
+                if result.success?
+                  render json: serialize_resource(@resource.reload)
+                else
+                  render_result_error(result)
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/fulfill
+            def fulfill
+              with_order_lock do
+                @resource.ship!
+                render json: serialize_resource(@resource.reload)
+              rescue StateMachines::InvalidTransition => e
+                render_service_error(e.message)
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/cancel
+            def cancel
+              with_order_lock do
+                @resource.cancel!
+                render json: serialize_resource(@resource.reload)
+              rescue StateMachines::InvalidTransition => e
+                render_service_error(e.message)
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/resume
+            def resume
+              with_order_lock do
+                @resource.resume!
+                render json: serialize_resource(@resource.reload)
+              rescue StateMachines::InvalidTransition => e
+                render_service_error(e.message)
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/split
+            def split
+              with_order_lock do
+                variant = Spree::Variant.find_by_prefix_id!(params[:variant_id])
+                quantity = params[:quantity].to_i
+
+                stock_location = if params[:stock_location_id].present?
+                                   Spree::StockLocation.find_by_prefix_id!(params[:stock_location_id])
+                                 else
+                                   @resource.stock_location
+                                 end
+
+                fulfilment_changer = @resource.transfer_to_location(variant, quantity, stock_location)
+
+                if fulfilment_changer.run!
+                  fulfillments = @order.reload.shipments
+                  render json: {
+                    data: fulfillments.map { |s| serialize_resource(s) }
+                  }
+                else
+                  render_validation_error(fulfilment_changer.errors)
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Shipment
+            end
+
+            def serializer_class
+              Spree.api.admin_fulfillment_serializer
+            end
+
+            def parent_association
+              :shipments
+            end
+
+            def permitted_params
+              params.permit(:tracking, :selected_shipping_rate_id, :stock_location_id, :state)
+            end
+          end
+        end
+      end
+    end
+  end
+end