spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -12,10 +12,6 @@ module Spree
               @parent = current_user
             end
 
-            def parent_association
-              :store_credits
-            end
-
             def scope
               super.for_store(current_store).where(currency: current_currency)
             end
@@ -27,7 +23,6 @@ module Spree
             def serializer_class
               Spree.api.store_credit_serializer
             end
-
           end
         end
       end

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

@@ -18,6 +18,10 @@ module Spree
             # the buyer never named and could not predict.
             before_action :require_kind!, only: %i[show update destroy]
 
+            request_params('TaxIdentifierParams', action: :update) do |body|
+              body.include_attributes Spree::Api::V3::TaxIdentifierRequestSchema
+            end
+
             # GET /api/v3/store/customers/me/tax_identifiers
             #
             # Everything the buyer could choose between at checkout. Small and
@@ -65,7 +69,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/customers_controller.rb

@@ -11,6 +11,33 @@ module Spree
           skip_before_action :authenticate_user, only: [:create]
           prepend_before_action :require_authentication!, only: [:show, :update]
 
+          CUSTOMER_FIELDS = Spree::Api::V3::RequestSchema.new do |schema|
+            schema.attribute :first_name, :string, example: 'John'
+            schema.attribute :last_name, :string, example: 'Doe'
+            schema.attribute :phone, :string, example: '+1 555 123 4567'
+            schema.attribute :accepts_email_marketing, :boolean
+            schema.attribute :metadata, :hash, description: 'Write-only key-value metadata.'
+          end
+
+          request_params 'RegisterParams', action: :create do |body|
+            body.attribute :email, :string, required: true, format: :email, example: 'newuser@example.com'
+            body.attribute :password, :string, required: true, example: 'password123'
+            body.attribute :password_confirmation, :string, example: 'password123'
+            body.include_attributes CUSTOMER_FIELDS
+            body.attribute :terms_of_service, :boolean,
+              permit: false,
+              description: "Whether the customer ticked the storefront's terms of service box. Recorded as their consent."
+          end
+
+          request_params 'UpdateCustomerParams', action: :update do |body|
+            body.attribute :email, :string, format: :email, example: 'customer@example.com'
+            body.attribute :password, :string
+            body.attribute :password_confirmation, :string
+            body.attribute :current_password, :string,
+              description: 'Required when changing the email or the password.'
+            body.include_attributes CUSTOMER_FIELDS
+          end
+
           # POST /api/v3/store/customers
           # Registration runs through the customer_create_workflow seam
           # (password requirement, newsletter-subscriber linking, registration
@@ -83,8 +110,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:email, :password, :password_confirmation, :first_name, :last_name,
-                          :accepts_email_marketing, :phone, :current_password, metadata: {})
+            params.permit(*declared_permitted_attributes)
           end
 
           private

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

@@ -30,7 +30,7 @@ module Spree
             unless data_request&.downloadable?
               return render_error(
                 code: 'data_request_expired',
-                message: Spree.t('data_request_errors.download_unavailable'),
+                message: I18n.t('spree.data_request_errors.download_unavailable'),
                 status: :forbidden
               )
             end

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

@@ -26,7 +26,7 @@ module Spree
           def pickup_points
             provider = find_resource.pickup_point_provider_instance
             if provider.nil?
-              return render_error(code: ERROR_CODES[:record_not_found], message: Spree.t('errors.messages.no_pickup_point_provider'), status: :not_found)
+              return render_error(code: ERROR_CODES[:record_not_found], message: I18n.t('spree.errors.messages.no_pickup_point_provider'), status: :not_found)
             end
 
             latitude = params[:latitude].presence&.to_f

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

@@ -10,6 +10,28 @@ module Spree
                      only: [:create, :verify, :request_unsubscribe],
                      with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_register]) }
 
