@clivly/sdk 0.7.0 → 0.8.0

package/README.md

@@ -124,7 +124,7 @@ the heartbeat and sync loop. It is dev-server only; use `runScheduled()` or
 Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
 
 ```bash
-npx clivly ping     # CLIVLY_API_KEY + API reachability
+npx clivly ping     # CLIVLY_SECRET_KEY + API reachability
 npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
 ```
 

package/dist/index.cjs

@@ -2,6 +2,85 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_drizzle_meta = require("./drizzle-meta-CdCs30q3.cjs");
 const require_chat_session = require("./chat-session.cjs");
 let _clivly_core_entity_config = require("@clivly/core/entity-config");
+//#region 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 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 src/custom-slug.ts
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
@@ -82,6 +161,56 @@ function describeFetchError(entity, error) {
 	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
 }
 //#endregion
+//#region 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 src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -172,6 +301,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
@@ -198,6 +332,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) {
@@ -236,6 +371,7 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	checks.push(...await mappingDryRunChecks(config));
 	const result = await connect();
 	checks.push({
 		name: "Heartbeat",
@@ -279,6 +415,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,
@@ -290,6 +427,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -332,6 +471,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -622,31 +763,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/dist/index.mjs

@@ -1,6 +1,85 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { defineClivlyConfig } from "@clivly/core/entity-config";
+//#region 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 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 src/custom-slug.ts
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
@@ -81,6 +160,56 @@ function describeFetchError(entity, error) {
 	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
 }
 //#endregion
+//#region 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 src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -171,6 +300,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
@@ -197,6 +331,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) {
@@ -235,6 +370,7 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	checks.push(...await mappingDryRunChecks(config));
 	const result = await connect();
 	checks.push({
 		name: "Heartbeat",
@@ -278,6 +414,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,
@@ -289,6 +426,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -331,6 +470,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -621,31 +762,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -55,10 +55,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.7.0"
+    "@clivly/core": "0.8.0"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.30",
+    "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {