@zerotal/notifications 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,83 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [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
+
+- **SMTP submission on port 587 works.** The STARTTLS upgrade completed its handshake
+  and then sent nothing: `upgradeTLS()` returns the new socket while the handshake is
+  still in flight, and a write issued in that window is **dropped** — not buffered,
+  not an error, gone. The `EHLO` that has to follow STARTTLS went into that gap on
+  every send, so the server waited for a command that never came while the client
+  waited for a reply that never came, until the read timed out.
+
+  Everything either side looked healthy, which is what made it expensive: the server
+  logged a good TLS session and then a connection lost. Port 465 was unaffected,
+  because implicit TLS finishes before `Bun.connect()` resolves and there is no window
+  to write into — so mail worked on the port nobody documents, and configuring the 587
+  that every provider _does_ document produced silence. No error, no bounce, no log
+  line, and password resets that never arrived. `upgradeTLS()` now resolves only once
+  the handshake has completed, bounded by the reply timeout.
+
+- **TLS certificates are actually verified, on both transports.** `rejectUnauthorized`
+  is not enforced by the runtime: Bun reports `authorized: true` for a self-signed
+  certificate on `Bun.connect()` and on `upgradeTLS()` alike, whether the flag is set
+  or not, and puts the real reason in `authorizationError` beside it. Trusting the
+  flag made TLS decorative — the connection was encrypted, and would have accepted
+  that encryption from anyone in the network path, which is the one property TLS
+  exists to provide. The driver now reads the handshake result itself and fails
+  closed; `rejectUnauthorized: false` still accepts a self-signed relay, deliberately.
+
+- **The server greeting cannot be lost to a race.** `Bun.connect()` resolves after the
+  socket opens, and the 220 can arrive before the `await` returns — the data callback
+  reached for a connection object that did not exist yet. Early bytes are now buffered
+  and replayed.
+
+### Added
+
+- **A doctor check for a production `mail.driver` of `"log"`.** It is the default, it
+  is right in development, and it is the quietest possible production failure: every
+  message is written to a log file, nothing reports a problem, and password resets
+  stop arriving until someone asks why. `zt doctor` reports it and `zt deploy` refuses
+  on it.
+
+  Two tiers, because the same value means two things. An app with a real
+  `mail.from.address` configured `log` by accident, or had it knocked back, and its
+  mail is going nowhere — that fails. An app still on the placeholder address probably
+  sends no mail at all, and failing its deploy over a setting it never touched would be
+  the framework inventing a problem — that warns.
+
+### Testing
+
+- `SmtpSubmission.test.ts` runs the whole 587 flow against a real STARTTLS peer.
+  The existing tests could not: they upgrade into a peer that is already speaking TLS,
+  because Bun cannot be a STARTTLS _server_ — and the bug lived in the one step that
+  arrangement skips. The fixture peer runs under Node, which can wrap a connected
+  socket as a TLS server. The limitation was the harness's, never the client's.
+
 ## [1.9.0] — 2026-08-29
 
 ### Documented

package/api-surface.md

@@ -375,8 +375,8 @@ interface NotificationChannel = {
 interface NotificationConfigShape = {
   database: {    table: string;}
   mail: MailConfigShape
-  slack?: {    webhook?: string;}
-  sms?: SmsConfigShape
+  slack?: {    webhook?: string;} | undefined
+  sms?: SmsConfigShape | undefined
 }
 
 interface NotificationRecord = {
@@ -415,8 +415,8 @@ interface SlackMessage = {
 
 interface SmsConfigShape = {
   driver: 'twilio' | 'vonage'
-  twilio?: TwilioConfigShape
-  vonage?: VonageConfigShape
+  twilio?: TwilioConfigShape | undefined
+  vonage?: VonageConfigShape | undefined
 }
 
 interface SmsMessage = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0",
-    "@zerotal/orm": "1.9.0",
-    "@zerotal/queue": "1.9.0"
+    "@zerotal/core": "1.11.0",
+    "@zerotal/orm": "1.11.0",
+    "@zerotal/queue": "1.11.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.9.0",
+    "@zerotal/broadcasting": "1.11.0",
     "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/doctor.ts

@@ -0,0 +1,74 @@
+/**
+ * The deployment check `zt doctor` and `zt deploy` run against the mail config.
+ *
+ * `mail.driver` defaults to `"log"`, which is right in development and is the
+ * quietest possible production failure: every message is written to a log file and
+ * nothing anywhere reports a problem. No error, no bounce, no send — just password
+ * resets that never arrive, found days later by someone asking why.
+ *
+ * @module
+ */
+import { deployEnv, isProdLike } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import { NotificationConfig } from "./config.ts";
+import type { NotificationConfigShape } from "./types.ts";
+
+/**
+ * The from-address a project that never configured mail still has.
+ *
+ * It is what tells "this app does not send mail" apart from "this app sends mail
+ * and its driver got knocked back to the default", which are the same setting and
+ * very different problems. Anyone who set up mail changed this.
+ */
+const PLACEHOLDER_FROM = "hello@example.com";
+
+/** The loaded notification config, or the defaults when the app declares none. */
+function _mailConfig(app: Application): NotificationConfigShape["mail"] | undefined {
+  try {
+    const config = app.container.makeSync("config") as {
+      get<T>(key: string, fallback: T): T;
+    };
+    return config.get<NotificationConfigShape>("notifications", NotificationConfig()).mail;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Refuse a production release whose mail goes to a log file.
+ *
+ * Two tiers, because the same value means two things. An app with a real
+ * from-address configured `log` by accident — or had it knocked back — and its mail
+ * is silently going nowhere: that fails. An app still on the placeholder address
+ * probably sends no mail at all, and failing its deploy over a setting it never
+ * touched would be the framework inventing a problem: that warns.
+ */
+export const mailDriverCheck: DoctorCheck = {
+  id: "mail-driver",
+  label: "Mail driver",
+  run(app: Application): DoctorCheckResult {
+    const mail = _mailConfig(app);
+    if (!mail) return { status: "ok", message: "no mail config to check" };
+
+    if (mail.driver !== "log") {
+      return { status: "ok", message: `${mail.driver}` };
+    }
+
+    if (!isProdLike(deployEnv())) {
+      return { status: "ok", message: "log (fine outside production)" };
+    }
+
+    const configured = mail.from.address !== PLACEHOLDER_FROM;
+    return {
+      status: configured ? "fail" : "warn",
+      message: configured
+        ? `mail.driver is "log" in production, but mail.from.address is set to ` +
+          `${mail.from.address} — every message this app sends is being written to a ` +
+          `log file and delivered to nobody.`
+        : `mail.driver is "log" in production. Nothing is delivered. ` +
+          `(mail.from.address is still the default, so this app may not send mail at all.)`,
+      fix: 'Set mail.driver to "smtp" or "resend" in config/notifications.ts, and its credentials with it.',
+    };
+  },
+};

package/src/drivers/SmtpDriver.ts

@@ -19,6 +19,12 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  * Every reply is parsed and its status code checked, so a rejected recipient or a
  * failed authentication raises {@link SmtpResponseError} instead of being
  * mistaken for a successful send.
+ *
+ * Certificate verification is enforced here rather than by the runtime. Bun does
+ * not honour `rejectUnauthorized` on either `Bun.connect()` or `upgradeTLS()` — it
+ * reports the peer as authorized and puts the real reason beside it — so both
+ * transports check the handshake result themselves and fail closed. See
+ * `_certificateFailure`.
  */
 export class SmtpDriver implements MailDriver {
   constructor(
@@ -142,6 +148,34 @@ interface SmtpReply {
   text: string;
 }
 
+/**
+ * Whether a completed handshake should be treated as a failure.
+ *
+ * **`rejectUnauthorized` is not enforced by the runtime.** Bun reports
+ * `authorized: true` for a self-signed certificate whether the flag is on or off,
+ * on `Bun.connect()` and on `upgradeTLS()` alike, and hands back the real reason in
+ * `authorizationError` beside it. Trusting the flag made TLS decorative on both
+ * paths: the connection was encrypted and would have accepted that encryption from
+ * anyone in the network path, which is the property TLS exists to provide.
+ *
+ * So the error is the signal and the flag is not. Verification is the framework's
+ * to enforce, and it fails closed.
+ *
+ * @param authorized - What the runtime claims about the peer.
+ * @param authorizationError - Why it would not have been authorized, if anything.
+ * @param rejectUnauthorized - Whether this connection asked for verification.
+ * @returns The error to fail with, or `undefined` to accept the peer.
+ */
+function _certificateFailure(
+  authorized: boolean,
+  authorizationError: Error | null | undefined,
+  rejectUnauthorized: boolean,
+): Error | undefined {
+  if (!rejectUnauthorized) return undefined;
+  if (authorized && !authorizationError) return undefined;
+  return authorizationError ?? new Error("the server's certificate could not be verified");
+}
+
 /**
  * A single SMTP session — owns the socket, buffers incoming bytes, and hands
  * back one complete reply at a time.
@@ -210,9 +244,26 @@ export class SmtpConnection {
     port: number,
     options: { tls: boolean; rejectUnauthorized: boolean; timeoutMs: number },
   ): Promise<SmtpConnection> {
-    let conn!: SmtpConnection;
+    // The session, once there is one. A box rather than a bare `let`, because the
+    // socket callbacks below are installed before it exists and have to see it
+    // appear — `Bun.connect()` resolves after the socket is open, so the server's
+    // 220 greeting can beat the `await` that produces it.
+    const session: { conn?: SmtpConnection } = {};
+
+    // Bytes that arrive in that window. Dropping the greeting deadlocks the session
+    // on its own first read.
+    const early: Uint8Array[] = [];
+
+    let settle: (error?: Error) => void = () => {};
+    const verified = options.tls
+      ? new Promise<void>((resolve, reject) => {
+          settle = (error) => (error ? reject(error) : resolve());
+        })
+      : undefined;
+
+    let socket: import("bun").Socket<undefined>;
     try {
-      const socket = await Bun.connect<undefined>({
+      socket = await Bun.connect<undefined>({
         hostname: host,
         port,
         ...(options.tls
@@ -220,14 +271,23 @@ export class SmtpConnection {
           : {}),
         socket: {
           // Generation 0: the connection as opened. An upgrade supersedes it.
-          data: (_s, data) => conn._onData(data, 0),
-          error: (_s, err) => conn._onError(err, 0),
-          close: () => conn._onClose(0),
+          data: (_s, data) => {
+            if (session.conn) session.conn._onData(data, 0);
+            else early.push(data);
+          },
+          error: (_s, err) => {
+            settle(err);
+            session.conn?._onError(err, 0);
+          },
+          close: () => {
+            settle(new Error("the server closed the connection during the TLS handshake"));
+            session.conn?._onClose(0);
+          },
+          handshake: (_s, authorized, authorizationError) =>
+            settle(_certificateFailure(authorized, authorizationError, options.rejectUnauthorized)),
           open: () => {},
         },
       });
-      conn = new SmtpConnection(socket, host, port, options.timeoutMs, options.tls);
-      return conn;
     } catch (error) {
       throw new SmtpConnectionError(
         `Could not connect to SMTP server ${host}:${port} — ${
@@ -235,20 +295,78 @@ export class SmtpConnection {
         }`,
       );
     }
+
+    const conn = new SmtpConnection(socket, host, port, options.timeoutMs, options.tls);
+    session.conn = conn;
+    for (const chunk of early) conn._onData(chunk, 0);
+
+    // Implicit TLS (465) verifies here, for the same reason STARTTLS verifies in
+    // `upgradeTLS`: `rejectUnauthorized` is not enforced by the runtime, so a
+    // connection that asked for a verified certificate has to check that it got one.
+    if (verified) {
+      try {
+        await conn._withTimeout(verified, `completing the TLS handshake with ${host}`);
+      } catch (error) {
+        conn.close();
+        throw new SmtpConnectionError(
+          `TLS connection to ${host}:${port} failed — ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+
+    return conn;
   }
 
-  /** Upgrade a plaintext connection to TLS after a 220 response to STARTTLS. */
+  /**
+   * Upgrade a plaintext connection to TLS after a 220 response to STARTTLS.
+   *
+   * Resolves once the handshake has actually completed, and that is the whole
+   * point of it being async. `upgradeTLS()` returns the new socket immediately,
+   * while the handshake is still in flight, and **a write issued in that window is
+   * dropped** — not buffered and flushed, not an error, just gone. The `EHLO` that
+   * has to follow STARTTLS was written into that gap, so the server sat waiting
+   * for a command that was never sent while the client sat waiting for a reply
+   * that was never coming, until the read timed out thirty seconds later.
+   *
+   * What made it expensive to place is that everything either side looks right.
+   * The handshake completes; the server logs a healthy TLS session and then a
+   * connection lost. Port 465 is unaffected, because implicit TLS finishes its
+   * handshake before `Bun.connect()` resolves and there is no window to write
+   * into. So mail worked, on the port that is not the one every provider
+   * documents, and configuring the documented 587 produced silence — no error, no
+   * bounce, no log line, just password resets that never arrived.
+   *
+   * @param host - Hostname, used as the TLS server name.
+   * @param rejectUnauthorized - Refuse a certificate that does not verify.
+   * @throws {@link SmtpConnectionError} When the upgrade or the handshake fails.
+   */
   async upgradeTLS(host: string, rejectUnauthorized: boolean): Promise<void> {
     try {
       // Bumped before the call, so the plaintext socket's callbacks are already
       // stale by the time the handshake can deliver its first record.
       const generation = ++this._generation;
+
+      let settle!: (error?: Error) => void;
+      const handshake = new Promise<void>((resolve, reject) => {
+        settle = (error) => (error ? reject(error) : resolve());
+      });
+
       const [, tls] = this._socket.upgradeTLS<undefined>({
         tls: { rejectUnauthorized, serverName: host },
         socket: {
           data: (_s, data) => this._onData(data, generation),
-          error: (_s, err) => this._onError(err, generation),
-          close: () => this._onClose(generation),
+          error: (_s, err) => {
+            settle(err);
+            this._onError(err, generation);
+          },
+          close: () => {
+            settle(new Error("the server closed the connection during the TLS handshake"));
+            this._onClose(generation);
+          },
+          handshake: (_s, authorized, authorizationError) =>
+            settle(_certificateFailure(authorized, authorizationError, rejectUnauthorized)),
           open: () => {},
         },
       });
@@ -258,6 +376,8 @@ export class SmtpConnection {
       // belongs to the discarded plaintext stream.
       this._buffer = "";
       this._replies = [];
+
+      await this._withTimeout(handshake, `completing the TLS handshake with ${host}`);
     } catch (error) {
       throw new SmtpConnectionError(
         `STARTTLS upgrade failed for ${host} — ${
@@ -267,6 +387,33 @@ export class SmtpConnection {
     }
   }
 
+  /**
+   * Reject `work` if it has not settled within the session's reply timeout.
+   *
+   * A handshake that never completes and never errors is a hang with no reply to
+   * time out on, so the read timeout that covers every other step does not cover
+   * this one.
+   *
+   * @param work - The promise to bound.
+   * @param what - Named in the timeout message.
+   */
+  private async _withTimeout<T>(work: Promise<T>, what: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race([
+        work,
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`timed out after ${this._timeoutMs}ms ${what}`)),
+            this._timeoutMs,
+          );
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   /** Write a command plus its CRLF terminator. */
   send(command: string): void {
     this.write(`${command}\r\n`);

package/src/provider/NotificationProvider.ts

@@ -6,6 +6,8 @@ import { NotificationConfig } from "../config.ts";
 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 {
@@ -35,6 +37,11 @@ export class NotificationProvider extends ServiceProvider {
     // The admin panel binds its contribution surface during registration, so the
     // booting phase reaches it regardless of provider order.
     installNotificationsAdmin(this.app);
+
+    // `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.`,
+    };
+  },
+};

package/src/types.ts

@@ -98,8 +98,8 @@ export interface VonageConfigShape {
 
 export interface SmsConfigShape {
   driver: "twilio" | "vonage";
-  twilio?: TwilioConfigShape;
-  vonage?: VonageConfigShape;
+  twilio?: TwilioConfigShape | undefined;
+  vonage?: VonageConfigShape | undefined;
 }
 
 export interface NotificationConfigShape {
@@ -117,13 +117,15 @@ export interface NotificationConfigShape {
    * The per-notification toSlack() method provides the webhookUrl, so this is
    * only needed if you want a global fallback URL.
    */
-  slack?: {
-    /** Default webhook URL — can be overridden per-notification in toSlack(). */
-    webhook?: string;
-  };
+  slack?:
+    | {
+        /** Default webhook URL — can be overridden per-notification in toSlack(). */
+        webhook?: string;
+      }
+    | undefined;
   /**
    * SMS provider settings (Twilio or Vonage).
    * Required when any notification uses the 'sms' channel.
    */
-  sms?: SmsConfigShape;
+  sms?: SmsConfigShape | undefined;
 }