@vellumai/assistant 0.6.5 → 0.7.0

package/src/runtime/routes/contact-routes.ts

@@ -1,20 +1,17 @@
 /**
- * Route handlers for contact management endpoints.
+ * Route handlers for contact and invite management endpoints.
  *
- * GET    /v1/contacts                      — list contacts
- * POST   /v1/contacts                      — create or update a contact
- * GET    /v1/contacts/:id                  — get a contact by ID
- * DELETE /v1/contacts/:id                  — delete a contact
- * POST   /v1/contacts/merge                — merge two contacts
- * POST   /v1/contacts/guardian/channel      — add a channel to the guardian contact
- * PATCH  /v1/contact-channels/:contactChannelId — update a contact channel's status/policy
+ * All routes are served by both the HTTP server and the IPC server
+ * via the shared ROUTES array.
+ *
+ * IMPORTANT: contacts/:id routes are placed LAST in the ROUTES array so
+ * they don't shadow more-specific sub-paths like contacts/invites.
  */
 
 import { z } from "zod";
 
 import {
   deleteContact,
-  findGuardianContact,
   getAssistantContactMetadata,
   getChannelById,
   getContact,
@@ -34,9 +31,21 @@ import type {
   ContactType,
 } from "../../contacts/types.js";
 import { resolveGuardianName } from "../../prompts/user-reference.js";
-import type { AuthContext } from "../auth/types.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import {
+  createIngressInvite,
+  listIngressInvites,
+  redeemIngressInvite,
+  redeemVoiceInviteCode,
+  revokeIngressInvite,
+  triggerInviteCall,
+} from "../invite-service.js";
+import {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function withGuardianNameOverride<
   T extends { role: string; displayName: string },
@@ -56,144 +65,550 @@ const VALID_ASSISTANT_SPECIES: readonly AssistantSpecies[] = [
   "openclaw",
 ];
 
-/**
- * GET /v1/contacts?limit=50&role=guardian&contactType=human
- *
- * Also supports search query params: query, channelAddress, channelType.
- * When any search param is provided, delegates to searchContacts() instead of listContacts().
- */
-export function handleListContacts(url: URL): Response {
-  const limit = Number(url.searchParams.get("limit") ?? 50);
-  const role = url.searchParams.get("role") as ContactRole | null;
-  const contactTypeParam = url.searchParams.get("contactType");
-  const query = url.searchParams.get("query");
-  const channelAddress = url.searchParams.get("channelAddress");
-  const channelType = url.searchParams.get("channelType");
+const VALID_CHANNEL_STATUSES: readonly ChannelStatus[] = [
+  "active",
+  "pending",
+  "revoked",
+  "blocked",
+  "unverified",
+];
+const VALID_CHANNEL_POLICIES: readonly ChannelPolicy[] = [
+  "allow",
+  "deny",
+  "escalate",
+];
+
+function isContactType(value: string): value is ContactType {
+  return (VALID_CONTACT_TYPES as readonly string[]).includes(value);
+}
+
+function isAssistantSpecies(value: string): value is AssistantSpecies {
+  return (VALID_ASSISTANT_SPECIES as readonly string[]).includes(value);
+}
+
+function isChannelStatus(value: string): value is ChannelStatus {
+  return (VALID_CHANNEL_STATUSES as readonly string[]).includes(value);
+}
+
+function isChannelPolicy(value: string): value is ChannelPolicy {
+  return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
+}
+
+// ---------------------------------------------------------------------------
+// Contact handlers (transport-agnostic)
+// ---------------------------------------------------------------------------
+
+function handleListContacts(queryParams: Record<string, string>) {
+  const limit = Number(queryParams.limit ?? 50);
+  const role = (queryParams.role as ContactRole) || undefined;
+  const contactTypeParam = queryParams.contactType;
+  const query = queryParams.query || undefined;
+  const channelAddress = queryParams.channelAddress || undefined;
+  const channelType = queryParams.channelType || undefined;
+
   if (contactTypeParam && !isContactType(contactTypeParam)) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid contactType "${contactTypeParam}". Must be one of: ${VALID_CONTACT_TYPES.join(", ")}`,
-      400,
     );
   }
 
-  const hasSearchParams = query || channelAddress || channelType;
-
   const contactType = contactTypeParam
     ? (contactTypeParam as ContactType)
     : undefined;
 
-  if (hasSearchParams) {
+  if (query || channelAddress || channelType) {
     const contacts = searchContacts({
-      query: query ?? undefined,
-      channelAddress: channelAddress ?? undefined,
-      channelType: channelType ?? undefined,
-      role: role ?? undefined,
+      query,
+      channelAddress,
+      channelType,
+      role,
       contactType,
       limit,
     });
-    return Response.json({
+    return {
       ok: true,
       contacts: contacts.map(withGuardianNameOverride),
-    });
+    };
   }
 
-  const contacts = listContacts(limit, role ?? undefined, contactType);
-  return Response.json({
+  const contacts = listContacts(limit, role, contactType);
+  return {
     ok: true,
     contacts: contacts.map(withGuardianNameOverride),
-  });
+  };
 }
 
-/**
- * GET /v1/contacts/:id
- */
-export function handleGetContact(contactId: string): Response {
+function handleGetContact(contactId: string) {
   const contact = getContact(contactId);
   if (!contact) {
-    return httpError("NOT_FOUND", `Contact "${contactId}" not found`, 404);
+    throw new NotFoundError(`Contact "${contactId}" not found`);
   }
   const assistantMeta =
     contact.contactType === "assistant"
       ? getAssistantContactMetadata(contact.id)
       : undefined;
-  return Response.json({
+  return {
     ok: true,
     contact: withGuardianNameOverride(contact),
     assistantMetadata: assistantMeta ?? undefined,
-  });
+  };
 }
 
-/**
- * DELETE /v1/contacts/:id
- */
-export function handleDeleteContact(contactId: string): Response {
+function handleDeleteContact(contactId: string) {
   const result = deleteContact(contactId);
   if (result === "not_found") {
-    return httpError("NOT_FOUND", `Contact "${contactId}" not found`, 404);
+    throw new NotFoundError(`Contact "${contactId}" not found`);
   }
   if (result === "is_guardian") {
-    return httpError("FORBIDDEN", "Cannot delete a guardian contact", 403);
+    throw new ForbiddenError("Cannot delete a guardian contact");
   }
-  return new Response(null, { status: 204 });
+  return null;
 }
 
-/**
- * POST /v1/contacts/merge { keepId, mergeId }
- */
-export async function handleMergeContacts(req: Request): Promise<Response> {
-  const body = (await req.json()) as { keepId?: string; mergeId?: string };
+// ---------------------------------------------------------------------------
+// Invite handlers (transport-agnostic)
+// ---------------------------------------------------------------------------
+
+export function handleListInvites({ queryParams = {} }: RouteHandlerArgs) {
+  const result = listIngressInvites({
+    sourceChannel: queryParams.sourceChannel,
+    status: queryParams.status,
+  });
 
-  if (!body.keepId || !body.mergeId) {
-    return httpError("BAD_REQUEST", "keepId and mergeId are required", 400);
+  if (!result.ok) {
+    throw new BadRequestError(result.error);
   }
+  return { ok: true, invites: result.data };
+}
 
-  try {
-    const contact = mergeContacts(body.keepId, body.mergeId);
-    return Response.json({
-      ok: true,
-      contact: withGuardianNameOverride(contact),
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return httpError("BAD_REQUEST", message, 400);
+export async function handleCreateInvite({ body = {} }: RouteHandlerArgs) {
+  const result = await createIngressInvite({
+    sourceChannel: body.sourceChannel as string | undefined,
+    note: body.note as string | undefined,
+    maxUses: body.maxUses as number | undefined,
+    expiresInMs: body.expiresInMs as number | undefined,
+    contactName: body.contactName as string | undefined,
+    expectedExternalUserId: body.expectedExternalUserId as string | undefined,
+    voiceCodeDigits: body.voiceCodeDigits as number | undefined,
+    friendName: body.friendName as string | undefined,
+    guardianName: body.guardianName as string | undefined,
+    contactId: body.contactId as string,
+  });
+
+  if (!result.ok) {
+    throw new BadRequestError(result.error);
   }
+  return { ok: true, invite: result.data };
 }
 
-const VALID_CHANNEL_STATUSES: readonly ChannelStatus[] = [
-  "active",
-  "pending",
-  "revoked",
-  "blocked",
-  "unverified",
-];
-const VALID_CHANNEL_POLICIES: readonly ChannelPolicy[] = [
-  "allow",
-  "deny",
-  "escalate",
-];
+export function handleRevokeInvite({ pathParams = {} }: RouteHandlerArgs) {
+  const result = revokeIngressInvite(pathParams.id);
 
-function isContactType(value: string): value is ContactType {
-  return (VALID_CONTACT_TYPES as readonly string[]).includes(value);
+  if (!result.ok) {
+    throw new NotFoundError(result.error);
+  }
+  return { ok: true, invite: result.data };
 }
 
-function isAssistantSpecies(value: string): value is AssistantSpecies {
-  return (VALID_ASSISTANT_SPECIES as readonly string[]).includes(value);
+export async function handleRedeemInvite({ body = {} }: RouteHandlerArgs) {
+  if (body.code != null) {
+    const callerExternalUserId = body.callerExternalUserId as
+      | string
+      | undefined;
+    const code = body.code as string | undefined;
+
+    if (!callerExternalUserId || !code) {
+      throw new BadRequestError("callerExternalUserId and code are required");
+    }
+
+    const result = redeemVoiceInviteCode({
+      assistantId: body.assistantId as string | undefined,
+      callerExternalUserId,
+      sourceChannel: "phone",
+      code,
+    });
+
+    if (!result.ok) {
+      throw new BadRequestError(result.reason);
+    }
+
+    return {
+      ok: true,
+      type: result.type,
+      memberId: result.memberId,
+      ...(result.type === "redeemed" ? { inviteId: result.inviteId } : {}),
+    };
+  }
+
+  const result = redeemIngressInvite({
+    token: body.token as string | undefined,
+    externalUserId: body.externalUserId as string | undefined,
+    externalChatId: body.externalChatId as string | undefined,
+    sourceChannel: body.sourceChannel as string | undefined,
+  });
+
+  if (!result.ok) {
+    throw new BadRequestError(result.error);
+  }
+  return { ok: true, invite: result.data };
 }
 
-function isChannelStatus(value: string): value is ChannelStatus {
-  return (VALID_CHANNEL_STATUSES as readonly string[]).includes(value);
+export async function handleTriggerInviteCall({
+  pathParams = {},
+}: RouteHandlerArgs) {
+  const result = await triggerInviteCall(pathParams.id);
+  if (!result.ok) {
+    throw new BadRequestError(result.error);
+  }
+  return { ok: true, callSid: result.data.callSid };
 }
 
-function isChannelPolicy(value: string): value is ChannelPolicy {
-  return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
+// ---------------------------------------------------------------------------
+// Shared route definitions (HTTP + IPC)
+//
+// Order matters: contacts/invites/* routes must precede the contacts/:id
+// catch-all to avoid the parameterized pattern shadowing literal sub-paths.
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  // ── contacts (exact) ────────────────────────────────────────────────
+  {
+    operationId: "listContacts",
+    endpoint: "contacts",
+    method: "GET",
+    summary: "List contacts",
+    description:
+      "Return all contacts, optionally filtered by type or channel status.",
+    tags: ["contacts"],
+    queryParams: [
+      {
+        name: "limit",
+        schema: { type: "integer" },
+        description: "Max contacts to return (default 50)",
+      },
+      {
+        name: "role",
+        schema: { type: "string" },
+        description: "Filter by role (e.g. guardian)",
+      },
+      {
+        name: "contactType",
+        schema: { type: "string" },
+        description: "Filter by contact type (human or assistant)",
+      },
+      {
+        name: "query",
+        schema: { type: "string" },
+        description: "Full-text search query",
+      },
+      {
+        name: "channelAddress",
+        schema: { type: "string" },
+        description: "Filter by channel address",
+      },
+      {
+        name: "channelType",
+        schema: { type: "string" },
+        description: "Filter by channel type",
+      },
+    ],
+    responseBody: z.object({
+      ok: z.boolean(),
+      contacts: z
+        .array(z.unknown())
+        .describe("Contact objects with channels and metadata"),
+    }),
+    handler: ({ queryParams }: RouteHandlerArgs) =>
+      handleListContacts(queryParams ?? {}),
+  },
+
+  // ── contacts/invites (must precede contacts/:id) ────────────────────
+  {
+    operationId: "invites_list",
+    endpoint: "contacts/invites",
+    method: "GET",
+    handler: handleListInvites,
+    summary: "List invites",
+    description:
+      "Return all invites, optionally filtered by sourceChannel or status.",
+    tags: ["contacts"],
+    queryParams: [
+      {
+        name: "sourceChannel",
+        description: "Filter by source channel",
+      },
+      {
+        name: "status",
+        description: "Filter by invite status",
+      },
+    ],
+    responseBody: z.object({
+      ok: z.boolean(),
+      invites: z.array(z.unknown()).describe("Invite objects"),
+    }),
+  },
+  {
+    operationId: "invites_create",
+    endpoint: "contacts/invites",
+    method: "POST",
+    handler: handleCreateInvite,
+    responseStatus: "201",
+    summary: "Create an invite",
+    description:
+      'Create a new invite. Supports voice invites when sourceChannel is "phone".',
+    tags: ["contacts"],
+    requestBody: z.object({
+      contactId: z.string().describe("Contact to invite"),
+      sourceChannel: z
+        .string()
+        .describe("Source channel (e.g. phone)")
+        .optional(),
+      note: z.string().describe("Optional note").optional(),
+      maxUses: z.number().describe("Max redemptions").optional(),
+      expiresInMs: z.number().describe("Expiry duration in ms").optional(),
+      contactName: z.string().describe("Contact display name").optional(),
+      expectedExternalUserId: z
+        .string()
+        .describe("Expected user ID (E.164 for phone)")
+        .optional(),
+      friendName: z.string().describe("Friend name for the invite").optional(),
+      guardianName: z.string().describe("Guardian name").optional(),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      invite: z.object({}).passthrough().describe("Created invite"),
+    }),
+    additionalResponses: {
+      "400": {
+        description: "Invalid invite parameters",
+      },
+    },
+  },
+  {
+    operationId: "invites_redeem",
+    endpoint: "contacts/invites/redeem",
+    method: "POST",
+    handler: handleRedeemInvite,
+    summary: "Redeem an invite",
+    description: "Redeem an invite by token or voice code.",
+    tags: ["contacts"],
+    requestBody: z.object({
+      token: z.string().describe("Invite token (token-based redemption)"),
+      code: z.string().describe("Voice code (voice-code redemption)"),
+      callerExternalUserId: z
+        .string()
+        .describe("Caller E.164 phone (voice-code)"),
+      externalUserId: z.string().describe("External user ID (token-based)"),
+      externalChatId: z.string().describe("External chat ID (token-based)"),
+      sourceChannel: z.string().describe("Source channel (token-based)"),
+      assistantId: z.string().describe("Assistant ID (voice-code)"),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      invite: z
+        .object({})
+        .passthrough()
+        .describe("Redeemed invite (token path)"),
+      type: z.string().describe("Redemption type (voice path)"),
+      memberId: z.string().describe("Member ID (voice path)"),
+    }),
+    additionalResponses: {
+      "400": {
+        description: "Invalid redemption parameters or failed redemption",
+      },
+    },
+  },
+  {
+    operationId: "invites_revoke",
+    endpoint: "contacts/invites/:id",
+    method: "DELETE",
+    policyKey: "contacts/invites",
+    handler: handleRevokeInvite,
+    summary: "Revoke an invite",
+    description: "Revoke an invite by ID.",
+    tags: ["contacts"],
+    additionalResponses: {
+      "404": {
+        description: "Invite not found",
+      },
+    },
+  },
+  {
+    operationId: "invites_trigger_call",
+    endpoint: "contacts/invites/:id/call",
+    method: "POST",
+    policyKey: "contacts/invites",
+    handler: handleTriggerInviteCall,
+    summary: "Trigger invite call",
+    description: "Trigger an outbound call for a phone invite.",
+    tags: ["contacts"],
+    responseBody: z.object({
+      ok: z.boolean(),
+      callSid: z.string().describe("Call SID from the provider"),
+    }),
+    additionalResponses: {
+      "400": {
+        description: "Invite not eligible for outbound call",
+      },
+    },
+  },
+
+  // ── contacts/search ──────────────────────────────────────────────────
+  {
+    operationId: "search_contacts",
+    endpoint: "contacts/search",
+    method: "POST",
+    summary: "Search contacts",
+    description: "Search contacts by query, channel address, or channel type.",
+    tags: ["contacts"],
+    requestBody: z.object({
+      query: z.string().optional(),
+      channelAddress: z.string().optional(),
+      channelType: z.string().optional(),
+      limit: z.number().optional(),
+    }),
+    responseBody: z.array(z.object({}).passthrough()),
+    handler: ({ body = {} }: RouteHandlerArgs) => {
+      const parsed = z
+        .object({
+          query: z.string().optional(),
+          channelAddress: z.string().optional(),
+          channelType: z.string().optional(),
+          limit: z.number().optional(),
+        })
+        .parse(body);
+      return searchContacts(parsed);
+    },
+  },
+
+  // ── contacts/:id (MUST be last — path param shadows sub-paths) ────
+  {
+    operationId: "getContact",
+    endpoint: "contacts/:id",
+    method: "GET",
+    policyKey: "contacts",
+    summary: "Get a contact",
+    description:
+      "Return a single contact with its channels and assistant metadata.",
+    tags: ["contacts"],
+    responseBody: z.object({
+      ok: z.boolean(),
+      contact: z.object({}).passthrough().describe("Contact details"),
+      assistantMetadata: z
+        .object({})
+        .passthrough()
+        .describe("Assistant-side metadata"),
+    }),
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleGetContact(pathParams!.id),
+  },
+  {
+    operationId: "deleteContact",
+    endpoint: "contacts/:id",
+    method: "DELETE",
+    policyKey: "contacts",
+    summary: "Delete a contact",
+    description: "Delete a contact by ID.",
+    tags: ["contacts"],
+    responseStatus: "204",
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleDeleteContact(pathParams!.id),
+  },
+  {
+    operationId: "upsert_contact",
+    endpoint: "contacts",
+    method: "POST",
+    summary: "Create or update a contact",
+    description:
+      "Create a new contact or update an existing one. Supports upsert by contactId or channel handle.",
+    tags: ["contacts"],
+    requestBody: z.object({
+      contactId: z.string().describe("Existing contact ID (for update)"),
+      displayName: z.string().describe("Display name"),
+      channels: z
+        .array(z.unknown())
+        .describe("Channel objects with channelId, handle, displayName"),
+      assistantMetadata: z
+        .object({})
+        .passthrough()
+        .describe("Assistant-side metadata"),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      contact: z
+        .object({})
+        .passthrough()
+        .describe("Created or updated contact"),
+    }),
+    handler: (args: RouteHandlerArgs) => handleUpsertContactRoute(args),
+  },
+  {
+    operationId: "merge_contacts",
+    endpoint: "contacts/merge",
+    method: "POST",
+    summary: "Merge two contacts",
+    description: "Merge two contacts, keeping one and absorbing the other.",
+    tags: ["contacts"],
+    requestBody: z.object({
+      keepId: z.string().describe("ID of the contact to keep"),
+      mergeId: z
+        .string()
+        .describe("ID of the contact to merge into the kept one"),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      contact: z.object({}).passthrough().describe("Merged contact"),
+    }),
+    handler: (args: RouteHandlerArgs) => handleMergeContactsRoute(args),
+  },
+  {
+    operationId: "updateContactChannel",
+    endpoint: "contact-channels/:contactChannelId",
+    method: "PATCH",
+    policyKey: "contact-channels",
+    summary: "Update a contact channel",
+    description: "Update status, policy, or reason on a contact's channel.",
+    tags: ["contacts"],
+    requestBody: z.object({
+      status: z.string().describe("Channel status"),
+      policy: z.string().describe("Channel policy"),
+      reason: z.string().describe("Reason for the change"),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      contact: z
+        .object({})
+        .passthrough()
+        .describe("Updated contact (if applicable)"),
+    }),
+    handler: (args: RouteHandlerArgs) => handleUpdateContactChannelRoute(args),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Transport-agnostic handlers (moved from HTTP-only)
+// ---------------------------------------------------------------------------
+
+function handleMergeContactsRoute(args: RouteHandlerArgs) {
+  const { body } = args;
+  const keepId = body?.keepId as string | undefined;
+  const mergeId = body?.mergeId as string | undefined;
+
+  if (!keepId || !mergeId) {
+    throw new BadRequestError("keepId and mergeId are required");
+  }
+
+  try {
+    const contact = mergeContacts(keepId, mergeId);
+    return { ok: true, contact: withGuardianNameOverride(contact) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new BadRequestError(message);
+  }
 }
 
-/**
- * POST /v1/contacts { displayName, id?, notes?, contactType?, assistantMetadata?, ... }
- */
-export async function handleUpsertContact(req: Request): Promise<Response> {
-  const body = (await req.json()) as {
+function handleUpsertContactRoute(args: RouteHandlerArgs) {
+  const body = (args.body ?? {}) as {
     id?: string;
     displayName?: string;
     notes?: string;
@@ -219,34 +634,26 @@ export async function handleUpsertContact(req: Request): Promise<Response> {
     typeof body.displayName !== "string" ||
     body.displayName.trim().length === 0
   ) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       "displayName is required and must be a non-empty string",
-      400,
     );
   }
 
   if (body.contactType !== undefined && !isContactType(body.contactType)) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid contactType "${body.contactType}". Must be one of: ${VALID_CONTACT_TYPES.join(", ")}`,
-      400,
     );
   }
 
   if (body.contactType === "assistant") {
     if (!body.assistantMetadata) {
-      return httpError(
-        "BAD_REQUEST",
+      throw new BadRequestError(
         'assistantMetadata is required when contactType is "assistant"',
-        400,
       );
     }
     if (!isAssistantSpecies(body.assistantMetadata.species)) {
-      return httpError(
-        "BAD_REQUEST",
+      throw new BadRequestError(
         `Invalid species "${body.assistantMetadata.species}". Must be one of: ${VALID_ASSISTANT_SPECIES.join(", ")}`,
-        400,
       );
     }
     try {
@@ -255,47 +662,37 @@ export async function handleUpsertContact(req: Request): Promise<Response> {
         body.assistantMetadata.metadata ?? null,
       );
     } catch (err) {
-      return httpError(
-        "BAD_REQUEST",
+      throw new BadRequestError(
         err instanceof Error ? err.message : String(err),
-        400,
       );
     }
   }
 
   if (body.contactType === "human" && body.assistantMetadata) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       'assistantMetadata must not be provided when contactType is "human"',
-      400,
     );
   }
 
   if (body.assistantMetadata && !body.contactType) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       'contactType must be "assistant" when assistantMetadata is provided',
-      400,
     );
   }
 
   if (body.channels) {
     if (!Array.isArray(body.channels)) {
-      return httpError("BAD_REQUEST", "channels must be an array", 400);
+      throw new BadRequestError("channels must be an array");
     }
     for (const ch of body.channels) {
       if (ch.status !== undefined && !isChannelStatus(ch.status)) {
-        return httpError(
-          "BAD_REQUEST",
+        throw new BadRequestError(
           `Invalid channel status "${ch.status}". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
-          400,
         );
       }
       if (ch.policy !== undefined && !isChannelPolicy(ch.policy)) {
-        return httpError(
-          "BAD_REQUEST",
+        throw new BadRequestError(
           `Invalid channel policy "${ch.policy}". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
-          400,
         );
       }
     }
@@ -323,62 +720,41 @@ export async function handleUpsertContact(req: Request): Promise<Response> {
       });
     }
 
