@clivly/sdk 0.7.2 → 0.7.3

package/README.md

@@ -1,66 +1,36 @@
 # @clivly/sdk
 
-Connect an app to Clivly Cloud. The SDK sends heartbeats, reports schema
-discovery data, syncs source rows to Clivly over outbound HTTPS, and can expose
-a signed trigger route so Clivly can start a sync from the dashboard.
+Connect your app to Clivly Cloud. The SDK sends a heartbeat, reports your schema
+for entity mapping, and mirrors your contacts and companies into Clivly over
+outbound HTTPS. If you configure `syncTrigger`, Clivly can also call back into
+your app to start a sync from the dashboard.
 
-## Which package should I install?
+For the end-to-end onboarding flow, start with
+[`docs/guides/connecting-to-clivly-cloud.md`](../../docs/guides/connecting-to-clivly-cloud.md).
+This README stays focused on the SDK surface itself.
 
-For most new integrations, install the consolidated public package:
+## Install
 
 ```bash
 npm install clivly
 ```
 
-and import from:
+Clivly's stable packages publish on npm's `latest` tag. Use `@next` only when
+you are intentionally validating a prerelease build.
 
-```ts
-import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle } from "clivly/drizzle";
-```
+Add `drizzle-orm` when you use `clivly/drizzle`, and
+`vite` when you use the Vite/TanStack Start plugin.
 
-`@clivly/sdk` remains a public package if you prefer a direct dependency on the
-SDK package itself:
-
-```bash
-npm install @clivly/sdk
-```
-
-with imports from:
+## Usage
 
 ```ts
-import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
-import { fromDrizzle } from "@clivly/sdk/drizzle";
-```
-
-Stable releases publish on npm's `latest` tag. Use `@next` only when you are
-intentionally validating a prerelease build.
-
-Add `drizzle-orm` when you use the Drizzle helpers, and `vite` when you use the
-Vite/TanStack Start plugin.
-
-## Surface
-
-Public exports from this package:
-
-- `@clivly/sdk`:
-  `createClivlySDK`, `defineClivlyConfig`, `createChatSessionHandler`,
-  `ClivlyError`, `ClivlyNetworkError`, `ClivlyRateLimitError`,
-  `ClivlyAuthError`
-- `@clivly/sdk/drizzle`:
-  Drizzle source helpers such as `fromDrizzle`
-- `@clivly/sdk/vite`:
-  the Vite/TanStack Start lifecycle plugin
-- `@clivly/sdk/chat-session`:
-  chat-session handler helpers when you want that subpath explicitly
-
-## Basic usage
-
-```ts
-import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
-import { fromDrizzle } from "@clivly/sdk/drizzle";
+import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
+import { fromDrizzle } from "clivly/drizzle";
 import { db, participants, accounts } from "./db";
 
+// Declarative entity config — the non-deprecated source of truth. It maps your
+// host tables/columns onto CRM concepts, and `defineClivlyConfig` validates it
+// at load (warning on any non-canonical field key that would mirror as empty).
 const entities = defineClivlyConfig({
   entities: {
     participants: {
@@ -77,67 +47,62 @@ const entities = defineClivlyConfig({
 });
 
 const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!,
+  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… from Settings → API keys
   entities,
   source: {
-    contacts: fromDrizzle(db, participants, {
-      entity: "participants",
-      cursorField: "updatedAt",
-    }),
-    companies: fromDrizzle(db, accounts, {
-      entity: "accounts",
-      cursorField: "updatedAt",
-    }),
+    contacts: fromDrizzle(db, participants, { entity: "participants", cursorField: "updatedAt" }),
+    companies: fromDrizzle(db, accounts, { entity: "accounts", cursorField: "updatedAt" }),
   },
   sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
 });
 
-const status = await clivly.connect();
-if (!status.ok) {
-  throw new Error(`Clivly: ${status.reason}`);
-}
-
-await clivly.start();
-```
-
-`fromDrizzle` builds the keyset-paginated `fetchPage` function the SDK needs.
-`cursorField` and `idField` are Drizzle property keys such as `updatedAt`, not
-database column names such as `updated_at`. Non-Drizzle apps can provide their
-own `fetchPage` implementation.
+const status = await clivly.connect(); // rich result: { ok, status, reason, retryable, org? }
+if (!status.ok) throw new Error(`Clivly: ${status.reason}`);
+await clivly.start();      // heartbeat + backfill + interval delta sync
 
-## Remote sync trigger
-
-If you configure `syncTrigger`, Clivly can ask your app to run a sync from the
-dashboard:
-
-```ts
-const clivly = createClivlySDK({
+// Optional: let Clivly's dashboard start a sync in this app.
+const remote = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
-  source: { /* ... */ },
+  source: { /* … */ },
   syncTrigger: {
     path: "/api/clivly/tick",
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
-    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
+    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
   },
 });
 
 export async function POST(request: Request) {
-  return clivly.createClivlyHandler()(request);
+  return remote.createClivlyHandler()(request);
 }
 ```
 
