cursedbelt-server 4.26.1 → 4.28.0

package/src/server/notifications/d1.ts

@@ -0,0 +1,334 @@
+/**
+ * `cursedbelt-server/notifications/d1` — the notification service over D1, for an app a Worker
+ * serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `createNotificationService` builds cwip's `createSqliteNotificationStore` over a synchronous
+ * `bun:sqlite` handle; a Worker has neither. `apps/family`'s port to a Worker + D1 (task 393)
+ * needs the SAME inbox — the same table, the same coalescing, the same routes — so this is
+ * cwip's `NotificationStore` contract implemented over D1, handed to cwip's own
+ * `createNotificationCenter`, and mounted by the same `mountNotificationRoutes`. The engine
+ * stays cwip's; only the storage changes.
+ *
+ * ── What is the same, and what is not ─────────────────────────────────────
+ *   · The table is `createSqliteNotificationStore`'s, column for column and index for index
+ *     ({@link notificationsDdl}; `./d1.spec.ts` compares the two schemas), so coalescing is
+ *     still the partial unique index and never only a read.
+ *   · Every store method runs cwip's statement, bound identically; `./d1.spec.ts` drives both
+ *     stores through one scenario and compares every result and every row.
+ *   · 🔴 `hub` is always `null` and `{base}/stream` is never mounted. Live delivery is an
+ *     in-memory set of open streams, and a Worker isolate cannot share one with the isolate
+ *     that produced the notification — a stream route that answered 200 and never emitted
+ *     would be worse than the 404 the client already falls back from. The poll transport is
+ *     the delivery story here, exactly as it is for `live: false` on the Mac.
+ *   · 🔴 No DDL runs here, ever. The sync store migrates on construction; on D1 the table is
+ *     the app's `db/schema.sql`, built from {@link notificationsDdl} (or from an in-memory run
+ *     of `NOTIFICATION_MIGRATIONS` — the two converge, and the spec proves it).
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`../telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./service.js`,
+ * `./migrations.js` or `./index.js` here.
+ *
+ * ```ts
+ * import { createD1NotificationService } from "cursedbelt-server/notifications/d1";
+ *
+ * const notifications = createD1NotificationService({ db: createRemoteD1(env.DB) });
+ * notifications.mount(app, { authorize: (c) => sso.userOf(c)?.id ?? null });
+ * await notifications.center.notify(userId, { type: "share.grant", title: "Shared with you" });
+ * ```
+ */
+import {
+	type AppNotification,
+	createNotificationCenter,
+	type ListNotificationsQuery,
+	type NotificationPage,
+	type NotificationStore,
+} from "cwip/notifications";
+import type { D1LikeBindable, D1LikeDatabase } from "../d1/types.js";
+import { mountNotificationRoutes } from "./routes.js";
+import type { NotificationService } from "./types.js";
+
+export type { NotificationService, NotificationServiceMountOptions } from "./types.js";
+
+/** The default table — the name `createSqliteNotificationStore` and `NOTIFICATION_MIGRATIONS` use. */
+export const D1_NOTIFICATIONS_TABLE = "notifications";
+
+const DEFAULT_LIMIT = 50;
+
+const assertIdentifier = (name: string): void => {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+		throw new Error(`notifications: invalid table identifier: ${name}`);
+	}
+};
+
+/**
+ * The DDL a D1 schema needs for the notification table — the FINAL shape
+ * `createSqliteNotificationStore` migrates any database to (its later `source`/`severity`
+ * columns are in the CREATE, as they are in cwip's), with both indexes. Idempotent.
+ */
+export function notificationsDdl(table: string = D1_NOTIFICATIONS_TABLE): string[] {
+	assertIdentifier(table);
+	return [
+		`CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      source TEXT,
+      severity TEXT NOT NULL DEFAULT 'info',
+      title TEXT NOT NULL,
+      body TEXT,
+      link TEXT,
+      resource_type TEXT,
+      resource_id TEXT,
+      actor_id TEXT,
+      actor_name TEXT,
+      group_key TEXT,
+      count INTEGER NOT NULL DEFAULT 1,
+      read INTEGER NOT NULL DEFAULT 0,
+      done INTEGER NOT NULL DEFAULT 0
+    )`,
+		`CREATE INDEX IF NOT EXISTS idx_${table}_user ON ${table}(user_id, done, read, created_at)`,
+		`CREATE UNIQUE INDEX IF NOT EXISTS idx_${table}_group ON ${table}(user_id, group_key)
+     WHERE group_key IS NOT NULL AND done = 0`,
+	];
+}
+
+/** {@link notificationsDdl} for the default table. */
+export const NOTIFICATIONS_DDL: readonly string[] = notificationsDdl();
+
+interface NotificationRow {
+	id: string;
+	user_id: string;
+	created_at: number;
+	updated_at: number;
+	type: string;
+	source: string | null;
+	severity: AppNotification["severity"];
+	title: string;
+	body: string | null;
+	link: string | null;
+	resource_type: string | null;
+	resource_id: string | null;
+	actor_id: string | null;
+	actor_name: string | null;
+	group_key: string | null;
+	count: number;
+	read: number;
+	done: number;
+}
+
+/** cwip's `rowToNotification`, verbatim in effect — an absent column is `undefined`, never `null`. */
+const rowToNotification = (row: NotificationRow): AppNotification => ({
+	id: row.id,
+	userId: row.user_id,
+	createdAt: row.created_at,
+	updatedAt: row.updated_at,
+	type: row.type,
+	source: row.source ?? undefined,
+	severity: row.severity ?? "info",
+	title: row.title,
+	body: row.body ?? undefined,
+	link: row.link ?? undefined,
+	resourceType: row.resource_type ?? undefined,
+	resourceId: row.resource_id ?? undefined,
+	actorId: row.actor_id ?? undefined,
+	actorName: row.actor_name ?? undefined,
+	groupKey: row.group_key ?? undefined,
+	count: row.count,
+	read: !!row.read,
+	done: !!row.done,
+});
+
+export interface D1NotificationStoreOptions {
+	/** Table name override (identifier-validated). Default `notifications`. */
+	table?: string;
+}
+
+/**
+ * cwip's `NotificationStore` over D1 — the same statements as `createSqliteNotificationStore`,
+ * awaited. Every method is user-scoped, as the contract requires. Runs no DDL.
+ */
+export function createD1NotificationStore(
+	db: D1LikeDatabase,
+	options: D1NotificationStoreOptions = {},
+): NotificationStore {
+	const table = options.table ?? D1_NOTIFICATIONS_TABLE;
+	assertIdentifier(table);
+
+	const insertSql = `
+    INSERT INTO ${table} (id, user_id, created_at, updated_at, type, source, severity, title,
+      body, link, resource_type, resource_id, actor_id, actor_name, group_key, count, read, done)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `;
+	const updateSql = `
+    UPDATE ${table} SET updated_at = ?, type = ?, source = ?, severity = ?, title = ?, body = ?,
+      link = ?, resource_type = ?, resource_id = ?, actor_id = ?, actor_name = ?, group_key = ?,
+      count = ?, read = ?, done = ?
+    WHERE id = ? AND user_id = ?
+  `;
+
+	/** 🔴 Every optional becomes `null` and every boolean `0/1` HERE — D1 refuses an
+	 *  `undefined` bind outright, where `bun:sqlite` would have bound NULL without a word. */
+	const bindDraftColumns = (n: AppNotification): D1LikeBindable[] => [
+		n.type,
+		n.source ?? null,
+		n.severity,
+		n.title,
+		n.body ?? null,
+		n.link ?? null,
+		n.resourceType ?? null,
+		n.resourceId ?? null,
+		n.actorId ?? null,
+		n.actorName ?? null,
+		n.groupKey ?? null,
+		n.count,
+		n.read ? 1 : 0,
+		n.done ? 1 : 0,
+	];
+
+	const one = async (sql: string, ...values: D1LikeBindable[]): Promise<AppNotification | null> => {
+		const row = await db
+			.prepare(sql)
+			.bind(...values)
+			.first<NotificationRow>();
+		return row ? rowToNotification(row) : null;
+	};
+	const changes = async (sql: string, ...values: D1LikeBindable[]): Promise<number> =>
+		(
+			await db
+				.prepare(sql)
+				.bind(...values)
+				.run()
+		).meta.changes;
+
+	return {
+		insert: async (n) => {
+			await db
+				.prepare(insertSql)
+				.bind(n.id, n.userId, n.createdAt, n.updatedAt, ...bindDraftColumns(n))
+				.run();
+		},
+
+		update: async (n) => {
+			await db
+				.prepare(updateSql)
+				.bind(n.updatedAt, ...bindDraftColumns(n), n.id, n.userId)
+				.run();
+		},
+
+		findOpenByGroup: (userId, groupKey) =>
+			one(`SELECT * FROM ${table} WHERE user_id = ? AND group_key = ? AND done = 0 LIMIT 1`, userId, groupKey),
+
+		get: (userId, id) => one(`SELECT * FROM ${table} WHERE id = ? AND user_id = ?`, id, userId),
+
+		list: async ({
+			userId,
+			filter = "all",
+			limit = DEFAULT_LIMIT,
+			offset = 0,
+		}: ListNotificationsQuery): Promise<NotificationPage> => {
+			const where =
+				filter === "unread"
+					? "user_id = ? AND done = 0 AND read = 0"
+					: filter === "done"
+						? "user_id = ? AND done = 1"
+						: "user_id = ? AND done = 0";
+			// `rowid DESC` breaks a same-millisecond tie by insertion order, as cwip's store does —
+			// its comment has the measurement. D1 tables are rowid tables, so it means the same there.
+			const { results } = await db
+				.prepare(`SELECT * FROM ${table} WHERE ${where} ORDER BY created_at DESC, rowid DESC LIMIT ? OFFSET ?`)
+				.bind(userId, limit + 1, offset)
+				.all<NotificationRow>();
+			return { items: results.slice(0, limit).map(rowToNotification), hasMore: results.length > limit };
+		},
+
+		unreadCount: async (userId) =>
+			(await db
+				.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE user_id = ? AND done = 0 AND read = 0`)
+				.bind(userId)
+				.first<number>("n")) ?? 0,
+
+		markRead: (userId, id, read) =>
+			changes(
+				`UPDATE ${table} SET read = ? WHERE id = ? AND user_id = ? AND read != ?`,
+				read ? 1 : 0,
+				id,
+				userId,
+				read ? 1 : 0,
+			),
+
+		markAllRead: (userId) =>
+			changes(`UPDATE ${table} SET read = 1 WHERE user_id = ? AND done = 0 AND read = 0`, userId),
+
+		setDone: (userId, id, done) =>
+			changes(
+				`UPDATE ${table} SET done = ?, read = CASE WHEN ? = 1 THEN 1 ELSE read END
+           WHERE id = ? AND user_id = ? AND done != ?`,
+				done ? 1 : 0,
+				done ? 1 : 0,
+				id,
+				userId,
+				done ? 1 : 0,
+			),
+
+		doneAll: (userId) => changes(`UPDATE ${table} SET done = 1, read = 1 WHERE user_id = ? AND done = 0`, userId),
+
+		remove: (userId, id) => changes(`DELETE FROM ${table} WHERE id = ? AND user_id = ?`, id, userId),
+
+		pruneDone: (olderThanMs) => changes(`DELETE FROM ${table} WHERE done = 1 AND updated_at < ?`, olderThanMs),
+	};
+}
+
+export interface CreateD1NotificationServiceOptions {
+	/** The app's D1 handle — `createRemoteD1(env.DB)` on a Worker, `createLocalD1(sqlite)` in a test. */
+	db: D1LikeDatabase;
+	/** Table name override (identifier-validated). */
+	table?: string;
+	/** Resolve a role audience (`notifyAudience({ role })`) to user ids. */
+	resolveRole?: (role: string) => Promise<string[]>;
+	/** Producer-path failures land here. Defaults to stderr. */
+	onError?: (error: unknown, context: string) => void;
+	/** Test seams, forwarded to the center. */
+	now?: () => number;
+	newId?: () => string;
+}
+
+/**
+ * The whole server half over D1 — `createNotificationService`'s shape, with `hub: null`.
+ * `mount` hangs the same routes on the app, minus `{base}/stream` (see the header).
+ */
+export function createD1NotificationService(options: CreateD1NotificationServiceOptions): NotificationService {
+	const onError =
+		options.onError ??
+		((error: unknown, context: string) =>
+			console.error(`[notifications] ${context}:`, error instanceof Error ? error.message : error));
+
+	const store = createD1NotificationStore(options.db, { table: options.table });
+
+	const center = createNotificationCenter({
+		store,
+		resolveRole: options.resolveRole,
+		now: options.now,
+		newId: options.newId,
+		onError,
+	});
+
+	return {
+		center,
+		store,
+		hub: null,
+		mount(app, mountOptions) {
+			mountNotificationRoutes(app, {
+				center,
+				authorize: mountOptions.authorize,
+				basePath: mountOptions.basePath,
+				maxLimit: mountOptions.maxLimit,
+			});
+		},
+		close() {
+			// Nothing to close: there are no live streams on D1.
+		},
+	};
+}

package/src/server/notifications/service.ts

@@ -16,13 +16,16 @@ import type { Database } from "bun:sqlite";
 import {
 	createNotificationCenter,
 	createSqliteNotificationStore,
-	type NotificationCenter,
 	type NotificationDb,
-	type NotificationStore,
 } from "cwip/notifications";
-import type { Context, Hono } from "hono";
-import { createNotificationHub, type NotificationHub } from "./hub.js";
+import { createNotificationHub } from "./hub.js";
 import { mountNotificationRoutes } from "./routes.js";
+import type { NotificationService } from "./types.js";
+
+// The service's SHAPE has no driver in it, so `./d1.ts` (which runs on `workerd`) returns the
+// same `NotificationService` without reaching this file. Re-exported so
+// `cursedbelt-server/notifications` is unchanged.
+export type { NotificationService, NotificationServiceMountOptions } from "./types.js";
 
 export interface CreateNotificationServiceOptions {
 	/** The app's own database — the table lands beside its rows. */
@@ -44,25 +47,6 @@ export interface CreateNotificationServiceOptions {
 	newId?: () => string;
 }
 
-export interface NotificationServiceMountOptions {
-	/** Resolve the caller to a user id, or null to refuse. */
-	authorize: (c: Context) => string | null | Promise<string | null>;
-	/** Path prefix. Default `/api/notifications`. */
-	basePath?: string;
-	/** Largest page a caller may ask for. Default 200. */
-	maxLimit?: number;
-}
-
-export interface NotificationService {
-	readonly center: NotificationCenter;
-	readonly store: NotificationStore;
-	/** Null when `live: false` — there is then nothing to stream. */
-	readonly hub: NotificationHub | null;
-	mount(app: Hono, options: NotificationServiceMountOptions): void;
-	/** Drop live subscribers (shutdown, tests). Safe to call with no hub. */
-	close(): void;
-}
-
 export function createNotificationService(
 	options: CreateNotificationServiceOptions,
 ): NotificationService {

package/src/server/notifications/types.ts

@@ -0,0 +1,29 @@
+/**
+ * The notification service's shape with no driver attached — what `createNotificationService`
+ * (`bun:sqlite`) and `createD1NotificationService` (D1, `./d1.ts`) both return. It lives apart
+ * from `./service.ts` so the D1 half, which runs on `workerd`, never reaches a module that
+ * names `bun:sqlite`, not even as a type.
+ */
+import type { NotificationCenter, NotificationStore } from "cwip/notifications";
+import type { Context, Hono } from "hono";
+import type { NotificationHub } from "./hub.js";
+
+export interface NotificationServiceMountOptions {
+	/** Resolve the caller to a user id, or null to refuse. */
+	authorize: (c: Context) => string | null | Promise<string | null>;
+	/** Path prefix. Default `/api/notifications`. */
+	basePath?: string;
+	/** Largest page a caller may ask for. Default 200. */
+	maxLimit?: number;
+}
+
+export interface NotificationService {
+	readonly center: NotificationCenter;
+	readonly store: NotificationStore;
+	/** Null when `live: false`, and always on D1 (`./d1.ts`) — there is then nothing to stream,
+	 *  and the client's poll transport is the whole delivery story. */
+	readonly hub: NotificationHub | null;
+	mount(app: Hono, options: NotificationServiceMountOptions): void;
+	/** Drop live subscribers (shutdown, tests). Safe to call with no hub. */
+	close(): void;
+}

package/src/server/sharing/contract.ts

@@ -0,0 +1,109 @@
+/**
+ * The store's contract with no driver attached: the input shapes both stores take, the
+ * {@link AsyncShareStore} a D1-backed store satisfies, and the two subject helpers.
+ *
+ * It lives apart from `./store.ts` so that `./d1.ts` — which runs on `workerd` — and its
+ * declaration file never reach a module that names `bun:sqlite`, not even as a type. The
+ * sync store re-exports everything here, so `cursedbelt-server/sharing` is unchanged.
+ */
+import type {
+	ShareAccess,
+	ShareEvent,
+	ShareGrant,
+	ShareGroup,
+	ShareGroupMember,
+	ShareLevel,
+	ShareSubject,
+	ShareViewer,
+} from "cursedbelt-core/sharing/model";
+
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export const user = (id: string): ShareSubject => ({ type: "user", id });
+export const group = (id: string): ShareSubject => ({ type: "group", id });
+
+/** A resource within the store's own app — the `app` half is supplied by the
+ *  store, so a caller cannot mistakenly write a grant into another app's rows. */
+export interface ShareTarget {
+	kind: string;
+	id: string;
+}
+
+export interface GrantInput extends ShareTarget {
+	subject: ShareSubject;
+	level: ShareLevel;
+	grantedBy: string;
+	note?: string;
+}
+
+export interface RevokeInput extends ShareTarget {
+	subject: ShareSubject;
+	revokedBy: string;
+	note?: string;
+}
+
+export interface ShareEventQuery {
+	kind?: string;
+	id?: string;
+	subject?: ShareSubject;
+	/** Newest first, capped. Default 200 — a panel shows a page, and an unbounded
+	 *  audit read on a busy resource is the query that times out in production. */
+	limit?: number;
+}
+
+/** What `sharedSql` takes — the store supplies `app`. */
+export interface SharedSqlInput {
+	kind: string;
+	subjectId: string;
+	column: string;
+	atLeast?: ShareLevel;
+}
+
+/**
+ * The share store over an ASYNC database — `createD1ShareStore` in
+ * `cursedbelt-server/sharing/d1`.
+ *
+ * The same methods as the sync `ShareStore`, with the same names, arguments and meaning;
+ * every method that touches the database resolves instead of returning. `sharedSql` stays
+ * synchronous because it touches nothing: it emits the SAME fragment the sync store does, for
+ * an app to embed in its own D1 queries. `sharing/d1.spec.ts` checks the two stores expose
+ * exactly the same method names, so neither can grow a verb the other lacks.
+ */
+export interface AsyncShareStore {
+	/** The app this store speaks for. */
+	readonly app: string;
+	grant(input: GrantInput): Promise<ShareGrant>;
+	revoke(input: RevokeInput): Promise<ShareLevel | null>;
+	revokeResource(target: ShareTarget, revokedBy: string): Promise<number>;
+	revokeSubject(subject: ShareSubject, revokedBy: string): Promise<number>;
+	listForResource(target: ShareTarget): Promise<ShareGrant[]>;
+	listForSubject(subject: ShareSubject): Promise<ShareGrant[]>;
+	accessFor(target: ShareTarget, viewer: ShareViewer): Promise<ShareAccess>;
+	resourceIdsFor(kind: string, viewer: ShareViewer, atLeast?: ShareLevel): Promise<string[]>;
+	sharedSql(input: SharedSqlInput): string;
+	createGroup(input: { id: string; name: string; createdBy: string; note?: string }): Promise<ShareGroup>;
+	renameGroup(id: string, name: string, actor: string): Promise<void>;
+	deleteGroup(id: string, actor: string): Promise<void>;
+	listGroups(): Promise<ShareGroup[]>;
+	addGroupMember(groupId: string, subjectId: string, actor: string): Promise<void>;
+	removeGroupMember(groupId: string, subjectId: string, actor: string): Promise<void>;
+	listGroupMembers(groupId: string): Promise<ShareGroupMember[]>;
+	groupIdsFor(subjectId: string): Promise<string[]>;
+	events(query?: ShareEventQuery): Promise<ShareEvent[]>;
+}
+
+/**
+ * A value that may or may not be a promise — what a consumer holding EITHER store gets back
+ * from a call, and what it can always `await`.
+ */
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * Either store, as a consumer that works over both sees it: every method's result is
+ * {@link Awaitable}. `mountShareRoutes` takes this, and awaits every call — awaiting a
+ * synchronous value is a no-op, so the sync store's behaviour through it is unchanged.
+ */
+export type AwaitableShareStore = {
+	readonly [K in keyof AsyncShareStore]: AsyncShareStore[K] extends (...args: infer A) => Promise<infer R>
+		? (...args: A) => Awaitable<R>
+		: AsyncShareStore[K];
+};