spree_api 6.0.0.beta4 → 6.0.0.rc2

data/app/controllers/spree/api/v3/seller/profile_controller.rb

@@ -20,6 +20,38 @@ module Spree
 
           scoped_resource :seller_profile
 
+          # Enumerated rather than borrowing the legacy global list, which
+          # permits :id, :user_id and :deleted_at.
+          request_params 'ProfileUpdateParams' do |body|
+            body.attribute :name, :string, example: 'Acme Supplies'
+            body.attribute :contact_email, :string, nullable: true, format: :email
+            body.attribute :billing_email, :string, nullable: true, format: :email
+            body.attribute :about, :string,
+              nullable: true,
+              description: "Sanitized HTML: the seller's public description."
+            body.attribute :legal_name, :string,
+              nullable: true,
+              description: 'The business a commission invoice is made out to.'
+            body.attribute :registration_number, :string, nullable: true
+            body.attribute :logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :square_logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :cover_photo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :billing_address, :object, as: 'SellerAddressParams' do |billing_address|
+              billing_address.include_attributes Spree::Api::V3::AddressRequestSchema
+            end
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: "Answers to the custom fields this marketplace's onboarding asks for. A field nothing asked for is ignored rather than written."
+            body.attribute :accept_terms, :boolean,
+              permit: false,
+              description: "Stamps the moment the seller accepted the marketplace's terms. One-way: sending `false` does not unmake the stamp."
+          end
+
           def show
             render json: serialize_seller
           end
@@ -54,8 +86,6 @@ module Spree
             %w[show]
           end
 
-          # Enumerated rather than borrowing the legacy global list, which
-          # permits :id, :user_id and :deleted_at.
           # Accepting the marketplace's terms is a profile write, not an endpoint
           # of its own: `accept_terms: true` stamps the time, which is what the
           # AcceptTerms requirement reads.
@@ -104,14 +134,7 @@ module Spree
           end
 
           def permitted_params
-            normalize_params(
-              params.permit(:name, :contact_email, :billing_email, :about,
-                            :legal_name, :registration_number,
-                            :logo, :square_logo, :cover_photo,
-                            billing_address: Spree::Api::V3::AddressParams::ADDRESS_KEYS,
-                            custom_fields: [:id, :custom_field_definition_id, :value,
-                                            { value: [] }, { value: {} }])
-            )
+            normalize_params(params.permit(*declared_permitted_attributes))
           end
 
           private

data/app/controllers/spree/api/v3/seller/requirement_submissions_controller.rb

@@ -12,6 +12,16 @@ module Spree
         class RequirementSubmissionsController < Seller::BaseController
           scoped_resource :seller_profile
 
+          # `file_signed_id` comes from POST /files, so the bytes are already in
+          # storage by the time this runs.
+          request_params 'RequirementSubmissionParams' do |body|
+            body.attribute :note, :string, description: 'Anything the seller wants to say alongside the submission.'
+            body.attribute :reference, :string,
+              description: 'A reference number or external identifier, for requirements that ask for one.'
+            body.attribute :file_signed_id, :string,
+              description: 'A `signed_id` from `POST /files`, for requirements that ask for a document.'
+          end
+
           before_action :set_requirement, only: [:create]
           before_action :set_submission, only: [:download]
 
@@ -24,7 +34,7 @@ module Spree
               requirement: @requirement,
               note: attributes[:note],
               reference: attributes[:reference],
-              file: attributes[:file],
+              file: attributes[:file_signed_id],
               submitted_by: try_spree_current_user
             )
 
@@ -42,7 +52,7 @@ module Spree
             unless @submission.file.attached?
               return render_error(
                 code: ErrorHandler::ERROR_CODES[:validation_error],
-                message: Spree.t(:seller_submission_no_file),
+                message: I18n.t('spree.seller_submission_no_file'),
                 status: :unprocessable_content
               )
             end
@@ -57,11 +67,8 @@ module Spree
 
           protected
 
