@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "NotificationRenderer and RendererInput removed, immediate notify renders with the tenant config",
+    "detail": "The inline (immediate, job-less) delivery path now gets the tenant config accessor like the delivery.render job, so the mail layout shows the tenant name in both paths. DeliveryServiceOptions and CreateDeliveryTestContextOptions accept tenantConfigFor; runProdApp wires it from the boot config resolver. The types NotificationRenderer and RendererInput are removed from the delivery exports because the legacy renderer path is gone.",
+    "migration": "Drop NotificationRenderer and RendererInput imports; render mails with template + meta on r.notification (see renderer-foundation)."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "ChannelContext.renderMail renders template notifications for the email channel",
+    "detail": "A notification that declares a template is rendered through the mail renderer plugin with the recipient locale and the notification variables; the email channel fails when renderMail is missing instead of falling back to the legacy renderer. The job path passes the tenant config accessor to the renderer, the inline path renders without one."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mails can attach a PDF that is rendered from a document template when the mail is sent",
+    "detail": "notify data.attachments accepts { kind: \"rendered-pdf\", templateSlug, variables, fileName, locale? }. The send job renders the PDF through the document-pdf renderer, so the job payload carries the variables (at most 64000 bytes as JSON), not the bytes. Variables are stored in the job payload, so keep personal data out of them or accept that retention."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "ChannelContext.readAttachment takes an attachment origin",
+    "detail": "readAttachment(ref, origin) with origin \"template\" (from the renderer) or \"message\" (default, from notify data). Only template attachments may fall back to the system tenant; file refs from notify data stay limited to the sending tenant."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "EMAIL_CHANNEL_NAME, createTemplateMailRenderer and createEmailAttachmentReader are exported",
+    "detail": "The email channel name is a shared constant instead of a string literal. The mail renderer and the inline-attachment reader that build the channel context are exported and accept a tenant-bound db, so a handler can send through the same path as a notification."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Notification messages carry attachments (file refs and inline cid images)",
+    "detail": "RenderedMessage and the send job payload accept attachments as references (kind file or inline), never bytes. ChannelContext.readAttachment resolves them tenant-scoped at send time; createDeliveryService takes a new filesForTenant option for the inline fallback path."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "NotifyFactory takes an optional fileProviderResolver, so immediate and bootstrap mails can read attachments too"
+  },
+  {
+    "version": "0.363.0",
+    "type": "fix",
+    "title": "Queued mails render with the tenant's config again",
+    "detail": "The delivery render and send jobs read the tenant config through ctx.configFor, which job contexts do not carry, so queued mails rendered without tenant name, locale, currency and branding. Both jobs now use ctx.config, which the job runner builds for the payload's tenant."
+  },
   {
     "version": "0.357.0",
     "type": "improvement",

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -1,8 +1,115 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createTenantDb, type DbConnection, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { ChannelContext } from "./types.js";
+import { readFileRefContent } from "../file-foundation/index.js";
+import {
+  collectRendererPlugins,
+  createRendererFoundationApi,
+  type MailPayload,
+  RendererError,
+} from "../renderer-foundation/index.js";
+import { FALLBACK_LOCALE } from "../template-resolver/index.js";
+import type { EmailAttachmentRef, RenderedPdfAttachmentRef } from "./attachment-ref.js";
+import type { AttachmentOrigin, ChannelContext, RenderedMail } from "./types.js";
+
+export function createTemplateMailRenderer(
+  db: DbConnection | TenantDb,
+  registry: Registry,
+  tenantId: TenantId,
+  config: ConfigAccessor | undefined,
+): (payload: MailPayload) => Promise<RenderedMail> {
+  return async (payload) => {
+    const plugin = createRendererFoundationApi(
+      collectRendererPlugins(registry),
+    ).createRendererForTenant({ tenantId, kind: "mail" });
+    const response = await plugin.render(
+      { kind: "mail", payload },
+      { db, registry, tenantId, ...(config !== undefined && { config }) },
+    );
+    if (response.kind !== "mail") {
+      throw new RendererError(
+        `[delivery] renderer "${plugin.name}" answered a mail request with kind "${response.kind}"`,
+        "other",
+      );
+    }
+    return {
+      subject: response.subject,
+      html: response.html,
+      text: response.text,
+      ...(response.previewText !== undefined && { previewText: response.previewText }),
+      ...(response.attachments !== undefined && { attachments: response.attachments }),
+    };
+  };
+}
+
+const INLINE_IMAGE_CONTENT_TYPE_PREFIX = "image/";
+const PDF_CONTENT_TYPE = "application/pdf";
+
+// Renders at send time so the job payload carries variables, not bytes. A failure throws:
+// the send job retries instead of mailing without the document the recipient expects.
+function createPdfRenderer(
+  db: DbConnection | TenantDb,
+  registry: Registry,
+  tenantId: TenantId,
+  config: ConfigAccessor | undefined,
+  filesForTenant: (tenantId: string) => FileContext | undefined,
+) {
+  return async (ref: RenderedPdfAttachmentRef) => {
+    const plugin = createRendererFoundationApi(
+      collectRendererPlugins(registry),
+    ).createRendererForTenant({ tenantId, kind: "document-pdf" });
+    const response = await plugin.render(
+      {
+        kind: "document-pdf",
+        payload: {
+          slug: ref.templateSlug,
+          locale: ref.locale ?? FALLBACK_LOCALE,
+          variables: ref.variables,
+        },
+      },
+      { db, registry, tenantId, filesForTenant, ...(config !== undefined && { config }) },
+    );
+    if (response.kind !== "document-pdf") {
+      throw new RendererError(
+        `[delivery] renderer "${plugin.name}" answered a document-pdf request with kind "${response.kind}"`,
+        "other",
+      );
+    }
+    return { content: response.pdfBytes, contentType: PDF_CONTENT_TYPE };
+  };
+}
+
+// Inline images and file attachments the renderer took from a template may come from the system
+// tenant (system template or tenant override of one). A file ref from notify data stays limited to
+// the job's own tenant, since a caller picks it. Inline content that is not an image is dropped, so
+// a swapped fileRef id cannot smuggle a document into the mail body.
+export function createEmailAttachmentReader(
+  db: DbConnection | TenantDb,
+  registry: Registry,
+  tenantId: TenantId,
+  config: ConfigAccessor | undefined,
+  filesForTenant: (tenantId: string) => FileContext | undefined,
+): NonNullable<ChannelContext["readAttachment"]> {
+  const renderPdf = createPdfRenderer(db, registry, tenantId, config, filesForTenant);
+  return async (ref: EmailAttachmentRef, origin: AttachmentOrigin = "message") => {
+    if (ref.kind === "rendered-pdf") return renderPdf(ref);
+    const found = await readFileRefContent({
+      db,
+      filesForTenant,
+      fileRefId: ref.fileRefId,
+      allowedTenantIds:
+        ref.kind === "file" && origin === "message" ? [tenantId] : [tenantId, SYSTEM_TENANT_ID],
+    });
+    if (found === null) return null;
+    if (ref.kind === "inline" && !found.contentType.startsWith(INLINE_IMAGE_CONTENT_TYPE_PREFIX)) {
+      return null;
+    }
+    return { content: found.content, contentType: found.contentType };
+  };
+}
 
 // Build the per-tenant context a channel's resolve/render/send receives.
 // Shared by the synchronous delivery-service path and the async job handlers
@@ -14,6 +121,24 @@ export function buildChannelContext(
   sseBroker: SseBroker | undefined,
   tenantId: TenantId,
   secrets?: SecretsContext,
+  tenantConfig?: ConfigAccessor,
+  filesForTenant?: (tenantId: string) => FileContext | undefined,
 ): ChannelContext {
-  return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId, secrets };
+  return {
+    db: createTenantDb(db, tenantId),
+    registry,
+    sseBroker,
+    tenantId,
+    secrets,
+    renderMail: createTemplateMailRenderer(db, registry, tenantId, tenantConfig),
+    ...(filesForTenant !== undefined && {
+      readAttachment: createEmailAttachmentReader(
+        db,
+        registry,
+        tenantId,
+        tenantConfig,
+        filesForTenant,
+      ),
+    }),
+  };
 }

package/packages/bundled-features/src/delivery/constants.ts

@@ -6,6 +6,8 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 // channel-in-app, channel-push, ...).
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel" as const;
 
+export const EMAIL_CHANNEL_NAME = "email" as const;
+
 export {
   DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
   DELIVERY_ATTEMPT_EVENT,

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -2,22 +2,32 @@ import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  ConfigAccessor,
   DeliveryErrorCode,
   EscapeHatchAuditSink,
   NotifyDelivery,
+  NotifyDispatched,
   NotifyJobDispatcher,
   NotifyOptions,
   NotifyPriority,
   Registry,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  assertNotificationVariables,
+  createSystemUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
-import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  assertNotifyTargetsOwnTenant,
+  createEscapeHatchReporter,
+} from "@cosmicdrift/kumiko-framework/pipeline";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
+import { fileContextFromResolver } from "../file-foundation/index.js";
 import { redactErrorText } from "../shared/index.js";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
@@ -77,6 +87,11 @@ export type DeliveryServiceOptions = {
   // Credentials source for inline-delivered chat channels (webhook URL / bot
   // token). Jobs get ctx.secrets from the job runner instead.
   readonly secrets?: SecretsContext;
+  // File storage for inline-delivered mails with attachments; jobs use their own ctx instead.
+  readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
+  // Tenant config for inline rendering (mail layout reads tenant name, locale);
+  // job-delivered mails get the same accessor from the job context's configFor.
+  readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
   // Attributed escape-hatch audit for resolveUserIdsForTenant's ctx.systemDb —
   // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
@@ -96,11 +111,6 @@ export function collectChannels(registry: Registry): DeliveryChannel[] {
   });
 }
 
-// `collectRenderers` entfernt 2026-05-19: notificationRenderer-Extension-Point
-// wurde nie konsumiert (channel-email nimmt renderer als Konstruktor-Option,
-// nicht aus Extension-Usages). Multi-Kind-Plugin-Pool lebt jetzt im
-// `renderer-foundation`-Bundle via `collectRendererPlugins`.
-
 export function createDeliveryService(options: DeliveryServiceOptions): DeliveryService {
   const {
     db,
@@ -113,6 +123,8 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     idempotencyRedis,
     jobRunner,
     secrets,
+    filesForTenant,
+    tenantConfigFor,
     escapeHatchAuditSink,
     log,
   } = options;
@@ -214,9 +226,14 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     return routedChannelCount === 1 ? idempotencyKey : undefined;
   }
 
-  async function resolveUserIdsForTenant(tenantId: TenantId): Promise<readonly string[]> {
+  async function resolveUserIdsForTenant(
+    run: NotifyRun,
+    tenantId: TenantId,
+  ): Promise<readonly string[]> {
     if (!tenantUserIdsQuery) {
-      throw new Error("Tenant broadcast requires tenantUserIdsQuery in DeliveryServiceOptions");
+      throw new Error(
+        "Tenant broadcast (to: { tenant }) requires the tenant feature (default wiring) or an explicit tenantUserIdsQuery in DeliveryServiceOptions",
+      );
     }
     const handler = registry.getQueryHandler(tenantUserIdsQuery);
     if (!handler) {
@@ -235,7 +252,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     // path a cross-tenant read the dispatcher never allows. Cross-tenant reach only
     // exists through the grant-carrying systemDb view below.
     const isSystem = registry.isHandlerSystemScoped(tenantUserIdsQuery);
-    const tenantDb = createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, {
+    const tenantDb = createTenantDb(run.db, tenantId, "tenant", undefined, undefined, undefined, {
       report,
     });
     // The dispatcher grants a systemScope handler's ctx.systemDb.unsafeRaw() ungated —
@@ -243,7 +260,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     // caller. Only the systemDb view's own source TenantDb carries the grant, so it
     // can't leak onto ctx.db.
     const systemDbSourceTenantDb = isSystem
-      ? createTenantDb(db, tenantId, "system", undefined, undefined, undefined, {
+      ? createTenantDb(run.db, tenantId, "system", undefined, undefined, undefined, {
           report,
           unsafeRaw: { reason: `r.systemScope() handler "${tenantUserIdsQuery}"` },
         })
@@ -268,12 +285,16 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   // State of one notify() call: collects the per-channel outcome returned to
   // the caller. Passed explicitly — the service itself is shared across calls.
   type NotifyRun = {
+    // All DB work of the call runs here: inside a write transaction the caller passes the
+    // outside-tx pool, because the app pool's slots may all be held by waiting write txs.
+    readonly db: DbConnection;
     readonly deliveries: NotifyDelivery[];
     readonly jobDispatcher: NotifyJobDispatcher | undefined;
     readonly locale: string | undefined;
     // Set only when exactly one channel carries the call: the queued job may then free
     // the key on terminal failure without risking a duplicate send on another channel.
     readonly jobIdempotencyKey: string | undefined;
+    readonly filesForTenant: ((tenantId: string) => FileContext | undefined) | undefined;
   };
 
   function recordDelivery(
@@ -295,7 +316,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   // attempts instead append a queued event up front and a terminal event from
   // the send job — see deliverViaChannel + jobs.ts.
   async function logDelivery(run: NotifyRun, entry: DeliveryLogEntry): Promise<void> {
-    const attemptId = await logAttempt(db, registry, entry);
+    const attemptId = await logAttempt(run.db, registry, entry);
     recordDelivery(run, entry, attemptId);
   }
 
@@ -372,7 +393,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         error: null,
         priority,
       };
-      await appendAttemptEvent(db, registry, deliveryAttemptId, queuedEntry);
+      await appendAttemptEvent(run.db, registry, deliveryAttemptId, queuedEntry);
       await run.jobDispatcher.dispatch(
         channel.render ? DeliveryJobs.render : DeliveryJobs.send,
         {
@@ -460,6 +481,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   // no blind-index key configured means no hash, so nothing to look up. One
   // query per notify() call, not per recipient and channel.
   async function loadSuppressedAddresses(
+    run: NotifyRun,
     tenantId: TenantId,
     notificationType: string,
     priority: NotifyPriority,
@@ -472,7 +494,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       const addressHash = hashUnsubscribeAddress(address);
       if (addressHash !== undefined) addressHashes.add(addressHash);
     }
-    return selectOptedOutAddresses(db, tenantId, notificationType, [...addressHashes]);
+    return selectOptedOutAddresses(run.db, tenantId, notificationType, [...addressHashes]);
   }
 
   function isAddressSuppressed(
@@ -487,13 +509,14 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   const recipientChannelKey = (userId: string, channelName: string) => `${userId}|${channelName}`;
 
   async function isChannelDeliverable(
+    run: NotifyRun,
     userId: string,
     tenantId: TenantId,
     notificationType: string,
     channelName: string,
   ): Promise<boolean> {
     if (isChannelKilled && (await isChannelKilled(tenantId, channelName))) return false;
-    return isChannelEnabled(userId, tenantId, notificationType, channelName);
+    return isChannelEnabled(run, userId, tenantId, notificationType, channelName);
   }
 
   // Resolves every user's channel addresses up front so the opt-out lookup can
@@ -502,17 +525,28 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   // Channels the kill switch or the user's preferences disable are never resolved
   // here: resolve may have side effects and deliverToUser skips those channels.
   async function prefetchUserAddresses(
+    run: NotifyRun,
     userIds: readonly string[],
     tenantId: TenantId,
     notificationType: string,
   ): Promise<Map<string, string | null>> {
     const addresses = new Map<string, string | null>();
-    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    const channelCtx = buildChannelContext(
+      run.db,
+      registry,
+      sseBroker,
+      tenantId,
+      secrets,
+      tenantConfigFor?.(tenantId),
+      run.filesForTenant,
+    );
     for (const userId of userIds) {
       for (const channel of channels) {
         if (!channel.resolve) continue;
         try {
-          if (!(await isChannelDeliverable(userId, tenantId, notificationType, channel.name))) {
+          if (
+            !(await isChannelDeliverable(run, userId, tenantId, notificationType, channel.name))
+          ) {
             continue;
           }
           addresses.set(
@@ -537,13 +571,14 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   //   { type: "orderAssigned", channel: "*", enabled: true }  enables orderAssigned everywhere
   //   → orderAssigned on inApp: disabled (conservative) unless an exact entry overrides.
   async function isChannelEnabled(
+    run: NotifyRun,
     userId: string,
     tenantId: TenantId,
     notificationType: string,
     channelName: string,
   ): Promise<boolean> {
     const prefs = await selectNotificationPreferences(
-      db,
+      run.db,
       tenantId,
       userId,
       notificationType,
@@ -573,7 +608,15 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     prefetchedAddresses: ReadonlyMap<string, string | null>,
     suppressed: ReadonlySet<AddressOptOutKey>,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    const channelCtx = buildChannelContext(
+      run.db,
+      registry,
+      sseBroker,
+      tenantId,
+      secrets,
+      tenantConfigFor?.(tenantId),
+      run.filesForTenant,
+    );
 
     for (const channel of channels) {
       // Route-only channel (no per-user address): not a user-notification target.
@@ -601,7 +644,13 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
       // Check preferences (critical priority skips preference check)
       if (priority !== "critical") {
-        const enabled = await isChannelEnabled(userId, tenantId, notificationType, channel.name);
+        const enabled = await isChannelEnabled(
+          run,
+          userId,
+          tenantId,
+          notificationType,
+          channel.name,
+        );
         if (!enabled) {
           await logDelivery(run, {
             tenantId,
@@ -707,8 +756,17 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     recipientId: string | null,
     run: NotifyRun,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    const channelCtx = buildChannelContext(
+      run.db,
+      registry,
+      sseBroker,
+      tenantId,
+      secrets,
+      tenantConfigFor?.(tenantId),
+      run.filesForTenant,
+    );
     const suppressed = await loadSuppressedAddresses(
+      run,
       tenantId,
       notificationType,
       priority,
@@ -815,7 +873,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       if (typeof to === "string") {
         userIds = [to];
       } else if ("tenant" in to) {
-        userIds = await resolveUserIdsForTenant(to.tenant);
+        userIds = await resolveUserIdsForTenant(run, to.tenant);
       } else {
         userIds = to;
       }
@@ -823,8 +881,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       const prefetchedAddresses =
         priority === "critical"
           ? new Map<string, string | null>()
-          : await prefetchUserAddresses(userIds, tenantId, notificationType);
+          : await prefetchUserAddresses(run, userIds, tenantId, notificationType);
       const suppressed = await loadSuppressedAddresses(
+        run,
         tenantId,
         notificationType,
         priority,
@@ -846,15 +905,34 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
   }
 
+  function dispatched(run: NotifyRun): NotifyDispatched {
+    return { kind: "dispatched", deliveries: run.deliveries };
+  }
+
   return {
-    async notify(notificationType, options, _user, tenantId, jobDispatcher) {
+    async notify(
+      notificationType,
+      options,
+      _user,
+      tenantId,
+      jobDispatcher,
+      deliveryDb,
+      fileProviderResolver,
+    ) {
+      assertNotifyTargetsOwnTenant(options, tenantId);
+      assertNotificationVariables(registry, notificationType, options.data);
       const { route, idempotencyKey } = options;
       const priority: NotifyPriority = options.priority ?? "normal";
       const run: NotifyRun = {
+        db: deliveryDb ?? db,
         deliveries: [],
         jobDispatcher: options.immediate ? undefined : (jobDispatcher ?? jobRunner),
         locale: options.locale,
         jobIdempotencyKey: jobIdempotencyKeyFor(idempotencyKey, route),
+        filesForTenant:
+          fileProviderResolver === undefined
+            ? filesForTenant
+            : (fileTenantId) => fileContextFromResolver(fileProviderResolver, fileTenantId),
       };
 
       if (idempotencyKey) {
@@ -870,7 +948,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             error: "duplicate_idempotency_key",
             priority,
           });
-          return { deliveries: run.deliveries };
+          return dispatched(run);
         }
       }
 
@@ -888,7 +966,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         throw err;
       }
       await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run);
-      return { deliveries: run.deliveries };
+      return dispatched(run);
     },
   };
 }

package/packages/bundled-features/src/delivery/feature.ts

@@ -61,7 +61,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
   return defineFeature("delivery", (r) => {
     r.describe(
-      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
+      'The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app\'s `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message\'s `data.unsubscribeUrl` points at the unsubscribe route.',
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",

package/packages/bundled-features/src/delivery/index.ts

@@ -1,9 +1,24 @@
+export { sanitizePdfAttachmentFileName } from "../shared/index.js";
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export {
+  type EmailAttachmentRef,
+  emailAttachmentRefSchema,
+  type FileAttachmentRef,
+  fileAttachmentRefSchema,
+  type InlineAttachmentRef,
+  inlineAttachmentRefSchema,
+  MAX_EMAIL_ATTACHMENTS,
+  MAX_RENDERED_PDF_VARIABLES_BYTES,
+  type RenderedPdfAttachmentRef,
+  renderedPdfAttachmentRefSchema,
+  toAttachmentRef,
+} from "./attachment-ref.js";
 export {
   type AttemptLogRetentionOptions,
   DEFAULT_ATTEMPT_LOG_RETENTION_DAYS,
   runAttemptLogRetention,
 } from "./attempt-log-retention.js";
+export { createEmailAttachmentReader, createTemplateMailRenderer } from "./channel-context.js";
 export {
   type ChatWebhookChannelOptions,
   chatMessageText,
@@ -36,6 +51,7 @@ export {
   DeliveryJobs,
   DeliveryQueries,
   DeliveryStatus,
+  EMAIL_CHANNEL_NAME,
 } from "./constants.js";
 export {
   collectChannels,
@@ -55,6 +71,7 @@ export {
 } from "./tables.js";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.js";
 export {
+  type AttachmentOrigin,
   type ChannelContext,
   type ChannelMessage,
   type ChannelResult,
@@ -64,9 +81,7 @@ export {
   type DeliveryLogEntry,
   type DeliveryService,
   isDeliveryChannelPlugin,
-  type NotificationRenderer,
   type RenderedMessage,
-  type RendererInput,
 } from "./types.js";
 export {
   type AddressUnsubscribeTokenPayload,