Describe the integration, notification and MCP surfaces in the contract

Sixteen routes the native client already calls were absent from the OpenAPI
registry, so the published spec said nothing about them. `openapi:check`
compares the registry against the YAML and never the routes against the
registry, which is why the gap survived.

Nightscout status / test / disconnect, the WHOOP credential and status reads,
and the Withings status / disconnect pair land in the integrations module. The
three per-channel configs under `/api/settings/*` join the settings module; the
notification preference and delivery-health surfaces get their own module, as do
the MCP connector connections and tokens.

These are credential-bearing surfaces, so the contract states what each response
actually carries. Every channel GET reduces its secret to a boolean, and the
descriptions say so, along with the consequence: a client cannot read the value
back, so an empty value on the way in preserves the stored one rather than
clearing it. `POST /api/mcp/tokens` is the one operation that returns a usable
Bearer, and its description says outright that this is the only copy.

Two inline request schemas move to the validations modules they belong in, so
the registry documents the same object the handler parses rather than a
restatement of it.
This commit is contained in:
Marc-André Bombeck committed 2026-08-22 12:21:16 +02:00
1 parent a6c239d952
commit c8035fdd78
9 files changed
+1330 -21

No files matched your search

+6 -12
View File
@@ -18,7 +18,6 @@
* every REST write) — it only admits the confirmed in-process write tools.
*/
import { NextRequest } from "next/server";
import { z } from "zod/v4";
import { apiHandler, requireAuth } from "@/lib/api-handler";
import {
@@ -33,16 +32,11 @@ import { issueApiToken } from "@/lib/auth/issue-token";
import { isApiGloballyEnabled } from "@/lib/app-settings";
import { prisma } from "@/lib/db";
import { SCOPE_HEALTH_READ, SCOPE_HEALTH_WRITE } from "@/lib/mcp/oauth/config";
const createSchema = z.object({
name: z.string().min(1, "Name required").max(100),
expiresInDays: z.number().int().min(1).max(365).optional(),
// The ONLY two scope shapes this endpoint will mint. `read` (default) is the
// least-privilege read token; `read_write` adds `health:write` so the
// confirmed `/mcp` write tools become available. Anything else is rejected
// by the enum — the endpoint can never mint a wildcard or arbitrary grant.
scope: z.enum(["read", "read_write"]).optional().default("read"),
});
// The ONLY two scope shapes this endpoint will mint. `read` (default) is the
// least-privilege read token; `read_write` adds `health:write` so the confirmed
// `/mcp` write tools become available. Anything else is rejected by the enum —
// the endpoint can never mint a wildcard or arbitrary grant.
import { createMcpTokenSchema } from "@/lib/validations/mcp";
export const GET = apiHandler(async () => {
const { user } = await requireAuth();
@@ -89,7 +83,7 @@ export const POST = apiHandler(async (request: NextRequest) => {
});
if (jsonError) return jsonError;
const parsed = createSchema.safeParse(body);
const parsed = createMcpTokenSchema.safeParse(body);
if (!parsed.success) {
return returnAllZodIssues(parsed.error, 422);
}
+2 -6
View File
@@ -1,5 +1,4 @@
import { NextRequest } from "next/server";
import { z } from "zod/v4";
import { prisma } from "@/lib/db";
import { apiHandler, requireAuth } from "@/lib/api-handler";
import { annotate } from "@/lib/logging/context";
@@ -7,6 +6,7 @@ import { apiSuccess, apiError } from "@/lib/api-response";
import { CHANNEL_TYPE_LABELS, EVENT_TYPES } from "@/lib/notifications/types";
import type { ChannelType, EventType } from "@/lib/notifications/types";
import { reEnableChannel } from "@/lib/notifications/channel-state";
import { reEnableChannelSchema } from "@/lib/validations/notifications";
export const dynamic = "force-dynamic";
@@ -131,10 +131,6 @@ export const GET = apiHandler(async () => {
return apiSuccess({ channels: data, events });
});
const reEnableSchema = z.object({
channelId: z.string().min(1).max(64),
});
/**
* POST /api/notifications/status
*
@@ -159,7 +155,7 @@ export const POST = apiHandler(async (request: NextRequest) => {
return apiError("Invalid JSON data", 422);
}
const parsed = reEnableSchema.safeParse(body);
const parsed = reEnableChannelSchema.safeParse(body);
if (!parsed.success) return apiError("Invalid data", 422);
const channel = await prisma.notificationChannel.findFirst({