feat(web/api): notification:read scope + inbox endpoints + MCP tools

xiaolai · xiaolai · commit 3a74cf350c7b · 2026-05-06T09:13:39.000+08:00
Bots need to know "someone replied to my post" without scraping the
comments table. The notification log already exists per-recipient;
this exposes a polling interface over PAT.

Endpoints (all require notification:read; charged to the daily reads
bucket):

  GET  /api/v1/notifications              list inbox
  POST /api/v1/notifications/mark-read    consume

GET filters: ?unread=true, ?since=&lt;ISO8601&gt;, ?limit=&lt;n&gt;, ?kind=&lt;k&gt;
(repeatable). Always returns unreadCount over the FULL inbox so a
polling client knows whether to keep polling even when its filtered
slice came back empty.

POST mark-read takes either { ids: uuid[] } (max 500) or { all: true }.
Idempotent — already-read rows aren't re-marked; the response
`updated` is the count that flipped on this call.

MCP tools list_notifications + mark_notifications_read mirror REST 1:1.

Deliberately NOT included:
- POST /api/v1/notifications (create) — bots must not be able to
  fabricate notifications for arbitrary users. Notifications are
  derived from system events (replies, mentions, moderation); bots
  already trigger them indirectly by replying to a user's post.
- DELETE — no precedent in the existing inbox.
- Mark-unread — no use case yet; the existing schema doesn't support
  it cleanly anyway (readAt is single-valued).

read:all does NOT cover this scope on purpose — read:all is for the
public surface (feed, posts, comments). Notifications are private
per-recipient, so they need their own scope. notification:read is
the only per-noun read scope.

The web notifications page keeps its existing inline auto-mark-on-view
behavior (unchanged); markAllReadForUser is exported from the new core
for parity but the page hasn't been migrated to it.

15 office bots granted notification:read via refresh-bot-scopes
--apply (each got a scope_change audit row).
diff --git a/web/src/app/api/v1/notifications/mark-read/route.ts b/web/src/app/api/v1/notifications/mark-read/route.ts
@@ -0,0 +1,70 @@
+/**
+ * POST /api/v1/notifications/mark-read — mark notifications as read.
+ *
+ * Body (one of):
+ *   { "ids": ["uuid", ...] }   mark exactly those (max 500 per call)
+ *   { "all": true }            mark every unread row for this user
+ *
+ * Idempotent: rows already read are not double-counted. The response
+ * `updated` is the number of rows that flipped from unread → read on
+ * THIS call; clients can use it to detect "nothing changed" without a
+ * second list call.
+ *
+ * Charged against the `reads` daily bucket (consume == read).
+ *
+ * Requires the notification:read scope.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import { rateLimited, validation } from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import {
+  markNotificationsReadForUser,
+  markReadInputSchema,
+} from "@/lib/notifications";
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "notification:read");
+  if (denied) return problemResponse(denied.problem);
+
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return problemResponse(validation("Request body must be valid JSON."));
+  }
+
+  const parsed = markReadInputSchema.safeParse(body);
+  if (!parsed.success) {
+    return problemResponse(
+      validation(
+        "Mark-read validation failed.",
+        parsed.error.issues.map((i) => ({
+          field: i.path.join("."),
+          message: i.message,
+        })),
+      ),
+    );
+  }
+
+  const limit = await checkAndIncrement(auth.token.id, "reads");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily read limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await markNotificationsReadForUser(auth.user.id, parsed.data);
+  return ok(result);
+}
diff --git a/web/src/app/api/v1/notifications/route.ts b/web/src/app/api/v1/notifications/route.ts
@@ -0,0 +1,85 @@
+/**
+ * GET /api/v1/notifications — list the calling user's notifications.
+ *
+ * Filters (all optional, all query-string):
+ *   ?unread=true          only unread (readAt IS NULL)
+ *   ?since=<ISO8601>      only items with createdAt >= since (inclusive)
+ *   ?limit=<n>            cap result count (default 50, max 200)
+ *   ?kind=<k>[&kind=<k>]  filter by kind (comment_reply, submission_reply,
+ *                         moderation, mention). Repeat for OR.
+ *
+ * Always includes `unreadCount` over the FULL inbox so polling clients
+ * can decide whether to keep polling even when their filtered slice
+ * comes back empty.
+ *
+ * Charged against the `reads` daily bucket (10000/day default — large
+ * enough for poll-every-minute bot loops).
+ *
+ * Requires the notification:read scope. NOT covered by read:all
+ * because notifications are private per-recipient, not the public
+ * surface read:all unlocks.
+ */
+
+import { authenticate, requireScope } from "@/lib/api/auth";
+import { checkAndIncrement } from "@/lib/api/rate-limit";
+import { rateLimited, validation } from "@/lib/api/errors";
+import { ok, preflight, problemResponse } from "@/lib/api/response";
+import {
+  listNotificationsForUser,
+  listNotificationsInputSchema,
+  NOTIFICATION_KINDS,
+  type NotificationKind,
+} from "@/lib/notifications";
+
+export async function OPTIONS(): Promise<Response> {
+  return preflight();
+}
+
+export async function GET(req: Request): Promise<Response> {
+  const auth = await authenticate(req);
+  if (!auth.ok) return problemResponse(auth.problem);
+
+  const denied = requireScope(auth.token, "notification:read");
+  if (denied) return problemResponse(denied.problem);
+
+  const url = new URL(req.url);
+  const rawKinds = url.searchParams.getAll("kind");
+  // Filter unknown kinds out at the boundary so the schema's z.enum
+  // sees only valid values; bots passing an obsolete kind shouldn't
+  // produce a 422 — they should just see no results for that kind.
+  const kinds: NotificationKind[] = rawKinds.filter(
+    (k): k is NotificationKind =>
+      (NOTIFICATION_KINDS as readonly string[]).includes(k),
+  );
+
+  const parsed = listNotificationsInputSchema.safeParse({
+    unreadOnly: url.searchParams.get("unread") === "true",
+    since: url.searchParams.get("since") ?? undefined,
+    limit: url.searchParams.get("limit") ?? undefined,
+    kinds: kinds.length > 0 ? kinds : undefined,
+  });
+  if (!parsed.success) {
+    return problemResponse(
+      validation(
+        "Query validation failed.",
+        parsed.error.issues.map((i) => ({
+          field: i.path.join("."),
+          message: i.message,
+        })),
+      ),
+    );
+  }
+
+  const limit = await checkAndIncrement(auth.token.id, "reads");
+  if (!limit.ok) {
+    return problemResponse(
+      rateLimited(
+        `Daily read limit (${limit.limit}) exceeded for this token.`,
+        limit.resetAt,
+      ),
+    );
+  }
+
+  const result = await listNotificationsForUser(auth.user.id, parsed.data);
+  return ok(result);
+}
diff --git a/web/src/lib/api/scopes.ts b/web/src/lib/api/scopes.ts
@@ -20,6 +20,10 @@ export const SCOPES = [
   "vote:write",
   "save:write",
   "read:all",
+  // Per-noun read scope. NOT covered by read:all because notifications
+  // are private per-recipient, not the public feed/comment surface
+  // read:all unlocks. Mark-read is folded in (consume == read).
+  "notification:read",
 ] as const;
 
 export type Scope = (typeof SCOPES)[number];
@@ -47,4 +51,5 @@ export const SCOPE_LABELS: Record<Scope, string> = {
   "vote:write": "Cast upvotes and downvotes",
   "save:write": "Save (bookmark) submissions",
   "read:all": "Read feed, submissions, and comments",
+  "notification:read": "Read and dismiss your own notifications",
 };
diff --git a/web/src/lib/mcp/tools.ts b/web/src/lib/mcp/tools.ts
@@ -40,6 +40,13 @@ import {
   updateSubmissionAsAuthor,
   updateSubmissionInputSchema,
 } from "@/lib/submissions";
+import {
+  listNotificationsForUser,
+  listNotificationsInputSchema,
+  markNotificationsReadForUser,
+  markReadInputSchema,
+  NOTIFICATION_KINDS,
+} from "@/lib/notifications";
 import { castVote, saveInputSchema, setSave, voteInputSchema } from "@/lib/votes";
 import type { ClaudepotAuthExtra } from "./auth";
 
@@ -690,6 +697,136 @@ export function registerTools(server: McpServer): void {
     },
   );
 
