@businessdash/sdk 0.9.60

package/src/errors.ts

@@ -0,0 +1,338 @@
+export class BiabApiError extends Error {
+	readonly status: number;
+	readonly body: unknown;
+	readonly path: string;
+
+	constructor(input: {
+		status: number;
+		path: string;
+		message: string;
+		body: unknown;
+	}) {
+		super(input.message);
+		this.name = "BiabApiError";
+		this.status = input.status;
+		this.body = input.body;
+		this.path = input.path;
+	}
+}
+
+/**
+ * Discriminated body BIAB returns when the package API refuses to
+ * run a handler — three reasons:
+ *
+ * - `plan_required` — feature not in the org's plan (customer can
+ *   still use site; upsell card is the right UI).
+ * - `payment_required` — org's billing is 0-60 days past-due.
+ *   Static-data routes still serve; interactive ones return this
+ *   shape and the org's customer-facing site keeps working.
+ * - `service_suspended` — 60+ days past-due. Everything returns
+ *   this shape. The SDK consumer should render a 503 fallback page
+ *   so search engines treat the outage as temporary, not
+ *   permanent.
+ *
+ * READ endpoints return 200 with this body so consumers can branch
+ * cleanly without try/catch; WRITE endpoints return 402 so
+ * accidental mutations surface as exceptions.
+ */
+export type BiabPlanGateBody =
+	| {
+			available: false;
+			reason: "plan_required";
+			requiredFeature: string;
+			requiredPlan: string;
+			planDisplayName: string;
+			upgradeUrl: string;
+			message: string;
+	  }
+	| {
+			available: false;
+			reason: "payment_required";
+			daysLapsed: number;
+			daysUntilSuspension: number;
+			upgradeUrl: string;
+			message: string;
+	  }
+	| {
+			available: false;
+			reason: "service_suspended";
+			daysLapsed: number;
+			upgradeUrl: string;
+			message: string;
+	  };
+
+export function isBiabPlanGateBody(value: unknown): value is BiabPlanGateBody {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	if (v["available"] !== false) return false;
+	if (
+		v["reason"] !== "plan_required" &&
+		v["reason"] !== "payment_required" &&
+		v["reason"] !== "service_suspended"
+	) {
+		return false;
+	}
+	return (
+		typeof v["upgradeUrl"] === "string" && typeof v["message"] === "string"
+	);
+}
+
+/**
+ * Base class for every billing/entitlement rejection. Catch this to
+ * handle "the SDK refused to serve" uniformly; catch one of the three
+ * subclasses (or `instanceof`-narrow on this class) to branch on the
+ * specific reason.
+ */
+export class BiabAccessRejectedError extends Error {
+	readonly reason: "plan_required" | "payment_required" | "service_suspended";
+	readonly upgradeUrl: string;
+	readonly featureMessage: string;
+	readonly path: string;
+	readonly status: number;
+
+	constructor(input: {
+		body: BiabPlanGateBody;
+		path: string;
+		status: number;
+	}) {
+		super(input.body.message);
+		this.name = "BiabAccessRejectedError";
+		this.reason = input.body.reason;
+		this.upgradeUrl = input.body.upgradeUrl;
+		this.featureMessage = input.body.message;
+		this.path = input.path;
+		this.status = input.status;
+	}
+}
+
+/**
+ * Thrown when the org's plan doesn't include the feature the call
+ * needs. The org can resolve this by upgrading (or by adding the
+ * specific feature à la carte once that surface ships).
+ */
+export class BiabFeatureNotEntitledError extends BiabAccessRejectedError {
+	readonly feature: string;
+	readonly requiredPlan: string;
+	readonly planDisplayName: string;
+
+	constructor(input: {
+		body: Extract<BiabPlanGateBody, { reason: "plan_required" }>;
+		path: string;
+		status: number;
+	}) {
+		super(input);
+		this.name = "BiabFeatureNotEntitledError";
+		this.feature = input.body.requiredFeature;
+		this.requiredPlan = input.body.requiredPlan;
+		this.planDisplayName = input.body.planDisplayName;
+	}
+}
+
+/**
+ * Thrown when the org's billing is 0-60 days past-due. Static-data
+ * routes (marketing bundle, sitemap, robots, parallel-page reads,
+ * gallery/blog reads) continue serving normally — interactive ones
+ * (forms, cart, scheduling bookings, chatbot writes) throw this.
+ */
+export class BiabPaymentLapsedError extends BiabAccessRejectedError {
+	readonly daysLapsed: number;
+	readonly daysUntilSuspension: number;
+
+	constructor(input: {
+		body: Extract<BiabPlanGateBody, { reason: "payment_required" }>;
+		path: string;
+		status: number;
+	}) {
+		super(input);
+		this.name = "BiabPaymentLapsedError";
+		this.daysLapsed = input.body.daysLapsed;
+		this.daysUntilSuspension = input.body.daysUntilSuspension;
+	}
+}
+
+/**
+ * Thrown when the org's billing has been past-due for more than 60
+ * days. Every SDK call throws this; the consumer's framework-level
+ * page handler should catch it and return HTTP 503 with a "site
+ * temporarily unavailable" page so search engines treat the outage
+ * as temporary. `robots.txt` and `sitemap.xml` separately switch to
+ * suspended-mode bodies (`Disallow: /` / empty) for the same reason.
+ */
+export class BiabServiceSuspendedError extends BiabAccessRejectedError {
+	readonly daysLapsed: number;
+
+	constructor(input: {
+		body: Extract<BiabPlanGateBody, { reason: "service_suspended" }>;
+		path: string;
+		status: number;
+	}) {
+		super(input);
+		this.name = "BiabServiceSuspendedError";
+		this.daysLapsed = input.body.daysLapsed;
+	}
+}
+
+/**
+ * Factory the transport uses to throw the right subclass.
+ */
+export function accessRejectionFromBody(input: {
+	body: BiabPlanGateBody;
+	path: string;
+	status: number;
+}): BiabAccessRejectedError {
+	switch (input.body.reason) {
+		case "plan_required":
+			return new BiabFeatureNotEntitledError({
+				body: input.body,
+				path: input.path,
+				status: input.status,
+			});
+		case "payment_required":
+			return new BiabPaymentLapsedError({
+				body: input.body,
+				path: input.path,
+				status: input.status,
+			});
+		case "service_suspended":
+			return new BiabServiceSuspendedError({
+				body: input.body,
+				path: input.path,
+				status: input.status,
+			});
+	}
+}
+
+/**
+ * Result shape returned by `unwrapAccess` — either the data the
+ * inner promise resolved to, OR a `rejected` descriptor (one of the
+ * three reasons) so the consumer can render the appropriate card.
+ * Errors that aren't access rejections continue to throw.
+ *
+ * ```ts
+ * const result = await unwrapAccess(() => client.gallery.list());
+ * if (result.rejected) {
+ *   switch (result.rejected.reason) {
+ *     case "plan_required": return <UpsellCard {...result.rejected} />;
+ *     case "payment_required": return <BillingLapsedCard {...result.rejected} />;
+ *     case "service_suspended": return <SiteUnavailableCard {...result.rejected} />;
+ *   }
+ * }
+ * return <Gallery items={result.data} />;
+ * ```
+ */
+export type UnwrappedAccess<T> =
+	| { data: T; rejected: null }
+	| {
+			data: null;
+			rejected:
+				| {
+						reason: "plan_required";
+						feature: string;
+						requiredPlan: string;
+						planDisplayName: string;
+						upgradeUrl: string;
+						message: string;
+				  }
+				| {
+						reason: "payment_required";
+						daysLapsed: number;
+						daysUntilSuspension: number;
+						upgradeUrl: string;
+						message: string;
+				  }
+				| {
+						reason: "service_suspended";
+						daysLapsed: number;
+						upgradeUrl: string;
+						message: string;
+				  };
+	  };
+
+export async function unwrapAccess<T>(
+	fn: () => Promise<T>,
+): Promise<UnwrappedAccess<T>> {
+	try {
+		const data = await fn();
+		return { data, rejected: null };
+	} catch (err) {
+		if (err instanceof BiabFeatureNotEntitledError) {
+			return {
+				data: null,
+				rejected: {
+					reason: "plan_required",
+					feature: err.feature,
+					requiredPlan: err.requiredPlan,
+					planDisplayName: err.planDisplayName,
+					upgradeUrl: err.upgradeUrl,
+					message: err.featureMessage,
+				},
+			};
+		}
+		if (err instanceof BiabPaymentLapsedError) {
+			return {
+				data: null,
+				rejected: {
+					reason: "payment_required",
+					daysLapsed: err.daysLapsed,
+					daysUntilSuspension: err.daysUntilSuspension,
+					upgradeUrl: err.upgradeUrl,
+					message: err.featureMessage,
+				},
+			};
+		}
+		if (err instanceof BiabServiceSuspendedError) {
+			return {
+				data: null,
+				rejected: {
+					reason: "service_suspended",
+					daysLapsed: err.daysLapsed,
+					upgradeUrl: err.upgradeUrl,
+					message: err.featureMessage,
+				},
+			};
+		}
+		throw err;
+	}
+}
+
+/**
+ * Back-compat alias for the plan-only escape hatch. Same shape as
+ * `unwrapAccess` but only catches `BiabFeatureNotEntitledError` —
+ * other access rejections (payment lapse, suspension) still throw.
+ * Prefer `unwrapAccess` for new code.
+ */
+export type UnwrappedEntitlement<T> =
+	| { data: T; notEntitled: null }
+	| {
+			data: null;
+			notEntitled: {
+				feature: string;
+				requiredPlan: string;
+				planDisplayName: string;
+				upgradeUrl: string;
+				featureMessage: string | null;
+			};
+	  };
+
+export async function unwrapEntitlement<T>(
+	fn: () => Promise<T>,
+): Promise<UnwrappedEntitlement<T>> {
+	try {
+		const data = await fn();
+		return { data, notEntitled: null };
+	} catch (err) {
+		if (err instanceof BiabFeatureNotEntitledError) {
+			return {
+				data: null,
+				notEntitled: {
+					feature: err.feature,
+					requiredPlan: err.requiredPlan,
+					planDisplayName: err.planDisplayName,
+					upgradeUrl: err.upgradeUrl,
+					featureMessage: err.featureMessage,
+				},
+			};
+		}
+		throw err;
+	}
+}

package/src/forms-core/autocomplete.ts

@@ -0,0 +1,97 @@
+/**
+ * HTML autofill (`autocomplete`) resolution for `<BiabForm>` inputs.
+ *
+ * Browsers autofill an input when it carries a recognized `autocomplete` token
+ * (https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill).
+ * The SDK infers a sensible token per field (so a "Full name" text field gets
+ * `name`, an email field gets `email`, etc.), and lets the consumer:
+ *
+ *   - turn it off globally (`<BiabForm autoComplete={false}>` → every input
+ *     gets `autocomplete="off"`), and
+ *   - override per field (`fieldAutoComplete={{ [fieldId]: "off" | true | token }}`),
+ *
+ * Precedence (highest first): per-field override → schema token (`field.autocomplete`)
+ * → global off → inferred token.
+ */
+
+import type { FormCoreField } from "./validation.js";
+
+/** Global + per-field autofill configuration, threaded from `<BiabForm>`. */
+export type AutocompleteConfig = {
+	/** Global default. `false` emits `autocomplete="off"` on every input.
+	 *  Defaults to `true` (infer tokens). */
+	enabled?: boolean;
+	/** Per-field overrides keyed by field id: a literal token, `true` (infer),
+	 *  or `false` (off). Wins over everything else. */
+	overrides?: Record<string, string | boolean>;
+};
+
+/** Label/key → token heuristics, in priority order (first match wins). */
+const KEY_TOKEN_MAP: ReadonlyArray<readonly [RegExp, string]> = [
+	[/first[\s_-]?name|given[\s_-]?name/i, "given-name"],
+	[/last[\s_-]?name|family[\s_-]?name|surname/i, "family-name"],
+	[/full[\s_-]?name|your[\s_-]?name|^name$|contact[\s_-]?name/i, "name"],
+	[/company|organi[sz]ation|business[\s_-]?name|employer/i, "organization"],
+	[/job[\s_-]?title|position|occupation/i, "organization-title"],
+	[/web[\s_-]?site|homepage|\burl\b/i, "url"],
+	[
+		/address[\s_-]?line[\s_-]?2|apartment|\bapt\b|\bsuite\b|\bunit\b/i,
+		"address-line2",
+	],
+	[
+		/street|address[\s_-]?line[\s_-]?1|^address1?$|street[\s_-]?address/i,
+		"street-address",
+	],
+	[/\bcity\b|\btown\b/i, "address-level2"],
+	[/\bstate\b|province|region/i, "address-level1"],
+	[/\bzip\b|postal|post[\s_-]?code/i, "postal-code"],
+	[/\bcountry\b/i, "country-name"],
+	[/birth|\bdob\b/i, "bday"],
+	[
+		/work[\s_-]?phone|office[\s_-]?phone|company[\s_-]?phone|mobile|cell/i,
+		"tel",
+	],
+];
+
+/**
+ * Best-guess `autocomplete` token for a field from its type, then its key/label.
+ * Returns `undefined` when nothing sensible applies (e.g. a freeform number) so
+ * the attribute can be omitted entirely.
+ */
+export function inferAutocompleteToken(
+	field: FormCoreField,
+): string | undefined {
+	switch (field.type) {
+		case "email":
+			return "email";
+		case "phone":
+			return "tel";
+		case "url":
+			return "url";
+	}
+	const haystack = `${field.key ?? ""} ${field.label ?? ""}`;
+	for (const [pattern, token] of KEY_TOKEN_MAP) {
+		if (pattern.test(haystack)) return token;
+	}
+	return undefined;
+}
+
+/**
+ * Resolve the final `autocomplete` attribute value for a field, or `undefined`
+ * to omit it. Applies the precedence documented above.
+ */
+export function resolveFieldAutocomplete(
+	field: FormCoreField,
+	config: AutocompleteConfig,
+): string | undefined {
+	const override = config.overrides?.[field.id];
+	if (typeof override === "string") return override;
+	if (override === false) return "off";
+	if (override === true) return inferAutocompleteToken(field) ?? "on";
+
+	if (typeof field.autocomplete === "string" && field.autocomplete) {
+		return field.autocomplete;
+	}
+	if (config.enabled === false) return "off";
+	return inferAutocompleteToken(field);
+}

