@businessdash/sdk 0.9.60

package/dist/data-model-schema.d.ts

@@ -0,0 +1,962 @@
+/**
+ * `defineDataModel` — declare an org's custom database (tables + enums) in
+ * code, push it with `biab-dev sync-data-model`, promote it in the dashboard.
+ *
+ * Deliberately SEPARATE from `marketing-schema.ts`. A website's content shape
+ * and an org's database shape are different artifacts with different review
+ * cadence, blast radius, and plausibly different owners — so they get separate
+ * config files, commands, endpoints, and API scopes. Nothing is shared but the
+ * transport conventions (canonical checksum, draft/published slots).
+ *
+ *   biab.config.ts             → defineSiteMarketingSchema → sync-schema
+ *   biab.data-model.config.ts  → defineDataModel           → sync-data-model
+ *
+ * Pure builders — no DB, no network, no side effects. Validation here is about
+ * catching a typo in CI before it becomes a push; the server re-validates
+ * everything it receives and is the real authority.
+ *
+ * See Resources/BIAB-Data-Model-CLI-Plan.md for the full design.
+ */
+/**
+ * Value kinds a field can hold. Mirrors the platform's FieldType catalog.
+ * Not every entry is accepted by the push endpoint yet — see
+ * `UNSUPPORTED_FIELD_TYPES`.
+ */
+import type { EnumEntry } from "./enums.js";
+export declare const FIELD_TYPES: readonly ["TEXT", "NUMBER", "NUMERIC", "BOOLEAN", "DATE", "DATE_TIME", "UUID", "SELECT", "MULTI_SELECT", "RATING", "POSITION", "CURRENCY", "EMAILS", "PHONES", "LINKS", "ADDRESS", "FULL_NAME", "ACTOR", "RELATION", "MORPH_RELATION", "FILES", "RICH_TEXT", "RAW_JSON", "ARRAY", "TS_VECTOR"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+export declare function isFieldType(value: string): value is FieldType;
+/** Common field options that can be chained. */
+export interface FieldOptions {
+    required?: boolean;
+    nullable?: boolean;
+    defaultValue?: unknown;
+    indexed?: boolean;
+    unique?: boolean;
+    description?: string;
+}
+/** Relation metadata for relationship descriptors. */
+export interface RelationMetadata {
+    type: "one-to-many" | "many-to-many";
+    targetCollection: string;
+    joinCollectionName?: string;
+    fields?: Record<string, AnyFieldBuilder>;
+    onDeleteAction?: DeleteAction;
+}
+/** Builder for a single field definition. */
+export interface FieldBuilder<T extends FieldType = FieldType, TValue = InferJsType<T>, TRequired extends boolean = false, TNullable extends boolean = true> {
+    readonly __valueType?: TValue;
+    readonly __requiredType?: TRequired;
+    readonly __nullableType?: TNullable;
+    required: () => FieldBuilder<T, TValue, true, false>;
+    optional: () => FieldBuilder<T, TValue, false, true>;
+    nullable: <TNextNullable extends boolean = true>(value?: TNextNullable) => FieldBuilder<T, TValue, TRequired, TNextNullable>;
+    default: (value: unknown) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    indexed: (value?: boolean) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    unique: (value?: boolean) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    description: (text: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    helper: (text: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    formElement: (element: AllFormElements, metadata?: ElementMetadata) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    validate: (rules: ValidationRules) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    dynamicOptions: (config: DynamicOptionsDef) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    requiredIf: (condition: RequiredIfCondition) => FieldBuilder<T, TValue, false, TNullable>;
+    regex: (pattern: RegExp | string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    check: (sqlExpression: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    strategy: (mode: StorageStrategy, separateTableName?: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    encrypted: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+    encryptedLight: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+    private: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+    references: (targetCollection: string, onDelete?: "restrict" | "setNull" | "cascade") => FieldBuilder<"RELATION", string, TRequired, TNullable>;
+    /**
+     * This record may reference SEVERAL of `targetCollection`.
+     *
+     * That's the whole declaration — there is no join table to name, design, or
+     * maintain. BIAB stores every link in one universal link table, so "many"
+     * is a property of the relation rather than a second collection the author
+     * has to invent and keep in step.
+     *
+     * `fields` optionally declares values that belong to the PAIRING rather than
+     * to either side ("this technology, at expert level").
+     *
+     * `joinCollectionName` is accepted for backwards compatibility and ignored;
+     * nothing has ever read it.
+     */
+    belongsToMany: (targetCollection: string, options?: {
+        /** @deprecated Ignored — BIAB has no per-pair join table to name. */
+        joinCollectionName?: string;
+        fields?: Record<string, AnyFieldBuilder>;
+    }) => FieldBuilder<"RELATION", string[], TRequired, TNullable>;
+    onDelete: (action: DeleteAction) => FieldBuilder<T, TValue, TRequired, TNullable>;
+    build: () => FieldDefinition;
+}
+export type AnyFieldBuilder = FieldBuilder<FieldType, unknown, boolean, boolean>;
+type RequiredFromOptions<O> = O extends {
+    required: true;
+} ? true : false;
+type NullableFromOptions<O> = O extends {
+    nullable: infer N extends boolean;
+} ? N : O extends {
+    required: true;
+} ? false : true;
+type EnumValue<T> = T extends {
+    values: readonly (infer V extends string)[];
+} ? V : T extends readonly (infer Entry)[] ? Entry extends string ? Entry : Entry extends {
+    value: infer V extends string;
+} ? V : never : string;
+/** Runtime value stored by a measurement field. */
+export interface MeasurementValue {
+    value: number;
+    unit: string;
+}
+/** A field builder whose required and nullable flags were supplied as options. */
+export type ConfiguredFieldBuilder<T extends FieldType, TValue, O extends FieldOptions | undefined> = FieldBuilder<T, TValue, RequiredFromOptions<O>, NullableFromOptions<O>>;
+/** Infer the submitted/runtime value represented by a single field builder. */
+export type InferFieldValue<B> = B extends FieldBuilder<infer _T, infer TValue, infer _TRequired, infer TNullable> ? true extends TNullable ? TValue | null : TValue : never;
+type RequiredFieldKeys<F extends Record<string, AnyFieldBuilder>> = {
+    [K in keyof F]-?: F[K] extends FieldBuilder<infer _T, infer _TValue, infer TRequired, infer _TNullable> ? TRequired extends true ? K : never : never;
+}[keyof F];
+type OptionalFieldKeys<F extends Record<string, AnyFieldBuilder>> = Exclude<keyof F, RequiredFieldKeys<F>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Infer an object value type from a map of BIAB field declarations. */
+export type InferFieldsValues<F extends Record<string, AnyFieldBuilder>> = Simplify<{
+    [K in RequiredFieldKeys<F>]: InferFieldValue<F[K]>;
+} & {
+    [K in OptionalFieldKeys<F>]?: InferFieldValue<F[K]> | undefined;
+}>;
+/** Result of calling a fields method (e.g., fields.text()) */
+export interface FieldSpec extends FieldDefinition {
+}
+/** The fields namespace object — entry point for the fluent field API. */
+export interface Fields {
+    text: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"TEXT", string, O>;
+    number: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"NUMBER", number, O>;
+    numeric: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"NUMERIC", number, O>;
+    boolean: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"BOOLEAN", boolean, O>;
+    date: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"DATE", string, O>;
+    dateTime: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"DATE_TIME", string, O>;
+    uuid: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"UUID", string, O>;
+    enum: <const T extends readonly (string | {
+        value: string;
+        label?: string;
+    })[] | {
+        values: readonly string[];
+        entries: EnumEntry[];
+    }, O extends FieldOptions | undefined = undefined>(values: T, options?: O) => ConfiguredFieldBuilder<"SELECT", EnumValue<T>, O>;
+    multiEnum: <const T extends readonly (string | {
+        value: string;
+        label?: string;
+    })[] | {
+        values: readonly string[];
+        entries: EnumEntry[];
+    }, O extends FieldOptions | undefined = undefined>(values: T, options?: O) => ConfiguredFieldBuilder<"MULTI_SELECT", EnumValue<T>[], O>;
+    reference: <O extends (FieldOptions & {
+        onDelete?: "restrict" | "setNull" | "cascade";
+    }) | undefined = undefined>(targetCollection: string, options?: O) => ConfiguredFieldBuilder<"RELATION", string, O>;
+    relation: () => FieldBuilder<"RELATION", string>;
+    url: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"TEXT", string, O>;
+    email: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"EMAILS", string, O>;
+    phone: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"PHONES", string, O>;
+    richText: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"RICH_TEXT", string, O>;
+    json: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"RAW_JSON", unknown, O>;
+    array: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"ARRAY", unknown[], O>;
+    measurement: <O extends FieldOptions | undefined = undefined>(config: MeasurementDef, options?: O) => ConfiguredFieldBuilder<"RAW_JSON", MeasurementValue, O>;
+    object: <F extends Record<string, AnyFieldBuilder>, O extends FieldOptions | undefined = undefined>(config: {
+        properties: F;
+    } | F, options?: O) => ConfiguredFieldBuilder<"RAW_JSON", InferFieldsValues<F>, O>;
+    file: <O extends FieldOptions | undefined = undefined>(config?: FileDef, options?: O) => ConfiguredFieldBuilder<"FILES", unknown[], O>;
+    address: <O extends FieldOptions | undefined = undefined>(config?: AddressDef, options?: O) => ConfiguredFieldBuilder<"RAW_JSON", Record<string, unknown>, O>;
+    geo: <O extends FieldOptions | undefined = undefined>(options?: O) => ConfiguredFieldBuilder<"RAW_JSON", Record<string, unknown>, O>;
+}
+/** The fields builder namespace — exported for consumer use. */
+export declare const fields: Fields;
+/**
+ * Compact alias for `fields`. Same object, shorter name.
+ *
+ * ```ts
+ * import { bd } from "@businessdash/sdk";
+ *
+ * collection("features", {
+ *   fields: {
+ *     name: bd.text().required(),
+ *   },
+ * });
+ * ```
+ */
+export declare const bd: Fields;
+/** Collection definition options */
+export interface CollectionOptions<F extends Record<string, AnyFieldBuilder> = Record<string, AnyFieldBuilder>> {
+    fields: F;
+    description?: string;
+    icon?: string;
+    visibility?: "private" | "authenticated" | "public";
+    labelIdentifierFieldName?: string;
+    /**
+     * Stable identity override. Usually unnecessary because collection()
+     * derives a deterministic UUID from tableName.
+     */
+    universalIdentifier?: string;
+    /** Override the primary key strategy for this collection. */
+    idType?: PrimaryKeyType;
+    /** Row-level security policies for this collection. */
+    rlsPolicies?: RlsPolicyConfig[];
+}
+/** Collection definition returned by collection(). */
+export interface CollectionDefinition<F extends Record<string, AnyFieldBuilder> = Record<string, AnyFieldBuilder>> extends ObjectDefinition {
+    fields: FieldDefinition[];
+    relations?: Array<{
+        fieldName: string;
+        meta: RelationMetadata;
+    }>;
+    /** Primary key strategy override for this collection. */
+    idType?: PrimaryKeyType;
+    /** Row-level security policies. */
+    rlsPolicies?: RlsPolicyConfig[];
+    /** Phantom type for field inference. */
+    __fields?: F;
+}
+/**
+ * Define a collection (table) with a fluent fields API.
+ *
+ * @example
+ * ```ts
+ * const FeatureStatus = Enums(["planned", "inProgress", "completed"]);
+ *
+ * const featureGroups = collection("feature_groups", {
+ *   fields: {
+ *     name: fields.text().required(),
+ *     category_id: fields.reference("categories").required(),
+ *     status: fields.enum(FeatureStatus).default("planned"),
+ *     icon: fields.text().optional(),
+ *     image_url: fields.url().optional(),
+ *   },
+ * });
+ * ```
+ */
+export declare function collection<F extends Record<string, AnyFieldBuilder>>(tableName: string, options: CollectionOptions<F>): CollectionDefinition<F>;
+/**
+ * Polymorphic relations (one field pointing at several object kinds) aren't
+ * accepted yet. Declaring one fails fast here rather than at upload.
+ */
+export declare const UNSUPPORTED_FIELD_TYPES: readonly FieldType[];
+/** Relation values live in a link table, not in the record's own storage. */
+export declare const RELATION_FIELD_TYPES: readonly FieldType[];
+export declare function isRelationFieldType(type: FieldType): boolean;
+/**
+ * One value in a SELECT / MULTI_SELECT field — what BIAB calls an "enum".
+ * Not a native Postgres enum: options are metadata, so adding or relabelling
+ * one costs no migration.
+ */
+export type SelectOption = {
+    /** The value a record actually stores. */
+    value: string;
+    label: string;
+    position: number;
+    color?: string;
+    /**
+     * Stable identity for this option, surviving a `value` rename.
+     *
+     * OPTIONAL, and the reason matters. Records store the option's `value`
+     * string, so renaming `"filed"` → `"submitted"` would otherwise read as
+     * remove-plus-add: a destructive-looking plan for a safe change, and every
+     * row holding the old string quietly fails validation. With an identifier,
+     * the diff sees a rename and backfills the rows.
+     *
+     * Omit it and nothing breaks — the diff falls back to matching on `value`,
+     * which is exactly the pre-existing behavior. Supply it and renames become
+     * safe. That's why this is additive rather than required: no migration is
+     * forced on options that already exist.
+     */
+    universalIdentifier?: string;
+};
+/** What happens to a record that something else still links to. */
+export type RelationOnDelete = "restrict" | "setNull" | "cascade";
+/** Delete action modifier for the fluent relation chain. */
+export type DeleteAction = "CASCADE" | "RESTRICT" | "SET NULL" | "NO ACTION";
+/** Primary key strategy for auto-injected id fields. */
+export type PrimaryKeyType = "uuid" | "integer";
+export type ExtTextType = "short_text" | "long_text" | "email" | "url" | "rich_text_input" | "dropdown" | "radio_group" | "checkbox_group" | "choice_cards" | "services_selector" | "phone_number" | "date" | "credit_card" | "collection_select" | "timePicker" | "time_picker.date" | "time_picker.time" | "color";
+export type ExtObjectType = "address_group" | "measurement" | "availability" | "object" | "geo" | "date_range" | "time_picker_timeslot" | "time_picker_datetime";
+export type ExtArrayType = "multi-select" | "checkbox_group_many" | "choice_cards_many" | "services_selector_many" | "tags" | "formFileValue";
+export type ExtBooleanType = "yes_no_toggle" | "yes_no_checkbox";
+export type ExtNumberType = "number" | "phone_number_basic" | "currency" | "range" | "star_rating" | "happiness_rating";
+export type AllFormElements = ExtTextType | ExtObjectType | ExtArrayType | ExtBooleanType | ExtNumberType;
+export type ChoiceCardDef = {
+    name: string;
+    icon?: string;
+    image_url?: string;
+    price?: number;
+    link_url?: string;
+    product_id?: string;
+    description?: string;
+};
+export type RangeDef = {
+    min: number;
+    max: number;
+    step?: number;
+    unit: "number" | "percentage" | "currency";
+};
+export type MeasurementCategory = "sound" | "pressure" | "torque" | "speed" | "time" | "area" | "volume" | "power" | "energy" | "storage" | "storageSpeed" | "frequency" | "temperature" | "mass" | "length" | "currency" | (string & {});
+export declare const PREDEFINED_UNITS: Record<string, readonly string[]>;
+export type MeasurementDef = {
+    category: MeasurementCategory;
+    unitPicker: "fixed" | "userDefined";
+    default_unit: string;
+    resolve_to_your_unit: string;
+    allow_decimals: boolean;
+};
+export type ObjectPropertyDef = {
+    name: string;
+    label?: string;
+    field: FieldDefinition;
+};
+export type ObjectSchemaDef = {
+    properties: ObjectPropertyDef[];
+    strategy?: StorageStrategy;
+    separateTableName?: string;
+};
+export type DynamicOptionsDef = {
+    endpoint: string;
+    cachePolicy?: "stale-while-revalidate" | "no-cache" | "cache-first";
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+};
+export type StorageStrategy = "flattened" | "jsonb" | "separateTable";
+export type EncryptionMode = "none" | "user" | "master";
+export type RlsPolicyConfig = {
+    roles: ("authenticated" | "anonymous" | "admin" | string)[];
+    actions: ("read" | "write" | "update" | "delete")[];
+    expression?: string;
+};
+export type RequiredIfCondition = {
+    fieldRef: string;
+    op: "equals" | "notEquals";
+    values: unknown[];
+};
+export type FileDef = {
+    max_size_mb?: number;
+    allowed_mimetypes?: string[];
+};
+export type AddressDef = {
+    require_postal_code?: boolean;
+    restrict_countries?: string[];
+};
+export type ElementMetadata = ChoiceCardDef[] | RangeDef | MeasurementDef | ObjectSchemaDef | FileDef | AddressDef | undefined;
+export type SpecialDateValue = "today()" | string | Date;
+export interface ValidationRules {
+    lessThan?: number;
+    greaterThan?: number;
+    lessThanToday?: boolean;
+    greaterThanToday?: boolean;
+    specificDateValue?: SpecialDateValue;
+    minLength?: number;
+    maxLength?: number;
+    floor?: boolean;
+    isDecimal?: boolean;
+    round?: number;
+    positive?: boolean;
+    notNull?: boolean;
+    requiredIf?: RequiredIfCondition;
+    regex?: RegExp | string;
+    checkExpression?: string;
+}
+/** Runtime field value validator using ValidationRules. */
+export declare function validateFieldValue(value: unknown, rules: ValidationRules, context?: Record<string, unknown>): {
+    valid: boolean;
+    value: unknown;
+    error?: string;
+};
+/** Runtime measurement value validator. */
+export declare function validateAndResolveMeasurement(input: {
+    value: unknown;
+    unit: string;
+}, meta: MeasurementDef): {
+    valid: boolean;
+    value?: {
+        value: number;
+        unit: string;
+    };
+    error?: string;
+};
+export type FieldDefinition = {
+    /** Stable identity. Survives renames — the diff keys on this, never on `name`. */
+    universalIdentifier: string;
+    /** camelCase. Doubles as the storage key, so renaming it backfills every row. */
+    name: string;
+    label: string;
+    type: FieldType;
+    icon?: string;
+    description?: string;
+    isRequired?: boolean;
+    isNullable?: boolean;
+    isUnique?: boolean;
+    defaultValue?: unknown;
+    isIndexed?: boolean;
+    isPrimaryKey?: boolean;
+    isAutoIncrement?: boolean;
+    position?: number;
+    /** Explicitly chosen form element for rendering. */
+    formElement?: AllFormElements;
+    /** Metadata payload for complex form elements (choice_cards options, range bounds). */
+    elementMetadata?: ElementMetadata;
+    /** Auto-populated list of compatible form elements for this field type. */
+    recommendedFormElements?: AllFormElements[];
+    /** Validation constraints for this field. */
+    validation?: ValidationRules;
+    /** Inline helper/instruction text displayed next to the field. */
+    helperText?: string;
+    /** Dynamic options endpoint for dropdown/radio/etc. */
+    dynamicOptions?: DynamicOptionsDef;
+    options?: SelectOption[];
+    relationTarget?: string;
+    onDelete?: RelationOnDelete;
+    /**
+     * RELATION only — how many targets one source record may link to.
+     * `"one"` makes this a single-value reference (a new pick replaces the old);
+     * `"many"` (the default, and what `belongsToMany` sets) is a join table.
+     */
+    relationCardinality?: "one" | "many";
+    /**
+     * RELATION + `many` only — typed payload carried ON EACH LINK, compiled from
+     * `belongsToMany(..., { fields })`. This is what turns a bare pair of ids into
+     * a real join table: "which technologies, and at what proficiency".
+     */
+    linkAttributes?: LinkAttributeDefinition[];
+    /** Storage strategy for object fields. */
+    strategy?: StorageStrategy;
+    /** Custom side-table name for separateTable strategy. */
+    separateTableName?: string;
+    /** Field-level encryption mode. */
+    encryption?: EncryptionMode;
+    /** Strip from public API responses. */
+    isPrivate?: boolean;
+};
+/** One typed attribute carried on a many-to-many link row. Mirrors
+ *  `LinkAttributeDef` on the BIAB side (`src/shared/data-model/link-attributes.ts`). */
+export type LinkAttributeDefinition = {
+    name: string;
+    label: string;
+    type: "TEXT" | "NUMBER" | "BOOLEAN" | "SELECT";
+    options?: string[];
+    isRequired?: boolean;
+    description?: string;
+};
+export type ObjectKind = "standard" | "custom";
+/**
+ * Who may read an object's rows from outside your server.
+ *
+ * - `private` (default) — your server only, with a secret key. Nothing on the
+ *   public internet can read it.
+ * - `authenticated` — any customer signed in to your site, via tenant auth.
+ * - `public` — anyone at all, with a publishable (`pk_…`) key.
+ *
+ * ⚠️ `authenticated` means **any signed-in customer can read every row of this
+ * object**. It does NOT scope rows to the customer they belong to — that's
+ * row-level ownership, which this flag does not do. Never use `authenticated`
+ * to keep one customer's data away from another's.
+ *
+ * Applies to reads from outside only. Your dashboard always sees everything.
+ */
+export type ObjectVisibility = "private" | "authenticated" | "public";
+export declare const objectVisibilityValues: readonly ObjectVisibility[];
+export type ObjectDefinition = {
+    /** Stable identity. Survives renames. */
+    universalIdentifier: string;
+    /** `custom` (a new table) or `standard` (custom fields on a BIAB entity). */
+    kind?: ObjectKind;
+    /**
+     * Who may read these rows from outside. Defaults to `private`.
+     *
+     * Declaring it here makes exposure reviewable in a pull request instead of
+     * a setting someone flipped once. It still only PROPOSES: like every other
+     * part of the model, a human promotes it before it takes effect.
+     *
+     * See {@link ObjectVisibility} — especially what `authenticated` does not do.
+     */
+    visibility?: ObjectVisibility;
+    nameSingular: string;
+    namePlural: string;
+    labelSingular: string;
+    labelPlural: string;
+    icon?: string;
+    description?: string;
+    /** Which field is a record's headline. Must be one of `fields`. */
+    labelIdentifierFieldName?: string;
+    /**
+     * `kind: "standard"` only — the BIAB entity these fields attach to
+     * (e.g. "contact"). The object's own system fields stay immutable from
+     * the CLI; only custom fields are yours to declare.
+     */
+    standardEntityName?: string;
+    /** Which feature owns this table (set via SchemaBoundary). */
+    featureId?: string;
+    fields: FieldDefinition[];
+};
+export declare function defineCollection<T extends FieldDefinition>(definition: T): Readonly<T>;
+export declare function defineCollection<T extends ObjectDefinition>(definition: T): Readonly<T & {
+    kind: ObjectKind;
+}>;
+export declare function defineField<T extends ObjectDefinition>(definition: T): Readonly<T & {
+    kind: ObjectKind;
+}>;
+export declare function defineField<T extends FieldDefinition>(definition: T): Readonly<T>;
+/**
+ * @deprecated Use `defineField` (or `defineCollection`) instead. `defineObject` will be removed in a future release.
+ */
+export declare function defineObject<T extends ObjectDefinition>(definition: T): Readonly<T & {
+    kind: ObjectKind;
+}>;
+export type DataModelInput = {
+    objects?: ObjectDefinition[];
+    collections?: ObjectDefinition[];
+    /** Free-form provenance carried into the artifact (git sha, app name, …). */
+    metadata?: Record<string, string | number | boolean>;
+};
+export type DataModelArtifact = {
+    $schema: "https://biab.app/schemas/data-model/v1";
+    version: 1;
+    metadata: Record<string, string | number | boolean>;
+    objects: Array<{
+        universalIdentifier: string;
+        kind: ObjectKind;
+        nameSingular: string;
+        namePlural: string;
+        labelSingular: string;
+        labelPlural: string;
+        /**
+         * Omitted entirely when private — see the note in `build()`. Absent
+         * means private; the two are the same model and must hash the same.
+         */
+        visibility?: ObjectVisibility;
+        icon?: string;
+        description?: string;
+        labelIdentifierFieldName?: string;
+        standardEntityName?: string;
+        fields: Array<{
+            universalIdentifier: string;
+            name: string;
+            label: string;
+            type: FieldType;
+            icon?: string;
+            description?: string;
+            isNullable?: boolean;
+            isUnique?: boolean;
+            isIndexed?: boolean;
+            isPrimaryKey?: boolean;
+            isAutoIncrement?: boolean;
+            formElement?: AllFormElements;
+            elementMetadata?: ElementMetadata;
+            recommendedFormElements?: AllFormElements[];
+            validation?: ValidationRules;
+            helperText?: string;
+            defaultValue?: unknown;
+            position?: number;
+            options?: SelectOption[];
+            relationTarget?: string;
+            onDelete?: RelationOnDelete;
+            strategy?: StorageStrategy;
+            separateTableName?: string;
+        }>;
+    }>;
+};
+export type DataModelClientShape = {
+    readonly objects: readonly Readonly<ObjectDefinition>[];
+    /** The document to upload. */
+    toJSONSchema(): DataModelArtifact;
+    /** SHA-256 of the canonicalized artifact. The server recomputes and compares. */
+    checksum(): Promise<string>;
+};
+export declare function computeDataModelChecksum(body: Record<string, unknown>): Promise<string>;
+/** Global options for createSchema(). */
+export interface SchemaOptions {
+    /** Default primary key strategy across all collections. Defaults to 'uuid'. */
+    defaultIdType?: PrimaryKeyType;
+}
+/**
+ * Declare the org's custom database schema. Default-export the result from
+ * `biab.data-model.config.ts`.
+ *
+ * ```ts
+ * export default createSchema({
+ *   collections: [
+ *     defineField({
+ *       universalIdentifier: "6f1c…",
+ *       nameSingular: "permit", namePlural: "permits",
+ *       labelSingular: "Permit", labelPlural: "Permits",
+ *       labelIdentifierFieldName: "title",
+ *       fields: [
+ *         defineCollection({ universalIdentifier: "a2b4…", name: "title", label: "Title", type: "TEXT" }),
+ *       ],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function createSchema(input: DataModelInput, options?: SchemaOptions): DataModelClientShape;
+/**
+ * @deprecated Use `createSchema` instead. `defineDataModel` will be removed in a future release.
+ */
+export declare function defineDataModel(input: DataModelInput): DataModelClientShape;
+export type ProgressStyle = "multi-step" | "progress_bar";
+export type LogicalOperator = "AND" | "OR";
+export type RuleMatchOperator = "equals" | "not_equals" | "any_of" | "none_of";
+export interface EvaluationRule {
+    fieldRef: string;
+    op: RuleMatchOperator;
+    values: unknown[];
+}
+/** Map a FieldType to its corresponding JavaScript runtime type. */
+export type InferJsType<T extends FieldType> = T extends "NUMBER" | "NUMERIC" | "CURRENCY" | "RATING" | "POSITION" ? number : T extends "BOOLEAN" ? boolean : T extends "ARRAY" | "MULTI_SELECT" | "FILES" ? unknown[] : T extends "RAW_JSON" | "ADDRESS" ? unknown : string;
+/** Infer the submitted/runtime object for one collection declaration. */
+export type InferCollectionValues<C> = C extends CollectionDefinition<infer F> ? InferFieldsValues<F> : never;
+/**
+ * Infer values for a field map, one collection, or a map of collections used
+ * by a custom form.
+ */
+export type InferFormValues<T> = T extends CollectionDefinition ? InferCollectionValues<T> : T extends Record<string, AnyFieldBuilder> ? InferFieldsValues<T> : T extends Record<string, CollectionDefinition> ? {
+    [K in keyof T]: InferCollectionValues<T[K]>;
+} : never;
+/** Infer a keyed value map for an entire schema's collection declarations. */
+export type InferSchemaValues<T extends Record<string, CollectionDefinition>> = {
+    [K in keyof T]: InferCollectionValues<T[K]>;
+};
+/** Extract all "collectionName.fieldName" paths from a tuple of CollectionDefinitions. */
+export type ExtractFieldPaths<C extends readonly CollectionDefinition[]> = {
+    [I in keyof C]: C[I] extends CollectionDefinition<infer F> ? {
+        [K in keyof F & string]: C[I]["nameSingular"] extends string ? `${C[I]["nameSingular"]}.${K}` : never;
+    }[keyof F & string] : never;
+}[number];
+/** Resolve a dot path like "projects.budget" to its JS type. */
+export type FindFieldTypeByPath<Path extends string, C extends readonly CollectionDefinition[]> = C[number] extends CollectionDefinition<infer F> ? Path extends `${infer N}.${infer K}` ? K extends keyof F ? InferFieldValue<F[K]> : never : never : never;
+/** A conditional rule with compile-time validation against the schema. */
+export type SecureEvalRule<C extends readonly CollectionDefinition[], Path extends ExtractFieldPaths<C> = ExtractFieldPaths<C>> = {
+    fieldReference: Path;
+    op: "equals" | "not_equals" | "any_of" | "none_of";
+    values: FindFieldTypeByPath<Path, C>[];
+};
+export interface OptionGroup<C extends readonly CollectionDefinition[] = readonly CollectionDefinition[]> {
+    name: string;
+    nodes: FormNode<C>[];
+    helperText?: string;
+}
+export type FormNode<C extends readonly CollectionDefinition[] = readonly CollectionDefinition[]> = {
+    type: "render_collection";
+    collectionId: ExtractFieldPaths<C> extends never ? string : C[number]["nameSingular"];
+    helperText?: string;
+} | {
+    type: "step_group";
+    name: string;
+    helperText?: string;
+    children: FormNode<C>[];
+} | {
+    type: "conditional_group";
+    fieldReference: ExtractFieldPaths<C> extends never ? string : ExtractFieldPaths<C>;
+    condition: "any_of" | "all_of" | "equals";
+    values: unknown[];
+    rules?: SecureEvalRule<C>[];
+    helperText?: string;
+    children: FormNode<C>[];
+} | {
+    type: "or_group";
+    helperText?: string;
+    button_label?: string;
+    options: OptionGroup<C>[];
+} | {
+    type: "multi_populator";
+    collectionId: ExtractFieldPaths<C> extends never ? string : C[number]["nameSingular"];
+    max_entries?: number;
+    button_label?: string;
+    helperText?: string;
+};
+export interface FormStepNode {
+    type: "form_step";
+    name: string;
+    showTitle?: boolean;
+    helperText?: string;
+    children: LayoutNode[];
+}
+export interface ConditionalBlockNode {
+    type: "conditional_block";
+    matchStrategy: LogicalOperator;
+    rules: EvaluationRule[];
+    showTitle?: boolean;
+    helperText?: string;
+    children: LayoutNode[];
+}
+export interface MultiPopulatorNode {
+    type: "multi_populator";
+    max_entries?: number;
+    button_label?: string;
+    showTitle?: boolean;
+    helperText?: string;
+    /**
+     * Where each repeated entry is persisted. When omitted, the orchestrator
+     * infers `separateTable` from the repeater's single child collection.
+     */
+    output?: MultiPopulatorOutput;
+    /**
+     * Field template for JSONB entries. Secondary-table repeaters derive their
+     * fields from the target collection instead.
+     */
+    entryFields?: FieldDefinition[];
+    children: LayoutNode[];
+}
+export type MultiPopulatorOutput = {
+    strategy: "jsonb";
+    /** Existing `collection.field` whose field declares `.strategy("jsonb")`. */
+    fieldRef: string;
+} | {
+    strategy: "separateTable";
+    /** Target collection; inferred when the repeater has exactly one child collection. */
+    collectionId?: string;
+};
+export interface MultiPopulatorConfig {
+    max_entries?: number;
+    button_label?: string;
+    showTitle?: boolean;
+    helperText?: string;
+    output?: MultiPopulatorOutput;
+    /**
+     * Schema for one JSONB array entry. Required for `output.strategy: "jsonb"`
+     * and invalid for secondary-table output.
+     */
+    entryFields?: Record<string, AnyFieldBuilder>;
+}
+export interface OrConditionNode {
+    type: "or_condition";
+    showTitle?: boolean;
+    helperText?: string;
+    button_label?: string;
+    branches: OptionGroup[];
+}
+export interface CollectionRefNode {
+    type: "render_collection";
+    collectionId: string;
+    helperText?: string;
+}
+export type LayoutNode = FormStepNode | ConditionalBlockNode | MultiPopulatorNode | OrConditionNode | CollectionRefNode;
+export interface FormOrchestrationOptions {
+    defaultIdType?: PrimaryKeyType;
+    consecutive?: boolean;
+    progress?: boolean;
+    progress_style?: ProgressStyle;
+}
+export interface FormAndSchemaConfig<C extends readonly CollectionDefinition[] = readonly CollectionDefinition[]> {
+    collections: C;
+    layout: FormNode<C>[];
+    options?: FormOrchestrationOptions;
+}
+/** A custom-form draft generated from one compiled collection. */
+export type GeneratedFormCandidate = {
+    /** Stable key used by BIAB to update this generated draft idempotently. */
+    sourceKey: string;
+    name: string;
+    slug: string;
+    description: string;
+    fields: Array<{
+        id: string;
+        label: string;
+        /** BIAB custom-form renderer element type. */
+        type: string;
+        required: boolean;
+        outputKey: string;
+        options?: string[];
+        defaultValue?: string | boolean;
+        placeholder?: string;
+        helpText?: string;
+        regexPattern?: string;
+        validation?: {
+            min?: number;
+            max?: number;
+        };
+        collectionSelectConfig?: {
+            collectionKey: string;
+            labelField?: string;
+            valueMode: "id";
+            multi?: boolean;
+        };
+    }>;
+    settings: {
+        isConsecutive: boolean;
+        showProgress: boolean;
+        progressStyle?: "bar" | "steps";
+        generatedFrom: {
+            kind: "data_model";
+            sourceKey: string;
+            objectIdentifier?: string;
+            objectIdentifiers?: string[];
+        };
+        actions: Array<{
+            id: string;
+            type: "create_records";
+            enabled: true;
+            mapping: Record<string, string>;
+            config: {
+                composite: {
+                    creates: Array<{
+                        alias: string;
+                        object: string;
+                        fieldMap: Record<string, string>;
+                        links?: Array<{
+                            field: string;
+                            to: string;
+                        }>;
+                    }>;
+                };
+            };
+        }>;
+    };
+};
+export type BoundaryMetadata = {
+    featureId: string;
+    name: string;
+    description?: string;
+};
+export type SchemaBoundaryNode = {
+    type: "schema_boundary";
+    meta: BoundaryMetadata;
+    children: (CollectionDefinition | SchemaBoundaryNode | LayoutNode)[];
+};
+/**
+ * Group collections (and nested boundaries) under a named feature.
+ * The orchestrator flattens these when building the schema graph.
+ *
+ * ```ts
+ * SchemaBoundary(
+ *   { featureId: "crm", name: "CRM", description: "Contact management" },
+ *   collection("contacts", { fields: { name: fields.text() } }),
+ * )
+ * ```
+ */
+export declare function SchemaBoundary(meta: BoundaryMetadata, ...children: (CollectionDefinition | SchemaBoundaryNode | LayoutNode)[]): SchemaBoundaryNode;
+/**
+ * @deprecated Use `layoutContainers` instead. This API will be removed in a future release.
+ */
+export declare const layout: {
+    step: <C extends readonly CollectionDefinition[] = readonly CollectionDefinition<Record<string, AnyFieldBuilder>>[]>(name: string, children: FormNode<C>[], options?: {
+        helperText?: string;
+    }) => FormNode<C>;
+    collection: <C extends readonly CollectionDefinition[] = readonly CollectionDefinition<Record<string, AnyFieldBuilder>>[]>(collectionId: string, options?: {
+        helperText?: string;
+    }) => FormNode<C>;
+    conditional: <C extends readonly CollectionDefinition[] = readonly CollectionDefinition<Record<string, AnyFieldBuilder>>[]>(fieldReference: string, condition: "any_of" | "all_of" | "equals", values: unknown[], rules: SecureEvalRule<C>[] | undefined, children: FormNode<C>[], options?: {
+        helperText?: string;
+    }) => FormNode<C>;
+    or: <C extends readonly CollectionDefinition[] = readonly CollectionDefinition<Record<string, AnyFieldBuilder>>[]>(options: OptionGroup<C>[], containerOptions?: {
+        helperText?: string;
+        button_label?: string;
+    }) => FormNode<C>;
+    multiPopulator: <C extends readonly CollectionDefinition[] = readonly CollectionDefinition<Record<string, AnyFieldBuilder>>[]>(collectionId: string, options?: {
+        max_entries?: number;
+        button_label?: string;
+        helperText?: string;
+    }) => FormNode<C>;
+};
+/**
+ * Semantic layout wrappers for form structure. Each container isolates
+ * UI flow rules without contaminating your core database collections.
+ *
+ * ```ts
+ * import { layoutContainers } from "@businessdash/sdk";
+ * const { FormStep, ConditionalBlock, MultiPopulator, OrCondition } = layoutContainers;
+ * ```
+ */
+type LayoutChild = LayoutNode | CollectionDefinition;
+declare function createFormStepNode(name: string, options?: {
+    showTitle?: boolean;
+    helperText?: string;
+}, ...children: LayoutChild[]): FormStepNode;
+declare function createConditionalBlockNode(config: {
+    matchStrategy: LogicalOperator;
+    rules: EvaluationRule[];
+    showTitle?: boolean;
+    helperText?: string;
+}, ...children: LayoutChild[]): ConditionalBlockNode;
+declare function createMultiPopulatorNode(config?: MultiPopulatorConfig, ...children: LayoutChild[]): MultiPopulatorNode;
+declare function createOrConditionNode(options?: {
+    showTitle?: boolean;
+    helperText?: string;
+    button_label?: string;
+}, branches?: OptionGroup[]): OrConditionNode;
+export declare const layoutContainers: {
+    FormStep: typeof createFormStepNode;
+    ConditionalBlock: typeof createConditionalBlockNode;
+    MultiPopulator: typeof createMultiPopulatorNode;
+    OrCondition: typeof createOrConditionNode;
+};
+/** The three atomic operations generated for one collection. */
+export interface SingleResourceForms {
+    /** The collection this bundle operates on (its universalIdentifier). */
+    collectionId: string;
+    create: GeneratedFormCandidate;
+    edit: GeneratedFormCandidate;
+    delete: GeneratedFormCandidate;
+    /**
+     * Collections this one points at, so an operator can see at a glance what a
+     * form depends on.
+     *
+     * INFORMATIONAL ONLY. Nothing needs to "inject" these: a relation field's
+     * generated picker already carries `collectionSelectConfig.collectionKey`,
+     * and options load live at render. This list is for humans, not plumbing.
+     */
+    dependencies: string[];
+}
+export interface SingleResourceFormOptions extends FormOrchestrationOptions {
+    /**
+     * Sibling collections, used ONLY to describe what a delete would cascade to.
+     * Omit and the delete form makes no cascade claim at all — silence beats a
+     * confident sentence that might be wrong about someone's data.
+     */
+    relatedObjects?: readonly Readonly<ObjectDefinition>[];
+}
+/**
+ * Generate the three atomic, single-record forms for one collection — Create,
+ * Edit and Delete — instead of one big multi-step wizard.
+ *
+ * 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.
+ *
+ * Lineage: `create` deliberately KEEPS the base `data-model:<uid>` sourceKey
+ * that 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` and `delete` take suffixed keys
+ * off the same stem.
+ */
+export declare function createSingleResourceForm(object: Readonly<ObjectDefinition>, options?: SingleResourceFormOptions): SingleResourceForms;
+/**
+ * Compile a layout tree into a pure database schema + UI form tree.
+ *
+ * Unlike the previous API which required separate `collections` and `layout`
+ * properties, this new signature accepts a flat array of `SchemaBoundary`,
+ * `collection()` definitions, and layout containers — extracting collections
+ * and the visual render graph from the same expression tree.
+ *
+ * ```ts
+ * const result = createFormSchemaOrchestrator([
+ *   SchemaBoundary(
+ *     { featureId: "crm", name: "CRM" },
+ *     collection("contacts", { fields: { name: bd.text().required() } }),
+ *   ),
+ * ], { defaultIdType: "uuid", consecutive: true });
+ * ```
+ */
+export declare function createFormSchemaOrchestrator(boundaries: (SchemaBoundaryNode | CollectionDefinition | LayoutNode)[], options?: FormOrchestrationOptions): {
+    databaseSchema: DataModelClientShape;
+    uiFormTree: LayoutNode[];
+    /**
+     * Inactive form drafts the CLI can include with the schema proposal.
+     * Every field uses its explicit formElement or the first compatible
+     * recommendedFormElements entry.
+     */
+    generatedForms: GeneratedFormCandidate[];
+    formControlSettings: {
+        consecutive: boolean;
+        progress: boolean;
+        progressStyle?: ProgressStyle;
+    };
+    featureTags: Record<string, string>;
+};
+export {};
+//# sourceMappingURL=data-model-schema.d.ts.map