@company-semantics/contracts 82.0.0 → 83.1.0

package/src/user-notifications/lifecycle-registry.ts

@@ -0,0 +1,123 @@
+/**
+ * NOTIFICATION_LIFECYCLE — every inbox kind's declared lifecycle
+ * (notification-lifecycle-is-declared-per-kind). See ./lifecycle for what each
+ * axis means.
+ */
+import type { UserNotificationKind } from "./kinds";
+import type { NotificationLifecycle } from "./lifecycle";
+
+const INDEPENDENT = {
+  condition: "none",
+  resolution: "never",
+  retention: "standard",
+} as const;
+const PER_KIND = { scope: "kind" } as const;
+const RESOLVED_FOR_ALL = {
+  mode: "source",
+  audience: "all-recipients",
+} as const;
+/** One active row per kind; each repeat is news again. */
+const RENEWING = {
+  condition: PER_KIND,
+  supersedes: true,
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+} as const;
+/** A standing condition: repeats update it quietly; the domain resolves it. */
+const STANDING = {
+  condition: PER_KIND,
+  supersedes: true,
+  attentionOnSupersede: "preserve",
+  resolution: RESOLVED_FOR_ALL,
+  retention: "standard",
+} as const;
+
+/**
+ * Every kind's lifecycle. Annotated (not `satisfies`) so a missing kind and an
+ * excess key are both compile errors. Values mirror
+ * company-semantics-control docs/notification-inbox.md § Per-kind lifecycle.
+ * (prettier-ignore keeps the annotation on one line, where it is greppable.)
+ */
+// prettier-ignore
+export const NOTIFICATION_LIFECYCLE: Readonly<Record<UserNotificationKind, NotificationLifecycle>> = {
+  "companyMd.access_requested": {
+    condition: { scope: "fields", fields: ["requestId"] },
+    supersedes: false,
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "companyMd.access_request_approved": INDEPENDENT,
+  "companyMd.access_request_denied": INDEPENDENT,
+  "comment.mention": {
+    condition: { scope: "fields", fields: ["subjectId", "subjectType"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "comment.reply": {
+    condition: { scope: "fields", fields: ["subjectId", "subjectType"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "chat.mention": {
+    condition: { scope: "fields", fields: ["chatId"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.org_became_shared": INDEPENDENT,
+  "proactive.brief_morning": RENEWING,
+  "proactive.billing_balance_below_half": STANDING,
+  "proactive.billing_balance_below_threshold": STANDING,
+  "proactive.billing_balance_exhausted": STANDING,
+  "proactive.billing_auto_recharge_failed": STANDING,
+  "proactive.billing_payment_past_due": STANDING,
+  "proactive.billing_suspended": STANDING,
+  "proactive.billing_byo_key_invalid": {
+    condition: { scope: "fields", fields: ["configId"] },
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "proactive.billing_user_monthly_limit_reached": {
+    condition: { scope: "fields", fields: ["userId"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.billing_auto_recharge_succeeded": RENEWING,
+  "proactive.billing_top_up_credited": RENEWING,
+  "proactive.billing_monthly_budget_80": RENEWING,
+  "proactive.billing_monthly_budget_100": RENEWING,
+  "proactive.billing_provider_price_changed": RENEWING,
+  "proactive.billing_payment_recovered": RENEWING,
+  "proactive.billing_subscription_canceled": RENEWING,
+  "proactive.source_sync_docs_updated": {
+    condition: PER_KIND,
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.source_sync_review_ready": {
+    condition: { scope: "fields", fields: ["checkpoint"] },
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "proactive.org_structure_review_ready": {
+    condition: PER_KIND,
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+};

package/src/user-notifications/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * The lifecycle of an inbox row, declared per kind.
+ *
+ * A notification row is the CURRENT ATTENTION ITEM for one condition, not an
+ * event record (control ADR `notification-inbox-is-an-attention-surface`).
+ *
+ *   condition   — what the row is about; addresses RESOLUTION. `none` = an
+ *                 independent delivery with no identity.
+ *   supersedes  — a property of the condition: a repeat occurrence updates the
+ *                 active row instead of appending one.
+ *   attentionOnSupersede — `renew` restores the kind's normal initial attention
+ *                 state (unread, or read when its class is born read);
+ *                 `preserve` keeps the row's current read state.
+ *   resolution  — `never`, or resolved by its producing DOMAIN (`source`) for
+ *                 `all-recipients` or only the `recipient`.
+ *   retention   — `standard`, or `persistent` (longer bounds; declared, never
+ *                 accidental).
+ *
+ * There is no Archive. See company-semantics-control docs/notification-inbox.md.
+ */
+
+export const NOTIFICATION_ATTENTION_ON_SUPERSEDE = [
+  "renew",
+  "preserve",
+] as const;
+export type NotificationAttentionOnSupersede =
+  (typeof NOTIFICATION_ATTENTION_ON_SUPERSEDE)[number];
+
+export const NOTIFICATION_RESOLUTION_AUDIENCES = [
+  "all-recipients",
+  "recipient",
+] as const;
+export type NotificationResolutionAudience =
+  (typeof NOTIFICATION_RESOLUTION_AUDIENCES)[number];
+
+export const NOTIFICATION_RETENTION_CLASSES = [
+  "standard",
+  "persistent",
+] as const;
+export type NotificationRetention =
+  (typeof NOTIFICATION_RETENTION_CLASSES)[number];
+
+export type NotificationCondition =
+  | { readonly scope: "kind" }
+  | {
+      readonly scope: "fields";
+      readonly fields: readonly [string, ...string[]];
+    };
+
+export type NotificationResolution =
+  | "never"
+  | {
+      readonly mode: "source";
+      readonly audience: NotificationResolutionAudience;
+    };
+
+type Supersession =
+  | { readonly supersedes: false }
+  | {
+      readonly supersedes: true;
+      readonly attentionOnSupersede: NotificationAttentionOnSupersede;
+    };
+
+export type NotificationLifecycle =
+  | {
+      /** An independent delivery: no identity, cannot resolve, cannot supersede. */
+      readonly condition: "none";
+      readonly resolution: "never";
+      readonly retention: NotificationRetention;
+    }
+  | ({
+      readonly condition: NotificationCondition;
+      readonly resolution: NotificationResolution;
+      readonly retention: NotificationRetention;
+    } & Supersession);

package/src/user-notifications/schemas.ts

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { ActionItemSchema, ActionItemTargetSchema } from "../action-items";
+import { FeedSelectorSchema } from "./feed-lifecycle";
 import { USER_NOTIFICATION_KINDS } from "./kinds";
 
 /** Zod mirror of the vocabulary. `./kinds` owns the list; this never restates it. */
@@ -68,9 +69,22 @@ export const UserNotificationSchema = z.object({
    * longer see" is itself true and useful; it simply does not link anywhere.
    */
   href: z.string().nullable(),
+  /** When the row was first written — its FIRST occurrence. */
   createdAt: z.string(),
-  /** `null` while unread. The only mutable field on the row. */
+  /** `null` while unread. Changed by the read/unread verbs and by supersession. */
   readAt: z.string().nullable(),
+  /**
+   * The time of the LATEST occurrence this row represents — the ordering and
+   * retention clock. Equals `createdAt` until a repeat supersedes into the row.
+   */
+  activityAt: z.string(),
+  /** How many occurrences this row has absorbed by supersession. 1 for a fresh row. */
+  occurrenceCount: z.number().int().positive(),
+  /**
+   * Set when the producing domain resolved the row's condition; `null` while
+   * it stands. A resolved row still renders (muted) until retention removes it.
+   */
+  resolvedAt: z.string().nullable(),
 });
 export type UserNotification = z.infer<typeof UserNotificationSchema>;
 
@@ -103,7 +117,8 @@ 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"
+ * `actionable` row first, then `informational` rows — unread-and-unresolved
+ * first, then `activityAt` DESC, `id` DESC. "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.
@@ -119,10 +134,16 @@ export const FeedListResponseSchema = z.object({
   /**
    * 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.
+   * Encodes `(unread, activityAt, id)`, mirroring the ordering above — `id`
+   * breaks ties so two rows with the same activity cannot straddle a page
+   * boundary and be served twice or skipped. Never parse it.
    */
   nextCursor: z.string().nullable(),
+  /**
+   * The number of notification rows matching the requested view — never action
+   * items, never a window. What "Select all in this view" would touch.
+   */
+  viewCount: z.number().int().nonnegative(),
   /**
    * Total unread across ALL retained notifications — NOT within the returned
    * window.
@@ -136,8 +157,8 @@ export const FeedListResponseSchema = z.object({
 });
 export type FeedListResponse = z.infer<typeof FeedListResponseSchema>;
 
-/** `POST /api/me/feed/read` — mark specific informational rows read. */
+/** `POST /api/me/feed/read` — mark the selected informational rows read. */
 export const FeedMarkReadRequestSchema = z.object({
-  notificationIds: z.array(z.string()).min(1).max(200),
+  selector: FeedSelectorSchema,
 });
 export type FeedMarkReadRequest = z.infer<typeof FeedMarkReadRequestSchema>;