@businessdash/sdk 0.9.60 → 0.9.70

package/src/legal-core/index.ts

@@ -0,0 +1,276 @@
+/**
+ * `@businessdash/sdk/legal` — the org's legal pages, rendered on their site.
+ *
+ * Privacy policy, terms, refund policy: written once in the BusinessDash
+ * dashboard, and appearing on the org's own domain without anyone authoring a
+ * page for them.
+ *
+ * ## The design constraint that decides everything: your page must win
+ *
+ * A consumer who writes their own `/privacy` must keep it, and their build must
+ * not fail because we also wanted that path. There is a tempting wrong answer —
+ * generate `app/privacy/page.tsx` at install time — and it fails badly: two
+ * files claiming one route is a hard build error in Next, Remix, Nuxt, Astro,
+ * SvelteKit and TanStack Start alike. It turns "I wrote my own privacy page"
+ * into a broken deploy.
+ *
+ * So **this SDK never claims a literal path.** It gives you a resolver to mount
+ * in a CATCH-ALL route, and every one of those frameworks resolves a static
+ * segment before a catch-all:
+ *
+ * | Framework    | Your page              | The catch-all              |
+ * |--------------|------------------------|----------------------------|
+ * | Next (app)   | `app/privacy/page.tsx` | `app/[...slug]/page.tsx`   |
+ * | Remix / RR7  | `routes/privacy.tsx`   | `routes/$.tsx`             |
+ * | Astro        | `pages/privacy.astro`  | `pages/[...slug].astro`    |
+ * | Nuxt         | `pages/privacy.vue`    | `pages/[...slug].vue`      |
+ * | SvelteKit    | `routes/privacy/+page` | `routes/[...rest]/+page`   |
+ * | TanStack     | `routes/privacy.tsx`   | `routes/$.tsx`             |
+ *
+ * Write your own page and it simply shadows ours. No conflict, no build error,
+ * no configuration, and nothing to remove — the override is the framework's own
+ * routing precedence rather than anything we invented.
+ *
+ * The corollary: `resolveLegalPage()` returns `null` for a slug with no
+ * document, and your catch-all must then fall through to its normal 404. It is
+ * a resolver, not a router, precisely so it cannot swallow paths it has no
+ * business answering.
+ *
+ * ## What you render
+ *
+ * `contentHtml` is sanitised server-side when the org saves it, so it is safe
+ * to inject. The page is deliberately unstyled markup: legal pages should look
+ * like the rest of the site, and an SDK that shipped its own typography would
+ * be one more thing to override. `renderLegalPageHtml()` produces semantic HTML
+ * with stable `data-biab-legal-*` hooks you can style, or ignore entirely and
+ * build your own from the same data.
+ *
+ * @module
+ */
+
+import type {
+	LegalDocument,
+	LegalDocumentSummary,
+	LegalListResponse,
+	LegalPresentation,
+} from "../contracts.js";
+
+/** The subset of the SDK client this module needs. */
+export type LegalClientLike = {
+	legal: {
+		list(): Promise<LegalListResponse>;
+		get(slug: string): Promise<LegalDocument>;
+	};
+};
+
+/**
+ * Turn a catch-all's path segments into a slug.
+ *
+ * Accepts what each framework actually hands you — an array of segments, a
+ * joined path, with or without leading slashes — because normalising this at
+ * every call site is how the two sides end up disagreeing about `/privacy/`
+ * versus `privacy`.
+ */
+export function legalSlugFrom(input: string | string[] | undefined): string {
+	if (!input) return "";
+	const joined = Array.isArray(input) ? input.join("/") : input;
+	return joined
+		.trim()
+		.toLowerCase()
+		.replace(/^\/+|\/+$/g, "")
+		.replace(/\/{2,}/g, "/");
+}
+
+export type ResolveLegalPageOptions = {
+	client: LegalClientLike;
+	/** Whatever the catch-all captured. */
+	slug: string | string[] | undefined;
+};
+
+/**
+ * The document at this path, or null if there isn't one.
+ *
+ * **Null means fall through to your own 404.** Returning an "empty legal page"
+ * would put a bare heading reading "Privacy Policy" on every unmatched URL on
+ * the site, which is worse than a 404 in every way that matters — it is wrong
+ * for users, wrong for crawlers, and hides real routing mistakes.
+ *
+ * A network failure also returns null rather than throwing. A catch-all runs on
+ * every unmatched request, and an exception there takes down paths that have
+ * nothing to do with legal pages; a 404 during an outage is recoverable, a
+ * 500 on every unknown URL is not.
+ */
+export async function resolveLegalPage(
+	options: ResolveLegalPageOptions,
+): Promise<LegalDocument | null> {
+	const slug = legalSlugFrom(options.slug);
+	if (!slug) return null;
+	try {
+		return await options.client.legal.get(slug);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The links an org wants in their footer.
+ *
+ * Filtered on `showInFooter`, which is separate from published on purpose: an
+ * org may need a document to exist at a URL they hand to a processor without
+ * putting it in front of every visitor.
+ */
+export function legalFooterLinks(
+	list: LegalListResponse | LegalDocumentSummary[],
+	options: { basePath?: string } = {},
+): Array<{ href: string; label: string }> {
+	const items = Array.isArray(list) ? list : list.items;
+	const base = (options.basePath ?? "").replace(/\/+$/, "");
+	return items
+		.filter((doc) => doc.showInFooter)
+		.map((doc) => ({ href: `${base}/${doc.slug}`, label: doc.title }));
+}
+
+/** Escape text destined for markup. Titles are plain text, not HTML. */
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+/**
+ * "Last updated" text, or null when the org never set a date.
+ *
+ * Uses `effectiveDate` in preference to `updatedAt`: a typo fix bumps
+ * `updatedAt` and should not tell every reader the terms changed. The org
+ * decides when a change was material by setting the effective date.
+ *
+ * ## Formatted in UTC, deliberately
+ *
+ * The dashboard stores a calendar date as midnight UTC, so formatting in the
+ * READER's zone shifts it a day for everyone west of UTC — an effective date of
+ * 1 August renders as "July 31" in New York. On a marketing page that is a
+ * cosmetic bug; on a document whose whole purpose is to say when terms changed,
+ * it is a wrong date shown to roughly half the audience.
+ */
+export function legalLastUpdated(
+	document: Pick<LegalDocument, "effectiveDate">,
+	locale?: string,
+): string | null {
+	if (!document.effectiveDate) return null;
+	const date = new Date(document.effectiveDate);
+	if (Number.isNaN(date.getTime())) return null;
+	return date.toLocaleDateString(locale, {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+		timeZone: "UTC",
+	});
+}
+
+export type RenderLegalPageOptions = {
+	/** Wrapped around everything. Defaults to `biab-legal`. */
+	className?: string;
+	/** Locale for the "Last updated" line. */
+	locale?: string;
+	/** Where the logo links to. Defaults to `/`. */
+	homeHref?: string;
+};
+
+/**
+ * Semantic markup for one document: header, title, body, footer.
+ *
+ * Unstyled by design. Every element carries a stable `data-biab-legal-*`
+ * attribute so a stylesheet can reach it, and none carries a class you would
+ * have to fight. If you want a different structure, read the same fields off
+ * the document and build your own — this is a convenience, not a requirement.
+ *
+ * `contentHtml`, `headerHtml` and `footerHtml` are inserted as-is because they
+ * were sanitised when the org saved them. The title and logo URL are escaped
+ * here, since they are plain values that have never been through a sanitiser.
+ */
+export function renderLegalPageHtml(
+	document: LegalDocument,
+	options: RenderLegalPageOptions = {},
+): string {
+	const presentation = document.presentation;
+	const className = options.className ?? "biab-legal";
+	const homeHref = options.homeHref ?? "/";
+	const updated = legalLastUpdated(document, options.locale);
+
+	const logo = (where: "header" | "footer") => {
+		const show =
+			where === "header"
+				? presentation.showLogoInHeader
+				: presentation.showLogoInFooter;
+		if (!show || !presentation.logoUrl) return "";
+		return (
+			`<a href="${escapeHtml(homeHref)}" data-biab-legal-logo-link>` +
+			`<img src="${escapeHtml(presentation.logoUrl)}" alt="" data-biab-legal-logo="${where}" />` +
+			"</a>"
+		);
+	};
+
+	const parts = [
+		`<article class="${escapeHtml(className)}" data-biab-legal>`,
+		"<header data-biab-legal-header>",
+		logo("header"),
+		presentation.headerHtml ?? "",
+		`<h1 data-biab-legal-title>${escapeHtml(document.title)}</h1>`,
+		updated
+			? `<p data-biab-legal-updated>Last updated: ${escapeHtml(updated)}</p>`
+			: "",
+		"</header>",
+		`<div data-biab-legal-body>${document.contentHtml}</div>`,
+		"<footer data-biab-legal-footer>",
+		presentation.footerHtml ?? "",
+		logo("footer"),
+		"</footer>",
+		"</article>",
+	];
+	return parts.filter(Boolean).join("");
+}
+
+/**
+ * Page metadata for a legal document.
+ *
+ * `noindex` is deliberately NOT set. Legal pages should be indexable: people
+ * search for "acme refund policy", and app stores and payment processors check
+ * that the URL you gave them resolves to something a crawler can see.
+ *
+ * Feed this to `@businessdash/sdk/seo-core`'s adapters, or spread it into your
+ * framework's own metadata export.
+ */
+export function legalPageSeo(
+	document: LegalDocument,
+	options: { siteName?: string; canonical?: string } = {},
+): {
+	title: string;
+	description: string;
+	canonical?: string;
+	openGraph: { title: string; type: "article"; url?: string };
+} {
+	const title = options.siteName
+		? `${document.title} — ${options.siteName}`
+		: document.title;
+	return {
+		title,
+		// Built from the title rather than the body: the first sentence of a
+		// privacy policy is boilerplate ("This policy explains how…") and makes
+		// a description indistinguishable from every other company's.
+		description: options.siteName
+			? `The ${document.title.toLowerCase()} for ${options.siteName}.`
+			: `Read our ${document.title.toLowerCase()}.`,
+		...(options.canonical === undefined
+			? {}
+			: { canonical: options.canonical }),
+		openGraph: {
+			title,
+			type: "article",
+			...(options.canonical === undefined ? {} : { url: options.canonical }),
+		},
+	};
+}
+
+export type { LegalDocument, LegalDocumentSummary, LegalPresentation };

package/src/marketing-core/index.ts

@@ -0,0 +1,209 @@
+/**
+ * `@businessdash/sdk/marketing` — the headless marketing-page controller.
+ *
+ * Marketing pages were React-only, and the reason was accidental: the logic is
+ * a cache, a fetch and a status flag. This lifts it out so every binding can
+ * render a schema-driven page.
+ *
+ * ## Why the cache matters here specifically
+ *
+ * A site can have many marketing pages, and a visitor reads one. Fetching all
+ * of them to render one is the obvious mistake, so `open()` pulls a single page
+ * on demand, and `prefetch()` exists for the case where you know what is coming
+ * next (a nav hover, a likely next step) and want it warm before the click.
+ *
+ * The SDK client keeps its own cache; this controller does not duplicate it. It
+ * tracks WHICH page is showing and whether a request is in flight — the cache
+ * itself stays one layer down, where every framework already shares it.
+ *
+ * @module
+ */
+
+import type {
+	GetSiteMarketingPageResponse,
+	ListSiteMarketingPagesResponse,
+} from "../contracts.js";
+
+export type MarketingCoreClient = {
+	marketingPages: {
+		list(): Promise<ListSiteMarketingPagesResponse>;
+		get(
+			pageKey?: string,
+			options?: { skipCache?: boolean },
+		): Promise<GetSiteMarketingPageResponse>;
+		prefetch(pageKey?: string): Promise<GetSiteMarketingPageResponse>;
+	};
+};
+
+export type MarketingStatus = "idle" | "loading" | "ready" | "error";
+
+/** Field names are STABLE and load-bearing for every framework binding. */
+export type MarketingSnapshot = {
+	status: MarketingStatus;
+	/** Every page on the site — keys and titles, not bodies. */
+	pages: ListSiteMarketingPagesResponse["pages"];
+	/** The page currently open, or `null`. */
+	page: GetSiteMarketingPageResponse | null;
+	/** Which key `page` belongs to. */
+	pageKey: string | null;
+	error: Error | null;
+	pending: { list: boolean; page: boolean };
+};
+
+export type MarketingController = {
+	snapshot(): MarketingSnapshot;
+	subscribe(callback: (snapshot: MarketingSnapshot) => void): () => void;
+	/** Fetch the page index. */
+	load(): Promise<void>;
+	/** Fetch and show one page. */
+	open(pageKey?: string, options?: { skipCache?: boolean }): Promise<void>;
+	/** Warm a page's cache without showing it. Failures are swallowed. */
+	prefetch(pageKey?: string): Promise<void>;
+	close(): void;
+	destroy(): void;
+};
+
+export type CreateMarketingControllerOptions = {
+	client: MarketingCoreClient;
+	onError?: (error: Error) => void;
+};
+
+function toError(cause: unknown, fallback: string): Error {
+	return cause instanceof Error ? cause : new Error(fallback);
+}
+
+export function createMarketingController(
+	options: CreateMarketingControllerOptions,
+): MarketingController {
+	const { client, onError } = options;
+
+	let destroyed = false;
+	/** Guards against a slow page landing after the visitor moved on. */
+	let pageToken = 0;
+	const subscribers = new Set<(s: MarketingSnapshot) => void>();
+
+	const state: {
+		status: MarketingStatus;
+		pages: ListSiteMarketingPagesResponse["pages"];
+		page: GetSiteMarketingPageResponse | null;
+		pageKey: string | null;
+		error: Error | null;
+		pending: MarketingSnapshot["pending"];
+	} = {
+		status: "idle",
+		pages: [],
+		page: null,
+		pageKey: null,
+		error: null,
+		pending: { list: false, page: false },
+	};
+
+	let cached: MarketingSnapshot | null = null;
+
+	function snapshot(): MarketingSnapshot {
+		if (!cached) {
+			cached = {
+				status: state.status,
+				pages: state.pages,
+				page: state.page,
+				pageKey: state.pageKey,
+				error: state.error,
+				pending: state.pending,
+			};
+		}
+		return cached;
+	}
+
+	function notify(): void {
+		if (destroyed) return;
+		cached = null;
+		const next = snapshot();
+		for (const cb of subscribers) cb(next);
+	}
+
+	function fail(cause: unknown, fallback: string): void {
+		const error = toError(cause, fallback);
+		state.error = error;
+		if (state.status !== "ready") state.status = "error";
+		onError?.(error);
+	}
+
+	return {
+		snapshot,
+
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+			};
+		},
+
+		async load() {
+			if (destroyed) return;
+			state.pending.list = true;
+			state.error = null;
+			if (state.status === "idle") state.status = "loading";
+			notify();
+			try {
+				const res = await client.marketingPages.list();
+				if (destroyed) return;
+				state.pages = res.pages;
+				state.status = "ready";
+			} catch (cause) {
+				if (!destroyed) fail(cause, "Failed to load the page index.");
+			} finally {
+				if (!destroyed) {
+					state.pending.list = false;
+					notify();
+				}
+			}
+		},
+
+		async open(pageKey = "home", openOptions) {
+			if (destroyed) return;
+			const token = ++pageToken;
+			state.pending.page = true;
+			state.error = null;
+			state.pageKey = pageKey;
+			notify();
+			try {
+				const page = await client.marketingPages.get(pageKey, openOptions);
+				if (destroyed || token !== pageToken) return;
+				state.page = page;
+				state.status = "ready";
+			} catch (cause) {
+				if (destroyed || token !== pageToken) return;
+				fail(cause, `Failed to load the "${pageKey}" page.`);
+			} finally {
+				if (!destroyed && token === pageToken) {
+					state.pending.page = false;
+					notify();
+				}
+			}
+		},
+
+		async prefetch(pageKey = "home") {
+			if (destroyed) return;
+			try {
+				await client.marketingPages.prefetch(pageKey);
+			} catch {
+				// Prefetching is a guess about where the visitor is going. Being
+				// wrong, or failing, must never surface as an error on the page
+				// they are actually reading.
+			}
+		},
+
+		close() {
+			if (destroyed) return;
+			pageToken += 1; // orphan any in-flight page request
+			state.page = null;
+			state.pageKey = null;
+			notify();
+		},
+
+		destroy() {
+			destroyed = true;
+			subscribers.clear();
+		},
+	};
+}

package/src/marketing.ts

@@ -0,0 +1,7 @@
+/**
+ * `@businessdash/sdk/marketing` — the framework-agnostic marketing-page core.
+ *
+ * @module
+ */
+
+export * from "./marketing-core/index.js";