@businessdash/sdk 0.9.60

package/src/marketing-schema.ts

@@ -0,0 +1,395 @@
+/**
+ * Consumer-facing builder for the schema-driven marketing-page flow.
+ *
+ * The consumer's codebase is the source of truth for the content model.
+ * `defineSiteMarketingSchema()` lets them declare each section as a typed
+ * zod schema + UI metadata, and produces an artifact the SDK CLI uploads
+ * to BIAB:
+ *
+ *   const marketing = defineSiteMarketingSchema({
+ *     brandTokens: ["company.name", "company.phone", "company.email"],
+ *     sections: {
+ *       hero: section({
+ *         label: "Hero",
+ *         schema: z.object({
+ *           eyebrow: z.string().optional(),
+ *           title: z.string(),
+ *           body: z.string().optional(),
+ *           primaryCta: z.object({ label: z.string(), href: z.string() }).optional(),
+ *         }),
+ *         defaults: { title: "Built right, the first time." },
+ *         ui: {
+ *           body: { widget: "richtext" },
+ *           primaryCta: { collapsedByDefault: false },
+ *         },
+ *       }),
+ *
+ *       gallery: section({
+ *         label: "Gallery",
+ *         schema: z.object({
+ *           title: z.string().optional(),
+ *           layout: z.enum(["grid", "masonry", "carousel"]).default("grid"),
+ *           maxItems: z.number().int().positive().default(12),
+ *         }),
+ *         dataSource: { kind: "project-media", configureHref: "/dashboard/projects" },
+ *       }),
+ *     },
+ *   });
+ *
+ * Then in the consumer's pages:
+ *
+ *   const { sections } = await marketing.client.getPageBundle({ pageKey, locale });
+ *   const hero = marketing.parseSection("hero", sections.hero);  // fully typed
+ *
+ * `marketing.toJSONSchema()` produces the body the CLI uploads. The same
+ * SHA-256 canonicalization the server uses lives here too, so the CLI's
+ * claimed checksum matches what the server recomputes.
+ */
+
+import type { ZodTypeAny, z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// ── UI hint types ────────────────────────────────────────────────────
+
+/**
+ * The fixed allowlist of widget kinds. The dashboard form renderer + the
+ * server's schema validator only accept these — anything else is rejected
+ * at upload time. Keep this in lockstep with the server's
+ * `ALLOWED_FIELD_KINDS` constant in `src/server/site-data/marketing-schema.ts`.
+ */
+export const SITE_MARKETING_FIELD_WIDGETS = [
+	"text",
+	"textarea",
+	"richtext",
+	"url",
+	"email",
+	"image",
+	"number",
+	"integer",
+	"boolean",
+	"select",
+	"multiselect",
+	"color",
+	"date",
+	"markdown",
+	"array",
+	"object",
+	"dataSource",
+] as const;
+
+export type SiteMarketingFieldWidget =
+	(typeof SITE_MARKETING_FIELD_WIDGETS)[number];
+
+export const SITE_MARKETING_DATA_SOURCE_KINDS = [
+	"project-media",
+	"blog-posts",
+	"services-products",
+] as const;
+
+export type SiteMarketingDataSourceKind =
+	(typeof SITE_MARKETING_DATA_SOURCE_KINDS)[number];
+
+/**
+ * UI hints overlaid on a section's zod schema. Each key is a dotted
+ * path into the schema (e.g. `"primaryCta.label"`); the corresponding
+ * value tells the dashboard renderer which widget / options to use.
+ *
+ * `widget` is optional — the renderer infers a sensible default from
+ * the zod type (string → "text", `z.string().url()` → "url",
+ * `z.array(...)` → "array", etc.). Override only when the inferred
+ * default isn't right (e.g. a string that should render as "richtext").
+ */
+export type SiteMarketingFieldUI = {
+	widget?: SiteMarketingFieldWidget;
+	label?: string;
+	helpText?: string;
+	placeholder?: string;
+	enum?: readonly string[];
+	collapsedByDefault?: boolean;
+	rows?: number;
+	min?: number;
+	max?: number;
+};
+
+export type SiteMarketingDataSourceMarker = {
+	kind: SiteMarketingDataSourceKind;
+	/** Where the dashboard's "Configure data source →" button links to. */
+	configureHref: string;
+	/** Optional human-readable note shown beside the configure CTA. */
+	helpText?: string;
+};
+
+// ── Section + schema builders ────────────────────────────────────────
+
+export type SiteMarketingSectionDef<S extends ZodTypeAny = ZodTypeAny> = {
+	label: string;
+	description?: string;
+	icon?: string;
+	schema: S;
+	defaults?: Partial<z.input<S>>;
+	ui?: Record<string, SiteMarketingFieldUI>;
+	/** When set, the dashboard renders a "Configure data source →" tile
+	 *  instead of editing the row as a regular form. Items come from the
+	 *  named BIAB module at render time. */
+	dataSource?: SiteMarketingDataSourceMarker;
+};
+
+/**
+ * Helper that exists solely so consumers can write
+ *   section({ ... })
+ * instead of having to specify the zod-typed generic. Inference is
+ * preserved end-to-end.
+ */
+export function section<S extends ZodTypeAny>(
+	def: SiteMarketingSectionDef<S>,
+): SiteMarketingSectionDef<S> {
+	return def;
+}
+
+/**
+ * Optional `contentSync` configuration consumed by the
+ * `biab-dev sync-content` CLI command. Lets the consumer declare:
+ *   - Where local JSON content lives on disk
+ *   - Which directories map to which BIAB pageKeys (explicit) or to
+ *     follow a glob convention (auto-derived)
+ *   - Which filename → sectionKey aliases are needed (e.g.
+ *     `marquee.json` actually means `trustMarquee`)
+ *   - Which locales to sync (defaults to ["en"])
+ *
+ * The default layout is `<rootDir>/<locale>/<page>/<section>.json`,
+ * which matches the convention emitted by the `@businessdash/sdk` content
+ * loader (`getContent`). For trees that wrap pages in an intermediate
+ * segment (e.g. `<rootDir>/<locale>/pages/<page>/`) or that keep
+ * cross-page content in a sibling dir (e.g. `<locale>/shared/`),
+ * supply an explicit `pages` array.
+ */
+export type SiteMarketingContentSyncConfig = {
+	/** Directory (relative to `biab.config.*`) where JSON content trees live. */
+	rootDir: string;
+	/**
+	 * Explicit page directories. Each entry maps a filesystem path
+	 * (relative to `rootDir`, with optional `{locale}` placeholder) to
+	 * a `pageKey` in BIAB. When omitted, the CLI auto-discovers using
+	 * `<rootDir>/<locale>/*` and uses the leaf dir name as the pageKey.
+	 *
+	 * Example for a `<locale>/pages/<name>/` + `<locale>/shared/` layout:
+	 *   pages: [
+	 *     { dir: "{locale}/shared", pageKey: "shared" },
+	 *     { dir: "{locale}/pages/home", pageKey: "home" },
+	 *     { dir: "{locale}/pages/about", pageKey: "about" },
+	 *   ]
+	 */
+	pages?: ReadonlyArray<{ dir: string; pageKey: string }>;
+	/**
+	 * Maps a file basename (without `.json`) → schema sectionKey.
+	 * Supports both:
+	 *   - `"<basename>"` — global alias (e.g. `"marquee": "trustMarquee"`)
+	 *   - `"<pageKey>/<basename>"` — scoped alias (e.g.
+	 *     `"about/page": "aboutPage"`). Scoped takes precedence.
+	 */
+	sectionAliases?: Record<string, string>;
+	/**
+	 * Locales to sync. Each substitutes for `{locale}` in `pages[].dir`.
+	 * Defaults to `["en"]`.
+	 */
+	locales?: readonly string[];
+	/**
+	 * Section keys to skip — typically the ones whose data comes from
+	 * managed sources (gallery from media uploads, blogFeed from the
+	 * blog editor, pricing from services/products). The CLI will still
+	 * warn if it sees a file matching one of these, but won't upload.
+	 */
+	skipSections?: readonly string[];
+};
+
+export type SiteMarketingSchemaInput<
+	Sections extends Record<string, SiteMarketingSectionDef> = Record<
+		string,
+		SiteMarketingSectionDef
+	>,
+> = {
+	sections: Sections;
+	/**
+	 * Declared brand-token keys (e.g. `["company.name", "company.phone"]`).
+	 * The dashboard renders a token-resolution preview that highlights
+	 * any token referenced in a section value but missing from the
+	 * site's `brandTokens` map.
+	 */
+	brandTokens?: readonly string[];
+	/** Free-form metadata shipped alongside the schema (your build SHA, source repo URL, etc.). */
+	metadata?: Record<string, string | number | boolean>;
+	/** Optional config for `biab-dev sync-content`. */
+	contentSync?: SiteMarketingContentSyncConfig;
+};
+
+// ── Canonicalization + checksum ──────────────────────────────────────
+
+/**
+ * Sort keys recursively before serialization so two functionally
+ * identical schemas hash to the same SHA-256. Mirrors the server's
+ * canonicalization byte-for-byte — the CLI's claimed checksum has to
+ * match what the server recomputes.
+ */
+function canonicalize(value: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const out: Record<string, unknown> = {};
+	for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+		if (k === "__proto__" || k === "constructor" || k === "prototype") {
+			continue;
+		}
+		out[k] = canonicalize((value as Record<string, unknown>)[k]);
+	}
+	return out;
+}
+
+/**
+ * Web Crypto `crypto.subtle.digest` is async, so this returns a promise.
+ * Node ≥ 18 ships `globalThis.crypto.subtle`. The CLI awaits this once
+ * before POSTing — no per-request cost.
+ */
+async function sha256Hex(input: string): Promise<string> {
+	const buf = new TextEncoder().encode(input);
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", buf);
+	return Array.from(new Uint8Array(digest))
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+export async function computeSiteMarketingSchemaChecksum(
+	schemaBody: Record<string, unknown>,
+): Promise<string> {
+	return sha256Hex(JSON.stringify(canonicalize(schemaBody)));
+}
+
+// ── Build the JSON-Schema artifact ──────────────────────────────────
+
+function uiTreeFromZod(
+	uiOverrides: Record<string, SiteMarketingFieldUI> | undefined,
+): Record<string, SiteMarketingFieldUI> {
+	if (!uiOverrides) return {};
+	const out: Record<string, SiteMarketingFieldUI> = {};
+	for (const [path, hint] of Object.entries(uiOverrides)) {
+		if (
+			path === "__proto__" ||
+			path === "constructor" ||
+			path === "prototype"
+		) {
+			continue;
+		}
+		out[path] = hint;
+	}
+	return out;
+}
+
+export type SiteMarketingSchemaArtifact = {
+	$schema: "https://biab.app/schemas/marketing/v1";
+	version: 1;
+	brandTokens: readonly string[];
+	metadata: Record<string, string | number | boolean>;
+	sections: Record<
+		string,
+		{
+			label: string;
+			description?: string;
+			icon?: string;
+			schema: Record<string, unknown>;
+			defaults?: unknown;
+			ui?: Record<string, SiteMarketingFieldUI>;
+			dataSource?: SiteMarketingDataSourceMarker;
+		}
+	>;
+};
+
+export type SiteMarketingClientShape<
+	Sections extends Record<string, SiteMarketingSectionDef>,
+> = {
+	/** Reusable section schemas keyed by section key — handy for runtime parsing. */
+	readonly sections: Sections;
+	/** Optional file-tree → BIAB mapping for the `sync-content` CLI. */
+	readonly contentSync: SiteMarketingContentSyncConfig | undefined;
+	/** JSON-Schema artifact ready to upload to BIAB. */
+	toJSONSchema(): SiteMarketingSchemaArtifact;
+	/** SHA-256 hex digest of the canonicalized JSON-Schema artifact. */
+	checksum(): Promise<string>;
+	/**
+	 * Type-safe parser for a value returned by `getPageBundle`'s
+	 * `sections[key]` payload. Returns `null` when the section is
+	 * absent or its `ok: false`.
+	 */
+	parseSection<K extends keyof Sections>(
+		key: K,
+		entry: { ok: true; data: unknown } | { ok: false } | null | undefined,
+	): z.output<Sections[K]["schema"]> | null;
+};
+
+export function defineSiteMarketingSchema<
+	Sections extends Record<string, SiteMarketingSectionDef>,
+>(
+	input: SiteMarketingSchemaInput<Sections>,
+): SiteMarketingClientShape<Sections> {
+	const { sections, brandTokens = [], metadata = {}, contentSync } = input;
+
+	let cachedArtifact: SiteMarketingSchemaArtifact | null = null;
+
+	function build(): SiteMarketingSchemaArtifact {
+		if (cachedArtifact) return cachedArtifact;
+		const out: SiteMarketingSchemaArtifact = {
+			$schema: "https://biab.app/schemas/marketing/v1",
+			version: 1,
+			brandTokens: [...brandTokens],
+			metadata: { ...metadata },
+			sections: {},
+		};
+		for (const [key, def] of Object.entries(sections) as [
+			string,
+			SiteMarketingSectionDef,
+		][]) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") {
+				continue;
+			}
+			const jsonSchema = zodToJsonSchema(def.schema, {
+				$refStrategy: "none",
+				target: "jsonSchema7",
+			}) as Record<string, unknown>;
+			const sectionEntry: SiteMarketingSchemaArtifact["sections"][string] = {
+				label: def.label,
+				schema: jsonSchema,
+				ui: uiTreeFromZod(def.ui),
+			};
+			if (def.description !== undefined)
+				sectionEntry.description = def.description;
+			if (def.icon !== undefined) sectionEntry.icon = def.icon;
+			if (def.defaults !== undefined) sectionEntry.defaults = def.defaults;
+			if (def.dataSource !== undefined)
+				sectionEntry.dataSource = def.dataSource;
+			out.sections[key] = sectionEntry;
+		}
+		cachedArtifact = out;
+		return out;
+	}
+
+	return {
+		sections,
+		contentSync,
+		toJSONSchema: build,
+		async checksum() {
+			const artifact = build();
+			return computeSiteMarketingSchemaChecksum(
+				artifact as unknown as Record<string, unknown>,
+			);
+		},
+		parseSection<K extends keyof Sections>(
+			key: K,
+			entry: { ok: true; data: unknown } | { ok: false } | null | undefined,
+		): z.output<Sections[K]["schema"]> | null {
+			if (!entry || entry.ok === false) return null;
+			const def = sections[key];
+			if (!def) return null;
+			const parsed = def.schema.safeParse(entry.data);
+			return parsed.success
+				? (parsed.data as z.output<Sections[K]["schema"]>)
+				: null;
+		},
+	};
+}

package/src/mcp.ts

@@ -0,0 +1,108 @@
+/**
+ * Serve your business's MCP connector from YOUR domain.
+ *
+ * The platform's host-resolved `/api/mcp` only exists on sites the platform
+ * serves. If you host your own app with the SDK, mount these two handlers
+ * and your domain gains the same connector surface — so the URL an org
+ * hands to Claude / ChatGPT / Gemini is their own site, exactly like the
+ * docs promise:
+ *
+ * ```ts
+ * // app/api/mcp/route.ts
+ * import { mcpHandler } from '@businessdash/sdk/mcp'
+ * export const { POST, GET } = mcpHandler({
+ *   siteId: process.env.BIAB_SITE_ID!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BIAB_APP_URL!, // https://www.biab.app
+ * })
+ *
+ * // app/.well-known/mcp.json/route.ts
+ * import { mcpManifestHandler } from '@businessdash/sdk/mcp'
+ * export const GET = mcpManifestHandler({
+ *   siteId: process.env.BIAB_SITE_ID!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BIAB_APP_URL!,
+ * })
+ * ```
+ *
+ * Thin by design: the body is forwarded verbatim and the platform still
+ * enforces the org's MCP opt-in and per-tool write gates — a proxy can't
+ * widen anything.
+ */
+
+export type McpProxyOptions = {
+	siteId: string;
+	/** Platform origin, e.g. "https://www.biab.app". */
+	baseUrl: string;
+};
+
+function upstream(options: McpProxyOptions): string {
+	return `${options.baseUrl.replace(/\/$/, "")}/api/public/mcp/${encodeURIComponent(
+		options.siteId,
+	)}`;
+}
+
+/** POST proxies JSON-RPC to the platform; GET mirrors the spec's 405. */
+export function mcpHandler(options: McpProxyOptions): {
+	POST: (request: Request) => Promise<Response>;
+	GET: () => Promise<Response>;
+} {
+	const target = upstream(options);
+	return {
+		POST: async (request: Request) => {
+			try {
+				const res = await fetch(target, {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						Accept: request.headers.get("accept") ?? "application/json",
+					},
+					body: await request.text(),
+				});
+				const text = await res.text();
+				return new Response(text.length > 0 ? text : null, {
+					status: res.status,
+					headers: {
+						"Content-Type":
+							res.headers.get("content-type") ?? "application/json",
+						"Cache-Control": "no-store",
+					},
+				});
+			} catch {
+				return Response.json(
+					{
+						jsonrpc: "2.0",
+						id: null,
+						error: { code: -32603, message: "Upstream unavailable" },
+					},
+					{ status: 502 },
+				);
+			}
+		},
+		GET: async () =>
+			new Response(null, { status: 405, headers: { Allow: "POST" } }),
+	};
+}
+
+/** Serves `.well-known/mcp.json` with the endpoint URL pointing at YOUR domain. */
+export function mcpManifestHandler(
+	options: McpProxyOptions,
+): (request: Request) => Promise<Response> {
+	const target = `${upstream(options)}/manifest`;
+	return async (request: Request) => {
+		try {
+			const origin = new URL(request.url).origin;
+			const res = await fetch(
+				`${target}?origin=${encodeURIComponent(origin)}`,
+				{ next: { revalidate: 300 } } as RequestInit,
+			);
+			return new Response(await res.text(), {
+				status: res.status,
+				headers: {
+					"Content-Type": "application/json",
+					"Cache-Control": "public, max-age=300",
+				},
+			});
+		} catch {
+			return Response.json({ error: "upstream_unavailable" }, { status: 502 });
+		}
+	};
+}

package/src/native.ts

@@ -0,0 +1,73 @@
+/**
+ * `@businessdash/sdk/native` — the entry point for React Native / Expo.
+ *
+ * ## Why this exists
+ *
+ * The root export (`.`) re-exports `createAuthHandler` and `getTenantSession`
+ * from `auth-handler.ts`, which calls `Buffer.from(state, "base64url")`.
+ * `Buffer` is a Node global that React Native does not provide, and Metro does
+ * not polyfill it. The call sits inside a function rather than at module
+ * scope, so importing the root *appears* to work — right up until a sign-in
+ * callback is decoded and it throws `ReferenceError: Buffer is not defined` in
+ * production.
+ *
+ * That whole module is server-side by design anyway: an auth handler is a
+ * thing a tenant's SERVER mounts to receive an OAuth callback and set a
+ * cookie. An app has neither. Same for `proxy.ts` (a same-origin proxy route)
+ * and `revalidate-verify.ts` (`node:crypto`).
+ *
+ * So this entry is the data layer with the server-only surface removed. It is
+ * additive — nothing here changes what `.` exports.
+ *
+ * ## What a native app does instead
+ *
+ * - **Auth** — drive the hosted flow directly: `POST auth/start`, open the URL
+ *   in a web-auth session, then `POST auth/exchange` with the `code` and
+ *   `state` from your deep-link callback. `client.auth` has all three.
+ * - **Forms** — `<biab-form>` is a DOM custom element with no native
+ *   counterpart. Read the schema and render it with your own components.
+ * - **Revalidation** — irrelevant. The webhook targets a server that holds a
+ *   cache; an app just re-fetches.
+ *
+ * ## Metro
+ *
+ * Subpath exports (`@businessdash/sdk/native`) need Metro's package-exports
+ * support. Expo SDK 51+ enables it by default; on bare React Native set
+ * `unstable_enablePackageExports = true` in `metro.config.js`. Without it the
+ * import fails to resolve at all, with an error that looks like a missing
+ * dependency.
+ */
+
+export type { BiabDevClientOptions, FetchLike } from "./client.js";
+export {
+	BiabDevClient,
+	createBiabDevClient,
+} from "./client.js";
+export {
+	accessRejectionFromBody,
+	BiabAccessRejectedError,
+	BiabApiError,
+	BiabFeatureNotEntitledError,
+	BiabPaymentLapsedError,
+	type BiabPlanGateBody,
+	BiabServiceSuspendedError,
+	isBiabPlanGateBody,
+	type UnwrappedAccess,
+	type UnwrappedEntitlement,
+} from "./errors.js";
+export type {
+	BiabClient,
+	CreateBiabClientOptions,
+	FormFieldDef,
+	FormRenderSettings,
+	FormSchema,
+	FormSubmissionData,
+	FormSubmitResult,
+	FormValidationIssue,
+	GalleryResource,
+	SchedulingBookingResult,
+	SchedulingEventType,
+	SchedulingResource,
+	SchedulingSlot,
+} from "./sdk.js";
+export { createBiabClient } from "./sdk.js";

package/src/next-revalidate.ts

@@ -0,0 +1,124 @@
+/**
+ * Drop-in Next.js route handler for BIAB revalidation webhooks.
+ *
+ * Consumer mounts this with literally one line:
+ *
+ *     // app/api/biab/revalidate/route.ts
+ *     export { POST } from "@businessdash/sdk/next/revalidate";
+ *
+ * That's it. The handler:
+ *
+ *   1. Reads the shared secret from `BIAB_REVALIDATION_SECRET`
+ *      (override via `createRevalidateHandler({ secret })` if env
+ *      isn't available — see below).
+ *   2. Verifies the `X-Biab-Signature: t=<unix>,v1=<hex>` header.
+ *      Constant-time hash compare, ±5 minute replay window.
+ *   3. Calls `revalidateTag(tag, { expire: 0 })` for each tag in
+ *      the payload.
+ *   4. Returns `{ ok: true, revalidated: string[] }`.
+ *
+ * For non-Next consumers, import `verifyAndExtractTags` directly
+ * from `@businessdash/sdk/adapters/revalidate` and call your framework's
+ * invalidation primitive (CDN purge, KV delete, static rebuild
+ * trigger). The verification logic is framework-agnostic and lives
+ * in a separate file so non-Next bundlers don't transitively pick
+ * up `next/cache`.
+ */
+
+import {
+	type BiabPublishPayload,
+	type VerifyOptions,
+	type VerifyResult,
+	verifyAndExtractTags,
+} from "./revalidate-verify.js";
+
+// Re-export for backwards compatibility — callers that previously
+// imported these from `@businessdash/sdk/next/revalidate` still work.
+export {
+	type BiabPublishPayload,
+	type VerifyOptions,
+	type VerifyResult,
+	verifyAndExtractTags,
+};
+
+// ---------------------------------------------------------------------------
+// Next.js route handler
+// ---------------------------------------------------------------------------
+
+export interface CreateRevalidateHandlerOptions {
+	/**
+	 * Override the secret instead of reading from
+	 * `BIAB_REVALIDATION_SECRET`. Useful in tests or when the
+	 * consumer manages secrets in a non-standard place.
+	 */
+	secret?: string;
+}
+
+type NextRevalidateTagFn = (
+	tag: string,
+	profile: string | { expire?: number },
+) => void;
+
+async function callRevalidateTag(tags: string[]): Promise<string[]> {
+	// Lazy-import so the SDK is usable outside Next without dragging
+	// `next/cache` into the bundle. The module name lives in a variable
+	// so TypeScript doesn't try to type-check the missing dep at build
+	// time — the import is purely runtime.
+	const modName = "next/cache";
+	const mod: { revalidateTag?: NextRevalidateTagFn } | null = await import(
+		/* @vite-ignore */ /* webpackIgnore: true */ modName
+	).catch(() => null);
+	if (!mod || typeof mod.revalidateTag !== "function") {
+		return [];
+	}
+	const fn = mod.revalidateTag;
+	const revalidated: string[] = [];
+	for (const tag of tags) {
+		try {
+			fn(tag, { expire: 0 });
+			revalidated.push(tag);
+		} catch {
+			/* outside a Next request scope — caller may retry */
+		}
+	}
+	return revalidated;
+}
+
+export function createRevalidateHandler(
+	opts: CreateRevalidateHandlerOptions = {},
+) {
+	return async function POST(request: Request): Promise<Response> {
+		const secret = opts.secret ?? process.env["BIAB_REVALIDATION_SECRET"];
+		if (!secret) {
+			return Response.json(
+				{ ok: false, reason: "missing_revalidation_secret_env" },
+				{ status: 500 },
+			);
+		}
+		const rawBody = await request.text();
+		const sig = request.headers.get("x-biab-signature");
+		const verified = verifyAndExtractTags({
+			secret,
+			rawBody,
+			signatureHeader: sig,
+		});
+		if (!verified.ok || !verified.payload) {
+			return Response.json(
+				{ ok: false, reason: verified.reason ?? "verify_failed" },
+				{ status: 401 },
+			);
+		}
+		const revalidated = await callRevalidateTag(verified.payload.tags);
+		return Response.json({
+			ok: true,
+			revalidated,
+			orgId: verified.payload.orgId,
+		});
+	};
+}
+
+/**
+ * Default `POST` handler the consumer re-exports. Reads the secret
+ * from `BIAB_REVALIDATION_SECRET` env automatically.
+ */
+export const POST = createRevalidateHandler();