@cosmicdrift/kumiko-bundled-features 0.366.0 → 0.368.0

package/dist/delivery/delivery-service.js

@@ -1,19 +1,19 @@
 import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { assertNotificationVariables, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { assertNotificationVariables, bridgeStub, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { assertNotifyTargetsOwnTenant, createEscapeHatchReporter, } from "@cosmicdrift/kumiko-framework/pipeline";
-import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { fileContextFromResolver } from "../file-foundation/index.js";
 import { redactErrorText } from "../shared/index.js";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
-import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank, } from "./constants.js";
+import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank, EMAIL_CHANNEL_NAME, } from "./constants.js";
 import { addressOptOutKey, selectOptedOutAddresses, } from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
 import { notificationTypeNames } from "./notification-type-aliases.js";
 import { isDeliveryChannelPlugin, } from "./types.js";
+import { buildUnsubscribeUrl, unsubscribeLinkOrigin, } from "./unsubscribe-link.js";
 export function redactedMessageOf(err) {
     return redactErrorText(err instanceof Error ? err.message : String(err));
 }
@@ -28,7 +28,7 @@ export function collectChannels(registry) {
     });
 }
 export function createDeliveryService(options) {
-    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, filesForTenant, tenantConfigFor, escapeHatchAuditSink, log, } = options;
+    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, filesForTenant, tenantConfigFor, escapeHatchAuditSink, log, unsubscribeLinks, } = options;
     const idemRedis = idempotencyRedis ?? rateLimit?.redis;
     const logError = createFallbackLogger("delivery", log);
     // Rate limit check: atomic INCR + TTL + over-limit rollback via server-side
