clivly 0.9.5 → 0.9.7

package/drizzle.mjs

@@ -1,7 +1,7 @@
-import { t as BASE_REF } from "./projection-CSGJbZlZ.mjs";
+import { t as BASE_REF } from "./projection-hnPSgH6G.mjs";
 import { t as DRIZZLE_META } from "./drizzle-meta-D-5k3n0i.mjs";
-import { a as quoteIdent, n as compileProjectionIdentity, r as compileProjectionJoins, t as compileProjectionFrom } from "./projection-sql-BgnfiGqF.mjs";
-import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-3kvhkwO7.mjs";
+import { a as compileProjectionPreview, i as compileProjectionJoins, n as compileProjectionFrom, r as compileProjectionIdentity, s as quoteIdent } from "./projection-sql-9zzTVGvf.mjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-wbcuG-cy.mjs";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
 //#region ../sdk/src/drizzle-projection.ts
 /** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
@@ -39,10 +39,12 @@ function fromDrizzleProjection(db, projection, opts) {
 	const client = db;
 	const known = /* @__PURE__ */ new Set([BASE_REF, ...projection.joins.map((j) => j.key)]);
 	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
-	const cursorRef = parseRef(opts.cursorField);
-	assertKnownRef(cursorRef, known, "cursorField");
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
 	const identityExpr = compileProjectionIdentity(projection, opts.basePkColumn ?? "");
+	const fromClause = [compileProjectionFrom(projection), ...compileProjectionJoins(projection)].join(" ");
+	if (opts.cursorField === void 0) return fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
 	const cursorToken = refToken(cursorRef);
 	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
 	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
@@ -54,11 +56,7 @@ function fromDrizzleProjection(db, projection, opts) {
 		emitted.add(token);
 		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
 	}
-	const head = [
-		`select ${selectItems.join(", ")}`,
-		compileProjectionFrom(projection),
-		...compileProjectionJoins(projection)
-	].join(" ");
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
 		cursorField: cursorToken,
@@ -71,6 +69,49 @@ function fromDrizzleProjection(db, projection, opts) {
 		}
 	};
 }
+/**
+* The identity-only paging path `fromDrizzleProjection` takes when
+* `cursorField` is omitted. Deliberately not a generalisation of the
+* timestamp path above — it selects no timestamp cursor, pages on the
+* identity expression alone, and always reports `cursorField`/`idField` as
+* `"id"`, the alias every row carries either way.
+*/
+function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts) {
+	const selectItems = [`${identityExpr} AS ${quoteIdent("id")}`];
+	const emitted = /* @__PURE__ */ new Set();
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
+	}
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: "id",
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? sql` where ${sql.raw(identityExpr)} > ${since.id}` : sql``;
+			const query = sql`${sql.raw(head)}${where} order by ${sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
+//#region ../sdk/src/projection-preview.ts
+/** `db.execute` returns either an array or `{ rows }`, depending on driver. */
+function rowsOf(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("previewProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+async function previewProjection(db, projection, opts) {
+	const client = db;
+	const { sql } = await import("drizzle-orm");
+	return rowsOf(await client.execute(sql.raw(compileProjectionPreview(projection, opts.limit))));
+}
 //#endregion
 //#region ../sdk/src/drizzle.ts
 function inferIdField(table) {
@@ -134,6 +175,16 @@ function drizzleIntrospector(db) {
 		},
 		async sampleSelect(table) {
 			await client.execute(sql`select 1 from ${sql.identifier(table)} limit 1`);
+		},
+		runProjection(projection, opts) {
+			return previewProjection(db, projection, opts);
+		},
+		projectionSource(projection, opts) {
+			return fromDrizzleProjection(db, projection, {
+				entity: opts.objectType,
+				objectType: opts.objectType,
+				...opts.basePkColumn ? { basePkColumn: opts.basePkColumn } : {}
+			});
 		}
 	};
 }

package/{entity-config-B74SPOUZ.mjs → entity-config-C8IIkrmX.mjs}

@@ -1,4 +1,4 @@
-import { a as _enum, c as literal, d as strictObject, f as string, i as projectionSchema, l as number, o as array, p as union, r as identityRefs, s as boolean, t as BASE_REF, u as record } from "./projection-CSGJbZlZ.mjs";
+import { a as projectionSchema, c as boolean, d as record, f as strictObject, i as identityRefs, l as literal, m as union, o as _enum, p as string, s as array, t as BASE_REF, u as number } from "./projection-hnPSgH6G.mjs";
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.
@@ -137,7 +137,7 @@ function checkTablesExist(errors, projection, resolver, base) {
 		if (!hasRichMeta(table)) {
 			errors.push({
 				path,
-				message: `table "${name}" has no key/column metadata — upgrade @clivly/sdk and re-run discovery before using a projection`
+				message: `table "${name}" was discovered without column types or unique keys, which a projection needs to prove its id is unique. Redeploy or restart the app so it re-reports its schema (or run \`clivly push-schema\`); if the table is declared by hand as \`{ name, columns }\`, use \`discoverFromDrizzle\` so keys and types come with it.`
 			});
 			ok = false;
 		}
