@cosmicdrift/kumiko-samples 0.339.0 → 0.341.0

package/packages/bundled-features/src/channel-telegram/index.ts

@@ -1,2 +1,9 @@
 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/packages/bundled-features/src/channel-telegram/telegram-channel.ts

@@ -10,30 +10,65 @@ import {
 
 export type TelegramChannelOptions = {
   // App-level override (tests, self-hosted Bot API server); never tenant config.
+  // Its host must be listed in `allowedHosts`, otherwise boot fails.
   readonly apiBaseUrl?: string;
+  // Replaces the default allowlist (`api.telegram.org`); required for a self-hosted Bot API server.
+  readonly allowedHosts?: readonly string[];
+  // Default true; `false` only for local http test servers.
+  readonly requireHttps?: boolean;
   readonly timeoutMs?: number;
 };
 
 export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_DEFAULT_ALLOWED_HOSTS: readonly string[] = ["api.telegram.org"];
 export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export const TELEGRAM_SECRET_KEYS = { botToken: "channel-telegram:secret:bot-token" } as const;
 
 // 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: string): boolean {
+  return TELEGRAM_CHAT_ID_PATTERN.test(address);
+}
+
+export function isTelegramBotToken(token: string): boolean {
+  return TELEGRAM_BOT_TOKEN_PATTERN.test(token);
+}
+
 export function createTelegramChannel(
   options: TelegramChannelOptions,
   botTokenKey: string,
 ): DeliveryChannel {
   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: URL;
+  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: string | undefined;
@@ -46,21 +81,14 @@ export function createTelegramChannel(
       } 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: string;
-      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/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "breaking",
+    "title": "Chat channels deliver in production boot, ctx.notify returns a NotifyResult",
+    "detail": "Chat channels (slack, discord, teams, telegram) now deliver in production boot. `runProdApp`, `runDevApp` and `runWorkerApp` pass the tenant secrets to the delivery service and hand queued channels to the `delivery.render`/`delivery.send` jobs of the calling context's job runner. `delivery.render` now receives `ctx.secrets` as well. Without a job runner, queued channels still deliver inline, now with secrets. `runBootstrap` is a one-shot process whose queue nobody drains after it exits, so it keeps delivering queued channels inline (the SystemAdmin invitation goes out before the process ends).\n`NotifyFn` returns a `NotifyResult` (`{ deliveries }` with channel, recipientId, status `queued | sent | failed | skipped`, error and `deliveryAttemptId` per delivery) instead of `void`. `NotifyOptions.immediate` delivers queued channels inline for one call and bypasses job retry, for \"send test message\" handlers. `NotifyFactory` takes an optional job dispatcher as third argument, and `DeliveryService.notify` an optional per-call dispatcher.\nConsumers: `NotifyFn` implementations in tests and mocks must now return a `NotifyResult`, e.g. `async () => ({ deliveries: [] })`. When running the API without a worker (`runSingleInstance: false`), a dedicated worker must process the delivery jobs.",
+    "migration": "NotifyFn implementations in tests and mocks must return a NotifyResult, e.g. async () => ({ deliveries: [] }). Queued channels now run through the delivery jobs in production; an API-only deployment (runSingleInstance: false) needs a worker that mounts delivery and the channel features."
+  },
   {
     "version": "0.339.0",
     "type": "improvement",

package/packages/bundled-features/src/delivery/chat-webhook-channel.ts

@@ -1,6 +1,7 @@
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import {
   type ChatSendResult,
+  type ChatWebhookTarget,
   chatConnectionNameSchema,
   DEFAULT_CHAT_TIMEOUT_MS,
   postChatWebhook,
@@ -25,6 +26,22 @@ export function chatMessageText(message: ChannelMessage): string {
   return message.body ? `${message.title}\n${message.body}` : message.title;
 }
 
+export function resolveChatWebhookTarget(
+  provider: {
+    readonly defaultAllowedHosts: readonly string[];
+    readonly requiredPathPrefix?: string;
+  },
+  options: ChatWebhookChannelOptions,
+): ChatWebhookTarget {
+  return {
+    allowedHosts: options.allowedHosts ?? provider.defaultAllowedHosts,
+    requireHttps: options.requireHttps ?? true,
+    ...(provider.requiredPathPrefix !== undefined && {
+      requiredPathPrefix: provider.requiredPathPrefix,
+    }),
+  };
+}
+
 export type ChatWebhookChannelSpec = {
   readonly name: string;
   readonly featureName: string;
@@ -62,11 +79,7 @@ export function createChatWebhookChannel(spec: ChatWebhookChannelSpec): Delivery
 
       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/packages/bundled-features/src/delivery/chat-webhook-sender.ts

@@ -28,12 +28,15 @@ export const chatConnectionNameSchema = z
   .max(64)
   .regex(/^[a-z0-9][a-z0-9-]*$/);
 
-export type ChatWebhookRequest = {
-  readonly url: string;
+export type ChatWebhookTarget = {
   // Exact hostnames, or suffixes with a leading dot (".webhook.office.com").
   readonly allowedHosts: readonly string[];
   readonly requireHttps: boolean;
   readonly requiredPathPrefix?: string;
+};
+
+export type ChatWebhookRequest = ChatWebhookTarget & {
+  readonly url: string;
   readonly timeoutMs: number;
   readonly body: unknown;
   // Test seam; production always uses the policy-bound egress().
@@ -60,30 +63,36 @@ function hostMatches(hostname: string, allowedHost: string): boolean {
 
 // 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: ChatWebhookRequest): URL | undefined {
+export function checkChatWebhookTarget(target: ChatWebhookTarget, url: string): URL | undefined {
   let parsed: URL;
   try {
-    parsed = new URL(request.url);
+    parsed = new URL(url);
   } catch {
     return undefined;
   }
   const protocolAllowed =
-    parsed.protocol === "https:" || (!request.requireHttps && parsed.protocol === "http:");
+    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 !== "") return undefined;
+  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))) return undefined;
+  if (!target.allowedHosts.some((allowed) => hostMatches(hostname, allowed))) return undefined;
   if (
-    request.requiredPathPrefix !== undefined &&
-    !parsed.pathname.startsWith(request.requiredPathPrefix)
+    target.requiredPathPrefix !== undefined &&
+    !parsed.pathname.startsWith(target.requiredPathPrefix)
   ) {
     return undefined;
   }
   return parsed;
 }
 
+export function chatWebhookUrlSchema(target: ChatWebhookTarget): z.ZodType<string> {
+  return z
+    .string()
+    .refine((url) => checkChatWebhookTarget(target, url) !== undefined, "invalid webhook url");
+}
+
 function isTimeout(err: unknown): boolean {
   return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
 }
@@ -104,7 +113,7 @@ function classifyFailure(err: unknown): ChatSendFailureCode {
 // 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: ChatWebhookRequest): Promise<ChatSendResult> {
-  const target = checkTarget(request);
+  const target = checkChatWebhookTarget(request, request.url);
   if (!target) return { ok: false, code: "host_not_allowed" };
 
   let response: Response;

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

@@ -3,14 +3,16 @@ import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
   EscapeHatchAuditSink,
+  NotifyDelivery,
+  NotifyJobDispatcher,
   NotifyPriority,
   Registry,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
-import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
@@ -49,10 +51,14 @@ export type DeliveryServiceOptions = {
   // Must be present whenever callers rely on idempotencyKey, otherwise notify()
   // throws at the callsite (silent no-op would be a correctness bug).
   readonly idempotencyRedis?: Redis;
-  // Job runner for async (queued-mode) channels: email/push render+send run in
-  // the delivery.render → delivery.send jobs. When absent, queued channels fall
-  // back to synchronous inline delivery (job-less setups, unit tests).
-  readonly jobRunner?: JobRunner;
+  // Job dispatcher for async (queued-mode) channels: email/push/chat render+send
+  // run in the delivery.render → delivery.send jobs. notify() may override it per
+  // call. When neither is present, queued channels fall back to synchronous
+  // inline delivery (job-less setups, unit tests).
+  readonly jobRunner?: NotifyJobDispatcher;
+  // Credentials source for inline-delivered chat channels (webhook URL / bot
+  // token). Jobs get ctx.secrets from the job runner instead.
+  readonly secrets?: SecretsContext;
   // Attributed escape-hatch audit for resolveUserIdsForTenant's ctx.systemDb —
   // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
@@ -88,6 +94,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     isChannelKilled,
     idempotencyRedis,
     jobRunner,
+    secrets,
     escapeHatchAuditSink,
     log,
   } = options;
@@ -207,11 +214,34 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     )) as readonly string[];
   }
 
