@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/cap-counter/enforce-cap.d.ts

@@ -57,6 +57,9 @@ export declare function assertBelowHardCap(valueSeenByLastUnit: number, cap: {
     readonly capName: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    readonly periodStartIso?: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): void;
 /**
  * Synchronous read-and-check of the calling tenant's counter for
@@ -85,6 +88,8 @@ export declare function enforceCap(ctx: CapCounterContext, options: {
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): Promise<EnforceCapResult>;
 /**
  * Synchronous read-and-check of the calling tenant's Rolling-Window-
@@ -120,6 +125,9 @@ export declare function enforceRollingCap(ctx: CapCounterContext, options: {
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export declare class CapExceededError extends KumikoError {
     readonly capName: string;
@@ -128,7 +136,13 @@ export declare class CapExceededError extends KumikoError {
     readonly tolerance: CapToleranceProfile;
     readonly code: "cap_exceeded";
     readonly httpStatus = 429;
-    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile);
+    readonly resetAt: string | undefined;
+    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile, options?: {
+        readonly resetAt?: string;
+        readonly i18nKey?: string;
+        readonly cause?: Error;
+        readonly now?: Temporal.Instant;
+    });
 }
 /**
  * Calendar-month period start in UTC. Use this for monthly caps
@@ -137,6 +151,7 @@ export declare class CapExceededError extends KumikoError {
  * Returns ISO string for the 1st of the current month at 00:00 UTC.
  */
 export declare function currentCalendarMonthStartIso(now?: Temporal.Instant): string;
+export declare function calendarMonthPeriodEndIso(periodStartIso: string): string;
 /**
  * Soft-hit-notifier callback. Caller liefert die Funktion die ein
  * delivery-event emittet (z.B. `delivery.send({to, template, payload})`).
@@ -169,6 +184,8 @@ export declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly markSoftWarnedOutsideTransaction?: boolean;
 }): Promise<EnforceCapResult>;
 /**

package/dist/cap-counter/enforce-cap.js

@@ -17,8 +17,24 @@ export const CAP_TOLERANCES = {
 export function assertBelowHardCap(valueSeenByLastUnit, cap) {
     const tolerance = CAP_TOLERANCES[cap.profile];
     if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-        throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+        const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
+        throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance, {
+            ...(resetAt !== undefined && { resetAt }),
+            ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
+        });
+    }
+}
+function resolvePeriodEndIso(periodStartIso, periodEndIso) {
+    if (periodStartIso === undefined)
+        return periodEndIso;
+    if (periodEndIso === undefined)
+        return calendarMonthPeriodEndIso(periodStartIso);
+    const start = Temporal.Instant.from(periodStartIso);
+    const end = Temporal.Instant.from(periodEndIso);
+    if (Temporal.Instant.compare(end, start) <= 0) {
+        throw new Error(`cap-counter: periodEndIso (${periodEndIso}) must be after periodStartIso (${periodStartIso})`);
     }
+    return end.toString();
 }
 // =============================================================================
 // Enforce-Cap helper
@@ -115,6 +131,9 @@ export async function enforceRollingCap(ctx, options) {
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export class CapExceededError extends KumikoError {
     capName;
@@ -123,17 +142,32 @@ export class CapExceededError extends KumikoError {
     tolerance;
     code = "cap_exceeded";
     httpStatus = 429;
-    constructor(capName, limit, currentValue, tolerance) {
+    resetAt;
+    constructor(capName, limit, currentValue, tolerance, options) {
+        const resetAt = options?.resetAt;
+        const retryAfterSeconds = resetAt === undefined
+            ? undefined
+            : Math.max(0, Math.ceil(Temporal.Instant.from(resetAt).epochMilliseconds / 1000 -
+                (options?.now ?? Temporal.Now.instant()).epochMilliseconds / 1000));
         super({
-            message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.`,
-            i18nKey: "errors.cap.exceeded",
-            i18nParams: { capName, limit, currentValue },
-            details: { capName, limit, currentValue, tolerance },
+            message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.${resetAt === undefined ? "" : ` Resets at ${resetAt}.`}`,
+            i18nKey: options?.i18nKey ?? "errors.cap.exceeded",
+            i18nParams: { capName, limit, currentValue, ...(resetAt !== undefined && { resetAt }) },
+            details: {
+                capName,
+                limit,
+                currentValue,
+                tolerance,
+                ...(resetAt !== undefined && { resetAt, retryAfterSeconds }),
+            },
+            ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+            ...(options?.cause && { cause: options.cause }),
         });
         this.capName = capName;
         this.limit = limit;
         this.currentValue = currentValue;
         this.tolerance = tolerance;
+        this.resetAt = resetAt;
     }
 }
 // =============================================================================
@@ -158,6 +192,13 @@ export function currentCalendarMonthStartIso(now = Temporal.Now.instant()) {
     });
     return start.toInstant().toString();
 }
+export function calendarMonthPeriodEndIso(periodStartIso) {
+    return Temporal.Instant.from(periodStartIso)
+        .toZonedDateTimeISO("UTC")
+        .add({ months: 1 })
+        .toInstant()
+        .toString();
+}
 /**
  * Calendar-Period-enforcement + automatische soft-hit-Notification.
  * Ruft `enforceCap`, bei `crossed: true` den Notifier UND
@@ -175,6 +216,8 @@ export async function enforceCapAndMaybeNotify(ctx, options) {
         limit: options.limit,
         profile: options.profile,
         ...(options.amount !== undefined && { amount: options.amount }),
+        ...(options.periodEndIso !== undefined && { periodEndIso: options.periodEndIso }),
+        ...(options.i18nKey !== undefined && { i18nKey: options.i18nKey }),
     });
     if (result.state === "soft-hit" && result.crossed) {
         await options.notify({

package/dist/cap-counter/index.d.ts

@@ -2,7 +2,7 @@ export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js"
 export { type BookCapUsageOptions, bookCapUsage, type MarkCapSoftWarnedOptions, markCapSoftWarned, type ReadRollingCapUsageOptions, readRollingCapUsage, } from "./book-cap-usage.js";
 export { type CalendarCapUsageReservation, type CalendarCapUsageReservationSpec, reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
 export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
-export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
+export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, calendarMonthPeriodEndIso, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";

package/dist/cap-counter/index.js

@@ -3,7 +3,7 @@ export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js"
 export { bookCapUsage, markCapSoftWarned, readRollingCapUsage, } from "./book-cap-usage.js";
 export { reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
 export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
-export { CAP_TOLERANCES, CapExceededError, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
+export { CAP_TOLERANCES, CapExceededError, calendarMonthPeriodEndIso, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -10,6 +10,8 @@ import { type CapToleranceProfileName, type SoftHitNotifier } from "./enforce-ca
 export type CalendarCapDef = {
     readonly capName: string;
     readonly periodStartIso: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     /** Increment-amount post-success. Default 1. */

package/dist/cap-overview/handlers/tenant-caps-list.query.js

@@ -2,6 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable, decodeCursor, encodeCursor } from "@cosmicdrift/kumiko-framework/db";
 import { definePagedQueryHandler, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
 import { decryptTenantNames, tenantTable } from "../../tenant/index.js";
@@ -34,7 +35,7 @@ async function resolveLimitsByTenantAndCap(caps, tenants, configFor) {
     return new Map(entries);
 }
 function isSortableField(field) {
-    return SORTABLE_FIELDS.includes(field);
+    return isOneOf(SORTABLE_FIELDS, field);
 }
 // tier is a plain string with no defined ordering — lt/gt have no meaning
 // on it and are rejected rather than silently treated as "no filter".

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

@@ -1,13 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { CapUsageBar } from "./cap-usage-bar.js";
 function isCapUsage(value) {
-    if (typeof value !== "object" || value === null)
+    if (!isPlainObject(value))
         return false;
-    const used = value.used;
-    const limit = value.limit;
+    const used = value["used"];
+    const limit = value["limit"];
     return ((typeof used === "number" || used === null) &&
         (typeof limit === "number" || limit === null) &&
-        typeof value.fraction === "number");
+        typeof value["fraction"] === "number");
 }
 export function CapUsageCell({ value }) {
     if (!isCapUsage(value))

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

@@ -1,9 +1,9 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { type DeliveryChannel, type NotificationRenderer } from "../delivery/index.js";
+import { type DeliveryChannel, type EmailAttachmentRef } from "../delivery/index.js";
 import type { EmailTransport } from "./types.js";
+export declare function fileAttachmentsFrom(data: Readonly<Record<string, unknown>> | undefined, messageLocale?: string): readonly EmailAttachmentRef[];
 export type EmailChannelOptions = {
     readonly transport: EmailTransport;
-    readonly renderer: NotificationRenderer;
     readonly resolveEmail: (userId: string, ctx: {
         db: unknown;
         tenantId: TenantId;

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

@@ -1,5 +1,6 @@
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
-import { DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, } from "../delivery/index.js";
+import * as z from "zod";
+import { DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, EMAIL_CHANNEL_NAME, fileAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, renderedPdfAttachmentRefSchema, } from "../delivery/index.js";
 import { decryptStoredPii } from "../shared/index.js";
 import { guardEmailMessage } from "./pii-guard.js";
 // Envelope (From / Reply-To / threading headers) rides on the channel data —
@@ -65,31 +66,95 @@ function emailEnvelopeFrom(data) {
         ...(headers && { headers }),
     };
 }
+const fileAttachmentsSchema = z
+    .array(z.discriminatedUnion("kind", [fileAttachmentRefSchema, renderedPdfAttachmentRefSchema]))
+    .max(MAX_EMAIL_ATTACHMENTS);
+// Only kinds "file" and "rendered-pdf" may come from notify data; inline images are created by the renderer alone.
+// Invalid input throws instead of dropping the attachment silently.
+export function fileAttachmentsFrom(data, messageLocale) {
+    const raw = data?.["attachments"];
+    if (raw === undefined)
+        return [];
+    return fileAttachmentsSchema
+        .parse(raw)
+        .map((ref) => ref.kind === "rendered-pdf" && ref.locale === undefined && messageLocale !== undefined
+        ? { ...ref, locale: messageLocale }
+        : ref);
+}
+const INLINE_EXTENSION_BY_CONTENT_TYPE = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+async function resolveAttachments(sources, ctx) {
+    if (sources.length === 0)
+        return [];
+    if (ctx.readAttachment === undefined) {
+        throw new Error("email channel: the message has attachments but the channel context cannot read files");
+    }
+    const resolved = [];
+    for (const { ref, origin } of sources) {
+        const found = await ctx.readAttachment(ref, origin);
+        if (ref.kind === "rendered-pdf") {
+            if (found === null) {
+                throw new Error(`email channel: rendering attachment "${ref.fileName}" returned nothing`);
+            }
+            resolved.push({
+                kind: "rendered-pdf",
+                templateSlug: ref.templateSlug,
+                fileName: ref.fileName,
+                content: found.content,
+                contentType: found.contentType,
+            });
+            continue;
+        }
+        if (found === null) {
+            // A missing inline image only degrades the look; a missing file is content the recipient expects.
+            if (ref.kind === "inline")
+                continue;
+            throw new Error(`email channel: attachment file ${ref.fileRefId} was not found`);
+        }
+        const fileName = ref.kind === "file"
+            ? ref.fileName
+            : INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]
+                ? `${ref.cid}.${INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]}`
+                : ref.cid;
+        resolved.push({ ...ref, fileName, content: found.content, contentType: found.contentType });
+    }
+    return resolved;
+}
 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)
+    const { transport, resolveEmail } = options;
+    // Render runs in the delivery.render job, decoupled from the SMTP send so
+    // each can retry independently. Extracted so the inline path (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 rendererInput = {
-            template: message.notificationType,
-            variables,
-            locale: message.locale,
+    async function renderMessage(message, ctx) {
+        const notificationType = message.notificationType;
+        if (ctx.registry.getAllNotifications().get(notificationType)?.template === undefined) {
+            throw new Error(`email channel: notification "${notificationType}" has no mail template, declare template + meta on r.notification`);
+        }
+        if (ctx.renderMail === undefined) {
+            throw new Error(`email channel: notification "${notificationType}" has a mail template but the channel context carries no renderMail`);
+        }
+        const unsubscribeUrl = message.data?.["unsubscribeUrl"];
+        const { subject, html, text, attachments, fromName, replyTo } = await ctx.renderMail({
+            slug: notificationType,
+            locale: message.locale ?? "en",
+            variables: message.data ?? {},
+            ...(typeof unsubscribeUrl === "string" && { unsubscribeUrl }),
+        });
+        return {
+            html,
+            subject,
+            text,
+            ...(fromName !== undefined && { fromName }),
+            ...(replyTo !== undefined && { replyTo }),
+            ...(attachments !== undefined && { attachments }),
         };
-        const html = await renderer.render(rendererInput);
-        const text = renderer.renderText ? await renderer.renderText(rendererInput) : undefined;
-        const subject = variables["subject"] ?? message.title; // @cast-boundary dynamic-key
-        return { html, subject, ...(text !== undefined && { text }) };
     }
     return {
-        name: "email",
+        name: EMAIL_CHANNEL_NAME,
         mode: "queued",
         // resolveEmail typically returns the raw stored user.email, which is ciphertext under an active KMS.
         async resolve(userId, ctx) {
@@ -99,18 +164,28 @@ export function createEmailChannel(options) {
             const address = await decryptStoredPii(stored, "email", "channel-email:resolve");
             return address === PII_ERASED_SENTINEL ? null : address;
         },
-        render(message, _ctx) {
-            return renderMessage(message);
+        render(message, ctx) {
+            return renderMessage(message, ctx);
         },
-        async send(address, message, _ctx, rendered) {
-            const { html, subject, text } = rendered ?? (await renderMessage(message));
-            const envelope = emailEnvelopeFrom(message.data);
+        async send(address, message, ctx, rendered) {
+            const { html, subject, text, attachments, fromName, replyTo } = rendered ?? (await renderMessage(message, ctx));
+            // Template-level sender defaults; notify data wins.
+            const envelope = {
+                ...(fromName && { fromName }),
+                ...(replyTo && { replyTo }),
+                ...emailEnvelopeFrom(message.data),
+            };
+            const resolvedAttachments = await resolveAttachments([
+                ...(attachments ?? []).map((ref) => ({ ref, origin: "template" })),
+                ...fileAttachmentsFrom(message.data, message.locale).map((ref) => ({ ref, origin: "message" })),
+            ], ctx);
             await transport.send(guardEmailMessage({
                 to: address,
                 subject,
                 html,
                 ...(text !== undefined && { text }),
                 ...envelope,
+                ...(resolvedAttachments.length > 0 && { attachments: resolvedAttachments }),
             }));
             return { status: "sent", address };
         },

package/dist/channel-email/feature.js

@@ -1,10 +1,10 @@
-import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { DELIVERY_CHANNEL_EXTENSION, EMAIL_CHANNEL_NAME, } 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.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` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.");
         r.uiHints({
             displayLabel: "Email Channel",
             category: "notifications",
@@ -12,7 +12,7 @@ export function createChannelEmailFeature(options) {
         });
         r.requires("delivery");
         r.translations({ keys: { "delivery.channel.email": { en: "Email" } } });
-        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, EMAIL_CHANNEL_NAME, {
             mode: channel.mode,
             resolve: channel.resolve,
             render: channel.render,

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

@@ -2,4 +2,4 @@ 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";
+export { createInMemoryTransport, type EmailAttachment, type EmailAttachmentRef, type EmailMessage, type EmailTransport, } from "./types.js";

package/dist/channel-email/index.js

@@ -2,4 +2,4 @@ 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";
+export { createInMemoryTransport, } from "./types.js";

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

@@ -8,6 +8,15 @@ const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 // 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.
+function assertAttachmentNamesArePlain(message) {
+    for (const attachment of message.attachments ?? []) {
+        const fields = [attachment.fileName, attachment.kind === "inline" ? attachment.cid : undefined];
+        if (fields.some((field) => field?.includes(CIPHERTEXT_MARKER))) {
+            throw new Error(`[channel-email] refusing to send: attachment file name is a PII ciphertext ` +
+                `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`);
+        }
+    }
+}
 export function guardEmailMessage(message) {
     // Every envelope address, not just `to`: a ciphertext From, From-Name or Reply-To is
     // the same garbage as a ciphertext recipient — refuse rather than mail it.
@@ -28,6 +37,7 @@ export function guardEmailMessage(message) {
                 `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`);
         }
     }
+    assertAttachmentNamesArePlain(message);
     const leaking = message.subject.includes(CIPHERTEXT_MARKER) ||
         message.html.includes(CIPHERTEXT_MARKER) ||
         message.text?.includes(CIPHERTEXT_MARKER) === true;

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

@@ -37,6 +37,16 @@ function fromHeader(address, fromName) {
     const [parsed] = addressparser(address, { flatten: true });
     return parsed?.address ? { name, address: parsed.address } : address;
 }
+function toNodemailerAttachment(attachment) {
+    const base = {
+        filename: attachment.fileName,
+        content: Buffer.from(attachment.content),
+        contentType: attachment.contentType,
+    };
+    return attachment.kind === "inline"
+        ? { ...base, cid: attachment.cid, contentDisposition: "inline" }
+        : base;
+}
 export function createSmtpTransport(options) {
     const transporter = createTransport({
         host: options.host,
@@ -57,6 +67,9 @@ export function createSmtpTransport(options) {
                 ...(message.text !== undefined && { text: message.text }),
                 ...(message.replyTo && { replyTo: message.replyTo }),
                 ...(message.headers && { headers: message.headers }),
+                ...(message.attachments && {
+                    attachments: message.attachments.map(toNodemailerAttachment),
+                }),
             });
         },
     };

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

@@ -1,3 +1,10 @@
+import type { EmailAttachmentRef, FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef } from "../delivery/index.js";
+export type { EmailAttachmentRef };
+export type EmailAttachment = (InlineAttachmentRef | FileAttachmentRef | Pick<RenderedPdfAttachmentRef, "kind" | "templateSlug">) & {
+    readonly content: Uint8Array;
+    readonly contentType: string;
+    readonly fileName: string;
+};
 export type EmailMessage = {
     readonly to: string;
     readonly subject: string;
@@ -7,6 +14,7 @@ export type EmailMessage = {
     readonly fromName?: string;
     readonly replyTo?: string;
     readonly headers?: Readonly<Record<string, string>>;
+    readonly attachments?: readonly EmailAttachment[];
 };
 export type EmailTransport = {
     send(message: EmailMessage): Promise<void>;

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

@@ -1,4 +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>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

@@ -3,4 +3,4 @@ export declare const markReadWrite: import("@cosmicdrift/kumiko-types/define-han
     id: z.ZodNumber;
 }, z.core.$strip>, {
     id: number | undefined;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/compliance-profiles/handlers/set-profile.write.d.ts

@@ -10,4 +10,4 @@ export declare const setProfileWrite: import("@cosmicdrift/kumiko-types/define-h
 }, z.core.$strip>, {
     profileKey: "de-hr-dsgvo-hgb" | "eu-dsgvo" | "swiss-dsg";
     isNew: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/config/handlers/reset.write.d.ts

@@ -9,4 +9,4 @@ export declare const resetWrite: import("@cosmicdrift/kumiko-types/define-handle
 }, z.core.$strip>, {
     key: string;
     scope: import("@cosmicdrift/kumiko-types/config-scope").ConfigScope;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/config/handlers/set.write.d.ts

@@ -11,4 +11,4 @@ export declare const setWrite: import("@cosmicdrift/kumiko-types/define-handler"
     key: string;
     value: string | number | boolean;
     scope: import("@cosmicdrift/kumiko-types/config-scope").ConfigScope;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/config/handlers/set.write.js

@@ -1,6 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject, } from "@cosmicdrift/kumiko-framework/crypto";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, scopeTenantDbToTenant } from "@cosmicdrift/kumiko-framework/db";
 import { ConfigScopes, defineWriteHandler, isEncryptedAtRest, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, isKumikoError, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
@@ -74,7 +74,7 @@ export const setWrite = defineWriteHandler({
                     scope,
                     tenantId,
                     userId,
-                    db,
+                    db: scopeTenantDbToTenant(db, tenantId),
                 });
             }
             catch (error) {
@@ -120,8 +120,7 @@ export const setWrite = defineWriteHandler({
                 });
             }
             // scope="system" was already rejected above — narrow accordingly.
-            const subject = resolvePiiSubject(scope, // @cast-boundary runtime-checked above
-            tenantId, userId);
+            const subject = resolvePiiSubject(scope, tenantId, userId);
             const kmsCtx = {
                 requestId: requestContext.get()?.requestId ?? "config:write:set",
                 tenantId,

package/dist/config/resolver.d.ts

@@ -7,6 +7,7 @@ export type ConfigResolverOptions = {
     cipher?: EnvelopeCipher;
     appOverrides?: AppConfigOverrides;
 };
+export declare function decryptStoredValue(raw: string, keyDef: ConfigKeyDefinition, cipher: EnvelopeCipher | undefined, qualifiedKey: string): Promise<string>;
 export declare function createConfigResolver(options?: ConfigResolverOptions): ConfigResolver;
 export declare function validateAppOverrides(registry: {
     getConfigKey: (key: string) => import("@cosmicdrift/kumiko-framework/engine").ConfigKeyDefinition | undefined;

package/dist/config/resolver.js

@@ -57,6 +57,15 @@ async function decryptPiiEncrypted(raw, qualifiedKey) {
     const kmsCtx = { requestId: requestContext.get()?.requestId ?? "config:resolver" };
     return decryptPiiValueForSubject(kms, raw, kmsCtx, qualifiedKey);
 }
+// Plaintext form of a stored config_values.value for every read path (resolver,
+// bootstrap idempotency check).
+export async function decryptStoredValue(raw, keyDef, cipher, qualifiedKey) {
+    if (keyDef.encrypted)
+        return decryptEncrypted(cipher, raw, qualifiedKey);
+    if (keyDef.piiEncrypted)
+        return decryptPiiEncrypted(raw, qualifiedKey);
+    return raw;
+}
 // backing="secrets" keys store their value in the secrets store (flat per
 // (tenant,key) at SYSTEM_TENANT_ID), not in config_values. Both read paths
 // (getWithSource + buildCascade) route the system rung here. Missing reader =
@@ -142,13 +151,7 @@ async function buildCascade(qualifiedKey, keyDef, tenantId, userId, db, fetchRow
         }
         const row = await fetchRow(lookup.tenantId, lookup.userId);
         if (row?.value !== null && row?.value !== undefined) {
-            let raw = row.value;
-            if (keyDef.encrypted) {
-                raw = await decryptEncrypted(cipher, raw, qualifiedKey);
-            }
-            else if (keyDef.piiEncrypted) {
-                raw = await decryptPiiEncrypted(raw, qualifiedKey);
-            }
+            const raw = await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey);
             if (activeIndex === -1)
                 activeIndex = levels.length;
             levels.push({
@@ -296,13 +299,7 @@ export function createConfigResolver(options = {}) {
             for (const lookup of lookups) {
                 const row = await findRow(qualifiedKey, lookup.tenantId, lookup.userId, db);
                 if (row?.value !== null && row?.value !== undefined) {
-                    let raw = row.value;
-                    if (keyDef.encrypted) {
-                        raw = await decryptEncrypted(cipher, raw, qualifiedKey);
-                    }
-                    else if (keyDef.piiEncrypted) {
-                        raw = await decryptPiiEncrypted(raw, qualifiedKey);
-                    }
+                    const raw = await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey);
                     return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
                 }
             }