@zerotal/notifications 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -8,6 +8,60 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.1] — 2026-08-31
+
+### Added
+
+- **`MailMessage.header()` and `MailPayload.headers`** — set a header the driver does
+  not build itself. `MailPayload` had `to`/`from`/`subject`/`text`/`html`/`cc`/`bcc`/
+  `replyTo`/`attachments` and no way to add one, so a team that wanted
+  `List-Unsubscribe` had to patch a vendored copy of this package and settled for a
+  footer link instead.
+
+  That is not an equivalent substitute. Gmail and Yahoo draw their native unsubscribe
+  control from the header, and a recipient who cannot find a control marks the message
+  as spam instead — a judgement that attaches to the sending domain and degrades
+  delivery of everything else it sends. Pair it with `List-Unsubscribe-Post` for the
+  one-click form both providers now expect.
+
+  Wired through all three drivers: SMTP writes them into the message, Resend sends
+  them as the API's `headers` object, and the log driver prints them, since the reason
+  to set one is that a client does something with it and the log driver is where that
+  gets checked before anything is sent for real.
+
+  Names the drivers build themselves are refused rather than sent twice — a second
+  `Subject` is an ambiguous message, not an override — and the error names the
+  `MailMessage` method to use instead. The list is exported as
+  `RESERVED_MAIL_HEADERS`, with `resolveHeaders()` beside it for anyone writing a
+  custom transport. Validation runs when the header is set, so the throw carries the
+  stack of the code that wrote it rather than of a queue worker three hops away, and
+  again in the driver, because a payload can reach one without passing through
+  `MailMessage`. CR and LF in a value are folded to a space: left raw they end the
+  header and let the remainder be read as further headers, which is how a `Bcc`
+  arrives courtesy of whoever supplied a tracking ID.
+
+## [1.11.0] — 2026-08-31
+
+### Changed
+
+- **The database channel is built on first use, not at construction.** Registering the
+  provider used to open a `DatabaseChannel` against `database.table` — default
+  `notifications` — and create that table, whether or not any notification ever routed
+  there. An app that never uses the channel now never touches the table, and the
+  manager no longer resolves a database connection while it is being constructed.
+
+### Added
+
+- **A doctor check for a `notifications` table that is not the framework's.**
+  `notifications` is a very ordinary name for a table an app already owns, and one
+  app's was a completely different shape — `household_id`, `title`, `body`,
+  `action_url`, with an in-app inbox reading it. The only thing between the
+  framework's channel and a wrong-shaped insert into that inbox was that no
+  notification's `channels()` happened to return `"database"`. A convention holding
+  back data corruption is a convention that will lose, so `zt doctor` now says so
+  before the first notification does. Silent when the table does not exist yet, which
+  is every fresh checkout.
+
 ## [1.10.0] — 2026-08-30
 
 ### Fixed

package/api-surface.md

@@ -54,6 +54,7 @@ class MailMessage = {
   embed: (cid: string, attachment: Omit<MailAttachment, 'cid' | 'inline'>) => MailMessage
   from: (address: AddressInput) => MailMessage
   greeting: {    (text: string): MailMessage;    (text: string, style: TextStyle): MailMessage;    (build: (t: RichLine) => void): MailMessage;}
+  header: (name: string, value: string) => MailMessage
   html: (content: string) => MailMessage
   line: {    (text: string): MailMessage;    (text: string, style: TextStyle): MailMessage;    (build: (t: RichLine) => void): MailMessage;}
   replyTo: (address: AddressInput) => MailMessage
@@ -304,12 +305,16 @@ const NotificationRegistry = {    _map: Map<string, NotificationClass>;    regis
 
 const Notify = NotificationManager
 
+const RESERVED_MAIL_HEADERS = readonly string[]
+
 function channelStats = () => ChannelStat[]
 
 function NotificationConfig = (options?: DeepPartial<NotificationConfigShape>) => NotificationConfigShape
 
 function recentDeliveries = () => RecentDelivery[]
 
+function resolveHeaders = (headers: Record<string, string>) => Record<string, string>
+
 interface ChannelStat = {
   avgMs: number
   channel: string
@@ -352,6 +357,7 @@ interface MailPayload = {
   bcc?: MailAddress[]
   cc?: MailAddress[]
   from: MailAddress
+  headers?: Record<string, string>
   html?: string
   replyTo?: MailAddress
   subject: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0",
-    "@zerotal/orm": "1.10.0",
-    "@zerotal/queue": "1.10.0"
+    "@zerotal/core": "1.11.1",
+    "@zerotal/orm": "1.11.1",
+    "@zerotal/queue": "1.11.1"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.10.0",
+    "@zerotal/broadcasting": "1.11.1",
     "typescript": "^5.8.0"
   },
   "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",

package/src/NotificationManager.ts

@@ -23,13 +23,29 @@ export class NotificationManager {
   private readonly _resolvers = new Map<string, ChannelResolver>();
   /** Resolved channel instances, memoized per name. */
   private readonly _channels = new Map<string, NotificationChannel>();
-  private readonly _db: DatabaseChannel;
+  /**
+   * The database channel, built on first use rather than at construction.
+   *
+   * It used to be built in the constructor, which meant every app that registered
+   * this provider opened a `DatabaseChannel` against `database.table` — default
+   * `notifications` — whether or not any notification ever routed there. `notifications`
+   * is a very ordinary name for a table an app already owns, and one app's is a
+   * completely different shape: `household_id`, `user_id`, `title`, `body`,
+   * `action_url`, with an in-app inbox reading it. The only thing standing between
+   * the framework's channel and a wrong-shaped insert into that inbox was that no
+   * notification's `channels()` happened to return `"database"`. A convention holding
+   * back data corruption is a convention that will lose.
+   *
+   * Building it lazily does not make the collision safe — `notificationsTableCheck`
+   * is what reports that — but it means an app that never uses the channel never
+   * touches the table, and it stops the manager resolving a database connection at
+   * construction time.
+   */
+  private _dbChannel: DatabaseChannel | undefined;
 
   constructor(private readonly config: NotificationConfigShape) {
-    this._db = new DatabaseChannel(config.database.table, _getConnection());
-
     this._resolvers.set("mail", () => new MailChannel(config.mail));
-    this._resolvers.set("database", () => this._db);
+    this._resolvers.set("database", () => this.database);
     this._resolvers.set("broadcast", () => new BroadcastChannel());
 
     this._resolvers.set("slack", () => {
@@ -241,7 +257,8 @@ export class NotificationManager {
 
   /** Expose the database channel for direct queries (unread, markAsRead). */
   get database(): DatabaseChannel {
-    return this._db;
+    this._dbChannel ??= new DatabaseChannel(this.config.database.table, _getConnection());
+    return this._dbChannel;
   }
 
   private async _dispatch(

package/src/drivers/LogDriver.ts

@@ -15,6 +15,10 @@ export class LogDriver implements MailDriver {
       `From:    ${message.from.name ? `${message.from.name} <${message.from.address}>` : message.from.address}`,
       `Subject: ${message.subject}`,
       ...(message.cc?.length ? [`CC:      ${message.cc.map((a) => a.address).join(", ")}`] : []),
+      // Printed because the reason to set one is that a mail client does
+      // something with it, and the log driver is where that gets checked before
+      // anything is sent for real.
+      ...Object.entries(message.headers ?? {}).map(([n, v]) => `${n}: ${v}`),
       ...(message.attachments?.length
         ? [
             `Files:   ${message.attachments

package/src/drivers/MailDriver.ts

@@ -36,6 +36,70 @@ export interface MailAttachment {
   cid?: string;
 }
 
+/**
+ * Header names a driver builds itself, which a custom header may not set.
+ *
+ * Two reasons, and both are about a message that arrives wrong rather than one
+ * that fails to send. `Content-Type`, `MIME-Version` and
+ * `Content-Transfer-Encoding` describe the body a driver is assembling — a second
+ * copy makes the structure ambiguous and clients disagree about which to believe.
+ * The rest already have a dedicated method on {@link MailMessage}; setting one
+ * here would duplicate the header rather than replace it, because the driver has
+ * no way to know which was meant.
+ *
+ * Compared case-insensitively — header names are not case-sensitive, so
+ * `content-type` has to be refused as readily as `Content-Type`.
+ */
+export const RESERVED_MAIL_HEADERS: readonly string[] = [
+  "bcc",
+  "cc",
+  "content-transfer-encoding",
+  "content-type",
+  "date",
+  "from",
+  "message-id",
+  "mime-version",
+  "reply-to",
+  "subject",
+  "to",
+];
+
+/**
+ * Custom headers, sanitised and checked against {@link RESERVED_MAIL_HEADERS}.
+ *
+ * @param headers - Header names to values, as written by the caller.
+ * @returns The same headers with CR and LF removed from every value.
+ * @throws When a name is reserved, or a name is not a legal header token.
+ */
+export function resolveHeaders(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const trimmed = name.trim();
+    if (RESERVED_MAIL_HEADERS.includes(trimmed.toLowerCase())) {
+      throw new Error(
+        `[Zerotal/notifications] "${trimmed}" is set by the mail driver and cannot be ` +
+          `passed as a custom header — it would be sent twice rather than replaced. ` +
+          `Use the MailMessage method for it (.subject(), .from(), .to(), .cc(), .bcc(), ` +
+          `.replyTo()) where there is one.`,
+      );
+    }
+    // RFC 5322 field names are printable ASCII except colon. A name carrying a
+    // colon, a space or a newline does not become a header — it becomes a way to
+    // write the rest of the message.
+    if (!/^[!-9;-~]+$/.test(trimmed)) {
+      throw new Error(
+        `[Zerotal/notifications] "${trimmed}" is not a valid header name — a header name is ` +
+          `printable ASCII with no spaces, colons or line breaks.`,
+      );
+    }
+    // CR/LF in a value ends the header and lets the remainder be read as further
+    // headers. Stripped rather than refused: unlike the name, a value is often
+    // built from content, and folding it to one line keeps the message intact.
+    out[trimmed] = value.replace(/[\r\n]+/g, " ").trim();
+  }
+  return out;
+}
+
 /** The resolved, ready-to-send shape of a single email. */
 export interface MailPayload {
   to: MailAddress[];
@@ -47,6 +111,25 @@ export interface MailPayload {
   bcc?: MailAddress[];
   replyTo?: MailAddress;
   attachments?: MailAttachment[];
+  /**
+   * Extra headers to put on the message, beyond the ones the driver builds.
+   *
+   * The reason this exists is `List-Unsubscribe`: Gmail and Yahoo draw their
+   * native unsubscribe control beside the sender from that header, and there is
+   * no way to ask for it other than sending it. A footer link is a different
+   * thing in a different place, and bulk senders are required to send the header.
+   *
+   * Names in {@link RESERVED_MAIL_HEADERS} are refused — see there for why.
+   *
+   * @example
+   * ```ts
+   * new MailMessage()
+   *   .subject("Your weekly digest")
+   *   .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>`)
+   *   .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+   * ```
+   */
+  headers?: Record<string, string>;
 }
 
 export interface MailDriver {

package/src/drivers/ResendDriver.ts

@@ -1,4 +1,5 @@
 import type { MailDriver, MailPayload } from "./MailDriver.ts";
+import { resolveHeaders } from "./MailDriver.ts";
 import { NotificationDeliveryError } from "../errors.ts";
 
 /**
@@ -21,6 +22,12 @@ export class ResendDriver implements MailDriver {
     if (message.cc?.length) body["cc"] = message.cc.map((a) => a.address);
     if (message.bcc?.length) body["bcc"] = message.bcc.map((a) => a.address);
     if (message.replyTo) body["reply_to"] = message.replyTo.address;
+    // Resend takes custom headers as an object and sets the rest itself, so the
+    // reserved names are refused here too rather than handed to the API to
+    // silently drop or duplicate.
+    if (message.headers && Object.keys(message.headers).length > 0) {
+      body["headers"] = resolveHeaders(message.headers);
+    }
     if (message.html !== undefined) body["html"] = message.html;
     if (message.text !== undefined) body["text"] = message.text;
     if (message.attachments?.length) {

package/src/drivers/SmtpDriver.ts

@@ -1,4 +1,5 @@
 import type { MailDriver, MailPayload, MailAddress } from "./MailDriver.ts";
+import { resolveHeaders } from "./MailDriver.ts";
 import { SmtpResponseError, SmtpConnectionError } from "../errors.ts";
 
 /** How long to wait for any single SMTP reply before giving up. */
@@ -616,6 +617,15 @@ function buildRawMessage(msg: MailPayload): string {
   );
   lines.push("MIME-Version: 1.0");
 
+  // Re-validated here, not just in `MailMessage.header()`, because a payload can
+  // reach a driver without ever passing through the builder — a job deserialising
+  // one, or an app constructing a MailPayload literal. Placing them after the
+  // headers this function owns would not be enough on its own: a second `Subject`
+  // is still a second `Subject`, wherever it sits.
+  for (const [name, value] of Object.entries(resolveHeaders(msg.headers ?? {}))) {
+    lines.push(`${name}: ${encodeHeaderValue(value)}`);
+  }
+
   const attachments = msg.attachments ?? [];
   const body = renderBody(msg);
 

package/src/index.ts

@@ -38,6 +38,10 @@ export type {
   MailAttachment,
   AddressInput,
 } from "./drivers/MailDriver.ts";
+// Exported for the same reason the drivers above are: writing a custom transport
+// is a supported thing to do, and a custom transport has to refuse the same header
+// names the built-in ones refuse.
+export { RESERVED_MAIL_HEADERS, resolveHeaders } from "./drivers/MailDriver.ts";
 
 export { SendNotificationJob } from "./SendNotificationJob.ts";
 export { BroadcastNotificationJob } from "./BroadcastNotificationJob.ts";

package/src/messages/MailMessage.ts

@@ -1,6 +1,7 @@
 import { tryCurrentApp } from "@zerotal/core";
 import {
   resolveAddress,
+  resolveHeaders,
   type AddressInput,
   type MailAddress,
   type MailAttachment,
@@ -165,6 +166,7 @@ export class MailMessage {
   private _from?: MailAddress;
   private _replyTo?: MailAddress;
   private _attachments: MailAttachment[] = [];
+  private _headers: Record<string, string> = {};
 
   subject(text: string): this {
     this._subject = text;
@@ -254,6 +256,44 @@ export class MailMessage {
     return this;
   }
 
+  /**
+   * Set a header on the message, beyond the ones the driver builds itself.
+   *
+   * The header this exists for is `List-Unsubscribe`. Gmail and Yahoo draw their
+   * native unsubscribe control — the one beside the sender's name, not the one in
+   * your footer — from that header, and there is no other way to ask for it. Bulk
+   * senders are required to send it; everyone else benefits from a recipient who
+   * unsubscribes instead of reporting spam, because the second one costs the
+   * sending domain its reputation and the first does not.
+   *
+   * Pair it with `List-Unsubscribe-Post` to get the one-click form, which is what
+   * both providers now expect: the header alone leaves the recipient a `mailto:`
+   * or a link to follow, and only the pair produces a button that resolves in one
+   * press.
+   *
+   * Header names the driver builds itself are refused rather than sent twice —
+   * see {@link RESERVED_MAIL_HEADERS}. Calling this twice with the same name
+   * replaces the value, since a driver cannot know which of two was meant.
+   *
+   * @param name - Header name. Printable ASCII, no spaces or colons.
+   * @param value - Header value. CR and LF are folded to a space.
+   * @throws When the name is reserved or malformed.
+   *
+   * @example
+   * ```ts
+   * new MailMessage()
+   *   .subject("Your weekly digest")
+   *   .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>, <mailto:unsub@app.test>`)
+   *   .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+   * ```
+   */
+  header(name: string, value: string): this {
+    // Validated here rather than at send time so the throw carries the stack of
+    // the code that wrote the header, not of a queue worker three hops away.
+    Object.assign(this._headers, resolveHeaders({ [name]: value }));
+    return this;
+  }
+
   /**
    * Attach a file to the message.
    *
@@ -321,6 +361,7 @@ export class MailMessage {
       ...(this._bcc.length > 0 ? { bcc: this._bcc } : {}),
       ...(this._replyTo ? { replyTo: this._replyTo } : {}),
       ...(this._attachments.length > 0 ? { attachments: this._attachments } : {}),
+      ...(Object.keys(this._headers).length > 0 ? { headers: this._headers } : {}),
     };
   }
 

package/src/provider/NotificationProvider.ts

@@ -7,6 +7,7 @@ import { installNotificationsObservability } from "../observability.ts";
 import { installNotificationStats } from "../stats.ts";
 import { installNotificationsAdmin } from "../admin.ts";
 import { mailDriverCheck } from "../doctor.ts";
+import { notificationsTableCheck } from "../tableDoctor.ts";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -40,6 +41,7 @@ export class NotificationProvider extends ServiceProvider {
     // `zt doctor`, and through it `zt deploy`: mail going to a log file in
     // production is the quietest failure this package has.
     this.app.registerDoctorCheck?.(mailDriverCheck);
+    this.app.registerDoctorCheck?.(notificationsTableCheck);
   }
 
   override async onBooted(): Promise<void> {

package/src/tableDoctor.ts

@@ -0,0 +1,92 @@
+/**
+ * The check for a `notifications` table that is not the framework's.
+ *
+ * `database.table` defaults to `notifications`, which is a very ordinary name for a
+ * table an app already owns. One app's was a completely different shape —
+ * `household_id`, `user_id`, `title`, `body`, `action_url`, with an in-app inbox
+ * reading it — and the only thing standing between the framework's channel and a
+ * wrong-shaped insert into that inbox was that no notification's `channels()`
+ * happened to return `"database"`.
+ *
+ * A convention holding back data corruption is a convention that will lose. This
+ * says so at `zt doctor` time, before the first notification does.
+ *
+ * @module
+ */
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import { NotificationConfig } from "./config.ts";
+import type { NotificationConfigShape } from "./types.ts";
+
+/** Columns `DatabaseChannel` writes on every insert. */
+const REQUIRED = [
+  "id",
+  "notifiable_type",
+  "notifiable_id",
+  "type",
+  "data",
+  "read_at",
+  "created_at",
+] as const;
+
+/** The table's column names, or `null` when it does not exist / cannot be read. */
+async function _columnsOf(sql: unknown, table: string): Promise<Set<string> | null> {
+  const query = sql as (strings: TemplateStringsArray, ...v: unknown[]) => Promise<unknown[]>;
+  try {
+    // `pragma_table_info` is the table-valued form, so the name binds as a parameter
+    // rather than being concatenated into the statement.
+    const rows = (await query`SELECT name FROM pragma_table_info(${table})`) as {
+      name?: string;
+    }[];
+    if (rows.length === 0) return null;
+    return new Set(rows.map((r) => String(r.name)));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Report a configured notifications table whose shape is not the one the channel
+ * writes.
+ *
+ * Silent when the table does not exist yet — that is the normal state before the
+ * migration runs, and warning about it would fire on every fresh checkout.
+ */
+export const notificationsTableCheck: DoctorCheck = {
+  id: "notifications-table",
+  label: "Notifications table",
+  async run(app: Application): Promise<DoctorCheckResult> {
+    let table = "notifications";
+    let sql: unknown;
+    try {
+      const config = app.container.makeSync("config") as { get<T>(k: string, d: T): T };
+      table = config.get<NotificationConfigShape>("notifications", NotificationConfig()).database
+        .table;
+      sql = app.container.makeSync("db");
+    } catch {
+      return { status: "ok", message: "no database connection to check" };
+    }
+    if (!sql) return { status: "ok", message: "no database connection to check" };
+
+    const columns = await _columnsOf(sql, table);
+    if (columns === null) {
+      // Not created yet, or not SQLite. Either way there is nothing to compare.
+      return { status: "ok", message: `${table} not present yet` };
+    }
+
+    const missing = REQUIRED.filter((name) => !columns.has(name));
+    if (missing.length === 0) return { status: "ok", message: `${table} matches` };
+
+    return {
+      status: "fail",
+      message:
+        `The table "${table}" exists but is missing ${missing.join(", ")} — so it is not the ` +
+        `table @zerotal/notifications writes, and a notification routed to the "database" ` +
+        `channel would insert the wrong shape into it.`,
+      fix:
+        `Point the framework elsewhere with database.table in config/notifications.ts ` +
+        `(e.g. "framework_notifications"), or run the package's migration to create the ` +
+        `table it expects.`,
+    };
+  },
+};