pi-roundtable-web 0.25.0 → 0.26.1

package/src/notices/service.ts

@@ -0,0 +1,294 @@
+import { ConfigError, type Logger } from "pi-roundtable";
+import type { NoticeView, ServerFrame } from "../api-types.ts";
+import type { PushDispatch } from "../push/dispatch.ts";
+import type { Notices, OpenTarget } from "../web-app.ts";
+import type { NoticeFor, NoticeStore } from "./store.ts";
+import { openUrl, type RoutingOptions } from "./urls.ts";
+
+const MAX_TAG = 200;
+const MAX_TITLE = 200;
+const MAX_BODY = 2000;
+const MAX_RECIPIENTS = 500;
+const PAGE_ID = /^[a-z0-9-]{1,40}$/;
+
+export interface NoticeServiceOptions {
+	store: NoticeStore;
+	dispatch: PushDispatch;
+	/** Puts a frame on the open sockets of one person. */
+	deliver(frame: ServerFrame, principalId: string): void;
+	routing: RoutingOptions;
+	logger: Logger;
+}
+
+/** A notice as the bell shows it. */
+export function viewOf(notice: NoticeFor): NoticeView {
+	return {
+		tag: notice.tag,
+		title: notice.title,
+		...(notice.body ? { body: notice.body } : {}),
+		...(notice.open
+			? {
+					open:
+						"room" in notice.open
+							? {
+									room: notice.open.room,
+									...(notice.open.message === undefined
+										? {}
+										: { message: notice.open.message }),
+								}
+							: {
+									page: notice.open.page,
+									...(notice.open.query
+										? { query: { ...notice.open.query } }
+										: {}),
+								},
+				}
+			: {}),
+		urgency: notice.urgency,
+		ackable: notice.ackable,
+		raisedAt: notice.raisedAt.toISOString(),
+		...(notice.ackedAt ? { acked: true as const } : {}),
+	};
+}
+
+const refuse = (message: string): never => {
+	throw new ConfigError(`notices: ${message}`);
+};
+
+function checkOpen(open: OpenTarget | undefined): void {
+	if (!open) return;
+	if ("room" in open) {
+		if (typeof open.room !== "string" || open.room.length === 0)
+			refuse("open.room must be a room key");
+		if (
+			open.message !== undefined &&
+			!(Number.isSafeInteger(open.message) && open.message >= 0)
+		)
+			refuse("open.message must be a message id");
+	} else if (!PAGE_ID.test(open.page))
+		refuse("open.page must match [a-z0-9-]{1,40}");
+}
+
+/**
+ * The notices of the host: person-addressed, with state. A notice is a row the bell shows to its
+ * addressees and, when push is on, a push to their devices; the badge is the count of those that
+ * ask for an answer and have none. Everything a person can do to it (read, answer) is checked
+ * against the addressee list, which only the host changes.
+ */
+export class NoticeService implements Notices {
+	readonly #options: NoticeServiceOptions;
+	readonly #listeners = new Set<(tag: string, principalId: string) => void>();
+
+	constructor(options: NoticeServiceOptions) {
+		this.#options = options;
+	}
+
+	async raise(notice: Parameters<Notices["raise"]>[0]): Promise<void> {
+		const { store } = this.#options;
+		const to = [...new Set(notice.to)];
+		if (notice.tag.length === 0 || notice.tag.length > MAX_TAG)
+			refuse(`the tag must be 1 to ${MAX_TAG} characters`);
+		if (to.length === 0 || to.length > MAX_RECIPIENTS)
+			refuse(`a notice goes to 1 to ${MAX_RECIPIENTS} people`);
+		if (notice.title.length === 0 || notice.title.length > MAX_TITLE)
+			refuse(`the title must be 1 to ${MAX_TITLE} characters`);
+		if ((notice.body?.length ?? 0) > MAX_BODY)
+			refuse(`the body is longer than ${MAX_BODY} characters`);
+		checkOpen(notice.open);
+		this.#checkVia(notice.via);
+		await store.raise(
+			{
+				tag: notice.tag,
+				title: notice.title,
+				...(notice.body ? { body: notice.body } : {}),
+				...(notice.open ? { open: notice.open } : {}),
+				urgency: notice.urgency,
+				ackable: notice.ackable === true,
+			},
+			to,
+		);
+		await Promise.all(
+			to.map((principalId) =>
+				this.#tell(notice.tag, principalId, {
+					push: notice.push !== false,
+					...(notice.via ? { via: notice.via } : {}),
+				}),
+			),
+		);
+	}
+
+	async renotify(
+		tag: string,
+		add: readonly string[] = [],
+		options: { via?: readonly string[] } = {},
+	): Promise<void> {
+		this.#checkVia(options.via);
+		const people = await this.#options.store.renotify(tag, [...new Set(add)]);
+		if (!people) return;
+		await Promise.all(
+			people.map((principalId) =>
+				this.#tell(tag, principalId, {
+					push: true,
+					...(options.via ? { via: options.via } : {}),
+				}),
+			),
+		);
+	}
+
+	async resolve(
+		tag: string,
+		by?: { principalId?: string; reason: string },
+	): Promise<void> {
+		const { store } = this.#options;
+		const before = new Map<string, NoticeFor | undefined>();
+		const open = (await store.pending(tag))?.to ?? [];
+		for (const principalId of open)
+			before.set(principalId, await store.of(tag, principalId));
+		const people = await store.resolve(tag, by);
+		if (!people) return;
+		await Promise.all(
+			people.map((principalId) =>
+				this.#cleared(tag, principalId, before.get(principalId)),
+			),
+		);
+	}
+
+	/** Tells one addressee's pages and devices a notice is gone. */
+	async #cleared(
+		tag: string,
+		principalId: string,
+		was: NoticeFor | undefined,
+	): Promise<void> {
+		const { store, dispatch, routing } = this.#options;
+		this.#options.deliver({ type: "notice_resolved", tag }, principalId);
+		const count = await this.#sendBadge(principalId);
+		// Only a device that was pushed this notice has something to close.
+		if (await store.delivered(tag, principalId))
+			await dispatch.clear(
+				principalId,
+				tag,
+				openUrl(was?.open, routing),
+				count,
+			);
+	}
+
+	pending(tag: string): ReturnType<Notices["pending"]> {
+		return this.#options.store.pending(tag);
+	}
+
+	onAck(listener: (tag: string, principalId: string) => void): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	// ── What the person does ──
+
+	/** The person's open notices and their count. */
+	async listFor(
+		principalId: string,
+	): Promise<{ notices: NoticeView[]; badge: number }> {
+		const { store } = this.#options;
+		const [notices, badge] = await Promise.all([
+			store.openFor(principalId),
+			store.unhandled(principalId),
+		]);
+		return { notices: notices.map(viewOf), badge };
+	}
+
+	/** The person handled a notice; false when it is not theirs, is closed, or asks for no answer. */
+	async ack(tag: string, principalId: string): Promise<boolean> {
+		const { store, dispatch, routing } = this.#options;
+		if (!(await store.ack(tag, principalId))) return false;
+		const notice = await store.of(tag, principalId);
+		if (notice)
+			this.#options.deliver(
+				{ type: "notice", notice: viewOf(notice) },
+				principalId,
+			);
+		const count = await this.#sendBadge(principalId);
+		// Their other devices stop showing it.
+		if (await store.delivered(tag, principalId))
+			await dispatch.clear(
+				principalId,
+				tag,
+				openUrl(notice?.open, routing),
+				count,
+			);
+		for (const listener of this.#listeners) {
+			try {
+				listener(tag, principalId);
+			} catch (error) {
+				this.#options.logger.warn({ err: error, tag }, "an ack listener threw");
+			}
+		}
+		return true;
+	}
+
+	/** Records a receipt from the service worker; false when the notice is not addressed to the person. */
+	receipt(
+		tag: string,
+		principalId: string,
+		event: "received" | "opened",
+	): Promise<boolean> {
+		return this.#options.store.receipt(tag, principalId, event);
+	}
+
+	/** The count the app icon shows for the person: their notices not handled. */
+	badge(principalId: string): Promise<number> {
+		return this.#options.store.unhandled(principalId);
+	}
+
+	/** The frames a socket gets when it opens: every notice that is open for the person, and the count. */
+	async frames(principalId: string): Promise<ServerFrame[]> {
+		const { notices, badge } = await this.listFor(principalId);
+		return [
+			...notices.map((notice): ServerFrame => ({ type: "notice", notice })),
+			{ type: "badge", count: badge },
+		];
+	}
+
+	// ── Inside ──
+
+	#checkVia(via: readonly string[] | undefined): void {
+		if (!via) return;
+		const known = this.#options.dispatch.transports;
+		if (via.length === 0) refuse("via names no transport");
+		for (const name of via)
+			if (!known.includes(name))
+				refuse(
+					`via names ${JSON.stringify(name)}, but the sender has ${known.join(", ")}; list a host transport in push.transports`,
+				);
+	}
+
+	async #sendBadge(principalId: string): Promise<number> {
+		const count = await this.#options.store.unhandled(principalId);
+		this.#options.deliver({ type: "badge", count }, principalId);
+		return count;
+	}
+
+	/** Shows a notice to one addressee and, when asked, pushes it to their devices. */
+	async #tell(
+		tag: string,
+		principalId: string,
+		options: { push: boolean; via?: readonly string[] },
+	): Promise<void> {
+		const { store, dispatch, routing } = this.#options;
+		const notice = await store.of(tag, principalId);
+		if (!notice) return;
+		this.#options.deliver(
+			{ type: "notice", notice: viewOf(notice) },
+			principalId,
+		);
+		const count = await this.#sendBadge(principalId);
+		if (!options.push) return;
+		await dispatch.notice(principalId, {
+			tag,
+			title: notice.title,
+			...(notice.body ? { body: notice.body } : {}),
+			open: openUrl(notice.open, routing),
+			urgency: notice.urgency,
+			badge: count,
+			...(options.via ? { via: options.via } : {}),
+		});
+	}
+}

package/src/notices/store.ts

@@ -0,0 +1,298 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import type { OpenTarget } from "../web-app.ts";
+
+/** Where a tap on a notice goes. */
+export type NoticeOpen = OpenTarget;
+
+/** A notice as it is stored. */
+export interface StoredNotice {
+	tag: string;
+	title: string;
+	body?: string;
+	open?: NoticeOpen;
+	urgency: "normal" | "high";
+	ackable: boolean;
+	raisedAt: Date;
+	resolvedAt?: Date;
+	resolvedBy?: string;
+	reason?: string;
+}
+
+/** One notice with the state of the person it is shown to. */
+export interface NoticeFor extends StoredNotice {
+	ackedAt?: Date;
+}
+
+interface NoticeRow {
+	tag: string;
+	title: string;
+	body: string | null;
+	open: NoticeOpen | string | null;
+	urgency: "normal" | "high";
+	ackable: boolean;
+	raised_at: Date;
+	resolved_at: Date | null;
+	resolved_by: string | null;
+	reason: string | null;
+	acked_at?: Date | null;
+}
+
+/** A jsonb column as the driver hands it back: parsed, or as text. */
+function openOf(value: NoticeRow["open"]): NoticeOpen | undefined {
+	if (value === null) return undefined;
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value) as NoticeOpen;
+	} catch {
+		return undefined;
+	}
+}
+
+const noticeOf = (row: NoticeRow): StoredNotice => {
+	const open = openOf(row.open);
+	return {
+		tag: row.tag,
+		title: row.title,
+		...(row.body === null ? {} : { body: row.body }),
+		...(open ? { open } : {}),
+		urgency: row.urgency,
+		ackable: row.ackable,
+		raisedAt: row.raised_at,
+		...(row.resolved_at ? { resolvedAt: row.resolved_at } : {}),
+		...(row.resolved_by ? { resolvedBy: row.resolved_by } : {}),
+		...(row.reason ? { reason: row.reason } : {}),
+	};
+};
+
+/** Resolved notices are kept this long, in days, and then deleted. */
+const KEEP_RESOLVED_DAYS = 30;
+
+/** What `pending` reports for a notice. */
+export interface NoticeState {
+	raisedAt: Date;
+	to: readonly string[];
+	acked: readonly { principalId: string; at: Date }[];
+	received: readonly string[];
+	opened: readonly string[];
+}
+
+/** The notices (`web_notices`) and who each one is addressed to and how they answered (`web_notice_recipients`). */
+export class NoticeStore {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-notices",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_notices (
+					tag text PRIMARY KEY,
+					title text NOT NULL,
+					body text,
+					open jsonb,
+					urgency text NOT NULL,
+					ackable boolean NOT NULL DEFAULT false,
+					raised_at timestamptz NOT NULL DEFAULT now(),
+					resolved_at timestamptz,
+					resolved_by text,
+					reason text
+				)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_notice_recipients (
+					tag text NOT NULL REFERENCES web_notices (tag) ON DELETE CASCADE,
+					principal_id text NOT NULL,
+					added_at timestamptz NOT NULL DEFAULT now(),
+					acked_at timestamptz,
+					received_at timestamptz,
+					opened_at timestamptz,
+					PRIMARY KEY (tag, principal_id)
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_notice_recipients_principal ON web_notice_recipients (principal_id)`;
+		},
+	};
+
+	/**
+	 * Raises a notice, or raises it again: the notice is replaced and reopened, and its recipients
+	 * become exactly `to`, each starting unanswered.
+	 */
+	async raise(
+		notice: Omit<
+			StoredNotice,
+			"raisedAt" | "resolvedAt" | "resolvedBy" | "reason"
+		>,
+		to: readonly string[],
+	): Promise<void> {
+		await this.#sql.begin(async (tx) => {
+			await tx`
+				INSERT INTO web_notices (tag, title, body, open, urgency, ackable)
+				VALUES (${notice.tag}, ${notice.title}, ${notice.body ?? null},
+					${notice.open ? JSON.stringify(notice.open) : null}::jsonb,
+					${notice.urgency}, ${notice.ackable})
+				ON CONFLICT (tag) DO UPDATE SET
+					title = EXCLUDED.title, body = EXCLUDED.body, open = EXCLUDED.open,
+					urgency = EXCLUDED.urgency, ackable = EXCLUDED.ackable,
+					raised_at = now(), resolved_at = NULL, resolved_by = NULL, reason = NULL`;
+			await tx`DELETE FROM web_notice_recipients WHERE tag = ${notice.tag}`;
+			for (const principalId of to)
+				await tx`
+					INSERT INTO web_notice_recipients (tag, principal_id)
+					VALUES (${notice.tag}, ${principalId})`;
+		});
+	}
+
+	/** Adds recipients to an open notice and starts the ones who have not handled it over; returns who now gets it again. */
+	async renotify(
+		tag: string,
+		add: readonly string[],
+	): Promise<readonly string[] | undefined> {
+		return this.#sql.begin(async (tx) => {
+			const [found]: { tag: string }[] = await tx`
+				SELECT tag FROM web_notices WHERE tag = ${tag} AND resolved_at IS NULL FOR UPDATE`;
+			if (!found) return undefined;
+			for (const principalId of add)
+				await tx`
+					INSERT INTO web_notice_recipients (tag, principal_id)
+					VALUES (${tag}, ${principalId}) ON CONFLICT DO NOTHING`;
+			const rows: { principal_id: string }[] = await tx`
+				SELECT principal_id FROM web_notice_recipients
+				WHERE tag = ${tag} AND acked_at IS NULL ORDER BY added_at, principal_id`;
+			return rows.map((row) => row.principal_id);
+		});
+	}
+
+	/** Closes a notice; false when there is none open under the tag. */
+	async resolve(
+		tag: string,
+		by: { principalId?: string; reason: string } | undefined,
+	): Promise<readonly string[] | undefined> {
+		return this.#sql.begin(async (tx) => {
+			const rows: { tag: string }[] = await tx`
+				UPDATE web_notices SET resolved_at = now(), resolved_by = ${by?.principalId ?? null},
+					reason = ${by?.reason ?? null}
+				WHERE tag = ${tag} AND resolved_at IS NULL RETURNING tag`;
+			if (rows.length === 0) return undefined;
+			const to: { principal_id: string }[] = await tx`
+				SELECT principal_id FROM web_notice_recipients WHERE tag = ${tag}`;
+			return to.map((row) => row.principal_id);
+		});
+	}
+
+	/** The notice as the person sees it, if it is addressed to them. */
+	async of(tag: string, principalId: string): Promise<NoticeFor | undefined> {
+		const [row]: NoticeRow[] = await this.#sql`
+			SELECT n.*, r.acked_at FROM web_notices n
+			JOIN web_notice_recipients r ON r.tag = n.tag
+			WHERE n.tag = ${tag} AND r.principal_id = ${principalId}`;
+		return row ? this.#forPerson(row) : undefined;
+	}
+
+	/** The notices not resolved that are addressed to the person, newest first. */
+	async openFor(principalId: string): Promise<NoticeFor[]> {
+		const rows: NoticeRow[] = await this.#sql`
+			SELECT n.*, r.acked_at FROM web_notices n
+			JOIN web_notice_recipients r ON r.tag = n.tag
+			WHERE r.principal_id = ${principalId} AND n.resolved_at IS NULL
+			ORDER BY n.raised_at DESC, n.tag
+			LIMIT 200`;
+		return rows.map((row) => this.#forPerson(row));
+	}
+
+	#forPerson(row: NoticeRow): NoticeFor {
+		return {
+			...noticeOf(row),
+			...(row.acked_at ? { ackedAt: row.acked_at } : {}),
+		};
+	}
+
+	/** How many notices the person has to handle: addressed to them, open, wanting an answer and not acked. */
+	async unhandled(principalId: string): Promise<number> {
+		const [found]: { n: number }[] = await this.#sql`
+			SELECT count(*)::int AS n FROM web_notices n
+			JOIN web_notice_recipients r ON r.tag = n.tag
+			WHERE r.principal_id = ${principalId} AND n.resolved_at IS NULL
+				AND n.ackable AND r.acked_at IS NULL`;
+		return found?.n ?? 0;
+	}
+
+	/** Marks a notice handled by the person; false when it is not addressed to them, not open, or not ackable. */
+	async ack(tag: string, principalId: string): Promise<boolean> {
+		const rows: unknown[] = await this.#sql`
+			UPDATE web_notice_recipients r SET acked_at = COALESCE(r.acked_at, now())
+			FROM web_notices n
+			WHERE n.tag = r.tag AND r.tag = ${tag} AND r.principal_id = ${principalId}
+				AND n.resolved_at IS NULL AND n.ackable
+			RETURNING r.tag`;
+		return rows.length > 0;
+	}
+
+	/**
+	 * Records that the person's device received or opened the notice; false when the notice is not
+	 * addressed to them. The first time of each is kept.
+	 */
+	async receipt(
+		tag: string,
+		principalId: string,
+		event: "received" | "opened",
+	): Promise<boolean> {
+		const rows: unknown[] =
+			event === "received"
+				? await this.#sql`
+					UPDATE web_notice_recipients SET received_at = COALESCE(received_at, now())
+					WHERE tag = ${tag} AND principal_id = ${principalId} RETURNING tag`
+				: await this.#sql`
+					UPDATE web_notice_recipients SET opened_at = COALESCE(opened_at, now())
+					WHERE tag = ${tag} AND principal_id = ${principalId} RETURNING tag`;
+		return rows.length > 0;
+	}
+
+	async pending(tag: string): Promise<NoticeState | undefined> {
+		const [notice]: { raised_at: Date }[] = await this.#sql`
+			SELECT raised_at FROM web_notices WHERE tag = ${tag} AND resolved_at IS NULL`;
+		if (!notice) return undefined;
+		const rows: {
+			principal_id: string;
+			acked_at: Date | null;
+			received_at: Date | null;
+			opened_at: Date | null;
+		}[] = await this.#sql`
+			SELECT principal_id, acked_at, received_at, opened_at FROM web_notice_recipients
+			WHERE tag = ${tag} ORDER BY added_at, principal_id`;
+		return {
+			raisedAt: notice.raised_at,
+			to: rows.map((row) => row.principal_id),
+			acked: rows.flatMap((row) =>
+				row.acked_at
+					? [{ principalId: row.principal_id, at: row.acked_at }]
+					: [],
+			),
+			received: rows
+				.filter((row) => row.received_at)
+				.map((row) => row.principal_id),
+			opened: rows
+				.filter((row) => row.opened_at)
+				.map((row) => row.principal_id),
+		};
+	}
+
+	/** Whether a push for this tag was delivered to the person: they have a device that holds its notification. */
+	async delivered(tag: string, principalId: string): Promise<boolean> {
+		const [found]: { n: number }[] = await this.#sql`
+			SELECT count(*)::int AS n FROM web_push_outbox o
+			JOIN web_push_deliveries d ON d.outbox_id = o.id
+			WHERE o.tag = ${tag} AND o.principal_id = ${principalId}
+				AND o.kind = 'notice' AND d.result = 'sent'`;
+		return (found?.n ?? 0) > 0;
+	}
+
+	/** Deletes the notices resolved long ago; returns how many. */
+	async sweep(): Promise<number> {
+		const rows: unknown[] = await this.#sql`
+			DELETE FROM web_notices
+			WHERE resolved_at < now() - make_interval(days => ${KEEP_RESOLVED_DAYS}) RETURNING tag`;
+		return rows.length;
+	}
+}

package/src/notices/urls.ts

@@ -0,0 +1,38 @@
+import type { OpenTarget } from "../web-app.ts";
+
+/** How the page's routes are written in an address. */
+export interface RoutingOptions {
+	/** The path the console is served under, without a trailing slash. */
+	mount: string;
+	/** `path` puts the route in the path; `hash` after a `#`. */
+	routing: "path" | "hash";
+}
+
+const queryOf = (
+	query: Readonly<Record<string, string>> | undefined,
+): string => {
+	const entries = Object.entries(query ?? {});
+	if (entries.length === 0) return "";
+	return `?${new URLSearchParams(entries).toString()}`;
+};
+
+/**
+ * The address a tap on a notice or push opens, under the origin: a room (scrolled to a message
+ * when one is named), a page with its query, or the app itself when the target is absent. The
+ * service worker, and a cold start of the app, open exactly this address.
+ */
+export function openUrl(
+	open: OpenTarget | undefined,
+	routing: RoutingOptions,
+): string {
+	const base =
+		routing.routing === "path" ? `${routing.mount}/` : `${routing.mount}/#/`;
+	if (!open) return `${routing.mount}/`;
+	if ("room" in open)
+		return `${base}room/${encodeURIComponent(open.room)}${queryOf(
+			open.message === undefined
+				? undefined
+				: { message: String(open.message) },
+		)}`;
+	return `${base}p/${encodeURIComponent(open.page)}${queryOf(open.query)}`;
+}

package/src/onboarding/api.ts

@@ -0,0 +1,32 @@
+import { ConsoleHttpError as HttpError, json } from "../http.ts";
+import type { RouteArea } from "../web-app.ts";
+import type { OnboardingService } from "./service.ts";
+
+/**
+ * `GET api/onboarding` lists the steps that apply to the person; `POST api/onboarding/<step>/waive`
+ * waives a required step that offers a waiver. The principal is the session's.
+ */
+export function onboardingArea(onboarding: OnboardingService): RouteArea {
+	return {
+		area: "onboarding",
+		async handle(request, parts, { viewer }) {
+			try {
+				const [step, action] = parts;
+				if (step === undefined && request.method === "GET")
+					return json(await onboarding.view(viewer));
+				if (step !== undefined && action === "waive" && parts.length === 2) {
+					if (request.method !== "POST")
+						throw new HttpError(405, "Method not allowed.");
+					if (!(await onboarding.waive(viewer.principalId, step)))
+						throw new HttpError(400, "That step cannot be waived.");
+					return json(await onboarding.view(viewer));
+				}
+				throw new HttpError(404, "There is no such API.");
+			} catch (error) {
+				if (error instanceof HttpError)
+					return json({ error: error.message }, error.status);
+				throw error;
+			}
+		},
+	};
+}