@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/data-retention/schema/tenant-retention-override.ts

@@ -0,0 +1,50 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+//
+// Per (tenantId, entityName) eine optionale Override-Config die das
+// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
+//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
+//   - Pilot-Tenant der länger speichert für Test
+//   - Branchenspezifische verkürzte Fristen
+//
+// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+//
+// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
+// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+//
+// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
+// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+export const tenantRetentionOverrideEntity = createEntity({
+  table: "read_tenant_retention_overrides",
+  fields: {
+    entityName: createTextField({
+      required: true,
+      maxLength: 100,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    config: createLongTextField({
+      required: true,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    reason: createTextField({
+      required: true,
+      maxLength: 500,
+      personal: false,
+      reason: "is_business_data",
+    }),
+  },
+  indexes: [{ unique: true, columns: ["tenantId", "entityName"] }],
+});
+
+export const tenantRetentionOverrideTable = buildEntityTable(
+  "tenantRetentionOverride",
+  tenantRetentionOverrideEntity,
+);

package/packages/bundled-features/src/delivery/address-opt-out.ts

@@ -0,0 +1,204 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { computeBlindIndex, configuredBlindIndexKey } from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
+import { DeliveryErrors } from "./public-names.js";
+import { notificationAddressOptOutEntity, notificationAddressOptOutsTable } from "./tables.js";
+
+const executor = createEventStoreExecutor(
+  notificationAddressOptOutsTable,
+  notificationAddressOptOutEntity,
+  { entityName: "notification-address-opt-out" },
+);
+
+// Keyed hash of a recipient address that never had a user account — the
+// plaintext address must never reach the opt-out row or the unsubscribe token.
+// Undefined when no blind-index key is configured: there is nothing to
+// compare against, so callers must treat that as "can't tell".
+export function hashUnsubscribeAddress(address: string): string | undefined {
+  const key = configuredBlindIndexKey();
+  if (key === undefined) return undefined;
+  return computeBlindIndex(key, address.trim().toLowerCase());
+}
+
+export type UpsertAddressOptOutInput = {
+  readonly tenantId: TenantId;
+  readonly addressHash: string;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
+type OptOutLookupRow = { readonly id: string };
+
+async function lookup(
+  db: TenantDb,
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+): Promise<OptOutLookupRow | undefined> {
+  return fetchOne<OptOutLookupRow>(db, notificationAddressOptOutsTable, {
+    tenantId,
+    addressHash,
+    notificationType,
+    channel,
+  });
+}
+
+// One row per (tenant, addressHash, type, channel): mirrors
+// preferenceAggregateId in upsert-preference.ts — concurrent first-time
+// opt-outs collide on the same stream at append, not on the projection's
+// unique index.
+//
+// `generation` picks a distinct deterministic id for the same business key —
+// needed because removeAddressOptOut() hard-deletes the row (no softDelete on
+// this entity, see tables.ts), which leaves generation 0's stream in a
+// deleted state forever (event-store streams are immutable once deleted).
+// A later opt-out for the same address/type/channel must land on a fresh
+// stream instead of colliding with the dead one. Generation 0 keeps the
+// unsuffixed id for backwards-compatibility with rows written before
+// resubscribe existed.
+function addressOptOutAggregateId(
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+  generation: number,
+): string {
+  const base = `${tenantId}|${addressHash}|${notificationType}|${channel}`;
+  return generateDeterministicId(
+    "delivery:notification-address-opt-out",
+    generation === 0 ? base : `${base}|g${generation}`,
+  );
+}
+
+// Hard-cap on generation retries — a version_conflict with no row means the
+// stream at that generation was deleted by a previous resubscribe; this
+// bounds the opt-out/resubscribe ping-pong instead of looping forever on a
+// pathological retry storm.
+const MAX_ADDRESS_OPT_OUT_GENERATIONS = 100;
+
+// Test-only: lets integration tests seed a row at an arbitrary generation
+// (e.g. the last one, to exercise removeAddressOptOut's limit) via the same
+// executor.create seed pattern production code uses, instead of looping
+// upsertAddressOptOut 100 times or writing the table directly.
+export function addressOptOutAggregateIdForTests(
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+  generation: number,
+): string {
+  return addressOptOutAggregateId(tenantId, addressHash, notificationType, channel, generation);
+}
+
+export const MAX_ADDRESS_OPT_OUT_GENERATIONS_FOR_TESTS = MAX_ADDRESS_OPT_OUT_GENERATIONS;
+
+/**
+ * Create-or-noop: opting the same address out twice must not produce a
+ * second row or fail the second click. Resubscribing (removeAddressOptOut)
+ * hard-deletes the row, so a later opt-out probes forward through
+ * generations until it finds one whose stream isn't already dead.
+ */
+export async function upsertAddressOptOut(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertAddressOptOutInput,
+): Promise<WriteResult<UpsertAddressOptOutInput>> {
+  const existing = await lookup(
+    db,
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+  );
+  if (existing) return { isSuccess: true, data: input };
+
+  let lastFailure: WriteResult<UpsertAddressOptOutInput> | undefined;
+  for (let generation = 0; generation < MAX_ADDRESS_OPT_OUT_GENERATIONS; generation++) {
+    const id = addressOptOutAggregateId(
+      input.tenantId,
+      input.addressHash,
+      input.notificationType,
+      input.channel,
+      generation,
+    );
+    const created = await executor.create(
+      {
+        id,
+        addressHash: input.addressHash,
+        notificationType: input.notificationType,
+        channel: input.channel,
+      },
+      actor,
+      db,
+    );
+    if (created.isSuccess) return { isSuccess: true, data: input };
+    if (created.error.code !== "version_conflict") return created;
+
+    // Race-fallback: another request's create already won this generation's
+    // id between our lookup and this create — the existing row already IS
+    // the opt-out, so the race loser just reports success too.
+    const afterRace = await lookup(
+      db,
+      input.tenantId,
+      input.addressHash,
+      input.notificationType,
+      input.channel,
+    );
+    if (afterRace) return { isSuccess: true, data: input };
+
+    // No row after the conflict: this generation's stream was deleted by a
+    // prior resubscribe. Try the next generation instead of failing.
+    lastFailure = created;
+  }
+  return lastFailure ?? { isSuccess: true, data: input };
+}
+
+/**
+ * Resubscribe: hard-deletes the opt-out row so `isAddressOptedOut` reports
+ * false again. Idempotent — no row means the address was never (or is no
+ * longer) opted out, which is already the desired end state.
+ *
+ * Refuses to delete the row sitting at the last available id generation:
+ * unsubscribe must always succeed, and once every generation below the cap
+ * is dead, only a live row at the last generation still guarantees that
+ * (upsertAddressOptOut's existing-row check, no generation loop needed).
+ */
+export async function removeAddressOptOut(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertAddressOptOutInput,
+): Promise<WriteResult<UpsertAddressOptOutInput>> {
+  const existing = await lookup(
+    db,
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+  );
+  if (!existing) return { isSuccess: true, data: input };
+
+  const lastGenerationId = addressOptOutAggregateId(
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+    MAX_ADDRESS_OPT_OUT_GENERATIONS - 1,
+  );
+  if (existing.id === lastGenerationId) {
+    return writeFailure(
+      new ConflictError({
+        message: "resubscribe limit reached: this address must stay opted out",
+        i18nKey: "delivery.errors.resubscribeLimitReached",
+        details: { reason: DeliveryErrors.resubscribeLimitReached },
+      }),
+    );
+  }
+
+  const deleted = await executor.delete({ id: existing.id }, actor, db);
+  if (!deleted.isSuccess) return deleted;
+  return { isSuccess: true, data: input };
+}

package/packages/bundled-features/src/delivery/attempt-log.ts

@@ -0,0 +1,66 @@
+// Shared delivery-attempt event writer. Used both synchronously by the
+// delivery-service (inline channels, skips) and asynchronously by the
+// delivery.render / delivery.send job handlers — keeping the append +
+// inline-projection logic in one place so both paths produce identical rows.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { append, getStreamVersion } from "@cosmicdrift/kumiko-framework/event-store";
+import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { DELIVERY_ATTEMPT_EVENT } from "./constants.js";
+import { deliveryAttemptSchema } from "./events.js";
+import type { DeliveryLogEntry } from "./types.js";
+
+// Shared append + inline-projection write (low-level append() does not
+// auto-fire projections — only the dispatcher/executor paths do).
+async function writeAttemptEvent(
+  db: DbConnection,
+  registry: Registry,
+  attemptId: string,
+  expectedVersion: number,
+  entry: DeliveryLogEntry,
+): Promise<void> {
+  const { tenantId, ...rest } = entry;
+  // Schema-parse to match ctx.appendEvent's guarantee: a payload drift between
+  // service/job + feature-registration fails loudly here instead of landing on
+  // the events-table and crashing a consumer later.
+  const payload = deliveryAttemptSchema.parse(rest);
+  const stored = await append(db, {
+    aggregateId: attemptId,
+    aggregateType: "deliveryAttempt",
+    tenantId,
+    expectedVersion,
+    type: DELIVERY_ATTEMPT_EVENT,
+    payload,
+    metadata: { userId: "system" },
+  });
+  await runProjectionsForEvent(stored, registry, db);
+}
+
+// Append one delivery-attempt event to `attemptId`'s stream — for the
+// MULTI-EVENT path (queued → sent/failed follow-ups), where the stream may
+// already carry the "queued" event and the real current version must be
+// looked up.
+export async function appendAttemptEvent(
+  db: DbConnection,
+  registry: Registry,
+  attemptId: string,
+  entry: DeliveryLogEntry,
+): Promise<void> {
+  const expectedVersion = await getStreamVersion(db, attemptId, entry.tenantId);
+  await writeAttemptEvent(db, registry, attemptId, expectedVersion, entry);
+}
+
+// Single-shot terminal log (inline channels, skips, idempotency dups): a
+// FRESH aggregate id is guaranteed version 0 — skip the getStreamVersion
+// round-trip that appendAttemptEvent needs for its follow-up-event case.
+export async function logAttempt(
+  db: DbConnection,
+  registry: Registry,
+  entry: DeliveryLogEntry,
+): Promise<string> {
+  const attemptId = generateId();
+  await writeAttemptEvent(db, registry, attemptId, 0, entry);
+  return attemptId;
+}

package/packages/bundled-features/src/delivery/changes.json

@@ -0,0 +1,86 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "tenant broadcast recipient query no longer reads across tenants through ctx.db",
+    "detail": "delivery: the `tenantUserIdsQuery` handler of a tenant broadcast now always gets a tenant-filtered `ctx.db` and `ctx.dbOutsideTransaction`, also when it is declared `r.systemScope()`. A systemScope handler could previously read the memberships of every tenant through `ctx.db` and notify users of foreign tenants. Cross-tenant reads stay available through `ctx.systemDb`.",
+    "migration": "No action needed for handlers that resolve recipients through `ctx.systemDb`, like `tenant:query:resolveUserIds`. A systemScope handler that read `ctx.db` unfiltered now sees only the broadcast tenant's rows."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "Delivery log paging no longer skips rows tied on the sort value",
+    "detail": "The delivery log query no longer skips rows at a page boundary when the sort column has duplicate values. A toggle flip received while the initial snapshot loads is no longer overwritten by the older DB read. The stale job-run sweep encrypts and updates once per triggering user instead of once per run."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Channel plugin guard validates mode and render",
+    "detail": "Stricter input guards. A delivery channel plugin must declare `mode` as `inline` or `queued` and a function `render`, otherwise boot fails instead of silently dispatching inline. The derivatives-sharp overlay rejects a non-finite `marginPct` before it reaches sharp. A document-ingest provider can no longer register under the reserved name `unknown`, which marks upcast legacy ingest events. The unsubscribe POST route also accepts a JSON body.",
+    "migration": "A delivery channel plugin must now declare `mode` as `\"inline\"` or `\"queued\"` and a function `render`; boot fails otherwise instead of dispatching inline."
+  },
+  {
+    "version": "0.330.0",
+    "type": "improvement",
+    "title": "store_delivery_attempts gets an index on (tenant_id, created_at) (fw#3396)",
+    "detail": "Windowed per-tenant dashboard aggregates over delivery attempts (metrics feature) filter on tenant_id and created_at.",
+    "migration": "Run `kumiko migrate generate` and apply the migration: it adds `store_delivery_attempts_tenant_id_created_at_idx`."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "New POST /api/delivery/resubscribe route undoes an unsubscribe/opt-out",
+    "detail": "createUnsubscribeRoutes now also mounts POST /api/delivery/resubscribe (JSON {token} or form body only, never the query string, to stay safe against mail-client link prefetchers). It accepts the same signed tokens as the unsubscribe routes and re-enables the preference (signed-in user) or removes the address opt-out (no-account recipient). A resubscribed address opt-out is hard-deleted; a later re-opt-out for the same address/type/channel lands on a fresh event-stream generation instead of reviving the deleted one.",
+    "migration": "No action needed: the route is additive and mounted automatically wherever createUnsubscribeRoutes({ secret }) already runs. Sign resubscribe links with the same signUnsubscribeToken/signAddressUnsubscribeToken used for unsubscribe links."
+  },
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "Unsubscribe route splits into a non-writing GET confirmation page and a writing POST (RFC 8058)",
+    "detail": "`createUnsubscribeRoute({ secret })`, which mounted a single `GET` route\nthat wrote the opt-out as a side effect of the request, is replaced by\n`createUnsubscribeRoutes({ secret })`, which returns both routes for the\nsame path: `GET` renders a confirmation page (`<form method=\"post\">`) and\nperforms no write; `POST` performs the write, reading the token from a\nform-urlencoded body first, then the query string as a fallback (so an\nRFC-8058 one-click client that POSTs `token=` only in the URL still works).\nToken verification and error mapping (`400 unsubscribe_token_invalid`) are\nunchanged and shared between both routes.",
+    "migration": "Replace `extraRoutes: [createUnsubscribeRoute({ secret })]` with\n`extraRoutes: [...createUnsubscribeRoutes({ secret })]`.\n\nUnsubscribe links already mailed out before this upgrade now show a\nconfirmation page on click instead of unsubscribing immediately — the\nrecipient must submit the form (or a one-click mail client must POST) to\ncomplete the opt-out. If the app rendered its own confirmation page in\nfront of the old GET link, it can be removed; the framework route now\ncovers that step."
+  },
+  {
+    "version": "0.315.0",
+    "type": "fix",
+    "title": "delivery honors an address opt-out on sends to a user account",
+    "detail": "`deliverToUser` only checked the user's notification preferences, so an\naddress that had been opted out via an address unsubscribe token still got\nmail once it belonged to a user account. It now runs the same check\n`deliverDirect` already applied: when the resolved channel address has a\n`notification-address-opt-out` row for that tenant, notificationType and\nchannel, the attempt is logged as `skipped` / `unsubscribed` with\n`recipientAddress: null`. Critical priority still bypasses it\n(kumiko-framework#3275)."
+  },
+  {
+    "version": "0.315.0",
+    "type": "improvement",
+    "title": "Delivery unsubscribe route is now mountable via extraRoutes",
+    "detail": "`createUnsubscribeRoute` previously returned a raw Hono app that needed a\n`DbConnection` (`{ db, jwtSecret }`) and had to be mounted by hand with\n`stack.app.route(...)`, bypassing the framework's request pipeline. It now\nreturns an `ExtraRouteDefinition` built via `signatureRoute`, taking only\n`{ secret }`, and mounts at the fixed path `GET /api/delivery/unsubscribe?token=`\n(exported as `DELIVERY_UNSUBSCRIBE_PATH`). Mount it with\n`extraRoutes: [createUnsubscribeRoute({ secret: env.UNSUBSCRIBE_SECRET })]`.\n`signUnsubscribeToken` / `signAddressUnsubscribeToken` must sign with the\nsame secret. The secret must be at least 32 characters and must NOT reuse\nthe app's session `JWT_SECRET` — all three entry points fail fast on a\nshort secret.\nThe write itself now goes through two new SystemAdmin-only handlers,\n`delivery:write:unsubscribe-address` and `delivery:write:unsubscribe-user`,\ndispatched via `dispatchSystemWrite` once the route's `verify()` has proven\nthe token's authenticity. An invalid or expired token always responds 400\nwith `{ error: { code: \"unsubscribe_token_invalid\" } }`, never leaking the\nunderlying JWT-library error text.\nNew notification-preference and notification-address-opt-out rows get a\ndeterministic aggregate id derived from (tenant, user or address hash,\nnotificationType, channel), so concurrent clicks on the same link collide\nat the event-store append and converge on one row instead of failing with\na unique or version conflict. Existing rows keep their ids."
+  },
+  {
+    "version": "0.313.0",
+    "type": "breaking",
+    "title": "delivery direct sends to a route address can now be unsubscribed via a signed link",
+    "detail": "ctx.notify(type, { route: { email } }) direct sends had no unsubscribe\npath: only sends to a user account with a notification-preference row\ncould opt out, so a recipient with no account could never stop the mail.\nAdded hashUnsubscribeAddress (keyed blind-index hash of the trimmed,\nlowercased address — the plaintext address never reaches the token or\nthe opt-out table), signAddressUnsubscribeToken (HS256 JWT, issuer\n\"kumiko:unsubscribe\", no expiry — a leaked link can only opt one\naddress out of one notificationType/channel, and there is no signed-in\nflow to request a fresh one), and a new notification-address-opt-out\nevent-sourced entity/table. createUnsubscribeRoute now accepts both the\nexisting user token and the new address token on the same route; the\nexisting signUnsubscribeToken and its JWT shape are unchanged. deliverDirect\nnow skips a channel (logDelivery status \"skipped\", error \"unsubscribed\", recipientAddress null)\nwhen the destination address has an opt-out row for that tenant/\nnotificationType/channel, unless priority is \"critical\" — the same rule\nuser-preference suppression already follows. The lookup is skipped\nentirely when no blind-index key is configured.",
+    "migration": "Run `kumiko migrate generate` to add the notification address opt-out table."
+  },
+  {
+    "version": "0.296.0",
+    "type": "breaking",
+    "title": "delivery requires tenant",
+    "migration": "delivery now declares r.requires(\"tenant\") because its delivery-log screen references tenant:tenant. Stacks that mount delivery must also mount createTenantFeature() (and its config dependency)."
+  },
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "systemScope handlers get a default per-tenant+handler rate limit; delivery:preferences opts out (fw#2861).",
+    "detail": "`delivery` mounts under `r.systemScope()`, so `delivery:write:set-preference`/`delivery:query:log` without their own `rateLimit` now default to `{ per: \"tenant+handler\", limit: 600, windowSeconds: 60 }` once an app has a `RateLimitResolver` configured (framework change, see kumiko-framework changes.json 0.271.0). `delivery:query:preferences` declares `rateLimit: { disabled: true, reason: \"...\" }` — it is a self-scoped read of the caller's own notification preference rows, hit on every page load, and a per-tenant bucket would throttle the whole tenant's page loads instead of just that one handler's traffic."
+  },
+  {
+    "version": "0.208.2",
+    "type": "improvement",
+    "title": "`/delivery-log` is a declarative projectionList screen (#2221).",
+    "detail": "The 103-line hand-rolled `custom` screen (`delivery-log-screen.tsx`) is gone. `r.screen({ id: DELIVERY_LOG_SCREEN_ID, type: \"projectionList\", ... })` drives the list off `delivery:query:log`, now built on `definePagedQueryHandler` with `cursor`/`limit`/`sort`/`sortDirection` and a server-side sort whitelist (type-guarded, not an `as`-cast) covering `createdAt`/`type`/`channel`/`status` — `recipient` isn't sortable since it's PII decrypted per-row, not a column SQL can ORDER BY. Pagination is cursor-based (`pagination: \"infinite\"`): `deliveryAttemptsTable.id` is an event-stream aggregate id, not a sequential PK, so there's no cheap offset/COUNT(*) path. The notificationType/recipientAddress → type/recipient display-name mapping moved from the old client component into the query handler, matching the read-projection convention for declarative list screens; column i18n keys moved from the client-only bundle into the server-registered `DELIVERY_I18N` so the generic renderer can resolve them. The status column keeps one small TSX cell (`DeliveryStatusCell`, a `StatusBadge`), registered as a `columnRenderer` — that's the only surviving hand-written UI for this screen."
+  },
+  {
+    "version": "0.120.0",
+    "type": "improvement",
+    "title": "PII on custom-event payloads (#799).",
+    "detail": "PII on custom-event payloads (#799). `r.defineEvent(name, schema, { piiFields: { recipientAddress: { subjectField: \"recipientId\" } } })` declares payload fields that are encrypted under the owning user's DEK (crypto-shredding). Enforcement lives in the low-level event-store `append()` — the single write funnel — so `ctx.appendEvent`, MSP-apply AND out-of-dispatcher writers (delivery attempt-log, jobs run-logger) are all covered; the stored event and the returned echo carry ciphertext, keeping inline projections and rebuilds identical. A null subject field (system cron runs, recipient-less attempts) stays plaintext — there is no user key to shred. Misconfigured `piiFields` (unknown field/subjectField) throw at feature-definition time. Bundled features annotated: `delivery:event:attempt`.`recipientAddress` (subject = recipientId) and `jobs` `run-started`.`payload` (subject = triggeredById); the pseudonymous fk ids stay plaintext. `delivery log.query` and `jobs list/details` decrypt for display — a forgotten subject shows `[[erased]]`. This makes the events-only aggregates from #797 Art.-17-capable: user-forget erases the DEK, historical delivery addresses and job payloads become unreadable without touching the append-only stream. New exports: `encryptPiiValueForSubject`, `configureEventPiiCatalog`/`configuredEventPiiCatalog`/`encryptEventPayloadPii` (framework/crypto)."
+  }
+]

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -0,0 +1,17 @@
+import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ChannelContext } from "./types.js";
+
+// Build the per-tenant context a channel's resolve/render/send receives.
+// Shared by the synchronous delivery-service path and the async job handlers
+// (which pass sseBroker=undefined — only the inline inApp channel uses SSE,
+// and it never runs through a job).
+export function buildChannelContext(
+  db: DbConnection,
+  registry: Registry,
+  sseBroker: SseBroker | undefined,
+  tenantId: TenantId,
+): ChannelContext {
+  return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId };
+}

