@unifiedcommerce/plugin-marketplace 0.0.1

package/src/routes/payouts.ts

@@ -0,0 +1,49 @@
+import { router } from "@unifiedcommerce/core";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import type { PayoutService } from "../services/payout";
+import { stripUndefined } from "./util";
+
+export function buildPayoutRoutes(services: {
+  payout: PayoutService;
+}): PluginRouteRegistration[] {
+  const r = router("Marketplace - Payouts", "/marketplace/payouts");
+
+  // ─── List payouts ──────────────────────────────────────────────────────────
+  r.get("/")
+    .summary("List payouts")
+    .permission("marketplace:admin")
+    .handler(async ({ query }) => {
+      return services.payout.listPayouts(stripUndefined({
+        vendorId: query.vendorId as string | undefined,
+        status: query.status as string | undefined,
+      }));
+    });
+
+  // ─── Run payout cycle ──────────────────────────────────────────────────────
+  r.post("/run")
+    .summary("Run a payout cycle")
+    .permission("marketplace:admin")
+    .handler(async () => {
+      return services.payout.runPayoutCycle();
+    });
+
+  // ─── Retry payout ──────────────────────────────────────────────────────────
+  r.post("/{id}/retry")
+    .summary("Retry a failed payout")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      return services.payout.retryPayout(params.id!);
+    });
+
+  // ─── Get payout by id ──────────────────────────────────────────────────────
+  r.get("/{id}")
+    .summary("Get payout by ID")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const payout = await services.payout.getPayoutById(params.id!);
+      if (!payout) throw new Error("Payout not found");
+      return payout;
+    });
+
+  return r.routes();
+}

package/src/routes/sub-orders.ts

@@ -0,0 +1,54 @@
+import { router } from "@unifiedcommerce/core";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import type { z } from "@hono/zod-openapi";
+import type { SubOrderService } from "../services/sub-order";
+import type { SubOrderStatus } from "../types";
+import { UpdateSubOrderStatusBodySchema } from "../schemas/sub-orders";
+import { stripUndefined } from "./util";
+
+export function buildSubOrderRoutes(services: {
+  subOrder: SubOrderService;
+}): PluginRouteRegistration[] {
+  const r = router("Marketplace - Sub-Orders", "/marketplace/sub-orders");
+
+  // ─── List sub-orders ───────────────────────────────────────────────────────
+  r.get("/")
+    .summary("List sub-orders")
+    .permission("marketplace:admin")
+    .handler(async ({ query }) => {
+      return services.subOrder.list(stripUndefined({
+        orderId: query.orderId as string | undefined,
+        vendorId: query.vendorId as string | undefined,
+        status: query.status as string | undefined,
+      }));
+    });
+
+  // ─── Get sub-order by id ───────────────────────────────────────────────────
+  r.get("/{id}")
+    .summary("Get sub-order by ID")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const subOrder = await services.subOrder.getById(params.id!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      return subOrder;
+    });
+
+  // ─── Force status change ───────────────────────────────────────────────────
+  r.patch("/{id}/status")
+    .summary("Force a sub-order status change")
+    .permission("marketplace:admin")
+    .input(UpdateSubOrderStatusBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UpdateSubOrderStatusBodySchema>;
+      const subOrder = await services.subOrder.getById(params.id!);
+      if (!subOrder) throw new Error("Sub-order not found");
+
+      // Use cancel() for cancelled status to trigger side effects
+      // (inventory release + ledger reversal)
+      return body.status === "cancelled"
+        ? services.subOrder.cancel(params.id!, "Admin force cancel")
+        : services.subOrder.forceStatus(params.id!, body.status as SubOrderStatus);
+    });
+
+  return r.routes();
+}

package/src/routes/util.ts

