@12-apps/notifications 1.0.0

package/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * `@12-apps/notifications` — the channel-agnostic notification system: an
+ * always-on in-app inbox, per-user × per-category channel preferences, and
+ * pluggable email / SMS / WhatsApp / web-push transports behind vendor
+ * drivers (12-15).
+ *
+ * This ROOT entry is the framework-free, storage-free core: the types, the
+ * generator registry, the preference policy and the phone rules. It imports
+ * nothing that a browser cannot run and touches no database, which is what
+ * lets the react half share the vocabulary with the server half instead of
+ * restating it.
+ *
+ * The two halves each have ONE factory:
+ *
+ *     import { createApiNotifications } from '@12-apps/notifications/server';
+ *     import { createWebNotifications } from '@12-apps/notifications/react';
+ *
+ * plus `@12-apps/notifications/hono` to mount the backend on Hono and
+ * `@12-apps/notifications/web-push` for the VAPID sender (which is the only
+ * piece that needs the `web-push` package, hence its own subpath).
+ */
+
+export {
+  NOTIFICATION_CATEGORIES,
+  NOTIFICATION_CHANNELS,
+  taxonomyOf,
+  type DeliveryStatus,
+  type NotificationCategory,
+  type NotificationChannel,
+  type NotificationContent,
+  type NotificationEvent,
+  type NotificationGenerator,
+  type NotificationLogger,
+  type NotificationRecipient,
+  type NotificationTaxonomy,
+  type NotificationTransport,
+  type TransportRecipient,
+} from './types';
+
+export {
+  UnknownNotificationRecipientError,
+  UnknownNotificationTypeError,
+} from './errors';
+
+export {
+  createGeneratorRegistry,
+  type NotificationGeneratorRegistry,
+} from './generators';
+
+export {
+  DEFAULT_CHANNEL_ROW,
+  defaultChannelMatrix,
+  enabledChannelsOf,
+  mergeChoices,
+  mergeStoredRow,
+  type ChannelMatrix,
+  type ChannelRow,
+} from './preferences-core';
+
+export { normalizePhoneE164, type PhoneNormalizeOptions } from './phone';
+
+export {
+  DEFAULT_NOTIFICATION_MESSAGES,
+  messagesOf,
+  type NotificationMessages,
+} from './messages';
+
+export {
+  inboxWire,
+  type InboxNotification,
+  type ListNotificationsResult,
+  type NotificationRow,
+} from './wire';

package/src/messages.ts

@@ -0,0 +1,156 @@
+/**
+ * Every sentence this package can say to a USER, in one table.
+ *
+ * pt-BR by default because that is the product copy the surface shipped with
+ * (future-pay's storefront and backoffice are Brazilian); a host in another
+ * market passes `messages` and overrides the subset it cares about. The copy
+ * lives HERE rather than in each screen so the api half and the react half can
+ * never disagree about a sentence — the 401 body the wire returns and the
+ * error the panel renders come from the same key.
+ */
+export interface NotificationMessages {
+  // --- the wire ------------------------------------------------------------
+  unauthenticated: string;
+  invalidBody: string;
+  operationFailed: string;
+  /** `POST /notifications/mark-read` with neither `ids` nor `all`. */
+  markReadTargetRequired: string;
+
+  // --- the inbox panel -----------------------------------------------------
+  panelTitle: string;
+  markAllRead: string;
+  loading: string;
+  loadMore: string;
+  loadingMore: string;
+  loadFailedTitle: string;
+  loadFailedBody: string;
+  retry: string;
+  emptyTitle: string;
+  emptyBody: string;
+  openBell: string;
+  /** `(count) => 'Abrir notificações (3 não lidas)'`. */
+  openBellWithUnread: (count: number) => string;
+  unreadSuffix: string;
+  deleteOne: (title: string) => string;
+
+  // --- relative timestamps -------------------------------------------------
+  justNow: string;
+  minutesAgo: (minutes: number) => string;
+  hoursAgo: (hours: number) => string;
+  daysAgo: (days: number) => string;
+  /** Locale for the fallback absolute date on rows older than a week. */
+  dateLocale: string;
+
+  // --- the preferences screen ---------------------------------------------
+  preferencesTitle: string;
+  preferencesLead: string;
+  channelLabels: Record<string, string>;
+  channelUnavailableHints: Record<string, string>;
+  categoryLabels: Record<string, { title: string; description: string }>;
+  /** Fallback title for a category the host added but did not label. */
+  categoryFallbackTitle: (category: string) => string;
+  devicePushTitle: string;
+  devicePushIdle: string;
+  devicePushOn: string;
+  devicePushDenied: string;
+  devicePushFailed: string;
+  devicePushEnable: string;
+  devicePushEnabling: string;
+}
+
+/** future-pay's exact copy — the product default. */
+export const DEFAULT_NOTIFICATION_MESSAGES: NotificationMessages = {
+  unauthenticated: 'Não autenticado.',
+  invalidBody: 'Dados inválidos.',
+  operationFailed: 'Não foi possível concluir a operação.',
+  markReadTargetRequired: 'Informe `ids` ou `all: true` (exatamente um).',
+
+  panelTitle: 'Notificações',
+  markAllRead: 'Marcar todas como lidas',
+  loading: 'Carregando notificações...',
+  loadMore: 'Carregar mais',
+  loadingMore: 'Carregando...',
+  loadFailedTitle: 'Não foi possível carregar',
+  loadFailedBody: 'Tente novamente em instantes.',
+  retry: 'Tentar novamente',
+  emptyTitle: 'Nenhuma notificação',
+  emptyBody: 'Você está em dia — novidades aparecem aqui.',
+  openBell: 'Abrir notificações',
+  openBellWithUnread: (count) => `Abrir notificações (${count} não lidas)`,
+  unreadSuffix: 'não lida',
+  deleteOne: (title) => `Excluir notificação: ${title}`,
+
+  justNow: 'agora',
+  minutesAgo: (minutes) => `há ${minutes} min`,
+  hoursAgo: (hours) => `há ${hours} h`,
+  daysAgo: (days) => (days === 1 ? 'há 1 dia' : `há ${days} dias`),
+  dateLocale: 'pt-BR',
+
+  preferencesTitle: 'Notificações',
+  preferencesLead:
+    'Escolha como quer ser avisado, por tipo de assunto. O sino do app sempre recebe tudo.',
+  channelLabels: {
+    EMAIL: 'E-mail',
+    SMS: 'SMS',
+    WHATSAPP: 'WhatsApp',
+    WEB_PUSH: 'Navegador',
+  },
+  channelUnavailableHints: {
+    EMAIL: 'Envio de e-mail não está configurado neste ambiente.',
+    SMS: 'Cadastre um telefone no seu perfil para receber SMS.',
+    WHATSAPP: 'Cadastre um telefone no seu perfil para receber WhatsApp.',
+    WEB_PUSH: 'Alertas do navegador não estão configurados neste ambiente.',
+  },
+  categoryLabels: {
+    orders: {
+      title: 'Pedidos',
+      description: 'Confirmações e andamento dos seus pedidos.',
+    },
+    payments: {
+      title: 'Pagamentos',
+      description: 'Cobranças, comprovantes e falhas de pagamento.',
+    },
+    stock: {
+      title: 'Estoque',
+      description: 'Alertas de estoque das lojas que você administra.',
+    },
+    system: {
+      title: 'Sistema',
+      description: 'Avisos da sua conta e da plataforma.',
+    },
+  },
+  categoryFallbackTitle: (category) => category,
+  devicePushTitle: 'Alertas neste navegador',
+  devicePushIdle: 'Permita notificações para receber alertas mesmo com o site fechado.',
+  devicePushOn: 'Este navegador está recebendo alertas.',
+  devicePushDenied:
+    'Permissão negada — habilite notificações nas configurações do navegador.',
+  devicePushFailed: 'Não foi possível ativar. Tente novamente.',
+  devicePushEnable: 'Ativar',
+  devicePushEnabling: 'Ativando...',
+};
+
+/** The messages in force, defaulted to the pt-BR product copy. */
+export function messagesOf(config: {
+  messages?: Partial<NotificationMessages>;
+}): NotificationMessages {
+  const overrides = config.messages ?? {};
+  return {
+    ...DEFAULT_NOTIFICATION_MESSAGES,
+    ...overrides,
+    // Nested records merge per KEY. A host relabelling one channel must not
+    // erase the labels for the other three, which a shallow spread would do.
+    channelLabels: {
+      ...DEFAULT_NOTIFICATION_MESSAGES.channelLabels,
+      ...overrides.channelLabels,
+    },
+    channelUnavailableHints: {
+      ...DEFAULT_NOTIFICATION_MESSAGES.channelUnavailableHints,
+      ...overrides.channelUnavailableHints,
+    },
+    categoryLabels: {
+      ...DEFAULT_NOTIFICATION_MESSAGES.categoryLabels,
+      ...overrides.categoryLabels,
+    },
+  };
+}

package/src/phone.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared phone-destination rules for the SMS + WhatsApp transports.
+ *
+ * Providers need E.164 (`+5531999998888`); a host stores the phone as the user
+ * entered it. Best-effort normalization: an explicit `+` prefix is trusted; a
+ * bare 10/11-digit number is assumed to belong to `defaultCountryCode` and
+ * prefixed; anything else is unusable and makes the channel unavailable for
+ * that recipient.
+ *
+ * `defaultCountryCode` is REQUIRED, and that is the whole point of it being a
+ * parameter. It used to default to `55` (Brazil, the first host's market),
+ * which a published package must not do: a US adopter that never set it turned
+ * `4155552671` into `+554155552671` — a plausible Brazilian mobile — and sent a
+ * stranger the customer's order details. There is no country this package could
+ * assume that is not wrong for every other adopter, so it assumes none and the
+ * omission is a compile error rather than a wrong number. future-pay passes
+ * `'55'` explicitly.
+ *
+ * NOTE: "verified phone" is approximated by "has a normalizable phone on
+ * file" — a host with a real verification flow should tighten its contact
+ * directory to only return verified numbers, which is the single seam both
+ * transports funnel through.
+ */
+
+/** Options for {@link normalizePhoneE164}. */
+export interface PhoneNormalizeOptions {
+  /**
+   * Country calling code for a bare local number, digits only (`'55'`, `'1'`).
+   * Required: see the module docstring for why there is no default.
+   */
+  defaultCountryCode: string;
+}
+
+/** A local subscriber number: area code (2) + 8 or 9 digits. */
+const isLocal = (digits: string): boolean => digits.length === 10 || digits.length === 11;
+
+/** An already-international number. E.164 allows 8..15 digits. */
+const international = (digits: string): string | null =>
+  digits.length >= 8 && digits.length <= 15 ? `+${digits}` : null;
+
+/** Normalize a stored phone to E.164, or null when it can't be inferred. */
+export function normalizePhoneE164(
+  raw: string | null | undefined,
+  options: PhoneNormalizeOptions,
+): string | null {
+  if (!raw) return null;
+  const country = options.defaultCountryCode;
+  const trimmed = raw.trim();
+  const digits = trimmed.replace(/\D/g, '');
+  if (trimmed.startsWith('+')) return international(digits);
+  if (isLocal(digits)) return `+${country}${digits}`;
+  // A bare number that already carries the country code.
+  if (digits.startsWith(country) && isLocal(digits.slice(country.length))) {
+    return `+${digits}`;
+  }
+  return null;
+}

package/src/preferences-core.ts

@@ -0,0 +1,89 @@
+import {
+  NOTIFICATION_CHANNELS,
+  type NotificationCategory,
+  type NotificationChannel,
+} from './types';
+
+/**
+ * The preference POLICY, with no storage in it (12-15): which channels a
+ * category defaults to, how a stored JSON row is coerced onto the closed
+ * channel set, and how a partial save merges. `./server`'s store is the only
+ * thing that touches a database, so every rule here is unit-testable without
+ * one — and the react half can render the same defaults before the first read
+ * lands.
+ *
+ * Storage stores only EXPLICIT choices (one row per (user, category)); a
+ * missing row — or a missing channel key inside a row — falls back to
+ * {@link DEFAULT_CHANNEL_ROW}. Defaults: the free, low-friction channels
+ * (e-mail + web push) on; the paid per-message channels (SMS + WhatsApp) off
+ * until the user opts in. A host that disagrees passes `channelDefaults`.
+ */
+
+/** One category's channel toggles. */
+export type ChannelRow = Record<NotificationChannel, boolean>;
+
+/** A user's full category × channel matrix. */
+export type ChannelMatrix = Record<NotificationCategory, ChannelRow>;
+
+/** The policy applied when a user never touched a category's toggles. */
+export const DEFAULT_CHANNEL_ROW: ChannelRow = {
+  EMAIL: true,
+  SMS: false,
+  WHATSAPP: false,
+  WEB_PUSH: true,
+};
+
+/** The default matrix for one taxonomy (what the settings UI starts from). */
+export function defaultChannelMatrix(
+  categories: readonly NotificationCategory[],
+  channelDefaults: Partial<ChannelRow> = {},
+): ChannelMatrix {
+  const row = { ...DEFAULT_CHANNEL_ROW, ...channelDefaults };
+  return Object.fromEntries(
+    categories.map((category) => [category, { ...row }]),
+  ) as ChannelMatrix;
+}
+
+/**
+ * Coerce a stored JSON `channels` map onto the closed channel set, filling the
+ * gaps from `base`. A stored row that predates a channel keeps that channel's
+ * default rather than reading as "off", which is what lets a new transport ship
+ * without a data migration.
+ *
+ * The consequence, and the rule it implies: a channel ADDED later turns itself
+ * ON for a user who had explicitly switched every channel in that category off,
+ * because their stored row has no key for it. That is harmless for the four
+ * shipped channels — the two that cost money default off — so **a new channel
+ * must be added with a `false` default** unless the user's existing consent
+ * already covers it. The alternative (reading a missing key as "off") would need
+ * a data migration for every existing row on every channel that ever ships.
+ */
+export function mergeStoredRow(stored: unknown, base: ChannelRow): ChannelRow {
+  const row = { ...base };
+  if (stored && typeof stored === 'object') {
+    const record = stored as Record<string, unknown>;
+    for (const channel of NOTIFICATION_CHANNELS) {
+      const value = record[channel];
+      if (typeof value === 'boolean') row[channel] = value;
+    }
+  }
+  return row;
+}
+
+/** The channels enabled by one effective row — the router's gate. */
+export function enabledChannelsOf(row: ChannelRow): NotificationChannel[] {
+  return NOTIFICATION_CHANNELS.filter((channel) => row[channel]);
+}
+
+/**
+ * What a PUT writes for one category: the caller's toggles merged over the
+ * user's CURRENT effective row. A single-toggle save (how the settings UI
+ * writes) must never reset the category's other channels back to their
+ * defaults, which is exactly what a whole-row write would do.
+ */
+export function mergeChoices(
+  current: ChannelRow,
+  choices: Partial<ChannelRow>,
+): ChannelRow {
+  return { ...current, ...choices };
+}

package/src/react/api.ts

@@ -0,0 +1,111 @@
+import type { ChannelRow } from '../preferences-core';
+import type { NotificationChannel } from '../types';
+import type { ListNotificationsResult } from '../wire';
+
+import type { NotificationsResult, NotificationsTransport } from './transport';
+
+/**
+ * The wire client, bound to one mount (12-15).
+ *
+ * Every path this package's screens can call, in one place — which is what
+ * makes the api half's route table and the web half's URLs one contract instead
+ * of two lists that drift.
+ */
+
+/** `GET <mount>/notification-preferences` and the PUT's answer. */
+export interface PreferencesPayload {
+  preferences: Record<string, ChannelRow>;
+  availability: Record<NotificationChannel, boolean>;
+  /** The host's taxonomy, so the screen renders it without being told twice. */
+  categories: string[];
+}
+
+/** `GET <mount>/push-subscriptions`. */
+export interface PushRegistrationPayload {
+  /** null = web push is not configured on this deployment. */
+  vapidPublicKey: string | null;
+  count: number;
+  /**
+   * Whether the endpoint asked about is still registered to the caller. Present
+   * only when one was passed — see {@link NotificationsApiClient.getPushRegistration}.
+   */
+  registered?: boolean;
+}
+
+export interface NotificationsApiClient {
+  listNotifications(input: {
+    cursor?: string | null;
+    limit?: number;
+    filter?: 'all' | 'unread';
+  }): Promise<ListNotificationsResult>;
+  unreadCount(): Promise<number>;
+  markRead(ids: readonly string[]): Promise<NotificationsResult<{ updated: number }>>;
+  markAllRead(): Promise<NotificationsResult<{ updated: number }>>;
+  remove(ids: readonly string[]): Promise<NotificationsResult<{ deleted: number }>>;
+  getPreferences(): Promise<PreferencesPayload>;
+  savePreference(
+    category: string,
+    channel: NotificationChannel,
+    enabled: boolean,
+  ): Promise<NotificationsResult<PreferencesPayload>>;
+  /**
+   * The deployment's VAPID key and the caller's device count — and, when an
+   * `endpoint` is passed, whether the SERVER still has that exact subscription
+   * under the caller's id. The browser holding a subscription object is not
+   * evidence of that: a re-own or a 404/410 prune drops the row and leaves the
+   * browser's object in place.
+   */
+  getPushRegistration(input?: { endpoint?: string }): Promise<PushRegistrationPayload>;
+  savePushSubscription(input: {
+    endpoint: string;
+    keys: { p256dh: string; auth: string };
+  }): Promise<NotificationsResult<{ count: number }>>;
+  removePushSubscription(endpoint: string): Promise<NotificationsResult<{ count: number }>>;
+}
+
+export function createNotificationsApiClient(
+  apiBase: string,
+  transport: NotificationsTransport,
+): NotificationsApiClient {
+  const base = apiBase.replace(/\/$/, '');
+  const url = (path: string): string => `${base}${path}`;
+
+  return {
+    listNotifications({ cursor, limit, filter }) {
+      const params = new URLSearchParams();
+      if (limit !== undefined) params.set('limit', String(limit));
+      if (cursor) params.set('cursor', cursor);
+      if (filter) params.set('filter', filter);
+      const query = params.toString();
+      return transport.get<ListNotificationsResult>(
+        url(`/notifications${query ? `?${query}` : ''}`),
+      );
+    },
+    async unreadCount() {
+      const { count } = await transport.get<{ count: number }>(
+        url('/notifications/unread-count'),
+      );
+      return count;
+    },
+    markRead: (ids) =>
+      transport.send(url('/notifications/mark-read'), 'POST', { ids: [...ids] }),
+    markAllRead: () => transport.send(url('/notifications/mark-read'), 'POST', { all: true }),
+    remove: (ids) => transport.send(url('/notifications/delete'), 'POST', { ids: [...ids] }),
+    getPreferences: () => transport.get<PreferencesPayload>(url('/notification-preferences')),
+    savePreference: (category, channel, enabled) =>
+      transport.send(url('/notification-preferences'), 'PUT', {
+        [category]: { [channel]: enabled },
+      }),
+    getPushRegistration: ({ endpoint } = {}) =>
+      transport.get<PushRegistrationPayload>(
+        url(
+          endpoint
+            ? `/push-subscriptions?endpoint=${encodeURIComponent(endpoint)}`
+            : '/push-subscriptions',
+        ),
+      ),
+    savePushSubscription: (input) => transport.send(url('/push-subscriptions'), 'POST', input),
+    removePushSubscription: (endpoint) =>
+      transport.send(url('/push-subscriptions'), 'DELETE', { endpoint }),
+  };
+}

package/src/react/bell-button.tsx

@@ -0,0 +1,78 @@
+/**
+ * Bare bell trigger with the live unread badge — for hosts that do not already
+ * have a styled icon-button slot. A host with its own trigger chrome uses
+ * `useUnreadCount` + `Panel` directly.
+ */
+import type { JSX } from 'react';
+
+import { Badge } from '@12-apps/ui/data-display/Badge';
+import { Box } from '@12-apps/ui/mui/Box';
+
+import type { NotificationMessages } from '../messages';
+
+import { BellIcon } from './bell-icon';
+import { useUnreadCount, type NotificationsSubscribe } from './hooks';
+import type { InboxStore } from './inbox-state';
+
+const triggerSx = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  p: 0.5,
+  border: 'none',
+  background: 'none',
+  cursor: 'pointer',
+  color: 'text.primary',
+  lineHeight: 0,
+  '& *': { cursor: 'pointer' },
+  '&:hover': { color: 'primary.main' },
+  '&:focus-visible': {
+    outline: '2px solid',
+    outlineColor: 'primary.main',
+    outlineOffset: '2px',
+    borderRadius: '50%',
+  },
+} as const;
+
+export interface BellButtonProps {
+  onClick: () => void;
+  /** Signed-out hosts still mount the bell; `false` silences it. */
+  enabled?: boolean;
+}
+
+export function BellButton({
+  onClick,
+  enabled = true,
+  store,
+  messages,
+  subscribe,
+}: BellButtonProps & {
+  store: InboxStore;
+  messages: NotificationMessages;
+  subscribe?: NotificationsSubscribe;
+}): JSX.Element {
+  const count = useUnreadCount(store, {
+    enabled,
+    ...(subscribe ? { subscribe } : {}),
+  });
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onClick}
+      aria-label={count > 0 ? messages.openBellWithUnread(count) : messages.openBell}
+      data-testid="notifications-bell"
+      sx={triggerSx}
+    >
+      <Badge
+        content={count > 0 ? count : undefined}
+        color="primary"
+        variant="count"
+        max={99}
+        data-testid="notifications-badge"
+      >
+        <BellIcon size={28} />
+      </Badge>
+    </Box>
+  );
+}

package/src/react/bell-icon.tsx

@@ -0,0 +1,33 @@
+/** Inline SVG bell (no icon-library dependency in this package). */
+import type { JSX } from 'react';
+
+import { Box } from '@12-apps/ui/mui/Box';
+
+export function BellIcon({
+  size = 28,
+  dim = false,
+}: {
+  size?: number;
+  dim?: boolean;
+}): JSX.Element {
+  return (
+    <Box
+      component="svg"
+      viewBox="0 0 24 24"
+      aria-hidden
+      sx={{
+        width: size,
+        height: size,
+        fill: 'none',
+        stroke: 'currentColor',
+        opacity: dim ? 0.4 : 1,
+      }}
+      strokeWidth={1.8}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M6 9a6 6 0 0 1 12 0c0 5 2 6 2 6H4s2-1 2-6" />
+      <path d="M10 20a2 2 0 0 0 4 0" />
+    </Box>
+  );
+}