@stacksjs/types 0.70.45 → 0.70.53

package/dist/search-engine.d.ts

@@ -24,7 +24,7 @@ export type {
 // type Sorts = any
 // type Sort = any
 export declare interface SearchEngineOptions {
-  driver: 'meilisearch' | 'algolia' | 'opensearch'
+  driver: 'meilisearch' | 'algolia' | 'opensearch' | 'typesense'
   opensearch?: {
     host: string
     protocol: number
@@ -43,6 +43,12 @@ export declare interface SearchEngineOptions {
     apiKey: string
     searchOnlyApiKey?: string
   }
+  typesense?: {
+    host?: string
+    port?: number
+    protocol?: string
+    apiKey?: string
+  }
   filters?: {
     [key: string]: string
   }
@@ -118,5 +124,6 @@ export declare interface SearchOptions {
   sortable: string[]
   filterable: string[]
   options?: SearchEngineOptions
+  denormalize?: Record<string, string>
 }
 export type SearchEngineConfig = Partial<SearchEngineOptions>;

package/dist/services.d.ts

@@ -21,6 +21,14 @@ export declare interface ServicesOptions {
     redirectUrl: string
     scopes?: string[]
   }
+  apple?: {
+    clientId: string
+    teamId: string
+    keyId: string
+    privateKey: string
+    redirectUrl: string
+    scopes?: string[]
+  }
   facebook?: {
     clientId: string
     clientSecret: string
@@ -134,6 +142,7 @@ export declare interface ServicesOptions {
   stripe?: {
     secretKey?: string
     publicKey?: string
+    webhookSecret?: string
     apiVersion?: string
   }
 }

package/dist/stacks.d.ts

@@ -1,4 +1,4 @@
-import type { AiConfig, AnalyticsConfig, AppConfig, AuthConfig, BinaryConfig, CacheConfig, CloudConfig, DashboardConfig, DatabaseConfig, DnsConfig, DocsConfig, EmailConfig, ErrorConfig, FilesystemsConfig, GitConfig, HashingConfig, LibraryConfig, LoggingConfig, NotificationConfig, PaymentConfig, Ports, QueueConfig, RealtimeConfig, SaasConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, Team, UiConfig } from '.';
+import type { AiConfig, AnalyticsConfig, AppConfig, AuthConfig, BinaryConfig, CacheConfig, CloudConfig, CmsConfig, CommerceConfig, CorsConfig, DashboardConfig, DatabaseConfig, DnsConfig, DocsConfig, EmailConfig, ErrorConfig, FilesystemsConfig, GitConfig, HashingConfig, LibraryConfig, LoggingConfig, MarketingConfig, MonitoringConfig, NotificationConfig, PaymentConfig, Ports, QueueConfig, RealtimeConfig, SaasConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, Team, UiConfig } from '.';
 /**
  * **Stacks Options**
  *
@@ -11,10 +11,13 @@ export declare interface StacksOptions {
   analytics: AnalyticsConfig
   app: AppConfig
   auth: AuthConfig
+  cors?: CorsConfig
   realtime: RealtimeConfig
   cache: CacheConfig
   cli: BinaryConfig
   cloud: CloudConfig
+  cms: CmsConfig
+  commerce: CommerceConfig
   dashboard: DashboardConfig
   database: DatabaseConfig
   dns: DnsConfig
@@ -25,6 +28,8 @@ export declare interface StacksOptions {
   hashing: HashingConfig
   library: LibraryConfig
   logging: LoggingConfig
+  marketing: MarketingConfig
+  monitoring: MonitoringConfig
   notification: NotificationConfig
   payment: PaymentConfig
   ports: Ports

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/types",
   "type": "module",
-  "version": "0.70.45",
+  "version": "0.70.53",
   "description": "The Stacks framework types.",
   "author": "Chris Breuer",
   "contributors": [
@@ -45,12 +45,12 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/bunpress": "^0.1.4",
-    "@stacksjs/ts-validation": "^0.4.10",
-    "bun-query-builder": "^0.1.21"
+    "@stacksjs/bunpress": "^0.1.11",
+    "@stacksjs/ts-validation": "^0.5.0",
+    "bun-query-builder": "^0.1.38"
   },
   "devDependencies": {
-    "@stacksjs/validation": "^0.70.45",
+    "@stacksjs/validation": "0.70.53",
     "@types/bun": "^1.3.11",
     "typescript": "^5.9.3"
   },

package/src/auth.ts

@@ -1,4 +1,12 @@
 export interface AuthOptions {
+  /**
+   * Top-level feature gate. When `false`, the auth feature is inert at boot
+   * (no token/password-reset/email-verification flows wired up). Missing or
+   * `true` means auth is on.
+   */
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
   /**
    * The default authentication guard to use
    */
@@ -90,6 +98,37 @@ export interface AuthOptions {
      * @default 60
      */
     throttle: number
+
+    /**
+     * Reset-link URL template. Supports `{token}` and `{email}`
+     * placeholders. Absolute templates (`https://…`) are used as-is;
+     * path templates are prefixed with the app URL. Lets apps whose
+     * reset page lives on a custom route reuse `passwordResets().sendEmail()`
+     * instead of hand-rolling the send.
+     * @default '/password/reset/{token}?email={email}'
+     */
+    url?: string
+  }
+
+  /**
+   * Email verification configuration
+   */
+  emailVerification?: {
+    /**
+     * Token expiration time in minutes
+     * @default 60
+     */
+    expire?: number
+
+    /**
+     * Verification-link URL template. Supports `{id}` and `{token}`
+     * placeholders. Absolute templates (`https://…`) are used as-is;
+     * path templates are prefixed with the app URL. Lets apps whose
+     * verify page lives on a custom route reuse `sendVerificationEmail()`
+     * instead of hand-rolling the send.
+     * @default '/verify-email/{id}/{token}'
+     */
+    url?: string
   }
 }
 

package/src/cache.ts

@@ -6,11 +6,15 @@ export interface CacheOptions {
    * **Cache Driver**
    *
    * The cache driver that will be used by your application to store
-   * cached data. Supports 'memory' and 'redis' drivers.
+   * cached data. Supports 'memory', 'redis', and 'singlestore' drivers.
+   *
+   * The 'singlestore' driver persists cache entries in a SingleStore
+   * rowstore table (with epoch-based TTL) — useful when you want a single
+   * SingleStore cluster to back both your primary data and your cache.
    *
    * @default "memory"
    */
-  driver: 'memory' | 'redis'
+  driver: 'memory' | 'redis' | 'singlestore'
 
   /**
    * **Cache Prefix**
@@ -117,6 +121,49 @@ export interface CacheOptions {
        */
       deleteOnExpire?: boolean
     }
+
+    singlestore?: {
+      /**
+       * SingleStore host (MySQL wire protocol)
+       * @default "127.0.0.1"
+       */
+      host?: string
+
+      /**
+       * SingleStore port
+       * @default 3306
+       */
+      port?: number
+
+      /**
+       * SingleStore username
+       * @default "root"
+       */
+      username?: string
+
+      /**
+       * SingleStore password
+       */
+      password?: string
+
+      /**
+       * Database that holds the cache table
+       * @default "stacks"
+       */
+      database?: string
+
+      /**
+       * Table used to store cache entries
+       * @default "stacks_cache"
+       */
+      table?: string
+
+      /**
+       * Enable TLS (required by managed SingleStore / Helios)
+       * @default false
+       */
+      ssl?: boolean
+    }
   }
 }
 

package/src/cli.ts

@@ -238,6 +238,7 @@ export type CreateBooleanOption =
   | 'functions'
   | 'api'
   | 'database'
+  | 'minimal'
 export type CreateOptions = {
   [key in CreateBooleanOption]: boolean
 } & {

package/src/cms.ts

@@ -0,0 +1,14 @@
+/**
+ * **CMS Options**
+ *
+ * Top-level feature gate plus any future CMS-wide settings. The CMS bundle
+ * (Post / Page / Author / Comment / Tag / Category models + edit dashboards)
+ * stays inert at boot when `enabled` is `false`.
+ */
+export interface CmsOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+}
+
+export type CmsConfig = Partial<CmsOptions>

package/src/commerce.ts

@@ -0,0 +1,18 @@
+/**
+ * **Commerce Options**
+ *
+ * Top-level feature gate plus storefront defaults. The commerce bundle
+ * (Order / Cart / Product / Customer / Coupon / GiftCard / Shipping models +
+ * storefront API) stays inert at boot when `enabled` is `false`.
+ */
+export interface CommerceOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+  /** Default storefront currency (ISO 4217), e.g. `'USD'`. */
+  currency?: string
+  /** Default tax rate applied when no product/region rule overrides. */
+  defaultTaxRate?: number
+}
+
+export type CommerceConfig = Partial<CommerceOptions>

package/src/cors.ts

@@ -0,0 +1,86 @@
+/**
+ * CORS configuration types (stacksjs/stacks#1859 H-2).
+ *
+ * Lives in `@stacksjs/types` so userland `config/cors.ts` files can
+ * `import type { CorsConfig } from '@stacksjs/types'` and get full
+ * IntelliSense, and so the Cors middleware can read
+ * `config.cors` with proper typing instead of an `as any` cast.
+ */
+
+/**
+ * Raw CORS configuration — every field optional. Defaults fill in
+ * any field that's missing when the middleware resolves config.
+ *
+ * @example
+ * ```ts
+ * // config/cors.ts
+ * import type { CorsConfig } from '@stacksjs/types'
+ *
+ * export default {
+ *   origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   credentials: true,
+ *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *   allowedHeaders: ['Content-Type', 'Authorization', 'X-CSRF-Token'],
+ *   maxAge: 600,
+ * } satisfies CorsConfig
+ * ```
+ */
+export interface CorsConfig {
+  /**
+   * Allowed origins.
+   *
+   * - `'*'` permits any origin (incompatible with `credentials: true`).
+   * - A string array enumerates the explicit allow-list; the request's
+   *   `Origin` header is reflected verbatim when it matches.
+   * - A predicate function lets you implement dynamic allow-lists
+   *   (e.g. wildcards, regex, environment-dependent).
+   */
+  origin?: '*' | string[] | ((origin: string) => boolean)
+
+  /**
+   * HTTP methods the server accepts cross-origin. Echoed back in
+   * preflight `Access-Control-Allow-Methods` responses.
+   */
+  methods?: string[]
+
+  /**
+   * Request headers the browser is allowed to send cross-origin.
+   * Echoed back in preflight `Access-Control-Allow-Headers` responses.
+   */
+  allowedHeaders?: string[]
+
+  /**
+   * Response headers the browser is allowed to expose to JS via
+   * `fetch(...).then(r => r.headers.get(...))`. Anything not listed
+   * here is hidden from the SPA even though it's on the wire.
+   */
+  exposedHeaders?: string[]
+
+  /**
+   * Whether cookies / Authorization headers may be included
+   * cross-origin. **Setting this to `true` is incompatible with
+   * `origin: '*'`** — the spec requires an explicit origin.
+   */
+  credentials?: boolean
+
+  /**
+   * How long the browser may cache the preflight response, in
+   * seconds. Default 86_400 (24h). Lower values cost more preflights
+   * but pick up policy changes faster.
+   */
+  maxAge?: number
+}
+
+/**
+ * Resolved CORS configuration with all defaults applied. This is the
+ * shape the middleware passes through `applyCorsHeaders` /
+ * `buildPreflightResponse`.
+ */
+export interface ResolvedCorsConfig {
+  origin: '*' | string[] | ((origin: string) => boolean)
+  methods: string[]
+  allowedHeaders: string[]
+  exposedHeaders: string[]
+  credentials: boolean
+  maxAge: number
+}

