@clivly/core 0.1.0

package/dist/mapping-form.d.mts

@@ -0,0 +1,35 @@
+import { FilterExpr, RelationshipVia, RelationshipsMap } from "./entity-config.mjs";
+
+//#region src/mapping-form.d.ts
+/**
+ * A relationship the mapping UI can offer or has configured, in the shape the
+ * heuristic suggester produces. `entityTable` is the *host table name*; the
+ * mappings→config compiler resolves it to the canonical entity key, so it is
+ * persisted verbatim as the relationship's `entity` reference.
+ */
+interface RelationshipCandidate {
+  entityTable: string;
+  name: string;
+  via: RelationshipVia;
+}
+/**
+ * Build the filter for a discriminated entity: rows where `column` equals
+ * `value` belong to this entity (e.g. `role = "owner"`). Returns `undefined`
+ * when either side is blank so the caller can omit the filter entirely.
+ */
+declare function buildFilterFromDiscriminator(column: string | null | undefined, value: string): FilterExpr | undefined;
+/**
+ * A stable identity string for a relationship's `via`. Two candidates on the
+ * same source table always differ in their join (`fkOn`+column, join-table
+ * keys, or raw SQL), so this disambiguates candidates the heuristic gives the
+ * same `name` (every contact→company candidate is named "company").
+ */
+declare function relationshipViaSignature(via: RelationshipVia): string;
+/**
+ * Compile the selected relationship candidates into the persisted
+ * `RelationshipsMap`. Returns `undefined` for an empty selection so the caller
+ * omits the field.
+ */
+declare function buildRelationships(candidates: RelationshipCandidate[]): RelationshipsMap | undefined;
+//#endregion
+export { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature };

package/dist/mapping-form.mjs

@@ -0,0 +1,47 @@
+//#region src/mapping-form.ts
+/**
+* Build the filter for a discriminated entity: rows where `column` equals
+* `value` belong to this entity (e.g. `role = "owner"`). Returns `undefined`
+* when either side is blank so the caller can omit the filter entirely.
+*/
+function buildFilterFromDiscriminator(column, value) {
+	const col = column?.trim();
+	const val = value.trim();
+	if (!col || val === "") return;
+	return { [col]: { eq: val } };
+}
+/**
+* A stable identity string for a relationship's `via`. Two candidates on the
+* same source table always differ in their join (`fkOn`+column, join-table
+* keys, or raw SQL), so this disambiguates candidates the heuristic gives the
+* same `name` (every contact→company candidate is named "company").
+*/
+function relationshipViaSignature(via) {
+	if ("fkOn" in via) return `fk:${via.fkOn}:${via.column}`;
+	if ("through" in via) return `through:${via.through}:${via.localKey}:${via.foreignKey}`;
+	return `raw:${via.$raw}`;
+}
+/**
+* Compile the selected relationship candidates into the persisted
+* `RelationshipsMap`. Returns `undefined` for an empty selection so the caller
+* omits the field.
+*/
+function buildRelationships(candidates) {
+	if (candidates.length === 0) return;
+	const map = {};
+	for (const candidate of candidates) {
+		let key = candidate.name;
+		let suffix = 2;
+		while (key in map) {
+			key = `${candidate.name}_${suffix}`;
+			suffix++;
+		}
+		map[key] = {
+			entity: candidate.entityTable,
+			via: candidate.via
+		};
+	}
+	return map;
+}
+//#endregion
+export { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature };

package/dist/mappings-config.d.mts

