spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -6,9 +6,13 @@ module Spree
           class GiftCardsController < BaseController
             skip_before_action :set_resource, raise: false
 
+            request_params 'GiftCardApplyParams' do |body|
+              body.attribute :code, :string,
+                required: true,
+                description: 'The gift card code; matched case-insensitively.'
+            end
+
             # POST /api/v3/admin/orders/:order_id/gift_cards
-            #
-            # Body: { code: String }
             def create
               with_order_lock do
                 gift_card = find_gift_card!
@@ -53,17 +57,17 @@ module Spree
               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)
+                render_error(code: ERROR_CODES[:gift_card_not_found], message: I18n.t('spree.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)
+                render_error(code: ERROR_CODES[:gift_card_expired], message: I18n.t('spree.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)
+                render_error(code: ERROR_CODES[:gift_card_already_redeemed], message: I18n.t('spree.gift_card_already_redeemed'), status: :unprocessable_content)
                 return
               end
 

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

@@ -4,6 +4,16 @@ module Spree
       module Admin
         module Orders
           class ItemsController < BaseController
+            request_params :line_item do |body|
+              body.attribute :variant_id, :id, required: true, only: :create
+              body.attribute :quantity, :integer, example: 1, description: 'Defaults to 1 when adding an item.'
+              body.attribute :price, :decimal,
+                nullable: true,
+                description: "Negotiated unit price. Stamps the line `price_source: 'manual'`, so quantity changes and recalculation never re-price it; an explicit null reverts the line to catalog pricing. Omit to leave pricing alone. Draft (incomplete) orders only."
+              body.attribute :options, :hash, only: :create
+              body.attribute :metadata, :hash, only: :update
+            end
+
             # POST /api/v3/admin/orders/:order_id/items
             def create
               with_order_lock do
@@ -69,7 +79,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:variant_id, :quantity, :price, metadata: {}, options: {})
+              params.permit(*permitted_attributes)
             end
 
             private

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

@@ -11,25 +11,44 @@ module Spree
           class LabelsController < BaseController
             include Spree::Api::V3::Orders::ShippingLabelActions
 
+            # The permit list itself lives in ShippingLabelActions, shared with
+            # the seller branch; this declaration documents it.
+            request_params :shipping_label do |body|
+              body.attribute :file_signed_id, :string,
+                description: 'A `signed_id` from `files.upload()`. Its presence records a label bought elsewhere instead of buying one; without it the body is ignored and the label is bought through the carrier.'
+              body.attribute :tracking_number, :string,
+                description: 'The number printed on an uploaded label. Required with `file_signed_id`.'
+              body.attribute :carrier, :string,
+                description: "Free text; a forwarder's name is as valid as a carrier slug. Detected from the number when omitted."
+              body.attribute :service, :string, description: 'Carrier service the label was bought at.'
+              body.attribute :cost, :decimal,
+                description: "What the merchant paid the carrier. Accounting data only; it never touches the order's shipping charge."
+              body.attribute :currency, :currency, description: 'Currency of the cost.'
+              body.attribute :file_format, :string,
+                choices: %w[pdf png zpl],
+                description: 'Taken from the file when omitted.'
+              body.attribute :tracking_url, :string, description: 'Tracking page for the consignment the label mints.'
+            end
+
             before_action :set_resource, only: [:show, :download, :refund, :destroy]
 
             # POST .../labels
             #
-            # Buys the label through the parcel's provider, or — when a `file`
+            # Buys the label through the parcel's provider, or — when a `file_signed_id`
             # is given — records one the merchant bought elsewhere.
             def create
               authorize!(:create, Spree::ShippingLabel)
 
-              return record_uploaded_label if label_params[:file].present?
+              return record_uploaded_label if label_params[:file_signed_id].present?
+              # Buying is the default only when no file is sent at all. A file
+              # under its old name would otherwise fall through to buying a
+              # label on the carrier account.
+              return render_misnamed_label_file if params.key?(:file)
 
               with_order_lock do
                 result = Spree.shipping_label_purchase_workflow.call(owner: @parent)
 
-                if result.success?
-                  render json: serialize_resource(result.value), status: :created
-                else
-                  render_result_error(result)
-                end
+                render_result(result, status: :created)
               end
             end
 
@@ -38,11 +57,7 @@ module Spree
               with_order_lock do
                 result = Spree.shipping_label_refund_workflow.call(shipping_label: @resource)
 
-                if result.success?
-                  render json: serialize_resource(result.value)
-                else
-                  render_result_error(result)
-                end
+                render_result(result)
               end
             end
 
@@ -67,6 +82,16 @@ module Spree
                           @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
                         end
             end
+
+            private
+
+            def render_misnamed_label_file
+              render_error(
+                code: ERROR_CODES[:parameter_invalid],
+                message: I18n.t('spree.shipping_labels.errors.file_renamed'),
+                status: :unprocessable_content
+              )
+            end
           end
         end
       end

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

@@ -6,6 +6,18 @@ module Spree
           class PaymentsController < BaseController
             scoped_resource :payments
 
+            request_params :payment do |body|
+              body.attribute :payment_method_id, :id, required: true, on: :create
+              body.attribute :amount, :decimal, description: "Defaults to the order total left after store credit."
+              body.attribute :source_id, :id,
+                description: "A saved payment source of the order's customer (a credit card), for an off-session charge. Used only by payment methods that require a source."
+            end
+
+            request_params 'PaymentCaptureParams', action: :capture do |body|
+              body.attribute :amount, :decimal,
+                description: 'Captures part of the authorized amount. Defaults to all of it.'
+            end
+
             before_action :set_resource, only: [:show, :capture, :void]
 
             # POST /api/v3/admin/orders/:order_id/payments
@@ -52,26 +64,21 @@ module Spree
             # to prevent. Both flows are idempotent on replay — an
             # already-captured or already-void payment returns success.
             def capture
-              amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
+              amount = money_param(:amount, @resource.currency)
+              unless amount.nil? || amount.positive?
+                raise Spree::Money::InvalidFormat.new('must be greater than 0', field: :amount)
+              end
 
               result = Spree.payment_capture_workflow.call(payment: @resource, amount: amount)
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
 
             # PATCH /api/v3/admin/orders/:order_id/payments/:id/void
             def void
               result = Spree.payment_void_workflow.call(payment: @resource)
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
 
             protected
@@ -84,14 +91,6 @@ module Spree
               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.

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

@@ -6,6 +6,12 @@ module Spree
           class RefundsController < BaseController
             scoped_resource :refunds
 
+            request_params :refund do |body|
+              body.attribute :payment_id, :id, required: true, on: :create
+              body.attribute :amount, :decimal, required: true, on: :create
+              body.attribute :refund_reason_id, :id, description: "Defaults to the store's first refund reason."
+            end
+
             # POST /api/v3/admin/orders/:order_id/refunds
             #
             # Deliberately not wrapped in with_order_lock: the workflow calls
@@ -33,11 +39,7 @@ module Spree
                 order: @parent
               )
 
-              if result.success?
-                render json: serialize_resource(result.value), status: :created
-              else
-                render_result_error(result)
-              end
+              render_result(result, status: :created)
             end
 
             protected

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

@@ -19,6 +19,42 @@ module Spree
             # would be wrongly denied.
             scoped_resource :orders
 
+            request_params :return do |body|
+              body.attribute :items, :array,
+                required: true, on: :create,
+                only: :create,
+                description: 'Fulfilled units coming back, and how many of each.' do |item|
+                item.attribute :fulfillment_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :stock_location_id, :id,
+                description: 'Where the goods come back to. Defaults to the location that shipped them.'
+              body.attribute :reason_id, :id, description: "One of the store's return reasons."
+              body.attribute :memo, :string
+              body.attribute :metadata, :hash, only: :update
+            end
+
+            request_params 'ReturnReceiveParams', action: :receive do |body|
+              body.attribute :items, :array,
+                description: 'What actually arrived. Omit to receive everything as requested and resellable; send rows for a partial or damaged receipt.' do |item|
+                item.attribute :return_line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :resellable, :boolean,
+                  description: 'Goods that cannot be resold are received but never restocked. Defaults to true.'
+              end
+            end
+
+            request_params 'ReturnRefundParams', action: :refund do |body|
+              body.attribute :amount, :decimal, description: 'Defaults to the value of what was actually received.'
+              body.attribute :refund_method, :string,
+                choices: Spree::RefundMethods::METHODS,
+                description: '`store_credit` issues credit immediately; `original_payment` (the default) refunds through the gateway that took the money.'
+            end
+
+            request_params 'ReturnCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the return was canceled.'
+            end
+
             before_action :set_resource, only: [:show, :update, :approve, :receive, :refund, :cancel]
 
             # PATCH /api/v3/admin/orders/:order_id/returns/:id
@@ -50,7 +86,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+              params.permit(*permitted_attributes)
             end
 
             private

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

@@ -6,17 +6,20 @@ module Spree
           class StoreCreditsController < BaseController
             skip_before_action :set_resource, raise: false
 
+            request_params 'StoreCreditApplyParams' do |body|
+              body.attribute :amount, :decimal,
+                description: "Defaults to the customer's available store credit, up to the order total."
+            end
+
             # 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.store_credit_apply_service.call(
                   order: @parent,
-                  amount: params[:amount].try(:to_f)
+                  amount: money_param(:amount, @parent.currency)
                 )
 
                 if result.success?

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

@@ -7,11 +7,78 @@ module Spree
 
           scoped_resource :orders
 
-          # The order accepts a `po_document` signed blob id and streams it back.
+          # The order accepts a `po_document_signed_id` and streams it back.
           include ActiveStorage::SetCurrent
 
-          # A tampered signed id would otherwise surface as a 500.
-          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document
+          ADDRESS = Spree::Api::V3::RequestSchema.shape('AddressInputParams') do |schema|
+            schema.include_attributes Spree::Api::V3::Admin::AddressRequestSchema
+          end
+
+          request_params :order do |body|
+            body.external_references
+            body.attribute :email, :string, example: 'customer@example.com'
+            body.attribute :customer_id, :id
+            body.attribute :use_customer_default_address, :boolean,
+              only: :create,
+              description: "With `customer_id`, copies the customer's saved billing and shipping addresses onto the order."
+            body.attribute :currency, :currency, example: 'USD'
+            body.attribute :market_id, :id
+            body.attribute :channel_id, :id, description: 'Defaults to the store primary channel when omitted.'
+            body.attribute :locale, :locale, example: 'en-US'
+            body.attribute :customer_note, :string, description: 'Public, customer-visible note.'
+            body.attribute :internal_note, :string,
+              description: 'Staff-only note. Rich text HTML; reads come back as this plus `internal_note_html`.'
+            body.attribute :po_number, :string,
+              description: "The buyer's own purchase-order reference. Searchable alongside the order number, and rendered on every order-facing document."
+            body.attribute :po_document_signed_id, :string,
+              nullable: true,
+              description: "The `signed_id` of the buyer's purchase order, from `files.upload()` with `visibility: 'private'`. Null removes the document the order carries."
+            body.attribute :shipping_address_id, :id,
+              only: :create,
+              description: 'An existing address of the customer.'
+            body.attribute :billing_address_id, :id,
+              only: :create,
+              description: 'An existing address of the customer.'
+            body.attribute :preferred_stock_location_id, :id,
+              description: "Stock location to prefer for fulfillment. Order Routing's built-in preferred-location rule ranks it first; routing falls back to the next rule when the location can't cover the cart."
+            body.attribute :company_id, :id,
+              nullable: true,
+              description: "Makes the order a company purchase, with that company's catalog prices and tax treatment. Null makes a draft a plain customer order again."
+            body.attribute :coupon_code, :string,
+              only: :create,
+              description: 'Applied non-fatally: an invalid code does not block creation.'
+            body.attribute :metadata, :hash
+            body.attribute :tags, :array, of: :string
+            body.attribute :shipping_address, :object, shape: ADDRESS
+            body.attribute :billing_address, :object, shape: ADDRESS
+            body.attribute :items, :array,
+              description: 'Line items to upsert, keyed by variant. An entry sets that variant\'s quantity, creating the line item when the order has none; `quantity: 0` removes it. Variants you do not send are left alone.' do |item|
+              item.attribute :variant_id, :id, required: true
+              item.attribute :quantity, :integer, example: 1
+              item.attribute :price, :decimal,
+                nullable: true,
+                description: "Negotiated unit price; stamps `price_source: 'manual'`. Null reverts the line to catalog pricing. Draft orders only."
+              item.attribute :metadata, :hash
+            end
+          end
+
+          request_params 'OrderCompleteParams', action: :complete do |body|
+            body.attribute :payment_pending, :boolean
+            body.attribute :notify_customer, :boolean,
+              description: 'Send the order confirmation email after completion.'
+          end
+
+          request_params 'OrderCancelParams', action: :cancel do |body|
+            body.attribute :cancel_reason_id, :id,
+              description: "Why the order was canceled: the id of one of the store's cancellation reasons."
+            body.attribute :cancel_note, :string, description: 'Staff-facing note about the cancellation.'
+            body.attribute :refund_payments, :boolean,
+              description: "Whether this order's share of a payment shared across a split checkout is handed back."
+            body.attribute :refund_amount, :decimal,
+              description: 'How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared.'
+            body.attribute :notify_customer, :boolean,
+              description: 'Send the order cancellation email after canceling.'
+          end
 
           skip_before_action :set_resource, only: [:index, :create]
           before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resend_confirmation, :resend_digital_links, :po_document]