package/src/dashboard.ts

@@ -12,6 +12,14 @@
  * row when there's no newsletter without losing the model viewer.
  */
 export interface DashboardOptions {
+  /**
+   * Top-level feature gate. When `false`, the entire admin SPA + dashboard
+   * routes stay un-registered at boot. Missing or `true` keeps the dashboard
+   * on — the framework default, since every Stacks app wants it.
+   */
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
   /** Per-section visibility toggles. Omit a section to leave it enabled. */
   sections?: {
     library?: { enabled?: boolean }
@@ -35,6 +43,176 @@ export interface DashboardOptions {
       allModels?: { enabled?: boolean }
     }
   }
+  /**
+   * CI tracking surface — GitHub Actions health across the configured orgs.
+   * Ports the standalone `repo-dashboard` app into the dashboard
+   * (stacksjs/stacks#1844). Defaults to off because most projects don't
+   * own multiple GitHub orgs; opt in by listing orgs and surfacing a
+   * `GITHUB_TOKEN` in the environment.
+   */
+  ci?: {
+    enabled?: boolean
+    /** Orgs whose repos appear as per-tab CI cards. */
+    orgs?: string[]
+    /** Self-hosted runner caps per org. Defaults to {@link runnerCapDefault}. */
+    runnerCaps?: Record<string, number>
+    /** Fallback cap for orgs missing from `runnerCaps`. Defaults to 20. */
+    runnerCapDefault?: number
+    /** Repo names to exclude from the CI feed. */
+    ignoreRepos?: string[]
+    /**
+     * Failing-CI notification fan-out (stacksjs/stacks#1849).
+     *
+     * When enabled, the dashboard fires a notification through the
+     * configured channels every time a repo's CI transitions from
+     * success → failure (or first-time-seen → failure). Sticky-red
+     * repos don't keep firing; same-run-id polls don't re-fire; a
+     * 5-minute cooldown silences flap-storms.
+     */
+    notifications?: {
+      enabled?: boolean
+      /**
+       * Channels to fan out through. Maps to the same values
+       * `notify()` from @stacksjs/notifications accepts. Defaults to
+       * `['chat']` — Slack via webhook — because that channel
+       * doesn't need a recipient list (it's already scoped to a
+       * Slack channel via env).
+       */
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      /**
+       * Per-channel recipients for the channels that need one
+       * (email/sms/database). Skipped for `chat`. Each entry must
+       * carry the field the named channel requires (`email`,
+       * `phone`, `userId`).
+       */
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      /**
+       * Minimum delay (minutes) between consecutive notifications for
+       * the same repo. Defaults to 5. Set to 0 to disable.
+       */
+      cooldownMinutes?: number
+    }
+    /**
+     * Runner-pressure alerts (stacksjs/stacks#1850).
+     *
+     * When an org's queued-job count stays at or above
+     * `queuedThreshold` for `windowMinutes`, the dashboard fires a
+     * notification through the configured channels. Hysteresis: an
+     * already-alerting org doesn't re-fire until the queue drops
+     * below threshold for a full window first.
+     */
+    alerts?: {
+      enabled?: boolean
+      /** Queue depth at or above counts as pressure. Defaults to 8. */
+      queuedThreshold?: number
+      /** Duration the threshold must hold in either direction before
+       *  the alert fires / clears. Defaults to 10 minutes. */
+      windowMinutes?: number
+      /** Same channel options as {@link notifications.channels}. */
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      /** Same recipient shape as {@link notifications.recipients}. */
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      /**
+       * How long the runner-sample time-series is kept on disk.
+       * Older samples are pruned during each refresh to bound
+       * storage. Defaults to 24h.
+       */
+      retentionHours?: number
+    }
+  }
 }
 
 export type DashboardConfig = Partial<DashboardOptions>
