@unifiedcommerce/plugin-marketplace 0.0.1

package/src/schema.ts

@@ -0,0 +1,260 @@
+import { boolean, integer, jsonb, pgTable, text, timestamp, uuid, index, uniqueIndex } from "drizzle-orm/pg-core";
+
+// ─── Vendors ─────────────────────────────────────────────────────────────────
+
+export const vendors = pgTable("marketplace_vendors", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  name: text("name").notNull(),
+  slug: text("slug"),
+  email: text("email"),
+  description: text("description"),
+  logoUrl: text("logo_url"),
+  bannerUrl: text("banner_url"),
+  contactPhone: text("contact_phone"),
+  businessAddress: jsonb("business_address").$type<{
+    line1?: string; line2?: string; city?: string; state?: string;
+    postalCode?: string; country?: string;
+  }>(),
+  bankAccount: jsonb("bank_account").$type<{
+    accountHolder?: string; bankName?: string; routingNumber?: string;
+    accountNumber?: string; iban?: string; swift?: string;
+  }>(),
+  taxId: text("tax_id"),
+  status: text("status").notNull().default("pending"),
+  verificationStatus: text("verification_status").notNull().default("unverified"),
+  rejectionReason: text("rejection_reason"),
+  approvedCategories: jsonb("approved_categories").$type<string[] | null>(),
+  tier: text("tier").notNull().default("standard"),
+  performanceScore: integer("performance_score").notNull().default(100),
+  suspensionReason: text("suspension_reason"),
+  suspendedAt: timestamp("suspended_at", { withTimezone: true }),
+  commissionRateBps: integer("commission_rate_bps").notNull().default(1000),
+  payoutSchedule: text("payout_schedule").notNull().default("weekly"),
+  payoutMinimumCents: integer("payout_minimum_cents").notNull().default(5000),
+  holdbackDays: integer("holdback_days").notNull().default(7),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+
+  // ─── Store Connection (links vendor to their Shopify/WooCommerce store) ─────
+  storeConnectionProvider: text("store_connection_provider"),  // "shopify" | "woocommerce" | null
+  storeConnectionUrl: text("store_connection_url"),
+  storeAccessToken: text("store_access_token"),               // Shopify token or WC consumer key
+  storeConsumerSecret: text("store_consumer_secret"),          // WooCommerce consumer secret (null for Shopify)
+  storeWebhookSecret: text("store_webhook_secret"),
+  lastSyncAt: timestamp("last_sync_at", { withTimezone: true }),
+  syncStatus: text("sync_status").default("disconnected"),    // "healthy" | "stale" | "error" | "disconnected"
+
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgSlugUnique: uniqueIndex("marketplace_vendors_org_slug_unique").on(table.organizationId, table.slug),
+  orgIdx: index("idx_marketplace_vendors_org").on(table.organizationId),
+}));
+
+// ─── Vendor–Entity Links ─────────────────────────────────────────────────────
+
+export const vendorEntities = pgTable("marketplace_vendor_entities", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  entityId: uuid("entity_id").notNull(), // FK: → sellable_entities.id (cross-package; skipped due to drizzle-orm version mismatch between core and plugin)
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Vendor Documents ────────────────────────────────────────────────────────
+
+export const vendorDocuments = pgTable("marketplace_vendor_documents", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  type: text("type").notNull(),
+  fileUrl: text("file_url").notNull(),
+  status: text("status").notNull().default("pending"),
+  reviewerNotes: text("reviewer_notes"),
+  uploadedAt: timestamp("uploaded_at", { withTimezone: true }).defaultNow().notNull(),
+  reviewedAt: timestamp("reviewed_at", { withTimezone: true }),
+});
+
+// ─── Commission Rules ────────────────────────────────────────────────────────
+
+export const commissionRules = pgTable("marketplace_commission_rules", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  name: text("name").notNull(),
+  type: text("type").notNull(),
+  categorySlug: text("category_slug"),
+  vendorId: uuid("vendor_id").references(() => vendors.id, { onDelete: "cascade" }),
+  vendorTier: text("vendor_tier"),
+  minVolumeCents: integer("min_volume_cents"),
+  maxVolumeCents: integer("max_volume_cents"),
+  rateBps: integer("rate_bps").notNull(),
+  validFrom: timestamp("valid_from", { withTimezone: true }),
+  validUntil: timestamp("valid_until", { withTimezone: true }),
+  priority: integer("priority").notNull().default(0),
+  isActive: boolean("is_active").notNull().default(true),
+});
+
+// ─── Sub-Orders ──────────────────────────────────────────────────────────────
+
+export const vendorSubOrders = pgTable("marketplace_vendor_sub_orders", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  orderId: uuid("order_id").notNull(), // FK: → orders.id (cross-package; skipped due to drizzle-orm version mismatch between core and plugin)
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  status: text("status").notNull().default("pending"),
+  subtotal: integer("subtotal").notNull().default(0),
+  commissionAmount: integer("commission_amount").notNull().default(0),
+  payoutAmount: integer("payout_amount").notNull().default(0),
+  notified: boolean("notified").notNull().default(false),
+  lineItems: jsonb("line_items").$type<Array<{ entityId: string; quantity: number; totalPrice: number }>>().default([]),
+  trackingNumber: text("tracking_number"),
+  trackingUrl: text("tracking_url"),
+  carrier: text("carrier"),
+  fulfillmentStatus: text("fulfillment_status").notNull().default("unfulfilled"),  // "unfulfilled" | "partially_fulfilled" | "fulfilled"
+  confirmedAt: timestamp("confirmed_at", { withTimezone: true }),
+  shippedAt: timestamp("shipped_at", { withTimezone: true }),
+  deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+  cancelledAt: timestamp("cancelled_at", { withTimezone: true }),
+  cancellationReason: text("cancellation_reason"),
+  vendorNotes: text("vendor_notes"),
+
+  // ─── External Store Sync ────────────────────────────────────────────────────
+  externalOrderId: text("external_order_id"),       // Order ID in vendor's external store
+  externalOrderUrl: text("external_order_url"),      // Admin URL for vendor to view the order
+  externalSyncStatus: text("external_sync_status").default("pending"),  // "pending" | "synced" | "failed"
+
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Payouts ─────────────────────────────────────────────────────────────────
+
+export const vendorPayouts = pgTable("marketplace_vendor_payouts", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  subOrderId: uuid("sub_order_id"),
+  amount: integer("amount").notNull().default(0),
+  status: text("status").notNull().default("pending"),
+  payoutMethod: text("payout_method"),
+  externalReference: text("external_reference"),
+  periodStart: timestamp("period_start", { withTimezone: true }),
+  periodEnd: timestamp("period_end", { withTimezone: true }),
+  grossAmount: integer("gross_amount"),
+  deductions: jsonb("deductions").$type<Array<{ type: string; amount: number; reference?: string }>>(),
+  netAmount: integer("net_amount"),
+  failedAt: timestamp("failed_at", { withTimezone: true }),
+  failureReason: text("failure_reason"),
+  retryCount: integer("retry_count").notNull().default(0),
+  processedAt: timestamp("processed_at", { withTimezone: true }),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Vendor Balance Ledger ───────────────────────────────────────────────────
+
+export const vendorBalances = pgTable("marketplace_vendor_balances", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  type: text("type").notNull(),
+  amountCents: integer("amount_cents").notNull(),
+  runningBalanceCents: integer("running_balance_cents").notNull(),
+  referenceType: text("reference_type"),
+  referenceId: uuid("reference_id"),
+  description: text("description"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Disputes ────────────────────────────────────────────────────────────────
+
+export const disputes = pgTable("marketplace_disputes", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  subOrderId: uuid("sub_order_id").notNull().references(() => vendorSubOrders.id, { onDelete: "cascade" }),
+  openedBy: text("opened_by").notNull(),
+  reason: text("reason").notNull(),
+  description: text("description"),
+  status: text("status").notNull().default("open"),
+  resolution: text("resolution"),
+  resolutionNotes: text("resolution_notes"),
+  refundAmountCents: integer("refund_amount_cents"),
+  evidence: jsonb("evidence").$type<Array<{ party: string; type: string; url?: string; note?: string; at: string }>>().default([]),
+  resolvedBy: text("resolved_by"),
+  deadlineAt: timestamp("deadline_at", { withTimezone: true }),
+  openedAt: timestamp("opened_at", { withTimezone: true }).defaultNow().notNull(),
+  resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+});
+
+// ─── Vendor Reviews ──────────────────────────────────────────────────────────
+
+export const vendorReviews = pgTable("marketplace_vendor_reviews", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id"),
+  orderId: uuid("order_id"),
+  rating: integer("rating").notNull(),
+  title: text("title"),
+  body: text("body"),
+  status: text("status").notNull().default("published"),
+  vendorResponse: text("vendor_response"),
+  vendorRespondedAt: timestamp("vendor_responded_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Return Requests ─────────────────────────────────────────────────────────
+
+export const returnRequests = pgTable("marketplace_return_requests", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  subOrderId: uuid("sub_order_id").notNull().references(() => vendorSubOrders.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id"),
+  reason: text("reason").notNull(),
+  description: text("description"),
+  status: text("status").notNull().default("requested"),
+  lineItems: jsonb("line_items").$type<Array<{ entityId: string; quantity: number; reason?: string }>>(),
+  refundAmountCents: integer("refund_amount_cents"),
+  vendorNotes: text("vendor_notes"),
+  trackingNumber: text("tracking_number"),
+  requestedAt: timestamp("requested_at", { withTimezone: true }).defaultNow().notNull(),
+  resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+});
+
+// ─── RFQ (B2B) ──────────────────────────────────────────────────────────────
+
+export const rfqs = pgTable("marketplace_rfq", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  buyerId: uuid("buyer_id"),
+  title: text("title").notNull(),
+  description: text("description"),
+  categorySlug: text("category_slug"),
+  quantity: integer("quantity"),
+  budgetCents: integer("budget_cents"),
+  currency: text("currency").notNull().default("USD"),
+  deadlineAt: timestamp("deadline_at", { withTimezone: true }),
+  status: text("status").notNull().default("open"),
+  awardedVendorId: uuid("awarded_vendor_id"),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+export const rfqResponses = pgTable("marketplace_rfq_responses", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  rfqId: uuid("rfq_id").notNull().references(() => rfqs.id, { onDelete: "cascade" }),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  unitPriceCents: integer("unit_price_cents").notNull(),
+  totalPriceCents: integer("total_price_cents").notNull(),
+  leadTimeDays: integer("lead_time_days"),
+  notes: text("notes"),
+  status: text("status").notNull().default("submitted"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Contract Prices (B2B) ───────────────────────────────────────────────────
+
+export const contractPrices = pgTable("marketplace_contract_prices", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  vendorId: uuid("vendor_id").notNull().references(() => vendors.id, { onDelete: "cascade" }),
+  buyerId: uuid("buyer_id").notNull(),
+  entityId: uuid("entity_id").notNull(),
+  variantId: uuid("variant_id"),
+  priceCents: integer("price_cents").notNull(),
+  minQuantity: integer("min_quantity").notNull().default(1),
+  currency: text("currency").notNull().default("USD"),
+  validFrom: timestamp("valid_from", { withTimezone: true }),
+  validUntil: timestamp("valid_until", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});

package/src/schemas/b2b.ts

@@ -0,0 +1,238 @@
+import { z, createRoute } from "@hono/zod-openapi";
+
+const ErrorSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+  }),
+});
+
+const errorResponses = {
+  401: { content: { "application/json": { schema: ErrorSchema } }, description: "Authentication required." },
+  403: { content: { "application/json": { schema: ErrorSchema } }, description: "Insufficient permissions." },
+  404: { content: { "application/json": { schema: ErrorSchema } }, description: "Not found." },
+  422: { content: { "application/json": { schema: ErrorSchema } }, description: "Validation error." },
+  500: { content: { "application/json": { schema: ErrorSchema } }, description: "Server error." },
+} as const;
+
+const DataResponseSchema = z.object({ data: z.any() });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RFQ (Request for Quote)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// ─── Create RFQ ─────────────────────────────────────────────────────────────
+
+export const CreateRFQBodySchema = z.object({
+  title: z.string().min(1).openapi({ example: "Bulk order: 500 widgets" }),
+  buyerId: z.string().optional(),
+  description: z.string().optional(),
+  categorySlug: z.string().optional(),
+  quantity: z.number().int().optional().openapi({ example: 500 }),
+  budgetCents: z.number().int().optional().openapi({ example: 500000 }),
+  currency: z.string().optional().openapi({ example: "USD" }),
+  deadlineAt: z.string().optional().openapi({ example: "2026-04-01T00:00:00Z", description: "ISO 8601 date string" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateRFQRequest");
+
+export const createRFQRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/rfq",
+  tags: ["Marketplace - B2B"],
+  summary: "Create a Request for Quote",
+  request: {
+    body: { content: { "application/json": { schema: CreateRFQBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponseSchema } }, description: "RFQ created." },
+    ...errorResponses,
+  },
+});
+
+// ─── Respond to RFQ ─────────────────────────────────────────────────────────
+
+export const RespondRFQBodySchema = z.object({
+  vendorId: z.string().min(1).openapi({ example: "vendor_abc" }),
+  unitPriceCents: z.number().int().openapi({ example: 800 }),
+  totalPriceCents: z.number().int().openapi({ example: 400000 }),
+  leadTimeDays: z.number().int().optional().openapi({ example: 14 }),
+  notes: z.string().optional(),
+}).openapi("RespondRFQRequest");
+
+export const respondRFQRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/rfq/{id}/respond",
+  tags: ["Marketplace - B2B"],
+  summary: "Submit a vendor response to an RFQ",
+  request: {
+    params: z.object({ id: z.string() }),
+    body: { content: { "application/json": { schema: RespondRFQBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponseSchema } }, description: "RFQ response submitted." },
+    ...errorResponses,
+  },
+});
+
+// ─── Award RFQ ──────────────────────────────────────────────────────────────
+
+export const AwardRFQBodySchema = z.object({
+  vendorId: z.string().min(1).openapi({ example: "vendor_abc" }),
+}).openapi("AwardRFQRequest");
+
+export const awardRFQRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/rfq/{id}/award",
+  tags: ["Marketplace - B2B"],
+  summary: "Award an RFQ to a vendor",
+  request: {
+    params: z.object({ id: z.string() }),
+    body: { content: { "application/json": { schema: AwardRFQBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "RFQ awarded." },
+    ...errorResponses,
+  },
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONTRACT PRICES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// ─── Create Contract Price ──────────────────────────────────────────────────
+
+export const CreateContractPriceBodySchema = z.object({
+  vendorId: z.string().min(1).openapi({ example: "vendor_abc" }),
+  buyerId: z.string().min(1).openapi({ example: "buyer_xyz" }),
+  entityId: z.string().min(1).openapi({ example: "product_001" }),
+  variantId: z.string().optional(),
+  priceCents: z.number().int().openapi({ example: 7500 }),
+  minQuantity: z.number().int().optional().openapi({ example: 100 }),
+  currency: z.string().optional().openapi({ example: "USD" }),
+  validFrom: z.string().optional().openapi({ example: "2026-01-01T00:00:00Z", description: "ISO 8601 date string" }),
+  validUntil: z.string().optional().openapi({ example: "2026-12-31T23:59:59Z", description: "ISO 8601 date string" }),
+}).openapi("CreateContractPriceRequest");
+
+export const createContractPriceRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/contract-prices",
+  tags: ["Marketplace - B2B"],
+  summary: "Create a contract price",
+  request: {
+    body: { content: { "application/json": { schema: CreateContractPriceBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponseSchema } }, description: "Contract price created." },
+    ...errorResponses,
+  },
+});
+
+// ─── Update Contract Price ──────────────────────────────────────────────────
+
+export const UpdateContractPriceBodySchema = z.object({
+  priceCents: z.number().int().optional().openapi({ example: 7000 }),
+  minQuantity: z.number().int().optional(),
+  validFrom: z.string().nullable().optional().openapi({ description: "ISO 8601 date string or null to clear" }),
+  validUntil: z.string().nullable().optional().openapi({ description: "ISO 8601 date string or null to clear" }),
+}).openapi("UpdateContractPriceRequest");
+
+export const updateContractPriceRoute = createRoute({
+  method: "patch",
+  path: "/api/marketplace/contract-prices/{id}",
+  tags: ["Marketplace - B2B"],
+  summary: "Update a contract price",
+  request: {
+    params: z.object({ id: z.string() }),
+    body: { content: { "application/json": { schema: UpdateContractPriceBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "Contract price updated." },
+    ...errorResponses,
+  },
+});
+
+// ─── List RFQs ──────────────────────────────────────────────────────────────
+
+export const listRFQsRoute = createRoute({
+  method: "get",
+  path: "/api/marketplace/rfq",
+  tags: ["Marketplace - B2B"],
+  summary: "List Requests for Quote",
+  request: {
+    query: z.object({
+      status: z.string().optional(),
+      categorySlug: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "Success" },
+    ...errorResponses,
+  },
+});
+
+// ─── Get RFQ ────────────────────────────────────────────────────────────────
+
+export const getRFQRoute = createRoute({
+  method: "get",
+  path: "/api/marketplace/rfq/{id}",
+  tags: ["Marketplace - B2B"],
+  summary: "Get RFQ detail",
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "Success" },
+    ...errorResponses,
+  },
+});
+
+// ─── Close RFQ ──────────────────────────────────────────────────────────────
+
+export const closeRFQRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/rfq/{id}/close",
+  tags: ["Marketplace - B2B"],
+  summary: "Close an RFQ",
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "RFQ closed." },
+    ...errorResponses,
+  },
+});
+
+// ─── List Contract Prices ───────────────────────────────────────────────────
+
+export const listContractPricesRoute = createRoute({
+  method: "get",
+  path: "/api/marketplace/contract-prices",
+  tags: ["Marketplace - B2B"],
+  summary: "List contract prices",
+  request: {
+    query: z.object({
+      vendorId: z.string().optional(),
+      buyerId: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "Success" },
+    ...errorResponses,
+  },
+});
+
+// ─── Delete Contract Price ──────────────────────────────────────────────────
+
+export const deleteContractPriceRoute = createRoute({
+  method: "delete",
+  path: "/api/marketplace/contract-prices/{id}",
+  tags: ["Marketplace - B2B"],
+  summary: "Delete a contract price",
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponseSchema } }, description: "Contract price deleted." },
+    ...errorResponses,
+  },
+});

