Register onboarding chat operations in the OpenAPI contract

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Scott TongandPaperclip committed 2026-11-17 13:56:04 -08:00
1 parent 29f31707a5
commit 2dbad34445
3 files changed
+59 -20

No files matched your search

@@ -84,6 +84,7 @@ const apiPrefixes: Record<string, string> = {
"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,
+20 -20
View File
@@ -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<ReturnType<typeof heartbeatService>, "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;
}
+22
View File
@@ -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",