@clivly/sdk 0.4.0 → 0.7.1

package/README.md

@@ -18,15 +18,14 @@ 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` or `clivly/core/drizzle`, and
+Add `drizzle-orm` when you use `clivly/drizzle`, and
 `vite` when you use the Vite/TanStack Start plugin.
 
 ## Usage
 
 ```ts
-import { createClivlySDK } from "clivly/sdk";
+import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
 import { fromDrizzle } from "clivly/drizzle";
-import { defineClivlyConfig } from "clivly/core";
 import { db, participants, accounts } from "./db";
 
 // Declarative entity config — the non-deprecated source of truth. It maps your
@@ -48,7 +47,7 @@ const entities = defineClivlyConfig({
 });
 
 const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_API_KEY!, // sk_live_… from Settings → API keys
+  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… from Settings → API keys
   entities,
   source: {
     contacts: fromDrizzle(db, participants, { entity: "participants", cursorField: "updatedAt" }),
@@ -63,7 +62,7 @@ await clivly.start();      // heartbeat + backfill + interval delta sync
 
 // Optional: let Clivly's dashboard start a sync in this app.
 const remote = createClivlySDK({
-  apiKey: process.env.CLIVLY_API_KEY!,
+  apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
   source: { /* … */ },
   syncTrigger: {
@@ -71,7 +70,6 @@ const remote = createClivlySDK({
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
     secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
   },
-  verifyToken: process.env.CLIVLY_VERIFY_TOKEN,
 });
 
 export async function POST(request: Request) {
@@ -126,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
 ```
 
@@ -170,7 +168,7 @@ serverless cold start**, so a fresh isolate would re-page the whole entity. Pass
 
 ```ts
 const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_API_KEY!,
+  apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
   source: { /* … */ },
   cursorStore: {

package/dist/chat-session.cjs

@@ -36,7 +36,7 @@ function originAllowed(origin, allowedOrigins) {
 	if (!origin) return false;
 	return allowedOrigins.includes(origin);
 }
-function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch }) {
+function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
@@ -55,6 +55,12 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 			return jsonResponse({ error: "invalid_json" }, 400);
 		}
 		if (!isChatSessionRequestBody(body)) return jsonResponse({ error: "invalid_request" }, 400);
+		let hostUser = null;
+		if (resolveUser) try {
+			hostUser = await resolveUser(request);
+		} catch {
+			console.warn("[clivly] resolveUser threw; continuing without host identity");
+		}
 		try {
 			const upstream = await fetchImpl(sessionUrl, {
 				method: "POST",
@@ -67,7 +73,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 					widgetId: body.widgetId,
 					visitor: body.visitor,
 					visitorToken: body.visitorToken,
-					origin
+					origin,
+					...hostUser ? { hostUser } : {}
 				})
 			});
 			const responseBody = await upstream.text();

package/dist/chat-session.d.cts

@@ -1,11 +1,5 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-jMafEyTv.cjs";
-
+import { c as CreateChatSessionHandlerOptions } from "./types-DTaz5mLi.cjs";
 //#region src/chat-session.d.ts
-declare function createChatSessionHandler({
-  allowedOrigins,
-  apiKey,
-  apiUrl,
-  fetchImpl
-}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
 export { createChatSessionHandler };

package/dist/chat-session.d.mts

@@ -1,11 +1,5 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-B7wBCHRT.mjs";
-
+import { c as CreateChatSessionHandlerOptions } from "./types-DTaz5mLi.mjs";
 //#region src/chat-session.d.ts
-declare function createChatSessionHandler({
-  allowedOrigins,
-  apiKey,
-  apiUrl,
-  fetchImpl
-}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
 export { createChatSessionHandler };

package/dist/chat-session.mjs

@@ -35,7 +35,7 @@ function originAllowed(origin, allowedOrigins) {
 	if (!origin) return false;
 	return allowedOrigins.includes(origin);
 }
-function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch }) {
+function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
@@ -54,6 +54,12 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 			return jsonResponse({ error: "invalid_json" }, 400);
 		}
 		if (!isChatSessionRequestBody(body)) return jsonResponse({ error: "invalid_request" }, 400);
+		let hostUser = null;
+		if (resolveUser) try {
+			hostUser = await resolveUser(request);
+		} catch {
+			console.warn("[clivly] resolveUser threw; continuing without host identity");
+		}
 		try {
 			const upstream = await fetchImpl(sessionUrl, {
 				method: "POST",
@@ -66,7 +72,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 					widgetId: body.widgetId,
 					visitor: body.visitor,
 					visitorToken: body.visitorToken,
-					origin
+					origin,
+					...hostUser ? { hostUser } : {}
 				})
 			});
 			const responseBody = await upstream.text();

package/dist/drizzle.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_drizzle_meta = require("./drizzle-meta-iAu8w1hj.cjs");
+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");
 //#region src/drizzle.ts
 function buildColumnsMeta(table) {
 	const columns = (0, drizzle_orm.getTableColumns)(table);
@@ -103,5 +104,11 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
+Object.defineProperty(exports, "discoverFromDrizzle", {
+	enumerable: true,
+	get: function() {
+		return _clivly_core_drizzle.discoverFromDrizzle;
+	}
+});
 exports.drizzleIntrospector = drizzleIntrospector;
 exports.fromDrizzle = fromDrizzle;

package/dist/drizzle.d.cts

@@ -1,6 +1,6 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-jMafEyTv.cjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.cjs";
 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 { drizzleIntrospector, fromDrizzle };
+export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/drizzle.d.mts

@@ -1,6 +1,6 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-B7wBCHRT.mjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.mjs";
 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 { drizzleIntrospector, fromDrizzle };
+export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/drizzle.mjs

@@ -1,6 +1,7 @@
-import { t as DRIZZLE_META } from "./drizzle-meta-DMx_9nlj.mjs";
+import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
 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);
@@ -102,4 +103,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { drizzleIntrospector, fromDrizzle };
+export { discoverFromDrizzle, drizzleIntrospector, fromDrizzle };

package/dist/index.cjs

@@ -1,6 +1,86 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_drizzle_meta = require("./drizzle-meta-iAu8w1hj.cjs");
+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;
@@ -81,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:
@@ -171,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
@@ -197,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) {
@@ -235,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",
@@ -278,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,
@@ -289,6 +427,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -331,6 +471,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -395,9 +537,7 @@ function observedTriggerUrl(req) {
 	const proto = forwardedProto || requestUrl.protocol.replace(":", "");
 	try {
 		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
-	} catch {
-		return;
-	}
+	} catch {}
 }
 /**
 * Decide which trigger URL to report, in precedence order:
@@ -595,9 +735,7 @@ function connectReason(status) {
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
-	} catch {
-		return;
-	}
+	} catch {}
 }
 function retryAfterMs(res) {
 	const header = res.headers.get("retry-after");
@@ -620,35 +758,30 @@ function createFetcher(retry) {
 			}
 			if (!(res === null || isRetryableStatus(res.status)) || attempt >= maxAttempts) return res;
 			const backoff = baseDelayMs * 2 ** (attempt - 1) + Math.random() * baseDelayMs;
-			await sleep(res ? retryAfterMs(res) ?? backoff : backoff);
+			const wait = res ? retryAfterMs(res) ?? backoff : backoff;
+			await sleep(wait);
 		}
 	};
 }
+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
+	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 === "deal" && src.deals) return {
-		source: src.deals,
-		path: SYNC_DEALS_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) {
@@ -677,7 +810,7 @@ async function handlePreviewRequest(config, preview) {
 	if (!source) return jsonResponse({ error: `No configured source for table "${preview.sourceTable}"` }, 400);
 	const idField = source.idField ?? "id";
 	const filterColumns = preview.filter ? Object.keys(preview.filter).filter((k) => k !== "$raw") : [];
-	const needed = new Set([
+	const needed = /* @__PURE__ */ new Set([
 		idField,
 		...Object.values(preview.fieldMap),
 		...filterColumns
@@ -939,3 +1072,9 @@ exports.ClivlyNetworkError = ClivlyNetworkError;
 exports.ClivlyRateLimitError = ClivlyRateLimitError;
 exports.createChatSessionHandler = require_chat_session.createChatSessionHandler;
 exports.createClivlySDK = createClivlySDK;
+Object.defineProperty(exports, "defineClivlyConfig", {
+	enumerable: true,
+	get: function() {
+		return _clivly_core_entity_config.defineClivlyConfig;
+	}
+});

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-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-jMafEyTv.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-DTaz5mLi.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
-
+import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -31,4 +31,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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-B7wBCHRT.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-DTaz5mLi.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
-
+import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -31,4 +31,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/dist/index.mjs

@@ -1,5 +1,85 @@
-import { t as DRIZZLE_META } from "./drizzle-meta-DMx_9nlj.mjs";
+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;
@@ -80,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:
@@ -170,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
@@ -196,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) {
@@ -234,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",
@@ -277,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,
@@ -288,6 +426,8 @@ async function syncSource(args) {
 			source: source.entity,
 			rows: capped,
 			mode: "delta",
+			fetched: rows.length,
+			cursor: resumedFrom,
 			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
@@ -330,6 +470,8 @@ async function fullSyncSource(args) {
 		source: source.entity,
 		rows: all,
 		mode: "full",
+		fetched: all.length,
+		cursor: null,
 		...objectType ? { objectType } : {}
 	});
 	return {
@@ -394,9 +536,7 @@ function observedTriggerUrl(req) {
 	const proto = forwardedProto || requestUrl.protocol.replace(":", "");
 	try {
 		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
-	} catch {
-		return;
-	}
+	} catch {}
 }
 /**
 * Decide which trigger URL to report, in precedence order:
@@ -594,9 +734,7 @@ function connectReason(status) {
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
-	} catch {
-		return;
-	}
+	} catch {}
 }
 function retryAfterMs(res) {
 	const header = res.headers.get("retry-after");
@@ -619,35 +757,30 @@ function createFetcher(retry) {
 			}
 			if (!(res === null || isRetryableStatus(res.status)) || attempt >= maxAttempts) return res;
 			const backoff = baseDelayMs * 2 ** (attempt - 1) + Math.random() * baseDelayMs;
-			await sleep(res ? retryAfterMs(res) ?? backoff : backoff);
+			const wait = res ? retryAfterMs(res) ?? backoff : backoff;
+			await sleep(wait);
 		}
 	};
 }
+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) {
@@ -676,7 +809,7 @@ async function handlePreviewRequest(config, preview) {
 	if (!source) return jsonResponse({ error: `No configured source for table "${preview.sourceTable}"` }, 400);
 	const idField = source.idField ?? "id";
 	const filterColumns = preview.filter ? Object.keys(preview.filter).filter((k) => k !== "$raw") : [];
-	const needed = new Set([
+	const needed = /* @__PURE__ */ new Set([
 		idField,
 		...Object.values(preview.fieldMap),
 		...filterColumns
@@ -932,4 +1065,4 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK };
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/dist/{types-B7wBCHRT.d.mts → types-DTaz5mLi.d.cts}

@@ -1,5 +1,4 @@
 import { ClivlyEntitiesConfig } from "@clivly/core";
-
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -85,9 +84,12 @@ interface ClivlySDKConfig {
    * above is unambiguous; nothing here is part of the supported API.
    */
   experimental?: {
-    /** Cloudflare Tunnel token — reserved for tunnel mode. Not wired up yet. */tunnelToken?: string; /** CRM write-back target — reserved. Not wired up yet. */
+    /** Cloudflare Tunnel token — reserved for tunnel mode. Not wired up yet. */
+    tunnelToken?: string;
+    /** CRM write-back target — reserved. Not wired up yet. */
     writeBack?: {
-      enabled?: boolean; /** Only crm_* tables are ever accepted; this narrows further. */
+      enabled?: boolean;
+      /** Only crm_* tables are ever accepted; this narrows further. */
       tables?: string[];
     };
   };
@@ -116,7 +118,9 @@ interface ClivlySDKConfig {
    * responses (e.g. 4xx other than 429) are returned immediately, not retried.
    */
   retry?: {
-    /** Total attempts including the first. Defaults to 3. Min 1. */maxAttempts?: number; /** Base backoff in ms (doubled each attempt). Defaults to 500. */
+    /** Total attempts including the first. Defaults to 3. Min 1. */
+    maxAttempts?: number;
+    /** Base backoff in ms (doubled each attempt). Defaults to 500. */
     baseDelayMs?: number;
   };
   /** Tables/columns to report for entity discovery + mapping. */
@@ -126,7 +130,8 @@ interface ClivlySDKConfig {
   source?: {
     contacts: SyncSource;
     companies?: SyncSource;
-    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    deals?: SyncSource;
+    /** Org-defined custom objects to mirror. Each carries its object-type slug. */
     custom?: Array<SyncSource & {
       objectType: string;
     }>;
@@ -178,7 +183,9 @@ interface ClivlySDKConfig {
   /**
    * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
    * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
-   * authenticate the caller; without it the handler fails closed (HTTP 503).
+   * authenticate the caller; without it the handler fails closed (HTTP 503). No
+   * cloud consumer calls this endpoint yet — it is an inert primitive reserved for
+   * a future CRM/dashboard auth-passthrough.
    */
   verifyToken?: string;
 }
@@ -201,6 +208,13 @@ interface CreateChatSessionHandlerOptions {
   apiKey: string;
   apiUrl?: string;
   fetchImpl?: typeof fetch;
+  /**
+   * Optional host-auth hook. When provided, it runs on the incoming browser
+   * request (session cookies intact) and, on a non-null `ClivlyUser`, the host
+   * vouches for that verified identity to Clivly Cloud. Absent/null/throwing =
+   * the visitor stays self-reported. Never fails the session.
+   */
+  resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */

package/dist/{types-jMafEyTv.d.cts → types-DTaz5mLi.d.mts}

@@ -1,5 +1,4 @@
 import { ClivlyEntitiesConfig } from "@clivly/core";
-
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -85,9 +84,12 @@ interface ClivlySDKConfig {
    * above is unambiguous; nothing here is part of the supported API.
    */
   experimental?: {
-    /** Cloudflare Tunnel token — reserved for tunnel mode. Not wired up yet. */tunnelToken?: string; /** CRM write-back target — reserved. Not wired up yet. */
+    /** Cloudflare Tunnel token — reserved for tunnel mode. Not wired up yet. */
+    tunnelToken?: string;
+    /** CRM write-back target — reserved. Not wired up yet. */
     writeBack?: {
-      enabled?: boolean; /** Only crm_* tables are ever accepted; this narrows further. */
+      enabled?: boolean;
+      /** Only crm_* tables are ever accepted; this narrows further. */
       tables?: string[];
     };
   };
@@ -116,7 +118,9 @@ interface ClivlySDKConfig {
    * responses (e.g. 4xx other than 429) are returned immediately, not retried.
    */
   retry?: {
-    /** Total attempts including the first. Defaults to 3. Min 1. */maxAttempts?: number; /** Base backoff in ms (doubled each attempt). Defaults to 500. */
+    /** Total attempts including the first. Defaults to 3. Min 1. */
+    maxAttempts?: number;
+    /** Base backoff in ms (doubled each attempt). Defaults to 500. */
     baseDelayMs?: number;
   };
   /** Tables/columns to report for entity discovery + mapping. */
@@ -126,7 +130,8 @@ interface ClivlySDKConfig {
   source?: {
     contacts: SyncSource;
     companies?: SyncSource;
-    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    deals?: SyncSource;
+    /** Org-defined custom objects to mirror. Each carries its object-type slug. */
     custom?: Array<SyncSource & {
       objectType: string;
     }>;
@@ -178,7 +183,9 @@ interface ClivlySDKConfig {
   /**
    * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
    * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
-   * authenticate the caller; without it the handler fails closed (HTTP 503).
+   * authenticate the caller; without it the handler fails closed (HTTP 503). No
+   * cloud consumer calls this endpoint yet — it is an inert primitive reserved for
+   * a future CRM/dashboard auth-passthrough.
    */
   verifyToken?: string;
 }
@@ -201,6 +208,13 @@ interface CreateChatSessionHandlerOptions {
   apiKey: string;
   apiUrl?: string;
   fetchImpl?: typeof fetch;
+  /**
+   * Optional host-auth hook. When provided, it runs on the incoming browser
+   * request (session cookies intact) and, on a non-null `ClivlyUser`, the host
+   * vouches for that verified identity to Clivly Cloud. Absent/null/throwing =
+   * the visitor stays self-reported. Never fails the session.
+   */
+  resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */

package/dist/vite.d.cts

@@ -1,6 +1,5 @@
-import { a as ClivlySDK } from "./types-jMafEyTv.cjs";
+import { a as ClivlySDK } from "./types-DTaz5mLi.cjs";
 import { Plugin } from "vite";
-
 //#region src/vite.d.ts
 interface ClivlyViteOptions {
   /** Log prefix for Clivly's boot lines. Defaults to "clivly". */

package/dist/vite.d.mts

@@ -1,6 +1,5 @@
-import { a as ClivlySDK } from "./types-B7wBCHRT.mjs";
+import { a as ClivlySDK } from "./types-DTaz5mLi.mjs";
 import { Plugin } from "vite";
-
 //#region src/vite.d.ts
 interface ClivlyViteOptions {
   /** Log prefix for Clivly's boot lines. Defaults to "clivly". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.4.0",
+  "version": "0.7.1",
   "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.4.0"
+    "@clivly/core": "0.7.1"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.30",
+    "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {
@@ -72,11 +72,14 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",
     "drizzle-orm": "^0.45.2",
-    "tsdown": "^0.21.9",
+    "tsdown": "^0.22.14",
     "typescript": "^6",
     "vite": "^8.0.8",
     "vitest": "^3.2.0"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsdown",
     "check-types": "tsc --noEmit",