@@ -58,7 +125,7 @@ module Spree
           # are nested inside it.
           def complete
             with_order_lock do
-              result = Spree.order_complete_service.call(
+              result = Spree.order_complete_workflow.call(
                 order: @resource,
                 payment_pending: params[:payment_pending].to_b,
                 notify_customer: ActiveModel::Type::Boolean.new.cast(params[:notify_customer])
@@ -121,7 +188,7 @@ module Spree
             unless @resource.po_document.attached?
               return render_error(
                 code: ERROR_CODES[:validation_error],
-                message: Spree.t(:po_document_missing),
+                message: I18n.t('spree.po_document_missing'),
                 status: :unprocessable_content
               )
             end
@@ -244,14 +311,6 @@ module Spree
 
           private
 
-          def render_invalid_po_document
-            render_error(
-              code: ERROR_CODES[:validation_error],
-              message: Spree.t(:po_document_invalid_signed_id),
-              status: :unprocessable_content
-            )
-          end
-
           def resolve_customer
             customer_param = params[:customer_id].presence
             return unless customer_param
@@ -271,44 +330,13 @@ module Spree
           end
 
           def order_create_params
-            permitted = normalize_params(
-              params.permit(
-                :email, :customer_id, :use_customer_default_address,
-                :currency, :market_id, :channel_id, :locale,
-                :customer_note, :internal_note,
-                # The buyer's own purchase-order reference, and the signed blob
-                # id of the document behind it — a PO arriving by email and
-                # keyed in is the draft-order flow plus these two fields.
-                :po_number, :po_document,
-                :shipping_address_id, :billing_address_id,
-                :preferred_stock_location_id, :company_id,
-                :coupon_code,
-                metadata: {},
-                tags: [],
-                shipping_address: address_permitted_keys,
-                billing_address: address_permitted_keys,
-                items: item_permitted_keys
-              )
-            )
-            resolve_company_param(permitted)
+            resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:create))))
           end
 
