spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/spree/api/v3/admin/sellers/balances_controller.rb

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Sellers
+          # Where one seller stands with the marketplace, one row per currency:
+          # earned, paid, still owed, and earnings the provider has not yet
+          # confirmed.
+          #
+          # Under `payouts` rather than `sellers`: it is the ledger read from
+          # the seller's side, and a finance operator reads it without holding
+          # the key that edits sellers.
+          class BalancesController < Admin::BaseController
+            scoped_resource :payouts
+
+            before_action :set_seller
+
+            # GET /api/v3/admin/sellers/:seller_id/balances
+            def index
+              render json: { data: @seller.balances.map { |balance| serialize_balance(balance) } }
+            end
+
+            protected
+
+            def read_actions
+              %w[index]
+            end
+
+            private
+
+            def set_seller
+              @seller = current_store.sellers.find_by_prefix_id!(params[:seller_id])
+              authorize! :index, Spree::SellerTransfer
+            end
+
+            def serialize_balance(balance)
+              Spree.api.admin_seller_balance_serializer.new(balance, params: { store: current_store }).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/sellers/invitations_controller.rb

@@ -0,0 +1,77 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Sellers
+          # Offers to join one of the marketplace's sellers that nobody has
+          # accepted yet.
+          #
+          # The operator's counterpart to the seller panel's own invitations
+          # endpoint, and rooted the same way — at the seller's invitations, so
+          # an id from another seller reads as missing rather than as denied.
+          #
+          # Creating one is the `invite` action on the seller itself; what is
+          # here is the bookkeeping the operator needs when an offer went to
+          # the wrong address or never arrived.
+          class InvitationsController < Admin::BaseController
+            scoped_resource :sellers
+
+            before_action :set_seller
+            before_action :set_invitation, only: [:destroy, :resend]
+
+            # Pending only: an accepted invitation is a team member, which the
+            # team endpoint lists.
+            def index
+              invitations = @seller.invitations.pending.order(created_at: :desc)
+
+              render json: { data: invitations.map { |invitation| serialize(invitation) } }
+            end
+
+            def destroy
+              @invitation.destroy
+              head :no_content
+            end
+
+            # Sends the email again. The model refuses once the invitation has
+            # expired, 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_seller
+              @seller = current_store.sellers.find_by_prefix_id!(params[:seller_id])
+              authorize! :show, @seller
+            end
+
+            def set_invitation
+              @invitation = @seller.invitations.pending.find_by_prefix_id!(params[:id])
+            end
+
+            def serialize(invitation)
+              Spree.api.admin_invitation_serializer.new(
+                invitation, params: { store: current_store }
+              ).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rb

@@ -0,0 +1,107 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Sellers
+          # Settling one seller by hand.
+          #
+          # The scheduled sweep runs on each seller's own interval and skips
+          # anyone set to `manual` — that setting means "the operator decides
+          # when", and this is where they decide it. It is open to every seller
+          # rather than only the manual ones, because paying someone early is
+          # a reasonable thing to want and the sweep claims transfers inside a
+          # transaction, so a hand-run racing the scheduled one cannot settle
+          # the same earning twice.
+          #
+          # One payout per currency the seller is owed in: nothing is ever
+          # converted between them, so a seller trading in two is settled in
+          # each.
+          class PayoutsController < Admin::BaseController
+            scoped_resource :payouts
+
+            before_action :set_seller
+
+            # POST /api/v3/admin/sellers/:seller_id/payouts
+            def create
+              settled, failures = sweep_each_currency
+
+              if settled.any?
+                # A provider that refused one currency must not be silent just
+                # because another went through: the payout row exists and is
+                # failed or unresolved, and an operator reading "settled" would
+                # not know to go looking for it.
+                body = { data: settled.map { |payout| serialize_payout(payout) } }
+                body[:meta] = { failures: failures } if failures.any?
+
+                render json: body, status: :created
+              elsif failures.any?
+                render_error(
+                  code: ErrorHandler::ERROR_CODES[:validation_error],
+                  message: failures.map { |failure| failure[:message] }.join(' '),
+                  status: :unprocessable_content
+                )
+              else
+                # Every guard the sweep applies — no payout account, nothing
+                # unsettled, below the seller's minimum — ends the same way
+                # from here: there was nothing to send. Saying so is more use
+                # than a success that produced no payout.
+                render_error(
+                  code: ErrorHandler::ERROR_CODES[:validation_error],
+                  message: Spree.t(:seller_payout_nothing_to_settle),
+                  status: :unprocessable_content
+                )
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::SellerPayout
+            end
+
+            private
+
+            def set_seller
+              @seller = current_store.sellers.find_by_prefix_id!(params[:seller_id])
+              authorize! :update, Spree::SellerPayout
+            end
+
+            # Three outcomes per currency, and they are not interchangeable.
+            #
+            # A halted sweep answers *successfully* with the seller rather than
+            # a payout — that is how the workflow says "nothing to settle" — so
+            # a type check is what separates it from a real settlement. A
+            # failed one means the provider refused after a payout row was
+            # written, which is the outcome an operator most needs told.
+            #
+            # @return [Array(Array<Spree::SellerPayout>, Array<Hash>)]
+            def sweep_each_currency
+              settled = []
+              failures = []
+
+              currencies_owed.each do |currency|
+                result = Spree.seller_payout_sweep_workflow.call(seller: @seller, currency: currency)
+
+                if !result.success?
+                  failures << { currency: currency, message: result.error.to_s }
+                elsif result.value.is_a?(Spree::SellerPayout)
+                  settled << result.value
+                end
+              end
+
+              [settled, failures]
+            end
+
+            def currencies_owed
+              @seller.payable_currencies
+            end
+
+            def serialize_payout(payout)
+              Spree.api.admin_seller_payout_serializer.new(payout, params: { store: current_store }).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/sellers/team_controller.rb

@@ -0,0 +1,64 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Sellers
+          # The people who run one of the marketplace's sellers.
+          #
+          # The operator's view of what the seller panel manages for itself. It
+          # exists because the operator is the only one who can repair a seller
+          # nobody can sign in to any more — the last member left, or the wrong
+          # person was invited — which a seller by definition cannot do from
+          # inside their own panel.
+          #
+          # Inviting is not here: it is the `invite` action on the seller
+          # itself, which is a lifecycle workflow rather than bookkeeping on a
+          # team.
+          class TeamController < Admin::BaseController
+            scoped_resource :sellers
+
+            before_action :set_seller
+            before_action :set_member, only: [:destroy]
+
+            def index
+              render json: { data: @seller.users.map { |member| serialize_member(member) } }
+            end
+
+            # Revokes a member's access. Unlike the seller's own panel this
+            # does not insist on leaving one member behind: emptying the team
+            # is a state only the operator can undo, and refusing it here
+            # would leave them unable to remove somebody who should not have
+            # access — the reason this endpoint exists.
+            def destroy
+              @seller.remove_user(@member)
+              head :no_content
+            end
+
+            protected
+
+            def read_actions
+              %w[index]
+            end
+
+            private
+
+            def set_seller
+              @seller = current_store.sellers.find_by_prefix_id!(params[:seller_id])
+              authorize! :show, @seller
+            end
+
+            def set_member
+              @member = @seller.users.find_by_prefix_id!(params[:id])
+            end
+
+            def serialize_member(member)
+              Spree.api.admin_seller_team_member_serializer.new(
+                member, params: { store: current_store }
+              ).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/sellers_controller.rb

@@ -0,0 +1,197 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Sellers, as the marketplace operator manages them.
+        #
+        # Every status change is its own member action rather than mass
+        # assignment, because each one is a workflow with its own arguments —
+        # suspending carries a reason, inviting carries an email address. The
+        # `status` field is deliberately not writable through `update`: a
+        # seller moved by a PATCH would skip the mail, the payout provisioning
+        # and the extension hooks that make the transition mean something.
+        class SellersController < ResourceController
+          # Sellers are their own catalog resource: `read_sellers`/`write_sellers`
+          # is what a key needs here, and neither is grantable to a seller's own
+          # panel — managing sellers is the operator's job.
+          scoped_resource :sellers
+
+          before_action :set_resource, only: [:show, :update, :destroy, :invite, :approve, :suspend, :reject,
+                                              :onboarding, :reopen_onboarding]
+
+          # POST /api/v3/admin/sellers/:id/invite
+          #
+          # Opens the seller's team to someone. They become a member when they
+          # accept, on the same invitation rail the store's own staff use.
+          def invite
+            result = Spree.seller_invite_workflow.call(
+              seller: @resource,
+              email: params[:email],
+              role: role_for_invite,
+              inviter: try_spree_current_user
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value), status: :created
+            else
+              render_result_error(result)
+            end
+          end
+
+          # GET /api/v3/admin/sellers/:id/onboarding
+          #
+          # Where this seller stands against the marketplace's checklist. Its
+          # own action rather than a field on the seller: evaluating it costs
+          # a handful of queries per seller, which a list of twenty-five must
+          # not pay for a column most operators are not looking at.
+          def onboarding
+            authorize_resource!(@resource, :show)
+
+            requirements = Spree::Sellers::Requirements.new(@resource)
+
+            render json: {
+              status: @resource.status,
+              progress: requirements.progress,
+              requirements: serialize_requirement_statuses(requirements.statuses)
+            }
+          end
+
+          # PATCH /api/v3/admin/sellers/:id/approve
+          #
+          # `override_requirements` admits a seller whose checklist is not
+          # finished — the operator's deliberate exception, which the event
+          # records alongside what was outstanding.
+          def approve
+            run_workflow(Spree.seller_approve_workflow,
+                         approver: try_spree_current_user,
+                         override_requirements: ActiveModel::Type::Boolean.new.cast(params[:override_requirements]))
+          end
+
+          # PATCH /api/v3/admin/sellers/:id/reopen_onboarding
+          #
+          # Sends a seller awaiting review back to onboarding with a note.
+          # Distinct from reject, which turns them away.
+          def reopen_onboarding
+            run_workflow(Spree.seller_reopen_onboarding_workflow,
+                         note: params[:note],
+                         reopened_by: try_spree_current_user)
+          end
+
+          # PATCH /api/v3/admin/sellers/:id/suspend
+          def suspend
+            run_workflow(Spree.seller_suspend_workflow,
+                         reason: params[:reason],
+                         suspended_by: try_spree_current_user)
+          end
+
+          # PATCH /api/v3/admin/sellers/:id/reject
+          def reject
+            run_workflow(Spree.seller_reject_workflow,
+                         reason: params[:reason],
+                         rejected_by: try_spree_current_user)
+          end
+
+          protected
+
+          def model_class
+            Spree::Seller
+          end
+
+          def serializer_class
+            Spree.api.admin_seller_serializer
+          end
+
+          # `users` is preloaded because a seller team is small and its count is
+          # a cheap `.size` over loaded rows. `products` deliberately is not: a
+          # catalog can run to thousands, so the serializer counts it in SQL
+          # rather than materializing it just to measure it.
+          def collection_includes
+            [:users]
+          end
+
+          # A checklist kind may ask a payment provider whether a seller can be
+          # paid, which is one network call — fine for one seller, but a page
+          # of them would make the list as slow as the operator's connection.
+          # Marked here rather than inferred from the eager-loaded checklist,
+          # which a single-seller read shares.
+          def collection
+            @marked_collection ||= super.each { |seller| seller.onboarding_requirements_cached = true }
+          end
+
+          # What the serializer's onboarding progress reads for every seller,
+          # on the list and on the profile alike: the checklist's kinds look
+          # at addresses, branding and the seller's own submissions, and the
+          # requirements themselves hang off the store — one row shared by
+          # every seller on the page, so it loads once. Applied to the scope
+          # rather than the collection so a single-seller read gets it too.
+          def scope_includes
+            [:billing_address, :requirement_submissions, { stock_locations: [] },
+             { store: :seller_requirements, logo_attachment: :blob, cover_photo_attachment: :blob }]
+          end
+
+          # Enumerated rather than borrowing the legacy global list, which
+          # permits :id, :user_id and :deleted_at — the first of which would
+          # reintroduce the address-by-id hole below.
+          # The seller's own profile fields, plus the settlement and tax
+          # configuration only the operator sets. `status` is absent by
+          # design — see the class comment.
+          #
+          # Addresses are written as nested attributes, never as ids: an
+          # address has no store of its own, so accepting `billing_address_id`
+          # would bind an arbitrary row and the serializer would render it
+          # back in full — an enumeration oracle over every customer address
+          # on the installation.
+          def permitted_params
+            normalize_params(
+              params.permit(:name, :slug, :contact_email, :billing_email, :about,
+                            :logo, :square_logo, :cover_photo,
+                            :tax_remittance, :payouts_schedule_interval, :minimum_payout_amount,
+                            :holiday_mode_until,
+                            :legal_name, :registration_number,
+                            metadata: {},
+                            billing_address: Spree::Api::V3::AddressParams::ADDRESS_KEYS,
+                            custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }])
+            )
+          end
+
+          # Creating a seller provisions their stock location too, so it goes
+          # through the workflow rather than the base class's plain build.
+          def create_workflow
+            Spree.seller_create_workflow
+          end
+
+          # `onboarding` is a read of the seller — it changes nothing.
+          def read_actions
+            super + %w[onboarding]
+          end
+
+          private
+
+          def serialize_requirement_statuses(statuses)
+            serializer = Spree.api.admin_seller_requirement_status_serializer
+
+            statuses.map { |status| serializer.new(status, params: serializer_params).to_h }
+          end
+
+          def run_workflow(workflow, **arguments)
+            result = workflow.call(seller: @resource, **arguments)
+
+            if result.success?
+              render json: serialize_resource(result.value)
+            else
+              render_result_error(result)
+            end
+          end
+
+          # Read through the seller's own roles: a role id naming somewhere
+          # else is a 404 here rather than an invitation into another team.
+          def role_for_invite
+            return nil if params[:role_id].blank?
+
+            @resource.roles.find_by_prefix_id!(params[:role_id])
+          end
+        end
+      end
+    end
+  end
+end