@businessdash/sdk 0.9.60

package/package.json

@@ -0,0 +1,204 @@
+{
+	"name": "@businessdash/sdk",
+	"version": "0.9.60",
+	"description": "BusinessDash developer SDK \u2014 the data layer that lets you build customer-facing surfaces on your own domain while BusinessDash handles the operations stack behind the scenes. 0.9.x ships a comprehensive programmatic surface: storefront (products, categories, cart, checkout via Stripe Connect with Link payment), customer portal (work feed, per-item detail, quote accept/reject, job activity, comment threads, reviews, notification preferences), blog (posts, categories, threaded comments, reactions, paywalls, Mux video), Front Desk chat (sessions, AI bot, live human handoff, queue + place-in-line), coupons (validation against synced Stripe Promotion Codes \u2014 BOGO/BXGY/free-shipping kinds), shipping (multi-carrier rates + tracking via Shippo), address validation (Google Places, platform-proxied), customer notification preferences across in-app/email/SMS/webhook, subscriptions admin + Stripe sync, and followers/subscribers. Also: tenant sign-in/up/out via the auth handler, schema-driven marketing pages with restore semantics, typed JSON-LD SEO builders (LocalBusiness/Service/FAQ/Article/Breadcrumb/Review), and a CLI (`biab-dev sync-schema`) for the schema flow. The consumer renders the UI in their own design system on their own domain; BusinessDash supplies the data, the business logic, and the Stripe/Mux/Google/Shippo plumbing.",
+	"type": "module",
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"openapi.json",
+		"src"
+	],
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"biab-dev": "./dist/cli.js",
+		"businessdash": "./dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		},
+		"./contracts": {
+			"types": "./dist/contracts.d.ts",
+			"import": "./dist/contracts.js"
+		},
+		"./native": {
+			"types": "./dist/native.d.ts",
+			"import": "./dist/native.js"
+		},
+		"./enums": {
+			"types": "./dist/enums.d.ts",
+			"import": "./dist/enums.js"
+		},
+		"./graphql": {
+			"types": "./dist/graphql.d.ts",
+			"import": "./dist/graphql.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		},
+		"./forms": {
+			"types": "./dist/forms.d.ts",
+			"import": "./dist/forms.js"
+		},
+		"./collections": {
+			"types": "./dist/collections.d.ts",
+			"import": "./dist/collections.js"
+		},
+		"./static": {
+			"types": "./dist/static.d.ts",
+			"import": "./dist/static.js"
+		},
+		"./element": {
+			"types": "./dist/element.d.ts",
+			"import": "./dist/element.js"
+		},
+		"./vanilla": {
+			"types": "./dist/vanilla.d.ts",
+			"import": "./dist/vanilla.js"
+		},
+		"./vue": {
+			"types": "./src/vue/index.ts",
+			"import": "./src/vue/index.ts"
+		},
+		"./svelte": {
+			"svelte": "./src/svelte/index.ts",
+			"types": "./src/svelte/index.ts",
+			"import": "./src/svelte/index.ts"
+		},
+		"./solid": {
+			"types": "./src/solid.tsx",
+			"solid": "./src/solid.tsx",
+			"import": "./src/solid.tsx"
+		},
+		"./qwik": {
+			"types": "./src/qwik.tsx",
+			"import": "./src/qwik.tsx"
+		},
+		"./angular": {
+			"types": "./src/angular/index.ts",
+			"import": "./src/angular/index.ts"
+		},
+		"./react-analytics": {
+			"types": "./dist/react-analytics.d.ts",
+			"import": "./dist/react-analytics.js"
+		},
+		"./react-attribution": {
+			"types": "./dist/react-attribution.d.ts",
+			"import": "./dist/react-attribution.js"
+		},
+		"./analytics-core": {
+			"types": "./dist/analytics-core.d.ts",
+			"import": "./dist/analytics-core.js"
+		},
+		"./analytics-server": {
+			"types": "./dist/analytics-server.d.ts",
+			"import": "./dist/analytics-server.js"
+		},
+		"./distribution": {
+			"types": "./dist/distribution.d.ts",
+			"import": "./dist/distribution.js"
+		},
+		"./mcp": {
+			"types": "./dist/mcp.d.ts",
+			"import": "./dist/mcp.js"
+		},
+		"./proxy": {
+			"types": "./dist/proxy.d.ts",
+			"import": "./dist/proxy.js"
+		},
+		"./seo": {
+			"types": "./dist/seo.d.ts",
+			"import": "./dist/seo.js"
+		},
+		"./data-model-schema": {
+			"types": "./dist/data-model-schema.d.ts",
+			"import": "./dist/data-model-schema.js"
+		},
+		"./alpha": {
+			"types": "./dist/alpha.d.ts",
+			"import": "./dist/alpha.js"
+		},
+		"./marketing-schema": {
+			"types": "./dist/marketing-schema.d.ts",
+			"import": "./dist/marketing-schema.js"
+		},
+		"./next/revalidate": {
+			"types": "./dist/next-revalidate.d.ts",
+			"import": "./dist/next-revalidate.js"
+		},
+		"./adapters/revalidate": {
+			"types": "./dist/adapters-revalidate.d.ts",
+			"import": "./dist/adapters-revalidate.js"
+		},
+		"./biab-forms.css": "./dist/biab-forms.css"
+	},
+	"scripts": {
+		"clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true})\"",
+		"build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-cjs.js && node -e \"require('node:fs').copyFileSync('src/styles/biab-forms.css','dist/biab-forms.css')\"",
+		"openapi": "tsx scripts/openapi.ts",
+		"openapi:check": "tsx scripts/openapi.ts --check",
+		"postbuild": "node scripts/publish-types.js",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test:types": "tsc -p tsconfig.type-tests.json --noEmit",
+		"test": "tsx --test test/*.test.ts test/*.test.tsx",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"prepublishOnly": "npm run build"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Gold240sx/business-in-a-box.git",
+		"directory": "biab-dev"
+	},
+	"license": "MIT",
+	"homepage": "https://businessdash.us",
+	"keywords": [
+		"businessdash",
+		"biab",
+		"business-in-a-box",
+		"alpha"
+	],
+	"dependencies": {
+		"@js-temporal/polyfill": "^0.5.1",
+		"zod": "^3.25.76",
+		"zod-to-json-schema": "^3.25.2"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0",
+		"react-dom": ">=18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.1",
+		"@types/node": "^20.19.43",
+		"@types/react": "^19.2.17",
+		"esbuild": "^0.28.1",
+		"react": "^19.2.7",
+		"tsx": "^4.22.4",
+		"typescript": "^5.9.3"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

package/src/adapters-revalidate.ts

@@ -0,0 +1,88 @@
+/**
+ * Framework-agnostic revalidation handler builder.
+ *
+ * The Next.js drop-in at `@businessdash/sdk/next/revalidate` is the
+ * happy path for Next consumers — one-line `export { POST } from`
+ * and the handler verifies the HMAC + calls `revalidateTag`.
+ *
+ * For everything else (Cloudflare Workers, plain Node HTTP,
+ * SvelteKit, Remix, static-site rebuilds), this adapter exposes
+ * the same verification logic without the Next dependency. The
+ * consumer plugs in their own cache-invalidation callback —
+ * KV.delete, fetch(`/purge-cache`), trigger a static rebuild, etc.
+ *
+ * Usage example (Cloudflare Workers):
+ *
+ *     import { createGenericRevalidateHandler } from "@businessdash/sdk/adapters/revalidate";
+ *
+ *     const handler = createGenericRevalidateHandler({
+ *       secret: env.BIAB_REVALIDATION_SECRET,
+ *       onTagsRevalidated: async (tags) => {
+ *         for (const tag of tags) {
+ *           await env.PURGE_CACHE.fetch(new Request(`/?tag=${tag}`));
+ *         }
+ *       },
+ *     });
+ *
+ *     export default { fetch: (req) => handler(req) };
+ *
+ * The HMAC verification + replay-window logic lives in
+ * `verifyAndExtractTags` (next-revalidate.ts) and is shared.
+ */
+
+// Import directly from the framework-agnostic verifier so this
+// adapter file doesn't transitively pull in `next/cache` (which
+// some non-Next bundlers — Nuxt's Nitro, Cloudflare's workerd —
+// try to resolve at build time even when it's behind a runtime
+// dynamic import).
+export { verifyAndExtractTags } from "./revalidate-verify.js";
+
+import { verifyAndExtractTags } from "./revalidate-verify.js";
+
+export interface CreateGenericRevalidateHandlerOptions {
+	secret: string;
+	/**
+	 * Called when the request verifies and a publish event is
+	 * received. The consumer's framework-appropriate cache purge
+	 * goes here. Failures should throw so the response is 500 —
+	 * BIAB-side retry can re-deliver.
+	 */
+	onTagsRevalidated: (tags: string[], orgId: string) => Promise<void> | void;
+}
+
+export function createGenericRevalidateHandler(
+	opts: CreateGenericRevalidateHandlerOptions,
+) {
+	if (!opts.secret) {
+		throw new Error("createGenericRevalidateHandler: secret is required.");
+	}
+	return async function handle(request: Request): Promise<Response> {
+		const rawBody = await request.text();
+		const sig = request.headers.get("x-biab-signature");
+		const verified = verifyAndExtractTags({
+			secret: opts.secret,
+			rawBody,
+			signatureHeader: sig,
+		});
+		if (!verified.ok || !verified.payload) {
+			return Response.json(
+				{ ok: false, reason: verified.reason ?? "verify_failed" },
+				{ status: 401 },
+			);
+		}
+		try {
+			await opts.onTagsRevalidated(
+				verified.payload.tags,
+				verified.payload.orgId,
+			);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "callback_failed";
+			return Response.json({ ok: false, reason: message }, { status: 500 });
+		}
+		return Response.json({
+			ok: true,
+			revalidated: verified.payload.tags,
+			orgId: verified.payload.orgId,
+		});
+	};
+}

package/src/alpha.ts

@@ -0,0 +1,89 @@
+/**
+ * `@businessdash/sdk/alpha` — legacy/deprecated schema API for backward compatibility.
+ *
+ * This entrypoint re-exports the original `data-model-schema` surface exactly as
+ * it was available from `@businessdash/sdk` prior to the `0.9` entrypoint split.
+ *
+ * Use it when migrating old codebases that rely on the deprecated API:
+ *
+ * ```ts
+ * // old: import { defineDataModel, defineField, defineObject } from "@businessdash/sdk"
+ * // new:
+ * import { defineDataModel, defineField, defineObject } from "@businessdash/sdk/alpha"
+ *
+ * // Or for the full legacy surface:
+ * import * as Alpha from "@businessdash/sdk/alpha"
+ * ```
+ *
+ * New projects should use `@businessdash/sdk/collections` or `@businessdash/sdk/forms` instead.
+ */
+
+export {
+	type AddressDef,
+	type AllFormElements,
+	type BoundaryMetadata,
+	bd,
+	type ChoiceCardDef,
+	type CollectionDefinition,
+	type CollectionOptions,
+	collection,
+	computeDataModelChecksum,
+	createSchema,
+	type DataModelArtifact,
+	type DataModelClientShape,
+	type DataModelInput,
+	type DeleteAction,
+	type DynamicOptionsDef,
+	defineCollection,
+	defineDataModel,
+	defineField,
+	defineObject,
+	type ElementMetadata,
+	type EncryptionMode,
+	type ExtArrayType,
+	type ExtBooleanType,
+	type ExtNumberType,
+	type ExtObjectType,
+	type ExtractFieldPaths,
+	type ExtTextType,
+	FIELD_TYPES,
+	type FieldBuilder,
+	type FieldDefinition,
+	type FieldOptions,
+	type FieldSpec,
+	type Fields,
+	type FieldType,
+	type FileDef,
+	type FindFieldTypeByPath,
+	fields,
+	type InferJsType,
+	isFieldType,
+	isRelationFieldType,
+	type MeasurementCategory,
+	type MeasurementDef,
+	type ObjectDefinition,
+	type ObjectKind,
+	type ObjectPropertyDef,
+	type ObjectSchemaDef,
+	type ObjectVisibility,
+	objectVisibilityValues,
+	PREDEFINED_UNITS,
+	type PrimaryKeyType,
+	type RangeDef,
+	RELATION_FIELD_TYPES,
+	type RelationMetadata,
+	type RelationOnDelete,
+	type RequiredIfCondition,
+	type RlsPolicyConfig,
+	SchemaBoundary,
+	type SchemaBoundaryNode,
+	type SchemaOptions,
+	type SecureEvalRule,
+	type SelectOption,
+	type SpecialDateValue,
+	type StorageStrategy,
+	UNSUPPORTED_FIELD_TYPES,
+	type ValidationRules,
+	validateAndResolveMeasurement,
+	validateFieldValue,
+} from "./data-model-schema.js";

package/src/analytics-core.ts

@@ -0,0 +1,175 @@
+/**
+ * Framework-agnostic core for BIAB site analytics. The React
+ * component (`<BIABAnalytics />`) wraps this; Svelte/Qwik/Vue/
+ * vanilla-JS consumers call `initBiabAnalytics(opts)` directly
+ * from their framework's "on mount" hook and call the returned
+ * cleanup function in their "on unmount" hook.
+ *
+ * Same privacy posture as the React component:
+ *   - No cookies, no localStorage, no third-party requests
+ *   - Honours navigator.doNotTrack + globalPrivacyControl
+ *   - Never sees the visitor's IP or UA — those are read
+ *     server-side by the ingest endpoint and used only to
+ *     derive country + device family + a daily-rotating
+ *     anon-id hash that resets every UTC midnight.
+ */
+
+export type InitBiabAnalyticsOptions = {
+	siteId: string;
+	baseUrl: string;
+	apiKey: string;
+	/** Defaults to true. Set false only if your privacy policy
+	 *  already commits to honouring DNT/GPC and you want to
+	 *  count those visitors. */
+	respectDnt?: boolean;
+};
+
+export type BiabAnalyticsTracker = {
+	/** Tear down the listeners. Safe to call multiple times. */
+	stop: () => void;
+	/** Fire a custom event. */
+	track: (name: string, opts?: { path?: string }) => void;
+};
+
+export function initBiabAnalytics(
+	options: InitBiabAnalyticsOptions,
+): BiabAnalyticsTracker {
+	if (typeof window === "undefined") {
+		return { stop: () => {}, track: () => {} };
+	}
+	const respectDnt = options.respectDnt ?? true;
+	if (respectDnt && shouldOptOut()) {
+		return { stop: () => {}, track: () => {} };
+	}
+
+	const endpoint = `${options.baseUrl.replace(/\/$/, "")}/sites/${encodeURIComponent(
+		options.siteId,
+	)}/analytics/events`;
+
+	let lastPath: string | null = null;
+	let lastEnterAt = 0;
+	let stopped = false;
+
+	const send = (
+		kind: "pageview" | "session_start" | "custom",
+		payload: {
+			path?: string;
+			referer?: string | null;
+			durationMs?: number;
+			customEventName?: string;
+		} = {},
+	) => {
+		if (stopped) return;
+		const body = JSON.stringify({
+			kind,
+			path: payload.path ?? window.location.pathname,
+			referer:
+				payload.referer === undefined
+					? document.referrer || null
+					: payload.referer,
+			...(payload.durationMs != null ? { durationMs: payload.durationMs } : {}),
+			...(payload.customEventName
+				? { customEventName: payload.customEventName }
+				: {}),
+		});
+		const blob = new Blob([body], { type: "application/json" });
+		try {
+			if (
+				typeof navigator !== "undefined" &&
+				"sendBeacon" in navigator &&
+				navigator.sendBeacon(endpoint, blob)
+			) {
+				return;
+			}
+		} catch {
+			/* fallthrough */
+		}
+		fetch(endpoint, {
+			method: "POST",
+			body,
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${options.apiKey}`,
+			},
+			keepalive: true,
+		}).catch(() => {
+			/* drop silently — analytics shouldn't break the page */
+		});
+	};
+
+	const trackPageview = (nextPath: string) => {
+		const now = Date.now();
+		if (lastPath && lastEnterAt > 0) {
+			const dur = now - lastEnterAt;
+			send("custom", {
+				path: lastPath,
+				durationMs: Math.max(0, Math.min(dur, 24 * 60 * 60 * 1000)),
+				customEventName: "pageview_duration",
+			});
+		}
+		lastPath = nextPath;
+		lastEnterAt = now;
+		send("pageview", { path: nextPath });
+	};
+
+	// Session start once per init.
+	send("session_start");
+	trackPageview(window.location.pathname);
+
+	const origPush = history.pushState;
+	const origReplace = history.replaceState;
+	history.pushState = function (...args: Parameters<typeof history.pushState>) {
+		const ret = origPush.apply(this, args);
+		queueMicrotask(() => trackPageview(window.location.pathname));
+		return ret;
+	};
+	history.replaceState = function (
+		...args: Parameters<typeof history.replaceState>
+	) {
+		const ret = origReplace.apply(this, args);
+		queueMicrotask(() => trackPageview(window.location.pathname));
+		return ret;
+	};
+	const onPop = () => trackPageview(window.location.pathname);
+	window.addEventListener("popstate", onPop);
+
+	const onVisibility = () => {
+		if (document.visibilityState !== "hidden") return;
+		if (!lastPath || lastEnterAt === 0) return;
+		const dur = Date.now() - lastEnterAt;
+		send("custom", {
+			path: lastPath,
+			durationMs: Math.max(0, Math.min(dur, 24 * 60 * 60 * 1000)),
+			customEventName: "pageview_duration",
+		});
+	};
+	document.addEventListener("visibilitychange", onVisibility);
+
+	return {
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			history.pushState = origPush;
+			history.replaceState = origReplace;
+			window.removeEventListener("popstate", onPop);
+			document.removeEventListener("visibilitychange", onVisibility);
+		},
+		track: (name, opts) =>
+			send("custom", {
+				...(opts?.path !== undefined ? { path: opts.path } : {}),
+				customEventName: name,
+			}),
+	};
+}
+
+function shouldOptOut(): boolean {
+	if (typeof navigator === "undefined") return false;
+	const dnt =
+		(navigator as Navigator & { doNotTrack?: string }).doNotTrack ??
+		(window as Window & { doNotTrack?: string }).doNotTrack;
+	if (dnt === "1" || dnt === "yes") return true;
+	const gpc = (navigator as Navigator & { globalPrivacyControl?: boolean })
+		.globalPrivacyControl;
+	if (gpc === true) return true;
+	return false;
+}

package/src/analytics-server.ts

@@ -0,0 +1,99 @@
+/**
+ * Server-side analytics reporting — the half the browser tracker can't do.
+ *
+ * AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) fetch your HTML without
+ * executing JavaScript, so `<BIABAnalytics />` never sees them. Your server
+ * does. Call `reportAiCrawlerHit` from your middleware / request handler and
+ * BIAB records which pages the answer engines actually read — first-party
+ * AEO visibility, per page, per crawler.
+ *
+ * Next.js example (middleware.ts):
+ *
+ * ```ts
+ * import { isAiCrawlerUserAgent, reportAiCrawlerHit } from "@businessdash/sdk/analytics-server";
+ *
+ * export function middleware(request: Request) {
+ *   const ua = request.headers.get("user-agent");
+ *   if (isAiCrawlerUserAgent(ua)) {
+ *     // Fire-and-forget — never block or fail the crawler's request.
+ *     void reportAiCrawlerHit({
+ *       siteId: process.env.BIAB_SITE_ID!,
+ *       baseUrl: process.env.NEXT_PUBLIC_BIAB_API_URL!,
+ *       apiKey: process.env.NEXT_PUBLIC_BIAB_PUBLISHABLE_KEY!,
+ *       userAgent: ua,
+ *       path: new URL(request.url).pathname,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * Abuse posture: the ingest endpoint accepts a forwarded user-agent ONLY
+ * when it matches a known AI crawler — a forwarded human UA is dropped
+ * server-side, so this path can record crawler visibility but can never
+ * inflate the site's human visitor counts. If this local pattern list ever
+ * lags the platform's, the result is under-reporting, never bad data.
+ */
+
+/**
+ * Cheap prefilter mirroring the platform's AI-crawler classifier, so your
+ * middleware only spends a network call on requests that will be kept.
+ * The platform's list is authoritative — this one just saves the round trip.
+ */
+const AI_CRAWLER_UA_PATTERN =
+	/GPTBot|OAI-SearchBot|ChatGPT-User|ClaudeBot|Claude-User|Claude-SearchBot|Claude-Web|anthropic-ai|PerplexityBot|Perplexity-User|GrokBot|xAI-Crawler|Google-CloudVertexBot|GoogleOther|Applebot-Extended|meta-externalagent|Bytespider|CCBot|Amazonbot|cohere-ai|cohere-training-data-crawler|MistralAI-User|DuckAssistBot|YouBot|AI2Bot/i;
+
+export function isAiCrawlerUserAgent(
+	userAgent: string | null | undefined,
+): boolean {
+	return userAgent != null && AI_CRAWLER_UA_PATTERN.test(userAgent);
+}
+
+export type ReportAiCrawlerHitOptions = {
+	siteId: string;
+	/** Package-API base URL, e.g. "https://www.biab.app/api/package/v1". */
+	baseUrl: string;
+	/** Publishable key — same one `<BIABAnalytics />` uses. */
+	apiKey: string;
+	/** The crawler request's user-agent, verbatim. */
+	userAgent: string;
+	/** The path the crawler fetched, e.g. "/pricing". */
+	path: string;
+};
+
+/**
+ * Report one crawler fetch. Resolves quietly on every outcome — analytics
+ * must never break page serving — and returns whether the platform accepted
+ * the event (false for non-crawler UAs, network failures, etc.).
+ */
+export async function reportAiCrawlerHit(
+	options: ReportAiCrawlerHitOptions,
+): Promise<boolean> {
+	const endpoint = `${options.baseUrl.replace(/\/$/, "")}/sites/${encodeURIComponent(
+		options.siteId,
+	)}/analytics/events`;
+	try {
+		const res = await fetch(endpoint, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${options.apiKey}`,
+			},
+			body: JSON.stringify({
+				kind: "pageview",
+				path: options.path,
+				referer: null,
+				visitorUserAgent: options.userAgent,
+			}),
+			// Middleware runtimes kill slow side-requests anyway; keepalive
+			// lets the report outlive the response where supported.
+			keepalive: true,
+		});
+		if (!res.ok) return false;
+		const body = (await res.json().catch(() => null)) as {
+			accepted?: boolean;
+		} | null;
+		return body?.accepted === true;
+	} catch {
+		return false;
+	}
+}