@12-apps/notifications 4.8.0 → 4.10.0

package/src/email/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@12-apps/notifications/email` — ONE transactional-mail layout.
+ *
+ * ## Why it lives in this package
+ *
+ * This package already owned the delivery half: the `EmailDriver` port, the
+ * vendor table (`EMAIL_DRIVERS`) and, in `server/transports/email.ts`, a
+ * `formatEmail` that built a mail out of three `<p>` tags. That formatter is
+ * one of the three ad-hoc renderers this layout replaces — so shipping the
+ * layout anywhere else would have left the replacement in a package this one
+ * does not depend on, and the estate's own lesson is that adoption without
+ * deletion is the worst of both: two ways to render a mail, both maintained.
+ *
+ * Here, `formatEmail` renders THROUGH the layout the moment a host supplies a
+ * brand and a copy pack, and the ad-hoc path is what remains when it does not.
+ *
+ * Framework-free and dependency-free: safe in a browser, in a job, in a
+ * webhook — which is why it is its own subpath rather than part of `.`, whose
+ * consumers are the inbox and the preference matrix.
+ *
+ * The preview catalogue and its routes are `./email/previews`; the operator
+ * screen is `./email/previews/react`; the layout's own copy packs are
+ * `./email/locales`.
+ */
+export {
+  renderEmail,
+  renderEmailHtml,
+  safeHref,
+  type EmailAction,
+  type EmailChromeCopy,
+  type EmailDocument,
+  type EmailFact,
+  type RenderedEmail,
+} from './template';
+
+export { renderEmailText } from './text';
+
+export {
+  EMAIL_CONTENT_WIDTH,
+  EMAIL_FONT_STACK,
+  NEUTRAL_EMAIL_THEME,
+  type EmailTheme,
+} from './theme';

package/src/email/locales.ts

@@ -0,0 +1,29 @@
+import { EN_US_EMAIL_CHROME } from './chrome.en-US';
+import { PT_BR_EMAIL_CHROME } from './chrome.pt-BR';
+import type { EmailChromeCopy } from './template';
+
+/**
+ * The layout's own words, in every language this package ships.
+ *
+ * Its own subpath (`@12-apps/notifications/email/locales`) for the reason every
+ * copy-shipping package here uses one: keeping the packs off the layout entry
+ * is what lets that entry stay the framework-free mechanism a browser can
+ * import, and it is what makes "which language" a decision a host takes by
+ * name rather than one this package takes by default.
+ *
+ * Shaped as `Record<tag, pack>` rather than importing `@12-apps/i18n`'s
+ * `LocalePack`: a package must stay liftable into a repo that has never heard
+ * of that one, so the type is a local structural mirror. The two agree by tag,
+ * and `scripts/locale-coverage-gate.mjs` is what checks that they do.
+ *
+ * A host with ONE audience passes a pack by name. A host whose readers do not
+ * share a language passes `localeCopy(EMAIL_CHROME)` and each message is
+ * written in its own recipient's language — which is the whole reason
+ * `EmailDocument.chrome` is resolved per message rather than at a mount.
+ */
+export const EMAIL_CHROME: Readonly<Record<string, EmailChromeCopy>> = {
+  'pt-BR': PT_BR_EMAIL_CHROME,
+  'en-US': EN_US_EMAIL_CHROME,
+};
+
+export { EN_US_EMAIL_CHROME, PT_BR_EMAIL_CHROME };

package/src/email/previews/catalog.ts

@@ -0,0 +1,208 @@
+import type { RenderedEmail } from '../template';
+
+/**
+ * The preview catalogue: every message a host can send, as a navigable set.
+ *
+ * ## The problem it exists for
+ *
+ * There is normally no way to SEE a transactional mail without triggering the
+ * event that sends it — signing up with a throwaway address to look at the
+ * verification mail, settling an order to look at the receipt, exhausting a
+ * quota to look at that alert. So nobody looks, and a host that renders mail in
+ * three different ways does not find out.
+ *
+ * A layout nobody can see is one release from being three layouts again, which
+ * is why this ships in the same package as the layout rather than beside it.
+ *
+ * ## What is the package's and what is the host's
+ *
+ * The MECHANISM is here: group by owner, render one message for one reader,
+ * report what cannot be shown. WHICH messages exist is the host's, and it
+ * cannot be otherwise — a package cannot know that a host sends a
+ * "your quota is exhausted" notice, let alone what data that notice is
+ * rendered from.
+ *
+ * So a host declares SOURCES. Each names an owner and answers with its
+ * messages, and the catalogue is the union. That inverts the obvious design,
+ * where the package would hold a registry a host writes into: a source is
+ * asked, per request, so a source backed by a registry that fills at import
+ * time answers with whatever is registered NOW rather than with whatever had
+ * been registered when the mount was built.
+ *
+ * ## Why coverage is a first-class output
+ *
+ * A catalogue that quietly omits a message looks exactly like a product that
+ * does not send it. So a source may report what it knows it cannot show —
+ * a message with no sample data, or sample data for a message that no longer
+ * exists — and the surface returns that beside the list rather than swallowing
+ * it. A gap that is visible is a gap somebody closes.
+ */
+
+/** One previewable message. */
+export interface EmailPreviewMessage {
+  /**
+   * Stable id, and the path segment the console navigates by.
+   *
+   * The host chooses the spelling; the surface only requires it to be unique
+   * across every source. Ids that survive a rename are what make a link to one
+   * mail worth sending to a colleague.
+   */
+  readonly id: string;
+  /** The wire identity — an event type, a template key. Shown beside the subject. */
+  readonly key: string;
+  /** Which mail path this belongs to, for grouping inside one owner. */
+  readonly family: string;
+  /** Render it for one reader. MUST be pure — nothing may be sent. */
+  render(locale: string): RenderedEmail;
+}
+
+/** What a source knows it cannot show. Both directions are worth reporting. */
+export interface EmailPreviewCoverage {
+  /** Messages that exist but have no sample data, so no preview. */
+  readonly missing: readonly string[];
+  /** Sample data for a message nothing produces any more. */
+  readonly orphan: readonly string[];
+}
+
+/** One group of messages, owned by whichever code words them. */
+export interface EmailPreviewSource {
+  /**
+   * Who owns these messages — a package name, or the host's own module.
+   *
+   * This is the console's grouping, and it is the answer to "which parts of
+   * this system send mail", which is a question most hosts cannot otherwise
+   * answer at all.
+   */
+  readonly owner: string;
+  /** Called PER REQUEST — see the docblock above for why that matters. */
+  list(): readonly EmailPreviewMessage[];
+  /** Optional: what this source cannot show. Absent means "nothing missing". */
+  coverage?(): EmailPreviewCoverage;
+}
+
+/** One catalogue row: everything the sidebar needs, and no rendered bytes. */
+export interface EmailPreviewRow {
+  readonly id: string;
+  readonly key: string;
+  readonly family: string;
+  readonly owner: string;
+  /** The subject in the requested language, so the list reads as an inbox. */
+  readonly subject: string;
+}
+
+/** One rendered message: what the vendor would be handed, verbatim. */
+export interface EmailPreviewDetail extends EmailPreviewRow {
+  readonly locale: string;
+  readonly html: string;
+  readonly text: string;
+}
+
+export interface EmailPreviewIndex {
+  readonly locale: string;
+  readonly locales: readonly string[];
+  readonly items: readonly EmailPreviewRow[];
+  readonly coverage: EmailPreviewCoverage;
+}
+
+export interface EmailPreviewsConfig {
+  /** The host's sources, in the order the console should list their owners. */
+  readonly sources: readonly EmailPreviewSource[];
+  /**
+   * The languages a preview may be asked for.
+   *
+   * REQUIRED, and not derived from the shipped packs: a host's own messages may
+   * be written in languages this package has never heard of, and a preview that
+   * silently refused one of them would look exactly like a product with no
+   * translation.
+   */
+  readonly locales: readonly string[];
+  /** The language a preview opens in when the caller names none. */
+  readonly defaultLocale: string;
+}
+
+/** An id that appears in more than one source — the one thing that must not happen. */
+export class DuplicateEmailPreviewIdError extends Error {
+  constructor(id: string) {
+    super(`@12-apps/notifications: two e-mail preview messages share the id "${id}".`);
+    this.name = 'DuplicateEmailPreviewIdError';
+    Object.setPrototypeOf(this, DuplicateEmailPreviewIdError.prototype);
+  }
+}
+
+/** The catalogue, assembled from every source. */
+export interface ApiEmailPreviews {
+  /** Every message, with each subject rendered in `locale`. */
+  index(locale?: string): EmailPreviewIndex;
+  /** One rendered message, or `null` when no source owns that id. */
+  render(id: string, locale?: string): EmailPreviewDetail | null;
+  /** The union of every source's gaps. */
+  coverage(): EmailPreviewCoverage;
+  /** Is this a language the host said it writes in? */
+  supportsLocale(locale: string): boolean;
+}
+
+/** One source's messages, tagged with their owner. */
+interface OwnedMessage {
+  readonly owner: string;
+  readonly message: EmailPreviewMessage;
+}
+
+function collect(sources: readonly EmailPreviewSource[]): OwnedMessage[] {
+  const owned = sources.flatMap((source) =>
+    source.list().map((message) => ({ owner: source.owner, message })),
+  );
+  const seen = new Set<string>();
+  for (const { message } of owned) {
+    // A duplicate id makes one message unreachable and the other ambiguous —
+    // and silently, since the console would simply show whichever came first.
+    // Throwing here surfaces it on the request that would have hidden it.
+    if (seen.has(message.id)) throw new DuplicateEmailPreviewIdError(message.id);
+    seen.add(message.id);
+  }
+  return owned;
+}
+
+export function createEmailPreviews(config: EmailPreviewsConfig): ApiEmailPreviews {
+  const { sources, locales, defaultLocale } = config;
+  const localeOf = (locale?: string): string =>
+    locale && locales.includes(locale) ? locale : defaultLocale;
+
+  const rowOf = ({ owner, message }: OwnedMessage, locale: string): EmailPreviewRow => ({
+    id: message.id,
+    key: message.key,
+    family: message.family,
+    owner,
+    subject: message.render(locale).subject,
+  });
+
+  return {
+    index(locale) {
+      const tag = localeOf(locale);
+      return {
+        locale: tag,
+        locales,
+        items: collect(sources).map((owned) => rowOf(owned, tag)),
+        coverage: this.coverage(),
+      };
+    },
+    render(id, locale) {
+      const owned = collect(sources).find((entry) => entry.message.id === id);
+      if (!owned) return null;
+      const tag = localeOf(locale);
+      const message = owned.message.render(tag);
+      return { ...rowOf(owned, tag), locale: tag, html: message.html, text: message.text };
+    },
+    coverage() {
+      const missing: string[] = [];
+      const orphan: string[] = [];
+      for (const source of sources) {
+        const gap = source.coverage?.();
+        if (!gap) continue;
+        missing.push(...gap.missing);
+        orphan.push(...gap.orphan);
+      }
+      return { missing: missing.sort(), orphan: orphan.sort() };
+    },
+    supportsLocale: (locale) => locales.includes(locale),
+  };
+}

package/src/email/previews/hono.ts

@@ -0,0 +1,69 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import { emailPreviewRoutes } from './routes';
+import type { EmailPreviewsConfig } from './catalog';
+
+/**
+ * `@12-apps/notifications/email/previews/hono` — the catalogue as a router.
+ *
+ * The framework-neutral descriptors in `./server` are the contract; this is the
+ * adapter for the framework we happen to use, behind its own subpath with
+ * `hono` as an OPTIONAL peer — a host on Express, or one that only wants the
+ * layout, never resolves it.
+ *
+ * A host writes:
+ *
+ *   const previews = emailPreviewsRouter({ sources, locales, defaultLocale });
+ *   app.use('/api/platform/email-previews/*', requirePlatformOperator);
+ *   app.route('/api/platform/email-previews', previews.router);
+ *
+ * ## The `use` line above is not decoration
+ *
+ * This surface publishes a host's whole transactional-mail inventory and the
+ * exact wording of its verification and reset mails. The routes declare no
+ * session of their own because a package cannot know who a host lets look — so
+ * the gate is the host's, it is REQUIRED, and it is written here rather than
+ * left to be inferred, because the failure is silent: an ungated mount answers
+ * every stranger and nothing about it looks wrong.
+ */
+
+export interface EmailPreviewsHonoConfig extends EmailPreviewsConfig {
+  /**
+   * Optional last-resort refusal, for a host that would rather state the gate
+   * once here than mount middleware around the router.
+   *
+   * Returning `false` answers 403 before any handler runs. Absent means the
+   * host has gated the mount itself — which is the ordinary case, and why this
+   * is not required: a package that demanded its own guard would be a second
+   * authorization system beside the one the host already runs.
+   */
+  readonly allow?: (c: Context) => Promise<boolean> | boolean;
+}
+
+/** The mounted router, plus the descriptors it was built from. */
+export interface EmailPreviewsRouter {
+  router: Hono;
+}
+
+export function emailPreviewsRouter(config: EmailPreviewsHonoConfig): EmailPreviewsRouter {
+  const router = new Hono();
+
+  for (const route of emailPreviewRoutes(config)) {
+    router.get(route.path, async (c) => {
+      if (config.allow && !(await config.allow(c))) {
+        return c.json({ error: 'Forbidden.' }, 403);
+      }
+      const response = await route.handle({
+        params: c.req.param() as Record<string, string | undefined>,
+        // `Object.fromEntries` over the parsed query rather than the raw string:
+        // a repeated `?locale=` is a caller error, and taking the last value is
+        // the same answer every framework here gives.
+        query: c.req.query() as Record<string, string | undefined>,
+      });
+      return c.json(response.body as Record<string, unknown>, response.status as 200 | 400 | 404);
+    });
+  }
+
+  return { router };
+}

package/src/email/previews/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@12-apps/notifications/email/previews` — the preview catalogue and the
+ * routes over it.
+ *
+ * Behind its own subpath so a web bundle importing `./email` (the layout) or
+ * `./react` (the inbox) never resolves the server half.
+ */
+export {
+  createEmailPreviews,
+  DuplicateEmailPreviewIdError,
+  type ApiEmailPreviews,
+  type EmailPreviewCoverage,
+  type EmailPreviewDetail,
+  type EmailPreviewIndex,
+  type EmailPreviewMessage,
+  type EmailPreviewRow,
+  type EmailPreviewSource,
+  type EmailPreviewsConfig,
+} from './catalog';
+
+export {
+  emailPreviewRoutes,
+  type EmailPreviewRequest,
+  type EmailPreviewResponse,
+  type EmailPreviewRoute,
+} from './routes';

