@clivly/core 0.1.0 → 0.2.0

package/dist/sync-engine.cjs

@@ -0,0 +1,161 @@
+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 views = require_view_compiler.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, { composite: isCompositeEntity(config, view.entityKey) });
+		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
+exports.reconcile = reconcile;
+exports.runSync = runSync;

package/dist/sync-engine.d.cts

@@ -0,0 +1,148 @@
+import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+import { CompileOptions, CompiledView } from "./view-compiler.cjs";
+
+//#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;
+  /** Host-side company key; only consulted in composite (join-table) mode. */
+  companyRef: string | 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;
+  companySourceRef: string | null;
+} | {
+  kind: "update";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+  companySourceRef: string | null;
+} | {
+  kind: "restore";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+  companySourceRef: 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 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.
+ */
+declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+  composite?: boolean;
+}): 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.d.mts

@@ -31,6 +31,8 @@ interface SourceRow {
 /** An existing mirror row, as far as reconciliation needs to know. */
 interface MirrorRecord {
   archivedAt: Date | null;
+  /** Host-side company key; only consulted in composite (join-table) mode. */
+  companyRef: string | null;
   id: string;
   sourceRef: string;
 }
@@ -62,18 +64,21 @@ type PersistAction = {
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
+  companySourceRef: string | null;
 } | {
   kind: "update";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
+  companySourceRef: string | null;
 } | {
   kind: "restore";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
+  companySourceRef: string | null;
 } | {
   kind: "archive";
   id: string;
@@ -88,11 +93,16 @@ type PersistAction = {
  * - 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.
+ * 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.
  */
-declare function reconcile(source: SourceRow[], mirror: MirrorRecord[]): SyncAction[];
+declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+  composite?: boolean;
+}): 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). */

package/dist/sync-engine.mjs

@@ -9,24 +9,32 @@ import { compileEntityViews } from "./view-compiler.mjs";
 * - 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.
+* 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) {
+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) if (!seen.has(row.sourceRef)) {
-		seen.add(row.sourceRef);
-		rows.push(row);
+	for (const row of source) {
+		const key = keyOf(row.sourceRef, row.companyRef ?? null);
+		if (!seen.has(key)) {
+			seen.add(key);
+			rows.push(row);
+		}
 	}
-	const byRef = new Map(mirror.map((m) => [m.sourceRef, m]));
-	const liveRefs = /* @__PURE__ */ new Set();
+	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) {
-		liveRefs.add(row.sourceRef);
-		const existing = byRef.get(row.sourceRef);
 		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,
@@ -48,11 +56,14 @@ function reconcile(source, mirror) {
 			companyRef
 		});
 	}
-	for (const m of mirror) if (!(liveRefs.has(m.sourceRef) || m.archivedAt)) actions.push({
-		kind: "archive",
-		id: m.id,
-		sourceRef: m.sourceRef
-	});
+	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 = {
@@ -75,7 +86,8 @@ async function resolveActions(store, actions) {
 			id: "id" in action ? action.id : "",
 			sourceRef: action.sourceRef,
 			fields: action.fields,
-			companyId
+			companyId,
+			companySourceRef: action.companyRef ?? null
 		};
 	});
 }
@@ -88,6 +100,15 @@ function emptyTally() {
 	};
 }
 /**
+* 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.
 */
@@ -105,7 +126,7 @@ async function runSync(config, store, options = {}) {
 			concept: view.concept,
 			role: view.role
 		})]);
-		const actions = reconcile(source, mirror);
+		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) });
 		const persistActions = await resolveActions(store, actions);
 		await store.persist({
 			concept: view.concept,

package/dist/types.d.cts

@@ -0,0 +1,156 @@
+//#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 UpdateDealInput {
+  closeDate?: Date | null;
+  contactId?: string | null;
+  name?: string;
+  owner?: string | null;
+  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, UpdateDealInput, UpdateTaskInput };

package/dist/types.d.mts

@@ -105,6 +105,14 @@ interface CreateDealInput {
   stage?: DealStage;
   value?: number;
 }
+interface UpdateDealInput {
+  closeDate?: Date | null;
+  contactId?: string | null;
+  name?: string;
+  owner?: string | null;
+  stage?: DealStage;
+  value?: number;
+}
 interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
@@ -145,4 +153,4 @@ interface TaskFilters {
   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 };
+export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput };