@clivly/core 0.8.0 → 0.9.1

package/dist/entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config.cjs");
+const require_entity_config = require("./entity-config-Dh8aEcgj.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
@@ -101,7 +101,10 @@ const CONCEPT_FIELDS = {
 			"name",
 			"full_name",
 			"fullname",
-			"display_name"
+			"display_name",
+			"first_name",
+			"firstname",
+			"given_name"
 		],
 		required: false
 	}, {
@@ -224,12 +227,28 @@ function suggestCursorField(columnKeys) {
 	return null;
 }
 const MATERIALIZING = new Set(require_entity_config.MATERIALIZING_CONCEPTS);
+const ENDS_IN_CONSONANT_Y = /[^aeiou]y$/;
+const NEEDS_ES = /(s|x|z|ch|sh)$/;
+const IRREGULAR_PLURALS = {
+	person: "people",
+	child: "children",
+	man: "men",
+	woman: "women"
+};
+function pluralize(name) {
+	const irregular = IRREGULAR_PLURALS[name];
+	if (irregular) return irregular;
+	if (ENDS_IN_CONSONANT_Y.test(name)) return `${name.slice(0, -1)}ies`;
+	if (NEEDS_ES.test(name)) return `${name}es`;
+	return `${name}s`;
+}
 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 };
