@company-semantics/contracts 33.0.0 → 35.0.0

package/src/notifications/kinds/chat-shared.ts

@@ -0,0 +1,56 @@
+/**
+ * Chat-shared notification (someone shared a chat).
+ *
+ * The only kind that reproduces a real conversation: the chat's title is shown
+ * as the user's turn and the preview as the assistant's reply, elided into the
+ * call to action. `visibility` is carried by the payload but says nothing here —
+ * it is a fact about the share, not about what this notification tells you.
+ */
+
+import type { ChatUnitItem } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+import { NOTICE } from "../text";
+
+export const chatSharedDefinition: NotificationDefinition<"chat.shared"> = {
+  kind: "chat.shared",
+  compose: (payload, context) => {
+    const { chatTitle, shareUrl, previewText, sharedByName } = payload;
+
+    const items: ChatUnitItem[] = [
+      { type: "message", role: "user", text: chatTitle, from: sharedByName },
+      ...(previewText
+        ? [
+            {
+              type: "message" as const,
+              role: "assistant" as const,
+              text: previewText,
+            },
+          ]
+        : []),
+      { type: "continuation" },
+      { type: "callToAction", label: "SEE MORE", href: shareUrl },
+    ];
+
+    return {
+      metadata: {
+        kind: "chat.shared",
+        title: "A chat has been shared with you",
+      },
+      sections: [
+        {
+          elements: [
+            { type: "greeting" },
+            { type: "body", text: "A chat was shared with you." },
+            { type: "chatUnit", items },
+            {
+              type: "notice",
+              lines: [`This share was sent via ${context.brand.name}.`, NOTICE],
+            },
+            { type: "signature" },
+          ],
+        },
+      ],
+    };
+  },
+};

package/src/notifications/kinds/company-md-access-approved.ts

@@ -0,0 +1,57 @@
+/**
+ * Company.md access-approved notification (sent to the requester).
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+import { ACCESS_PHRASE } from "../text";
+
+export const accessApprovedDefinition: NotificationDefinition<"companyMd.access_request_approved"> =
+  {
+    kind: "companyMd.access_request_approved",
+    compose: (payload, context) => {
+      const { approverName, docTitle, accessLevel, docUrl } = payload;
+
+      return {
+        metadata: {
+          kind: "companyMd.access_request_approved",
+          title: "Your access request was approved",
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting" },
+              { type: "body", text: "Your access request was approved." },
+              {
+                type: "chatUnit",
+                items: [
+                  {
+                    type: "message",
+                    role: "assistant",
+                    text: "Open to view.",
+                  },
+                  { type: "callToAction", label: "OPEN", href: docUrl },
+                ],
+              },
+              {
+                type: "keyValueTable",
+                rows: [
+                  { label: "Document", value: `"${docTitle}"` },
+                  { label: "Access", value: ACCESS_PHRASE[accessLevel] },
+                  { label: "Approved by", value: approverName },
+                ],
+              },
+              {
+                type: "notice",
+                lines: [
+                  `This notification was sent via ${context.brand.name}.`,
+                  "Access is now active.",
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds/company-md-access-denied.ts

@@ -0,0 +1,61 @@
+/**
+ * Company.md access-denied notification (sent to the requester).
+ *
+ * The only kind with no call to action, and the only one whose chat unit exists
+ * solely to carry someone's words: with no `reason` there is nothing to quote,
+ * so the whole unit drops rather than degrading into an empty bubble.
+ */
+
+import type { NotificationElement } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+export const accessDeniedDefinition: NotificationDefinition<"companyMd.access_request_denied"> =
+  {
+    kind: "companyMd.access_request_denied",
+    compose: (payload, context) => {
+      const { approverName, docTitle, reason } = payload;
+
+      const elements: NotificationElement[] = [
+        { type: "greeting" },
+        { type: "body", text: "Your access request was declined." },
+        ...(reason
+          ? [
+              {
+                type: "chatUnit" as const,
+                items: [
+                  {
+                    type: "message" as const,
+                    role: "user" as const,
+                    text: reason,
+                    from: approverName,
+                  },
+                ],
+              },
+            ]
+          : []),
+        {
+          type: "keyValueTable",
+          rows: [
+            { label: "Document", value: `"${docTitle}"` },
+            { label: "Declined by", value: approverName },
+          ],
+        },
+        {
+          type: "notice",
+          lines: [
+            `This notification was sent via ${context.brand.name}.`,
+            "This request is now closed.",
+          ],
+        },
+        { type: "signature" },
+      ];
+
+      return {
+        metadata: {
+          kind: "companyMd.access_request_denied",
+          title: "Your access request was reviewed",
+        },
+        sections: [{ elements }],
+      };
+    },
+  };

package/src/notifications/kinds/company-md-access-requested.ts

@@ -0,0 +1,65 @@
+/**
+ * Company.md access-requested notification (sent to the doc owner).
+ *
+ * Closes by telling the recipient WHY they were asked ("You own this document.")
+ * rather than with the standard `NOTICE` — this notification is a request for a
+ * decision, so "no action is required" would be false.
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+export const accessRequestedDefinition: NotificationDefinition<"companyMd.access_requested"> =
+  {
+    kind: "companyMd.access_requested",
+    compose: (payload, context) => {
+      const { requesterName, docTitle, message, reviewUrl } = payload;
+
+      return {
+        metadata: {
+          kind: "companyMd.access_requested",
+          title: "Someone requested access to a document",
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting" },
+              { type: "body", text: "Someone requested document access." },
+              {
+                type: "chatUnit",
+                items: [
+                  message
+                    ? {
+                        type: "message",
+                        role: "user",
+                        text: message,
+                        from: requesterName,
+                      }
+                    : {
+                        type: "message",
+                        role: "assistant",
+                        text: "Review the request.",
+                      },
+                  { type: "callToAction", label: "REVIEW", href: reviewUrl },
+                ],
+              },
+              {
+                type: "keyValueTable",
+                rows: [
+                  { label: "From", value: requesterName },
+                  { label: "Document", value: `"${docTitle}"` },
+                ],
+              },
+              {
+                type: "notice",
+                lines: [
+                  `This notification was sent via ${context.brand.name}.`,
+                  "You own this document.",
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Every notification definition, one module each (ADR-CONTRACTS-085).
+ *
+ * Import this barrel as `./kinds/index`, never `./kinds` — the sibling
+ * `../kinds.ts` holds the `NotificationKind` union and wins that specifier under
+ * `moduleResolution: "bundler"`.
+ */
+
+export { accessApprovedDefinition } from "./company-md-access-approved";
+export { accessDeniedDefinition } from "./company-md-access-denied";
+export { accessRequestedDefinition } from "./company-md-access-requested";
+export { authOtpDefinition } from "./auth-otp";
+export { chatSharedDefinition } from "./chat-shared";
+export { orgInviteDefinition } from "./org-invite";
+export { ownershipTransferCompletedDefinition } from "./ownership-transfer-completed";
+export { ownershipTransferDefinition } from "./ownership-transfer";
+export { securityAlertDefinition } from "./security-alert";
+export { shareGrantedDefinition } from "./share-granted";
+export { unitOwnerGrantedDefinition } from "./unit-owner-granted";

package/src/notifications/kinds/org-invite.ts

@@ -0,0 +1,62 @@
+/**
+ * Org invite notification (join a workspace).
+ *
+ * The title interpolates `orgName` directly. `renderEmail` fills the registry's
+ * `{orgName}` placeholder against an untyped bag and leaves it verbatim when the
+ * field is missing; here the compiler guarantees the field, so the fallback has
+ * nothing left to catch. See ADR-CONTRACTS-085.
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+import { formatExpiry, NOTICE, titleCase } from "../text";
+
+export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
+  kind: "org.invite",
+  compose: (payload, context) => {
+    const { inviterName, orgName, role, acceptUrl, expiresAt } = payload;
+
+    return {
+      metadata: {
+        kind: "org.invite",
+        title: `You've been invited to join ${orgName} on Company Semantics`,
+      },
+      sections: [
+        {
+          elements: [
+            { type: "greeting" },
+            { type: "body", text: `${orgName} uses Company Semantics.` },
+            {
+              type: "chatUnit",
+              items: [
+                {
+                  type: "message",
+                  role: "assistant",
+                  text: "Join to accept the invitation.",
+                },
+                { type: "callToAction", label: "JOIN", href: acceptUrl },
+              ],
+            },
+            {
+              type: "keyValueTable",
+              rows: [
+                { label: "From", value: inviterName },
+                { label: "Workspace", value: orgName },
+                { label: "Role", value: titleCase(role) },
+                { label: "Expires", value: formatExpiry(expiresAt) },
+              ],
+            },
+            {
+              type: "notice",
+              lines: [
+                `This invitation was sent via ${context.brand.name}.`,
+                NOTICE,
+              ],
+            },
+            { type: "signature" },
+          ],
+        },
+      ],
+    };
+  },
+};

package/src/notifications/kinds/ownership-transfer-completed.ts

@@ -0,0 +1,57 @@
+/**
+ * Ownership-transfer-completed notice.
+ *
+ * Closes with a support instruction rather than the standard `NOTICE`: this one
+ * reports a change that already happened, so "no action is required" would be
+ * wrong if the recipient did not authorise it.
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+export const ownershipTransferCompletedDefinition: NotificationDefinition<"org.ownership_transfer_completed"> =
+  {
+    kind: "org.ownership_transfer_completed",
+    compose: (payload, context) => {
+      const { orgName, newOwnerEmail } = payload;
+
+      return {
+        metadata: {
+          kind: "org.ownership_transfer_completed",
+          title: "Workspace ownership has been transferred",
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting" },
+              { type: "body", text: "Ownership was transferred." },
+              {
+                type: "chatUnit",
+                items: [
+                  {
+                    type: "message",
+                    role: "assistant",
+                    text: "You're no longer the owner, but you remain an admin.",
+                  },
+                ],
+              },
+              {
+                type: "keyValueTable",
+                rows: [
+                  { label: "Workspace", value: orgName },
+                  { label: "New owner", value: newOwnerEmail },
+                ],
+              },
+              {
+                type: "notice",
+                lines: [
+                  `This confirmation was sent via ${context.brand.name}.`,
+                  "If you did not authorize this, contact support immediately.",
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds/ownership-transfer.ts

@@ -0,0 +1,68 @@
+/**
+ * Ownership-transfer invitation notification.
+ *
+ * `fromName` is absent for an admin-initiated transfer — there is no workspace
+ * owner to attribute — so the note bubble becomes an unattributed prompt and the
+ * From row drops out entirely.
+ */
+
+import type { KeyValueRow } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+import { formatExpiry, NOTICE } from "../text";
+
+export const ownershipTransferDefinition: NotificationDefinition<"org.ownership_transfer"> =
+  {
+    kind: "org.ownership_transfer",
+    compose: (payload, context) => {
+      const { orgName, acceptUrl, expiresAt, note, fromName } = payload;
+
+      const rows: KeyValueRow[] = [
+        ...(fromName ? [{ label: "From", value: fromName }] : []),
+        { label: "Workspace", value: orgName },
+        { label: "Expires", value: formatExpiry(expiresAt) },
+      ];
+
+      return {
+        metadata: {
+          kind: "org.ownership_transfer",
+          title: "You've been invited to become a workspace owner",
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting" },
+              { type: "body", text: "You've been invited to take ownership." },
+              {
+                type: "chatUnit",
+                items: [
+                  note
+                    ? {
+                        type: "message",
+                        role: "user",
+                        text: note,
+                        ...(fromName ? { from: fromName } : {}),
+                      }
+                    : {
+                        type: "message",
+                        role: "assistant",
+                        text: "Accept to take ownership.",
+                      },
+                  { type: "callToAction", label: "ACCEPT", href: acceptUrl },
+                ],
+              },
+              { type: "keyValueTable", rows },
+              {
+                type: "notice",
+                lines: [
+                  `This transfer was sent via ${context.brand.name}.`,
+                  NOTICE,
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds/security-alert.ts

@@ -0,0 +1,78 @@
+/**
+ * Security alert notification.
+ *
+ * The odd one out, in three ways, all faithful to what this alert says today:
+ * - It opens on a `warning` and has no greeting. A security notice addresses the
+ *   account, not the person.
+ * - It closes with no `notice`. "If you weren't expecting this, no action is
+ *   required" is the opposite of this notification's point.
+ * - It emits TWO `keyValueTable`s rather than one. `Details` sits between the
+ *   body lines and `Time` closes the alert, so grouping them would reorder what
+ *   the recipient reads. Order is content; the tables stay split.
+ */
+
+import type { NotificationElement } from "../content";
+import type { NotificationDefinition } from "../definition";
+import type { NotificationPayloads } from "../payloads";
+
+type SecurityAlertType = NotificationPayloads["security.alert"]["alertType"];
+
+/**
+ * The opening line and the "if you didn't…" line, per alert type. The three
+ * lines around them are identical for every alert, so only the difference is
+ * tabulated — the shape of the alert is stated once, in `compose`.
+ */
+const ALERT_COPY: Record<
+  SecurityAlertType,
+  { opening: string; denial: string }
+> = {
+  excessive_otp_requests: {
+    opening: "Unusual login-code activity detected.",
+    denial:
+      "If you didn't request these codes, someone may be trying to access your account.",
+  },
+  unusual_login_location: {
+    opening: "A login from an unusual location was detected.",
+    denial:
+      "If you didn't attempt to log in, someone may be trying to access your account.",
+  },
+};
+
+export const securityAlertDefinition: NotificationDefinition<"security.alert"> =
+  {
+    kind: "security.alert",
+    compose: (payload) => {
+      const { alertType, details, timestamp } = payload;
+      const copy = ALERT_COPY[alertType];
+
+      const elements: NotificationElement[] = [
+        { type: "warning" },
+        { type: "body", text: copy.opening },
+        { type: "keyValueTable", rows: [{ label: "Details", value: details }] },
+        // ONE paragraph, two lines: the reassurance and the denial are a couplet
+        // ("if it was you, nothing; if it wasn't, worry"), and the alert has read
+        // that way since it was written — the old `email/render/security-alert`
+        // spelled it `paragraph(..., "tight")` followed by a normal paragraph.
+        // Splitting them into two `body` elements would say they are two
+        // thoughts, and no renderer could recover that they are not.
+        {
+          type: "body",
+          text: `If this was you, no action is needed.\n${copy.denial}`,
+        },
+        { type: "body", text: "We recommend reviewing your account security." },
+        {
+          type: "keyValueTable",
+          rows: [{ label: "Time", value: new Date(timestamp).toUTCString() }],
+        },
+        { type: "signature" },
+      ];
+
+      return {
+        metadata: {
+          kind: "security.alert",
+          title: "Security alert for your account",
+        },
+        sections: [{ elements }],
+      };
+    },
+  };

package/src/notifications/kinds/share-granted.ts

@@ -0,0 +1,74 @@
+/**
+ * Share-granted notification (an entity was shared with the recipient).
+ *
+ * `entityTitle` is absent for entities that have no title (a meeting), so the
+ * Item row drops rather than rendering an empty quote.
+ */
+
+import type { KeyValueRow } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+import { ACCESS_PHRASE, NOTICE } from "../text";
+
+export const shareGrantedDefinition: NotificationDefinition<"share.granted"> = {
+  kind: "share.granted",
+  compose: (payload, context) => {
+    const {
+      granterName,
+      recipientName,
+      entityLabel,
+      entityTitle,
+      accessLevel,
+      ctaUrl,
+      message,
+    } = payload;
+
+    const rows: KeyValueRow[] = [
+      { label: "From", value: granterName },
+      ...(entityTitle ? [{ label: "Item", value: `"${entityTitle}"` }] : []),
+      { label: "Access", value: ACCESS_PHRASE[accessLevel] },
+    ];
+
+    return {
+      metadata: {
+        kind: "share.granted",
+        title: "Something has been shared with you",
+      },
+      sections: [
+        {
+          elements: [
+            { type: "greeting", ...(recipientName ? { recipientName } : {}) },
+            { type: "body", text: `A ${entityLabel} was shared with you.` },
+            {
+              type: "chatUnit",
+              items: [
+                message
+                  ? {
+                      type: "message",
+                      role: "user",
+                      text: message,
+                      from: granterName,
+                    }
+                  : {
+                      type: "message",
+                      role: "assistant",
+                      text: "Open to view.",
+                    },
+                { type: "callToAction", label: "OPEN", href: ctaUrl },
+              ],
+            },
+            { type: "keyValueTable", rows },
+            {
+              type: "notice",
+              lines: [
+                `This notification was sent via ${context.brand.name}.`,
+                NOTICE,
+              ],
+            },
+            { type: "signature" },
+          ],
+        },
+      ],
+    };
+  },
+};