@clivly/core 0.1.0 → 0.3.0-next.1

package/dist/entity-heuristics.mjs

@@ -0,0 +1,431 @@
+import { MATERIALIZING_CONCEPTS } from "./entity-config.mjs";
+import { CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor } from "./mapping-score.mjs";
+//#region src/entity-heuristics.ts
+const TARGET_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+const TABLE_PATTERNS = [
+	{
+		concept: "contact",
+		names: [
+			"users",
+			"customers",
+			"clients",
+			"accounts",
+			"participants",
+			"attendees",
+			"people",
+			"members",
+			"contacts"
+		]
+	},
+	{
+		concept: "company",
+		names: [
+			"companies",
+			"organizations",
+			"organisations",
+			"orgs",
+			"teams",
+			"businesses",
+			"accounts"
+		]
+	},
+	{
+		concept: "deal",
+		names: [
+			"deals",
+			"opportunities",
+			"subscriptions",
+			"orders",
+			"invoices",
+			"sales"
+		]
+	},
+	{
+		concept: "conversation",
+		names: [
+			"conversations",
+			"messages",
+			"tickets",
+			"threads",
+			"chats",
+			"inbox"
+		]
+	},
+	{
+		concept: "activity",
+		names: [
+			"events",
+			"activities",
+			"jobs",
+			"logs",
+			"audit",
+			"shifts",
+			"scans",
+			"sessions"
+		]
+	},
+	{
+		concept: "note",
+		names: [
+			"notes",
+			"comments",
+			"annotations"
+		]
+	}
+];
+const CONCEPT_FIELDS = {
+	contact: [{
+		field: "name",
+		candidates: [
+			"name",
+			"full_name",
+			"fullname",
+			"display_name"
+		],
+		required: false
+	}, {
+		field: "email",
+		candidates: ["email", "email_address"],
+		required: true
+	}],
+	company: [{
+		field: "name",
+		candidates: [
+			"name",
+			"company_name",
+			"legal_name",
+			"title"
+		],
+		required: true
+	}, {
+		field: "domain",
+		candidates: [
+			"domain",
+			"website",
+			"url"
+		],
+		required: false
+	}],
+	deal: [
+		{
+			field: "name",
+			candidates: ["name", "title"],
+			required: true
+		},
+		{
+			field: "value",
+			candidates: [
+				"value",
+				"amount",
+				"total",
+				"price"
+			],
+			required: false
+		},
+		{
+			field: "stage",
+			candidates: [
+				"stage",
+				"status",
+				"state"
+			],
+			required: false
+		}
+	],
+	activity: [
+		{
+			field: "type",
+			candidates: [
+				"type",
+				"kind",
+				"event_type"
+			],
+			required: false
+		},
+		{
+			field: "summary",
+			candidates: [
+				"summary",
+				"description",
+				"message",
+				"title"
+			],
+			required: false
+		},
+		{
+			field: "createdAt",
+			candidates: [
+				"created_at",
+				"createdat",
+				"timestamp"
+			],
+			required: false
+		}
+	],
+	conversation: [{
+		field: "status",
+		candidates: ["status", "state"],
+		required: false
+	}, {
+		field: "subject",
+		candidates: [
+			"subject",
+			"title",
+			"preview"
+		],
+		required: false
+	}],
+	note: [{
+		field: "body",
+		candidates: [
+			"body",
+			"content",
+			"text",
+			"note"
+		],
+		required: true
+	}]
+};
+const CURSOR_CANDIDATES = [
+	"updatedat",
+	"updated_at",
+	"modifiedat",
+	"modified_at",
+	"createdat",
+	"created_at"
+];
+function suggestCursorField(columnKeys) {
+	const lowerToActual = new Map(columnKeys.map((c) => [c.toLowerCase(), c]));
+	for (const candidate of CURSOR_CANDIDATES) {
+		const match = lowerToActual.get(candidate);
+		if (match) return match;
+	}
+	return null;
+}
+const MATERIALIZING = new Set(MATERIALIZING_CONCEPTS);
+function matchesConcept(tableName, concept) {
+	const normalized = tableName.toLowerCase();
+	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
+	if (!entry) return null;
+	if (entry.names.includes(normalized)) return { exact: true };
+	if (entry.names.some((name) => normalized.includes(name))) return { exact: false };
+	return null;
+}
+function metaFor(table, column) {
+	return table.columnsMeta?.find((c) => c.name === column);
+}
+function hasDefiningColumn(concept, columns) {
+	const lower = new Set(columns.map((c) => c.toLowerCase()));
+	const required = CONCEPT_FIELDS[concept].filter((f) => f.required);
+	return required.length > 0 && required.every((f) => f.candidates.some((c) => lower.has(c)));
+}
+function scoreConcepts(table) {
+	const out = [];
+	for (const concept of TARGET_CONCEPTS) {
+		if (!MATERIALIZING.has(concept)) continue;
+		const nameMatch = matchesConcept(table.name, concept);
+		if (!nameMatch) continue;
+		let score = 0;
+		const reasons = [];
+		if (nameMatch.exact) {
+			score += W.nameExact;
+			reasons.push(`name matches "${table.name}"`);
+		} else {
+			score += W.nameSubstring;
+			reasons.push(`name looks like ${concept}`);
+		}
+		if (hasDefiningColumn(concept, table.columns)) {
+			score += W.definingColumn;
+			reasons.push(`has the columns a ${concept} needs`);
+		}
+		if (table.columnsMeta?.some((c) => c.isPrimaryKey)) {
+			score += W.hasPrimaryKey;
+			reasons.push("has primary key");
+		}
+		if (table.rowCount !== void 0) if (table.rowCount === 0) {
+			score += W.emptyTable;
+			reasons.push("table is empty");
+		} else {
+			score += W.hasRows;
+			reasons.push(`${table.rowCount.toLocaleString("en-US")} rows`);
+		}
+		out.push({
+			value: concept,
+			score,
+			tier: tierFor(score, CONCEPT_TIERS),
+			reasons
+		});
+	}
+	return out.sort((a, b) => b.score - a.score);
+}
+function topConcept(table) {
+	const ranked = scoreConcepts(table);
+	const best = ranked[0];
+	if (!best) return null;
+	return {
+		best,
+		ambiguous: isAmbiguous(ranked)
+	};
+}
+function requiredFieldsFor(concept) {
+	if (concept === "custom") return [];
+	return CONCEPT_FIELDS[concept].filter((f) => f.required).map((f) => f.field);
+}
+function validateMapping(requiredFields, fieldMap) {
+	const missing = requiredFields.filter((field) => !fieldMap[field]);
+	return {
+		valid: missing.length === 0,
+		missing
+	};
+}
+const DISCRIMINATOR_COLUMNS = [
+	"role",
+	"type",
+	"kind",
+	"status",
+	"state",
+	"category",
+	"tier"
+];
+function suggestDiscriminatorColumns(columns) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	const out = [];
+	for (const name of DISCRIMINATOR_COLUMNS) {
+		const match = lowerToActual.get(name);
+		if (match) out.push(match);
+	}
+	return out;
+}
+const COMPANY_FK_HINTS = [
+	"organization_id",
+	"organisation_id",
+	"org_id",
+	"company_id",
+	"account_id",
+	"team_id"
+];
+function firstMatchingColumn(columns, hints) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	for (const hint of hints) {
+		const match = lowerToActual.get(hint);
+		if (match) return match;
+	}
+	return null;
+}
+/**
+* Suggest contact→company relationships. When the source table carries FK
+* metadata (`references`), the target table is a *fact*, not a name guess —
+* that scores highest. Without metadata (v1 hosts) we fall back to the legacy
+* FK-name hints at a lower tier.
+*/
+function scoreRelationships(source, allTables) {
+	const companyTables = allTables.filter((t) => t.name !== source.name && topConcept(t)?.best.value === "company");
+	if (companyTables.length === 0) return [];
+	const companyNames = new Set(companyTables.map((t) => t.name.toLowerCase()));
+	const out = [];
+	const seenTargets = /* @__PURE__ */ new Set();
+	for (const col of source.columnsMeta ?? []) {
+		const ref = col.references;
+		if (!(ref && companyNames.has(ref.table.toLowerCase()))) continue;
+		if (seenTargets.has(ref.table.toLowerCase())) continue;
+		seenTargets.add(ref.table.toLowerCase());
+		out.push({
+			value: {
+				name: "company",
+				entityTable: ref.table,
+				via: {
+					fkOn: "contact",
+					column: `${source.name}.${col.name}`
+				}
+			},
+			score: W.fkResolved,
+			tier: tierFor(W.fkResolved, RELATIONSHIP_TIERS),
+			reasons: [`foreign key → ${ref.table}.${ref.column}`]
+		});
+	}
+	if (source.columnsMeta?.length) return out.sort((a, b) => b.score - a.score);
+	const contactFk = firstMatchingColumn(source.columns, COMPANY_FK_HINTS);
+	if (contactFk) out.push({
+		value: {
+			name: "company",
+			entityTable: companyTables[0]?.name ?? "",
+			via: {
+				fkOn: "contact",
+				column: `${source.name}.${contactFk}`
+			}
+		},
+		score: W.fkNameHint,
+		tier: tierFor(W.fkNameHint, RELATIONSHIP_TIERS),
+		reasons: [`column "${contactFk}" looks like a company link`]
+	});
+	return out.sort((a, b) => b.score - a.score);
+}
+const FIELD_TYPE_EXPECTATION = {
+	name: "text",
+	email: "text",
+	domain: "text",
+	stage: "text",
+	status: "text",
+	subject: "text",
+	body: "text",
+	summary: "text",
+	type: "text",
+	value: "numeric",
+	createdAt: "timestamp"
+};
+function typeFits(field, type) {
+	const expectation = FIELD_TYPE_EXPECTATION[field];
+	if (!(expectation && type)) return null;
+	if (expectation === "text") return isTextLike(type);
+	if (expectation === "numeric") return isNumericLike(type);
+	return isTimestampLike(type);
+}
+function scoreFieldMap(concept, table) {
+	const lowerToActual = new Map(table.columns.map((c) => [c.toLowerCase(), c]));
+	const out = [];
+	for (const { field, candidates, required } of CONCEPT_FIELDS[concept]) for (const candidate of candidates) {
+		const column = lowerToActual.get(candidate);
+		if (!column) continue;
+		let score = W.fieldNameMatch;
+		const reasons = [`name matches "${column}"`];
+		const meta = metaFor(table, column);
+		const fits = typeFits(field, meta?.type);
+		if (fits === true) {
+			score += W.typeCompatible;
+			reasons.push(`type ${meta?.type}`);
+		} else if (fits === false) {
+			score += W.typeMismatch;
+			reasons.push(`type ${meta?.type} does not fit ${field}`);
+		}
+		if (required && meta?.nullable === false) {
+			score += W.requiredNotNull;
+			reasons.push("not null");
+		}
+		out.push({
+			value: {
+				field,
+				column,
+				required
+			},
+			score,
+			tier: tierFor(score, FIELD_TIERS),
+			reasons
+		});
+		break;
+	}
+	return out;
+}
+function toFieldMap(scored) {
+	const map = {};
+	for (const { value } of scored) map[value.field] = value.column;
+	return map;
+}
+//#endregion
+export { TARGET_CONCEPTS, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/index.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_adapter = require("./auth-adapter.cjs");
+const require_entity_config = require("./entity-config.cjs");
+const require_mapping_form = require("./mapping-form.cjs");
+const require_mappings_config = require("./mappings-config.cjs");
+const require_view_compiler = require("./view-compiler.cjs");
+const require_sync_engine = require("./sync-engine.cjs");
+exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
+exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
+exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
+exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.authCustom = require_auth_adapter.authCustom;
+exports.buildFilterFromDiscriminator = require_mapping_form.buildFilterFromDiscriminator;
+exports.buildRelationships = require_mapping_form.buildRelationships;
+exports.compileEntityView = require_view_compiler.compileEntityView;
+exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
+exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
+exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
+exports.filterSchema = require_entity_config.filterSchema;
+exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
+exports.reconcile = require_sync_engine.reconcile;
+exports.relationshipSchema = require_entity_config.relationshipSchema;
+exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;
+exports.relationshipsSchema = require_entity_config.relationshipsSchema;
+exports.runSync = require_sync_engine.runSync;
+exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
+import { CRMAdapter } from "./adapter.cjs";
+import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.cjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.cjs";
+import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
+import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
+import { CompileOptions, CompiledView, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
+import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.cjs";
+export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, Note, type PersistAction, RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput } from "./types.mjs";
+import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { CompileOptions, CompiledView, compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { CompileOptions, CompiledView, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
-export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type FilterExpr, type FilterValue, type MembershipResolver, type MirrorRecord, Note, type PersistAction, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, Note, type PersistAction, RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/mapping-form.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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
+exports.buildFilterFromDiscriminator = buildFilterFromDiscriminator;
+exports.buildRelationships = buildRelationships;
+exports.relationshipViaSignature = relationshipViaSignature;

package/dist/mapping-form.d.cts

@@ -0,0 +1,35 @@
+import { FilterExpr, RelationshipVia, RelationshipsMap } from "./entity-config.cjs";
+
+//#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-score.cjs

@@ -0,0 +1,97 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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
+exports.AMBIGUITY_MARGIN = AMBIGUITY_MARGIN;
+exports.CONCEPT_TIERS = CONCEPT_TIERS;
+exports.FIELD_TIERS = FIELD_TIERS;
+exports.RELATIONSHIP_TIERS = RELATIONSHIP_TIERS;
+exports.W = W;
+exports.isAmbiguous = isAmbiguous;
+exports.isNumericLike = isNumericLike;
+exports.isTextLike = isTextLike;
+exports.isTimestampLike = isTimestampLike;
+exports.tierFor = tierFor;