@digitalcanopy/notifications 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @digitalcanopy/notifications
+
+## 0.1.1
+
+### Patch Changes
+
+- Manual patch release for @digitalcanopy/notifications

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @digitalcanopy/notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Universal notification triage state machine, AI digest contracts, and a collapsible `NotificationDigestCard`.
+
+- `@digitalcanopy/notifications` – headless types, `triageReducer`, `buildDigestRollup`, `notificationKey`, `isSafeActionUrl` (no React required).
+- `@digitalcanopy/notifications/react` – `useNotificationDigest` and `NotificationDigestCard` (requires `react`).
+
+Notifications are identified by the composite key `source:id` (`notificationKey()`); `markRead`/`dismiss` take that key. Dismissed keys stay dismissed when re-ingested. Action URLs are rendered only if `isSafeActionUrl` allows them (http, https, mailto, relative).
+
+## Tailwind
+
+`NotificationDigestCard` uses Tailwind utility classes and ships no CSS. Add the package to your Tailwind `content` globs, e.g.:
+
+```js
+content: ['./src/**/*.{ts,tsx}', './node_modules/@digitalcanopy/notifications/dist/**/*.{js,mjs}']
+```

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@digitalcanopy/notifications",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Universal notification triage state machine, AI digest contracts, and collapsible digest card shared across SunShade apps",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/react/index.ts --dts --format cjs,esm --minify",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:boundaries": "vitest run"
+  },
+  "dependencies": {
+    "@radix-ui/react-collapsible": "^1.1.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 || >=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "react": "^19.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "keywords": [
+    "sunshade",
+    "notifications",
+    "triage",
+    "digest",
+    "react"
+  ],
+  "author": "SunShade Systems",
+  "license": "MIT"
+}

package/src/__tests__/react.test.tsx

@@ -0,0 +1,79 @@
+import { act, fireEvent, render, renderHook, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { NotificationDigestCard, useNotificationDigest } from '../react';
+import { buildDigestRollup } from '../triage';
+import type { ActionableNotification } from '../types';
+
+const n = (over: Partial<ActionableNotification>): ActionableNotification => ({
+  id: 'a',
+  tier: 'info',
+  title: 'Hello',
+  source: 'tracker',
+  createdAt: '2026-11-01T00:00:00Z',
+  read: false,
+  ...over,
+});
+
+beforeEach(() => window.localStorage.clear());
+
+describe('useNotificationDigest', () => {
+  it('clears isSummarizing when unread items are cleared mid-flight', async () => {
+    const summarizer = () => new Promise<string>(() => {});
+    const { result } = renderHook(() =>
+      useNotificationDigest({ initial: [n({ id: '1' })], summarizer })
+    );
+    await waitFor(() => expect(result.current.isSummarizing).toBe(true));
+    act(() => result.current.markAllRead());
+    await waitFor(() => expect(result.current.isSummarizing).toBe(false));
+  });
+
+  it('drops a stale summary when notification content changes', async () => {
+    const summarizer = async (items: readonly ActionableNotification[]) => items[0].title;
+    const { result } = renderHook(() =>
+      useNotificationDigest({ initial: [n({ id: '1', title: 'arriving' })], summarizer })
+    );
+    await waitFor(() => expect(result.current.digest.summary).toBe('arriving'));
+    act(() => result.current.ingest([n({ id: '1', title: 'canceled' })]));
+    expect(result.current.digest.summary).not.toBe('arriving');
+    await waitFor(() => expect(result.current.digest.summary).toBe('canceled'));
+  });
+
+  it('manages state through actions', () => {
+    const { result } = renderHook(() => useNotificationDigest({ initial: [n({ id: '1' })] }));
+    expect(result.current.digest.unread).toBe(1);
+    act(() => result.current.ingest([n({ id: '2', tier: 'critical' })]));
+    expect(result.current.digest.topTier).toBe('critical');
+    act(() => result.current.markAllRead());
+    expect(result.current.digest.unread).toBe(0);
+  });
+});
+
+describe('NotificationDigestCard', () => {
+  it('does not render unsafe action links', () => {
+    const digest = buildDigestRollup([
+      n({ id: '1', title: 'Bad', actionUrl: 'javascript:alert(1)', actionLabel: 'BadLink' }),
+      n({ id: '2', title: 'Good', actionUrl: 'https://example.com', actionLabel: 'GoodLink' }),
+    ]);
+    render(<NotificationDigestCard digest={digest} defaultOpen storageKey={null} />);
+    expect(screen.queryByText('BadLink')).toBeNull();
+    expect(screen.getByText('GoodLink')).toBeTruthy();
+  });
+
+  it('shows badge, tier accent, and persists open state', () => {
+    const digest = buildDigestRollup([n({ id: '1', tier: 'critical', title: 'Blocked' })]);
+    const { unmount } = render(<NotificationDigestCard digest={digest} />);
+    expect(screen.getByTestId('unread-badge').textContent).toBe('1');
+    expect(screen.getByTestId('notification-digest-card').className).toContain('border-l-rose-500');
+    expect(screen.queryByText('Blocked')).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: /Notifications/ }));
+    expect(screen.getByText('Blocked')).toBeTruthy();
+    unmount();
+    render(<NotificationDigestCard digest={digest} />);
+    expect(screen.getByText('Blocked')).toBeTruthy();
+  });
+
+  it('renders empty state when open with no items', () => {
+    render(<NotificationDigestCard digest={buildDigestRollup([])} defaultOpen storageKey={null} />);
+    expect(screen.getByText(/all caught up/)).toBeTruthy();
+  });
+});