package/src/email/previews/react/copy.en-US.ts

@@ -0,0 +1,24 @@
+import type { EmailPreviewScreenCopy } from './copy';
+
+/** US English — the twin that makes {@link PT_BR_EMAIL_PREVIEW_COPY} a choice. */
+export const EN_US_EMAIL_PREVIEW_COPY: EmailPreviewScreenCopy = {
+  title: 'Email previews',
+  description: 'Every email this system sends, grouped by the package that owns it. Nothing is sent from here.',
+  searchLabel: 'Filter',
+  searchPlaceholder: 'subject, event or package',
+  noMatches: 'No message matches the filter.',
+  pickOne: 'Pick a message from the list to see its preview.',
+  tabHtml: 'HTML',
+  tabText: 'Text',
+  tabSource: 'Source',
+  widthDesktop: 'Desktop',
+  widthMobile: 'Mobile',
+  subjectLabel: 'Subject',
+  frameTitle: 'Email preview',
+  coverageTitle: 'Incomplete coverage',
+  missingSamples: (keys) => `No sample data, so no preview: ${keys}.`,
+  orphanSamples: (keys) => `A sample exists but nothing produces this message any more: ${keys}.`,
+  loading: 'Loading...',
+  loadError: 'The previews could not be loaded.',
+  retry: 'Try again',
+};

package/src/email/previews/react/copy.pt-BR.ts

@@ -0,0 +1,24 @@
+import type { EmailPreviewScreenCopy } from './copy';
+
+/** Brazilian Portuguese, as a NAMED pack — never a default. */
+export const PT_BR_EMAIL_PREVIEW_COPY: EmailPreviewScreenCopy = {
+  title: 'Prévia de e-mails',
+  description: 'Todos os e-mails que este sistema envia, agrupados por pacote. Nada é enviado a partir daqui.',
+  searchLabel: 'Filtrar',
+  searchPlaceholder: 'assunto, evento ou pacote',
+  noMatches: 'Nenhuma mensagem corresponde ao filtro.',
+  pickOne: 'Escolha uma mensagem na lista para ver a prévia.',
+  tabHtml: 'HTML',
+  tabText: 'Texto',
+  tabSource: 'Código',
+  widthDesktop: 'Computador',
+  widthMobile: 'Celular',
+  subjectLabel: 'Assunto',
+  frameTitle: 'Prévia do e-mail',
+  coverageTitle: 'Cobertura incompleta',
+  missingSamples: (keys) => `Sem dados de exemplo, então não há prévia: ${keys}.`,
+  orphanSamples: (keys) => `Há exemplo, mas nada mais produz esta mensagem: ${keys}.`,
+  loading: 'Carregando...',
+  loadError: 'Não foi possível carregar as prévias.',
+  retry: 'Tentar novamente',
+};

