clivly 0.7.0 → 0.7.1

package/README.md

@@ -112,9 +112,9 @@ First-class route scaffolding currently exists for:
 - Nuxt
 
 Vue.js apps can still integrate Clivly, but they usually need a manual server
-layer for the tick and verify routes unless they are using Nuxt.
+layer for the tick route unless they are using Nuxt.
 
-When `init` finishes and `CLIVLY_API_KEY` is still empty, it hands you straight
+When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you straight
 into `clivly login` so you don't end up staring at a blank `.env`. That step is
 interactive, so it is skipped automatically when there is no TTY or when `CI` is
 set — and you can always turn it off yourself:
@@ -130,7 +130,7 @@ npx clivly init --no-browser   # pair, but print the URL instead of opening it
 npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
 ```
 
-Pairs this machine with a Clivly workspace and writes `CLIVLY_API_KEY` and
+Pairs this machine with a Clivly workspace and writes `CLIVLY_SECRET_KEY` and
 `CLIVLY_SYNC_TRIGGER_SECRET` into your project's `.env`. It creates a pairing
 session, prints (and by default opens) an approval link, and waits while you
 approve it in a signed-in browser. The approval link is always printed, so an
@@ -139,7 +139,7 @@ SSH or headless session can be approved by opening the link elsewhere.
 - `--no-browser` — print the approval URL without opening a browser.
 - `--force` — overwrite `.env` values that already have a real value. Without
   it, existing values are kept and reported as skipped; an empty placeholder
-  (`CLIVLY_API_KEY=`) is always filled in.
+  (`CLIVLY_SECRET_KEY=`) is always filled in.
 - `--rotate` — rotate the workspace's remote-sync trigger secret instead of
   revealing the current one. Your already-deployed host app will stop receiving
   sync triggers until you redeploy it with the new secret.
@@ -164,10 +164,9 @@ CLI requires pairing.
 
 | Value | Where to get it | Notes |
 | --- | --- | --- |
-| `CLIVLY_API_KEY` | Dashboard → **Settings → API keys** → Create | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. |
+| `CLIVLY_SECRET_KEY` | Dashboard → **Settings → API keys** → Create | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback. |
 | `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger. |
 | `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset. |
-| `CLIVLY_VERIFY_TOKEN` | Dashboard → **Integrations** | Only needed if you mount the auth-verify route. |
 
 Write them into the `.env` of the package that imports `clivly`, then re-run
 `clivly status` to confirm each rung goes green.
@@ -197,16 +196,16 @@ npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
 Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
 the length of the session, so remote sync can reach `localhost` while you
 develop. Your dev server is detected from `package.json` scripts, or pass it
-explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_API_KEY` set.
+explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY` set.
 The override is cleared when the process exits; remote sync is otherwise
 deploy-only.
 
 ## `clivly ping` / `clivly doctor`
 
-`clivly ping` reads `CLIVLY_API_KEY` from the environment, sends one heartbeat, and prints a clear ✅/❌ with the resolved org or the failure reason — so you can confirm a connection from the terminal without writing any code. Point it at a non-default backend with `--api-url <url>` (or `CLIVLY_API_URL`).
+`clivly ping` reads `CLIVLY_SECRET_KEY` from the environment, sends one heartbeat, and prints a clear ✅/❌ with the resolved org or the failure reason — so you can confirm a connection from the terminal without writing any code. Point it at a non-default backend with `--api-url <url>` (or `CLIVLY_API_URL`).
 
 ```bash
-CLIVLY_API_KEY=sk_live_… npx clivly ping
+CLIVLY_SECRET_KEY=sk_live_… npx clivly ping
 #
 # Clivly ping
 #   ✅ Connected to Clivly

package/core-entity-config.cjs

@@ -1,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 const require_entity_config = require("./entity-config-D87rV-tE.cjs");
 //#region src/core-entity-config.ts
-require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");
+require("./deprecate-subpath-B9ngvizt.cjs").warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");
 //#endregion
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;

package/core-entity-config.mjs

@@ -1,5 +1,5 @@
-import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, r as CUSTOM_CONCEPT, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-va2bkH5o.mjs";
+import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 //#region src/core-entity-config.ts
 warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");
 //#endregion

