@clivly/core 0.8.0 → 0.9.1

package/dist/view-compiler.cjs

@@ -1,189 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/view-compiler.ts
-/**
-* View compiler (Phase 2) — turns a validated entity config into read-only
-* Postgres view DDL.
-*
-* Each entity compiles to `crm_src_<entity>`: a projection over the host table
-* that (a) selects the source primary key as `id` (the sync engine's
-* `source_ref`), (b) aliases mapped columns to their Clivly field names,
-* (c) resolves each relationship to a `<relationship>_ref` column carrying the
-* host-side key, and (d) applies the entity's filter as a WHERE clause.
-*
-* The view is the security boundary: it exposes only allow-listed columns, and
-* the sync engine (Phase 3) reads exclusively from it — never the raw table.
-* Relationship refs stay host-side keys here; Phase 3 maps `<rel>_ref` onto the
-* corresponding `crm_companies.id` mirror row.
-*
-* Pure string generation — no DB access. Config is developer-authored, but all
-* identifiers and literals are still escaped so output is deterministic and
-* injection-safe.
-*/
-/** The source primary-key column. Assumed `id`; the sync engine reads it as `source_ref`. */
-const SOURCE_KEY = "id";
-const DEFAULT_VIEW_PREFIX = "crm_src_";
-const DEFAULT_ROLE = "primary";
-/** Quote a single identifier part, escaping embedded double-quotes. */
-function quoteIdent(name) {
-	return `"${name.replace(/"/g, "\"\"")}"`;
-}
-/** Emit a SQL literal for a scalar filter value. */
-function quoteLiteral(value) {
-	if (typeof value === "number") return String(value);
-	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
-	return `'${value.replace(/'/g, "''")}'`;
-}
-function quoteList(values) {
-	return `(${values.map((v) => quoteLiteral(v)).join(", ")})`;
-}
-/** Compile one column predicate into a SQL boolean expression. */
-function compilePredicate(table, column, value) {
-	const col = `${quoteIdent(table)}.${quoteIdent(column)}`;
-	if (value === null || typeof value !== "object") return `${col} = ${quoteLiteral(value)}`;
-	if ("eq" in value) return `${col} = ${quoteLiteral(value.eq)}`;
-	if ("ne" in value) return `${col} <> ${quoteLiteral(value.ne)}`;
-	if ("in" in value) return `${col} IN ${quoteList(value.in)}`;
-	if ("notIn" in value) return `${col} NOT IN ${quoteList(value.notIn)}`;
-	if ("isNull" in value) return `${col} IS NULL`;
-	if ("isNotNull" in value) return `${col} IS NOT NULL`;
-	throw new Error(`unsupported filter predicate on ${table}.${column}`);
-}
-/**
-* Build the WHERE conditions for an entity. Returns an array of SQL fragments
-* (ANDed by the caller). `$raw` filters pass through verbatim.
-*/
-function compileFilterConditions(table, filter) {
-	if (!filter) return [];
-	if ("$raw" in filter) return [`(${filter.$raw})`];
-	return Object.entries(filter).map(([column, value]) => compilePredicate(table, column, value));
-}
-/** Split a `table.column` ref, defaulting the table when unqualified. */
-function refParts(ref, defaultTable) {
-	const dot = ref.indexOf(".");
-	if (dot === -1) return {
-		table: defaultTable,
-		column: ref
-	};
-	return {
-		table: ref.slice(0, dot),
-		column: ref.slice(dot + 1)
-	};
-}
-function compileRelationship(relName, rel, source, related) {
-	const refCol = `${relName}_ref`;
-	const refAlias = quoteIdent(refCol);
-	const { via } = rel;
-	if ("fkOn" in via) {
-		const relatedTable = related?.source ?? "";
-		if (via.fkOn === "company") {
-			const { table, column } = refParts(via.column, relatedTable);
-			const relatedFilter = compileFilterConditions(table, related?.filter);
-			const on = [`${quoteIdent(table)}.${quoteIdent(column)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`, ...relatedFilter].join(" AND ");
-			return {
-				clause: `LEFT JOIN ${quoteIdent(table)} ON ${on}`,
-				refSelect: `${quoteIdent(table)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
-				refColumn: refCol
-			};
-		}
-		const { table, column } = refParts(via.column, source.source);
-		const on = [`${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} = ${quoteIdent(table)}.${quoteIdent(column)}`, ...compileFilterConditions(relatedTable, related?.filter)].join(" AND ");
-		return {
-			clause: `LEFT JOIN ${quoteIdent(relatedTable)} ON ${on}`,
-			refSelect: `${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
-			refColumn: refCol
-		};
-	}
-	if ("through" in via) {
-		const on = `${quoteIdent(via.through)}.${quoteIdent(via.localKey)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`;
-		return {
-			clause: `LEFT JOIN ${quoteIdent(via.through)} ON ${on}`,
-			refSelect: `${quoteIdent(via.through)}.${quoteIdent(via.foreignKey)} AS ${refAlias}`,
-			refColumn: refCol
-		};
-	}
-	return {
-		clause: via.$raw,
-		refSelect: null,
-		refColumn: refCol
-	};
-}
-function compileEntityView(config, entityKey, options = {}) {
-	const entity = config.entities[entityKey];
-	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
-	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
-	const src = entity.source;
-	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
-	const columns = ["id"];
-	for (const [field, column] of Object.entries(entity.fields)) {
-		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
-		columns.push(field);
-	}
-	const joins = [];
-	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
-		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
-		joins.push(compiled.clause);
-		if (compiled.refSelect) {
-			selectItems.push(compiled.refSelect);
-			columns.push(compiled.refColumn);
-		}
-	}
-	const conditions = compileFilterConditions(src, entity.filter);
-	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
-	const lines = [
-		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
-		`SELECT ${selectItems.join(", ")}`,
-		`FROM ${quoteIdent(src)}`,
-		...joins
-	];
-	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
-	const sql = `${lines.join("\n")};`;
-	return {
-		entityKey,
-		viewName,
-		concept: entity.concept,
-		role: entity.role ?? DEFAULT_ROLE,
-		sourceTable: src,
-		columns,
-		sql,
-		dropSql: `DROP VIEW IF EXISTS ${quoteIdent(viewName)};`
-	};
-}
-/** Compile every entity in the config into its view, in declaration order. */
-function compileEntityViews(config, options = {}) {
-	return Object.keys(config.entities).map((key) => compileEntityView(config, key, options));
-}
-/**
-* Dry-run each entity's compiled view against the host DB via a caller-provided
-* `run` function, so `$raw` filter/join fragments — which skip schema validation
-* (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
-* at sync time. Never throws: each view's outcome is collected into an
-* `ExplainResult`, so a mapping UI or CLI can show every problem at once.
-*
-* `run` should execute the SQL somewhere side-effect-free — e.g. inside a
-* transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
-* compiled SQL is a `CREATE OR REPLACE VIEW`.
-*/
-async function explainEntitiesConfig(config, run, options = {}) {
-	const results = [];
-	for (const view of compileEntityViews(config, options)) try {
-		await run(view.sql);
-		results.push({
-			entityKey: view.entityKey,
-			ok: true,
-			sql: view.sql
-		});
-	} catch (error) {
-		results.push({
-			entityKey: view.entityKey,
-			ok: false,
-			sql: view.sql,
-			error: error instanceof Error ? error.message : String(error)
-		});
-	}
-	return results;
-}
-//#endregion
-exports.DEFAULT_VIEW_PREFIX = DEFAULT_VIEW_PREFIX;
-exports.compileEntityView = compileEntityView;
-exports.compileEntityViews = compileEntityViews;
-exports.explainEntitiesConfig = explainEntitiesConfig;
+const require_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
+exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
+exports.compileEntityView = require_view_compiler.compileEntityView;
+exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
+exports.explainViewExecutionError = require_view_compiler.explainViewExecutionError;

package/dist/view-compiler.d.cts

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
 //#region src/view-compiler.d.ts
 declare const DEFAULT_VIEW_PREFIX = "crm_src_";
 interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
   sql: string;
   viewName: string;
 }
