@12-apps/notifications 1.0.0

package/src/react/preferences-screen.tsx

@@ -0,0 +1,242 @@
+/**
+ * The notification-preferences screen: the category × channel matrix over
+ * `GET/PUT <mount>/notification-preferences`.
+ *
+ * Toggles auto-save (optimistic, per change); channels that cannot reach the
+ * user right now (no phone on file / channel not declared) render disabled with
+ * a hint. Web Push additionally carries the per-BROWSER enable step, since a
+ * preference alone cannot reach a device that never subscribed.
+ */
+import { useCallback, useEffect, useState, type JSX } from 'react';
+
+import { LoadingState } from '@12-apps/ui/data-display/LoadingState';
+import { Switch } from '@12-apps/ui/form/Switch';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { NotificationMessages } from '../messages';
+import { NOTIFICATION_CHANNELS, type NotificationChannel } from '../types';
+
+import type { NotificationsApiClient, PreferencesPayload } from './api';
+import { WebPushDeviceSetup, type WebPushSetupConfig } from './web-push-setup';
+
+type Availability = Record<NotificationChannel, boolean>;
+
+/** One category's row of channel switches. */
+function CategoryCard({
+  category,
+  channels,
+  availability,
+  messages,
+  onToggle,
+}: {
+  category: string;
+  channels: Record<NotificationChannel, boolean>;
+  availability: Availability;
+  messages: NotificationMessages;
+  onToggle: (channel: NotificationChannel, enabled: boolean) => void;
+}): JSX.Element {
+  const labels = messages.categoryLabels[category];
+  return (
+    <Box
+      sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 2 }}
+      data-testid={`prefs-${category}`}
+    >
+      <Text variant="body" size="sm" weight="semibold" as="p">
+        {labels?.title ?? messages.categoryFallbackTitle(category)}
+      </Text>
+      {labels?.description ? (
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          {labels.description}
+        </Text>
+      ) : null}
+      <Box
+        sx={{
+          mt: 1.5,
+          display: 'grid',
+          gridTemplateColumns: { xs: '1fr 1fr', sm: 'repeat(4, 1fr)' },
+          gap: 1,
+        }}
+      >
+        {NOTIFICATION_CHANNELS.map((channel) => (
+          <Switch
+            key={channel}
+            size="sm"
+            color="primary"
+            label={messages.channelLabels[channel] ?? channel}
+            // An unavailable channel reads OFF regardless of the stored choice:
+            // a toggle that says "on" for a channel that cannot reach you is a
+            // promise the pipeline will not keep.
+            checked={channels[channel] && availability[channel]}
+            disabled={!availability[channel]}
+            onChange={(_, checked) => onToggle(channel, checked)}
+            // `dataTestId`, not `data-testid`: the UI Switch puts this one on
+            // the INPUT (and derives `-container` / `-label` from it), which is
+            // the element a click and a `disabled` assertion need.
+            dataTestId={`prefs-${category}-${channel}`}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+/** Why disabled toggles are disabled, one line per unavailable channel. */
+function UnavailableHints({
+  availability,
+  messages,
+}: {
+  availability: Availability;
+  messages: NotificationMessages;
+}): JSX.Element | null {
+  const unavailable = NOTIFICATION_CHANNELS.filter((channel) => !availability[channel]);
+  if (unavailable.length === 0) return null;
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.5 }}>
+      {unavailable.map((channel) => (
+        <Text
+          key={channel}
+          variant="caption"
+          size="xs"
+          color="secondary"
+          as="p"
+          data-testid={`prefs-hint-${channel}`}
+        >
+          {messages.channelLabels[channel] ?? channel}:{' '}
+          {messages.channelUnavailableHints[channel] ?? ''}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+export interface PreferencesScreenProps {
+  /** Rendered under the lead paragraph — a "back to account" link, typically. */
+  footer?: JSX.Element;
+}
+
+/** Optimistic per-toggle auto-save; a failed PUT takes the server's answer. */
+function usePreferences(api: NotificationsApiClient): {
+  payload: PreferencesPayload | null;
+  toggle: (category: string, channel: NotificationChannel, enabled: boolean) => void;
+} {
+  const [payload, setPayload] = useState<PreferencesPayload | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void api
+      .getPreferences()
+      .then((next) => {
+        if (!cancelled) setPayload(next);
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [api]);
+
+  const toggle = useCallback(
+    (category: string, channel: NotificationChannel, enabled: boolean) => {
+      setPayload((current) => {
+        const row = current?.preferences[category];
+        if (!current || !row) return current;
+        return {
+          ...current,
+          preferences: { ...current.preferences, [category]: { ...row, [channel]: enabled } },
+        };
+      });
+      const reconcile = (): void => {
+        void api.getPreferences().then(setPayload).catch(() => undefined);
+      };
+      void api
+        .savePreference(category, channel, enabled)
+        .then((result) => {
+          // The PUT answers with the whole matrix, so a success REPLACES the
+          // optimistic guess with the server's own row — which is what catches a
+          // save the server merged differently from the way the screen assumed.
+          if (result.ok) setPayload(result.data);
+          else reconcile();
+        })
+        // The packaged transport never rejects (it folds a failure into
+        // `ok: false`), but a HOST transport may — and an unhandled rejection
+        // would leave the toggle showing a choice the server never took.
+        .catch(reconcile);
+    },
+    [api],
+  );
+
+  return { payload, toggle };
+}
+
+export function PreferencesScreen({
+  footer,
+  api,
+  messages,
+  webPush,
+}: PreferencesScreenProps & {
+  api: NotificationsApiClient;
+  messages: NotificationMessages;
+  webPush: WebPushSetupConfig;
+}): JSX.Element {
+  const { payload, toggle } = usePreferences(api);
+
+  if (!payload) {
+    return (
+      <LoadingState
+        variant="spinner"
+        message={messages.loadingMore}
+        size="md"
+        dataTestId="notification-prefs-loading"
+      />
+    );
+  }
+
+  const { preferences, availability, categories } = payload;
+  return (
+    <Box
+      component="section"
+      data-testid="notification-prefs-view"
+      sx={{
+        maxWidth: 640,
+        mx: 'auto',
+        width: '100%',
+        px: 2,
+        py: 4,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 2,
+      }}
+    >
+      <Box>
+        <Text variant="heading" size="lg" as="h1">
+          {messages.preferencesTitle}
+        </Text>
+        <Text variant="caption" size="sm" color="secondary" as="p">
+          {messages.preferencesLead} {footer}
+        </Text>
+      </Box>
+      <WebPushDeviceSetup
+        available={availability.WEB_PUSH}
+        api={api}
+        messages={messages}
+        config={webPush}
+      />
+      {categories.map((category) => (
+        <CategoryCard
+          key={category}
+          category={category}
+          channels={preferences[category] ?? {
+            EMAIL: false,
+            SMS: false,
+            WHATSAPP: false,
+            WEB_PUSH: false,
+          }}
+          availability={availability}
+          messages={messages}
+          onToggle={(channel, enabled) => toggle(category, channel, enabled)}
+        />
+      ))}
+      <UnavailableHints availability={availability} messages={messages} />
+    </Box>
+  );
+}

package/src/react/relative-time.ts

@@ -0,0 +1,18 @@
+import type { NotificationMessages } from '../messages';
+
+/**
+ * "há 5 min"-style relative timestamp, falling back to an absolute date for
+ * anything older than a week. Every word comes from the messages table, so a
+ * host in another locale changes the copy and the locale together.
+ */
+export function relativeTime(iso: string, messages: NotificationMessages): string {
+  const elapsedMs = Date.now() - new Date(iso).getTime();
+  const minutes = Math.round(elapsedMs / 60_000);
+  if (minutes < 1) return messages.justNow;
+  if (minutes < 60) return messages.minutesAgo(minutes);
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return messages.hoursAgo(hours);
+  const days = Math.round(hours / 24);
+  if (days < 7) return messages.daysAgo(days);
+  return new Date(iso).toLocaleDateString(messages.dateLocale);
+}

package/src/react/row.tsx

@@ -0,0 +1,98 @@
+/** One inbox row: unread accent, content (opens/marks read), timestamp, delete. */
+import type { JSX } from 'react';
+
+import { Button } from '@12-apps/ui/form/Button';
+import { Box } from '@12-apps/ui/mui/Box';
+import { alpha, type Theme } from '@12-apps/ui/mui/styles';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { NotificationMessages } from '../messages';
+import type { InboxNotification } from '../wire';
+
+import { relativeTime } from './relative-time';
+
+const contentButtonSx = {
+  flex: 1,
+  minWidth: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 0.25,
+  textAlign: 'left',
+  border: 'none',
+  background: 'none',
+  p: 0,
+  cursor: 'pointer',
+  color: 'text.primary',
+  fontFamily: 'inherit',
+} as const;
+
+const unreadDotSx = {
+  width: 8,
+  height: 8,
+  borderRadius: '50%',
+  bgcolor: 'primary.main',
+  flex: '0 0 auto',
+} as const;
+
+export function NotificationRow({
+  notification,
+  messages,
+  onOpen,
+  onDelete,
+}: {
+  notification: InboxNotification;
+  messages: NotificationMessages;
+  onOpen: (notification: InboxNotification) => void;
+  onDelete: (id: string) => void;
+}): JSX.Element {
+  const unread = notification.readAt === null;
+  return (
+    <Box
+      data-testid={`notification-${notification.id}`}
+      sx={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: 1,
+        py: 1.5,
+        px: 1,
+        borderBottom: '1px solid',
+        borderColor: 'divider',
+        bgcolor: unread ? (t: Theme) => alpha(t.palette.primary.main, 0.06) : 'transparent',
+      }}
+    >
+      <Box
+        component="button"
+        type="button"
+        onClick={() => onOpen(notification)}
+        aria-label={
+          unread ? `${notification.title} (${messages.unreadSuffix})` : notification.title
+        }
+        sx={contentButtonSx}
+      >
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+          {unread ? <Box aria-hidden sx={unreadDotSx} /> : null}
+          <Text variant="body" size="sm" weight={unread ? 'bold' : 'medium'} as="span">
+            {notification.title}
+          </Text>
+        </Box>
+        <Text variant="caption" size="xs" color="secondary" as="span">
+          {notification.body}
+        </Text>
+        <Text variant="caption" size="xs" color="secondary" as="span" italic>
+          {relativeTime(notification.createdAt, messages)}
+        </Text>
+      </Box>
+
+      <Button
+        variant="ghost"
+        color="neutral"
+        size="xs"
+        aria-label={messages.deleteOne(notification.title)}
+        onClick={() => onDelete(notification.id)}
+        dataTestId={`notification-delete-${notification.id}`}
+      >
+        ✕
+      </Button>
+    </Box>
+  );
+}

package/src/react/transport.ts

@@ -0,0 +1,72 @@
+/**
+ * How the notification screens reach their data (12-15) — the report-builder
+ * transport doctrine: this is the ONLY way the surface performs I/O, so a
+ * caller supplying one has substituted the entire backend without stubbing a
+ * global. The default is same-origin `fetch` riding the browser's cookies.
+ */
+
+/** A write outcome the screens branch on — never a thrown mutation. */
+export type NotificationsResult<T> = { ok: true; data: T } | { ok: false; error: string };
+
+/** A failed read, carrying the status the screens branch on (401 = signed out). */
+export class NotificationsHttpError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'NotificationsHttpError';
+    this.status = status;
+    Object.setPrototypeOf(this, NotificationsHttpError.prototype);
+  }
+}
+
+export interface NotificationsTransport {
+  /** A read. Returns the payload INSIDE the `{ data }` envelope. */
+  get<T>(path: string): Promise<T>;
+  /** A write. Returns a {@link NotificationsResult} rather than rejecting. */
+  send<T>(path: string, method: string, body?: unknown): Promise<NotificationsResult<T>>;
+}
+
+const FALLBACK_ERROR = 'Não foi possível concluir a operação.';
+
+export function httpNotificationsTransport(fallbackError = FALLBACK_ERROR): NotificationsTransport {
+  return {
+    async get<T>(path: string): Promise<T> {
+      const response = await fetch(path, {
+        credentials: 'same-origin',
+        headers: { Accept: 'application/json' },
+      });
+      const payload = (await response.json().catch(() => null)) as
+        | { data?: T; error?: string }
+        | null;
+      if (!response.ok) {
+        throw new NotificationsHttpError(
+          response.status,
+          payload?.error ?? `HTTP ${response.status} for ${path}`,
+        );
+      }
+      return (payload?.data ?? payload) as T;
+    },
+
+    async send<T>(path: string, method: string, body?: unknown): Promise<NotificationsResult<T>> {
+      try {
+        const response = await fetch(path, {
+          method,
+          credentials: 'same-origin',
+          headers: {
+            Accept: 'application/json',
+            ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+          },
+          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (response.status === 204) return { ok: true, data: undefined as T };
+        const payload = (await response.json().catch(() => null)) as
+          | { data?: T; error?: string }
+          | null;
+        if (!response.ok) return { ok: false, error: payload?.error ?? fallbackError };
+        return { ok: true, data: (payload?.data ?? payload) as T };
+      } catch {
+        return { ok: false, error: fallbackError };
+      }
+    },
+  };
+}

package/src/react/web-push-client.ts

@@ -0,0 +1,113 @@
+import type { NotificationsApiClient } from './api';
+
+/**
+ * The browser half of Web Push: register the service worker, ask permission,
+ * subscribe with the deployment's VAPID public key (read from the packaged
+ * `GET <mount>/push-subscriptions`) and persist the subscription so the
+ * WEB_PUSH transport can reach this browser.
+ *
+ * A preference alone cannot reach a device that never subscribed, which is why
+ * this ships with the preferences screen rather than being left to the host.
+ * The one thing that IS the host's is the service-worker path — path-routed SPAs
+ * each control their own scope, and the file itself lives in the host's public
+ * directory.
+ */
+
+/** Why enabling push failed, mapped to a user-facing hint by the caller. */
+export type PushSetupResult =
+  | { ok: true }
+  | { ok: false; reason: 'unsupported' | 'unconfigured' | 'permission-denied' | 'error' };
+
+/** `PushManager.subscribe` needs the VAPID key as a Uint8Array. */
+function base64UrlToUint8Array(base64Url: string): Uint8Array {
+  const padding = '='.repeat((4 - (base64Url.length % 4)) % 4);
+  const base64 = (base64Url + padding).replaceAll('-', '+').replaceAll('_', '/');
+  const raw = atob(base64);
+  return Uint8Array.from(raw, (char) => char.charCodeAt(0));
+}
+
+export function pushSupported(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    'serviceWorker' in navigator &&
+    typeof window !== 'undefined' &&
+    'PushManager' in window &&
+    'Notification' in window
+  );
+}
+
+/** Whether this browser currently holds an active push subscription. */
+export async function getExistingPushSubscription(): Promise<PushSubscription | null> {
+  if (!pushSupported()) return null;
+  const registration = await navigator.serviceWorker.getRegistration();
+  if (!registration) return null;
+  return registration.pushManager.getSubscription();
+}
+
+/** Register the SW and return this browser's (possibly new) subscription. */
+async function obtainSubscription(
+  swPath: string,
+  vapidPublicKey: string,
+): Promise<PushSubscription> {
+  const registration = await navigator.serviceWorker.register(swPath);
+  await navigator.serviceWorker.ready;
+  return (
+    (await registration.pushManager.getSubscription()) ??
+    registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: base64UrlToUint8Array(vapidPublicKey) as BufferSource,
+    })
+  );
+}
+
+/**
+ * Full enable flow: configured? → permission → SW registration → subscribe →
+ * persist. Idempotent — an existing subscription is simply re-persisted (the
+ * server upserts on the endpoint).
+ */
+/** Persist the browser's subscription server-side (upsert on the endpoint). */
+async function persist(
+  api: NotificationsApiClient,
+  subscription: PushSubscription,
+): Promise<PushSetupResult> {
+  const json = subscription.toJSON();
+  if (!json.endpoint || !json.keys?.p256dh || !json.keys.auth) {
+    return { ok: false, reason: 'error' };
+  }
+  const saved = await api.savePushSubscription({
+    endpoint: json.endpoint,
+    keys: { p256dh: json.keys.p256dh, auth: json.keys.auth },
+  });
+  return saved.ok ? { ok: true } : { ok: false, reason: 'error' };
+}
+
+export async function enableWebPush(
+  api: NotificationsApiClient,
+  swPath = '/sw.js',
+): Promise<PushSetupResult> {
+  if (!pushSupported()) return { ok: false, reason: 'unsupported' };
+
+  const registration = await api.getPushRegistration().catch(() => null);
+  if (!registration?.vapidPublicKey) return { ok: false, reason: 'unconfigured' };
+
+  const permission = await Notification.requestPermission();
+  if (permission !== 'granted') return { ok: false, reason: 'permission-denied' };
+
+  try {
+    return await persist(
+      api,
+      await obtainSubscription(swPath, registration.vapidPublicKey),
+    );
+  } catch {
+    return { ok: false, reason: 'error' };
+  }
+}
+
+/** Disable flow: unsubscribe the browser and drop the server-side row. */
+export async function disableWebPush(api: NotificationsApiClient): Promise<void> {
+  const subscription = await getExistingPushSubscription();
+  if (!subscription) return;
+  const endpoint = subscription.endpoint;
+  await subscription.unsubscribe().catch(() => false);
+  await api.removePushSubscription(endpoint).catch(() => undefined);
+}