@@ -182,10 +182,27 @@ function checkRefs(errors, projection, resolver, base, basePk) {
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) checkRef(errors, resolver, `${base}.projection.fieldBindings.${field}`, binding.from);
 	for (const ref of identityRefs(projection.identity, basePk)) checkRef(errors, resolver, `${base}.projection.identity`, ref);
 }
+/**
+* Prove that a single-column identity (`column`, or `base_pk` with an
+* explicit column) is actually unique.
+*
+* `coversUniqueKey` fails closed on absent metadata, same as every other
+* check in this file: a column not provably covered by a unique key is
+* rejected, never assumed safe.
+*/
+function checkSingleColumnIdentity(errors, resolver, path, ref) {
+	const table = resolver.tableFor(ref.table);
+	if (!table) return;
+	if (!coversUniqueKey(table, [ref.column])) errors.push({
+		path,
+		message: `identity column "${ref.table}.${ref.column}" is not covered by a unique key of "${table.name}" — pick a column with a unique constraint, or use a composite identity that is`
+	});
+}
 function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 	const path = `${base}.projection.identity`;
 	const pk = primaryKeyColumns(baseTable);
-	if (projection.identity.kind === "base_pk" && !projection.identity.column) {
+	const { identity } = projection;
+	if (identity.kind === "base_pk" && !identity.column) {
 		if (pk.length === 0) {
 			errors.push({
 				path,
@@ -200,9 +217,21 @@ function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 			});
 			return;
 		}
+		return;
+	}
+	if (identity.kind === "base_pk" && identity.column) {
+		checkSingleColumnIdentity(errors, resolver, path, {
+			table: BASE_REF,
+			column: identity.column
+		});
+		return;
+	}
+	if (identity.kind === "column") {
+		checkSingleColumnIdentity(errors, resolver, path, identity.from);
+		return;
 	}
-	if (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	if (identity.kind !== "composite") return;
+	for (const part of identity.parts) {
 		const table = resolver.tableFor(part.table);
 		const meta = table && columnMetaFor(table, part.column);
 		if (!meta) continue;

package/{entity-config-7sGCk_nw.cjs → entity-config-CPM-Tp-d.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-Dz6_i1-w.cjs");
+const require_projection = require("./projection-DEwL-D8R.cjs");
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.
@@ -137,7 +137,7 @@ function checkTablesExist(errors, projection, resolver, base) {
 		if (!hasRichMeta(table)) {
 			errors.push({
 				path,
-				message: `table "${name}" has no key/column metadata — upgrade @clivly/sdk and re-run discovery before using a projection`
+				message: `table "${name}" was discovered without column types or unique keys, which a projection needs to prove its id is unique. Redeploy or restart the app so it re-reports its schema (or run \`clivly push-schema\`); if the table is declared by hand as \`{ name, columns }\`, use \`discoverFromDrizzle\` so keys and types come with it.`
 			});
 			ok = false;
 		}
@@ -182,10 +182,27 @@ function checkRefs(errors, projection, resolver, base, basePk) {
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) checkRef(errors, resolver, `${base}.projection.fieldBindings.${field}`, binding.from);
 	for (const ref of require_projection.identityRefs(projection.identity, basePk)) checkRef(errors, resolver, `${base}.projection.identity`, ref);
 }
+/**
+* Prove that a single-column identity (`column`, or `base_pk` with an
+* explicit column) is actually unique.
+*
+* `coversUniqueKey` fails closed on absent metadata, same as every other
+* check in this file: a column not provably covered by a unique key is
+* rejected, never assumed safe.
+*/
+function checkSingleColumnIdentity(errors, resolver, path, ref) {
+	const table = resolver.tableFor(ref.table);
+	if (!table) return;
+	if (!coversUniqueKey(table, [ref.column])) errors.push({
+		path,
+		message: `identity column "${ref.table}.${ref.column}" is not covered by a unique key of "${table.name}" — pick a column with a unique constraint, or use a composite identity that is`
+	});
+}
 function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 	const path = `${base}.projection.identity`;
 	const pk = primaryKeyColumns(baseTable);
-	if (projection.identity.kind === "base_pk" && !projection.identity.column) {
+	const { identity } = projection;
+	if (identity.kind === "base_pk" && !identity.column) {
 		if (pk.length === 0) {
 			errors.push({
 				path,
@@ -200,9 +217,21 @@ function checkIdentitySafety(errors, projection, resolver, base, baseTable) {
 			});
 			return;
 		}
+		return;
+	}
+	if (identity.kind === "base_pk" && identity.column) {
+		checkSingleColumnIdentity(errors, resolver, path, {
+			table: require_projection.BASE_REF,
+			column: identity.column
+		});
+		return;
+	}
+	if (identity.kind === "column") {
+		checkSingleColumnIdentity(errors, resolver, path, identity.from);
+		return;
 	}
-	if (projection.identity.kind !== "composite") return;
-	for (const part of projection.identity.parts) {
+	if (identity.kind !== "composite") return;
+	for (const part of identity.parts) {
 		const table = resolver.tableFor(part.table);
 		const meta = table && columnMetaFor(table, part.column);
 		if (!meta) continue;

package/index.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
+const require_entity_config = require("./entity-config-CPM-Tp-d.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-CM1UO-I7.cjs");
+const require_sdk = require("./sdk-BL9BCzyD.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -1596,7 +1596,7 @@ function planInit(schema, overrides = {}) {
 			todos.push(...candidateTodos);
 			company = candidate;
 			if (require_internal_entity_heuristics.matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
-		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain, or build a derived object from it in Clivly (Integrations → Map as custom object) if the fields live in a joined table.`);
 	}
 	if (contactTable && contact) {
 		const scored = require_internal_entity_heuristics.scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1871,6 +1871,7 @@ function renderImports(plan) {
 		"import { createClivlySDK, defineClivlyConfig } from \"clivly/sdk\";",
 		"import { fromDrizzle } from \"clivly/drizzle\";",
 		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
+		"import { drizzleIntrospector } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
 	if (plan.db === null) {
@@ -1903,6 +1904,9 @@ export default createClivlySDK({
   // Every table in your Drizzle schema, so the Clivly dashboard can offer them
   // all when you add a mapping — not just the ones wired up as sources below.
   schema: discoverFromDrizzle(schema),
+  // Lets derived objects authored in the dashboard run against this database.
+  // Without it they are fetched, validated and then skipped.
+  introspector: drizzleIntrospector(${dbExpr}),
   source: {
     // Keyed by CRM concept — contacts/companies/deals/custom.
     // NOT by your entity key. The entity's own \`source:\` above is a table name.
@@ -3124,15 +3128,16 @@ const triggerUrlStage = {
 	label: "Sync trigger URL",
 	needs: [configStage.id],
 	run(ctx) {
-		const url = ctx.sdk?.syncTrigger?.url;
-		if (url && !require_sdk.isPlaceholderUrl(url)) return Promise.resolve({
+		const trigger = ctx.sdk?.describeSyncTrigger?.();
+		if (trigger?.resolved) return Promise.resolve({
 			state: "pass",
-			detail: url
+			detail: trigger.resolved
 		});
-		const isPlaceholder = url !== void 0;
+		const configured = trigger?.configured;
+		const isPlaceholder = configured !== void 0 && require_sdk.isPlaceholderUrl(configured);
 		return Promise.resolve({
 			state: "warn",
-			detail: isPlaceholder ? `Still the placeholder (${url}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
+			detail: isPlaceholder ? `Still the scaffolded placeholder (${configured}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
 			hint: "Replace <yourDomain.com> with your deployed origin, or delete the line — on Vercel, Cloudflare Pages, Railway, Render and Fly the SDK derives the URL from the platform. For local development run `clivly dev`: it opens a tunnel and registers the URL for you, outranking whatever is in .env. Push-only setups can ignore this."
 		});
 	}
@@ -3200,6 +3205,32 @@ const STATUS_STAGES = [
 		}
 	},
 	sdkChecksStage,
+	{
+		id: "derived-objects",
+		label: "Dashboard-authored objects",
+		needs: [configStage.id],
+		run(ctx) {
+			const remote = ctx.sdk?.describeRemoteProjections?.();
+			if (!remote) return Promise.resolve({
+				state: "skip",
+				detail: "This app's installed clivly predates dashboard-authored objects."
+			});
+			if (!remote.capable) return Promise.resolve({
+				state: "warn",
+				detail: "Objects authored in the dashboard cannot run against this app.",
+				hint: "Add `introspector: drizzleIntrospector(db)` to clivly.config.ts."
+			});
+			if (!remote.ran) return Promise.resolve({
+				state: "pass",
+				detail: "Ready; no sync has run in this process yet."
+			});
+			const broken = remote.invalid + remote.failed;
+			return Promise.resolve({
+				state: broken > 0 ? "warn" : "pass",
+				detail: broken > 0 ? `${remote.ok} running, ${broken} not — open the object in Clivly for the reason.` : `${remote.ok} running.`
+			});
+		}
+	},
 	triggerUrlStage
 ];
 function defaultLoadSdk(path) {
@@ -3253,7 +3284,8 @@ const ALIAS_STAGE_IDS = {
 		"config",
 		"runtime",
 		"boot-hook",
-		"setup-checks"
+		"setup-checks",
+		"derived-objects"
 	],
 	connect: [
 		"api-key",

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-B74SPOUZ.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-C8IIkrmX.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-DYBDR939.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-CubnsyD9.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -1595,7 +1595,7 @@ function planInit(schema, overrides = {}) {
 			todos.push(...candidateTodos);
 			company = candidate;
 			if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
-		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain, or build a derived object from it in Clivly (Integrations → Map as custom object) if the fields live in a joined table.`);
 	}
 	if (contactTable && contact) {
 		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1870,6 +1870,7 @@ function renderImports(plan) {
 		"import { createClivlySDK, defineClivlyConfig } from \"clivly/sdk\";",
 		"import { fromDrizzle } from \"clivly/drizzle\";",
 		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
+		"import { drizzleIntrospector } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
 	if (plan.db === null) {
@@ -1902,6 +1903,9 @@ export default createClivlySDK({
   // Every table in your Drizzle schema, so the Clivly dashboard can offer them
   // all when you add a mapping — not just the ones wired up as sources below.
   schema: discoverFromDrizzle(schema),
+  // Lets derived objects authored in the dashboard run against this database.
+  // Without it they are fetched, validated and then skipped.
+  introspector: drizzleIntrospector(${dbExpr}),
   source: {
     // Keyed by CRM concept — contacts/companies/deals/custom.
     // NOT by your entity key. The entity's own \`source:\` above is a table name.
@@ -3123,15 +3127,16 @@ const triggerUrlStage = {
 	label: "Sync trigger URL",
 	needs: [configStage.id],
 	run(ctx) {
-		const url = ctx.sdk?.syncTrigger?.url;
-		if (url && !isPlaceholderUrl(url)) return Promise.resolve({
+		const trigger = ctx.sdk?.describeSyncTrigger?.();
+		if (trigger?.resolved) return Promise.resolve({
 			state: "pass",
-			detail: url
+			detail: trigger.resolved
 		});
-		const isPlaceholder = url !== void 0;
+		const configured = trigger?.configured;
+		const isPlaceholder = configured !== void 0 && isPlaceholderUrl(configured);
 		return Promise.resolve({
 			state: "warn",
-			detail: isPlaceholder ? `Still the placeholder (${url}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
+			detail: isPlaceholder ? `Still the scaffolded placeholder (${configured}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
 			hint: "Replace <yourDomain.com> with your deployed origin, or delete the line — on Vercel, Cloudflare Pages, Railway, Render and Fly the SDK derives the URL from the platform. For local development run `clivly dev`: it opens a tunnel and registers the URL for you, outranking whatever is in .env. Push-only setups can ignore this."
 		});
 	}
@@ -3199,6 +3204,32 @@ const STATUS_STAGES = [
 		}
 	},
 	sdkChecksStage,
+	{
+		id: "derived-objects",
+		label: "Dashboard-authored objects",
+		needs: [configStage.id],
+		run(ctx) {
+			const remote = ctx.sdk?.describeRemoteProjections?.();
+			if (!remote) return Promise.resolve({
+				state: "skip",
+				detail: "This app's installed clivly predates dashboard-authored objects."
+			});
+			if (!remote.capable) return Promise.resolve({
+				state: "warn",
+				detail: "Objects authored in the dashboard cannot run against this app.",
+				hint: "Add `introspector: drizzleIntrospector(db)` to clivly.config.ts."
+			});
+			if (!remote.ran) return Promise.resolve({
+				state: "pass",
+				detail: "Ready; no sync has run in this process yet."
+			});
+			const broken = remote.invalid + remote.failed;
+			return Promise.resolve({
+				state: broken > 0 ? "warn" : "pass",
+				detail: broken > 0 ? `${remote.ok} running, ${broken} not — open the object in Clivly for the reason.` : `${remote.ok} running.`
+			});
+		}
+	},
 	triggerUrlStage
 ];
 function defaultLoadSdk(path) {
@@ -3252,7 +3283,8 @@ const ALIAS_STAGE_IDS = {
 		"config",
 		"runtime",
 		"boot-hook",
-		"setup-checks"
+		"setup-checks",
+		"derived-objects"
 	],
 	connect: [
 		"api-key",