@porulle/plugin-marketplace 0.1.0

package/src/routes/b2b.ts

@@ -0,0 +1,179 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { z } from "@hono/zod-openapi";
+import type { RFQService } from "../services/rfq.js";
+import type { ContractPriceService } from "../services/contract-price.js";
+import type { MarketplacePluginOptions } from "../types.js";
+import {
+  CreateRFQBodySchema,
+  RespondRFQBodySchema,
+  AwardRFQBodySchema,
+  CreateContractPriceBodySchema,
+  UpdateContractPriceBodySchema,
+} from "../schemas/b2b.js";
+import { stripUndefined } from "./util.js";
+
+export function buildB2BRoutes(services: {
+  rfq?: RFQService | undefined;
+  contractPrice?: ContractPriceService | undefined;
+}, options: MarketplacePluginOptions): PluginRouteRegistration[] {
+  const allRoutes: PluginRouteRegistration[] = [];
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // RFQ (Request for Quote)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  if (services.rfq) {
+    const rfqSvc = services.rfq;
+    const rfq = router("Marketplace - B2B", "/marketplace/rfq");
+
+    rfq.post("/")
+      .summary("Create a Request for Quote")
+      .auth()
+      .input(CreateRFQBodySchema)
+      .handler(async ({ input }) => {
+        const body = input as z.infer<typeof CreateRFQBodySchema>;
+        return rfqSvc.create(stripUndefined({
+          buyerId: body.buyerId,
+          title: body.title,
+          description: body.description,
+          categorySlug: body.categorySlug,
+          quantity: body.quantity,
+          budgetCents: body.budgetCents,
+          currency: body.currency,
+          deadlineAt: body.deadlineAt ? new Date(body.deadlineAt) : undefined,
+          metadata: body.metadata,
+        }));
+      });
+
+    rfq.get("/")
+      .summary("List Requests for Quote")
+      .auth()
+      .handler(async ({ query }) => {
+        return rfqSvc.list(stripUndefined({
+          status: query.status as string | undefined,
+          categorySlug: query.categorySlug as string | undefined,
+        }));
+      });
+
+    rfq.get("/{id}")
+      .summary("Get RFQ detail")
+      .auth()
+      .handler(async ({ params }) => {
+        const item = await rfqSvc.getById(params.id!);
+        if (!item) throw new Error("RFQ not found");
+        const responses = await rfqSvc.getResponses(item.id);
+        return { ...item, responses };
+      });
+
+    rfq.post("/{id}/respond")
+      .summary("Submit a vendor response to an RFQ")
+      .auth()
+      .input(RespondRFQBodySchema)
+      .handler(async ({ params, input }) => {
+        const body = input as z.infer<typeof RespondRFQBodySchema>;
+        const item = await rfqSvc.getById(params.id!);
+        if (!item) throw new Error("RFQ not found");
+        return rfqSvc.respond(item.id, stripUndefined({
+          vendorId: body.vendorId,
+          unitPriceCents: body.unitPriceCents,
+          totalPriceCents: body.totalPriceCents,
+          leadTimeDays: body.leadTimeDays,
+          notes: body.notes,
+        }));
+      });
+
+    rfq.post("/{id}/award")
+      .summary("Award an RFQ to a vendor")
+      .auth()
+      .permission("marketplace:admin")
+      .input(AwardRFQBodySchema)
+      .handler(async ({ params, input }) => {
+        const body = input as z.infer<typeof AwardRFQBodySchema>;
+        const updated = await rfqSvc.award(params.id!, body.vendorId);
+        if (!updated) throw new Error("RFQ not found");
+        return updated;
+      });
+
+    rfq.post("/{id}/close")
+      .summary("Close an RFQ")
+      .auth()
+      .permission("marketplace:admin")
+      .handler(async ({ params }) => {
+        const updated = await rfqSvc.close(params.id!);
+        if (!updated) throw new Error("RFQ not found");
+        return updated;
+      });
+
+    allRoutes.push(...rfq.routes());
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CONTRACT PRICES
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  if (services.contractPrice) {
+    const cpSvc = services.contractPrice;
+    const cp = router("Marketplace - B2B", "/marketplace/contract-prices");
+
+    cp.get("/")
+      .summary("List contract prices")
+      .auth()
+      .handler(async ({ query }) => {
+        return cpSvc.list(stripUndefined({
+          vendorId: query.vendorId as string | undefined,
+          buyerId: query.buyerId as string | undefined,
+        }));
+      });
+
+    cp.post("/")
+      .summary("Create a contract price")
+      .auth()
+      .permission("marketplace:admin")
+      .input(CreateContractPriceBodySchema)
+      .handler(async ({ input }) => {
+        const body = input as z.infer<typeof CreateContractPriceBodySchema>;
+        return cpSvc.create(stripUndefined({
+          vendorId: body.vendorId,
+          buyerId: body.buyerId,
+          entityId: body.entityId,
+          variantId: body.variantId,
+          priceCents: body.priceCents,
+          minQuantity: body.minQuantity,
+          currency: body.currency,
+          validFrom: body.validFrom ? new Date(body.validFrom) : undefined,
+          validUntil: body.validUntil ? new Date(body.validUntil) : undefined,
+        }));
+      });
+
+    cp.patch("/{id}")
+      .summary("Update a contract price")
+      .auth()
+      .permission("marketplace:admin")
+      .input(UpdateContractPriceBodySchema)
+      .handler(async ({ params, input }) => {
+        const body = input as z.infer<typeof UpdateContractPriceBodySchema>;
+        const updateData: Record<string, unknown> = {};
+        if (body.priceCents !== undefined) updateData.priceCents = body.priceCents;
+        if (body.minQuantity !== undefined) updateData.minQuantity = body.minQuantity;
+        if (body.validFrom !== undefined) updateData.validFrom = body.validFrom ? new Date(body.validFrom) : null;
+        if (body.validUntil !== undefined) updateData.validUntil = body.validUntil ? new Date(body.validUntil) : null;
+        const updated = await cpSvc.update(params.id!, updateData);
+        if (!updated) throw new Error("Contract price not found");
+        return updated;
+      });
+
+    cp.delete("/{id}")
+      .summary("Delete a contract price")
+      .auth()
+      .permission("marketplace:admin")
+      .handler(async ({ params }) => {
+        await cpSvc.delete(params.id!);
+        return { deleted: true };
+      });
+
+    allRoutes.push(...cp.routes());
+  }
+
+  return allRoutes;
+}

