@clivly/sdk 0.8.0 → 0.9.0

package/dist/drizzle.cjs

@@ -1,43 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_drizzle_meta = require("./drizzle-meta-CdCs30q3.cjs");
-let drizzle_orm = require("drizzle-orm");
-let drizzle_orm_pg_core = require("drizzle-orm/pg-core");
 let _clivly_core_drizzle = require("@clivly/core/drizzle");
+let drizzle_orm = require("drizzle-orm");
 //#region src/drizzle.ts
-function buildColumnsMeta(table) {
-	const columns = (0, drizzle_orm.getTableColumns)(table);
-	const fkByColumn = /* @__PURE__ */ new Map();
-	try {
-		for (const fk of (0, drizzle_orm_pg_core.getTableConfig)(table).foreignKeys) {
-			const ref = fk.reference();
-			const foreignTable = (0, drizzle_orm.getTableName)(ref.foreignTable);
-			ref.columns.forEach((col, i) => {
-				const foreignCol = ref.foreignColumns[i];
-				if (foreignCol) fkByColumn.set(col.name, {
-					table: foreignTable,
-					column: foreignCol.name
-				});
-			});
-		}
-	} catch {}
-	return Object.values(columns).map((col) => {
-		const references = fkByColumn.get(col.name);
-		let type;
-		try {
-			type = col.getSQLType();
-		} catch {
-			type = void 0;
-		}
-		return {
-			name: col.name,
-			type,
-			nullable: !col.notNull,
-			isPrimaryKey: Boolean(col.primary),
-			isForeignKey: references !== void 0,
-			...references ? { references } : {}
-		};
-	});
-}
 function inferIdField(table) {
 	const columns = (0, drizzle_orm.getTableColumns)(table);
 	const primaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
@@ -65,18 +30,24 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
 	};
+	const uniqueConstraints = (0, _clivly_core_drizzle.buildUniqueConstraints)(table);
 	const meta = {
 		columnKeys: Object.keys(columns),
 		cursorField: opts.cursorField,
 		idField,
 		tableName: (0, drizzle_orm.getTableName)(table),
-		columnsMeta: buildColumnsMeta(table)
+		columnsMeta: (0, _clivly_core_drizzle.buildColumnsMeta)(table),
+		...uniqueConstraints === void 0 ? {} : { uniqueConstraints }
 	};
 	Object.defineProperty(source, require_drizzle_meta.DRIZZLE_META, {
 		value: meta,
@@ -104,6 +75,12 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
+Object.defineProperty(exports, "buildUniqueConstraints", {
+	enumerable: true,
+	get: function() {
+		return _clivly_core_drizzle.buildUniqueConstraints;
+	}
+});
 Object.defineProperty(exports, "discoverFromDrizzle", {
 	enumerable: true,
 	get: function() {

package/dist/drizzle.d.cts

@@ -1,6 +1,6 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.cjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-QPbki8ur.cjs";
 import { Table } from "drizzle-orm";
-import { discoverFromDrizzle } from "@clivly/core/drizzle";
+import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 //#region src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
@@ -25,4 +25,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/drizzle.d.mts

@@ -1,6 +1,6 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.mjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-QPbki8ur.mjs";
+import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
-import { discoverFromDrizzle } from "@clivly/core/drizzle";
 //#region src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
@@ -25,4 +25,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/drizzle.mjs

@@ -1,42 +1,7 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
+import { buildColumnsMeta, buildUniqueConstraints, buildUniqueConstraints as buildUniqueConstraints$1, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
-import { getTableConfig } from "drizzle-orm/pg-core";
-import { discoverFromDrizzle } from "@clivly/core/drizzle";
 //#region src/drizzle.ts
-function buildColumnsMeta(table) {
-	const columns = getTableColumns(table);
-	const fkByColumn = /* @__PURE__ */ new Map();
-	try {
-		for (const fk of getTableConfig(table).foreignKeys) {
-			const ref = fk.reference();
-			const foreignTable = getTableName(ref.foreignTable);
-			ref.columns.forEach((col, i) => {
-				const foreignCol = ref.foreignColumns[i];
-				if (foreignCol) fkByColumn.set(col.name, {
-					table: foreignTable,
-					column: foreignCol.name
-				});
-			});
-		}
-	} catch {}
-	return Object.values(columns).map((col) => {
-		const references = fkByColumn.get(col.name);
-		let type;
-		try {
-			type = col.getSQLType();
-		} catch {
-			type = void 0;
-		}
-		return {
-			name: col.name,
-			type,
-			nullable: !col.notNull,
-			isPrimaryKey: Boolean(col.primary),
-			isForeignKey: references !== void 0,
-			...references ? { references } : {}
-		};
-	});
-}
 function inferIdField(table) {
 	const columns = getTableColumns(table);
 	const primaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
@@ -64,18 +29,24 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${getTableName(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${getTableName(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
 	};
+	const uniqueConstraints = buildUniqueConstraints$1(table);
 	const meta = {
 		columnKeys: Object.keys(columns),
 		cursorField: opts.cursorField,
 		idField,
 		tableName: getTableName(table),
-		columnsMeta: buildColumnsMeta(table)
+		columnsMeta: buildColumnsMeta(table),
+		...uniqueConstraints === void 0 ? {} : { uniqueConstraints }
 	};
 	Object.defineProperty(source, DRIZZLE_META, {
 		value: meta,
@@ -103,4 +74,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/index.cjs

@@ -279,6 +279,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region src/doctor.ts
+const TEMPORAL_CURSOR_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"datetime",
+	"date",
+	"time"
+];
+/**
+* Warn when the sync cursor cannot observe an update.
+*
+* `clivly init` falls back to the primary key when a table has no
+* `updated_at`-like column, and emits a TODO saying "confirm it is monotonic".
+* A serial `id` *is* monotonic, so the note reads as satisfied — but monotonic
+* is only half the requirement. An `id` never changes, so every insert mirrors
+* and **no edit ever does**: a contact who changes their email keeps the old one
+* in the CRM forever, with nothing anywhere reporting a problem.
+*
+* A code comment could not enforce this; a real integrator shipped exactly this
+* configuration to production. This is the check that says so out loud.
+*/
+function cursorMonotonicityCheck(source) {
+	const meta = source[require_drizzle_meta.DRIZZLE_META];
+	if (!meta?.columnsMeta) return null;
+	const index = meta.columnKeys.indexOf(meta.cursorField);
+	const type = meta.columnsMeta[index]?.type?.toLowerCase();
+	if (!type) return null;
+	const temporal = TEMPORAL_CURSOR_TYPES.some((t) => type.startsWith(t));
+	const name = `Cursor tracks updates (${source.entity})`;
+	if (temporal) return {
+		name,
+		ok: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}) — edits re-sync.`
+	};
+	return {
+		name,
+		ok: true,
+		warn: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}), which does not change when a row is edited — inserts will sync, edits will not. Add an updated_at column to "${meta.tableName ?? source.entity}" and set it as the cursor, or accept insert-only mirroring.`
+	};
+}
 function configuredSources(config) {
 	const sources = [];
 	if (config.source?.contacts) sources.push(config.source.contacts);
@@ -307,32 +347,12 @@ async function mappingDryRunChecks(config) {
 	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
-* hides the rest. `ok` is the AND of all non-skipped checks.
+* Confirm each drizzle source actually has the cursor and id columns the sync
+* pages on. Hand-written sources have no column metadata, so they are skipped
+* rather than failed.
 */
-async function runDoctor(args) {
-	const { config, connect } = args;
+function cursorColumnChecks(sources) {
 	const checks = [];
-	const sources = configuredSources(config);
-	const hasKey = Boolean(config.apiKey);
-	checks.push({
-		name: "API key present",
-		ok: hasKey,
-		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
-	});
-	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
-	checks.push({
-		name: "Entities configured",
-		ok: entityCount > 0,
-		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
-	});
-	checks.push({
-		name: "Sources configured",
-		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) {
@@ -344,7 +364,7 @@ async function runDoctor(args) {
 			});
 			continue;
 		}
-		const idField = source.idField ?? "id";
+		const idField = meta.idField ?? source.idField ?? "id";
 		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
 		checks.push({
 			name: `Cursor/id columns exist (${source.entity})`,
@@ -352,6 +372,14 @@ async function runDoctor(args) {
 			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
 		});
 	}
+	return checks;
+}
+/**
+* Read one row from each source to prove the query works and that rows actually
+* carry the cursor key. Fetch errors are captured as failures, never thrown.
+*/
+async function sampleFetchChecks(sources) {
+	const checks = [];
 	for (const source of sources) try {
 		const rows = await source.fetchPage({
 			since: null,
@@ -371,10 +399,45 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	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
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, probe } = args;
+	const checks = [];
+	const sources = configuredSources(config);
+	const hasKey = Boolean(config.apiKey);
+	checks.push({
+		name: "API key present",
+		ok: hasKey,
+		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
+	});
+	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
+	checks.push({
+		name: "Entities configured",
+		ok: entityCount > 0,
+		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
+	});
+	checks.push({
+		name: "Sources configured",
+		ok: sources.length > 0,
+		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+	});
+	checks.push(checkConceptCoverage(config));
+	checks.push(...cursorColumnChecks(sources));
+	for (const source of sources) {
+		const check = cursorMonotonicityCheck(source);
+		if (check) checks.push(check);
+	}
+	checks.push(...await sampleFetchChecks(sources));
 	checks.push(...await mappingDryRunChecks(config));
-	const result = await connect();
+	const result = await probe();
 	checks.push({
-		name: "Heartbeat",
+		name: "Clivly reachable",
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
@@ -724,6 +787,7 @@ const UNAUTHORIZED_STATUS = 401;
 const FORBIDDEN_STATUS = 403;
 const CLIENT_ERROR_FLOOR = 400;
 const SERVICE_UNAVAILABLE_STATUS = 503;
+const NOT_FOUND_STATUS = 404;
 function connectReason(status) {
 	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
 	if (status === FORBIDDEN_STATUS) return "forbidden";
@@ -732,6 +796,10 @@ function connectReason(status) {
 	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
 	return "server_error";
 }
+function pingReason(status) {
+	if (status === NOT_FOUND_STATUS) return "server_too_old";
+	return connectReason(status);
+}
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
@@ -963,9 +1031,38 @@ function createClivlySDK(config) {
 			retryable: isRetryableStatus(response.status)
 		};
 	};
+	const ping = async () => {
+		const response = await fetcher(`${apiUrl}/clivly/sdk/ping`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${config.apiKey}` }
+		});
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) {
+			const body = await response.json().catch(() => ({}));
+			return {
+				ok: true,
+				status: response.status,
+				reason: "ok",
+				retryable: false,
+				org: body?.org,
+				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
+			};
+		}
+		return {
+			ok: false,
+			status: response.status,
+			reason: pingReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
 	const doctor = () => runDoctor({
 		config,
-		connect
+		probe: ping
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
@@ -1058,6 +1155,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DTaz5mLi.cjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-QPbki8ur.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DTaz5mLi.mjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-QPbki8ur.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -278,6 +278,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region src/doctor.ts
+const TEMPORAL_CURSOR_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"datetime",
+	"date",
+	"time"
+];
+/**
+* Warn when the sync cursor cannot observe an update.
+*
+* `clivly init` falls back to the primary key when a table has no
+* `updated_at`-like column, and emits a TODO saying "confirm it is monotonic".
+* A serial `id` *is* monotonic, so the note reads as satisfied — but monotonic
+* is only half the requirement. An `id` never changes, so every insert mirrors
+* and **no edit ever does**: a contact who changes their email keeps the old one
+* in the CRM forever, with nothing anywhere reporting a problem.
+*
+* A code comment could not enforce this; a real integrator shipped exactly this
+* configuration to production. This is the check that says so out loud.
+*/
+function cursorMonotonicityCheck(source) {
+	const meta = source[DRIZZLE_META];
+	if (!meta?.columnsMeta) return null;
+	const index = meta.columnKeys.indexOf(meta.cursorField);
+	const type = meta.columnsMeta[index]?.type?.toLowerCase();
+	if (!type) return null;
+	const temporal = TEMPORAL_CURSOR_TYPES.some((t) => type.startsWith(t));
+	const name = `Cursor tracks updates (${source.entity})`;
+	if (temporal) return {
+		name,
+		ok: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}) — edits re-sync.`
+	};
+	return {
+		name,
+		ok: true,
+		warn: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}), which does not change when a row is edited — inserts will sync, edits will not. Add an updated_at column to "${meta.tableName ?? source.entity}" and set it as the cursor, or accept insert-only mirroring.`
+	};
+}
 function configuredSources(config) {
 	const sources = [];
 	if (config.source?.contacts) sources.push(config.source.contacts);
@@ -306,32 +346,12 @@ async function mappingDryRunChecks(config) {
 	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
-* hides the rest. `ok` is the AND of all non-skipped checks.
+* Confirm each drizzle source actually has the cursor and id columns the sync
+* pages on. Hand-written sources have no column metadata, so they are skipped
+* rather than failed.
 */
-async function runDoctor(args) {
-	const { config, connect } = args;
+function cursorColumnChecks(sources) {
 	const checks = [];
-	const sources = configuredSources(config);
-	const hasKey = Boolean(config.apiKey);
-	checks.push({
-		name: "API key present",
-		ok: hasKey,
-		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
-	});
-	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
-	checks.push({
-		name: "Entities configured",
-		ok: entityCount > 0,
-		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
-	});
-	checks.push({
-		name: "Sources configured",
-		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) {
@@ -343,7 +363,7 @@ async function runDoctor(args) {
 			});
 			continue;
 		}
-		const idField = source.idField ?? "id";
+		const idField = meta.idField ?? source.idField ?? "id";
 		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
 		checks.push({
 			name: `Cursor/id columns exist (${source.entity})`,
@@ -351,6 +371,14 @@ async function runDoctor(args) {
 			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
 		});
 	}
+	return checks;
+}
+/**
+* Read one row from each source to prove the query works and that rows actually
+* carry the cursor key. Fetch errors are captured as failures, never thrown.
+*/
+async function sampleFetchChecks(sources) {
+	const checks = [];
 	for (const source of sources) try {
 		const rows = await source.fetchPage({
 			since: null,
@@ -370,10 +398,45 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	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
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, probe } = args;
+	const checks = [];
+	const sources = configuredSources(config);
+	const hasKey = Boolean(config.apiKey);
+	checks.push({
+		name: "API key present",
+		ok: hasKey,
+		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
+	});
+	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
+	checks.push({
+		name: "Entities configured",
+		ok: entityCount > 0,
+		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
+	});
+	checks.push({
+		name: "Sources configured",
+		ok: sources.length > 0,
+		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+	});
+	checks.push(checkConceptCoverage(config));
+	checks.push(...cursorColumnChecks(sources));
+	for (const source of sources) {
+		const check = cursorMonotonicityCheck(source);
+		if (check) checks.push(check);
+	}
+	checks.push(...await sampleFetchChecks(sources));
 	checks.push(...await mappingDryRunChecks(config));
-	const result = await connect();
+	const result = await probe();
 	checks.push({
-		name: "Heartbeat",
+		name: "Clivly reachable",
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
@@ -723,6 +786,7 @@ const UNAUTHORIZED_STATUS = 401;
 const FORBIDDEN_STATUS = 403;
 const CLIENT_ERROR_FLOOR = 400;
 const SERVICE_UNAVAILABLE_STATUS = 503;
+const NOT_FOUND_STATUS = 404;
 function connectReason(status) {
 	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
 	if (status === FORBIDDEN_STATUS) return "forbidden";
@@ -731,6 +795,10 @@ function connectReason(status) {
 	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
 	return "server_error";
 }
+function pingReason(status) {
+	if (status === NOT_FOUND_STATUS) return "server_too_old";
+	return connectReason(status);
+}
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
@@ -962,9 +1030,38 @@ function createClivlySDK(config) {
 			retryable: isRetryableStatus(response.status)
 		};
 	};
+	const ping = async () => {
+		const response = await fetcher(`${apiUrl}/clivly/sdk/ping`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${config.apiKey}` }
+		});
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) {
+			const body = await response.json().catch(() => ({}));
+			return {
+				ok: true,
+				status: response.status,
+				reason: "ok",
+				retryable: false,
+				org: body?.org,
+				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
+			};
+		}
+		return {
+			ok: false,
+			status: response.status,
+			reason: pingReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
 	const doctor = () => runDoctor({
 		config,
-		connect
+		probe: ping
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
@@ -1057,6 +1154,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,