@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.363.0

package/dist/data-retention/run-retention-cleanup.js

@@ -43,6 +43,7 @@ import { createEventStoreExecutor, createTenantDb, nullBlindIndexesForSubject, W
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runInSubTransaction } from "../shared/index.js";
 import { computeCutoff } from "./keep-for.js";
 import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.js";
@@ -219,10 +220,9 @@ function collectSingleFileHolders(registry) {
         const { singleFields } = planFileFields(entity.fields);
         if (singleFields.length === 0)
             continue;
-        const table = proj.table; // @cast-boundary column-presence probe
         holders.push({
             table: proj.table,
-            tableHasTenantId: table["tenantId"] !== undefined,
+            tableHasTenantId: propertyOf(proj.table, "tenantId") !== undefined,
             singleFields,
         });
     }
@@ -473,10 +473,9 @@ export async function runRetentionCleanup(args) {
         const entity = registry.getEntity(entityName);
         if (!entity)
             continue;
-        const table = proj.table; // @cast-boundary column-presence probe
         const declaredReference = policy.reference ?? DEFAULT_REFERENCE_FIELD;
         const referenceField = FRAMEWORK_REFERENCE_ALIAS[declaredReference] ?? declaredReference;
-        if (table[referenceField] === undefined) {
+        if (propertyOf(proj.table, referenceField) === undefined) {
             skipped.push({ entityName, reason: "missing_reference_column" });
             continue;
         }
@@ -485,7 +484,7 @@ export async function runRetentionCleanup(args) {
         // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
         // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
         // anderen treffen.
-        if (table["tenantId"] !== undefined) {
+        if (propertyOf(proj.table, "tenantId") !== undefined) {
             where["tenantId"] = tenantId;
         }
         switch (policy.strategy) {
@@ -531,7 +530,8 @@ export async function runRetentionCleanup(args) {
                 break;
             }
             case "softDelete": {
-                if (table["isDeleted"] === undefined || table["deletedAt"] === undefined) {
+                if (propertyOf(proj.table, "isDeleted") === undefined ||
+                    propertyOf(proj.table, "deletedAt") === undefined) {
                     skipped.push({ entityName, reason: "missing_softdelete_columns" });
                     break;
                 }

package/dist/delivery/attachment-ref.d.ts

@@ -0,0 +1,39 @@
+import * as z from "zod";
+import type { FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef } from "../renderer-foundation/index.js";
+export type { FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef };
+export type EmailAttachmentRef = InlineAttachmentRef | FileAttachmentRef | RenderedPdfAttachmentRef;
+export declare const MAX_EMAIL_ATTACHMENTS = 20;
+export declare const MAX_RENDERED_PDF_VARIABLES_BYTES = 64000;
+export declare const inlineAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    cid: z.ZodString;
+    fileRefId: z.ZodString;
+}, z.core.$strict>;
+export declare const fileAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    fileRefId: z.ZodString;
+    fileName: z.ZodString;
+}, z.core.$strict>;
+export declare const renderedPdfAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rendered-pdf">;
+    templateSlug: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    fileName: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const emailAttachmentRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    cid: z.ZodString;
+    fileRefId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    fileRefId: z.ZodString;
+    fileName: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"rendered-pdf">;
+    templateSlug: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    fileName: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export declare function toAttachmentRef(ref: EmailAttachmentRef): EmailAttachmentRef;

package/dist/delivery/attachment-ref.js

@@ -0,0 +1,64 @@
+import * as z from "zod";
+import { attachmentFileNameSchema } from "../shared/index.js";
+import { isDocumentResourceKey, templateSlugSchema } from "../template-resolver/index.js";
+export const MAX_EMAIL_ATTACHMENTS = 20;
+export const MAX_RENDERED_PDF_VARIABLES_BYTES = 64_000;
+const MAX_ID_LENGTH = 64;
+const fileRefIdSchema = z.string().min(1).max(MAX_ID_LENGTH);
+export const inlineAttachmentRefSchema = z
+    .object({
+    kind: z.literal("inline"),
+    cid: z.string().min(1).max(MAX_ID_LENGTH).refine(isDocumentResourceKey),
+    fileRefId: fileRefIdSchema,
+})
+    .strict();
+export const fileAttachmentRefSchema = z
+    .object({
+    kind: z.literal("file"),
+    fileRefId: fileRefIdSchema,
+    fileName: attachmentFileNameSchema,
+})
+    .strict();
+export const renderedPdfAttachmentRefSchema = z
+    .object({
+    kind: z.literal("rendered-pdf"),
+    templateSlug: templateSlugSchema,
+    variables: z
+        .record(z.string(), z.unknown())
+        .refine((value) => Buffer.byteLength(JSON.stringify(value)) <= MAX_RENDERED_PDF_VARIABLES_BYTES, {
+        message: `variables must not exceed ${MAX_RENDERED_PDF_VARIABLES_BYTES} bytes as JSON`,
+    }),
+    fileName: attachmentFileNameSchema.refine((name) => name.toLowerCase().endsWith(".pdf"), {
+        message: "file name must end with .pdf",
+    }),
+    locale: z
+        .string()
+        .min(2)
+        .max(8)
+        .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "locale must be ISO 639-1 (e.g. de, en, en-us)")
+        .optional(),
+})
+    .strict();
+export const emailAttachmentRefSchema = z.discriminatedUnion("kind", [
+    inlineAttachmentRefSchema,
+    fileAttachmentRefSchema,
+    renderedPdfAttachmentRefSchema,
+]);
+// Rebuilds only the contract fields so bytes a caller attached to a ref object
+// can never ride into a job payload.
+export function toAttachmentRef(ref) {
+    switch (ref.kind) {
+        case "inline":
+            return { kind: "inline", cid: ref.cid, fileRefId: ref.fileRefId };
+        case "file":
+            return { kind: "file", fileRefId: ref.fileRefId, fileName: ref.fileName };
+        case "rendered-pdf":
+            return {
+                kind: "rendered-pdf",
+                templateSlug: ref.templateSlug,
+                variables: ref.variables,
+                fileName: ref.fileName,
+                ...(ref.locale !== undefined && { locale: ref.locale }),
+            };
+    }
+}

package/dist/delivery/channel-context.d.ts

@@ -1,6 +1,10 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type DbConnection, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry, TenantId } 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";
-export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId, secrets?: SecretsContext): ChannelContext;
+import { type MailPayload } from "../renderer-foundation/index.js";
+import type { ChannelContext, RenderedMail } from "./types.js";
+export declare function createTemplateMailRenderer(db: DbConnection | TenantDb, registry: Registry, tenantId: TenantId, config: ConfigAccessor | undefined): (payload: MailPayload) => Promise<RenderedMail>;
+export declare function createEmailAttachmentReader(db: DbConnection | TenantDb, registry: Registry, tenantId: TenantId, config: ConfigAccessor | undefined, filesForTenant: (tenantId: string) => FileContext | undefined): NonNullable<ChannelContext["readAttachment"]>;
+export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId, secrets?: SecretsContext, tenantConfig?: ConfigAccessor, filesForTenant?: (tenantId: string) => FileContext | undefined): ChannelContext;

package/dist/delivery/channel-context.js

@@ -1,8 +1,82 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { readFileRefContent } from "../file-foundation/index.js";
+import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
+import { FALLBACK_LOCALE } from "../template-resolver/index.js";
+export function createTemplateMailRenderer(db, registry, tenantId, config) {
+    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, registry, tenantId, config, filesForTenant) {
+    return async (ref) => {
+        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, registry, tenantId, config, filesForTenant) {
+    const renderPdf = createPdfRenderer(db, registry, tenantId, config, filesForTenant);
+    return async (ref, origin = "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
 // (which pass sseBroker=undefined — only the inline inApp channel uses SSE,
 // and it never runs through a job).
-export function buildChannelContext(db, registry, sseBroker, tenantId, secrets) {
-    return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId, secrets };
+export function buildChannelContext(db, registry, sseBroker, tenantId, secrets, tenantConfig, filesForTenant) {
+    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/dist/delivery/constants.d.ts

@@ -1,5 +1,6 @@
 import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
 export declare const DELIVERY_CHANNEL_EXTENSION: "deliveryChannel";
+export declare const EMAIL_CHANNEL_NAME: "email";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
 export declare function deliveryIdempotencyRedisKey(tenantId: string, key: string): string;
 export declare const deliveryPriorityRank: Record<NotifyPriority, number>;

package/dist/delivery/constants.js

@@ -3,6 +3,7 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 // Extension-point name for delivery-channel plugins (channel-email,
 // channel-in-app, channel-push, ...).
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel";
+export const EMAIL_CHANNEL_NAME = "email";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
 // Single source for claim (delivery-service) and terminal-failure release (jobs).
 export function deliveryIdempotencyRedisKey(tenantId, key) {

package/dist/delivery/delivery-service.d.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigAccessor, EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
@@ -23,6 +24,8 @@ export type DeliveryServiceOptions = {
     readonly idempotencyRedis?: Redis;
     readonly jobRunner?: NotifyJobDispatcher;
     readonly secrets?: SecretsContext;
+    readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
+    readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly log?: Logger;
 };

package/dist/delivery/delivery-service.js

@@ -1,9 +1,10 @@
 import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import { assertNotificationVariables, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
+import { assertNotifyTargetsOwnTenant, createEscapeHatchReporter, } from "@cosmicdrift/kumiko-framework/pipeline";
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+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";
@@ -25,12 +26,8 @@ export function collectChannels(registry) {
         return { name: usage.entityName, ...usage.options };
     });
 }
-// `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) {
-    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, escapeHatchAuditSink, log, } = options;
+    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, filesForTenant, tenantConfigFor, escapeHatchAuditSink, log, } = options;
     const idemRedis = idempotencyRedis ?? rateLimit?.redis;
     const logError = createFallbackLogger("delivery", log);
     // Rate limit check: atomic INCR + TTL + over-limit rollback via server-side
@@ -96,9 +93,9 @@ export function createDeliveryService(options) {
         const routedChannelCount = channels.filter((channel) => route[channel.name]).length;
         return routedChannelCount === 1 ? idempotencyKey : undefined;
     }
-    async function resolveUserIdsForTenant(tenantId) {
+    async function resolveUserIdsForTenant(run, tenantId) {
         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) {
@@ -117,7 +114,7 @@ export function createDeliveryService(options) {
         // 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 —
@@ -125,7 +122,7 @@ export function createDeliveryService(options) {
         // 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}"` },
             })
@@ -157,7 +154,7 @@ export function createDeliveryService(options) {
     // attempts instead append a queued event up front and a terminal event from
     // the send job — see deliverViaChannel + jobs.ts.
     async function logDelivery(run, entry) {
-        const attemptId = await logAttempt(db, registry, entry);
+        const attemptId = await logAttempt(run.db, registry, entry);
         recordDelivery(run, entry, attemptId);
     }
     // The stored/returned error is only the code; the redacted message goes to the log.
@@ -199,7 +196,7 @@ export function createDeliveryService(options) {
                 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, {
                 channelName: channel.name,
                 address,
@@ -276,7 +273,7 @@ export function createDeliveryService(options) {
     // route address with no user account) — same suppression rule either way:
     // 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(tenantId, notificationType, priority, addresses) {
+    async function loadSuppressedAddresses(run, tenantId, notificationType, priority, addresses) {
         // Critical priority skips address opt-outs, same rule as user preferences.
         if (priority === "critical")
             return new Set();
@@ -286,32 +283,32 @@ export function createDeliveryService(options) {
             if (addressHash !== undefined)
                 addressHashes.add(addressHash);
         }
-        return selectOptedOutAddresses(db, tenantId, notificationType, [...addressHashes]);
+        return selectOptedOutAddresses(run.db, tenantId, notificationType, [...addressHashes]);
     }
     function isAddressSuppressed(suppressed, address, channelName) {
         const addressHash = hashUnsubscribeAddress(address);
         return addressHash !== undefined && suppressed.has(addressOptOutKey(addressHash, channelName));
     }
     const recipientChannelKey = (userId, channelName) => `${userId}|${channelName}`;
-    async function isChannelDeliverable(userId, tenantId, notificationType, channelName) {
+    async function isChannelDeliverable(run, userId, tenantId, notificationType, channelName) {
         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
     // cover them all at once. A resolve that throws stays out of the map: the
     // delivery loop resolves it again and reports channel_error as before.
     // 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(userIds, tenantId, notificationType) {
+    async function prefetchUserAddresses(run, userIds, tenantId, notificationType) {
         const addresses = new Map();
-        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(recipientChannelKey(userId, channel.name), await channel.resolve(userId, channelCtx));
@@ -332,8 +329,8 @@ export function createDeliveryService(options) {
     //   { type: "*", channel: "inApp", enabled: false }         disables inApp globally
     //   { type: "orderAssigned", channel: "*", enabled: true }  enables orderAssigned everywhere
     //   → orderAssigned on inApp: disabled (conservative) unless an exact entry overrides.
-    async function isChannelEnabled(userId, tenantId, notificationType, channelName) {
-        const prefs = await selectNotificationPreferences(db, tenantId, userId, notificationType, channelName);
+    async function isChannelEnabled(run, userId, tenantId, notificationType, channelName) {
+        const prefs = await selectNotificationPreferences(run.db, tenantId, userId, notificationType, channelName);
         if (prefs.length === 0)
             return true;
         // Exact match (both specific) wins over any wildcard
@@ -345,7 +342,7 @@ export function createDeliveryService(options) {
         return !prefs.some((p) => p.enabled === false);
     }
     async function deliverToUser(userId, notificationType, data, tenantId, priority, run, prefetchedAddresses, suppressed) {
-        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.
             if (!channel.resolve)
@@ -370,7 +367,7 @@ export function createDeliveryService(options) {
             }
             // 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,
@@ -464,8 +461,8 @@ export function createDeliveryService(options) {
         }
     }
     async function deliverDirect(route, notificationType, data, tenantId, priority, recipientId, run) {
-        const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
-        const suppressed = await loadSuppressedAddresses(tenantId, notificationType, priority, Object.values(route));
+        const channelCtx = buildChannelContext(run.db, registry, sseBroker, tenantId, secrets, tenantConfigFor?.(tenantId), run.filesForTenant);
+        const suppressed = await loadSuppressedAddresses(run, tenantId, notificationType, priority, Object.values(route));
         // Direct routing skips preferences (no user account) but NOT rate limit
         // — direct sends can still be abused (webhook replays, test harnesses).
         for (const channel of channels) {
@@ -549,29 +546,38 @@ export function createDeliveryService(options) {
                 userIds = [to];
             }
             else if ("tenant" in to) {
-                userIds = await resolveUserIdsForTenant(to.tenant);
+                userIds = await resolveUserIdsForTenant(run, to.tenant);
             }
             else {
                 userIds = to;
             }
             const prefetchedAddresses = priority === "critical"
                 ? new Map()
-                : await prefetchUserAddresses(userIds, tenantId, notificationType);
-            const suppressed = await loadSuppressedAddresses(tenantId, notificationType, priority, [...prefetchedAddresses.values()].filter((address) => !!address));
+                : await prefetchUserAddresses(run, userIds, tenantId, notificationType);
+            const suppressed = await loadSuppressedAddresses(run, tenantId, notificationType, priority, [...prefetchedAddresses.values()].filter((address) => !!address));
             for (const userId of userIds) {
                 await deliverToUser(userId, notificationType, data, tenantId, priority, run, prefetchedAddresses, suppressed);
             }
         }
     }
+    function dispatched(run) {
+        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 = options.priority ?? "normal";
             const run = {
+                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) {
                 const first = await claimIdempotency(tenantId, idempotencyKey);
@@ -586,7 +592,7 @@ export function createDeliveryService(options) {
                         error: "duplicate_idempotency_key",
                         priority,
                     });
-                    return { deliveries: run.deliveries };
+                    return dispatched(run);
                 }
             }
             try {
@@ -602,7 +608,7 @@ export function createDeliveryService(options) {
                 throw err;
             }
             await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run);
-            return { deliveries: run.deliveries };
+            return dispatched(run);
         },
     };
 }

package/dist/delivery/feature.js

@@ -19,7 +19,7 @@ export function createDeliveryFeature(options) {
     const resolvedAccess = options?.access ?? access.admin;
     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.");
+        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). 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",
             category: "notifications",

package/dist/delivery/index.d.ts

@@ -1,13 +1,16 @@
+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, createChatWebhookChannel, resolveChatWebhookTarget, toChannelResult, } from "./chat-webhook-channel.js";
 export { type ChatSendFailureCode, type ChatSendResult, type ChatWebhookRequest, type ChatWebhookResponse, type ChatWebhookTarget, chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
 export type { DeliveryStatusValue } from "./constants.js";
-export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.js";
-export { type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type NotificationRenderer, type RenderedMessage, type RendererInput, } from "./types.js";
+export { type AttachmentOrigin, type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type RenderedMessage, } from "./types.js";
 export { type AddressUnsubscribeTokenPayload, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, signAddressUnsubscribeToken, signUnsubscribeToken, type UnsubscribeRouteOptions, type UnsubscribeTokenPayload, } from "./unsubscribe.js";

package/dist/delivery/index.js

@@ -1,8 +1,11 @@
+export { sanitizePdfAttachmentFileName } from "../shared/index.js";
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export { emailAttachmentRefSchema, fileAttachmentRefSchema, inlineAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, renderedPdfAttachmentRefSchema, toAttachmentRef, } from "./attachment-ref.js";
 export { DEFAULT_ATTEMPT_LOG_RETENTION_DAYS, runAttemptLogRetention, } from "./attempt-log-retention.js";
+export { createEmailAttachmentReader, createTemplateMailRenderer } from "./channel-context.js";
 export { chatMessageText, createChatWebhookChannel, resolveChatWebhookTarget, toChannelResult, } from "./chat-webhook-channel.js";
 export { chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
-export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";