cursedbelt-server 4.26.1 → 4.28.0

package/dist/server/notifications/d1.js

@@ -0,0 +1,226 @@
+/**
+ * `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 { createNotificationCenter, } from "cwip/notifications";
+import { mountNotificationRoutes } from "./routes.js";
+/** The default table — the name `createSqliteNotificationStore` and `NOTIFICATION_MIGRATIONS` use. */
+export const D1_NOTIFICATIONS_TABLE = "notifications";
+const DEFAULT_LIMIT = 50;
+const assertIdentifier = (name) => {
+    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 = D1_NOTIFICATIONS_TABLE) {
+    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 = notificationsDdl();
+/** cwip's `rowToNotification`, verbatim in effect — an absent column is `undefined`, never `null`. */
+const rowToNotification = (row) => ({
+    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,
+});
+/**
+ * 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, options = {}) {
+    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) => [
+        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, ...values) => {
+        const row = await db
+            .prepare(sql)
+            .bind(...values)
+            .first();
+        return row ? rowToNotification(row) : null;
+    };
+    const changes = async (sql, ...values) => (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, }) => {
+            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();
+            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("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),
+    };
+}
+/**
+ * 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) {
+    const onError = options.onError ??
+        ((error, context) => 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/dist/server/notifications/service.d.ts

@@ -13,9 +13,8 @@
  * import and no wiring to get wrong.
  */
 import type { Database } from "bun:sqlite";
-import { type NotificationCenter, type NotificationStore } from "cwip/notifications";
-import type { Context, Hono } from "hono";
-import { type NotificationHub } from "./hub.js";
+import type { NotificationService } from "./types.js";
+export type { NotificationService, NotificationServiceMountOptions } from "./types.js";
 export interface CreateNotificationServiceOptions {
     /** The app's own database — the table lands beside its rows. */
     db: Database;
@@ -38,21 +37,4 @@ export interface CreateNotificationServiceOptions {
     now?: () => number;
     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 declare function createNotificationService(options: CreateNotificationServiceOptions): NotificationService;

package/dist/server/notifications/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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/dist/server/notifications/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/sharing/contract.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 declare const user: (id: string) => ShareSubject;
+export declare const group: (id: string) => ShareSubject;
+/** 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];
+};

package/dist/server/sharing/contract.js

@@ -0,0 +1,3 @@
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export const user = (id) => ({ type: "user", id });
+export const group = (id) => ({ type: "group", id });

package/dist/server/sharing/d1.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `cursedbelt-server/sharing/d1` — the fleet's sharing model over D1, for an app a Worker serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `./store.ts` is synchronous `bun:sqlite`, and a Worker has neither. `apps/family`'s port to
+ * a Worker + D1 (task 393) needs the SAME grants, revokes, groups and audit trail, in the SAME
+ * four tables, so a database moved from the Mac to D1 keeps meaning what it meant. This is that
+ * store, beside the sync one — which stays exactly as it was, because `auth` and `station` are
+ * still Bun servers.
+ *
+ * ── What is the same, and what is not ─────────────────────────────────────
+ * Same methods, names, arguments, validation and results as `ShareStore`; every method that
+ * touches the database resolves instead of returning. `sharedSql` is still synchronous and
+ * emits the identical fragment, for an app to embed in its own D1 queries. The SQL is the
+ * sync store's own (`./statements.ts`), and `./d1.spec.ts` runs both stores through one
+ * scenario and compares every call's result and every table's rows.
+ *
+ * The four properties of `./store.ts`'s header hold, by different means:
+ *  1. **Every mutation writes its audit row in the same transaction.** D1 has no interactive
+ *     transaction, so each mutation is ONE `db.batch([...])` — atomic on D1, a real
+ *     transaction locally. Where the sync store reads the grant and then decides what to log,
+ *     this store logs FROM the grant row inside that batch (`INSERT … SELECT … RETURNING`),
+ *     so there is no window between the read and the write for another request to use.
+ *  2. **A revoked grant's history survives it** — the event insert runs before the delete.
+ *  3. **`revokeResource` is one call** — two statements, one batch, however many grants.
+ *  4. **The hook cannot break a write.** `onEvent` runs after the batch commits; a throw — or
+ *     a rejected promise, which a Worker's hook may well return — is caught and warned.
+ *
+ * Differences a caller can observe, each deliberate:
+ *   · A multi-grant revoke (`revokeResource`, `revokeSubject`, `deleteGroup`) writes its
+ *     events oldest-grant-first (`ORDER BY grant_id`); the sync store writes them in whatever
+ *     order its SELECT happened to return. Same events, a defined order.
+ *   · `onEvent` may return a promise, and the store AWAITS it before resolving — a Worker that
+ *     returned before the hook settled could have it cut off with the isolate.
+ *   · Validation failures REJECT rather than throw synchronously (they are async methods).
+ *   · 🔴 No DDL runs here, ever. The sync store migrates on construction; on D1 the schema is
+ *     the app's `db/schema.sql`, built from {@link SHARE_DDL} (the exact statements the sync
+ *     migration runs), and applied by `wrangler d1 migrations`. A request-time `CREATE TABLE`
+ *     is a write per invocation against the 1,000-query budget, for nothing.
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`../telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./store.js` or
+ * `./migrations.js` here — `./schema.js`, `./statements.js` and `./contract.js` are the
+ * driver-free halves they were split into.
+ *
+ * ```ts
+ * import { createD1ShareStore } from "cursedbelt-server/sharing/d1";
+ *
+ * const shares = createD1ShareStore({ db: createRemoteD1(env.DB), app: "family", onEvent });
+ * await shares.grant({ kind: "person", id, subject: user(email), level: "read", grantedBy });
+ * const where = shares.sharedSql({ kind: "person", subjectId: viewer.email, column: "p.id" });
+ * ```
+ */
+import { type ShareEvent } from "cursedbelt-core/sharing/model";
+import type { D1LikeDatabase } from "../d1/types.js";
+import type { AsyncShareStore } from "./contract.js";
+export { group, user } from "./contract.js";
+export type { AsyncShareStore, Awaitable, AwaitableShareStore, GrantInput, RevokeInput, SharedSqlInput, ShareEventQuery, ShareTarget, } from "./contract.js";
+export { SHARE_DDL, SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./schema.js";
+export interface D1ShareStoreOptions {
+    /** The app's D1 handle — `createRemoteD1(env.DB)` on a Worker, `createLocalD1(sqlite)` in a test. */
+    db: D1LikeDatabase;
+    /** The satellite this store speaks for. Fixed at construction, as in the sync store. */
+    app: string;
+    /**
+     * Notified after every committed mutation, as in the sync store. May return a promise; the
+     * store awaits it, and neither a throw nor a rejection can undo the write.
+     */
+    onEvent?: (event: ShareEvent) => void | Promise<void>;
+    /** Injectable clock, for tests that assert ordering. ISO-8601 strings. */
+    now?: () => string;
+}
+/**
+ * The share store over D1. Runs no DDL — see the header; the tables come from
+ * {@link SHARE_DDL} in the app's schema.
+ */
+export declare function createD1ShareStore(options: D1ShareStoreOptions): AsyncShareStore;