spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,169 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Sign-in for the marketplace seller panel.
+        #
+        # Its own surface rather than a reuse of the admin one, so login policy
+        # can differ per panel: a store that requires SSO for its own staff can
+        # still let sellers sign in with a password, because the two read
+        # different strategy registries against the same user class.
+        class AuthController < Seller::BaseController
+          include Spree::Api::V3::Seller::AuthCookies
+          include Spree::Api::V3::AuthenticationStrategies
+
+          skip_scope_check!
+
+          # A distinct `name:` per declaration — without one Rails keys every
+          # counter in the controller on one cache entry, so the provider list
+          # a login page fetches on every load would spend the login budget.
+          rate_limit to: Spree::Api::Config[:rate_limit_login],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache, only: :create, name: 'seller_login',
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
+          rate_limit to: Spree::Api::Config[:rate_limit_refresh],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache, only: :providers, name: 'seller_providers',
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_refresh]) }
+          rate_limit to: Spree::Api::Config[:rate_limit_refresh],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache, only: [:refresh, :logout], name: 'seller_refresh',
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_refresh]) }
+
+          # Signing in is what establishes which sellers the caller may act as,
+          # so these actions run before any seller is known.
+          skip_before_action :set_current_seller_context, only: [:create, :refresh, :logout, :providers]
+          skip_before_action :authenticate_seller!, only: [:create, :refresh, :logout, :providers]
+
+          # POST /api/v3/seller/auth/login
+          def create
+            strategy = authentication_strategy
+            return unless strategy
+
+            result = strategy.authenticate
+            return render_authentication_failed(result.error) unless result.success?
+
+            user = result.value
+            # A store's own staff share this user class, so authenticating is
+            # not enough: without a role on some seller there is no panel to
+            # sign in to, and minting a token would hand out an audience the
+            # holder can do nothing with.
+            return render_authentication_failed(Spree.t(:seller_membership_required)) unless user.seller_member?
+
+            set_refresh_cookie(
+              Spree::RefreshToken.create_for(
+                user,
+                audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER,
+                request_env: request_env_for_token
+              )
+            )
+            render json: auth_response(user)
+          end
+
+          # GET /api/v3/seller/auth/providers
+          def providers
+            render json: { providers: Spree.seller_authentication_strategies.describe }
+          end
+
+          # POST /api/v3/seller/auth/refresh
+          def refresh
+            refresh_token_value = refresh_token_from_cookie
+
+            if refresh_token_value.blank?
+              return render_error(
+                code: ErrorHandler::ERROR_CODES[:invalid_refresh_token],
+                message: 'Refresh token cookie missing',
+                status: :unauthorized
+              )
+            end
+
+            # Narrowed by audience: a token minted on another surface must not
+            # be exchangeable for a seller one.
+            refresh_token = Spree::RefreshToken.active.
+                            for_audience(Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER).
+                            find_by(token: refresh_token_value)
+
+            if refresh_token.nil?
+              clear_refresh_cookie
+              return render_error(
+                code: ErrorHandler::ERROR_CODES[:invalid_refresh_token],
+                message: 'Invalid or expired refresh token',
+                status: :unauthorized
+              )
+            end
+
+            user = refresh_token.user
+            # Membership can be revoked while a session is live; the refresh is
+            # where that takes effect.
+            unless user.seller_member?
+              refresh_token.destroy
+              clear_refresh_cookie
+              return render_error(
+                code: ErrorHandler::ERROR_CODES[:access_denied],
+                message: Spree.t(:seller_membership_required),
+                status: :forbidden
+              )
+            end
+
+            set_refresh_cookie(refresh_token.rotate!(request_env: request_env_for_token))
+            render json: auth_response(user)
+          end
+
+          # POST /api/v3/seller/auth/logout
+          def logout
+            refresh_token_value = refresh_token_from_cookie
+
+            if refresh_token_value.present?
+              Spree::RefreshToken.
+                for_audience(Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER).
+                find_by(token: refresh_token_value)&.destroy
+            end
+
+            clear_refresh_cookie
+            head :no_content
+          end
+
+          private
+
+          def render_authentication_failed(message)
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:authentication_failed],
+              message: message,
+              status: :unauthorized
+            )
+          end
+
+          def auth_response(user)
+            {
+              token: generate_jwt(user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER),
+              user: Spree.api.seller_team_member_serializer.new(user, params: { store: user.sellers.first&.store }).to_h,
+              sellers: serialized_sellers(user)
+            }
+          end
+
+          # The panel needs these to choose an X-Spree-Seller-Id before it can
+          # make any other request.
+          def serialized_sellers(user)
+            user.sellers.map { |seller| { id: seller.prefixed_id, name: seller.name, status: seller.status } }
+          end
+
+          def authentication_strategies
+            Spree.seller_authentication_strategies
+          end
+
+          def authentication_user_class
+            Spree.admin_user_class
+          end
+
+          def jwt_expiration
+            Spree::Api::Config[:admin_jwt_expiration]
+          end
+
+          def request_env_for_token
+            { ip_address: request.remote_ip, user_agent: request.user_agent&.truncate(255) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Where this seller stands: what they have earned, what has reached
+        # them, and what the marketplace still owes — one row per currency.
+        #
+        # A computed collection rather than a resource: nothing here is a
+        # record, so there is no id to fetch and nothing to page.
+        class BalancesController < Seller::BaseController
+          scoped_resource :seller_earnings
+
+          # GET /api/v3/seller/balances
+          def index
+            authorize! :index, :seller_earnings
+
+            render json: { data: current_seller.balances.map { |balance| serialize_balance(balance) } }
+          end
+
+          protected
+
+          def read_actions
+            %w[index]
+          end
+
+          private
+
+          def serialize_balance(balance)
+            Spree.api.seller_balance_serializer.new(balance, params: { store: current_store }).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Anchor for the marketplace seller panel.
+        #
+        # Deliberately not a subclass of the admin anchor: the admin branch
+        # resolves everything through `current_store`, and inheriting those
+        # lookups is precisely how a seller would come to read the whole
+        # store. Concerns and workflows are shared; controllers are not.
+        #
+        # Mirrors Seller::ResourceController — they anchor parallel inheritance
+        # branches, so a concern added to one must be added to the other.
+        class BaseController < Spree::Api::V3::BaseController
+          include Spree::Api::V3::Seller::SellerContext
+          include Spree::Api::V3::SellerAuthentication
+
+          before_action :authenticate_seller!
+
+          include Spree::Api::V3::ScopedAuthorization
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What went wrong with a delivery.
+        class ClaimReasonsController < ReasonsController
+          protected
+
+          def model_class
+            Spree::ClaimReason
+          end
+
+          def reasons_association
+            :claim_reasons
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Countries for the panel's address forms.
+        #
+        # Public reference data — the same list the storefront and the
+        # operator's dashboard serve — so it is exempt from the key gate, as
+        # its admin twin is. A seller filling in a billing address needs every
+        # country, not the ones their marketplace happens to sell into.
+        class CountriesController < Seller::BaseController
+          skip_scope_check!
+
+          # GET /api/v3/seller/countries
+          #
+          # Unpaginated: there are ~250 countries and an address dropdown needs
+          # them all at once, which Pagy's global max_limit would prevent.
+          def index
+            countries = Spree::Country.all.sort_by(&:name)
+
+            render json: {
+              data: countries.map { |country| serialize_country(country) },
+              meta: { count: countries.size }
+            }
+          end
+
+          private
+
+          def serialize_country(country)
+            Spree.api.country_serializer.new(
+              country, params: { store: current_store, expand: ['states'] }
+            ).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,265 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # How this seller ships: the methods they create, price and retire
+        # against the marketplace's profiles and zones
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        #
+        # The listing also carries the marketplace methods the operator shares
+        # with sellers, so a seller can see what already ships their goods
+        # before adding anything. Those rows are read-only — `find_resource`
+        # roots writes in the seller's own methods, so a shared method's id is
+        # a 404 on every action but `show`.
+        #
+        # Carriers stay the marketplace's: a seller's method prices through
+        # the internal rate provider and is fulfilled by hand, which is what
+        # `Spree::DeliveryMethod` validates and why neither provider is
+        # writable here.
+        class DeliveryMethodsController < Seller::ResourceController
+          scoped_resource :delivery_methods
+
+          # GET /api/v3/seller/delivery_methods/calculators
+          # The ways a seller can price a method, with the preference schema
+          # each one's form is rendered from.
+          def calculators
+            authorize! :create, model_class
+
+            data = Spree::DeliveryMethod.calculators.map do |calculator_class|
+              {
+                type: calculator_class.api_type,
+                name: calculator_class.description,
+                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          # GET /api/v3/seller/delivery_methods/rule_types
+          # The conditions a seller may put on a method. A subset of the
+          # operator's: the rest either segment the marketplace's own traffic
+          # or point at catalog rows this branch does not serve.
+          def rule_types
+            authorize! :create, model_class
+
+            data = seller_rule_classes.map do |klass|
+              {
+                type: klass.api_type,
+                name: klass.human_name,
+                description: klass.human_description,
+                preference_schema: klass.serialized_preference_schema
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          # Built off `resource_scope` rather than the inherited
+          # `build_resource`: the row is born the seller's own that way, and
+          # the payload carries calculator fields that are not columns.
+          def create
+            @resource = resource_scope.new
+            @resource.store = current_store
+            @resource.assign_attributes(assignable_params)
+            authorize_resource!(@resource, :create)
+            rederive_origin_group(@resource)
+            assign_calculator(@resource)
+
+            if @resource.errors.empty? && @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            @resource.assign_attributes(assignable_params)
+            rederive_origin_group(@resource)
+            assign_calculator(@resource)
+
+            if @resource.errors.empty? && @resource.save
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::DeliveryMethod
+          end
+
+          def serializer_class
+            Spree.api.seller_delivery_method_serializer
+          end
+
+          # Reading shows the seller's own methods plus the marketplace ones
+          # shared with them — the same set the estimator will quote their
+          # packages by, so the page answers "how do my goods ship" rather
+          # than only "what have I made".
+          def scope
+            current_store.delivery_methods.
+              available_to_seller(current_seller).
+              includes(*collection_includes).
+              preload_associations_lazily
+          end
+
+          # Writes root in the seller's own methods, so a shared marketplace
+          # method cannot be edited or deleted through this branch.
+          def resource_scope
+            current_seller.delivery_methods
+          end
+
+          def find_resource
+            action_name == 'show' ? super : resource_scope.find_by_prefix_id!(params[:id])
+          end
+
+          # No provider fields: both are fixed for a seller's method, and
+          # permitting them would let a write fail validation for a choice the
+          # seller was never offered. No markup either — that prices a
+          # carrier's quote, and a seller has no carrier.
+          def permitted_params
+            params.permit(
+              *model_additional_permitted_attributes,
+              :name, :admin_name, :code, :storefront_visible, :tracking_url,
+              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
+              :calculator_type,
+              :delivery_profile_id, :delivery_zone_id,
+              calculator_preferences: {},
+              rules: [:id, :type, :active, { preferences: {} }, *subclassed_rule_attributes]
+            )
+          end
+
+          # Association-backed config a rule declares on its own class. Empty
+          # today — the one core rule that declares any is withheld from this
+          # branch — but a seller-eligible rule that grows some would
+          # otherwise have them dropped by `permit` without a word.
+          #
+          # Read from the seller's own rule set, not every registered kind, so
+          # a withheld rule's attributes never become permitted here.
+          def subclassed_rule_attributes
+            seller_rule_classes.flat_map do |klass|
+              klass.respond_to?(:additional_permitted_attributes) ? klass.additional_permitted_attributes : []
+            end.uniq
+          end
+
+          def collection_includes
+            [:calculator, :delivery_zone, :delivery_profile, :delivery_method_rules]
+          end
+
+          private
+
+          # Rule kinds this branch does not offer. Channel rules segment the
+          # marketplace's own traffic, and the excluded-products rule points at
+          # a catalog picker the seller panel does not have — a seller who will
+          # not ship something does not list it.
+          #
+          # Matched by name rather than by class identity: in development the
+          # registry holds classes from an earlier reload, so comparing
+          # constants silently matches nothing and every kind stays on offer.
+          WITHHELD_RULE_TYPES = %w[
+            Spree::DeliveryMethodRules::ChannelRule
+            Spree::DeliveryMethodRules::ExcludedProductsRule
+          ].freeze
+
+          # The rule kinds a seller may put on their own method.
+          def seller_rule_classes
+            Spree.delivery_method_rules.reject { |klass| WITHHELD_RULE_TYPES.include?(klass.to_s) }
+          end
+
+          # Resolves the marketplace vocabulary a seller picks from, through
+          # the store: a profile or zone that is not this store's is a 404
+          # rather than a validation error, matching how the product form
+          # resolves its own pickers.
+          def assignable_params
+            attributes = permitted_params.except(
+              :delivery_profile_id, :delivery_zone_id, :calculator_type, :calculator_preferences, :rules
+            )
+
+            if params.key?(:delivery_profile_id)
+              attributes[:delivery_profile] = current_store.delivery_profiles.find_by_prefix_id!(params[:delivery_profile_id])
+            end
+
+            if params.key?(:delivery_zone_id)
+              attributes[:delivery_zone] =
+                params[:delivery_zone_id].present? ? current_store.delivery_zones.find_by_prefix_id!(params[:delivery_zone_id]) : nil
+            end
+
+            attributes[:rules] = permitted_rule_rows if params.key?(:rules)
+            attributes
+          end
+
+          # The origin group is derived, never chosen: a seller picks the kind
+          # of goods and where it ships, and which warehouses offer the method
+          # follows from those. The model derives it only on create, so a
+          # profile or zone change here has to re-derive it — otherwise the
+          # row keeps a group the new zone contradicts, and the composition
+          # validation refuses the save.
+          def rederive_origin_group(delivery_method)
+            return unless delivery_method.delivery_profile_id_changed? || delivery_method.delivery_zone_id_changed?
+
+            delivery_method.delivery_origin_group =
+              delivery_method.delivery_zone&.delivery_origin_group ||
+              delivery_method.delivery_profile&.default_origin_group
+          end
+
+          # A rule kind this branch does not offer is refused rather than
+          # dropped: silently ignoring it would report a save the seller can
+          # see did not take.
+          def permitted_rule_rows
+            allowed = seller_rule_classes.map(&:api_type)
+
+            Array(permitted_params[:rules]).map do |row|
+              row = row.to_h
+              raise ActiveRecord::RecordNotFound unless allowed.include?(row['type'].to_s)
+
+              row
+            end
+          end
+
+          def assign_calculator(delivery_method)
+            calculator_type = permitted_params[:calculator_type]
+            preferences = permitted_params[:calculator_preferences]
+
+            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
+              registered = Spree::DeliveryMethod.calculators.find do |klass|
+                klass.api_type == calculator_type
+              end
+              unless registered
+                delivery_method.errors.add(:calculator_type, :invalid)
+                return
+              end
+
+              # Resolved from the registry entry's OWN name, never the
+              # request's: nothing user-supplied reaches `constantize`. Going
+              # back through the name rather than instantiating `registered`
+              # directly is what survives a reload — in development the
+              # registry holds a class from an earlier one, and an instance of
+              # it fails the association's type check.
+              delivery_method.calculator = registered.to_s.constantize.new
+            end
+
+            return if preferences.blank?
+
+            # A payload may carry preferences without naming a calculator —
+            # editing the amount on a method that already has one, or creating
+            # with the default. The model only builds the default calculator
+            # at validation, so without this the preferences land on nothing
+            # and the amount the merchant typed is silently replaced by a free
+            # rate.
+            delivery_method.ensure_calculator
+            return if delivery_method.calculator.nil?
+
+            preferences.each do |key, value|
+              next unless delivery_method.calculator.has_preference?(key)
+
+              delivery_method.calculator.set_preference(key, value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The marketplace's delivery profiles — what kind of goods a product
+        # is (parcel, digital, pallet), which decides how it can be shipped.
+        #
+        # Read only: a seller assigns a profile to their product and never
+        # defines one, since the profile is the vocabulary the marketplace's
+        # zones and methods hang off
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        #
+        # Gated on `read_products` rather than the operator's `settings` key,
+        # which a seller must never hold: this list exists for the product
+        # form's picker, so a key that may read products may read the
+        # vocabulary that form fills in.
+        #
+        # It backs the delivery-method form's picker too, so `delivery_methods`
+        # opens it as well — a member granted only that key would otherwise
+        # load the page and find an empty "kind of goods" list with no way to
+        # create a method.
+        class DeliveryProfilesController < Seller::ResourceController
+          scoped_resource :products
+
+          protected
+
+          # Either key reads this vocabulary. Answers whichever the caller
+          # actually holds so the gate passes for both surfaces; the declared
+          # resource stands as the default, which keeps the fail-closed
+          # behaviour when neither is held.
+          def scoped_resource_name
+            reads_through_delivery_methods? ? :delivery_methods : super
+          end
+
+          # Checked against whichever principal is on the request — a secret
+          # key answers by its scopes, a signed-in member by their role's keys.
+          def reads_through_delivery_methods?
+            return false if holds_key?('read_products')
+
+            holds_key?('read_delivery_methods')
+          end
+
+          def holds_key?(key)
+            return current_api_key.has_scope?(key) if current_api_key.present?
+
+            ability = current_ability
+            ability.respond_to?(:permission_keys) && ability.permission_keys.include?(key)
+          end
+
+          def model_class
+            Spree::DeliveryProfile
+          end
+
+          def serializer_class
+            Spree.api.seller_delivery_profile_serializer
+          end
+
+          def scope
+            current_store.delivery_profiles
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The marketplace's delivery zones — where its methods may ship to.
+        #
+        # Read only: a seller narrows their own method to one of these and
+        # never draws one, because where the marketplace ships is its own
+        # decision (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        #
+        # Filtered by profile through the usual Ransack parameters, so the
+        # panel asks for the zones under the profile a method belongs to.
+        class DeliveryZonesController < Seller::ResourceController
+          scoped_resource :delivery_methods
+
+          protected
+
+          def model_class
+            Spree::DeliveryZone
+          end
+
+          def serializer_class
+            Spree.api.seller_delivery_zone_serializer
+          end
+
+          # `delivery_profile_id` is an explicit filter rather than a Ransack
+          # predicate: a zone only means something under its profile, so the
+          # picker asks for one profile's zones and an id from another store
+          # is a 404 rather than an empty list.
+          def scope
+            zones = current_store.delivery_zones.includes(:delivery_profile)
+            return zones if params[:delivery_profile_id].blank?
+
+            profile = current_store.delivery_profiles.find_by_prefix_id!(params[:delivery_profile_id])
+            zones.where(delivery_profile_id: profile.id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Presigning for a seller's own uploads — today the documents their
+        # onboarding asks for.
+        #
+        # A blob created here is not attached to anything yet: it becomes a
+        # submission only when the seller posts its signed id, and that
+        # endpoint is the one that checks the requirement is theirs. So the
+        # narrowest meaningful gate is the seller's own profile, which every
+        # member of a seller's team holds.
+        class DirectUploadsController < Seller::BaseController
+          include Spree::Api::V3::DirectUploads
+
+          scoped_resource :seller_profile
+        end
+      end
+    end
+  end
+end