@atelic-action/ui 0.14.0 → 0.15.0

package/src/artifact/artifactConfig.ts

@@ -0,0 +1,134 @@
+/**
+ * The contract between an artifact and the components that host it.
+ *
+ * An artifact is a document, not a business's website, so this is a fraction
+ * of a marketing site's config: who it is from, who it was prepared for,
+ * where it is hosted, who may read it, and whether an open reports to the
+ * CRM. Everything a reader sees on the page itself arrives as content, never
+ * from here.
+ */
+
+/**
+ * Copy for the access-gate login screen. Present in the config so the login
+ * page is themed and worded per artifact with no code edits. The gate itself
+ * is turned on by setting GATE_SESSION_SECRET on the Vercel project, not by
+ * this block; `access` below says whether it must be. See ACCESS-GATE.md.
+ */
+export interface GateConfig {
+	/** Mono eyebrow above the headline, e.g. "Private preview". */
+	eyebrow?: string;
+	/** Login headline. */
+	headline: string;
+	/** Sub-lead under the headline. */
+	lead: string;
+	/** Fine-print attribution, e.g. "Built by Jane Maker". Defaults to the sender's name. */
+	builtBy?: string;
+	/** Contact email shown in the fine print. Defaults to the sender's email. */
+	contactEmail?: string;
+}
+
+/**
+ * A named reader, sealed. This config ships in the script every page loads,
+ * so it lists neither the reader's email nor their token: `id` is a digest
+ * of the token, and `sealed` is the email encrypted under a key derived from
+ * it. Only the reader's own link opens it (readers.ts).
+ */
+export interface ArtifactReader {
+	id: string;
+	sealed: string;
+}
+
+/**
+ * Who the document is from: the practice, on every artifact. The lockup in
+ * the header renders from `logo` exactly as the marketing chrome's does, so
+ * a client branded artifact host keeps the sender's chrome over the client's
+ * palette (GATE.md, Branding an Artifact Host).
+ */
+export interface ArtifactSender {
+	/** The sender's name, worn in the header and the gate's fine print. */
+	name: string;
+	/**
+	 * The chrome identity. `src` is the mark image; omit it for a pure text
+	 * wordmark. `tile` renders a CSS glyph tile instead of an image (a dark
+	 * rounded square bearing the given character in the brand's own webfont,
+	 * with the accent bar beneath, since an SVG-as-img mark cannot load
+	 * webfonts). `wordmark` overrides the rendered text when it should differ
+	 * from `name`; `run` appends the trailing fade bar after it.
+	 */
+	logo: { src?: string; alt: string; tile?: string; wordmark?: string; run?: boolean };
+	/** Where the header lockup points; the sender's own site. */
+	href?: string;
+	/** Reply address, shown in the access gate's fine print. */
+	email: string;
+}
+
+/** Who the document was prepared for; the business's name suffixes every title. */
+export interface ArtifactRecipient {
+	name: string;
+	/**
+	 * The recipient's mark for the header lockup ("atelic × <mark>"), cut for
+	 * the dark bar (a light mark on transparent). Unset, the header wears the
+	 * sender's lockup alone. ArtifactShell passes it to the ui header as
+	 * `brand.recipient` (@atelic-action/ui 0.6.0 and later).
+	 *
+	 * A logo is a brand mark, not a private signal, so the file lives under
+	 * public/brand/, which the access wall leaves open: the router's pending
+	 * page carries the header, so every page preloads this mark, the login
+	 * page included, and one under public/images/ would be held there. The
+	 * writeup's printed copy is white paper, so the lockup it prints in place
+	 * of the header takes a mark cut for a light ground (`recipient.logoSrc`
+	 * in the writeup's content).
+	 */
+	logo?: { src: string; alt: string };
+}
+
+export interface ArtifactConfig {
+	/** Canonical origin of the hosted twin, no trailing slash, e.g. "https://og.atelic.me". */
+	url: string;
+	/**
+	 * Who may read it, which decides where it may be hosted (the practice's
+	 * FOOTPRINT.md, Privacy). "public" when everything on it was read from
+	 * public signals, a prospect's writeup; "private" when anything came from
+	 * the owner's own consoles, which is every customer's writeup and every
+	 * monthly page. A private artifact deploys only behind the armed wall:
+	 * the build fails on Vercel without the wall's variables
+	 * (scripts/check-access.ts), and scripts/check-wall.ts proves the live
+	 * host answers with the wall before any link goes out (ACCESS-GATE.md).
+	 */
+	access: "public" | "private";
+	sender: ArtifactSender;
+	recipient: ArtifactRecipient;
+	/** Social card image; a site-relative path resolves against `url`. */
+	ogImage?: string;
+	/**
+	 * Robots line for every page. Artifacts default to "noindex, nofollow"
+	 * and there is no reason to raise it: a document handed to one business
+	 * is never search inventory.
+	 */
+	robots?: string;
+	/**
+	 * Analytics wiring. When `hubspotPortalId` is set, the HubSpot tracking
+	 * code loads and records the open; because an artifact lives on its own
+	 * host, every visit is attributable to that engagement. `hubspotRegion`
+	 * picks the loader host and defaults to "na1"; na2 portals load from
+	 * js-na2.hs-scripts.com.
+	 *
+	 * `identify` says who each link identifies, and every cut says it: a
+	 * reader for every named person a link goes to, or an empty list. When a
+	 * visit arrives with `?k=<token>` (the token on that person's link), the
+	 * visitor is identified to HubSpot by their email, so the open lands on
+	 * their contact timeline. Visits without a token stay anonymous. Mint a
+	 * reader with `bun run reader <email>`.
+	 *
+	 * A private artifact needs nobody listed: its readers sign in at the
+	 * wall and are identified by the email they signed in with. DEPLOY.md,
+	 * Who Opened It, is the procedure.
+	 */
+	analytics?: {
+		hubspotPortalId: string;
+		hubspotRegion?: "na1" | "na2" | "eu1";
+		identify: ArtifactReader[];
+	};
+	/** Copy for the access-gate login screen (see GateConfig). */
+	gate?: GateConfig;
+}

