@reflagged/shell 1.8.1 → 1.9.0

package/README.md

@@ -123,6 +123,106 @@ addresses without a platform account are skipped. The token comes from the
 module client of the platform may request. Errors throw `NotifyError` with
 the HTTP `status` and the base's error `code`.
 
+#### Rich mails (`blocks`, since 1.9.0)
+
+`title`, `body` and one button are enough for a short note. For anything with
+structure — a status, facts, a table, a transcript — send `blocks`. A module
+chooses the building blocks; how they look (colours, fonts, logo, spacing)
+comes from the tenant's branding, rendered by the base with React Email. There
+is no HTML and no style property, so every module's mail looks like it
+belongs to the tenant and renders in Outlook, Gmail and Apple Mail alike.
+
+```ts
+import { createNotifier, type Block } from '@reflagged/shell/notifications/notifier'
+
+const blocks: Block[] = [
+  { type: 'callout', tone: 'warning', title: 'Rückruf nötig', text: 'Weitergabe zugesagt' },
+  {
+    type: 'facts',
+    items: [
+      { label: 'Anliegen', value: 'Angebot für einen Onlineshop' },
+      { label: 'Rückruf an', value: [{ text: '0721 952 795 78', href: 'tel:+4972195279578' }] },
+      { label: 'Dauer', value: '1:05 Min.' },
+    ],
+  },
+  {
+    type: 'section',
+    title: 'Gesprächsverlauf',
+    tone: 'outlined',
+    blocks: [
+      {
+        type: 'conversation',
+        messages: [
+          { speaker: 'Agent', side: 'end', text: 'Hallo, hier ist die digitale Assistenz.' },
+          { speaker: 'Anrufer', text: 'Ich möchte bitte zurückgerufen werden.' },
+        ],
+      },
+    ],
+  },
+]
+
+await createNotifier().notify({
+  idempotencyKey: `call-${call.id}-callback`,
+  topic: 'voice.call.callback',
+  category: 'transactional',
+  title: 'Rückrufwunsch – Angebot Onlineshop',  // subject and heading
+  body: 'Angebot für einen Onlineshop',          // short text for the inbox list
+  blocks,
+  actionUrl: `https://voice.acme.rfl.gd/calls/${call.id}`,
+  actionLabel: 'Anruf öffnen',                   // rendered as the last button
+  recipients: [{ role: 'org:admins' }],
+})
+```
+
+| Block | Fields | Use for |
+|---|---|---|
+| `heading` | `text`, `level?` 1–3 | sub-headings inside the mail |
+| `text` | `text`, `size?` sm/md/lg, `muted?`, `align?` | paragraphs; line breaks are kept |
+| `button` | `label`, `url`, `variant?` primary/secondary, `align?` | links as buttons (`tel:`/`mailto:` too) |
+| `image` | `src`, `alt`, `width?`, `href?`, `align?` | charts, screenshots — https on the booking's or tenant's domain |
+| `callout` | `tone` neutral/info/success/warning/danger, `title?`, `text?` | status banners; tone colours are fixed, not branded |
+| `facts` | `items[{ label, value }]` | label/value pairs |
+| `list` | `items[]`, `ordered?` | bullet or numbered lists |
+| `table` | `columns[{ label, align? }]`, `rows[][]` | tabular data, up to 8 columns / 200 rows |
+| `quote` | `text`, `cite?` | quoted statements |
+| `conversation` | `messages[{ speaker, text, side?, time? }]` | transcripts, chats; `side: 'end'` = the module's own side |
+| `code` | `code`, `language?` | logs, snippets (monospace) |
+| `divider`, `spacer` | `size?` | separation |
+| `section` | `blocks`, `title?`, `tone?` plain/muted/outlined | grouping |
+| `row` | `columns[{ blocks, width? }]` (2–4) | side-by-side content, e.g. key figures |
+
+Every `text`/`value`/cell is a `RichText`: a plain string, or spans for
+emphasis and links — `[{ text: 'fett', bold: true }, { text: ' und ' },
+{ text: 'Link', href: 'https://…' }]`. Markdown is **not** interpreted.
+
+Rules the base enforces (400 with the failing path otherwise): only the
+blocks above, no extra properties, links https/`tel:`/`mailto:`, images from
+the booking's or tenant's domains, at most 200 top-level blocks, 100 kB, and
+`section`/`row` nested three levels deep. The base also writes a plain-text
+part from the blocks and shows the full mail in the platform inbox. Without
+`blocks`, `body` is rendered as paragraphs as before. Types:
+`@reflagged/shell/notifications/blocks`.
+
+#### Email: modules do not send mail themselves
+
+Every mail a module sends to a person goes through `notify()`. A module
+configures **no SMTP server, no mail adapter and no mail credentials** — no
+`@payloadcms/email-*`, no `nodemailer`, no `SMTP_*` variables in the manifest
+or compose file. The base owns the sender per tenant (own SMTP server,
+Microsoft 365 or the platform's `app@rfl.gd` with SPF/DKIM), the branding,
+the user's preferences, unsubscribe links and the delivery log.
+
+- `category: 'transactional'` for mails that must arrive (cannot be opted
+  out of), `'activity'` for everything else.
+- Only people with a platform account in the booking's organization can be
+  reached. Mail to outsiders (a tenant's own customers, newsletters) is not
+  supported — raise it with the platform team instead of adding a transport.
+- **Passwords are not a module concern.** Users sign in through the
+  platform's SSO; password reset, invitations and 2FA live in the base. The
+  local Payload login is a bootstrap fallback for the first admin only —
+  never hand out local module credentials to customers, because the module
+  cannot send them a reset mail.
+
 The bell shows the unread count (from `/api/shell-info`) and links to the
 central inbox:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reflagged/shell",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Shared app shell for Reflagged services — OIDC auth, SSO, app switcher",
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,7 @@
     "./package.json": "./package.json",
     "./components/ServiceIcon": "./src/components/ServiceIcon.tsx",
     "./notifications/notifier": "./src/lib/notifications/notifier.ts",
+    "./notifications/blocks": "./src/lib/notifications/blocks.ts",
     "./components/NotificationBell": "./src/components/NotificationBell.tsx",
     "./components/ImpersonationCapsule": "./src/components/ImpersonationCapsule.tsx"
   },

package/src/lib/notifications/blocks.ts

@@ -0,0 +1,109 @@
+/**
+ * Content blocks for platform mails (`notify({ blocks })`).
+ *
+ * A module describes WHAT a mail says — a status, facts, a conversation, a
+ * table — and the base decides HOW it looks: colours, fonts, logo and layout
+ * come from the tenant's branding. There is no HTML and no style property;
+ * text is always literal (`**x**` stays `**x**`), emphasis and links go into
+ * spans.
+ *
+ * Validated by the base (rflgd-base `src/lib/notifications/blocks/schema.ts`);
+ * an invalid block answers 400 with the path of the offending field.
+ *
+ * Limits: 200 top-level blocks, 100 kB as JSON, `section`/`row` nested at most
+ * three levels. Links: https, `tel:` or `mailto:`. Images: https on a domain of
+ * the booking or the tenant (anything else would be a tracking pixel).
+ */
+
+/** A run of text with optional emphasis or a link. */
+export type Span = {
+  text: string
+  bold?: boolean
+  italic?: boolean
+  strike?: boolean
+  code?: boolean
+  /** https://…, tel:+49…, mailto:… */
+  href?: string
+}
+
+/** Plain text, or spans for emphasis and links. Line breaks are kept. */
+export type RichText = string | Span[]
+
+export type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'danger'
+export type Align = 'left' | 'center' | 'right'
+
+export type HeadingBlock = { type: 'heading'; text: RichText; level?: 1 | 2 | 3 }
+export type TextBlock = {
+  type: 'text'
+  text: RichText
+  size?: 'sm' | 'md' | 'lg'
+  muted?: boolean
+  align?: Align
+}
+export type ButtonBlock = {
+  type: 'button'
+  label: string
+  url: string
+  variant?: 'primary' | 'secondary'
+  align?: Align
+}
+export type ImageBlock = {
+  type: 'image'
+  /** https on a domain of the booking or the tenant. PNG/JPEG/GIF render everywhere. */
+  src: string
+  alt: string
+  /** CSS pixels, 16–600; scales down on narrow screens. */
+  width?: number
+  href?: string
+  align?: Align
+}
+export type DividerBlock = { type: 'divider' }
+export type SpacerBlock = { type: 'spacer'; size?: 'sm' | 'md' | 'lg' }
+/** Status banner: "Rückruf nötig", "Freigabe abgelehnt", … */
+export type CalloutBlock = { type: 'callout'; tone: Tone; title?: string; text?: RichText }
+/** Label/value pairs, e.g. caller, number, duration. */
+export type FactsBlock = { type: 'facts'; items: { label: string; value: RichText }[] }
+export type ListBlock = { type: 'list'; items: RichText[]; ordered?: boolean }
+export type TableBlock = {
+  type: 'table'
+  columns: { label: string; align?: Align }[]
+  rows: RichText[][]
+}
+export type QuoteBlock = { type: 'quote'; text: RichText; cite?: string }
+export type ConversationBlock = {
+  type: 'conversation'
+  messages: {
+    speaker: string
+    text: RichText
+    /** `end` marks the module's own side (agent, bot, colleague). */
+    side?: 'start' | 'end'
+    time?: string
+  }[]
+}
+export type CodeBlock = { type: 'code'; code: string; language?: string }
+/** Groups blocks under an optional title, plain, on a muted ground or outlined. */
+export type SectionBlock = {
+  type: 'section'
+  title?: string
+  tone?: 'plain' | 'muted' | 'outlined'
+  blocks: Block[]
+}
+/** 2–4 columns side by side; `width` in percent. */
+export type RowBlock = { type: 'row'; columns: { width?: number; blocks: Block[] }[] }
+
+export type Block =
+  | HeadingBlock
+  | TextBlock
+  | ButtonBlock
+  | ImageBlock
+  | DividerBlock
+  | SpacerBlock
+  | CalloutBlock
+  | FactsBlock
+  | ListBlock
+  | TableBlock
+  | QuoteBlock
+  | ConversationBlock
+  | CodeBlock
+  | SectionBlock
+  | RowBlock

package/src/lib/notifications/notifier.ts

@@ -16,6 +16,10 @@
  * Modules send data, never HTML; the base renders and brands every mail.
  */
 
+import type { Block } from './blocks'
+
+export type { Block } from './blocks'
+
 export type NotificationRecipient =
   | { userId: number }
   | { email: string }
@@ -32,6 +36,11 @@ export type NotifyInput = {
   actionUrl?: string
   actionLabel?: string
   data?: Record<string, unknown>
+  /**
+   * Structured mail content (status, facts, tables, conversations, …). The
+   * base renders it in the tenant's branding; `body` stays the short inbox text.
+   */
+  blocks?: Block[]
   recipients: NotificationRecipient[]
 }