@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/delivery/index.ts

@@ -0,0 +1,35 @@
+export type { DeliveryStatusValue } from "./constants";
+export {
+  DELIVERY_FEATURE,
+  DeliveryErrors,
+  DeliveryHandlers,
+  DeliveryQueries,
+  DeliveryStatus,
+} from "./constants";
+export {
+  collectChannels,
+  collectRenderers,
+  createDeliveryService,
+  type DeliveryServiceOptions,
+  type KillSwitchResolver,
+  type RateLimitConfig,
+} from "./delivery-service";
+export { createDeliveryFeature } from "./feature";
+export { deliveryAttemptsTable, notificationPreferencesTable } from "./tables";
+export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing";
+export type {
+  ChannelContext,
+  ChannelMessage,
+  ChannelResult,
+  DeliveryChannel,
+  DeliveryLogEntry,
+  DeliveryService,
+  NotificationRenderer,
+  RendererInput,
+} from "./types";
+export {
+  createUnsubscribeRoute,
+  signUnsubscribeToken,
+  type UnsubscribeRouteOptions,
+  type UnsubscribeTokenPayload,
+} from "./unsubscribe";

package/src/delivery/tables.ts

@@ -0,0 +1,74 @@
+import {
+  boolean,
+  buildBaseColumns,
+  instant,
+  table as pgTable,
+  text,
+  uniqueIndex,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { sql } from "drizzle-orm";
+
+// Delivery-log is an append-only stream of per-attempt records. The stream
+// of truth lives in the events-Tabelle (one aggregate per attempt, event
+// type `delivery:event:attempt`). An INLINE projection materialises each
+// event into a row of deliveryAttemptsTable for the log-query handler —
+// same TX as the event-append, so callers can read their own writes
+// synchronously. No r.entity is registered for `deliveryAttempt`: the
+// boot-validator accepts events-only projection sources as long as every
+// apply-key is a registered domain-event (see registry.ts).
+//
+// PK = event aggregate-id (uuid). Keeps the projection row linked back to
+// its event stream 1:1 — same convention as jobRunsTable + tenantSecretsTable.
+// Event replays stay idempotent (primary-key conflict instead of duplicate rows).
+export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
+  id: uuid("id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  notificationType: text("notification_type").notNull(),
+  channel: text("channel").notNull(),
+  // User-IDs as UUID-strings post-ES migration.
+  recipientId: text("recipient_id"),
+  recipientAddress: text("recipient_address"),
+  status: text("status").notNull().$type<"sent" | "failed" | "skipped">(),
+  error: text("error"),
+  createdAt: instant("created_at").default(sql`now()`).notNull(),
+});
+
+// User-scoped opt-in/opt-out for (notificationType, channel) pairs. Post-ES
+// refactor: each row is a notificationPreference aggregate with
+// `.created / .updated / .deleted` lifecycle events written via the
+// event-store executor. The unique index on (tenant, user, type, channel)
+// is the effective natural key; the uuid PK is the aggregate id.
+export const notificationPreferenceEntity = createEntity({
+  table: "read_notification_preferences",
+  fields: {
+    userId: createTextField({ required: true }),
+    notificationType: createTextField({ required: true }), // qualified name or "*"
+    channel: createTextField({ required: true }), // "inApp", "email", "push", or "*"
+    enabled: createBooleanField({ default: true }),
+  },
+});
+
+export const notificationPreferencesTable = pgTable(
+  "read_notification_preferences",
+  {
+    ...buildBaseColumns(false, "uuid"),
+    userId: text("user_id").notNull(),
+    notificationType: text("notification_type").notNull(),
+    channel: text("channel").notNull(),
+    enabled: boolean("enabled").default(true).notNull(),
+  },
+  (table) => [
+    uniqueIndex("read_notification_preferences_unique").on(
+      table.tenantId,
+      table.userId,
+      table.notificationType,
+      table.channel,
+    ),
+  ],
+);

package/src/delivery/testing.ts

@@ -0,0 +1,47 @@
+import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { Redis } from "ioredis";
+import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service";
+import { collectChannels, createDeliveryService } from "./delivery-service";
+import type { DeliveryService } from "./types";
+
+export type CreateDeliveryTestContextOptions = {
+  readonly tenantUserIdsQuery?: string;
+  readonly rateLimit?: RateLimitConfig;
+  readonly isChannelKilled?: KillSwitchResolver;
+};
+
+/**
+ * Helper for setupTestStack: creates a DeliveryService + _notifyFactory for the test context.
+ * Abstracts the boilerplate that every Delivery-using test needs.
+ *
+ * Usage:
+ *   setupTestStack({
+ *     features: [...],
+ *     extraContext: (deps) => createDeliveryTestContext(deps, { tenantUserIdsQuery: TenantQueries.resolveUserIds }),
+ *   });
+ */
+export function createDeliveryTestContext(
+  deps: { registry: Registry; db: DbConnection; sseBroker: SseBroker; redis: Redis },
+  options: CreateDeliveryTestContextOptions = {},
+): Record<string, unknown> & { deliveryService: DeliveryService } {
+  const { registry, db, sseBroker } = deps;
+  const channels = collectChannels(registry);
+  const deliveryService = createDeliveryService({
+    db,
+    registry,
+    sseBroker,
+    channels,
+    ...options,
+  });
+
+  return {
+    deliveryService, // exposed so tests can inspect/call directly if needed
+    _notifyFactory:
+      (user: { id: number; tenantId: TenantId }, tenantId: TenantId) =>
+      (notificationType: string, notifyOptions: Record<string, unknown>) =>
+        // @cast-boundary engine-bridge — generic test-helper → typed entity-specific notify()
+        deliveryService.notify(notificationType, notifyOptions as never, user as never, tenantId),
+  };
+}