-With `syncTrigger.url` and `syncTrigger.secret` configured, the SDK reports the
-trigger URL on each heartbeat and rejects unsigned or badly-signed requests.
-Without `syncTrigger`, cloud mode is push-only: Clivly can observe the app but
-cannot start a sync from the dashboard.
+`fromDrizzle` generates the keyset-paginated `fetchPage` the SDK needs, inferring the
+tie-breaker id from the table's primary key — pass `idField` to override.
+`cursorField` and `idField` are Drizzle property keys (`updatedAt`), not database
+column names (`updated_at`). Rows are keyed by your source column names; Clivly
+applies the field map you confirmed during onboarding, so re-mapping never needs
+a redeploy. Non-Drizzle hosts can still pass a hand-written `fetchPage` closure
+instead.
+
+With `syncTrigger.url` + `syncTrigger.secret` configured, the SDK reports the
+trigger URL on each heartbeat and rejects unsigned or badly-signed trigger
+requests. Without `syncTrigger`, cloud mode is push-only: Clivly can observe
+the app but cannot start a sync from the dashboard.
+
+If you rotate a remote-sync secret from Clivly's dashboard after the encryption
+rollout, Clivly stores it encrypted at rest. The server-side deployment must
+have `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` configured, while your app continues
+to use `CLIVLY_SYNC_TRIGGER_SECRET`. Existing plaintext rows remain valid during
+rollout, and older rows can be backfilled with
+`node ./scripts/backfill-sync-trigger-secrets.mjs --write`.
 
 ## Vite / TanStack Start
 
-For long-lived Vite dev servers, wire the SDK lifecycle through the plugin:
+For long-lived Vite dev servers, wire the SDK lifecycle through the Vite plugin:
 
 ```ts
-import { clivlyVite } from "@clivly/sdk/vite";
+import { clivlyVite } from "clivly/vite";
 import clivly from "./clivly.config";
 import { defineConfig } from "vite";
 
@@ -146,80 +111,115 @@ export default defineConfig({
 });
 ```
 
-The plugin calls `connect()` for a startup status line, then `start()` for the
-heartbeat and sync loop. It is dev-server only; use `runScheduled()` or
-`createClivlyHandler()` for request-scoped runtimes.
+The plugin calls `connect()` for a clear startup status line, then `start()` for
+the heartbeat and sync loop. It is dev-server only; use `runScheduled()` or
+`createClivlyHandler()` for serverless production runtimes.
+
+> **Legacy:** the flat `contactEntity` / `contactFields` form is still accepted but
+> **deprecated** — prefer the `entities` config above, which is the same model the
+> mapping table and sync engine share.
 
 ## Verify your setup
 
-If your instance lives in `clivly.config.ts`, the CLI can validate the setup:
+Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
 
 ```bash
-npx clivly ping
-npx clivly doctor
+npx clivly ping     # CLIVLY_SECRET_KEY + API reachability
+npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
 ```
 
-In code, `await clivly.doctor()` returns the same structured read-only checks.
+In a monorepo, pass the app config explicitly:
+
+```bash
+npx clivly doctor --config ./apps/web/clivly.config.ts
+```
+
+Or in code: `await clivly.doctor()` returns `{ ok, checks }` — the same six read-only checks.
 
 ## Serverless / edge
 
-On request-scoped runtimes such as Cloudflare Workers, Vercel, or Lambda, do
-not call `start()`. Use `runScheduled()` or mount `createClivlyHandler()`
-instead:
+On request-scoped runtimes (Cloudflare Workers, Vercel, Lambda) there is no long-lived
+process, so `start()`'s `setInterval` keep-alive loop can't persist — it stops ticking after
+the first response. **Don't call `start()` there.** Instead drive one-shot runs from a
+scheduled trigger with `runScheduled()`, or mount `createClivlyHandler()` at a route:
 
 ```ts
+// Cloudflare Workers
 export default {
-  scheduled: () => clivly.runScheduled(),
-  fetch: clivly.createClivlyHandler(),
+  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
+  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping / external scheduler
 };
 ```
 
-`runScheduled()` throws on a failed push so cron jobs surface failures.
-`createClivlyHandler()` returns `200` on success and `500` on a failed run.
+`runScheduled()` throws if a sync push fails (so a cron run is marked failed);
+`createClivlyHandler()` returns `200` when the triggered run finishes successfully,
+`500` otherwise. If the run carries a Clivly-issued run id, the SDK also reports
+the final outcome back to Clivly so the dashboard reflects `running` vs
+`succeeded` vs `failed` truthfully. `start()` emits a warning if it detects a
+serverless runtime. Verify a connection from the terminal any time with
+`npx clivly ping`.
 
 ### Persisting the delta cursor
 
