@clivly/core 0.9.0 → 0.9.2

package/dist/entity-config.d.cts

@@ -1,414 +1,2 @@
-import { z } from "zod";
-//#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>;
-  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>;
-    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>;
-/** 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`.
- */
-declare function defineClivlyConfig(config: ClivlyEntitiesConfig, 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 { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, O as relationshipsSchema, S as customObjectDeclarations, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, c as ClivlyEntityConfigInput, d as CrmConcept, f as CustomObjectDeclaration, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredColumnMeta, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.cjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, CustomObjectDeclaration, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };