@12-apps/notifications 4.7.1 → 4.9.0

package/ADOPTING.md

@@ -22,6 +22,8 @@ sweep — endpoints and screens included.
 | **Hono** | `@12-apps/notifications/hono` | `const notifications = notificationsRouter({ ...serverConfig, resolveActor }); app.route('/api/account', notifications.router)`. A one-call mount; `hono` is an OPTIONAL peer, so importing the root, `/server` or `/react` never resolves it. |
 | **React** | `@12-apps/notifications/react` | Call `createWebNotifications({ apiBase })`. `BellWithPanel` is the whole feature as one element; `BellButton` + `Panel` are the pair for a host with its own chrome; `page` is the preferences screen you route to. pt-BR product copy and the origin host's test ids ship inside. |
 | **Web Push** | `@12-apps/notifications/web-push` | `sender: vapidPushSender({ subject, publicKey, privateKey })` on the `WEB_PUSH` declaration. Its own subpath because it is the only piece that needs `web-push` — an OPTIONAL peer a host that never enables the channel never installs. |
+| **Mail layout** | `@12-apps/notifications/email` | `renderEmail(document)` → `{ subject, html, text }`. Framework-free and dependency-free. Turn it on for the EMAIL transport by declaring `layout`; the copy packs are `@12-apps/notifications/email/locales`. |
+| **Previews** | `@12-apps/notifications/email/previews` | The preview catalogue and its two route descriptors. `@12-apps/notifications/email/previews/hono` is the one-call mount; `.../previews/react` is the operator screen. A SECOND wiring manifest — see "The mail layout and its preview console". |
 | **Prisma** | `prisma/notifications.prisma` + `prisma/migrations/*` | Run `pnpm --filter @12-apps/notifications prisma:sync -- <host schema dir>`: the partial is **COPIED** into the host's multi-file schema folder — never symlinked (a symlinked migration is silently skipped by Prisma; a symlinked partial dangles under `turbo prune`). Migrations are discovered structurally from the installed package's `prisma/migrations` by the host's plugin-migration sync. |
 
 ## Host wiring rules (the ones that bite)
@@ -55,6 +57,20 @@ sweep — endpoints and screens included.
    }
    ```
 
+   `getContact` may also answer `locale` — the recipient's own language. It
+   belongs here rather than on the event because it is a fact about the PERSON,
+   not about what happened, and this package has no user table to read it from.
+   Supplying it is what makes a bilingual generator mean anything: a
+   notification is stored as rendered TEXT, so the language is fixed when the
+   row is written, and the router asks for it at exactly that moment. Omit the
+   field, or answer `null`, and every generator falls back to its own default
+   exactly as before — which is the honest answer for a host that stores no
+   per-user language yet.
+
+   The tag is the RECIPIENT's, never the request's. The person who triggers a
+   notification is routinely not the person who reads it, so resolving from
+   `Accept-Language` would word the notice for the wrong human.
+
    Returning `null` means "no such recipient", and `notify` throws
    `UnknownNotificationRecipientError` on it. That is deliberate: a
    notification addressed to nobody is a caller bug, never a silent drop.
@@ -119,6 +135,24 @@ sweep — endpoints and screens included.
    or call `registerGenerator` for a module imported later. The generator's
    `category` is what the router gates fan-out on.
 
+   `generate` takes an optional second argument, `{ locale }` — the recipient's
+   language, from `getContact`. Reach for it when your readers do not share one:
+
+   ```ts
+   const orderPaid = {
+     type: 'order.paid',
+     category: 'orders',
+     // Resolved HERE, per notice — never where the generator is built.
+     generate: (payload, context) => resolveCopy(ORDER_PAID_COPY, context ?? {}).of(payload),
+   };
+   ```
+
+   Resolving where the generator is BUILT is the mistake this parameter exists
+   to prevent: generators are registered once, at boot, so a table chosen there
+   words every notification the process will ever write in a single language —
+   and a host with one audience cannot tell the difference. A one-parameter
+   `generate` stays valid and unchanged.
+
 7. **Billing stays outside, and its gate is `channelPolicy`.** The money logic
    is the host's — this package never learns what a plan is. What it owns is
    *where the answer is asked for*: `(clientId, channels) => channels`, awaited
@@ -307,6 +341,113 @@ There are **no foreign keys into host tables**: `user_id` and `client_id` are
 by-value scalars. Add your own in a host migration — `ON DELETE CASCADE` on
 both is the recommendation, so a deleted account takes its inbox with it.
 
+## The mail layout and its preview console
+
+Both are optional and independent of everything above: the layout is a pure
+function, and the console declares no `db`, so adopting either touches no schema.
+
+### 1. Turning the layout on for the EMAIL transport
+
+Add `layout` to the driver declaration. Without it you keep the previous
+rendering byte for byte — this is opt-in because `brand` and `chrome` are
+REQUIRED with no default, so making them mandatory would break every host
+already declaring EMAIL, at runtime, on the first send.
+
+```ts
+import { PT_BR_EMAIL_CHROME } from '@12-apps/notifications/email/locales';
+
+{ channel: 'EMAIL', driver: 'resend', apiKey, from, linkLabel: 'Ver detalhes',
+  layout: { brand: 'Loja Exemplo', chrome: PT_BR_EMAIL_CHROME, locale: 'pt-BR' } }
+```
+
+`theme` may be omitted; the layout ships a neutral grey-on-white palette. That
+one asymmetry is deliberate and argued in `src/email/theme.ts`: a wrong-language
+default is invisible until a customer complains, where a missing theme is
+visible in the first preview.
+
+For a host whose recipients do not share a language, resolve `chrome` per
+message rather than at the mount — a mail's language is the RECIPIENT's, not the
+request's.
+
+### 2. YOU gate the console. The routes only ask
+
+`emailPreviewRoutes` declares `kind: 'authenticated'` on both descriptors — the
+wiring contract's word for "behind the host's session resolution and its RBAC".
+It names no permission id, because the ids are yours. **So the descriptor asks
+for a gate; it cannot supply one.**
+
+The surface publishes your whole transactional-mail inventory and the exact
+wording and link shape of your verification and password-reset mails — the
+reference somebody writing a convincing phishing mail for your product would
+want. Mount it behind whichever gate you already use for platform staff:
+
+```ts
+import { emailPreviewsRouter } from '@12-apps/notifications/email/previews/hono';
+
+app.use('/api/platform/email-previews/*', requirePlatformOperator);
+app.route('/api/platform/email-previews', emailPreviewsRouter(previews).router);
+```
+
+`allow` on the config is there for a host that would rather state the refusal
+once in the config than mount middleware around the router. Either is fine;
+neither is optional.
+
+### 3. Declare the SOURCES — and expect to be asked repeatedly
+
+A package cannot know that you send a "your quota is exhausted" notice, let
+alone what data it renders from. So you declare sources, and each is asked
+**per request**:
+
+```ts
+const previews = {
+  sources: [authMailSource(), notificationMailSource()],
+  locales: ['pt-BR', 'en-US'],
+  defaultLocale: 'pt-BR',
+};
+```
+
+Per request rather than once at the mount, because domain modules typically
+register their messages as an import side effect. A catalogue built once lists
+whatever happened to be imported first — which looks exactly like a product that
+sends fewer mails than it does.
+
+Ids must be unique across every source; a duplicate THROWS, because the
+alternative is one message unreachable and the other ambiguous, silently.
+
+### 4. `coverage` is optional, and worth writing
+
+A catalogue that quietly omits a message looks exactly like a product that does
+not send it. Report what you cannot show — a message with no sample data, or
+sample data for a message that no longer exists — and the screen renders it as a
+warning strip. Pair it with a unit test asserting `missing` is empty, and a mail
+added without a sample becomes a red test naming the type rather than a gap
+nobody sees.
+
+### 5. Adopt it as the SECOND manifest
+
+`@12-apps/notifications-email-previews` is a separate manifest from the same
+package, so a host mounts the inbox and declines the console (or vice versa) in
+writing rather than silently getting both behind one gate:
+
+```ts
+host.adoptServer({
+  manifest: notificationEmailPreviewsManifest,
+  server: notificationEmailPreviewsServerManifest,
+  bindings: { http: { mountPath: '/api/platform/email-previews', config: previews } },
+});
+```
+
+The web half binds `{ apiBase, copy }`, with `copy` a pack passed by name —
+`EN_US_EMAIL_PREVIEW_COPY` or `PT_BR_EMAIL_PREVIEW_COPY` from
+`@12-apps/notifications/email/previews/react`.
+
+### 6. Nothing can be sent from the console
+
+It holds no driver, no transport and no address, and `render` is pure by the
+contract `EmailPreviewMessage` states. The one mistake a preview surface must be
+incapable of — putting a sample in somebody's inbox — is not reachable from that
+code at all, rather than merely not done.
+
 ## What does NOT come with it
 
 - **The events.** Generators are host code (see rule 6).
@@ -314,3 +455,7 @@ both is the recommendation, so a deleted account takes its inbox with it.
 - **A plan model.** `channelPolicy` answers; it does not decide.
 - **An authorization engine.** `audience` answers; it does not decide.
 - **A service worker.** The file is the host's (rule 12).
+- **The mail INVENTORY.** The preview console renders what you declare as
+  sources; it cannot discover what your product sends.
+- **A brand, a palette or a sentence.** The layout requires the first, defaults
+  only the second, and ships the third as packs you pass by name.

package/README.md

@@ -121,6 +121,71 @@ a form B's keys decrypt) and the preferences screen derives "this browser is
 receiving alerts" from the SERVER's answer, not from the browser's own
 subscription object.
 
+## One mail layout, and a console that previews it
+
+`EMAIL` used to render a mail as three bare `<p>` tags. That is a **layout**
+problem rather than a wording one — a paragraph with no document around it
+inherits whatever the client decides: 13px Arial in Gmail, Times New Roman in
+Outlook, no centring anywhere — so the layout ships here, beside the transport
+that needed it.
+
+```ts
+import { renderEmail } from '@12-apps/notifications/email';
+import { PT_BR_EMAIL_CHROME } from '@12-apps/notifications/email/locales';
+```
+
+`renderEmail(document)` takes STRUCTURE — a heading, paragraphs, an optional
+facts table, at most one call to action — and never markup. Three things follow,
+and each was a real defect in the renderers it replaces:
+
+1. **Escaping cannot be forgotten.** It happens in one place.
+2. **The plain-text twin cannot drift.** Both halves render from the same
+   object. A `text/html` part with no `text/plain` twin is scored by every major
+   spam filter.
+3. **A preview is honest**, because the console renders exactly this.
+
+The client constraints are encoded once so no caller has to know them: tables
+rather than divs (Outlook lays HTML out with Word), inline styles only (Gmail
+strips `<style>`), no web fonts or `color-mix()` or CSS variables, a hidden
+preheader, a `bgcolor` attribute **and** a background style on the CTA.
+
+**The EMAIL transport opts in.** Declare `layout` on the driver declaration and
+`formatEmail` renders the shared document; omit it and you keep the previous
+rendering byte for byte. Opt-in rather than automatic because `brand` and
+`chrome` are required with no default — a package that defaulted them would sign
+another company's mail, in a language nobody chose — so making them mandatory
+would break every host already declaring EMAIL, at runtime, on the first send.
+
+```ts
+{ channel: 'EMAIL', driver: 'resend', apiKey, from, linkLabel: 'Ver detalhes',
+  layout: { brand: 'Loja Exemplo', chrome: PT_BR_EMAIL_CHROME, locale: 'pt-BR' } }
+```
+
+### The preview console
+
+There is normally no way to *see* a transactional mail without triggering the
+event that sends it — signing up with a throwaway address for the verification
+mail, settling an order for the receipt. So nobody looks, and a product
+rendering three ways does not find out. A layout nobody can see is one release
+from being three again, which is why the console ships in the same package.
+
+It is the package's **second wiring manifest**
+(`@12-apps/notifications-email-previews`), because the first has already spent
+`http` on the account inbox and `surface` on the bell. That split is deliberate:
+the inbox ships to every signed-in user, and this console publishes the whole
+mail inventory and the exact wording and link shape of the verification and
+reset mails. **You gate the mount** — the routes declare `kind: 'authenticated'`
+and name no permission id, because the ids are the host's.
+
+WHICH messages exist is yours too, declared as `sources` that are asked **per
+request** (a source backed by a registry that fills at import time would
+otherwise answer with whatever was imported first). A source reports its own
+`coverage` — what it cannot show — and the screen renders that as a warning
+strip rather than pretending to be complete. Nothing can be sent from it: it
+holds no driver, no transport and no address.
+
+See **[ADOPTING.md](./ADOPTING.md)** for the mount, the gate and the sources.
+
 ## The models
 
 `prisma/notifications.prisma` — `Notification`, `NotificationDelivery`,

package/dist/catalog-BOVZ2b-b.d.ts

@@ -0,0 +1,132 @@
+import { R as RenderedEmail } from './template-Dlt5S54z.js';
+
+/**
+ * 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. */
+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. */
+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. */
+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. */
+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. */
+interface EmailPreviewDetail extends EmailPreviewRow {
+    readonly locale: string;
+    readonly html: string;
+    readonly text: string;
+}
+interface EmailPreviewIndex {
+    readonly locale: string;
+    readonly locales: readonly string[];
+    readonly items: readonly EmailPreviewRow[];
+    readonly coverage: EmailPreviewCoverage;
+}
+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. */
+declare class DuplicateEmailPreviewIdError extends Error {
+    constructor(id: string);
+}
+/** The catalogue, assembled from every source. */
+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;
+}
+declare function createEmailPreviews(config: EmailPreviewsConfig): ApiEmailPreviews;
+
+export { type ApiEmailPreviews as A, DuplicateEmailPreviewIdError as D, type EmailPreviewsConfig as E, type EmailPreviewCoverage as a, type EmailPreviewDetail as b, type EmailPreviewIndex as c, type EmailPreviewMessage as d, type EmailPreviewRow as e, type EmailPreviewSource as f, createEmailPreviews as g };

package/dist/{chunk-XE7HZVMH.js → chunk-BGI4BQ66.js}

@@ -19,4 +19,4 @@ export {
   NOTIFICATION_CHANNELS,
   taxonomyOf
 };
-//# sourceMappingURL=chunk-XE7HZVMH.js.map
+//# sourceMappingURL=chunk-BGI4BQ66.js.map

package/dist/chunk-BGI4BQ66.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Core types of the channel-agnostic notification system (12-15).\n *\n * Three decoupled layers, each open for extension without touching the others:\n *   - GENERATORS map a typed domain event to agnostic content (title/body/…).\n *   - The CHANNEL ROUTER always writes the notification-centre inbox record,\n *     then fans out one delivery per enabled channel.\n *   - TRANSPORTS format the agnostic content for one channel and send it.\n *\n * Nothing here knows about a concrete channel's wire format — that lives\n * entirely inside each transport adapter — and nothing here knows about a\n * concrete DOMAIN either: the event `type` set, the preference categories and\n * the channel list are all host config (see {@link NotificationTaxonomy}).\n */\n\n/** Transport channels a notification can fan out to (DB CHECK mirrors this). */\nexport const NOTIFICATION_CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'] as const;\nexport type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];\n\n/**\n * The preference categories are the HOST's, and required.\n *\n * There used to be a `NOTIFICATION_CATEGORIES = ['orders','payments','stock',\n * 'system']` here — one product's set — and `taxonomyOf` fell back to it\n * whenever a host passed none. The docstring argued the case itself: \"it is\n * product vocabulary, not machinery\", and then shipped the vocabulary anyway as\n * the default, which is the only part a forgetful host would ever see.\n *\n * The consequence was quiet rather than loud: the settings screen renders four\n * rows a foreign host never chose, its own categories are absent, and every\n * preference a user sets is filed against a taxonomy nothing else in that\n * system uses. Nothing throws, because `category` is deliberately a free string\n * — the packaged migration puts **no CHECK** on it, precisely because a closed\n * set would be wrong for every host but the first. That freedom is what made\n * the default undetectable.\n *\n * `channel` and `status` are different and keep their CHECKs: those ARE this\n * library's own closed sets.\n */\nexport type NotificationCategory = string;\n\n/**\n * Per-channel delivery lifecycle (DB CHECK mirrors this).\n *\n * `SENDING` is the CLAIM: exactly one dispatcher moves a row out of `QUEUED`,\n * so two dispatchers can never both send the same delivery. A row left\n * `SENDING` is a dispatcher that died mid-send, and the sweep reclaims it once\n * it is older than the cutoff.\n *\n * `DEAD` is terminal: the attempt ceiling was reached (or the recipient no\n * longer exists), and no sweep will pick the row up again. Without it a\n * permanently invalid destination is a billed provider call on every sweep,\n * forever, and the sweep's working set only grows.\n */\nexport type DeliveryStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED' | 'DEAD';\n\n/**\n * Channel-agnostic content a generator produces. This is what the inbox stores\n * verbatim and what every transport's formatter receives — no channel may leak\n * its wire format into it.\n */\nexport interface NotificationContent {\n  title: string;\n  body: string;\n  /** In-app deep link (a same-origin path such as `/orders/123`). */\n  link?: string;\n  /** Structured extras for consumers that want more than text. */\n  data?: Record<string, unknown>;\n}\n\n/** Who receives a notification. `clientId` scopes it to a tenant when set. */\nexport interface NotificationRecipient {\n  userId: string;\n  clientId?: string;\n}\n\n/**\n * A typed domain event handed to `notify`. `type` selects the registered\n * generator; `payload` is that generator's typed input. Callers never touch\n * channels, formatting, or preferences.\n */\nexport interface NotificationEvent<TPayload = unknown> {\n  type: string;\n  recipient: NotificationRecipient;\n  payload: TPayload;\n}\n\n/**\n * Maps one domain event type to agnostic content. Registered through the\n * server config (or `registerGenerator` for a late arrival); adding a\n * generator never touches existing generators, the router, or any transport\n * (open/closed).\n */\n/**\n * Who the content is being rendered FOR — the reader, at the moment the\n * generator is asked.\n *\n * A notification is stored as rendered TEXT: title and body are columns, so\n * the language is chosen once, when the row is written, and never again. That\n * makes this the only honest place to ask. A generator is registered at BOOT —\n * a host that resolved its words there would pin every future reader to\n * whichever language the process happened to start in, invisibly, because a\n * single-locale host cannot tell the difference.\n *\n * The tag is the RECIPIENT's, never the request's. The person who triggers a\n * notification is routinely not the person who reads it: an invite is sent\n * because an administrator acted and is read by the invitee. Reading\n * `Accept-Language` here would be a bug that only ever surfaces as somebody\n * being told things in a language they do not speak.\n *\n * Absent means \"nobody said\" — a host with one audience, or one that stores no\n * per-user language, populates nothing and every generator answers with its\n * own default exactly as it did before this existed.\n */\nexport interface NotificationGenerateContext {\n  readonly locale?: string | null;\n}\n\nexport interface NotificationGenerator<TPayload = unknown> {\n  /** The event key, dot-namespaced (\"order.paid\"). One generator per type. */\n  type: string;\n  /** The preference category the router gates this type's fan-out on. */\n  category: NotificationCategory;\n  /**\n   * Render this event's content for ONE recipient.\n   *\n   * `context` is OPTIONAL, and that is what keeps every generator written\n   * before it working: a one-parameter `generate` is assignable to this\n   * signature unchanged. A host that passes nothing is stating a fact — it has\n   * no language for this reader — rather than asserting a default.\n   */\n  generate: (payload: TPayload, context?: NotificationGenerateContext) => NotificationContent;\n}\n\n/**\n * The recipient as a transport sees them: resolved destinations only. Built by\n * the router from the host's contact directory + the push subscriptions this\n * package owns; transports use it to answer\n * {@link NotificationTransport.supports}.\n */\nexport interface TransportRecipient {\n  userId: string;\n  email: string | null;\n  /**\n   * The recipient's own language, when the host's contact directory states\n   * one. Absent means \"nobody said\" — see {@link NotificationGenerateContext}.\n   */\n  locale?: string | null;\n  /** Phone as the host stores it (transports normalize per provider rules). */\n  phone: string | null;\n  /** How many active browser push subscriptions the user holds. */\n  pushSubscriptionCount: number;\n}\n\n/**\n * One pluggable channel adapter: a FORMATTER (agnostic content → channel\n * message) plus a SENDER. Adding a channel = registering one of these; the\n * router dispatches through the registry and needs no change.\n *\n * `send` resolves on success and THROWS on failure — the router records the\n * error on the delivery row and isolates it from other channels. Sends must be\n * retry-safe: the router may re-dispatch a QUEUED/FAILED delivery.\n */\nexport interface NotificationTransport<TMessage = unknown> {\n  channel: NotificationChannel;\n  /**\n   * Whether this recipient is addressable on this channel right now — the\n   * destination exists (e-mail / phone / push subscription) AND the provider\n   * is configured. `false` simply skips the channel (no delivery row).\n   */\n  supports(recipient: TransportRecipient): boolean;\n  /** Transform the agnostic content into this channel's message shape. */\n  format(content: NotificationContent): TMessage;\n  /** Deliver the formatted message to the recipient. Throws on failure. */\n  send(message: TMessage, recipient: TransportRecipient): Promise<void>;\n}\n\n/**\n * The host's product vocabulary. Everything below the surface (routing,\n * delivery rows, retries, the wire) is identical for every host; WHICH\n * categories exist and how they are labelled is not.\n */\nexport interface NotificationTaxonomy {\n  /** The preference categories, in the order the settings screen lists them. */\n  categories: readonly NotificationCategory[];\n}\n\n/**\n * The taxonomy in force. `categories` is REQUIRED — see above.\n *\n * The empty check was already here and stays: an empty list and a missing one\n * are the same mistake, and both now fail at assembly rather than rendering an\n * empty settings screen or somebody else's four rows.\n */\nexport function taxonomyOf(config: {\n  categories: readonly NotificationCategory[];\n}): NotificationTaxonomy {\n  const categories = config.categories;\n  if (!categories || categories.length === 0) {\n    throw new Error(\n      '@12-apps/notifications: `categories` is required and must not be empty — ' +\n        'the preference categories are the host\\'s product vocabulary.',\n    );\n  }\n  return { categories: [...categories] };\n}\n\n/** The host's logger. Defaults to the console (the @12-apps/jobs precedent). */\nexport interface NotificationLogger {\n  info(message: string, ...meta: unknown[]): void;\n  error(message: string, ...meta: unknown[]): void;\n}\n"],"mappings":";;;;;AAgBO,IAAM,wBAAwB,CAAC,SAAS,OAAO,YAAY,UAAU;AAkLrE,SAAS,WAAW,QAEF;AACvB,QAAM,aAAa,OAAO;AAC1B,MAAI,CAAC,cAAc,WAAW,WAAW,GAAG;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO,EAAE,YAAY,CAAC,GAAG,UAAU,EAAE;AACvC;AAXgB;","names":[]}

package/dist/chunk-EKUSNUBT.js

@@ -0,0 +1,222 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/email/text.ts
+function renderEmailText(document) {
+  const blocks = [
+    document.heading,
+    "",
+    ...textParagraphs(document),
+    ...textFacts(document),
+    ...textAction(document),
+    ...textNotes(document),
+    "--",
+    document.chrome.tagline(document.brand),
+    document.chrome.automated
+  ];
+  return `${blocks.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+`;
+}
+__name(renderEmailText, "renderEmailText");
+function textParagraphs(document) {
+  return (document.paragraphs ?? []).flatMap((text) => [text, ""]);
+}
+__name(textParagraphs, "textParagraphs");
+function textFacts(document) {
+  const rows = document.facts ?? [];
+  return rows.length === 0 ? [] : [...rows.map((f) => `${f.label}: ${f.value}`), ""];
+}
+__name(textFacts, "textFacts");
+function textAction(document) {
+  return document.action ? [`${document.action.label}: ${document.action.href}`, ""] : [];
+}
+__name(textAction, "textAction");
+function textNotes(document) {
+  const notes = document.notes ?? [];
+  return notes.length === 0 ? [] : [...notes, ""];
+}
+__name(textNotes, "textNotes");
+
+// src/email/theme.ts
+var NEUTRAL_EMAIL_THEME = {
+  page: "#F5F6F8",
+  surface: "#FFFFFF",
+  panel: "#F5F6F8",
+  border: "#E1E4E9",
+  ink: "#1A1D23",
+  muted: "#5C6470",
+  accent: "#1F5EDB",
+  onAccent: "#FFFFFF",
+  rule: "#1F5EDB"
+};
+var EMAIL_FONT_STACK = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'";
+var EMAIL_CONTENT_WIDTH = 600;
+
+// src/email/template.ts
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+__name(escapeHtml, "escapeHtml");
+var SAFE_LINK_SCHEMES = /* @__PURE__ */ new Set(["http:", "https:", "mailto:"]);
+function safeHref(href) {
+  const trimmed = href.trim();
+  if (trimmed.startsWith("/")) return escapeHtml(trimmed);
+  try {
+    const url = new URL(trimmed);
+    return SAFE_LINK_SCHEMES.has(url.protocol) ? escapeHtml(url.toString()) : "#";
+  } catch {
+    return "#";
+  }
+}
+__name(safeHref, "safeHref");
+function preheaderOf(document) {
+  return document.preheader ?? document.paragraphs?.[0] ?? document.heading;
+}
+__name(preheaderOf, "preheaderOf");
+function paragraph(text, theme) {
+  return `<p style="margin:0 0 16px;font-size:16px;line-height:1.6;color:${theme.ink}">${escapeHtml(text)}</p>`;
+}
+__name(paragraph, "paragraph");
+function facts(rows, theme) {
+  if (rows.length === 0) return "";
+  const cells = rows.map((row, index) => {
+    const divider = index === 0 ? "" : `border-top:1px solid ${theme.border};`;
+    const value = row.emphasis ? `font-size:20px;font-weight:700;color:${theme.ink}` : `font-size:15px;color:${theme.ink}`;
+    return [
+      `<tr>`,
+      `<td style="${divider}padding:12px 0 12px 16px;font-size:13px;line-height:1.4;color:${theme.muted};text-transform:uppercase;letter-spacing:.4px;white-space:nowrap">${escapeHtml(row.label)}</td>`,
+      `<td align="right" style="${divider}padding:12px 16px 12px 0;line-height:1.4;${value}">${escapeHtml(row.value)}</td>`,
+      `</tr>`
+    ].join("");
+  }).join("");
+  return [
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="border-collapse:separate;background:${theme.page};border:1px solid ${theme.border};border-radius:10px;margin:0 0 24px">`,
+    cells,
+    `</table>`
+  ].join("");
+}
+__name(facts, "facts");
+function action(cta, theme) {
+  return [
+    `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:8px 0 24px">`,
+    `<tr>`,
+    `<td align="center" bgcolor="${theme.accent}" style="border-radius:8px;background:${theme.accent}">`,
+    `<a href="${safeHref(cta.href)}" style="display:inline-block;padding:14px 32px;font-family:${EMAIL_FONT_STACK};font-size:16px;font-weight:600;line-height:1;color:${theme.onAccent};text-decoration:none;border-radius:8px">${escapeHtml(cta.label)}</a>`,
+    `</td>`,
+    `</tr>`,
+    `</table>`
+  ].join("");
+}
+__name(action, "action");
+function fallback(cta, chrome, theme) {
+  return [
+    `<p style="margin:0 0 8px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.fallbackHint)}</p>`,
+    `<p style="margin:0 0 24px;font-size:13px;line-height:1.5;word-break:break-all"><a href="${safeHref(cta.href)}" style="color:${theme.accent};text-decoration:underline">${escapeHtml(cta.href)}</a></p>`
+  ].join("");
+}
+__name(fallback, "fallback");
+function header(document, theme) {
+  return [
+    `<tr>`,
+    `<td style="padding:32px 40px 0">`,
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">`,
+    `<tr><td style="font-size:20px;font-weight:700;letter-spacing:-.2px;color:${theme.ink}">${escapeHtml(document.brand)}</td></tr>`,
+    `<tr><td style="padding-top:12px"><div style="height:3px;width:44px;background:${theme.rule};border-radius:2px;font-size:0;line-height:0">&nbsp;</div></td></tr>`,
+    `</table>`,
+    `</td>`,
+    `</tr>`
+  ].join("");
+}
+__name(header, "header");
+function footer(document, theme) {
+  const { chrome, brand } = document;
+  return [
+    `<tr>`,
+    `<td style="padding:0 40px 40px">`,
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">`,
+    `<tr><td style="border-top:1px solid ${theme.border};padding-top:20px">`,
+    `<p style="margin:0 0 6px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.tagline(brand))}</p>`,
+    `<p style="margin:0;font-size:12px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.automated)}</p>`,
+    `</td></tr>`,
+    `</table>`,
+    `</td>`,
+    `</tr>`
+  ].join("");
+}
+__name(footer, "footer");
+function styleBlock() {
+  return [
+    `<style>`,
+    `@media only screen and (max-width:620px){`,
+    `.fp-card{width:100%!important;border-radius:0!important;border-left:0!important;border-right:0!important}`,
+    `.fp-pad{padding-left:24px!important;padding-right:24px!important}`,
+    `.fp-h1{font-size:22px!important}`,
+    `}`,
+    `</style>`
+  ].join("");
+}
+__name(styleBlock, "styleBlock");
+function renderEmailHtml(document) {
+  const theme = document.theme ?? NEUTRAL_EMAIL_THEME;
+  const body = [
+    `<h1 class="fp-h1" style="margin:0 0 16px;font-size:26px;line-height:1.25;font-weight:700;letter-spacing:-.3px;color:${theme.ink}">${escapeHtml(document.heading)}</h1>`,
+    ...(document.paragraphs ?? []).map((text) => paragraph(text, theme)),
+    facts(document.facts ?? [], theme),
+    ...document.action ? [action(document.action, theme)] : [],
+    ...document.action ? [fallback(document.action, document.chrome, theme)] : [],
+    ...(document.notes ?? []).map(
+      (note) => `<p style="margin:0 0 8px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(note)}</p>`
+    )
+  ].join("\n      ");
+  return `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="${escapeHtml(document.locale)}">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="x-apple-disable-message-reformatting" />
+<meta name="color-scheme" content="light" />
+<meta name="supported-color-schemes" content="light" />
+<title>${escapeHtml(document.subject)}</title>
+${styleBlock()}
+</head>
+<body style="margin:0;padding:0;background:${theme.page};font-family:${EMAIL_FONT_STACK};-webkit-font-smoothing:antialiased">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;mso-hide:all">${escapeHtml(preheaderOf(document))}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:${theme.page}">
+<tr>
+<td align="center" style="padding:32px 12px">
+<table role="presentation" class="fp-card" width="${EMAIL_CONTENT_WIDTH}" cellpadding="0" cellspacing="0" border="0" style="width:${EMAIL_CONTENT_WIDTH}px;max-width:100%;background:${theme.surface};border:1px solid ${theme.border};border-radius:14px">
+${header(document, theme)}
+<tr>
+<td class="fp-pad" style="padding:24px 40px 8px">
+      ${body}
+</td>
+</tr>
+${footer(document, theme)}
+</table>
+</td>
+</tr>
+</table>
+</body>
+</html>`;
+}
+__name(renderEmailHtml, "renderEmailHtml");
+function renderEmail(document) {
+  return {
+    subject: document.subject,
+    html: renderEmailHtml(document),
+    text: renderEmailText(document)
+  };
+}
+__name(renderEmail, "renderEmail");
+
+export {
+  renderEmailText,
+  NEUTRAL_EMAIL_THEME,
+  EMAIL_FONT_STACK,
+  EMAIL_CONTENT_WIDTH,
+  safeHref,
+  renderEmailHtml,
+  renderEmail
+};
+//# sourceMappingURL=chunk-EKUSNUBT.js.map