+  // State of one notify() call: collects the per-channel outcome returned to
+  // the caller. Passed explicitly — the service itself is shared across calls.
+  type NotifyRun = {
+    readonly deliveries: NotifyDelivery[];
+    readonly jobDispatcher: NotifyJobDispatcher | undefined;
+    readonly locale: string | undefined;
+  };
+
+  function recordDelivery(
+    run: NotifyRun,
+    entry: DeliveryLogEntry,
+    deliveryAttemptId: string,
+  ): void {
+    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: DeliveryLogEntry): Promise<void> {
-    await logAttempt(db, registry, entry);
+  async function logDelivery(run: NotifyRun, entry: DeliveryLogEntry): Promise<void> {
+    const attemptId = await logAttempt(db, registry, entry);
+    recordDelivery(run, entry, attemptId);
   }
 
   // Deliver one resolved (channel, address) pair. Inline channels (inApp) and
@@ -220,6 +250,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   // hand off to the delivery.render (or delivery.send) job, which appends the
   // terminal event on the same attempt stream.
   async function deliverViaChannel(args: {
+    run: NotifyRun;
     channel: DeliveryChannel;
     address: string;
     message: ChannelMessage;
@@ -230,6 +261,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     priority: NotifyPriority;
   }): Promise<void> {
     const {
+      run,
       channel,
       address,
       message,
@@ -240,12 +272,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       priority,
     } = args;
 
-    if (channel.mode === "queued" && jobRunner) {
+    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: DeliveryLogEntry = {
         tenantId,
         notificationType,
         channel: channel.name,
@@ -254,8 +286,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         status: "queued",
         error: null,
         priority,
-      });
-      await jobRunner.dispatch(
+      };
+      await appendAttemptEvent(db, registry, deliveryAttemptId, queuedEntry);
+      await run.jobDispatcher.dispatch(
         channel.render ? DeliveryJobs.render : DeliveryJobs.send,
         {
           channelName: channel.name,
@@ -269,11 +302,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         },
         { 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,
@@ -290,6 +324,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     notificationType: string,
     data: Readonly<Record<string, unknown>> | undefined,
     channelName: string,
+    locale: string | undefined,
   ): ChannelMessage {
     // Look up per-channel template from notification definition
     const notifDef = registry.getAllNotifications().get(notificationType);
@@ -303,6 +338,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         title: (channelData["title"] as string) ?? (data["title"] as string) ?? notificationType,
         body: channelData["body"] as string | undefined,
         data: channelData,
+        locale,
       };
     }
 
@@ -312,6 +348,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       title: (data?.["title"] as string) ?? notificationType,
       body: data?.["body"] as string | undefined,
       data,
+      locale,
     };
   }
 
@@ -371,20 +408,21 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     data: Readonly<Record<string, unknown>> | undefined,
     tenantId: TenantId,
     priority: NotifyPriority,
+    run: NotifyRun,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+    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,
@@ -402,7 +440,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       if (priority !== "critical") {
         const enabled = await isChannelEnabled(userId, tenantId, notificationType, channel.name);
         if (!enabled) {
-          await logDelivery({
+          await logDelivery(run, {
             tenantId,
             notificationType,
             channel: channel.name,
@@ -420,7 +458,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       if (rateLimit) {
         const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
         if (!allowed) {
-          await logDelivery({
+          await logDelivery(run, {
             tenantId,
             notificationType,
             channel: channel.name,
@@ -437,7 +475,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       try {
         const address = await channel.resolve(userId, channelCtx);
         if (!address) {
-          await logDelivery({
+          await logDelivery(run, {
             tenantId,
             notificationType,
             channel: channel.name,
@@ -454,7 +492,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           priority !== "critical" &&
           (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
         ) {
-          await logDelivery({
+          await logDelivery(run, {
             tenantId,
             notificationType,
             channel: channel.name,
@@ -468,6 +506,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         }
 
         await deliverViaChannel({
+          run,
           channel,
           address,
           message,
@@ -478,7 +517,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           priority,
         });
       } catch (err) {
-        await logDelivery({
+        await logDelivery(run, {
           tenantId,
           notificationType,
           channel: channel.name,
@@ -499,14 +538,15 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantId: TenantId,
     priority: NotifyPriority,
     recipientId: string | null,
+    run: NotifyRun,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+    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
@@ -515,7 +555,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         priority !== "critical" &&
         (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
       ) {
-        await logDelivery({
+        await logDelivery(run, {
           tenantId,
           notificationType,
           channel: channel.name,
@@ -532,7 +572,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       if (rateLimit) {
         const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
         if (!allowed) {
-          await logDelivery({
+          await logDelivery(run, {
             tenantId,
             notificationType,
             channel: channel.name,
@@ -548,6 +588,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
       try {
         await deliverViaChannel({
+          run,
           channel,
           address,
           message,
@@ -558,7 +599,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           priority,
         });
       } catch (err) {
-        await logDelivery({
+        await logDelivery(run, {
           tenantId,
           notificationType,
           channel: channel.name,
@@ -573,14 +614,19 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
   }
 
   return {
-    async notify(notificationType, options, _user, tenantId) {
+    async notify(notificationType, options, _user, tenantId, jobDispatcher) {
       const { to, route, data, idempotencyKey } = options;
       const priority: NotifyPriority = options.priority ?? "normal";
+      const run: NotifyRun = {
+        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: "*",
@@ -590,8 +636,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             error: "duplicate_idempotency_key",
             priority,
           });
-          // skip: duplicate send deduped via idempotency key, logged above
-          return;
+          return { deliveries: run.deliveries };
         }
       }
 
@@ -603,9 +648,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           tenantId,
           priority,
           options.recipientId ?? null,
+          run,
         );
-        // skip: direct route delivered, no recipient resolution needed
-        return;
+        return { deliveries: run.deliveries };
       }
 
       if (to !== undefined) {
@@ -620,9 +665,10 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         }
 
         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/packages/bundled-features/src/delivery/index.ts

@@ -3,13 +3,17 @@ 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,

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

@@ -31,6 +31,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({
@@ -82,6 +83,7 @@ function toMessage(p: RenderJobPayload): ChannelMessage {
     title: p.message.title,
     body: p.message.body,
     data: p.message.data,
+    locale: p.message.locale,
   };
 }
 
@@ -115,7 +117,7 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
   const tenantId = p.tenantId as 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) {

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

@@ -1,8 +1,11 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  NotifyDeliveryStatus,
+  NotifyJobDispatcher,
   NotifyOptions,
   NotifyPriority,
+  NotifyResult,
   Registry,
   SessionUser,
   TenantId,
@@ -17,8 +20,8 @@ export type ChannelContext = {
   readonly registry: Registry;
   readonly sseBroker: SseBroker | undefined;
   readonly tenantId: TenantId;
-  // Only wired on the delivery.send job path. Chat channels read their
-  // per-tenant webhook URL / bot token from it; inline sends have none.
+  // Chat channels read their per-tenant webhook URL / bot token from it.
+  // Absent when no secrets feature/KEK is wired.
   readonly secrets?: SecretsContext | undefined;
 };
 
@@ -27,6 +30,7 @@ export type ChannelMessage = {
   readonly title: string;
   readonly body: string | undefined;
   readonly data: Readonly<Record<string, unknown>> | undefined;
+  readonly locale?: string | undefined;
 };
 
 export type ChannelResult = {
@@ -70,6 +74,7 @@ export type DeliveryChannel = {
 export type RendererInput = {
   readonly template: string;
   readonly variables: Readonly<Record<string, unknown>>;
+  readonly locale?: string | undefined;
 };
 
 export type NotificationRenderer = {
@@ -85,7 +90,7 @@ export type DeliveryLogEntry = {
   readonly channel: string;
   readonly recipientId: string | null;
   readonly recipientAddress: string | null;
-  readonly status: "queued" | "sent" | "failed" | "skipped";
+  readonly status: NotifyDeliveryStatus;
   readonly error: string | null;
   readonly priority: NotifyPriority;
 };
@@ -98,7 +103,8 @@ export type DeliveryService = {
     options: NotifyOptions,
     user: SessionUser,
     tenantId: TenantId,
-  ): Promise<void>;
+    jobDispatcher?: NotifyJobDispatcher,
+  ): Promise<NotifyResult>;
 };
 
 // r.useExtension options-shape: `name` is NOT part of the registration