@clivly/sdk 0.2.0 → 0.3.0-next.1

package/dist/index.mjs

@@ -1,13 +1,96 @@
-import { t as DRIZZLE_META } from "./drizzle-meta-CAJ43cLc.mjs";
+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 six read-only setup checks and return a structured report. Every check
+* 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.
 */
@@ -76,6 +159,7 @@ async function runDoctor(args) {
 		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
@@ -107,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;
@@ -117,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,
@@ -137,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;
@@ -161,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,
@@ -210,12 +297,15 @@ var ClivlyNetworkError = class extends ClivlyError {};
 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) {
@@ -230,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 ?? []) {
@@ -239,10 +340,16 @@ 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() {
@@ -273,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;
@@ -325,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
@@ -342,42 +546,77 @@ function createClivlySDK(config) {
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
 	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 syncOne = async (source, path, mode) => {
+	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, 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,
-			batchSize,
-			push
+			batchSize: effectiveBatchSize,
+			push,
+			objectType,
+			maxRows: maxRowsOverride
 		});
-		await cursorStore.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",
@@ -391,7 +630,8 @@ function createClivlySDK(config) {
 			sdkVersion: config.sdkVersion,
 			contactEntity: resolveContactEntity(config),
 			namespaceReady: config.namespaceReady ?? false,
-			schema: buildSchema(config)
+			schema: buildSchema(config),
+			...config.syncTrigger?.url ? { syncTrigger: { url: config.syncTrigger.url } } : {}
 		})
 	});
 	const heartbeat = async () => {
@@ -427,13 +667,48 @@ function createClivlySDK(config) {
 		await heartbeat();
 		if (config.source) await runSync(options);
 	};
-	const createClivlyHandler = () => async (_req) => {
+	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 {
-			await runScheduled();
-			return jsonResponse({ ok: true }, 200);
+			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);
 		}

package/dist/{types-B0aSxJ6V.d.cts → namespace-probe-DFpvfl7T.d.mts}

@@ -1,18 +1,39 @@
 import { ClivlyEntitiesConfig } from "@clivly/core";
 
 //#region src/drizzle-meta.d.ts
-declare const DRIZZLE_META: unique symbol;
+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 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 DiscoveredTable {
   columns: string[];
+  /** Schema-v2 typed column metadata (types, PK/FK, nullability). */
+  columnsMeta?: DiscoveredColumn[];
   name: string;
+  /** Approximate source row count, when cheaply derivable. */
+  rowCount?: number;
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */
@@ -60,7 +81,18 @@ interface ClivlySDKConfig {
   framework?: string;
   /** Heartbeat cadence in ms. Defaults to 60s. */
   heartbeatIntervalMs?: number;
-  /** Whether the crm_* namespace exists in the host DB (self-reported). */
+  /**
+   * Optional live namespace probe, used on-demand by `doctor()`'s "Namespace
+   * reachable" check to verify every required source table + column is
+   * genuinely reachable. Not consulted by the heartbeat. Build one with
+   * `drizzleIntrospector(db)` from `@clivly/sdk/drizzle`.
+   */
+  introspector?: NamespaceIntrospector;
+  /**
+   * Self-reported readiness sent on every heartbeat as-is (no live check).
+   * For a real reachability check, configure `introspector` and run
+   * `doctor()`.
+   */
   namespaceReady?: boolean;
   orm?: string;
   /**
@@ -80,6 +112,10 @@ interface ClivlySDKConfig {
   source?: {
     contacts: SyncSource;
     companies?: SyncSource;
+    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    custom?: Array<SyncSource & {
+      objectType: string;
+    }>;
   };
   sync?: {
     onBoot?: boolean;
@@ -91,6 +127,29 @@ interface ClivlySDKConfig {
     intervalMs?: number;
     batchSize?: number;
   };
+  /**
+   * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
+   *
+   * Without it, cloud mode is push-only — Clivly can watch the app but can't
+   * start anything, so the dashboard's "Run sync" has nothing to call. With it,
+   * the SDK reports `url` on each heartbeat and requires every trigger request to
+   * be signed with `secret`.
+   */
+  syncTrigger?: {
+    /**
+     * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
+     * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
+     * heartbeat; a URL set in the dashboard overrides it.
+     */
+    url?: string;
+    /**
+     * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
+     * sync. When set, `createClivlyHandler()` rejects any request that isn't
+     * validly signed. Leave unset only if the route is already unreachable from
+     * the public internet.
+     */
+    secret?: string;
+  };
   /**
    * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
    * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
@@ -178,10 +237,16 @@ interface ClivlySDK {
    */
   createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
   /**
-   * A fetch handler to mount at a route and drive from an external scheduler
-   * (Cloudflare Workers cron, an uptime ping, etc.). Each request runs one
-   * `runScheduled()` and returns JSON: 200 when the sync succeeded, 500 otherwise.
-   * The ergonomic serverless entry point alongside `runScheduled()`.
+   * 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. */
@@ -200,6 +265,7 @@ interface ClivlySDK {
    */
   runScheduled(options?: {
     mode?: SyncMode;
+    runId?: string;
   }): Promise<void>;
   /**
    * Send the initial heartbeat and start the keep-alive loop. For long-lived
@@ -218,7 +284,16 @@ interface ClivlySDK {
    */
   sync(options?: {
     mode?: SyncMode;
+    runId?: string;
   }): Promise<void>;
 }
 //#endregion
-export { ClivlyUser as a, DoctorCheck as c, ClivlySDKConfig as i, DoctorReport as l, ClivlyConnectResult as n, CursorStore as o, ClivlySDK as r, DiscoveredTable as s, ClivlyConnectReason as t, SyncSource as u };
+//#region src/namespace-probe.d.ts
+interface NamespaceIntrospector {
+  /** All base table names in the reachable schema. */
+  listTables(): Promise<string[]>;
+  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
+  sampleSelect(table: string): Promise<void>;
+}
+//#endregion
+export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };