@cosmicdrift/kumiko-bundled-features 0.365.1 → 0.367.0

package/dist/delivery/unsubscribe-link.d.ts

@@ -0,0 +1,25 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ChannelContext } from "./types.js";
+/** Secret shared with `createUnsubscribeRoutes` plus the public origin the links point at. */
+export type UnsubscribeLinkConfig = {
+    readonly secret: string;
+    readonly baseUrl: string;
+    /** The sending tenant's own public origin (subdomain or custom domain), null when it has
+     *  none. The host must serve this app's `/api` routes. Null, a throw or an unusable value
+     *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
+    readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
+};
+export type UnsubscribeLinkRecipient = {
+    readonly kind: "user";
+    readonly userId: string;
+} | {
+    readonly kind: "address";
+    readonly address: string;
+};
+export declare function unsubscribeLinkOrigin(config: UnsubscribeLinkConfig, ctx: ChannelContext, onFallback: (reason: string) => void): Promise<string>;
+export declare function buildUnsubscribeUrl(config: UnsubscribeLinkConfig, origin: string, recipient: UnsubscribeLinkRecipient, scope: {
+    tenantId: TenantId;
+    notificationType: string;
+    channel: string;
+    locale: string | undefined;
+}): Promise<string | undefined>;

package/dist/delivery/unsubscribe-link.js

@@ -0,0 +1,40 @@
+import { publicOriginOf } from "@cosmicdrift/kumiko-framework/api";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import { DELIVERY_UNSUBSCRIBE_PATH } from "./constants.js";
+import { signAddressUnsubscribeToken, signUnsubscribeToken } from "./unsubscribe.js";
+// https only, unless the app itself runs on plain http (local dev): a tenant origin must not
+// downgrade the link that carries the token.
+function isUsableTenantOrigin(origin, baseUrl) {
+    return (origin.startsWith("https://") || (baseUrl.startsWith("http://") && origin.startsWith("http://")));
+}
+export async function unsubscribeLinkOrigin(config, ctx, onFallback) {
+    if (config.tenantOrigin === undefined)
+        return config.baseUrl;
+    let resolved;
+    try {
+        resolved = await config.tenantOrigin(ctx);
+    }
+    catch (err) {
+        onFallback(`tenantOrigin threw (${err instanceof Error ? err.name : typeof err})`);
+        return config.baseUrl;
+    }
+    if (resolved === null || resolved === undefined)
+        return config.baseUrl;
+    const origin = publicOriginOf(resolved);
+    if (origin === undefined || !isUsableTenantOrigin(origin, config.baseUrl)) {
+        onFallback("tenantOrigin returned no usable https origin");
+        return config.baseUrl;
+    }
+    return origin;
+}
+// Undefined means "no link": without a blind-index key an address opt-out could never be
+// matched again, and a mail without a link is better than a failed send.
+export async function buildUnsubscribeUrl(config, origin, recipient, scope) {
+    if (recipient.kind === "address" && hashUnsubscribeAddress(recipient.address) === undefined) {
+        return undefined;
+    }
+    const token = recipient.kind === "user"
+        ? await signUnsubscribeToken({ ...scope, userId: recipient.userId }, config.secret)
+        : await signAddressUnsubscribeToken({ ...scope, address: recipient.address }, config.secret);
+    return `${origin}${DELIVERY_UNSUBSCRIBE_PATH}?token=${encodeURIComponent(token)}`;
+}

package/dist/delivery/unsubscribe-page-strings.d.ts

@@ -0,0 +1,11 @@
+export declare const UNSUBSCRIBE_PAGE_EN: {
+    readonly "mail.unsubscribe.confirmTitle": "Unsubscribe";
+    readonly "mail.unsubscribe.confirmQuestion": "Unsubscribe from these emails?";
+    readonly "mail.unsubscribe.confirmButton": "Unsubscribe";
+    readonly "mail.unsubscribe.doneTitle": "Unsubscribed";
+    readonly "mail.unsubscribe.doneMessage": "You have been unsubscribed.";
+    readonly "mail.unsubscribe.undoButton": "Undo";
+    readonly "mail.unsubscribe.resubscribedTitle": "Subscribed again";
+    readonly "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.";
+    readonly "mail.unsubscribe.failed": "That did not work. Please try again later.";
+};

package/dist/delivery/unsubscribe-page-strings.js

@@ -0,0 +1,15 @@
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+// The pages behind a mailed unsubscribe link speak the mail's language, so their texts live in
+// the mail translations: English here, other languages in the locale packages.
+export const UNSUBSCRIBE_PAGE_EN = {
+    "mail.unsubscribe.confirmTitle": "Unsubscribe",
+    "mail.unsubscribe.confirmQuestion": "Unsubscribe from these emails?",
+    "mail.unsubscribe.confirmButton": "Unsubscribe",
+    "mail.unsubscribe.doneTitle": "Unsubscribed",
+    "mail.unsubscribe.doneMessage": "You have been unsubscribed.",
+    "mail.unsubscribe.undoButton": "Undo",
+    "mail.unsubscribe.resubscribedTitle": "Subscribed again",
+    "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
+    "mail.unsubscribe.failed": "That did not work. Please try again later.",
+};
+registerMailTranslations("en", UNSUBSCRIBE_PAGE_EN);

package/dist/delivery/unsubscribe.d.ts

@@ -1,16 +1,19 @@
 import { type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import "./unsubscribe-page-strings.js";
 export type UnsubscribeTokenPayload = {
     readonly userId: string;
     readonly tenantId: TenantId;
     readonly notificationType: string;
     readonly channel: string;
+    readonly locale?: string | undefined;
 };
 export type AddressUnsubscribeTokenPayload = {
     readonly tenantId: TenantId;
     readonly address: string;
     readonly notificationType: string;
     readonly channel: string;
+    readonly locale?: string | undefined;
 };
 /**
  * `secret` must be a value dedicated to unsubscribe-token signing — do NOT

package/dist/delivery/unsubscribe.js

@@ -1,10 +1,18 @@
 import { ExtraRouteRejection, signatureRoute, } from "@cosmicdrift/kumiko-framework/api";
+import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
 import * as z from "zod";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { DELIVERY_RESUBSCRIBE_PATH, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, } from "./constants.js";
+import "./unsubscribe-page-strings.js";
+// The mail's locale, so the pages behind the link speak the mail's language. Optional: links
+// signed before the claim existed keep verifying and fall back to English.
+const localeClaimSchema = z
+    .string()
+    .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
+    .optional();
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
 //
@@ -19,6 +27,7 @@ const unsubscribeJwtPayloadSchema = z.object({
     tenantId: z.string().min(1),
     notificationType: z.string().min(1),
     channel: z.string().min(1),
+    locale: localeClaimSchema,
 });
 // Address-token payload. `sub` and `addressHash` are the same value (the
 // subject claim IS the blind-index hash) — kept as two fields because the
@@ -31,6 +40,7 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
     notificationType: z.string().min(1),
     channel: z.string().min(1),
     addressHash: z.string().min(1),
+    locale: localeClaimSchema,
 });
 const UNSUBSCRIBE_EXPIRY = "7d";
 const RESUBSCRIBE_EXPIRY = "1h";
@@ -42,6 +52,10 @@ function assertUnsubscribeSecret(secret, caller) {
         throw new Error(`${caller}: secret must be ≥${MIN_UNSUBSCRIBE_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`);
     }
 }
+// An unusable locale is left out instead of failing the send; the pages then fall back to English.
+function localeClaim(locale) {
+    return locale !== undefined && localeClaimSchema.safeParse(locale).success ? { locale } : {};
+}
 const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
     error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 };
@@ -52,6 +66,7 @@ export async function signUnsubscribeToken(payload, secret) {
         tenantId: payload.tenantId,
         notificationType: payload.notificationType,
         channel: payload.channel,
+        ...localeClaim(payload.locale),
     })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(String(payload.userId))
@@ -80,6 +95,7 @@ export async function signAddressUnsubscribeToken(payload, secret) {
         channel: payload.channel,
         addressHash,
         kind: "address",
+        ...localeClaim(payload.locale),
     })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(addressHash)
@@ -104,6 +120,7 @@ async function signResubscribeToken(verified, encodedSecret) {
         tenantId: verified.tenantId,
         notificationType: verified.notificationType,
         channel: verified.channel,
+        ...localeClaim(verified.locale),
     };
     const jwt = verified.kind === "address"
         ? new jose.SignJWT({
@@ -154,6 +171,7 @@ async function verifyUnsubscribeToken(token, encodedSecret, purpose) {
                 addressHash: parsed.addressHash,
                 notificationType: parsed.notificationType,
                 channel: parsed.channel,
+                locale: parsed.locale,
             };
         }
         const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
@@ -169,6 +187,7 @@ async function verifyUnsubscribeToken(token, encodedSecret, purpose) {
             userId: parsed.sub,
             notificationType: parsed.notificationType,
             channel: parsed.channel,
+            locale: parsed.locale,
         };
     }
     catch (err) {
@@ -228,39 +247,50 @@ async function dispatchResubscribeWrite(verified, deps) {
         return "success";
     return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
 }
-function confirmationPage(token) {
+function pageLocale(locale) {
+    return resolveMailLocale(locale ?? "en");
+}
+function htmlPage(locale, title, bodyHtml) {
     return `<!doctype html>
-<html>
+<html lang="${escapeHtmlAttr(locale)}">
 <head>
 <meta charset="utf-8">
 <meta name="robots" content="noindex">
-<title>Unsubscribe</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtmlAttr(title)}</title>
 </head>
 <body>
-<p>Unsubscribe from these emails?</p>
-<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
-<button type="submit">Unsubscribe</button>
-</form>
+${bodyHtml}
 </body>
 </html>`;
 }
-function unsubscribedPage(resubscribeToken) {
-    return `<!doctype html>
-<html>
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<title>Unsubscribed</title>
-</head>
-<body>
-<p>You have been unsubscribed.</p>
+function confirmationPage(token, locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.confirmTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
+</form>`);
+}
+function unsubscribedPage(resubscribeToken, locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.doneTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>
 <form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
 <input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
-<button type="submit">Undo</button>
-</form>
-</body>
-</html>`;
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
+</form>`);
+}
+function resubscribedPage(locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.resubscribedTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`);
+}
+function failedPage(locale) {
+    const lang = pageLocale(locale);
+    const message = mailT(lang, "mail.unsubscribe.failed");
+    return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+}
+function isFormRequest(contentType) {
+    return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
 // One-click clients put the token in the query string; only the
 // confirmation-page form submits it in the body.
@@ -304,10 +334,10 @@ export function createUnsubscribeRoutes(options) {
             if (!token) {
                 throw new ExtraRouteRejection(400, UNSUBSCRIBE_TOKEN_INVALID_BODY, "missing unsubscribe token");
             }
-            await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-            return { token };
+            const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
+            return { token, locale: verified.locale };
         },
-        handler: async (c, { token }) => c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+        handler: async (c, { token, locale }) => c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
     });
     const writeRoute = signatureRoute({
         method: "POST",
@@ -320,11 +350,9 @@ export function createUnsubscribeRoutes(options) {
             // (e.g. events-table missing, DB down) behind a misleading 400.
             const succeeded = await dispatchUnsubscribeWrite(verified, deps);
             if (!succeeded) {
-                return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
+                return c.html(failedPage(verified.locale), 500, { "Cache-Control": "no-store" });
             }
-            return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
-                "Cache-Control": "no-store",
-            });
+            return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret), verified.locale), 200, { "Cache-Control": "no-store" });
         },
     });
     // Undo direction: token only from the JSON/form body, never the query
@@ -337,6 +365,14 @@ export function createUnsubscribeRoutes(options) {
         verify: async (request) => verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
         handler: async (c, verified, deps) => {
             const outcome = await dispatchResubscribeWrite(verified, deps);
+            // The undo button on the unsubscribed page posts a form; a browser should land on a page.
+            if (isFormRequest(c.req.header("content-type"))) {
+                return outcome === "success"
+                    ? c.html(resubscribedPage(verified.locale), 200, { "Cache-Control": "no-store" })
+                    : c.html(failedPage(verified.locale), outcome === "limit_reached" ? 409 : 500, {
+                        "Cache-Control": "no-store",
+                    });
+            }
             if (outcome === "limit_reached") {
                 return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
                     "Cache-Control": "no-store",

package/dist/derivatives-sharp/feature.js

@@ -9,7 +9,7 @@ export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("file-derivatives");
+    r.requires({ features: ["file-derivatives"] });
     const plugin = { render: renderImage };
     r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
 });

package/dist/document-ingest-foundation/feature.js

@@ -90,8 +90,8 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
     });
     // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
     // tenant-subject ciphertext and needs the destroy hook below.
-    r.requires("config", "tenant-lifecycle");
-    r.entity("documentExtract", documentExtractEntity);
+    r.requires({ features: ["config", "tenant-lifecycle"] });
+    r.entity({ name: "documentExtract", ...documentExtractEntity });
     r.useExtension(EXT_TENANT_DATA, "documentExtract", {
         destroy: documentExtractTenantDestroyHook,
     });

package/dist/file-derivatives/feature.js

@@ -53,12 +53,12 @@ export function createFileDerivativesFeature(opts = {}) {
         });
         // Needs a storage provider to read the original + write the variant —
         // without file-foundation there's nothing to derive from or write to.
-        r.requires("file-foundation");
+        r.requires({ features: ["file-foundation"] });
         // variant() reads fileRefsTable, which "files" (not file-foundation)
         // owns — without this, mounting file-derivatives + file-foundation
         // alone boots fine but fails at request-time with a SQL error the first
         // time variant() runs.
-        r.requires("files");
+        r.requires({ features: ["files"] });
         r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
             onRegister: () => {
                 // No side-effects at register-time — resolution (exact MIME match,
@@ -103,7 +103,7 @@ export function createFileDerivativesFeature(opts = {}) {
                 // tenant's public variants from staying reachable — require the
                 // dependency so a missing mount fails boot, not the tenant check
                 // silently no-op-ing at request time.
-                r.requires("tenant");
+                r.requires({ features: ["tenant"] });
                 r.queryHandler(publicVariantByFileRefQuery);
             }
             r.httpRoute({

package/dist/file-foundation/feature.js

@@ -27,7 +27,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("config");
+    r.requires({ features: ["config"] });
     r.extendsRegistrar(EXT_FILE_PROVIDER, {
         onRegister: () => {
             // No side-effects at register-time — registry stores the usage,

package/dist/file-provider-inmemory/feature.js

@@ -49,10 +49,10 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    // Kein r.requires("config") + kein r.requires("secrets") — der
+    // Kein requires auf "config" oder "secrets" — der
     // In-Memory-Provider hat keine Config + kein Secret. Nur die
     // file-foundation muss da sein (Plugin-extension-point).
-    r.requires("file-foundation");
+    r.requires({ features: ["file-foundation"] });
     const plugin = {
         build: async (_ctx, tenantId) => {
             // Returnt den per-tenant Storage. Identitätsstabil zwischen calls

package/dist/file-provider-s3/feature.js

@@ -32,9 +32,9 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("config");
-    r.requires("secrets");
-    r.requires("file-foundation");
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["secrets"] });
+    r.requires({ features: ["file-foundation"] });
     const secretAccessKey = r.secret("s3.secretAccessKey", {
         label: { en: "S3 secret access key" },
         hint: {

package/dist/file-provider-s3-env/feature.js

@@ -32,10 +32,10 @@ export const fileProviderS3EnvFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    // No r.requires("config") / r.requires("secrets") — credentials come from
+    // No requires on "config" or "secrets" — credentials come from
     // env, not the per-tenant config + secrets store. Only the file-foundation
     // plugin-extension-point must be mounted.
-    r.requires("file-foundation");
+    r.requires({ features: ["file-foundation"] });
     const plugin = {
         // tenantId ignored: one shared bucket serves all tenants (isolation via
         // tenant-prefixed / UUID keys). Built fresh per call like file-provider-s3;

package/dist/files-tenant-data/index.js

@@ -23,7 +23,7 @@ export function createFilesTenantDataFeature() {
             category: "compliance",
             recommended: false,
         });
-        r.requires("tenant-lifecycle");
+        r.requires({ features: ["tenant-lifecycle"] });
         r.optionalRequires("files");
         r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy: fileRefTenantDestroyHook });
         r.useExtension(EXT_STORAGE_PROVIDER, "fileRef", { destroyTenant: fileRefStorageDestroyHook });

package/dist/folders/feature.js

@@ -31,8 +31,8 @@ function registerFolders(r, access, toggleable, ownership, parents) {
     if (toggleable !== undefined)
         r.toggleable(toggleable);
     const folderAssignmentEntity = createFolderAssignmentEntity(ownership, parents);
-    r.entity("folder", folderEntity);
-    r.entity("folder-assignment", folderAssignmentEntity);
+    r.entity({ name: "folder", ...folderEntity });
+    r.entity({ name: "folder-assignment", ...folderAssignmentEntity });
     // Folder catalog — plain CRUD, no custom logic. update is rename (and, in a
     // later stage, reparent: it accepts changes.parentId, optimistic-locked).
     r.writeHandler(defineEntityCreateHandler("folder", folderEntity, {

package/dist/folders-user-data/index.js

@@ -11,7 +11,7 @@ export const foldersUserDataFeature = defineFeature("folders-user-data", (r) =>
     // OPTIONAL: if it's mounted toggleable(default=false) (e.g. per-tenant via
     // tier), a hard r.requires would throw an "effectively disabled" boot
     // warning even though the folder entities exist and the hooks work fine.
-    r.requires("user-data-rights");
+    r.requires({ features: ["user-data-rights"] });
     r.optionalRequires("folders");
     r.useExtension(EXT_USER_DATA, "folder", {
         export: folderExportHook,

package/dist/form-draft/feature.js

@@ -23,11 +23,11 @@ function registerFormDraft(r) {
     // config is optional: the retention-days key only resolves when the
     // config feature is mounted (ctx.configResolver present) — the cleanup
     // job already falls back to FORM_DRAFT_DEFAULT_RETENTION_DAYS otherwise
-    // (see handlers/cleanup.job.ts). A hard r.requires("config") would break
+    // (see handlers/cleanup.job.ts). A hard r.requires({ features: ["config"] }) would break
     // every app that mounts form-draft without config, which is a breaking
     // change no minor/patch release should introduce silently.
     r.optionalRequires("config");
-    r.entity("form-draft", formDraftEntity);
+    r.entity({ name: "form-draft", ...formDraftEntity });
     r.writeHandler(saveDraftWrite);
     r.writeHandler(discardDraftWrite);
     r.queryHandler(getDraftQuery);

package/dist/form-draft-user-data/index.js

@@ -8,7 +8,7 @@ import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engi
 import { formDraftDeleteHook, formDraftExportHook } from "./hooks.js";
 export const formDraftUserDataFeature = defineFeature("form-draft-user-data", (r) => {
     r.describe("GDPR (Art. 20 export / Art. 17 erasure) coverage for the `form-draft` feature's `form-draft` entity. Mounts the EXT_USER_DATA export hook so a user's saved drafts are included in the user-data export bundle, and a delete hook that physically removes the user's own draft rows on forget. Kept separate from `form-draft` so form-draft consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `form-draft`.");
-    r.requires("user-data-rights");
+    r.requires({ features: ["user-data-rights"] });
     r.optionalRequires("form-draft");
     r.useExtension(EXT_USER_DATA, "form-draft", {
         export: formDraftExportHook,

package/dist/inbound-mail-foundation/connect-routes.d.ts

@@ -1,5 +1,6 @@
 import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import { type OAuthAccessTokenManager } from "./oauth-access-token.js";
+import type { InboundMailContext } from "./types.js";
 export type InboundMailConnectRoutesOptions = {
     /** HMAC-secret for the state param (deploy-time env — `scope:"system"`
      *  secrets don't exist in secrets-v1). */
@@ -21,6 +22,8 @@ export type InboundMailConnectRoutesOptions = {
      *  lock and primes the access-token cache from the code exchange. Omitted
      *  → plain secret write, no cache priming. */
     readonly oauthTokens?: OAuthAccessTokenManager;
+    /** Handed to the provider plugin's context (`InboundMailContext.metricsFor`). */
+    readonly metricsFor?: InboundMailContext["metricsFor"];
 };
 /** Builds the `entry:"user"`/`entry:"signature"` extraRoute pair. Mount via
  *  `extraRoutes: createInboundMailConnectRoutes(options)`. */

package/dist/inbound-mail-foundation/connect-routes.js

@@ -80,7 +80,12 @@ export function createInboundMailConnectRoutes(options) {
             if (!deps.secrets) {
                 return errorJson(c, 500, "secrets_context_missing", `${INBOUND_MAIL_FOUNDATION_FEATURE}: no secrets context wired for the oauth callback route — the refresh token cannot be persisted`);
             }
-            const providerCtx = { registry: deps.registry, secrets: deps.secrets, config: undefined };
+            const providerCtx = {
+                registry: deps.registry,
+                secrets: deps.secrets,
+                config: undefined,
+                ...(options.metricsFor && { metricsFor: options.metricsFor }),
+            };
             let plugin;
             try {
                 plugin = resolveInboundProviderForKey(providerCtx, state.providerKey);

package/dist/inbound-mail-foundation/feature.js

@@ -62,7 +62,7 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
         recommended: false,
     });
     // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
-    r.requires("tenant-lifecycle");
+    r.requires({ features: ["tenant-lifecycle"] });
     // 5 fine-grained domain-events (Payload-Schemas: events.ts).
     // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
     // "displayName" stays plaintext (often the mailbox owner's real name for

package/dist/inbound-mail-foundation/types.d.ts

@@ -1,20 +1,25 @@
 import type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "./constants.js";
 /**
- * Slim-Context für Provider-Plugins.
+ * Slim context for provider plugins.
  *
- * **Felder:**
- *   config   — tenant-config-reads (host/port/... der Plugins)
- *   registry — extension-Lookup in der Factory (nicht plugin-intern)
- *   secrets  — tenant-secret-reads (IMAP-Passwort, OAuth-Refresh-Token)
- *   _userId  — Audit-Identity für secret-reads. Handler-Pfad: dispatcher
- *              setzt Caller-User-ID; Worker-Pfad: System-Identity.
+ * **Fields:**
+ *   config   — tenant config reads (host/port/... of the plugins)
+ *   registry — extension lookup in the factory (not plugin-internal)
+ *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
+ *   _userId  — audit identity for secret reads. Handler path: the dispatcher
+ *              sets the caller user ID; worker path: system identity.
+ *   metricsFor — metrics handle of a feature by name, same behavior as
+ *              HandlerContext.metricsFor: unregistered metrics are a silent
+ *              no-op instead of a throw.
  */
 export type InboundMailContext = {
     readonly config?: ConfigAccessor;
     readonly registry?: Registry;
     readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
     readonly _userId?: string | undefined;
+    readonly metricsFor?: (featureName: string) => MetricsHandle;
 };
 /**
  * Plaintext-Sicht auf ein verbundenes Postfach, wie Provider sie sehen.
@@ -141,6 +146,11 @@ export type InboundMailProviderPlugin = {
          *  whose provider declares `oauth` (authMethod oauth/xoauth2). Absent
          *  for password accounts and providers without an oauth flow. */
         readonly accessToken?: string;
+        /** Batch lookup of the provider message ids not yet ingested for this
+         *  account (committed seen anchors, one query per call). Call it after
+         *  the listing/delta page and download MIME only for the returned ids.
+         *  Ingest dedup stays the correctness anchor; this only saves downloads. */
+        readonly filterUnknownMessageIds?: (providerMessageIds: readonly string[]) => Promise<ReadonlySet<string>>;
     }) => Promise<InboundFetchResult>;
     /** Nur OAuth-Provider. */
     readonly oauth?: InboundOAuthFlow;

package/dist/inbound-mail-foundation/watch-supervisor.js

@@ -14,7 +14,7 @@
 // app owner still wires the supervisor in bin/server.ts:
 //
 //   const supervisor = createInboundMailSupervisor({
-//     providerCtx: { registry: deps.registry, secrets },
+//     providerCtx: { registry: deps.registry, secrets, metricsFor: deps.metricsFor },
 //     db,
 //     dispatchWrite: ({ handlerQn, payload, tenantId }) =>
 //       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
@@ -48,7 +48,7 @@ import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/ku
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { InboundMailAccountStatuses, InboundMailFoundationHandlers } from "./constants.js";
-import { MAIL_ACCOUNT_PII_FIELDS, syncCursorTable } from "./entities.js";
+import { MAIL_ACCOUNT_PII_FIELDS, seenMessageTable, syncCursorTable } from "./entities.js";
 import { createOAuthAccessTokenManager, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 import { mailAccountsProjectionTable } from "./projection.js";
 import { resolveInboundProviderForAccount } from "./provider-factory.js";
@@ -255,6 +255,19 @@ export function createInboundMailSupervisor(deps) {
     // ---------------------------------------------------------------
     // Poll (Reconciliation).
     // ---------------------------------------------------------------
+    function unknownMessageIdsFilterFor(account) {
+        return async (providerMessageIds) => {
+            if (providerMessageIds.length === 0)
+                return new Set();
+            const seen = await selectMany(deps.db, seenMessageTable, {
+                tenantId: account.tenantId,
+                accountId: account.id,
+                providerMessageId: { in: providerMessageIds },
+            }, { fields: ["providerMessageId"] });
+            const seenIds = new Set(seen.map((row) => row.providerMessageId));
+            return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
+        };
+    }
     async function pollAccount(account, plugin) {
         let cursor = await loadCursor(account.id);
         let budget = maxMessagesPerPoll;
@@ -265,6 +278,7 @@ export function createInboundMailSupervisor(deps) {
                 const result = await plugin.fetch(deps.providerCtx, account, cursor, {
                     backfillWindowDays,
                     maxMessages: budget,
+                    filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
                     ...(accessToken !== undefined && { accessToken }),
                 });
                 await ingestBatch(account, result.messages, JSON.stringify(result.nextCursor));

package/dist/inbound-provider-imap/feature.js

@@ -224,8 +224,8 @@ export const inboundProviderImapFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "notifications",
         recommended: false,
     });
-    r.requires("inbound-mail-foundation");
-    r.requires("secrets");
+    r.requires({ features: ["inbound-mail-foundation"] });
+    r.requires({ features: ["secrets"] });
     r.envSchema(mailAllowedPrivateHostsEnvSchema);
     r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
 });

package/dist/inbound-provider-inmemory/feature.js

@@ -110,6 +110,6 @@ export const inboundProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) =>
         category: "notifications",
         recommended: false,
     });
-    r.requires("inbound-mail-foundation");
+    r.requires({ features: ["inbound-mail-foundation"] });
     r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, inMemoryInboundMailPlugin);
 });