spree_api 5.6.1 → 6.0.0.beta1

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

@@ -8,23 +8,26 @@ module Spree
           protected
 
           def set_parent
-            @parent = current_user.wishlists.find_by_prefix_id!(params[:wishlist_id])
+            @parent = storefront_access_policy.
+                      scope(Spree::Wishlist.for_store(current_store)).
+                      find_by_prefix_id!(params[:wishlist_id])
+            authorize_storefront_write!(@parent)
           end
 
           def parent_association
-            :wished_items
+            :wishlist_items
           end
 
           def model_class
-            Spree::WishedItem
+            Spree::WishlistItem
           end
 
           def serializer_class
-            Spree.api.wished_item_serializer
+            Spree.api.wishlist_item_serializer
           end
 
-          def permitted_params
-            params.permit(Spree::PermittedAttributes.wished_item_attributes)
+          def resource_permitted_attributes
+            [:variant_id, :quantity]
           end
         end
       end

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

@@ -20,7 +20,7 @@ module Spree
           protected
 
           def scope
-            current_user.wishlists.for_store(current_store)
+            storefront_access_policy.scope(Spree::Wishlist.for_store(current_store))
           end
 
           def model_class
@@ -31,8 +31,8 @@ module Spree
             Spree.api.wishlist_serializer
           end
 
-          def permitted_params
-            params.permit(Spree::PermittedAttributes.wishlist_attributes)
+          def resource_permitted_attributes
+            [:name, :is_default, :is_private]
           end
         end
       end

data/app/controllers/spree/api/v3/webhooks/fulfillments_controller.rb

@@ -0,0 +1,88 @@
+module Spree
+  module Api
+    module V3
+      module Webhooks
+        # Carrier webhooks, addressed to the integration holding the carrier's
+        # credentials: POST /api/v3/webhooks/fulfillments/:integration_id.
+        #
+        # Mirrors the payments webhook endpoint: the integration verifies the
+        # signature synchronously (401 when it fails, so a misconfigured
+        # sender notices), translates the payload into core vocabulary, and
+        # anything unrecognised is acknowledged with 200 — carriers retry
+        # anything else, and there is nothing to retry for a parcel that is
+        # not ours. Unlike payments there is no job hand-off: recording a
+        # tracking update is a couple of database writes, well inside any
+        # sender's timeout.
+        class FulfillmentsController < ActionController::API
+          include ActionController::RateLimiting
+          include Spree::Core::ControllerHelpers::Store
+
+          # Must render — instance_exec'd in a before_action, where only
+          # render/redirect halts the chain.
+          RATE_LIMIT_RESPONSE = -> {
+            response.headers['Retry-After'] = '60'
+            render json: { error: { code: 'rate_limit_exceeded', message: 'Too many requests' } },
+                   status: :too_many_requests
+          }
+
+          rate_limit to: 120, within: 1.minute,
+                     store: Rails.cache,
+                     by: -> { request.remote_ip },
+                     with: RATE_LIMIT_RESPONSE
+
+          def create
+            integration = current_store.integrations.active.find_by_prefix_id!(params[:integration_id])
+
+            event = integration.parse_webhook_event(request.raw_post, request.headers)
+            return head :ok if event.nil?
+
+            delivery = find_delivery(event[:tracking_code])
+            return head :ok if delivery.nil?
+
+            Spree.delivery_update_tracking_workflow.call(
+              delivery: delivery,
+              **event.except(:tracking_code)
+            )
+
+            head :ok
+          rescue Spree::Integration::WebhookSignatureError
+            head :unauthorized
+          rescue ActiveRecord::RecordNotFound
+            head :not_found
+          rescue StandardError => e
+            Rails.error.report(e, source: 'spree.webhooks.fulfillments')
+            head :ok
+          end
+
+          private
+
+          # Scoped to the store the verified integration belongs to — a
+          # tracking code can never address another tenant's parcel — and to
+          # consignments whose parcel was not canceled, so a recycled code
+          # cannot reopen an old one. The newest wins when a code was reused.
+          # Carriers reuse tracking numbers across years, so a code can match
+          # more than one consignment. The store-scoped index makes that
+          # candidate set tiny — almost always one row — and the stood-down
+          # ones are dropped from it rather than from every parcel in the
+          # database. The newest survivor wins.
+          CANDIDATE_LIMIT = 20
+
+          def find_delivery(tracking_code)
+            return if tracking_code.blank?
+
+            # Paged rather than capped: a tracking number reused across
+            # canceled owners would otherwise fill the window and hide the
+            # live delivery behind them, and the webhook would be
+            # acknowledged without applying the carrier's update.
+            current_store.deliveries.
+              where(tracking_number: tracking_code).
+              order(created_at: :desc, id: :desc).
+              includes(:owner).
+              find_each(batch_size: CANDIDATE_LIMIT, order: :desc).
+              find { |delivery| delivery.owner.present? && !delivery.owner.canceled? }
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/webhooks/payments_controller.rb

@@ -6,9 +6,12 @@ module Spree
           include ActionController::RateLimiting
           include Spree::Core::ControllerHelpers::Store
 
+          # Must render — instance_exec'd in a before_action, where only
+          # render/redirect halts the chain.
           RATE_LIMIT_RESPONSE = -> {
-            [429, { 'Content-Type' => 'application/json', 'Retry-After' => '60' },
-             [{ error: { code: 'rate_limit_exceeded', message: 'Too many requests' } }.to_json]]
+            response.headers['Retry-After'] = '60'
+            render json: { error: { code: 'rate_limit_exceeded', message: 'Too many requests' } },
+                   status: :too_many_requests
           }
 
           rate_limit to: 120, within: 1.minute,

data/app/controllers/spree/api/v3/webhooks/payouts_controller.rb

@@ -0,0 +1,61 @@
+module Spree
+  module Api
+    module V3
+      module Webhooks
+        # Marketplace events about sellers: POST /api/v3/webhooks/payouts/:payment_method_id.
+        #
+        # Separate from the payments endpoint because providers scope the two
+        # separately. Events originating in a seller's own account — whether
+        # they may be paid, whether a payout reached their bank — arrive on
+        # their own subscription with their own signing secret, so verifying
+        # them against the payment endpoint's secret would reject every one.
+        #
+        # Addressed to the payment method because a marketplace pays sellers
+        # out of the account it charges their customers from: the same
+        # credentials, and so the same record.
+        #
+        # Handled inline rather than handed to a job, like the carrier
+        # endpoint: marking a seller payable or a payout settled is a couple of
+        # database writes, well inside any sender's timeout.
+        class PayoutsController < ActionController::API
+          include ActionController::RateLimiting
+          include Spree::Core::ControllerHelpers::Store
+
+          # Must render — instance_exec'd in a before_action, where only
+          # render/redirect halts the chain.
+          RATE_LIMIT_RESPONSE = -> {
+            response.headers['Retry-After'] = '60'
+            render json: { error: { code: 'rate_limit_exceeded', message: 'Too many requests' } },
+                   status: :too_many_requests
+          }
+
+          rate_limit to: 120, within: 1.minute,
+                     store: Rails.cache,
+                     by: -> { request.remote_ip },
+                     with: RATE_LIMIT_RESPONSE
+
+          def create
+            payment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])
+            return head :not_found unless payment_method.respond_to?(:handle_payout_webhook)
+
+            payment_method.handle_payout_webhook(request.raw_post, request.headers)
+
+            head :ok
+          rescue Spree::PaymentMethod::WebhookSignatureError
+            head :unauthorized
+          rescue ActiveRecord::RecordNotFound
+            head :not_found
+          rescue StandardError => e
+            # 500, unlike the payments endpoint beside this one — that hands
+            # its work to a job, so accepting the delivery is honest. This acts
+            # inline, so answering 200 for work that failed tells the provider
+            # the settlement was recorded when it was not, and nothing will
+            # redeliver it. A retry is the only thing that recovers it.
+            Rails.error.report(e, source: 'spree.webhooks.payouts')
+            head :internal_server_error
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/spree/api/data_request_urls.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    # The one place that knows how a finished export is addressed. Mirrors
+    # DigitalLinkUrls: the route only exists in this gem, while the email that
+    # needs it absolute lives in another.
+    module DataRequestUrls
+      module_function
+
+      # @param data_request [Spree::DataRequest]
+      # @return [String] path relative to the API host
+      def download_path(data_request)
+        Spree::Core::Engine.routes.url_helpers.api_v3_store_data_request_download_path(
+          token: data_request.download_token
+        )
+      end
+
+      # @param data_request [Spree::DataRequest]
+      # @param host [String] the backend's own URL
+      # @return [String] absolute URL, for emails and anything else off-request
+      def download_url(data_request, host)
+        URI.join(host, download_path(data_request)).to_s
+      end
+    end
+  end
+end