-By default the delta cursor lives in memory. For serverless runtimes, pass a
-persistent `cursorStore`:
+Delta sync tracks a per-entity cursor so each run only pages rows changed since the last one.
+By default that cursor lives in memory — fine for a long-lived process, but **lost on every
+serverless cold start**, so a fresh isolate would re-page the whole entity. Pass a
+`cursorStore` backed by your own KV/DB to persist it:
 
 ```ts
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
-  source: { /* ... */ },
+  source: { /* … */ },
   cursorStore: {
+    // `SyncCursor` is { id: string; time: Date } — serialize `time` (e.g. ISO string).
     get: async (entity) => {
       const raw = await kv.get(`clivly:cursor:${entity}`);
       return raw ? { id: raw.id, time: new Date(raw.time) } : null;
     },
     set: (entity, cursor) =>
-      kv.put(
-        `clivly:cursor:${entity}`,
-        cursor ? { id: cursor.id, time: cursor.time.toISOString() } : null
-      ),
+      kv.put(`clivly:cursor:${entity}`, cursor && { id: cursor.id, time: cursor.time.toISOString() }),
   },
 });
 ```
 
-Delta sync is at-least-once. Without a persisted cursor after a cold start,
-rows may be re-sent; they are not silently skipped.
+Delta sync is **at-least-once**: after a cold start with no persisted cursor, rows since the
+last push may be re-sent (the server dedupes by id) — it never silently skips rows. Use
+`sync({ mode: "full" })` when you need the server to reconcile deletions (archive-on-leave).
 
-## Known limitations
+## Many-to-many company membership
 
-- `start()` is for long-lived runtimes only.
-- `fromDrizzle` is the first-class generated source path today.
-- The legacy flat `contactEntity` / `contactFields` config is still accepted but
-  deprecated in favor of `defineClivlyConfig({ entities: ... })`.
+If a mapping links contacts to companies through a join table
+(`via: { through: … }`), that entity's source must return **one row per
+membership**, each row carrying the join table's foreign-key column.
 
-## More docs
+```ts
+// Ada belongs to two organizations: two rows, differing only in org_id.
+{ id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "acme"   }
+{ id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "globex" }
+```
 
-- Cloud onboarding guide:
-  [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
-- CLI reference:
-  [packages/cli/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/cli/README.md)
-- Release notes:
-  [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+This mirrors what the embedded model produces with `LEFT JOIN <join table>`, and
+it is what lets Clivly keep one CRM row per membership instead of collapsing the
+person onto whichever company happened to come first.
 
-## License
+A person with no membership may omit the column entirely or send it as `null` —
+both are accepted. But if **no** pushed row carries the column, the push is
+rejected with `400 invalid_config`: silently keeping one membership would be
+worse than failing, because the row counts look correct either way.
+
+## Known limitations
+
+- `start()` is for long-lived runtimes only. On serverless/edge, use
+  `runScheduled()` or `createClivlyHandler()`.
+- `fromDrizzle` is the first-class generated source path today. Non-Drizzle hosts
+  should provide a hand-written `fetchPage`.
+- The flat `contactEntity` / `contactFields` config still works but is deprecated
+  in favor of `defineClivlyConfig({ entities: ... })`.
+
+## More docs
 
-MIT
+- Onboarding guide:
+  [`docs/guides/connecting-to-clivly-cloud.md`](../../docs/guides/connecting-to-clivly-cloud.md)
+- CLI docs: [`../cli/README.md`](../cli/README.md)
+- Release notes: [`../../CHANGELOG.md`](../../CHANGELOG.md)

package/dist/chat-session.d.cts

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

package/dist/chat-session.d.mts

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

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.cjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-DPSn54S6.cjs";
 import { Table } from "drizzle-orm";
 import { discoverFromDrizzle } from "@clivly/core/drizzle";
 //#region src/drizzle.d.ts

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-DTaz5mLi.mjs";
+import { m as NamespaceIntrospector, p as SyncSource } from "./types-DPSn54S6.mjs";
 import { Table } from "drizzle-orm";
 import { discoverFromDrizzle } from "@clivly/core/drizzle";
 //#region src/drizzle.d.ts

package/dist/index.cjs

@@ -279,6 +279,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region 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[require_drizzle_meta.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);
@@ -307,32 +347,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[require_drizzle_meta.DRIZZLE_META];
 		if (!meta) {
@@ -352,6 +372,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,
@@ -371,10 +399,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}).`
 	});
@@ -724,6 +787,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";
@@ -732,6 +796,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;
@@ -963,9 +1031,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();
@@ -1058,6 +1155,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DTaz5mLi.cjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DPSn54S6.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DTaz5mLi.mjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, i as ClivlyConnectResult, l as CursorStore, n as ChatWidgetVisitor, o as ClivlySDKConfig, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DPSn54S6.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, defineClivlyConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -278,6 +278,46 @@ function errorMessage(error) {
 }
 //#endregion
 //#region 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);
@@ -306,32 +346,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) {
@@ -351,6 +371,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,
@@ -370,10 +398,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}).`
 	});