+          request_params 'CreateNewsletterSubscriberParams', action: :create do |body|
+            body.attribute :email, :string, required: true, format: :email, example: 'subscriber@example.com'
+            body.attribute :redirect_url, :string,
+              format: :uri,
+              example: 'https://your-store.com/newsletter/confirm',
+              description: "The storefront URL the verification token is appended to. Left out of the webhook payload unless it matches one of the store's allowed origins."
+          end
+
+          request_params 'VerifyNewsletterSubscriberParams', action: :verify do |body|
+            body.attribute :token, :string,
+              required: true,
+              example: 'abc123def456',
+              description: 'The verification token from the confirmation email.'
+          end
+
+          request_params 'RequestNewsletterUnsubscribeParams', action: :request_unsubscribe do |body|
+            body.attribute :email, :string, format: :email, example: 'subscriber@example.com'
+            body.attribute :redirect_url, :string,
+              format: :uri,
+              description: "The storefront URL the unsubscribe token is appended to in the email. Left out of the event payload unless it matches one of the store's allowed origins."
+          end
+
           # POST /api/v3/store/newsletter_subscribers
           def create
             subscriber = Spree::NewsletterSubscriber.subscribe(
@@ -43,7 +65,7 @@ module Spree
             unless subscriber
               return render_error(
                 code: ERROR_CODES[:invalid_token],
-                message: Spree.t(:newsletter_verification_token_invalid, scope: :api),
+                message: I18n.t('spree.api.newsletter_verification_token_invalid'),
                 status: :unprocessable_content
               )
             end
@@ -64,7 +86,7 @@ module Spree
             if subscriber.blank?
               return render_error(
                 code: ERROR_CODES[:invalid_token],
-                message: Spree.t(:newsletter_unsubscribe_token_invalid, scope: :api),
+                message: I18n.t('spree.api.newsletter_unsubscribe_token_invalid'),
                 status: :unprocessable_content
               )
             end
@@ -87,18 +109,9 @@ module Spree
             subscriber = Spree::NewsletterSubscriber.for_store(current_store).find_by(email: params[:email])
 
             if subscriber
-              payload = {
-                id: subscriber.prefixed_id,
-                email: subscriber.email,
-                unsubscribe_token: subscriber.generate_token_for(:unsubscribe),
-                store_id: current_store.prefixed_id,
-                customer_id: subscriber.customer&.prefixed_id
-              }
-
-              redirect_url = validated_redirect_url
-              payload[:redirect_url] = redirect_url if redirect_url.present?
-
-              subscriber.publish_event('newsletter_subscriber.unsubscribe_requested', payload)
+              event_name = 'newsletter_subscriber.unsubscribe_requested'
+              payload = subscriber.event_payload_for(event_name, store: current_store, redirect_url: validated_redirect_url.presence)
+              subscriber.publish_event(event_name, payload)
             end
 
             head :accepted

data/app/controllers/spree/api/v3/store/orders/claims_controller.rb

@@ -10,6 +10,16 @@ module Spree
           # Whether a customer may file a claim is store policy and belongs in
           # a `claims.create.validate` hook rather than here.
           class ClaimsController < Store::ResourceController
+            request_params 'CreateClaimParams', action: :create do |body|
+              body.attribute :items, :array, required: true do |item|
+                item.attribute :line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :description, :string, description: 'What is wrong with the item.'
+              end
+              body.attribute :reason_id, :id, description: "One of the store's claim reasons."
+              body.attribute :memo, :string
+            end
+
             def create
               result = Spree.claim_create_workflow.call(
                 order: @parent,
@@ -18,11 +28,7 @@ module Spree
                 memo: create_params[:memo]
               )
 
-              if result.success?
-                render json: serialize_resource(result.value), status: :created
-              else
-                render_result_error(result)
-              end
+              render_result(result, status: :created)
             end
 
             protected
@@ -63,8 +69,7 @@ module Spree
             end
 
             def create_params
-              @create_params ||= params.permit(:memo, :reason_id,
-                                               items: [:line_item_id, :quantity, :description])
+              @create_params ||= params.permit(*declared_permitted_attributes)
             end
 
             private

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

@@ -17,6 +17,15 @@ module Spree
             # standard actions are listed alongside the label download.
             before_action :set_resource, only: [:show, :update, :destroy, :label]
 
+            request_params 'CreateReturnParams', action: :create do |body|
+              body.attribute :items, :array, required: true do |item|
+                item.attribute :fulfillment_item_id, :id, required: true, description: 'The shipped unit coming back.'
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :reason_id, :id, description: "One of the store's return reasons."
+              body.attribute :memo, :string
+            end
+
             # GET /api/v3/store/orders/:order_id/returns/:id/label
             #
             # The customer's return label, streamed to whoever owns the order.
@@ -37,11 +46,7 @@ module Spree
                 memo: create_params[:memo]
               )
 
-              if result.success?
-                render json: serialize_resource(result.value), status: :created
-              else
-                render_result_error(result)
-              end
+              render_result(result, status: :created)
             end
 
             protected
@@ -89,7 +94,7 @@ module Spree
             end
 
             def create_params
-              @create_params ||= params.permit(:memo, :reason_id, items: [:fulfillment_item_id, :quantity])
+              @create_params ||= params.permit(*declared_permitted_attributes)
             end
 
             private

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

@@ -3,6 +3,8 @@ module Spree
     module V3
       module Store
         class OrdersController < Store::BaseController
+          include Spree::Api::V3::PurchaseSerialization
+
           # GET /api/v3/store/orders/:id
           # Single order lookup — accessible via order token (guests) or JWT (authenticated users)
           before_action :find_order!
@@ -13,26 +15,61 @@ module Spree
 
           private
 
-          # The cart's prefixed id stays the client's stable checkout handle:
-          # after completion it resolves here to the order created from that
-          # cart (Order#cart_id is unique; the order copies the cart token).
+          # The cart's prefixed id stays the client's stable checkout handle.
+          # A plain completion leaves the order it created carrying that id
+          # (Order#cart_id is unique; the order copies the cart token). A
+          # checkout that reached several sellers divided into one order per
+          # seller and moved the id up to the group holding them, so the same
+          # handle resolves to the group — a confirmation asking what its cart
+          # became is answered with the whole purchase either way, never one
+          # seller's share of it.
+          #
+          # The group's own id resolves here too, for a client re-reading what
+          # completion handed back, the way +carts#complete+ already accepts it.
           def find_order!
             cart_pk = Spree::Cart.decode_own_prefixed_id(params[:id])
-            @order = cart_pk ? scope.find_by!(cart_id: cart_pk) : scope.find_by_prefix_id!(params[:id])
+            @order = cart_pk ? find_by_cart!(cart_pk) : find_by_prefixed_id!(params[:id])
+          end
+
+          # @return [Spree::Order, Spree::OrderGroup]
+          def find_by_cart!(cart_pk)
+            scope.find_by(cart_id: cart_pk) || group_scope.find_by(cart_id: cart_pk) || not_found!
+          end
+
+          # @return [Spree::Order, Spree::OrderGroup]
+          def find_by_prefixed_id!(id)
+            scope.find_by_prefix_id(id) || group_scope.find_by_prefix_id(id) || not_found!
           end
 
-          # `market` and `fulfillments` are the withdrawal deadline's inputs and
-          # the serializer emits it on every response, so they are preloaded
-          # here rather than through `collection_includes` — this controller
-          # loads through `find_order!`, which never touches a collection.
+          # Neither lookup answered. The caller asked `/orders`, so that is what
+          # the 404 names — which of the two ran last is this endpoint's
+          # business, and `order_not_found` is the code clients already handle.
+          def not_found!
+            raise ActiveRecord::RecordNotFound.new(nil, Spree::Order.name)
+          end
+
+          # Preloaded lazily, which `collection` would do for a list: this
+          # controller loads through `find_order!`, so it asks for it itself.
+          # Every association the serializer walks — items, parcels, their
+          # rates and discounts — is then fetched once for all the rows that
+          # need it, rather than once per row.
           def scope
             storefront_access_policy.
               scope(current_store.orders.complete, token: order_token).
-              includes(:market, :fulfillments)
+              preload_associations_lazily
+          end
+
+          # A group renders every child through the order serializer, so this
+          # matters most here: without it each seller in the checkout adds its
+          # own round of queries for the same associations.
+          def group_scope
+            storefront_access_policy.
+              scope(current_store.order_groups, token: order_token).
+              preload_associations_lazily
           end
 
           def serializer_class
-            Spree.api.order_serializer
+            purchase_serializer_for(@order)
           end
         end
       end

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

@@ -9,6 +9,14 @@ module Spree
 
           protected
 
+          def additional_sort_fields
+            Spree::SearchProvider::Base::SORT_FIELDS
+          end
+
+          def custom_field_filters?
+            true
+          end
+
           def model_class
             Spree::Product
           end

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