+
+/**
+ * Per-model dashboard configuration (stacksjs/stacks#1843).
+ *
+ * Attach to a model definition to influence how the model surfaces in the
+ * dashboard sidebar without touching the framework's dashboard internals:
+ *
+ * ```ts
+ * defineModel({
+ *   name: 'AuditLog',
+ *   table: 'audit_logs',
+ *   dashboard: {
+ *     section: 'management',
+ *     icon: 'shield',
+ *     roles: ['admin'],
+ *     description: 'Append-only audit trail (admin-only)',
+ *   },
+ *   attributes: { … },
+ * })
+ * ```
+ *
+ * Resolution chain (most specific → fallback):
+ *
+ *   1. `dashboard.enabled === false` → model is hidden from the sidebar
+ *      entirely. The dynamic ORM viewer (`/models/<id>`) still works for
+ *      direct navigation, but the row is suppressed.
+ *   2. `dashboard.section` → pins the model to that section, overriding
+ *      the path-based auto-categorisation (commerce/, Content/, etc.).
+ *   3. `dashboard.label` / `dashboard.icon` → display overrides; fall back
+ *      to the model name and `iconMap` lookup.
+ *   4. `dashboard.roles` → role-gates the sidebar row. The server-side
+ *      sidebar builder emits the row with role metadata; the client filters
+ *      it out for users who lack a matching role. Permissive default
+ *      (unauthenticated viewers see everything — see `useRole.ts`).
+ */
+export interface DashboardModelOptions {
+  /**
+   * Hide this model from the dashboard sidebar entirely. Direct
+   * navigation to `/models/<id>` still works — this only suppresses the
+   * sidebar row.
+   *
+   * Defaults to `true` (model is shown).
+   */
+  enabled?: boolean
+
+  /**
+   * Override the display name in the sidebar. Defaults to the model name.
+   */
+  label?: string
+
+  /**
+   * Override the icon. Defaults to the auto-derived one in `iconMap`.
+   * The string is whatever the active sidebar icon set expects
+   * (e.g., SF Symbol name for the native sidebar; Lucide-style name for
+   * the web sidebar).
+   */
+  icon?: string
+
+  /**
+   * Pin this model to a specific sidebar section instead of the
+   * auto-derived category. Useful when a "logs" model lives under
+   * `app/Models/` (userland) but should appear under Management rather
+   * than Data.
+   */
+  section?:
+    | 'home'
+    | 'library'
+    | 'content'
+    | 'commerce'
+    | 'marketing'
+    | 'analytics'
+    | 'management'
+    | 'utilities'
+    | 'data'
+    | 'app'
+
+  /**
+   * Role-gate the sidebar row. The row is rendered server-side with
+   * `data-required-roles="…"`; the client filters it out via
+   * `useRole()` if the viewer doesn't hold any of the listed roles.
+   *
+   * The dev-mode default in `useRole()` means unauthenticated viewers
+   * (e.g., the local dev dashboard) see role-gated rows as if they
+   * were a dev — see `composables/useRole.ts` for the full chain.
+   */
+  roles?: string[]
+
+  /**
+   * Short tooltip / hover description for the sidebar row. Optional —
+   * sidebars that don't support tooltips ignore it.
+   */
+  description?: string
+}