package/src/routes/commission.ts

@@ -0,0 +1,95 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { z } from "@hono/zod-openapi";
+import type { CommissionService } from "../services/commission.js";
+import {
+  CreateCommissionRuleBodySchema,
+  UpdateCommissionRuleBodySchema,
+  PreviewCommissionBodySchema,
+} from "../schemas/commission.js";
+import { stripUndefined } from "./util.js";
+
+export function buildCommissionRoutes(services: {
+  commission: CommissionService;
+}): PluginRouteRegistration[] {
+  const r = router("Marketplace - Commission", "/marketplace/commission-rules");
+
+  // ─── List commission rules ─────────────────────────────────────────────────
+  r.get("/")
+    .summary("List all commission rules")
+    .permission("marketplace:admin")
+    .handler(async () => {
+      return services.commission.listRules();
+    });
+
+  // ─── Create commission rule ────────────────────────────────────────────────
+  r.post("/")
+    .summary("Create a commission rule")
+    .permission("marketplace:admin")
+    .input(CreateCommissionRuleBodySchema)
+    .handler(async ({ input }) => {
+      const body = input as z.infer<typeof CreateCommissionRuleBodySchema>;
+      return services.commission.createRule(stripUndefined({
+        name: body.name,
+        type: body.type,
+        rateBps: body.rateBps,
+        categorySlug: body.categorySlug,
+        vendorId: body.vendorId,
+        vendorTier: body.vendorTier,
+        minVolumeCents: body.minVolumeCents,
+        maxVolumeCents: body.maxVolumeCents,
+        validFrom: body.validFrom ? new Date(body.validFrom) : undefined,
+        validUntil: body.validUntil ? new Date(body.validUntil) : undefined,
+        priority: body.priority,
+      }));
+    });
+
+  // ─── Update commission rule ────────────────────────────────────────────────
+  r.patch("/{id}")
+    .summary("Update a commission rule")
+    .permission("marketplace:admin")
+    .input(UpdateCommissionRuleBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UpdateCommissionRuleBodySchema>;
+      const updateData: Record<string, unknown> = {};
+      if (body.name !== undefined) updateData.name = body.name;
+      if (body.rateBps !== undefined) updateData.rateBps = body.rateBps;
+      if (body.categorySlug !== undefined) updateData.categorySlug = body.categorySlug;
+      if (body.vendorTier !== undefined) updateData.vendorTier = body.vendorTier;
+      if (body.minVolumeCents !== undefined) updateData.minVolumeCents = body.minVolumeCents;
+      if (body.maxVolumeCents !== undefined) updateData.maxVolumeCents = body.maxVolumeCents;
+      if (body.validFrom !== undefined) updateData.validFrom = body.validFrom ? new Date(body.validFrom) : null;
+      if (body.validUntil !== undefined) updateData.validUntil = body.validUntil ? new Date(body.validUntil) : null;
+      if (body.priority !== undefined) updateData.priority = body.priority;
+      if (body.isActive !== undefined) updateData.isActive = body.isActive;
+
+      const updated = await services.commission.updateRule(params.id!, updateData);
+      if (!updated) throw new Error("Commission rule not found");
+      return updated;
+    });
+
+  // ─── Delete commission rule ────────────────────────────────────────────────
+  r.delete("/{id}")
+    .summary("Delete a commission rule")
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      await services.commission.deleteRule(params.id!);
+      return { deleted: true };
+    });
+
+  // ─── Preview commission rate ───────────────────────────────────────────────
+  r.post("/preview")
+    .summary("Preview the commission rate for a vendor")
+    .permission("marketplace:admin")
+    .input(PreviewCommissionBodySchema)
+    .handler(async ({ input }) => {
+      const body = input as z.infer<typeof PreviewCommissionBodySchema>;
+      return services.commission.previewRate(
+        body.vendorId,
+        body.categorySlug,
+        body.volumeCents,
+      );
+    });
+
+  return r.routes();
+}