+	const candidates = [normalized, pluralize(normalized)];
+	if (candidates.some((candidate) => entry.names.includes(candidate))) return { exact: true };
+	if (entry.names.some((name) => candidates.some((candidate) => candidate.includes(name)))) return { exact: false };
 	return null;
 }
 function metaFor(table, column) {
@@ -245,17 +264,18 @@ function scoreConcepts(table) {
 	for (const concept of TARGET_CONCEPTS) {
 		if (!MATERIALIZING.has(concept)) continue;
 		const nameMatch = matchesConcept(table.name, concept);
-		if (!nameMatch) continue;
+		const definingColumns = hasDefiningColumn(concept, table.columns);
+		if (!(nameMatch || definingColumns)) continue;
 		let score = 0;
 		const reasons = [];
-		if (nameMatch.exact) {
+		if (nameMatch?.exact) {
 			score += require_mapping_score.W.nameExact;
 			reasons.push(`name matches "${table.name}"`);
-		} else {
+		} else if (nameMatch) {
 			score += require_mapping_score.W.nameSubstring;
 			reasons.push(`name looks like ${concept}`);
 		}
-		if (hasDefiningColumn(concept, table.columns)) {
+		if (definingColumns) {
 			score += require_mapping_score.W.definingColumn;
 			reasons.push(`has the columns a ${concept} needs`);
 		}

package/dist/entity-heuristics.d.cts

@@ -1,3 +1,4 @@
+import { f as DiscoveredColumnMeta } from "./entity-config-CLxI8dVb.cjs";
 import { Scored } from "./mapping-score.cjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.d.mts

@@ -1,3 +1,4 @@
+import { f as DiscoveredColumnMeta } from "./entity-config-CLxI8dVb.mjs";
 import { Scored } from "./mapping-score.mjs";
 //#region src/entity-heuristics.d.ts
 declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
@@ -6,17 +7,6 @@ declare function suggestCursorField(columnKeys: string[]): string | null;
 declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface DiscoveredColumnMeta {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  references?: {
-    table: string;
-    column: string;
-  };
-  type?: string;
-}
 interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
@@ -64,4 +54,4 @@ interface FieldSuggestion {
 declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
 declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { MATERIALIZING_CONCEPTS } from "./entity-config.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-8Fgr6IOH.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 = [
@@ -100,7 +100,10 @@ const CONCEPT_FIELDS = {
 			"name",
 			"full_name",
 			"fullname",
-			"display_name"
+			"display_name",
+			"first_name",
+			"firstname",
+			"given_name"
 		],
 		required: false
 	}, {
@@ -223,12 +226,28 @@ function suggestCursorField(columnKeys) {
 	return null;
 }
 const MATERIALIZING = new Set(MATERIALIZING_CONCEPTS);
+const ENDS_IN_CONSONANT_Y = /[^aeiou]y$/;
+const NEEDS_ES = /(s|x|z|ch|sh)$/;
+const IRREGULAR_PLURALS = {
+	person: "people",
+	child: "children",
+	man: "men",
+	woman: "women"
+};
+function pluralize(name) {
+	const irregular = IRREGULAR_PLURALS[name];
+	if (irregular) return irregular;
+	if (ENDS_IN_CONSONANT_Y.test(name)) return `${name.slice(0, -1)}ies`;
+	if (NEEDS_ES.test(name)) return `${name}es`;
+	return `${name}s`;
+}
 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 };
+	const candidates = [normalized, pluralize(normalized)];
+	if (candidates.some((candidate) => entry.names.includes(candidate))) return { exact: true };
+	if (entry.names.some((name) => candidates.some((candidate) => candidate.includes(name)))) return { exact: false };
 	return null;
 }
 function metaFor(table, column) {
@@ -244,17 +263,18 @@ function scoreConcepts(table) {
 	for (const concept of TARGET_CONCEPTS) {
 		if (!MATERIALIZING.has(concept)) continue;
 		const nameMatch = matchesConcept(table.name, concept);
-		if (!nameMatch) continue;
+		const definingColumns = hasDefiningColumn(concept, table.columns);
+		if (!(nameMatch || definingColumns)) continue;
 		let score = 0;
 		const reasons = [];
-		if (nameMatch.exact) {
+		if (nameMatch?.exact) {
 			score += W.nameExact;
 			reasons.push(`name matches "${table.name}"`);
-		} else {
+		} else if (nameMatch) {
 			score += W.nameSubstring;
 			reasons.push(`name looks like ${concept}`);
 		}
-		if (hasDefiningColumn(concept, table.columns)) {
+		if (definingColumns) {
 			score += W.definingColumn;
 			reasons.push(`has the columns a ${concept} needs`);
 		}

package/dist/env-file.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/env-file.ts
+const ENV_FRAMEWORKS = [
+	"next",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt",
+	"hono-workers"
+];
+const ENV_FILES = {
+	next: ".env.local",
+	"tanstack-start": ".env",
+	sveltekit: ".env",
+	remix: ".env",
+	nuxt: ".env",
+	"hono-workers": ".dev.vars"
+};
+/** The conventional env file for a framework. `.env` when we do not know. */
+function envFileFor(framework) {
+	return ENV_FILES[normalizeFramework(framework)] ?? ".env";
+}
+const ALIASES = {
+	next: "next",
+	nextjs: "next",
+	"next.js": "next",
+	"tanstack-start": "tanstack-start",
+	tanstack: "tanstack-start",
+	sveltekit: "sveltekit",
+	remix: "remix",
+	nuxt: "nuxt",
+	"hono-workers": "hono-workers",
+	hono: "hono-workers",
+	workers: "hono-workers"
+};
+/** The canonical id for a framework name, or null when unrecognised. */
+function normalizeFramework(framework) {
+	if (!framework) return null;
+	return ALIASES[framework.toLowerCase()] ?? null;
+}
+/**
+* Which env file to actually write to.
+*
+* Prefers a file that already holds the key over the conventional one: a
+* project that has been running with credentials in `.env` must not suddenly
+* get a second copy in `.env.local`, leaving two files disagreeing and the
+* stale one still loading. Convention applies to new setups, not to a working
+* one someone already has.
+*/
+function resolveEnvFile(input) {
+	const conventional = envFileFor(input.framework);
+	if (input.existing.includes(conventional)) return conventional;
+	return input.existing[0] ?? conventional;
+}
+//#endregion
+exports.ENV_FRAMEWORKS = ENV_FRAMEWORKS;
+exports.envFileFor = envFileFor;
+exports.normalizeFramework = normalizeFramework;
+exports.resolveEnvFile = resolveEnvFile;

package/dist/env-file.d.cts

@@ -0,0 +1,23 @@
+//#region src/env-file.d.ts
+declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+type EnvFramework = (typeof ENV_FRAMEWORKS)[number];
+/** The conventional env file for a framework. `.env` when we do not know. */
+declare function envFileFor(framework: string | null | undefined): string;
+/** The canonical id for a framework name, or null when unrecognised. */
+declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
+/**
+ * Which env file to actually write to.
+ *
+ * Prefers a file that already holds the key over the conventional one: a
+ * project that has been running with credentials in `.env` must not suddenly
+ * get a second copy in `.env.local`, leaving two files disagreeing and the
+ * stale one still loading. Convention applies to new setups, not to a working
+ * one someone already has.
+ */
+declare function resolveEnvFile(input: {
+  /** Candidate filenames that already contain the credential, if any. */
+  existing: string[];
+  framework: string | null | undefined;
+}): string;
+//#endregion
+export { ENV_FRAMEWORKS, EnvFramework, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/env-file.d.mts

@@ -0,0 +1,23 @@
+//#region src/env-file.d.ts
+declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+type EnvFramework = (typeof ENV_FRAMEWORKS)[number];
+/** The conventional env file for a framework. `.env` when we do not know. */
+declare function envFileFor(framework: string | null | undefined): string;
+/** The canonical id for a framework name, or null when unrecognised. */
+declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
+/**
+ * Which env file to actually write to.
+ *
+ * Prefers a file that already holds the key over the conventional one: a
+ * project that has been running with credentials in `.env` must not suddenly
+ * get a second copy in `.env.local`, leaving two files disagreeing and the
+ * stale one still loading. Convention applies to new setups, not to a working
+ * one someone already has.
+ */
+declare function resolveEnvFile(input: {
+  /** Candidate filenames that already contain the credential, if any. */
+  existing: string[];
+  framework: string | null | undefined;
+}): string;
+//#endregion
+export { ENV_FRAMEWORKS, EnvFramework, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/env-file.mjs

@@ -0,0 +1,55 @@
+//#region src/env-file.ts
+const ENV_FRAMEWORKS = [
+	"next",
+	"tanstack-start",
+	"sveltekit",
+	"remix",
+	"nuxt",
+	"hono-workers"
+];
+const ENV_FILES = {
+	next: ".env.local",
+	"tanstack-start": ".env",
+	sveltekit: ".env",
+	remix: ".env",
+	nuxt: ".env",
+	"hono-workers": ".dev.vars"
+};
+/** The conventional env file for a framework. `.env` when we do not know. */
+function envFileFor(framework) {
+	return ENV_FILES[normalizeFramework(framework)] ?? ".env";
+}
+const ALIASES = {
+	next: "next",
+	nextjs: "next",
+	"next.js": "next",
+	"tanstack-start": "tanstack-start",
+	tanstack: "tanstack-start",
+	sveltekit: "sveltekit",
+	remix: "remix",
+	nuxt: "nuxt",
+	"hono-workers": "hono-workers",
+	hono: "hono-workers",
+	workers: "hono-workers"
+};
+/** The canonical id for a framework name, or null when unrecognised. */
+function normalizeFramework(framework) {
+	if (!framework) return null;
+	return ALIASES[framework.toLowerCase()] ?? null;
+}
+/**
+* Which env file to actually write to.
+*
+* Prefers a file that already holds the key over the conventional one: a
+* project that has been running with credentials in `.env` must not suddenly
+* get a second copy in `.env.local`, leaving two files disagreeing and the
+* stale one still loading. Convention applies to new setups, not to a working
+* one someone already has.
+*/
+function resolveEnvFile(input) {
+	const conventional = envFileFor(input.framework);
+	if (input.existing.includes(conventional)) return conventional;
+	return input.existing[0] ?? conventional;
+}
+//#endregion
+export { ENV_FRAMEWORKS, envFileFor, normalizeFramework, resolveEnvFile };

package/dist/index.cjs

@@ -1,10 +1,77 @@
 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_projection = require("./projection-BXBkh7qp.cjs");
+const require_entity_config = require("./entity-config-Dh8aEcgj.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_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
 const require_sync_engine = require("./sync-engine.cjs");
+//#region src/projection-draft.ts
+function emptyProjectionDraft(baseTable) {
+	return {
+		baseTable,
+		entityKey: "",
+		fieldBindings: {},
+		identity: { kind: "base_pk" },
+		joins: []
+	};
+}
+/**
+* The ON conditions implied by a foreign key between the two tables, so the
+* builder can pre-fill a join instead of making the user hand-pick columns.
+* Returns [] when no FK relates them — the user then picks manually.
+*/
+function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
+	const join = schema.find((t) => t.name === joinTable);
+	const conditions = [];
+	for (const column of join?.columnsMeta ?? []) if (column.references?.table === baseTable) conditions.push({
+		left: {
+			table: joinKey,
+			column: column.name
+		},
+		op: "eq",
+		right: {
+			table: require_projection.BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+function draftToProjection(draft) {
+	if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
+	if (Object.keys(draft.fieldBindings).length === 0) return null;
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: draft.entityKey,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+function draftErrors(draft, schema) {
+	const projection = draftToProjection(draft);
+	if (!projection) return [{
+		path: "projection",
+		message: "Name the object and map a field."
+	}];
+	return require_entity_config.validateProjection(projection, schema, "projection");
+}
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+function describeCardinality(draft, schema) {
+	const projection = draftToProjection(draft);
+	if (!projection) return [];
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const fanning = new Set(require_entity_config.fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+exports.BASE_REF = require_projection.BASE_REF;
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
@@ -13,16 +80,30 @@ 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.columnMetaFor = require_entity_config.columnMetaFor;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
+exports.describeCardinality = describeCardinality;
+exports.draftErrors = draftErrors;
+exports.draftToProjection = draftToProjection;
+exports.emptyProjectionDraft = emptyProjectionDraft;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
 exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
+exports.fanOutJoins = require_entity_config.fanOutJoins;
 exports.filterSchema = require_entity_config.filterSchema;
+exports.hasRichMeta = require_entity_config.hasRichMeta;
+exports.identityRefs = require_projection.identityRefs;
+exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
+exports.primaryKeyColumns = require_entity_config.primaryKeyColumns;
+exports.projectionSchema = require_projection.projectionSchema;
 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.suggestJoinConditions = suggestJoinConditions;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;
+exports.validateProjection = require_entity_config.validateProjection;

package/dist/index.d.cts

@@ -1,9 +1,79 @@
 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 { A as ProjectionIdentity, C as filterSchema, D as validateEntitiesConfig, E as relationshipsSchema, F as projectionSchema, M as ProjectionMapping, N as ProjectionRef, O as BASE_REF, P as identityRefs, S as entitiesConfigSchema, T as relationshipSchema, _ as MaterializingConcept, a as ClivlyEntitiesConfig, b as RelationshipsMap, d as CrmConcept, f as DiscoveredColumnMeta, g as MATERIALIZING_CONCEPTS, h as FilterValue, i as ClivlyConfigError, j as ProjectionJoin, k as ProjectionFieldBinding, l as ConfigValidationError, m as FilterExpr, n as CRM_CONCEPTS, p as DiscoveredSchemaTable, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as RelationshipSpec, x as defineClivlyConfig, y as RelationshipVia } from "./entity-config-CLxI8dVb.cjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.cjs";
-export { type Activity, type ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#region src/projection-cardinality.d.ts
+declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
+/** Every join in the projection that can multiply rows. */
+declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
+//#endregion
+//#region src/projection-draft.d.ts
+/**
+ * The builder's in-progress shape.
+ *
+ * A draft is deliberately looser than a `ProjectionMapping`: it exists while
+ * the user is still choosing things, so every field can be empty. All of the
+ * builder's rules live here as pure functions, which keeps the React components
+ * presentational and lets the rules be tested without a DOM.
+ */
+interface ProjectionDraft {
+  baseTable: string;
+  entityKey: string;
+  fieldBindings: Record<string, ProjectionFieldBinding>;
+  identity: ProjectionIdentity;
+  joins: ProjectionJoin[];
+}
+declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
+/**
+ * The ON conditions implied by a foreign key between the two tables, so the
+ * builder can pre-fill a join instead of making the user hand-pick columns.
+ * Returns [] when no FK relates them — the user then picks manually.
+ */
+declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
+  fansOut: boolean;
+  joinKey: string;
+}>;
+//#endregion
+//#region src/projection-validate.d.ts
+/**
+ * Validate a projection against the discovered schema. Returns every error
+ * found (not just the first) so a builder UI can show them all at once.
+ */
+declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+//#endregion
+//#region src/schema-meta.d.ts
+/**
+ * Accessors over a discovered table's schema-v2 metadata.
+ *
+ * Every helper treats *absent* metadata as **unknown**, never as a negative
+ * fact. `coversUniqueKey` returning false on a v1 payload is what makes
+ * projection validation fail closed: we cannot prove a join is many-to-one, so
+ * we refuse to compile it rather than guess.
+ */
+declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
+/**
+ * Every primary-key column. More than one entry means a composite PK, which is
+ * why `base_pk` identity is rejected for such tables.
+ */
+declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
+/**
+ * Do `columns` contain every column of at least one unique key on `table`?
+ *
+ * This is the fan-out test. A join whose ON columns cover a unique key of the
+ * joined table matches at most one row per base row; one that does not can
+ * match many.
+ */
+declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
+/** Is this table's payload rich enough to validate a projection against? */
+declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
+//#endregion
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.d.mts

@@ -1,9 +1,79 @@
 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, 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 { A as ProjectionIdentity, C as filterSchema, D as validateEntitiesConfig, E as relationshipsSchema, F as projectionSchema, M as ProjectionMapping, N as ProjectionRef, O as BASE_REF, P as identityRefs, S as entitiesConfigSchema, T as relationshipSchema, _ as MaterializingConcept, a as ClivlyEntitiesConfig, b as RelationshipsMap, d as CrmConcept, f as DiscoveredColumnMeta, g as MATERIALIZING_CONCEPTS, h as FilterValue, i as ClivlyConfigError, j as ProjectionJoin, k as ProjectionFieldBinding, l as ConfigValidationError, m as FilterExpr, n as CRM_CONCEPTS, p as DiscoveredSchemaTable, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as RelationshipSpec, x as defineClivlyConfig, y as RelationshipVia } from "./entity-config-CLxI8dVb.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
 import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
-export { type Activity, type ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#region src/projection-cardinality.d.ts
+declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
+/** Every join in the projection that can multiply rows. */
+declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
+//#endregion
+//#region src/projection-draft.d.ts
+/**
+ * The builder's in-progress shape.
+ *
+ * A draft is deliberately looser than a `ProjectionMapping`: it exists while
+ * the user is still choosing things, so every field can be empty. All of the
+ * builder's rules live here as pure functions, which keeps the React components
+ * presentational and lets the rules be tested without a DOM.
+ */
+interface ProjectionDraft {
+  baseTable: string;
+  entityKey: string;
+  fieldBindings: Record<string, ProjectionFieldBinding>;
+  identity: ProjectionIdentity;
+  joins: ProjectionJoin[];
+}
+declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
+/**
+ * The ON conditions implied by a foreign key between the two tables, so the
+ * builder can pre-fill a join instead of making the user hand-pick columns.
+ * Returns [] when no FK relates them — the user then picks manually.
+ */
+declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
+/** Per-join fan-out, for the builder's inline cardinality hints. */
+declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
+  fansOut: boolean;
+  joinKey: string;
+}>;
+//#endregion
+//#region src/projection-validate.d.ts
+/**
+ * Validate a projection against the discovered schema. Returns every error
+ * found (not just the first) so a builder UI can show them all at once.
+ */
+declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+//#endregion
+//#region src/schema-meta.d.ts
+/**
+ * Accessors over a discovered table's schema-v2 metadata.
+ *
+ * Every helper treats *absent* metadata as **unknown**, never as a negative
+ * fact. `coversUniqueKey` returning false on a v1 payload is what makes
+ * projection validation fail closed: we cannot prove a join is many-to-one, so
+ * we refuse to compile it rather than guess.
+ */
+declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
+/**
+ * Every primary-key column. More than one entry means a composite PK, which is
+ * why `base_pk` identity is rejected for such tables.
+ */
+declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
+/**
+ * Do `columns` contain every column of at least one unique key on `table`?
+ *
+ * This is the fan-out test. A join whose ON columns cover a unique key of the
+ * joined table matches at most one row per base row; one that does not can
+ * match many.
+ */
+declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
+/** Is this table's payload rich enough to validate a projection against? */
+declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
+//#endregion
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };