@businessdash/sdk 0.9.80 → 0.9.90

package/src/marketing-core/index.ts

@@ -22,6 +22,7 @@
 import type {
 	GetSiteMarketingPageResponse,
 	ListSiteMarketingPagesResponse,
+	SiteMarketingPage,
 } from "../contracts.js";
 
 export type MarketingCoreClient = {
@@ -68,6 +69,67 @@ export type CreateMarketingControllerOptions = {
 	onError?: (error: Error) => void;
 };
 
+/**
+ * The snapshot, reduced to what a view actually renders.
+ *
+ * Every binding needs the same four-way answer — nothing yet, working on it,
+ * here it is, that failed — and the same precedence between them. Deriving
+ * that in each binding is how they drift, so it is derived once here and the
+ * bindings just render the result.
+ */
+export type MarketingPageView =
+	| { status: "idle"; page: null }
+	| { status: "loading"; page: null }
+	| { status: "ready"; page: SiteMarketingPage | null }
+	| { status: "error"; page: null; error: Error };
+
+export type MarketingListView =
+	| { status: "idle"; pages: null }
+	| { status: "loading"; pages: null }
+	| { status: "ready"; pages: ListSiteMarketingPagesResponse["pages"] }
+	| { status: "error"; pages: null; error: Error };
+
+/**
+ * What to render for one page key.
+ *
+ * `cachedPage` is the caller's synchronous cache read. The controller cannot
+ * do it — the cache lives in the client, one layer down — but without it a
+ * page that is already cached flashes "loading" while the controller catches
+ * up, which is the exact cost the cache exists to avoid.
+ *
+ * A page WINS over an error: a stale page beside a failed refresh is more
+ * use to a visitor than an error where the content was.
+ */
+export function marketingPageView(
+	snapshot: MarketingSnapshot,
+	pageKey: string,
+	cachedPage: SiteMarketingPage | null = null,
+): MarketingPageView {
+	const fromController =
+		snapshot.pageKey === pageKey && snapshot.page ? snapshot.page.page : null;
+	const page = fromController ?? cachedPage;
+	if (page) return { status: "ready", page };
+	if (snapshot.error) {
+		return { status: "error", page: null, error: snapshot.error };
+	}
+	if (snapshot.pending.page) return { status: "loading", page: null };
+	return { status: "idle", page: null };
+}
+
+/** What to render for the page index. */
+export function marketingListView(
+	snapshot: MarketingSnapshot,
+): MarketingListView {
+	if (snapshot.error) {
+		return { status: "error", pages: null, error: snapshot.error };
+	}
+	if (snapshot.pending.list) return { status: "loading", pages: null };
+	if (snapshot.status === "ready") {
+		return { status: "ready", pages: snapshot.pages };
+	}
+	return { status: "idle", pages: null };
+}
+
 function toError(cause: unknown, fallback: string): Error {
 	return cause instanceof Error ? cause : new Error(fallback);
 }

package/src/marketing-schema.ts

@@ -4,7 +4,7 @@
  * 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:
+ * to BD:
  *
  *   const marketing = defineSiteMarketingSchema({
  *     brandTokens: ["company.name", "company.phone", "company.email"],
@@ -130,7 +130,7 @@ export type SiteMarketingSectionDef<S extends ZodTypeAny = ZodTypeAny> = {
 	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. */
+	 *  named BD module at render time. */
 	dataSource?: SiteMarketingDataSourceMarker;
 };
 
@@ -148,9 +148,9 @@ export function section<S extends ZodTypeAny>(
 
 /**
  * Optional `contentSync` configuration consumed by the
- * `biab-dev sync-content` CLI command. Lets the consumer declare:
+ * `bd 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
+ *   - Which directories map to which BD pageKeys (explicit) or to
  *     follow a glob convention (auto-derived)
  *   - Which filename → sectionKey aliases are needed (e.g.
  *     `marquee.json` actually means `trustMarquee`)
@@ -164,12 +164,12 @@ export function section<S extends ZodTypeAny>(
  * supply an explicit `pages` array.
  */
 export type SiteMarketingContentSyncConfig = {
-	/** Directory (relative to `biab.config.*`) where JSON content trees live. */
+	/** Directory (relative to `bd.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
+	 * a `pageKey` in BD. 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:
@@ -218,7 +218,7 @@ export type SiteMarketingSchemaInput<
 	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`. */
+	/** Optional config for `bd sync-content`. */
 	contentSync?: SiteMarketingContentSyncConfig;
 };
 
@@ -306,9 +306,9 @@ export type SiteMarketingClientShape<
 > = {
 	/** Reusable section schemas keyed by section key — handy for runtime parsing. */
 	readonly sections: Sections;
-	/** Optional file-tree → BIAB mapping for the `sync-content` CLI. */
+	/** Optional file-tree → BD mapping for the `sync-content` CLI. */
 	readonly contentSync: SiteMarketingContentSyncConfig | undefined;
-	/** JSON-Schema artifact ready to upload to BIAB. */
+	/** JSON-Schema artifact ready to upload to BD. */
 	toJSONSchema(): SiteMarketingSchemaArtifact;
 	/** SHA-256 hex digest of the canonicalized JSON-Schema artifact. */
 	checksum(): Promise<string>;

package/src/mcp.ts

@@ -11,15 +11,15 @@
  * // 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
+ *   siteId: process.env.BD_SITE_ID!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BD_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!,
+ *   siteId: process.env.BD_SITE_ID!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BD_APP_URL!,
  * })
  * ```
  *

package/src/native.ts

@@ -24,7 +24,7 @@
  * - **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
+ * - **Forms** — `<bd-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.
@@ -38,26 +38,26 @@
  * dependency.
  */
 
-export type { BiabDevClientOptions, FetchLike } from "./client.js";
+export type { BdApiClientOptions, FetchLike } from "./client.js";
 export {
-	BiabDevClient,
-	createBiabDevClient,
+	BdApiClient,
+	createBdApiClient,
 } from "./client.js";
 export {
 	accessRejectionFromBody,
-	BiabAccessRejectedError,
-	BiabApiError,
-	BiabFeatureNotEntitledError,
-	BiabPaymentLapsedError,
-	type BiabPlanGateBody,
-	BiabServiceSuspendedError,
-	isBiabPlanGateBody,
+	BdAccessRejectedError,
+	BdApiError,
+	BdFeatureNotEntitledError,
+	BdPaymentLapsedError,
+	type BdPlanGateBody,
+	BdServiceSuspendedError,
+	isBdPlanGateBody,
 	type UnwrappedAccess,
 	type UnwrappedEntitlement,
 } from "./errors.js";
 export type {
-	BiabClient,
-	CreateBiabClientOptions,
+	BdClient,
+	CreateBdClientOptions,
 	FormFieldDef,
 	FormRenderSettings,
 	FormSchema,
@@ -70,4 +70,4 @@ export type {
 	SchedulingResource,
 	SchedulingSlot,
 } from "./sdk.js";
-export { createBiabClient } from "./sdk.js";
+export { createBdClient } from "./sdk.js";

package/src/next-revalidate.ts

@@ -1,17 +1,17 @@
 /**
- * Drop-in Next.js route handler for BIAB revalidation webhooks.
+ * Drop-in Next.js route handler for BD revalidation webhooks.
  *
  * Consumer mounts this with literally one line:
  *
- *     // app/api/biab/revalidate/route.ts
+ *     // app/api/bd/revalidate/route.ts
  *     export { POST } from "@businessdash/sdk/next/revalidate";
  *
  * That's it. The handler:
  *
- *   1. Reads the shared secret from `BIAB_REVALIDATION_SECRET`
+ *   1. Reads the shared secret from `BD_REVALIDATION_SECRET`
  *      (override via `createRevalidateHandler({ secret })` if env
  *      isn't available — see below).
- *   2. Verifies the `X-Biab-Signature: t=<unix>,v1=<hex>` header.
+ *   2. Verifies the `X-Bd-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.
@@ -26,7 +26,7 @@
  */
 
 import {
-	type BiabPublishPayload,
+	type BdPublishPayload,
 	type VerifyOptions,
 	type VerifyResult,
 	verifyAndExtractTags,
@@ -35,7 +35,7 @@ import {
 // Re-export for backwards compatibility — callers that previously
 // imported these from `@businessdash/sdk/next/revalidate` still work.
 export {
-	type BiabPublishPayload,
+	type BdPublishPayload,
 	type VerifyOptions,
 	type VerifyResult,
 	verifyAndExtractTags,
@@ -48,7 +48,7 @@ export {
 export interface CreateRevalidateHandlerOptions {
 	/**
 	 * Override the secret instead of reading from
-	 * `BIAB_REVALIDATION_SECRET`. Useful in tests or when the
+	 * `BD_REVALIDATION_SECRET`. Useful in tests or when the
 	 * consumer manages secrets in a non-standard place.
 	 */
 	secret?: string;
@@ -88,7 +88,7 @@ export function createRevalidateHandler(
 	opts: CreateRevalidateHandlerOptions = {},
 ) {
 	return async function POST(request: Request): Promise<Response> {
-		const secret = opts.secret ?? process.env["BIAB_REVALIDATION_SECRET"];
+		const secret = opts.secret ?? process.env["BD_REVALIDATION_SECRET"];
 		if (!secret) {
 			return Response.json(
 				{ ok: false, reason: "missing_revalidation_secret_env" },
@@ -96,7 +96,7 @@ export function createRevalidateHandler(
 			);
 		}
 		const rawBody = await request.text();
-		const sig = request.headers.get("x-biab-signature");
+		const sig = request.headers.get("x-bd-signature");
 		const verified = verifyAndExtractTags({
 			secret,
 			rawBody,
@@ -119,6 +119,6 @@ export function createRevalidateHandler(
 
 /**
  * Default `POST` handler the consumer re-exports. Reads the secret
- * from `BIAB_REVALIDATION_SECRET` env automatically.
+ * from `BD_REVALIDATION_SECRET` env automatically.
  */
 export const POST = createRevalidateHandler();

package/src/notifications-core/index.ts

@@ -353,7 +353,7 @@ export function createNotificationFeed(
 /**
  * Push notifications relayed by the service worker, for tabs that are open.
  *
- * The worker shipped at `@businessdash/sdk/biab-sw.js` posts every push to its
+ * The worker shipped at `@businessdash/sdk/bd-sw.js` posts every push to its
  * clients. A worker written by hand has to do the same — post
  * `{ type: "businessdash:push", payload }` — or this source hears nothing.
  */

package/src/parallel-pages.ts

@@ -28,8 +28,8 @@
  *   });
  *
  * `defineParallelPage` is a pure builder — no DB writes, no HTTP. It
- * returns a frozen, type-checked artifact. Push to the BIAB server
- * later via `biab-dev sync-parallel-pages` (or the SDK's
+ * returns a frozen, type-checked artifact. Push to the BD server
+ * later via `bd sync-parallel-pages` (or the SDK's
  * `client.parallelPages.upsertDefinition()` when wired).
  */
 
@@ -78,7 +78,7 @@ export type ParallelPageInput<
 export type ParallelPageDefinition<
 	V extends Record<string, ParallelPageVariableInput>,
 > = {
-	readonly $kind: "biab.parallelPage";
+	readonly $kind: "bd.parallelPage";
 	readonly key: string;
 	readonly routePattern: string;
 	readonly variables: ReadonlyArray<{
@@ -166,7 +166,7 @@ export function defineParallelPage<
 	}
 
 	return Object.freeze({
-		$kind: "biab.parallelPage",
+		$kind: "bd.parallelPage",
 		key: input.key,
 		routePattern: input.routePattern,
 		variables: Object.freeze(variables),
@@ -179,7 +179,7 @@ export function defineParallelPage<
 /**
  * Type guard for the artifact `defineParallelPage` returns. Useful
  * when consumers export a mixed array of marketing + parallel-page
- * declarations from one `biab.config.ts`.
+ * declarations from one `bd.config.ts`.
  */
 export function isParallelPageDefinition(
 	value: unknown,
@@ -187,6 +187,6 @@ export function isParallelPageDefinition(
 	return (
 		!!value &&
 		typeof value === "object" &&
-		(value as { $kind?: unknown }).$kind === "biab.parallelPage"
+		(value as { $kind?: unknown }).$kind === "bd.parallelPage"
 	);
 }

package/src/portal-core/index.ts

@@ -8,7 +8,7 @@
  * not put their own customer portal on their own domain in their own design.
  *
  * This is the native path. Four things about the surface shape the design, and
- * all of them come from the audit in `Resources/BIAB-Customer-Portal-SDK-Audit.md`.
+ * all of them come from the audit in `Resources/BD-Customer-Portal-SDK-Audit.md`.
  *
  * ## 1. The session is not optional
  *

package/src/proxy.ts

@@ -1,7 +1,7 @@
 import {
-	BiabDevClient,
-	type BiabDevClientOptions,
-	BiabDevCustomerPortalClient,
+	BdApiClient,
+	type BdApiClientOptions,
+	BdCustomerPortalClient,
 } from "./client.js";
 
 /**
@@ -14,24 +14,24 @@ import {
  *
  * Pattern (Next.js example) — your tenant ships:
  *   - this client in browser bundles, configured with `proxyBaseUrl`
- *     (e.g. `/api/biab/customer-portal`).
+ *     (e.g. `/api/bd/customer-portal`).
  *   - a route at that path that calls {@link createCustomerPortalProxyHandler}
- *     with your real BIAB API key + the BIAB org id this site is pinned to.
+ *     with your real BD API key + the BD org id this site is pinned to.
  *
  * The browser client only knows the proxy URL. The bearer key never leaves
  * the tenant server.
  */
 export type BrowserCustomerPortalClientOptions = {
-	/** Same-origin proxy path or absolute URL (e.g. "/api/biab/customer-portal"). */
+	/** Same-origin proxy path or absolute URL (e.g. "/api/bd/customer-portal"). */
 	proxyBaseUrl: string;
 	fetch?: typeof fetch;
 };
 
-class BrowserBiabDevClient extends BiabDevClient {
+class BrowserBdApiClient extends BdApiClient {
 	constructor(options: BrowserCustomerPortalClientOptions) {
 		// Pass a placeholder API key — the proxy ignores the Authorization
 		// header from the browser and substitutes its own.
-		const init: BiabDevClientOptions = {
+		const init: BdApiClientOptions = {
 			baseUrl: options.proxyBaseUrl,
 			apiKey: "browser-proxy",
 		};
@@ -44,41 +44,41 @@ class BrowserBiabDevClient extends BiabDevClient {
 
 /**
  * Browser-only client that talks to your tenant's same-origin proxy route.
- * The proxy injects the BIAB API key and the `X-BIAB-Customer-Portal-Org`
+ * The proxy injects the BD API key and the `X-BD-Customer-Portal-Org`
  * pin, so the browser never sees either secret.
  */
 export function createBrowserCustomerPortalClient(
 	options: BrowserCustomerPortalClientOptions,
 ) {
-	const inner = new BrowserBiabDevClient(options);
-	return new BiabDevCustomerPortalClient(inner, null);
+	const inner = new BrowserBdApiClient(options);
+	return new BdCustomerPortalClient(inner, null);
 }
 
 /**
  * Helper for the *server-side* proxy route a tenant ships. Returns a fetch
  * handler that:
- *   - rewrites incoming request paths to the BIAB host's customer-portal API
- *   - injects the BIAB API key and `X-BIAB-Customer-Portal-Org` header
+ *   - rewrites incoming request paths to the BD host's customer-portal API
+ *   - injects the BD API key and `X-BD-Customer-Portal-Org` header
  *   - forwards the response unchanged.
  *
- * @example // app/api/biab/customer-portal/[...path]/route.ts
+ * @example // app/api/bd/customer-portal/[...path]/route.ts
  * export const GET = createCustomerPortalProxyHandler({
- *   biabBaseUrl: "https://biab.app/api/package/v1",
- *   apiKey: process.env.BIAB_API_KEY!,
- *   organizationId: process.env.BIAB_ORG_ID!,
+ *   bdBaseUrl: "https://biab.app/api/package/v1",
+ *   apiKey: process.env.BD_API_KEY!,
+ *   organizationId: process.env.BD_ORG_ID!,
  * });
  * export const POST = GET;
  */
 export type CustomerPortalProxyOptions = {
-	biabBaseUrl: string;
+	bdBaseUrl: string;
 	apiKey: string;
-	/** The BIAB organization id (`org.id` from the portal context) this site is
-	 *  pinned to. Sent as the `X-BIAB-Customer-Portal-Org` header. */
+	/** The BD organization id (`org.id` from the portal context) this site is
+	 *  pinned to. Sent as the `X-BD-Customer-Portal-Org` header. */
 	organizationId?: string;
 	/**
-	 * @deprecated Use {@link organizationId} (the BIAB org id). Still accepted —
-	 * the platform resolves the pin header by BIAB id or the legacy provider id —
-	 * but new integrations should pass the BIAB org id and drop any
+	 * @deprecated Use {@link organizationId} (the BD org id). Still accepted —
+	 * the platform resolves the pin header by BD id or the legacy provider id —
+	 * but new integrations should pass the BD org id and drop any
 	 * provider-specific env var.
 	 */
 	workosOrganizationId?: string;
@@ -112,11 +112,11 @@ export function createCustomerPortalProxyHandler(
 	options: CustomerPortalProxyOptions,
 ) {
 	const fetchImpl = options.fetch ?? fetch;
-	const base = options.biabBaseUrl.endsWith("/")
-		? options.biabBaseUrl
-		: `${options.biabBaseUrl}/`;
+	const base = options.bdBaseUrl.endsWith("/")
+		? options.bdBaseUrl
+		: `${options.bdBaseUrl}/`;
 	const siteOrigin = normalizeSiteOriginForProxy(options.siteOrigin);
-	// Prefer the BIAB org id; fall back to the deprecated provider-id alias so
+	// Prefer the BD org id; fall back to the deprecated provider-id alias so
 	// existing integrations keep working until they migrate.
 	const orgPin = options.organizationId ?? options.workosOrganizationId;
 	if (!orgPin) {
@@ -137,7 +137,7 @@ export function createCustomerPortalProxyHandler(
 
 		const upstreamHeaders = new Headers();
 		upstreamHeaders.set("Authorization", `Bearer ${options.apiKey}`);
-		upstreamHeaders.set("X-BIAB-Customer-Portal-Org", orgPin);
+		upstreamHeaders.set("X-BD-Customer-Portal-Org", orgPin);
 		upstreamHeaders.set("Accept", "application/json");
 		if (siteOrigin) {
 			upstreamHeaders.set("Origin", siteOrigin);

package/src/push-core/index.ts

@@ -159,9 +159,11 @@ export function pushPermission(): NotificationPermission | "unsupported" {
  * Backed by an explicit `ArrayBuffer` rather than `new Uint8Array(length)`:
  * TypeScript's DOM types want a `BufferSource`, and a `Uint8Array` over the
  * generic `ArrayBufferLike` (which could be a `SharedArrayBuffer`) does not
- * satisfy it.
+ * satisfy it. The return type stays UNPARAMETERISED because this shipped
+ * source is compiled by consumers' own TypeScript, and `Uint8Array<T>`
+ * only parses on 5.7+ — the one `BufferSource` call site casts instead.
  */
-function urlBase64ToUint8Array(base64: string): Uint8Array<ArrayBuffer> {
+function urlBase64ToUint8Array(base64: string): Uint8Array {
 	const padding = "=".repeat((4 - (base64.length % 4)) % 4);
 	const normalised = (base64 + padding).replace(/-/g, "+").replace(/_/g, "/");
 	const raw = atob(normalised);
@@ -200,7 +202,7 @@ export type SubscribeOptions = {
 	/** From `GET customer-portal/push`. */
 	vapidPublicKey: string;
 	/**
-	 * Path to the service worker ON YOUR ORIGIN. Defaults to `/biab-sw.js`.
+	 * Path to the service worker ON YOUR ORIGIN. Defaults to `/bd-sw.js`.
 	 *
 	 * It must be served from your own domain — a worker on someone else's
 	 * cannot receive your visitors' push. Copy the one this SDK ships.
@@ -258,7 +260,7 @@ export async function subscribeToPush(
 
 	try {
 		const registration = await navigator.serviceWorker.register(
-			options.serviceWorkerPath ?? "/biab-sw.js",
+			options.serviceWorkerPath ?? "/bd-sw.js",
 			{ scope: options.scope ?? "/" },
 		);
 		// A worker that is installing cannot take a subscription yet.
@@ -287,7 +289,11 @@ export async function subscribeToPush(
 				// Required by every browser now — a subscription without it is
 				// rejected outright rather than delivered to nobody.
 				userVisibleOnly: true,
-				applicationServerKey: urlBase64ToUint8Array(options.vapidPublicKey),
+				// The cast is sound — the bytes are ArrayBuffer-backed above —
+				// and keeps the helper's signature parseable on pre-5.7 TS.
+				applicationServerKey: urlBase64ToUint8Array(
+					options.vapidPublicKey,
+				) as BufferSource,
 			}));
 
 		return { ok: true, subscription: toPayload(subscription) };