package/core-entity-heuristics.cjs

@@ -1,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
 //#region src/core-entity-heuristics.ts
-require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/entity-heuristics", "clivly/internal/entity-heuristics");
+require("./deprecate-subpath-B9ngvizt.cjs").warnDeprecatedSubpath("clivly/core/entity-heuristics", "clivly/internal/entity-heuristics");
 //#endregion
 exports.TARGET_CONCEPTS = require_internal_entity_heuristics.TARGET_CONCEPTS;
 exports.matchesConcept = require_internal_entity_heuristics.matchesConcept;

package/core-entity-heuristics.mjs

@@ -1,5 +1,5 @@
-import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import { TARGET_CONCEPTS, matchesConcept, requiredFieldsFor, scoreConcepts, scoreFieldMap, scoreRelationships, suggestCursorField, suggestDiscriminatorColumns, toFieldMap, topConcept, validateMapping } from "./internal-entity-heuristics.mjs";
+import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 //#region src/core-entity-heuristics.ts
 warnDeprecatedSubpath("clivly/core/entity-heuristics", "clivly/internal/entity-heuristics");
 //#endregion

package/core-mapping-score.cjs

@@ -1,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 const require_mapping_score = require("./mapping-score-CaB3F4Uu.cjs");
 //#region src/core-mapping-score.ts
-require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/mapping-score", "clivly/internal/mapping-score");
+require("./deprecate-subpath-B9ngvizt.cjs").warnDeprecatedSubpath("clivly/core/mapping-score", "clivly/internal/mapping-score");
 //#endregion
 exports.AMBIGUITY_MARGIN = require_mapping_score.AMBIGUITY_MARGIN;
 exports.CONCEPT_TIERS = require_mapping_score.CONCEPT_TIERS;

package/core-mapping-score.mjs

@@ -1,5 +1,5 @@
-import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import { a as W, c as isTextLike, i as RELATIONSHIP_TIERS, l as isTimestampLike, n as CONCEPT_TIERS, o as isAmbiguous, r as FIELD_TIERS, s as isNumericLike, t as AMBIGUITY_MARGIN, u as tierFor } from "./mapping-score-C68uAqGB.mjs";
+import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 //#region src/core-mapping-score.ts
 warnDeprecatedSubpath("clivly/core/mapping-score", "clivly/internal/mapping-score");
 //#endregion

package/core.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 const require_entity_config = require("./entity-config-D87rV-tE.cjs");
+const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 const require_auth_adapter = require("./auth-adapter-CiEXcweZ.cjs");
 const require_mapping_form = require("./mapping-form-BpfON_ME.cjs");
 const require_mappings_config = require("./mappings-config-BsRADNRv.cjs");

package/core.mjs

@@ -1,5 +1,5 @@
-import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import { a as MATERIALIZING_CONCEPTS, c as filterSchema, d as validateEntitiesConfig, i as ClivlyConfigError, l as relationshipSchema, n as CRM_CONCEPTS, o as defineClivlyConfig, s as entitiesConfigSchema, t as CANONICAL_FIELDS, u as relationshipsSchema } from "./entity-config-va2bkH5o.mjs";
+import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import { t as authCustom } from "./auth-adapter-gfVDxf3d.mjs";
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
 import { t as mappingsToEntitiesConfig } from "./mappings-config-Dbgxx3Nv.mjs";

package/index.cjs

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-D87rV-tE.cjs");
-require("./core-entity-config.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-require("./core-entity-heuristics.cjs");
-require("./core-mapping-score.cjs");
-const require_sdk = require("./sdk-CzOf596t.cjs");
+const require_sdk = require("./sdk-iqOXeWIp.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -720,6 +717,12 @@ function siblingDbCandidates(schemaPath) {
 	const dir = isDirectory(schemaPath) ? schemaPath : (0, node_path.dirname)(schemaPath);
 	return SIBLING_DB_NAMES.map((name) => (0, node_path.join)(dir, name));
 }
+function parentDbCandidates(schemaPath, cwd) {
+	const parent = (0, node_path.dirname)(isDirectory(schemaPath) ? schemaPath : (0, node_path.dirname)(schemaPath));
+	const relativeToRoot = (0, node_path.relative)((0, node_path.resolve)(cwd), (0, node_path.resolve)(parent));
+	if (!(relativeToRoot === "" || !relativeToRoot.startsWith(".."))) return [];
+	return SIBLING_DB_NAMES.map((name) => (0, node_path.join)(parent, name));
+}
 async function discoverSchema(opts) {
 	const load = opts.load ?? defaultLoader$1(opts.cwd);
 	const mod = await loadSchemaModule(opts.schemaPath, load);
@@ -751,6 +754,13 @@ async function discoverSchema(opts) {
 		load,
 		match: isDrizzleDb
 	});
+	if (db === null) db = await probeModule({
+		candidates: parentDbCandidates(opts.schemaPath, opts.cwd),
+		cwd: opts.cwd,
+		graph: opts.graph,
+		load,
+		match: isDrizzleDb
+	});
 	return {
 		tables,
 		importPath,
@@ -1286,10 +1296,6 @@ function renderSource(role, entity, dbExpr) {
 	const opts = entity.idField === null ? `{ entity: "${entity.tableName}", cursorField: "${entity.cursorField}" }` : `{ entity: "${entity.tableName}", cursorField: "${entity.cursorField}", idField: "${entity.idField}" }`;
 	return `    ${role}: fromDrizzle(${dbExpr}, schema.${entity.moduleKey}, ${opts})`;
 }
-function fallbackDbImportPath(schemaImportPath) {
-	const slash = schemaImportPath.lastIndexOf("/");
-	return `${slash >= 0 ? schemaImportPath.slice(0, slash) : "."}/db`;
-}
 function dbIsInSchemaModule(plan) {
 	return plan.db !== null && plan.db.importPath === plan.importPath;
 }
@@ -1304,7 +1310,7 @@ function renderImports(plan) {
 		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
-	if (!plan.db) lines.push(`import { db } from "${fallbackDbImportPath(plan.importPath)}"; // TODO: point at your Drizzle instance`);
+	if (!plan.db) lines.push("import { db } from \"<YOUR_DB_MODULE>\"; // TODO(clivly): replace with the path to your Drizzle `db` instance — NOT your schema file");
 	else if (!dbIsInSchemaModule(plan)) lines.push(`import { ${plan.db.moduleKey} } from "${plan.db.importPath}";`);
 	return lines.join("\n");
 }
@@ -1333,6 +1339,8 @@ export default createClivlySDK({
   // all when you add a mapping — not just the ones wired up as sources below.
   schema: discoverFromDrizzle(schema),
   source: {
+    // Keyed by CRM concept — contacts/companies/deals/custom.
+    // NOT by your entity key. The entity's own \`source:\` above is a table name.
 ${sources.join(",\n")},
   },
   syncTrigger: {
@@ -2133,7 +2141,7 @@ const STATUS_STAGES = [
 			return Promise.resolve({
 				state: "warn",
 				detail: "Not set — remote sync cannot call back into this app.",
-				hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. Push-only setups can ignore this."
+				hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
 			});
 		}
 	}

package/index.mjs

@@ -1,11 +1,8 @@
 #!/usr/bin/env node
 import { t as CANONICAL_FIELDS } from "./entity-config-va2bkH5o.mjs";
-import "./core-entity-config.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import "./core-entity-heuristics.mjs";
-import "./core-mapping-score.mjs";
-import { t as createClivlySDK } from "./sdk-C_1sGiH8.mjs";
+import { t as createClivlySDK } from "./sdk-C6WANW8M.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
@@ -719,6 +716,12 @@ function siblingDbCandidates(schemaPath) {
 	const dir = isDirectory(schemaPath) ? schemaPath : dirname(schemaPath);
 	return SIBLING_DB_NAMES.map((name) => join(dir, name));
 }
+function parentDbCandidates(schemaPath, cwd) {
+	const parent = dirname(isDirectory(schemaPath) ? schemaPath : dirname(schemaPath));
+	const relativeToRoot = relative(resolve(cwd), resolve(parent));
+	if (!(relativeToRoot === "" || !relativeToRoot.startsWith(".."))) return [];
+	return SIBLING_DB_NAMES.map((name) => join(parent, name));
+}
 async function discoverSchema(opts) {
 	const load = opts.load ?? defaultLoader$1(opts.cwd);
 	const mod = await loadSchemaModule(opts.schemaPath, load);
@@ -750,6 +753,13 @@ async function discoverSchema(opts) {
 		load,
 		match: isDrizzleDb
 	});
+	if (db === null) db = await probeModule({
+		candidates: parentDbCandidates(opts.schemaPath, opts.cwd),
+		cwd: opts.cwd,
+		graph: opts.graph,
+		load,
+		match: isDrizzleDb
+	});
 	return {
 		tables,
 		importPath,
@@ -1285,10 +1295,6 @@ function renderSource(role, entity, dbExpr) {
 	const opts = entity.idField === null ? `{ entity: "${entity.tableName}", cursorField: "${entity.cursorField}" }` : `{ entity: "${entity.tableName}", cursorField: "${entity.cursorField}", idField: "${entity.idField}" }`;
 	return `    ${role}: fromDrizzle(${dbExpr}, schema.${entity.moduleKey}, ${opts})`;
 }
-function fallbackDbImportPath(schemaImportPath) {
-	const slash = schemaImportPath.lastIndexOf("/");
-	return `${slash >= 0 ? schemaImportPath.slice(0, slash) : "."}/db`;
-}
 function dbIsInSchemaModule(plan) {
 	return plan.db !== null && plan.db.importPath === plan.importPath;
 }
@@ -1303,7 +1309,7 @@ function renderImports(plan) {
 		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
-	if (!plan.db) lines.push(`import { db } from "${fallbackDbImportPath(plan.importPath)}"; // TODO: point at your Drizzle instance`);
+	if (!plan.db) lines.push("import { db } from \"<YOUR_DB_MODULE>\"; // TODO(clivly): replace with the path to your Drizzle `db` instance — NOT your schema file");
 	else if (!dbIsInSchemaModule(plan)) lines.push(`import { ${plan.db.moduleKey} } from "${plan.db.importPath}";`);
 	return lines.join("\n");
 }
@@ -1332,6 +1338,8 @@ export default createClivlySDK({
   // all when you add a mapping — not just the ones wired up as sources below.
   schema: discoverFromDrizzle(schema),
   source: {
+    // Keyed by CRM concept — contacts/companies/deals/custom.
+    // NOT by your entity key. The entity's own \`source:\` above is a table name.
 ${sources.join(",\n")},
   },
   syncTrigger: {
@@ -2132,7 +2140,7 @@ const STATUS_STAGES = [
 			return Promise.resolve({
 				state: "warn",
 				detail: "Not set — remote sync cannot call back into this app.",
-				hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. Push-only setups can ignore this."
+				hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
 			});
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",
@@ -367,8 +367,8 @@
   "peerDependencies": {
     "@clerk/backend": ">=1",
     "@workos-inc/node": ">=7",
-    "better-auth": ">=1",
-    "drizzle-orm": ">=0.30",
+    "better-auth": ">=1.6.22",
+    "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {

package/{sdk-C_1sGiH8.mjs → sdk-C6WANW8M.mjs}

@@ -1,4 +1,83 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-D-5k3n0i.mjs";
+//#region ../sdk/src/entity-source.ts
+const CONCEPT_KEYS = {
+	contact: "contacts",
+	company: "companies",
+	deal: "deals"
+};
+function resolveEntitySource(config, entityKey) {
+	const entity = config.entities?.entities?.[entityKey];
+	const src = config.source;
+	if (!(entity && src)) return null;
+	const conceptKey = CONCEPT_KEYS[entity.concept];
+	if (conceptKey) {
+		const source = src[conceptKey];
+		return source ? {
+			concept: entity.concept,
+			expectedKey: conceptKey,
+			source
+		} : null;
+	}
+	if (entity.concept === "custom") {
+		const match = (src.custom ?? []).find((c) => c.entity === entity.source || c.entity === entityKey);
+		return match ? {
+			concept: "custom",
+			expectedKey: "custom",
+			source: match
+		} : null;
+	}
+	return null;
+}
+/** The `config.source` key an entity's concept requires, present or not. */
+function expectedSourceKey(concept) {
+	return CONCEPT_KEYS[concept] ?? "custom";
+}
+//#endregion
+//#region ../sdk/src/concept-coverage.ts
+const CHECK_NAME = "Entity → source coverage";
+function configuredKeys(config) {
+	const src = config.source;
+	if (!src) return [];
+	return Object.entries(src).filter(([, value]) => Array.isArray(value) ? value.length > 0 : Boolean(value)).map(([key]) => key);
+}
+/**
+* Every configured entity must resolve to a source, or it silently syncs
+* nothing. This is the check that catches `source` keyed by entity name rather
+* than by CRM concept — a mistake that otherwise shows up only as a run that
+* succeeds with zero rows.
+*/
+function checkConceptCoverage(config) {
+	const entities = config.entities?.entities ?? {};
+	const keys = Object.keys(entities);
+	if (keys.length === 0) return {
+		name: CHECK_NAME,
+		ok: false,
+		skipped: true,
+		detail: "No entities configured — nothing to cross-check."
+	};
+	const unresolved = keys.filter((key) => resolveEntitySource(config, key) === null);
+	if (unresolved.length === 0) return {
+		name: CHECK_NAME,
+		ok: true,
+		detail: `${keys.length} entit${keys.length === 1 ? "y" : "ies"} resolve to a configured source.`
+	};
+	const available = configuredKeys(config);
+	const listed = available.length > 0 ? available.join(", ") : "(none)";
+	const problems = unresolved.map((key) => {
+		const concept = entities[key]?.concept ?? "unknown";
+		if (concept === "custom") {
+			const custom = config.source?.custom ?? [];
+			if (custom.length > 0) return `"${key}" has concept "custom" but no entry in \`source.custom\` matches it — it will never sync. Entities configured in \`source.custom\`: ${custom.map((c) => c.entity).join(", ")}.`;
+		}
+		return `"${key}" has concept "${concept}" but no \`source.${expectedSourceKey(concept)}\` is configured — it will never sync.`;
+	});
+	return {
+		name: CHECK_NAME,
+		ok: false,
+		detail: `${problems.join(" ")} Configured source keys: ${listed}. \`source\` is keyed by CRM concept, not by entity key.`
+	};
+}
+//#endregion
 //#region ../sdk/src/custom-slug.ts
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
@@ -79,6 +158,56 @@ function describeFetchError(entity, error) {
 	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
 }
 //#endregion
+//#region ../sdk/src/mapping-dry-run.ts
+/**
+* Fetch one real row and push it through the entity's field map.
+*
+* The distinction from "Sample fetch": that proves the query runs, this proves
+* the row that comes back actually carries the columns `fields` names. A
+* mapping that points at a column the row lacks produces empty CRM records
+* rather than an error, so it has to be caught here.
+*
+* An empty table SKIPS rather than fails — a fresh database is not a
+* misconfiguration, and failing on it would train people to ignore the check.
+*/
+async function runMappingDryRun(config, entityKey) {
+	const name = `Field mapping dry run (${entityKey})`;
+	const resolved = resolveEntitySource(config, entityKey);
+	if (!resolved) return {
+		name,
+		ok: false,
+		skipped: true,
+		detail: `"${entityKey}" resolves to no source — see the coverage check above.`
+	};
+	const fields = config.entities?.entities?.[entityKey]?.fields ?? {};
+	let rows;
+	try {
+		rows = await resolved.source.fetchPage({
+			since: null,
+			limit: 1
+		});
+	} catch (error) {
+		return {
+			name,
+			ok: false,
+			detail: describeFetchError(entityKey, error)
+		};
+	}
+	const row = rows[0];
+	if (row === void 0) return {
+		name,
+		ok: false,
+		skipped: true,
+		detail: `"${resolved.source.entity}" is empty — nothing to map yet.`
+	};
+	const missing = Object.entries(fields).filter(([, column]) => !(column in row)).map(([field, column]) => `${field} → ${column}`);
+	return {
+		name,
+		ok: missing.length === 0,
+		detail: missing.length === 0 ? `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.` : `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
+	};
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -169,6 +298,11 @@ async function namespaceCheck(config) {
 		detail: probeResult.reachable ? "All required source tables are reachable." : probeResult.error?.message ?? "namespace unreachable"
 	};
 }
+async function mappingDryRunChecks(config) {
+	const checks = [];
+	for (const entityKey of Object.keys(config.entities?.entities ?? {})) checks.push(await runMappingDryRun(config, entityKey));
+	return checks;
+}
 /**
 * Run the read-only setup checks and return a structured report. Every check
 * captures its own error into `detail` rather than throwing, so one failure never
@@ -195,6 +329,7 @@ async function runDoctor(args) {
 		ok: sources.length > 0,
 		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
 	});
+	checks.push(checkConceptCoverage(config));
 	for (const source of sources) {
 		const meta = source[DRIZZLE_META];
 		if (!meta) {
@@ -233,6 +368,7 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	checks.push(...await mappingDryRunChecks(config));
 	const result = await connect();
 	checks.push({
 		name: "Heartbeat",
@@ -276,6 +412,7 @@ async function syncSource(args) {
 	const idField = source.idField ?? DEFAULT_ID_FIELD;
 	let cursor = since;
 	let pushed = 0;
+	const resumedFrom = since === null ? null : since.time.toISOString();
 	for (;;) {
 		const rows = await source.fetchPage({
 			since: cursor,
@@ -287,6 +424,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -329,6 +468,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -708,31 +849,25 @@ function createFetcher(retry) {
 		}
 	};
 }
+const CONCEPT_PATHS = {
+	contacts: SYNC_CONTACTS_PATH,
+	companies: SYNC_COMPANIES_PATH,
+	deals: SYNC_DEALS_PATH,
+	custom: SYNC_CUSTOM_PATH
+};
 function resolveSampleSource(config, entityKey) {
-	const entity = config.entities?.entities?.[entityKey];
-	const src = config.source;
-	if (!(entity && src)) return null;
-	if (entity.concept === "contact" && src.contacts) return {
-		source: src.contacts,
-		path: SYNC_CONTACTS_PATH
-	};
-	if (entity.concept === "company" && src.companies) return {
-		source: src.companies,
-		path: SYNC_COMPANIES_PATH
-	};
-	if (entity.concept === "deal" && src.deals) return {
-		source: src.deals,
-		path: SYNC_DEALS_PATH
+	const resolved = resolveEntitySource(config, entityKey);
+	if (!resolved) return null;
+	const path = CONCEPT_PATHS[resolved.expectedKey];
+	if (!path) return null;
+	return resolved.expectedKey === "custom" ? {
+		source: resolved.source,
+		path,
+		objectType: resolved.source.objectType
+	} : {
+		source: resolved.source,
+		path
 	};
-	if (entity.concept === "custom") {
-		const custom = (src.custom ?? []).find((c) => c.entity === entity.source || c.entity === entityKey);
-		return custom ? {
-			source: custom,
-			path: SYNC_CUSTOM_PATH,
-			objectType: custom.objectType
-		} : null;
-	}
-	return null;
 }
 const PREVIEW_LIMIT = 5;
 function resolvePreviewSource(config, sourceTable) {

package/{sdk-CzOf596t.cjs → sdk-iqOXeWIp.cjs}

@@ -1,4 +1,83 @@
 const require_drizzle_meta = require("./drizzle-meta-Bb1JWYqf.cjs");
+//#region ../sdk/src/entity-source.ts
+const CONCEPT_KEYS = {
+	contact: "contacts",
+	company: "companies",
+	deal: "deals"
+};
+function resolveEntitySource(config, entityKey) {
+	const entity = config.entities?.entities?.[entityKey];
+	const src = config.source;
+	if (!(entity && src)) return null;
+	const conceptKey = CONCEPT_KEYS[entity.concept];
+	if (conceptKey) {
+		const source = src[conceptKey];
+		return source ? {
+			concept: entity.concept,
+			expectedKey: conceptKey,
+			source
+		} : null;
+	}
+	if (entity.concept === "custom") {
+		const match = (src.custom ?? []).find((c) => c.entity === entity.source || c.entity === entityKey);
+		return match ? {
+			concept: "custom",
+			expectedKey: "custom",
+			source: match
+		} : null;
+	}
+	return null;
+}
+/** The `config.source` key an entity's concept requires, present or not. */
+function expectedSourceKey(concept) {
+	return CONCEPT_KEYS[concept] ?? "custom";
+}
+//#endregion
+//#region ../sdk/src/concept-coverage.ts
+const CHECK_NAME = "Entity → source coverage";
+function configuredKeys(config) {
+	const src = config.source;
+	if (!src) return [];
+	return Object.entries(src).filter(([, value]) => Array.isArray(value) ? value.length > 0 : Boolean(value)).map(([key]) => key);
+}
+/**
+* Every configured entity must resolve to a source, or it silently syncs
+* nothing. This is the check that catches `source` keyed by entity name rather
+* than by CRM concept — a mistake that otherwise shows up only as a run that
+* succeeds with zero rows.
+*/
+function checkConceptCoverage(config) {
+	const entities = config.entities?.entities ?? {};
+	const keys = Object.keys(entities);
+	if (keys.length === 0) return {
+		name: CHECK_NAME,
+		ok: false,
+		skipped: true,
+		detail: "No entities configured — nothing to cross-check."
+	};
+	const unresolved = keys.filter((key) => resolveEntitySource(config, key) === null);
+	if (unresolved.length === 0) return {
+		name: CHECK_NAME,
+		ok: true,
+		detail: `${keys.length} entit${keys.length === 1 ? "y" : "ies"} resolve to a configured source.`
+	};
+	const available = configuredKeys(config);
+	const listed = available.length > 0 ? available.join(", ") : "(none)";
+	const problems = unresolved.map((key) => {
+		const concept = entities[key]?.concept ?? "unknown";
+		if (concept === "custom") {
+			const custom = config.source?.custom ?? [];
+			if (custom.length > 0) return `"${key}" has concept "custom" but no entry in \`source.custom\` matches it — it will never sync. Entities configured in \`source.custom\`: ${custom.map((c) => c.entity).join(", ")}.`;
+		}
+		return `"${key}" has concept "${concept}" but no \`source.${expectedSourceKey(concept)}\` is configured — it will never sync.`;
+	});
+	return {
+		name: CHECK_NAME,
+		ok: false,
+		detail: `${problems.join(" ")} Configured source keys: ${listed}. \`source\` is keyed by CRM concept, not by entity key.`
+	};
+}
+//#endregion
 //#region ../sdk/src/custom-slug.ts
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
@@ -79,6 +158,56 @@ function describeFetchError(entity, error) {
 	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
 }
 //#endregion
+//#region ../sdk/src/mapping-dry-run.ts
+/**
+* Fetch one real row and push it through the entity's field map.
+*
+* The distinction from "Sample fetch": that proves the query runs, this proves
+* the row that comes back actually carries the columns `fields` names. A
+* mapping that points at a column the row lacks produces empty CRM records
+* rather than an error, so it has to be caught here.
+*
+* An empty table SKIPS rather than fails — a fresh database is not a
+* misconfiguration, and failing on it would train people to ignore the check.
+*/
+async function runMappingDryRun(config, entityKey) {
+	const name = `Field mapping dry run (${entityKey})`;
+	const resolved = resolveEntitySource(config, entityKey);
+	if (!resolved) return {
+		name,
+		ok: false,
+		skipped: true,
+		detail: `"${entityKey}" resolves to no source — see the coverage check above.`
+	};
+	const fields = config.entities?.entities?.[entityKey]?.fields ?? {};
+	let rows;
+	try {
+		rows = await resolved.source.fetchPage({
+			since: null,
+			limit: 1
+		});
+	} catch (error) {
+		return {
+			name,
+			ok: false,
+			detail: describeFetchError(entityKey, error)
+		};
+	}
+	const row = rows[0];
+	if (row === void 0) return {
+		name,
+		ok: false,
+		skipped: true,
+		detail: `"${resolved.source.entity}" is empty — nothing to map yet.`
+	};
+	const missing = Object.entries(fields).filter(([, column]) => !(column in row)).map(([field, column]) => `${field} → ${column}`);
+	return {
+		name,
+		ok: missing.length === 0,
+		detail: missing.length === 0 ? `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.` : `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
+	};
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -169,6 +298,11 @@ async function namespaceCheck(config) {
 		detail: probeResult.reachable ? "All required source tables are reachable." : probeResult.error?.message ?? "namespace unreachable"
 	};
 }
+async function mappingDryRunChecks(config) {
+	const checks = [];
+	for (const entityKey of Object.keys(config.entities?.entities ?? {})) checks.push(await runMappingDryRun(config, entityKey));
+	return checks;
+}
 /**
 * Run the read-only setup checks and return a structured report. Every check
 * captures its own error into `detail` rather than throwing, so one failure never
@@ -195,6 +329,7 @@ async function runDoctor(args) {
 		ok: sources.length > 0,
 		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
 	});
+	checks.push(checkConceptCoverage(config));
 	for (const source of sources) {
 		const meta = source[require_drizzle_meta.DRIZZLE_META];
 		if (!meta) {
@@ -233,6 +368,7 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	checks.push(...await mappingDryRunChecks(config));
 	const result = await connect();
 	checks.push({
 		name: "Heartbeat",
@@ -276,6 +412,7 @@ async function syncSource(args) {
 	const idField = source.idField ?? DEFAULT_ID_FIELD;
 	let cursor = since;
 	let pushed = 0;
+	const resumedFrom = since === null ? null : since.time.toISOString();
 	for (;;) {
 		const rows = await source.fetchPage({
 			since: cursor,
@@ -287,6 +424,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -329,6 +468,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -708,31 +849,25 @@ function createFetcher(retry) {
 		}
 	};
 }
+const CONCEPT_PATHS = {
+	contacts: SYNC_CONTACTS_PATH,
+	companies: SYNC_COMPANIES_PATH,
+	deals: SYNC_DEALS_PATH,
+	custom: SYNC_CUSTOM_PATH
+};
 function resolveSampleSource(config, entityKey) {
-	const entity = config.entities?.entities?.[entityKey];
-	const src = config.source;
-	if (!(entity && src)) return null;
-	if (entity.concept === "contact" && src.contacts) return {
-		source: src.contacts,
-		path: SYNC_CONTACTS_PATH
-	};
-	if (entity.concept === "company" && src.companies) return {
-		source: src.companies,
-		path: SYNC_COMPANIES_PATH
-	};
-	if (entity.concept === "deal" && src.deals) return {
-		source: src.deals,
-		path: SYNC_DEALS_PATH
+	const resolved = resolveEntitySource(config, entityKey);
+	if (!resolved) return null;
+	const path = CONCEPT_PATHS[resolved.expectedKey];
+	if (!path) return null;
+	return resolved.expectedKey === "custom" ? {
+		source: resolved.source,
+		path,
+		objectType: resolved.source.objectType
+	} : {
+		source: resolved.source,
+		path
 	};
-	if (entity.concept === "custom") {
-		const custom = (src.custom ?? []).find((c) => c.entity === entity.source || c.entity === entityKey);
-		return custom ? {
-			source: custom,
-			path: SYNC_CUSTOM_PATH,
-			objectType: custom.objectType
-		} : null;
-	}
-	return null;
 }
 const PREVIEW_LIMIT = 5;
 function resolvePreviewSource(config, sourceTable) {

package/sdk.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-D87rV-tE.cjs");
-const require_sdk = require("./sdk-CzOf596t.cjs");
+const require_sdk = require("./sdk-iqOXeWIp.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.mjs

@@ -1,3 +1,3 @@
 import { o as defineClivlyConfig } from "./entity-config-va2bkH5o.mjs";
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-C_1sGiH8.mjs";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-C6WANW8M.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, defineClivlyConfig };