@@ -0,0 +1,41 @@
+import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+
+//#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;
+}
+/**
+ * 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.mjs

@@ -0,0 +1,79 @@
+//#region src/mappings-config.ts
+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: { ...row.fieldMap }
+	};
+	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
+export { mappingsToEntitiesConfig };

package/dist/sync-engine.d.mts

@@ -0,0 +1,138 @@
+import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+import { CompileOptions, CompiledView } from "./view-compiler.mjs";
+
+//#region src/sync-engine.d.ts
+/**
+ * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's
+ * own mirror tables (`crm_companies`, `crm_contacts`).
+ *
+ * The reconciliation is the heart of the design: rows present in a view are
+ * created or updated in the mirror; rows that *leave* a view (e.g. an owner
+ * demoted to a member) are **archived, not deleted**, so their deals/activities
+ * survive. Identity fields are host-owned and overwritten each run; Clivly-owned
+ * CRM fields are never touched here.
+ *
+ * `reconcile()` is a pure function and independently testable. `runSync()`
+ * orchestrates: compile views → for each (companies first, so contact
+ * `company_ref`s resolve to a live `crm_companies.id`) read the view, reconcile
+ * against the current mirror, resolve company refs, and persist. All DB I/O is
+ * behind the `SyncStore` port — core stays ORM-agnostic; the SDK/drizzle
+ * package provides the concrete store.
+ */
+/** A row read from a compiled view (what Postgres returns). */
+interface SourceRow {
+  /** Host-side company key from `<relationship>_ref`; resolved before persist. */
+  companyRef?: string | null;
+  /** Mapped identity fields (clivly field → value). */
+  fields: Record<string, string | null>;
+  /** The source primary key — becomes the mirror row's `source_ref`. */
+  sourceRef: string;
+}
+/** An existing mirror row, as far as reconciliation needs to know. */
+interface MirrorRecord {
+  archivedAt: Date | null;
+  id: string;
+  sourceRef: string;
+}
+type SyncAction = {
+  kind: "create";
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "update";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "restore";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "archive";
+  id: string;
+  sourceRef: string;
+};
+/** A persist action with the company ref resolved to a `crm_companies.id`. */
+type PersistAction = {
+  kind: "create";
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+} | {
+  kind: "update";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+} | {
+  kind: "restore";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+} | {
+  kind: "archive";
+  id: string;
+  sourceRef: string;
+};
+/**
+ * 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 `sourceRef` (first wins). A person appearing
+ * under multiple companies (many-to-many via a join table) collapses to their
+ * first company here; richer many-to-many membership is deferred.
+ */
+declare function reconcile(source: SourceRow[], mirror: MirrorRecord[]): SyncAction[];
+/** DB I/O port. The concrete store lives in the SDK/drizzle package. */
+interface SyncStore {
+  /** Current mirror rows for a concept + role (including archived). */
+  listMirror(input: {
+    concept: string;
+    role: string;
+  }): Promise<MirrorRecord[]>;
+  /** Apply the resolved actions to the mirror table for this concept + role. */
+  persist(input: {
+    concept: string;
+    role: string;
+    actions: PersistAction[];
+  }): Promise<void>;
+  /** Execute the view's SQL and return its rows. */
+  readView(view: CompiledView): Promise<SourceRow[]>;
+  /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
+  resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
+}
+interface EntitySyncResult {
+  archived: number;
+  concept: string;
+  created: number;
+  entityKey: string;
+  restored: number;
+  role: string;
+  updated: number;
+}
+interface SyncResult {
+  entities: EntitySyncResult[];
+  totals: {
+    created: number;
+    updated: number;
+    restored: number;
+    archived: number;
+  };
+}
+/**
+ * Run a full sync: compile the config's views, then reconcile + persist each,
+ * companies first. Returns per-entity and total action counts.
+ */
+declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+//#endregion
+export { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync };

package/dist/sync-engine.mjs

@@ -0,0 +1,138 @@
+import { compileEntityViews } from "./view-compiler.mjs";
+//#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 `sourceRef` (first wins). A person appearing
+* under multiple companies (many-to-many via a join table) collapses to their
+* first company here; richer many-to-many membership is deferred.
+*/
+function reconcile(source, mirror) {
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	for (const row of source) if (!seen.has(row.sourceRef)) {
+		seen.add(row.sourceRef);
+		rows.push(row);
+	}
+	const byRef = new Map(mirror.map((m) => [m.sourceRef, m]));
+	const liveRefs = /* @__PURE__ */ new Set();
+	const actions = [];
+	for (const row of rows) {
+		liveRefs.add(row.sourceRef);
+		const existing = byRef.get(row.sourceRef);
+		const companyRef = row.companyRef ?? null;
+		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) if (!(liveRefs.has(m.sourceRef) || 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
+		};
+	});
+}
+function emptyTally() {
+	return {
+		create: 0,
+		update: 0,
+		restore: 0,
+		archive: 0
+	};
+}
+/**
+* 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 views = compileEntityViews(config, options).sort(syncOrder);
+	const entities = [];
+	const totals = {
+		created: 0,
+		updated: 0,
+		restored: 0,
+		archived: 0
+	};
+	for (const view of views) {
+		const [source, mirror] = await Promise.all([store.readView(view), store.listMirror({
+			concept: view.concept,
+			role: view.role
+		})]);
+		const actions = reconcile(source, mirror);
+		const persistActions = await resolveActions(store, actions);
+		await store.persist({
+			concept: view.concept,
+			role: view.role,
+			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
+	};
+}
+//#endregion
+export { reconcile, runSync };

package/dist/types.d.mts

@@ -0,0 +1,148 @@
+//#region src/types.d.ts
+type ContactStatus = "lead" | "active" | "customer" | "churned";
+type DealStage = "lead" | "qualified" | "proposal" | "negotiation" | "won" | "lost";
+type TaskStatus = "todo" | "in_progress" | "done" | "cancelled";
+type TaskPriority = "low" | "medium" | "high";
+type TaskEntityType = "contact" | "company" | "deal";
+type ActivityType = "note" | "email" | "task" | "deal" | "call";
+type CrmRole = "owner" | "admin" | "member" | "developer" | "support_agent";
+interface Contact {
+  companyId: string | null;
+  createdAt: Date;
+  email: string;
+  id: string;
+  lastActivityAt: Date | null;
+  name: string;
+  orgId: string;
+  status: ContactStatus;
+  title: string | null;
+}
+interface Company {
+  createdAt: Date;
+  domain: string | null;
+  id: string;
+  industry: string | null;
+  name: string;
+  orgId: string;
+  size: string | null;
+}
+interface Deal {
+  closeDate: Date | null;
+  contactId: string | null;
+  createdAt: Date;
+  id: string;
+  name: string;
+  orgId: string;
+  owner: string | null;
+  stage: DealStage;
+  value: number;
+}
+interface Task {
+  archivedAt: Date | null;
+  assignee: string | null;
+  completedAt: Date | null;
+  contactId: string | null;
+  createdAt: Date;
+  createdBy: string | null;
+  description: string | null;
+  dueAt: Date | null;
+  entityId: string | null;
+  entityType: TaskEntityType | null;
+  id: string;
+  orgId: string;
+  priority: TaskPriority;
+  status: TaskStatus;
+  title: string;
+}
+interface Note {
+  archivedAt: Date | null;
+  author: string | null;
+  body: string;
+  contactId: string | null;
+  createdAt: Date;
+  createdBy: string | null;
+  entityId: string | null;
+  entityType: TaskEntityType | null;
+  id: string;
+  isTemplate: boolean;
+  orgId: string;
+  title: string;
+  updatedAt: Date;
+}
+interface Activity {
+  actor: string | null;
+  contactId: string | null;
+  createdAt: Date;
+  id: string;
+  orgId: string;
+  summary: string;
+  type: ActivityType;
+}
+interface CreateContactInput {
+  companyId?: string;
+  email: string;
+  name: string;
+  status?: ContactStatus;
+  title?: string;
+}
+interface UpdateContactInput {
+  companyId?: string | null;
+  email?: string;
+  name?: string;
+  status?: ContactStatus;
+  title?: string | null;
+}
+interface CreateCompanyInput {
+  domain?: string;
+  industry?: string;
+  name: string;
+  size?: string;
+}
+interface CreateDealInput {
+  contactId?: string;
+  name: string;
+  owner?: string;
+  stage?: DealStage;
+  value?: number;
+}
+interface CreateTaskInput {
+  assignee?: string;
+  createdBy?: string;
+  description?: string;
+  dueAt?: Date;
+  entityId?: string;
+  entityType?: TaskEntityType;
+  priority?: TaskPriority;
+  title: string;
+}
+interface UpdateTaskInput {
+  assignee?: string | null;
+  description?: string | null;
+  dueAt?: Date | null;
+  entityId?: string | null;
+  entityType?: TaskEntityType | null;
+  priority?: TaskPriority;
+  title?: string;
+}
+interface CreateActivityInput {
+  actor?: string;
+  contactId?: string;
+  summary: string;
+  type: ActivityType;
+}
+interface ContactFilters {
+  companyId?: string;
+  search?: string;
+  status?: ContactStatus;
+}
+interface TaskFilters {
+  assignee?: string;
+  entityId?: string;
+  entityType?: TaskEntityType;
+  includeArchived?: boolean;
+  includeCompleted?: boolean;
+  priority?: TaskPriority;
+  status?: TaskStatus;
+}
+//#endregion
+export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/view-compiler.d.mts

@@ -0,0 +1,43 @@
+import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+
+//#region src/view-compiler.d.ts
+interface CompileOptions {
+  /**
+   * Optional tenant-scoping predicate ANDed into every view's WHERE, e.g.
+   * `{ column: "workspace_id", value: "ws_123" }`. Column must exist on the
+   * entity's source table (the compiler does not verify that — validate first).
+   */
+  orgScope?: {
+    column: string;
+    value: string | number;
+  };
+  /**
+   * Emit views `WITH (security_invoker = true)` so they run with the querying
+   * role's privileges instead of the (owner's) definer privileges — the
+   * default Postgres behaviour, which bypasses the caller's RLS. Defaults to
+   * `true`: the security boundary the product promises. Set `false` only for
+   * hosts on Postgres < 15, which lacks the option.
+   */
+  securityInvoker?: boolean;
+  /** View name prefix. Defaults to `crm_src_`. */
+  viewPrefix?: string;
+}
+interface CompiledView {
+  /** Output column names in SELECT order (`id`, mapped fields, then `<rel>_ref`s). */
+  columns: string[];
+  concept: string;
+  /** `DROP VIEW IF EXISTS …` statement (for teardown / reconfiguration). */
+  dropSql: string;
+  entityKey: string;
+  /** Resolved role — the entity's `role` or `"primary"`. */
+  role: string;
+  sourceTable: string;
+  /** `CREATE OR REPLACE VIEW … AS …` statement. */
+  sql: string;
+  viewName: string;
+}
+declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
+/** Compile every entity in the config into its view, in declaration order. */
+declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
+//#endregion
+export { CompileOptions, CompiledView, compileEntityView, compileEntityViews };