package/packages/bundled-features/src/delivery/constants.ts

@@ -0,0 +1,36 @@
+import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
+import { QnTypes, qn } from "@cosmicdrift/kumiko-framework/engine";
+import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
+
+// Extension-point name for delivery-channel plugins (channel-email,
+// channel-in-app, channel-push, ...).
+export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel" as const;
+
+export {
+  DELIVERY_ATTEMPT_EVENT,
+  DELIVERY_FEATURE,
+  DELIVERY_LOG_SCREEN_ID,
+  DELIVERY_RESUBSCRIBE_PATH,
+  DELIVERY_STATUS_CELL_COMPONENT,
+  DELIVERY_UNSUBSCRIBE_PATH,
+  DeliveryErrors,
+  DeliveryHandlers,
+  DeliveryJobNames,
+  DeliveryQueries,
+  DeliveryStatus,
+  type DeliveryStatusValue,
+} from "./public-names.js";
+
+// notify() priority → BullMQ job priority. Lower number = processed first; all
+// > 0 so prioritised delivery jobs never mix with BullMQ's "0 = unprioritised
+// FIFO" bucket. critical jobs jump ahead of normal/low in the worker queue.
+export const deliveryPriorityRank: Record<NotifyPriority, number> = {
+  critical: 1,
+  normal: 2,
+  low: 3,
+};
+
+export const DeliveryJobs = {
+  render: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.render),
+  send: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.send),
+} as const;

