@businessdash/sdk 0.9.60

package/README.md

@@ -0,0 +1,899 @@
+# `@businessdash/sdk`
+
+> Formerly published as `@biab-dev/sdk` (≤0.9.53) — same API, new name.
+
+**Alpha — 0.9.53.** This package declares, validates, and orchestrates your application's database schema, form layout, and type-safe field rules in a single declarative pipeline — and ships the answer-engine surface (llms.txt + product feed, MCP connector proxy, AI-crawler analytics) that makes the site you build with it legible to AI assistants.
+
+---
+
+## Install
+
+```bash
+pnpm add @businessdash/sdk
+```
+
+## Imports
+
+```ts
+import {
+  collection,
+  bd,
+  Enums,
+  createFormSchemaOrchestrator,
+  layoutContainers,
+  SchemaBoundary,
+} from "@businessdash/sdk";
+
+// Destructure visual layout wrappers for intuitive, HTML-like inline grouping
+const { FormStep, ConditionalBlock, MultiPopulator, OrCondition } = layoutContainers;
+```
+
+---
+
+## Core `bd` Primitive Modifiers
+
+The compact `bd` factory namespace eliminates boilerplate. Each chain method implements fluent builders to define data rules, UI presentation hints, database constraints, and cryptographic security features.
+
+### Core Field API Reference
+
+```ts
+bd.text().formElement("short_text")       // Map raw DB type to a front-end input component
+  .validate({ minLength: 3, maxLength: 100 })  // Append structural validation parameters
+  .helper("The display name of the item")       // Descriptive metadata for tooltips
+  .regex(/^[A-Z][a-z]+$/)                      // Absolute input string validation
+  .check("name != ''")                          // Low-level SQL CHECK constraint
+  .encrypted()                                  // Per-user cryptographic isolation
+  .encryptedLight()                             // Master key encryption-at-rest
+  .private()                                    // Strip from public log telemetry
+  .required();
+```
+
+Available `.validate()` rules:
+
+| Rule | Applies to | Description |
+|---|---|---|
+| `minLength` | TEXT, ARRAY | Minimum characters or entries |
+| `maxLength` | TEXT, ARRAY | Maximum characters or entries |
+| `lessThan` | NUMBER, NUMERIC | Strictly less than |
+| `greaterThan` | NUMBER, NUMERIC | Strictly greater than |
+| `round` | NUMBER, NUMERIC | Decimal places to round to |
+| `positive` | NUMBER, NUMERIC | Must be >= 0 |
+| `notNull` | Any | Reject null/empty |
+| `floor` | NUMBER, NUMERIC | Floor the value |
+| `isDecimal` | NUMBER, NUMERIC | Must have decimal component |
+| `regex` | TEXT | Pattern match |
+| `checkExpression` | TEXT, NUMBER | SQL CHECK expression |
+| `lessThanToday` | DATE, DATE_TIME | Must be historical |
+| `greaterThanToday` | DATE, DATE_TIME | Must be future |
+
+### Form Elements
+
+```ts
+.formElement("short_text")     // TEXT → short/long/email/url/dropdown/radio/color/…
+.formElement("currency")       // NUMBER/NUMERIC → currency/range/star_rating/…
+.formElement("yes_no_toggle")  // BOOLEAN → yes_no_toggle / yes_no_checkbox
+.formElement("dropdown")       // SELECT → dropdown / radio_group
+.formElement("measurement")    // RAW_JSON → measurement/address_group/geo/object
+.formElement("formFileValue")  // FILES → file upload
+```
+
+### Complex Data Fields
+
+**`bd.measurement(options)`** — Explicit physics metrics compiler block:
+
+```ts
+memoryBusSpeed: bd.measurement({
+  category: "storageSpeed",
+  unitPicker: "fixed",
+  default_unit: "MHz",
+  resolve_to_your_unit: "MT/s",
+  allow_decimals: true,
+}).required()
+```
+
+Supported categories: `sound`, `pressure`, `torque`, `speed` (incl. `Mach`, `ly/yr`), `time`, `area`, `volume`, `power`, `energy`, `storage`, `storageSpeed`, `frequency`, `temperature`, `mass`, `length` ( incl. `µm`, `nm`), `currency`.
+
+**`bd.object(properties)`** — Structural nested JSON with storage strategy:
+
+```ts
+metadata: bd.object({
+  sku: bd.text().required(),
+  warehouse: bd.text(),
+}).strategy("flattened")  // or "jsonb" | "separateTable" (spawns 1:1 side-table)
+```
+
+All `RAW_JSON` object elements support JSONB output, not only `bd.object()`:
+
+```ts
+shippingAddress: bd.address().strategy("jsonb"),
+availability: bd.json().formElement("availability").strategy("jsonb"),
+bookingWindow: bd.json().formElement("date_range").strategy("jsonb"),
+coordinates: bd.geo().strategy("jsonb"),
+```
+
+`strategy` and `separateTableName` are included in `toJSONSchema()`.
+
+**`bd.file(options)`** — File uploads:
+
+```ts
+architectureSpecs: bd.file({
+  max_size_mb: 15,
+  allowed_mimetypes: ["application/pdf"],
+}).optional()
+```
+
+---
+
+## Optional Schema Boundaries
+
+`SchemaBoundary()` is feature metadata, not form layout. It accepts collections
+or nested boundaries directly and does not require a step, wizard, repeater, or
+group:
+
+```ts
+const projects = collection("projects", {
+  fields: { title: bd.text().required() },
+});
+
+const direct = createFormSchemaOrchestrator([projects]);
+
+const tagged = createFormSchemaOrchestrator([
+  SchemaBoundary(
+    { featureId: "projects", name: "Projects" },
+    projects,
+  ),
+]);
+```
+
+Both declarations compile the same collection. The second additionally sets
+`tagged.featureTags.project` to `"projects"`.
+
+## High-Utility Form Layout Containers
+
+Layout containers are optional semantic wrappers. Add them only when the UI
+needs steps, conditional visibility, repetition, or branching.
+
+### `FormStep(name, options, ...children)`
+
+Wraps schema portions into sequential steps for multi-step wizards:
+
+```ts
+FormStep("taxonomy_setup", {
+  showTitle: true,
+  helperText: "Configure high-level project taxonomy.",
+},
+  collection("categories", { fields: { name: bd.text().required() } }),
+  collection("feature_groups", { fields: { name: bd.text().required() } }),
+)
+```
+
+### `ConditionalBlock(config, ...children)`
+
+Dynamically toggles visibility based on matching logic gates:
+
+```ts
+ConditionalBlock(
+  {
+    matchStrategy: "AND",
+    showTitle: true,
+    rules: [
+      { fieldRef: "project.isActive", op: "equals", values: [true] },
+    ],
+  },
+  collection("features", { fields: { name: bd.text().required() } }),
+)
+```
+
+Supports `matchStrategy: 'AND' | 'OR'` and operators: `equals`, `not_equals`, `any_of`, `none_of`.
+
+### `MultiPopulator(config, ...children)`
+
+Generates an N+1 array row repeater grid. A single child collection is inferred
+as a secondary-table output:
+
+```ts
+MultiPopulator({ max_entries: 5, button_label: "➕ Register Node" },
+  collection("hardware_nodes", {
+    fields: {
+      nodeSerial: bd.text().required().private(),
+      memoryBusSpeed: bd.measurement({
+        category: "storageSpeed",
+        unitPicker: "fixed",
+        default_unit: "MHz",
+        resolve_to_your_unit: "MT/s",
+        allow_decimals: true,
+      }).required(),
+    },
+  }),
+)
+```
+
+To keep the repeated array on a parent record instead, bind the repeater to a
+JSONB field and declare the shape of one entry:
+
+```ts
+const projects = collection("projects", {
+  fields: {
+    name: bd.text().required(),
+    teamMembers: bd.array().strategy("jsonb"),
+  },
+})
+
+createFormSchemaOrchestrator([
+  projects,
+  MultiPopulator({
+    max_entries: 10,
+    output: {
+      strategy: "jsonb",
+      fieldRef: "project.teamMembers",
+    },
+    entryFields: {
+      name: bd.text().required(),
+      role: bd.text().optional(),
+    },
+  }),
+])
+```
+
+The orchestrator rejects missing targets, scalar JSONB targets, fields without
+`.strategy("jsonb")`, and ambiguous implicit secondary-table outputs.
+
+### `OrCondition(options, branches)`
+
+Multi-path router layout engine for custom branching (tabbed selections):
+
+```ts
+OrCondition({ showTitle: true, button_label: "Select Target Pathway" }, [
+  {
+    name: "Hardware Validation Path",
+    helperText: "Provisions system telemetry benchmarks.",
+    nodes: [
+      MultiPopulator({ max_entries: 5, button_label: "➕ Register Node" },
+        collection("hardware_nodes", { fields: { /* ... */ } }),
+      ),
+    ],
+  },
+  {
+    name: "Standard Baseline Deployment Only",
+    nodes: [ /* ... */ ],
+  },
+])
+```
+
+---
+
+## Compile-Time Type Safety & Form Alignment
+
+The SDK leverages TypeScript type inference to turn common engineering mistakes into instant IDE compile errors.
+
+### Invalid Field Refs
+
+A typo inside a conditional block path (e.g. `projects.isActveeee`) fails validation at orchestration time:
+
+```bash
+⚠️ [BusinessDash SDK] Conditional rule references field "isActveeee"
+   in collection "projects" which does not exist.
+```
+
+### Data Type Mismatches
+
+Conditional `fieldRef` values are validated when orchestration runs. The current
+public type is `string`, so invalid collection or field paths are runtime
+alignment errors rather than template-literal compile-time errors.
+
+### Implicit Key Generation
+
+Primary keys are optional. The orchestration engine pre-scans collections, automatically injecting type-safe sequential integer or secure random `uuid` primary identifiers.
+
+---
+
+## Unified Schema & Form Orchestration Blueprint
+
+The complete declaration — combining database layers, field constraints, RLS policies, and layout:
+
+```ts
+import {
+  collection, bd, Enums,
+  createFormSchemaOrchestrator,
+  layoutContainers,
+} from "@businessdash/sdk";
+
+const { FormStep, ConditionalBlock, MultiPopulator, OrCondition } = layoutContainers;
+
+export const ProjectStatus = Enums(["planned", "in_progress", "beta", "completed"] as const);
+
+export const applicationMasterContext = createFormSchemaOrchestrator([
+
+  FormStep("taxonomy_setup", {
+      showTitle: true,
+      helperText: "Configure high-level project taxonomy and categorization mappings.",
+    },
+      collection("categories", {
+        fields: {
+          name: bd.text().formElement("short_text").required()
+            .validate({ minLength: 3 }).helper("Category name."),
+          icon: bd.text().formElement("short_text").optional(),
+        },
+      }),
+
+      collection("feature_groups", {
+        fields: {
+          name: bd.text().formElement("short_text").required(),
+          category_id: bd.relation()
+            .references("categories").onDelete("CASCADE").required(),
+        },
+      }),
+    ),
+
+  FormStep("feature_engineering", { showTitle: true },
+
+      collection("features", {
+        rlsPolicies: [
+          { roles: ["authenticated"], actions: ["read"], expression: "owner_id = auth.uid()" },
+        ],
+        fields: {
+          name: bd.text().formElement("short_text").required().regex(/^[A-Z][a-z]+$/),
+          status: bd.text().formElement("dropdown").required(),
+
+          estimatedBudget: bd.number().formElement("currency")
+            .check("estimated_budget >= 0").validate({ round: 2 }),
+
+          feature_group_id: bd.relation()
+            .references("feature_groups").onDelete("CASCADE").required(),
+
+          related_features: bd.relation().belongsToMany("features", {
+            joinCollectionName: "feature_references",
+            fields: {
+              isBidirectional: bd.boolean().formElement("yes_no_toggle").default(false),
+            },
+          }),
+        },
+      }),
+  ),
+
+  FormStep("routing_and_sandbox_studio", { showTitle: true },
+
+      OrCondition({ showTitle: true, button_label: "Select Target Pathway" }, [
+        {
+          name: "Hardware Validation Path",
+          helperText: "Provisions system telemetry benchmarks using physical metrics components.",
+          nodes: [
+            MultiPopulator({ max_entries: 5, button_label: "➕ Register Network Hardware Node" },
+              collection("hardware_nodes", {
+                fields: {
+                  nodeSerial: bd.text().formElement("short_text").required().private(),
+                  memoryBusSpeed: bd.measurement({
+                    category: "storageSpeed",
+                    unitPicker: "fixed",
+                    default_unit: "MHz",
+                    resolve_to_your_unit: "MT/s",
+                    allow_decimals: true,
+                  }).required(),
+                  architectureSpecs: bd.file({
+                    max_size_mb: 15,
+                    allowed_mimetypes: ["application/pdf"],
+                  }).optional(),
+                },
+              }),
+            ),
+          ],
+        },
+        {
+          name: "Standard Baseline Deployment Only",
+          nodes: [],
+        },
+      ]),
+  ),
+
+], {
+  defaultIdType: "uuid",        // Auto-injects unique string identifiers for missing primary keys
+  consecutive: true,            // Forces strict wizard sequence stepping rules
+  progress_style: "progress_bar", // Instructs the layout renderer to generate progress indicators
+});
+```
+
+---
+
+## Deployment Validation Lifecycle
+
+When `createFormSchemaOrchestrator` compiles, it parses the layout tree and splits it into two isolated channels:
+
+- **`databaseSchema`** — A pure array of raw collection models, stripped of UI components, ready to stream to Prisma, Drizzle, or raw storage pipelines.
+- **`uiFormTree`** — The complete visual rendering graph mapping steps, multi-populators, validation constraints, and helper text fields for your form engine.
+
+If a layout node points to an unmapped collection or field, orchestration stops
+with a focused diagnostic:
+
+```bash
+[BusinessDash SDK] Conditional rule references field "isActive"
+in collection "project" which does not exist.
+```
+
+---
+
+## AI Distribution — llms.txt & Product Feed on Your Domain
+
+Orgs curate products/services for answer engines under **Dashboard → Marketing
+→ AI Distribution**; the platform keeps two public artifacts current per site —
+an OpenAI merchant-feed-shaped product feed and an `llms.txt`. The llms.txt
+convention only works at the site's own root (an AI crawler asks for
+`https://yoursite.com/llms.txt`), while the source of truth lives on BusinessDash where
+the org curates it. `@businessdash/sdk/distribution` proxies the two together:
+
+```ts
+// app/llms.txt/route.ts
+import { llmsTxtHandler } from '@businessdash/sdk/distribution'
+
+export const GET = llmsTxtHandler({
+  siteId: process.env.BIAB_SITE_ID!,
+  baseUrl: process.env.NEXT_PUBLIC_BIAB_APP_URL!, // e.g. https://www.biab.app
+})
+```
+
+- **`llmsTxtHandler(options)`** serves the curated llms.txt from your own
+  domain root, with a 5-minute `s-maxage` + `stale-while-revalidate`. An
+  upstream 404 (feed disabled or entitlement lapsed) passes through untouched;
+  network failure returns a plain 503 — it never throws into the framework.
+- **`productFeedUrl(options)` / `llmsTxtUrl(options)`** build the public BIAB
+  feed URLs. The product feed needs no proxy — submit its BusinessDash URL directly to
+  merchant/feed programs; `productFeedUrl` builds it for display/submission.
+
+Pair the feed with the `product()` JSON-LD builder from `@businessdash/sdk/seo`:
+the feed gets your product INTO the engines' catalogs; the markup is what their
+crawlers verify on the landing page itself.
+
+## MCP Connector on 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 the two
+`@businessdash/sdk/mcp` handlers and your domain gains the same connector surface —
+so the URL an org hands to Claude / ChatGPT / Gemini is their own site:
+
+```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!,
+})
+```
+
+- **`mcpHandler(options)`** — `POST` proxies JSON-RPC to the platform's public
+  per-site connector; `GET` mirrors the spec's 405. An unreachable upstream
+  answers with a proper JSON-RPC `-32603` error and a 502.
+- **`mcpManifestHandler(options)`** — serves `.well-known/mcp.json` with the
+  endpoint URL rewritten to YOUR domain (the requesting origin).
+- **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.
+
+## AI-Crawler Visibility (AEO Analytics)
+
+AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) fetch your HTML without
+executing JavaScript, so `<BIABAnalytics />` never sees them. Your server does
+— report them from middleware via `@businessdash/sdk/analytics-server`:
+
+```ts
+// middleware.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,
+    });
+  }
+}
+```
+
+Read it back with `biab.site(siteId).analytics.aiVisibility({ days: 30 })` —
+per-crawler fetch counts, distinct pages read, vendor, intent
+(`training` / `search` / `user`), and last-seen timestamps. Branch on
+`.available`; same plan gating as `pageViews()`.
+
+---
+
+## Entrypoints
+
+| Import path | Contents |
+|---|---|
+| `@businessdash/sdk` | Main barrel — all schema, layout, client, auth, SEO exports |
+| `@businessdash/sdk/contracts` | Zod schemas + inferred types for every API surface |
+| `@businessdash/sdk/enums` | Enum helpers — label formatting, enum entry utilities |
+| `@businessdash/sdk/collections` | Schema primitives — `collection()`, `createSchema()`, `bd`, `Enums()`, `SchemaBoundary` |
+| `@businessdash/sdk/forms` | Form layout + runtime — `layoutContainers`, `createFormSchemaOrchestrator()`, `createSingleResourceForm()`, controller, formula engine |
+| `@businessdash/sdk/static` | Static data — `Enums()`, enum types |
+| `@businessdash/sdk/react` | React bindings — form, auth, analytics, attribution |
+| `@businessdash/sdk/vue` | Vue binding — `<BiabForm>` |
+| `@businessdash/sdk/svelte` | Svelte binding — `<BiabForm>` |
+| `@businessdash/sdk/solid` | Solid binding — `<BiabForm>` |
+| `@businessdash/sdk/qwik` | Qwik binding — `<BiabForm>` |
+| `@businessdash/sdk/angular` | Angular binding — `<biab-form>` component |
+| `@businessdash/sdk/element` | `<biab-form>` custom element — drop-in web component |
+| `@businessdash/sdk/vanilla` | Framework-free imperative DOM binding — `mountBiabForm()` |
+| `@businessdash/sdk/react-analytics` | `<BIABAnalytics />` — browser page-view tracker for React |
+| `@businessdash/sdk/react-attribution` | "Powered by BusinessDash" attribution badge |
+| `@businessdash/sdk/analytics-core` | Framework-agnostic analytics core — `initBiabAnalytics()` |
+| `@businessdash/sdk/analytics-server` | Server-side AEO reporting — `isAiCrawlerUserAgent()`, `reportAiCrawlerHit()` |
+| `@businessdash/sdk/distribution` | llms.txt proxy + feed URLs — `llmsTxtHandler()`, `productFeedUrl()`, `llmsTxtUrl()` |
+| `@businessdash/sdk/mcp` | MCP connector proxy — `mcpHandler()`, `mcpManifestHandler()` |
+| `@businessdash/sdk/proxy` | `BiabDevClient` / customer-portal client re-exports for proxy setups |
+| `@businessdash/sdk/seo` | JSON-LD builders — `localBusiness()`, `product()`, … |
+| `@businessdash/sdk/data-model-schema` | `defineDataModel` — org custom database (tables + enums) as code |
+| `@businessdash/sdk/alpha` | Legacy/deprecated pre-0.9 schema API, re-exported for compatibility |
+| `@businessdash/sdk/marketing-schema` | `defineSiteMarketingSchema()` — schema-driven marketing-page flow |
+| `@businessdash/sdk/next/revalidate` | One-line Next.js route handler for BusinessDash revalidation webhooks |
+| `@businessdash/sdk/adapters/revalidate` | Framework-agnostic revalidation handler builder |
+| `@businessdash/sdk/biab-forms.css` | Default form stylesheet |
+
+## Releases
+
+> **Versioning convention (0.9.50+):** Significant feature groups bump the minor
+> field directly. Previous releases used the 36-band patch series (0.9.36, 0.9.35…).
+> The 0.9.35 docs are archived at `docs-legacy/0.9.35/` — this is the first
+> supported SDK baseline. 0.9.50 introduces the unified Schema, Validation, and
+> Form orchestration pipeline with `createFormSchemaOrchestrator`, `layoutContainers`,
+> and the full `bd` field builder namespace.
+>
+> **0.8.x = schema-driven marketing flow.** Major surface bump (still
+> alpha). New entrypoints: `defineSiteMarketingSchema()`,
+> `@businessdash/sdk/seo` for typed JSON-LD builders, and a `biab-dev` CLI.
+>
+> **0.9.x = full programmatic consumer surface.** The largest expansion
+> yet: native storefront / cart / checkout / coupons / subscriptions,
+> customer portal + tenant auth (`createAuthHandler`, `getTenantSession`,
+> `<SignIn/>` `<SignUp/>` `<SignOut/>` `useUser`), blog, a paginated
+> reviews wall, address autocomplete + shipping, programmatic local SEO
+> (`defineParallelPage()`), the revalidation webhook channel
+> (`@businessdash/sdk/next/revalidate` + `@businessdash/sdk/adapters/revalidate`),
+> privacy-conscious analytics (`@businessdash/sdk/react-analytics` +
+> `@businessdash/sdk/analytics-core`), and a three-state billing-lifecycle
+> degradation contract. Detailed per-version notes below.
+
+The 3 most recent releases are below. **For the complete release
+history, see the [changelog](https://www.biab.app/docs/developer/changelog).**
+
+### 0.9.53 — AI Distribution, AEO Visibility & the MCP Proxy
+
+The release that makes a consumer-hosted site legible to answer engines. Three
+new entrypoints — `@businessdash/sdk/distribution`, `@businessdash/sdk/mcp`, and
+`@businessdash/sdk/analytics-server` — plus an AI-visibility read-back on the
+analytics client, a `product()` JSON-LD builder, and two formula functions.
+
+#### `@businessdash/sdk/distribution` — llms.txt + product feed on your domain
+
+Orgs curate products/services (or custom entries) under **Dashboard →
+Marketing → AI Distribution**, and the platform keeps two public artifacts
+current per site: an OpenAI merchant-feed-shaped **product feed** (submittable
+to ChatGPT's product-feed program as-is) and an **`llms.txt`**. The llms.txt
+convention only works at the site's own root — an AI crawler asks for
+`https://yoursite.com/llms.txt` — while the source of truth lives on BusinessDash where
+the org curates it. The new entrypoint proxies the two together:
+
+```ts
+// app/llms.txt/route.ts
+import { llmsTxtHandler } from '@businessdash/sdk/distribution'
+
+export const GET = llmsTxtHandler({
+  siteId: process.env.BIAB_SITE_ID!,
+  baseUrl: process.env.NEXT_PUBLIC_BIAB_APP_URL!, // e.g. https://www.biab.app
+})
+```
+
+- **`llmsTxtHandler(options)`** — GET handler serving the curated llms.txt from
+  your own domain root. Upstream 404 passes through untouched (feed disabled or
+  entitlement lapsed), network failure returns a plain 503 — it never throws
+  into the framework. Responses carry a 5-minute `s-maxage` +
+  `stale-while-revalidate`.
+- **`productFeedUrl(options)` / `llmsTxtUrl(options)`** — build the public BIAB
+  feed URLs. The product feed needs no proxy — you submit its BusinessDash URL directly
+  to merchant/feed programs; `productFeedUrl` builds it for display/submission.
+- Gated by the org's **AI Distribution** feature (`marketing.ai_distribution`);
+  a lapsed entitlement surfaces as the pass-through 404.
+
+#### `@businessdash/sdk/mcp` — the site's AI connector on ANY 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!,
+})
+```
+
+- **`mcpHandler(options)`** — `POST` proxies JSON-RPC to the platform's public
+  per-site connector; `GET` mirrors the spec's 405. An unreachable upstream
+  answers with a proper JSON-RPC `-32603` error and a 502.
+- **`mcpManifestHandler(options)`** — serves `.well-known/mcp.json` with the
+  endpoint URL rewritten to YOUR domain (the requesting origin).
+- **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.
+
+#### `@businessdash/sdk/analytics-server` — first-party AEO visibility
+
+AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) fetch your HTML without
+executing JavaScript, so `<BIABAnalytics />` never sees them. Your server does:
+
+```ts
+// middleware.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,
+    });
+  }
+}
+```
+
+- **`isAiCrawlerUserAgent(ua)`** — cheap prefilter mirroring the platform's
+  AI-crawler classifier (GPTBot, OAI-SearchBot, ClaudeBot/Claude-User/
+  Claude-SearchBot, PerplexityBot, GrokBot/xAI-Crawler, Google-CloudVertexBot,
+  GoogleOther, Applebot-Extended, Bytespider, CCBot, Amazonbot, MistralAI-User,
+  DuckAssistBot, YouBot, AI2Bot, …). The platform's list is authoritative — a
+  lagging local list only under-reports, never records bad data.
+- **`reportAiCrawlerHit(options)`** — reports one crawler fetch with the
+  publishable key. Resolves quietly on every outcome — analytics must never
+  break page serving. Abuse posture: the ingest endpoint keeps a forwarded
+  user-agent ONLY when it classifies as a known AI crawler, so this path can
+  record crawler visibility but can never inflate human visitor counts.
+- **Read it back — `analytics.aiVisibility()`.** Which crawlers actually
+  fetched your pages: fetch counts, distinct pages read, vendor, intent
+  (`training` / `search` / `user` — corpus building vs. answer-engine indexing
+  vs. a live assistant reading on a person's behalf), and when each last came:
+
+  ```ts
+  const ai = await biab.site(siteId).analytics.aiVisibility({ days: 30 });
+  if (ai.available) {
+    for (const c of ai.crawlers)
+      console.log(`${c.name}: ${c.fetches} fetches over ${c.distinctPages} pages`);
+  }
+  ```
+
+  Ordered most-fetches-first; defaults to a 30-day window. Branch on
+  `.available` — same plan gating as `pageViews()`. Contracts export the
+  `aiVisibility*` schemas and `AiCrawlerVisibility` types.
+
+#### `product()` JSON-LD builder
+
+`@businessdash/sdk/seo` adds a schema.org **Product** (+ nested Offer) builder —
+what shopping surfaces and answer engines read off a product page:
+
+```ts
+import { product } from "@businessdash/sdk/seo";
+
+const jsonLd = product({
+  url: "https://acme.co/store/widget",
+  name: "Widget",
+  brand: "Acme",
+  offer: { priceCents: 12900, availability: "InStock" },
+});
+```
+
+`priceCents` is integer cents, formatted to schema.org's decimal string here.
+Pair it with the AI Distribution product feed: the feed gets your product INTO
+the engines' catalogs; this markup is what their crawlers verify on the landing
+page itself.
+
+#### Formula library: `SUBSTITUTE` + `SLUGIFY`
+
+Two additions to `FORMULA_FUNCTIONS` (the engine behind the Math/calculation
+form element and Business Functions, via `@businessdash/sdk/forms`):
+
+- **`SUBSTITUTE(text, find, replace, [find2, replace2, …])`** — multi-pair text
+  replacement applied in a **single pass**, so a replacement's output is never
+  itself re-replaced (pairs stay independent of their order; longest match wins
+  at each position).
+- **`SLUGIFY(text)`** — the platform's canonical strict slug: lowercase, accents
+  stripped, non-alphanumerics collapsed to single hyphens.
+  `SLUGIFY("Solar Panel Install (2026)")` → `"solar-panel-install-2026"`.
+
+#### Platform-side in this release window
+
+Customer Loyalty (points + tiers) and a Customer Portal expansion (including a
+staff preview-as-customer mode) shipped on the dashboard/portal side — no new
+SDK exports yet. The org-grade OAuth MCP connector (the assistant acting as org
+STAFF, with a consent screen and per-tool write gates) lives on the platform
+host; the SDK's `mcp` entrypoint above fronts the public site-visitor
+connector.
+
+### 0.9.52 — Single-Resource Forms, Typed Join Tables & a Careers Surface
+
+The schema pipeline learns to generate atomic Create/Edit/Delete forms,
+many-to-many joins carry typed payloads, public job postings get a client, two
+new form elements land, and a batch of parity fixes makes the dashboard and an
+SDK-rendered form finally agree on conditional logic.
+
+#### `createSingleResourceForm()` — Create / Edit / Delete instead of a wizard
+
+```ts
+import { createSingleResourceForm } from "@businessdash/sdk/forms";
+
+const { create, edit, delete: remove, dependencies } =
+  createSingleResourceForm(object);
+```
+
+- Generates the **three atomic, single-record forms** for one collection —
+  Create, Edit and Delete — instead of one big multi-step wizard. Edit and
+  Delete lead with a record picker ("which row are we acting on?").
+- **Relation fields become live collection pickers** automatically, single or
+  multi according to the relation's own cardinality, so a many-to-many is
+  filled in inline and the join table never surfaces as a concept.
+- **Delete states its impact honestly** — read from the relations that actually
+  point AT the collection and their declared `onDelete`, rather than asserting
+  a generic "respects referential integrity".
+- **Lineage-safe.** `create` keeps the base `data-model:<uid>` sourceKey the
+  one-form-per-collection generator has always used, so promoting a model that
+  previously produced a single form updates that draft rather than orphaning it
+  and creating a duplicate; `edit`/`delete` take suffixed keys off the same
+  stem. Types `SingleResourceForms` / `SingleResourceFormOptions` are exported
+  from `@businessdash/sdk` and `@businessdash/sdk/forms`.
+
+#### Typed join tables — `belongsToMany({ fields })` end-to-end
+
+- A join's columns — declared with the same `bd` field builders as a
+  collection's — now compile into typed **link-attribute definitions**
+  (`LinkAttributeDefinition`, mirroring the platform's link-attributes
+  contract), the typed payload each many-to-many link row may carry.
+- A link is an EDGE, not a record: only a small set of value kinds makes sense
+  on one. Anything richer maps to TEXT rather than silently pretending to be
+  supported — richer shapes are asking for a real collection.
+
+#### `client.hiring` — careers pages on your own domain
+
+The org's open job postings and their categories, so a consumer can render a
+careers page in their own design system:
+
+```ts
+const { items } = await client.hiring.list({ limit: 20 });
+const posting = await client.hiring.get("senior-installer");
+if (posting.applicationFormId) {
+  const form = await client.forms.schema(posting.applicationFormId);
+}
+```
+
+- **`list({ limit, offset, category })`** — one page of open postings,
+  newest-first, offset-paged via `nextOffset`. Only postings that are
+  published, active, have seats left, and are under their application cap are
+  returned — a careers page never advertises a role that can no longer be
+  applied to.
+- **`get(slug)`** — rejects with a 404 for drafts, closed, archived, filled, or
+  capped postings; treat that as "this role is gone", not a transient failure.
+- **`categories()`** — job categories with a count of open postings in each,
+  enough for filter chips or grouped sections without fetching every posting.
+- **Read-only by construction.** Internal hiring state (openings filled,
+  application caps, default permissions/roles, interview questions) never
+  crosses this boundary. To take applications, hand the posting's
+  `applicationFormId` to the forms surface — this client grants no submit path
+  of its own. Contracts export `jobPostingSchema`, `jobCategorySchema`, and
+  friends.
+
+#### New form elements: `icon_select` and `image_input`
+
+- **`icon_select`** — pick an icon by name from a searchable grid. The value is
+  the icon's kebab-case name; `iconConfig.allowedIcons` curates the choices (a
+  curated list skips the network entirely), otherwise the picker lazily fetches
+  the platform's icon-name index. Names render as
+  `<img src="…/api/icons/<name>.svg">` — the SDK deliberately bundles no icon
+  set (~1,600 icons, and three of the bindings can't import a React package),
+  so the platform stays the single source of truth for what a name means.
+- **`image_input`** — one image as a single URL string, from an upload OR a
+  pasted URL (`imageInputConfig.sources: "both" | "upload" | "url"`).
+- **Display variants** — `display` extends beyond `toggle`/`checkbox` to
+  `"dropdown"` and `"combobox"`. Display-only: never affects the submitted
+  value or its validation. Dropdowns self-upgrade to a searchable input past 10
+  options, or when the builder chose the ComboBox card
+  (`SEARCHABLE_THRESHOLD` / `shouldSearchOptions`).
+- **Shared element helpers** exported from `@businessdash/sdk/forms`:
+  `BIAB_ICON_BASE`, `iconUrl`, `ICON_INDEX_URL`, `fetchIconNames`,
+  `filterIconNames`, `SEARCHABLE_THRESHOLD`, `shouldSearchOptions`. The new
+  elements render in the React, Vue, Svelte and Angular bindings.
+
+#### Conditional-logic parity — the dashboard and your site now agree
+
+- **`match: "any"` is honored.** The clause combinator was missing from the
+  SDK's rule type, so a rule the builder saved as "ANY of" silently evaluated
+  as "ALL of" once it rendered through the SDK — the dashboard and a consumer's
+  site disagreed about the same form. Fixed across every binding.
+- **`matchField` on collection-picker rules.** Collection pickers store record
+  IDs — a rule can now compare a column of the chosen record instead
+  (`"__label__"` = the displayed label); unresolved falls back to the raw
+  value.
+- **Conditional PAGES.** `input_group` now gates on its `conditionRule` (at the
+  root of a consecutive form a group IS a page, so a rule there makes the whole
+  page conditional). A page whose rule is currently false is DROPPED from the
+  step partition — "Next" skips straight past it and the progress indicator
+  loses its entry — in React, Svelte, Vue, Angular, Solid, Qwik and vanilla
+  alike. Its required fields no longer block Next/Submit, and stale values
+  behind a hidden group no longer decide an `or_condition` branch. New
+  `isNodeVisible` export.
+
+#### CLI: `wipe-database`
+
+- **`biab-dev wipe-database --collections a,b`** — developer shortcut that
+  wipes records AND removes the named collections from the schema: the
+  backup-first data-wipe flow plus a pruned schema-draft push. The schema
+  change still requires dashboard promotion.
+- **`--all`** calls the data-model **reset** endpoint, which atomically
+  soft-deletes all metadata, clears records, and removes schema slots. The
+  server saves and verifies the backup before resetting any data.
+- Accepts `--dry-run`, and `--yes` to collapse to a single confirmation
+  (unlike `wipe-collections`, which stays interactive-only by design).
+
+#### Fixes
+
+- **Node-ESM import specifiers.** Internal extensionless imports in the
+  validation and schema modules gained explicit `.js` specifiers
+  (`./enums.js`, `./email-domains.js`, `./units.js`, `./us-states.js`) — no
+  more resolution failures for Node ESM / `NodeNext` consumers.
+- **`createFormSchemaOrchestrator`** throws a focused error when `boundaries`
+  isn't an array, instead of failing obscurely mid-walk.
+
+### 0.9.51 — Pipeline Completion
+
+The 0.9.50 notes below were written at 0.9.51 and describe the unified
+Schema/Validation/Form pipeline **as completed in this release** — several
+documented pieces landed between the two npm artifacts. If you installed the
+0.9.50 artifact, upgrading gets you:
+
+- **`biab-dev wipe-collections`** — the backup-first record wipe (two-stage
+  confirmation, verified Media backup, state-bound execution) documented under
+  0.9.50.
+- **Generated-form schema sync** — `sync-data-model` accepts the full
+  orchestrator result, offers the interactive candidate multi-select, and
+  supports `--forms`, `--forms slug-a,slug-b`, and `--no-forms` for CI.
+- **The compile-time `Infer*` family** — `InferFieldValue`,
+  `InferFieldsValues`, `InferCollectionValues`, `InferFormValues`,
+  `InferSchemaValues` (+ the type-inference compile tests behind them).
+- **Multi-location business details** — `companyAddressSchema` /
+  `companyLocationSchema`, `BusinessAddress` / `BusinessLocation`,
+  `localBusinessLocations()` + `biabSchemas.localBusinessLocations()`, and the
+  extended `localBusiness()` builder.
+- **Deterministic fluent identities** — collection, field, injected
+  primary-key, junction, and generated-form IDs converge across CLI
+  evaluations; camelCase junction fields and distinct `source…Id` /
+  `target…Id` self-relation fields.
+- **Correct published artifacts** — root declarations generated from the
+  TypeScript build (replacing the handwritten ambient declaration) and the
+  `dist/index.cjs` runtime file the `require` export map had been promising.
+- **Legacy docs archive** — the 0.9.35 README/CHANGELOG moved to
+  `docs-legacy/0.9.35/`, and the package README was rebuilt around the 0.9.50
+  pipeline.
+
+## Legacy Docs
+
+The 0.9.35 docs are archived at [`docs-legacy/0.9.35/`](./docs-legacy/0.9.35/).