@@ -7,6 +7,16 @@ module Spree
 
           prepend_before_action :require_authentication!
 
+          request_params 'CreateWishlistItemParams', action: :create do |body|
+            body.attribute :variant_id, :id, required: true, example: 'variant_abc123'
+            body.attribute :quantity, :integer, example: 1
+          end
+
+          request_params 'UpdateWishlistItemParams', action: :update do |body|
+            body.attribute :variant_id, :id, description: 'Moves the item to another variant.'
+            body.attribute :quantity, :integer, example: 2
+          end
+
           protected
 
           def set_parent
@@ -16,10 +26,6 @@ module Spree
             authorize_storefront_write!(@parent)
           end
 
-          def parent_association
-            :wishlist_items
-          end
-
           def model_class
             Spree::WishlistItem
           end
@@ -28,10 +34,6 @@ module Spree
             Spree.api.wishlist_item_serializer
           end
 
-          def resource_permitted_attributes
-            [:variant_id, :quantity]
-          end
-
           # The item renders its variant and product, so the variant must be
           # one the buyer could find in the listing — not a draft, another
           # catalog's product, or an id guessed from the sequence.

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

@@ -5,6 +5,18 @@ module Spree
         class WishlistsController < ResourceController
           prepend_before_action :require_authentication!
 
+          request_params 'CreateWishlistParams', action: :create do |body|
+            body.attribute :name, :string, required: true, example: 'Birthday Ideas'
+            body.attribute :is_private, :boolean
+            body.attribute :is_default, :boolean
+          end
+
+          request_params 'UpdateWishlistParams', action: :update do |body|
+            body.attribute :name, :string, example: 'Updated Name'
+            body.attribute :is_private, :boolean
+            body.attribute :is_default, :boolean
+          end
+
           # POST /api/v3/store/wishlists
           def create
             @resource = current_user.wishlists.build(permitted_params)
@@ -30,10 +42,6 @@ module Spree
           def serializer_class
             Spree.api.wishlist_serializer
           end
-
-          def resource_permitted_attributes
-            [:name, :is_default, :is_private]
-          end
         end
       end
     end

data/app/request_schemas/spree/api/v3/address_request_schema.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      # The writable attributes of an address, wherever it hangs. One list
+      # rather than one per endpoint: an address is the same record on every
+      # write path, so a column added on one but missed on another would be
+      # dropped silently. Not published on its own: each endpoint includes
+      # these attributes into its own type, beside what it adds.
+      class AddressRequestSchema < Spree::Api::V3::RequestSchema
+        attribute :first_name, :string
+        attribute :last_name, :string
+        attribute :company, :string
+        attribute :address1, :string
+        attribute :address2, :string
+        attribute :city, :string
+        attribute :postal_code, :string
+        attribute :phone, :string
+        attribute :label, :string
+        attribute :country_code, :country, example: 'US', description: 'ISO 3166-1 alpha-2 code, such as `US`.'
+        attribute :state_code, :string,
+          example: 'NY',
+          description: 'The state or province abbreviation, such as `NY`.'
+        attribute :state_name, :string, description: 'For countries without states in the database.'
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/address_request_schema.rb

