@cosmicdrift/kumiko-samples 0.338.0 → 0.340.0

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -12,6 +12,7 @@
 
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants.js";
+import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.js";
 
 // Aggregate-type für den event-store. Eine subscription pro Tenant ist
 // ein stream; der subscriptionAggregateId-helper liefert die stream-id.
@@ -196,6 +197,23 @@ export type ContractTerminationRequestedPayload = z.infer<
   typeof contractTerminationRequestedPayloadSchema
 >;
 
+// A public declaration matched to this tenant. The provider cancel runs in a
+// job triggered by this event, so the request itself only looks up and appends.
+export const CONTRACT_TERMINATION_DECLARED_EVENT_SHORT = "contract-termination-declared" as const;
+export const CONTRACT_TERMINATION_DECLARED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_DECLARED_EVENT_SHORT}` as const;
+
+export const contractTerminationDeclaredPayloadSchema = z.object({
+  requestId: z.string().min(1).max(100),
+  declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+  terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+  receivedAtIso: z.string().min(1),
+  locale: z.enum(CONSENT_LOCALES),
+});
+export type ContractTerminationDeclaredPayload = z.infer<
+  typeof contractTerminationDeclaredPayloadSchema
+>;
+
 export const CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE =
   "contract-termination-unmatched" as const;
 export const CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT = "contract-termination-unmatched" as const;

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -64,7 +64,7 @@ export function createCheckoutSessionHandler(
 ): WriteHandlerDef {
   const consumerProtection = options.consumerProtection;
   const schema = consumerProtection
-    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema })
+    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() })
     : createCheckoutSessionSchema;
   return {
     name: "create-checkout-session",
@@ -79,10 +79,9 @@ export function createCheckoutSessionHandler(
       const payload = event.payload as CreateCheckoutSessionPayload;
 
       const mode = payload.mode ?? "subscription";
-      const consent =
-        consumerProtection && payload.consent
-          ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
-          : undefined;
+      const consent = consumerProtection
+        ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
+        : undefined;
 
       const result = await openCheckout(
         ctx,

package/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts

@@ -35,7 +35,9 @@ export function createStartPlanCheckoutHandler(
   const consumerProtection = options.consumerProtection;
   const tierSchema = z.object({ tier: z.enum(plans) });
   const schema = (
-    consumerProtection ? tierSchema.extend({ consent: consentPayloadSchema }) : tierSchema
+    consumerProtection
+      ? tierSchema.extend({ consent: consentPayloadSchema.optional() })
+      : tierSchema
   ).strict();
 
   return {
@@ -65,10 +67,9 @@ export function createStartPlanCheckoutHandler(
         });
       }
 
-      const consent =
-        consumerProtection && payload.consent
-          ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
-          : undefined;
+      const consent = consumerProtection
+        ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
+        : undefined;
 
       const baseUrl = options.baseUrl ?? "";
       const result = await openCheckout(

package/packages/bundled-features/src/billing-foundation/i18n.ts

@@ -124,6 +124,9 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.priceUnavailable": {
     en: "This plan's price is temporarily unavailable.",
   },
+  "billing-foundation.errors.consentRequired": {
+    en: "Confirm both consent boxes before you continue.",
+  },
   "billing-foundation.errors.consentTextOutdated": {
     en: "The consent text has changed. Reload the page and confirm again.",
   },

package/packages/bundled-features/src/billing-foundation/projection.ts

@@ -14,11 +14,14 @@
 // `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
 // import). setupTestStack pusht sie automatisch via r.projection.table.
 
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  insertOnConflictDoNothing,
+  requireEntityTableMeta,
+  upsertOnConflict,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { paymentRowId } from "./aggregate-id.js";
-import { insertPaymentProjectionRow } from "./db/queries/payment-projection.js";
-import { upsertSubscriptionProjectionRow } from "./db/queries/subscription-projection.js";
 import { paymentEntity, subscriptionEntity } from "./entities.js";
 import type { PaymentEventPayload, SubscriptionEventPayload } from "./events.js";
 
@@ -32,6 +35,17 @@ export const subscriptionsProjectionTable = buildEntityTable("subscription", sub
 // production must add read_payments to their own drizzle/generate.ts too.
 export const paymentsProjectionTable = buildEntityTable("payment", paymentEntity);
 
+// Unbranded metas: the apply functions below ARE the executor of these
+// projections, so they may write through the typed helpers.
+const subscriptionsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  subscriptionsProjectionTable,
+  "subscription",
+);
+const paymentsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  paymentsProjectionTable,
+  "payment",
+);
+
 // =============================================================================
 // Shared helpers
 // =============================================================================
@@ -69,9 +83,7 @@ function cancelAtSetFromPayload(p: SubscriptionEventPayload): {
  *  on every apply including the initial create — a projection rebuild at a
  *  different wall-clock time must materialize the exact same row, and
  *  `getSubscriptionForTenant`'s `lastChangedAt` (staleness check for
- *  incomplete subscriptions) depends on that determinism. Raw `.unsafe()`
- *  bypasses the typed query-builder's Temporal.Instant-to-string coercion,
- *  hence the explicit `.toString()`. */
+ *  incomplete subscriptions) depends on that determinism. */
 async function upsert(
   tx: Parameters<Parameters<typeof defineApply<SubscriptionEventPayload>>[0]>[1],
   event: { aggregateId: string; tenantId: string; createdAt: Temporal.Instant },
@@ -92,38 +104,21 @@ async function upsert(
   // INSERT-Pfad und nur den teil-`set` für ON CONFLICT.
   const insertCols = {
     id: event.aggregateId,
-    tenant_id: event.tenantId,
-    provider_name: fullPayload.providerName,
-    provider_customer_id: fullPayload.providerCustomerId,
-    provider_subscription_id: fullPayload.providerSubscriptionId,
+    tenantId: event.tenantId,
+    providerName: fullPayload.providerName,
+    providerCustomerId: fullPayload.providerCustomerId,
+    providerSubscriptionId: fullPayload.providerSubscriptionId,
     status: fullPayload.status,
     tier: fullPayload.tier,
-    current_period_end: fullPayload.currentPeriodEndIso,
-    cancel_at: fullPayload.cancelAtIso ?? null,
-    modified_at: event.createdAt.toString(),
+    currentPeriodEnd: fullPayload.currentPeriodEndIso,
+    cancelAt: fullPayload.cancelAtIso ?? null,
+    modifiedAt: event.createdAt,
   };
-  // Map camelCase set-keys to snake_case DB columns.
-  const setMap: Record<keyof typeof set, string> = {
-    providerName: "provider_name",
-    providerCustomerId: "provider_customer_id",
-    providerSubscriptionId: "provider_subscription_id",
-    status: "status",
-    tier: "tier",
-    currentPeriodEnd: "current_period_end",
-    cancelAt: "cancel_at",
-  };
-  const insertParams = Object.values(insertCols);
-  const setEntries = Object.entries(set).filter(([, v]) => v !== undefined);
-  // modified_at is already bound as the last insertParams placeholder —
-  // reused (not re-pushed) for the ON CONFLICT SET clause below.
-  const setClauses: string[] = [`"modified_at" = $${insertParams.length}`];
-  const allParams: unknown[] = [...insertParams];
-  for (const [k, v] of setEntries) {
-    allParams.push(v);
-    setClauses.push(`"${setMap[k as keyof typeof set]}" = $${allParams.length}`);
-  }
-  const tableName = (subscriptionsProjectionTable as { tableName: string }).tableName;
-  await upsertSubscriptionProjectionRow(tx, tableName, insertCols, setClauses, allParams);
+  const definedSet = Object.fromEntries(Object.entries(set).filter(([, v]) => v !== undefined));
+  await upsertOnConflict(tx, subscriptionsProjectionMeta, insertCols, {
+    conflictKeys: ["id"],
+    update: { modifiedAt: event.createdAt, ...definedSet },
+  });
 }
 
 // =============================================================================
@@ -209,7 +204,6 @@ export const applyInvoicePaymentFailed = defineApply<SubscriptionEventPayload>(
  *  the second tenant's row. ON CONFLICT DO NOTHING also makes a projection
  *  rebuild idempotent without mutating an existing row. */
 export const applyPaymentReceived = defineApply<PaymentEventPayload>(async (event, tx) => {
-  const tableName = (paymentsProjectionTable as { tableName: string }).tableName;
   const providerEventId = event.metadata.headers?.["providerEventId"];
   const providerName = event.metadata.headers?.["providerName"];
   if (typeof providerEventId !== "string" || typeof providerName !== "string") {
@@ -217,11 +211,11 @@ export const applyPaymentReceived = defineApply<PaymentEventPayload>(async (even
       "applyPaymentReceived: event.metadata.headers is missing providerEventId/providerName — process-payment-event.write.ts always sets both",
     );
   }
-  await insertPaymentProjectionRow(tx, tableName, {
+  await insertOnConflictDoNothing(tx, paymentsProjectionMeta, {
     id: paymentRowId(event.tenantId, providerName, providerEventId),
-    tenant_id: event.tenantId,
-    provider_name: event.payload.providerName,
-    provider_customer_id: event.payload.providerCustomerId,
-    price_id: event.payload.priceId,
+    tenantId: event.tenantId,
+    providerName: event.payload.providerName,
+    providerCustomerId: event.payload.providerCustomerId,
+    priceId: event.payload.priceId,
   });
 });

package/packages/bundled-features/src/billing-foundation/tenant-destroy-hook.ts

@@ -26,7 +26,7 @@ export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON =
 export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
   declareEscapeHatch({ reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON),
+    db: ctx.db.unsafeRaw(),
     tenantId: ctx.tenantId,
   });
   const aggregateId = subscriptionAggregateId(ctx.tenantId);
@@ -39,7 +39,7 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
   } else {
     await ctx.db.deleteMany(subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
   }
-  await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
+  await archiveStream(ctx.db.unsafeRaw(), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
@@ -56,7 +56,7 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
 export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
   declareEscapeHatch({ reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON),
+    db: ctx.db.unsafeRaw(),
     tenantId: ctx.tenantId,
   });
   const aggregateId = paymentAggregateId(ctx.tenantId);
@@ -71,7 +71,7 @@ export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<
       tenantId: ctx.tenantId,
     });
   }
-  await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
+  await archiveStream(ctx.db.unsafeRaw(), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: PAYMENT_AGGREGATE_TYPE,

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -35,6 +35,7 @@ import {
   type SubscriptionCancelTiming,
   type SubscriptionEventType,
   type SubscriptionStatus,
+  type TerminationScope,
 } from "./constants.js";
 
 // =============================================================================
@@ -389,6 +390,11 @@ export type ConsumerProtectionOptions = {
   /** Per-locale VAT note; must carry at least `de` and `en`. */
   readonly vatNote: Readonly<Record<string, string>>;
   readonly operatorEmail: string;
+  /** Where the public § 312k declaration is reachable. `"tenant-host"`
+   *  (default): on a host that resolves a tenant. `"platform"`: also on a
+   *  host that resolves none (the platform apex) — the declaration then runs
+   *  without a request tenant and finds the contract by the declarant's email. */
+  readonly terminationScope?: TerminationScope;
   /** Root-relative paths or absolute https URLs. */
   readonly legalLinks: {
     readonly terms: string;

package/packages/bundled-features/src/billing-foundation/validate-options.ts

@@ -4,6 +4,7 @@
 // re-exported from index.ts.
 
 import * as z from "zod";
+import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
 import type { BillingFoundationOptions, ConsumerProtectionOptions } from "./types.js";
 
 function isRootRelativePath(path: string): boolean {
@@ -35,6 +36,11 @@ function validateConsumerProtection(cp: ConsumerProtectionOptions): void {
       `createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`,
     );
   }
+  if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
+    throw new Error(
+      `createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`,
+    );
+  }
   for (const [key, link] of Object.entries(cp.legalLinks)) {
     if (!isRootRelativeOrHttpsUrl(link)) {
       throw new Error(

package/packages/bundled-features/src/channel-discord/discord-channel.ts

@@ -0,0 +1,32 @@
+import {
+  type ChatWebhookChannelOptions,
+  chatMessageText,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+  truncateChars,
+} from "../delivery/index.js";
+
+export type DiscordChannelOptions = ChatWebhookChannelOptions;
+
+export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"] as const;
+export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export const DISCORD_CONTENT_MAX_CHARS = 2000;
+
+export function createDiscordChannel(
+  options: DiscordChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "discord",
+    featureName: "channel-discord",
+    defaultAllowedHosts: DISCORD_DEFAULT_ALLOWED_HOSTS,
+    requiredPathPrefix: DISCORD_WEBHOOK_PATH_PREFIX,
+    keyFor,
+    // parse: [] keeps @everyone / @here / role and user mentions in the text inert.
+    buildBody: (message) => ({
+      content: truncateChars(chatMessageText(message), DISCORD_CONTENT_MAX_CHARS),
+      allowed_mentions: { parse: [] },
+    }),
+    options,
+  });
+}

package/packages/bundled-features/src/channel-discord/feature.ts

@@ -0,0 +1,40 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+
+export function createChannelDiscordFeature(
+  options: DiscordChannelOptions = {},
+): FeatureDefinition {
+  return defineFeature("channel-discord", (r) => {
+    r.describe(
+      'Posts delivery notifications to a Discord webhook, registered as the `discord` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { discord: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-discord:webhooks.<connection name>`; only the connection name is logged. Mentions are disabled and content is cut to 2000 characters. Requires `delivery` and `secrets`. Host allowlist (discord.com, discordapp.com, path /api/webhooks/), https-only and the request timeout are app options of `createChannelDiscordFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Discord Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: { en: "Discord webhooks", de: "Discord-Webhooks", es: "Webhooks de Discord" },
+      hint: {
+        en: 'One secret per connection name; the value is the Discord webhook URL. Address it with route: { discord: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Discord-Webhook-URL. Adressierung mit route: { discord: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Discord. Se usa con route: { discord: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createDiscordChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "discord", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

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

@@ -0,0 +1,2 @@
+export { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+export { createChannelDiscordFeature } from "./feature.js";

package/packages/bundled-features/src/channel-slack/feature.ts

@@ -0,0 +1,38 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";
+
+export function createChannelSlackFeature(options: SlackChannelOptions = {}): FeatureDefinition {
+  return defineFeature("channel-slack", (r) => {
+    r.describe(
+      'Posts delivery notifications to a Slack incoming webhook, registered as the `slack` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { slack: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-slack:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (hooks.slack.com), https-only and the request timeout are app options of `createChannelSlackFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Slack Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: { en: "Slack webhooks", de: "Slack-Webhooks", es: "Webhooks de Slack" },
+      hint: {
+        en: 'One secret per connection name; the value is the Slack webhook URL. Address it with route: { slack: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Slack-Webhook-URL. Adressierung mit route: { slack: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Slack. Se usa con route: { slack: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createSlackChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "slack", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

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

@@ -0,0 +1,2 @@
+export { createChannelSlackFeature } from "./feature.js";
+export { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";

package/packages/bundled-features/src/channel-slack/slack-channel.ts

@@ -0,0 +1,29 @@
+import {
+  type ChatWebhookChannelOptions,
+  chatMessageText,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+} from "../delivery/index.js";
+
+export type SlackChannelOptions = ChatWebhookChannelOptions;
+
+export const SLACK_DEFAULT_ALLOWED_HOSTS = ["hooks.slack.com"] as const;
+
+// Slack mrkdwn treats & < > as control characters (links, @-mentions via <!channel>).
+export function escapeSlackText(text: string): string {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function createSlackChannel(
+  options: SlackChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "slack",
+    featureName: "channel-slack",
+    defaultAllowedHosts: SLACK_DEFAULT_ALLOWED_HOSTS,
+    keyFor,
+    buildBody: (message) => ({ text: escapeSlackText(chatMessageText(message)) }),
+    options,
+  });
+}

package/packages/bundled-features/src/channel-teams/feature.ts

@@ -0,0 +1,42 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";
+
+export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): FeatureDefinition {
+  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.',
+    );
+    r.uiHints({
+      displayLabel: "Microsoft Teams Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: {
+        en: "Microsoft Teams webhooks",
+        de: "Microsoft Teams-Webhooks",
+        es: "Webhooks de Microsoft Teams",
+      },
+      hint: {
+        en: 'One secret per connection name; the value is the Microsoft Teams webhook URL. Address it with route: { teams: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Microsoft Teams-Webhook-URL. Adressierung mit route: { teams: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Microsoft Teams. Se usa con route: { teams: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createTeamsChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

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

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

package/packages/bundled-features/src/channel-teams/teams-channel.ts

@@ -0,0 +1,50 @@
+import {
+  type ChatWebhookChannelOptions,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+} from "../delivery/index.js";
+
+export type TeamsChannelOptions = ChatWebhookChannelOptions;
+
+export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
+  ".webhook.office.com",
+  ".logic.azure.com",
+  ".powerplatform.com",
+] as const;
+
+// Text only ever goes into TextBlocks (no markup interpretation of titles/bodies
+// beyond Adaptive Card's own text rendering).
+export function buildTeamsAdaptiveCard(title: string, body: string | undefined): unknown {
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        contentUrl: null,
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [
+            { type: "TextBlock", text: title, weight: "Bolder", wrap: true },
+            ...(body ? [{ type: "TextBlock", text: body, wrap: true }] : []),
+          ],
+        },
+      },
+    ],
+  };
+}
+
+export function createTeamsChannel(
+  options: TeamsChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "teams",
+    featureName: "channel-teams",
+    defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS,
+    keyFor,
+    buildBody: (message) => buildTeamsAdaptiveCard(message.title, message.body),
+    options,
+  });
+}

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

@@ -0,0 +1,35 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";
+
+export function createChannelTelegramFeature(
+  options: TelegramChannelOptions = {},
+): FeatureDefinition {
+  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.uiHints({
+      displayLabel: "Telegram Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const botToken = r.secret("botToken", {
+      label: { en: "Telegram bot token" },
+      hint: {
+        en: 'Token from @BotFather. Used for every Telegram chat the tenant addresses via route: { telegram: "<chat id>" }.',
+      },
+      redact: () => "••••••••",
+      scope: "tenant",
+    });
+
+    const channel = createTelegramChannel(options, botToken.name);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "telegram", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

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

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

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

@@ -0,0 +1,74 @@
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import {
+  chatMessageText,
+  DEFAULT_CHAT_TIMEOUT_MS,
+  type DeliveryChannel,
+  postChatWebhook,
+  toChannelResult,
+  truncateChars,
+} from "../delivery/index.js";
+
+export type TelegramChannelOptions = {
+  // App-level override (tests, self-hosted Bot API server); never tenant config.
+  readonly apiBaseUrl?: string;
+  readonly timeoutMs?: number;
+};
+
+export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+
+// 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 createTelegramChannel(
+  options: TelegramChannelOptions,
+  botTokenKey: string,
+): DeliveryChannel {
+  const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_DEFAULT_API_BASE_URL;
+
+  return {
+    name: "telegram",
+    mode: "queued",
+
+    async send(address, message, ctx) {
+      if (!TELEGRAM_CHAT_ID_PATTERN.test(address)) {
+        return toChannelResult(address, { ok: false, code: "invalid_address" });
+      }
+      let token: string | undefined;
+      try {
+        const revealed = await ctx.secrets?.get(ctx.tenantId, botTokenKey, {
+          userId: SYSTEM_USER_ID,
+          handlerName: "channel-telegram:send",
+        });
+        token = revealed?.reveal();
+      } catch {
+        token = undefined;
+      }
+      if (!token || !TELEGRAM_BOT_TOKEN_PATTERN.test(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:"),
+        timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
+        // No parse_mode: Telegram renders the text literally.
+        body: {
+          chat_id: address,
+          text: truncateChars(chatMessageText(message), TELEGRAM_TEXT_MAX_CHARS),
+        },
+      });
+      return toChannelResult(address, result);
+    },
+  };
+}