-          # What a seller may say about a requirement. `file` is a direct-upload
-          # signed id, so it is a string like the rest — the bytes are already
-          # in storage by the time this runs.
           def permitted_params
-            params.permit(:note, :reference, :file)
+            params.permit(*declared_permitted_attributes)
           end
 
           def read_actions

data/app/controllers/spree/api/v3/seller/resource_controller.rb

@@ -11,6 +11,7 @@ module Spree
           include Spree::Api::V3::Seller::SellerContext
           include Spree::Api::V3::SellerAuthentication
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
 
           protected
 
@@ -65,6 +66,17 @@ module Spree
             model_class.table_name.delete_prefix('spree_').to_sym
           end
 
+          # What extensions opened to sellers, never the operator-level list:
+          # an attribute opened to operators must not become seller-writable
+          # by accident.
+          def model_additional_permitted_attributes
+            return [] unless respond_to?(:model_class, true)
+
+            Array(model_class.try(:additional_seller_permitted_attributes))
+          rescue NotImplementedError
+            []
+          end
+
           def authorize_resource!(resource = @resource, action = action_name.to_sym)
             authorize!(action, resource)
           end

data/app/controllers/spree/api/v3/seller/stock_locations_controller.rb

@@ -24,6 +24,49 @@ module Spree
           # stock.
           scoped_resource :stock
 
+          # The same set the operator's controller permits: a seller runs
+          # their own warehouse, so every field on the shared form is theirs to
+          # set. Anything missing here is dropped by `permit` without a word,
+          # and the form would appear to save while quietly discarding it.
+          request_params :stock_location do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Main warehouse'
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :active, :boolean, description: 'Set `false` to retire a location: there is no delete.'
+            body.attribute :default, :boolean
+            body.attribute :kind, :string,
+              choices: Spree::StockLocation::KINDS,
+              open: true,
+              example: 'warehouse',
+              description: 'Categorizes the location.'
+            body.attribute :propagate_all_variants, :boolean
+            body.attribute :backorderable_default, :boolean
+            body.attribute :address1, :string, nullable: true
+            body.attribute :address2, :string, nullable: true
+            body.attribute :city, :string, nullable: true
+            body.attribute :zipcode, :string, nullable: true
+            body.attribute :phone, :string, nullable: true
+            body.attribute :company, :string, nullable: true
+            body.attribute :country_code, :country,
+              nullable: true,
+              example: 'US',
+              description: 'ISO-3166 alpha-2 country code.'
+            body.attribute :state_code, :string,
+              nullable: true,
+              example: 'OR',
+              description: "State or province abbreviation, resolved against the selected country's states."
+            body.attribute :state_name, :string,
+              nullable: true,
+              description: "Free-text state for countries that don't have a states list."
+            body.attribute :pickup_enabled, :boolean
+            body.attribute :pickup_stock_policy, :string,
+              choices: Spree::StockLocation::PICKUP_STOCK_POLICIES,
+              description: '`local` collects only items at this location; `any` lets items transfer in from other locations (ship-to-store).'
+            body.attribute :pickup_ready_in_minutes, :integer, nullable: true
+            body.attribute :returns_enabled, :boolean,
+              description: 'Whether customers may send returns to this location.'
+            body.attribute :pickup_instructions, :string, nullable: true
+          end
+
           protected
 
           def model_class
@@ -34,20 +77,8 @@ module Spree
             Spree.api.seller_stock_location_serializer
           end
 
-          # The same set the operator's controller permits: a seller runs
-          # their own warehouse, so every field on the shared form is theirs to
-          # set. Anything missing here is dropped by `permit` without a word,
-          # and the form would appear to save while quietly discarding it.
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :active, :default,
-              :kind, :propagate_all_variants, :backorderable_default,
-              :address1, :address2, :city, :zipcode, :phone, :company,
-              :country_code, :state_code, :state_name,
-              :pickup_enabled, :pickup_stock_policy, :returns_enabled,
-              :pickup_ready_in_minutes, :pickup_instructions
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/seller/tax_identifiers_controller.rb

