@clivly/core 0.9.0 → 0.9.2

package/dist/entity-config-buOIVtMM.d.mts

@@ -0,0 +1,580 @@
+import { z } from "zod";
+//#region src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: z.ZodObject<{
+  table: z.ZodString;
+  column: z.ZodString;
+}, z.core.$strict>;
+type ProjectionRef = z.infer<typeof projectionRefSchema>;
+declare const projectionJoinSchema: z.ZodObject<{
+  key: z.ZodString;
+  table: z.ZodString;
+  type: z.ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: z.ZodArray<z.ZodObject<{
+    left: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+    op: z.ZodLiteral<"eq">;
+    right: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: z.ZodObject<{
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"base_pk">;
+  column: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"column">;
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"composite">;
+  parts: z.ZodArray<z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>]>;
+type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
+declare const projectionSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  kind: z.ZodLiteral<"projection">;
+  entityKey: z.ZodString;
+  baseTable: z.ZodString;
+  joins: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    table: z.ZodString;
+    type: z.ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: z.ZodArray<z.ZodObject<{
+      left: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+      op: z.ZodLiteral<"eq">;
+      right: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+  identity: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"base_pk">;
+    column: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"composite">;
+    parts: z.ZodArray<z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>>;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type ProjectionMapping = z.infer<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region src/entity-config.d.ts
+/**
+ * Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
+ * promise into a real capability.
+ *
+ * A CRM entity is no longer a flat table name. It is a *derived entity*: a
+ * filtered slice of a host table (`source` + `filter`), a column allowlist
+ * (`fields` + `readOnly`), and declared `relationships` to other entities. The
+ * same host table can back several entities (e.g. `users` → owners + members)
+ * distinguished by `role`.
+ *
+ * This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
+ * structural helper) and `validateEntitiesConfig` (semantic validation against
+ * the host's discovered schema). It performs NO DB access and generates no SQL —
+ * the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
+ */
+/** Canonical CRM concepts a host entity can map onto. */
+declare const CRM_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+type CrmConcept = (typeof CRM_CONCEPTS)[number];
+/**
+ * The canonical `fields` keys the mirror actually persists, per concept — the
+ * crm_* columns the sync store writes. An entity's `fields` map keys must be one
+ * of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
+ * structurally but has no destination column, so the store silently writes an
+ * empty value. `validateEntitiesConfig` flags those.
+ *
+ * This is the single source of truth — the Drizzle store imports it, so the
+ * two can't drift (the drift is what made the silent-data-loss trap possible).
+ * Concepts absent here aren't materialized yet, so their field keys are
+ * unconstrained.
+ */
+declare const CANONICAL_FIELDS: {
+  readonly contact: readonly ["name", "email", "title", "status"];
+  readonly company: readonly ["name", "domain", "industry", "size"];
+  readonly deal: readonly ["name", "value", "stage"];
+};
+/**
+ * The concepts the mapping→sync pipeline can actually materialize into `crm_*`
+ * tables. These are exactly the CANONICAL_FIELDS keys — the Drizzle sync store's
+ * `persist()` throws for any other concept, so offering one (in the mapping
+ * editor, in suggestions, or via the upsert API) is a broken affordance.
+ *
+ * The broader CRM_CONCEPTS set still validates structurally, so previously
+ * stored rows for not-yet-materialized concepts keep rendering. When a concept
+ * gains a sync-store path, add its canonical fields above and it joins this set
+ * automatically (guarded by the MATERIALIZING_CONCEPTS drift test).
+ */
+declare const MATERIALIZING_CONCEPTS: readonly ["contact", "company", "deal"];
+type MaterializingConcept = (typeof MATERIALIZING_CONCEPTS)[number];
+/**
+ * The org-defined custom-object target. Deliberately NOT a member of
+ * CRM_CONCEPTS / CANONICAL_FIELDS / MATERIALIZING_CONCEPTS — a custom object has
+ * no fixed canonical columns; its mapping's fieldMap keys ARE its properties.
+ * Handled as an explicit branch wherever concepts are switched on, so the
+ * canonical-concept invariants (and their drift test) stay intact.
+ */
+declare const CUSTOM_CONCEPT: "custom";
+declare const filterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+  eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>;
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+declare const filterSchema: z.ZodUnion<readonly [z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+  eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>>]>;
+type FilterExpr = z.infer<typeof filterSchema>;
+/** A single column predicate value (scalar shorthand or operator object). */
+type FilterValue = z.infer<typeof filterValueSchema>;
+/**
+ * How the link between two entities is expressed in the host schema:
+ * - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
+ * - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
+ * - `through`         — a join table sits between them (many-to-many, role often here)
+ * - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
+ *
+ * `column` and the join-table keys are `table.column` or bare `column` strings.
+ */
+declare const relationshipViaSchema: z.ZodUnion<readonly [z.ZodObject<{
+  fkOn: z.ZodEnum<{
+    contact: "contact";
+    company: "company";
+  }>;
+  column: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  through: z.ZodString;
+  localKey: z.ZodString;
+  foreignKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>]>;
+type RelationshipVia = z.infer<typeof relationshipViaSchema>;
+declare const relationshipSchema: z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type RelationshipSpec = z.infer<typeof relationshipSchema>;
+/** A named map of relationships, as stored on an entity / in the mappings row. */
+declare const relationshipsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>>;
+type RelationshipsMap = z.infer<typeof relationshipsSchema>;
+declare const entitySchema: z.ZodObject<{
+  concept: z.ZodUnion<readonly [z.ZodEnum<{
+    contact: "contact";
+    company: "company";
+    deal: "deal";
+    activity: "activity";
+    conversation: "conversation";
+    note: "note";
+  }>, z.ZodLiteral<"custom">]>;
+  source: z.ZodString;
+  role: z.ZodOptional<z.ZodString>;
+  filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+    eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>, z.ZodObject<{
+    ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>, z.ZodObject<{
+    in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNull: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNotNull: z.ZodLiteral<true>;
+  }, z.core.$strict>]>]>>]>>;
+  fields: z.ZodRecord<z.ZodString, z.ZodString>;
+  readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    entity: z.ZodString;
+    via: z.ZodUnion<readonly [z.ZodObject<{
+      fkOn: z.ZodEnum<{
+        contact: "contact";
+        company: "company";
+      }>;
+      column: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      through: z.ZodString;
+      localKey: z.ZodString;
+      foreignKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      $raw: z.ZodString;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>>>;
+  targetObjectTypeId: z.ZodOptional<z.ZodString>;
+  objectType: z.ZodOptional<z.ZodObject<{
+    name: z.ZodString;
+    pluralName: z.ZodOptional<z.ZodString>;
+    iconKey: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  projection: z.ZodOptional<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"projection">;
+    entityKey: z.ZodString;
+    baseTable: z.ZodString;
+    joins: z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      table: z.ZodString;
+      type: z.ZodEnum<{
+        inner: "inner";
+        left: "left";
+      }>;
+      on: z.ZodArray<z.ZodObject<{
+        left: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+        op: z.ZodLiteral<"eq">;
+        right: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+      from: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+    identity: z.ZodUnion<readonly [z.ZodObject<{
+      kind: z.ZodLiteral<"base_pk">;
+      column: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      kind: z.ZodLiteral<"column">;
+      from: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+      kind: z.ZodLiteral<"composite">;
+      parts: z.ZodArray<z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>>;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ClivlyEntityConfig = z.infer<typeof entitySchema>;
+declare const entitiesConfigSchema: z.ZodObject<{
+  entities: z.ZodRecord<z.ZodString, z.ZodObject<{
+    concept: z.ZodUnion<readonly [z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+      deal: "deal";
+      activity: "activity";
+      conversation: "conversation";
+      note: "note";
+    }>, z.ZodLiteral<"custom">]>;
+    source: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+      $raw: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+      eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strict>, z.ZodObject<{
+      ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strict>, z.ZodObject<{
+      in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNull: z.ZodLiteral<true>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNotNull: z.ZodLiteral<true>;
+    }, z.core.$strict>]>]>>]>>;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      entity: z.ZodString;
+      via: z.ZodUnion<readonly [z.ZodObject<{
+        fkOn: z.ZodEnum<{
+          contact: "contact";
+          company: "company";
+        }>;
+        column: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        through: z.ZodString;
+        localKey: z.ZodString;
+        foreignKey: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        $raw: z.ZodString;
+      }, z.core.$strict>]>;
+    }, z.core.$strict>>>;
+    targetObjectTypeId: z.ZodOptional<z.ZodString>;
+    objectType: z.ZodOptional<z.ZodObject<{
+      name: z.ZodString;
+      pluralName: z.ZodOptional<z.ZodString>;
+      iconKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    projection: z.ZodOptional<z.ZodObject<{
+      version: z.ZodLiteral<1>;
+      kind: z.ZodLiteral<"projection">;
+      entityKey: z.ZodString;
+      baseTable: z.ZodString;
+      joins: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        table: z.ZodString;
+        type: z.ZodEnum<{
+          inner: "inner";
+          left: "left";
+        }>;
+        on: z.ZodArray<z.ZodObject<{
+          left: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+          }, z.core.$strict>;
+          op: z.ZodLiteral<"eq">;
+          right: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+          }, z.core.$strict>;
+        }, z.core.$strict>>;
+      }, z.core.$strict>>;
+      fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+        from: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>>;
+      identity: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"base_pk">;
+        column: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"column">;
+        from: z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"composite">;
+        parts: z.ZodArray<z.ZodObject<{
+          table: z.ZodString;
+          column: z.ZodString;
+        }, z.core.$strict>>;
+      }, z.core.$strict>]>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ClivlyEntitiesConfig = z.infer<typeof entitiesConfigSchema>;
+/**
+ * What an author may hand to `defineClivlyConfig`. Identical to
+ * `ClivlyEntityConfig` except that a projection entity may omit `fields` —
+ * it is derived from `projection.fieldBindings`. Without a projection `fields`
+ * stays required, so the looser input never weakens the ordinary case.
+ */
+type ClivlyEntityConfigInput = (ClivlyEntityConfig & {
+  projection?: undefined;
+}) | (Omit<ClivlyEntityConfig, "fields"> & {
+  fields?: Record<string, string>;
+  projection: ProjectionMapping;
+});
+type ClivlyEntitiesConfigInput = Omit<ClivlyEntitiesConfig, "entities"> & {
+  entities: Record<string, ClivlyEntityConfigInput>;
+};
+/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
+declare class ClivlyConfigError extends Error {
+  readonly issues: ConfigValidationError[];
+  constructor(issues: ConfigValidationError[]);
+}
+/**
+ * Structural helper for `clivly.config.ts`. Gives full type inference on the
+ * literal you pass and eagerly parses it, so shape errors surface at config
+ * load rather than at sync time.
+ *
+ * It also catches the silent-data-loss footgun: a non-canonical field key for a
+ * materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
+ * destination column, so the store would write an empty value. By default these
+ * are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
+ * a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
+ * needs the discovered schema; see `validateEntitiesConfig`.
+ */
+/** A custom object the host declares in config, for `push-schema` to ensure. */
+interface CustomObjectDeclaration {
+  iconKey?: string;
+  name: string;
+  pluralName?: string;
+  /** Unique per org and immutable — the entity key. */
+  slug: string;
+}
+/**
+ * The custom objects a config declares, keyed by entity slug. Entities that
+ * already carry an explicit `targetObjectTypeId` are omitted: their object type
+ * exists server-side and re-declaring it would be a no-op at best.
+ */
+declare function customObjectDeclarations(config: ClivlyEntitiesConfig): CustomObjectDeclaration[];
+/**
+ * The `fields` entry a projection binding implies, qualified as `ref.column`.
+ * Qualified rather than bare: two bindings can pull the same column name from
+ * different tables (`cl.full_name` and `adv.full_name`), which a bare column
+ * name cannot tell apart.
+ */
+declare function projectionFields(projection: ProjectionMapping): Record<string, string>;
+declare function defineClivlyConfig(config: ClivlyEntitiesConfigInput, options?: {
+  strict?: boolean;
+  onWarn?: (message: string) => void;
+}): ClivlyEntitiesConfig;
+/**
+ * Per-column metadata a host reports for a discovered table. Structurally
+ * identical to the SDK's `DiscoveredColumn` and to `entity-heuristics.ts`'s
+ * (currently separate) `DiscoveredColumnMeta` — a later task converges that
+ * module onto this one. Every field is optional: a v1 host reports column
+ * names only.
+ */
+interface DiscoveredColumnMeta {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  references?: {
+    table: string;
+    column: string;
+  };
+  type?: string;
+}
+/**
+ * A host table the SDK reported for discovery. Structurally identical to the
+ * SDK's `DiscoveredTable`; duplicated here to keep `@clivly/core` free of an
+ * SDK dependency (core is the base contract SDK builds on).
+ *
+ * `columns` is the stable v1 contract. `columnsMeta` and `uniqueConstraints`
+ * are the enrichment projection mappings require — absent on v1 hosts, which
+ * is why projection validation fails closed rather than assuming "no keys".
+ */
+interface DiscoveredSchemaTable {
+  columns: string[];
+  columnsMeta?: DiscoveredColumnMeta[];
+  name: string;
+  /** Every unique key as DB column names; PKs included. Absent = unknown. */
+  uniqueConstraints?: string[][];
+}
+interface ConfigValidationError {
+  message: string;
+  /** Dotted path into the config, e.g. `entities.owner.fields.email`. */
+  path: string;
+}
+interface ConfigValidationResult {
+  errors: ConfigValidationError[];
+  valid: boolean;
+}
+/**
+ * Validate a (structurally valid) config against the host's discovered schema:
+ * source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
+ * columns exist, and relationships point at real entities/tables/columns.
+ *
+ * `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
+ * every error found (not just the first) so a mapping UI or CLI can show them
+ * all at once.
+ */
+declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
+//#endregion
+export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionRef as F, identityRefs as I, projectionSchema as L, ProjectionIdentity as M, ProjectionJoin as N, relationshipsSchema as O, ProjectionMapping as P, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, ProjectionFieldBinding as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };

package/dist/entity-config.cjs

@@ -1,13 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-PoOGzvpN.cjs");
+const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
 exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.customObjectDeclarations = require_entity_config.customObjectDeclarations;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
 exports.filterSchema = require_entity_config.filterSchema;
+exports.projectionFields = require_entity_config.projectionFields;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;