@reflagged/shell 1.3.2 → 1.4.0

package/README.md

@@ -94,6 +94,44 @@ export { default, config } from '@reflagged/shell/middleware'
 Other API re-exports: `@reflagged/shell/api/oidc-callback`,
 `@reflagged/shell/api/oidc-signout`, `@reflagged/shell/api/shell-info`.
 
+### Notifications (`createNotifier`, `NotificationBell`)
+
+Since 1.4.0 a module can post notifications to the platform inbox. The base
+stores one inbox entry per recipient, renders and brands the mail, and
+delivers it through the tenant's sender. Modules send data, never HTML.
+
+```ts
+// server only — uses OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET
+import { createNotifier } from '@reflagged/shell/notifications/notifier'
+
+const notifier = createNotifier()
+await notifier.notify({
+  idempotencyKey: `absence-${absence.id}-approved`, // same key → no duplicate
+  topic: 'kollega.absence.approved',               // <module>.<object>.<event>
+  category: 'activity',                            // or 'transactional' (not opt-out-able)
+  title: 'Urlaub genehmigt',
+  body: '12.–16. Oktober',
+  actionUrl: `https://kollega.acme.rfl.gd/abwesenheiten/${absence.id}`, // https, own or tenant domain
+  actionLabel: 'Antrag öffnen',
+  recipients: [{ email: requester.email }],        // or { userId } / { role: 'org:admins' | 'org:members' }
+})
+```
+
+Recipients must belong to the booking's organization (403 otherwise);
+addresses without a platform account are skipped. The token comes from the
+`client_credentials` grant with scope `notifications:write`, which every
+module client of the platform may request. Errors throw `NotifyError` with
+the HTTP `status` and the base's error `code`.
+
+The bell shows the unread count (from `/api/shell-info`) and links to the
+central inbox:
+
+```tsx
+import { NotificationBell } from '@reflagged/shell/components/NotificationBell'
+
+<NotificationBell />
+```
+
 ## Local development (live-edit against a consumer)
 
 A published package is frozen in `node_modules`. To iterate on the shell and a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reflagged/shell",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Shared app shell for Reflagged services — OIDC auth, SSO, app switcher",
   "type": "module",
   "sideEffects": false,
@@ -27,7 +27,9 @@
     "./api/oidc-signout": "./src/lib/api/oidc-signout.ts",
     "./api/shell-info": "./src/lib/api/shell-info.ts",
     "./package.json": "./package.json",
-    "./components/ServiceIcon": "./src/components/ServiceIcon.tsx"
+    "./components/ServiceIcon": "./src/components/ServiceIcon.tsx",
+    "./notifications/notifier": "./src/lib/notifications/notifier.ts",
+    "./components/NotificationBell": "./src/components/NotificationBell.tsx"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/components/NotificationBell.tsx

@@ -0,0 +1,85 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+type ShellInfo = { unreadNotifications?: number; baseUrl?: string; org?: { tenantSlug?: string | null } | null }
+
+/**
+ * Bell for module headers: unread count from rflgd-base (via the module's
+ * /api/shell-info proxy) and a link to the central inbox. Renders nothing
+ * until the shell info is known, so a module without a session stays clean.
+ */
+export function NotificationBell({
+  inboxUrl,
+  className,
+}: {
+  /** Override the inbox link; defaults to `<baseUrl>/benachrichtigungen`. */
+  inboxUrl?: string
+  className?: string
+}) {
+  const [info, setInfo] = useState<ShellInfo | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    fetch('/api/shell-info', { credentials: 'include' })
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: ShellInfo | null) => {
+        if (!cancelled) setInfo(data)
+      })
+      .catch(() => undefined)
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  if (!info) return null
+  const unread = info.unreadNotifications ?? 0
+  const href = inboxUrl ?? `${(info.baseUrl ?? 'https://app.rfl.gd').replace(/\/$/, '')}/benachrichtigungen`
+  const label = unread > 0 ? `Benachrichtigungen, ${unread} ungelesen` : 'Benachrichtigungen'
+
+  return (
+    <a
+      href={href}
+      aria-label={label}
+      title={label}
+      data-testid="rflgd-notification-bell"
+      className={className}
+      style={{
+        position: 'relative',
+        display: 'inline-grid',
+        placeItems: 'center',
+        width: 40,
+        height: 40,
+        borderRadius: 10,
+        color: 'inherit',
+      }}
+    >
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+        <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9" />
+        <path d="M10.3 21a1.94 1.94 0 0 0 3.4 0" />
+      </svg>
+      {unread > 0 ? (
+        <span
+          data-testid="rflgd-notification-badge"
+          style={{
+            position: 'absolute',
+            top: 4,
+            right: 4,
+            minWidth: 16,
+            height: 16,
+            padding: '0 4px',
+            borderRadius: 999,
+            background: '#7D551A',
+            color: '#fff',
+            fontSize: 9,
+            lineHeight: '16px',
+            textAlign: 'center',
+            fontVariantNumeric: 'tabular-nums',
+          }}
+        >
+          {unread > 99 ? '99+' : unread}
+        </span>
+      ) : null}
+    </a>
+  )
+}

package/src/lib/notifications/notifier.ts

@@ -0,0 +1,120 @@
+/**
+ * Server-side helper for modules: post notifications to the rflgd-base inbox.
+ *
+ *   const notifier = createNotifier()           // reads OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET
+ *   await notifier.notify({
+ *     idempotencyKey: `absence-${id}-approved`,
+ *     topic: 'kollega.absence.approved',
+ *     category: 'activity',
+ *     title: 'Urlaub genehmigt',
+ *     actionUrl: `https://kollega.acme.rfl.gd/abwesenheiten/${id}`,
+ *     recipients: [{ email: requester.email }],
+ *   })
+ *
+ * The token is fetched with the client_credentials grant (scope
+ * `notifications:write`) and cached until shortly before it expires.
+ * Modules send data, never HTML; the base renders and brands every mail.
+ */
+
+export type NotificationRecipient =
+  | { userId: number }
+  | { email: string }
+  | { role: 'org:admins' | 'org:members' }
+
+export type NotifyInput = {
+  idempotencyKey: string
+  /** `<module>.<object>.<event>`, lower case. */
+  topic: string
+  category: 'transactional' | 'activity'
+  title: string
+  body?: string
+  /** https link on the module's or tenant's domain. */
+  actionUrl?: string
+  actionLabel?: string
+  data?: Record<string, unknown>
+  recipients: NotificationRecipient[]
+}
+
+export type NotifyResult = { ids: number[]; recipients: number; skipped: number }
+
+export class NotifyError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string,
+  ) {
+    super(message)
+    this.name = 'NotifyError'
+  }
+}
+
+type NotifierOptions = {
+  issuer?: string
+  clientId?: string
+  clientSecret?: string
+  fetch?: typeof fetch
+}
+
+const SCOPE = 'notifications:write'
+const EXPIRY_SKEW_MS = 60_000
+
+export function createNotifier(options: NotifierOptions = {}) {
+  const issuer = (options.issuer ?? process.env.OIDC_ISSUER ?? '').replace(/\/$/, '')
+  const clientId = options.clientId ?? process.env.OIDC_CLIENT_ID ?? ''
+  const clientSecret = options.clientSecret ?? process.env.OIDC_CLIENT_SECRET ?? ''
+  const doFetch = options.fetch ?? fetch
+  if (!issuer || !clientId || !clientSecret) {
+    throw new Error('createNotifier: OIDC_ISSUER, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET are required')
+  }
+  const baseUrl = issuer.replace(/\/oidc$/, '')
+  let cached: { token: string; expiresAt: number } | null = null
+
+  async function token(): Promise<string> {
+    if (cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now()) return cached.token
+    const res = await doFetch(`${issuer}/token`, {
+      method: 'POST',
+      headers: {
+        authorization: `Basic ${btoa(`${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`)}`,
+        'content-type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({ grant_type: 'client_credentials', scope: SCOPE }),
+    })
+    const body = (await res.json().catch(() => ({}))) as {
+      access_token?: string
+      expires_in?: number
+      error?: string
+    }
+    if (!res.ok || !body.access_token) {
+      throw new NotifyError(`token request failed: ${body.error ?? res.status}`, res.status, body.error ?? 'token')
+    }
+    cached = { token: body.access_token, expiresAt: Date.now() + (body.expires_in ?? 600) * 1000 }
+    return cached.token
+  }
+
+  async function send(input: NotifyInput, accessToken: string): Promise<Response> {
+    return doFetch(`${baseUrl}/api/notifications`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${accessToken}`, 'content-type': 'application/json' },
+      body: JSON.stringify(input),
+    })
+  }
+
+  return {
+    async notify(input: NotifyInput): Promise<NotifyResult> {
+      let res = await send(input, await token())
+      if (res.status === 401) {
+        cached = null
+        res = await send(input, await token())
+      }
+      const body = (await res.json().catch(() => ({}))) as {
+        success?: boolean
+        data?: NotifyResult
+        error?: { code?: string; message?: string }
+      }
+      if (!res.ok || !body.success || !body.data) {
+        throw new NotifyError(body.error?.message ?? `notify failed (${res.status})`, res.status, body.error?.code ?? 'failed')
+      }
+      return body.data
+    },
+  }
+}