package/src/artifact/index.ts

@@ -0,0 +1,25 @@
+export { newTabProps } from "../lib/newTabProps";
+export { AppErrorBoundary } from "./AppErrorBoundary";
+export { ArtifactShell, type ArtifactShellProps } from "./ArtifactShell";
+export type {
+	ArtifactConfig,
+	ArtifactReader,
+	ArtifactRecipient,
+	ArtifactSender,
+	GateConfig,
+} from "./artifactConfig";
+export { ErrorFallback } from "./ErrorFallback";
+export { Gate, type GatePayload, type GatePerson, type GateProps, normalizeEmail } from "./Gate";
+export { GradeChip, gradeLabel } from "./GradeChip";
+export { buildPageHead, canonicalUrl, type PageMeta } from "./pageHead";
+export * from "./Report";
+export {
+	mintToken,
+	openReader,
+	readerId,
+	readerLink,
+	sealReader,
+	whoIsReading,
+} from "./readers";
+export { SignOff } from "./SignOff";
+export * from "./Writeup";

package/src/artifact/pageHead.ts

@@ -0,0 +1,58 @@
+import type { ArtifactConfig } from "./artifactConfig";
+
+export interface PageMeta {
+	/**
+	 * The page topic, e.g. "Monthly Report". The recipient's name is
+	 * appended automatically so every page reads "Topic | Business". Keep
+	 * topics short enough that the full title stays under about 60 characters.
+	 */
+	title: string;
+	/** Escape hatch: use title exactly as given, no recipient suffix. */
+	titleAbsolute?: boolean;
+	description: string;
+	/** Path from the host root, e.g. "/report". */
+	path: string;
+	ogType?: string;
+	ogImage?: string;
+	/**
+	 * Per-page robots override. Beats the artifact wide value, which is
+	 * already noindex; here so a page can never be opened up by accident.
+	 */
+	robots?: string;
+}
+
+/** Canonical URL for a path under the artifact's origin. */
+export function canonicalUrl(site: ArtifactConfig, path: string): string {
+	return path === "/" ? `${site.url}/` : `${site.url}${path}`;
+}
+
+/**
+ * Builds the head() meta and link entries for an artifact page: title,
+ * description, robots, canonical, Open Graph, and Twitter card. There is no
+ * structured data anywhere in this template on purpose. Structured data is
+ * how a page asks to be understood by a search engine, and a document sent
+ * to one business is asking nothing of the kind.
+ */
+export function buildPageHead(site: ArtifactConfig, page: PageMeta) {
+	const canonical = canonicalUrl(site, page.path);
+	// og:image must be a full URL per the OG spec; site-relative paths
+	// (self-hosted images under public/) resolve against the host origin.
+	const ogImageRaw = page.ogImage ?? site.ogImage;
+	const ogImage = ogImageRaw?.startsWith("/") ? `${site.url}${ogImageRaw}` : ogImageRaw;
+	const title = page.titleAbsolute ? page.title : `${page.title} | ${site.recipient.name}`;
+	return {
+		meta: [
+			{ title },
+			{ name: "description", content: page.description },
+			{ name: "robots", content: page.robots ?? site.robots ?? "noindex, nofollow" },
+			{ property: "og:type", content: page.ogType ?? "website" },
+			{ property: "og:site_name", content: site.recipient.name },
+			{ property: "og:title", content: page.title },
+			{ property: "og:description", content: page.description },
+			{ property: "og:url", content: canonical },
+			...(ogImage ? [{ property: "og:image", content: ogImage }] : []),
+			{ name: "twitter:card", content: "summary_large_image" },
+		],
+		links: [{ rel: "canonical", href: canonical }],
+	};
+}

package/src/artifact/readers.ts

@@ -0,0 +1,146 @@
+import type { ArtifactReader } from "./artifactConfig.js";
+
+/**
+ * Who opened it. An artifact reports every open to the practice's HubSpot
+ * portal, and an open lands on a person's contact record only when the visit
+ * says who they are. A visit says so one of two ways:
+ *
+ * - **Their link.** Every link sent to a named person carries
+ *   `?k=<their token>`, and site.config.ts lists that reader.
+ * - **The wall.** A reader who signed in on a private host is known by the
+ *   email they signed in with, read from the `gate_email` cookie.
+ *
+ * site.config.ts ships in the script every page loads, so a reader is listed
+ * sealed, never in the clear: `id` is a digest of the token, and `sealed` is
+ * the email encrypted under a key derived from the token. Only the link can
+ * open it, and the link is in one person's inbox. Reading the page's source
+ * gives nobody's address.
+ *
+ * Nothing here touches the page or the network, so it tests without a
+ * browser. The root route does the one impure thing, the push to HubSpot.
+ *
+ * This file is also built to dist/ and exported on its own as
+ * `@atelic-action/ui/artifact/readers`, because a site's browser tests and
+ * its reader script import it under Node, which runs no TypeScript inside
+ * node_modules. So it keeps the built corner's rules: no JSX, and `.js` on
+ * its relative imports.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function toBase64Url(bytes: Uint8Array): string {
+	return btoa(String.fromCharCode(...bytes))
+		.replaceAll("+", "-")
+		.replaceAll("/", "_")
+		.replaceAll("=", "");
+}
+
+function fromBase64Url(text: string): Uint8Array<ArrayBuffer> {
+	const padded = text.replaceAll("-", "+").replaceAll("_", "/");
+	return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+}
+
+async function digest(text: string): Promise<ArrayBuffer> {
+	return crypto.subtle.digest("SHA-256", encoder.encode(text));
+}
+
+/** What a config lists a token under: a digest, so the token itself never ships. */
+export async function readerId(token: string): Promise<string> {
+	const bytes = new Uint8Array(await digest(`id:${token}`));
+	return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function keyFor(token: string): Promise<CryptoKey> {
+	return crypto.subtle.importKey("raw", await digest(`key:${token}`), "AES-GCM", false, [
+		"encrypt",
+		"decrypt",
+	]);
+}
+
+/** A fresh token for one reader's links: twelve characters, safe in a URL. */
+export function mintToken(): string {
+	return toBase64Url(crypto.getRandomValues(new Uint8Array(9)));
+}
+
+/** Seal a reader's email under their token: the entry site.config.ts lists. */
+export async function sealReader(email: string, token: string): Promise<ArtifactReader> {
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const sealed = new Uint8Array(
+		await crypto.subtle.encrypt(
+			{ name: "AES-GCM", iv },
+			await keyFor(token),
+			encoder.encode(email),
+		),
+	);
+	const packed = new Uint8Array(iv.length + sealed.length);
+	packed.set(iv);
+	packed.set(sealed, iv.length);
+	return { id: await readerId(token), sealed: toBase64Url(packed) };
+}
+
+/** The email a link's token opens, or undefined when it opens nobody's. */
+export async function openReader(
+	readers: ArtifactReader[] | undefined,
+	token: string | null | undefined,
+): Promise<string | undefined> {
+	if (!token || !readers?.length) return undefined;
+	const id = await readerId(token);
+	const reader = readers.find((entry) => entry.id === id);
+	if (!reader) return undefined;
+	try {
+		const packed = fromBase64Url(reader.sealed);
+		const opened = await crypto.subtle.decrypt(
+			{ name: "AES-GCM", iv: packed.slice(0, 12) },
+			await keyFor(token),
+			packed.slice(12),
+		);
+		return decoder.decode(opened);
+	} catch {
+		return undefined;
+	}
+}
+
+function domainOf(email: string): string {
+	return email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+}
+
+/**
+ * The email this visit should be identified as, or undefined to leave it
+ * anonymous.
+ *
+ * On a private artifact the sign in decides, and a link's token never
+ * overrides it: the wall checked who this is, and a token only says who a
+ * link was sent to. So a signed in reader is identified by their own email,
+ * and a reader on the sender's domain is nobody's open even through someone
+ * else's link, since that is the practice reading its own document. A
+ * visit with no sign in (the wall not armed, as in local dev) falls back to
+ * the link.
+ *
+ * A public artifact has no wall, so a `gate_email` cookie there proves
+ * nothing and is never read: the link's token is the only identity.
+ */
+export async function whoIsReading(visit: {
+	readers: ArtifactReader[] | undefined;
+	search: string;
+	access: "public" | "private";
+	gateEmail: string;
+	senderEmail: string;
+}): Promise<string | undefined> {
+	if (visit.access === "private") {
+		const signedIn = visit.gateEmail.trim();
+		if (signedIn.includes("@")) {
+			if (domainOf(signedIn) === domainOf(visit.senderEmail)) return undefined;
+			return signedIn;
+		}
+	}
+	const token = new URLSearchParams(visit.search).get("k");
+	return openReader(visit.readers, token);
+}
+
+/** The link to send a reader: the artifact's page with their token on it. */
+export function readerLink(siteUrl: string, token: string, path = "/writeup"): string {
+	const url = new URL(path, siteUrl);
+	url.searchParams.set("k", token);
+	return url.toString();
+}