@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

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/handlers/resubscribe-address.write.d.ts

@@ -6,4 +6,4 @@ export declare const resubscribeAddressWrite: import("@cosmicdrift/kumiko-types/
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/delivery/handlers/resubscribe-user.write.d.ts

@@ -6,4 +6,4 @@ export declare const resubscribeUserWrite: import("@cosmicdrift/kumiko-types/def
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/delivery/handlers/set-preference.write.d.ts

@@ -7,4 +7,4 @@ export declare const setPreferenceWrite: import("@cosmicdrift/kumiko-types/defin
     notificationType: string;
     channel: string;
     enabled: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/delivery/handlers/unsubscribe-address.write.d.ts

@@ -6,4 +6,4 @@ export declare const unsubscribeAddressWrite: import("@cosmicdrift/kumiko-types/
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/delivery/handlers/unsubscribe-user.write.d.ts

@@ -6,4 +6,4 @@ export declare const unsubscribeUserWrite: import("@cosmicdrift/kumiko-types/def
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/delivery/index.d.ts

@@ -1,13 +1,16 @@
+export { sanitizePdfAttachmentFileName } from "../shared/index.js";
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export { DELIVERY_ENVELOPE_DATA_KEYS, type EmailAttachmentRef, emailAttachmentRefSchema, type FileAttachmentRef, fileAttachmentRefSchema, type InlineAttachmentRef, inlineAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, type RenderedPdfAttachmentRef, renderedPdfAttachmentRefSchema, toAttachmentRef, withoutDeliveryEnvelopeKeys, } 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 { DELIVERY_ENVELOPE_DATA_KEYS, emailAttachmentRefSchema, fileAttachmentRefSchema, inlineAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, renderedPdfAttachmentRefSchema, toAttachmentRef, withoutDeliveryEnvelopeKeys, } 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";

package/dist/delivery/jobs.js

@@ -6,6 +6,8 @@
 // these handlers append the terminal sent/failed event on the same stream.
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import { emailAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, toAttachmentRef, } from "./attachment-ref.js";
 import { appendAttemptEvent } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank } from "./constants.js";
@@ -30,7 +32,14 @@ const renderJobPayloadSchema = z.object({
 });
 const sendJobPayloadSchema = renderJobPayloadSchema.extend({
     rendered: z
-        .object({ html: z.string(), subject: z.string(), text: z.string().optional() })
+        .object({
+        html: z.string(),
+        subject: z.string(),
+        text: z.string().optional(),
+        fromName: z.string().optional(),
+        replyTo: z.string().optional(),
+        attachments: z.array(emailAttachmentRefSchema).max(MAX_EMAIL_ATTACHMENTS).optional(),
+    })
         .optional(),
 });
 function requireTenantScopedDeps(ctx, tenantId) {
@@ -39,15 +48,30 @@ function requireTenantScopedDeps(ctx, tenantId) {
         throw new Error("delivery job: missing registry in job context");
     // delivery is r.systemScope()'d, so JobContext.systemDb is guaranteed; unsafeRaw
     // hands the underlying DbConnection to both — safe since they filter by tenantId themselves.
+    // Attachment lookups read only this tenant's FileRefs, plus the system tenant's for inline images.
     if (!ctx.systemDb) {
         throw new InternalError({
             message: "delivery job: ctx.systemDb missing on a system-scoped job",
         });
     }
+    // Also makes ctx.config (built for the job's tenant) the accessor of the payload tenant;
+    // job contexts carry no configFor.
     ctx.systemDb.assertTenantMatch(tenantId);
-    const db = ctx.systemDb.unsafeRaw("delivery attempt append and channel context filter by this job's tenantId themselves"); // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
+    const db = ctx.systemDb.unsafeRaw("attempt append and channel context filter by this job's tenantId; attachment lookup reads only the job tenant's FileRefs plus, for inline images, the system tenant's"); // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
     return { db, registry };
 }
+function toSendRendered(rendered) {
+    return {
+        html: rendered.html,
+        subject: rendered.subject,
+        ...(rendered.text !== undefined && { text: rendered.text }),
+        ...(rendered.fromName !== undefined && { fromName: rendered.fromName }),
+        ...(rendered.replyTo !== undefined && { replyTo: rendered.replyTo }),
+        ...(rendered.attachments !== undefined && {
+            attachments: rendered.attachments.map(toAttachmentRef),
+        }),
+    };
+}
 function resolveChannel(registry, name) {
     const channel = collectChannels(registry).find((c) => c.name === name);
     if (!channel)
@@ -76,12 +100,11 @@ function entryFor(p, status, error, address, confirmed) {
         ...(confirmed === false && { confirmed }),
     };
 }
-// Only the final retry frees the key: earlier failures are retried by the runner and
-// must still dedup. Assumes ctx.redis is the handle the service claimed on; runProdApp
-// wires the same instance into both.
-async function releaseIdempotencyOnTerminalFailure(ctx, p) {
-    // skip: nothing to release before the last attempt or without an idempotency key
-    if (!ctx.finalAttempt || !p.idempotencyKey)
+// Assumes ctx.redis is the handle the service claimed on; runProdApp wires the same
+// instance into both.
+async function releaseIdempotencyKey(ctx, p) {
+    // skip: no idempotency key was claimed for this notification
+    if (!p.idempotencyKey)
         return;
     if (!ctx.redis) {
         ctx.log.warn("delivery: idempotency key not released, job context has no redis", {
@@ -98,6 +121,26 @@ async function releaseIdempotencyOnTerminalFailure(ctx, p) {
         });
     }
 }
+// Only the final retry frees the key: earlier failures are retried by the runner and
+// must still dedup.
+async function releaseIdempotencyOnTerminalFailure(ctx, p) {
+    // skip: not the last attempt, the runner retries and the key must keep deduplicating
+    if (!ctx.finalAttempt)
+        return;
+    await releaseIdempotencyKey(ctx, p);
+}
+// Covers every throw after the payload parsed, not just the attempt-logged ones: a
+// missing registry or unknown channel on the last attempt would otherwise hold the key
+// until its TTL.
+async function releasingKeyOnTerminalFailure(ctx, p, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        await releaseIdempotencyOnTerminalFailure(ctx, p);
+        throw err;
+    }
+}
 // The job runner stores err.message in the run row, and BullMQ keeps failedReason and
 // the stack trace in Redis in plain text, so the rethrown error carries only the code.
 // The redacted message goes to the log.
@@ -108,7 +151,6 @@ async function failAttempt(ctx, db, registry, p, code, err) {
         channel: p.channelName,
     });
     await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, "failed", code, p.address));
-    await releaseIdempotencyOnTerminalFailure(ctx, p);
     throw new Error(code);
 }
 // Render the message and hand off to delivery.send. On failure: record the
@@ -116,10 +158,13 @@ async function failAttempt(ctx, db, registry, p, code, err) {
 // the send step is never reached, so a stuck render can't half-send.
 export const deliveryRenderJob = async (payload, ctx) => {
     const p = renderJobPayloadSchema.parse(payload);
+    return releasingKeyOnTerminalFailure(ctx, p, () => renderStep(p, ctx));
+};
+async function renderStep(p, ctx) {
     const tenantId = p.tenantId; // @cast-boundary engine-payload — stream tenant
     const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
     const channel = resolveChannel(registry, p.channelName);
-    const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
+    const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets, ctx.config, (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId));
     let rendered;
     try {
         if (!channel.render) {
@@ -132,26 +177,33 @@ export const deliveryRenderJob = async (payload, ctx) => {
     }
     try {
         const jobRunner = ctx["jobRunner"]; // @cast-boundary dynamic-key — dispatch lives on the concrete runner
-        await jobRunner.dispatch(DeliveryJobs.send, { ...p, rendered }, { priority: deliveryPriorityRank[p.priority] });
+        await jobRunner.dispatch(DeliveryJobs.send, { ...p, rendered: toSendRendered(rendered) }, { priority: deliveryPriorityRank[p.priority] });
     }
     catch (err) {
         return failAttempt(ctx, db, registry, p, "channel_error", err);
     }
-};
+}
 // Deliver via the channel using the rendered payload (if any). On failure:
 // record the terminal failed event and rethrow so BullMQ retries the send with
 // the same already-rendered HTML — no re-render needed.
 export const deliverySendJob = async (payload, ctx) => {
     const p = sendJobPayloadSchema.parse(payload);
+    return releasingKeyOnTerminalFailure(ctx, p, () => sendStep(p, ctx));
+};
+async function sendStep(p, ctx) {
     const tenantId = p.tenantId; // @cast-boundary engine-payload — stream tenant
     const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
     const channel = resolveChannel(registry, p.channelName);
-    const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
+    const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets, ctx.config, (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId));
     try {
         const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);
         await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, result.status, result.error ?? null, result.address ?? p.address, result.confirmed));
+        // A soft failure ends the job successfully, so no retry follows and the caller's
+        // retry must not be skipped as a duplicate.
+        if (result.status === "failed")
+            await releaseIdempotencyKey(ctx, p);
     }
     catch (err) {
         return failAttempt(ctx, db, registry, p, "send_failed", err);
     }
-};
+}

package/dist/delivery/notify-factory.js

@@ -2,5 +2,8 @@
 // job dispatcher is handed to notify() per call, so queued channels go through
 // the delivery jobs. deliverQueuedInline drops the dispatcher and sends inline.
 export function createDeliveryNotifyFactory(deliveryService, options = {}) {
-    return (user, tenantId, jobDispatcher) => (notificationType, notifyOptions) => deliveryService.notify(notificationType, notifyOptions, user, tenantId, options.deliverQueuedInline === true ? undefined : jobDispatcher);
+    return (user, tenantId, jobDispatcher, deliveryDb, fileProviderResolver) => {
+        const notify = (notificationType, notifyOptions) => deliveryService.notify(notificationType, notifyOptions, user, tenantId, options.deliverQueuedInline === true ? undefined : jobDispatcher, deliveryDb, fileProviderResolver);
+        return notify;
+    };
 }

package/dist/delivery/testing.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, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigAccessor, EscapeHatchAuditSink, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
@@ -16,6 +17,8 @@ export type CreateDeliveryTestContextOptions = {
     readonly jobRunner?: JobRunner;
     readonly secrets?: SecretsContext;
     readonly idempotencyRedis?: Redis;
+    readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
+    readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
 };
 /**
  * Helper for setupTestStack: creates a DeliveryService + _notifyFactory for the test context.

package/dist/delivery/types.d.ts

@@ -1,15 +1,35 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { DeliveryErrorCode, NotifyDeliveryStatus, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DeliveryErrorCode, NotifyDeliveryStatus, NotifyDispatched, NotifyJobDispatcher, NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { MailPayload, RenderedTemplateRef } from "../renderer-foundation/index.js";
+import type { EmailAttachmentRef } from "./attachment-ref.js";
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
+export type RenderedMail = {
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    readonly previewText?: string;
+    readonly fromName?: string;
+    readonly replyTo?: string;
+    readonly attachments?: readonly EmailAttachmentRef[];
+    /** The layout version the html was rendered through; the editor preview names it. */
+    readonly layout?: RenderedTemplateRef;
+};
 export type ChannelContext = {
     readonly db: TenantDb;
     readonly registry: Registry;
     readonly sseBroker: SseBroker | undefined;
     readonly tenantId: TenantId;
     readonly secrets?: SecretsContext | undefined;
+    readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
+    readonly readAttachment?: (ref: EmailAttachmentRef, origin?: AttachmentOrigin) => Promise<{
+        readonly content: Uint8Array;
+        readonly contentType: string;
+    } | null>;
 };
+export type AttachmentOrigin = "template" | "message";
 export type ChannelMessage = {
     readonly notificationType: string;
     readonly title: string;
@@ -27,6 +47,9 @@ export type RenderedMessage = {
     readonly html: string;
     readonly subject: string;
     readonly text?: string;
+    readonly fromName?: string;
+    readonly replyTo?: string;
+    readonly attachments?: readonly EmailAttachmentRef[];
 };
 export declare const DELIVERY_CHANNEL_MODES: readonly ["inline", "queued"];
 export type DeliveryChannelMode = (typeof DELIVERY_CHANNEL_MODES)[number];
@@ -38,17 +61,6 @@ export type DeliveryChannel = {
     render?(message: ChannelMessage, ctx: ChannelContext): Promise<RenderedMessage>;
     send(address: string, message: ChannelMessage, ctx: ChannelContext, rendered?: RenderedMessage): Promise<ChannelResult>;
 };
-export type RendererInput = {
-    readonly template: string;
-    readonly variables: Readonly<Record<string, unknown>>;
-    readonly locale?: string | undefined;
-};
-export type NotificationRenderer = {
-    readonly name: string;
-    render(input: RendererInput): Promise<string>;
-    /** Plain-text version of the same mail; the email channel sends it as the text part of a multipart/alternative mail. */
-    renderText?(input: RendererInput): Promise<string>;
-};
 export type DeliveryLogEntry = {
     readonly tenantId: TenantId;
     readonly notificationType: string;
@@ -61,7 +73,7 @@ export type DeliveryLogEntry = {
     readonly confirmed?: false;
 };
 export type DeliveryService = {
-    notify(notificationType: string, options: NotifyOptions, user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher): Promise<NotifyResult>;
+    notify(notificationType: string, options: NotifyOptions, user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher, deliveryDb?: DbConnection, fileProviderResolver?: FileProviderResolver): Promise<NotifyDispatched>;
 };
 export type DeliveryChannelPlugin = Omit<DeliveryChannel, "name">;
 export declare function isDeliveryChannelPlugin(o: unknown): o is DeliveryChannelPlugin;

package/dist/delivery/unsubscribe.js

@@ -1,5 +1,6 @@
 import { ExtraRouteRejection, signatureRoute, } from "@cosmicdrift/kumiko-framework/api";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
 import * as z from "zod";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
@@ -280,7 +281,9 @@ function tokenFromRequestBody(request) {
     if (contentType?.includes("application/json")) {
         try {
             const parsed = JSON.parse(request.rawBody);
-            return typeof parsed.token === "string" ? parsed.token : undefined;
+            return isPlainObject(parsed) && typeof parsed["token"] === "string"
+                ? parsed["token"]
+                : undefined;
         }
         catch {
             return undefined;

package/dist/derivatives-sharp/render.js

@@ -3,12 +3,9 @@
 // region blur (see BlurRegion). Server-only: sharp is a native binding.
 import QRCode from "qrcode";
 import sharp from "sharp";
+import { assertNotSvg, SHARP_INPUT_OPTIONS } from "../shared/index.js";
 const MIN_SHARP_SIGMA = 0.3;
 const MAX_SHARP_SIGMA = 1000;
-// Above this, a decoded pixel buffer runs into hundreds of MB before any
-// resize even happens — sharp's own default (~268MP) is still large enough
-// to be an OOM primitive for a single request.
-const MAX_INPUT_PIXELS = 100_000_000;
 // Longest output edge a caller may request via `size`/`maxEdge`. Without a
 // cap, `{ maxEdge: 50000 }` allocates a multi-gigabyte buffer per encoder
 // step before any client sees a byte back.
@@ -27,26 +24,12 @@ const MAX_QR_DATA_LENGTH = 1024;
 // camera capture — the AC claims phone-scannable, so an under-sized layer
 // throws instead of caching a silently unusable image.
 const MIN_QR_PIXEL_WIDTH = 160;
-// sequentialRead trades random pixel access for lower peak memory on
-// streamed formats — applied at every decode entry point below since none
-// of them need non-sequential access to the *original* bytes (extract runs
-// against a single already-buffered region per call).
-const SHARP_INPUT_OPTIONS = { limitInputPixels: MAX_INPUT_PIXELS, sequentialRead: true };
 function normalizeMimeType(mimeType) {
     return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
 }
 function clampSigma(sigma) {
     return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
 }
-// Shared trust boundary for every image byte source this renderer decodes —
-// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
-// alike: a base64 string in a field declaration isn't more trustworthy than
-// an upload just because it came from app code.
-function assertNotSvg(format) {
-    if (format === "svg") {
-        throw new Error("derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.");
-    }
-}
 function assertValidRegion(region) {
     const values = [region.x, region.y, region.width, region.height];
     if (values.some((v) => !Number.isFinite(v)) || region.width <= 0 || region.height <= 0) {