spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,95 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What a seller submits about one requirement: an attestation they
+        # tick, a document they upload, a reference they paste.
+        #
+        # Create only. A submission records what was said and when — editing
+        # one would rewrite that history, and withdrawing is not a thing a
+        # seller does: they submit again, and the latest one counts. Accepting,
+        # rejecting and waiving belong to the operator, on their own branch.
+        class RequirementSubmissionsController < Seller::BaseController
+          scoped_resource :seller_profile
+
+          before_action :set_requirement, only: [:create]
+          before_action :set_submission, only: [:download]
+
+          # POST /api/v3/seller/requirements/:requirement_id/submissions
+          def create
+            attributes = permitted_params
+
+            result = Spree.seller_requirement_submission_create_workflow.call(
+              seller: current_seller,
+              requirement: @requirement,
+              note: attributes[:note],
+              reference: attributes[:reference],
+              file: attributes[:file],
+              submitted_by: try_spree_current_user
+            )
+
+            return render_service_error(result.error) unless result.success?
+
+            render json: serialize(result.value), status: :created
+          end
+
+          # GET /api/v3/seller/requirement_submissions/:id/download
+          #
+          # Authorized per request rather than served from a storage URL:
+          # these are identity documents, and a link that works for anyone
+          # holding it is not a property we want them to have.
+          def download
+            unless @submission.file.attached?
+              return render_error(
+                code: ErrorHandler::ERROR_CODES[:validation_error],
+                message: Spree.t(:seller_submission_no_file),
+                status: :unprocessable_content
+              )
+            end
+
+            send_data(
+              @submission.file.download,
+              filename: @submission.file.filename.to_s,
+              type: @submission.file.content_type,
+              disposition: 'attachment'
+            )
+          end
+
+          protected
+
+          # What a seller may say about a requirement. `file` is a direct-upload
+          # signed id, so it is a string like the rest — the bytes are already
+          # in storage by the time this runs.
+          def permitted_params
+            params.permit(:note, :reference, :file)
+          end
+
+          def read_actions
+            %w[download]
+          end
+
+          private
+
+          # Through the store's own checklist: a requirement id belonging to
+          # another marketplace 404s rather than letting a seller submit
+          # against someone else's configuration.
+          def set_requirement
+            @requirement = current_store.seller_requirements.find_by_prefix_id!(params[:requirement_id])
+          end
+
+          # Through the seller, so one seller can never read another's
+          # documents.
+          def set_submission
+            @submission = current_seller.requirement_submissions.find_by_prefix_id!(params[:id])
+          end
+
+          def serialize(submission)
+            Spree.api.seller_requirement_submission_serializer.new(
+              submission, params: { store: current_store }
+            ).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Anchor for seller-facing CRUD.
+        #
+        # Mirrors Seller::BaseController's concerns; any concern added to one
+        # must be added to the other, since they anchor parallel inheritance
+        # branches rather than one chain.
+        class ResourceController < Spree::Api::V3::ResourceController
+          include Spree::Api::V3::Seller::SellerContext
+          include Spree::Api::V3::SellerAuthentication
+          include Spree::Api::V3::ScopedAuthorization
+
+          protected
+
+          def authenticate_request!
+            authenticate_seller!
+          end
+
+          # Every collection is rooted in the seller's own records.
+          #
+          # The inherited implementation roots at `for_store(current_store)`,
+          # which on this branch would hand a seller the whole marketplace —
+          # so subclasses name a `seller_association` and the root scope comes
+          # from the seller itself. Tenancy is this fetch, not the ability:
+          # authorizing without it reads store-wide.
+          #
+          # Tenancy is all this roots, though — it does not judge whether a
+          # record is the seller's business. A controller reaching orders must
+          # also exclude drafts, which `current_seller_orders` does.
+          def scope
+            return super if @parent.present?
+
+            base_scope = current_seller.public_send(seller_association)
+            base_scope = base_scope.includes(scope_includes) if scope_includes.any?
+            base_scope = base_scope.preload_associations_lazily
+            model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
+          end
+
+          # A new record is this seller's, whatever the payload says, and its
+          # store follows the seller rather than the request.
+          def resource_scope
+            return super if @parent.present?
+
+            current_seller.public_send(seller_association)
+          end
+
+          def build_resource
+            resource = super
+            resource.store = current_store if resource.respond_to?(:store=)
+            resource
+          end
+
+          # The seller association this controller reads through, defaulting to
+          # the model's plural name (`Spree::Product` -> `products`). Override
+          # when the association is named differently.
+          #
+          # @return [Symbol]
+          def seller_association
+            model_class.table_name.delete_prefix('spree_').to_sym
+          end
+
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            authorize!(action, resource)
+          end
+
+          def authorize_parent!(parent)
+            authorize!(parent_ability_action, parent)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Why goods come back.
+        class ReturnReasonsController < ReasonsController
+          protected
+
+          def model_class
+            Spree::ReturnReason
+          end
+
+          def reasons_association
+            :return_reasons
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A seller's own stock locations — where their inventory sits and
+        # where customer returns are sent.
+        #
+        # Rooted in `current_seller.stock_locations`, so an id belonging to
+        # the operator or to another seller is a 404. That matters more here
+        # than on most collections: a stock location is an address a shopper
+        # is given, and the operator's warehouse address is not a seller's to
+        # read or to hand out.
+        #
+        # No destroy: a location holds stock levels and is named on historical
+        # fulfillments, so removing one is an inventory operation rather than
+        # a delete. A seller retires a location by deactivating it.
+        class StockLocationsController < Seller::ResourceController
+          # `:stock`, the catalog resource that lists `Spree::StockLocation`
+          # among its subjects — there is no `stock_locations` resource, and a
+          # name the catalog does not know skips the key gate entirely rather
+          # than failing loudly. Writes take `write_stock` here where the
+          # operator's twin takes `write_settings`: another seller's warehouse
+          # is store-wide administration, but a seller's own is just their
+          # stock.
+          scoped_resource :stock
+
+          protected
+
+          def model_class
+            Spree::StockLocation
+          end
+
+          def serializer_class
+            Spree.api.seller_stock_location_serializer
+          end
+
+          # The same set the operator's controller permits: a seller runs
+          # their own warehouse, so every field on the shared form is theirs to
+          # set. Anything missing here is dropped by `permit` without a word,
+          # and the form would appear to save while quietly discarding it.
+          def permitted_params
+            params.permit(
+              *model_additional_permitted_attributes,
+              :name, :admin_name, :active, :default,
+              :kind, :propagate_all_variants, :backorderable_default,
+              :address1, :address2, :city, :zipcode, :phone, :company,
+              :country_code, :state_code, :state_name,
+              :pickup_enabled, :pickup_stock_policy, :returns_enabled,
+              :pickup_ready_in_minutes, :pickup_instructions
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The seller's own tax registrations — the numbers the marketplace's
+        # commission invoice is made out to, and what makes EU reverse charge
+        # on that fee possible.
+        #
+        # A collection rather than a single field, for the same reason a
+        # company's is: a business trading in more than one regime holds a
+        # registration in each, and they are not alternatives. One per kind,
+        # which the model enforces.
+        #
+        # Rooted in `current_seller.tax_identifiers`, so an id belonging to
+        # another seller is a 404.
+        class TaxIdentifiersController < Seller::ResourceController
+          include Spree::Api::V3::TaxIdentifierValidation
+
+          # Part of the seller's own identity, like the legal name and billing
+          # address the profile carries — not a store-wide setting.
+          scoped_resource :seller_profile
+
+          # Re-declaring the filter replaces the inherited options, so the
+          # standard actions have to be listed alongside the custom one.
+          before_action :set_resource, only: [:show, :update, :destroy, :validate]
+
+          protected
+
+          def model_class
+            Spree::TaxIdentifier
+          end
+
+          def serializer_class
+            Spree.api.seller_tax_identifier_serializer
+          end
+
+          def seller_association
+            :tax_identifiers
+          end
+
+          def permitted_params
+            params.permit(:kind, :value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The people who run this seller.
+        #
+        # Rooted at `current_seller` throughout, so a seller can only ever see
+        # and change their own team. Inviting reuses the workflow the operator
+        # calls, which means one invitation rail and one set of hooks.
+        #
+        # No custom roles: every member holds the seller's own seeded admin
+        # role, which already carries the whole seller vocabulary. Splitting
+        # that into narrower roles is a design of its own.
+        class TeamController < Seller::BaseController
+          scoped_resource :seller_profile
+
+          before_action :set_member, only: [:destroy]
+
+          def index
+            render json: { data: members.map { |member| serialize_member(member) } }
+          end
+
+          # Invites a colleague onto this seller's team. They join when they
+          # accept, on the same invitation rail — and same email — the
+          # marketplace operator's invitations use.
+          #
+          # Not `Spree::Sellers::Invite`: that workflow means "open this seller
+          # for its first owner" and moves the seller to `invited`. A trading
+          # seller's status must not flip because someone hired staff, and the
+          # workflow rightly refuses an approved seller. Hiring is not a
+          # lifecycle transition.
+          def create
+            invitation = current_seller.invitations.new(
+              email: params[:email],
+              role: current_seller.default_user_role,
+              inviter: try_spree_current_user
+            )
+
+            if invitation.save
+              render json: serialize_invitation(invitation), status: :created
+            else
+              render_validation_error(invitation.errors)
+            end
+          end
+
+          # Revokes a member's access. The seller keeps at least one member:
+          # emptying the team would leave a seller nobody can sign in to, and
+          # only the operator could put someone back.
+          #
+          # Counted and removed under a lock on the seller. Unlocked, two
+          # concurrent deletes against a two-member team both see two and both
+          # proceed — the one state this endpoint exists to prevent, and one a
+          # seller cannot repair themselves.
+          def destroy
+            removed = current_seller.with_lock do
+              # `distinct`: `users` reaches through role_users, so a member
+              # holding two roles on this seller is counted twice — while
+              # `remove_user` deletes every one of their roles at once. Without
+              # it, a two-role seller with one person reads as a team of two
+              # and this check would let them remove themselves.
+              next false if current_seller.users.distinct.count <= 1
+
+              current_seller.remove_user(@member)
+              true
+            end
+
+            return head :no_content if removed
+
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:processing_error],
+              message: Spree.t(:seller_team_last_member),
+              status: :unprocessable_content
+            )
+          end
+
+          protected
+
+          def read_actions
+            %w[index]
+          end
+
+          private
+
+          def members
+            @members ||= current_seller.users.to_a
+          end
+
+          def set_member
+            @member = current_seller.users.find_by_prefix_id!(params[:id])
+          end
+
+          def serialize_member(member)
+            Spree.api.seller_team_member_serializer.new(member, params: { store: current_store }).to_h
+          end
+
+          def serialize_invitation(invitation)
+            Spree.api.seller_invitation_serializer.new(invitation, params: { store: current_store }).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The registered carriers a tracking number can be pinned to.
+        #
+        # Registry data (`Spree.tracking_carriers`) rather than store records,
+        # so the seller's carrier picker renders from the same list the
+        # operator's does and a carrier added by an extension appears without
+        # a client change. Gated by `fulfillments`: a seller reads these while
+        # marking a parcel sent.
+        class TrackingCarriersController < Seller::BaseController
+          scoped_resource :fulfillments
+
+          # GET /api/v3/seller/tracking_carriers
+          def index
+            authorize! :update, Spree::Fulfillment
+
+            data = Spree.tracking_carriers.map do |slug, carrier|
+              { id: slug, name: carrier[:name] }
+            end
+
+            render json: { data: data.sort_by { |carrier| carrier[:name] } }
+          end
+
+          protected
+
+          def read_actions
+            %w[index]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What this seller has earned, order by order.
+        #
+        # Read-only: a transfer records money that moved, or is moving, and
+        # what corrects it is a reversal — another row, written by the refund
+        # — rather than an edit. Rooted in `current_seller.seller_transfers`,
+        # so another seller's row is a 404 by construction.
+        class TransfersController < Seller::ResourceController
+          scoped_resource :seller_earnings
+
+          protected
+
+          def model_class
+            Spree::SellerTransfer
+          end
+
+          def serializer_class
+            Spree.api.seller_transfer_serializer
+          end
+
+          def scope
+            super.order(created_at: :desc)
+          end
+
+          def collection_includes
+            [:order, :payout, :reversed_from]
+          end
+
+          # The ledger classes belong to `payouts`, the operator's key, which a
+          # seller never holds. The question this endpoint asks is "may this
+          # seller read their own books", which is what `:seller_earnings`
+          # answers; which rows are theirs is the scope above.
+          def authorize_resource!(_resource = @resource, action = action_name.to_sym)
+            authorize!(action, :seller_earnings)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Account
+          # The signed-in buyer's company memberships — each with its node and
+          # ancestor path, so an account page can offer "buying for" choices
+          # in one request.
+          class CompaniesController < ResourceController
+            prepend_before_action :require_authentication!
+
+            # GET /api/v3/store/account/companies
+            def index
+              memberships = current_user.company_memberships.
+                            joins(:company).
+                            merge(Spree::Company.where(store_id: current_store.id)).
+                            includes(company: :parent)
+
+              render json: {
+                'data' => memberships.map do |membership|
+                  Spree.api.company_membership_serializer.new(membership, params: serializer_params).to_h.merge(
+                    'company' => Spree.api.company_serializer.new(membership.company, params: serializer_params).to_h
+                  )
+                end
+              }
+            end
+
+            protected
+
+            def model_class
+              Spree::CompanyMembership
+            end
+
+            def serializer_class
+              Spree.api.company_membership_serializer
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,11 +3,16 @@ module Spree
     module V3
       module Store
         class AuthController < Store::BaseController
+          include Spree::Api::V3::AuthenticationStrategies
+
           allow_guest_storefront_access!
-          # Tighter rate limits for auth endpoints (per IP to prevent brute force)
-          rate_limit to: Spree::Api::Config[:rate_limit_login], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :logout, with: RATE_LIMIT_RESPONSE
+          # Tighter rate limits for auth endpoints (per IP to prevent brute
+          # force). Distinct `name:` per declaration — without one, Rails keys
+          # every counter in this controller on the same (controller, client)
+          # cache entry, silently merging the budgets.
+          rate_limit to: Spree::Api::Config[:rate_limit_login], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :create, name: '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: :refresh, name: 'refresh', 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: :logout, name: 'logout', with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_refresh]) }
 
           skip_before_action :authenticate_user, only: [:create, :refresh, :logout]
 
@@ -17,7 +22,7 @@ module Spree
           #   { "provider": "email", "email": "...", "password": "..." }
           def create
             strategy = authentication_strategy
-            return unless strategy # Error already rendered by determine_strategy
+            return unless strategy # Error already rendered by authentication_strategy
 
             result = strategy.authenticate
 
@@ -47,7 +52,7 @@ module Spree
               )
             end
 
-            refresh_token = Spree::RefreshToken.active.find_by(token: refresh_token_value)
+            refresh_token = Spree::RefreshToken.active.for_audience(JWT_AUDIENCE_STORE).find_by(token: refresh_token_value)
 
             if refresh_token.nil?
               return render_error(
@@ -71,11 +76,14 @@ module Spree
           # Accepts: { "refresh_token": "rt_xxx" }
           # Revokes the submitted refresh token. The token itself is the
           # credential — no access JWT is required, so clients with an expired
-          # access token can still log out.
+          # access token can still log out. Narrowed to this surface's own
+          # tokens: ending a session belongs to the surface that started it.
           def logout
             refresh_token_value = params[:refresh_token]
 
-            Spree::RefreshToken.find_by(token: refresh_token_value)&.destroy if refresh_token_value.present?
+            if refresh_token_value.present?
+              Spree::RefreshToken.for_audience(JWT_AUDIENCE_STORE).find_by(token: refresh_token_value)&.destroy
+            end
 
             head :no_content
           end
@@ -96,7 +104,7 @@ module Spree
           private
 
           def auth_response(user)
-            refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+            refresh_token = Spree::RefreshToken.create_for(user, audience: JWT_AUDIENCE_STORE, request_env: request_env_for_token)
 
             {
               token: generate_jwt(user),
@@ -112,33 +120,12 @@ module Spree
             }
           end
 
-          def authentication_strategy
-            strategy_class = determine_strategy
-            return nil unless strategy_class
-
-            strategy_class.new(
-              params: params,
-              request_env: request.headers.env,
-              user_class: Spree.user_class
-            )
+          def authentication_strategies
+            Spree.store_authentication_strategies
           end
 
-          def determine_strategy
-            provider = params[:provider].presence || 'email'
-
-            # Retrieve pre-loaded strategy class from configuration
-            strategy_class = Spree.store_authentication_strategies[provider]
-
-            unless strategy_class
-              render_error(
-                code: ERROR_CODES[:invalid_provider],
-                message: "Unsupported authentication provider: #{provider}",
-                status: :bad_request
-              )
-              return nil
-            end
-
-            strategy_class
+          def authentication_user_class
+            Spree.customer_class
           end
 
           def user_serializer

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

@@ -3,6 +3,9 @@ module Spree
     module V3
       module Store
         class BaseController < Spree::Api::V3::BaseController
+          # The publishable key selects the store — must come before
+          # ChannelResolution, whose store-context callback reads it.
+          include Spree::Api::V3::KeyStoreContext
           # Channel resolution is a Store API concern — admin endpoints return
           # data across all channels and filter via Ransack instead. Including
           # this here keeps the +X-Spree-Channel+ header from accidentally
@@ -13,6 +16,7 @@ module Spree
           # ResourceController ones. Public endpoints opt out with
           # +allow_guest_storefront_access!+.
           include Spree::Api::V3::StorefrontGating
+          include Spree::Api::V3::StorefrontAccess
 
           # Require publishable API key for all Store API requests. Prepended so
           # the key is authenticated BEFORE ChannelResolution's