@clivly/sdk 0.1.0 → 0.3.0-next.1

package/dist/index.mjs

@@ -1,3 +1,171 @@
+import { t as DRIZZLE_META } from "./drizzle-meta-DMx_9nlj.mjs";
+//#region src/namespace-probe.ts
+/**
+* Verify the tables the integration depends on are genuinely reachable:
+* connect, list tables, confirm each required table exists, then prove it's
+* selectable with a sample `SELECT ... LIMIT 1`. Column-shape validation is
+* not this probe's job — `doctor()`'s "Cursor/id columns exist" check
+* validates columns using the correct Drizzle metadata. Never throws —
+* connection/permission problems become `error.kind: "unreachable"`, missing
+* tables become `"schema"`.
+*/
+async function probeNamespace(introspector, requiredTables) {
+	let present;
+	try {
+		present = new Set(await introspector.listTables());
+	} catch (error) {
+		return {
+			reachable: false,
+			missingTables: requiredTables,
+			error: {
+				kind: "unreachable",
+				message: errorMessage(error)
+			}
+		};
+	}
+	const missingTables = requiredTables.filter((t) => !present.has(t));
+	if (missingTables.length > 0) return {
+		reachable: false,
+		missingTables,
+		error: {
+			kind: "schema",
+			message: `missing table(s): ${missingTables.join(", ")}`
+		}
+	};
+	for (const table of requiredTables) try {
+		await introspector.sampleSelect(table);
+	} catch (error) {
+		return {
+			reachable: false,
+			missingTables: [],
+			error: {
+				kind: "unreachable",
+				message: errorMessage(error)
+			}
+		};
+	}
+	return {
+		reachable: true,
+		missingTables: []
+	};
+}
+/** The distinct source tables the integration reads, derived from the entity config. */
+function requiredTablesFromConfig(config) {
+	const tables = /* @__PURE__ */ new Set();
+	const sources = [
+		config.source?.contacts,
+		config.source?.companies,
+		config.source?.deals,
+		...config.source?.custom ?? []
+	].filter((source) => Boolean(source));
+	const tableNameByEntity = new Map(sources.map((source) => [source.entity, source[DRIZZLE_META]?.tableName]));
+	for (const entity of Object.values(config.entities?.entities ?? {})) tables.add(tableNameByEntity.get(entity.source) ?? entity.source);
+	return [...tables];
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/doctor.ts
+function configuredSources(config) {
+	const sources = [];
+	if (config.source?.contacts) sources.push(config.source.contacts);
+	if (config.source?.companies) sources.push(config.source.companies);
+	if (config.source?.deals) sources.push(config.source.deals);
+	sources.push(...config.source?.custom ?? []);
+	return sources;
+}
+async function namespaceCheck(config) {
+	if (!config.introspector) return {
+		name: "Namespace reachable",
+		ok: false,
+		skipped: true,
+		detail: "No introspector configured — set `introspector` in clivly.config to probe the namespace."
+	};
+	const probeResult = await probeNamespace(config.introspector, requiredTablesFromConfig(config));
+	return {
+		name: "Namespace reachable",
+		ok: probeResult.reachable,
+		detail: probeResult.reachable ? "All required source tables are reachable." : probeResult.error?.message ?? "namespace unreachable"
+	};
+}
+/**
+* Run the read-only setup checks and return a structured report. Every check
+* captures its own error into `detail` rather than throwing, so one failure never
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, connect } = args;
+	const checks = [];
+	const sources = configuredSources(config);
+	const hasKey = Boolean(config.apiKey);
+	checks.push({
+		name: "API key present",
+		ok: hasKey,
+		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
+	});
+	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
+	checks.push({
+		name: "Entities configured",
+		ok: entityCount > 0,
+		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
+	});
+	checks.push({
+		name: "Sources configured",
+		ok: sources.length > 0,
+		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+	});
+	for (const source of sources) {
+		const meta = source[DRIZZLE_META];
+		if (!meta) {
+			checks.push({
+				name: `Cursor/id columns exist (${source.entity})`,
+				ok: false,
+				skipped: true,
+				detail: `"${source.entity}" is a hand-written source — column check skipped.`
+			});
+			continue;
+		}
+		const idField = source.idField ?? "id";
+		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
+		checks.push({
+			name: `Cursor/id columns exist (${source.entity})`,
+			ok: missing.length === 0,
+			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
+		});
+	}
+	for (const source of sources) try {
+		const rows = await source.fetchPage({
+			since: null,
+			limit: 1
+		});
+		const firstRow = rows[0];
+		const missingCursor = firstRow !== void 0 && !(source.cursorField in firstRow);
+		checks.push({
+			name: `Sample fetch (${source.entity})`,
+			ok: !missingCursor,
+			detail: missingCursor ? `"${source.entity}" rows lack the cursor key "${source.cursorField}".` : `"${source.entity}" returned ${rows.length} row(s).`
+		});
+	} catch (error) {
+		checks.push({
+			name: `Sample fetch (${source.entity})`,
+			ok: false,
+			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+		});
+	}
+	const result = await connect();
+	checks.push({
+		name: "Heartbeat",
+		ok: result.ok,
+		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
+	});
+	checks.push(await namespaceCheck(config));
+	return {
+		ok: checks.every((check) => check.skipped || check.ok),
+		checks
+	};
+}
+//#endregion
 //#region src/sync.ts
 const DEFAULT_ID_FIELD = "id";
 function isAfter(candidate, current) {
@@ -23,7 +191,7 @@ function nextCursor(rows, cursorField, idField, current) {
 	return max;
 }
 async function syncSource(args) {
-	const { source, path, since, batchSize, push } = args;
+	const { source, path, since, batchSize, push, objectType, maxRows } = args;
 	const idField = source.idField ?? DEFAULT_ID_FIELD;
 	let cursor = since;
 	let pushed = 0;
@@ -33,18 +201,20 @@ async function syncSource(args) {
 			limit: batchSize
 		});
 		if (rows.length === 0) break;
+		const capped = maxRows === void 0 ? rows : rows.slice(0, maxRows);
 		if (!await push(path, {
 			source: source.entity,
-			rows,
-			mode: "delta"
+			rows: capped,
+			mode: "delta",
+			...objectType ? { objectType } : {}
 		})) return {
 			pushed,
 			cursor,
 			ok: false
 		};
-		pushed += rows.length;
-		cursor = nextCursor(rows, source.cursorField, idField, cursor);
-		if (rows.length < batchSize) break;
+		pushed += capped.length;
+		cursor = nextCursor(capped, source.cursorField, idField, cursor);
+		if (maxRows !== void 0 || rows.length < batchSize) break;
 	}
 	return {
 		pushed,
@@ -53,7 +223,7 @@ async function syncSource(args) {
 	};
 }
 async function fullSyncSource(args) {
-	const { source, path, batchSize, push } = args;
+	const { source, path, batchSize, push, objectType } = args;
 	const idField = source.idField ?? DEFAULT_ID_FIELD;
 	const all = [];
 	let cursor = null;
@@ -77,7 +247,8 @@ async function fullSyncSource(args) {
 	const ok = await push(path, {
 		source: source.entity,
 		rows: all,
-		mode: "full"
+		mode: "full",
+		...objectType ? { objectType } : {}
 	});
 	return {
 		pushed: ok ? all.length : 0,
@@ -86,16 +257,55 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/errors.ts
+var ClivlyError = class ClivlyError extends Error {
+	/** HTTP status, or null when the request never completed (network error). */
+	status;
+	reason;
+	/** Whether a retry could plausibly succeed (network, 429, 5xx). */
+	retryable;
+	constructor(result, message) {
+		super(message ?? `Clivly connection failed: ${result.reason}`);
+		this.name = new.target.name;
+		this.status = result.status;
+		this.reason = result.reason;
+		this.retryable = result.retryable;
+	}
+	/**
+	* Build the error subclass matching a failed result's reason, or `null` when
+	* the result is `ok`.
+	*/
+	static from(result) {
+		if (result.ok) return null;
+		switch (result.reason) {
+			case "invalid_api_key":
+			case "forbidden": return new ClivlyAuthError(result);
+			case "rate_limited": return new ClivlyRateLimitError(result);
+			case "network_error": return new ClivlyNetworkError(result);
+			default: return new ClivlyError(result);
+		}
+	}
+};
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+var ClivlyAuthError = class extends ClivlyError {};
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+var ClivlyRateLimitError = class extends ClivlyError {};
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+var ClivlyNetworkError = class extends ClivlyError {};
+//#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://api.clivly.com";
 const DEFAULT_HEARTBEAT_MS = 6e4;
 const DEFAULT_BATCH_SIZE = 500;