package/src/delivery/types.ts

@@ -0,0 +1,71 @@
+import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  NotifyOptions,
+  Registry,
+  SessionUser,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// --- Channel Interface ---
+
+export type ChannelContext = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly sseBroker: SseBroker | undefined;
+  readonly tenantId: TenantId;
+};
+
+export type ChannelMessage = {
+  readonly notificationType: string;
+  readonly title: string;
+  readonly body: string | undefined;
+  readonly data: Readonly<Record<string, unknown>> | undefined;
+};
+
+export type ChannelResult = {
+  readonly status: "sent" | "failed" | "skipped";
+  readonly error?: string;
+  readonly address?: string;
+};
+
+export type DeliveryChannel = {
+  readonly name: string;
+  resolve(userId: string, ctx: ChannelContext): Promise<string | null>;
+  send(address: string, message: ChannelMessage, ctx: ChannelContext): Promise<ChannelResult>;
+};
+
+// --- Notification Renderer ---
+
+export type RendererInput = {
+  readonly template: string;
+  readonly variables: Readonly<Record<string, unknown>>;
+};
+
+export type NotificationRenderer = {
+  readonly name: string;
+  render(input: RendererInput): Promise<string>;
+};
+
+// --- Delivery Log Entry ---
+
+export type DeliveryLogEntry = {
+  readonly tenantId: TenantId;
+  readonly notificationType: string;
+  readonly channel: string;
+  readonly recipientId: string | null;
+  readonly recipientAddress: string | null;
+  readonly status: "sent" | "failed" | "skipped";
+  readonly error: string | null;
+};
+
+// --- Delivery Service ---
+
+export type DeliveryService = {
+  notify(
+    notificationType: string,
+    options: NotifyOptions,
+    user: SessionUser,
+    tenantId: TenantId,
+  ): Promise<void>;
+};

package/src/delivery/unsubscribe.ts

@@ -0,0 +1,99 @@
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Hono } from "hono";
+import * as jose from "jose";
+import { z } from "zod";
+import { upsertPreference } from "./upsert-preference";
+
+// Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
+// wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+const unsubscribeJwtPayloadSchema = z.object({
+  sub: z.string().min(1),
+  tenantId: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+});
+
+export type UnsubscribeTokenPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
+export type UnsubscribeRouteOptions = {
+  readonly db: DbConnection;
+  readonly jwtSecret: string;
+};
+
+const UNSUBSCRIBE_EXPIRY = "7d";
+// The route runs outside the dispatcher — no SessionUser, no JWT middleware.
+// Bill the event against the token-subject (the user owns their preference)
+// and attribute it as a system-role action. This mirrors the way jobs and
+// seeds attribute their out-of-band writes.
+const SYSTEM_ROLES = ["system"] as const;
+
+export async function signUnsubscribeToken(
+  payload: UnsubscribeTokenPayload,
+  secret: string,
+): Promise<string> {
+  const encodedSecret = new TextEncoder().encode(secret);
+  return new jose.SignJWT({
+    tenantId: payload.tenantId,
+    notificationType: payload.notificationType,
+    channel: payload.channel,
+  })
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(String(payload.userId))
+    .setIssuer("kumiko:unsubscribe")
+    .setIssuedAt()
+    .setExpirationTime(UNSUBSCRIBE_EXPIRY)
+    .sign(encodedSecret);
+}
+
+export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
+  const { db, jwtSecret } = options;
+  const encodedSecret = new TextEncoder().encode(jwtSecret);
+  const app = new Hono();
+
+  app.get("/unsubscribe", async (c) => {
+    const token = c.req.query("token");
+    if (!token) {
+      return c.text("Missing token", 400);
+    }
+
+    let userId: string;
+    let tenantId: TenantId;
+    let notificationType: string;
+    let channel: string;
+    try {
+      const { payload } = await jose.jwtVerify(token, encodedSecret, {
+        issuer: "kumiko:unsubscribe",
+      });
+      const parsed = unsubscribeJwtPayloadSchema.parse(payload);
+      userId = parsed.sub;
+      // @cast-boundary engine-bridge — string post-zod → branded TenantId
+      tenantId = parsed.tenantId as TenantId;
+      notificationType = parsed.notificationType;
+      channel = parsed.channel;
+    } catch {
+      return c.text("Invalid or expired token", 400);
+    }
+
+    // Token-verify passed — everything below is a legitimate write. Don't
+    // swallow write-errors as "invalid token", that would mask real bugs
+    // (e.g. events-table missing, DB down) behind a misleading 400.
+    const actor = { id: userId, tenantId, roles: SYSTEM_ROLES };
+    const tdb = createTenantDb(db, tenantId, "system");
+    await upsertPreference(tdb, actor, {
+      tenantId,
+      userId,
+      notificationType,
+      channel,
+      enabled: false,
+    });
+    return c.text("You have been unsubscribed.", 200);
+  });
+
+  return app;
+}

package/src/delivery/upsert-preference.ts

@@ -0,0 +1,145 @@
+// Race-safe upsert for notification-preferences. Pre-ES this was a single
+// `onConflictDoUpdate` statement on the preferences table; post-ES we go
+// through the event-store executor, which doesn't offer a built-in upsert.
+// Splitting into lookup + create|update re-opens the race window for
+// concurrent requests — typical case: a user clicks the same "unsubscribe"
+// email link three times in a second.
+//
+// The fix: try the optimistic path (lookup + create|update), and on a
+// unique-index-violation race from a parallel create, re-lookup and fall
+// through to update. Worst case: one extra roundtrip for the loser of
+// the race. Happy path: same number of queries as the pre-ES upsert.
+
+import {
+  createEventStoreExecutor,
+  fetchOne,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables";
+
+const executor = createEventStoreExecutor(
+  notificationPreferencesTable,
+  notificationPreferenceEntity,
+  { entityName: "notification-preference" },
+);
+
+// Konkretes Lookup-Result-Shape — nur die zwei Felder die der upsert
+// tatsächlich für den Update-Path braucht. Vermeidet `row["x"] as T` index-
+// access casts; der Generic-Param am fetchOne macht den Cast zentralisiert
+// im Helper (db-row-boundary), nicht 4× pro Callsite.
+type PreferenceLookupRow = { readonly id: string; readonly version: number };
+
+async function lookup(
+  db: TenantDb,
+  tenantId: TenantId,
+  userId: string,
+  notificationType: string,
+  channel: string,
+): Promise<PreferenceLookupRow | undefined> {
+  return fetchOne<PreferenceLookupRow>(
+    db,
+    notificationPreferencesTable,
+    eq(notificationPreferencesTable.tenantId, tenantId),
+    eq(notificationPreferencesTable.userId, userId),
+    eq(notificationPreferencesTable.notificationType, notificationType),
+    eq(notificationPreferencesTable.channel, channel),
+  );
+}
+
+export type UpsertPreferenceInput = {
+  readonly tenantId: TenantId;
+  readonly userId: string;
+  readonly notificationType: string;
+  readonly channel: string;
+  readonly enabled: boolean;
+};
+
+/**
+ * Idempotent "set-this-preference-to-enabled-state" against the preferences
+ * aggregate stream. Emits either `.created` (first time) or `.updated`
+ * (subsequent) and catches the race-induced unique-index violation as a
+ * fallback to update.
+ */
+export async function upsertPreference(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertPreferenceInput,
+): Promise<WriteResult<UpsertPreferenceInput>> {
+  const existing = await lookup(
+    db,
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+
+  if (existing) {
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: { enabled: input.enabled },
+      },
+      actor,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: input };
+  }
+
+  try {
+    const result = await executor.create(
+      {
+        userId: input.userId,
+        notificationType: input.notificationType,
+        channel: input.channel,
+        enabled: input.enabled,
+      },
+      actor,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: input };
+  } catch (err) {
+    // Race-fallback: another request beat us to the insert between our
+    // lookup and the executor.create. The unique-index on
+    // (tenant, user, type, channel) fires Postgres error 23505. Only that
+    // specific error triggers the retry; DB-disconnect or any other
+    // failure must bubble up unchanged so callers see the real cause.
+    if (!isUniqueViolation(err)) throw err;
+    const afterRace = await lookup(
+      db,
+      input.tenantId,
+      input.userId,
+      input.notificationType,
+      input.channel,
+    );
+    if (!afterRace) throw err;
+    const result = await executor.update(
+      {
+        id: afterRace.id,
+        version: afterRace.version,
+        changes: { enabled: input.enabled },
+      },
+      actor,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: input };
+  }
+}
+
+// Narrow detection for Postgres "duplicate key violates unique constraint"
+// (SQLSTATE 23505). Drivers wrap the DB error in varying envelopes; we
+// check the `code` field plus a string-match fallback so the match survives
+// minor driver-version shifts without drifting wide.
+function isUniqueViolation(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { code?: unknown; cause?: { code?: unknown }; message?: unknown };
+  if (e.code === "23505") return true;
+  if (e.cause && typeof e.cause === "object" && e.cause.code === "23505") return true;
+  if (typeof e.message === "string" && e.message.includes("23505")) return true;
+  return false;
+}