-    return Response.json(
-      { ok: true, contact: withGuardianNameOverride(contact) },
-      { status: contact.created ? 201 : 200 },
-    );
+    return { ok: true, contact: withGuardianNameOverride(contact) };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return httpError("BAD_REQUEST", message, 400);
+    throw new BadRequestError(message);
   }
 }
 
-/**
- * PATCH /v1/contact-channels/:contactChannelId { status?, policy?, reason? }
- */
-export async function handleUpdateContactChannel(
-  req: Request,
-  channelId: string,
-): Promise<Response> {
-  const body = (await req.json()) as {
+function handleUpdateContactChannelRoute(args: RouteHandlerArgs) {
+  const channelId = args.pathParams!.contactChannelId;
+  const body = (args.body ?? {}) as {
     status?: string;
     policy?: string;
     reason?: string;
   };
 
   if (body.status !== undefined && !isChannelStatus(body.status)) {
-    return httpError(
-      "BAD_REQUEST",
-      `Invalid status "${
-        body.status
-      }". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
-      400,
+    throw new BadRequestError(
+      `Invalid status "${body.status}". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
     );
   }
 
   if (body.policy !== undefined && !isChannelPolicy(body.policy)) {
-    return httpError(
-      "BAD_REQUEST",
-      `Invalid policy "${
-        body.policy
-      }". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
-      400,
+    throw new BadRequestError(
+      `Invalid policy "${body.policy}". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
     );
   }
 
-  // Blocked-state guard: revoking a blocked channel is not allowed because
-  // blocking is a stronger action than revoking. The caller must explicitly
-  // unblock (set status to "active") before revoking.
   if (body.status === "revoked") {
     const existing = getChannelById(channelId);
     if (!existing) {
-      return httpError("NOT_FOUND", `Channel "${channelId}" not found`, 404);
+      throw new NotFoundError(`Channel "${channelId}" not found`);
     }
     if (existing.status === "blocked") {
-      return httpError(
-        "CONFLICT",
+      throw new ConflictError(
         "Cannot revoke a blocked channel. Unblock it first or leave it blocked.",
-        409,
       );
     }
   }
@@ -401,266 +777,16 @@ export async function handleUpdateContactChannel(
   });
 
   if (!updated) {
-    return httpError("NOT_FOUND", `Channel "${channelId}" not found`, 404);
+    throw new NotFoundError(`Channel "${channelId}" not found`);
   }
 
   const parentContact = getContact(updated.contactId);
-  return Response.json({
+  return {
     ok: true,
     contact: parentContact
       ? withGuardianNameOverride(parentContact)
       : undefined,
-  });
-}
-
-/**
- * POST /v1/contacts/guardian/channel
- *
- * Add a single channel to the existing guardian contact.
- * If no guardian contact exists, returns 404.
- * If the caller is not the guardian, returns 403.
- *
- * Used by the guardian to auto-verify their own channel.
- */
-export async function handleAddGuardianChannel(
-  req: Request,
-  authContext: AuthContext,
-): Promise<Response> {
-  // This endpoint is restricted to gateway service tokens only — the
-  // platform calls it during email registration to auto-verify the owner's
-  // email as a guardian channel. Direct actor/local calls are not permitted
-  // because the endpoint bypasses normal channel verification (no code sent,
-  // no confirmation) and would allow guardian channel takeover (ATL-102).
-  if (authContext.principalType !== "svc_gateway") {
-    return httpError(
-      "FORBIDDEN",
-      "This endpoint is restricted to platform service calls",
-      403,
-    );
-  }
-
-  const body = (await req.json()) as {
-    type: string;
-    address: string;
-    externalUserId?: string;
-    externalChatId?: string;
-    status?: string;
-    policy?: string;
   };
-
-  if (!body.type || !body.address) {
-    return httpError("BAD_REQUEST", "type and address are required", 400);
-  }
-
-  if (!body.externalUserId) {
-    return httpError(
-      "BAD_REQUEST",
-      "externalUserId is required for trust resolution",
-      400,
-    );
-  }
-
-  if (body.status !== undefined && !isChannelStatus(body.status)) {
-    return httpError(
-      "BAD_REQUEST",
-      `Invalid channel status "${body.status}". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
-      400,
-    );
-  }
-
-  if (body.policy !== undefined && !isChannelPolicy(body.policy)) {
-    return httpError(
-      "BAD_REQUEST",
-      `Invalid channel policy "${body.policy}". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
-      400,
-    );
-  }
-
-  const guardian = findGuardianContact();
-  if (!guardian) {
-    return httpError(
-      "NOT_FOUND",
-      "No guardian contact exists. The guardian must be verified on at least one channel first.",
-      404,
-    );
-  }
-
-  // Upsert the guardian with the new channel added.
-  const updated = upsertContact({
-    id: guardian.id,
-    displayName: guardian.displayName,
-    role: "guardian",
-    channels: [
-      {
-        ...body,
-        status: (body.status as ChannelStatus) ?? "active",
-        policy: body.policy as ChannelPolicy | undefined,
-        verifiedAt: Date.now(),
-        verifiedVia: "guardian_channel_endpoint",
-      },
-    ],
-  });
-
-  return Response.json(
-    { ok: true, contact: withGuardianNameOverride(updated) },
-    { status: 200 },
-  );
 }
 
-// ---------------------------------------------------------------------------
-// Route definitions
-// ---------------------------------------------------------------------------
-
-export function contactRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "contacts",
-      method: "GET",
-      summary: "List contacts",
-      description:
-        "Return all contacts, optionally filtered by type or channel status.",
-      tags: ["contacts"],
-      responseBody: z.object({
-        ok: z.boolean(),
-        contacts: z
-          .array(z.unknown())
-          .describe("Contact objects with channels and metadata"),
-      }),
-      handler: ({ url }) => handleListContacts(url),
-    },
-    {
-      endpoint: "contacts",
-      method: "POST",
-      summary: "Create or update a contact",
-      description:
-        "Create a new contact or update an existing one. Supports upsert by contactId or channel handle.",
-      tags: ["contacts"],
-      requestBody: z.object({
-        contactId: z.string().describe("Existing contact ID (for update)"),
-        displayName: z.string().describe("Display name"),
-        channels: z
-          .array(z.unknown())
-          .describe("Channel objects with channelId, handle, displayName"),
-        assistantMetadata: z
-          .object({})
-          .passthrough()
-          .describe("Assistant-side metadata"),
-      }),
-      responseBody: z.object({
-        ok: z.boolean(),
-        contact: z
-          .object({})
-          .passthrough()
-          .describe("Created or updated contact"),
-      }),
-      handler: async ({ req }) => handleUpsertContact(req),
-    },
-    {
-      endpoint: "contacts/merge",
-      method: "POST",
-      summary: "Merge two contacts",
-      description: "Merge two contacts, keeping one and absorbing the other.",
-      tags: ["contacts"],
-      requestBody: z.object({
-        keepId: z.string().describe("ID of the contact to keep"),
-        mergeId: z
-          .string()
-          .describe("ID of the contact to merge into the kept one"),
-      }),
-      responseBody: z.object({
-        ok: z.boolean(),
-        contact: z.object({}).passthrough().describe("Merged contact"),
-      }),
-      handler: async ({ req }) => handleMergeContacts(req),
-    },
-    {
-      endpoint: "contacts/guardian/channel",
-      method: "POST",
-      policyKey: "contacts",
-      summary: "Add a channel to the guardian contact",
-      description: "Used by the guardian to auto-verify their own channel.",
-      tags: ["contacts"],
-      requestBody: z.object({
-        type: z.string().describe("Channel type, e.g. 'email'"),
-        address: z
-          .string()
-          .describe("Channel address, e.g. 'user@example.com'"),
-        externalUserId: z
-          .string()
-          .describe("External user ID for trust resolution"),
-        status: z
-          .string()
-          .optional()
-          .describe("Channel status (default: active)"),
-      }),
-      responseBody: z.object({
-        ok: z.boolean(),
-        contact: z
-          .object({})
-          .passthrough()
-          .describe("Updated guardian contact"),
-      }),
-      handler: async ({ req, authContext }) =>
-        handleAddGuardianChannel(req, authContext),
-    },
-    {
-      endpoint: "contact-channels/:contactChannelId",
-      method: "PATCH",
-      policyKey: "contact-channels",
-      summary: "Update a contact channel",
-      description: "Update status, policy, or reason on a contact's channel.",
-      tags: ["contacts"],
-      requestBody: z.object({
-        status: z.string().describe("Channel status"),
-        policy: z.string().describe("Channel policy"),
-        reason: z.string().describe("Reason for the change"),
-      }),
-      responseBody: z.object({
-        ok: z.boolean(),
-        contact: z
-          .object({})
-          .passthrough()
-          .describe("Updated contact (if applicable)"),
-      }),
-      handler: async ({ req, params }) =>
-        handleUpdateContactChannel(req, params.contactChannelId),
-    },
-  ];
-}
 
-/**
- * Catch-all `contacts/:id` route. Must be registered AFTER any routes that
- * share the `contacts/` prefix (e.g. `inviteRouteDefinitions()`) to avoid
- * the `:id` parameter matching literal sub-paths like "invites".
- */
-export function contactCatchAllRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "contacts/:id",
-      method: "GET",
-      policyKey: "contacts",
-      summary: "Get a contact",
-      description:
-        "Return a single contact with its channels and assistant metadata.",
-      tags: ["contacts"],
-      responseBody: z.object({
-        ok: z.boolean(),
-        contact: z.object({}).passthrough().describe("Contact details"),
-        assistantMetadata: z
-          .object({})
-          .passthrough()
-          .describe("Assistant-side metadata"),
-      }),
-      handler: ({ params }) => handleGetContact(params.id),
-    },
-    {
-      endpoint: "contacts/:id",
-      method: "DELETE",
-      policyKey: "contacts",
-      summary: "Delete a contact",
-      description: "Delete a contact by ID.",
-      tags: ["contacts"],
-      handler: ({ params }) => handleDeleteContact(params.id),
-    },
-  ];
-}