package/src/__tests__/triage.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { buildDigestRollup, createTriageState, triageReducer } from '../triage';
+import { isSafeActionUrl } from '../url';
+import type { ActionableNotification } from '../types';
+
+const n = (over: Partial<ActionableNotification>): ActionableNotification => ({
+  id: 'a',
+  tier: 'info',
+  title: 't',
+  source: 'tracker',
+  createdAt: '2026-11-01T00:00:00Z',
+  read: false,
+  ...over,
+});
+
+describe('triage', () => {
+  it('rolls up unread counts and top tier', () => {
+    const r = buildDigestRollup([
+      n({ id: '1', tier: 'info' }),
+      n({ id: '2', tier: 'critical', read: true }),
+      n({ id: '3', tier: 'attention' }),
+    ]);
+    expect(r.total).toBe(3);
+    expect(r.unread).toBe(2);
+    expect(r.topTier).toBe('attention');
+    expect(r.items[0].id).toBe('2');
+  });
+
+  it('returns null topTier when empty', () => {
+    expect(buildDigestRollup([]).topTier).toBeNull();
+  });
+
+  it('ingests without resurrecting read items, and dedupes', () => {
+    let s = createTriageState([n({ id: '1', read: true })]);
+    s = triageReducer(s, { type: 'ingest', notifications: [n({ id: '1' }), n({ id: '2' })] });
+    expect(s.items).toHaveLength(2);
+    expect(s.items.find((i) => i.id === '1')?.read).toBe(true);
+  });
+
+  it('marks read, marks all read, dismisses', () => {
+    let s = createTriageState([n({ id: '1' }), n({ id: '2' })]);
+    s = triageReducer(s, { type: 'markRead', key: 'tracker:1' });
+    expect(buildDigestRollup(s.items).unread).toBe(1);
+    s = triageReducer(s, { type: 'markAllRead' });
+    expect(buildDigestRollup(s.items).unread).toBe(0);
+    s = triageReducer(s, { type: 'dismiss', key: 'tracker:2' });
+    expect(s.items).toHaveLength(1);
+  });
+
+  it('keeps same-id notifications from different sources distinct', () => {
+    let s = createTriageState([n({ id: '1', source: 'tracker' }), n({ id: '1', source: 'cozy' })]);
+    expect(s.items).toHaveLength(2);
+    s = triageReducer(s, { type: 'markRead', key: 'cozy:1' });
+    expect(s.items.find((i) => i.source === 'tracker')?.read).toBe(false);
+    expect(s.items.find((i) => i.source === 'cozy')?.read).toBe(true);
+  });
+
+  it('does not resurrect dismissed notifications on re-ingest', () => {
+    let s = createTriageState([n({ id: '1' })]);
+    s = triageReducer(s, { type: 'dismiss', key: 'tracker:1' });
+    s = triageReducer(s, { type: 'ingest', notifications: [n({ id: '1' })] });
+    expect(s.items).toHaveLength(0);
+  });
+});
+
+describe('isSafeActionUrl', () => {
+  it('allows safe URLs and rejects script schemes', () => {
+    for (const u of ['https://a.com', 'http://a.com', 'mailto:a@b.c', '/path', '#x', './x', 'foo/bar']) {
+      expect(isSafeActionUrl(u)).toBe(true);
+    }
+    for (const u of ['javascript:alert(1)', ' JaVaScRiPt:alert(1)', 'java\nscript:alert(1)', 'data:text/html,x', '//evil.com', '', undefined]) {
+      expect(isSafeActionUrl(u as string | undefined)).toBe(false);
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export {
+  buildDigestRollup,
+  compareNotifications,
+  createTriageState,
+  notificationKey,
+  sortNotifications,
+  tierRank,
+  triageReducer,
+} from './triage';
+export { isSafeActionUrl } from './url';

package/src/react/NotificationDigestCard.tsx

@@ -0,0 +1,154 @@
+import * as Collapsible from '@radix-ui/react-collapsible';
+import { useCallback, useState, type ReactNode } from 'react';
+import { notificationKey } from '../triage';
+import type { ActionableNotification, DigestRollup, UrgencyTier } from '../types';
+import { isSafeActionUrl } from '../url';
+
+export const TIER_STYLES: Record<UrgencyTier, { rail: string; glyph: string; label: string }> = {
+  critical: { rail: 'border-l-4 border-l-rose-500', glyph: '!', label: 'Critical' },
+  attention: { rail: 'border-l-4 border-l-amber-400', glyph: '•', label: 'Needs attention' },
+  info: { rail: 'border-l-4 border-l-sky-500', glyph: 'i', label: 'Info' },
+};
+
+const DEFAULT_STORAGE_KEY = 'sunshade:notification-digest:open';
+
+function readStoredOpen(key: string | null, fallback: boolean): boolean {
+  if (!key || typeof window === 'undefined') return fallback;
+  try {
+    const v = window.localStorage.getItem(key);
+    return v === null ? fallback : v === '1';
+  } catch {
+    return fallback;
+  }
+}
+
+function writeStoredOpen(key: string | null, open: boolean): void {
+  if (!key || typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(key, open ? '1' : '0');
+  } catch {
+    /* storage unavailable; state stays in-memory */
+  }
+}
+
+export interface NotificationDigestCardProps {
+  digest: DigestRollup;
+  title?: string;
+  defaultOpen?: boolean;
+  /** localStorage key for persisted open state. Pass null to disable persistence. */
+  storageKey?: string | null;
+  className?: string;
+  /** Receives the composite source:id key. */
+  onMarkRead?: (key: string) => void;
+  onMarkAllRead?: () => void;
+  onDismiss?: (key: string) => void;
+  /** Override rendering of a single row. */
+  renderItem?: (item: ActionableNotification) => ReactNode;
+  emptyState?: ReactNode;
+}
+
+export function NotificationDigestCard({
+  digest,
+  title = 'Notifications',
+  defaultOpen = false,
+  storageKey = DEFAULT_STORAGE_KEY,
+  className = '',
+  onMarkRead,
+  onMarkAllRead,
+  onDismiss,
+  renderItem,
+  emptyState = <p className="px-4 py-3 text-sm text-slate-500">You're all caught up.</p>,
+}: NotificationDigestCardProps) {
+  const [open, setOpen] = useState(() => readStoredOpen(storageKey, defaultOpen));
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      setOpen(next);
+      writeStoredOpen(storageKey, next);
+    },
+    [storageKey]
+  );
+
+  const tier = digest.topTier ?? 'info';
+  const style = TIER_STYLES[tier];
+
+  return (
+    <Collapsible.Root
+      open={open}
+      onOpenChange={handleOpenChange}
+      data-testid="notification-digest-card"
+      data-tier={tier}
+      className={`rounded-md border border-slate-200 bg-white ${style.rail} ${className}`.trim()}
+    >
+      <div className="flex items-center justify-between gap-2 px-4 py-3">
+        <Collapsible.Trigger asChild>
+          <button type="button" className="flex flex-1 items-center gap-2 text-left font-medium">
+            <span aria-hidden="true">{style.glyph}</span>
+            <span>{title}</span>
+            {digest.unread > 0 && (
+              <span
+                data-testid="unread-badge"
+                aria-label={`${digest.unread} unread`}
+                className="animate-pulse rounded-full bg-rose-500 px-2 py-0.5 text-xs text-white"
+              >
+                {digest.unread}
+              </span>
+            )}
+          </button>
+        </Collapsible.Trigger>
+        {digest.unread > 0 && onMarkAllRead && (
+          <button type="button" className="text-xs text-slate-500 underline" onClick={onMarkAllRead}>
+            Mark all read
+          </button>
+        )}
+      </div>
+      {digest.summary && <p className="px-4 pb-2 text-sm text-slate-600">{digest.summary}</p>}
+      <Collapsible.Content>
+        {digest.items.length === 0 ? (
+          emptyState
+        ) : (
+          <ul className="divide-y divide-slate-100">
+            {digest.items.map((item) =>
+              renderItem ? (
+                <li key={notificationKey(item)}>{renderItem(item)}</li>
+              ) : (
+                <li
+                  key={notificationKey(item)}
+                  data-tier={item.tier}
+                  className={`${TIER_STYLES[item.tier].rail} flex items-start gap-2 px-4 py-2 ${
+                    item.read ? 'opacity-60' : ''
+                  }`}
+                >
+                  <span aria-hidden="true">{TIER_STYLES[item.tier].glyph}</span>
+                  <div className="flex-1">
+                    <p className="text-sm font-medium">{item.title}</p>
+                    {item.body && <p className="text-xs text-slate-600">{item.body}</p>}
+                    {isSafeActionUrl(item.actionUrl) && (
+                      <a href={item.actionUrl} className="text-xs text-sky-600 underline">
+                        {item.actionLabel ?? 'Open'}
+                      </a>
+                    )}
+                  </div>
+                  {!item.read && onMarkRead && (
+                    <button type="button" className="text-xs" onClick={() => onMarkRead(notificationKey(item))}>
+                      Mark read
+                    </button>
+                  )}
+                  {onDismiss && (
+                    <button
+                      type="button"
+                      aria-label={`Dismiss ${item.title}`}
+                      className="text-xs"
+                      onClick={() => onDismiss(notificationKey(item))}
+                    >
+                      ✕
+                    </button>
+                  )}
+                </li>
+              )
+            )}
+          </ul>
+        )}
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,7 @@
+export { useNotificationDigest } from './useNotificationDigest';
+export type {
+  UseNotificationDigestOptions,
+  UseNotificationDigestResult,
+} from './useNotificationDigest';
+export { NotificationDigestCard, TIER_STYLES } from './NotificationDigestCard';
+export type { NotificationDigestCardProps } from './NotificationDigestCard';

package/src/react/useNotificationDigest.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { buildDigestRollup, createTriageState, triageReducer } from '../triage';
+import type { ActionableNotification, DigestRollup, DigestSummarizer } from '../types';
+
+export interface UseNotificationDigestOptions {
+  initial?: ActionableNotification[];
+  /** Optional AI summarizer; only invoked when there are unread items. */
+  summarizer?: DigestSummarizer;
+}
+
+export interface UseNotificationDigestResult {
+  digest: DigestRollup;
+  ingest: (notifications: ActionableNotification[]) => void;
+  /** `key` is the composite `source:id` from `notificationKey()`. */
+  markRead: (key: string) => void;
+  markAllRead: () => void;
+  dismiss: (key: string) => void;
+  reset: (notifications?: ActionableNotification[]) => void;
+  isSummarizing: boolean;
+  summaryError: Error | null;
+}
+
+export function useNotificationDigest(
+  options: UseNotificationDigestOptions = {}
+): UseNotificationDigestResult {
+  const { initial, summarizer } = options;
+  const [state, dispatch] = useReducer(triageReducer, initial, (i) => createTriageState(i));
+  const [summary, setSummary] = useState<string | undefined>();
+  const [isSummarizing, setIsSummarizing] = useState(false);
+  const [summaryError, setSummaryError] = useState<Error | null>(null);
+  const summarizerRef = useRef(summarizer);
+  summarizerRef.current = summarizer;
+
+  const unreadItems = useMemo(() => state.items.filter((i) => !i.read), [state.items]);
+  // Content-sensitive key: re-summarize when an unread item's content changes, not just its id.
+  const unreadKey = JSON.stringify(
+    unreadItems
+      .map((i) => [i.source, i.id, i.tier, i.title, i.body ?? ''])
+      .sort((a, b) => (a.join('\u0000') < b.join('\u0000') ? -1 : 1))
+  );
+
+  useEffect(() => {
+    // Drop any previous summary immediately so it never describes stale content.
+    setSummary(undefined);
+    const run = summarizerRef.current;
+    if (!run || unreadItems.length === 0) {
+      setIsSummarizing(false);
+      setSummaryError(null);
+      return;
+    }
+    const controller = new AbortController();
+    setIsSummarizing(true);
+    setSummaryError(null);
+    run(unreadItems, controller.signal)
+      .then((text) => {
+        if (!controller.signal.aborted) setSummary(text);
+      })
+      .catch((err: unknown) => {
+        if (!controller.signal.aborted) {
+          setSummaryError(err instanceof Error ? err : new Error(String(err)));
+        }
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setIsSummarizing(false);
+      });
+    return () => controller.abort();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [unreadKey]);
+
+  const digest = useMemo(() => buildDigestRollup(state.items, summary), [state.items, summary]);
+
+  return {
+    digest,
+    ingest: useCallback((notifications) => dispatch({ type: 'ingest', notifications }), []),
+    markRead: useCallback((key) => dispatch({ type: 'markRead', key }), []),
+    markAllRead: useCallback(() => dispatch({ type: 'markAllRead' }), []),
+    dismiss: useCallback((key) => dispatch({ type: 'dismiss', key }), []),
+    reset: useCallback((notifications) => dispatch({ type: 'reset', notifications }), []),
+    isSummarizing,
+    summaryError,
+  };
+}

package/src/triage.ts

@@ -0,0 +1,94 @@
+import {
+  URGENCY_TIERS,
+  type ActionableNotification,
+  type DigestRollup,
+  type TriageAction,
+  type TriageState,
+  type UrgencyTier,
+} from './types';
+
+/** Notifications are unique per (source, id), not by id alone. */
+export function notificationKey(n: Pick<ActionableNotification, 'source' | 'id'>): string {
+  return `${n.source}:${n.id}`;
+}
+
+export function tierRank(tier: UrgencyTier): number {
+  return URGENCY_TIERS.indexOf(tier);
+}
+
+export function compareNotifications(a: ActionableNotification, b: ActionableNotification): number {
+  return (
+    tierRank(a.tier) - tierRank(b.tier) ||
+    Number(a.read) - Number(b.read) ||
+    Date.parse(b.createdAt) - Date.parse(a.createdAt)
+  );
+}
+
+export function sortNotifications(items: readonly ActionableNotification[]): ActionableNotification[] {
+  return [...items].sort(compareNotifications);
+}
+
+export function buildDigestRollup(
+  items: readonly ActionableNotification[],
+  summary?: string
+): DigestRollup {
+  const unreadByTier: Record<UrgencyTier, number> = { critical: 0, attention: 0, info: 0 };
+  for (const item of items) {
+    if (!item.read) unreadByTier[item.tier] += 1;
+  }
+  const unread = unreadByTier.critical + unreadByTier.attention + unreadByTier.info;
+  const topTier = URGENCY_TIERS.find((t) => unreadByTier[t] > 0) ?? null;
+  return {
+    total: items.length,
+    unread,
+    unreadByTier,
+    topTier,
+    items: sortNotifications(items),
+    ...(summary !== undefined ? { summary } : {}),
+  };
+}
+
+export function createTriageState(items: ActionableNotification[] = []): TriageState {
+  return { items: dedupe(items), dismissed: [] };
+}
+
+function dedupe(items: readonly ActionableNotification[]): ActionableNotification[] {
+  const map = new Map<string, ActionableNotification>();
+  for (const item of items) map.set(notificationKey(item), item);
+  return [...map.values()];
+}
+
+export function triageReducer(state: TriageState, action: TriageAction): TriageState {
+  switch (action.type) {
+    case 'ingest': {
+      const dismissed = new Set(state.dismissed);
+      const existing = new Map(state.items.map((i) => [notificationKey(i), i]));
+      for (const incoming of action.notifications) {
+        const key = notificationKey(incoming);
+        if (dismissed.has(key)) continue;
+        const prev = existing.get(key);
+        // Never resurrect an already-read item as unread on re-ingest.
+        existing.set(key, prev?.read ? { ...incoming, read: true } : incoming);
+      }
+      return { ...state, items: [...existing.values()] };
+    }
+    case 'markRead':
+      return {
+        ...state,
+        items: state.items.map((i) => (notificationKey(i) === action.key ? { ...i, read: true } : i)),
+      };
+    case 'markAllRead':
+      return { ...state, items: state.items.map((i) => (i.read ? i : { ...i, read: true })) };
+    case 'dismiss':
+      return {
+        items: state.items.filter((i) => notificationKey(i) !== action.key),
+        dismissed: state.dismissed.includes(action.key)
+          ? state.dismissed
+          : [...state.dismissed, action.key],
+      };
+    case 'reset':
+      return createTriageState(action.notifications ?? []);
+    default:
+      return state;
+  }
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+/** Urgency tiers, ordered from most to least urgent. */
+export type UrgencyTier = 'critical' | 'attention' | 'info';
+
+export const URGENCY_TIERS: readonly UrgencyTier[] = ['critical', 'attention', 'info'];
+
+export interface ActionableNotification {
+  id: string;
+  tier: UrgencyTier;
+  title: string;
+  body?: string;
+  /** Originating app/feature, e.g. "tracker", "cozy", "hub". */
+  source: string;
+  /** ISO-8601 timestamp. */
+  createdAt: string;
+  read: boolean;
+  actionUrl?: string;
+  actionLabel?: string;
+  /** Optional grouping key (e.g. peer care drops from the same sender). */
+  groupKey?: string;
+}
+
+export interface DigestRollup {
+  total: number;
+  unread: number;
+  unreadByTier: Record<UrgencyTier, number>;
+  /** Highest tier among unread items, or null when everything is read. */
+  topTier: UrgencyTier | null;
+  /** Items sorted by tier, then unread first, then newest first. */
+  items: ActionableNotification[];
+  /** Optional AI-generated summary of the digest. */
+  summary?: string;
+}
+
+/** AI summarization contract: implemented by consuming apps. */
+export type DigestSummarizer = (
+  items: readonly ActionableNotification[],
+  signal?: AbortSignal
+) => Promise<string>;
+
+export interface TriageState {
+  items: ActionableNotification[];
+  /** Keys (see `notificationKey`) of dismissed items; re-ingesting them is a no-op. */
+  dismissed: string[];
+}
+
+/**
+ * Actions address notifications by composite key (`source:id`), since IDs are
+ * only unique within a source. Use `notificationKey()` to build one.
+ */
+export type TriageAction =
+  | { type: 'ingest'; notifications: ActionableNotification[] }
+  | { type: 'markRead'; key: string }
+  | { type: 'markAllRead' }
+  | { type: 'dismiss'; key: string }
+  | { type: 'reset'; notifications?: ActionableNotification[] };

package/src/url.ts

@@ -0,0 +1,19 @@
+const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:']);
+
+/**
+ * Returns true only for http(s)/mailto URLs and same-origin relative paths.
+ * Rejects `javascript:`, `data:` and other script-capable schemes.
+ */
+export function isSafeActionUrl(url: string | undefined): url is string {
+  if (!url) return false;
+  // Strip control chars/whitespace browsers ignore inside schemes (e.g. "java\nscript:").
+  const trimmed = url.replace(/[\u0000-\u0020\u007f-\u009f]/g, '');
+  if (trimmed.startsWith('//')) return false;
+  if (/^[/#?.]/.test(trimmed)) return true;
+  try {
+    return SAFE_PROTOCOLS.has(new URL(trimmed).protocol);
+  } catch {
+    // No scheme: treat as a relative path only if it has no colon before a slash.
+    return !/^[^/?#]*:/.test(trimmed);
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "lib": ["esnext", "dom"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    css: false,
+  },
+});