@clivly/core 0.8.0 → 0.9.0

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-PoOGzvpN.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-BwZ9UgLp.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 { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, 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 { a as ProjectionIdentity, c as ProjectionRef, i as ProjectionFieldBinding, l as identityRefs, n as mappingsToEntitiesConfig, o as ProjectionJoin, r as BASE_REF, s as ProjectionMapping, t as EntityMappingRow, u as projectionSchema } from "./mappings-config-BWo4cRDF.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 { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, 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 { a as ProjectionIdentity, c as ProjectionRef, i as ProjectionFieldBinding, l as identityRefs, n as mappingsToEntitiesConfig, o as ProjectionJoin, r as BASE_REF, s as ProjectionMapping, t as EntityMappingRow, u as projectionSchema } from "./mappings-config-B0W5bVZj.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 };

package/dist/index.mjs

@@ -1,7 +1,73 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, MATERIALIZING_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
+import { _ as hasRichMeta, a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, f as validateProjection, g as coversUniqueKey, h as columnMetaFor, i as ClivlyConfigError, l as relationshipSchema, m as joinFansOut, n as CRM_CONCEPTS, o as defineClivlyConfig, p as fanOutJoins, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema, v as primaryKeyColumns } from "./entity-config-Tb5bbKLj.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
+import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-BKrBA_II.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };
+//#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: 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 (!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 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(fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, 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/integration-state.cjs