package/src/forms-core/business-function.ts

@@ -0,0 +1,209 @@
+/**
+ * Business-function runtime — the typed layer over the formula engine.
+ *
+ * A business function has typed **inputs** (with required/default) and one or
+ * more typed **outputs** ("exported variables"), each its own expression. This
+ * module runs a function definition end-to-end and *self-corrects*: a missing
+ * optional input falls back to its default; a missing required input or a
+ * bad/null/wrong-type output is flagged per-output (with an optional fallback)
+ * while the other outputs still resolve — it never throws out. Outputs may
+ * reference inputs, prior outputs (declaration order = a mini-pipeline), and
+ * other business functions (composition).
+ *
+ * Pure + isomorphic (no DB, no React). The registry/UI and the form runner build
+ * on this; the SDK mirrors it.
+ */
+
+import {
+	type EvalOptions,
+	type FormulaObject,
+	type FormulaValue,
+	type FormulaVars,
+	isFormulaObjectValue,
+	parseFormula,
+	runFormula,
+} from "./formula.js";
+
+export type FnValueType =
+	| "number"
+	| "text"
+	| "boolean"
+	| "date"
+	| "object"
+	| "any";
+
+export interface FnInput {
+	key: string;
+	label?: string;
+	type: FnValueType;
+	required?: boolean;
+	default?: FormulaValue;
+}
+
+export interface FnOutput {
+	key: string;
+	label?: string;
+	type: FnValueType;
+	/** Expression over inputs / prior outputs / other functions. */
+	formula: string;
+	/** Used when the computed value is missing/invalid for the declared type. */
+	fallback?: FormulaValue;
+}
+
+export interface BusinessFunctionDef {
+	slug?: string;
+	inputs: FnInput[];
+	outputs: FnOutput[];
+}
+
+export interface FnIssue {
+	scope: "input" | "output";
+	key: string;
+	reason: string;
+}
+
+export interface FnRunResult {
+	ok: boolean;
+	/** The exported object — successfully computed outputs (incl. applied fallbacks). */
+	outputs: FormulaObject;
+	issues: FnIssue[];
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ].*)?$/;
+
+/** Coerce a raw value to a declared type, or return an error reason. */
+function coerce(
+	value: unknown,
+	type: FnValueType,
+): { ok: true; value: FormulaValue } | { ok: false; reason: string } {
+	if (type === "any") return { ok: true, value: value as FormulaValue };
+	if (type === "object") {
+		if (value && typeof value === "object" && !Array.isArray(value))
+			return { ok: true, value: value as FormulaObject };
+		return { ok: false, reason: "expected an object" };
+	}
+	if (type === "number") {
+		const n = typeof value === "number" ? value : Number(value);
+		return Number.isNaN(n)
+			? { ok: false, reason: "not a number" }
+			: { ok: true, value: n };
+	}
+	if (type === "boolean") {
+		if (typeof value === "boolean") return { ok: true, value };
+		if (value === "true" || value === 1) return { ok: true, value: true };
+		if (value === "false" || value === 0) return { ok: true, value: false };
+		return { ok: false, reason: "not a boolean" };
+	}
+	if (type === "date") {
+		const s = String(value);
+		if (ISO_DATE.test(s) && !Number.isNaN(new Date(s).getTime()))
+			return { ok: true, value: s };
+		return { ok: false, reason: "not a date" };
+	}
+	// text
+	return { ok: true, value: typeof value === "string" ? value : String(value) };
+}
+
+/** Validate an already-computed value against a declared output type. */
+function matchesType(value: FormulaValue, type: FnValueType): boolean {
+	switch (type) {
+		case "any":
+			return true;
+		case "number":
+			return typeof value === "number" && !Number.isNaN(value);
+		case "text":
+			return typeof value === "string";
+		case "boolean":
+			return typeof value === "boolean";
+		case "object":
+			return isFormulaObjectValue(value);
+		case "date":
+			return typeof value === "string" && ISO_DATE.test(value);
+	}
+}
+
+/**
+ * Run a business function. `rawInputs` is keyed by input `key`. `options.functions`
+ * supplies other business functions for composition. Never throws.
+ */
+export function runBusinessFunction(
+	def: BusinessFunctionDef,
+	rawInputs: Record<string, unknown>,
+	options?: EvalOptions,
+): FnRunResult {
+	const issues: FnIssue[] = [];
+	const vars: FormulaVars = {};
+
+	// 1. Coerce inputs (missing optional → default; missing required → issue).
+	for (const input of def.inputs) {
+		const raw = rawInputs[input.key];
+		const missing = raw === undefined || raw === null || raw === "";
+		if (missing) {
+			if (input.default !== undefined) {
+				vars[input.key] = input.default;
+			} else if (input.required) {
+				issues.push({
+					scope: "input",
+					key: input.key,
+					reason: "required value is missing",
+				});
+			}
+			continue;
+		}
+		const c = coerce(raw, input.type);
+		if (c.ok) vars[input.key] = c.value;
+		else issues.push({ scope: "input", key: input.key, reason: c.reason });
+	}
+
+	// 2. Evaluate each output in order; later outputs can read earlier ones.
+	const outputs: FormulaObject = {};
+	for (const out of def.outputs) {
+		const r = runFormula(out.formula, vars, options);
+		if (!r.ok) {
+			if (out.fallback !== undefined) {
+				outputs[out.key] = out.fallback;
+				vars[out.key] = out.fallback;
+			} else {
+				issues.push({ scope: "output", key: out.key, reason: r.error });
+			}
+			continue;
+		}
+		if (!matchesType(r.value, out.type)) {
+			if (out.fallback !== undefined) {
+				outputs[out.key] = out.fallback;
+				vars[out.key] = out.fallback;
+			} else {
+				issues.push({
+					scope: "output",
+					key: out.key,
+					reason: `expected ${out.type}`,
+				});
+			}
+			continue;
+		}
+		outputs[out.key] = r.value;
+		vars[out.key] = r.value;
+	}
+
+	return { ok: issues.length === 0, outputs, issues };
+}
+
+/** Build the {@link EvalOptions} function map from a set of business functions,
+ *  so formulas can call them by name. Params are the function's input keys (in
+ *  order); a call resolves to the function's FIRST output (single-output
+ *  convenience) — multi-output composition is wired via input bindings, not
+ *  in-formula calls. */
+export function functionsToEvalOptions(
+	defs: Record<string, BusinessFunctionDef>,
+): EvalOptions {
+	const functions: NonNullable<EvalOptions["functions"]> = {};
+	for (const [name, def] of Object.entries(defs)) {
+		const first = def.outputs[0];
+		if (!first) continue;
+		functions[name] = {
+			params: def.inputs.map((i) => i.key),
+			formula: parseFormula(first.formula),
+		};
+	}
+	return { functions };
+}