@clivly/core 0.2.0 → 0.3.0-next.1

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

@@ -53,6 +53,7 @@ function buildEntity(row, refIndex) {
 		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 = {};

package/dist/mappings-config.d.cts

@@ -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.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

@@ -52,6 +52,7 @@ function buildEntity(row, refIndex) {
 		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 = {};

package/dist/sync-engine.cjs

@@ -114,7 +114,8 @@ function isCompositeEntity(config, entityKey) {
 * 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 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,
@@ -123,15 +124,18 @@ async function runSync(config, store, options = {}) {
 		archived: 0
 	};
 	for (const view of views) {
-		const [source, mirror] = await Promise.all([store.readView(view), store.listMirror({
+		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
+			role: view.role,
+			objectTypeId
 		})]);
-		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) });
+		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();
@@ -156,6 +160,52 @@ async function runSync(config, store, options = {}) {
 		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;

package/dist/sync-engine.d.cts

@@ -108,16 +108,23 @@ interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
-    role: 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;
+    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. */
-  readView(view: CompiledView): Promise<SourceRow[]>;
+  /**
+   * 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>>;
 }
@@ -144,5 +151,33 @@ interface SyncResult {
  * 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 { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync };
+export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };

package/dist/sync-engine.d.mts

@@ -108,16 +108,23 @@ interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
-    role: 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;
+    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. */
-  readView(view: CompiledView): Promise<SourceRow[]>;
+  /**
+   * 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>>;
 }
@@ -144,5 +151,33 @@ interface SyncResult {
  * 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 { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync };
+export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };

package/dist/sync-engine.mjs

@@ -113,7 +113,8 @@ function isCompositeEntity(config, entityKey) {
 * companies first. Returns per-entity and total action counts.
 */
 async function runSync(config, store, options = {}) {
-	const views = compileEntityViews(config, options).sort(syncOrder);
+	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,
@@ -122,15 +123,18 @@ async function runSync(config, store, options = {}) {
 		archived: 0
 	};
 	for (const view of views) {
-		const [source, mirror] = await Promise.all([store.readView(view), store.listMirror({
+		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
+			role: view.role,
+			objectTypeId
 		})]);
-		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) });
+		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();
@@ -155,5 +159,49 @@ async function runSync(config, store, options = {}) {
 		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 { reconcile, runSync };
+export { computeSampleWarnings, previewSync, reconcile, runSync };

package/dist/types.d.cts

@@ -34,6 +34,7 @@ interface Deal {
   name: string;
   orgId: string;
   owner: string | null;
+  position: number | null;
   stage: DealStage;
   value: number;
 }
@@ -138,9 +139,11 @@ interface CreateActivityInput {
   summary: string;
   type: ActivityType;
 }
+type RecordSource = "all" | "synced";
 interface ContactFilters {
   companyId?: string;
   search?: string;
+  source?: RecordSource;
   status?: ContactStatus;
 }
 interface TaskFilters {
@@ -153,4 +156,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, UpdateDealInput, UpdateTaskInput };
+export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput };

package/dist/types.d.mts

@@ -34,6 +34,7 @@ interface Deal {
   name: string;
   orgId: string;
   owner: string | null;
+  position: number | null;
   stage: DealStage;
   value: number;
 }
@@ -138,9 +139,11 @@ interface CreateActivityInput {
   summary: string;
   type: ActivityType;
 }
+type RecordSource = "all" | "synced";
 interface ContactFilters {
   companyId?: string;
   search?: string;
+  source?: RecordSource;
   status?: ContactStatus;
 }
 interface TaskFilters {
@@ -153,4 +156,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, UpdateDealInput, UpdateTaskInput };
+export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput };

package/dist/view-compiler.d.cts

@@ -11,6 +11,13 @@ interface CompileOptions {
     column: string;
     value: string | number;
   };
+  /**
+   * Restrict `runSync` to a single entity's view, for a "test with one
+   * record" dry run. See `runSync`'s `sample` option in `sync-engine.ts`.
+   */
+  sample?: {
+    entityKey: string;
+  };
   /**
    * Emit views `WITH (security_invoker = true)` so they run with the querying
    * role's privileges instead of the (owner's) definer privileges — the

package/dist/view-compiler.d.mts

@@ -11,6 +11,13 @@ interface CompileOptions {
     column: string;
     value: string | number;
   };
+  /**
+   * Restrict `runSync` to a single entity's view, for a "test with one
+   * record" dry run. See `runSync`'s `sample` option in `sync-engine.ts`.
+   */
+  sample?: {
+    entityKey: string;
+  };
   /**
    * Emit views `WITH (security_invoker = true)` so they run with the querying
    * role's privileges instead of the (owner's) definer privileges — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.2.0",
+  "version": "0.3.0-next.1",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
@@ -37,6 +37,16 @@
         "default": "./dist/entity-heuristics.cjs"
       }
     },
+    "./mapping-score": {
+      "import": {
+        "types": "./dist/mapping-score.d.mts",
+        "default": "./dist/mapping-score.mjs"
+      },
+      "require": {
+        "types": "./dist/mapping-score.d.cts",
+        "default": "./dist/mapping-score.cjs"
+      }
+    },
     "./auth-adapter": {
       "import": {
         "types": "./dist/auth-adapter.d.mts",
@@ -139,7 +149,7 @@
     "drizzle-orm": "^0.45.1",
     "tsdown": "^0.21.9",
     "typescript": "^6",
-    "vitest": "^3.2.4"
+    "vitest": "3.2.7"
   },
   "scripts": {
     "build": "tsdown",