spree_api 6.0.0.rc1 → 6.0.0.rc3

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,
@@ -59,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.
@@ -85,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
@@ -24,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

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A variant and quantity the `create_line_items` promotion action adds.
+        class PromotionActionLineItemRequestSchema < Spree::Api::V3::RequestSchema
+          publishes 'PromotionActionLineItemParams'
+
+          attribute :variant_id, :id, required: true
+          attribute :quantity, :integer, required: true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The keys of a promotion action beyond `type`, shared by the promotion action endpoints and the `actions` written with a promotion.
+        class PromotionActionRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :preferences, :hash,
+            description: "Values for the action kind's settings schema, from `GET /promotion_actions/types`."
+          attribute :calculator, :object, shape: Spree::Api::V3::Admin::PromotionActionCalculatorRequestSchema,
+            permit: false,
+            description: 'For adjustment actions.'
+          attribute :line_items, :array, of: Spree::Api::V3::Admin::PromotionActionLineItemRequestSchema,
+            permit: false,
+            description: 'For `create_line_items`: the variants to add and their quantities. Variants left out are removed.'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The keys of a promotion rule or action beyond `type`, shared by the
+        # nested promotion rule and action endpoints and by the `rules` and
+        # `actions` written with a promotion. Kind-specific keys are read
+        # per kind from its `additional_permitted_attributes`, so they are
+        # documented here and left out of the permit list.
+        class PromotionRuleRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :preferences, :hash,
+            description: "Values for the rule kind's settings schema, from `GET /promotion_rules/types`."
+          attribute :product_ids, :array, of: :id, permit: false, description: 'For the `product` rule.'
+          attribute :category_ids, :array, of: :id, permit: false, description: 'For the `category` rule.'
+          attribute :customer_ids, :array, of: :id,
+            permit: false,
+            description: 'For the `user` rule: the customers who qualify.'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A reason staff pick from: claim, refund, return and order
+        # cancellation reasons all take the same body.
+        class ReasonRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :name, :string, required: true, on: :create
+          attribute :active, :boolean, description: 'Whether the reason is offered on new records.'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A customer's or a company's tax registration, as staff write it.
+        class TaxIdentifierRequestSchema < Spree::Api::V3::RequestSchema
+          attribute :kind, :string,
+            example: 'gb_vat',
+            description: "#{Spree::Api::V3::TaxIdentifierRequestSchema::KIND_DESCRIPTION}"
+          attribute :value, :string, example: 'GB123456789'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      # A custom field value written inline with its owner (product, category, seller…).
+      class CustomFieldValueRequestSchema < Spree::Api::V3::RequestSchema
+        publishes 'CustomFieldValueParams'
+
+        attribute :id, :id
+        attribute :custom_field_definition_id, :id
+        attribute :value, :any,
+          description: 'A scalar for text, number and boolean fields; a list or a hash for JSON fields.'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Spree
+  module Api
+    module V3
+      # A file sent to `POST /files` (Spree::Api::V3::FileUploads): its
+      # details for a direct upload, or its bytes in a multipart request.
+      class FileUploadRequestSchema < Spree::Api::V3::RequestSchema
+        attribute :filename, :string, required: true, example: 'registration.pdf'
+        attribute :content_type, :string, required: true, example: 'application/pdf'
+        attribute :byte_size, :integer, example: 51_234
+        attribute :checksum, :string,
+          example: 'rL0Y20zC+Fzt72VPzMSk2A==',
+          description: 'Base64-encoded MD5 digest of the file; the storage service checks the bytes against it.'
+        attribute :visibility, :string,
+          choices: Spree::FileUpload::VISIBILITIES,
+          description: '`public` (the default) for images, videos and CSV files anyone may fetch, `private` for any type.'
+        attribute :file, :string, format: :binary, description: 'The bytes, for a multipart upload.'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      # What a media row itself carries, whichever endpoint writes it. Not
+      # published on its own: each endpoint adds how the file arrives.
+      class MediaRequestSchema < Spree::Api::V3::RequestSchema
+        attribute :alt, :string, nullable: true, example: 'Front view'
+        attribute :position, :integer, example: 1
+        attribute :media_type, :string,
+          choices: Spree::Media::MEDIA_TYPES,
+          example: 'image',
+          description: 'Defaults to `image`. `video` needs a `signed_id`; `external_video` needs an `external_video_url`.'
+        attribute :external_video_url, :string,
+          nullable: true,
+          description: 'YouTube or Vimeo link. Required when `media_type` is `external_video`.'
+        attribute :poster_signed_id, :string,
+          description: "A `signed_id` from `files.upload()` for a video's poster frame."
+        attribute :focal_point_x, :number,
+          nullable: true,
+          description: 'Where the image is anchored when cropped, from 0 to 1.'
+        attribute :focal_point_y, :number,
+          nullable: true,
+          description: 'Where the image is anchored when cropped, from 0 to 1.'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      # A variant's price in one currency.
+      class PriceRequestSchema < Spree::Api::V3::RequestSchema
+        publishes 'PriceParams'
+
+        attribute :currency, :currency, required: true, example: 'USD'
+        attribute :amount, :decimal,
+          required: true,
+          example: '29.99',
+          description: 'A canonical decimal string (`"1234.56"`: period decimal, no grouping). The API does not parse localized input.'
+        attribute :compare_at_amount, :decimal, nullable: true, example: '39.99'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Spree
+  module Api
+    module V3
+      # A variant's stock at one location.
+      class StockLevelRequestSchema < Spree::Api::V3::RequestSchema
+        publishes 'StockLevelParams'
+
+        # Rows are matched by location: an `id` would be ignored.
+        attribute :stock_location_id, :id, required: true, description: 'The location holding the stock (`sloc_...`).'
+        attribute :count_on_hand, :integer,
+          required: true,
+          description: 'Units physically at the location, not units available to sell: stock promised to placed orders counts until it ships. Sent as the count the shelf should end at; the API records the difference as an adjustment in the stock history.'
+        attribute :backorderable, :boolean,
+          description: 'Whether this location sells the variant beyond what it holds.'
+      end
+    end
+  end
+end