+          # Named rather than read from the action, since an upsert reaches
+          # update from the create action.
           def order_update_params
-            permitted = normalize_params(
-              params.permit(
-                :email, :customer_id,
-                :customer_note, :internal_note,
-                :po_number, :po_document,
-                :currency, :locale, :market_id, :channel_id,
-                :preferred_stock_location_id, :company_id,
-                metadata: {},
-                tags: [],
-                shipping_address: address_permitted_keys,
-                billing_address: address_permitted_keys,
-                items: item_permitted_keys
-              )
-            )
-            resolve_company_param(permitted)
+            resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:update))))
           end
 
           # An incidental lookup like any other: resolved through the store so
@@ -326,20 +354,6 @@ module Spree
               end
             permitted
           end
-
-          def address_permitted_keys
-            [
-              :firstname, :lastname, :first_name, :last_name,
-              :address1, :address2, :city,
-              :country_code, :state_code,
-              :zipcode, :postal_code, :phone, :alternative_phone,
-              :state_name, :company, :label
-            ]
-          end
-
-          def item_permitted_keys
-            [:variant_id, :quantity, :price, { metadata: {} }]
-          end
         end
       end
     end

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

@@ -14,6 +14,36 @@ module Spree
         class PackageTypesController < ResourceController
           scoped_resource :package_types
 
+          request_params :package_type do |body|
+            body.attribute :name, :string,
+              required: true, on: :create,
+              example: 'Euro pallet',
+              description: 'Unique within the store.'
+            body.attribute :kind, :string,
+              required: true, on: :create,
+              choices: Spree::PackageType::KINDS,
+              example: 'pallet',
+              description: 'What this packaging is: the box parcels ship in, or the carton, pallet or container a wholesale order leaves on.'
+            body.attribute :length, :number, nullable: true
+            body.attribute :width, :number, nullable: true
+            body.attribute :height, :number, nullable: true
+            body.attribute :dimensions_unit, :string,
+              nullable: true,
+              choices: Spree::Variant::DIMENSION_UNITS,
+              example: 'cm',
+              description: "Unit the three dimensions are in; falls back to the store's unit system."
+            body.attribute :weight, :number,
+              nullable: true,
+              description: "The empty package's own weight, added to content weight on every quote."
+            body.attribute :max_weight, :number,
+              nullable: true,
+              description: 'What the package can hold, not the same as its own weight.'
+            body.attribute :weight_unit, :string, nullable: true, choices: Spree::Variant::WEIGHT_UNITS, example: 'kg'
+            body.attribute :default, :boolean,
+              description: 'The box every parcel quote is built on. Setting this demotes whichever row held it.'
+            body.attribute :metadata, :hash
+          end
+
           protected
 
           def model_class
@@ -27,11 +57,6 @@ module Spree
           def collection_includes
             [:seller]
           end
-
-          def resource_permitted_attributes
-            [:name, :kind, :length, :width, :height, :dimensions_unit,
-             :weight, :max_weight, :weight_unit, :default, { metadata: {} }]
-          end
         end
       end
     end

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

@@ -15,20 +15,39 @@ module Spree
 
           skip_before_action :authenticate_admin!
 
+          request_params 'PasswordResetRequestParams', action: :create do |body|
+            body.attribute :email, :string,
+              required: true,
+              permit: false,
+              format: :email,
+              example: 'admin@example.com'
+            body.attribute :redirect_url, :string,
+              permit: false,
+              example: 'https://admin.your-store.com/reset-password',
+              description: 'The page the emailed reset link points at, with the reset token appended. Honored only on the dashboard origin, for an account that is staff of the store; ignored otherwise.'
+          end
+
+          request_params 'PasswordResetParams', action: :update do |body|
+            body.attribute :password, :string, required: true, permit: false
+            body.attribute :password_confirmation, :string, required: true, permit: false
+          end
+
           # POST /api/v3/admin/password_resets
           def create
             user = Spree.admin_user_class.find_by(email: params[:email])
 
             if user
-              redirect_url = trusted_redirect_url(user)
-              token = user.generate_token_for(:password_reset)
-              event_payload = { reset_token: token, email: user.email, store_id: current_store.prefixed_id }
-              event_payload[:redirect_url] = redirect_url if redirect_url.present?
-              user.publish_event('admin_user.password_reset_requested', event_payload)
+              event_name = 'admin_user.password_reset_requested'
+              payload = user.event_payload_for(
+                event_name,
+                reset_token: user.generate_token_for(:password_reset), store: current_store,
+                redirect_url: trusted_redirect_url(user).presence
+              )
+              user.publish_event(event_name, payload)
             end
 
             # Always return 202 to prevent email enumeration
-            render json: { message: Spree.t(:password_reset_requested, scope: :api) }, status: :accepted
+            render json: { message: I18n.t('spree.api.password_reset_requested') }, status: :accepted
           end
 
           # PATCH /api/v3/admin/password_resets/:id
@@ -38,7 +57,7 @@ module Spree
             unless user
               return render_error(
                 code: ERROR_CODES[:password_reset_token_invalid],
-                message: Spree.t(:password_reset_token_invalid, scope: :api),
+                message: I18n.t('spree.api.password_reset_token_invalid'),
                 status: :unprocessable_content
               )
             end