package/packages/bundled-features/src/delivery/db/queries/address-opt-outs.ts

@@ -0,0 +1,23 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// Exact match only — unlike notification-preferences there is no wildcard
+// ("*") semantics for address opt-outs, the token that creates a row always
+// carries one concrete notificationType/channel pair.
+export async function isAddressOptedOut(
+  db: DbConnection,
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+): Promise<boolean> {
+  const rows = await unsafeReadRetrying<{ readonly id: string }>(
+    db,
+    `SELECT id FROM read_notification_address_opt_outs
+     WHERE tenant_id = $1 AND address_hash = $2 AND notification_type = $3 AND channel = $4
+     LIMIT 1`,
+    [tenantId, addressHash, notificationType, channel],
+  );
+  return rows.length > 0;
+}

package/packages/bundled-features/src/delivery/db/queries/preferences.ts

@@ -0,0 +1,32 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type NotificationPreferenceRow = {
+  readonly notificationType: string;
+  readonly channel: string;
+  readonly enabled: boolean;
+};
+
+// @wrapper-known semantic-alias
+export async function selectNotificationPreferences(
+  db: DbConnection,
+  tenantId: TenantId,
+  userId: string,
+  notificationType: string,
+  channelName: string,
+): Promise<readonly NotificationPreferenceRow[]> {
+  return unsafeReadRetrying<NotificationPreferenceRow>(
+    db,
+    `SELECT notification_type AS "notificationType", channel, enabled
+     FROM read_notification_preferences
+     WHERE tenant_id = $1
+       AND user_id = $2
+       AND (
+         (notification_type = $3 AND channel = $4)
+         OR (notification_type = '*' AND channel = $4)
+         OR (notification_type = $3 AND channel = '*')
+       )`,
+    [tenantId, userId, notificationType, channelName],
+  );
+}