@clivly/core 0.10.9 → 0.11.0

package/dist/entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-J5KYJVTO.cjs");
+const require_entity_config = require("./entity-config-C2sKAti2.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [
@@ -95,23 +95,39 @@ const TABLE_PATTERNS = [
 	}
 ];
 const CONCEPT_FIELDS = {
-	contact: [{
-		field: "name",
-		candidates: [
-			"name",
-			"full_name",
-			"fullname",
-			"display_name",
-			"first_name",
-			"firstname",
-			"given_name"
-		],
-		required: false
-	}, {
-		field: "email",
-		candidates: ["email", "email_address"],
-		required: true
-	}],
+	contact: [
+		{
+			field: "name",
+			candidates: [
+				"name",
+				"full_name",
+				"fullname",
+				"display_name",
+				"first_name",
+				"firstname",
+				"given_name"
+			],
+			required: false
+		},
+		{
+			field: "email",
+			candidates: ["email", "email_address"],
+			required: true
+		},
+		{
+			field: "phone",
+			candidates: [
+				"phone",
+				"phone_number",
+				"phonenumber",
+				"mobile",
+				"mobile_number",
+				"mobilenumber",
+				"telephone"
+			],
+			required: false
+		}
+	],
 	company: [{
 		field: "name",
 		candidates: [
@@ -363,12 +379,14 @@ function scoreConcepts(table) {
 			score += require_mapping_score.W.hasPrimaryKey;
 			reasons.push("has primary key");
 		}
-		if (table.rowCount !== void 0) if (table.rowCount === 0) {
-			score += require_mapping_score.W.emptyTable;
-			reasons.push("table is empty");
-		} else {
-			score += require_mapping_score.W.hasRows;
-			reasons.push(`${table.rowCount.toLocaleString("en-US")} rows`);
+		if (table.rowCount !== void 0) {
+			if (table.rowCount === 0) {
+				score += require_mapping_score.W.emptyTable;
+				reasons.push("table is empty");
+			} else {
+				score += require_mapping_score.W.hasRows;
+				reasons.push(`${table.rowCount.toLocaleString("en-US")} rows`);
+			}
 		}
 		out.push({
 			value: concept,
@@ -484,6 +502,7 @@ function scoreRelationships(source, allTables) {
 const FIELD_TYPE_EXPECTATION = {
 	name: "text",
 	email: "text",
+	phone: "text",
 	domain: "text",
 	stage: "text",
 	status: "text",

package/dist/entity-heuristics.d.cts

@@ -1,13 +1,13 @@
-import { p as DiscoveredColumnMeta } from "./entity-config-ChHLozko.cjs";
+import { p as DiscoveredColumnMeta } from "./entity-config-OhC4Otkz.cjs";
 import { Scored } from "./mapping-score.cjs";
 //#region src/entity-heuristics.d.ts
-declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
-type TargetConcept = (typeof TARGET_CONCEPTS)[number];
-declare function suggestCursorField(columnKeys: string[]): string | null;
-declare function matchesConcept(tableName: string, concept: TargetConcept): {
+export declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+export type TargetConcept = (typeof TARGET_CONCEPTS)[number];
+export declare function suggestCursorField(columnKeys: string[]): string | null;
+export declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface ScoredTable {
+export interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
   name: string;
@@ -18,7 +18,7 @@ interface ScoredTable {
  * and from bulk apply, so one click can never map an auth table into the CRM.
  * They stay manually selectable — an explicit, informed choice is legitimate.
  */
-declare function hasSensitiveColumns(columns: string[]): boolean;
+export declare function hasSensitiveColumns(columns: string[]): boolean;
 /**
  * Is this table one your auth library created, rather than one you wrote?
  *
@@ -26,20 +26,20 @@ declare function hasSensitiveColumns(columns: string[]): boolean;
  * concept. Never to exclude them: mapping `user` as the contact entity is
  * legitimate for plenty of apps, and it stays selectable.
  */
-declare function isFrameworkTable(name: string): boolean;
-declare function hasDefiningColumn(concept: TargetConcept, columns: string[]): boolean;
-declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
-declare function topConcept(table: ScoredTable): {
+export declare function isFrameworkTable(name: string): boolean;
+export declare function hasDefiningColumn(concept: TargetConcept, columns: string[]): boolean;
+export declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
+export declare function topConcept(table: ScoredTable): {
   best: Scored<TargetConcept>;
   ambiguous: boolean;
 } | null;
-declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
-declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
+export declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
+export declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
   valid: boolean;
   missing: string[];
 };
-declare function suggestDiscriminatorColumns(columns: string[]): string[];
-type SuggestedVia = {
+export declare function suggestDiscriminatorColumns(columns: string[]): string[];
+export type SuggestedVia = {
   fkOn: "company" | "contact";
   column: string;
 } | {
@@ -47,7 +47,7 @@ type SuggestedVia = {
   localKey: string;
   foreignKey: string;
 };
-interface RelationshipSuggestion {
+export interface RelationshipSuggestion {
   /** The related host table. */
   entityTable: string;
   /** Suggested relationship name (defaults to the related concept). */
@@ -60,13 +60,13 @@ interface RelationshipSuggestion {
  * that scores highest. Without metadata (v1 hosts) we fall back to the legacy
  * FK-name hints at a lower tier.
  */
-declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
-interface FieldSuggestion {
+export declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
+export interface FieldSuggestion {
   column: string;
   field: string;
   required: boolean;
 }
-declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
-declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
+export declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
+export declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, hasDefiningColumn, hasSensitiveColumns, isFrameworkTable, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export type { DiscoveredColumnMeta };

package/dist/entity-heuristics.d.mts

@@ -1,13 +1,13 @@
-import { p as DiscoveredColumnMeta } from "./entity-config-ChHLozko.mjs";
+import { p as DiscoveredColumnMeta } from "./entity-config-OhC4Otkz.mjs";
 import { Scored } from "./mapping-score.mjs";
 //#region src/entity-heuristics.d.ts
-declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
-type TargetConcept = (typeof TARGET_CONCEPTS)[number];
-declare function suggestCursorField(columnKeys: string[]): string | null;
-declare function matchesConcept(tableName: string, concept: TargetConcept): {
+export declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+export type TargetConcept = (typeof TARGET_CONCEPTS)[number];
+export declare function suggestCursorField(columnKeys: string[]): string | null;
+export declare function matchesConcept(tableName: string, concept: TargetConcept): {
   exact: boolean;
 } | null;
-interface ScoredTable {
+export interface ScoredTable {
   columns: string[];
   columnsMeta?: DiscoveredColumnMeta[];
   name: string;
@@ -18,7 +18,7 @@ interface ScoredTable {
  * and from bulk apply, so one click can never map an auth table into the CRM.
  * They stay manually selectable — an explicit, informed choice is legitimate.
  */
-declare function hasSensitiveColumns(columns: string[]): boolean;
+export declare function hasSensitiveColumns(columns: string[]): boolean;
 /**
  * Is this table one your auth library created, rather than one you wrote?
  *
@@ -26,20 +26,20 @@ declare function hasSensitiveColumns(columns: string[]): boolean;
  * concept. Never to exclude them: mapping `user` as the contact entity is
  * legitimate for plenty of apps, and it stays selectable.
  */
-declare function isFrameworkTable(name: string): boolean;
-declare function hasDefiningColumn(concept: TargetConcept, columns: string[]): boolean;
-declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
-declare function topConcept(table: ScoredTable): {
+export declare function isFrameworkTable(name: string): boolean;
+export declare function hasDefiningColumn(concept: TargetConcept, columns: string[]): boolean;
+export declare function scoreConcepts(table: ScoredTable): Scored<TargetConcept>[];
+export declare function topConcept(table: ScoredTable): {
   best: Scored<TargetConcept>;
   ambiguous: boolean;
 } | null;
-declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
-declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
+export declare function requiredFieldsFor(concept: TargetConcept | "custom"): string[];
+export declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
   valid: boolean;
   missing: string[];
 };
-declare function suggestDiscriminatorColumns(columns: string[]): string[];
-type SuggestedVia = {
+export declare function suggestDiscriminatorColumns(columns: string[]): string[];
+export type SuggestedVia = {
   fkOn: "company" | "contact";
   column: string;
 } | {
@@ -47,7 +47,7 @@ type SuggestedVia = {
   localKey: string;
   foreignKey: string;
 };
-interface RelationshipSuggestion {
+export interface RelationshipSuggestion {
   /** The related host table. */
   entityTable: string;
   /** Suggested relationship name (defaults to the related concept). */
@@ -60,13 +60,13 @@ interface RelationshipSuggestion {
  * that scores highest. Without metadata (v1 hosts) we fall back to the legacy
  * FK-name hints at a lower tier.
  */
-declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
-interface FieldSuggestion {
+export declare function scoreRelationships(source: ScoredTable, allTables: ScoredTable[]): Scored<RelationshipSuggestion>[];
+export interface FieldSuggestion {
   column: string;
   field: string;
   required: boolean;
 }
-declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
-declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
+export declare function scoreFieldMap(concept: TargetConcept, table: ScoredTable): Scored<FieldSuggestion>[];
+export declare function toFieldMap(scored: Scored<FieldSuggestion>[]): Record<string, string>;
 //#endregion
-export { type DiscoveredColumnMeta, FieldSuggestion, RelationshipSuggestion, ScoredTable, SuggestedVia, TARGET_CONCEPTS, TargetConcept, hasDefiningColumn, hasSensitiveColumns, isFrameworkTable, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping };
+export type { DiscoveredColumnMeta };

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { a as MATERIALIZING_CONCEPTS } from "./entity-config-C_NDVfrL.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-C0rtu-K_.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 = [
@@ -94,23 +94,39 @@ const TABLE_PATTERNS = [
 	}
 ];
 const CONCEPT_FIELDS = {
-	contact: [{
-		field: "name",
-		candidates: [
-			"name",
-			"full_name",
-			"fullname",
-			"display_name",
-			"first_name",
-			"firstname",
-			"given_name"
-		],
-		required: false
-	}, {
-		field: "email",
-		candidates: ["email", "email_address"],
-		required: true
-	}],
+	contact: [
+		{
+			field: "name",
+			candidates: [
+				"name",
+				"full_name",
+				"fullname",
+				"display_name",
+				"first_name",
+				"firstname",
+				"given_name"
+			],
+			required: false
+		},
+		{
+			field: "email",
+			candidates: ["email", "email_address"],
+			required: true
+		},
+		{
+			field: "phone",
+			candidates: [
+				"phone",
+				"phone_number",
+				"phonenumber",
+				"mobile",
+				"mobile_number",
+				"mobilenumber",
+				"telephone"
+			],
+			required: false
+		}
+	],
 	company: [{
 		field: "name",
 		candidates: [
@@ -362,12 +378,14 @@ function scoreConcepts(table) {
 			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`);
+		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,
@@ -483,6 +501,7 @@ function scoreRelationships(source, allTables) {
 const FIELD_TYPE_EXPECTATION = {
 	name: "text",
 	email: "text",
+	phone: "text",
 	domain: "text",
 	stage: "text",
 	status: "text",

package/dist/env-file.d.cts

@@ -1,10 +1,10 @@
 //#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];
+export declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+export 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;
+export 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;
+export declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
 /**
  * Which env file to actually write to.
  *
@@ -14,10 +14,9 @@ declare function normalizeFramework(framework: string | null | undefined): EnvFr
  * stale one still loading. Convention applies to new setups, not to a working
  * one someone already has.
  */
-declare function resolveEnvFile(input: {
+export 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 };
+//#endregion

package/dist/env-file.d.mts

@@ -1,10 +1,10 @@
 //#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];
+export declare const ENV_FRAMEWORKS: readonly ["next", "tanstack-start", "sveltekit", "remix", "nuxt", "hono-workers"];
+export 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;
+export 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;
+export declare function normalizeFramework(framework: string | null | undefined): EnvFramework | null;
 /**
  * Which env file to actually write to.
  *
@@ -14,10 +14,9 @@ declare function normalizeFramework(framework: string | null | undefined): EnvFr
  * stale one still loading. Convention applies to new setups, not to a working
  * one someone already has.
  */
-declare function resolveEnvFile(input: {
+export 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 };
+//#endregion

package/dist/index.cjs

@@ -2,12 +2,90 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_auth_adapter = require("./auth-adapter.cjs");
 const require_projection = require("./projection-DFgCoyZl.cjs");
 const require_schema_meta = require("./schema-meta-Cgi0MnHh.cjs");
-const require_entity_config = require("./entity-config-J5KYJVTO.cjs");
+const require_entity_config = require("./entity-config-C2sKAti2.cjs");
 const require_mapping_form = require("./mapping-form.cjs");
 const require_mappings_config = require("./mappings-config.cjs");
 const require_view_compiler = require("./view-compiler-DP4Fbj7-.cjs");
 const require_sync_engine = require("./sync-engine.cjs");
 const require_types = require("./types.cjs");
+//#region src/host-owned-fields.ts
+/**
+* Which fields a CRM record lets a user edit.
+*
+* A record synced from the host app carries a `sourceRef`. Its identity fields
+* are rewritten from the host view on every sync run, so an edit to one would
+* be silently reverted minutes later — the user sees their change accepted,
+* then gone, with nothing explaining why. That is worse than refusing it.
+*
+* So host-owned fields are rejected at the API, not merely disabled in the UI:
+* the UI is not the security boundary, and the SDK and any future public API
+* reach the same routers.
+*
+* Records created inside the CRM have no `sourceRef` and are fully editable —
+* nothing else owns them.
+*
+* This is the cheap half of a capability matrix. It answers "may a user write
+* this?" but not "may the sync engine write this?", which stays implicit
+* because sync bypasses these routers entirely. An override model (the
+* `stageOverrideAt` pattern on `crm_deals`) can replace this later without
+* changing callers.
+*/
+/** Contact fields the host view owns when the row is synced. */
+const HOST_OWNED_CONTACT_FIELDS = ["email", "name"];
+/**
+* Company fields the host view owns when the row is synced.
+*
+* `email` and `phone` joined this list in the same change that made them
+* mappable (migration 0048). They are not identity fields, but ownership here
+* follows what sync rewrites, not what feels identity-like: both flow from the
+* host view on every run, exactly as `email` does for contacts above. Widening
+* `CANONICAL_FIELDS.company` without widening this list is the specific bug
+* this module's doc comment calls worse than refusing the edit.
+*
+* `primaryContactId` is deliberately absent: it is a CRM-side judgement about
+* who to talk to, never sourced from the host, so it stays editable on synced
+* rows.
+*/
+const HOST_OWNED_COMPANY_FIELDS = [
+	"domain",
+	"name",
+	"email",
+	"phone"
+];
+/**
+* True when the record is owned by a host view rather than by the CRM.
+*
+* Deliberately keyed on `sourceRef` and not `entityRole`: `entityRole` is a
+* mapping label that can be absent on a synced row, while `sourceRef` is the
+* identity the sync engine reconciles against and is set for exactly the rows
+* sync will rewrite.
+*/
+function isHostOwned(record) {
+	return Boolean(record.sourceRef);
+}
+function rejectedFields(record, patch, owned) {
+	if (!isHostOwned(record)) return [];
+	return owned.filter((field) => patch[field] !== void 0);
+}
+/**
+* Host-owned contact fields this patch would change, or `[]` when the patch is
+* allowed. Callers turn a non-empty result into a 400 naming the fields.
+*/
+function rejectedContactFields(contact, patch) {
+	return rejectedFields(contact, patch, HOST_OWNED_CONTACT_FIELDS);
+}
+/** Host-owned company fields this patch would change, or `[]`. */
+function rejectedCompanyFields(company, patch) {
+	return rejectedFields(company, patch, HOST_OWNED_COMPANY_FIELDS);
+}
+/**
+* The message shown when a write is refused. Names the fields and says where
+* they come from, so the reason is actionable rather than a bare "forbidden".
+*/
+function hostOwnedFieldMessage(fields) {
+	return `The ${fields.join(", ")} ${fields.length > 1 ? "fields are" : "field is"} synced from your app and cannot be edited here. Change it in your app and it will update on the next sync.`;
+}
+//#endregion
 //#region src/slug.ts
 /**
 * The one `slugify`.
@@ -180,8 +258,10 @@ exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
 exports.fanOutJoins = require_entity_config.fanOutJoins;
 exports.filterSchema = require_entity_config.filterSchema;
 exports.hasRichMeta = require_schema_meta.hasRichMeta;
+exports.hostOwnedFieldMessage = hostOwnedFieldMessage;
 exports.identityRefs = require_projection.identityRefs;
 exports.isClosedStageType = require_types.isClosedStageType;
+exports.isHostOwned = isHostOwned;
 exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
 exports.matchesCondition = matchesCondition;
@@ -191,6 +271,8 @@ exports.projectionFields = require_entity_config.projectionFields;
 exports.projectionSchema = require_projection.projectionSchema;
 exports.quoteIdent = require_view_compiler.quoteIdent;
 exports.reconcile = require_sync_engine.reconcile;
+exports.rejectedCompanyFields = rejectedCompanyFields;
+exports.rejectedContactFields = rejectedContactFields;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;