@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/rate-limiting/handlers/bucket-access.js

@@ -0,0 +1,28 @@
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { RateLimitErrors } from "../constants.js";
+function ownsBucket(bucket, caller) {
+    const [dimension, subject, ...handler] = bucket.split(":");
+    if (dimension === undefined)
+        return false;
+    const owner = dimension === "tenant" || dimension === "tenant+handler"
+        ? caller.tenantId
+        : dimension === "user" || dimension === "user+handler"
+            ? caller.id
+            : undefined;
+    if (owner === undefined)
+        return false;
+    // Segment-exact: a startsWith check would pass `tenant:<own-id>-other`.
+    if (subject !== owner)
+        return false;
+    return dimension.endsWith("+handler") ? handler.length > 0 : handler.length === 0;
+}
+export function bucketAccessDenied(bucket, caller) {
+    if (caller.roles.includes("SystemAdmin"))
+        return undefined;
+    if (ownsBucket(bucket, caller))
+        return undefined;
+    return new AccessDeniedError({
+        i18nKey: "rateLimiting.errors.bucketOutsideTenant",
+        details: { reason: RateLimitErrors.bucketOutsideTenant },
+    });
+}

package/dist/rate-limiting/handlers/status.query.d.ts

@@ -0,0 +1,13 @@
+import * as z from "zod";
+export declare const rateLimitStatus: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"status", z.ZodObject<{
+    bucket: z.ZodString;
+    limit: z.ZodNumber;
+    windowSeconds: z.ZodNumber;
+}, z.core.$strip>, {
+    bucket: string;
+    limit: number;
+    remaining: number;
+    windowSeconds: number;
+    resetAt: string;
+    retryAfterSeconds: number;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/rate-limiting/handlers/status.query.js

@@ -0,0 +1,59 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { RateLimitErrors } from "../constants.js";
+import { bucketAccessDenied } from "./bucket-access.js";
+// Ops-side bucket inspection. Pass the bucket key (e.g. "user:42",
+// "user+handler:42:orders:write:order:create") plus the limit/window the bucket
+// was configured with, and get back the current state. Backed by
+// resolver.peek() — purely read-only, no token deduction and no
+// refill-timestamp update, so dashboards can poll without nudging the
+// bucket state ahead of the next real request.
+//
+// Use cases: ops-CLI ("kumiko rl status user:42"), support agent debugging
+// "why is this user blocked", dashboard tile.
+//
+// Bucket key format is owned by the framework (see rate-limit/bucket.ts);
+// callers pass the constructed key directly. We don't synthesize from
+// (per, user, handler) here — peeking is a low-level op, the lookup
+// surface stays small. Because the key is caller-supplied, bucket-access.ts
+// restricts it to the caller's own tenant/user unless they are SystemAdmin.
+export const rateLimitStatus = defineQueryHandler({
+    // Short name — the registry qualifies this to `rate-limiting:query:status`
+    // when the feature is registered. Passing the qualified form here would
+    // double-prefix it and the handler wouldn't be reachable.
+    name: "status",
+    description: "Peeks at one rate-limit bucket and returns its remaining tokens, window and next reset without consuming a token; use it to explain why a caller is being throttled. Non-SystemAdmin callers may only peek their own tenant's buckets (`tenant:`/`tenant+handler:`) and their own user buckets (`user:`/`user+handler:`); every other key, including the global `ip:`/`l1:`/`l2:` buckets, requires SystemAdmin.",
+    schema: z.object({
+        bucket: z.string().min(1),
+        limit: z.number().int().positive(),
+        windowSeconds: z.number().int().positive(),
+    }),
+    access: { roles: ["Admin", "SystemAdmin"] },
+    handler: async (query, ctx) => {
+        // Before the resolver check, so a foreign-tenant caller learns nothing
+        // about the wiring either.
+        const denied = bucketAccessDenied(query.payload.bucket, ctx.user);
+        if (denied)
+            throw denied;
+        if (!ctx.rateLimit) {
+            throw new UnprocessableError(RateLimitErrors.resolverUnavailable, {
+                i18nKey: "rateLimiting.errors.resolverUnavailable",
+            });
+        }
+        const decision = await ctx.rateLimit.peek(query.payload.bucket, {
+            limit: query.payload.limit,
+            windowSeconds: query.payload.windowSeconds,
+        });
+        return {
+            bucket: query.payload.bucket,
+            limit: decision.limit,
+            remaining: decision.remaining,
+            windowSeconds: decision.windowSeconds,
+            // resetAt is meaningful only if the bucket is currently exhausted;
+            // we still return it so dashboards can show "next refill" uniformly.
+            resetAt: decision.resetAt.toString(),
+            retryAfterSeconds: decision.retryAfterSeconds,
+        };
+    },
+});

package/dist/rate-limiting/index.d.ts

@@ -0,0 +1,2 @@
+export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants.js";
+export { createRateLimitingFeature } from "./feature.js";

package/dist/rate-limiting/index.js

@@ -0,0 +1,2 @@
+export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants.js";
+export { createRateLimitingFeature } from "./feature.js";

package/dist/readiness/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const READINESS_FEATURE: "readiness";
+export declare const ReadinessQueries: {
+    readonly status: "readiness:query:status";
+};

package/dist/readiness/constants.js

@@ -0,0 +1,6 @@
+// Feature name
+export const READINESS_FEATURE = "readiness";
+// Qualified query handler names (QN format: scope:type:name)
+export const ReadinessQueries = {
+    status: "readiness:query:status",
+};

package/dist/readiness/feature.d.ts

@@ -0,0 +1,7 @@
+export declare const readinessFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: {
+        queries: {
+            status: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+        };
+    };
+};

package/dist/readiness/feature.js

@@ -0,0 +1,25 @@
+// kumiko-feature-version: 1
+//
+// readiness — one-call tenant-onboarding rollup above config + secrets.
+//
+// `config:query:readiness` lists required config keys without a usable
+// value; `secrets:query:list` lists set secrets. Neither can verdict
+// "tenant is ready" alone. This feature requires both, so its status
+// query may roll up missing config + missing required secrets + a single
+// `ready` boolean — the settings-checklist call for admin UIs.
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { statusQuery } from "./handlers/status.query.js";
+export const readinessFeature = defineFeature("readiness", (r) => {
+    r.describe("One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`.");
+    r.uiHints({
+        displayLabel: "Readiness · Onboarding Probe",
+        category: "operations",
+        recommended: false,
+    });
+    r.requires("config");
+    r.requires("secrets");
+    const queries = {
+        status: r.queryHandler(statusQuery),
+    };
+    return { queries };
+});

package/dist/readiness/handlers/status.query.d.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+export type ReadinessMissingSecret = {
+    readonly key: string;
+};
+export declare const statusQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"status", z.ZodObject<{}, z.core.$strip>, {
+    missingConfig: import("@cosmicdrift/kumiko-bundled-features/config").ReadinessMissingKey[];
+    missingSecrets: ReadinessMissingSecret[];
+    ready: boolean;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/readiness/handlers/status.query.js

@@ -0,0 +1,41 @@
+import { buildProviderSelectionGate, collectMissingRequiredConfig, } from "@cosmicdrift/kumiko-bundled-features/config";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { ReadinessQueries } from "../constants.js";
+// The one-call rollup config:query:readiness deliberately refused: that
+// query can't see secrets, this feature requires both — so it may verdict.
+export const statusQuery = defineQueryHandler({
+    name: "status",
+    description: "Reports whether the caller's tenant is fully configured, naming every required config key and every required secret that is still unset; use it to answer what is missing before go-live.",
+    schema: z.object({}),
+    // Same gate as secrets:query:list — the response names missing secrets.
+    access: { roles: ["TenantAdmin"] },
+    handler: async (query, ctx) => {
+        // One gate for both halves: required keys/secrets of provider-features
+        // count only while their provider is the selected one (r.extensionSelector).
+        const gate = await buildProviderSelectionGate(ctx, ReadinessQueries.status, query.user, ctx.db);
+        // skipAccessFilter: das Verdict muss ALLE required Keys zählen — der
+        // Handler selbst ist TenantAdmin-gated, der Per-Key-Filter wäre hier
+        // eine ready:true-Lüge für SystemAdmin-gated Keys (277/1).
+        const missingConfig = await collectMissingRequiredConfig(ctx, ReadinessQueries.status, query.user, ctx.db, gate, { skipAccessFilter: true });
+        // has() is metadata-only: no decryption, no read-audit event — a
+        // readiness probe must not pollute the credential-read trail.
+        const secrets = requireSecretsContext(ctx, ReadinessQueries.status);
+        const missingSecrets = [];
+        for (const [qualifiedName, keyDef] of ctx.registry.getAllSecretKeys()) {
+            if (keyDef.required !== true)
+                continue;
+            if (!gate(qualifiedName))
+                continue;
+            if (!(await secrets.has(query.user.tenantId, qualifiedName))) {
+                missingSecrets.push({ key: qualifiedName });
+            }
+        }
+        return {
+            missingConfig,
+            missingSecrets,
+            ready: missingConfig.length === 0 && missingSecrets.length === 0,
+        };
+    },
+});

package/dist/readiness/index.d.ts

@@ -0,0 +1,3 @@
+export { READINESS_FEATURE, ReadinessQueries } from "./constants.js";
+export { readinessFeature } from "./feature.js";
+export type { ReadinessMissingSecret } from "./handlers/status.query.js";

package/dist/readiness/index.js

@@ -0,0 +1,2 @@
+export { READINESS_FEATURE, ReadinessQueries } from "./constants.js";
+export { readinessFeature } from "./feature.js";

package/dist/renderer-foundation/api.d.ts

@@ -0,0 +1,30 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type RenderKind } from "./constants.js";
+import { type RendererPlugin } from "./types.js";
+export type RendererFoundationApi = {
+    /**
+     * Wählt + returnt ein RendererPlugin für (tenantId × kind). Caller
+     * rufen anschließend `plugin.render(req, ctx)`.
+     *
+     * **Auswahl-Reihenfolge:**
+     *   1. Tenant-spezifische Config (config-Bundle: `rendererPluginByKind`)
+     *   2. DEFAULT_PLUGIN_BY_KIND aus constants
+     *   3. Erstes Plugin im Pool das das kind bedient
+     *   4. `RendererError("no_plugin_for_kind")` wenn nichts passt
+     *
+     * **Caller-Pattern:** `tenantId` MUSS vom Server kommen (typisch
+     * `ctx.user.tenantId`). Plugins, die Service-Access brauchen (z.B.
+     * `renderer-mail-html` für Layout-Resolve via `template-resolver`),
+     * erhalten `RendererContext` als zweites Argument zu `render()` —
+     * matcht das Pattern von `DeliveryChannel.send(addr, msg, ctx)`.
+     * Plugins ohne Service-Deps (z.B. `renderer-simple`) ignorieren ctx.
+     */
+    readonly createRendererForTenant: (args: {
+        readonly tenantId: TenantId;
+        readonly kind: RenderKind;
+    }) => RendererPlugin;
+};
+export declare function createRendererFoundationApi(plugins: ReadonlyArray<RendererPlugin>, tenantConfigLookup?: (tenantId: TenantId) => Record<string, string> | null): RendererFoundationApi;
+export declare function requireRendererFoundation(ctx: {
+    readonly rendererFoundation?: RendererFoundationApi;
+} | object, callerName: string): RendererFoundationApi;

