@clivly/core 0.1.0 → 0.2.0

package/dist/entity-config.d.cts

@@ -0,0 +1,272 @@
+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"];
+};
+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.ZodEnum<{
+    contact: "contact";
+    company: "company";
+    deal: "deal";
+    activity: "activity";
+    conversation: "conversation";
+    note: "note";
+  }>;
+  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>>>;
+}, z.core.$strict>;
+type ClivlyEntityConfig = z.infer<typeof entitySchema>;
+declare const entitiesConfigSchema: z.ZodObject<{
+  entities: z.ZodRecord<z.ZodString, z.ZodObject<{
+    concept: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+      deal: "deal";
+      activity: "activity";
+      conversation: "conversation";
+      note: "note";
+    }>;
+    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>>>;
+  }, 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;
+/**
+ * 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).
+ */
+interface DiscoveredSchemaTable {
+  columns: string[];
+  name: 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, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.d.mts

@@ -219,13 +219,27 @@ declare const entitiesConfigSchema: z.ZodObject<{
   }, 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. Does NOT validate against the host schema —
- * that needs the discovered schema; see `validateEntitiesConfig`.
+ * 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): ClivlyEntitiesConfig;
+declare function defineClivlyConfig(config: ClivlyEntitiesConfig, options?: {
+  strict?: boolean;
+  onWarn?: (message: string) => void;
+}): ClivlyEntitiesConfig;
 /**
  * A host table the SDK reported for discovery. Structurally identical to the
  * SDK's `DiscoveredTable`; duplicated here to keep `@clivly/core` free of an
@@ -255,4 +269,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.mjs

@@ -146,14 +146,56 @@ const entitySchema = z.strictObject({
 	relationships: z.record(z.string(), relationshipSchema).optional()
 });
 const entitiesConfigSchema = z.strictObject({ entities: z.record(z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
+/** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
+var ClivlyConfigError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Clivly config has ${issues.length} non-canonical field mapping(s) that would write empty values at sync time:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
+		this.name = "ClivlyConfigError";
+		this.issues = issues;
+	}
+};
+function nonCanonicalFieldKeys(entity) {
+	const canonical = CANONICAL_FIELDS[entity.concept];
+	if (!canonical) return [];
+	return Object.keys(entity.fields).filter((key) => !canonical.includes(key));
+}
+function nonCanonicalMessage(entity, field) {
+	const canonical = CANONICAL_FIELDS[entity.concept] ?? [];
+	return `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`;
+}
+function canonicalFieldIssues(config) {
+	const issues = [];
+	for (const [key, entity] of Object.entries(config.entities)) for (const field of nonCanonicalFieldKeys(entity)) issues.push({
+		path: `entities.${key}.fields.${field}`,
+		message: nonCanonicalMessage(entity, field)
+	});
+	return issues;
+}
+function defaultWarn(message) {
+	console.warn(message);
+}
 /**
 * 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. Does NOT validate against the host schema —
-* that needs the discovered schema; see `validateEntitiesConfig`.
+* 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`.
 */
-function defineClivlyConfig(config) {
-	return entitiesConfigSchema.parse(config);
+function defineClivlyConfig(config, options) {
+	const parsed = entitiesConfigSchema.parse(config);
+	const issues = canonicalFieldIssues(parsed);
+	if (issues.length > 0) {
+		if (options?.strict) throw new ClivlyConfigError(issues);
+		const warn = options?.onWarn ?? defaultWarn;
+		for (const issue of issues) warn(`⚠ Clivly config: ${issue.message} (${issue.path}) — this field would write an empty value at sync time. Pass { strict: true } to make this throw.`);
+	}
+	return parsed;
 }
 /** Split a `table.column` / bare `column` ref into its parts. */
 function parseColumnRef(ref) {
@@ -191,11 +233,8 @@ var SchemaValidator = class {
 	}
 };
 function validateFields(v, base, entity) {
-	const canonical = CANONICAL_FIELDS[entity.concept];
-	for (const [field, column] of Object.entries(entity.fields)) {
-		v.requireColumn(`${base}.fields.${field}`, entity.source, column);
-		if (canonical && !canonical.includes(field)) v.report(`${base}.fields.${field}`, `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`);
-	}
+	for (const [field, column] of Object.entries(entity.fields)) v.requireColumn(`${base}.fields.${field}`, entity.source, column);
+	for (const field of nonCanonicalFieldKeys(entity)) v.report(`${base}.fields.${field}`, nonCanonicalMessage(entity, field));
 }
 function validateReadOnly(v, base, entity) {
 	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
@@ -263,4 +302,4 @@ function validateEntitiesConfig(config, schema) {
 	};
 }
 //#endregion
-export { CANONICAL_FIELDS, CRM_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };