@builder-builder/builder 0.0.22 → 0.0.24

package/README.md

@@ -17,9 +17,40 @@ Where BB runs and which backing services it talks to.
 | local dev         | Clerk test       | local supabase (docker) |
 | Vercel production | Clerk production | Supabase cloud project  |
 
+## What lives where
+
+Knowing what's stored in Clerk vs Supabase matters because `npm run db:reset` wipes Supabase but not Clerk.
+
+| 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`                     |
+
+After a reset, you typically re-seed entities from a consumer repo. API keys keep working — re-seeding only repopulates Supabase.
+
 ## Builder environments
 
-Every entity carries an `environment` of `development`, `staging`, or `production`. Same database, different rows. `development` rows are mutable; `staging` and `production` are immutable snapshots written when promoting from `development`.
+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.
+
+| 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
 
@@ -33,15 +64,18 @@ Each API key is minted in `/settings` with three properties:
 
 Keys are scoped to the org they were minted in and never see other orgs' data.
 
-| 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             |
+### 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.
 
 ## Scripts
 
 - `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.
+- `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.js

@@ -2,15 +2,25 @@ 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);
+    const { url, apiKey, headers } = v.parse(BuilderBuilderClientOptionsSchema, options);
     return {
         builder: {
             get: async (id) => {
-                const response = await fetch(`${url}/api/builder/${id}`, {
-                    headers: { 'X-Builder-Builder-Key': apiKey }
+                const requestUrl = `${url}/api/builder/${id}`;
+                const response = await fetch(requestUrl, {
+                    headers: {
+                        ...headers,
+                        'X-Builder-Builder-Key': apiKey
+                    }
                 });
                 if (!response.ok) {
-                    throw new BuilderException([]);
+                    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/schema.d.ts

@@ -2,6 +2,7 @@ import * as v from 'valibot';
 export declare const BuilderBuilderClientOptionsSchema: v.ObjectSchema<{
     readonly url: v.StringSchema<undefined>;
     readonly apiKey: v.StringSchema<undefined>;
+    readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;
 export type BuilderBuilderClientOptions = v.InferOutput<typeof BuilderBuilderClientOptionsSchema>;
 export declare const BuilderBuilderGetResponseSchema: v.ObjectSchema<{

package/dist/client/schema.js

@@ -3,7 +3,8 @@ import { BuilderReferencesSchema, BuilderSerialisedSchema } from '../entities/in
 import { BuilderVariantsSchema } from '../instance.js';
 export const BuilderBuilderClientOptionsSchema = v.object({
     url: v.string(),
-    apiKey: v.string()
+    apiKey: v.string(),
+    headers: v.optional(v.record(v.string(), v.string()))
 });
 export const BuilderBuilderGetResponseSchema = v.object({
     name: v.string(),

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,6 +1,6 @@
 {
   "name": "@builder-builder/builder",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -39,7 +39,7 @@
     "lint": "prettier --check . && eslint .",
     "test": "npm run test:unit -- --run",
     "test:unit": "npm run messages && vitest --project client --project server",
-    "test:integration:local": "npm run messages && dotenv -e .env.development.local -- 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/server/db/database.types.ts'",
     "db:types:local": "supabase gen types typescript --local > ./src/lib/server/db/database.types.ts",