@cosmicdrift/kumiko-bundled-features 0.338.0 → 0.340.0

package/dist/billing-foundation/projection.js

@@ -13,11 +13,10 @@
 // foundation production mounten müssen die Tabelle in ihre eigene
 // `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
 // import). setupTestStack pusht sie automatisch via r.projection.table.
+import { insertOnConflictDoNothing, requireEntityTableMeta, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable } 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";
 // Drizzle-table-instance aus dem entity-shape. Wird sowohl von der
 // projection-apply als auch von list-query / get-helper genutzt damit
@@ -27,6 +26,10 @@ export const subscriptionsProjectionTable = buildEntityTable("subscription", sub
 // raw drizzle-pgTable, not an r.entity — apps mounting billing-foundation in
 // 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 = requireEntityTableMeta(subscriptionsProjectionTable, "subscription");
+const paymentsProjectionMeta = requireEntityTableMeta(paymentsProjectionTable, "payment");
 // =============================================================================
 // Shared helpers
 // =============================================================================
@@ -59,9 +62,7 @@ function cancelAtSetFromPayload(p) {
  *  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, event, set, fullPayload) {
     // INSERT-fallback braucht ALL fields (NOT NULL constraints). Wenn
     // jemand nur teil-felder updated (z.B. invoice-payment-failed nur
@@ -69,38 +70,21 @@ async function upsert(tx, event, set, fullPayload) {
     // 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 = {
-        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 = [`"modified_at" = $${insertParams.length}`];
-    const allParams = [...insertParams];
-    for (const [k, v] of setEntries) {
-        allParams.push(v);
-        setClauses.push(`"${setMap[k]}" = $${allParams.length}`);
-    }
-    const tableName = subscriptionsProjectionTable.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 },
+    });
 }
 // =============================================================================
 // Apply-functions — eine pro event-typ
@@ -164,17 +148,16 @@ export const applyInvoicePaymentFailed = defineApply(async (event, tx) => {
  *  the second tenant's row. ON CONFLICT DO NOTHING also makes a projection
  *  rebuild idempotent without mutating an existing row. */
 export const applyPaymentReceived = defineApply(async (event, tx) => {
-    const tableName = paymentsProjectionTable.tableName;
     const providerEventId = event.metadata.headers?.["providerEventId"];
     const providerName = event.metadata.headers?.["providerName"];
     if (typeof providerEventId !== "string" || typeof providerName !== "string") {
         throw new Error("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/dist/billing-foundation/tenant-destroy-hook.js

@@ -20,7 +20,7 @@ export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up th
 export async function subscriptionTenantDestroyHook(ctx) {
     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);
@@ -30,7 +30,7 @@ export async function subscriptionTenantDestroyHook(ctx) {
     else {
         await ctx.db.deleteMany(subscriptionsProjectionTable, { 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,
@@ -46,7 +46,7 @@ export async function subscriptionTenantDestroyHook(ctx) {
 export async function paymentTenantDestroyHook(ctx) {
     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);
@@ -58,7 +58,7 @@ export async function paymentTenantDestroyHook(ctx) {
             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/dist/billing-foundation/types.d.ts

@@ -2,7 +2,7 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus } from "./constants.js";
+import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } from "./constants.js";
 export type SubscriptionEvent = {
     /** Discriminator against PaymentEvent. Optional (instead of required) so
      *  existing plugins like subscription-mollie, which don't set this field,
@@ -289,6 +289,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/dist/billing-foundation/validate-options.js

@@ -3,6 +3,7 @@
 // concerns (app-feature-structure guard's 300-line budget). Internal — not
 // re-exported from index.ts.
 import * as z from "zod";
+import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
 function isRootRelativePath(path) {
     return path.startsWith("/") && !path.startsWith("//");
 }
@@ -28,6 +29,9 @@ function validateConsumerProtection(cp) {
     if (!z.email().safeParse(cp.operatorEmail).success) {
         throw new Error(`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(`createBillingFoundationFeature: consumerProtection.legalLinks.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`);

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

@@ -0,0 +1,6 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type DiscordChannelOptions = ChatWebhookChannelOptions;
+export declare const DISCORD_DEFAULT_ALLOWED_HOSTS: readonly ["discord.com", "discordapp.com"];
+export declare const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export declare const DISCORD_CONTENT_MAX_CHARS = 2000;
+export declare function createDiscordChannel(options: DiscordChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-discord/discord-channel.js

@@ -0,0 +1,19 @@
+import { chatMessageText, createChatWebhookChannel, truncateChars, } from "../delivery/index.js";
+export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"];
+export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export const DISCORD_CONTENT_MAX_CHARS = 2000;
+export function createDiscordChannel(options, keyFor) {
+    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/dist/channel-discord/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type DiscordChannelOptions } from "./discord-channel.js";
+export declare function createChannelDiscordFeature(options?: DiscordChannelOptions): FeatureDefinition;

package/dist/channel-discord/feature.js

@@ -0,0 +1,30 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createDiscordChannel } from "./discord-channel.js";
+export function createChannelDiscordFeature(options = {}) {
+    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/dist/channel-discord/index.d.ts

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

package/dist/channel-discord/index.js

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

package/dist/channel-slack/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type SlackChannelOptions } from "./slack-channel.js";
+export declare function createChannelSlackFeature(options?: SlackChannelOptions): FeatureDefinition;

package/dist/channel-slack/feature.js

@@ -0,0 +1,30 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createSlackChannel } from "./slack-channel.js";
+export function createChannelSlackFeature(options = {}) {
+    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/dist/channel-slack/index.d.ts

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

package/dist/channel-slack/index.js

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

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

@@ -0,0 +1,5 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type SlackChannelOptions = ChatWebhookChannelOptions;
+export declare const SLACK_DEFAULT_ALLOWED_HOSTS: readonly ["hooks.slack.com"];
+export declare function escapeSlackText(text: string): string;
+export declare function createSlackChannel(options: SlackChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-slack/slack-channel.js

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

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

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type TeamsChannelOptions } from "./teams-channel.js";
+export declare function createChannelTeamsFeature(options?: TeamsChannelOptions): FeatureDefinition;

package/dist/channel-teams/feature.js

@@ -0,0 +1,34 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createTeamsChannel } 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.');
+        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/dist/channel-teams/index.d.ts

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

package/dist/channel-teams/index.js

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

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

@@ -0,0 +1,5 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type TeamsChannelOptions = ChatWebhookChannelOptions;
+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

@@ -0,0 +1,38 @@
+import { createChatWebhookChannel, } from "../delivery/index.js";
+export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
+    ".webhook.office.com",
+    ".logic.azure.com",
+    ".powerplatform.com",
+];
+// Text only ever goes into TextBlocks (no markup interpretation of titles/bodies
+// beyond Adaptive Card's own text rendering).
+export function buildTeamsAdaptiveCard(title, body) {
+    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, keyFor) {
+    return createChatWebhookChannel({
+        name: "teams",
+        featureName: "channel-teams",
+        defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS,
+        keyFor,
+        buildBody: (message) => buildTeamsAdaptiveCard(message.title, message.body),
+        options,
+    });
+}

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

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type TelegramChannelOptions } from "./telegram-channel.js";
+export declare function createChannelTelegramFeature(options?: TelegramChannelOptions): FeatureDefinition;

package/dist/channel-telegram/feature.js

@@ -0,0 +1,28 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createTelegramChannel } 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.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/dist/channel-telegram/index.d.ts

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

package/dist/channel-telegram/index.js

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

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

@@ -0,0 +1,8 @@
+import { type DeliveryChannel } from "../delivery/index.js";
+export type TelegramChannelOptions = {
+    readonly apiBaseUrl?: string;
+    readonly timeoutMs?: number;
+};
+export declare const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export declare const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export declare function createTelegramChannel(options: TelegramChannelOptions, botTokenKey: string): DeliveryChannel;

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

@@ -0,0 +1,54 @@
+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_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, botTokenKey) {
+    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;
+            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;
+            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);
+        },
+    };
+}

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -248,17 +248,17 @@ export const forgetSubjectWrite = defineWriteHandler({
                 ? { kind: "tenant", tenantId: raw.tenantId }
                 : { kind: "record", entity: raw.entity, id: raw.id };
         const subjectKey = subjectIdToKey(subject);
-        const tenantScopeDenial = await resolveTenantScopeDenial(ctx.db.unsafeRaw("tenant-scope check runs against the subject's tenant, not necessarily the caller's"), ctx.registry.features, event.user, raw);
+        const tenantScopeDenial = await resolveTenantScopeDenial(ctx.db.unsafeRaw(), ctx.registry.features, event.user, raw);
         if (tenantScopeDenial) {
-            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, denialReasonOf(tenantScopeDenial), ctx.dbOutsideTransaction?.unsafeRaw("denial audit append: names the prober's own tenant stream on the outside-transaction db"));
+            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, denialReasonOf(tenantScopeDenial), ctx.dbOutsideTransaction?.unsafeRaw());
             return auditFailure ?? tenantScopeDenial;
         }
         // Runs after the tenant gate but before any key is touched: a retention
         // check ahead of the tenant gate would leak a foreign entity's retention
         // posture to a cross-tenant prober.
-        const retentionDenial = await resolveRetentionDenial(ctx, raw, () => ctx.db.unsafeRaw("retention check reads the record row's owning tenant, not the caller's"));
+        const retentionDenial = await resolveRetentionDenial(ctx, raw, () => ctx.db.unsafeRaw());
         if (retentionDenial) {
-            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, TARGET_RECORD_RETENTION_BLOCK_DELETE, ctx.dbOutsideTransaction?.unsafeRaw("denial audit append: names the prober's own tenant stream on the outside-transaction db"));
+            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, TARGET_RECORD_RETENTION_BLOCK_DELETE, ctx.dbOutsideTransaction?.unsafeRaw());
             return auditFailure ?? retentionDenial;
         }
         // Erase BEFORE the audit append: if the append throws, the key is gone
@@ -272,7 +272,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         });
         // Blind-index sweep (#818): nulls bidx columns now so the deterministic
         // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
-        const crossTenantSubjectRunner = ctx.db.unsafeRaw("blind-index sweep and search purge address the subject across tenants");
+        const crossTenantSubjectRunner = ctx.db.unsafeRaw();
         await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
         // Derived search index still holds plaintext (#1610) — purge next to the
         // blind-index sweep. No adapter → no-op (apps without search).
@@ -300,7 +300,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         // update is best-effort for real users.
         if (raw.kind === "user" && ctx.registry.features.has("user")) {
             try {
-                const userLifecycleRunner = ctx.db.unsafeRaw("user lifecycle update and PAT revoke run on the SYSTEM user stream");
+                const userLifecycleRunner = ctx.db.unsafeRaw();
                 await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
                 if (ctx.registry.features.has("personal-access-tokens")) {
                     await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);

package/dist/custom-fields/handlers/clear-custom-field.write.js

@@ -31,7 +31,7 @@ export const clearCustomFieldHandler = {
     },
     handler: async (event, ctx) => {
         const payload = event.payload; // @cast-boundary engine-payload
-        const accessCheck = await checkFieldAccessForWrite(ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON), event.user.tenantId, payload.entityName, payload.fieldKey, event.user.roles);
+        const accessCheck = await checkFieldAccessForWrite(ctx.db.unsafeRaw(), event.user.tenantId, payload.entityName, payload.fieldKey, event.user.roles);
         if (!accessCheck.ok) {
             if (accessCheck.reason === "field_definition_not_found") {
                 return failNotFound("fieldDefinition", payload.fieldKey);

package/dist/custom-fields/handlers/define-tenant-field.write.js

@@ -26,7 +26,7 @@ export function createDefineTenantFieldHandler(opts = {}) {
                 throw new Error("define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions");
             }
             if (limit !== undefined) {
-                const current = await countTenantFieldDefinitions(ctx.db.unsafeRaw(DEFINE_TENANT_FIELD_REASON), tenantId);
+                const current = await countTenantFieldDefinitions(ctx.db.unsafeRaw(), tenantId);
                 if (current >= limit) {
                     return failUnprocessable("cap_exceeded", {
                         capName: "customFields.fieldDefinition.count",

package/dist/custom-fields/handlers/set-custom-field.write.js

@@ -54,7 +54,7 @@ export const setCustomFieldHandler = {
     },
     handler: async (event, ctx) => {
         const payload = event.payload; // @cast-boundary engine-payload
-        const loaded = await loadFieldDefinition(ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON), event.user.tenantId, payload.entityName, payload.fieldKey);
+        const loaded = await loadFieldDefinition(ctx.db.unsafeRaw(), event.user.tenantId, payload.entityName, payload.fieldKey);
         if (!loaded.found) {
             return failNotFound("fieldDefinition", payload.fieldKey);
         }

package/dist/custom-fields/wire-user-data-rights.js

@@ -46,7 +46,7 @@ export function wireCustomFieldsUserDataRightsFor(r, opts) {
     const tableName = extractTableName(opts.entityTable, "custom-fields/wire-user-data-rights");
     // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar API, not a React hook.
     r.useExtension(EXT_USER_DATA, opts.entityName, {
-        export: async (ctx) => exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+        export: async (ctx) => exportCustomFields(ctx.db.unsafeRaw(), ctx, tableName, opts),
         escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
     });
 }