spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -12,7 +12,7 @@ module Spree
           # unconditional presigner would let anyone holding one mint blobs in
           # the merchant's bucket. Reaching this action means holding the cart.
           #
-          # Blobs are minted on private storage, because attaching a signed id
+          # Files are minted on private storage, because attaching a signed id
           # never moves a blob between services and a purchase order carries the
           # buyer's prices, terms and internal cost codes.
           class PoDocumentsController < Store::BaseController
@@ -21,10 +21,20 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'CreatePoDocumentParams', action: :create do |body|
+              body.attribute :filename, :string, required: true
+              body.attribute :content_type, :string, required: true
+              body.attribute :byte_size, :integer, required: true
+              body.attribute :checksum, :string,
+                required: true,
+                description: 'Base64-encoded MD5 digest of the file; the storage service checks the bytes against it.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/po_document
             #
-            # Exchanges blob metadata for an upload URL. The returned signed id
-            # is then sent back as `po_document` on a cart update, which is what
+            # Takes the same flat request as the Admin API's `POST /files` and
+            # answers with the same shape. The returned signed id is then sent
+            # back as `po_document_signed_id` on a cart update, which is what
             # actually attaches it.
             #
             # The declared size and type are checked here, before any URL is
@@ -34,20 +44,20 @@ module Spree
             # only runs once the bytes are already stored. It is a gate on the
             # cheap lie, not a substitute: the attach-time check still reads
             # the stored object, which is what catches an under-declared size.
+            # Bytes in the request itself are not accepted here: a publishable
+            # key is public.
             def create
-              return render_po_document_invalid unless acceptable_upload?
-
-              blob = ActiveStorage::Blob.create_before_direct_upload!(
-                service_name: Spree.private_storage_service_name, **blob_params
+              file_upload = Spree::FileUpload.new(
+                store: current_store,
+                visibility: 'private',
+                max_byte_size: Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE,
+                allowed_content_types: Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES,
+                **params.permit(*declared_permitted_attributes).to_h.symbolize_keys
               )
 
-              render json: {
-                direct_upload: {
-                  url: blob.service_url_for_direct_upload,
-                  headers: blob.service_headers_for_direct_upload
-                },
-                signed_id: blob.signed_id
-              }, status: :created
+              return render_po_document_invalid unless file_upload.save
+
+              render json: Spree.api.file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :created
             end
 
             # GET /api/v3/store/carts/:cart_id/po_document
@@ -79,23 +89,11 @@ module Spree
 
             private
 
-            def blob_params
-              params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
-            end
-
-            def acceptable_upload?
-              declared_size = Integer(blob_params[:byte_size].to_s, exception: false)
-
-              declared_size&.positive? &&
-                declared_size <= Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE &&
-                Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES.include?(blob_params[:content_type])
-            end
-
             def render_po_document_invalid
               render_error(
                 code: ERROR_CODES[:parameter_invalid],
-                message: Spree.t(
-                  :po_document_invalid,
+                message: I18n.t(
+                  'spree.po_document_invalid',
                   size: ActiveSupport::NumberHelper.number_to_human_size(
                     Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE
                   )

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

@@ -10,15 +10,22 @@ module Spree
             before_action :require_authentication!
             before_action :find_cart!
 
+            request_params 'ApplyStoreCreditParams', action: :create do |body|
+              body.attribute :amount, :decimal,
+                example: '10.00',
+                description: 'Defaults to as much as the cart can use.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/store_credits
             def create
               with_order_lock do
                 result = Spree.store_credit_apply_service.call(
                   order: @cart,
-                  amount: params[:amount].try(:to_f)
+                  amount: money_param(:amount, @cart.currency)
                 )
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart
                 else
                   render_service_error(result.error)
@@ -32,6 +39,7 @@ module Spree
                 result = Spree.store_credit_remove_service.call(order: @cart)
 
                 if result.success?
+                  sweep_unavailable_coupon_code!
                   render_cart
                 else
                   render_service_error(result.error)

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

@@ -25,6 +25,10 @@ module Spree
             # frozen onto the order at completion.
             before_action :require_kind_and_value!, only: :update
 
+            request_params('TaxIdentifierParams', action: :update) do |body|
+              body.include_attributes Spree::Api::V3::TaxIdentifierRequestSchema
+            end
+
             # GET /api/v3/store/carts/:cart_id/tax_identifier
             #
             # The registration this cart will be taxed against — the override
@@ -73,7 +77,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:kind, :value)
+              params.permit(*declared_permitted_attributes)
             end
 
             private

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

@@ -5,15 +5,66 @@ module Spree
         class CartsController < Store::ResourceController
           include Spree::Api::V3::CartResolvable
           include Spree::Api::V3::OrderLock
-          # The cart accepts a `po_document` signed blob id.
+          # The cart accepts a `po_document_signed_id`.
           include ActiveStorage::SetCurrent
 
-          # A tampered signed id would otherwise surface as a 500.
-          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document
-
           skip_before_action :set_resource
           prepend_before_action :require_authentication!, only: [:index, :associate]
 
+          CART_ADDRESS = Spree::Api::V3::RequestSchema.shape('CartAddressParams') do |schema|
+            schema.attribute :id, :id,
+              description: 'An existing address of the customer to use. The other fields are then ignored.'
+            schema.include_attributes Spree::Api::V3::Store::AddressRequestSchema
+            schema.attribute :quick_checkout, :boolean,
+              description: 'Relaxes validation (name, phone, postal code, street), for express checkouts that share a partial address.'
+          end
+
+          # Creating and updating a cart accept the same fields.
+          CART_FIELDS = Spree::Api::V3::RequestSchema.new do |schema|
+            schema.attribute :email, :string, format: :email, example: 'customer@example.com'
+            schema.attribute :customer_note, :string, example: 'Leave at door'
+            schema.attribute :market_id, :id
+            schema.attribute :currency, :currency
+            schema.attribute :locale, :locale
+            schema.attribute :shipping_address_id, :id,
+              description: 'An existing address to ship to.',
+              example: 'addr_abc123'
+            schema.attribute :billing_address_id, :id,
+              description: 'An existing address to bill.',
+              example: 'addr_def456'
+            schema.attribute :preferred_stock_location_id, :id
+            schema.attribute :company_id, :id, nullable: true, description: <<~TEXT.squish
+              The company node this purchase is for. The buyer must have standing over it: a membership
+              on that node or one of its ancestors. Null clears it, and with it the company's catalog,
+              pricing and tax anchoring.
+            TEXT
+            schema.attribute :po_number, :string, nullable: true, description: <<~TEXT.squish
+              The buyer's own purchase-order reference. Their accounting reconciles the order, the
+              invoice and the payment against it. Blank clears it.
+            TEXT
+            schema.attribute :po_document_signed_id, :string, nullable: true, description: <<~TEXT.squish
+              The `signed_id` of the buyer's purchase order, from `POST /store/carts/:id/po_document`.
+              Blank detaches the document.
+            TEXT
+            schema.attribute :use_shipping, :boolean,
+              description: 'When true, copies the shipping address to the billing address.'
+            schema.attribute :shipping_address, :object, shape: CART_ADDRESS, description: 'A new shipping address.'
+            schema.attribute :billing_address, :object, shape: CART_ADDRESS, description: 'A new billing address.'
+            schema.attribute :metadata, :hash,
+              description: 'Write-only key-value metadata, merged with what the cart has.'
+            schema.attribute :items, :array,
+              as: 'LineItemInputParams',
+              description: 'Items to upsert: sets the quantity of a variant already in the cart, adds the others.' do |item|
+              item.attribute :variant_id, :id, required: true, example: 'variant_abc123'
+              item.attribute :quantity, :integer, example: 2, description: 'Defaults to 1.'
+              item.attribute :metadata, :hash, description: 'Key-value metadata, merged with what the line item has.'
+              item.attribute :options, :hash
+            end
+          end
+
+          request_params('CreateCartParams', action: :create) { |body| body.include_attributes CART_FIELDS }
+          request_params('UpdateCartParams', action: :update) { |body| body.include_attributes CART_FIELDS }
+
           # GET /api/v3/store/carts/:id
           # Returns cart by prefixed ID
           # Auto-advances the checkout state machine so that shipments and
@@ -26,12 +77,13 @@ module Spree
             # with_order_lock, and a read must not 409 against the fence.
             if @cart.ship_address_id.present? && @cart.fulfillments.empty? && !@cart.completion_claimed?
               ActiveRecord::Base.connected_to(role: :writing) do
-                with_order_lock { Spree::Checkout::Advance.call(order: @cart) }
+                with_order_lock { Spree.checkout_advance_service.call(order: @cart) }
               end
             end
 
             # The customer is returning to a cart that may have sat for days.
             sweep_unbuyable_lines!
+            sweep_unavailable_coupon_code!
             render_cart
           end
 
@@ -39,9 +91,9 @@ module Spree
           # Creates a new shopping cart (order)
           # Can be created by guests or authenticated customers
           def create
-            result = Spree::Carts::Create.call(
+            result = Spree.carts_create_service.call(
               params: permitted_params.merge(
-                user: current_user,
+                customer: current_user,
                 store: current_store,
                 channel: current_channel,
                 currency: current_currency,
@@ -64,12 +116,13 @@ module Spree
             find_cart!
 
             with_order_lock do
-              result = Spree::Carts::Update.call(
+              result = Spree.carts_update_service.call(
                 cart: @cart,
                 params: permitted_params
               )
 
               if result.success?
+                sweep_unavailable_coupon_code!
                 render_cart
               else
                 render_service_error(result.error, code: ERROR_CODES[:validation_error])
@@ -107,6 +160,7 @@ module Spree
             if result.success?
               # Signing in hands back a cart built earlier, possibly long ago.
               sweep_unbuyable_lines!
+              sweep_unavailable_coupon_code!
               render_cart
             else
               render_service_error(result.error.to_s)
@@ -121,7 +175,7 @@ module Spree
             find_cart!(include_completed: true)
 
             if @cart.guest_checkout_disallowed?
-              return render_authentication_required('api.errors.guest_checkout_not_allowed', 'You must be signed in to complete checkout')
+              return render_authentication_required(I18n.t('spree.api.errors.guest_checkout_not_allowed'))
             end
 
             result = Spree::Dependencies.carts_complete_workflow.constantize.call(cart: @cart)
@@ -181,50 +235,8 @@ 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 permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :email,
-              :customer_note,
-              :market_id,
-              :currency,
-              :locale,
-              :shipping_address_id,
-              :billing_address_id,
-              :preferred_stock_location_id,
-              :company_id,
-              # The buyer's own purchase-order reference, and the signed blob id
-              # of the document behind it (from POST .../carts/:id/po_document).
-              :po_number,
-              :po_document,
-              :use_shipping,
-              shipping_address: address_params,
-              billing_address: address_params,
-              metadata: {},
-              items: item_params
-            )
-          end
-
-          def address_params
-            [
-              :id, :first_name, :last_name,
-              :address1, :address2,
-              :city, :postal_code, :phone, :company,
-              # country_iso and state_abbr are the legacy write names, accepted until 6.1.
-              :country_code, :country_iso, :state_code, :state_abbr, :state_name, :quick_checkout
-            ]
-          end
-
-          def item_params
-            [:variant_id, :quantity, { metadata: {}, options: {} }]
+            params.permit(*permitted_attributes)
           end
 
           # Find incomplete cart for associate action.

data/app/controllers/spree/api/v3/store/companies/addresses_controller.rb

@@ -9,6 +9,18 @@ module Spree
           class AddressesController < BaseController
             include Spree::Api::V3::CompanyAddressWrites
 
+            request_params :company_address do |body|
+              body.include_attributes Spree::Api::V3::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :zipcode, :string, deprecated: 'Use `postal_code`. Removed in 6.1.'
+              body.attribute :default_billing, :boolean,
+                permit: false,
+                description: "True makes this the node's default billing address, false gives that up, and leaving it out changes nothing."
+              body.attribute :default_shipping, :boolean,
+                permit: false,
+                description: "True makes this the node's default shipping address, false gives that up, and leaving it out changes nothing."
+            end
+
             # POST /api/v3/store/companies/:company_id/addresses
             def create
               result = Spree.address_create_service.call(
@@ -65,14 +77,6 @@ module Spree
             def scope
               action_name == 'index' ? @parent.address_book : @parent.addresses
             end
-
-            def parent_association
-              :addresses
-            end
-
-            def permitted_params
-              params.permit(:label, *Spree::Api::V3::AddressParams::ADDRESS_KEYS)
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/store/companies/invitations_controller.rb

@@ -15,7 +15,7 @@ module Spree
               else
                 render_error(
                   code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                  message: Spree.t('company_invitations.not_pending'),
+                  message: I18n.t('spree.company_invitations.not_pending'),
                   status: :unprocessable_content
                 )
               end
@@ -38,10 +38,6 @@ module Spree
             def scope
               action_name == 'index' ? @parent.invitations.pending : @parent.invitations
             end
-
-            def parent_association
-              :invitations
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/store/companies/members_controller.rb

@@ -11,6 +11,10 @@ module Spree
           # email has an account. Any member can invite; restraint is
           # Enterprise's policy layer.
           class MembersController < BaseController
+            request_params 'AddCompanyMemberParams', action: :create do |body|
+              body.attribute :customer_email, :string, required: true, example: 'colleague@acme.test'
+            end
+
             # POST /api/v3/store/companies/:company_id/members
             def create
               result = Spree.company_add_member_service.call(

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

@@ -10,6 +10,10 @@ module Spree
         class CompaniesController < ResourceController
           prepend_before_action :require_authentication!
 
+          request_params 'UpdateCompanyParams', action: :update do |body|
+            body.attribute :name, :string, example: 'Acme Industrial Group'
+          end
+
           # PATCH /api/v3/store/companies/:id
           def update
             authorize_storefront_write!(@resource)
@@ -38,7 +42,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:name)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

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

@@ -17,6 +17,14 @@ module Spree
           # standing scope would 404 the unauthenticated invitee.
           skip_before_action :set_resource
 
+          request_params 'AcceptCompanyInvitationParams', action: :accept do |body|
+            body.attribute :first_name, :string, example: 'Ada'
+            body.attribute :last_name, :string, example: 'Lovelace'
+            body.attribute :phone, :string
+            body.attribute :password, :string, example: 'a-strong-password'
+            body.attribute :password_confirmation, :string, example: 'a-strong-password'
+          end
+
           # GET /api/v3/store/company_invitations/:token — what is being
           # joined. Expired and revoked tokens 404.
           def show
@@ -52,7 +60,7 @@ module Spree
             else
               render_error(
                 code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                message: Spree.t('company_invitations.not_pending'),
+                message: I18n.t('spree.company_invitations.not_pending'),
                 status: :unprocessable_content
               )
             end
@@ -81,7 +89,7 @@ module Spree
           end
 
           def registration_params
-            params.permit(:first_name, :last_name, :phone, :password, :password_confirmation)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/store/customer/addresses_controller.rb

@@ -7,6 +7,13 @@ module Spree
             prepend_before_action :require_authentication!
             before_action :set_resource, only: [:show, :update, :destroy]
 
+            request_params :address do |body|
+              body.include_attributes Spree::Api::V3::Store::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :is_default_billing, :boolean, description: 'Makes this the default billing address.'
+              body.attribute :is_default_shipping, :boolean, description: 'Makes this the default shipping address.'
+            end
+
             # POST /api/v3/store/customers/me/addresses
             def create
               result = Spree.address_create_service.call(
@@ -49,10 +56,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :addresses
-            end
-
             def model_class
               Spree::Address
             end
@@ -62,13 +65,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                *model_additional_permitted_attributes,
-                :first_name, :last_name, :address1, :address2, :city,
-                # country_iso and state_abbr are the legacy write names, accepted until 6.1.
-                :postal_code, :phone, :company, :country_code, :country_iso, :state_code, :state_abbr, :state_name,
-                :is_default_billing, :is_default_shipping
-              )
+              params.permit(*permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/customer/credit_cards_controller.rb

@@ -12,10 +12,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :credit_cards
-            end
-
             # Customers are global; a saved card belongs to the store-scoped
             # payment method it was created against, so the nested collection is
             # bound to the current store's payment methods.

data/app/controllers/spree/api/v3/store/customer/data_requests_controller.rb

@@ -15,6 +15,11 @@ module Spree
 
             prepend_before_action :require_authentication!
 
+            request_params 'CreateDataRequestParams', action: :create do |body|
+              body.attribute :kind, :string, choices: Spree::DataRequest::KINDS, description: 'Defaults to `access`.'
+              body.attribute :current_password, :string, description: 'Required for `erasure`.'
+            end
+
             # POST /api/v3/store/customers/me/data_requests
             def create
               return render_current_password_invalid if erasure? && !valid_current_password?
@@ -46,10 +51,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :data_requests
-            end
-
             # A person sees their own requests and no one else's. The store
             # narrowing is restated because the parent branch of the base scope
             # replaces `for_store` with the association, and a customer is
@@ -69,7 +70,6 @@ module Spree
             def erasure?
               params[:kind].to_s == Spree::DataRequest::ERASURE
             end
-
           end
         end
       end

data/app/controllers/spree/api/v3/store/customer/digital_links_controller.rb

@@ -23,10 +23,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :digital_links
-            end
-
             # The `digital_links` association reaches links through orders and
             # line items, so it carries a DISTINCT and inherits an ORDER BY on
             # the line items' table. PostgreSQL rejects DISTINCT combined with

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

@@ -12,10 +12,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :gift_cards
-            end
-
             def model_class
               Spree::GiftCard
             end

data/app/controllers/spree/api/v3/store/customer/orders_controller.rb

@@ -20,10 +20,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :orders
-            end
-
             def scope
               super.for_store(current_store).complete
             end

data/app/controllers/spree/api/v3/store/customer/password_resets_controller.rb

@@ -14,6 +14,23 @@ module Spree
 
             skip_before_action :authenticate_user
 
+            request_params 'RequestPasswordResetParams', action: :create do |body|
+              body.attribute :email, :string,
+                required: true,
+                format: :email,
+                example: 'customer@example.com',
+                description: 'The email of the account to reset.'
+              body.attribute :redirect_url, :string,
+                format: :uri,
+                example: 'https://myshop.com/reset-password',
+                description: "Where the reset link sends the customer. Ignored unless it matches one of the store's allowed origins."
+            end
+
+            request_params 'ResetPasswordParams', action: :update do |body|
+              body.attribute :password, :string, required: true, example: 'newsecurepassword'
+              body.attribute :password_confirmation, :string, required: true, example: 'newsecurepassword'
+            end
+
             # POST /api/v3/store/password_resets
             def create
               redirect_url = params[:redirect_url]
@@ -32,14 +49,16 @@ module Spree
               user = Spree.customer_class.find_by(email: params[:email])
 
               if 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('customer.password_reset_requested', event_payload)
+                event_name = 'customer.password_reset_requested'
+                payload = user.event_payload_for(
+                  event_name,
+                  reset_token: user.generate_token_for(:password_reset), store: current_store, redirect_url: redirect_url.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/store/password_resets/:id
@@ -49,7 +68,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

data/app/controllers/spree/api/v3/store/customer/payment_setup_sessions_controller.rb

@@ -9,6 +9,15 @@ module Spree
             skip_before_action :set_resource
             before_action :set_payment_setup_session, only: [:show, :complete]
 
+            request_params 'CreatePaymentSetupSessionParams', action: :create do |body|
+              body.attribute :payment_method_id, :id, required: true, example: 'pm_abc123'
+              body.attribute :external_data, :hash, description: 'Provider-specific data passed to the gateway.'
+            end
+
+            request_params 'CompletePaymentSetupSessionParams', action: :complete do |body|
+              body.attribute :external_data, :hash, description: 'Provider-specific completion data.'
+            end
+
             # POST /api/v3/store/customer/payment_setup_sessions
             def create
               payment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])
@@ -50,10 +59,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :payment_setup_sessions
-            end
-
             def model_class
               Spree::PaymentSetupSession
             end
@@ -62,12 +67,8 @@ module Spree
               Spree.api.payment_setup_session_serializer
             end
 
-            def resource_permitted_attributes
-              [:payment_method_id, { external_data: {} }]
-            end
-
             def complete_params
-              params.permit({ external_data: {} })
+              params.permit(*declared_permitted_attributes)
             end
 
             private