spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,152 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Public invitation acceptance for the seller panel — mounted under
+        # `/api/v3/seller/auth/...` so the issued refresh-token cookie's path
+        # matches `/auth/refresh`.
+        #
+        # Parallel to the admin controller rather than a subclass of it, per
+        # Decision 10: what differs is the audience it issues and the
+        # invitations it will touch, and both are the point.
+        class InvitationAcceptancesController < Spree::Api::V3::BaseController
+          include Spree::Api::V3::Seller::AuthCookies
+          include Spree::Api::V3::JwtAuthentication
+
+          # No `skip_scope_check!`: this extends the plain v3 base, which has
+          # no authentication or scope gate to lift. The emailed token is the
+          # only credential, exactly as on the admin twin.
+          rate_limit to: Spree::Api::Config[:rate_limit_login],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     only: [:lookup, :accept],
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
+
+          # GET /api/v3/seller/auth/invitations/:id/lookup?token=:token
+          def lookup
+            return unless load_invitation
+
+            render json: Spree.api.seller_invitation_serializer.new(
+              @invitation, params: { store: @invitation.store }
+            ).serializable_hash
+          end
+
+          # POST /api/v3/seller/auth/invitations/:id/accept?token=:token
+          # Body: { password?, password_confirmation?, first_name?, last_name? }
+          def accept
+            return unless load_invitation
+
+            user = resolve_or_create_invitee(@invitation)
+            return if performed?
+
+            @invitation.invitee = user
+            result = Spree.invitation_accept_workflow.call(invitation: @invitation)
+
+            return render_service_error(result.error) unless result.success?
+
+            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
+
+          private
+
+          # Only invitations onto a seller are acceptable here. A staff
+          # invitation carries no seller membership, so accepting one through
+          # this endpoint would mint a seller token for someone who runs no
+          # seller — and it is indistinguishable from "not found" on purpose,
+          # since the caller is unauthenticated either way.
+          #
+          # Token mismatch is treated identically to "not found" to avoid
+          # leaking whether an ID exists.
+          def load_invitation
+            decoded_id = Spree::Invitation.decode_prefixed_id(params[:id])
+            @invitation = Spree::Invitation.pending.not_expired.
+                          where(resource_type: Spree::Seller.to_s).
+                          find_by(id: decoded_id, token: params[:token])
+
+            unless @invitation
+              render_error(
+                code: ErrorHandler::ERROR_CODES[:record_not_found],
+                message: Spree.t(:invitation_not_acceptable),
+                status: :not_found
+              )
+              return false
+            end
+
+            true
+          end
+
+          # Email match between the invitation and any existing account is
+          # implicit: we look the user up by `invitation.email`, never by a
+          # client-supplied email. The token is the credential.
+          def resolve_or_create_invitee(invitation)
+            existing = Spree.admin_user_class.find_by(email: invitation.email)
+            return authenticate_existing(existing) if existing
+
+            create_new_invitee(invitation)
+          end
+
+          def authenticate_existing(user)
+            return user if user.valid_password?(params[:password].to_s)
+
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:authentication_failed],
+              message: Spree.t(:invalid_password),
+              status: :unauthorized
+            )
+            nil
+          end
+
+          def create_new_invitee(invitation)
+            if params[:password].blank?
+              render_error(
+                code: ErrorHandler::ERROR_CODES[:parameter_missing],
+                message: Spree.t(:password_required_to_create_account),
+                status: :unprocessable_content
+              )
+              return nil
+            end
+
+            Spree.admin_user_class.create!(signup_params(invitation))
+          end
+
+          def signup_params(invitation)
+            params.permit(:password, :password_confirmation, :first_name, :last_name).
+              merge(email: invitation.email)
+          end
+
+          # Same shape as the login response, so the panel can sign the new
+          # member straight in rather than bouncing them to a login form.
+          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: @invitation.store }
+              ).to_h,
+              sellers: serialized_sellers(user)
+            }
+          end
+
+          def serialized_sellers(user)
+            user.sellers.map { |seller| { id: seller.prefixed_id, name: seller.name, status: seller.status } }
+          end
+
+          def request_env_for_token
+            { ip_address: request.remote_ip, user_agent: request.user_agent&.truncate(255) }
+          end
+
+          def jwt_expiration
+            Spree::Api::Config[:admin_jwt_expiration]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Invitations this seller has sent that nobody has accepted yet.
+        #
+        # Separate from `TeamController` because they are different things: a
+        # member is a person who can sign in, an invitation is an offer that
+        # may lapse. Creating one still belongs to the team endpoint — hiring
+        # is what the seller is doing — while chasing or withdrawing one is
+        # bookkeeping on the offer itself.
+        #
+        # Rooted at `current_seller.invitations` throughout, so a seller can
+        # neither see nor touch an invitation sent by anyone else.
+        class InvitationsController < Seller::BaseController
+          scoped_resource :seller_profile
+
+          before_action :set_invitation, only: [:destroy, :resend]
+
+          # Pending only: an accepted invitation is a team member, and the
+          # panel already lists those.
+          def index
+            invitations = current_seller.invitations.pending.order(created_at: :desc)
+
+            render json: { data: invitations.map { |invitation| serialize(invitation) } }
+          end
+
+          # Withdraws an offer that has not been accepted.
+          def destroy
+            @invitation.destroy
+            head :no_content
+          end
+
+          # Sends the invitation email again, for a colleague who never got
+          # the first one. The model refuses once the invitation has expired
+          # or been accepted, and says so rather than silently doing nothing.
+          def resend
+            if @invitation.expired?
+              return render_error(
+                code: ErrorHandler::ERROR_CODES[:processing_error],
+                message: Spree.t(:invitation_expired),
+                status: :unprocessable_content
+              )
+            end
+
+            @invitation.resend!
+            render json: serialize(@invitation)
+          end
+
+          protected
+
+          def read_actions
+            %w[index]
+          end
+
+          private
+
+          def set_invitation
+            @invitation = current_seller.invitations.pending.find_by_prefix_id!(params[:id])
+          end
+
+          def serialize(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/me_controller.rb

@@ -0,0 +1,72 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The signed-in seller: who they are, which sellers they act for, and
+        # what they may do on the selected one.
+        #
+        # Structurally exempt from seller scoping — this is what tells the
+        # panel which X-Spree-Seller-Id to send, so it has to answer before one
+        # is chosen. Sending the header still narrows `permission_keys` to that
+        # seller.
+        class MeController < Seller::BaseController
+          include Spree::Api::V3::PermissionSerialization
+
+          skip_scope_check!
+          skip_before_action :set_current_seller_context
+          before_action :require_current_user!
+
+          def show
+            render json: me_response
+          end
+
+          private
+
+          def me_response
+            {
+              user: Spree.api.seller_team_member_serializer.new(current_user, params: serializer_params).to_h,
+              sellers: serialized_sellers,
+              # Both shapes, exactly as the admin `/me`: the panel's `<Can>`
+              # reads CanCanCan rules, the key gate reads keys. Sending only
+              # keys left `<Can>` answering false for everything on the seller
+              # panel — silently, since nothing gated on it yet.
+              permissions: serialize_permissions(seller_ability),
+              permission_keys: serialize_permission_keys(seller_ability)
+            }
+          end
+
+          def serialized_sellers
+            current_user.sellers.map do |seller|
+              { id: seller.prefixed_id, name: seller.name, slug: seller.slug, status: seller.status }
+            end
+          end
+
+          # Empty until a seller is named: capability is per seller, so there is
+          # no meaningful answer spanning all of them. A bare ability (no
+          # resource) serializes to nothing rather than raising, so the panel
+          # can call `/me` before choosing a seller.
+          def seller_ability
+            return Spree::Ability.new(nil) if current_seller.nil?
+
+            current_ability
+          end
+
+          def serializer_params
+            { store: current_store || current_user.sellers.first&.store }
+          end
+
+          def require_current_user!
+            return true if current_user
+
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:record_not_found],
+              message: Spree.t(:me_no_current_user),
+              status: :not_found
+            )
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What the marketplace asks of this seller, and how far along they are.
+        #
+        # Singular by nature: there is exactly one seller in play and it is
+        # `current_seller`, never an id from the request. The checklist is
+        # computed on read through the one evaluator the operator's view and
+        # the approval gate also use, so the panel and the operator can never
+        # be looking at different answers.
+        class OnboardingController < Seller::BaseController
+          scoped_resource :seller_profile
+
+          # GET /api/v3/seller/onboarding
+          def show
+            render json: onboarding_payload
+          end
+
+          # POST /api/v3/seller/onboarding/submit_for_review
+          #
+          # The seller says they are ready. Refused with the blocking
+          # requirements named — a bare "not ready" leaves them guessing which
+          # of eight things it meant.
+          def submit_for_review
+            result = Spree.seller_submit_for_review_workflow.call(
+              seller: current_seller,
+              submitted_by: try_spree_current_user
+            )
+
+            return render_service_error(result.error) unless result.success?
+
+            render json: onboarding_payload
+          end
+
+          # POST /api/v3/seller/onboarding/payout_account
+          #
+          # A fresh link to wherever the provider collects what it needs before
+          # it will pay this seller. Minted per request rather than rendered
+          # with the checklist, because these links are short-lived and
+          # single-use — one made while drawing a page is often dead by the
+          # time the seller clicks it.
+          #
+          # The panel says where to come back to. Core does not know the
+          # panel's routes, and a marketplace may host it anywhere.
+          def payout_account
+            provider = current_store.payout_provider_instance
+            url = provider.onboarding_url(
+              current_seller,
+              refresh_url: panel_url(params.require(:refresh_url)),
+              return_url: panel_url(params.require(:return_url))
+            )
+
+            # A null link rather than an empty response: the panel has to tell
+            # "this provider hosts nothing" from "the request failed", and a
+            # 204 makes the client infer that from an absence.
+            render json: { url: url.presence }
+          rescue Spree::Core::GatewayError => e
+            render_service_error(e.message)
+          end
+
+          protected
+
+          def read_actions
+            %w[show]
+          end
+
+          private
+
+          # Where a provider may send the seller back to.
+          #
+          # Checked against the panel's own origin rather than echoed: a seller
+          # could otherwise name any address and turn the marketplace's genuine
+          # provider flow into a redirect to a page of their choosing, which is
+          # a convincing place to ask somebody for credentials. Anything else
+          # falls back to the panel's own root.
+          def panel_url(candidate)
+            panel = Spree::Sellers::PanelUrl.call(store: current_store)
+            return panel if candidate.blank?
+
+            uri = URI.parse(candidate.to_s)
+            allowed = URI.parse(panel)
+
+            same_origin = uri.scheme == allowed.scheme && uri.host == allowed.host && uri.port == allowed.port
+            same_origin ? candidate.to_s : panel
+          rescue URI::InvalidURIError
+            panel
+          end
+
+          def requirements
+            @requirements ||= Spree::Sellers::Requirements.new(current_seller.reload)
+          end
+
+          def onboarding_payload
+            {
+              status: current_seller.status,
+              progress: requirements.progress,
+              requirements: requirements.statuses.map { |status| serialize_status(status) }
+            }
+          end
+
+          def serialize_status(status)
+            Spree.api.seller_requirement_status_serializer.new(
+              status, params: { store: current_store }
+            ).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Why an order was called off.
+        #
+        # Read-only here, like the other vocabularies, but gated by `orders`
+        # rather than the `settings` key the operator's own CRUD sits behind —
+        # `settings` is never seller-grantable, and a seller cancelling their
+        # own order needs to name a reason from the marketplace's list.
+        class OrderCancellationReasonsController < ReasonsController
+          protected
+
+          def model_class
+            Spree::OrderCancellationReason
+          end
+
+          def reasons_association
+            :order_cancellation_reasons
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # Anchor for everything nested under one of this seller's orders.
+          #
+          # Mirrors Admin::Orders::BaseController: the parent order is fetched
+          # once here rather than in each controller. The difference is the
+          # root — `current_seller_orders`, which is the seller's own orders
+          # minus drafts, since neither an in-flight checkout nor the
+          # operator's working document is this seller's to act on.
+          #
+          # Deliberately not a subclass of the admin base: that one resolves
+          # through `current_store`, and inheriting its lookups is precisely
+          # how a seller would come to read the whole marketplace.
+          class BaseController < Seller::ResourceController
+            include Spree::Api::V3::OrderLock
+
+            before_action :authorize_order_access!
+
+            scoped_resource :orders
+
+            protected
+
+            def set_parent
+              @parent = current_seller_orders.find_by_prefix_id!(params[:order_id])
+              @order = @parent
+            end
+
+            # Reads need only `:show` on the order; every write needs
+            # `:update`, so a seller who may only view an order cannot ship,
+            # refund or cancel against it. Derived from +read_actions+ rather
+            # than a hand-kept list, so a new write action is a write by
+            # default instead of silently unauthorized.
+            def authorize_order_access!
+              authorize_parent!(@parent)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # Something went wrong with a delivery on one of this seller's
+          # orders, and the seller makes it right.
+          #
+          # The workflows are the operator's, shared through the concern, so a
+          # claim settled here credits and restocks exactly as it does when
+          # the marketplace handles it. What is here is what makes it the
+          # seller's: the order comes from `current_seller_orders`, so a claim
+          # on somebody else's order reads as missing rather than denied, and
+          # a replacement may only be promised out of this seller's catalogue.
+          class ClaimsController < BaseController
+            include Spree::Api::V3::Orders::ClaimActions
+
+            before_action :set_resource, only: [:show, :approve, :resolve, :deny, :cancel]
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_claim_serializer
+            end
+
+            def collection_includes
+              [:reason, { claim_line_items: [:variant, :line_item, :replacement_variant] }]
+            end
+
+            private
+
+            # The seller's own catalogue: a replacement is stock this seller
+            # sends, so a variant belonging to another seller is not theirs to
+            # promise.
+            def replacement_variant_for(variant_id)
+              return nil if variant_id.blank?
+
+              current_seller.variants.find_by_prefix_id!(variant_id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders/deliveries_controller.rb

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # The consignments on a parcel the seller ships themselves.
+          #
+          # CRUD is shared with the operator's branch through the concern.
+          # What is here is what makes it the seller's: the order comes from
+          # `current_seller_orders`, so a fulfillment on somebody else's order
+          # reads as missing rather than denied.
+          #
+          # No `mark_delivered`: that a parcel arrived is the buyer's word,
+          # not the sender's, so confirming receipt stays with the operator
+          # and the carrier feed.
+          class DeliveriesController < BaseController
+            include Spree::Api::V3::Orders::DeliveryActions
+
+            before_action :set_resource, only: [:show, :update, :destroy]
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_delivery_serializer
+            end
+
+            # The labels and consignments hang off the fulfillment, not the
+            # order, so the parent is narrowed one step past the base's.
+            def set_parent
+              super
+              @parent = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders/exchanges_controller.rb

@@ -0,0 +1,50 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # Swapping goods on one of this seller's orders — a different size,
+          # colour or product.
+          #
+          # The workflows are the operator's, shared through the concern. What
+          # is here is what makes it the seller's: the order comes from
+          # `current_seller_orders`, and the replacement variant is resolved
+          # through `current_seller.variants` rather than the store's, because
+          # a seller exchanges into their own catalogue and reaching a rival's
+          # variant here would put that seller's stock on this seller's order.
+          class ExchangesController < BaseController
+            include Spree::Api::V3::Orders::ExchangeActions
+
+            before_action :set_resource, only: [:show, :approve, :receive, :fulfill, :cancel]
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_exchange_serializer
+            end
+
+            def collection_includes
+              [:reason, :stock_location,
+               { exchange_line_items: [:original_variant, :new_variant, :line_item] }]
+            end
+
+            private
+
+            # The seller's own catalogue and their own shelves — a rival's
+            # variant is not theirs to send, nor a marketplace warehouse
+            # theirs to restock.
+            def replacement_variant_for(variant_id)
+              current_seller.variants.find_by_prefix_id!(variant_id)
+            end
+
+            def stock_location_for_create
+              return nil if create_params[:stock_location_id].blank?
+
+              current_seller.stock_locations.find_by_prefix_id!(create_params[:stock_location_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb

@@ -0,0 +1,79 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # The parcels this seller owes on one of their orders.
+          #
+          # Shipping, cancelling and splitting are the operator's workflows,
+          # shared through the concern, so the customer email, the label
+          # purchase and the extension hooks all happen exactly as they do
+          # when the marketplace ships on the seller's behalf.
+          #
+          # What is here is what makes them the seller's: the order comes from
+          # `current_seller_orders`, so a fulfillment on somebody else's order
+          # reads as missing rather than denied, and both the goods that may
+          # be split and the shelves they ship from are the seller's own.
+          #
+          # No `mark_delivered` and no `create`: that goods arrived is the
+          # buyer's word rather than the sender's, and a parcel comes into
+          # being from the order, not from the seller.
+          class FulfillmentsController < BaseController
+            include Spree::Api::V3::Orders::FulfillmentActions
+
+            before_action :set_resource, only: [:show, :update, :fulfill, :cancel, :split]
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_fulfillment_serializer
+            end
+
+            def collection_includes
+              [:deliveries, :shipping_labels, :fulfillment_items]
+            end
+
+            def permitted_params
+              params.permit(:tracking, :tracking_carrier, :stock_location_id,
+                            :selected_delivery_rate_id)
+            end
+
+            private
+
+            # What may be split out is what this parcel is actually carrying,
+            # resolved through the order rather than the catalogue.
+            def variant_for_split
+              @order.variants.find_by_prefix_id!(params[:variant_id])
+            end
+
+            # The seller's own shelves only — defaulting to where this parcel
+            # already sits.
+            def stock_location_for_split
+              return @resource.stock_location if params[:stock_location_id].blank?
+
+              seller_stock_location!(params[:stock_location_id])
+            end
+
+            # The workflow assigns the origin raw, so the prefixed id is
+            # resolved through the seller's own shelves first — a marketplace
+            # warehouse 404s here rather than reaching the assignment.
+            def update_attributes
+              attributes = permitted_params.to_h
+
+              if permitted_params[:stock_location_id].present?
+                attributes['stock_location_id'] =
+                  seller_stock_location!(permitted_params[:stock_location_id]).id
+              end
+
+              attributes
+            end
+
+            def seller_stock_location!(id)
+              current_seller.stock_locations.find_by_prefix_id!(id)
+            end
+          end
+        end
+      end
+    end
+  end
+end