@@ -0,0 +1,242 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/integration-state.ts
+const INTEGRATION_STEPS = [
+	"credential",
+	"application",
+	"schema",
+	"mapping",
+	"trigger",
+	"sync",
+	"widget"
+];
+const INTEGRATION_STEP_LABELS = {
+	credential: "Secure credential",
+	application: "Application connected",
+	schema: "Schema discovered",
+	mapping: "Entities mapped",
+	trigger: "Clivly can start a sync",
+	sync: "First sync observed",
+	widget: "Chat widget installed"
+};
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+const STEP_PREREQUISITES = {
+	credential: [],
+	application: ["credential"],
+	schema: ["application"],
+	mapping: ["schema"],
+	trigger: ["application"],
+	sync: ["mapping", "trigger"],
+	widget: ["application"]
+};
+function stepIndex(id) {
+	return INTEGRATION_STEPS.indexOf(id);
+}
+/** A heartbeat older than this means the app stopped checking in. */
+const HEARTBEAT_STALE_MS = 600 * 1e3;
+function formatAge(ms) {
+	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
+	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
+	return `${Math.round(ms / 36e5)}h ago`;
+}
+function heartbeatAge(facts) {
+	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
+}
+/** Is the raw condition behind each step met, ignoring prerequisites? */
+function isSatisfied(id, facts) {
+	const age = heartbeatAge(facts);
+	switch (id) {
+		case "credential": return facts.hasCredential;
+		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "schema": return facts.discoveredTableCount > 0;
+		case "mapping": return facts.mappedEntityCount > 0;
+		case "trigger": return facts.triggerConfigured;
+		case "sync": return facts.lastRun?.ok === true;
+		default: return facts.widgetInstalled;
+	}
+}
+function evidenceFor(id, facts) {
+	const age = heartbeatAge(facts);
+	if (id === "application" && age !== null) return `heartbeat ${formatAge(age)}`;
+	if (id === "schema" && facts.discoveredTableCount > 0) return `found ${facts.discoveredTableCount} tables`;
+	if (id === "mapping" && facts.mappedEntityCount > 0) return `${facts.mappedEntityCount} entity mapped`;
+	if (id === "trigger" && facts.triggerConfigured) return "trigger URL and secret set";
+	if (id === "sync" && facts.lastRun) return `last run ${formatAge(facts.now - facts.lastRun.at)}`;
+	return null;
+}
+function problemFor(id, facts) {
+	if (id === "sync" && facts.lastRun && !facts.lastRun.ok) return {
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see the host response."
+	};
+	if (id === "application") {
+		const age = heartbeatAge(facts);
+		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
+			code: "heartbeat_stale",
+			message: `Your app stopped checking in ${formatAge(age)}.`,
+			fix: "Start your app, then run `npx clivly status`."
+		};
+		if (age === null && facts.everConnected) return {
+			code: "heartbeat_stale",
+			message: "Your application stopped checking in.",
+			fix: "Start your app, then run `npx clivly status`."
+		};
+	}
+	return null;
+}
+/**
+* Walk the ladder once. A step is `blocked` when an earlier step it needs has
+* not been satisfied — a prerequisite statement, not a verdict about this step
+* — and only the first unsatisfied step is `active`, so exactly one root cause
+* ever surfaces.
+*/
+function resolveSteps(facts) {
+	const satisfied = /* @__PURE__ */ new Set();
+	const steps = [];
+	let activeTaken = false;
+	for (const id of INTEGRATION_STEPS) {
+		const unmet = STEP_PREREQUISITES[id].find((need) => !satisfied.has(need));
+		const label = INTEGRATION_STEP_LABELS[id];
+		if (isSatisfied(id, facts)) {
+			satisfied.add(id);
+			steps.push({
+				id,
+				label,
+				state: "done",
+				blockedBy: null,
+				evidence: evidenceFor(id, facts),
+				problem: null
+			});
+			continue;
+		}
+		if (unmet !== void 0) {
+			steps.push({
+				id,
+				label,
+				state: "blocked",
+				blockedBy: unmet,
+				evidence: null,
+				problem: null
+			});
+			continue;
+		}
+		const problem = problemFor(id, facts);
+		let state = "active";
+		if (problem) state = "failed";
+		else if (id === "widget") state = "skipped";
+		const claimsAttention = state === "active" || state === "failed";
+		steps.push({
+			id,
+			label,
+			state: activeTaken && state === "active" ? "blocked" : state,
+			blockedBy: null,
+			evidence: evidenceFor(id, facts),
+			problem: activeTaken ? null : problem
+		});
+		if (claimsAttention) activeTaken = true;
+	}
+	return steps;
+}
+const STEP_STATUS_WHEN_ACTIVE = {
+	credential: "not_configured",
+	application: "awaiting_connection",
+	schema: "connected",
+	mapping: "mapping_required",
+	trigger: "trigger_required",
+	sync: "ready_to_sync",
+	widget: "healthy"
+};
+/**
+* Collapse the ladder to the single status the surfaces switch on. Live
+* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+* ladder position, because they describe the integration as it is now rather
+* than how far setup once got.
+*/
+function deriveStatus(steps, facts) {
+	if (facts.syncInFlight) return "syncing";
+	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
+	if (steps.some((step) => step.state === "failed")) return "error";
+	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
+	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
+	return facts.warnings.length > 0 ? "warning" : "healthy";
+}
+/**
+* The command that installs Clivly into a host app. Exported because the connect
+* dialog prints it too, and it must be the same string as the one the ladder
+* recommends — that pairing is what C-05 broke.
+*/
+const INSTALL_COMMAND = "npx clivly init";
+const NEXT_BY_STEP = {
+	credential: {
+		label: "Create a credential",
+		command: null,
+		envFile: null
+	},
+	application: {
+		label: "Install Clivly in your app",
+		command: INSTALL_COMMAND,
+		envFile: ".env.local"
+	},
+	schema: {
+		label: "Check what the SDK reported",
+		command: "npx clivly status",
+		envFile: null
+	},
+	mapping: {
+		label: "Choose the table holding your people",
+		command: null,
+		envFile: null
+	},
+	trigger: {
+		label: "Let Clivly start a sync",
+		command: null,
+		envFile: null
+	},
+	sync: {
+		label: "Run the first sync",
+		command: "npx clivly sync",
+		envFile: null
+	},
+	widget: {
+		label: "Install the chat widget",
+		command: null,
+		envFile: null
+	}
+};
+/**
+* THE one producer of `next.command`. Six surfaces previously each invented
+* their own "run this next" string, and one of them named a read-only command
+* as the fix for a write problem (C-05). If you need a command for the
+* next-action slot, call this — do not write another one.
+*/
+function nextAction(steps, status) {
+	if (status === "healthy" || status === "syncing") return null;
+	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
+	if (!blocking) return null;
+	if (blocking.problem?.code === "heartbeat_stale") return {
+		label: "Reconnect your app",
+		command: "npx clivly status",
+		envFile: null
+	};
+	return NEXT_BY_STEP[blocking.id];
+}
+function computeIntegrationState(facts) {
+	const steps = resolveSteps(facts);
+	const status = deriveStatus(steps, facts);
+	return {
+		status,
+		steps,
+		next: nextAction(steps, status)
+	};
+}
+//#endregion
+exports.INSTALL_COMMAND = INSTALL_COMMAND;
+exports.INTEGRATION_STEPS = INTEGRATION_STEPS;
+exports.INTEGRATION_STEP_LABELS = INTEGRATION_STEP_LABELS;
+exports.STEP_PREREQUISITES = STEP_PREREQUISITES;
+exports.computeIntegrationState = computeIntegrationState;
+exports.deriveStatus = deriveStatus;
+exports.formatAge = formatAge;
+exports.nextAction = nextAction;
+exports.resolveSteps = resolveSteps;
+exports.stepIndex = stepIndex;