data/app/models/spree/api/digital_link_urls.rb

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    # The one place that knows how a download link is addressed. Both consumers
+    # live in different gems — the store serializer emits the path, the email
+    # needs it absolute — and the route only exists here, in the gem that draws
+    # it, so neither the core model nor the emails gem can own this.
+    module DigitalLinkUrls
+      module_function
+
+      # @param digital_link [Spree::DigitalLink]
+      # @return [String] path relative to the API host
+      def download_path(digital_link)
+        Spree::Core::Engine.routes.url_helpers.api_v3_store_digital_link_download_path(
+          token: digital_link.token
+        )
+      end
+
+      # @param digital_link [Spree::DigitalLink]
+      # @param host [String] the backend's own URL
+      # @return [String] absolute URL, for emails and anything else off-request
+      def download_url(digital_link, host)
+        URI.join(host, download_path(digital_link)).to_s
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/address_serializer.rb

@@ -5,13 +5,25 @@ module Spree
         typelize first_name: [:string, nullable: true], last_name: [:string, nullable: true], full_name: :string,
                  address1: [:string, nullable: true], address2: [:string, nullable: true],
                  city: [:string, nullable: true], postal_code: [:string, nullable: true], phone: [:string, nullable: true],
-                 company: [:string, nullable: true], state_abbr: [:string, nullable: true], state_name: [:string, nullable: true],
-                 state_text: [:string, nullable: true], country_iso: :string, country_name: :string,
-                 quick_checkout: :boolean, is_default_billing: :boolean, is_default_shipping: :boolean
+                 company: [:string, nullable: true], state_code: [:string, nullable: true],
+                 state_abbr: [:string, nullable: true], state_name: [:string, nullable: true],
+                 state_text: [:string, nullable: true], country_code: :string, country_iso: :string,
+                 country_name: :string,
+                 quick_checkout: :boolean, is_default_billing: :boolean, is_default_shipping: :boolean,
+                 label: [:string, nullable: true]
+
+        # What the address is filed under in whichever book owns it — a
+        # customer's ("Home") or a company node's ("Northern Warehouse").
+        attributes :label
 
         attributes :first_name, :last_name, :full_name, :address1, :address2, :postal_code,
-                   :city, :phone, :company, :country_name, :country_iso, :state_text,
-                   :state_abbr, :quick_checkout, :is_default_billing, :is_default_shipping
+                   :city, :phone, :company, :country_name, :country_code, :state_text,
+                   :state_code, :quick_checkout, :is_default_billing, :is_default_shipping
+
+        # @deprecated Storefronts shipped against these names; use +state_code+
+        #   and +country_code+. Removed in 6.1.
+        attribute :state_abbr, &:state_code
+        attribute :country_iso, &:country_code
 
         # State name - used for countries without predefined states
         attribute :state_name do |address|