@@ -723,6 +786,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";
@@ -731,6 +795,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;
@@ -962,9 +1030,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();
@@ -1057,6 +1154,7 @@ function createClivlySDK(config) {
 		stop,
 		heartbeat,
 		connect,
+		ping,
 		doctor,
 		runScheduled,
 		createClivlyHandler,

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

@@ -225,14 +225,33 @@ interface DoctorCheck {
   ok: boolean;
   /** True when the check could not run (e.g. a hand-written source). */
   skipped?: boolean;
+  /**
+   * True when the setup works but carries a risk worth stating.
+   *
+   * Distinct from `ok: false`, which means "this is broken, fix it before you
+   * rely on it". A warning is for a configuration that will run and sync, yet
+   * behaves in a way the developer probably did not intend — the cursor check
+   * below is the motivating case: syncing from an `id` column succeeds, mirrors
+   * every insert, and silently never re-syncs an edited row.
+   *
+   * Warnings do not fail `doctor`. Reporting them as failures would train
+   * people to ignore a red ladder on a working setup, which is worse than not
+   * reporting them at all.
+   */
+  warn?: 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";
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "server_too_old" | "network_error";
 interface ClivlyConnectResult {
+  /**
+   * When the org's app last heartbeated, or null if it never has. Set only by
+   * `ping()` — `connect()` IS a heartbeat, so the question is meaningless there.
+   */
+  appLastSeenAt?: string | null;
   ok: boolean;
   /** Org resolved from a successful heartbeat, when the server returns it. */
   org?: {
@@ -310,6 +329,14 @@ interface ClivlySDK {
    * loop and back-compat; use `connect()` when you need the failure reason.
    */
   heartbeat(): Promise<boolean>;
+  /**
+   * Read-only diagnostic probe. Proves the API key is valid and Clivly is
+   * reachable, and resolves the org — without reporting anything about the
+   * host app. Use this for `clivly status` and other diagnostics; use
+   * `connect()` only from the running app, which is entitled to report its
+   * own state.
+   */
+  ping(): Promise<ClivlyConnectResult>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

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

@@ -225,14 +225,33 @@ interface DoctorCheck {
   ok: boolean;
   /** True when the check could not run (e.g. a hand-written source). */
   skipped?: boolean;
+  /**
+   * True when the setup works but carries a risk worth stating.
+   *
+   * Distinct from `ok: false`, which means "this is broken, fix it before you
+   * rely on it". A warning is for a configuration that will run and sync, yet
+   * behaves in a way the developer probably did not intend — the cursor check
+   * below is the motivating case: syncing from an `id` column succeeds, mirrors
+   * every insert, and silently never re-syncs an edited row.
+   *
+   * Warnings do not fail `doctor`. Reporting them as failures would train
+   * people to ignore a red ladder on a working setup, which is worse than not
+   * reporting them at all.
+   */
+  warn?: 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";
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "server_too_old" | "network_error";
 interface ClivlyConnectResult {
+  /**
+   * When the org's app last heartbeated, or null if it never has. Set only by
+   * `ping()` — `connect()` IS a heartbeat, so the question is meaningless there.
+   */
+  appLastSeenAt?: string | null;
   ok: boolean;
   /** Org resolved from a successful heartbeat, when the server returns it. */
   org?: {
@@ -310,6 +329,14 @@ interface ClivlySDK {
    * loop and back-compat; use `connect()` when you need the failure reason.
    */
   heartbeat(): Promise<boolean>;
+  /**
+   * Read-only diagnostic probe. Proves the API key is valid and Clivly is
+   * reachable, and resolves the org — without reporting anything about the
+   * host app. Use this for `clivly status` and other diagnostics; use
+   * `connect()` only from the running app, which is entitled to report its
+   * own state.
+   */
+  ping(): Promise<ClivlyConnectResult>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-DTaz5mLi.cjs";
+import { a as ClivlySDK } from "./types-DPSn54S6.cjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-DTaz5mLi.mjs";
+import { a as ClivlySDK } from "./types-DPSn54S6.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.7.2"
+    "@clivly/core": "0.7.3"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",