@@ -24,6 +24,15 @@ module Spree
           # standard actions have to be listed alongside the custom one.
           before_action :set_resource, only: [:show, :update, :destroy, :validate]
 
+          request_params :seller_tax_identifier do |body|
+            body.attribute :kind, :string, required: true, on: :create,
+              example: 'eu_vat',
+              description: "#{Spree::Api::V3::TaxIdentifierRequestSchema::KIND_DESCRIPTION} One registration per kind."
+            body.attribute :value, :string, required: true, on: :create,
+              example: 'DE100000008',
+              description: 'A number the validator for its kind refuses is rejected rather than stored.'
+          end
+
           protected
 
           def model_class
@@ -39,7 +48,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:kind, :value)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/seller/team_controller.rb

@@ -16,6 +16,10 @@ module Spree
 
           before_action :set_member, only: [:destroy]
 
+          request_params :team_member do |body|
+            body.attribute :email, :string, required: true, example: 'colleague@acme.test'
+          end
+
           def index
             render json: { data: members.map { |member| serialize_member(member) } }
           end
@@ -68,7 +72,7 @@ module Spree
 
             render_error(
               code: ErrorHandler::ERROR_CODES[:processing_error],
-              message: Spree.t(:seller_team_last_member),
+              message: I18n.t('spree.seller_team_last_member'),
               status: :unprocessable_content
             )
           end

data/app/controllers/spree/api/v3/store/auth_controller.rb

@@ -16,6 +16,16 @@ module Spree
 
           skip_before_action :authenticate_user, only: [:create, :refresh, :logout]
 
+          request_params 'RefreshTokenParams', action: :refresh do |body|
+            body.attribute :refresh_token, :string,
+              required: true,
+              description: 'The refresh token from the login response.'
+          end
+
+          request_params 'LogoutParams', action: :logout do |body|
+            body.attribute :refresh_token, :string, description: 'The refresh token to revoke.'
+          end
+
           # POST  /api/v3/store/auth/login
           # Supports multiple authentication providers via :provider param
           # Example:

data/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb

@@ -9,6 +9,13 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'ApplyDiscountCodeParams', action: :create do |body|
+              body.attribute :code, :string,
+                required: true,
+                example: 'SAVE10',
+                description: 'The promotion code to apply.'
+            end
+
             # POST  /api/v3/store/carts/:cart_id/discount_codes
             # Applies a discount code. A real-but-not-yet-eligible code is
             # accepted and persisted — recalculation activates the discount
@@ -64,12 +71,12 @@ module Spree
             def attach_pending_coupon_warning
               @cart.warnings |= [{
                 code: coupon_handler.status_code.to_s,
-                message: coupon_handler.error.presence || Spree.t(:coupon_code_not_eligible)
+                message: coupon_handler.error.presence || I18n.t('spree.coupon_code_not_eligible')
               }]
             end
 
             def permitted_params
-              params.permit(:code)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/fulfillments_controller.rb

@@ -9,13 +9,12 @@ module Spree
 
             before_action :find_cart!
 
-            # GET /api/v3/store/carts/:cart_id/fulfillments
-            def index
-              fulfillments = @cart.fulfillments.includes(delivery_rates: :delivery_method)
-              render json: {
-                data: fulfillments.map { |s| Spree.api.fulfillment_serializer.new(s, params: serializer_params).to_h },
-                meta: { count: fulfillments.size }
-              }
+            request_params 'UpdateFulfillmentParams', action: :update do |body|
+              body.attribute :selected_delivery_rate_id, :id,
+                example: 'dr_abc123',
+                description: 'The delivery rate to select.'
+              body.attribute :pickup_point_external_id, :string,
+                description: "For a pickup point delivery method: the provider's id of the point to collect from."
             end
 
             # PATCH /api/v3/store/carts/:cart_id/fulfillments/:id
