@clivly/sdk 0.7.0 → 0.7.2

package/README.md

@@ -1,36 +1,66 @@
 # @clivly/sdk
 
-Connect your app to Clivly Cloud. The SDK sends a heartbeat, reports your schema
-for entity mapping, and mirrors your contacts and companies into Clivly over
-outbound HTTPS. If you configure `syncTrigger`, Clivly can also call back into
-your app to start a sync from the dashboard.
+Connect an app to Clivly Cloud. The SDK sends heartbeats, reports schema
+discovery data, syncs source rows to Clivly over outbound HTTPS, and can expose
+a signed trigger route so Clivly can start a sync from the dashboard.
 
-For the end-to-end onboarding flow, start with
-[`docs/guides/connecting-to-clivly-cloud.md`](../../docs/guides/connecting-to-clivly-cloud.md).
-This README stays focused on the SDK surface itself.
+## Which package should I install?
 
-## Install
+For most new integrations, install the consolidated public package:
 
 ```bash
 npm install clivly
 ```
 
-Clivly's stable packages publish on npm's `latest` tag. Use `@next` only when
-you are intentionally validating a prerelease build.
-
-Add `drizzle-orm` when you use `clivly/drizzle`, and
-`vite` when you use the Vite/TanStack Start plugin.
-
-## Usage
+and import from:
 
 ```ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
 import { fromDrizzle } from "clivly/drizzle";
+```
+
+`@clivly/sdk` remains a public package if you prefer a direct dependency on the
+SDK package itself:
+
+```bash
+npm install @clivly/sdk
+```
+
+with imports from:
+
+```ts
+import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
+import { fromDrizzle } from "@clivly/sdk/drizzle";
+```
+
+Stable releases publish on npm's `latest` tag. Use `@next` only when you are
+intentionally validating a prerelease build.
+
+Add `drizzle-orm` when you use the Drizzle helpers, and `vite` when you use the
+Vite/TanStack Start plugin.
+
+## Surface
+
+Public exports from this package:
+
+- `@clivly/sdk`:
+  `createClivlySDK`, `defineClivlyConfig`, `createChatSessionHandler`,
+  `ClivlyError`, `ClivlyNetworkError`, `ClivlyRateLimitError`,
+  `ClivlyAuthError`
+- `@clivly/sdk/drizzle`:
+  Drizzle source helpers such as `fromDrizzle`
+- `@clivly/sdk/vite`:
+  the Vite/TanStack Start lifecycle plugin
+- `@clivly/sdk/chat-session`:
+  chat-session handler helpers when you want that subpath explicitly
+
+## Basic usage
+
+```ts
+import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
+import { fromDrizzle } from "@clivly/sdk/drizzle";
 import { db, participants, accounts } from "./db";
 
-// Declarative entity config — the non-deprecated source of truth. It maps your
-// host tables/columns onto CRM concepts, and `defineClivlyConfig` validates it
-// at load (warning on any non-canonical field key that would mirror as empty).
 const entities = defineClivlyConfig({
   entities: {
     participants: {
@@ -47,62 +77,67 @@ const entities = defineClivlyConfig({
 });
 
 const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… from Settings → API keys
+  apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
   source: {
-    contacts: fromDrizzle(db, participants, { entity: "participants", cursorField: "updatedAt" }),
-    companies: fromDrizzle(db, accounts, { entity: "accounts", cursorField: "updatedAt" }),
+    contacts: fromDrizzle(db, participants, {
+      entity: "participants",
+      cursorField: "updatedAt",
+    }),
+    companies: fromDrizzle(db, accounts, {
+      entity: "accounts",
+      cursorField: "updatedAt",
+    }),
   },
   sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
 });
 
-const status = await clivly.connect(); // rich result: { ok, status, reason, retryable, org? }
-if (!status.ok) throw new Error(`Clivly: ${status.reason}`);
-await clivly.start();      // heartbeat + backfill + interval delta sync
+const status = await clivly.connect();
+if (!status.ok) {
+  throw new Error(`Clivly: ${status.reason}`);
+}
+
+await clivly.start();
+```
+
+`fromDrizzle` builds the keyset-paginated `fetchPage` function the SDK needs.
+`cursorField` and `idField` are Drizzle property keys such as `updatedAt`, not
+database column names such as `updated_at`. Non-Drizzle apps can provide their
+own `fetchPage` implementation.
 
-// Optional: let Clivly's dashboard start a sync in this app.
-const remote = createClivlySDK({
+## Remote sync trigger
+
+If you configure `syncTrigger`, Clivly can ask your app to run a sync from the
+dashboard:
+
+```ts
+const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
-  source: { /* … */ },
+  source: { /* ... */ },
   syncTrigger: {
     path: "/api/clivly/tick",
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
-    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
+    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
   },
 });
 
 export async function POST(request: Request) {
-  return remote.createClivlyHandler()(request);
+  return clivly.createClivlyHandler()(request);
 }
 ```
 
-`fromDrizzle` generates the keyset-paginated `fetchPage` the SDK needs, inferring the
-tie-breaker id from the table's primary key — pass `idField` to override.
-`cursorField` and `idField` are Drizzle property keys (`updatedAt`), not database
-column names (`updated_at`). Rows are keyed by your source column names; Clivly
-applies the field map you confirmed during onboarding, so re-mapping never needs
-a redeploy. Non-Drizzle hosts can still pass a hand-written `fetchPage` closure
-instead.
-
-With `syncTrigger.url` + `syncTrigger.secret` configured, the SDK reports the
-trigger URL on each heartbeat and rejects unsigned or badly-signed trigger
-requests. Without `syncTrigger`, cloud mode is push-only: Clivly can observe
-the app but cannot start a sync from the dashboard.
-
-If you rotate a remote-sync secret from Clivly's dashboard after the encryption
-rollout, Clivly stores it encrypted at rest. The server-side deployment must
-have `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` configured, while your app continues
-to use `CLIVLY_SYNC_TRIGGER_SECRET`. Existing plaintext rows remain valid during
-rollout, and older rows can be backfilled with
-`node ./scripts/backfill-sync-trigger-secrets.mjs --write`.
+With `syncTrigger.url` and `syncTrigger.secret` configured, the SDK reports the
+trigger URL on each heartbeat and rejects unsigned or badly-signed requests.
+Without `syncTrigger`, cloud mode is push-only: Clivly can observe the app but
+cannot start a sync from the dashboard.
 
 ## Vite / TanStack Start
 
-For long-lived Vite dev servers, wire the SDK lifecycle through the Vite plugin:
+For long-lived Vite dev servers, wire the SDK lifecycle through the plugin:
 
 ```ts
-import { clivlyVite } from "clivly/vite";
+import { clivlyVite } from "@clivly/sdk/vite";
 import clivly from "./clivly.config";
 import { defineConfig } from "vite";
 
@@ -111,115 +146,80 @@ export default defineConfig({
 });
 ```
 
-The plugin calls `connect()` for a clear startup status line, then `start()` for
-the heartbeat and sync loop. It is dev-server only; use `runScheduled()` or
-`createClivlyHandler()` for serverless production runtimes.
-
-> **Legacy:** the flat `contactEntity` / `contactFields` form is still accepted but
-> **deprecated** — prefer the `entities` config above, which is the same model the
-> mapping table and sync engine share.
+The plugin calls `connect()` for a startup status line, then `start()` for the
+heartbeat and sync loop. It is dev-server only; use `runScheduled()` or
+`createClivlyHandler()` for request-scoped runtimes.
 
 ## Verify your setup
 
-Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
+If your instance lives in `clivly.config.ts`, the CLI can validate the setup:
 
 ```bash
-npx clivly ping     # CLIVLY_API_KEY + API reachability
-npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
+npx clivly ping
+npx clivly doctor
 ```
 
-In a monorepo, pass the app config explicitly:
-
-```bash
-npx clivly doctor --config ./apps/web/clivly.config.ts
-```
-
-Or in code: `await clivly.doctor()` returns `{ ok, checks }` — the same six read-only checks.
+In code, `await clivly.doctor()` returns the same structured read-only checks.
 
 ## Serverless / edge
 
-On request-scoped runtimes (Cloudflare Workers, Vercel, Lambda) there is no long-lived
-process, so `start()`'s `setInterval` keep-alive loop can't persist — it stops ticking after
-the first response. **Don't call `start()` there.** Instead drive one-shot runs from a
-scheduled trigger with `runScheduled()`, or mount `createClivlyHandler()` at a route:
+On request-scoped runtimes such as Cloudflare Workers, Vercel, or Lambda, do
+not call `start()`. Use `runScheduled()` or mount `createClivlyHandler()`
+instead:
 
 ```ts
-// Cloudflare Workers
 export default {
-  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
-  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping / external scheduler
+  scheduled: () => clivly.runScheduled(),
+  fetch: clivly.createClivlyHandler(),
 };
 ```
 
-`runScheduled()` throws if a sync push fails (so a cron run is marked failed);
-`createClivlyHandler()` returns `200` when the triggered run finishes successfully,
-`500` otherwise. If the run carries a Clivly-issued run id, the SDK also reports
-the final outcome back to Clivly so the dashboard reflects `running` vs
-`succeeded` vs `failed` truthfully. `start()` emits a warning if it detects a
-serverless runtime. Verify a connection from the terminal any time with
-`npx clivly ping`.
+`runScheduled()` throws on a failed push so cron jobs surface failures.
+`createClivlyHandler()` returns `200` on success and `500` on a failed run.
 
 ### Persisting the delta cursor
 
-Delta sync tracks a per-entity cursor so each run only pages rows changed since the last one.
-By default that cursor lives in memory — fine for a long-lived process, but **lost on every
-serverless cold start**, so a fresh isolate would re-page the whole entity. Pass a
-`cursorStore` backed by your own KV/DB to persist it:
+By default the delta cursor lives in memory. For serverless runtimes, pass a
+persistent `cursorStore`:
 
 ```ts
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
-  source: { /* … */ },
+  source: { /* ... */ },
   cursorStore: {
-    // `SyncCursor` is { id: string; time: Date } — serialize `time` (e.g. ISO string).
     get: async (entity) => {
       const raw = await kv.get(`clivly:cursor:${entity}`);
       return raw ? { id: raw.id, time: new Date(raw.time) } : null;
     },
     set: (entity, cursor) =>
-      kv.put(`clivly:cursor:${entity}`, cursor && { id: cursor.id, time: cursor.time.toISOString() }),
+      kv.put(
+        `clivly:cursor:${entity}`,
+        cursor ? { id: cursor.id, time: cursor.time.toISOString() } : null
+      ),
   },
 });
 ```
 
-Delta sync is **at-least-once**: after a cold start with no persisted cursor, rows since the
-last push may be re-sent (the server dedupes by id) — it never silently skips rows. Use
-`sync({ mode: "full" })` when you need the server to reconcile deletions (archive-on-leave).
-
-## Many-to-many company membership
-
-If a mapping links contacts to companies through a join table
-(`via: { through: … }`), that entity's source must return **one row per
-membership**, each row carrying the join table's foreign-key column.
-
-```ts
-// Ada belongs to two organizations: two rows, differing only in org_id.
-{ id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "acme"   }
-{ id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "globex" }
-```
-
-This mirrors what the embedded model produces with `LEFT JOIN <join table>`, and
-it is what lets Clivly keep one CRM row per membership instead of collapsing the
-person onto whichever company happened to come first.
-
-A person with no membership may omit the column entirely or send it as `null` —
-both are accepted. But if **no** pushed row carries the column, the push is
-rejected with `400 invalid_config`: silently keeping one membership would be
-worse than failing, because the row counts look correct either way.
+Delta sync is at-least-once. Without a persisted cursor after a cold start,
+rows may be re-sent; they are not silently skipped.
 
 ## Known limitations
 
-- `start()` is for long-lived runtimes only. On serverless/edge, use
-  `runScheduled()` or `createClivlyHandler()`.
-- `fromDrizzle` is the first-class generated source path today. Non-Drizzle hosts
-  should provide a hand-written `fetchPage`.
-- The flat `contactEntity` / `contactFields` config still works but is deprecated
-  in favor of `defineClivlyConfig({ entities: ... })`.
+- `start()` is for long-lived runtimes only.
+- `fromDrizzle` is the first-class generated source path today.
+- The legacy flat `contactEntity` / `contactFields` config is still accepted but
+  deprecated in favor of `defineClivlyConfig({ entities: ... })`.
 
 ## More docs
 
-- Onboarding guide:
-  [`docs/guides/connecting-to-clivly-cloud.md`](../../docs/guides/connecting-to-clivly-cloud.md)
-- CLI docs: [`../cli/README.md`](../cli/README.md)
-- Release notes: [`../../CHANGELOG.md`](../../CHANGELOG.md)
+- Cloud onboarding guide:
+  [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
+- CLI reference:
+  [packages/cli/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/cli/README.md)
+- Release notes:
+  [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+
+## License
+
+MIT

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.7.2",
   "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.7.2"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.30",
+    "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {