clivly 0.1.0 → 0.2.1

package/sync-engine-DedXngop.mjs

@@ -0,0 +1,207 @@
+import { n as compileEntityViews } from "./view-compiler-CosFGar8.mjs";
+//#region ../core/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 = 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
+export { runSync as i, previewSync as n, reconcile as r, computeSampleWarnings as t };

package/sync-engine-uhfzKM-e.d.cts

@@ -0,0 +1,183 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-GczjD3y8.cjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-B4UYTvRM.cjs";
+
+//#region ../core/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; /** Target custom-object type id, for `concept: "custom"` entities. */
+    objectTypeId?: string;
+  }): Promise<MirrorRecord[]>;
+  /** Apply the resolved actions to the mirror table for this concept + role. */
+  persist(input: {
+    concept: string;
+    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    objectTypeId?: string;
+    actions: PersistAction[];
+  }): Promise<void>;
+  /**
+   * Execute the view's SQL and return its rows. `opts.limit`, when given,
+   * caps the number of rows returned (used by `runSync`'s sample mode).
+   */
+  readView(view: CompiledView, opts?: {
+    limit?: number;
+  }): 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>;
+interface PreviewWarning {
+  field?: string;
+  message: string;
+}
+interface PreviewResult {
+  rows: SourceRow[];
+  sampledCount: number;
+  warnings: PreviewWarning[];
+}
+/**
+ * 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.
+ */
+declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+/**
+ * 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).
+ */
+declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+  limit: number;
+  requiredFields: string[];
+  sourceTable: string;
+}): Promise<PreviewResult>;
+//#endregion
+export { PreviewWarning as a, SyncResult as c, previewSync as d, reconcile as f, PreviewResult as i, SyncStore as l, MirrorRecord as n, SourceRow as o, runSync as p, PersistAction as r, SyncAction as s, EntitySyncResult as t, computeSampleWarnings as u };

package/types-C4POUcvk.d.mts

@@ -0,0 +1,158 @@
+//#region ../core/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;
+}
+type RecordSource = "all" | "synced";
+interface ContactFilters {
+  companyId?: string;
+  search?: string;
+  source?: RecordSource;
+  status?: ContactStatus;
+}
+interface TaskFilters {
+  assignee?: string;
+  entityId?: string;
+  entityType?: TaskEntityType;
+  includeArchived?: boolean;
+  includeCompleted?: boolean;
+  priority?: TaskPriority;
+  status?: TaskStatus;
+}
+//#endregion
+export { UpdateDealInput as C, UpdateContactInput as S, Task as _, ContactFilters as a, TaskPriority as b, CreateCompanyInput as c, CreateTaskInput as d, CrmRole as f, RecordSource as g, Note as h, Contact as i, CreateContactInput as l, DealStage as m, ActivityType as n, ContactStatus as o, Deal as p, Company as r, CreateActivityInput as s, Activity as t, CreateDealInput as u, TaskEntityType as v, UpdateTaskInput as w, TaskStatus as x, TaskFilters as y };

package/types-LJTBhkcN.d.cts

@@ -0,0 +1,158 @@
+//#region ../core/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;
+}
+type RecordSource = "all" | "synced";
+interface ContactFilters {
+  companyId?: string;
+  search?: string;
+  source?: RecordSource;
+  status?: ContactStatus;
+}
+interface TaskFilters {
+  assignee?: string;
+  entityId?: string;
+  entityType?: TaskEntityType;
+  includeArchived?: boolean;
+  includeCompleted?: boolean;
+  priority?: TaskPriority;
+  status?: TaskStatus;
+}
+//#endregion
+export { UpdateDealInput as C, UpdateContactInput as S, Task as _, ContactFilters as a, TaskPriority as b, CreateCompanyInput as c, CreateTaskInput as d, CrmRole as f, RecordSource as g, Note as h, Contact as i, CreateContactInput as l, DealStage as m, ActivityType as n, ContactStatus as o, Deal as p, Company as r, CreateActivityInput as s, Activity as t, CreateDealInput as u, TaskEntityType as v, UpdateTaskInput as w, TaskStatus as x, TaskFilters as y };