package/dist/renderer-foundation/api.js

@@ -0,0 +1,66 @@
+// RendererFoundationApi — Cross-Feature-Schnittstelle. Konsumenten
+// (delivery, mail-Sender, Solon NKA-PDF-Generator) holen sich pro
+// Render-Call den passenden Plugin via `createRendererForTenant`.
+// Pattern symmetrisch zu ai-foundation's `createLLMProviderForTenant`.
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { DEFAULT_PLUGIN_BY_KIND } from "./constants.js";
+import { RendererError } from "./types.js";
+// Plugin-Pool wird zur Boot-Zeit aus Extension-Usages aufgebaut.
+// Aus dem Registry kommen alle registrierten Plugins. Foundation-Feature
+// baut den Pool via `collectRendererPlugins(registry)` und steckt das
+// Result in extraContext.
+export function createRendererFoundationApi(plugins, tenantConfigLookup = () => null) {
+    const byKind = indexByKind(plugins);
+    return {
+        createRendererForTenant: ({ tenantId, kind }) => {
+            const tenantConfig = tenantConfigLookup(tenantId) ?? {};
+            // 1. Tenant-Override
+            const tenantPluginName = tenantConfig[kind];
+            if (tenantPluginName) {
+                const plugin = plugins.find((p) => p.name === tenantPluginName && p.kinds.includes(kind));
+                if (plugin)
+                    return plugin;
+                // Tenant-Config zeigt auf nicht-registriertes Plugin — fällt durch zu Default
+            }
+            // 2. Default-Plugin
+            const defaultName = DEFAULT_PLUGIN_BY_KIND[kind];
+            if (defaultName) {
+                const plugin = plugins.find((p) => p.name === defaultName && p.kinds.includes(kind));
+                if (plugin)
+                    return plugin;
+            }
+            // 3. Erstes Plugin im Pool das das kind bedient
+            const first = byKind.get(kind)?.[0];
+            if (first)
+                return first;
+            // 4. Kein Plugin → Error
+            throw new RendererError(`[renderer-foundation] no plugin registered for kind="${kind}". Mount at least one plugin (renderer-simple, renderer-mail-html, renderer-puppeteer-client) for this kind.`, "no_plugin_for_kind");
+        },
+    };
+}
+function indexByKind(plugins) {
+    const map = new Map();
+    for (const plugin of plugins) {
+        for (const kind of plugin.kinds) {
+            const list = map.get(kind) ?? [];
+            list.push(plugin);
+            map.set(kind, list);
+        }
+    }
+    return map;
+}
+// Single point of truth für "dieser Handler braucht renderer-foundation".
+// Pattern symmetrisch zu requireTemplateResolver + requireTextContent.
+export function requireRendererFoundation(ctx, callerName) {
+    // @cast-boundary engine-bridge — rendererFoundation kommt per extraContext
+    // aus App-Bootstrap.
+    const api = ctx.rendererFoundation;
+    if (!api) {
+        throw new InternalError({
+            message: `[${callerName}] ctx.rendererFoundation missing — App-Bootstrap muss ` +
+                `extraContext: { rendererFoundation: createRendererFoundationApi(plugins) } setzen ` +
+                `(siehe renderer-foundation/README.md).`,
+        });
+    }
+    return api;
+}

