@businessdash/sdk 0.9.60

package/src/forms.ts

@@ -0,0 +1,63 @@
+/**
+ * `@businessdash/sdk/forms` — public entry for the headless `<BiabForm>` core.
+ *
+ * This is the compiled (tsc → dist) entry the framework bindings depend on. It
+ * re-exports the framework-agnostic controller + validation primitives from
+ * `forms-core`. Bindings shipped as SOURCE (Vue / Svelte / Solid / Qwik /
+ * Angular) import from `@businessdash/sdk/forms`; bindings compiled to dist (React /
+ * web-component / vanilla) do the same.
+ */
+
+export * from "./forms-core/index.js";
+
+// ── Form Schema Design Layer ─────────────────────────────────────────
+//
+// These exports let you define the *structure* of a form (layout / steps /
+// conditional groups) that is compiled by createFormSchemaOrchestrator()
+// alongside your collections. They live here because platform forms are
+// assembled from both schema layout + runtime controller.
+//
+// ```ts
+// import { layout, createFormSchemaOrchestrator } from "@businessdash/sdk/forms";
+// ```
+
+export {
+	type BoundaryMetadata,
+	type CollectionRefNode,
+	type ConditionalBlockNode,
+	createFormSchemaOrchestrator,
+	createSingleResourceForm,
+	type EvaluationRule,
+	type FormAndSchemaConfig,
+	type FormNode,
+	type FormOrchestrationOptions,
+	type FormStepNode,
+	type InferCollectionValues,
+	type InferFieldsValues,
+	type InferFieldValue,
+	type InferFormValues,
+	type InferSchemaValues,
+	type LayoutNode,
+	type LogicalOperator,
+	layout,
+	layoutContainers,
+	type MultiPopulatorConfig,
+	type MultiPopulatorNode,
+	type MultiPopulatorOutput,
+	type OptionGroup,
+	type OrConditionNode,
+	type ProgressStyle,
+	type RuleMatchOperator,
+	SchemaBoundary,
+	type SchemaBoundaryNode,
+	type SingleResourceFormOptions,
+	type SingleResourceForms,
+} from "./data-model-schema.js";
+
+/**
+ * Slug of the platform-provided default contact form ("General Inquiry"). Any
+ * org that hasn't authored its own `general-inquiry` form falls back to this
+ * platform default, so a starter renders a working contact form with zero
+ * dashboard setup. Swap in your own org's form slug once you've built one.
+ */
+export const BIAB_DEFAULT_FORM_SLUG = "general-inquiry";

package/src/gallery-types.ts

@@ -0,0 +1,31 @@
+/**
+ * Shape of one gallery item returned by `GET /sites/{siteId}/gallery`.
+ *
+ * Mirrors the platform-side `BundleGalleryItem` so the SDK can offer
+ * typed field selection (`fields: ["src", "title"]` narrows the
+ * return type via const generics in `sdk.ts`).
+ *
+ * Kept as a flat type — no SDK dependency on zod or runtime
+ * validation here, since `createBiabClient` trusts the platform
+ * response (the platform owns the schema; the SDK is a typed
+ * facade).
+ */
+export interface BundleGalleryItem {
+	id: string;
+	type: "image" | "video";
+	src: string;
+	width: number | null;
+	height: number | null;
+	blurDataURL: string | null;
+	alt: string | null;
+	title: string | null;
+	category: string | null;
+	description: string | null;
+	jobId: string | null;
+	jobName: string | null;
+	takenAt: string | null;
+	location: string | null;
+	system: string | null;
+	year: number | null;
+	aboutHtml: string | null;
+}

package/src/graphql.ts

@@ -0,0 +1,295 @@
+/**
+ * Generate a GraphQL SDL schema from a BIAB data model.
+ *
+ * "GraphQL layer compatibility" for a data-model-as-code platform starts here:
+ * a real, typed GraphQL schema of the org's custom database that any GraphQL
+ * codegen / tooling can consume, and that an AI agent can read alongside a
+ * `export-data-model` snapshot — the schema of the data next to the data.
+ *
+ * Pure and dependency-free: string generation over the live-model artifact
+ * (the same JSON `view-data-model --json` returns), exactly how
+ * `view-data-model --out` renders the TS config client-side. It does NOT stand
+ * up a GraphQL server — execution (resolvers over this schema) is a separate,
+ * heavier layer that needs a runtime.
+ *
+ * Shape decisions:
+ *   - Every relation is a LIST. BIAB relations are link rows (`sync-records`
+ *     converges an array of target ids), and the records API always returns
+ *     `relations` as arrays — so `[Target!]!` is faithful, one-to-one included.
+ *   - SELECT/MULTI_SELECT become a GraphQL enum WHEN every option value is a
+ *     legal, unique enum name; otherwise a `String` with the allowed values in
+ *     a comment. Keeps the SDL valid against arbitrary option text.
+ *   - CURRENCY is `Int` — money is integer cents platform-wide.
+ */
+
+export type GraphqlSdlOption = { value: string; label?: string };
+
+export type GraphqlSdlField = {
+	name: string;
+	type: string;
+	label?: string;
+	description?: string;
+	/** Absent OR true ⇒ nullable; only an explicit `false` marks a required field. */
+	isNullable?: boolean;
+	options?: GraphqlSdlOption[];
+	/** `universalIdentifier` of the target object, for RELATION/MORPH_RELATION. */
+	relationTarget?: string;
+};
+
+export type GraphqlSdlObject = {
+	universalIdentifier: string;
+	kind?: string;
+	nameSingular: string;
+	namePlural: string;
+	labelSingular?: string;
+	labelPlural?: string;
+	description?: string;
+	fields: GraphqlSdlField[];
+};
+
+export type GraphqlSdlModel = { objects: GraphqlSdlObject[] };
+
+const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+
+function pascal(input: string): string {
+	const parts = input.split(/[^0-9A-Za-z]+/).filter(Boolean);
+	const joined = parts
+		.map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+		.join("");
+	return /^[A-Za-z_]/.test(joined) ? joined : `T${joined}`;
+}
+
+function camel(input: string): string {
+	const p = pascal(input);
+	return p.charAt(0).toLowerCase() + p.slice(1);
+}
+
+/** GraphQL descriptions are triple-quoted strings; a stray `"""` would break
+ *  the block, so collapse them. */
+function describe(text: string | undefined, indent: string): string {
+	if (!text) return "";
+	const clean = text.replace(/"""/g, '"').replace(/\r?\n/g, " ").trim();
+	return clean ? `${indent}"""${clean}"""\n` : "";
+}
+
+type EnumPlan = { name: string; values: string[] } | null;
+
+/** An enum only if every option value is already a legal, unique GraphQL enum
+ *  member — otherwise the field falls back to String and stays valid. */
+function planEnum(typeName: string, field: GraphqlSdlField): EnumPlan {
+	const values = (field.options ?? []).map((o) => o.value);
+	if (values.length === 0) return null;
+	const seen = new Set<string>();
+	for (const v of values) {
+		if (!GRAPHQL_NAME.test(v) || seen.has(v)) return null;
+		seen.add(v);
+	}
+	return { name: `${typeName}${pascal(field.name)}`, values };
+}
+
+function scalarFor(field: GraphqlSdlField): string {
+	switch (field.type) {
+		case "NUMBER":
+			return "Float";
+		case "RATING":
+			return "Int";
+		case "CURRENCY":
+			return "Int";
+		case "BOOLEAN":
+			return "Boolean";
+		case "DATE_TIME":
+			return "DateTime";
+		default:
+			// TEXT, UUID, RICH_TEXT, EMAILS, PHONES, DATE, and anything unmapped.
+			return "String";
+	}
+}
+
+/**
+ * Render the model as a GraphQL SDL document (string).
+ *
+ * By default only `kind === "custom"` objects — the custom collections — are
+ * emitted; standard CRM objects are the platform's, not the org's schema. Pass
+ * `includeStandard` to emit them too.
+ */
+export function dataModelToGraphqlSdl(
+	model: GraphqlSdlModel,
+	opts: { includeStandard?: boolean; header?: string } = {},
+): string {
+	const all = model.objects ?? [];
+	const objects = opts.includeStandard
+		? all
+		: all.filter((o) => o.kind !== "standard");
+
+	// Target-type resolution spans the WHOLE model — a custom object can relate
+	// to a standard one even when standard types aren't emitted.
+	const typeNameByUid = new Map(
+		all.map((o) => [o.universalIdentifier, pascal(o.nameSingular)]),
+	);
+
+	const enums: string[] = [];
+	const types: string[] = [];
+	const connections: string[] = [];
+	const queryFields: string[] = [];
+
+	for (const obj of objects) {
+		const typeName = pascal(obj.nameSingular);
+		const lines: string[] = [];
+		lines.push(describe(obj.description ?? obj.labelSingular, ""));
+		lines.push(`type ${typeName} {`);
+		lines.push("\tid: ID!");
+		lines.push("\tuniversalIdentifier: ID");
+
+		for (const field of obj.fields) {
+			if (field.name === "id" || field.name === "universalIdentifier") continue;
+			const fieldName = camel(field.name);
+			if (!GRAPHQL_NAME.test(fieldName)) continue;
+			const required = field.isNullable === false;
+
+			let gqlType: string;
+			if (field.type === "RELATION" || field.type === "MORPH_RELATION") {
+				const target = field.relationTarget
+					? typeNameByUid.get(field.relationTarget)
+					: undefined;
+				// A relation always resolves to a list (link rows); a morph with no
+				// single target degrades to JSON rather than an invalid ref.
+				gqlType = target ? `[${target}!]!` : "JSON";
+			} else if (field.type === "SELECT" || field.type === "MULTI_SELECT") {
+				const plan = planEnum(typeName, field);
+				if (plan) {
+					enums.push(
+						`enum ${plan.name} {\n${plan.values.map((v) => `\t${v}`).join("\n")}\n}`,
+					);
+					gqlType =
+						field.type === "MULTI_SELECT" ? `[${plan.name}!]` : plan.name;
+				} else {
+					gqlType = field.type === "MULTI_SELECT" ? "[String!]" : "String";
+				}
+			} else {
+				gqlType = scalarFor(field);
+			}
+
+			if (required && !gqlType.endsWith("!")) gqlType = `${gqlType}!`;
+			lines.push(describe(field.description ?? field.label, "\t"));
+			lines.push(`\t${fieldName}: ${gqlType}`);
+		}
+
+		lines.push("\tcreatedAt: DateTime!");
+		lines.push("\tupdatedAt: DateTime!");
+		lines.push("}");
+		types.push(lines.filter(Boolean).join("\n"));
+
+		connections.push(
+			`type ${typeName}Connection {\n\tnodes: [${typeName}!]!\n\t"""Pass back to \`cursor\` for the next page; null on the last page."""\n\tnextCursor: String\n}`,
+		);
+		queryFields.push(
+			`\t${camel(obj.namePlural)}(limit: Int, cursor: String): ${typeName}Connection!`,
+		);
+		queryFields.push(`\t${camel(obj.nameSingular)}(id: ID!): ${typeName}`);
+	}
+
+	const header =
+		opts.header ??
+		"# GraphQL schema generated from your BIAB data model by `biab-dev export-graphql-schema`.\n# Regenerate on schema change; commit it for a git-diffable, AI-readable contract.";
+
+	const scalars =
+		"scalar DateTime\nscalar JSON\n\n# Cents; money is integer cents platform-wide.\n";
+
+	const query =
+		queryFields.length > 0
+			? `type Query {\n${queryFields.join("\n")}\n}`
+			: "type Query {\n\t_empty: Boolean\n}";
+
+	return [
+		header,
+		scalars.trim(),
+		enums.join("\n\n"),
+		types.join("\n\n"),
+		connections.join("\n\n"),
+		query,
+	]
+		.filter((s) => s.trim().length > 0)
+		.join("\n\n")
+		.concat("\n");
+}
+
+// ── Client ───────────────────────────────────────────────────────────
+
+export type GraphqlResult<T = unknown> = {
+	data?: T;
+	errors?: Array<{
+		message: string;
+		locations?: Array<{ line: number; column: number }>;
+		path?: Array<string | number>;
+	}>;
+};
+
+export type GraphqlClient = {
+	query<T = unknown>(
+		query: string,
+		variables?: Record<string, unknown>,
+		operationName?: string,
+	): Promise<GraphqlResult<T>>;
+};
+
+/**
+ * Minimal client for the executable GraphQL endpoint
+ * (`POST /sites/{siteId}/graphql`). Dependency-free — a typed fetch wrapper, so
+ * it drops into any of the SDK's framework starters without pulling in a
+ * GraphQL client library. Pair the returned shape with types generated from
+ * `export-graphql-schema` for end-to-end typing.
+ *
+ * Requires a SECRET key with the `graphql:query` scope (the endpoint is not
+ * browser-callable). Enterprise entitlement + rate limits are enforced
+ * server-side; a plan-gated caller gets `{ available: false }` rather than
+ * `data`/`errors`, so check for that if you gate the UI on it.
+ */
+export function createGraphqlClient(input: {
+	/** Package API base, e.g. `https://biab.app/api/package/v1`. */
+	baseUrl: string;
+	siteId: string;
+	/** A secret (`biab_…`) key holding `graphql:query`. */
+	apiKey: string;
+	fetch?: typeof fetch;
+}): GraphqlClient {
+	const doFetch = input.fetch ?? globalThis.fetch;
+	const base = input.baseUrl.replace(/\/+$/, "");
+	const url = `${base}/sites/${encodeURIComponent(input.siteId)}/graphql`;
+	return {
+		async query<T = unknown>(
+			query: string,
+			variables?: Record<string, unknown>,
+			operationName?: string,
+		): Promise<GraphqlResult<T>> {
+			const res = await doFetch(url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${input.apiKey}`,
+				},
+				body: JSON.stringify({
+					query,
+					...(variables ? { variables } : {}),
+					...(operationName ? { operationName } : {}),
+				}),
+			});
+			const text = await res.text();
+			let parsed: unknown = null;
+			try {
+				parsed = text ? JSON.parse(text) : null;
+			} catch {
+				parsed = null;
+			}
+			if (!res.ok) {
+				const message =
+					parsed &&
+					typeof parsed === "object" &&
+					typeof (parsed as { message?: unknown }).message === "string"
+						? (parsed as { message: string }).message
+						: `HTTP ${res.status} ${res.statusText}`;
+				return { errors: [{ message }] } as GraphqlResult<T>;
+			}
+			return (parsed ?? {}) as GraphqlResult<T>;
+		},
+	};
+}