spree_api 5.4.3 → 5.5.0.rc1

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

@@ -0,0 +1,79 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class GiftCardsController < BaseController
+            scoped_resource :gift_cards
+
+            skip_before_action :set_resource, raise: false
+
+            # POST /api/v3/admin/orders/:order_id/gift_cards
+            #
+            # Body: { code: String }
+            def create
+              with_order_lock do
+                gift_card = find_gift_card!
+                return unless gift_card
+
+                result = @parent.apply_gift_card(gift_card)
+
+                if result.success?
+                  render json: serializer_class.new(gift_card).to_h, status: :created
+                else
+                  render_service_error(result.error)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/gift_cards/:id
+            def destroy
+              with_order_lock do
+                result = @parent.remove_gift_card
+
+                if result.success?
+                  head :no_content
+                else
+                  render_service_error(result.error)
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::GiftCard
+            end
+
+            def serializer_class
+              Spree.api.admin_gift_card_serializer
+            end
+
+            private
+
+            def find_gift_card!
+              gift_card = current_store.gift_cards.find_by(code: params[:code]&.downcase)
+
+              if gift_card.nil?
+                render_error(code: ERROR_CODES[:gift_card_not_found], message: Spree.t(:gift_card_not_found), status: :not_found)
+                return
+              end
+
+              if gift_card.expired?
+                render_error(code: ERROR_CODES[:gift_card_expired], message: Spree.t(:gift_card_expired), status: :unprocessable_content)
+                return
+              end
+
+              if gift_card.redeemed?
+                render_error(code: ERROR_CODES[:gift_card_already_redeemed], message: Spree.t(:gift_card_already_redeemed), status: :unprocessable_content)
+                return
+              end
+
+              gift_card
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class ItemsController < BaseController
+            scoped_resource :orders
+
+            # POST /api/v3/admin/orders/:order_id/items
+            def create
+              with_order_lock do
+                result = Spree.cart_add_item_service.call(
+                  order: @parent,
+                  variant: variant,
+                  quantity: permitted_params[:quantity] || 1,
+                  options: permitted_params[:options] || {}
+                )
+
+                if result.success?
+                  render json: serialize_resource(result.value), status: :created
+                else
+                  render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/items/:id
+            def update
+              with_order_lock do
+                if permitted_params[:quantity].present?
+                  result = Spree.cart_set_item_quantity_service.call(
+                    order: @parent,
+                    line_item: @resource,
+                    quantity: permitted_params[:quantity]
+                  )
+
+                  if result.success?
+                    render json: serialize_resource(@resource.reload)
+                  else
+                    render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+                  end
+                else
+                  if @resource.update(permitted_params.except(:variant_id, :quantity))
+                    render json: serialize_resource(@resource)
+                  else
+                    render_errors(@resource.errors)
+                  end
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/items/:id
+            def destroy
+              with_order_lock do
+                Spree.cart_remove_line_item_service.call(
+                  order: @parent,
+                  line_item: @resource
+                )
+
+                head :no_content
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::LineItem
+            end
+
+            def serializer_class
+              Spree.api.admin_line_item_serializer
+            end
+
+            def parent_association
+              :line_items
+            end
+
+            def permitted_params
+              params.permit(:variant_id, :quantity, metadata: {}, options: {})
+            end
+
+            private
+
+            def variant
+              @variant ||= current_store.variants.find_by_prefix_id!(permitted_params[:variant_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class PaymentsController < BaseController
+            scoped_resource :payments
+
+            before_action :set_resource, only: [:show, :capture, :void]
+
+            # POST /api/v3/admin/orders/:order_id/payments
+            #
+            # Supports off-session admin charges by passing `source_id` referencing a
+            # saved payment source (e.g. a Spree::CreditCard owned by the order's customer).
+            # The source must belong to the customer assigned to the order.
+            def create
+              with_order_lock do
+                payment_method = Spree::PaymentMethod.find_by_prefix_id!(params[:payment_method_id])
+                @resource = @parent.payments.build(
+                  amount: params[:amount] || @parent.order_total_after_store_credit,
+                  payment_method: payment_method
+                )
+
+                if params[:source_id].present? && payment_method.source_required?
+                  @resource.source = find_source!(payment_method, params[:source_id])
+                end
+
+                authorize_resource!(@resource, :create)
+
+                if @resource.save
+                  render json: serialize_resource(@resource), status: :created
+                else
+                  render_validation_error(@resource.errors)
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/payments/:id/capture
+            def capture
+              with_order_lock do
+                amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
+                @resource.capture!(amount)
+                render json: serialize_resource(@resource.reload)
+              rescue Spree::Core::GatewayError => e
+                render_service_error(e.message)
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/payments/:id/void
+            def void
+              with_order_lock do
+                @resource.void_transaction!
+                render json: serialize_resource(@resource.reload)
+              rescue Spree::Core::GatewayError => e
+                render_service_error(e.message)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Payment
+            end
+
+            def serializer_class
+              Spree.api.admin_payment_serializer
+            end
+
+            def parent_association
+              :payments
+            end
+
+            def permitted_params
+              params.permit(:amount, :payment_method_id, :source_id)
+            end
+
+            # Saved-source charges require an order customer — sources are scoped
+            # to that customer to prevent attaching customer A's card to
+            # customer B's order. Refuse if no customer is assigned.
+            def find_source!(payment_method, source_id)
+              raise ActiveRecord::RecordNotFound unless @parent.user
+
+              @parent.user.credit_cards.find_by_prefix_id!(source_id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class RefundsController < BaseController
+            scoped_resource :refunds
+
+            # POST /api/v3/admin/orders/:order_id/refunds
+            def create
+              with_order_lock do
+                payment = @parent.payments.find_by_prefix_id!(params[:payment_id])
+                reason = Spree::RefundReason.find_by_prefix_id!(params[:refund_reason_id]) if params[:refund_reason_id].present?
+                reason ||= Spree::RefundReason.first
+
+                @resource = payment.refunds.build(
+                  amount: params[:amount],
+                  reason: reason,
+                  transaction_id: nil
+                )
+                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::Refund
+            end
+
+            def serializer_class
+              Spree.api.admin_refund_serializer
+            end
+
+            def scope
+              Spree::Refund.where(payment_id: @parent.payment_ids)
+            end
+
+            def collection_includes
+              [:payment, :reason]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          class StoreCreditsController < BaseController
+            scoped_resource :store_credits
+
+            skip_before_action :set_resource, raise: false
+
+            # POST /api/v3/admin/orders/:order_id/store_credits
+            #
+            # Body: { amount: Number (optional) }
+            #
+            # When `amount` is omitted, applies the customer's available store
+            # credit up to the order total.
+            def create
+              with_order_lock do
+                result = Spree.checkout_add_store_credit_service.call(
+                  order: @parent,
+                  amount: params[:amount].try(:to_f)
+                )
+
+                if result.success?
+                  render json: serialize_resource(result.value), status: :created
+                else
+                  render_service_error(result.error)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/store_credits
+            def destroy
+              with_order_lock do
+                result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+
+                if result.success?
+                  head :no_content
+                else
+                  render_service_error(result.error)
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Order
+            end
+
+            def serializer_class
+              Spree.api.admin_order_serializer
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class OrdersController < ResourceController
+          include Spree::Api::V3::OrderLock
+
+          scoped_resource :orders
+
+          skip_before_action :set_resource, only: [:index, :create]
+          before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resume, :resend_confirmation]
+
+          # POST /api/v3/admin/orders
+          def create
+            authorize!(:create, Spree::Order)
+
+            result = Spree.order_create_service.call(
+              store: current_store,
+              user: resolve_user,
+              params: order_create_params
+            )
+
+            if result.success?
+              @resource = result.value
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_service_error(result.error)
+            end
+          end
+
+          # PATCH /api/v3/admin/orders/:id
+          def update
+            with_order_lock do
+              result = Spree.order_update_service.call(
+                order: @resource,
+                params: order_update_params
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_validation_error(@resource.errors.presence || result.error)
+              end
+            end
+          end
+
+          # PATCH /api/v3/admin/orders/:id/complete
+          def complete
+            with_order_lock do
+              result = Spree.order_complete_service.call(
+                order: @resource,
+                payment_pending: ActiveModel::Type::Boolean.new.cast(params[:payment_pending]),
+                notify_customer: ActiveModel::Type::Boolean.new.cast(params[:notify_customer])
+              )
+
+              if result.success?
+                render json: serialize_resource(@resource.reload)
+              else
+                render_service_error(@resource.errors.presence || result.error, code: ERROR_CODES[:order_cannot_complete])
+              end
+            end
+          end
+
+          # PATCH /api/v3/admin/orders/:id/cancel
+          def cancel
+            with_order_lock do
+              @resource.canceled_by(try_spree_current_user)
+              render json: serialize_resource(@resource.reload)
+            end
+          end
+
+          # PATCH /api/v3/admin/orders/:id/approve
+          def approve
+            with_order_lock do
+              @resource.approved_by(try_spree_current_user)
+              render json: serialize_resource(@resource.reload)
+            end
+          end
+
+          # PATCH /api/v3/admin/orders/:id/resume
+          def resume
+            with_order_lock do
+              @resource.resume!
+              render json: serialize_resource(@resource.reload)
+            end
+          end
+
+          # POST /api/v3/admin/orders/:id/resend_confirmation
+          def resend_confirmation
+            @resource.publish_event('order.completed')
+            render json: serialize_resource(@resource)
+          end
+
+          protected
+
+          def model_class
+            Spree::Order
+          end
+
+          def serializer_class
+            Spree.api.admin_order_serializer
+          end
+
+          # Override scope — Order uses SingleStoreResource (for_store)
+          def scope
+            current_store.orders.accessible_by(current_ability, :show).preload_associations_lazily
+          end
+
+          def set_resource
+            @resource = scope.find_by_prefix_id!(params[:id])
+            @order = @resource # needed for OrderLock
+            authorize_resource!(@resource)
+          end
+
+          # Map state transition actions to :update permission
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            mapped_action = case action
+                            when :complete, :cancel, :approve, :resume, :resend_confirmation
+                              :update
+                            else
+                              action
+                            end
+            authorize!(mapped_action, resource)
+          end
+
+          def collection_includes
+            [:line_items, :user, :channel, :rich_text_internal_note]
+          end
+
+          private
+
+          def resolve_user
+            customer_param = params[:customer_id].presence || params[:user_id].presence
+            return unless customer_param
+
+            Spree.user_class.find_by_param!(customer_param)
+          end
+
+          def order_create_params
+            normalize_params(
+              params.permit(
+                :email, :customer_id, :user_id, :use_customer_default_address,
+                :currency, :market_id, :channel_id, :locale,
+                :customer_note, :internal_note,
+                :shipping_address_id, :billing_address_id,
+                :preferred_stock_location_id,
+                :coupon_code,
+                metadata: {},
+                tags: [],
+                shipping_address: address_permitted_keys,
+                billing_address: address_permitted_keys,
+                items: item_permitted_keys
+              )
+            )
+          end
+
+          def order_update_params
+            normalize_params(
+              params.permit(
+                :email, :customer_id, :user_id,
+                :customer_note, :internal_note,
+                :currency, :locale, :market_id, :channel_id,
+                :preferred_stock_location_id,
+                metadata: {},
+                tags: [],
+                ship_address: address_permitted_keys,
+                bill_address: address_permitted_keys,
+                items: item_permitted_keys
+              )
+            )
+          end
+
+          def address_permitted_keys
+            [
+              :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
+            ]
+          end
+
+          def item_permitted_keys
+            [:variant_id, :quantity, { metadata: {} }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class PaymentMethodsController < ResourceController
+          include Spree::Api::V3::Admin::SubclassedResource
+
+          scoped_resource :settings
+
+          subclassed_via -> { Spree::PaymentMethod.providers },
+                         unknown_type_error: 'unknown_payment_method_type'
+
+          # Lists available payment provider subclasses for the create form.
+          # Returns: { data: [{ type, label, description, preference_schema }] }.
+          # The preference_schema array describes the provider-specific
+          # configuration fields, so admin UIs can render a generic
+          # preferences form without hard-coding per-provider knowledge.
+          # Filters out subclasses already installed in the current store —
+          # mirrors the legacy admin's "available_payment_methods" helper, so
+          # admins don't see (and accidentally double-install) the same
+          # provider twice.
+          def types
+            authorize! :create, model_class
+
+            # Query via direct join rather than `current_store.payment_methods`
+            # — the has_many-through association can cache stale results when
+            # `current_store` was loaded earlier in the request (e.g. by the
+            # auth layer).
+            installed_class_names = Spree::PaymentMethod
+                                      .joins(:store_payment_methods)
+                                      .where(spree_payment_methods_stores: { store_id: current_store.id })
+                                      .pluck(:type)
+            installed_shorthands = installed_class_names.filter_map do |name|
+              name.safe_constantize&.api_type
+            end
+            available = model_class.subclasses_with_preference_schema.reject do |entry|
+              installed_shorthands.include?(entry[:type])
+            end
+
+            render json: { data: available }
+          end
+
+          protected
+
+          def model_class
+            Spree::PaymentMethod
+          end
+
+          def serializer_class
+            Spree.api.admin_payment_method_serializer
+          end
+
+          # Explicit allowlist per the v3 convention — flat params, no
+          # reach into the global `Spree::PermittedAttributes` registry
+          # (which is the legacy Rails admin's surface). `type` and
+          # `preferences` are added by `SubclassedResource` on top.
+          def permitted_params
+            params.permit(:name, :description, :active, :storefront_visible, :auto_capture, :position, metadata: {}, preferences: {})
+          end
+
+          private
+
+          # New payment methods get scoped to the current store automatically.
+          def build_subclassed_resource(klass, attrs)
+            resource = klass.new(attrs)
+            resource.stores = [current_store] if resource.stores.empty?
+            resource
+          end
+        end
+      end
+    end
+  end
+end