@clivly/core 0.1.0 → 0.3.0-next.1

package/dist/mapping-score.d.cts

@@ -0,0 +1,49 @@
+//#region src/mapping-score.d.ts
+type Tier = "High" | "Medium" | "Low";
+interface Scored<T> {
+  /** Human-readable chips, e.g. `type text`, `name matches "contacts"`. */
+  reasons: string[];
+  /** Internal — used for ranking and the apply threshold. Never rendered. */
+  score: number;
+  tier: Tier;
+  value: T;
+}
+/** Tier cut-offs: score >= high → High; >= medium → Medium; else Low. */
+interface Thresholds {
+  high: number;
+  medium: number;
+}
+declare const CONCEPT_TIERS: Thresholds;
+declare const FIELD_TIERS: Thresholds;
+declare const RELATIONSHIP_TIERS: Thresholds;
+/** Two concept candidates closer than this are treated as ambiguous. */
+declare const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+declare const W: {
+  readonly nameExact: 50;
+  readonly nameSubstring: 25;
+  readonly definingColumn: 20;
+  readonly hasPrimaryKey: 10;
+  readonly hasRows: 10;
+  readonly emptyTable: -20;
+  readonly fieldNameMatch: 50;
+  readonly typeCompatible: 30;
+  readonly typeMismatch: -30;
+  readonly requiredNotNull: 10;
+  readonly fkResolved: 60;
+  readonly fkNameHint: 30;
+  readonly joinTable: 20;
+};
+declare function tierFor(score: number, t: Thresholds): Tier;
+declare function isTextLike(type: string | undefined): boolean;
+declare function isNumericLike(type: string | undefined): boolean;
+declare function isTimestampLike(type: string | undefined): boolean;
+/**
+ * True when the top two candidates are too close to call. Callers must never
+ * one-click apply an ambiguous result — the user picks.
+ */
+declare function isAmbiguous(ranked: Array<{
+  score: number;
+}>): boolean;
+//#endregion
+export { AMBIGUITY_MARGIN, CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, Scored, Thresholds, Tier, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor };

package/dist/mapping-score.d.mts

@@ -0,0 +1,49 @@
+//#region src/mapping-score.d.ts
+type Tier = "High" | "Medium" | "Low";
+interface Scored<T> {
+  /** Human-readable chips, e.g. `type text`, `name matches "contacts"`. */
+  reasons: string[];
+  /** Internal — used for ranking and the apply threshold. Never rendered. */
+  score: number;
+  tier: Tier;
+  value: T;
+}
+/** Tier cut-offs: score >= high → High; >= medium → Medium; else Low. */
+interface Thresholds {
+  high: number;
+  medium: number;
+}
+declare const CONCEPT_TIERS: Thresholds;
+declare const FIELD_TIERS: Thresholds;
+declare const RELATIONSHIP_TIERS: Thresholds;
+/** Two concept candidates closer than this are treated as ambiguous. */
+declare const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+declare const W: {
+  readonly nameExact: 50;
+  readonly nameSubstring: 25;
+  readonly definingColumn: 20;
+  readonly hasPrimaryKey: 10;
+  readonly hasRows: 10;
+  readonly emptyTable: -20;
+  readonly fieldNameMatch: 50;
+  readonly typeCompatible: 30;
+  readonly typeMismatch: -30;
+  readonly requiredNotNull: 10;
+  readonly fkResolved: 60;
+  readonly fkNameHint: 30;
+  readonly joinTable: 20;
+};
+declare function tierFor(score: number, t: Thresholds): Tier;
+declare function isTextLike(type: string | undefined): boolean;
+declare function isNumericLike(type: string | undefined): boolean;
+declare function isTimestampLike(type: string | undefined): boolean;
+/**
+ * True when the top two candidates are too close to call. Callers must never
+ * one-click apply an ambiguous result — the user picks.
+ */
+declare function isAmbiguous(ranked: Array<{
+  score: number;
+}>): boolean;
+//#endregion
+export { AMBIGUITY_MARGIN, CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, Scored, Thresholds, Tier, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor };

package/dist/mapping-score.mjs

@@ -0,0 +1,87 @@
+//#region src/mapping-score.ts
+const CONCEPT_TIERS = {
+	high: 70,
+	medium: 40
+};
+const FIELD_TIERS = {
+	high: 70,
+	medium: 40
+};
+const RELATIONSHIP_TIERS = {
+	high: 60,
+	medium: 30
+};
+/** Two concept candidates closer than this are treated as ambiguous. */
+const AMBIGUITY_MARGIN = 15;
+/** Signal weights. Tuned against fixtures; adjust here, not at call sites. */
+const W = {
+	nameExact: 50,
+	nameSubstring: 25,
+	definingColumn: 20,
+	hasPrimaryKey: 10,
+	hasRows: 10,
+	emptyTable: -20,
+	fieldNameMatch: 50,
+	typeCompatible: 30,
+	typeMismatch: -30,
+	requiredNotNull: 10,
+	fkResolved: 60,
+	fkNameHint: 30,
+	joinTable: 20
+};
+function tierFor(score, t) {
+	if (score >= t.high) return "High";
+	if (score >= t.medium) return "Medium";
+	return "Low";
+}
+const TEXT_TYPES = [
+	"text",
+	"varchar",
+	"char",
+	"citext",
+	"uuid",
+	"string"
+];
+const NUMERIC_TYPES = [
+	"numeric",
+	"decimal",
+	"int",
+	"integer",
+	"bigint",
+	"smallint",
+	"float",
+	"double",
+	"real",
+	"money"
+];
+const TIMESTAMP_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"date",
+	"datetime"
+];
+function matchesType(type, list) {
+	if (!type) return false;
+	const normalized = type.toLowerCase();
+	return list.some((t) => normalized.startsWith(t));
+}
+function isTextLike(type) {
+	return matchesType(type, TEXT_TYPES);
+}
+function isNumericLike(type) {
+	return matchesType(type, NUMERIC_TYPES);
+}
+function isTimestampLike(type) {
+	return matchesType(type, TIMESTAMP_TYPES);
+}
+/**
+* True when the top two candidates are too close to call. Callers must never
+* one-click apply an ambiguous result — the user picks.
+*/
+function isAmbiguous(ranked) {
+	const [first, second] = ranked;
+	if (!(first && second)) return false;
+	return first.score - second.score < 15;
+}
+//#endregion
+export { AMBIGUITY_MARGIN, CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor };

package/dist/mappings-config.cjs

@@ -0,0 +1,100 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_entity_config = require("./entity-config.cjs");
+//#region src/mappings-config.ts
+const RESERVED_FIELD = "id";
+/**
+* Restrict a persisted field map to what the mirror can actually store: drop
+* the reserved `id` key (for every concept) and, for materialized concepts
+* (contact/company), any key that isn't canonical. This makes the pipeline
+* resilient to legacy or mis-suggested field maps — a stray `id` no longer
+* blocks the whole sync.
+*/
+function canonicalFields(concept, fieldMap) {
+	const allowed = require_entity_config.CANONICAL_FIELDS[concept];
+	const result = {};
+	for (const [field, column] of Object.entries(fieldMap)) {
+		if (field === RESERVED_FIELD) continue;
+		if (allowed && !allowed.includes(field)) continue;
+		result[field] = column;
+	}
+	return result;
+}
+const DEFAULT_ROLE = "primary";
+const ACTIVE_STATUS = "active";
+function isEligible(row) {
+	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+}
+/**
+* Preferred key for a row: the bare source table when it backs a single entity,
+* else role-suffixed so multiple roles on one table stay distinct and stable
+* (the primary role keeps the bare name). Uniqueness is still enforced by the
+* caller in case two rows land on the same preferred key.
+*/
+function preferredKey(row, tableCounts) {
+	const role = row.role ?? DEFAULT_ROLE;
+	if ((tableCounts.get(row.sourceTable) ?? 0) <= 1) return row.sourceTable;
+	return role === DEFAULT_ROLE ? row.sourceTable : `${row.sourceTable}__${role}`;
+}
+function uniquify(base, used) {
+	if (!used.has(base)) {
+		used.add(base);
+		return base;
+	}
+	let suffix = 2;
+	while (used.has(`${base}__${suffix}`)) suffix++;
+	const key = `${base}__${suffix}`;
+	used.add(key);
+	return key;
+}
+function buildEntity(row, refIndex) {
+	const entity = {
+		concept: row.targetConcept,
+		source: row.sourceTable,
+		role: row.role ?? DEFAULT_ROLE,
+		fields: canonicalFields(row.targetConcept, row.fieldMap)
+	};
+	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
+	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
+	if (row.relationships && Object.keys(row.relationships).length > 0) {
+		const relationships = {};
+		for (const [name, spec] of Object.entries(row.relationships)) {
+			const rel = spec;
+			relationships[name] = {
+				entity: refIndex.get(rel.entity) ?? rel.entity,
+				via: rel.via
+			};
+		}
+		entity.relationships = relationships;
+	}
+	return entity;
+}
+/**
+* Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+* rows with at least one mapped field are included; disabled/suggested rows and
+* unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+* eligible — a no-op the view compiler and sync engine both tolerate.
+*/
+function mappingsToEntitiesConfig(rows) {
+	const eligible = rows.filter(isEligible);
+	const tableCounts = /* @__PURE__ */ new Map();
+	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	const used = /* @__PURE__ */ new Set();
+	const tableAnchor = /* @__PURE__ */ new Map();
+	const assigned = [];
+	for (const row of eligible) {
+		const key = uniquify(preferredKey(row, tableCounts), used);
+		assigned.push({
+			row,
+			key
+		});
+		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
+	}
+	const refIndex = /* @__PURE__ */ new Map();
+	for (const { key } of assigned) refIndex.set(key, key);
+	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);
+	const entities = {};
+	for (const { row, key } of assigned) entities[key] = buildEntity(row, refIndex);
+	return { entities };
+}
+//#endregion
+exports.mappingsToEntitiesConfig = mappingsToEntitiesConfig;

package/dist/mappings-config.d.cts

@@ -0,0 +1,42 @@
+import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+
+//#region src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { EntityMappingRow, mappingsToEntitiesConfig };

package/dist/mappings-config.d.mts

@@ -29,6 +29,7 @@ interface EntityMappingRow {
   sourceTable: string;
   status?: string | null;
   targetConcept: string;
+  targetObjectTypeId?: string | null;
 }
 /**
  * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`

package/dist/mappings-config.mjs

@@ -1,4 +1,23 @@
+import { CANONICAL_FIELDS } from "./entity-config.mjs";
 //#region src/mappings-config.ts
+const RESERVED_FIELD = "id";
+/**
+* Restrict a persisted field map to what the mirror can actually store: drop
+* the reserved `id` key (for every concept) and, for materialized concepts
+* (contact/company), any key that isn't canonical. This makes the pipeline
+* resilient to legacy or mis-suggested field maps — a stray `id` no longer
+* blocks the whole sync.
+*/
+function canonicalFields(concept, fieldMap) {
+	const allowed = CANONICAL_FIELDS[concept];
+	const result = {};
+	for (const [field, column] of Object.entries(fieldMap)) {
+		if (field === RESERVED_FIELD) continue;
+		if (allowed && !allowed.includes(field)) continue;
+		result[field] = column;
+	}
+	return result;
+}
 const DEFAULT_ROLE = "primary";
 const ACTIVE_STATUS = "active";
 function isEligible(row) {
@@ -31,8 +50,9 @@ function buildEntity(row, refIndex) {
 		concept: row.targetConcept,
 		source: row.sourceTable,
 		role: row.role ?? DEFAULT_ROLE,
-		fields: { ...row.fieldMap }
+		fields: canonicalFields(row.targetConcept, row.fieldMap)
 	};
+	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
 	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
 	if (row.relationships && Object.keys(row.relationships).length > 0) {
 		const relationships = {};

package/dist/sync-engine.cjs

@@ -0,0 +1,211 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_view_compiler = require("./view-compiler.cjs");
+//#region src/sync-engine.ts
+/**
+* Diff a view's rows against the current mirror population for one entity.
+*
+* - source row with no mirror row      → create
+* - source row with a live mirror row  → update (overwrite identity fields)
+* - source row with an archived mirror → restore (re-activate + update)
+* - live mirror row absent from source → archive (soft delete, keep history)
+* - archived mirror row absent from source → no-op
+*
+* Source rows are de-duplicated by the reconciliation key (first wins). In
+* simple mode (default) the key is `sourceRef`. In composite mode — used for
+* `through` (join-table) entities, where the compiled view fans a person out
+* into one row per membership — the key is `(sourceRef, companyRef)`, so a
+* person in several companies materializes one mirror row per company and a
+* single membership leaving archives only that one row.
+*/
+function reconcile(source, mirror, opts = {}) {
+	const keyOf = (sourceRef, companyRef) => opts.composite ? `${sourceRef}\0${companyRef ?? ""}` : sourceRef;
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	for (const row of source) {
+		const key = keyOf(row.sourceRef, row.companyRef ?? null);
+		if (!seen.has(key)) {
+			seen.add(key);
+			rows.push(row);
+		}
+	}
+	const byKey = new Map(mirror.map((m) => [keyOf(m.sourceRef, m.companyRef), m]));
+	const liveKeys = /* @__PURE__ */ new Set();
+	const actions = [];
+	for (const row of rows) {
+		const companyRef = row.companyRef ?? null;
+		const key = keyOf(row.sourceRef, companyRef);
+		liveKeys.add(key);
+		const existing = byKey.get(key);
+		if (!existing) actions.push({
+			kind: "create",
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+		else if (existing.archivedAt) actions.push({
+			kind: "restore",
+			id: existing.id,
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+		else actions.push({
+			kind: "update",
+			id: existing.id,
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+	}
+	for (const m of mirror) {
+		const key = keyOf(m.sourceRef, m.companyRef);
+		if (!(liveKeys.has(key) || m.archivedAt)) actions.push({
+			kind: "archive",
+			id: m.id,
+			sourceRef: m.sourceRef
+		});
+	}
+	return actions;
+}
+const CONCEPT_ORDER = {
+	company: 0,
+	contact: 1
+};
+/** Companies before contacts, so contact company_refs resolve to a live mirror. */
+function syncOrder(a, b) {
+	return (CONCEPT_ORDER[a.concept] ?? 99) - (CONCEPT_ORDER[b.concept] ?? 99);
+}
+async function resolveActions(store, actions) {
+	const refs = /* @__PURE__ */ new Set();
+	for (const action of actions) if (action.kind !== "archive" && action.companyRef) refs.add(action.companyRef);
+	const resolved = refs.size ? await store.resolveCompanyRefs([...refs]) : /* @__PURE__ */ new Map();
+	return actions.map((action) => {
+		if (action.kind === "archive") return action;
+		const companyId = action.companyRef ? resolved.get(action.companyRef) ?? null : null;
+		return {
+			kind: action.kind,
+			id: "id" in action ? action.id : "",
+			sourceRef: action.sourceRef,
+			fields: action.fields,
+			companyId,
+			companySourceRef: action.companyRef ?? null
+		};
+	});
+}
+function emptyTally() {
+	return {
+		create: 0,
+		update: 0,
+		restore: 0,
+		archive: 0
+	};
+}
+/**
+* An entity whose company relationship is a `through` (join-table) join fans out
+* into one source row per membership, so its mirror must be keyed compositely.
+*/
+function isCompositeEntity(config, entityKey) {
+	const entity = config.entities[entityKey];
+	if (!entity?.relationships) return false;
+	return Object.values(entity.relationships).some((rel) => "through" in rel.via);
+}
+/**
+* Run a full sync: compile the config's views, then reconcile + persist each,
+* companies first. Returns per-entity and total action counts.
+*/
+async function runSync(config, store, options = {}) {
+	const allViews = require_view_compiler.compileEntityViews(config, options).sort(syncOrder);
+	const views = options.sample ? allViews.filter((v) => v.entityKey === options.sample?.entityKey) : allViews;
+	const entities = [];
+	const totals = {
+		created: 0,
+		updated: 0,
+		restored: 0,
+		archived: 0
+	};
+	for (const view of views) {
+		const objectTypeId = config.entities[view.entityKey]?.targetObjectTypeId;
+		const [source, mirror] = await Promise.all([store.readView(view, options.sample ? { limit: 1 } : void 0), store.listMirror({
+			concept: view.concept,
+			role: view.role,
+			objectTypeId
+		})]);
+		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) }).filter((a) => !(options.sample && a.kind === "archive"));
+		const persistActions = await resolveActions(store, actions);
+		await store.persist({
+			concept: view.concept,
+			role: view.role,
+			objectTypeId,
+			actions: persistActions
+		});
+		const counts = emptyTally();
+		for (const action of actions) counts[action.kind] += 1;
+		const result = {
+			entityKey: view.entityKey,
+			concept: view.concept,
+			role: view.role,
+			created: counts.create,
+			updated: counts.update,
+			restored: counts.restore,
+			archived: counts.archive
+		};
+		entities.push(result);
+		totals.created += result.created;
+		totals.updated += result.updated;
+		totals.restored += result.restored;
+		totals.archived += result.archived;
+	}
+	return {
+		entities,
+		totals
+	};
+}
+function isEmptyValue(value) {
+	return value === null || value === void 0 || value === "";
+}
+/**
+* Sample-scoped data-quality warnings over projected preview rows. Each mapped
+* (or required-but-unmapped) field yields at most one warning, by precedence:
+* a required field empty in ≥1 row → `K/N` form; an optional field empty in
+* ALL rows → all-empty form; zero source rows → a single table-level warning.
+*/
+function computeSampleWarnings(rows, requiredFields, sourceTable) {
+	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const required = new Set(requiredFields);
+	const fields = new Set(requiredFields);
+	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
+	const warnings = [];
+	for (const field of [...fields].sort()) {
+		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
+		if (required.has(field)) {
+			if (emptyCount > 0) warnings.push({
+				field,
+				message: `${field} empty in ${emptyCount}/${rows.length} sampled`
+			});
+		} else if (emptyCount === rows.length) warnings.push({
+			field,
+			message: `${field} is empty in all ${rows.length} sampled rows`
+		});
+	}
+	return warnings;
+}
+/**
+* Zero-write preview: read ≤`limit` rows through the compiled view (a pure
+* SELECT whose SQL already projects each row into its mapped fields) and
+* compute sample warnings. Calls ONLY `store.readView` — never a write path —
+* so it can never mutate the mirror. The distinct, write-one-row sibling is
+* `runSync`'s sample mode (T13).
+*/
+async function previewSync(store, view, opts) {
+	const rows = await store.readView(view, { limit: opts.limit });
+	return {
+		rows,
+		sampledCount: rows.length,
+		warnings: computeSampleWarnings(rows, opts.requiredFields, opts.sourceTable)
+	};
+}
+//#endregion
+exports.computeSampleWarnings = computeSampleWarnings;
+exports.previewSync = previewSync;
+exports.reconcile = reconcile;
+exports.runSync = runSync;