@businessdash/sdk 0.9.60

package/src/react-analytics.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useEffect } from "react";
+
+import {
+	type InitBiabAnalyticsOptions,
+	initBiabAnalytics,
+} from "./analytics-core.js";
+
+/**
+ * <BIABAnalytics /> — privacy-conscious site analytics for React
+ * SDK consumers. Thin wrapper over `initBiabAnalytics()`; non-React
+ * consumers can import that function directly from
+ * `@businessdash/sdk/analytics-core`.
+ *
+ * Drop into the root layout once:
+ *
+ *   import { BIABAnalytics } from "@businessdash/sdk/react-analytics";
+ *
+ *   <BIABAnalytics
+ *     siteId={process.env.BIAB_SITE_ID!}
+ *     baseUrl={process.env.BIAB_PACKAGE_API_BASE_URL!}
+ *     apiKey={process.env.NEXT_PUBLIC_BIAB_PUBLIC_KEY!}
+ *   />
+ *
+ * What it does + privacy posture: see analytics-core.ts.
+ */
+export function BIABAnalytics(props: InitBiabAnalyticsOptions) {
+	// Destructure so the effect closes over the individual config values (its real
+	// dependencies) rather than the `props` object identity, which changes every render.
+	const { siteId, baseUrl, apiKey, respectDnt } = props;
+	useEffect(() => {
+		const tracker = initBiabAnalytics({
+			siteId,
+			baseUrl,
+			apiKey,
+			...(respectDnt !== undefined ? { respectDnt } : {}),
+		});
+		return () => tracker.stop();
+	}, [siteId, baseUrl, apiKey, respectDnt]);
+	return null;
+}
+
+/** BusinessDash-era name for `<BIABAnalytics />` — same component; the
+ *  original export stays for every existing consumer. */
+export const BusinessDashAnalytics = BIABAnalytics;
+
+/**
+ * Fire a custom event (e.g. "newsletter_signup_clicked") from
+ * anywhere in the consumer site. The first call boots a tracker
+ * if one isn't already running on this page; subsequent calls
+ * piggyback on the existing one.
+ */
+export function trackBiabEvent(input: {
+	siteId: string;
+	baseUrl: string;
+	apiKey: string;
+	customEventName: string;
+	path?: string;
+}): void {
+	if (typeof window === "undefined") return;
+	const tracker = initBiabAnalytics({
+		siteId: input.siteId,
+		baseUrl: input.baseUrl,
+		apiKey: input.apiKey,
+	});
+	tracker.track(
+		input.customEventName,
+		input.path ? { path: input.path } : undefined,
+	);
+	tracker.stop();
+}
+
+export type { InitBiabAnalyticsOptions } from "./analytics-core.js";
+// Re-export the core for non-React consumers convenience.
+export { initBiabAnalytics } from "./analytics-core.js";

package/src/react-attribution.tsx

@@ -0,0 +1,192 @@
+import { BUSINESS_DASH_LOGO } from "./attribution-logo.js";
+
+/**
+ * The "Powered by BusinessDash" attribution badge.
+ *
+ * Two exports:
+ *   - {@link BusinessDashFooterBanner} — the presentational badge. Pure, server-
+ *     renderable, no data fetching. Drop it in and pass `siteId`.
+ *   - {@link BusinessDashFooter} — an async Server Component that reads the site's
+ *     attribution policy first, so it renders the badge when required and lets a
+ *     paid plan hide it. Prefer this in a Next.js Server Component.
+ *
+ * ── Why server-render it ──
+ *
+ * BusinessDash verifies the badge by fetching your live domain and looking for
+ * the backlink below. If the badge is server-rendered it's in the raw HTML the
+ * check sees; if it's client-only, the check would need a headless browser to
+ * find it. So rendering it server-side isn't about stopping tampering (you own
+ * your code) — it's about the badge being *visible to the verification*.
+ *
+ * The `?ref=<siteId>` on the link is that marker. Keep it.
+ */
+
+type Variation = "block" | "inline" | "none";
+
+export interface BusinessDashFooterBannerProps {
+	/**
+	 * Your BusinessDash site id. Used to build the verifiable backlink
+	 * (`biab.app/?ref=<siteId>`). Omitting it renders a plain link with no marker
+	 * — fine visually, but a verification crawl won't credit it.
+	 */
+	siteId?: string;
+	/** Company/brand name shown after the © symbol. */
+	companyName?: string;
+	/** Year shown after the © symbol. Defaults to the current year. */
+	year?: number;
+	/** Layout variation. Defaults to "block". */
+	variation?: Variation;
+	/**
+	 * Override the link target. Defaults to `https://biab.app/?ref=<siteId>` (or
+	 * `https://biab.app` without a siteId). Only override if you know you want to
+	 * — a non-biab.app href won't verify.
+	 */
+	href?: string;
+	/**
+	 * Render nothing. Handy for a plan that's allowed to remove the badge — but
+	 * note removal is only *permitted*, not enforced, by this prop. See
+	 * {@link BusinessDashFooter}, which sets it from the live policy.
+	 */
+	hidden?: boolean;
+	/** Extra classes applied to the outer wrapper. */
+	className?: string;
+}
+
+/**
+ * The default link: the verifiable backlink when we have a siteId. Exported for
+ * tests — the `?ref` marker is what a verification crawl matches on, so it's the
+ * one bit worth pinning.
+ */
+export function resolveHref(siteId?: string, href?: string): string {
+	if (href) return href;
+	return siteId
+		? `https://biab.app/?ref=${encodeURIComponent(siteId)}`
+		: "https://biab.app";
+}
+
+export function BusinessDashFooterBanner({
+	siteId,
+	companyName = "Your Company",
+	year = new Date().getFullYear(),
+	variation = "block",
+	href,
+	hidden = false,
+	className = "",
+}: BusinessDashFooterBannerProps) {
+	if (hidden || variation === "none") return null;
+
+	const linkHref = resolveHref(siteId, href);
+
+	const content = (
+		<>
+			<span className="whitespace-nowrap text-zinc-500">
+				<span className="font-bold">&copy;</span> {year} {companyName}
+			</span>
+			<span className="text-zinc-600">&middot;</span>
+			<span className="flex items-center gap-1 whitespace-nowrap text-zinc-600">
+				Powered by
+				<a
+					aria-label="BusinessDash"
+					className="inline-flex cursor-pointer items-center opacity-90 transition-opacity hover:opacity-100"
+					href={linkHref}
+					rel="noopener"
+					target="_blank"
+				>
+					{/* A plain <img>, not next/image: this ships to any React app,
+					    and the logo is an inline data URI with nothing to optimize. */}
+					<img
+						alt="BusinessDash"
+						className="h-[24px] w-auto"
+						src={BUSINESS_DASH_LOGO}
+					/>
+				</a>
+			</span>
+		</>
+	);
+
+	if (variation === "inline") {
+		return (
+			<>
+				{/* Desktop: centered along the bottom of a relative footer */}
+				<div
+					className={`absolute bottom-0 left-0 hidden w-screen flex-wrap items-center justify-center gap-x-3 gap-y-1 pb-1 text-[13px] md:flex ${className}`}
+				>
+					{content}
+				</div>
+				{/* Small screens: static, centered */}
+				<div
+					className={`mx-auto flex w-fit flex-wrap items-center justify-center gap-x-3 gap-y-1 pb-1 text-[13px] md:hidden ${className}`}
+				>
+					{content}
+				</div>
+			</>
+		);
+	}
+
+	// block (default)
+	return (
+		<div
+			className={`mx-auto flex w-fit flex-wrap items-center justify-center gap-x-3 gap-y-1 text-[13px] ${className}`}
+		>
+			{content}
+		</div>
+	);
+}
+
+export default BusinessDashFooterBanner;
+
+/** The slice of the site client this component needs — kept structural so it
+ *  doesn't drag the whole client type in. */
+export interface AttributionPolicyReader {
+	attribution: {
+		policy: () => Promise<{ siteId: string; required: boolean }>;
+	};
+}
+
+export interface BusinessDashFooterProps
+	extends Omit<BusinessDashFooterBannerProps, "siteId" | "hidden"> {
+	/** A configured site client, e.g. `biab.site(siteId)`. */
+	client: AttributionPolicyReader;
+	/**
+	 * Ask to hide the badge. Honored ONLY when the plan permits removal
+	 * (`policy.required === false`); on a plan that requires the badge this is
+	 * ignored and the badge shows. Defaults to `false` (always show).
+	 */
+	optOut?: boolean;
+}
+
+/**
+ * Policy-aware badge for a Next.js Server Component.
+ *
+ * Reads the live attribution policy, then renders {@link BusinessDashFooterBanner}
+ * with the right `siteId` (for the marker) and an auto-resolved `hidden`: a paid
+ * plan that passed `optOut` gets a blank; a plan that requires the badge always
+ * shows it, `optOut` or not.
+ *
+ * ```tsx
+ * // app/layout.tsx (Server Component)
+ * export default async function Layout({ children }) {
+ *   return (
+ *     <>
+ *       {children}
+ *       <BusinessDashFooter client={biab.site(SITE_ID)} companyName="Acme Co" />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export async function BusinessDashFooter({
+	client,
+	optOut = false,
+	...bannerProps
+}: BusinessDashFooterProps) {
+	const policy = await client.attribution.policy();
+	const hidden = optOut && !policy.required;
+	return (
+		<BusinessDashFooterBanner
+			{...bannerProps}
+			hidden={hidden}
+			siteId={policy.siteId}
+		/>
+	);
+}

package/src/react-marketing.tsx

@@ -0,0 +1,338 @@
+/**
+ * React hooks for the schema-driven marketing-page flow.
+ *
+ * The base SDK file (`react.tsx`) is already past the workspace's
+ * "stop and ask before growing" file-size threshold, so these new hooks
+ * live alongside it in their own module. Same import target for
+ * consumers either way — both files are re-exported from `react.tsx`
+ * via the SDK's `./react` entrypoint.
+ *
+ * Hooks here intentionally bypass `useEffect`-managed sessions (the
+ * approach the older iframe surfaces use) — marketing data is plain
+ * JSON-over-fetch with process-wide caching on the client. That keeps
+ * the SSR story simple: the same `client.site(siteId).marketing.*`
+ * methods consumed in `getServerSideProps` / RSC code paths are what
+ * these hooks call client-side.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { BiabDevClient } from "./client.js";
+import type {
+	GetMarketingLocalesResponse,
+	GetMarketingPageBundleResponse,
+	GetPublishedMarketingSchemaResponse,
+	SiteMarketingSectionEntry,
+} from "./contracts.js";
+
+// ── Bundle hook ─────────────────────────────────────────────────────
+
+type BundleState =
+	| { status: "idle"; bundle: null; error: null }
+	| { status: "loading"; bundle: null; error: null }
+	| { status: "ready"; bundle: GetMarketingPageBundleResponse; error: null }
+	| { status: "error"; bundle: null; error: Error };
+
+/**
+ * Live-site bundle reader. One call returns:
+ *   - `sections`: `Record<sectionKey, {ok:true,data,source} | {ok:false,error}>`
+ *     — a malformed section degrades to empty in the consumer's renderer
+ *     instead of crashing the page.
+ *   - `seo`: a fully-shaped SEO object with brand tokens already expanded.
+ *   - `availableLocales` for the language switcher.
+ *
+ * The hook reads from the SDK's process-wide cache when present
+ * (warmed by `prefetchPageBundle()` or an earlier render on the same
+ * `(siteId, pageKey, locale)` key) and only hits the network on cache
+ * miss. `refresh()` does a `skipCache` round-trip — useful after a
+ * dashboard save that the SDK didn't initiate.
+ */
+export function useMarketingPageBundle(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+	pageKey?: string;
+	locale?: string;
+	enabled?: boolean;
+}): BundleState & { refresh: () => Promise<void> } {
+	const {
+		apiKey,
+		baseUrl,
+		siteId,
+		pageKey = "home",
+		locale = "en",
+		enabled = true,
+	} = options;
+	const client = useMemo(
+		() => new BiabDevClient({ apiKey, baseUrl }),
+		[apiKey, baseUrl],
+	);
+
+	const initial = client
+		.site(siteId)
+		.marketing.getPageBundleCached({ pageKey, locale });
+	const [state, setState] = useState<BundleState>(
+		initial
+			? { status: "ready", bundle: initial, error: null }
+			: { status: "idle", bundle: null, error: null },
+	);
+
+	const fetchOnce = useCallback(
+		async (skipCache = false) => {
+			if (!enabled) return;
+			setState({ status: "loading", bundle: null, error: null });
+			try {
+				const response = await client
+					.site(siteId)
+					.marketing.getPageBundle({ pageKey, locale }, { skipCache });
+				setState({ status: "ready", bundle: response, error: null });
+			} catch (err) {
+				setState({
+					status: "error",
+					bundle: null,
+					error: err instanceof Error ? err : new Error("Bundle load failed"),
+				});
+			}
+		},
+		[client, siteId, pageKey, locale, enabled],
+	);
+
+	useEffect(() => {
+		if (!enabled) return;
+		const hit = client
+			.site(siteId)
+			.marketing.getPageBundleCached({ pageKey, locale });
+		if (hit) {
+			setState({ status: "ready", bundle: hit, error: null });
+			return;
+		}
+		void fetchOnce(false);
+	}, [client, siteId, pageKey, locale, enabled, fetchOnce]);
+
+	return { ...state, refresh: () => fetchOnce(true) };
+}
+
+// ── Single-section convenience hook ─────────────────────────────────
+
+type SectionState<T> =
+	| { status: "idle" | "loading"; data: null; entry: null; error: null }
+	| {
+			status: "ready";
+			data: T | null;
+			entry: SiteMarketingSectionEntry | null;
+			error: null;
+	  }
+	| { status: "error"; data: null; entry: null; error: Error };
+
+/**
+ * Pull one section out of the bundle for `(pageKey, locale)`. Pass a
+ * `parse` function to validate the section data against the consumer's
+ * zod schema (this is what `defineSiteMarketingSchema(...).parseSection(...)`
+ * gives you).
+ *
+ * When the underlying section entry is `{ ok: false }`, `data` resolves
+ * to `null` so the consumer renderer can short-circuit to "render
+ * empty" without checking the entry shape.
+ */
+export function useMarketingSection<T>(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+	pageKey?: string;
+	locale?: string;
+	sectionKey: string;
+	parse?: (entry: SiteMarketingSectionEntry | null | undefined) => T | null;
+	enabled?: boolean;
+}): SectionState<T> {
+	const { apiKey, baseUrl, siteId, sectionKey, parse } = options;
+
+	// Build the inner bundle-hook options conditionally so the optional
+	// keys aren't present when the consumer didn't pass them. tsc's
+	// `exactOptionalPropertyTypes` flag distinguishes `prop: undefined`
+	// from "prop absent" and the latter is what the bundle hook expects.
+	const bundleOptions: Parameters<typeof useMarketingPageBundle>[0] = {
+		apiKey,
+		baseUrl,
+		siteId,
+	};
+	if (options.pageKey !== undefined) bundleOptions.pageKey = options.pageKey;
+	if (options.locale !== undefined) bundleOptions.locale = options.locale;
+	if (options.enabled !== undefined) bundleOptions.enabled = options.enabled;
+
+	const bundle = useMarketingPageBundle(bundleOptions);
+
+	return useMemo<SectionState<T>>(() => {
+		if (bundle.status === "loading" || bundle.status === "idle") {
+			return { status: bundle.status, data: null, entry: null, error: null };
+		}
+		if (bundle.status === "error") {
+			return { status: "error", data: null, entry: null, error: bundle.error };
+		}
+		const entry = bundle.bundle.sections[sectionKey] ?? null;
+		const data: T | null = parse
+			? parse(entry)
+			: entry?.ok
+				? (entry.data as T)
+				: null;
+		return { status: "ready", data, entry, error: null };
+	}, [bundle, sectionKey, parse]);
+}
+
+// ── SEO sub-hook ────────────────────────────────────────────────────
+
+export function useMarketingPageSeo(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+	pageKey?: string;
+	locale?: string;
+}) {
+	const bundle = useMarketingPageBundle(options);
+	return useMemo(() => {
+		if (bundle.status !== "ready") {
+			return { status: bundle.status, seo: null } as const;
+		}
+		return { status: "ready" as const, seo: bundle.bundle.seo };
+	}, [bundle]);
+}
+
+// ── Published schema (rarely changes) ────────────────────────────────
+
+type SchemaState =
+	| { status: "idle" | "loading"; schema: null; error: null }
+	| {
+			status: "ready";
+			schema: GetPublishedMarketingSchemaResponse["schema"];
+			error: null;
+	  }
+	| { status: "error"; schema: null; error: Error };
+
+/**
+ * Fetch the consumer's *published* schema once per process (cache
+ * scoped to `siteId`). Most consumers don't need this in the browser —
+ * the schema lives in their own bundle via `defineSiteMarketingSchema`
+ * — but it's the right primitive for "preview-as-other-tenant"
+ * tooling or for editors that introspect their own published artifact.
+ */
+export function usePublishedMarketingSchema(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+	enabled?: boolean;
+}): SchemaState & { refresh: () => Promise<void> } {
+	const { apiKey, baseUrl, siteId, enabled = true } = options;
+	const client = useMemo(
+		() => new BiabDevClient({ apiKey, baseUrl }),
+		[apiKey, baseUrl],
+	);
+	const [state, setState] = useState<SchemaState>({
+		status: "idle",
+		schema: null,
+		error: null,
+	});
+
+	const fetchOnce = useCallback(
+		async (skipCache = false) => {
+			if (!enabled) return;
+			setState({ status: "loading", schema: null, error: null });
+			try {
+				const response = await client
+					.site(siteId)
+					.marketing.getPublishedSchema({ skipCache });
+				setState({ status: "ready", schema: response.schema, error: null });
+			} catch (err) {
+				setState({
+					status: "error",
+					schema: null,
+					error: err instanceof Error ? err : new Error("Schema load failed"),
+				});
+			}
+		},
+		[client, siteId, enabled],
+	);
+
+	useEffect(() => {
+		void fetchOnce(false);
+	}, [fetchOnce]);
+
+	return { ...state, refresh: () => fetchOnce(true) };
+}
+
+// ── Locales + brand tokens (sites with i18n) ─────────────────────────
+
+type LocalesState =
+	| { status: "idle" | "loading"; data: null; error: null }
+	| { status: "ready"; data: GetMarketingLocalesResponse; error: null }
+	| { status: "error"; data: null; error: Error };
+
+export function useMarketingLocales(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+}): LocalesState {
+	const { apiKey, baseUrl, siteId } = options;
+	const client = useMemo(
+		() => new BiabDevClient({ apiKey, baseUrl }),
+		[apiKey, baseUrl],
+	);
+	const [state, setState] = useState<LocalesState>({
+		status: "idle",
+		data: null,
+		error: null,
+	});
+
+	// Avoid double-fires in strict mode by remembering the last
+	// `(siteId, apiKey, baseUrl)` we resolved against.
+	const inflight = useRef("");
+
+	useEffect(() => {
+		const fp = `${apiKey}|${baseUrl}|${siteId}`;
+		if (inflight.current === fp) return;
+		inflight.current = fp;
+		setState({ status: "loading", data: null, error: null });
+		client
+			.site(siteId)
+			.marketing.getLocales()
+			.then((data) => setState({ status: "ready", data, error: null }))
+			.catch((err) =>
+				setState({
+					status: "error",
+					data: null,
+					error: err instanceof Error ? err : new Error("Locales load failed"),
+				}),
+			);
+	}, [client, siteId, apiKey, baseUrl]);
+
+	return state;
+}
+
+// ── Bundle preloader ────────────────────────────────────────────────
+
+/**
+ * Stable `prefetch({ pageKey, locale })` you can wire to
+ * `<Link onPointerEnter>` / `onFocus` so the next page is already
+ * loaded by the time the visitor clicks. Idempotent — repeat calls hit
+ * the cache.
+ */
+export function useMarketingBundlePreloader(options: {
+	apiKey: string;
+	baseUrl: string;
+	siteId: string;
+}): (input?: { pageKey?: string; locale?: string }) => Promise<void> {
+	const { apiKey, baseUrl, siteId } = options;
+	const client = useMemo(
+		() => new BiabDevClient({ apiKey, baseUrl }),
+		[apiKey, baseUrl],
+	);
+	return useCallback(
+		async (input?: { pageKey?: string; locale?: string }) => {
+			try {
+				await client.site(siteId).marketing.prefetchPageBundle(input);
+			} catch {
+				// preload failures are non-fatal — the actual page render will
+				// surface the error via the bundle hook.
+			}
+		},
+		[client, siteId],
+	);
+}