+/**
+ * Translate a driver error from executing a compiled view into something
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
+ *
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+ * compiler cannot catch this itself because the host executes the SQL.
+ */
+declare function explainViewExecutionError(error: unknown): string | undefined;
 declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
 declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
  */
 declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
 //#endregion
-export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig };
+export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/dist/view-compiler.d.mts

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
 //#region src/view-compiler.d.ts
 declare const DEFAULT_VIEW_PREFIX = "crm_src_";
 interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
   sql: string;
   viewName: string;
 }
+/**
+ * Translate a driver error from executing a compiled view into something
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
+ *
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+ * compiler cannot catch this itself because the host executes the SQL.
+ */
+declare function explainViewExecutionError(error: unknown): string | undefined;
 declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
 declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
  */
 declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
 //#endregion
-export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig };
+export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/dist/view-compiler.mjs

@@ -1,185 +1,2 @@
-//#region src/view-compiler.ts
-/**
-* View compiler (Phase 2) — turns a validated entity config into read-only
-* Postgres view DDL.
-*
-* Each entity compiles to `crm_src_<entity>`: a projection over the host table
-* that (a) selects the source primary key as `id` (the sync engine's
-* `source_ref`), (b) aliases mapped columns to their Clivly field names,
-* (c) resolves each relationship to a `<relationship>_ref` column carrying the
-* host-side key, and (d) applies the entity's filter as a WHERE clause.
-*
-* The view is the security boundary: it exposes only allow-listed columns, and
-* the sync engine (Phase 3) reads exclusively from it — never the raw table.
-* Relationship refs stay host-side keys here; Phase 3 maps `<rel>_ref` onto the
-* corresponding `crm_companies.id` mirror row.
-*
-* Pure string generation — no DB access. Config is developer-authored, but all
-* identifiers and literals are still escaped so output is deterministic and
-* injection-safe.
-*/
-/** The source primary-key column. Assumed `id`; the sync engine reads it as `source_ref`. */
-const SOURCE_KEY = "id";
-const DEFAULT_VIEW_PREFIX = "crm_src_";
-const DEFAULT_ROLE = "primary";
-/** Quote a single identifier part, escaping embedded double-quotes. */
-function quoteIdent(name) {
-	return `"${name.replace(/"/g, "\"\"")}"`;
-}
-/** Emit a SQL literal for a scalar filter value. */
-function quoteLiteral(value) {
-	if (typeof value === "number") return String(value);
-	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
-	return `'${value.replace(/'/g, "''")}'`;
-}
-function quoteList(values) {
-	return `(${values.map((v) => quoteLiteral(v)).join(", ")})`;
-}
-/** Compile one column predicate into a SQL boolean expression. */
-function compilePredicate(table, column, value) {
-	const col = `${quoteIdent(table)}.${quoteIdent(column)}`;
-	if (value === null || typeof value !== "object") return `${col} = ${quoteLiteral(value)}`;
-	if ("eq" in value) return `${col} = ${quoteLiteral(value.eq)}`;
-	if ("ne" in value) return `${col} <> ${quoteLiteral(value.ne)}`;
-	if ("in" in value) return `${col} IN ${quoteList(value.in)}`;
-	if ("notIn" in value) return `${col} NOT IN ${quoteList(value.notIn)}`;
-	if ("isNull" in value) return `${col} IS NULL`;
-	if ("isNotNull" in value) return `${col} IS NOT NULL`;
-	throw new Error(`unsupported filter predicate on ${table}.${column}`);
-}
-/**
-* Build the WHERE conditions for an entity. Returns an array of SQL fragments
-* (ANDed by the caller). `$raw` filters pass through verbatim.
-*/
-function compileFilterConditions(table, filter) {
-	if (!filter) return [];
-	if ("$raw" in filter) return [`(${filter.$raw})`];
-	return Object.entries(filter).map(([column, value]) => compilePredicate(table, column, value));
-}
-/** Split a `table.column` ref, defaulting the table when unqualified. */
-function refParts(ref, defaultTable) {
-	const dot = ref.indexOf(".");
-	if (dot === -1) return {
-		table: defaultTable,
-		column: ref
-	};
-	return {
-		table: ref.slice(0, dot),
-		column: ref.slice(dot + 1)
-	};
-}
-function compileRelationship(relName, rel, source, related) {
-	const refCol = `${relName}_ref`;
-	const refAlias = quoteIdent(refCol);
-	const { via } = rel;
-	if ("fkOn" in via) {
-		const relatedTable = related?.source ?? "";
-		if (via.fkOn === "company") {
-			const { table, column } = refParts(via.column, relatedTable);
-			const relatedFilter = compileFilterConditions(table, related?.filter);
-			const on = [`${quoteIdent(table)}.${quoteIdent(column)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`, ...relatedFilter].join(" AND ");
-			return {
-				clause: `LEFT JOIN ${quoteIdent(table)} ON ${on}`,
-				refSelect: `${quoteIdent(table)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
-				refColumn: refCol
-			};
-		}
-		const { table, column } = refParts(via.column, source.source);
-		const on = [`${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} = ${quoteIdent(table)}.${quoteIdent(column)}`, ...compileFilterConditions(relatedTable, related?.filter)].join(" AND ");
-		return {
-			clause: `LEFT JOIN ${quoteIdent(relatedTable)} ON ${on}`,
-			refSelect: `${quoteIdent(relatedTable)}.${quoteIdent(SOURCE_KEY)} AS ${refAlias}`,
-			refColumn: refCol
-		};
-	}
-	if ("through" in via) {
-		const on = `${quoteIdent(via.through)}.${quoteIdent(via.localKey)} = ${quoteIdent(source.source)}.${quoteIdent(SOURCE_KEY)}`;
-		return {
-			clause: `LEFT JOIN ${quoteIdent(via.through)} ON ${on}`,
-			refSelect: `${quoteIdent(via.through)}.${quoteIdent(via.foreignKey)} AS ${refAlias}`,
-			refColumn: refCol
-		};
-	}
-	return {
-		clause: via.$raw,
-		refSelect: null,
-		refColumn: refCol
-	};
-}
-function compileEntityView(config, entityKey, options = {}) {
-	const entity = config.entities[entityKey];
-	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
-	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
-	const src = entity.source;
-	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
-	const columns = ["id"];
-	for (const [field, column] of Object.entries(entity.fields)) {
-		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
-		columns.push(field);
-	}
-	const joins = [];
-	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
-		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
-		joins.push(compiled.clause);
-		if (compiled.refSelect) {
-			selectItems.push(compiled.refSelect);
-			columns.push(compiled.refColumn);
-		}
-	}
-	const conditions = compileFilterConditions(src, entity.filter);
-	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
-	const lines = [
-		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
-		`SELECT ${selectItems.join(", ")}`,
-		`FROM ${quoteIdent(src)}`,
-		...joins
-	];
-	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
-	const sql = `${lines.join("\n")};`;
-	return {
-		entityKey,
-		viewName,
-		concept: entity.concept,
-		role: entity.role ?? DEFAULT_ROLE,
-		sourceTable: src,
-		columns,
-		sql,
-		dropSql: `DROP VIEW IF EXISTS ${quoteIdent(viewName)};`
-	};
-}
-/** Compile every entity in the config into its view, in declaration order. */
-function compileEntityViews(config, options = {}) {
-	return Object.keys(config.entities).map((key) => compileEntityView(config, key, options));
-}
-/**
-* Dry-run each entity's compiled view against the host DB via a caller-provided
-* `run` function, so `$raw` filter/join fragments — which skip schema validation
-* (see `validateEntitiesConfig`) — fail loudly *before* the first sync instead of
-* at sync time. Never throws: each view's outcome is collected into an
-* `ExplainResult`, so a mapping UI or CLI can show every problem at once.
-*
-* `run` should execute the SQL somewhere side-effect-free — e.g. inside a
-* transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
-* compiled SQL is a `CREATE OR REPLACE VIEW`.
-*/
-async function explainEntitiesConfig(config, run, options = {}) {
-	const results = [];
-	for (const view of compileEntityViews(config, options)) try {
-		await run(view.sql);
-		results.push({
-			entityKey: view.entityKey,
-			ok: true,
-			sql: view.sql
-		});
-	} catch (error) {
-		results.push({
-			entityKey: view.entityKey,
-			ok: false,
-			sql: view.sql,
-			error: error instanceof Error ? error.message : String(error)
-		});
-	}
-	return results;
-}
-//#endregion
-export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig };
+import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CcqsGxv4.mjs";
+export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
@@ -47,6 +47,26 @@
         "default": "./dist/mapping-score.cjs"
       }
     },
+    "./integration-state": {
+      "import": {
+        "types": "./dist/integration-state.d.mts",
+        "default": "./dist/integration-state.mjs"
+      },
+      "require": {
+        "types": "./dist/integration-state.d.cts",
+        "default": "./dist/integration-state.cjs"
+      }
+    },
+    "./env-file": {
+      "import": {
+        "types": "./dist/env-file.d.mts",
+        "default": "./dist/env-file.mjs"
+      },
+      "require": {
+        "types": "./dist/env-file.d.cts",
+        "default": "./dist/env-file.cjs"
+      }
+    },
     "./auth-adapter": {
       "import": {
         "types": "./dist/auth-adapter.d.mts",