From 2dbad344452fcd79332b38cf713417b0660e909f Mon Sep 17 00:00:00 2001 From: Scott Tong Date: Tue, 17 Nov 2026 13:54:06 -0800 Subject: [PATCH] Register onboarding chat operations in the OpenAPI contract Co-Authored-By: Paperclip --- server/src/__tests__/openapi-routes.test.ts | 17 +++++++++ server/src/routes/onboarding-chat.ts | 40 ++++++++++----------- server/src/routes/openapi.ts | 22 ++++++++++++ 3 files changed, 59 insertions(+), 20 deletions(-) diff --git a/server/src/__tests__/openapi-routes.test.ts b/server/src/__tests__/openapi-routes.test.ts index 69c2a5e4bfa..72d5dfabb13 100644 --- a/server/src/__tests__/openapi-routes.test.ts +++ b/server/src/__tests__/openapi-routes.test.ts @@ -84,6 +84,7 @@ const apiPrefixes: Record = { "link-previews.ts": "/api", "managed-agent-profiles.ts": "/api", "onboarding-seed.ts": "/api", + "onboarding-chat.ts": "/api", "openapi.ts": "/api", "plugin-ui-static.ts": "/api", "plugins.ts": "/api", @@ -1308,6 +1309,22 @@ describe("openapi routes", () => { expect(callback.parameters).toContainEqual(expect.objectContaining({ in: "query", name: "state", required: true, schema: expect.objectContaining({ maxLength: 128 }) })); }); + it("documents board-owned onboarding chat and visible welcome operations", () => { + const { spec } = loadSpecRoutes(); + const base = "/api/companies/{companyId}/chats/{agentRef}/onboarding"; + for (const path of [base, `${base}/greeting`]) { + const operation = spec.paths[path]?.post; + expect(operation).toBeDefined(); + expect(operation["x-paperclip-authorization"]).toEqual({ actor: "board" }); + expect(operation.security).toEqual([{ BoardSessionAuth: [] }, { BoardApiKeyAuth: [] }]); + expect(operation.responses["200"]).toBeDefined(); + expect(operation.responses["403"]).toBeDefined(); + expect(operation.responses["404"]).toBeDefined(); + } + expect(spec.paths[`${base}/greeting`].post.responses["200"].content["application/json"].schema) + .toMatchObject({ type: "object", required: ["started"], properties: { started: { type: "boolean" } } }); + }); + it("covers the mounted server routes exactly", () => { const { routes: actualRoutes, diff --git a/server/src/routes/onboarding-chat.ts b/server/src/routes/onboarding-chat.ts index 0a94cdb66fb..fbba4cbaf5b 100644 --- a/server/src/routes/onboarding-chat.ts +++ b/server/src/routes/onboarding-chat.ts @@ -1,4 +1,4 @@ -import { Router } from "express"; +import { Router, type RequestHandler } from "express"; import type { Db } from "@paperclipai/db"; import { forbidden, notFound } from "../errors.js"; import { agentService } from "../services/agents.js"; @@ -10,24 +10,24 @@ import { assertCompanyAccess } from "./authz.js"; export function onboardingChatRoutes(db: Db, heartbeat: Pick, "wakeup">) { const router = Router(); - for (const greeting of [false, true]) { - router.post(`/companies/:companyId/chats/:agentRef/onboarding${greeting ? "/greeting" : ""}`, async (req, res) => { - const companyId = req.params.companyId as string; - assertCompanyAccess(req, companyId); - if (req.actor.type !== "board" || !req.actor.userId) throw forbidden("Board user access required"); - if (!(await instanceSettingsService(db).getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled"); - const resolved = await agentService(db).resolveByReference(companyId, req.params.agentRef as string); - if (!resolved.agent || resolved.ambiguous) throw notFound("Agent not found"); - const agent = resolved.agent; - const userId = req.actor.userId; - if (!greeting) { - res.json(await ensureOnboardingChat(db, { companyId, agentId: agent.id, agentName: agent.name, userId })); - return; - } - const issue = await issueService(db).getConversation(companyId, agent.id, userId); - if (!issue) throw notFound("Conversation not found"); - res.json({ started: await startOnboardingGreeting(db, issue, userId, heartbeat.wakeup) }); - }); - } + const handle = (greeting: boolean): RequestHandler => async (req, res) => { + const companyId = req.params.companyId as string; + assertCompanyAccess(req, companyId); + if (req.actor.type !== "board" || !req.actor.userId) throw forbidden("Board user access required"); + if (!(await instanceSettingsService(db).getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled"); + const resolved = await agentService(db).resolveByReference(companyId, req.params.agentRef as string); + if (!resolved.agent || resolved.ambiguous) throw notFound("Agent not found"); + const agent = resolved.agent; + const userId = req.actor.userId; + if (!greeting) { + res.json(await ensureOnboardingChat(db, { companyId, agentId: agent.id, agentName: agent.name, userId })); + return; + } + const issue = await issueService(db).getConversation(companyId, agent.id, userId); + if (!issue) throw notFound("Conversation not found"); + res.json({ started: await startOnboardingGreeting(db, issue, userId, heartbeat.wakeup) }); + }; + router.post("/companies/:companyId/chats/:agentRef/onboarding", handle(false)); + router.post("/companies/:companyId/chats/:agentRef/onboarding/greeting", handle(true)); return router; } diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index 19e87bd6507..a80a1a74074 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -1467,6 +1467,8 @@ const mcpSkillsBoardOperations = [ ] as const; const BOARD_ONLY_OPERATIONS = new Set([ + "POST /api/companies/{companyId}/chats/{agentRef}/onboarding", + "POST /api/companies/{companyId}/chats/{agentRef}/onboarding/greeting", "PATCH /api/agents/{id}/permission-grants", // Budget changes are board-only (assertBoard in routes/costs.ts). "POST /api/companies/{companyId}/budgets/policies", @@ -4428,6 +4430,26 @@ registry.registerPath({ // ─── Issues ────────────────────────────────────────────────────────────────── +registry.registerPath({ + method: "post", + path: "/api/companies/{companyId}/chats/{agentRef}/onboarding", + tags: ["issues"], + summary: "Open the current board user's onboarding chat", + description: "Requires Agent Chat and company access. Reuses the caller's existing conversation or creates an unnumbered standing chat with onboarding context. Creates no execution task or project and starts no agent turn.", + request: { params: z.object({ companyId: z.string(), agentRef: z.string() }) }, + responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound }, +}); + +registry.registerPath({ + method: "post", + path: "/api/companies/{companyId}/chats/{agentRef}/onboarding/greeting", + tags: ["issues"], + summary: "Start the visible onboarding chat's live welcome", + description: "Call after the chat is visible. Requires an existing conversation owned by the caller. Returns started=true when a welcome is queued or already pending, or false when the conversation no longer needs a welcome. Retries failed or timed-out attempts and preserves normal agent admission gates.", + request: { params: z.object({ companyId: z.string(), agentRef: z.string() }) }, + responses: { 200: r.ok(z.object({ started: z.boolean() })), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound }, +}); + registry.registerPath({ method: "get", path: "/api/companies/{companyId}/chats",