clivly 0.4.1 → 0.7.1

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

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

package/sdk.cjs

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

package/sdk.d.cts

@@ -1,41 +1 @@
-import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-CkHCj9tQ.cjs";
-
-//#region ../sdk/src/chat-session.d.ts
-declare function createChatSessionHandler({
-  allowedOrigins,
-  apiKey,
-  apiUrl,
-  fetchImpl
-}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
-//#endregion
-//#region ../sdk/src/errors.d.ts
-declare class ClivlyError extends Error {
-  /** HTTP status, or null when the request never completed (network error). */
-  readonly status: number | null;
-  readonly reason: ClivlyConnectResult["reason"];
-  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
-  readonly retryable: boolean;
-  constructor(result: ClivlyConnectResult, message?: string);
-  /**
-   * Build the error subclass matching a failed result's reason, or `null` when
-   * the result is `ok`.
-   */
-  static from(result: ClivlyConnectResult): ClivlyError | null;
-}
-/** The API key was rejected (401) or lacks access (403). Not retryable. */
-declare class ClivlyAuthError extends ClivlyError {}
-/** Rate limited (429). Retryable after backoff / `Retry-After`. */
-declare class ClivlyRateLimitError extends ClivlyError {}
-/** The request never reached the server (network/DNS/TLS). Retryable. */
-declare class ClivlyNetworkError extends ClivlyError {}
-//#endregion
-//#region ../sdk/src/index.d.ts
-/**
- * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
- * and the auth-verify handler — connects a developer's app to a running Clivly
- * backend today. Tunnel management and CRM write-back are scaffolded (see the
- * clearly-marked TODOs) and land with the Cloudflare infrastructure.
- */
-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 {}

package/sdk.d.mts

@@ -1,41 +1 @@
-import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-CA4Vj40g.mjs";
-
-//#region ../sdk/src/chat-session.d.ts
-declare function createChatSessionHandler({
-  allowedOrigins,
-  apiKey,
-  apiUrl,
-  fetchImpl
-}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
-//#endregion
-//#region ../sdk/src/errors.d.ts
-declare class ClivlyError extends Error {
-  /** HTTP status, or null when the request never completed (network error). */
-  readonly status: number | null;
-  readonly reason: ClivlyConnectResult["reason"];
-  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
-  readonly retryable: boolean;
-  constructor(result: ClivlyConnectResult, message?: string);
-  /**
-   * Build the error subclass matching a failed result's reason, or `null` when
-   * the result is `ok`.
-   */
-  static from(result: ClivlyConnectResult): ClivlyError | null;
-}
-/** The API key was rejected (401) or lacks access (403). Not retryable. */
-declare class ClivlyAuthError extends ClivlyError {}
-/** Rate limited (429). Retryable after backoff / `Retry-After`. */
-declare class ClivlyRateLimitError extends ClivlyError {}
-/** The request never reached the server (network/DNS/TLS). Retryable. */
-declare class ClivlyNetworkError extends ClivlyError {}
-//#endregion
-//#region ../sdk/src/index.d.ts
-/**
- * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
- * and the auth-verify handler — connects a developer's app to a running Clivly
- * backend today. Tunnel management and CRM write-back are scaffolded (see the
- * clearly-marked TODOs) and land with the Cloudflare infrastructure.
- */
-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 {}

package/sdk.mjs

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

package/{sync-engine-DIVMG9EV.d.cts → sync-engine-B7QIbXro.d.cts}

@@ -1,6 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-GczjD3y8.cjs";
-import { n as CompiledView, t as CompileOptions } from "./view-compiler-4HsRUTWH.cjs";
-
+import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.cjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-BWz0sGdm.cjs";
 //#region ../core/src/sync-engine.d.ts
 /**
  * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's
@@ -108,13 +107,15 @@ interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
-    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    role: string;
+    /** Target custom-object type id, for `concept: "custom"` entities. */
     objectTypeId?: string;
   }): Promise<MirrorRecord[]>;
   /** Apply the resolved actions to the mirror table for this concept + role. */
   persist(input: {
     concept: string;
-    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    role: string;
+    /** Target custom-object type id, for `concept: "custom"` entities. */
     objectTypeId?: string;
     actions: PersistAction[];
   }): Promise<void>;

package/{sync-engine-BtzkzKmY.cjs → sync-engine-CzEbpQGv.cjs}

@@ -1,4 +1,4 @@
-const require_view_compiler = require("./view-compiler-BcgJINr7.cjs");
+const require_view_compiler = require("./view-compiler-BIwvm-o2.cjs");
 //#region ../core/src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/{sync-engine-DLx243iw.d.mts → sync-engine-DGk_AeHJ.d.mts}

@@ -1,6 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-D1DFyeUp.mjs";
-import { n as CompiledView, t as CompileOptions } from "./view-compiler-BpIDExjd.mjs";
-
+import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.mjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-Bn_EJJMO.mjs";
 //#region ../core/src/sync-engine.d.ts
 /**
  * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's
@@ -108,13 +107,15 @@ interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
-    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    role: string;
+    /** Target custom-object type id, for `concept: "custom"` entities. */
     objectTypeId?: string;
   }): Promise<MirrorRecord[]>;
   /** Apply the resolved actions to the mirror table for this concept + role. */
   persist(input: {
     concept: string;
-    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    role: string;
+    /** Target custom-object type id, for `concept: "custom"` entities. */
     objectTypeId?: string;
     actions: PersistAction[];
   }): Promise<void>;

package/{sync-engine-D9vghQab.mjs → sync-engine-Do5ru3WF.mjs}