@@ -36,6 +35,7 @@ module Spree
 
                 recalculate
 
+                sweep_unavailable_coupon_code!
                 render_cart
               end
             end
@@ -43,7 +43,7 @@ module Spree
             private
 
             def permitted_params
-              params.permit(:selected_delivery_rate_id, :pickup_point_external_id)
+              params.permit(*declared_permitted_attributes)
             end
 
             def recalculate
@@ -62,8 +62,8 @@ module Spree
               if provider.nil?
                 render_error(
                   code: ERROR_CODES[:validation_error],
-                  message: Spree.t('errors.messages.no_pickup_point_provider'),
-                  status: :unprocessable_entity
+                  message: I18n.t('spree.errors.messages.no_pickup_point_provider'),
+                  status: :unprocessable_content
                 )
                 return false
               end
@@ -72,7 +72,7 @@ module Spree
               if point.nil?
                 render_error(
                   code: ERROR_CODES[:record_not_found],
-                  message: Spree.t('errors.messages.pickup_point_not_found'),
+                  message: I18n.t('spree.errors.messages.pickup_point_not_found'),
                   status: :not_found
                 )
                 return false

data/app/controllers/spree/api/v3/store/carts/gift_cards_controller.rb

@@ -9,6 +9,13 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'ApplyGiftCardParams', action: :create do |body|
+              body.attribute :code, :string,
+                required: true,
+                example: 'GC-ABCD-1234',
+                description: 'The gift card code to apply.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/gift_cards
             def create
               with_order_lock do
@@ -18,6 +25,7 @@ module Spree
                 result = @cart.apply_gift_card(gift_card)
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart(status: :created)
                 else
                   render_service_error(result.error)
@@ -31,6 +39,7 @@ module Spree
                 result = @cart.remove_gift_card
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart
                 else
                   render_service_error(result.error)
@@ -44,17 +53,17 @@ module Spree
               gift_card = @cart.store.gift_cards.find_by(code: permitted_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
 
@@ -62,7 +71,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:code)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/items_controller.rb

@@ -9,6 +9,22 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'AddLineItemParams', action: :create do |body|
+              body.attribute :variant_id, :id, required: true, example: 'variant_abc123'
+              body.attribute :quantity, :integer, example: 2, description: 'Defaults to 1.'
+              body.attribute :metadata, :hash,
+                example: { gift_message: 'Happy Birthday!' },
+                description: 'Write-only key-value metadata.'
+              body.attribute :options, :hash, description: 'Values for line item attributes an extension adds.'
+            end
+
+            request_params 'UpdateLineItemParams', action: :update do |body|
+              body.attribute :quantity, :integer, example: 5, description: 'At least 1. Remove an item with DELETE.'
+              body.attribute :metadata, :hash,
+                example: { engraving: 'J.D.' },
+                description: 'Write-only key-value metadata, merged with what the line item has.'
+            end
+
             # POST  /api/v3/store/carts/:cart_id/items
             def create
               with_order_lock do
@@ -21,6 +37,7 @@ module Spree
                 )
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart(status: :created)
                 else
                   render_result_error(result)
@@ -41,7 +58,7 @@ module Spree
                   if permitted_params[:quantity].to_i < 1
                     return render_error(
                       code: ERROR_CODES[:invalid_quantity],
-                      message: Spree.t('cart_line_item.quantity_must_be_positive'),
+                      message: I18n.t('spree.cart_line_item.quantity_must_be_positive'),
                       status: :unprocessable_content
                     )
                   end
@@ -56,6 +73,7 @@ module Spree
                   )
 
                   if result.success?
+                    sweep_unavailable_coupon_code!
                     render_cart
                   else
                     render_result_error(result)
@@ -67,6 +85,7 @@ module Spree
                     @line_item.update!(metadata: @line_item.metadata.merge(permitted_params[:metadata].to_h))
                   end
 
+                  sweep_unavailable_coupon_code!
                   render_cart
                 end
               end
@@ -83,6 +102,7 @@ module Spree
                 )
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart
                 else
                   render_result_error(result)
@@ -93,7 +113,7 @@ module Spree
             private
 
             def variant
-              @variant ||= current_store.variants.find_by_prefix_id!(permitted_params[:variant_id])
+              @variant ||= @cart.orderable_variants.find_by_prefix_id!(permitted_params[:variant_id])
             end
 
             # Extension attributes ride in `options`, which is how AddItem
@@ -109,11 +129,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                :id, :variant_id, :quantity,
-                *Spree::LineItem.additional_permitted_attributes,
-                { metadata: {}, options: {} }
-              )
+              params.permit(*declared_permitted_attributes, *Spree::LineItem.additional_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb

@@ -10,6 +10,24 @@ module Spree
             before_action :find_cart!
             before_action :set_payment_session, only: [:show, :update, :complete]
 
+            request_params 'CreatePaymentSessionParams', action: :create do |body|
+              body.attribute :payment_method_id, :id, required: true, example: 'pm_abc123'
+              body.attribute :amount, :decimal,
+                example: '99.99',
+                description: 'Defaults to the order total minus store credits.'
+              body.attribute :external_data, :hash, description: 'Provider-specific data passed to the gateway.'
+            end
+
+            request_params 'UpdatePaymentSessionParams', action: :update do |body|
+              body.attribute :amount, :decimal, example: '50.00'
+              body.attribute :external_data, :hash, description: 'Provider-specific data to update.'
+            end
+
+            request_params 'CompletePaymentSessionParams', action: :complete do |body|
+              body.attribute :session_result, :string, description: 'Provider-specific session result token.'
+              body.attribute :external_data, :hash, description: 'Provider-specific completion data.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/payment_sessions
             def create
               with_order_lock do
@@ -19,7 +37,7 @@ module Spree
                 unless payment_method.available_for_order?(@cart)
                   return render_error(
                     code: 'payment_method_unavailable',
-                    message: Spree.t('api.v3.payments.method_unavailable'),
+                    message: I18n.t('spree.api.v3.payments.method_unavailable'),
                     status: :unprocessable_content
                   )
                 end
@@ -94,15 +112,11 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                :amount, :payment_method_id,
-                *Spree::PaymentSession.additional_permitted_attributes,
-                { external_data: {} }
-              )
+              params.permit(*declared_permitted_attributes, *Spree::PaymentSession.additional_permitted_attributes)
             end
 
             def complete_params
-              params.permit(:session_result, { external_data: {} })
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/store/carts/payments_controller.rb

@@ -8,6 +8,17 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'CreatePaymentParams', action: :create do |body|
+              body.attribute :payment_method_id, :id,
+                required: true,
+                example: 'pm_abc123',
+                description: 'A payment method that needs no payment session.'
+              body.attribute :amount, :decimal,
+                example: '99.99',
+                description: 'Defaults to the order total minus store credits.'
+              body.attribute :metadata, :hash, description: 'Key-value metadata to attach to the payment.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/payments
             # Creates a payment for non-session payment methods (e.g. Check, Cash on Delivery, Bank Transfer)
             def create
@@ -20,15 +31,17 @@ module Spree
               if payment_method.session_required?
                 return render_error(
                   code: 'payment_session_required',
-                  message: Spree.t('api.v3.payments.session_required'),
+                  message: I18n.t('spree.api.v3.payments.session_required'),
                   status: :unprocessable_content
                 )
               end
 
-              unless payment_method.available_for_order?(@cart)
+              # Store credit passes the lookup above but has its own endpoint, so
+              # it is never among the methods the cart offers.
+              unless @cart.payment_methods.include?(payment_method)
                 return render_error(
                   code: 'payment_method_unavailable',
-                  message: Spree.t('api.v3.payments.method_unavailable'),
+                  message: I18n.t('spree.api.v3.payments.method_unavailable'),
                   status: :unprocessable_content
                 )
               end