package/src/routes/disputes-returns-reviews.ts

@@ -0,0 +1,209 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { z } from "@hono/zod-openapi";
+import type { DisputeService } from "../services/dispute.js";
+import type { ReturnService } from "../services/return.js";
+import type { ReviewService } from "../services/review.js";
+import type { DisputeResolution, ReviewStatus } from "../types.js";
+import {
+  OpenDisputeBodySchema,
+  RespondDisputeBodySchema,
+  ResolveDisputeBodySchema,
+  RequestReturnBodySchema,
+  ShipBackReturnBodySchema,
+  CreateReviewBodySchema,
+  ModerateReviewBodySchema,
+} from "../schemas/disputes-returns-reviews.js";
+import { stripUndefined } from "./util.js";
+
+export function buildDisputesReturnsReviewsRoutes(services: {
+  dispute: DisputeService;
+  return: ReturnService;
+  review: ReviewService;
+}): PluginRouteRegistration[] {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DISPUTES
+  // ═══════════════════════════════════════════════════════════════════════════
+  const disputes = router("Marketplace - Disputes", "/marketplace/disputes");
+
+  disputes.post("/")
+    .summary("Open a dispute")
+    .auth()
+    .input(OpenDisputeBodySchema)
+    .handler(async ({ input }) => {
+      const body = input as z.infer<typeof OpenDisputeBodySchema>;
+      return services.dispute.open(stripUndefined({
+        subOrderId: body.subOrderId,
+        openedBy: body.openedBy,
+        reason: body.reason,
+        description: body.description,
+      }));
+    });
+
+  disputes.get("/")
+    .summary("List disputes")
+    .auth()
+    .handler(async ({ query }) => {
+      return services.dispute.list(stripUndefined({
+        status: query.status as string | undefined,
+        subOrderId: query.subOrderId as string | undefined,
+      }));
+    });
+
+  disputes.get("/{id}")
+    .summary("Get dispute by ID")
+    .auth()
+    .handler(async ({ params }) => {
+      const dispute = await services.dispute.getById(params.id!);
+      if (!dispute) throw new Error("Dispute not found");
+      return dispute;
+    });
+
+  disputes.post("/{id}/respond")
+    .summary("Respond to a dispute")
+    .auth()
+    .input(RespondDisputeBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof RespondDisputeBodySchema>;
+      return services.dispute.respond(params.id!, stripUndefined({
+        party: body.party,
+        note: body.note,
+        url: body.url,
+      }));
+    });
+
+  disputes.post("/{id}/escalate")
+    .summary("Escalate a dispute")
+    .auth()
+    .permission("marketplace:admin")
+    .handler(async ({ params }) => {
+      const updated = await services.dispute.escalate(params.id!);
+      if (!updated) throw new Error("Dispute not found");
+      return updated;
+    });
+
+  disputes.post("/{id}/resolve")
+    .summary("Resolve a dispute")
+    .auth()
+    .permission("marketplace:admin")
+    .input(ResolveDisputeBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof ResolveDisputeBodySchema>;
+      const updated = await services.dispute.resolve(params.id!, stripUndefined({
+        resolution: body.resolution as DisputeResolution,
+        notes: body.notes,
+        refundAmountCents: body.refundAmountCents,
+        resolvedBy: body.resolvedBy,
+      }));
+      if (!updated) throw new Error("Dispute not found");
+      return updated;
+    });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // RETURNS
+  // ═══════════════════════════════════════════════════════════════════════════
+  const returns = router("Marketplace - Returns", "/marketplace/returns");
+
+  returns.post("/")
+    .summary("Request a return")
+    .auth()
+    .input(RequestReturnBodySchema)
+    .handler(async ({ input }) => {
+      const body = input as z.infer<typeof RequestReturnBodySchema>;
+      return services.return.request(stripUndefined({
+        subOrderId: body.subOrderId,
+        customerId: body.customerId,
+        reason: body.reason,
+        description: body.description,
+        lineItems: body.lineItems as { entityId: string; quantity: number; reason?: string }[] | undefined,
+      }));
+    });
+
+  returns.get("/")
+    .summary("List returns")
+    .auth()
+    .handler(async ({ query }) => {
+      return services.return.list(stripUndefined({
+        subOrderId: query.subOrderId as string | undefined,
+        status: query.status as string | undefined,
+      }));
+    });
+
+  returns.get("/{id}")
+    .summary("Get return by ID")
+    .auth()
+    .handler(async ({ params }) => {
+      const ret = await services.return.getById(params.id!);
+      if (!ret) throw new Error("Return not found");
+      return ret;
+    });
+
+  returns.post("/{id}/ship-back")
+    .summary("Ship back a return")
+    .auth()
+    .input(ShipBackReturnBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof ShipBackReturnBodySchema>;
+      const updated = await services.return.shipBack(params.id!, body.trackingNumber);
+      if (!updated) throw new Error("Return not found");
+      return updated;
+    });
+
+  returns.post("/{id}/receive")
+    .summary("Mark a return as received")
+    .auth()
+    .handler(async ({ params }) => {
+      const updated = await services.return.receive(params.id!);
+      if (!updated) throw new Error("Return not found");
+      return updated;
+    });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // REVIEWS
+  // ═══════════════════════════════════════════════════════════════════════════
+  const vendorReviews = router("Marketplace - Reviews", "/marketplace/vendors");
+
+  vendorReviews.post("/{id}/reviews")
+    .summary("Create a vendor review")
+    .auth()
+    .input(CreateReviewBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof CreateReviewBodySchema>;
+      return services.review.create(stripUndefined({
+        vendorId: params.id!,
+        customerId: body.customerId,
+        orderId: body.orderId,
+        rating: body.rating,
+        title: body.title,
+        body: body.body,
+      }));
+    });
+
+  vendorReviews.get("/{id}/reviews")
+    .summary("List reviews for a vendor")
+    .auth()
+    .handler(async ({ params }) => {
+      return services.review.getForVendor(params.id!);
+    });
+
+  const reviewsMod = router("Marketplace - Reviews", "/marketplace/reviews");
+
+  reviewsMod.patch("/{id}")
+    .summary("Moderate a review (update status)")
+    .auth()
+    .permission("marketplace:admin")
+    .input(ModerateReviewBodySchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof ModerateReviewBodySchema>;
+      const updated = await services.review.moderate(params.id!, body.status as ReviewStatus);
+      if (!updated) throw new Error("Review not found");
+      return updated;
+    });
+
+  return [
+    ...disputes.routes(),
+    ...returns.routes(),
+    ...vendorReviews.routes(),
+    ...reviewsMod.routes(),
+  ];
+}

package/src/routes/payouts.ts

@@ -0,0 +1,49 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { PayoutService } from "../services/payout.js";
+import { stripUndefined } from "./util.js";
+
+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 "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { z } from "@hono/zod-openapi";
+import type { SubOrderService } from "../services/sub-order.js";
+import type { SubOrderStatus } from "../types.js";
+import { UpdateSubOrderStatusBodySchema } from "../schemas/sub-orders.js";
+import { stripUndefined } from "./util.js";
+
+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]>;
+}