create-astram-app 0.12.10 → 0.13.0

package/template/frontend/src/shell/notificationsView.js

@@ -0,0 +1,138 @@
+/**
+ * notificationsView — React-free helpers for the header bell and Announcements menus (G-027
+ * step 5). Kept pure so `node --test` covers them (notificationsView.test.mjs); the menus in
+ * NotificationsMenu.jsx / AnnouncementsMenu.jsx only render what these return.
+ */
+
+/** The counts poll interval (spec §10: 60 s, plus window focus). */
+export const POLL_MS = 60_000;
+
+/** The longest notice link the server accepts (guard `NOTIFICATION_LINK_MAX`). */
+const LINK_MAX = 512;
+
+// Any C0 control character or DEL (the guard's link rule refuses them all, newline included).
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+
+/** Badge text for an unread count: 0 (or not a count) ⇒ '' (no badge), above 9 ⇒ '9+'. */
+export function badgeText(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 1) return '';
+  return n > 9 ? '9+' : String(Math.floor(n));
+}
+
+/** Accessible name for a header menu button, e.g. "Notifications, 3 unread". */
+export function badgeLabel(label, n) {
+  const text = badgeText(n);
+  return text ? `${label}, ${text} unread` : label;
+}
+
+/**
+ * "just now" / "5 min ago" / "3 h ago" / "2 d ago", then the date. `now` is a ms timestamp;
+ * `opts` ({ locale, timeZone }) only shapes the date form (tests pin them). An unparsable time
+ * ⇒ '' (never "Invalid Date"); a time slightly in the future (clock skew) ⇒ "just now".
+ */
+export function relativeTime(iso, now = Date.now(), opts = {}) {
+  if (typeof iso !== 'string' || iso === '') return '';
+  const at = Date.parse(iso);
+  if (Number.isNaN(at)) return '';
+  const seconds = Math.floor((now - at) / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days} d ago`;
+  return formatDay(at, opts);
+}
+
+/** A calendar date ("20 Oct 2026" in en-GB), or '' when unparsable. */
+function formatDay(ms, { locale, timeZone } = {}) {
+  try {
+    return new Date(ms).toLocaleDateString(locale, {
+      day: 'numeric',
+      month: 'short',
+      year: 'numeric',
+      ...(timeZone ? { timeZone } : {}),
+    });
+  } catch {
+    return '';
+  }
+}
+
+/** An admin task's heading: "New permission: <label>". Never falls back to the raw key. */
+export function taskTitle(row) {
+  const label = typeof row?.label === 'string' ? row.label.trim() : '';
+  return label ? `New permission: ${label}` : 'New permission';
+}
+
+/**
+ * When the task's permission first appeared: "Release 1.4.0 · 20 Oct 2026", either half alone,
+ * or '' when neither is known. `opts` as for {@link relativeTime}.
+ */
+export function taskSince(row, opts = {}) {
+  const parts = [];
+  if (typeof row?.firstSeenVersion === 'string' && row.firstSeenVersion !== '') {
+    parts.push(`Release ${row.firstSeenVersion}`);
+  }
+  if (typeof row?.firstSeenAt === 'string') {
+    const at = Date.parse(row.firstSeenAt);
+    if (!Number.isNaN(at)) {
+      const day = formatDay(at, opts);
+      if (day) parts.push(day);
+    }
+  }
+  return parts.join(' · ');
+}
+
+/**
+ * The notice link when it is safe to follow inside the app, else null. Mirrors the guard rule
+ * (`notification.service.ts` `validLink`): one leading `/` (never `//`), no backslash, no control
+ * character, at most 512 characters. A scheme can never follow a single leading `/`.
+ */
+export function safeAppLink(link) {
+  if (typeof link !== 'string' || link === '' || link.length > LINK_MAX) return null;
+  if (!link.startsWith('/') || link.startsWith('//')) return null;
+  if (link.includes('\\') || CONTROL_CHARS.test(link)) return null;
+  return link;
+}
+
+/** Poll the counts only while the tab is visible (`document.visibilityState`). */
+export function shouldPoll(visibilityState) {
+  return visibilityState === 'visible';
+}
+
+/**
+ * The key that owns a set of badge counts: tenant, principal and session id of the signed-in
+ * session, or null when signed out. The counts store stamps its counts with this key and the
+ * hook compares it during render, so one user's counts never show for the next session.
+ */
+export function sessionKeyOf(session) {
+  if (!session || typeof session !== 'object') return null;
+  return `${session.tenantId ?? ''}:${session.principalId ?? ''}:${session.sessionId ?? ''}`;
+}
+
+const NO_COUNTS = Object.freeze({ personal: 0, announcement: 0, tasks: 0 });
+
+/**
+ * The counts to show for `sessionKey`: the stored counts only when they were fetched for that
+ * same session, else all 0 (signed out, a different session, or nothing fetched yet).
+ * A missing or non-numeric field reads as 0.
+ */
+export function countsFor(stored, sessionKey) {
+  if (typeof sessionKey !== 'string' || sessionKey === '') return NO_COUNTS;
+  if (!stored || stored.sessionKey !== sessionKey) return NO_COUNTS;
+  const n = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+  return {
+    personal: n(stored.personal),
+    announcement: n(stored.announcement),
+    tasks: n(stored.tasks),
+  };
+}
+
+/** The Announcements badge: unread announcement notices plus open admin tasks. */
+export function announcementsBadgeCount(counts) {
+  const a = Number.isFinite(counts?.announcement) ? counts.announcement : 0;
+  const t = Number.isFinite(counts?.tasks) ? counts.tasks : 0;
+  return a + t;
+}

package/template/frontend/src/shell/notificationsView.test.mjs

@@ -0,0 +1,182 @@
+// notificationsView.test.mjs — header bell / Announcements helpers (G-027 step 5): badge text,
+// relative time, task heading, the app-relative link rule (mirrors the guard) and the
+// visibility-gated poll.
+//
+//   node --test src/shell/notificationsView.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  POLL_MS,
+  announcementsBadgeCount,
+  badgeLabel,
+  badgeText,
+  countsFor,
+  relativeTime,
+  sessionKeyOf,
+  safeAppLink,
+  shouldPoll,
+  taskSince,
+  taskTitle,
+} from './notificationsView.js';
+
+const fmt = { locale: 'en-GB', timeZone: 'UTC' };
+const now = Date.parse('2026-10-26T12:00:00.000Z');
+const ago = (ms) => new Date(now - ms).toISOString();
+
+describe('badgeText', () => {
+  test('0, negatives and non-counts ⇒ no badge', () => {
+    for (const n of [0, -1, NaN, undefined, null, '3']) assert.equal(badgeText(n), '');
+  });
+  test('1..9 as is, above 9 ⇒ 9+', () => {
+    assert.equal(badgeText(1), '1');
+    assert.equal(badgeText(9), '9');
+    assert.equal(badgeText(10), '9+');
+    assert.equal(badgeText(250), '9+');
+  });
+  test('badgeLabel names the count for screen readers', () => {
+    assert.equal(badgeLabel('Notifications', 0), 'Notifications');
+    assert.equal(badgeLabel('Notifications', 3), 'Notifications, 3 unread');
+    assert.equal(badgeLabel('Announcements', 12), 'Announcements, 9+ unread');
+  });
+  test('announcementsBadgeCount adds unread announcements and open tasks', () => {
+    assert.equal(announcementsBadgeCount({ announcement: 2, tasks: 3, personal: 7 }), 5);
+    assert.equal(announcementsBadgeCount({ announcement: 2 }), 2);
+    assert.equal(announcementsBadgeCount(null), 0);
+  });
+});
+
+describe('relativeTime', () => {
+  test('under a minute (and slight future skew) ⇒ just now', () => {
+    assert.equal(relativeTime(ago(5_000), now, fmt), 'just now');
+    assert.equal(relativeTime(ago(-30_000), now, fmt), 'just now');
+  });
+  test('minutes, hours, days', () => {
+    assert.equal(relativeTime(ago(5 * 60_000), now, fmt), '5 min ago');
+    assert.equal(relativeTime(ago(3 * 3_600_000), now, fmt), '3 h ago');
+    assert.equal(relativeTime(ago(2 * 86_400_000), now, fmt), '2 d ago');
+  });
+  test('a week or more ⇒ the date', () => {
+    assert.equal(relativeTime('2026-10-01T09:00:00.000Z', now, fmt), '1 Oct 2026');
+  });
+  test('missing or unparsable ⇒ empty, never "Invalid Date"', () => {
+    assert.equal(relativeTime(undefined, now, fmt), '');
+    assert.equal(relativeTime('', now, fmt), '');
+    assert.equal(relativeTime('not a date', now, fmt), '');
+  });
+});
+
+describe('taskTitle / taskSince', () => {
+  test('heading uses the label, never the key', () => {
+    assert.equal(
+      taskTitle({ label: 'Invoices: approve', key: 'billing:invoice:approve' }),
+      'New permission: Invoices: approve',
+    );
+    assert.equal(taskTitle({ label: '  ', key: 'billing:invoice:approve' }), 'New permission');
+    assert.equal(taskTitle(null), 'New permission');
+  });
+  test('first-seen release and date', () => {
+    const row = { firstSeenVersion: '1.4.0', firstSeenAt: '2026-10-20T09:30:00.000Z' };
+    assert.equal(taskSince(row, fmt), 'Release 1.4.0 · 20 Oct 2026');
+    assert.equal(taskSince({ firstSeenVersion: '1.4.0', firstSeenAt: null }, fmt), 'Release 1.4.0');
+    assert.equal(
+      taskSince({ firstSeenVersion: null, firstSeenAt: row.firstSeenAt }, fmt),
+      '20 Oct 2026',
+    );
+    assert.equal(taskSince({ firstSeenVersion: null, firstSeenAt: 'x' }, fmt), '');
+  });
+});
+
+describe('safeAppLink (the guard link rule)', () => {
+  test('app-relative paths pass', () => {
+    assert.equal(safeAppLink('/imports/42?tab=review'), '/imports/42?tab=review');
+    assert.equal(safeAppLink('/access'), '/access');
+  });
+  test('absolute, protocol-relative, schemes and relative paths are refused', () => {
+    for (const link of [
+      'https://evil.example/phish',
+      '//evil.example',
+      'javascript:alert(1)',
+      'imports/1',
+      ' /imports/1',
+    ]) {
+      assert.equal(safeAppLink(link), null, link);
+    }
+  });
+  test('backslashes and control characters are refused', () => {
+    for (const link of ['/\\evil.example', '/a\tb', '/a\nb', '/a\u0000b', '/a\u007fb']) {
+      assert.equal(safeAppLink(link), null, JSON.stringify(link));
+    }
+  });
+  test('empty, non-string and over-long ⇒ null', () => {
+    assert.equal(safeAppLink(''), null);
+    assert.equal(safeAppLink(null), null);
+    assert.equal(safeAppLink(42), null);
+    assert.equal(safeAppLink('/' + 'x'.repeat(512)), null);
+    assert.equal(safeAppLink('/' + 'x'.repeat(511)), '/' + 'x'.repeat(511));
+  });
+});
+
+describe('sessionKeyOf', () => {
+  test('tenant, principal and session id; null when signed out', () => {
+    assert.equal(sessionKeyOf({ tenantId: 't1', principalId: 'p1', sessionId: 's1' }), 't1:p1:s1');
+    assert.equal(sessionKeyOf({ principalId: 'p1' }), ':p1:');
+    assert.equal(sessionKeyOf(null), null);
+    assert.equal(sessionKeyOf(undefined), null);
+  });
+  test('a different user or a new session gives a different key', () => {
+    const a = sessionKeyOf({ tenantId: 't1', principalId: 'pA', sessionId: 's1' });
+    const b = sessionKeyOf({ tenantId: 't1', principalId: 'pB', sessionId: 's2' });
+    const a2 = sessionKeyOf({ tenantId: 't1', principalId: 'pA', sessionId: 's3' });
+    assert.notEqual(a, b);
+    assert.notEqual(a, a2);
+  });
+});
+
+describe('countsFor', () => {
+  const zero = { personal: 0, announcement: 0, tasks: 0 };
+  const storedA = { personal: 3, announcement: 2, tasks: 5, sessionKey: 't1:pA:s1' };
+
+  test('the stored counts for their own session', () => {
+    assert.deepEqual(countsFor(storedA, 't1:pA:s1'), { personal: 3, announcement: 2, tasks: 5 });
+  });
+  test("another session never sees the previous user's counts (sign-out, sign-in as B)", () => {
+    assert.deepEqual(countsFor(storedA, 't1:pB:s2'), zero);
+    assert.deepEqual(countsFor(storedA, 't1:pA:s9'), zero);
+  });
+  test('signed out or no key ⇒ 0', () => {
+    assert.deepEqual(countsFor(storedA, null), zero);
+    assert.deepEqual(countsFor(storedA, ''), zero);
+    assert.deepEqual(countsFor(storedA, undefined), zero);
+  });
+  test('nothing stored, or counts stamped with no session ⇒ 0', () => {
+    assert.deepEqual(countsFor(null, 't1:pA:s1'), zero);
+    assert.deepEqual(countsFor({ personal: 4, announcement: 1, tasks: 1 }, 't1:pA:s1'), zero);
+    assert.deepEqual(
+      countsFor({ personal: 4, announcement: 1, tasks: 1, sessionKey: null }, 't1:pA:s1'),
+      zero,
+    );
+  });
+  test('missing, negative or non-numeric fields read as 0', () => {
+    assert.deepEqual(
+      countsFor({ sessionKey: 'k', personal: -1, announcement: Number.NaN, tasks: '7' }, 'k'),
+      zero,
+    );
+    assert.deepEqual(countsFor({ sessionKey: 'k', personal: 2 }, 'k'), {
+      personal: 2,
+      announcement: 0,
+      tasks: 0,
+    });
+  });
+});
+
+describe('shouldPoll', () => {
+  test('only while the tab is visible', () => {
+    assert.equal(shouldPoll('visible'), true);
+    assert.equal(shouldPoll('hidden'), false);
+    assert.equal(shouldPoll('prerender'), false);
+    assert.equal(shouldPoll(undefined), false);
+  });
+  test('60 s cadence', () => {
+    assert.equal(POLL_MS, 60_000);
+  });
+});

package/template/frontend/src/shell/useNotificationCounts.js

@@ -0,0 +1,211 @@
+/**
+ * useNotificationCounts — the ONE shared source of the header badge counts (G-027 step 5):
+ * `{ personal, announcement, tasks, refresh }`.
+ *
+ * Why a module-level store (read through `useSyncExternalStore`) rather than a React provider:
+ * every page renders its own <AppShell>, so anything mounted inside the shell remounts on each
+ * navigation, and the Access form (Phase 3) renders the shell rather than sitting under it. A
+ * provider would have to live in main.jsx/App.jsx; the store needs no new wrapper, survives
+ * those remounts (no badge flicker, no request per navigation) and lets any component under
+ * <AuthProvider> call the same `refresh()`.
+ *
+ * Triggers (spec §5.C, §11): sign-in (a new session), window focus, every 60 s only while
+ * `document.visibilityState === 'visible'`, at once when the tab becomes visible again, and
+ * `refresh()` after the user's own actions. Listeners and the interval are armed while at least
+ * one component uses the hook and a token is present; re-armed when the token or session
+ * changes (the auth-facts pattern in AuthContext.jsx). A failed call keeps the last value; the
+ * services never throw, and nothing here does either.
+ *
+ * Tasks = `listPermissionAnnouncements({ status: 'open', limit: 1 }).total`, only when
+ * `can('identity:role:update')` (cosmetic, fail closed: no facts ⇒ 0 and no call); a 403 ⇒ 0.
+ * The server still decides every call.
+ */
+import { useEffect, useSyncExternalStore } from 'react';
+import { useAuth } from '@/auth/AuthContext';
+import { POLL_MS, countsFor, sessionKeyOf, shouldPoll } from './notificationsView';
+
+/** The permission that shows the admin tasks (the server's own check on the route). */
+export const TASKS_PERMISSION = 'identity:role:update';
+
+// The stored counts carry the session key they were fetched for; the hook shows them only to
+// that same session (countsFor), so a previous user's counts never render for the next one,
+// even on the first render before `configure` runs.
+const ZERO = Object.freeze({ personal: 0, announcement: 0, tasks: 0, sessionKey: null });
+
+// Focus and visibilitychange both fire when the user returns to the tab: one request, not two.
+const TRIGGER_GAP_MS = 2_000;
+
+const store = {
+  counts: ZERO,
+  listeners: new Set(),
+  /** { notifications, identity, token, sessionKey, canTasks } from the latest render. */
+  deps: null,
+  /** Bumped per refresh and on a session change; an older answer is dropped. */
+  seq: 0,
+  lastStartedAt: 0,
+  consumers: 0,
+  disarm: null,
+};
+
+function emit(next) {
+  store.counts = next;
+  for (const listener of store.listeners) listener();
+}
+
+function subscribe(listener) {
+  store.listeners.add(listener);
+  return () => store.listeners.delete(listener);
+}
+
+function snapshot() {
+  return store.counts;
+}
+
+/** Fetch both counts for the current session. Resolves once applied; never rejects. */
+async function runRefresh() {
+  const deps = store.deps;
+  if (!deps?.token) return;
+  const seq = ++store.seq;
+  store.lastStartedAt = Date.now();
+  const { notifications, identity, token, canTasks, sessionKey } = deps;
+  let unread;
+  let tasks;
+  try {
+    [unread, tasks] = await Promise.all([
+      notifications.unreadNotificationCount(token),
+      canTasks
+        ? identity.listPermissionAnnouncements(token, { status: 'open', limit: 1 })
+        : Promise.resolve(null),
+    ]);
+  } catch {
+    return; // documented never to throw; belt and braces — keep the last value
+  }
+  // Superseded by a later refresh, or the session changed meanwhile: drop this answer.
+  if (seq !== store.seq || store.deps?.sessionKey !== sessionKey) return;
+  // The last value for THIS session (0s when the stored counts belong to another one).
+  const prev = countsFor(store.counts, sessionKey);
+  let taskCount = prev.tasks;
+  if (!canTasks || tasks?.status === 403) taskCount = 0;
+  else if (tasks?.ok === true) taskCount = tasks.total;
+  const next = {
+    personal: unread?.ok === true ? unread.personal : prev.personal,
+    announcement: unread?.ok === true ? unread.announcement : prev.announcement,
+    tasks: taskCount,
+    sessionKey,
+  };
+  if (
+    store.counts.sessionKey !== sessionKey ||
+    next.personal !== prev.personal ||
+    next.announcement !== prev.announcement ||
+    next.tasks !== prev.tasks
+  ) {
+    emit(next);
+  }
+}
+
+/** Refresh now (after the user's own action). Safe to call anywhere, any time. */
+export function refreshNotificationCounts() {
+  return runRefresh();
+}
+
+/** Take the latest services/token/session/permission from a render. */
+function configure(next) {
+  const prev = store.deps;
+  store.deps = next;
+  const sessionChanged = prev?.sessionKey !== next.sessionKey;
+  if (sessionChanged || !next.token) {
+    store.seq += 1; // drop any answer for the previous session
+    store.lastStartedAt = 0;
+    if (store.counts !== ZERO) emit(ZERO);
+  }
+  if (!next.token) return;
+  // Sign-in (new session), or the tasks permission arrived/left with the auth facts.
+  if (sessionChanged || prev?.canTasks !== next.canTasks) void runRefresh();
+}
+
+/** Attach focus / visibility listeners and the interval for one consumer; returns its release. */
+function arm() {
+  store.consumers += 1;
+  if (store.consumers === 1) {
+    let intervalId = null;
+    const visible = () => shouldPoll(document.visibilityState);
+    const startInterval = () => {
+      if (intervalId === null) {
+        intervalId = setInterval(() => {
+          if (visible()) void runRefresh();
+        }, POLL_MS);
+      }
+    };
+    const stopInterval = () => {
+      if (intervalId !== null) clearInterval(intervalId);
+      intervalId = null;
+    };
+    const poke = () => {
+      if (visible() && Date.now() - store.lastStartedAt >= TRIGGER_GAP_MS) void runRefresh();
+    };
+    const onVisibility = () => {
+      if (visible()) {
+        poke(); // one immediate refresh, then the 60 s cycle from now
+        stopInterval();
+        startInterval();
+      } else {
+        stopInterval(); // hidden: no count requests at all
+      }
+    };
+    window.addEventListener('focus', poke);
+    document.addEventListener('visibilitychange', onVisibility);
+    if (visible()) startInterval();
+    store.disarm = () => {
+      window.removeEventListener('focus', poke);
+      document.removeEventListener('visibilitychange', onVisibility);
+      stopInterval();
+    };
+  }
+  // Re-armed after a navigation (the shell remounts): refresh only if the last one is a poll old.
+  if (shouldPoll(document.visibilityState) && Date.now() - store.lastStartedAt >= POLL_MS) {
+    void runRefresh();
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    store.consumers -= 1;
+    if (store.consumers === 0 && store.disarm) {
+      store.disarm();
+      store.disarm = null;
+    }
+  };
+}
+
+/**
+ * `{ personal, announcement, tasks, refresh }` for the signed-in user; all 0 when signed out.
+ * Call `refresh()` right after the user's own mark read, mark all read, dismiss, reopen or saved
+ * grant so the badges move at once rather than on the next poll.
+ */
+export function useNotificationCounts() {
+  const { tokens, session, notifications, identity, can } = useAuth();
+  const token = tokens?.accessToken ?? null;
+  const sessionKey = sessionKeyOf(session);
+  const canTasks = can(TASKS_PERMISSION);
+
+  useEffect(() => {
+    configure({ notifications, identity, token, sessionKey, canTasks });
+  }, [notifications, identity, token, sessionKey, canTasks]);
+
+  // Re-armed whenever the token/session changes so a stale closure never polls for a
+  // signed-out or replaced session.
+  useEffect(() => {
+    if (!token) return undefined;
+    return arm();
+  }, [token, sessionKey]);
+
+  const counts = useSyncExternalStore(subscribe, snapshot, snapshot);
+  // Decided during render: counts stamped with another session (or none) show as 0.
+  const current = countsFor(counts, token ? sessionKey : null);
+  return {
+    personal: current.personal,
+    announcement: current.announcement,
+    tasks: current.tasks,
+    refresh: refreshNotificationCounts,
+  };
+}

package/template/server/package.json

@@ -25,7 +25,7 @@
     "@astram/engine": "0.16.2",
     "@astram/guard": "0.25.1",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.22.0",
+    "@astram/identity": "0.23.0",
     "@astram/messaging": "0.1.11",
     "@astram/migrate": "0.7.4",
     "@astram/sdk": "^0.2.0",