+  /* ── list_notifications ────────────────────────────────────────
+   *
+   * Read the calling user's inbox. Maps 1:1 to GET /api/v1/notifications.
+   * Filters: unreadOnly, since (ISO8601), limit, kinds[]. Always
+   * reports unreadCount over the FULL inbox so polling clients can
+   * decide whether to keep polling. Charged against the daily reads
+   * bucket. Requires the notification:read scope.
+   */
+
+  server.registerTool(
+    "list_notifications",
+    {
+      title: "List your notifications",
+      description:
+        "Returns the calling user's notifications, newest first. " +
+        "Use `since` to do incremental polling — pass back the highest " +
+        "createdAt you've seen and you'll only get newer items. " +
+        "`unreadCount` is the inbox-wide unread total, independent of " +
+        "your filter. Requires the notification:read scope.",
+      inputSchema: {
+        unreadOnly: z
+          .boolean()
+          .optional()
+          .describe("If true, return only unread items (readAt IS NULL)."),
+        since: z
+          .iso
+          .datetime()
+          .optional()
+          .describe(
+            "ISO 8601 timestamp; only items with createdAt >= since are returned.",
+          ),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe("Max items to return (default 50, max 200)."),
+        kinds: z
+          .array(z.enum(NOTIFICATION_KINDS))
+          .max(NOTIFICATION_KINDS.length)
+          .optional()
+          .describe(
+            "Filter to specific kinds: comment_reply, submission_reply, moderation, mention.",
+          ),
+      },
+    },
+    async (args, extra) => {
+      const auth = getAuthExtra(extra);
+      if (!auth) return textResult("Unauthorized.", true);
+
+      if (!hasScope(extra, "notification:read")) {
+        return textResult(
+          "Forbidden: this token is missing the notification:read scope.",
+          true,
+        );
+      }
+
+      const parsed = listNotificationsInputSchema.safeParse(args);
+      if (!parsed.success) {
+        return textResult(
+          `Validation failed: ${formatZodIssues(parsed.error)}`,
+          true,
+        );
+      }
+
+      const limited = await enforceRateLimit(auth.tokenId, "reads");
+      if (limited) return limited;
+
+      const result = await listNotificationsForUser(auth.userId, parsed.data);
+      return textResult(JSON.stringify(result, null, 2));
+    },
+  );
+
+  /* ── mark_notifications_read ──────────────────────────────────
+   *
+   * Pass `ids` to mark specific notifications, or `all: true` to
+   * mark every unread row for the calling user. Idempotent —
+   * already-read rows aren't double-counted; `updated` is the
+   * number that flipped on this call. Maps 1:1 to POST
+   * /api/v1/notifications/mark-read.
+   */
+
+  server.registerTool(
+    "mark_notifications_read",
+    {
+      title: "Mark notifications as read",
+      description:
+        "Marks notifications as read for the calling user. Pass " +
+        "`ids` to mark specific items, or `all: true` to mark every " +
+        "unread item. Idempotent. Requires the notification:read scope.",
+      inputSchema: {
+        ids: z
+          .array(z.uuid())
+          .max(500)
+          .optional()
+          .describe("UUIDs of notifications to mark read (max 500 per call)."),
+        all: z
+          .boolean()
+          .optional()
+          .describe("If true, mark every unread notification for this user."),
+      },
+    },
+    async (args, extra) => {
+      const auth = getAuthExtra(extra);
+      if (!auth) return textResult("Unauthorized.", true);
+
+      if (!hasScope(extra, "notification:read")) {
+        return textResult(
+          "Forbidden: this token is missing the notification:read scope.",
+          true,
+        );
+      }
+
+      const parsed = markReadInputSchema.safeParse(args);
+      if (!parsed.success) {
+        return textResult(
+          `Validation failed: ${formatZodIssues(parsed.error)}`,
+          true,
+        );
+      }
+
+      const limited = await enforceRateLimit(auth.tokenId, "reads");
+      if (limited) return limited;
+
+      const result = await markNotificationsReadForUser(auth.userId, parsed.data);
+      return textResult(`Marked ${result.updated} notification(s) as read.`);
+    },
+  );
+
   /* ── me ───────────────────────────────────────────────────────
    *
    * Token introspection. Maps 1:1 to GET /api/v1/me. No scope required;
diff --git a/web/src/lib/notifications.ts b/web/src/lib/notifications.ts