package/dist/renderer-foundation/constants.d.ts

@@ -0,0 +1,4 @@
+import type { RenderKind as RenderKindLocal } from "../template-resolver/index.js";
+export declare const RENDERER_EXTENSION: "renderer";
+export { CONTENT_FORMATS, type ContentFormat, RENDER_KINDS, type RenderKind, } from "../template-resolver/index.js";
+export declare const DEFAULT_PLUGIN_BY_KIND: Readonly<Record<RenderKindLocal, string>>;

package/dist/renderer-foundation/constants.js

@@ -0,0 +1,12 @@
+// Extension-point name for renderer plugins (renderer-simple,
+// renderer-mail-html, renderer-puppeteer-client, ...).
+export const RENDERER_EXTENSION = "renderer";
+export { CONTENT_FORMATS, RENDER_KINDS, } from "../template-resolver/index.js";
+// Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
+// gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.
+export const DEFAULT_PLUGIN_BY_KIND = {
+    notification: "simple",
+    "mail-html": "mail-html",
+    "document-pdf": "puppeteer",
+    "image-snapshot": "puppeteer",
+};

package/dist/renderer-foundation/feature.d.ts

@@ -0,0 +1,6 @@
+import { type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type RendererPlugin } from "./types.js";
+export declare function createRendererFoundationFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: {};
+};
+export declare function collectRendererPlugins(registry: Registry): RendererPlugin[];

package/dist/renderer-foundation/feature.js

@@ -0,0 +1,44 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { RENDERER_EXTENSION } from "./constants.js";
+import { isRendererRegistrationPlugin } from "./types.js";
+// renderer-foundation — Plugin-Foundation für Renderer (Notification,
+// HTML-Mail, PDF, Image). Plan-Doc:
+// kumiko-platform/docs/plans/features/renderer-foundation.md
+//
+// Pattern symmetrisch zu ai-foundation: Foundation definiert den
+// Extension-Point `renderer`, Plugins (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client) registrieren sich via `r.useExtension`.
+// Konsumenten holen sich Plugin runtime via createRendererForTenant.
+export function createRendererFoundationFeature() {
+    return defineFeature("renderer-foundation", (r) => {
+        r.describe('Plugin registry for content rendering (notification HTML, mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block \u2014 add `renderer-simple` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.');
+        r.uiHints({
+            displayLabel: "Renderer Foundation",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("template-resolver");
+        r.extendsRegistrar(RENDERER_EXTENSION, {
+            onRegister: () => {
+                // Plugin-Konformitäts-Check könnte hier: shape-validation der
+                // options (kinds, render-Funktion present). Aktuell kein
+                // shape-check — Caller's TypeScript-Type-Sicherheit greift.
+            },
+        });
+        return {};
+    });
+}
+// Plugin-Pool-Aufbau zur Boot-Zeit. App-Bootstrap ruft das nach
+// Feature-Registration auf, baut den Pool, gibt ihn via extraContext
+// an die Handlers weiter.
+//
+// Symmetrisch zu collectChannels / collectRenderers in delivery-service.
+export function collectRendererPlugins(registry) {
+    const usages = registry.getExtensionUsages(RENDERER_EXTENSION);
+    return usages.map((usage) => {
+        if (!isRendererRegistrationPlugin(usage.options)) {
+            throw new Error(`${RENDERER_EXTENSION} registration for "${usage.entityName}" has invalid options`);
+        }
+        return { name: usage.entityName, ...usage.options };
+    });
+}

package/dist/renderer-foundation/index.d.ts

@@ -0,0 +1,4 @@
+export { createRendererFoundationApi, type RendererFoundationApi, requireRendererFoundation, } from "./api.js";
+export { CONTENT_FORMATS, type ContentFormat, DEFAULT_PLUGIN_BY_KIND, RENDER_KINDS, RENDERER_EXTENSION, type RenderKind, } from "./constants.js";
+export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.js";
+export { type DocumentPayload, type ImageOptions, isRendererRegistrationPlugin, type MailHtmlPayload, type NotificationPayload, type PdfOptions, type RendererContext, RendererError, type RendererPlugin, type RendererRegistrationPlugin, type RenderRequest, type RenderResponse, } from "./types.js";

package/dist/renderer-foundation/index.js

@@ -0,0 +1,4 @@
+export { createRendererFoundationApi, requireRendererFoundation, } from "./api.js";
+export { CONTENT_FORMATS, DEFAULT_PLUGIN_BY_KIND, RENDER_KINDS, RENDERER_EXTENSION, } from "./constants.js";
+export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.js";
+export { isRendererRegistrationPlugin, RendererError, } from "./types.js";

package/dist/renderer-foundation/types.d.ts

@@ -0,0 +1,99 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.js";
+export type RenderRequest = {
+    kind: "notification";
+    payload: NotificationPayload;
+} | {
+    kind: "mail-html";
+    payload: MailHtmlPayload;
+} | {
+    kind: "document-pdf";
+    payload: DocumentPayload;
+    options?: PdfOptions;
+} | {
+    kind: "image-snapshot";
+    payload: DocumentPayload;
+    options?: ImageOptions;
+};
+export type RenderResponse = {
+    kind: "notification";
+    html: string;
+} | {
+    kind: "mail-html";
+    html: string;
+    text: string;
+} | {
+    kind: "document-pdf";
+    pdfBytes: Uint8Array;
+    pageCount: number;
+    sizeBytes: number;
+} | {
+    kind: "image-snapshot";
+    imageBytes: Uint8Array;
+    format: "png" | "jpg";
+    width: number;
+    height: number;
+};
+export type NotificationPayload = {
+    readonly template?: string;
+    readonly content?: string;
+    readonly contentFormat?: ContentFormat;
+    readonly variables?: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+};
+export type MailHtmlPayload = {
+    readonly template?: string;
+    readonly content?: string;
+    readonly contentFormat?: ContentFormat;
+    readonly variables?: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+    readonly subject?: string;
+};
+export type DocumentPayload = {
+    readonly template?: string;
+    readonly content?: string;
+    readonly contentFormat?: ContentFormat;
+    readonly variables?: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+};
+export type PdfOptions = {
+    readonly format?: "A4" | "Letter";
+    readonly marginMm?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    readonly headerTemplate?: string;
+    readonly footerTemplate?: string;
+    readonly printBackground?: boolean;
+    readonly displayHeaderFooter?: boolean;
+};
+export type ImageOptions = {
+    readonly width?: number;
+    readonly height?: number;
+    readonly format?: "png" | "jpg";
+    readonly quality?: number;
+};
+export type RendererContext = {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly tenantId: TenantId;
+};
+export type RendererPlugin = {
+    readonly name: string;
+    readonly kinds: ReadonlyArray<RenderKind>;
+    render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+};
+export declare class RendererError extends Error {
+    readonly code: "no_plugin_for_kind" | "invalid_payload" | "other";
+    constructor(message: string, code: "no_plugin_for_kind" | "invalid_payload" | "other");
+}
+export type RendererRegistrationPlugin = Omit<RendererPlugin, "name">;
+export declare function isRendererRegistrationPlugin(o: unknown): o is RendererRegistrationPlugin;
+declare module "@cosmicdrift/kumiko-framework/engine" {
+    interface KumikoExtensionOptionsMap {
+        [RENDERER_EXTENSION]: RendererRegistrationPlugin;
+    }
+}

package/dist/renderer-foundation/types.js

@@ -0,0 +1,17 @@
+import { RENDERER_EXTENSION } from "./constants.js";
+export class RendererError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "RendererError";
+    }
+}
+export function isRendererRegistrationPlugin(o) {
+    return (typeof o === "object" &&
+        o !== null &&
+        "kinds" in o &&
+        Array.isArray(o.kinds) &&
+        "render" in o &&
+        typeof o.render === "function");
+}

package/dist/renderer-simple/feature.d.ts

@@ -0,0 +1,4 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type RendererContext, type RenderRequest, type RenderResponse } from "../renderer-foundation/index.js";
+export declare function adaptToFoundation(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+export declare function createRendererSimpleFeature(): FeatureDefinition;

package/dist/renderer-simple/feature.js

@@ -0,0 +1,40 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { RENDERER_EXTENSION, RendererError, } from "../renderer-foundation/index.js";
+import { resolveNotificationVariables } from "./resolve-variables.js";
+import { simpleRenderer } from "./simple-renderer.js";
+// Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
+// NotificationRenderer-Contract), renderer-foundation erwartet
+// `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
+// die simpleRenderer-Implementierung (Template-Strings → HTML mit
+// Inline-CSS) und packt sie in den RendererPlugin-Contract.
+//
+// Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
+export async function adaptToFoundation(req, ctx) {
+    if (req.kind !== "notification") {
+        // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
+        // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
+        throw new RendererError(`renderer-simple supports only kind="notification", got "${req.kind}"`, "invalid_payload");
+    }
+    const variables = await resolveNotificationVariables(req, ctx);
+    const html = await simpleRenderer.render({
+        template: req.payload.template ?? "",
+        variables,
+    });
+    return { kind: "notification", html };
+}
+export function createRendererSimpleFeature() {
+    return defineFeature("renderer-simple", (r) => {
+        r.describe('Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.');
+        r.uiHints({
+            displayLabel: "Renderer \u00b7 Simple",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("renderer-foundation");
+        r.optionalRequires("template-resolver");
+        r.useExtension(RENDERER_EXTENSION, "simple", {
+            kinds: ["notification"],
+            render: adaptToFoundation,
+        });
+    });
+}

package/dist/renderer-simple/index.d.ts

@@ -0,0 +1,2 @@
+export { createRendererSimpleFeature } from "./feature.js";
+export { simpleRenderer } from "./simple-renderer.js";

package/dist/renderer-simple/index.js

@@ -0,0 +1,2 @@
+export { createRendererSimpleFeature } from "./feature.js";
+export { simpleRenderer } from "./simple-renderer.js";

package/dist/renderer-simple/resolve-variables.d.ts

@@ -0,0 +1,7 @@
+import type { RendererContext, RenderRequest } from "../renderer-foundation/index.js";
+type NotificationRequest = Extract<RenderRequest, {
+    kind: "notification";
+}>;
+/** Merge template-resolver content (plain JSON EmailTemplateData) with runtime variables. */
+export declare function resolveNotificationVariables(req: NotificationRequest, ctx: RendererContext): Promise<Readonly<Record<string, unknown>>>;
+export {};

package/dist/renderer-simple/resolve-variables.js

@@ -0,0 +1,47 @@
+import { createTemplateResolverApi, FALLBACK_LOCALE, TemplateNotFoundError, } from "../template-resolver/index.js";
+/** Merge template-resolver content (plain JSON EmailTemplateData) with runtime variables. */
+export async function resolveNotificationVariables(req, ctx) {
+    const variables = req.payload.variables ?? {};
+    const slug = req.payload.template?.trim();
+    if (!slug || req.payload.content || !ctx.db || !ctx.registry.features.has("template-resolver")) {
+        return variables;
+    }
+    try {
+        const api = createTemplateResolverApi(ctx.db);
+        const locale = req.payload.locale ?? FALLBACK_LOCALE;
+        const resolved = await api.resolveTemplate({
+            tenantId: ctx.tenantId,
+            slug,
+            kind: "notification",
+            locale,
+        });
+        if (resolved.contentFormat === "plain") {
+            const base = parsePlainTemplateContent(resolved.content);
+            return { ...base, ...variables };
+        }
+        // body always wins from the resolved template for rendered formats — a runtime
+        // "variables.body" override would clobber the actual rendered content.
+        return { ...variables, body: resolved.content };
+    }
+    catch (err) {
+        if (err instanceof TemplateNotFoundError) {
+            return variables;
+        }
+        throw err;
+    }
+}
+function parsePlainTemplateContent(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // ponytail: non-JSON plain content becomes a single body section downstream
+    }
+    return { body: content };
+}

package/dist/renderer-simple/simple-renderer.d.ts

@@ -0,0 +1,2 @@
+import type { NotificationRenderer } from "../delivery/index.js";
+export declare const simpleRenderer: NotificationRenderer;