data/app/serializers/spree/api/v3/admin/address_serializer.rb

@@ -3,16 +3,39 @@ module Spree
     module V3
       module Admin
         class AddressSerializer < V3::AddressSerializer
-          typelize label: [:string, nullable: true],
-                   customer_id: [:string, nullable: true],
+          typelize customer_id: [:string, nullable: true],
+                   owner_id: [:string, nullable: true],
+                   owner_type: [:string, nullable: true],
+                   latitude: [:number, nullable: true],
+                   longitude: [:number, nullable: true],
                    metadata: 'Record<string, unknown>'
 
-          attributes :label, :metadata,
+          attributes :metadata,
                      created_at: :iso8601, updated_at: :iso8601
 
+          # Geocoded in the background after the address is saved, so both are
+          # null until that job has run — a client showing a map has to cope
+          # with an address it cannot place yet.
+          attribute :latitude do |address|
+            address.latitude&.to_f
+          end
+
+          attribute :longitude do |address|
+            address.longitude&.to_f
+          end
+
           attribute :customer_id do |address|
-            address.user&.prefixed_id
+            address.customer_owner&.prefixed_id
           end
+
+          # Who the row belongs to — a customer's book, a company node's, or a
+          # seller's billing address. `customer_id` above stays as the
+          # customer-only shorthand the customers surface reads.
+          attribute :owner_id do |address|
+            address.owner&.prefixed_id
+          end
+
+          attributes :owner_type
         end
       end
     end

data/app/serializers/spree/api/v3/admin/admin_user_serializer.rb

@@ -25,21 +25,24 @@ module Spree
           # the user might have on other stores. Block receives `params`
           # only when Alba passes it through the `serializer_params` hash —
           # we fall back to `Spree::Current.store` if not.
+          # Filtered in Ruby rather than with `for_resource`, so the staff
+          # index's preloaded roles are used instead of a query per user.
           attribute :roles do |user, params|
             store = params&.dig(:store) || Spree::Current.store
-            scope = user.role_users
-            scope = scope.where(resource: store) if store
-            scope.includes(:role).map { |ru| { id: ru.role.prefixed_id, name: ru.role.name } }
+            roles = user.spree_roles.to_a
+            roles = roles.select { |role| role.resource == store } if store
+            roles.map { |role| { id: role.prefixed_id, name: role.name } }
           end
 
-          # Every store this user holds a role on (via `Spree::RoleUser`) —
-          # unlike `roles`, deliberately NOT scoped to the current store, so
-          # the dashboard store switcher can offer all accessible stores.
-          # Dedupe/sort happen in Ruby (not `.distinct.order`) so the staff
-          # index's `collection_includes` preload is used instead of firing
-          # an extra query per user.
+          # Every store this user holds a role on — unlike `roles`,
+          # deliberately NOT scoped to the current store, so the dashboard
+          # store switcher can offer all accessible stores. Read off the same
+          # preloaded roles, and deduped/sorted in Ruby, so the staff index
+          # spends no extra query per user.
           attribute :stores do |user|
-            user.stores.uniq.sort_by(&:name).map do |store|
+            stores = user.spree_roles.filter_map { |role| role.resource if role.resource.is_a?(Spree::Store) }
+
+            stores.uniq.sort_by(&:name).map do |store|
               { id: store.prefixed_id, name: store.name, code: store.code }
             end
           end

data/app/serializers/spree/api/v3/admin/api_key_serializer.rb

@@ -12,7 +12,7 @@ module Spree
         # via {#plaintext_token} below — it is `nil` everywhere else.
         class ApiKeySerializer < V3::BaseSerializer
           typelize name: :string,
-                   key_type: :string,
+                   key_type: [:string, enum: Spree::ApiKey::KEY_TYPES],
                    token_prefix: [:string, nullable: true],
                    plaintext_token: [:string, nullable: true],
                    scopes: [:string, multi: true],