+const SAMPLE_BATCH_SIZE = 1;
 const DEFAULT_MAX_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 500;
 const RETRYABLE_STATUS_FLOOR = 500;
 const RATE_LIMITED_STATUS = 429;
 const SYNC_CONTACTS_PATH = "/clivly/sdk/sync/contacts";
 const SYNC_COMPANIES_PATH = "/clivly/sdk/sync/companies";
+const SYNC_DEALS_PATH = "/clivly/sdk/sync/deals";
+const SYNC_CUSTOM_PATH = "/clivly/sdk/sync/custom";
 const TRAILING_SLASH = /\/$/;
 const BEARER_PREFIX = /^Bearer\s+/i;
 function entitiesToTables(entities, byName) {
@@ -110,6 +320,17 @@ function resolveContactEntity(config) {
 	if (config.contactEntity) return config.contactEntity;
 	for (const entity of Object.values(config.entities?.entities ?? {})) if (entity.concept === "contact") return entity.source;
 }
+function collectSchemaMeta(config) {
+	const byTable = /* @__PURE__ */ new Map();
+	for (const table of config.schema ?? []) if (table.columnsMeta) byTable.set(table.name, table.columnsMeta);
+	const sources = [];
+	if (config.source) sources.push(config.source.contacts, config.source.companies, config.source.deals, ...config.source.custom ?? []);
+	for (const source of sources) {
+		const meta = source?.[DRIZZLE_META];
+		if (meta?.tableName && meta.columnsMeta) byTable.set(meta.tableName, meta.columnsMeta);
+	}
+	return byTable;
+}
 function buildSchema(config) {
 	const byName = /* @__PURE__ */ new Map();
 	for (const table of config.schema ?? []) {
@@ -119,12 +340,34 @@ function buildSchema(config) {
 	}
 	entitiesToTables(config.entities, byName);
 	if (config.contactEntity && !byName.has(config.contactEntity)) byName.set(config.contactEntity, new Set(config.contactFields ?? []));
-	return [...byName].map(([name, columns]) => ({
-		name,
-		columns: [...columns]
-	}));
+	const metaByTable = collectSchemaMeta(config);
+	return [...byName].map(([name, columns]) => {
+		const columnsMeta = metaByTable.get(name);
+		if (columnsMeta) for (const col of columnsMeta) columns.add(col.name);
+		return {
+			name,
+			columns: [...columns],
+			...columnsMeta ? { columnsMeta } : {}
+		};
+	});
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function createMemoryCursorStore() {
+	const cursors = /* @__PURE__ */ new Map();
+	return {
+		get: (entity) => cursors.get(entity) ?? null,
+		set: (entity, cursor) => {
+			cursors.set(entity, cursor);
+		}
+	};
+}
+function isLikelyServerless() {
+	const runtime = globalThis;
+	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
+	if (runtime.EdgeRuntime !== void 0) return true;
+	const env = runtime.process?.env;
+	return Boolean(env?.AWS_LAMBDA_FUNCTION_NAME || env?.VERCEL);
+}
 function jsonResponse(body, status) {
 	return new Response(JSON.stringify(body), {
 		status,
@@ -137,6 +380,36 @@ function timingSafeEqual(a, b) {
 	for (let i = 0; i < a.length; i++) mismatch += a.charCodeAt(i) === b.charCodeAt(i) ? 0 : 1;
 	return mismatch === 0;
 }
+const RUN_ID_HEADER = "x-clivly-run-id";
+const SIGNATURE_HEADER = "x-clivly-signature";
+const SIGNATURE_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
+const SECONDS_PER_MS = 1e3;
+function toHex(buffer) {
+	return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Verify that a sync-trigger request really came from Clivly.
+*
+* Clivly signs `${timestamp}.${rawBody}` with the shared secret, so this proves
+* two things at once: the caller holds the secret, and the body wasn't altered in
+* flight. The timestamp is inside the signed material, so an attacker can't
+* rewrite it to extend the replay window.
+*
+* Uses WebCrypto (not node:crypto) so it works unchanged on edge and worker
+* runtimes, where a host app is most likely to mount this.
+*/
+async function verifyTriggerSignature(header, rawBody, secret) {
+	const match = header ? SIGNATURE_HEADER_RE.exec(header) : null;
+	if (!match) return false;
+	const [, timestamp, provided] = match;
+	if (Math.abs(Math.floor(Date.now() / SECONDS_PER_MS) - Number(timestamp)) > SIGNATURE_TOLERANCE_SECONDS) return false;
+	const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return timingSafeEqual(provided, toHex(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${rawBody}`))));
+}
 function bearerToken(req) {
 	const header = req.headers.get("authorization");
 	if (!(header && BEARER_PREFIX.test(header))) return null;
@@ -145,6 +418,25 @@ function bearerToken(req) {
 function isRetryableStatus(status) {
 	return status === RATE_LIMITED_STATUS || status >= RETRYABLE_STATUS_FLOOR;
 }
+const UNAUTHORIZED_STATUS = 401;
+const FORBIDDEN_STATUS = 403;
+const CLIENT_ERROR_FLOOR = 400;
+const SERVICE_UNAVAILABLE_STATUS = 503;
+function connectReason(status) {
+	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
+	if (status === FORBIDDEN_STATUS) return "forbidden";
+	if (status === RATE_LIMITED_STATUS) return "rate_limited";
+	if (status >= RETRYABLE_STATUS_FLOOR) return "server_error";
+	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
+	return "server_error";
+}
+async function resolveOrg(response) {
+	try {
+		return (await response.json())?.org;
+	} catch {
+		return;
+	}
+}
 function retryAfterMs(res) {
 	const header = res.headers.get("retry-after");
 	if (!header) return null;
@@ -170,6 +462,73 @@ function createFetcher(retry) {
 		}
 	};
 }
+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
+	};
+	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) {
+	const src = config.source;
+	if (!src) return null;
+	return [
+		src.contacts,
+		src.companies,
+		src.deals,
+		...src.custom ?? []
+	].filter((s) => Boolean(s)).find((s) => s.entity === sourceTable) ?? null;
+}
+function toPreviewCell(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	if (value instanceof Date) return value.toISOString();
+	return String(value);
+}
+function slimPreviewRow(row, needed) {
+	const out = {};
+	for (const key of needed) out[key] = toPreviewCell(row[key]);
+	return out;
+}
+async function handlePreviewRequest(config, preview) {
+	const source = resolvePreviewSource(config, preview.sourceTable);
+	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([
+		idField,
+		...Object.values(preview.fieldMap),
+		...filterColumns
+	]);
+	const rows = (await source.fetchPage({
+		since: null,
+		limit: PREVIEW_LIMIT
+	})).slice(0, PREVIEW_LIMIT).map((row) => slimPreviewRow(row, needed));
+	return jsonResponse({
+		rows,
+		sampledCount: rows.length
+	}, 200);
+}
 /**
 * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
 * and the auth-verify handler — connects a developer's app to a running Clivly
@@ -185,62 +544,177 @@ function createClivlySDK(config) {
 		sync: null
 	};
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursors = /* @__PURE__ */ new Map();
+	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
-	const push = async (path, body) => {
-		return (await fetcher(`${apiUrl}${path}`, {
+	let warnedUnsignedTrigger = false;
+	let lastPushFailure = null;
+	const createPush = (runId) => async (path, body) => {
+		const response = await fetcher(`${apiUrl}${path}`, {
 			method: "POST",
 			headers: {
 				"content-type": "application/json",
-				authorization: `Bearer ${config.apiKey}`
+				authorization: `Bearer ${config.apiKey}`,
+				...runId ? { [RUN_ID_HEADER]: runId } : {}
 			},
 			body: JSON.stringify(body)
-		}))?.ok ?? false;
+		});
+		if (response?.ok) return true;
+		lastPushFailure ??= { status: response?.status ?? null };
+		return false;
+	};
+	const describePushFailure = (entities) => {
+		const base = `Clivly sync: push failed for ${entities.join(", ")}`;
+		const status = lastPushFailure?.status ?? null;
+		let cause;
+		if (status === 401 || status === 403) cause = "the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this org";
+		else if (status === null) cause = `couldn't reach Clivly at ${apiUrl} — check network access and CLIVLY_API_URL`;
+		else cause = `Clivly returned HTTP ${status}`;
+		return `${base}: ${cause}. Run \`clivly doctor\` to diagnose.`;
 	};
-	const syncOne = async (source, path, mode) => {
+	const syncOne = async (source, path, mode, objectType, runId, batchSizeOverride, maxRowsOverride, persistCursor = true) => {
+		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
+		const push = createPush(runId);
+		const effectiveBatchSize = batchSizeOverride ?? batchSize;
 		const result = mode === "full" ? await fullSyncSource({
 			source,
 			path,
-			batchSize,
-			push
+			batchSize: effectiveBatchSize,
+			push,
+			objectType
 		}) : await syncSource({
 			source,
 			path,
-			since: cursors.get(source.entity) ?? null,
-			batchSize,
-			push
+			since,
+			batchSize: effectiveBatchSize,
+			push,
+			objectType,
+			maxRows: maxRowsOverride
 		});
-		cursors.set(source.entity, result.cursor);
+		if (persistCursor) await cursorStore.set(source.entity, result.cursor);
 		return result.ok;
 	};
+	const syncCustomSources = async (customSources, mode, runId) => {
+		const failed = [];
+		for (const customSource of customSources ?? []) if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
+		return failed;
+	};
 	const runSync = async (options) => {
 		if (!config.source) return;
+		lastPushFailure = null;
 		const mode = options?.mode ?? "delta";
+		const runId = options?.runId;
 		const failed = [];
 		if (config.source.companies) {
-			if (!await syncOne(config.source.companies, SYNC_COMPANIES_PATH, mode)) failed.push(config.source.companies.entity);
+			if (!await syncOne(config.source.companies, SYNC_COMPANIES_PATH, mode, void 0, runId)) failed.push(config.source.companies.entity);
 		}
-		if (!await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode)) failed.push(config.source.contacts.entity);
-		if (failed.length > 0) throw new Error(`Clivly sync: push failed for ${failed.join(", ")}`);
+		if (!await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode, void 0, runId)) failed.push(config.source.contacts.entity);
+		if (config.source.deals && !await syncOne(config.source.deals, SYNC_DEALS_PATH, mode, void 0, runId)) failed.push(config.source.deals.entity);
+		failed.push(...await syncCustomSources(config.source.custom, mode, runId));
+		if (failed.length > 0) throw new Error(describePushFailure(failed));
+	};
+	const runSampleSync = async (entityKey, runId) => {
+		const resolved = resolveSampleSource(config, entityKey);
+		if (!resolved) throw new Error(`Clivly sync: sample entityKey "${entityKey}" did not resolve to a configured source`);
+		lastPushFailure = null;
+		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
 	};
+	const sendHeartbeat = () => fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${config.apiKey}`
+		},
+		body: JSON.stringify({
+			framework: config.framework,
+			orm: config.orm,
+			sdkVersion: config.sdkVersion,
+			contactEntity: resolveContactEntity(config),
+			namespaceReady: config.namespaceReady ?? false,
+			schema: buildSchema(config),
+			...config.syncTrigger?.url ? { syncTrigger: { url: config.syncTrigger.url } } : {}
+		})
+	});
 	const heartbeat = async () => {
-		return (await fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
-			method: "POST",
-			headers: {
-				"content-type": "application/json",
-				authorization: `Bearer ${config.apiKey}`
-			},
-			body: JSON.stringify({
-				framework: config.framework,
-				orm: config.orm,
-				sdkVersion: config.sdkVersion,
-				contactEntity: resolveContactEntity(config),
-				namespaceReady: config.namespaceReady ?? false,
-				schema: buildSchema(config)
-			})
-		}))?.ok ?? false;
+		return (await sendHeartbeat())?.ok ?? false;
+	};
+	const connect = async () => {
+		const response = await sendHeartbeat();
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) return {
+			ok: true,
+			status: response.status,
+			reason: "ok",
+			retryable: false,
+			org: await resolveOrg(response)
+		};
+		return {
+			ok: false,
+			status: response.status,
+			reason: connectReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
+	const doctor = () => runDoctor({
+		config,
+		connect
+	});
+	const runScheduled = async (options) => {
+		await heartbeat();
+		if (config.source) await runSync(options);
+	};
+	const triggerRequestAllowed = async (req, rawBody) => {
+		const secret = config.syncTrigger?.secret;
+		if (secret) return await verifyTriggerSignature(req.headers.get(SIGNATURE_HEADER), rawBody, secret);
+		if (!warnedUnsignedTrigger) {
+			warnedUnsignedTrigger = true;
+			console.warn("Clivly: the sync trigger route is mounted without `syncTrigger.secret`, so anyone who can reach the URL can start a sync. Set a secret (Integrations → Remote sync in Clivly) to require signed requests.");
+		}
+		return true;
+	};
+	const parseTriggerBody = (rawBody) => {
+		if (!rawBody) return {};
+		try {
+			return JSON.parse(rawBody);
+		} catch {
+			return {};
+		}
+	};
+	const createClivlyHandler = () => async (req) => {
+		const rawBody = await req.text().catch(() => "");
+		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
+			ok: false,
+			error: "unauthorized"
+		}, UNAUTHORIZED_STATUS);
+		const payload = parseTriggerBody(rawBody);
+		const runId = payload.runId ?? null;
+		const startedAt = Date.now();
+		try {
+			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
+			else await runScheduled({
+				mode: payload.mode,
+				runId: payload.runId
+			});
+			return jsonResponse({
+				ok: true,
+				runId,
+				durationMs: Date.now() - startedAt
+			}, 200);
+		} catch (error) {
+			return jsonResponse({
+				ok: false,
+				runId,
+				error: error instanceof Error ? error.message : String(error)
+			}, 500);
+		}
 	};
 	const start = async () => {
+		if (isLikelyServerless()) console.warn("clivly.start() uses a setInterval keep-alive loop, which does not persist on serverless/edge runtimes — it will stop ticking after the first response. Call clivly.runScheduled() from a scheduled/cron trigger, or mount clivly.createClivlyHandler() at a route instead.");
 		await heartbeat();
 		if (config.sync?.onBoot !== false) await runSync().catch(() => {});
 		if (!timers.heartbeat) {
@@ -267,7 +741,7 @@ function createClivlySDK(config) {
 		}
 	};
 	const createAuthVerifyHandler = (resolveUser) => async (req) => {
-		if (!config.verifyToken) return jsonResponse({ error: "verify token not configured" }, 500);
+		if (!config.verifyToken) return jsonResponse({ error: "Clivly verifyToken is not configured on the host app" }, SERVICE_UNAVAILABLE_STATUS);
 		const token = bearerToken(req);
 		if (!(token && timingSafeEqual(token, config.verifyToken))) return jsonResponse({ error: "unauthorized" }, 401);
 		const user = await resolveUser(req);
@@ -278,9 +752,13 @@ function createClivlySDK(config) {
 		start,
 		stop,
 		heartbeat,
+		connect,
+		doctor,
+		runScheduled,
+		createClivlyHandler,
 		sync: runSync,
 		createAuthVerifyHandler
 	};
 }
 //#endregion
-export { createClivlySDK };
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createClivlySDK };