@@ -0,0 +1,13 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The Admin API's address: the shared one plus the second phone number
+        # orders and customer address books keep.
+        class AddressRequestSchema < Spree::Api::V3::AddressRequestSchema
+          attribute :alternative_phone, :string
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/bulk_tags_request_schema.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The body of the shared bulk tag actions (Spree::Api::V3::BulkOperations).
+        # Each controller declares it as `BulkTagsParams` with only these fields,
+        # so the published component is the same wherever it is used.
+        class BulkTagsRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :ids, :array, of: :id,
+            required: true,
+            description: 'The records to change. Records the caller cannot update are skipped; an empty list changes nothing.'
+          attribute :tags, :array, of: :string, required: true, example: %w[vip wholesale]
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/catalog_order_minimum_request_schema.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The least a whole order must come to under a catalog, in one currency.
+        class CatalogOrderMinimumRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'CatalogOrderMinimumParams'
+
+          attribute :currency, :currency,
+            example: 'USD',
+            description: 'ISO 4217 code. Required on create; one minimum per currency.'
+          attribute :amount, :decimal, example: '500.00'
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/email_template_language_request_schema.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The language every email template endpoint takes. Read from the raw
+        # params (Admin::EmailTemplateLookup), so never permitted. Not
+        # published on its own.
+        class EmailTemplateLanguageRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :language, :string,
+            permit: false,
+            example: 'any',
+            description: 'A language code, or `any` (the default) for the version every language uses.'
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/email_template_preview_request_schema.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What the email template preview and test email endpoints render.
+        # Not published on its own: both declare it as `EmailTemplatePreviewParams`.
+        class EmailTemplatePreviewRequestSchema < Spree::Api::V3::Admin::EmailTemplateLanguageRequestSchema
+          attribute :subject, :string,
+            nullable: true,
+            example: 'Your order {{ order.number }} is confirmed',
+            description: 'An unsaved subject, in place of the current one.'
+          attribute :body, :string,
+            example: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+            description: 'An unsaved body, in place of the current one.'
+          attribute :record_id, :id,
+            example: 'or_m3Rp9wXz',
+            description: "The record to build sample data from; the store's latest matching record otherwise."
+          attribute :email_key, :string,
+            permit: false,
+            example: 'spree.order_mailer.confirm_email',
+            description: 'For the layout or a partial, the email to show it in.'
+          attribute :branding, :object,
+            permit: false,
+            description: "Unsaved colors and font to preview, named like the store's `email_*` settings." do |branding|
+            Spree::Emails::Branding::COLORS.each { |name| branding.attribute name, :string, nullable: true }
+            branding.attribute :font, :string, nullable: true, choices: Spree::Emails::Branding::FONTS.keys
+          end
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/price_adjustment_tier_request_schema.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One quantity tier of a price list's percentage adjustment.
+        class PriceAdjustmentTierRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'PriceAdjustmentTierParams'
+
+          attribute :min_quantity, :integer,
+            required: true,
+            example: 10,
+            description: "Above 1; quantity 1 is the list's own `price_adjustment_percentage`."
+          attribute :percentage, :decimal,
+            required: true,
+            example: '-10.0',
+            description: 'Signed: negative discounts, positive marks up.'
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/price_list_price_request_schema.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A fixed price a price list sets for one variant, currency and quantity.
+        class PriceListPriceRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'PriceListPriceOverrideParams'
+
+          attribute :id, :id,
+            description: 'Updates this price row. Without it, the row upserts on `(variant_id, currency, min_quantity)`.'
+          attribute :variant_id, :id, example: 'variant_xY9'
+          attribute :currency, :currency, example: 'USD'
+          attribute :min_quantity, :integer,
+            description: "The rung of the variant's ladder. Omit for the bottom rung."
+          attribute :amount, :decimal, nullable: true, example: '19.99'
+          attribute :compare_at_amount, :decimal, nullable: true, example: '19.99'
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/price_list_rule_request_schema.rb

@@ -0,0 +1,19 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A rule deciding when a price list applies, as price lists and catalogs write it.
+        class PriceListRuleRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'PriceListRuleParams'
+
+          attribute :id, :id, nullable: true, description: 'Present for existing rules. Omit to create a new one.'
+          attribute :type, :string,
+            required: true,
+            example: 'volume_rule',
+            description: 'Wire shorthand for the rule kind, from the price rule types endpoint.'
+          attribute :preferences, :hash, description: "The rule kind's settings, keyed by preference name."
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/product_membership_reposition_request_schema.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Moving a product within a category's or a collection's product list.
+        class ProductMembershipRepositionRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'ProductMembershipRepositionParams'
+
+          attribute :new_position, :integer,
+            required: true,
+            example: 0,
+            description: "0-based index among the parent's products."
+        end
+      end
+    end
+  end
+end

data/app/request_schemas/spree/api/v3/admin/promotion_action_calculator_request_schema.rb

@@ -0,0 +1,18 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The calculator of an adjustment promotion action.
+        class PromotionActionCalculatorRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'PromotionActionCalculatorParams'
+
+          attribute :type, :string,
+            example: 'flat_percent_item_total',
+            description: 'The calculator kind, from `GET /promotion_actions/calculators`. Changing it swaps the calculator.'
+          attribute :preferences, :hash,
+            description: "Values for the calculator's settings, such as `amount` or `flat_percent`."
+        end
+      end
+    end
+  end
+end