pi-roundtable-web 0.25.0 → 0.26.1

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