@@ -1,4 +1,4 @@
-import { r as compileEntityViews } from "./view-compiler-DeZzx_jn.mjs";
+import { r as compileEntityViews } from "./view-compiler-ChWr_Lml.mjs";
 //#region ../core/src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/types-CsL0rFYh.d.cts

@@ -0,0 +1,155 @@
+//#region ../sdk/src/drizzle-meta.d.ts
+declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
+interface DrizzleSourceMeta {
+  /** Drizzle property keys of every column on the source table. */
+  columnKeys: string[];
+  /** Schema-v2 typed column metadata derived from the Drizzle table. */
+  columnsMeta?: DiscoveredColumn[];
+  cursorField: string;
+  idField: string;
+  /** The backing table's real name, so discovery can key metadata by table. */
+  tableName?: string;
+}
+//#endregion
+//#region ../sdk/src/types.d.ts
+interface DiscoveredColumn {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  /** The column this FK points at, when it is a foreign key. */
+  references?: {
+    table: string;
+    column: string;
+  };
+  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
+  type?: string;
+}
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+interface DoctorCheck {
+  /** Human-readable outcome — what passed, or why it failed. */
+  detail: string;
+  /** Short label, e.g. "API key present". */
+  name: string;
+  /** True when the check passed. Ignored when `skipped` is true. */
+  ok: boolean;
+  /** True when the check could not run (e.g. a hand-written source). */
+  skipped?: boolean;
+}
+interface DoctorReport {
+  checks: DoctorCheck[];
+  /** AND of every non-skipped check's `ok`. */
+  ok: boolean;
+}
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
+interface ClivlyConnectResult {
+  ok: boolean;
+  /** Org resolved from a successful heartbeat, when the server returns it. */
+  org?: {
+    id?: string;
+    name?: string;
+  };
+  reason: ClivlyConnectReason;
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  retryable: boolean;
+  /** HTTP status, or null when the request never completed (network error). */
+  status: number | null;
+}
+interface SyncCursor {
+  /** The row's id, breaking ties when timestamps collide. */
+  id: string;
+  /** The row's cursor-field value (typically `updated_at`). */
+  time: Date;
+}
+interface SyncSource {
+  cursorField: string;
+  entity: string;
+  fetchPage(args: {
+    since: SyncCursor | null;
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
+  /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
+  idField?: string;
+  /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
+  [DRIZZLE_META]?: DrizzleSourceMeta;
+}
+type SyncMode = "delta" | "full";
+interface ClivlySDK {
+  /**
+   * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
+   * `status` (null on network failure), a coarse `reason`, whether it's
+   * `retryable`, and the resolved `org` when the server returns it. Never throws
+   * — inspect the result, or turn a failure into an exception with
+   * `ClivlyError.from(result)`. Prefer this over `heartbeat()` for onboarding,
+   * health checks, and one-shot serverless calls.
+   */
+  connect(): Promise<ClivlyConnectResult>;
+  /**
+   * Build the `/clivly/auth/verify` handler the developer mounts in their app.
+   * Clivly's cloud calls it to validate a CRM user's identity against the host
+   * app's session. Pass a resolver that reads the host session from the request.
+   *
+   * The handler authenticates the caller against `config.verifyToken` (presented
+   * as `Authorization: Bearer <token>`) before invoking the resolver, so the
+   * endpoint can't be used by third parties to probe host sessions. It fails
+   * closed with HTTP 503 if `verifyToken` is unset (a missing config value, not a
+   * server fault — so it won't trip the host's 5xx error alerting).
+   */
+  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
+  /**
+   * A fetch handler to mount at a route. Each request runs one `runScheduled()`
+   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
+   *
+   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
+   * requests are HMAC-signed and carry a run id), and the host's own scheduler
+   * (Workers cron, an uptime ping — no body).
+   *
+   * When `syncTrigger.secret` is set the handler rejects unsigned or
+   * badly-signed requests with 401. When it isn't, the route stays open to
+   * anyone who can reach it — set a secret if it's publicly routable.
+   */
+  createClivlyHandler(): (req: Request) => Promise<Response>;
+  /** Validate this setup end-to-end (read-only) before the first sync. */
+  doctor(): Promise<DoctorReport>;
+  /**
+   * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
+   * loop and back-compat; use `connect()` when you need the failure reason.
+   */
+  heartbeat(): Promise<boolean>;
+  /**
+   * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
+   * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s
+   * `setInterval` loop can't persist between invocations — call this from a
+   * scheduled/cron trigger. Throws if a sync push fails (so the run is marked
+   * failed); heartbeat is best-effort.
+   */
+  runScheduled(options?: {
+    mode?: SyncMode;
+    runId?: string;
+  }): Promise<void>;
+  /**
+   * Send the initial heartbeat and start the keep-alive loop. For long-lived
+   * hosts only — on serverless/edge the interval can't persist, so prefer
+   * `runScheduled()` / `createClivlyHandler()`. Emits a warning if a serverless
+   * runtime is detected.
+   */
+  start(): Promise<void>;
+  /** Stop the keep-alive loop. */
+  stop(): void;
+  /**
+   * Sync all configured sources now. `delta` (default) pages changed rows since
+   * the last cursor; `full` pushes each complete entity so the server can
+   * reconcile leavers (archive-on-leave). Throws if a push fails, so callers see
+   * the failure — the background keep-alive loop swallows and retries instead.
+   */
+  sync(options?: {
+    mode?: SyncMode;
+    runId?: string;
+  }): Promise<void>;
+}
+//#endregion
+export { SyncSource as n, ClivlySDK as t };