package/src/email/previews/react/copy.ts

@@ -0,0 +1,42 @@
+/**
+ * The SHAPE of the operator screen's words — no words.
+ *
+ * REQUIRED config with no default in any language, the copy-portability
+ * doctrine. `./copy.pt-BR` and `./copy.en-US` ship packs a host passes BY NAME.
+ *
+ * What is NOT here is anything from the mails themselves: a subject, a body and
+ * a button label all arrive from the server already rendered in whichever
+ * language the preview was asked for. That separation is the point of the
+ * language switch — the CHROME follows the operator, the MESSAGE follows its
+ * own recipient.
+ */
+export interface EmailPreviewScreenCopy {
+  readonly title: string;
+  readonly description: string;
+  /** The sidebar's filter field. */
+  readonly searchLabel: string;
+  readonly searchPlaceholder: string;
+  /** Nothing matched the filter. */
+  readonly noMatches: string;
+  /** No row is selected yet. */
+  readonly pickOne: string;
+  /** The three views of one message. */
+  readonly tabHtml: string;
+  readonly tabText: string;
+  readonly tabSource: string;
+  /** The two widths the HTML view renders at. */
+  readonly widthDesktop: string;
+  readonly widthMobile: string;
+  /** The subject line's label above the preview. */
+  readonly subjectLabel: string;
+  /** The sandboxed frame's title, for screen readers. */
+  readonly frameTitle: string;
+  /** The coverage strip, when the surface reports a gap. */
+  readonly coverageTitle: string;
+  readonly missingSamples: (keys: string) => string;
+  readonly orphanSamples: (keys: string) => string;
+  /** Loading and failure states. */
+  readonly loading: string;
+  readonly loadError: string;
+  readonly retry: string;
+}