package/src/database.ts

@@ -13,6 +13,20 @@ export interface DatabaseOptions {
       prefix?: string
     }
 
+    // SingleStore is MySQL wire-compatible (port 3306); it shares MySQL's
+    // connection shape and adds an optional `ssl` flag for managed (Helios)
+    // endpoints, which require TLS.
+    singlestore?: {
+      url?: string
+      host?: string
+      port?: number
+      name?: string
+      username?: string
+      password?: string
+      prefix?: string
+      ssl?: boolean
+    }
+
     sqlite: {
       url?: string
       database?: string

package/src/email.ts

@@ -277,6 +277,23 @@ export interface EmailOptions {
   }
 
   mailboxes: string[] | MailboxConfig[]
+
+  /**
+   * Auto-forwarding rules for received mail, provisioned to the mail server's
+   * readable `forwards.json` (re-read on every message — edits take effect
+   * with no restart).
+   *
+   * Key   = the delivered mailbox: the full address for a per-domain isolated
+   *         mailbox (e.g. `'no-reply@acme.com'`), or a bare local-part for a
+   *         legacy role mailbox (e.g. `'postmaster'`).
+   * Value = destination addresses. Targets on a local domain are written
+   *         straight to that mailbox's Maildir; external targets are relayed.
+   *         A copy also stays in the source mailbox.
+   *
+   * @example { 'no-reply@acme.com': ['chris@acme.com'] }
+   */
+  forwards?: Record<string, string[]>
+
   domain?: string
 
   url: string
@@ -286,6 +303,30 @@ export interface EmailOptions {
   notifications?: EmailNotificationsConfig
 
   default: 'log' | 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp'
+
+  /**
+   * Suppression-list enforcement policy (stacksjs/stacks#1880).
+   *
+   * - `'strict'`                — block all sends to suppressed
+   *   recipients (default)
+   * - `'transactional-allowed'` — block broadcasts; allow messages
+   *   with `tag: 'transactional'`
+   * - `'off'`                   — never block; the suppression
+   *   table is just a tracking record
+   *
+   * The check is opt-in at the table level — apps that haven't
+   * created the `email_suppressions` table see "always allowed"
+   * with a one-shot warn.
+   */
+  suppressionPolicy?: 'strict' | 'transactional-allowed' | 'off'
+
+  /**
+   * URL prefix the framework's default unsubscribe route mounts
+   * under (stacksjs/stacks#1880). Defaults to
+   * `/_stacks/email/unsubscribe`. The full link is built as
+   * `${app.url}${unsubscribeRoute}/${signed-token}`.
+   */
+  unsubscribeRoute?: string
 }
 
 export type EmailConfig = Partial<EmailOptions>
@@ -340,6 +381,17 @@ export interface EmailMessage {
   cc?: string | string[] | EmailAddress[]
   /** Blind carbon copy recipient(s) */
   bcc?: string | string[] | EmailAddress[]
+  /**
+   * Reply-To address(es) for the outgoing message.
+   *
+   * Drivers must propagate this to the provider's equivalent field
+   * (`ReplyToAddresses` on SES, `h:Reply-To` on Mailgun, `reply_to` on
+   * SendGrid, a `Reply-To:` header for SMTP). Previously the field
+   * lived as an `as any` stash on the message (stacksjs/stacks#1871 M-4)
+   * — promoting it to a first-class slot means drivers can be
+   * checked at compile time for coverage.
+   */
+  replyTo?: EmailAddress | EmailAddress[] | string | string[]
   /** Email subject line */
   subject: string
   /** Path to email template (Vue component) */
@@ -364,6 +416,48 @@ export interface EmailMessage {
   onError?: (error: Error) => Promise<{ message: string }> | { message: string }
   /** Optional custom handler */
   handle?: () => Promise<{ message: string }> | { message: string }
+  /**
+   * Caller-supplied idempotency key (stacksjs/stacks#1871 M-8).
+   *
+   * When set, `mail.send()` consults an `email_idempotency` dedup
+   * table before dispatching to the driver:
+   *   - hit: returns the cached EmailResult from the first send
+   *   - miss: dispatches, then records the result under the key
+   *
+   * Why it matters: queued send retries (the framework retries 3×
+   * with backoff) and external retry loops (webhook handlers that
+   * re-fire on transient failures, request POSTs that the user
+   * double-clicks) can otherwise deliver the same email multiple
+   * times. The key turns those retries into safe no-ops.
+   *
+   * Construction guidance: derive the key from the business event
+   * the email represents — e.g. `welcome:${userId}`,
+   * `order-confirmation:${orderId}:${attempt}`, not from message
+   * content (which would collide across unrelated sends).
+   *
+   * The dedup table is opt-in. When the migration hasn't been run
+   * yet, the framework warns once and falls back to "send every
+   * time" so unrelated apps aren't broken by the new behavior.
+   */
+  idempotencyKey?: string
+  /**
+   * Classification used by the suppression-policy check
+   * (stacksjs/stacks#1880). Set to `'transactional'` for messages
+   * that should bypass suppression when
+   * `email.suppressionPolicy: 'transactional-allowed'` is
+   * configured — password resets, billing receipts, magic-link
+   * sign-ins.
+   *
+   * Set to `'broadcast'` (or omit) for marketing / newsletter
+   * sends; those get blocked when the recipient is suppressed.
+   *
+   * Under the default `'strict'` policy this field has no effect
+   * — both transactional and broadcast sends get blocked. Apps
+   * that need to send password-reset emails to bounced addresses
+   * (rare, but legitimate) opt into `'transactional-allowed'` AND
+   * tag the message.
+   */
+  tag?: 'transactional' | 'broadcast'
 }
 
 // Email interfaces