pi-roundtable-web 0.24.2 → 0.26.0

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;
+			}
+		},
+	};
+}

package/src/onboarding/service.ts

@@ -0,0 +1,149 @@
+import type { IdentityService, Logger, PersonProfiles } from "pi-roundtable";
+import type { OnboardingStepView, OnboardingView } from "../api-types.ts";
+import type { Gate } from "../gate.ts";
+import type {
+	OnboardingStep,
+	StepStatus,
+	Viewer,
+	WebApp,
+	WebAppRegistry,
+} from "../web-app.ts";
+import type { OnboardingWaivers } from "./waivers.ts";
+
+type OnboardingPort = WebApp["onboarding"];
+
+/** The id of the notifications step. */
+export const PUSH_STEP = "push";
+/** The id of the step that links a provider's account. */
+export const linkStep = (provider: string): string => `link:${provider}`;
+
+export interface OnboardingServiceOptions {
+	registry: Pick<WebAppRegistry, "steps" | "step" | "prover">;
+	waivers: Pick<OnboardingWaivers, "waived" | "waive">;
+	gate: Pick<Gate, "changed">;
+	identity: Pick<IdentityService, "speakerFor" | "principal">;
+	profiles?: Pick<PersonProfiles, "of">;
+	push: WebApp["push"];
+	logger: Logger;
+}
+
+/**
+ * What a person owes before the app opens, and how they settle it. The steps are the host's
+ * (`registerStep`) and the app's own (`link:<provider>`, `push`); a step is undone until its
+ * `done` says it is, and a required one may be waived only when it offers a waiver.
+ */
+export class OnboardingService implements OnboardingPort {
+	readonly #options: OnboardingServiceOptions;
+
+	constructor(options: OnboardingServiceOptions) {
+		this.#options = options;
+	}
+
+	/** The person as a step's callbacks see them, built from their id alone. */
+	async viewerFor(principalId: string): Promise<Viewer> {
+		const { identity, profiles } = this.#options;
+		let tier: Viewer["tier"] = "member";
+		try {
+			tier = (await identity.speakerFor(principalId)).tier;
+		} catch {
+			// No tier: they are a member as far as a step is concerned.
+		}
+		const name =
+			(await profiles?.of(principalId))?.name ??
+			(await identity.principal(principalId))?.displayName ??
+			principalId;
+		return { principalId, speakerId: principalId, tier, roles: [], name };
+	}
+
+	async status(principalId: string): Promise<StepStatus[]> {
+		return this.statuses(await this.viewerFor(principalId));
+	}
+
+	/** Every step that applies to the viewer, with whether it is done or waived. */
+	async statuses(viewer: Viewer): Promise<StepStatus[]> {
+		const found: StepStatus[] = [];
+		for (const step of this.#options.registry.steps()) {
+			try {
+				if (step.applies && !(await step.applies(viewer))) continue;
+				const done = await step.done(viewer);
+				const waived =
+					!done && step.required
+						? await this.#options.waivers.waived(viewer.principalId, step.id)
+						: false;
+				found.push(statusOf(step, done, waived));
+			} catch (error) {
+				// A step that cannot be read is undone.
+				this.#options.logger.warn(
+					{ step: step.id, err: error },
+					"an onboarding step was not read",
+				);
+				found.push(statusOf(step, false, false));
+			}
+		}
+		return found;
+	}
+
+	changed(principalId: string): void {
+		this.#options.gate.changed(principalId);
+	}
+
+	/** The steps with the push state, as the onboarding page shows them. */
+	async view(viewer: Viewer): Promise<OnboardingView> {
+		const [steps, push] = await Promise.all([
+			this.statuses(viewer),
+			this.#options.push.status(viewer.principalId),
+		]);
+		return {
+			steps: steps.map(
+				(step): OnboardingStepView => ({
+					id: step.id,
+					label: step.label,
+					...(step.help ? { help: step.help } : {}),
+					...(step.builtin ? { builtin: step.builtin } : {}),
+					required: step.required,
+					open: step.open,
+					...(step.waiver ? { waiver: step.waiver } : {}),
+					done: step.done,
+					waived: step.waived,
+				}),
+			),
+			push: {
+				devices: push.devices,
+				...(push.lastReceiptAt
+					? { lastReceiptAt: push.lastReceiptAt.toISOString() }
+					: {}),
+				waived: push.waived,
+			},
+		};
+	}
+
+	/**
+	 * Waives a step for the person. Only a required step that offers a waiver can be; any other
+	 * answers false. Recorded with who and when, then the gate is asked again.
+	 */
+	async waive(principalId: string, stepId: string): Promise<boolean> {
+		const step = this.#options.registry.step(stepId);
+		if (!step?.required || !step.waiver) return false;
+		await this.#options.waivers.waive(principalId, stepId);
+		this.changed(principalId);
+		return true;
+	}
+}
+
+function statusOf(
+	step: OnboardingStep,
+	done: boolean,
+	waived: boolean,
+): StepStatus {
+	return {
+		id: step.id,
+		label: step.label,
+		...(step.help ? { help: step.help } : {}),
+		...(step.builtin ? { builtin: step.builtin } : {}),
+		required: step.required,
+		done,
+		waived,
+		open: step.open,
+		...(step.required && step.waiver ? { waiver: step.waiver } : {}),
+	};
+}

package/src/onboarding/steps.ts

@@ -0,0 +1,75 @@
+import type { IdentityService, Tier } from "pi-roundtable";
+import type { PushOutbox } from "../push/outbox.ts";
+import type { LinkProver, OnboardingStep, Viewer } from "../web-app.ts";
+import { linkStep, PUSH_STEP } from "./service.ts";
+
+export interface BuiltInStepsOptions {
+	/** `onboarding.links`: provider → required or nudge. */
+	links: Readonly<Record<string, "required" | "nudge">>;
+	/** `onboarding.push` and `onboarding.pushWaiver`. */
+	push: { mode: "required" | "nudge" | "off"; waiver: boolean };
+	/** The tiers whose people may receive push; the push step applies to these only. */
+	pushTiers: readonly Tier[];
+	prover(
+		provider: string,
+	): Pick<LinkProver, "provider" | "label" | "status"> | undefined;
+	identity: Pick<IdentityService, "identities">;
+	outbox: Pick<PushOutbox, "lastReceiptAt">;
+}
+
+/**
+ * The steps `onboarding` asks for. `link:<provider>` is done when the prover says the account is
+ * linked, or when the person has an identity of that provider from any source (a configuration, CLI
+ * or plugin link covers an owner, who never proves what the host already knows). `push` is done
+ * when a device of the person reported back within 30 days: a test push, or any notice.
+ */
+export function builtInSteps(options: BuiltInStepsOptions): OnboardingStep[] {
+	const steps: OnboardingStep[] = [];
+	for (const [provider, mode] of Object.entries(options.links)) {
+		steps.push({
+			id: linkStep(provider),
+			// Read when asked: a host registers its provers after the app has made its steps.
+			get label() {
+				return options.prover(provider)?.label ?? provider;
+			},
+			required: mode === "required",
+			builtin: "link",
+			open: { page: "profile" },
+			done: (viewer) => linked(options, provider, viewer),
+		});
+	}
+	if (options.push.mode !== "off") {
+		const required = options.push.mode === "required";
+		steps.push({
+			id: PUSH_STEP,
+			label: "Turn on notifications",
+			required,
+			builtin: "push",
+			open: { page: "onboarding" },
+			applies: (viewer) => options.pushTiers.includes(viewer.tier),
+			done: async (viewer) =>
+				(await options.outbox.lastReceiptAt(viewer.principalId)) !== undefined,
+			...(required && options.push.waiver
+				? {
+						waiver: {
+							label: "Skip for now",
+							confirm:
+								"Skip turning on notifications? You will not hear when something needs you.",
+						},
+					}
+				: {}),
+		});
+	}
+	return steps;
+}
+
+async function linked(
+	options: BuiltInStepsOptions,
+	provider: string,
+	viewer: Viewer,
+): Promise<boolean> {
+	const prover = options.prover(provider);
+	if (prover && (await prover.status(viewer.principalId)).linked) return true;
+	const identities = await options.identity.identities(viewer.principalId);
+	return identities.some((link) => link.provider === provider);
+}

package/src/onboarding/waivers.ts

@@ -0,0 +1,40 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import type { WaiverRead } from "../web-app.ts";
+
+/** The required steps people waived, with who and when, in `web_onboarding`. */
+export class OnboardingWaivers implements WaiverRead {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-onboarding",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_onboarding (
+					principal_id text NOT NULL,
+					step text NOT NULL,
+					state text NOT NULL CHECK (state IN ('waived')),
+					at timestamptz NOT NULL DEFAULT now(),
+					PRIMARY KEY (principal_id, step)
+				)`;
+		},
+	};
+
+	async waived(principalId: string, step: string): Promise<boolean> {
+		const [found]: { n: number }[] = await this.#sql`
+			SELECT count(*)::int AS n FROM web_onboarding
+			WHERE principal_id = ${principalId} AND step = ${step} AND state = 'waived'`;
+		return (found?.n ?? 0) > 0;
+	}
+
+	/** Records that the person waived the step; waiving twice keeps the first time. */
+	async waive(principalId: string, step: string): Promise<void> {
+		await this.#sql`
+			INSERT INTO web_onboarding (principal_id, step, state)
+			VALUES (${principalId}, ${step}, 'waived') ON CONFLICT DO NOTHING`;
+	}
+}