@cosmicdrift/kumiko-bundled-features 0.340.0 → 0.341.0

package/dist/channel-teams/feature.js

@@ -1,6 +1,6 @@
-import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { chatConnectionNameSchema, chatWebhookUrlSchema, DELIVERY_CHANNEL_EXTENSION, resolveChatWebhookTarget, } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { createTeamsChannel } from "./teams-channel.js";
+import { createTeamsChannel, TEAMS_DEFAULT_ALLOWED_HOSTS, } from "./teams-channel.js";
 export function createChannelTeamsFeature(options = {}) {
     return defineFeature("channel-teams", (r) => {
         r.describe('Posts delivery notifications to a Microsoft Teams webhook (Workflows or connector) as an Adaptive Card, registered as the `teams` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { teams: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-teams:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (.webhook.office.com, .logic.azure.com, .powerplatform.com), https-only and the request timeout are app options of `createChannelTeamsFeature(opts)`, never tenant config.');
@@ -11,6 +11,7 @@ export function createChannelTeamsFeature(options = {}) {
         });
         r.requires("delivery");
         r.requires("secrets");
+        const webhookTarget = resolveChatWebhookTarget({ defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS }, options);
         const webhooks = r.secretNamespace("webhooks", {
             label: {
                 en: "Microsoft Teams webhooks",
@@ -24,6 +25,7 @@ export function createChannelTeamsFeature(options = {}) {
             },
             scope: "tenant",
             nameSchema: chatConnectionNameSchema,
+            valueSchema: chatWebhookUrlSchema(webhookTarget),
         });
         const channel = createTeamsChannel(options, webhooks.keyFor);
         r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {

package/dist/channel-teams/index.d.ts

@@ -1,2 +1,2 @@
 export { createChannelTeamsFeature } from "./feature.js";
-export { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";
+export { createTeamsChannel, TEAMS_DEFAULT_ALLOWED_HOSTS, TEAMS_SECRET_KEYS, type TeamsChannelOptions, } from "./teams-channel.js";

package/dist/channel-teams/index.js

@@ -1,2 +1,2 @@
 export { createChannelTeamsFeature } from "./feature.js";
-export { createTeamsChannel } from "./teams-channel.js";
+export { createTeamsChannel, TEAMS_DEFAULT_ALLOWED_HOSTS, TEAMS_SECRET_KEYS, } from "./teams-channel.js";

package/dist/channel-teams/teams-channel.d.ts

@@ -1,5 +1,9 @@
 import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
 export type TeamsChannelOptions = ChatWebhookChannelOptions;
+export declare const TEAMS_SECRET_KEYS: {
+    readonly webhookPrefix: "channel-teams:webhooks.";
+    readonly webhookKeyFor: (connection: string) => string;
+};
 export declare const TEAMS_DEFAULT_ALLOWED_HOSTS: readonly [".webhook.office.com", ".logic.azure.com", ".powerplatform.com"];
 export declare function buildTeamsAdaptiveCard(title: string, body: string | undefined): unknown;
 export declare function createTeamsChannel(options: TeamsChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-teams/teams-channel.js

@@ -1,4 +1,8 @@
 import { createChatWebhookChannel, } from "../delivery/index.js";
+export const TEAMS_SECRET_KEYS = {
+    webhookPrefix: "channel-teams:webhooks.",
+    webhookKeyFor: (connection) => `channel-teams:webhooks.${connection}`,
+};
 export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
     ".webhook.office.com",
     ".logic.azure.com",

package/dist/channel-telegram/feature.js

@@ -1,9 +1,10 @@
 import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { createTelegramChannel } from "./telegram-channel.js";
+import * as z from "zod";
+import { createTelegramChannel, isTelegramBotToken, } from "./telegram-channel.js";
 export function createChannelTelegramFeature(options = {}) {
     return defineFeature("channel-telegram", (r) => {
-        r.describe('Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: "<chat id or @channel>" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL and request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.');
+        r.describe('Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: "<chat id or @channel>" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL, its host allowlist (`allowedHosts`, default `api.telegram.org`), `requireHttps` (default true; boot fails on a mismatch) and the request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.');
         r.uiHints({
             displayLabel: "Telegram Channel",
             category: "notifications",
@@ -18,6 +19,7 @@ export function createChannelTelegramFeature(options = {}) {
             },
             redact: () => "••••••••",
             scope: "tenant",
+            valueSchema: z.string().refine(isTelegramBotToken, "invalid bot token"),
         });
         const channel = createTelegramChannel(options, botToken.name);
         r.useExtension(DELIVERY_CHANNEL_EXTENSION, "telegram", {

package/dist/channel-telegram/index.d.ts

@@ -1,2 +1,2 @@
 export { createChannelTelegramFeature } from "./feature.js";
-export { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";
+export { createTelegramChannel, isTelegramBotToken, isTelegramChatId, TELEGRAM_DEFAULT_API_BASE_URL, TELEGRAM_SECRET_KEYS, type TelegramChannelOptions, } from "./telegram-channel.js";

package/dist/channel-telegram/index.js

@@ -1,2 +1,2 @@
 export { createChannelTelegramFeature } from "./feature.js";
-export { createTelegramChannel } from "./telegram-channel.js";
+export { createTelegramChannel, isTelegramBotToken, isTelegramChatId, TELEGRAM_DEFAULT_API_BASE_URL, TELEGRAM_SECRET_KEYS, } from "./telegram-channel.js";

package/dist/channel-telegram/telegram-channel.d.ts

@@ -1,8 +1,16 @@
 import { type DeliveryChannel } from "../delivery/index.js";
 export type TelegramChannelOptions = {
     readonly apiBaseUrl?: string;
+    readonly allowedHosts?: readonly string[];
+    readonly requireHttps?: boolean;
     readonly timeoutMs?: number;
 };
 export declare const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export declare const TELEGRAM_DEFAULT_ALLOWED_HOSTS: readonly string[];
 export declare const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export declare const TELEGRAM_SECRET_KEYS: {
+    readonly botToken: "channel-telegram:secret:bot-token";
+};
+export declare function isTelegramChatId(address: string): boolean;
+export declare function isTelegramBotToken(token: string): boolean;
 export declare function createTelegramChannel(options: TelegramChannelOptions, botTokenKey: string): DeliveryChannel;

package/dist/channel-telegram/telegram-channel.js

@@ -1,18 +1,42 @@
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import { chatMessageText, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, toChannelResult, truncateChars, } from "../delivery/index.js";
 export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_DEFAULT_ALLOWED_HOSTS = ["api.telegram.org"];
 export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export const TELEGRAM_SECRET_KEYS = { botToken: "channel-telegram:secret:bot-token" };
 // Numeric chat/group id (groups and channels are negative) or a public @channelname.
 const TELEGRAM_CHAT_ID_PATTERN = /^(-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{3,31})$/;
 // `<bot id>:<secret>`; the token is spliced into the URL path, so only the real shape passes.
 const TELEGRAM_BOT_TOKEN_PATTERN = /^\d{1,20}:[A-Za-z0-9_-]{10,}$/;
+export function isTelegramChatId(address) {
+    return TELEGRAM_CHAT_ID_PATTERN.test(address);
+}
+export function isTelegramBotToken(token) {
+    return TELEGRAM_BOT_TOKEN_PATTERN.test(token);
+}
 export function createTelegramChannel(options, botTokenKey) {
     const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_DEFAULT_API_BASE_URL;
+    const allowedHosts = options.allowedHosts ?? TELEGRAM_DEFAULT_ALLOWED_HOSTS;
+    const requireHttps = options.requireHttps ?? true;
+    // Fail at boot: a misconfigured base URL must not surface as per-send failures.
+    let parsedBase;
+    try {
+        parsedBase = new URL(apiBaseUrl);
+    }
+    catch {
+        throw new Error("channel-telegram: apiBaseUrl is not a valid URL");
+    }
+    if (!allowedHosts.includes(parsedBase.hostname)) {
+        throw new Error(`channel-telegram: apiBaseUrl host "${parsedBase.hostname}" is not in allowedHosts`);
+    }
+    if (requireHttps && parsedBase.protocol !== "https:") {
+        throw new Error("channel-telegram: apiBaseUrl must use https (set requireHttps: false to opt out)");
+    }
     return {
         name: "telegram",
         mode: "queued",
         async send(address, message, ctx) {
-            if (!TELEGRAM_CHAT_ID_PATTERN.test(address)) {
+            if (!isTelegramChatId(address)) {
                 return toChannelResult(address, { ok: false, code: "invalid_address" });
             }
             let token;
@@ -26,21 +50,13 @@ export function createTelegramChannel(options, botTokenKey) {
             catch {
                 token = undefined;
             }
-            if (!token || !TELEGRAM_BOT_TOKEN_PATTERN.test(token)) {
+            if (!token || !isTelegramBotToken(token)) {
                 return toChannelResult(address, { ok: false, code: "missing_credentials" });
             }
-            // The base URL is the allowlist: only its own host is reachable.
-            let baseHost;
-            try {
-                baseHost = new URL(apiBaseUrl).hostname;
-            }
-            catch {
-                return toChannelResult(address, { ok: false, code: "host_not_allowed" });
-            }
             const result = await postChatWebhook({
                 url: `${apiBaseUrl.replace(/\/+$/, "")}/bot${token}/sendMessage`,
-                allowedHosts: [baseHost],
-                requireHttps: apiBaseUrl.startsWith("https:"),
+                allowedHosts,
+                requireHttps,
                 timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
                 // No parse_mode: Telegram renders the text literally.
                 body: {

package/dist/delivery/chat-webhook-channel.d.ts

@@ -1,4 +1,4 @@
-import { type ChatSendResult } from "./chat-webhook-sender.js";
+import { type ChatSendResult, type ChatWebhookTarget } from "./chat-webhook-sender.js";
 import type { ChannelMessage, ChannelResult, DeliveryChannel } from "./types.js";
 export type ChatWebhookChannelOptions = {
     readonly allowedHosts?: readonly string[];
@@ -7,6 +7,10 @@ export type ChatWebhookChannelOptions = {
 };
 export declare function toChannelResult(address: string, result: ChatSendResult): ChannelResult;
 export declare function chatMessageText(message: ChannelMessage): string;
+export declare function resolveChatWebhookTarget(provider: {
+    readonly defaultAllowedHosts: readonly string[];
+    readonly requiredPathPrefix?: string;
+}, options: ChatWebhookChannelOptions): ChatWebhookTarget;
 export type ChatWebhookChannelSpec = {
     readonly name: string;
     readonly featureName: string;

package/dist/delivery/chat-webhook-channel.js

@@ -8,6 +8,15 @@ export function toChannelResult(address, result) {
 export function chatMessageText(message) {
     return message.body ? `${message.title}\n${message.body}` : message.title;
 }
+export function resolveChatWebhookTarget(provider, options) {
+    return {
+        allowedHosts: options.allowedHosts ?? provider.defaultAllowedHosts,
+        requireHttps: options.requireHttps ?? true,
+        ...(provider.requiredPathPrefix !== undefined && {
+            requiredPathPrefix: provider.requiredPathPrefix,
+        }),
+    };
+}
 // Slack/Discord/Teams: the route address is a tenant-chosen connection name, the
 // webhook URL lives in the secrets store under that name. Route-only (no resolve).
 export function createChatWebhookChannel(spec) {
@@ -34,11 +43,7 @@ export function createChatWebhookChannel(spec) {
                 return toChannelResult(address, { ok: false, code: "missing_credentials" });
             const result = await postChatWebhook({
                 url,
-                allowedHosts: options.allowedHosts ?? spec.defaultAllowedHosts,
-                requireHttps: options.requireHttps ?? true,
-                ...(spec.requiredPathPrefix !== undefined && {
-                    requiredPathPrefix: spec.requiredPathPrefix,
-                }),
+                ...resolveChatWebhookTarget(spec, options),
                 timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
                 body: spec.buildBody(message),
             });

package/dist/delivery/chat-webhook-sender.d.ts

@@ -8,14 +8,18 @@ export type ChatSendResult = {
 };
 export declare const DEFAULT_CHAT_TIMEOUT_MS = 10000;
 export declare const chatConnectionNameSchema: z.ZodString;
-export type ChatWebhookRequest = {
-    readonly url: string;
+export type ChatWebhookTarget = {
     readonly allowedHosts: readonly string[];
     readonly requireHttps: boolean;
     readonly requiredPathPrefix?: string;
+};
+export type ChatWebhookRequest = ChatWebhookTarget & {
+    readonly url: string;
     readonly timeoutMs: number;
     readonly body: unknown;
     readonly send?: (url: string, init: RequestInit) => Promise<Response>;
 };
+export declare function checkChatWebhookTarget(target: ChatWebhookTarget, url: string): URL | undefined;
+export declare function chatWebhookUrlSchema(target: ChatWebhookTarget): z.ZodType<string>;
 export declare function postChatWebhook(request: ChatWebhookRequest): Promise<ChatSendResult>;
 export declare function truncateChars(text: string, maxChars: number): string;

package/dist/delivery/chat-webhook-sender.js

@@ -27,31 +27,36 @@ function hostMatches(hostname, allowedHost) {
 }
 // Allowlist runs on the parsed URL, never on the raw string: userinfo
 // (`https://hooks.slack.com@evil.com`) and look-alike suffixes must not pass.
-function checkTarget(request) {
+export function checkChatWebhookTarget(target, url) {
     let parsed;
     try {
-        parsed = new URL(request.url);
+        parsed = new URL(url);
     }
     catch {
         return undefined;
     }
-    const protocolAllowed = parsed.protocol === "https:" || (!request.requireHttps && parsed.protocol === "http:");
+    const protocolAllowed = parsed.protocol === "https:" || (!target.requireHttps && parsed.protocol === "http:");
     if (!protocolAllowed)
         return undefined;
     // egress() has no port rule; a provider webhook over https never needs a custom port.
-    if (request.requireHttps && parsed.port !== "")
+    if (target.requireHttps && parsed.port !== "")
         return undefined;
     if (parsed.username !== "" || parsed.password !== "")
         return undefined;
     const hostname = parsed.hostname.toLowerCase();
-    if (!request.allowedHosts.some((allowed) => hostMatches(hostname, allowed)))
+    if (!target.allowedHosts.some((allowed) => hostMatches(hostname, allowed)))
         return undefined;
-    if (request.requiredPathPrefix !== undefined &&
-        !parsed.pathname.startsWith(request.requiredPathPrefix)) {
+    if (target.requiredPathPrefix !== undefined &&
+        !parsed.pathname.startsWith(target.requiredPathPrefix)) {
         return undefined;
     }
     return parsed;
 }
+export function chatWebhookUrlSchema(target) {
+    return z
+        .string()
+        .refine((url) => checkChatWebhookTarget(target, url) !== undefined, "invalid webhook url");
+}
 function isTimeout(err) {
     return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
 }
@@ -71,7 +76,7 @@ function classifyFailure(err) {
 // Never throws and never surfaces the URL: egress/Bun errors can carry it, so
 // every failure is reduced to a code here.
 export async function postChatWebhook(request) {
-    const target = checkTarget(request);
+    const target = checkChatWebhookTarget(request, request.url);
     if (!target)
         return { ok: false, code: "host_not_allowed" };
     let response;

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

@@ -1,8 +1,8 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { EscapeHatchAuditSink, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import type { EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import { type DeliveryChannel, type DeliveryService } from "./types.js";
 export type RateLimitConfig = {
@@ -20,7 +20,8 @@ export type DeliveryServiceOptions = {
     readonly rateLimit?: RateLimitConfig;
     readonly isChannelKilled?: KillSwitchResolver;
     readonly idempotencyRedis?: Redis;
-    readonly jobRunner?: JobRunner;
+    readonly jobRunner?: NotifyJobDispatcher;
+    readonly secrets?: SecretsContext;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly log?: Logger;
 };

package/dist/delivery/delivery-service.js

@@ -25,7 +25,7 @@ export function collectChannels(registry) {
 // 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, escapeHatchAuditSink, log, } = options;
+    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, escapeHatchAuditSink, log, } = options;
     const idemRedis = idempotencyRedis ?? rateLimit?.redis;
     // Rate limit check: atomic INCR + TTL + over-limit rollback via server-side
     // Lua. Runs single-threaded in Redis, so two parallel clients can't both
@@ -119,11 +119,21 @@ export function createDeliveryService(options) {
             ...bridgeStub(),
         }));
     }
+    function recordDelivery(run, entry, deliveryAttemptId) {
+        run.deliveries.push({
+            channel: entry.channel,
+            recipientId: entry.recipientId,
+            status: entry.status,
+            error: entry.error,
+            deliveryAttemptId,
+        });
+    }
     // Single-shot terminal log (inline channels, skips, idempotency dups). Async
     // attempts instead append a queued event up front and a terminal event from
     // the send job — see deliverViaChannel + jobs.ts.
-    async function logDelivery(entry) {
-        await logAttempt(db, registry, entry);
+    async function logDelivery(run, entry) {
+        const attemptId = await logAttempt(db, registry, entry);
+        recordDelivery(run, entry, attemptId);
     }
     // Deliver one resolved (channel, address) pair. Inline channels (inApp) and
     // the no-job-runner fallback render + send synchronously and log the terminal
@@ -131,13 +141,13 @@ export function createDeliveryService(options) {
     // hand off to the delivery.render (or delivery.send) job, which appends the
     // terminal event on the same attempt stream.
     async function deliverViaChannel(args) {
-        const { channel, address, message, channelCtx, tenantId, recipientId, notificationType, priority, } = args;
-        if (channel.mode === "queued" && jobRunner) {
+        const { run, channel, address, message, channelCtx, tenantId, recipientId, notificationType, priority, } = args;
+        if (channel.mode === "queued" && run.jobDispatcher) {
             // Async hand-off: record the attempt as queued, then dispatch the
             // render/send job — the terminal sent/failed event is appended by the
             // job, not here.
             const deliveryAttemptId = generateId();
-            await appendAttemptEvent(db, registry, deliveryAttemptId, {
+            const queuedEntry = {
                 tenantId,
                 notificationType,
                 channel: channel.name,
@@ -146,8 +156,9 @@ export function createDeliveryService(options) {
                 status: "queued",
                 error: null,
                 priority,
-            });
-            await jobRunner.dispatch(channel.render ? DeliveryJobs.render : DeliveryJobs.send, {
+            };
+            await appendAttemptEvent(db, registry, deliveryAttemptId, queuedEntry);
+            await run.jobDispatcher.dispatch(channel.render ? DeliveryJobs.render : DeliveryJobs.send, {
                 channelName: channel.name,
                 address,
                 tenantId,
@@ -157,12 +168,13 @@ export function createDeliveryService(options) {
                 priority,
                 message,
             }, { priority: deliveryPriorityRank[priority] });
+            recordDelivery(run, queuedEntry, deliveryAttemptId);
         }
         else {
             // Inline (inApp) or no-job-runner fallback: render + send synchronously.
             const rendered = channel.render ? await channel.render(message, channelCtx) : undefined;
             const result = await channel.send(address, message, channelCtx, rendered);
-            await logDelivery({
+            await logDelivery(run, {
                 tenantId,
                 notificationType,
                 channel: channel.name,
@@ -174,7 +186,7 @@ export function createDeliveryService(options) {
             });
         }
     }
-    function buildMessage(notificationType, data, channelName) {
+    function buildMessage(notificationType, data, channelName, locale) {
         // Look up per-channel template from notification definition
         const notifDef = registry.getAllNotifications().get(notificationType);
         const templateFn = notifDef?.templates?.[channelName];
@@ -186,6 +198,7 @@ export function createDeliveryService(options) {
                 title: channelData["title"] ?? data["title"] ?? notificationType,
                 body: channelData["body"],
                 data: channelData,
+                locale,
             };
         }
         // @cast-boundary engine-payload — generic notification.data shape
@@ -194,6 +207,7 @@ export function createDeliveryService(options) {
             title: data?.["title"] ?? notificationType,
             body: data?.["body"],
             data,
+            locale,
         };
     }
     // Shared by deliverToUser (resolved account address) and deliverDirect (a
@@ -226,18 +240,18 @@ export function createDeliveryService(options) {
         // and conservative — DB ordering no longer decides the outcome).
         return !prefs.some((p) => p.enabled === false);
     }
-    async function deliverToUser(userId, notificationType, data, tenantId, priority) {
-        const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+    async function deliverToUser(userId, notificationType, data, tenantId, priority, run) {
+        const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
         for (const channel of channels) {
             // Route-only channel (no per-user address): not a user-notification target.
             if (!channel.resolve)
                 continue;
-            const message = buildMessage(notificationType, data, channel.name);
+            const message = buildMessage(notificationType, data, channel.name, run.locale);
             // Kill switch: tenant admin disabled this channel entirely
             if (isChannelKilled) {
                 const killed = await isChannelKilled(tenantId, channel.name);
                 if (killed) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -254,7 +268,7 @@ export function createDeliveryService(options) {
             if (priority !== "critical") {
                 const enabled = await isChannelEnabled(userId, tenantId, notificationType, channel.name);
                 if (!enabled) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -271,7 +285,7 @@ export function createDeliveryService(options) {
             if (rateLimit) {
                 const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
                 if (!allowed) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -287,7 +301,7 @@ export function createDeliveryService(options) {
             try {
                 const address = await channel.resolve(userId, channelCtx);
                 if (!address) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -301,7 +315,7 @@ export function createDeliveryService(options) {
                 }
                 if (priority !== "critical" &&
                     (await isAddressSuppressed(address, tenantId, notificationType, channel.name))) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -314,6 +328,7 @@ export function createDeliveryService(options) {
                     continue;
                 }
                 await deliverViaChannel({
+                    run,
                     channel,
                     address,
                     message,
@@ -325,7 +340,7 @@ export function createDeliveryService(options) {
                 });
             }
             catch (err) {
-                await logDelivery({
+                await logDelivery(run, {
                     tenantId,
                     notificationType,
                     channel: channel.name,
@@ -338,20 +353,20 @@ export function createDeliveryService(options) {
             }
         }
     }
-    async function deliverDirect(route, notificationType, data, tenantId, priority, recipientId) {
-        const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+    async function deliverDirect(route, notificationType, data, tenantId, priority, recipientId, run) {
+        const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
         // 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) {
             const address = route[channel.name];
-            const message = buildMessage(notificationType, data, channel.name);
+            const message = buildMessage(notificationType, data, channel.name, run.locale);
             if (!address)
                 continue;
             // Address opt-out (critical priority skips it, same rule as user
             // preferences).
             if (priority !== "critical" &&
                 (await isAddressSuppressed(address, tenantId, notificationType, channel.name))) {
-                await logDelivery({
+                await logDelivery(run, {
                     tenantId,
                     notificationType,
                     channel: channel.name,
@@ -367,7 +382,7 @@ export function createDeliveryService(options) {
             if (rateLimit) {
                 const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
                 if (!allowed) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: channel.name,
@@ -382,6 +397,7 @@ export function createDeliveryService(options) {
             }
             try {
                 await deliverViaChannel({
+                    run,
                     channel,
                     address,
                     message,
@@ -393,7 +409,7 @@ export function createDeliveryService(options) {
                 });
             }
             catch (err) {
-                await logDelivery({
+                await logDelivery(run, {
                     tenantId,
                     notificationType,
                     channel: channel.name,
@@ -407,13 +423,18 @@ export function createDeliveryService(options) {
         }
     }
     return {
-        async notify(notificationType, options, _user, tenantId) {
+        async notify(notificationType, options, _user, tenantId, jobDispatcher) {
             const { to, route, data, idempotencyKey } = options;
             const priority = options.priority ?? "normal";
+            const run = {
+                deliveries: [],
+                jobDispatcher: options.immediate ? undefined : (jobDispatcher ?? jobRunner),
+                locale: options.locale,
+            };
             if (idempotencyKey) {
                 const first = await claimIdempotency(tenantId, idempotencyKey);
                 if (!first) {
-                    await logDelivery({
+                    await logDelivery(run, {
                         tenantId,
                         notificationType,
                         channel: "*",
@@ -423,14 +444,12 @@ export function createDeliveryService(options) {
                         error: "duplicate_idempotency_key",
                         priority,
                     });
-                    // skip: duplicate send deduped via idempotency key, logged above
-                    return;
+                    return { deliveries: run.deliveries };
                 }
             }
             if (route) {
-                await deliverDirect(route, notificationType, data, tenantId, priority, options.recipientId ?? null);
-                // skip: direct route delivered, no recipient resolution needed
-                return;
+                await deliverDirect(route, notificationType, data, tenantId, priority, options.recipientId ?? null, run);
+                return { deliveries: run.deliveries };
             }
             if (to !== undefined) {
                 let userIds;
@@ -444,9 +463,10 @@ export function createDeliveryService(options) {
                     userIds = to;
                 }
                 for (const userId of userIds) {
-                    await deliverToUser(userId, notificationType, data, tenantId, priority);
+                    await deliverToUser(userId, notificationType, data, tenantId, priority, run);
                 }
             }
+            return { deliveries: run.deliveries };
         },
     };
 }

package/dist/delivery/index.d.ts

@@ -1,6 +1,6 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
-export { type ChatWebhookChannelOptions, chatMessageText, createChatWebhookChannel, toChannelResult, } from "./chat-webhook-channel.js";
-export { type ChatSendFailureCode, type ChatSendResult, type ChatWebhookRequest, chatConnectionNameSchema, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
+export { type ChatWebhookChannelOptions, chatMessageText, createChatWebhookChannel, resolveChatWebhookTarget, toChannelResult, } from "./chat-webhook-channel.js";
+export { type ChatSendFailureCode, type ChatSendResult, type ChatWebhookRequest, type ChatWebhookTarget, chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
 export type { DeliveryStatusValue } from "./constants.js";
 export { DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";

package/dist/delivery/index.js

@@ -1,6 +1,6 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
-export { chatMessageText, createChatWebhookChannel, toChannelResult, } from "./chat-webhook-channel.js";
-export { chatConnectionNameSchema, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.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_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";

package/dist/delivery/jobs.js

@@ -15,6 +15,7 @@ const channelMessageSchema = z.object({
     title: z.string(),
     body: z.string().optional(),
     data: z.record(z.string(), z.unknown()).optional(),
+    locale: z.string().optional(),
 });
 const renderJobPayloadSchema = z.object({
     channelName: z.string(),
@@ -56,6 +57,7 @@ function toMessage(p) {
         title: p.message.title,
         body: p.message.body,
         data: p.message.data,
+        locale: p.message.locale,
     };
 }
 function entryFor(p, status, error, address) {
@@ -81,7 +83,7 @@ export const deliveryRenderJob = async (payload, 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);
+    const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
     try {
         if (!channel.render) {
             throw new Error(`delivery.render: channel "${p.channelName}" has no render step`);