@builder-builder/builder 0.0.21 → 0.0.23

package/README.md

@@ -1,38 +1,81 @@
-# sv
+# Builder Builder
 
-Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+## Setup
 
-## Creating a project
+```bash
+npm install
+supabase start
+npm run dev
+```
 
-If you're seeing this, you've probably already done this step. Congrats!
+## Deployment environments
 
-```bash
-# create a new project in the current directory
-npx sv create
+Where BB runs and which backing services it talks to.
 
-# create a new project in my-app
-npx sv create my-app
-```
+| Deployment        | Clerk instance   | Supabase instance       |
+| ----------------- | ---------------- | ----------------------- |
+| local dev         | Clerk test       | local supabase (docker) |
+| Vercel production | Clerk production | Supabase cloud project  |
 
-## Developing
+## What lives where
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+Knowing what's stored in Clerk vs Supabase matters because `npm run db:reset` wipes Supabase but not Clerk.
 
-```bash
-npm run dev
+| Lives in Clerk (survives `db:reset`) | Lives in Supabase (wiped by `db:reset`) |
+| ------------------------------------ | --------------------------------------- |
+| Users, orgs, roles, permissions      | `entities`, `entity_edits`              |
+| API keys (with all their claims)     | `builder_versions`                      |
+|                                      | `variants`, `variant_edits`             |
+|                                      | `entity_references`                     |
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
-```
+After a reset, you typically re-seed entities from a consumer repo. API keys keep working — re-seeding only repopulates Supabase.
 
-## Building
+## Builder environments
 
-To create a production version of your app:
+Every entity carries an `environment` of `development`, `staging`, or `production`. Same database, different tables/rows. `development` rows are mutable; `staging` and `production` are immutable snapshots written by promotion.
 
-```bash
-npm run build
-```
+| Environment   | `GET /api/builder/[id]` returns | `GET /api/builder/[id]/variants` returns |
+| ------------- | ------------------------------- | ---------------------------------------- |
+| `development` | live editable entity            | live editable variants                   |
+| `staging`     | staging snapshot                | staging snapshot variants                |
+| `production`  | production snapshot             | production snapshot variants             |
+
+## Promotion
+
+The only path from `development` (mutable working copy) into `staging` or `production` (immutable snapshots) is through the **Promote** action in BB's UI. Promotion:
+
+1. Runs validation on the entity and its references.
+2. If validation passes, writes a new immutable row into the target environment's snapshot table.
+3. If validation fails, the promote is rejected — nothing changes.
+
+So `builder_versions` is, by construction, always free of validation errors. Consumers reading with `environment: production` never see broken data; consumers reading with `environment: development` may see in-flight errors and should expect to handle them.
+
+Bulk writes that bypass the UI (like a seed script) land in `entities` only — they still need a UI promote afterwards to become visible to `production`-env consumers.
+
+## API key scoping
+
+Each API key is minted in `/settings` with three properties:
+
+| Property            | What it controls                                                                                                                                                                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Environment**     | Which dataset the key reads from: `development`, `staging`, or `production`.                                                                                                                                                                                                                                      |
+| **Profile**         | What the key can do. `read` keys can fetch; `readWrite` keys can also write variants.                                                                                                                                                                                                                             |
+| **Allowed origins** | Origin patterns (e.g. `https://*.example.com`) the key may be used from. Set this for browser keys; leave empty for server-to-server keys. The two modes are exclusive — a key with allowed origins requires an Origin header that matches, and a key without them rejects any request that has an Origin header. |
+
+Keys are scoped to the org they were minted in and never see other orgs' data.
+
+### Clerk permissions
+
+API key management is gated by `org:api_keys:{create,read,update,delete}`. These are **custom organization permissions** — Clerk doesn't ship them. In the Clerk dashboard:
+
+1. **Configure → Roles & Permissions → Permissions** — define `api_keys:create`, `api_keys:read`, `api_keys:update`, `api_keys:delete` (Clerk prefixes them with `org:` automatically).
+2. **Edit the org Admin role** — check all four, then **save** (defining a permission and granting it to a role are separate steps).
+
+Members need to sign out/in for new role permissions to land in their session token. Setup is per-Clerk-instance, so repeat for Clerk test and Clerk production.
 
-You can preview the production build with `npm run preview`.
+## Scripts
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+- `npm run verify` — tests, check, format, lint.
+- `npm run test:integration:local` — integration tests against local Supabase.
+- `npm run db:types:local` — regenerate `database.types.ts` from local schema.
+- `npm run db:reset` — wipe local Supabase, re-diff migrations, regenerate types. **Does not** touch Clerk.

package/dist/bb.js

@@ -75,7 +75,7 @@ function bbFactory(environment, references = []) {
             return result;
         }
         if (errors.length > 0) {
-            throw new BuilderException(errors);
+            throw new BuilderException({ category: 'validation', errors });
         }
         return [entity, []];
     }

package/dist/client/client.d.ts

@@ -0,0 +1,7 @@
+import type { BuilderBuilderClientOptions, BuilderBuilderGetResponse } from './schema.js';
+export type BuilderBuilderClient = {
+    builder: {
+        get(id: string): Promise<BuilderBuilderGetResponse>;
+    };
+};
+export declare function client(options: BuilderBuilderClientOptions): BuilderBuilderClient;

package/dist/client/client.js

@@ -0,0 +1,26 @@
+import * as v from 'valibot';
+import { BuilderException } from '../errors/index.js';
+import { BuilderBuilderClientOptionsSchema, BuilderBuilderGetResponseSchema } from './schema.js';
+export function client(options) {
+    const { url, apiKey } = v.parse(BuilderBuilderClientOptionsSchema, options);
+    return {
+        builder: {
+            get: async (id) => {
+                const requestUrl = `${url}/api/builder/${id}`;
+                const response = await fetch(requestUrl, {
+                    headers: { 'X-Builder-Builder-Key': apiKey }
+                });
+                if (!response.ok) {
+                    throw new BuilderException({
+                        category: 'request',
+                        url: requestUrl,
+                        status: response.status,
+                        statusText: response.statusText,
+                        body: await response.text()
+                    });
+                }
+                return v.parse(BuilderBuilderGetResponseSchema, await response.json());
+            }
+        }
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export type { BuilderBuilderClientOptions, BuilderBuilderGetResponse } from './schema.js';
+export type { BuilderBuilderClient } from './client.js';
+export { BuilderBuilderClientOptionsSchema, BuilderBuilderGetResponseSchema } from './schema.js';
+export { client } from './client.js';

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { BuilderBuilderClientOptionsSchema, BuilderBuilderGetResponseSchema } from './schema.js';
+export { client } from './client.js';

package/dist/client/schema.d.ts

@@ -0,0 +1,396 @@
+import * as v from 'valibot';
+export declare const BuilderBuilderClientOptionsSchema: v.ObjectSchema<{
+    readonly url: v.StringSchema<undefined>;
+    readonly apiKey: v.StringSchema<undefined>;
+}, undefined>;
+export type BuilderBuilderClientOptions = v.InferOutput<typeof BuilderBuilderClientOptionsSchema>;
+export declare const BuilderBuilderGetResponseSchema: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly serialised: v.GenericSchema<import("../index.js").BuilderSerialised>;
+    readonly references: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly serialised: v.GenericSchema<string | number | boolean | readonly (string | number)[] | readonly (readonly (string | number)[])[] | import("../index.js").BuilderSerialised | import("../index.js").BuilderModelSerialised | Readonly<{
+            type: "select";
+            readonly options: readonly [string, ...string[]];
+            defaultValue: string | null;
+            isOptional: boolean;
+            optionLabels: {
+                [x: string]: string;
+            };
+            tags?: readonly string[] | undefined;
+        }> | Readonly<{
+            type: "toggle";
+            valueType: "string" | "number" | "boolean";
+            defaultValue: string | number | boolean | null;
+            isOptional: boolean;
+            tags?: readonly string[] | undefined;
+        }> | import("../index.js").BuilderMatchSelectMap<Readonly<{
+            type: "parameter";
+            id: string;
+            name: string;
+        }> | Readonly<Readonly<{
+            type: "select";
+            readonly options: readonly [string, ...string[]];
+            defaultValue: string | null;
+            isOptional: boolean;
+            optionLabels: {
+                [x: string]: string;
+            };
+            tags?: readonly string[] | undefined;
+        }>> | Readonly<Readonly<{
+            type: "toggle";
+            valueType: "string" | "number" | "boolean";
+            defaultValue: string | number | boolean | null;
+            isOptional: boolean;
+            tags?: readonly string[] | undefined;
+        }>>> | import("../index.js").BuilderWhenSerialised<Readonly<Readonly<{
+            type: "select";
+            readonly options: readonly [string, ...string[]];
+            defaultValue: string | null;
+            isOptional: boolean;
+            optionLabels: {
+                [x: string]: string;
+            };
+            tags?: readonly string[] | undefined;
+        }>> | Readonly<Readonly<{
+            type: "toggle";
+            valueType: "string" | "number" | "boolean";
+            defaultValue: string | number | boolean | null;
+            isOptional: boolean;
+            tags?: readonly string[] | undefined;
+        }>>> | Readonly<{
+            fields: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | readonly Readonly<{
+                type: "component-field";
+                name: string;
+                valueType: "string" | "number" | "boolean";
+                isOptional: boolean;
+                tags?: readonly string[] | undefined;
+            }>[];
+            tags?: readonly string[] | undefined;
+        }> | import("../index.js").BuilderMatchSelectMap<Readonly<{
+            type: "parameter";
+            id: string;
+            name: string;
+        }> | Readonly<{
+            fields: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | readonly Readonly<{
+                type: "component-field";
+                name: string;
+                valueType: "string" | "number" | "boolean";
+                isOptional: boolean;
+                tags?: readonly string[] | undefined;
+            }>[];
+            tags?: readonly string[] | undefined;
+        }>> | import("../index.js").BuilderWhenSerialised<Readonly<{
+            fields: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | readonly Readonly<{
+                type: "component-field";
+                name: string;
+                valueType: "string" | "number" | "boolean";
+                isOptional: boolean;
+                tags?: readonly string[] | undefined;
+            }>[];
+            tags?: readonly string[] | undefined;
+        }>> | Readonly<{
+            model: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | import("../index.js").BuilderModelSerialised;
+            min: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            max: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            tags?: readonly string[] | undefined;
+        }> | import("../index.js").BuilderMatchSelectMap<Readonly<{
+            type: "parameter";
+            id: string;
+            name: string;
+        }> | Readonly<{
+            model: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | import("../index.js").BuilderModelSerialised;
+            min: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            max: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            tags?: readonly string[] | undefined;
+        }>> | import("../index.js").BuilderWhenSerialised<Readonly<{
+            model: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | import("../index.js").BuilderModelSerialised;
+            min: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            max: number | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            tags?: readonly string[] | undefined;
+        }>> | import("../index.js").BuilderUISerialised | Readonly<{
+            type: "input";
+            path: readonly (string | number)[] | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            displayName?: string | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | undefined;
+            kind?: string | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | undefined;
+            metadata?: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | Readonly<{
+                [x: string]: unknown;
+            }> | undefined;
+            tags?: readonly string[] | undefined;
+        }> | Readonly<{
+            type: "page";
+            label: string | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            inputs: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | readonly (Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | Readonly<{
+                type: "input";
+                path: readonly (string | number)[] | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }>;
+                displayName?: string | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | undefined;
+                kind?: string | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | undefined;
+                metadata?: Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | Readonly<{
+                    [x: string]: unknown;
+                }> | undefined;
+                tags?: readonly string[] | undefined;
+            }>)[];
+            tags?: readonly string[] | undefined;
+        }> | Readonly<{
+            type: "describe";
+            label: string | Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }>;
+            inputs: Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | readonly (Readonly<{
+                type: "parameter";
+                id: string;
+                name: string;
+            }> | Readonly<{
+                type: "ref";
+                id: string;
+            }> | Readonly<{
+                type: "input";
+                path: readonly (string | number)[] | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }>;
+                displayName?: string | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | undefined;
+                kind?: string | Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | undefined;
+                metadata?: Readonly<{
+                    type: "parameter";
+                    id: string;
+                    name: string;
+                }> | Readonly<{
+                    type: "ref";
+                    id: string;
+                }> | Readonly<{
+                    [x: string]: unknown;
+                }> | undefined;
+                tags?: readonly string[] | undefined;
+            }>)[];
+            tags?: readonly string[] | undefined;
+        }> | import("../index.js").BuilderUIPagesSerialised | readonly (Readonly<{
+            type: "parameter";
+            id: string;
+            name: string;
+        }> | Readonly<{
+            type: "ref";
+            id: string;
+        }> | import("../entities/index.js").BuilderUIItemSerialised)[] | import("../index.js").BuilderPricingSerialised | import("../entities/index.js").BuilderRates | readonly Readonly<{
+            name: string;
+            kind: "option" | "component" | "collection";
+        }>[]>;
+    }, undefined>, undefined>;
+    readonly variants: v.SchemaWithPipe<readonly [v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+        readonly instance: v.GenericSchema<import("../instance.js").BuilderInstance>;
+        readonly details: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.NullableSchema<v.UnionSchema<[v.StringSchema<undefined>, v.BooleanSchema<undefined>, v.NumberSchema<undefined>], undefined>, undefined>, undefined>, undefined>;
+        readonly tags: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.ReadonlyAction<string[]>]>, undefined>;
+    }, undefined>, v.ReadonlyAction<{
+        instance: import("../instance.js").BuilderInstance;
+        details?: {
+            [x: string]: string | number | boolean | null;
+        } | undefined;
+        tags?: readonly string[] | undefined;
+    }>]>, undefined>, v.ReadonlyAction<Readonly<{
+        instance: import("../instance.js").BuilderInstance;
+        details?: {
+            [x: string]: string | number | boolean | null;
+        } | undefined;
+        tags?: readonly string[] | undefined;
+    }>[]>]>, undefined>, v.ReadonlyAction<{
+        readonly [x: string]: readonly Readonly<{
+            instance: import("../instance.js").BuilderInstance;
+            details?: {
+                [x: string]: string | number | boolean | null;
+            } | undefined;
+            tags?: readonly string[] | undefined;
+        }>[];
+    }>]>;
+}, undefined>;
+export type BuilderBuilderGetResponse = v.InferOutput<typeof BuilderBuilderGetResponseSchema>;

package/dist/client/schema.js

@@ -0,0 +1,13 @@
+import * as v from 'valibot';
+import { BuilderReferencesSchema, BuilderSerialisedSchema } from '../entities/index.js';
+import { BuilderVariantsSchema } from '../instance.js';
+export const BuilderBuilderClientOptionsSchema = v.object({
+    url: v.string(),
+    apiKey: v.string()
+});
+export const BuilderBuilderGetResponseSchema = v.object({
+    name: v.string(),
+    serialised: BuilderSerialisedSchema,
+    references: BuilderReferencesSchema,
+    variants: BuilderVariantsSchema
+});

package/dist/errors/check.d.ts

@@ -1,7 +1,7 @@
 import * as v from 'valibot';
 declare class Check {
-    truthy<Input>(input: Input, message?: `${string}! ❌`): asserts input is Exclude<Input, null | undefined | '' | 0 | false>;
-    falsy(input: unknown, message?: `${string}! ❌`): void;
+    truthy<Input>(input: Input, message: `${string}! ❌`): asserts input is Exclude<Input, null | undefined | '' | 0 | false>;
+    falsy(input: unknown, message: `${string}! ❌`): void;
     is<const Schema extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(schema: Schema, input: unknown): input is v.InferOutput<Schema>;
     assert<const Schema extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(schema: Schema, input: unknown, message?: `${string}! ❌`): asserts input is v.InferOutput<Schema>;
 }

package/dist/errors/check.js

@@ -1,24 +1,29 @@
 import * as v from 'valibot';
-import { BuilderException } from './exception.js';
-const DEFAULT_MESSAGE = 'Unexpected value! ❌';
+import { BuilderException, formatSchemaIssues } from './exception.js';
 class Check {
-    truthy(input, message = DEFAULT_MESSAGE) {
+    truthy(input, message) {
         if (!input) {
-            throw new BuilderException([], message);
+            throw new BuilderException({ category: 'assertion', summary: message });
         }
     }
-    falsy(input, message = DEFAULT_MESSAGE) {
+    falsy(input, message) {
         if (input) {
-            throw new BuilderException([], message);
+            throw new BuilderException({ category: 'assertion', summary: message });
         }
     }
     is(schema, input) {
         return v.is(schema, input);
     }
-    assert(schema, input, message = DEFAULT_MESSAGE) {
-        if (!v.is(schema, input)) {
-            throw new BuilderException([], message);
+    assert(schema, input, message) {
+        const result = v.safeParse(schema, input);
+        if (result.success) {
+            return;
         }
+        throw new BuilderException({
+            category: 'assertion',
+            summary: message ?? formatSchemaIssues(result.issues),
+            issues: result.issues
+        });
     }
 }
 export const check = new Check();

package/dist/errors/exception.d.ts

@@ -1,5 +1,22 @@
 import type { BuilderErrors } from './errors';
-export declare class BuilderException extends globalThis.Error {
+import * as v from 'valibot';
+export type BuilderExceptionPayload = {
+    readonly category: 'validation';
     readonly errors: BuilderErrors;
-    constructor(errors: BuilderErrors, message?: string);
+} | {
+    readonly category: 'assertion';
+    readonly summary: string;
+    readonly issues?: ReadonlyArray<v.BaseIssue<unknown>>;
+} | {
+    readonly category: 'request';
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+};
+export declare class BuilderException extends globalThis.Error {
+    readonly payload: BuilderExceptionPayload;
+    constructor(payload: BuilderExceptionPayload);
+    get errors(): BuilderErrors;
 }
+export declare function formatSchemaIssues(issues: ReadonlyArray<v.BaseIssue<unknown>>): `${string}! ❌`;

package/dist/errors/exception.js

@@ -1,7 +1,77 @@
+import * as v from 'valibot';
 export class BuilderException extends globalThis.Error {
-    errors;
-    constructor(errors, message = '') {
-        super(`BuilderBuilder exception 🏗️${message ? `: ${message}` : ''}`);
-        this.errors = errors;
+    payload;
+    constructor(payload) {
+        super(formatMessage(payload));
+        this.payload = payload;
     }
+    get errors() {
+        return this.payload.category === 'validation' ? this.payload.errors : [];
+    }
+}
+export function formatSchemaIssues(issues) {
+    const [first, ...rest] = issues;
+    if (!first) {
+        return 'Schema validation failed! ❌';
+    }
+    const path = formatIssuePath(first);
+    const location = path ? ` at ${path}` : '';
+    const more = rest.length > 0 ? ` (+${rest.length} more)` : '';
+    return `${first.message}${location}${more}! ❌`;
+}
+const HEADER = 'BuilderBuilder error 🏗️';
+function formatMessage(payload) {
+    if (payload.category === 'validation') {
+        return formatValidation(payload.errors);
+    }
+    if (payload.category === 'assertion') {
+        return `${HEADER} — ${payload.summary}`;
+    }
+    return formatRequest(payload);
+}
+function formatValidation(errors) {
+    if (errors.length === 0) {
+        return `${HEADER} — validation failed`;
+    }
+    const noun = errors.length === 1 ? 'issue' : 'issues';
+    const lines = errors.map((error) => `  • ${formatBuilderError(error)}`);
+    return `${HEADER} — ${errors.length} validation ${noun}:\n${lines.join('\n')}`;
+}
+function formatBuilderError(error) {
+    const { kind, location, ...rest } = error;
+    const locationLabel = location.length > 0 ? ` at ${location.join('.')}` : '';
+    const detailEntries = Object.entries(rest);
+    if (detailEntries.length === 0) {
+        return `${kind}${locationLabel}`;
+    }
+    const details = detailEntries.map(([key, value]) => `${key}=${formatValue(value)}`).join(', ');
+    return `${kind}${locationLabel}: ${details}`;
+}
+function formatRequest(payload) {
+    const { url, status, statusText, body } = payload;
+    const statusLine = statusText ? `${status} ${statusText}` : `${status}`;
+    return `${HEADER} — Builder API request failed: ${statusLine}\n  url: ${url}\n  body: ${body}`;
+}
+function formatIssuePath(issue) {
+    if (!issue.path) {
+        return '';
+    }
+    return issue.path.map((segment) => segment.key).join('.');
+}
+function formatValue(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
 }

package/dist/errors/index.d.ts

@@ -1,4 +1,5 @@
 export type { BuilderError, BuilderErrorKind, BuilderErrorLocation, BuilderErrors } from './errors';
+export type { BuilderExceptionPayload } from './exception.js';
 export { check } from './check.js';
 export { BuilderValidateErrors } from './errors.js';
 export { BuilderException } from './exception.js';

package/dist/validate/brand.js

@@ -8,6 +8,6 @@ export function assertValidated(value) {
     if (typeof value !== 'object' || value === null || !VALIDATED_ENTITIES.has(value)) {
         const errors = new BuilderValidateErrors();
         errors.unvalidated(value);
-        throw new BuilderException(errors.errors);
+        throw new BuilderException({ category: 'validation', errors: errors.errors });
     }
 }

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@builder-builder/builder",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
     }
   },
   "files": [
@@ -18,9 +25,9 @@
   },
   "scripts": {
     "dev": "vite dev",
-    "predev": "npm run types:db",
+    "predev": "npm run db:types:local",
     "dev:v": "NO_UPDATE_NOTIFIER=false VERCEL_ENV=development vercel dev",
-    "build": "vite build",
+    "build": "NODE_ENV=production vite build",
     "package": "svelte-kit sync && svelte-package --input src/lib/builder",
     "preview": "vite preview",
     "prepare": "svelte-kit sync && npm run messages || echo ''",
@@ -32,10 +39,10 @@
     "lint": "prettier --check . && eslint .",
     "test": "npm run test:unit -- --run",
     "test:unit": "npm run messages && vitest --project client --project server",
-    "test:integration": "npm run messages && vitest run --project integration",
+    "test:integration:local": "npm run messages && dotenv -e .env.development.local -- sh -c 'npx tsx scripts/integration-clean.ts && vitest run --project integration'",
     "verify": "npm run test && npm run check && npm run lint",
-    "db:types": "dotenv -e .env -- sh -c 'supabase gen types typescript --project-id \"$SUPABASE_DEV_PROJECT_ID\" --schema public > ./src/lib/db/database.types.ts'",
-    "db:types:local": "supabase gen types typescript --local > ./src/lib/db/database.types.ts",
+    "db:types": "dotenv -e .env -- sh -c 'supabase gen types typescript --project-id \"$SUPABASE_DEV_PROJECT_ID\" --schema public > ./src/lib/server/db/database.types.ts'",
+    "db:types:local": "supabase gen types typescript --local > ./src/lib/server/db/database.types.ts",
     "db:reset": "rm -f supabase/migrations/*_initial.sql && supabase db diff --use-pg-delta -f initial && supabase db reset && npm run db:types:local"
   },
   "devDependencies": {