@@ -0,0 +1,42 @@
+/**
+ * Removes keys whose value is `undefined` from an object, returning a
+ * cleaned copy that satisfies `exactOptionalPropertyTypes`.
+ *
+ * Zod's `.optional()` produces `T | undefined` in inferred types, which
+ * can't be assigned to optional properties under `exactOptionalPropertyTypes`.
+ * This helper strips those `undefined` entries at runtime and casts the
+ * result so TypeScript accepts it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function stripUndefined<T>(obj: T): T extends Record<string, any> ? { [K in keyof T]: Exclude<T[K], undefined> } : T {
+  if (obj == null || typeof obj !== "object") return obj as never;
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result as never;
+}
+
+/** Keys that must never be exposed in API responses. */
+const VENDOR_SECRET_KEYS = [
+  "storeAccessToken",
+  "storeConsumerSecret",
+  "storeWebhookSecret",
+  "bankAccount",
+] as const;
+
+/**
+ * Returns a copy of a vendor record with sensitive fields removed.
+ *
+ * Accepts any object with string keys so it works with both single vendor
+ * rows and Drizzle `InferSelectModel` types without importing the schema.
+ */
+export function stripVendorSecrets<T extends Record<string, unknown>>(vendor: T): Omit<T, (typeof VENDOR_SECRET_KEYS)[number]> {
+  const copy = { ...vendor };
+  for (const key of VENDOR_SECRET_KEYS) {
+    delete copy[key];
+  }
+  return copy as Omit<T, (typeof VENDOR_SECRET_KEYS)[number]>;
+}

package/src/routes/vendor-portal.ts

@@ -0,0 +1,277 @@
+import { router } from "@unifiedcommerce/core";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import type { z } from "@hono/zod-openapi";
+import type { VendorService } from "../services/vendor";
+import type { SubOrderService } from "../services/sub-order";
+import type { PayoutService } from "../services/payout";
+import type { ReviewService } from "../services/review";
+import type { ReturnService } from "../services/return";
+import { vendorEntities } from "../schema";
+import { eq } from "drizzle-orm";
+import {
+  UpdateVendorProfileBodySchema,
+  UploadVendorDocumentBodySchema,
+  ShipSubOrderBodySchema,
+  CancelSubOrderBodySchema,
+  RespondToReviewBodySchema,
+  ApproveReturnBodySchema,
+  RejectReturnBodySchema,
+} from "../schemas/vendor-portal";
+import { stripUndefined, stripVendorSecrets } from "./util";
+
+/** Helper to extract vendorId from actor and throw if missing. */
+function requireVendorId(actor: { vendorId?: string | null } | null): string {
+  const vendorId = actor?.vendorId;
+  if (!vendorId) throw new Error("Forbidden");
+  return vendorId;
+}
+
+export function buildVendorPortalRoutes(services: {
+  vendor: VendorService;
+  subOrder: SubOrderService;
+  payout: PayoutService;
+  review: ReviewService;
+  return: ReturnService;
+}): PluginRouteRegistration[] {
+  const r = router("Marketplace - Vendor Portal", "/marketplace/vendor/me");
+
+  // ─── Get my vendor profile ─────────────────────────────────────────────────
+  r.get("/")
+    .summary("Get my vendor profile")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      const vendor = await services.vendor.getById(vendorId);
+      if (!vendor) throw new Error("Vendor not found");
+      return stripVendorSecrets(vendor);
+    });
+
+  // ─── Update my vendor profile ──────────────────────────────────────────────
+  r.patch("/")
+    .summary("Update my vendor profile")
+    .auth()
+    .input(UpdateVendorProfileBodySchema)
+    .handler(async ({ actor, input }) => {
+      const vendorId = requireVendorId(actor);
+      const body = input as z.infer<typeof UpdateVendorProfileBodySchema>;
+      const updated = await services.vendor.update(vendorId, stripUndefined(body));
+      if (!updated) throw new Error("Vendor not found");
+      return stripVendorSecrets(updated);
+    });
+
+  // ─── Upload document ───────────────────────────────────────────────────────
+  r.post("/documents")
+    .summary("Upload a document for my vendor profile")
+    .auth()
+    .input(UploadVendorDocumentBodySchema)
+    .handler(async ({ actor, input }) => {
+      const vendorId = requireVendorId(actor);
+      const body = input as z.infer<typeof UploadVendorDocumentBodySchema>;
+      return services.vendor.uploadDocument(vendorId, {
+        type: body.type,
+        fileUrl: body.fileUrl,
+      });
+    });
+
+  // ─── List my documents ─────────────────────────────────────────────────────
+  r.get("/documents")
+    .summary("List my vendor documents")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      return services.vendor.listDocuments(vendorId);
+    });
+
+  // ─── List my products ──────────────────────────────────────────────────────
+  r.get("/products")
+    .summary("List my products")
+    .auth()
+    .handler(async ({ actor, db }) => {
+      const vendorId = requireVendorId(actor);
+      const drizzle = db as import("../types").Db;
+      const entities = await drizzle
+        .select()
+        .from(vendorEntities)
+        .where(eq(vendorEntities.vendorId, vendorId));
+      return entities;
+    });
+
+  // ─── List my sub-orders ────────────────────────────────────────────────────
+  r.get("/orders")
+    .summary("List my sub-orders")
+    .auth()
+    .handler(async ({ actor, query }) => {
+      const vendorId = requireVendorId(actor);
+      const status = query.status as string | undefined;
+      return services.subOrder.listByVendor(vendorId, stripUndefined({ status }));
+    });
+
+  // ─── Get single sub-order ──────────────────────────────────────────────────
+  r.get("/orders/{subOrderId}")
+    .summary("Get a single sub-order")
+    .auth()
+    .handler(async ({ actor, params }) => {
+      const vendorId = requireVendorId(actor);
+      const subOrder = await services.subOrder.getById(params.subOrderId!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      if (subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      return subOrder;
+    });
+
+  // ─── Confirm sub-order ─────────────────────────────────────────────────────
+  r.post("/orders/{subOrderId}/confirm")
+    .summary("Confirm a sub-order")
+    .auth()
+    .handler(async ({ actor, params }) => {
+      const vendorId = requireVendorId(actor);
+      const subOrder = await services.subOrder.getById(params.subOrderId!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      if (subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      return services.subOrder.confirm(params.subOrderId!);
+    });
+
+  // ─── Ship sub-order ────────────────────────────────────────────────────────
+  r.post("/orders/{subOrderId}/ship")
+    .summary("Ship a sub-order")
+    .auth()
+    .input(ShipSubOrderBodySchema)
+    .handler(async ({ actor, params, input }) => {
+      const vendorId = requireVendorId(actor);
+      const body = input as z.infer<typeof ShipSubOrderBodySchema>;
+      const subOrder = await services.subOrder.getById(params.subOrderId!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      if (subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      return services.subOrder.ship(params.subOrderId!, {
+        trackingNumber: body.trackingNumber,
+        carrier: body.carrier,
+      });
+    });
+
+  // ─── Deliver sub-order ─────────────────────────────────────────────────────
+  r.post("/orders/{subOrderId}/deliver")
+    .summary("Mark a sub-order as delivered")
+    .auth()
+    .handler(async ({ actor, params }) => {
+      const vendorId = requireVendorId(actor);
+      const subOrder = await services.subOrder.getById(params.subOrderId!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      if (subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      return services.subOrder.deliver(params.subOrderId!);
+    });
+
+  // ─── Cancel sub-order ──────────────────────────────────────────────────────
+  r.post("/orders/{subOrderId}/cancel")
+    .summary("Cancel a sub-order")
+    .auth()
+    .input(CancelSubOrderBodySchema)
+    .handler(async ({ actor, params, input }) => {
+      const vendorId = requireVendorId(actor);
+      const body = input as z.infer<typeof CancelSubOrderBodySchema>;
+      const subOrder = await services.subOrder.getById(params.subOrderId!);
+      if (!subOrder) throw new Error("Sub-order not found");
+      if (subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      return services.subOrder.cancel(params.subOrderId!, body.reason);
+    });
+
+  // ─── List my payouts ───────────────────────────────────────────────────────
+  r.get("/payouts")
+    .summary("List my payouts")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      return services.payout.listPayouts({ vendorId });
+    });
+
+  // ─── My balance ────────────────────────────────────────────────────────────
+  r.get("/balance")
+    .summary("Get my balance")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      const balance = await services.payout.getBalance(vendorId);
+      const ledger = await services.payout.getLedger(vendorId);
+      return { balanceCents: balance, ledger };
+    });
+
+  // ─── My analytics ──────────────────────────────────────────────────────────
+  r.get("/analytics")
+    .summary("Get my analytics")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      const rating = await services.review.getAggregateRating(vendorId);
+      const balance = await services.payout.getBalance(vendorId);
+      return { rating, balanceCents: balance };
+    });
+
+  // ─── My reviews ────────────────────────────────────────────────────────────
+  r.get("/reviews")
+    .summary("List my reviews")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      return services.review.getForVendor(vendorId, true);
+    });
+
+  // ─── Respond to review ─────────────────────────────────────────────────────
+  r.post("/reviews/{id}/respond")
+    .summary("Respond to a review")
+    .auth()
+    .input(RespondToReviewBodySchema)
+    .handler(async ({ actor, params, input }) => {
+      const vendorId = requireVendorId(actor);
+      const body = input as z.infer<typeof RespondToReviewBodySchema>;
+      // IDOR prevention: verify the review belongs to this vendor
+      const vendorReviews = await services.review.getForVendor(vendorId, true);
+      const ownsReview = vendorReviews.some((rev: { id: string }) => rev.id === params.id!);
+      if (!ownsReview) throw new Error("Forbidden: review does not belong to this vendor");
+      const updated = await services.review.respond(params.id!, body.response);
+      if (!updated) throw new Error("Review not found");
+      return updated;
+    });
+
+  // ─── My returns ────────────────────────────────────────────────────────────
+  r.get("/returns")
+    .summary("List my returns")
+    .auth()
+    .handler(async ({ actor }) => {
+      const vendorId = requireVendorId(actor);
+      return services.return.listByVendor(vendorId);
+    });
+
+  // ─── Approve return ────────────────────────────────────────────────────────
+  r.post("/returns/{id}/approve")
+    .summary("Approve a return request")
+    .auth()
+    .input(ApproveReturnBodySchema)
+    .handler(async ({ actor, params, input }) => {
+      const vendorId = requireVendorId(actor);
+      const ret = await services.return.getById(params.id!);
+      if (!ret) throw new Error("Return not found");
+      const subOrder = await services.subOrder.getById(ret.subOrderId);
+      if (!subOrder || subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      const body = input as z.infer<typeof ApproveReturnBodySchema>;
+      const updated = await services.return.vendorApprove(params.id!, body.refundAmountCents);
+      if (!updated) throw new Error("Return not found");
+      return updated;
+    });
+
+  // ─── Reject return ─────────────────────────────────────────────────────────
+  r.post("/returns/{id}/reject")
+    .summary("Reject a return request")
+    .auth()
+    .input(RejectReturnBodySchema)
+    .handler(async ({ actor, params, input }) => {
+      const vendorId = requireVendorId(actor);
+      const ret = await services.return.getById(params.id!);
+      if (!ret) throw new Error("Return not found");
+      const subOrder = await services.subOrder.getById(ret.subOrderId);
+      if (!subOrder || subOrder.vendorId !== vendorId) throw new Error("Forbidden");
+      const body = input as z.infer<typeof RejectReturnBodySchema>;
+      const updated = await services.return.vendorReject(params.id!, body.notes);
+      if (!updated) throw new Error("Return not found");
+      return updated;
+    });
+
+  return r.routes();
+}

package/src/routes/vendors.ts

@@ -0,0 +1,201 @@
+import { router, resolveOrgId } from "@unifiedcommerce/core";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import type { z } from "@hono/zod-openapi";
+import type { VendorService } from "../services/vendor";
+import type { PayoutService } from "../services/payout";
+import type { ReviewService } from "../services/review";
+import type { MarketplacePluginOptions } from "../types";
+import {
+  CreateVendorBodySchema,
+  UpdateVendorBodySchema,
+  RejectVendorBodySchema,
+  SuspendVendorBodySchema,
+  UploadDocumentBodySchema,
+} from "../schemas/vendors";
+import { stripUndefined, stripVendorSecrets } from "./util";
+
+export function buildVendorRoutes(services: {
+  vendor: VendorService;
+  payout: PayoutService;
+  review: ReviewService;
+}, options?: MarketplacePluginOptions): PluginRouteRegistration[] {
+  const r = router("Marketplace - Vendors", "/marketplace/vendors");
+
+  // ─── List vendors ──────────────────────────────────────────────────────────
+  r.get("/")
+    .summary("List all vendors")
+    .permission("marketplace:admin")
+    .handler(async ({ query }) => {
+      const vendors = await services.vendor.list(stripUndefined({
+        status: query.status as string | undefined,
+        tier: query.tier as string | undefined,
+        search: query.search as string | undefined,
+      }));
+      return vendors.map(stripVendorSecrets);
+    });
+
+  // ─── Create vendor ─────────────────────────────────────────────────────────
+  r.post("/")
+    .summary("Create a vendor")
+    .permission("marketplace:admin")
+    .input(CreateVendorBodySchema)
+    .handler(async ({ input, actor }) => {
+      const body = input as z.infer<typeof CreateVendorBodySchema>;
+      const defaultBps = options?.defaultCommissionRateBps ?? 1000;
+      return services.vendor.create(resolveOrgId(actor), stripUndefined({
+        ...body,
+        commissionRateBps: body.commissionRateBps ?? defaultBps,
+      }));
+    });
+
+  // ─── Get vendor detail ─────────────────────────────────────────────────────
+  r.get("/{id}")
+    .summary("Get vendor detail")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      return stripVendorSecrets(vendor);
+    });
+
+  // ─── Update vendor ─────────────────────────────────────────────────────────
+  r.patch("/{id}")
+    .summary("Update a vendor")
+    .permission("marketplace:admin")
+    .input(UpdateVendorBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UpdateVendorBodySchema>;
+      const updated = await services.vendor.update(params.id!, stripUndefined(body));
+      if (!updated) throw new Error("Vendor not found");
+      return stripVendorSecrets(updated);
+    });
+
+  // ─── Approve vendor ────────────────────────────────────────────────────────
+  r.post("/{id}/approve")
+    .summary("Approve a vendor application")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const approved = await services.vendor.approve(params.id!);
+      if (!approved) throw new Error("Vendor not found");
+      return stripVendorSecrets(approved);
+    });
+
+  // ─── Reject vendor ─────────────────────────────────────────────────────────
+  r.post("/{id}/reject")
+    .summary("Reject a vendor application")
+    .permission("marketplace:admin")
+    .input(RejectVendorBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof RejectVendorBodySchema>;
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const rejected = await services.vendor.reject(params.id!, body.reason);
+      if (!rejected) throw new Error("Vendor not found");
+      return stripVendorSecrets(rejected);
+    });
+
+  // ─── Suspend vendor ────────────────────────────────────────────────────────
+  r.post("/{id}/suspend")
+    .summary("Suspend a vendor")
+    .permission("marketplace:admin")
+    .input(SuspendVendorBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof SuspendVendorBodySchema>;
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const suspended = await services.vendor.suspend(params.id!, body.reason);
+      if (!suspended) throw new Error("Vendor not found");
+      return stripVendorSecrets(suspended);
+    });
+
+  // ─── Reinstate vendor ──────────────────────────────────────────────────────
+  r.post("/{id}/reinstate")
+    .summary("Reinstate a suspended vendor")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const reinstated = await services.vendor.reinstate(params.id!);
+      if (!reinstated) throw new Error("Vendor not found");
+      return stripVendorSecrets(reinstated);
+    });
+
+  // ─── Upload vendor document ────────────────────────────────────────────────
+  r.post("/{id}/documents")
+    .summary("Upload a vendor document")
+    .permission("marketplace:admin")
+    .input(UploadDocumentBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UploadDocumentBodySchema>;
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      return services.vendor.uploadDocument(params.id!, {
+        type: body.type,
+        fileUrl: body.fileUrl,
+      });
+    });
+
+  // ─── List vendor documents ─────────────────────────────────────────────────
+  r.get("/{id}/documents")
+    .summary("List vendor documents")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      return services.vendor.listDocuments(params.id!);
+    });
+
+  // ─── Approve document ──────────────────────────────────────────────────────
+  r.post("/{id}/documents/{docId}/approve")
+    .summary("Approve a vendor document")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const updated = await services.vendor.approveDocument(params.docId!);
+      if (!updated) throw new Error("Document not found");
+      return updated;
+    });
+
+  // ─── Reject document ───────────────────────────────────────────────────────
+  r.post("/{id}/documents/{docId}/reject")
+    .summary("Reject a vendor document")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const updated = await services.vendor.rejectDocument(params.docId!);
+      if (!updated) throw new Error("Document not found");
+      return updated;
+    });
+
+  // ─── Vendor balance ────────────────────────────────────────────────────────
+  r.get("/{id}/balance")
+    .summary("Get vendor balance")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const balance = await services.payout.getBalance(params.id!);
+      const ledger = await services.payout.getLedger(params.id!);
+      return { balanceCents: balance, ledger };
+    });
+
+  // ─── Vendor performance ────────────────────────────────────────────────────
+  r.get("/{id}/performance")
+    .summary("Get vendor performance metrics")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const vendor = await services.vendor.getById(params.id!);
+      if (!vendor) throw new Error("Vendor not found");
+      const rating = await services.review.getAggregateRating(params.id!);
+      const balance = await services.payout.getBalance(params.id!);
+      return {
+        vendorId: params.id!,
+        performanceScore: vendor.performanceScore,
+        tier: vendor.tier,
+        rating,
+        balanceCents: balance,
+      };
+    });
+
+  return r.routes();
+}