package/src/schemas/commission.ts

@@ -0,0 +1,129 @@
+import { z, createRoute } from "@hono/zod-openapi";
+
+const ErrorSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+  }),
+});
+
+const errorResponses = {
+  401: { content: { "application/json": { schema: ErrorSchema } }, description: "Authentication required." },
+  403: { content: { "application/json": { schema: ErrorSchema } }, description: "Insufficient permissions." },
+  404: { content: { "application/json": { schema: ErrorSchema } }, description: "Not found." },
+  422: { content: { "application/json": { schema: ErrorSchema } }, description: "Validation error." },
+  500: { content: { "application/json": { schema: ErrorSchema } }, description: "Server error." },
+} as const;
+
+const CommissionResponseSchema = z.object({ data: z.any() });
+
+// ─── Create Commission Rule ──────────────────────────────────────────────────
+
+export const CreateCommissionRuleBodySchema = z.object({
+  name: z.string().min(1).openapi({ example: "Electronics Category Rate" }),
+  type: z.enum(["category", "volume_tier", "vendor_tier", "promotional"]).openapi({ example: "category" }),
+  rateBps: z.number().int().min(0).max(10000).openapi({ example: 1500, description: "Basis points (100 = 1%)" }),
+  categorySlug: z.string().optional(),
+  vendorId: z.uuid().optional(),
+  vendorTier: z.string().optional(),
+  minVolumeCents: z.number().int().optional(),
+  maxVolumeCents: z.number().int().optional(),
+  validFrom: z.string().optional().openapi({ example: "2026-01-01T00:00:00Z", description: "ISO 8601 date string" }),
+  validUntil: z.string().optional().openapi({ example: "2026-12-31T23:59:59Z", description: "ISO 8601 date string" }),
+  priority: z.number().int().optional(),
+}).openapi("CreateCommissionRuleRequest");
+
+export const createCommissionRuleRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/commission-rules",
+  tags: ["Marketplace - Commission"],
+  summary: "Create a commission rule",
+  request: {
+    body: { content: { "application/json": { schema: CreateCommissionRuleBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: CommissionResponseSchema } }, description: "Commission rule created." },
+    ...errorResponses,
+  },
+});
+
+// ─── Update Commission Rule ──────────────────────────────────────────────────
+
+export const UpdateCommissionRuleBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  rateBps: z.number().int().min(0).max(10000).optional(),
+  categorySlug: z.string().nullable().optional(),
+  vendorTier: z.string().nullable().optional(),
+  minVolumeCents: z.number().int().nullable().optional(),
+  maxVolumeCents: z.number().int().nullable().optional(),
+  validFrom: z.string().nullable().optional().openapi({ description: "ISO 8601 date string or null to clear" }),
+  validUntil: z.string().nullable().optional().openapi({ description: "ISO 8601 date string or null to clear" }),
+  priority: z.number().int().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateCommissionRuleRequest");
+
+export const updateCommissionRuleRoute = createRoute({
+  method: "patch",
+  path: "/api/marketplace/commission-rules/{id}",
+  tags: ["Marketplace - Commission"],
+  summary: "Update a commission rule",
+  request: {
+    params: z.object({ id: z.uuid() }),
+    body: { content: { "application/json": { schema: UpdateCommissionRuleBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: CommissionResponseSchema } }, description: "Commission rule updated." },
+    ...errorResponses,
+  },
+});
+
+// ─── Preview Commission Rate ─────────────────────────────────────────────────
+
+export const PreviewCommissionBodySchema = z.object({
+  vendorId: z.uuid().openapi({ example: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a" }),
+  categorySlug: z.string().optional(),
+  volumeCents: z.number().int().optional().openapi({ example: 100000, description: "Order volume in cents" }),
+}).openapi("PreviewCommissionRequest");
+
+export const previewCommissionRoute = createRoute({
+  method: "post",
+  path: "/api/marketplace/commission-rules/preview",
+  tags: ["Marketplace - Commission"],
+  summary: "Preview the commission rate for a vendor",
+  request: {
+    body: { content: { "application/json": { schema: PreviewCommissionBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: CommissionResponseSchema } }, description: "Commission rate preview." },
+    ...errorResponses,
+  },
+});
+
+// ─── List Commission Rules ──────────────────────────────────────────────────
+
+export const listCommissionRulesRoute = createRoute({
+  method: "get",
+  path: "/api/marketplace/commission-rules",
+  tags: ["Marketplace - Commission"],
+  summary: "List all commission rules",
+  responses: {
+    200: { content: { "application/json": { schema: CommissionResponseSchema } }, description: "Success" },
+    ...errorResponses,
+  },
+});
+
+// ─── Delete Commission Rule ─────────────────────────────────────────────────
+
+export const deleteCommissionRuleRoute = createRoute({
+  method: "delete",
+  path: "/api/marketplace/commission-rules/{id}",
+  tags: ["Marketplace - Commission"],
+  summary: "Delete a commission rule",
+  request: {
+    params: z.object({ id: z.uuid() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: CommissionResponseSchema } }, description: "Commission rule deleted." },
+    ...errorResponses,
+  },
+});