package/src/email/previews/react/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * `@12-apps/notifications/email/previews/react` — the operator screen over the
+ * preview catalogue.
+ *
+ * Its own subpath rather than a member of `./react`, which is the INBOX: the
+ * bell and the preference matrix ship to every signed-in user, and this screen
+ * is a platform-staff diagnostic. A host that mounts one has no reason to
+ * resolve the other.
+ */
+export { createEmailPreviewScreen, type EmailPreviewScreenConfig } from './preview-screen';
+export { type EmailPreviewScreenCopy } from './copy';
+export { EN_US_EMAIL_PREVIEW_COPY } from './copy.en-US';
+export { PT_BR_EMAIL_PREVIEW_COPY } from './copy.pt-BR';
+export { type PreviewTab, type PreviewWidth } from './message-view';

package/src/email/previews/react/loadable.tsx

@@ -0,0 +1,83 @@
+import type { JSX } from 'react';
+import { useEffect, useState } from 'react';
+
+import { Alert } from '@12-apps/ui/data-display/Alert';
+import { Button } from '@12-apps/ui/form/Button';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { EmailPreviewScreenCopy } from './copy';
+
+/**
+ * The screen's async plumbing: one hook, and the state it cannot render itself.
+ *
+ * Its own module because it is the half with no opinion about e-mail. What is
+ * left in `preview-screen.tsx` is composition — which columns, which panes,
+ * what the URL says — and this is the machinery underneath all of it.
+ *
+ * `keepPrevious` is the load-bearing option and its docblock says why: a
+ * consumer that renders children only while `data` is non-null gets those
+ * children UNMOUNTED by a blanking reload, which silently discards whatever
+ * state they held.
+ */
+
+/** A load that can fail, in the two states a screen has to render. */
+interface Loadable<T> {
+  data: T | null;
+  error: string | null;
+}
+
+export function useLoadable<T>(
+  load: () => Promise<T>,
+  options: { keepPrevious?: boolean } = {},
+): Loadable<T> & { reload: () => void } {
+  const [state, setState] = useState<Loadable<T>>({ data: null, error: null });
+  const [nonce, setNonce] = useState(0);
+  const { keepPrevious = false } = options;
+  useEffect(() => {
+    let live = true;
+    // `keepPrevious` holds the last good answer on screen while the next one is
+    // in flight, and it is not a nicety. The consumer of this hook renders its
+    // children only while `data` is non-null, so blanking here UNMOUNTS them —
+    // taking the filter text, the open tab and the chosen width with it. On a
+    // fast connection the refetch lands before anyone notices; on a slow one
+    // the operator watches what they just typed disappear.
+    setState((previous) => (keepPrevious ? { ...previous, error: null } : { data: null, error: null }));
+    load()
+      .then((data) => live && setState({ data, error: null }))
+      .catch(
+        (error: unknown) =>
+          live &&
+          setState({ data: null, error: error instanceof Error ? error.message : String(error) }),
+      );
+    return () => {
+      // A language switched twice in a second must not let the FIRST answer
+      // land last — the screen would show a document the operator did not ask
+      // for, with the toggle disagreeing.
+      live = false;
+    };
+  }, [load, nonce]);
+  return { ...state, reload: () => setNonce((n) => n + 1) };
+}
+
+export function Failure({
+  message,
+  copy,
+  onRetry,
+}: {
+  message: string;
+  copy: EmailPreviewScreenCopy;
+  onRetry: () => void;
+}): JSX.Element {
+  return (
+    <Box data-testid="email-preview-error" sx={{ display: 'flex', flexDirection: 'column', gap: 1, alignItems: 'flex-start' }}>
+      <Alert severity="error">
+        <Text as="p" size="sm">{copy.loadError}</Text>
+        <Text as="p" size="sm">{message}</Text>
+      </Alert>
+      <Button size="sm" variant="outline" onClick={onRetry}>
+        {copy.retry}
+      </Button>
+    </Box>
+  );
+}