clivly 0.7.1 → 0.7.3

package/{sdk-C6WANW8M.mjs → sdk-C2VL28du.mjs}

@@ -276,6 +276,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region ../sdk/src/doctor.ts
+const TEMPORAL_CURSOR_TYPES = [
+	"timestamp",
+	"timestamptz",
+	"datetime",
+	"date",
+	"time"
+];
+/**
+* Warn when the sync cursor cannot observe an update.
+*
+* `clivly init` falls back to the primary key when a table has no
+* `updated_at`-like column, and emits a TODO saying "confirm it is monotonic".
+* A serial `id` *is* monotonic, so the note reads as satisfied — but monotonic
+* is only half the requirement. An `id` never changes, so every insert mirrors
+* and **no edit ever does**: a contact who changes their email keeps the old one
+* in the CRM forever, with nothing anywhere reporting a problem.
+*
+* A code comment could not enforce this; a real integrator shipped exactly this
+* configuration to production. This is the check that says so out loud.
+*/
+function cursorMonotonicityCheck(source) {
+	const meta = source[DRIZZLE_META];
+	if (!meta?.columnsMeta) return null;
+	const index = meta.columnKeys.indexOf(meta.cursorField);
+	const type = meta.columnsMeta[index]?.type?.toLowerCase();
+	if (!type) return null;
+	const temporal = TEMPORAL_CURSOR_TYPES.some((t) => type.startsWith(t));
+	const name = `Cursor tracks updates (${source.entity})`;
+	if (temporal) return {
+		name,
+		ok: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}) — edits re-sync.`
+	};
+	return {
+		name,
+		ok: true,
+		warn: true,
+		detail: `"${source.entity}" pages on ${meta.cursorField} (${type}), which does not change when a row is edited — inserts will sync, edits will not. Add an updated_at column to "${meta.tableName ?? source.entity}" and set it as the cursor, or accept insert-only mirroring.`
+	};
+}
 function configuredSources(config) {
 	const sources = [];
 	if (config.source?.contacts) sources.push(config.source.contacts);
@@ -304,32 +344,12 @@ async function mappingDryRunChecks(config) {
 	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
-* hides the rest. `ok` is the AND of all non-skipped checks.
+* Confirm each drizzle source actually has the cursor and id columns the sync
+* pages on. Hand-written sources have no column metadata, so they are skipped
+* rather than failed.
 */
-async function runDoctor(args) {
-	const { config, connect } = args;
+function cursorColumnChecks(sources) {
 	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."
-	});
-	checks.push(checkConceptCoverage(config));
 	for (const source of sources) {
 		const meta = source[DRIZZLE_META];
 		if (!meta) {
@@ -349,6 +369,14 @@ async function runDoctor(args) {
 			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
 		});
 	}
+	return checks;
+}
+/**
+* Read one row from each source to prove the query works and that rows actually
+* carry the cursor key. Fetch errors are captured as failures, never thrown.
+*/
+async function sampleFetchChecks(sources) {
+	const checks = [];
 	for (const source of sources) try {
 		const rows = await source.fetchPage({
 			since: null,
@@ -368,10 +396,45 @@ async function runDoctor(args) {
 			detail: describeFetchError(source.entity, error)
 		});
 	}
+	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
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, probe } = 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."
+	});
+	checks.push(checkConceptCoverage(config));
+	checks.push(...cursorColumnChecks(sources));
+	for (const source of sources) {
+		const check = cursorMonotonicityCheck(source);
+		if (check) checks.push(check);
+	}
+	checks.push(...await sampleFetchChecks(sources));
 	checks.push(...await mappingDryRunChecks(config));
-	const result = await connect();
+	const result = await probe();
 	checks.push({
-		name: "Heartbeat",
+		name: "Clivly reachable",
 		ok: result.ok,
 		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
 	});
@@ -810,6 +873,7 @@ const UNAUTHORIZED_STATUS = 401;
 const FORBIDDEN_STATUS = 403;
 const CLIENT_ERROR_FLOOR = 400;
 const SERVICE_UNAVAILABLE_STATUS = 503;
+const NOT_FOUND_STATUS = 404;
 function connectReason(status) {
 	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
 	if (status === FORBIDDEN_STATUS) return "forbidden";
@@ -818,6 +882,10 @@ function connectReason(status) {
 	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
 	return "server_error";
 }
+function pingReason(status) {
+	if (status === NOT_FOUND_STATUS) return "server_too_old";
+	return connectReason(status);
+}
 async function resolveOrg(response) {
 	try {
 		return (await response.json())?.org;
@@ -1049,9 +1117,38 @@ function createClivlySDK(config) {
 			retryable: isRetryableStatus(response.status)
 		};
 	};
+	const ping = async () => {
+		const response = await fetcher(`${apiUrl}/clivly/sdk/ping`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${config.apiKey}` }
+		});
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) {
+			const body = await response.json().catch(() => ({}));
+			return {
+				ok: true,
+				status: response.status,
+				reason: "ok",
+				retryable: false,
+				org: body?.org,
+				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
+			};
+		}
+		return {
+			ok: false,
+			status: response.status,
+			reason: pingReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
 	const doctor = () => runDoctor({
 		config,
-		connect
+		probe: ping
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
@@ -1144,6 +1241,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,

package/sdk.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-D87rV-tE.cjs");
-const require_sdk = require("./sdk-iqOXeWIp.cjs");
+const require_sdk = require("./sdk-BrQYA-GT.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.d.cts

@@ -1 +1,36 @@
-export {}
+import { a as ClivlyEntitiesConfig, v as defineClivlyConfig } from "./entity-config-DoUCXtq5.cjs";
+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-DRzOtaRT.cjs";
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: 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, 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/sdk.d.mts

@@ -1 +1,36 @@
-export {}
+import { a as ClivlyEntitiesConfig, v as defineClivlyConfig } from "./entity-config-DoUCXtq5.mjs";
+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-B4WE45TH.mjs";
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: 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, 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/sdk.mjs

@@ -1,3 +1,3 @@
 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";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-C2VL28du.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, defineClivlyConfig };

package/vite.d.cts

@@ -1,4 +1,4 @@
-import { t as ClivlySDK } from "./types-CsL0rFYh.cjs";
+import { o as ClivlySDK } from "./namespace-probe-DRzOtaRT.cjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 interface ClivlyViteOptions {

package/vite.d.mts

@@ -1,4 +1,4 @@
-import { t as ClivlySDK } from "./types-CsL0rFYh.mjs";
+import { o as ClivlySDK } from "./namespace-probe-B4WE45TH.mjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 interface ClivlyViteOptions {

package/types-CsL0rFYh.d.cts

@@ -1,155 +0,0 @@
-//#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 };

package/types-CsL0rFYh.d.mts

@@ -1,155 +0,0 @@
-//#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 };