data/app/serializers/spree/api/v3/admin/applied_promotion_serializer.rb

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class AppliedPromotionSerializer < V3::AppliedPromotionSerializer
+          # The Admin API has no guest gating — money fields inherited from the
+          # store serializer are always present, so override their nullability.
+          typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false]
+
+          attributes created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/cart_serializer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin Cart serializer — the store shape plus operational timestamps,
+        # slimmed to what inspecting an originating cart needs. The cart's
+        # fulfillment/payment sub-graphs are pre-conversion duplicates of the
+        # order's own and are dropped (they also ballooned the generated type
+        # graph past the TypeScript instantiation limit). Kept associations
+        # are redeclared with admin counterparts — admin serializers never
+        # reference store serializers.
+        class CartSerializer < V3::CartSerializer
+          %i[fulfillments payments payment_methods gift_card discounts fees].each { |key| _attributes.delete(key) }
+
+          typelize completed_at: [:string, nullable: true]
+
+          attributes completed_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          many :order_promotions, key: :applied_promotions, resource: proc { Spree.api.admin_applied_promotion_serializer }
+          many :line_items, key: :items, resource: proc { Spree.api.admin_line_item_serializer }
+          one :billing_address, resource: proc { Spree.api.admin_address_serializer }
+          one :shipping_address, resource: proc { Spree.api.admin_address_serializer }
+          one :market, resource: proc { Spree.api.admin_market_serializer }
+
+          # An admin twin, so this package carries its own type rather
+          # than importing the store one.
+          one :freight_summary, resource: proc { Spree.api.admin_freight_summary_serializer }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_assignment_serializer.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CatalogAssignmentSerializer < V3::BaseSerializer
+          typelize catalog_id: :string, assignable_type: :string, assignable_id: :string,
+                   assignable_name: [:string, nullable: true]
+
+          attributes created_at: :iso8601
+
+          attribute :catalog_id do |assignment|
+            assignment.catalog.prefixed_id
+          end
+
+          # The client-facing type vocabulary: 'company', 'customer_group' —
+          # never Ruby class names.
+          attribute :assignable_type do |assignment|
+            assignment.assignable_type.demodulize.underscore
+          end
+
+          attribute :assignable_id do |assignment|
+            assignment.assignable&.prefixed_id
+          end
+
+          attribute :assignable_name do |assignment|
+            assignment.assignable.try(:name)
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_order_minimum_serializer.rb

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The least a whole order must come to under a catalog's agreement,
+        # in one currency.
+        class CatalogOrderMinimumSerializer < V3::BaseSerializer
+          typelize currency: :string, amount: :string, display_amount: :string
+
+          attributes :currency, created_at: :iso8601, updated_at: :iso8601
+
+          attribute :amount do |minimum|
+            minimum.amount.to_s
+          end
+
+          attribute :display_amount do |minimum|
+            minimum.display_amount.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_price_serializer.rb

