Initial commit: Port Nimara CRM (Layers 0-4)

Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/app/api/v1/admin/connections/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { getActiveConnections } from '@/lib/services/system-monitoring.service';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const connections = await getActiveConnections();
+    return NextResponse.json({ data: connections });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/custom-fields/[fieldId]/route.ts

@@ -0,0 +1,69 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { updateFieldSchema } from '@/lib/validators/custom-fields';
+import {
+  updateDefinition,
+  deleteDefinition,
+} from '@/lib/services/custom-fields.service';
+
+export const PATCH = withAuth(
+  withPermission(
+    'admin',
+    'manage_custom_fields',
+    async (req: NextRequest, ctx, params) => {
+      try {
+        const { fieldId } = params;
+        if (!fieldId) throw new NotFoundError('Custom field');
+
+        const body = await req.json();
+
+        // Parse only allowed fields; if fieldType sneaks in, the service will catch it
+        const data = updateFieldSchema.parse(body);
+
+        // Pass raw body too so service can detect fieldType mutation attempts
+        const updated = await updateDefinition(
+          ctx.portId,
+          fieldId,
+          ctx.userId,
+          { ...data, ...(body.fieldType !== undefined && { fieldType: body.fieldType }) },
+          {
+            userId: ctx.userId,
+            portId: ctx.portId,
+            ipAddress: ctx.ipAddress,
+            userAgent: ctx.userAgent,
+          },
+        );
+
+        return NextResponse.json({ data: updated });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  ),
+);
+
+export const DELETE = withAuth(
+  withPermission(
+    'admin',
+    'manage_custom_fields',
+    async (_req: NextRequest, ctx, params) => {
+      try {
+        const { fieldId } = params;
+        if (!fieldId) throw new NotFoundError('Custom field');
+
+        const result = await deleteDefinition(ctx.portId, fieldId, ctx.userId, {
+          userId: ctx.userId,
+          portId: ctx.portId,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        });
+
+        return NextResponse.json({ data: result });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  ),
+);

src/app/api/v1/admin/custom-fields/route.ts

@@ -0,0 +1,43 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { createFieldSchema } from '@/lib/validators/custom-fields';
+import {
+  listDefinitions,
+  createDefinition,
+} from '@/lib/services/custom-fields.service';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_custom_fields', async (req: NextRequest, ctx) => {
+    try {
+      const { searchParams } = new URL(req.url);
+      const entityType = searchParams.get('entityType') ?? undefined;
+
+      const data = await listDefinitions(ctx.portId, entityType);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_custom_fields', async (req: NextRequest, ctx) => {
+    try {
+      const body = await req.json();
+      const data = createFieldSchema.parse(body);
+
+      const definition = await createDefinition(ctx.portId, ctx.userId, data, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: definition }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/errors/route.ts

@@ -0,0 +1,21 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { getRecentErrors } from '@/lib/services/system-monitoring.service';
+
+export const GET = withAuth(async (req: NextRequest, ctx) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const url = new URL(req.url);
+    const limit = Math.min(100, Math.max(1, parseInt(url.searchParams.get('limit') ?? '20', 10)));
+
+    const errors = await getRecentErrors(limit);
+    return NextResponse.json({ data: errors });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/health/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { healthCheck } from '@/lib/services/system-monitoring.service';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const status = await healthCheck();
+    return NextResponse.json({ data: status });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/queues/[queueName]/[jobId]/retry/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { retryJob } from '@/lib/services/system-monitoring.service';
+import { QUEUE_CONFIGS, type QueueName } from '@/lib/queue';
+
+export const POST = withAuth(async (_req, ctx, params) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const queueName = params['queueName'];
+    const jobId = params['jobId'];
+    if (!queueName || !jobId) {
+      return NextResponse.json({ error: 'Missing parameters' }, { status: 400 });
+    }
+    const validQueues = Object.keys(QUEUE_CONFIGS) as QueueName[];
+    if (!validQueues.includes(queueName as QueueName)) {
+      return NextResponse.json({ error: 'Invalid queue name' }, { status: 400 });
+    }
+
+    await retryJob(queueName as QueueName, jobId, ctx.userId);
+    return NextResponse.json({ data: { success: true } });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/queues/[queueName]/[jobId]/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { deleteJob } from '@/lib/services/system-monitoring.service';
+import { QUEUE_CONFIGS, type QueueName } from '@/lib/queue';
+
+export const DELETE = withAuth(async (_req, ctx, params) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const queueName = params['queueName'];
+    const jobId = params['jobId'];
+    if (!queueName || !jobId) {
+      return NextResponse.json({ error: 'Missing parameters' }, { status: 400 });
+    }
+    const validQueues = Object.keys(QUEUE_CONFIGS) as QueueName[];
+    if (!validQueues.includes(queueName as QueueName)) {
+      return NextResponse.json({ error: 'Invalid queue name' }, { status: 400 });
+    }
+
+    await deleteJob(queueName as QueueName, jobId, ctx.userId);
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/queues/[queueName]/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { getQueueJobs } from '@/lib/services/system-monitoring.service';
+import { QUEUE_CONFIGS, type QueueName } from '@/lib/queue';
+
+export const GET = withAuth(async (req: NextRequest, ctx, params) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const { queueName } = params;
+    const validQueues = Object.keys(QUEUE_CONFIGS) as QueueName[];
+    if (!validQueues.includes(queueName as QueueName)) {
+      return NextResponse.json({ error: 'Invalid queue name' }, { status: 400 });
+    }
+
+    const url = new URL(req.url);
+    const status = (url.searchParams.get('status') ?? 'failed') as
+      | 'waiting'
+      | 'active'
+      | 'completed'
+      | 'failed'
+      | 'delayed';
+    const page = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10));
+    const limit = Math.min(100, Math.max(1, parseInt(url.searchParams.get('limit') ?? '20', 10)));
+
+    const result = await getQueueJobs(queueName as QueueName, status, page, limit);
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/queues/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { getQueueDashboard } from '@/lib/services/system-monitoring.service';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const queues = await getQueueDashboard();
+    return NextResponse.json({ data: queues });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/roles/[id]/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { roles } from '@/lib/db/schema';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, _ctx, params) => {
+    try {
+      const { id } = params;
+      if (!id) {
+        throw new NotFoundError('Role');
+      }
+
+      const role = await db.query.roles.findFirst({
+        where: eq(roles.id, id),
+      });
+
+      if (!role) {
+        throw new NotFoundError('Role');
+      }
+
+      return NextResponse.json({ data: role });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/roles/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { errorResponse } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, _ctx) => {
+    try {
+      const data = await db.query.roles.findMany({
+        orderBy: (roles, { asc }) => [asc(roles.name)],
+      });
+
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/templates/[templateId]/rollback/route.ts

@@ -0,0 +1,37 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { rollbackAdminTemplate } from '@/lib/services/document-templates.service';
+import { rollbackAdminTemplateSchema } from '@/lib/validators/document-templates';
+
+/**
+ * POST /api/v1/admin/templates/[templateId]/rollback
+ * Rolls the template back to a previously saved version.
+ * Creates a new version number (current + 1) with the restored content.
+ *
+ * Body: { version: number }
+ */
+export const POST = withAuth(
+  withPermission('documents', 'manage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, rollbackAdminTemplateSchema);
+      const result = await rollbackAdminTemplate(
+        ctx.portId,
+        params.templateId!,
+        body.version,
+        ctx.userId,
+        {
+          userId: ctx.userId,
+          portId: ctx.portId,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        },
+      );
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/templates/[templateId]/route.ts

@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  getAdminTemplate,
+  updateAdminTemplate,
+  deleteAdminTemplate,
+} from '@/lib/services/document-templates.service';
+import { updateAdminTemplateSchema } from '@/lib/validators/document-templates';
+
+/**
+ * GET /api/v1/admin/templates/[templateId]
+ * Retrieve a single TipTap-based document template.
+ */
+export const GET = withAuth(
+  withPermission('documents', 'manage', async (req, ctx, params) => {
+    try {
+      const template = await getAdminTemplate(ctx.portId, params.templateId!);
+      return NextResponse.json({ data: template });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * PATCH /api/v1/admin/templates/[templateId]
+ * Update a TipTap-based document template. Increments version if content changes.
+ */
+export const PATCH = withAuth(
+  withPermission('documents', 'manage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateAdminTemplateSchema);
+      const updated = await updateAdminTemplate(
+        ctx.portId,
+        params.templateId!,
+        ctx.userId,
+        body,
+        {
+          userId: ctx.userId,
+          portId: ctx.portId,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        },
+      );
+      return NextResponse.json({ data: updated });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * DELETE /api/v1/admin/templates/[templateId]
+ * Delete a TipTap-based document template.
+ */
+export const DELETE = withAuth(
+  withPermission('documents', 'manage', async (req, ctx, params) => {
+    try {
+      await deleteAdminTemplate(
+        ctx.portId,
+        params.templateId!,
+        ctx.userId,
+        {
+          userId: ctx.userId,
+          portId: ctx.portId,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        },
+      );
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/templates/[templateId]/versions/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { getAdminTemplateVersions } from '@/lib/services/document-templates.service';
+
+/**
+ * GET /api/v1/admin/templates/[templateId]/versions
+ * Returns version history for a template, sourced from audit_logs.
+ */
+export const GET = withAuth(
+  withPermission('documents', 'manage', async (req, ctx, params) => {
+    try {
+      const versions = await getAdminTemplateVersions(
+        ctx.portId,
+        params.templateId!,
+      );
+      return NextResponse.json({ data: versions });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/templates/preview/route.ts

@@ -0,0 +1,77 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse, ValidationError } from '@/lib/errors';
+import { generatePdf } from '@/lib/pdf/generate';
+import {
+  validateTipTapDocument,
+  tipTapToPdfmeTemplate,
+  buildContentInputsFromDoc,
+  substituteVariables,
+  type TipTapNode,
+} from '@/lib/pdf/tiptap-to-pdfme';
+import { previewAdminTemplateSchema } from '@/lib/validators/document-templates';
+
+/**
+ * POST /api/v1/admin/templates/preview
+ *
+ * Generates a preview PDF from a TipTap JSON content block.
+ * Returns { data: { pdfBase64: string } } — the client can render this
+ * in an <iframe src="data:application/pdf;base64,..."> or open in a new tab.
+ *
+ * Body:
+ *   content: TipTap JSON document
+ *   sampleData?: Record<string, string> — variable substitutions
+ */
+export const POST = withAuth(
+  withPermission('documents', 'manage', async (req, _ctx) => {
+    try {
+      const body = await parseBody(req, previewAdminTemplateSchema);
+
+      const doc = body.content as unknown as TipTapNode;
+      const sampleData = body.sampleData ?? {};
+
+      // Validate content nodes
+      const unsupported = validateTipTapDocument(doc);
+      if (unsupported.length > 0) {
+        throw new ValidationError(
+          `Content contains unsupported node types: ${unsupported.join(', ')}`,
+        );
+      }
+
+      // Substitute variables in text nodes
+      const substitutedDoc = substituteInDoc(doc, sampleData);
+
+      // Convert to pdfme template + inputs
+      const template = tipTapToPdfmeTemplate(substitutedDoc);
+      const inputs = buildContentInputsFromDoc(substitutedDoc, template);
+
+      const pdfBytes = await generatePdf(template, inputs);
+      const pdfBase64 = Buffer.from(pdfBytes).toString('base64');
+
+      return NextResponse.json({ data: { pdfBase64 } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * Deeply substitutes {{variable}} tokens in all text nodes of a TipTap doc.
+ */
+function substituteInDoc(
+  node: TipTapNode,
+  data: Record<string, string>,
+): TipTapNode {
+  if (node.type === 'text' && node.text) {
+    return { ...node, text: substituteVariables(node.text, data) };
+  }
+  if (node.content) {
+    return {
+      ...node,
+      content: node.content.map((child) => substituteInDoc(child, data)),
+    };
+  }
+  return node;
+}

src/app/api/v1/admin/templates/route.ts

@@ -0,0 +1,50 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  listAdminTemplates,
+  createAdminTemplate,
+} from '@/lib/services/document-templates.service';
+import {
+  listAdminTemplatesSchema,
+  createAdminTemplateSchema,
+} from '@/lib/validators/document-templates';
+
+/**
+ * GET /api/v1/admin/templates
+ * List TipTap-based document templates for the port.
+ */
+export const GET = withAuth(
+  withPermission('documents', 'manage', async (req, ctx) => {
+    try {
+      const query = parseQuery(req, listAdminTemplatesSchema);
+      const data = await listAdminTemplates(ctx.portId, query);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * POST /api/v1/admin/templates
+ * Create a new TipTap-based document template.
+ */
+export const POST = withAuth(
+  withPermission('documents', 'manage', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createAdminTemplateSchema);
+      const template = await createAdminTemplate(ctx.portId, ctx.userId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: template }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/users/options/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { withAuth } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { userPortRoles, userProfiles } from '@/lib/db/schema';
+import { errorResponse } from '@/lib/errors';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    const rows = await db
+      .select({
+        id: userPortRoles.userId,
+        displayName: userProfiles.displayName,
+      })
+      .from(userPortRoles)
+      .innerJoin(userProfiles, eq(userPortRoles.userId, userProfiles.userId))
+      .where(eq(userPortRoles.portId, ctx.portId))
+      .orderBy(userProfiles.displayName);
+
+    return NextResponse.json({ data: rows });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/users/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { userPortRoles, userProfiles, roles } from '@/lib/db/schema';
+import { errorResponse } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx) => {
+    try {
+      const rows = await db
+        .select({
+          userId: userPortRoles.userId,
+          displayName: userProfiles.displayName,
+          isActive: userProfiles.isActive,
+          lastLoginAt: userProfiles.lastLoginAt,
+          roleId: roles.id,
+          roleName: roles.name,
+        })
+        .from(userPortRoles)
+        .innerJoin(userProfiles, eq(userPortRoles.userId, userProfiles.userId))
+        .innerJoin(roles, eq(userPortRoles.roleId, roles.id))
+        .where(eq(userPortRoles.portId, ctx.portId))
+        .orderBy(userProfiles.displayName);
+
+      const data = rows.map((row) => ({
+        userId: row.userId,
+        displayName: row.displayName,
+        isActive: row.isActive,
+        lastLoginAt: row.lastLoginAt,
+        role: { id: row.roleId, name: row.roleName },
+      }));
+
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/webhooks/[webhookId]/deliveries/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listDeliveriesSchema } from '@/lib/validators/webhooks';
+import { listDeliveries } from '@/lib/services/webhooks.service';
+
+// ─── GET /api/v1/admin/webhooks/[webhookId]/deliveries ────────────────────────
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_webhooks', async (req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      const query = parseQuery(req, listDeliveriesSchema);
+      const result = await listDeliveries(ctx.portId, webhookId!, query);
+      return NextResponse.json(result);
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/webhooks/[webhookId]/regenerate-secret/route.ts

@@ -0,0 +1,24 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { regenerateSecret } from '@/lib/services/webhooks.service';
+
+// ─── POST /api/v1/admin/webhooks/[webhookId]/regenerate-secret ────────────────
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_webhooks', async (_req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      const data = await regenerateSecret(ctx.portId, webhookId!, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/webhooks/[webhookId]/route.ts

@@ -0,0 +1,64 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateWebhookSchema } from '@/lib/validators/webhooks';
+import {
+  getWebhook,
+  updateWebhook,
+  deleteWebhook,
+} from '@/lib/services/webhooks.service';
+
+// ─── GET /api/v1/admin/webhooks/[webhookId] ───────────────────────────────────
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_webhooks', async (_req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      const data = await getWebhook(ctx.portId, webhookId!);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+// ─── PATCH /api/v1/admin/webhooks/[webhookId] ─────────────────────────────────
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_webhooks', async (req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      const body = await parseBody(req, updateWebhookSchema);
+      const data = await updateWebhook(ctx.portId, webhookId!, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+// ─── DELETE /api/v1/admin/webhooks/[webhookId] ────────────────────────────────
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_webhooks', async (_req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      await deleteWebhook(ctx.portId, webhookId!, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/webhooks/[webhookId]/test/route.ts

@@ -0,0 +1,27 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { WEBHOOK_EVENTS } from '@/lib/services/webhook-event-map';
+import { sendTestWebhook } from '@/lib/services/webhooks.service';
+
+const testWebhookSchema = z.object({
+  eventType: z.enum(WEBHOOK_EVENTS).default('client.created'),
+});
+
+// ─── POST /api/v1/admin/webhooks/[webhookId]/test ─────────────────────────────
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_webhooks', async (req: NextRequest, ctx, params) => {
+    try {
+      const { webhookId } = params;
+      const body = await parseBody(req, testWebhookSchema);
+      const result = await sendTestWebhook(ctx.portId, webhookId!, body.eventType);
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/webhooks/route.ts

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createWebhookSchema } from '@/lib/validators/webhooks';
+import { listWebhooks, createWebhook } from '@/lib/services/webhooks.service';
+
+// ─── GET /api/v1/admin/webhooks ───────────────────────────────────────────────
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_webhooks', async (_req: NextRequest, ctx) => {
+    try {
+      const data = await listWebhooks(ctx.portId);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+// ─── POST /api/v1/admin/webhooks ──────────────────────────────────────────────
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_webhooks', async (req: NextRequest, ctx) => {
+    try {
+      const body = await parseBody(req, createWebhookSchema);
+      const webhook = await createWebhook(ctx.portId, ctx.userId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: webhook }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);