@@ -124,17 +124,27 @@ export function createDeliveryService(options) {
         // path a cross-tenant read the dispatcher never allows. Cross-tenant reach only
         // exists through the grant-carrying systemDb view below.
         const isSystem = registry.isHandlerSystemScoped(tenantUserIdsQuery);
-        const tenantDb = createTenantDb(run.db, tenantId, "tenant", undefined, undefined, undefined, {
-            report,
+        const tenantDb = createTenantDb({
+            db: run.db,
+            tenantId,
+            mode: "tenant",
+            grants: {
+                report,
+            },
         });
         // The dispatcher grants a systemScope handler's ctx.systemDb.unsafeRaw() ungated —
         // the grant comes from the handler's own r.systemScope() registration, not from this
         // caller. Only the systemDb view's own source TenantDb carries the grant, so it
         // can't leak onto ctx.db.
         const systemDbSourceTenantDb = isSystem
-            ? createTenantDb(run.db, tenantId, "system", undefined, undefined, undefined, {
-                report,
-                unsafeRaw: { reason: `r.systemScope() handler "${tenantUserIdsQuery}"` },
+            ? createTenantDb({
+                db: run.db,
+                tenantId,
+                mode: "system",
+                grants: {
+                    report,
+                    unsafeRaw: { reason: `r.systemScope() handler "${tenantUserIdsQuery}"` },
+                },
             })
             : undefined;
         // Hand-built context, not routed through the dispatcher — this needs both
@@ -255,6 +265,31 @@ export function createDeliveryService(options) {
             });
         }
     }
+    // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
+    // context, never from the notification data.
+    async function withUnsubscribeUrl(message, channelName, recipient, channelCtx) {
+        if (!unsubscribeLinks || channelName !== EMAIL_CHANNEL_NAME)
+            return message;
+        if (registry.getAllNotifications().get(message.notificationType)?.unsubscribe !== true) {
+            return message;
+        }
+        const supplied = message.data?.["unsubscribeUrl"];
+        if (typeof supplied === "string" && supplied !== "")
+            return message;
+        const origin = await unsubscribeLinkOrigin(unsubscribeLinks, channelCtx, (reason) => logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
+            tenantId: channelCtx.tenantId,
+            notificationType: message.notificationType,
+        }));
+        const unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
+            tenantId: channelCtx.tenantId,
+            notificationType: message.notificationType,
+            channel: channelName,
+            locale: message.locale,
+        });
+        return unsubscribeUrl === undefined
+            ? message
+            : { ...message, data: { ...message.data, unsubscribeUrl } };
+    }
     function buildMessage(notificationType, data, channelName, locale) {
         // Look up per-channel template from notification definition
         const notifDef = registry.getAllNotifications().get(notificationType);
@@ -435,7 +470,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message,
+                    message: await withUnsubscribeUrl(message, channel.name, { kind: "user", userId }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId: userId,
@@ -508,7 +543,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message,
+                    message: await withUnsubscribeUrl(message, channel.name, { kind: "address", address }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId,

package/dist/delivery/feature.js

@@ -1,4 +1,4 @@
-import { updateMany, upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany, upsertByPk } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineFeature, i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
 import { ConsumerLagError } from "@cosmicdrift/kumiko-framework/pipeline";
 import { resolveAttemptLogRetentionDays, runAttemptLogRetention } from "./attempt-log-retention.js";
@@ -19,7 +19,7 @@ export function createDeliveryFeature(options) {
     const resolvedAccess = options?.access ?? access.admin;
     const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
     return defineFeature("delivery", (r) => {
-        r.describe('The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app\'s `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message\'s `data.unsubscribeUrl` points at the unsubscribe route.');
+        r.describe("The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.");
         r.uiHints({
             displayLabel: "Notifications \u00b7 Dispatch Core",
             category: "notifications",

package/dist/delivery/handlers/log.query.js

@@ -1,5 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { decodeKeysetCursor, encodeKeysetCursor, } from "@cosmicdrift/kumiko-framework/db";
+import { decodeKeysetCursor, encodeKeysetCursor, selectMany, } from "@cosmicdrift/kumiko-framework/db";
 import { access, definePagedQueryHandler, isDeliveryErrorCode, isUuid, MAX_LIST_LIMIT, SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -30,7 +29,7 @@ function isDeliveryLogSortField(value) {
     return value in DELIVERY_LOG_SORT_COLUMNS;
 }
 // createdAt round-trips through Temporal.Instant (matches how the WHERE
-// builder coerces timestamptz values — see bun-db/query.ts prepareValue);
+// builder coerces timestamptz values — see db/query.ts prepareValue);
 // every other whitelisted column is a plain text column. Keyed by the
 // PHYSICAL column, not the display alias — row only has the DB field names
 // (e.g. notificationType), never the alias (e.g. "type").

package/dist/delivery/handlers/preferences.query.js

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/dist/delivery/handlers/unsubscribe-address.write.d.ts

@@ -1,4 +1,10 @@
 import * as z from "zod";
+export declare const unsubscribeAddressPayloadSchema: z.ZodObject<{
+    addressHash: z.ZodString;
+    notificationType: z.ZodString;
+    channel: z.ZodString;
+}, z.core.$strip>;
+export type UnsubscribeAddressPayload = z.infer<typeof unsubscribeAddressPayloadSchema>;
 export declare const unsubscribeAddressWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"unsubscribeAddress", z.ZodObject<{
     addressHash: z.ZodString;
     notificationType: z.ZodString;

package/dist/delivery/handlers/unsubscribe-address.write.js

@@ -3,13 +3,16 @@ import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { upsertAddressOptOut } from "../address-opt-out.js";
 import { currentNotificationType } from "../notification-type-aliases.js";
+// Also the payload an app job receives with `trigger: { on: DeliveryHandlers.unsubscribeAddress }`
+// after a committed address opt-out (the tenant is the job's `ctx.triggeredBy.tenantId`).
+export const unsubscribeAddressPayloadSchema = z.object({
+    addressHash: z.string().min(1),
+    notificationType: z.string().min(1),
+    channel: z.string().min(1),
+});
 export const unsubscribeAddressWrite = defineWriteHandler({
     name: "unsubscribeAddress",
-    schema: z.object({
-        addressHash: z.string().min(1),
-        notificationType: z.string().min(1),
-        channel: z.string().min(1),
-    }),
+    schema: unsubscribeAddressPayloadSchema,
     access: { roles: access.systemAdmin },
     // Only reachable via createUnsubscribeRoutes' POST dispatchSystemWrite, once
     // verify() has already proven the address-token signature — not a surface

package/dist/delivery/index.d.ts

@@ -9,8 +9,11 @@ export type { DeliveryStatusValue } from "./constants.js";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
+export { type UnsubscribeAddressPayload, unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.js";
 export { type AttachmentOrigin, type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type RenderedMessage, } from "./types.js";
 export { type AddressUnsubscribeTokenPayload, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, signAddressUnsubscribeToken, signUnsubscribeToken, type UnsubscribeRouteOptions, type UnsubscribeTokenPayload, } from "./unsubscribe.js";
+export type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/dist/delivery/index.js

@@ -8,8 +8,10 @@ export { chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget,
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";
+export { unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { createDeliveryTestContext } from "./testing.js";
 export { isDeliveryChannelPlugin, } from "./types.js";
 export { createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, signAddressUnsubscribeToken, signUnsubscribeToken, } from "./unsubscribe.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/dist/delivery/testing.d.ts

@@ -8,6 +8,7 @@ import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js";
 import type { DeliveryService } from "./types.js";
+import type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
 export type CreateDeliveryTestContextOptions = {
     readonly tenantUserIdsQuery?: string;
     readonly rateLimit?: RateLimitConfig;
@@ -19,6 +20,7 @@ export type CreateDeliveryTestContextOptions = {
     readonly idempotencyRedis?: Redis;
     readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
     readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
+    readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 /**
  * Helper for setupTestStack: creates a DeliveryService + _notifyFactory for the test context.

package/dist/delivery/types.d.ts

@@ -1,6 +1,6 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { DeliveryErrorCode, NotifyDeliveryStatus, NotifyDispatched, NotifyJobDispatcher, NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigAccessor, DeliveryErrorCode, NotifyDeliveryStatus, NotifyDispatched, NotifyJobDispatcher, NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { MailPayload, RenderedTemplateRef } from "../renderer-foundation/index.js";
@@ -23,6 +23,7 @@ export type ChannelContext = {
     readonly sseBroker: SseBroker | undefined;
     readonly tenantId: TenantId;
     readonly secrets?: SecretsContext | undefined;
+    readonly config?: ConfigAccessor | undefined;
     readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
     readonly readAttachment?: (ref: EmailAttachmentRef, origin?: AttachmentOrigin) => Promise<{
         readonly content: Uint8Array;

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/delivery/upsert-preference.js

@@ -12,8 +12,7 @@
 // loser's create() comes back as a `version_conflict` failure; re-lookup and
 // fall through to update, or no-op if the winner already set the target
 // `enabled` state.
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, fetchOne, } from "@cosmicdrift/kumiko-framework/db";
 import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
 import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.js";
 const executor = createEventStoreExecutor(notificationPreferencesTable, notificationPreferenceEntity, { entityName: "notification-preference" });

package/dist/derivatives-sharp/feature.d.ts

@@ -1,3 +1,7 @@
+export declare function createDerivativesSharpFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createDerivativesSharpFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const derivativesSharpFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/derivatives-sharp/feature.js

@@ -2,14 +2,18 @@
 import { defineFeature, EXT_DERIVATIVE_RENDERER } from "@cosmicdrift/kumiko-framework/engine";
 import { renderImage } from "./render.js";
 const FEATURE_NAME = "derivatives-sharp";
-export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
-    r.describe("Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.");
-    r.uiHints({
-        displayLabel: "File Derivatives · Sharp",
-        category: "storage",
-        recommended: false,
-    });
-    r.requires({ features: ["file-derivatives"] });
-    const plugin = { render: renderImage };
-    r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
-});
+export function createDerivativesSharpFeature() {
+    return defineFeature(FEATURE_NAME, (r) => {
+        r.describe("Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.");
+        r.uiHints({
+            displayLabel: "File Derivatives · Sharp",
+            category: "storage",
+            recommended: false,
+        });
+        r.requires({ features: ["file-derivatives"] });
+        const plugin = { render: renderImage };
+        r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
+    }, { dedupeOptions: {} });
+}
+/** @deprecated Use createDerivativesSharpFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const derivativesSharpFeature = createDerivativesSharpFeature();

package/dist/derivatives-sharp/index.d.ts

@@ -1,2 +1,2 @@
-export { derivativesSharpFeature } from "./feature.js";
+export { createDerivativesSharpFeature, derivativesSharpFeature } from "./feature.js";
 export { imageMetadata } from "./render.js";