@@ -0,0 +1,48 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What a buyer on one catalog pays for one product, and where that
+        # number came from — an explicit amount on the catalog's own list,
+        # that list's percentage applied to the base price, or the base price
+        # itself, meaning this agreement does not price the product at all
+        # (docs/plans/6.0-catalog-agreement-rework.md).
+        #
+        # Serializes a {Spree::CatalogPrice}, which is resolved rather than
+        # stored, so it carries no id.
+        class CatalogPriceSerializer < V3::BaseSerializer
+          # Resolved rather than stored, so the id is the priced variant's —
+          # the thing a client would actually act on. Null on a reading that
+          # names no variant.
+          _attributes.delete(:id)
+
+          typelize id: 'string | null', label: 'string | null', sku: 'string | null',
+                   amount: :string, display_amount: :string,
+                   currency: :string, source: [:string, enum: Spree::CatalogPrice::SOURCES], break_count: :number
+
+          # The variant this prices, so a row can name what it is showing —
+          # a product's variants can be priced differently, and one figure
+          # without a variant beside it names nothing
+          # (docs/plans/6.0-volume-pricing.md).
+          attribute :id, &:prefixed_id
+
+          attributes :label, :sku
+
+          # How many quantity tiers sit above this amount, so the view can say
+          # "and three more from a case up" rather than showing one figure as
+          # though it were the only one.
+          attributes :currency, :source, :break_count
+
+          attribute :amount, &:display_value
+
+          attributes :display_amount
+
+          # The ladder itself, so the agreement page can show what a buyer
+          # pays at each threshold without opening the price sheet
+          # (docs/plans/6.0-volume-pricing.md).
+          many :tiers, resource: proc { Spree.api.admin_catalog_price_tier_serializer }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_price_tier_serializer.rb

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One rung of a catalog's quantity ladder: from this quantity up, a
+        # buyer on this agreement pays this amount
+        # (docs/plans/6.0-volume-pricing.md).
+        #
+        # Serializes a {Spree::CatalogPriceTier}, which is resolved rather
+        # than stored, so it carries no id.
+        class CatalogPriceTierSerializer < V3::BaseSerializer
+          _attributes.delete(:id)
+
+          typelize min_quantity: :number, amount: :string, display_amount: :string
+
+          attributes :min_quantity, :display_amount
+
+          attribute :amount, &:display_value
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/catalog_product_serializer.rb

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # A product as seen from one catalog: what the membership card renders,
+        # plus what a buyer on this agreement actually pays for it and where
+        # that number comes from.
+        #
+        # The rows are expanded rather than always sent, because resolving
+        # them costs a query per page that the picker and the plain membership
+        # listing have no use for (docs/plans/6.0-catalog-agreement-rework.md).
+        # There is deliberately no product-level price: the card prices
+        # variants, and a figure on the product row would have to pick one
+        # variant to speak for the rest (docs/plans/6.0-volume-pricing.md).
+        class CatalogProductSerializer < Admin::MembershipProductSerializer
+          typelize quantity_rule: ['CatalogProductTerm', nullable: true]
+
+          # Priced off the same variant the row's own price is read from, so
+          # the agreement's amount and the shop's describe the same offer.
+          #
+          # Null means nothing prices this variant in this currency at all —
+          # distinct from a `base` source, which is a real amount the
+          # agreement simply does not touch.
+          # This product's quantity terms under the agreement, rolled up from
+          # the variant rows the page already loaded. Its own request used to
+          # fetch every rule in the catalog unpaginated and group them the
+          # same way, which is the same object graph this endpoint holds
+          # (docs/plans/6.0-volume-pricing.md).
+          attribute :quantity_rule, if: proc { expand?('quantity_rule') } do |product|
+            rules = params[:catalog_quantity_rules]&.fetch(product.id, nil)
+
+            if rules.present?
+              term = Spree::Catalogs::ProductTerm.new(product: product, rules: rules)
+              Spree.api.admin_catalog_product_term_serializer.new(term, params: params).to_h
+            end
+          end
+
+          # Every variant with what this agreement charges for it. A product's
+          # variants can be priced differently — and carry different quantity
+          # ladders — so a single figure on the product row names one variant's
+          # deal and hides the rest (docs/plans/6.0-volume-pricing.md).
+          # `source:` rather than a plain association: the rows are resolved
+          # per request against the catalog's price list, which the serializer
+          # receives in params rather than the product carrying it.
+          many :catalog_variants,
+               resource: proc { Spree.api.admin_catalog_price_serializer },
+               if: proc { expand?('catalog_price') },
+               source: lambda { |params|
+                 resolver = params[:catalog_price_resolver]
+
+                 variants.filter_map { |variant| resolver&.call(variant) }
+               }
+        end
+      end
+    end
+  end
+end