@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/cap-overview/web/cap-cards-panel.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { EmptyState, StatCard, StatusBadge, } from "@cosmicdrift/kumiko-renderer-web";
+import { Database, FileText, Gauge, Hash, Mail, Users } from "lucide-react";
+import { CapOverviewQueries } from "../constants.js";
+import { CapUsageBar } from "./cap-usage-bar.js";
+// caps:usage's wire tone stays "default"/"warn"/"danger" (matches the
+// server-side thresholds literally); mapped here to the renderer's actual
+// StatusTone vocabulary instead of inventing new CSS ("danger" has no
+// StatusBadge tone equivalent — "critical" is the closer semantic fit).
+const TONE_TO_STATUS = {
+    default: "muted",
+    warn: "warn",
+    danger: "critical",
+};
+// Matches CapIconKey (types.ts) 1:1 — extend both together.
+const CAP_ICONS = {
+    file: FileText,
+    hash: Hash,
+    database: Database,
+    users: Users,
+    mail: Mail,
+    gauge: Gauge,
+};
+// Narrows `used` only — `percent` can independently be null for an
+// unlimited cap (limit: null) even though used is measured.
+function isMeasured(cap) {
+    return cap.used !== null;
+}
+export function CapCardsPanel({ filterParams }) {
+    const t = useTranslation();
+    const { Banner } = usePrimitives();
+    const tenantId = typeof filterParams?.["tenantId"] === "string" ? filterParams["tenantId"] : undefined;
+    const query = useQuery(CapOverviewQueries.capsUsage, {
+        ...(tenantId !== undefined && { tenantId }),
+    });
+    if (query.error !== null) {
+        return (_jsx(Banner, { variant: "error", testId: "cap-cards-panel-error", children: query.error.message }));
+    }
+    const rows = query.data?.rows ?? [];
+    if (!query.loading && rows.length === 0) {
+        return _jsx(EmptyState, { title: t("cap-overview.cards.empty"), testId: "cap-cards-panel-empty" });
+    }
+    return (_jsxs("div", { 
+        // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
+        // styles.css's Tailwind v4 @source scan only covers renderer-web/src,
+        // renderer/src and samples/**/src (see its comment) — bundled-features
+        // isn't scanned, so a class unique to this file has no generated rule
+        // and silently no-ops (the grid fell back to one implicit column,
+        // stacking every card full-width). Reusing the exact classes
+        // dashboard-body.tsx's own panel grid already uses guarantees the
+        // rule exists, since that file IS in the scanned surface.
+        className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-4", "data-testid": "cap-cards-panel", children: [query.loading && rows.length === 0 && (_jsx("div", { className: "text-sm text-muted-foreground", children: t("cap-overview.cards.loading") })), rows.map((cap) => {
+                const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
+                return (_jsx(StatCard, { icon: Icon !== undefined ? _jsx(Icon, { className: "size-4" }) : undefined, label: t(cap.label), value: !isMeasured(cap)
+                        ? "—"
+                        : cap.limit === null
+                            ? String(cap.used)
+                            : `${cap.used} / ${cap.limit}`, ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }), testId: "cap-card", children: _jsxs("div", { className: "flex flex-col gap-2", children: [cap.percent !== null && (_jsx("div", { className: "flex items-center justify-between gap-2", children: _jsx(StatusBadge, { tone: TONE_TO_STATUS[cap.tone], children: `${cap.percent}%` }) })), _jsx(CapUsageBar, { usage: cap, showLabel: false })] }) }, cap.id));
+            })] }));
+}

package/dist/cap-overview/web/cap-usage-bar.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types.js";
+export declare function CapUsageBar({ usage, showLabel, }: {
+    readonly usage: CapUsage;
+    readonly showLabel?: boolean;
+}): ReactNode;

package/dist/cap-overview/web/cap-usage-bar.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @runtime client
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { computeTone } from "../usage-math.js";
+export function CapUsageBar({ usage, showLabel = true, }) {
+    const { Progress, Text, Banner } = usePrimitives();
+    const t = useTranslation();
+    if (usage.used === null) {
+        return (_jsx(Text, { variant: "small", testId: "cap-usage-not-measured", children: t("cap-overview.notMeasured") }));
+    }
+    if (usage.limit === null) {
+        // A progress bar with no denominator says nothing — show the raw count instead.
+        return showLabel ? (_jsx(Text, { variant: "small", testId: "cap-usage-unlimited", children: String(usage.used) })) : null;
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-1", children: [Progress ? (_jsx(Progress, { value: usage.fraction, tone: computeTone(usage.fraction), testId: "cap-usage-bar" })) : (_jsx(Banner, { variant: "error", testId: "cap-usage-bar-missing-primitive", children: t("cap-overview.errors.progressPrimitiveMissing") })), showLabel && _jsx(Text, { variant: "small", children: `${usage.used} / ${usage.limit}` })] }));
+}

package/dist/cap-overview/web/cap-usage-cell.d.ts

@@ -0,0 +1,3 @@
+import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+export declare function CapUsageCell({ value }: ColumnRendererProps): ReactNode;

package/dist/cap-overview/web/cap-usage-cell.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CapUsageBar } from "./cap-usage-bar.js";
+function isCapUsage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const used = value.used;
+    const limit = value.limit;
+    return ((typeof used === "number" || used === null) &&
+        (typeof limit === "number" || limit === null) &&
+        typeof value.fraction === "number");
+}
+export function CapUsageCell({ value }) {
+    if (!isCapUsage(value))
+        return null;
+    return _jsx(CapUsageBar, { usage: value });
+}

package/dist/cap-overview/web/client-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+export type CapOverviewClientOptions = {
+    readonly translations?: TranslationsByLocale;
+};
+export declare function capOverviewClient(options?: CapOverviewClientOptions): ClientFeatureDefinition;

package/dist/cap-overview/web/client-plugin.js

@@ -0,0 +1,15 @@
+import { CAP_CARDS_PANEL_COMPONENT, CAP_OVERVIEW_FEATURE, CAP_USAGE_CELL_COMPONENT, } from "../constants.js";
+import { CapCardsPanel } from "./cap-cards-panel.js";
+import { CapUsageCell } from "./cap-usage-cell.js";
+export function capOverviewClient(options) {
+    return {
+        name: CAP_OVERVIEW_FEATURE,
+        columnRenderers: {
+            [CAP_USAGE_CELL_COMPONENT]: CapUsageCell,
+        },
+        extensionSectionComponents: {
+            [CAP_CARDS_PANEL_COMPONENT]: CapCardsPanel,
+        },
+        ...(options?.translations !== undefined && { translations: options.translations }),
+    };
+}

package/dist/cap-overview/web/index.d.ts

@@ -0,0 +1,4 @@
+export { CapCardsPanel } from "./cap-cards-panel.js";
+export { CapUsageBar } from "./cap-usage-bar.js";
+export { CapUsageCell } from "./cap-usage-cell.js";
+export { type CapOverviewClientOptions, capOverviewClient } from "./client-plugin.js";

package/dist/cap-overview/web/index.js

@@ -0,0 +1,9 @@
+// @runtime client
+// Public exports for the browser side of the cap-overview feature.
+// Consumed via `@cosmicdrift/kumiko-bundled-features/cap-overview/web` —
+// the server side (createCapOverviewFeature) lives under
+// `@cosmicdrift/kumiko-bundled-features/cap-overview` and has no React deps.
+export { CapCardsPanel } from "./cap-cards-panel.js";
+export { CapUsageBar } from "./cap-usage-bar.js";
+export { CapUsageCell } from "./cap-usage-cell.js";
+export { capOverviewClient } from "./client-plugin.js";

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

@@ -0,0 +1,12 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type DeliveryChannel, type NotificationRenderer } from "../delivery/index.js";
+import type { EmailTransport } from "./types.js";
+export type EmailChannelOptions = {
+    readonly transport: EmailTransport;
+    readonly renderer: NotificationRenderer;
+    readonly resolveEmail: (userId: string, ctx: {
+        db: unknown;
+        tenantId: TenantId;
+    }) => Promise<string | null>;
+};
+export declare function createEmailChannel(options: EmailChannelOptions): DeliveryChannel;

package/dist/channel-email/email-channel.js

@@ -0,0 +1,85 @@
+import { DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, } from "../delivery/index.js";
+import { guardEmailMessage } from "./pii-guard.js";
+// Envelope (From / Reply-To / threading headers) rides on the channel data —
+// the notification's email template echoes it out of the notify() call, since
+// buildMessage collapses the raw data to the template's result. Content
+// (subject, html) is rendered; these three are copied straight to the message.
+function stringHeaders(raw) {
+    if (raw === undefined || raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+// Only the framework's own unsubscribe route can honor a one-click POST.
+function listUnsubscribeHeaders(data) {
+    const rawUrl = data?.["unsubscribeUrl"];
+    if (typeof rawUrl !== "string")
+        return undefined;
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return undefined;
+    if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH)
+        return undefined;
+    return {
+        "List-Unsubscribe": `<${url.toString()}>`,
+        "List-Unsubscribe-Post": DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
+    };
+}
+function emailEnvelopeFrom(data) {
+    if (!data)
+        return {};
+    const from = typeof data["from"] === "string" ? data["from"] : undefined;
+    const replyTo = typeof data["replyTo"] === "string" ? data["replyTo"] : undefined;
+    const autoHeaders = listUnsubscribeHeaders(data);
+    const explicitHeaders = stringHeaders(data["headers"]);
+    const headers = autoHeaders || explicitHeaders ? { ...autoHeaders, ...explicitHeaders } : undefined;
+    return { ...(from && { from }), ...(replyTo && { replyTo }), ...(headers && { headers }) };
+}
+export function createEmailChannel(options) {
+    const { transport, renderer, resolveEmail } = options;
+    // Render is the expensive step (template engine, possibly a remote service)
+    // and runs in the delivery.render job, decoupled from the SMTP send so each
+    // can retry independently. Extracted so the inline fallback (no job runner)
+    // can reuse it without going through the channel's own render() indirection.
+    async function renderMessage(message) {
+        // Build renderer input: per-channel template data (if any) or fall back
+        // to title/body from the message. Renderer handles both cases.
+        const variables = message.data ?? {
+            title: message.title,
+            body: message.body,
+        };
+        const html = await renderer.render({
+            template: message.notificationType,
+            variables,
+        });
+        const subject = variables["subject"] ?? message.title; // @cast-boundary dynamic-key
+        return { html, subject };
+    }
+    return {
+        name: "email",
+        mode: "queued",
+        async resolve(userId, ctx) {
+            return resolveEmail(userId, ctx);
+        },
+        render(message, _ctx) {
+            return renderMessage(message);
+        },
+        async send(address, message, _ctx, rendered) {
+            const { html, subject } = rendered ?? (await renderMessage(message));
+            const envelope = emailEnvelopeFrom(message.data);
+            await transport.send(guardEmailMessage({ to: address, subject, html, ...envelope }));
+            return { status: "sent", address };
+        },
+    };
+}

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

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

package/dist/channel-email/feature.js

@@ -0,0 +1,21 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEmailChannel } from "./email-channel.js";
+export function createChannelEmailFeature(options) {
+    const channel = createEmailChannel(options);
+    return defineFeature("channel-email", (r) => {
+        r.describe("Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.");
+        r.uiHints({
+            displayLabel: "Email Channel",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
+            mode: channel.mode,
+            resolve: channel.resolve,
+            render: channel.render,
+            send: channel.send,
+        });
+    });
+}

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

@@ -0,0 +1,5 @@
+export { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
+export { createChannelEmailFeature } from "./feature.js";
+export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
+export { createSmtpTransport, createSmtpTransportFromEnv, type SmtpEnv, type SmtpTransportOptions, } from "./smtp-transport.js";
+export { createInMemoryTransport, type EmailMessage, type EmailTransport } from "./types.js";

package/dist/channel-email/index.js

@@ -0,0 +1,5 @@
+export { createEmailChannel } from "./email-channel.js";
+export { createChannelEmailFeature } from "./feature.js";
+export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
+export { createSmtpTransport, createSmtpTransportFromEnv, } from "./smtp-transport.js";
+export { createInMemoryTransport } from "./types.js";

package/dist/channel-email/pii-guard.d.ts

@@ -0,0 +1,3 @@
+import type { EmailMessage, EmailTransport } from "./types.js";
+export declare function guardEmailMessage(message: EmailMessage): EmailMessage;
+export declare function withPiiCiphertextGuard(transport: EmailTransport): EmailTransport;

package/dist/channel-email/pii-guard.js

@@ -0,0 +1,47 @@
+import { PII_CIPHERTEXT_PREFIX } from "@cosmicdrift/kumiko-framework/crypto";
+const isProductionEnv = () => process.env["NODE_ENV"] === "production";
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
+// A PII ciphertext never belongs in an outgoing mail. A ciphertext RECIPIENT
+// is always refused (the address is garbage — better no mail than a leaked
+// blob); ciphertext in subject/body fails loud in dev and is redacted+logged
+// in prod.
+export function guardEmailMessage(message) {
+    // Every envelope address, not just `to`: a ciphertext From or Reply-To is
+    // the same garbage as a ciphertext recipient — refuse rather than mail it.
+    for (const [label, address] of [
+        ["recipient", message.to],
+        ["from", message.from],
+        ["reply-to", message.replyTo],
+    ]) {
+        if (address?.includes(CIPHERTEXT_MARKER)) {
+            throw new Error(`[channel-email] refusing to send: ${label} address is a PII ciphertext ` +
+                `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`);
+        }
+    }
+    for (const [headerName, headerValue] of Object.entries(message.headers ?? {})) {
+        if (typeof headerValue === "string" && headerValue.includes(CIPHERTEXT_MARKER)) {
+            throw new Error(`[channel-email] refusing to send: header "${headerName}" is a PII ciphertext ` +
+                `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`);
+        }
+    }
+    const leaking = message.subject.includes(CIPHERTEXT_MARKER) || message.html.includes(CIPHERTEXT_MARKER);
+    if (!leaking)
+        return message;
+    const detail = "[channel-email] mail subject/body contains a PII ciphertext " +
+        `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before rendering.`;
+    if (!isProductionEnv())
+        throw new Error(detail);
+    // biome-ignore lint/suspicious/noConsole: operator-visibility for a redacted prod leak
+    console.error(detail);
+    return {
+        ...message,
+        subject: message.subject.replace(CIPHERTEXT_RE, "[pii-redacted]"),
+        html: message.html.replace(CIPHERTEXT_RE, "[pii-redacted]"),
+    };
+}
+export function withPiiCiphertextGuard(transport) {
+    return { ...transport, send: async (message) => transport.send(guardEmailMessage(message)) };
+}

package/dist/channel-email/smtp-transport.d.ts

@@ -0,0 +1,53 @@
+import type { EmailTransport } from "./types.js";
+export type SmtpTransportOptions = {
+    /** SMTP-Server-Host (z.B. "smtp.gmail.com", "in-v3.mailjet.com",
+     *  "localhost" für Mailhog/MailCatcher in dev). */
+    readonly host: string;
+    /** Default 587 (STARTTLS). 465 für implicit-TLS, 25 für unencrypted
+     *  (nur lokal/intern, nie public). */
+    readonly port?: number;
+    /** TLS-Mode: true = implicit TLS auf port 465, false = STARTTLS auf
+     *  587 (oder plain auf 25). Default false (STARTTLS standard). */
+    readonly secure?: boolean;
+    /** Optional auth — manche internal-relays nehmen IP-whitelisting statt
+     *  Login. Wenn gesetzt, beide felder pflicht. */
+    readonly auth?: {
+        readonly user: string;
+        readonly pass: string;
+    };
+    /** App-wide default From. A single send can override it via
+     *  `EmailMessage.from` (reply from a specific mailbox); without an
+     *  override this applies. Accepts both "noreply@ex.com" and
+     *  "Name <noreply@ex.com>". */
+    readonly from: string;
+    /** TLS SNI hostname. Only needed when `host` is an IP address pinned by
+     *  the caller for a hostname it already resolved — nodemailer otherwise
+     *  skips SNI for an IP `host` and certificate validation would then check
+     *  the wrong name. Unset for the common case where `host` is already the
+     *  hostname to validate against. */
+    readonly servername?: string;
+};
+export declare function createSmtpTransport(options: SmtpTransportOptions): EmailTransport;
+/** Env-Felder die `createSmtpTransportFromEnv` liest. Apps die SMTP
+ *  nutzen extenden ihr env-Schema um genau diese Keys. */
+export type SmtpEnv = {
+    readonly SMTP_HOST?: string;
+    readonly SMTP_PORT?: string;
+    readonly SMTP_SECURE?: string;
+    readonly SMTP_USER?: string;
+    readonly SMTP_PASS?: string;
+    readonly SMTP_FROM?: string;
+};
+/**
+ * Boot-Time-Transport aus env. Ohne `SMTP_HOST` → `null` (Caller behandelt
+ * das als "kein Mail-Versand", statt zu crashen). Port wird zu Number
+ * gecoerced (default 587), `secure` ist `SMTP_SECURE === "true"`, auth nur
+ * wenn user UND pass gesetzt sind.
+ *
+ * Ersetzt den identischen `env.SMTP_HOST ? createSmtpTransport({...}) : null`
+ * Block den jede App in bin/main.ts + bin/server.ts hand-rollte — nur die
+ * From-Default (`fallbackFrom`) variiert pro App.
+ */
+export declare function createSmtpTransportFromEnv(env: SmtpEnv, opts: {
+    readonly fallbackFrom: string;
+}): EmailTransport | null;

package/dist/channel-email/smtp-transport.js

@@ -0,0 +1,64 @@
+// SMTP-Transport für EmailTransport-Interface. nodemailer-basiert
+// (battle-tested, TLS-AUTH-Pool-Reconnect handled). Universaler default
+// für apps die keinen Vendor-spezifischen Sender wollen — funktioniert
+// gegen jeden SMTP-Server (Gmail, eigener Postfix, Brevo-SMTP-relay,
+// Office 365, Mailhog für lokales testing).
+//
+// Why SMTP statt Vendor-API als default:
+//   1. EU-Story: kein Daten an US-Vendor, App-Owner wählt Server.
+//   2. Self-Hosting: Customer kann eigenen Mailserver nutzen, kein
+//      external account.
+//   3. Universalität: jeder Vendor (Brevo, Resend, Mailgun, Postmark)
+//      bietet auch SMTP — wer Brevo will, setzt Brevos SMTP-Credentials.
+//
+// Transport-Pool: nodemailer.createTransport({pool: true}) hält bis zu
+// 5 Verbindungen offen + reused. Bei kleinen Apps reicht das; für High-
+// Volume-Apps muss der Caller eine eigene Implementation mit
+// dedizierter Queue (BullMQ + retry) drüberlegen.
+import { createTransport } from "nodemailer";
+export function createSmtpTransport(options) {
+    const transporter = createTransport({
+        host: options.host,
+        port: options.port ?? 587,
+        secure: options.secure ?? false,
+        ...(options.auth && { auth: options.auth }),
+        ...(options.servername && { servername: options.servername }),
+        pool: true,
+        maxConnections: 5,
+    });
+    return {
+        async send(message) {
+            await transporter.sendMail({
+                from: message.from ?? options.from,
+                to: message.to,
+                subject: message.subject,
+                html: message.html,
+                ...(message.replyTo && { replyTo: message.replyTo }),
+                ...(message.headers && { headers: message.headers }),
+            });
+        },
+    };
+}
+/**
+ * Boot-Time-Transport aus env. Ohne `SMTP_HOST` → `null` (Caller behandelt
+ * das als "kein Mail-Versand", statt zu crashen). Port wird zu Number
+ * gecoerced (default 587), `secure` ist `SMTP_SECURE === "true"`, auth nur
+ * wenn user UND pass gesetzt sind.
+ *
+ * Ersetzt den identischen `env.SMTP_HOST ? createSmtpTransport({...}) : null`
+ * Block den jede App in bin/main.ts + bin/server.ts hand-rollte — nur die
+ * From-Default (`fallbackFrom`) variiert pro App.
+ */
+export function createSmtpTransportFromEnv(env, opts) {
+    if (!env.SMTP_HOST)
+        return null;
+    return createSmtpTransport({
+        host: env.SMTP_HOST,
+        port: env.SMTP_PORT ? Number(env.SMTP_PORT) : 587,
+        secure: env.SMTP_SECURE === "true",
+        ...(env.SMTP_USER && env.SMTP_PASS
+            ? { auth: { user: env.SMTP_USER, pass: env.SMTP_PASS } }
+            : {}),
+        from: env.SMTP_FROM ?? opts.fallbackFrom,
+    });
+}

package/dist/channel-email/types.d.ts

@@ -0,0 +1,17 @@
+export type EmailMessage = {
+    readonly to: string;
+    readonly subject: string;
+    readonly html: string;
+    readonly from?: string;
+    readonly replyTo?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+export type EmailTransport = {
+    send(message: EmailMessage): Promise<void>;
+};
+export declare function createInMemoryTransport(): EmailTransport & {
+    readonly sent: EmailMessage[];
+    failNext: null | {
+        message: string;
+    };
+};

package/dist/channel-email/types.js

@@ -0,0 +1,20 @@
+// InMemory transport for testing — collects sent emails.
+// `failNext` lets a test simulate a transient SMTP failure without
+// rebuilding the whole stack: set it before a single `notify()` call and
+// the transport throws once, then auto-resets.
+export function createInMemoryTransport() {
+    const sent = [];
+    const transport = {
+        sent,
+        failNext: null, // @cast-boundary generic-record
+        async send(message) {
+            if (transport.failNext) {
+                const err = new Error(transport.failNext.message);
+                transport.failNext = null;
+                throw err;
+            }
+            sent.push(message);
+        },
+    };
+    return transport;
+}

package/dist/channel-in-app/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const CHANNEL_IN_APP_FEATURE: "channel-in-app";
+export declare const InAppHandlers: {
+    readonly markRead: "channel-in-app:write:mark-read";
+    readonly markAllRead: "channel-in-app:write:mark-all-read";
+};
+export declare const InAppQueries: {
+    readonly inbox: "channel-in-app:query:inbox";
+    readonly unreadCount: "channel-in-app:query:unread-count";
+};

package/dist/channel-in-app/constants.js

@@ -0,0 +1,9 @@
+export const CHANNEL_IN_APP_FEATURE = "channel-in-app";
+export const InAppHandlers = {
+    markRead: "channel-in-app:write:mark-read",
+    markAllRead: "channel-in-app:write:mark-all-read",
+};
+export const InAppQueries = {
+    inbox: "channel-in-app:query:inbox",
+    unreadCount: "channel-in-app:query:unread-count",
+};

package/dist/channel-in-app/feature.d.ts

@@ -0,0 +1,2 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createChannelInAppFeature(): FeatureDefinition;

package/dist/channel-in-app/feature.js

@@ -0,0 +1,37 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { inboxQuery } from "./handlers/inbox.query.js";
+import { markAllReadWrite } from "./handlers/mark-all-read.write.js";
+import { markReadWrite } from "./handlers/mark-read.write.js";
+import { unreadCountQuery } from "./handlers/unread-count.query.js";
+import { inAppChannel } from "./in-app-channel.js";
+import { inAppMessagesTableMeta } from "./tables.js";
+export function createChannelInAppFeature() {
+    return defineFeature("channel-in-app", (r) => {
+        r.describe("Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.");
+        r.uiHints({
+            displayLabel: "In-App Inbox",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.storeTable(inAppMessagesTableMeta, {
+            reason: "read_side.in_app_messages",
+        });
+        // Register as delivery channel via extension system
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "inApp", {
+            mode: inAppChannel.mode,
+            resolve: inAppChannel.resolve,
+            send: inAppChannel.send,
+        });
+        const handlers = {
+            markRead: r.writeHandler(markReadWrite),
+            markAllRead: r.writeHandler(markAllReadWrite),
+        };
+        const queries = {
+            inbox: r.queryHandler(inboxQuery),
+            unreadCount: r.queryHandler(unreadCountQuery),
+        };
+        return { handlers, queries };
+    });
+}

package/dist/channel-in-app/handlers/inbox.query.d.ts

@@ -0,0 +1,7 @@
+import * as z from "zod";
+export declare const inboxQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"inbox", z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    unreadOnly: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, {
+    rows: readonly any[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/channel-in-app/handlers/inbox.query.js

@@ -0,0 +1,28 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { inAppMessagesTable } from "../tables.js";
+export const inboxQuery = defineQueryHandler({
+    name: "inbox",
+    schema: z.object({
+        limit: z.number().min(1).max(100).default(50),
+        unreadOnly: z.boolean().default(false),
+    }),
+    access: {
+        openToAll: {
+            reason: "each signed-in user reads only their own in-app inbox; the query filters " +
+                "inAppMessagesTable by the caller's own id",
+        },
+    },
+    description: "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
+    handler: async (query, ctx) => {
+        const where = { userId: query.user.id };
+        if (query.payload.unreadOnly)
+            where["isRead"] = false;
+        const rows = await selectMany(ctx.db, inAppMessagesTable, where, {
+            limit: query.payload.limit,
+            orderBy: { col: "createdAt", direction: "desc" },
+        });
+        return { rows };
+    },
+});

package/dist/channel-in-app/handlers/mark-all-read.write.d.ts

@@ -0,0 +1,4 @@
+import * as z from "zod";
+export declare const markAllReadWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"markAllRead", z.ZodObject<{}, z.core.$strip>, {
+    marked: number;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/channel-in-app/handlers/mark-all-read.write.js

@@ -0,0 +1,19 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { inAppMessagesTable } from "../tables.js";
+export const markAllReadWrite = defineWriteHandler({
+    name: "markAllRead",
+    schema: z.object({}),
+    access: {
+        openToAll: {
+            reason: "each signed-in user marks only their own unread in-app messages as read; the " +
+                "update is scoped to the caller's own userId",
+        },
+    },
+    description: "Marks every unread in-app message of the calling user as read and returns how many rows were touched; use it for a mark-all-as-read action.",
+    handler: async (event, ctx) => {
+        const rows = await updateMany(ctx.db, inAppMessagesTable, { isRead: true, readAt: Temporal.Now.instant() }, { userId: event.user.id, isRead: false });
+        return { isSuccess: true, data: { marked: rows.length } };
+    },
+});

package/dist/channel-in-app/handlers/mark-read.write.d.ts

@@ -0,0 +1,6 @@
+import * as z from "zod";
+export declare const markReadWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"markRead", z.ZodObject<{
+    id: z.ZodNumber;
+}, z.core.$strip>, {
+    id: number | undefined;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;