@company-semantics/contracts 42.1.0 → 44.0.0

package/src/user-notifications/schemas.ts

@@ -0,0 +1,133 @@
+/**
+ * The published shapes of the durable notification inbox and the merged feed
+ * that renders it (`GET /api/me/feed`).
+ *
+ * Zod-canonical: schema is the source of truth, the type is inferred.
+ */
+import { z } from "zod";
+import { ActionItemSchema, ActionItemTargetSchema } from "../action-items";
+import { USER_NOTIFICATION_KINDS } from "./kinds";
+
+/** Zod mirror of the vocabulary. `./kinds` owns the list; this never restates it. */
+export const UserNotificationKindSchema = z.enum(USER_NOTIFICATION_KINDS);
+
+/**
+ * One informational row, AS RENDERED — never as stored.
+ *
+ * The stored row holds identifiers only (`kind` + a `ref` of ids). Everything
+ * below that reads like prose — `title`, `detail`, `contextLabel`, `href` — is
+ * produced at READ TIME by the producing domain's renderer, under the reader's
+ * CURRENT authority. Three problems dissolve at once:
+ *
+ * - **Copy evolution.** There is no frozen prose in the database to decode, so
+ *   changing wording is a renderer change, not a migration.
+ * - **Authorization drift.** A user who lost access to a document after being
+ *   notified about it must not keep reading its title out of an old row. The
+ *   renderer re-checks and returns a tombstone instead.
+ * - **Deletion.** A notification about a deleted doc renders as a tombstone
+ *   rather than dangling.
+ *
+ * The invariant that makes this safe is on the storage side and is worth
+ * stating here too, because this is where someone would be tempted to break it:
+ * **a stored notification row never contains protected content**, so a stale row
+ * cannot leak one.
+ *
+ * Deliberately shaped PARALLEL to `ActionItemSchema` — same field names, same
+ * meanings — so the merged feed is a union over two near-identical rows and the
+ * existing roll-up helpers keep working unchanged.
+ */
+export const UserNotificationSchema = z.object({
+  /** The stored row's id. Unlike an action item's, this IS a row id. */
+  id: z.string(),
+  kind: UserNotificationKindSchema,
+  target: ActionItemTargetSchema,
+  /** ltree anchor for subtree roll-up; `null` = org-wide. */
+  unitPath: z.string().nullable(),
+  /** One line naming what happened, e.g. "Dev Patel approved your request". */
+  title: z.string(),
+  /** Optional second line — the decider's note, a reason. */
+  detail: z.string().nullable(),
+  /** The thing it is about, as the user names it, e.g. "Sales.md". */
+  contextLabel: z.string(),
+  /**
+   * Where to go to SEE it — a RELATIVE app path.
+   *
+   * `null` when the reader can no longer reach the referent (access revoked,
+   * doc deleted, or a `ref` this client's version cannot decode). A tombstoned
+   * row still renders, because "you were granted access to something you can no
+   * longer see" is itself true and useful; it simply does not link anywhere.
+   */
+  href: z.string().nullable(),
+  createdAt: z.string(),
+  /** `null` while unread. The only mutable field on the row. */
+  readAt: z.string().nullable(),
+});
+export type UserNotification = z.infer<typeof UserNotificationSchema>;
+
+// =============================================================================
+// The merged feed
+// =============================================================================
+
+/**
+ * One row of `/me/work`'s top section, discriminated by what it DEMANDS.
+ *
+ * `actionable` rows are derived standing state you can resolve; `informational`
+ * rows are stored facts you can only read. They are merged for PRESENTATION —
+ * one list under one heading — and nowhere else: the two producing vocabularies
+ * stay separate (ADR-CONT-104), and the `action-items` domain still owns no
+ * tables.
+ *
+ * Discriminating on `row` rather than sniffing for `readAt` keeps the client
+ * from having to know which fields imply which lifecycle.
+ */
+export const FeedItemSchema = z.discriminatedUnion("row", [
+  z.object({ row: z.literal("actionable"), item: ActionItemSchema }),
+  z.object({
+    row: z.literal("informational"),
+    notification: UserNotificationSchema,
+  }),
+]);
+export type FeedItem = z.infer<typeof FeedItemSchema>;
+
+/**
+ * `GET /api/me/feed`.
+ *
+ * ORDERING IS INTENTIONALLY GROUPED, NOT CHRONOLOGICALLY INTERLEAVED: every
+ * `actionable` row first, then `informational` rows newest-first. "Merged feed"
+ * names one visual surface, not one timeline. Grouping is what keeps "what do I
+ * owe?" answerable at a glance instead of scattered between announcements — and
+ * it is what makes the pagination rule below coherent.
+ *
+ * ONLY NOTIFICATIONS PAGINATE. Action items are already bounded by
+ * `ACTION_ITEM_LIMIT` and are standing state rather than a timeline, so page 1
+ * carries all of them plus the first page of notifications, and every
+ * subsequent page is notifications only. Paginating two independent sources
+ * against one cursor is where merged feeds go wrong.
+ */
+export const FeedListResponseSchema = z.object({
+  items: z.array(FeedItemSchema),
+  /**
+   * Opaque cursor for the NEXT page of informational rows; `null` at the end.
+   *
+   * Encodes `(createdAt, id)` — `id` breaks ties so two rows written in the same
+   * transaction cannot straddle a page boundary and be served twice or skipped.
+   */
+  nextCursor: z.string().nullable(),
+  /**
+   * Total unread across ALL retained notifications — NOT within the returned
+   * window.
+   *
+   * A windowed count would silently under-report the moment the inbox grew past
+   * one page, and this number drives a badge whose entire job is to be trusted.
+   */
+  unreadCount: z.number().int().nonnegative(),
+  /** True when the ACTIONABLE half hit its cap; notifications say so via `nextCursor`. */
+  truncated: z.boolean(),
+});
+export type FeedListResponse = z.infer<typeof FeedListResponseSchema>;
+
+/** `POST /api/me/feed/read` — mark specific informational rows read. */
+export const FeedMarkReadRequestSchema = z.object({
+  notificationIds: z.array(z.string()).min(1).max(200),
+});
+export type FeedMarkReadRequest = z.infer<typeof FeedMarkReadRequestSchema>;