@clivly/sdk 0.7.2 → 0.7.4

package/README.md

@@ -1,193 +1,333 @@
 # @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?
+Clivly never connects to your database — the SDK runs inside your app and is the
+only thing that touches your data.
 
-For most new integrations, install the consolidated public package:
+> **The canonical end-to-end integration guide is
+> [Connecting to Clivly Cloud](../../docs/guides/connecting-to-clivly-cloud.md).**
+> This README is the API-level reference for the SDK surface itself.
+
+## Prerequisites
+
+| Requirement | Version / note |
+| --- | --- |
+| Node.js | **≥ 22** |
+| `drizzle-orm` | Optional peer — only for `clivly/drizzle` |
+| `vite` | Optional peer — only for `clivly/vite` |
+| A Clivly org + secret key | Dashboard → **Connect app**, or **Settings → API keys** |
+
+## Installation
 
 ```bash
 npm install clivly
 ```
 
-and import from:
+Install `clivly`, not `@clivly/sdk`. The `clivly` package re-exports this SDK at
+`clivly/sdk` and is what `clivly init` installs, so you get the CLI and the
+runtime from one dependency at one version.
+
+> `@clivly/sdk` is published and works standalone if you want the runtime
+> without the CLI. Every import path below then drops the `clivly/` prefix:
+> `@clivly/sdk`, `@clivly/sdk/drizzle`, `@clivly/sdk/vite`,
+> `@clivly/sdk/chat-session`.
+
+> **Never `import` from the bare `clivly` specifier.** That entry is the CLI
+> binary; it pulls `node:fs` and `node:child_process` in at module scope and
+> throws on Workers and other edge runtimes. Use `clivly/sdk`.
+
+## Five-minute quick start
 
 ```ts
+// clivly.config.ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle } from "clivly/drizzle";
-```
+import { discoverFromDrizzle, fromDrizzle } from "clivly/drizzle";
+import * as schema from "./db/schema";
+import { db } from "./db";
 
-`@clivly/sdk` remains a public package if you prefer a direct dependency on the
-SDK package itself:
+const entities = defineClivlyConfig({
+  entities: {
+    users: {
+      concept: "contact",
+      source: "users",
+      fields: { name: "full_name", email: "email" },
+    },
+  },
+});
 
-```bash
-npm install @clivly/sdk
+export default createClivlySDK({
+  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… — never ships to a browser
+  entities,
+  schema: discoverFromDrizzle(schema),
+  source: {
+    contacts: fromDrizzle(db, schema.users, {
+      entity: "users",
+      cursorField: "updatedAt",
+    }),
+  },
+});
 ```
 
-with imports from:
-
 ```ts
-import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
-import { fromDrizzle } from "@clivly/sdk/drizzle";
+// somewhere that runs at boot
+import clivly from "./clivly.config";
+
+const result = await clivly.connect();
+if (!result.ok) throw new Error(`Clivly: ${result.reason}`);
+
+await clivly.start(); // long-lived hosts only — see below
 ```
 
-Stable releases publish on npm's `latest` tag. Use `@next` only when you are
-intentionally validating a prerelease build.
+`createClivlySDK(...)` is a **pure factory**. Constructing it — or importing a
+module that constructs it — does nothing on its own: no heartbeat, no sync, no
+network call. That keeps the SDK tree-shakeable (`sideEffects: false`), but it
+means a bare `import "./clivly.config"` will never connect. You must call an
+entry point.
 
-Add `drizzle-orm` when you use the Drizzle helpers, and `vite` when you use the
-Vite/TanStack Start plugin.
+## Step-by-step configuration
 
-## Surface
+### Choose the runtime entry point
 
-Public exports from this package:
+The single most consequential decision in the setup.
 
-- `@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
+| Host runtime | Use | Why |
+| --- | --- | --- |
+| Long-lived Node server, Vite dev | `clivlyVite(sdk)` or `await sdk.start()` | The `setInterval` keep-alive loop persists |
+| Cloudflare Workers, Vercel, Lambda | `sdk.createClivlyHandler()` at a route, and/or `sdk.runScheduled()` from cron | `setInterval` does **not** survive between invocations |
+| One-off health check | `await sdk.connect()` | Structured `{ ok, status, reason, retryable, org? }` |
 
-## Basic usage
+`start()` emits a console warning when it detects a serverless runtime, because
+there it stops ticking after the first response.
 
-```ts
-import { createClivlySDK, defineClivlyConfig } from "@clivly/sdk";
-import { fromDrizzle } from "@clivly/sdk/drizzle";
-import { db, participants, accounts } from "./db";
+### Entities vs. sources — the distinction that bites
 
+```ts
 const entities = defineClivlyConfig({
   entities: {
-    participants: {
-      concept: "contact",
-      source: "participants",
+    participants: {              // ← your entity key, arbitrary
+      concept: "contact",        // ← CRM concept
+      source: "participants",    // ← a HOST TABLE NAME
       fields: { name: "full_name", email: "email" },
     },
-    accounts: {
-      concept: "company",
-      source: "accounts",
-      fields: { name: "legal_name", domain: "website" },
-    },
   },
 });
 
-const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!,
+createClivlySDK({
   entities,
-  source: {
-    contacts: fromDrizzle(db, participants, {
-      entity: "participants",
-      cursorField: "updatedAt",
-    }),
-    companies: fromDrizzle(db, accounts, {
-      entity: "accounts",
-      cursorField: "updatedAt",
-    }),
+  source: {                      // ← keyed by CRM CONCEPT, never by entity key
+    contacts: fromDrizzle(db, participants, { … }),
   },
-  sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
 });
+```
 
-const status = await clivly.connect();
-if (!status.ok) {
-  throw new Error(`Clivly: ${status.reason}`);
-}
+`config.source` accepts only `contacts` / `companies` / `deals` / `custom`.
+Conflating the two axes means an entity resolves to no source and silently syncs
+nothing, without erroring. `clivly status` cross-checks this for you.
 
-await clivly.start();
-```
+### Sources
 
-`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.
+`fromDrizzle` generates the keyset-paginated `fetchPage` the SDK needs,
+inferring the tie-breaker id from the table's primary key — pass `idField` to
+override.
 
-## Remote sync trigger
+```ts
+fromDrizzle(db, schema.users, {
+  entity: "users",        // the host table name
+  cursorField: "updatedAt", // Drizzle PROPERTY key, not the DB column
+  idField: "id",            // optional; defaults to the primary key
+})
+```
 
-If you configure `syncTrigger`, Clivly can ask your app to run a sync from the
-dashboard:
+`cursorField` and `idField` are Drizzle property keys (`updatedAt`), **not**
+database column names (`updated_at`). `entities[].fields` goes the other way:
+its values are real **column** names (`full_name`), which is what
+`discoverFromDrizzle` reports and what the dashboard's mapping table stores.
+Clivly applies that field map on its side, so re-mapping never needs a
+redeploy.
+
+`fromDrizzle` projects every column under its real database name, so rows arrive
+column-keyed and the field map resolves. The `SyncSource` it returns therefore
+reports `cursorField` / `idField` as **column names** too — you still pass
+Drizzle property keys in, and it translates once.
+
+> **Upgrading from `clivly@0.7.3` or earlier?** Those versions returned rows
+> keyed by Drizzle **property** names, so on a snake_case schema any field whose
+> property key differed from its column name mirrored as empty — silently
+> (`email` worked by coincidence). `clivly status` reports it as
+> `❌ Field mapping dry run … missing mapped column(s): name → full_name`.
+> If you worked around it by mapping to the Drizzle key
+> (`fields: { name: "fullName" }`), **revert that to the column name** on
+> upgrade — the workaround is what breaks now.
+
+Non-Drizzle hosts pass a hand-written `fetchPage` instead. Page on the compound
+`(cursorField, idField)` watermark:
 
 ```ts
-const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!,
-  entities,
-  source: { /* ... */ },
-  syncTrigger: {
-    path: "/api/clivly/tick",
-    url: process.env.CLIVLY_SYNC_TRIGGER_URL,
-    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
+source: {
+  contacts: {
+    entity: "users",
+    cursorField: "updated_at",
+    idField: "id",
+    async fetchPage({ since, limit }) {
+      // WHERE (updated_at, id) > (:since.time, :since.id)
+      // ORDER BY updated_at ASC, id ASC LIMIT :limit
+      // (when `since` is null, return the first page ordered the same way)
+      return await myDb.query(/* … */);
+    },
   },
-});
+},
+```
 
-export async function POST(request: Request) {
-  return clivly.createClivlyHandler()(request);
-}
+### Remote sync trigger
+
+```ts
+syncTrigger: {
+  path: "/api/clivly/tick",
+  url: process.env.CLIVLY_SYNC_TRIGGER_URL,
+  secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
+},
 ```
 
-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.
+```ts
+// mount it — this is a plain (Request) => Promise<Response>
+export const POST = (request: Request) => clivly.createClivlyHandler()(request);
+```
+
+With `url` + `secret` configured, the SDK reports the trigger URL on each
+heartbeat and rejects unsigned or badly-signed requests with `401`. **Without a
+secret the route stays open to anyone who can reach it** — always set one if the
+route is publicly routable. Without `syncTrigger` at all, cloud mode is
+push-only: Clivly can observe the app but cannot start a sync from the
+dashboard.
+
+`url` is optional — the SDK discovers it from the hosting platform's environment
+or from the first request the route serves. Set it only to pin an address the
+SDK cannot infer.
+
+## Complete working example
 
-## Vite / TanStack Start
+See [the guide's worked example](../../docs/guides/connecting-to-clivly-cloud.md#6-complete-working-example)
+for a full Next.js + Drizzle + Vercel setup with `.env`, config, and route file.
 
-For long-lived Vite dev servers, wire the SDK lifecycle through the plugin:
+### Vite / TanStack Start
 
 ```ts
-import { clivlyVite } from "@clivly/sdk/vite";
-import clivly from "./clivly.config";
+// vite.config.ts
 import { defineConfig } from "vite";
+import { clivlyVite } from "clivly/vite";
+import clivly from "./clivly.config";
 
 export default defineConfig({
   plugins: [clivlyVite(clivly)],
 });
 ```
 
-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.
-
-## Verify your setup
+The plugin calls `connect()` for a clear startup status line, then `start()` for
+the heartbeat and sync loop, and `stop()` on shutdown. It is **dev-server
+only**; use `runScheduled()` or `createClivlyHandler()` for serverless
+production runtimes.
 
-If your instance lives in `clivly.config.ts`, the CLI can validate the setup:
+### Serverless / edge
 
-```bash
-npx clivly ping
-npx clivly doctor
+```ts
+// Cloudflare Workers
+export default {
+  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
+  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping
+};
 ```
 
-In code, `await clivly.doctor()` returns the same structured read-only checks.
+`runScheduled()` throws if a sync push fails, so a cron run is marked failed.
+`createClivlyHandler()` returns `200` when the triggered run finishes
+successfully and `500` otherwise, with `{ ok, runId, durationMs }` or
+`{ ok: false, runId, error }` in the body — which is how Clivly learns the
+outcome of a run it triggered.
 
-## Serverless / edge
+## Verify the integration
 
-On request-scoped runtimes such as Cloudflare Workers, Vercel, or Lambda, do
-not call `start()`. Use `runScheduled()` or mount `createClivlyHandler()`
-instead:
+```bash
+npx clivly status                                     # the whole ladder
+npx clivly status --config ./apps/web/clivly.config.ts # in a monorepo
+```
+
+Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`)
+so the CLI can find it. `ping`, `connect` and `doctor` remain as deprecated
+aliases running parts of the same ladder.
+
+In code, `await clivly.doctor()` returns `{ ok, checks }` — read-only, never
+mutating. The checks it currently runs:
+
+| Check | Verifies |
+| --- | --- |
+| API key present | `apiKey` is set |
+| Entities configured | At least one entity |
+| Sources configured | `source` is present and reachable |
+| Concept coverage | Every configured concept has a source |
+| Cursor / id columns | Drizzle sources page on a column that changes on edit |
+| Sample fetch | `fetchPage` actually returns rows |
+| Mapping dry-run | Each entity's compiled view runs |
+| Custom object slugs | Custom object types are valid |
+| Heartbeat | Clivly is reachable with this key |
+| Namespace reachable | Every mapped table/column exists (needs `introspector`) |
+
+`ok` is the AND of every non-skipped check. Checks can also come back
+`warn: true` — a working setup with a risk worth stating, such as paging on a
+column that never changes when a row is edited. **Warnings do not fail the
+report**, because training people to ignore a red ladder on a working setup
+would be worse.
+
+`namespaceReady` in your config is *self-reported* and sent as-is on every
+heartbeat; only `doctor()` with an `introspector` performs a live check:
 
 ```ts
-export default {
-  scheduled: () => clivly.runScheduled(),
-  fetch: clivly.createClivlyHandler(),
-};
+import { drizzleIntrospector } from "clivly/drizzle";
+
+createClivlySDK({ /* … */, introspector: drizzleIntrospector(db) });
 ```
 
-`runScheduled()` throws on a failed push so cron jobs surface failures.
-`createClivlyHandler()` returns `200` on success and `500` on a failed run.
+## Common errors and troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Nothing connects, no error | You imported the config but never called an entry point | Call `start()` / `runScheduled()`, or add `clivlyVite(sdk)` |
+| `reason: "invalid_api_key"` | `CLIVLY_SECRET_KEY` missing, wrong, or revoked by a regeneration | Re-run `npx clivly login` |
+| Sync works once on serverless, then stops | `start()`'s `setInterval` cannot persist | Use `runScheduled()` or `createClivlyHandler()` |
+| Every cold start re-reads everything | The default cursor store is in-memory | Pass a persistent [`cursorStore`](#persisting-the-delta-cursor) |
+| `401` on the tick route | Trigger secret differs between your app and Clivly | Redeploy with the current `CLIVLY_SYNC_TRIGGER_SECRET` |
+| An entity syncs nothing, silently | `source` keyed by entity key instead of CRM concept | Key it `contacts` / `companies` / `deals` / `custom` |
+| Rows sync on insert but never on edit | `cursorField` does not change on edit | Add an `updated_at` column and use it. `doctor()` warns about this |
+| `Field mapping dry run … missing mapped column(s)` | You are on `clivly@0.7.3` or earlier, where `fromDrizzle` returned Drizzle property keys | Upgrade — see the upgrade note above |
+| Push fails for one entity | See the thrown message | It names the HTTP status and what to check |
+| Config throws at import on Workers | Something in `clivly.config.ts` touched the filesystem | See [the edge contract](../../docs/guides/connecting-to-clivly-cloud.md#the-edge-contract-what-may-go-in-clivlyconfigts) |
+
+A failed push throws a message naming the cause, not a bare "push failed" — e.g.
+*"the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this
+org"*, or *"couldn't reach Clivly at https://api.clivly.com"*.
+
+Errors are also available as classes: `ClivlyError`, `ClivlyAuthError`,
+`ClivlyNetworkError`, `ClivlyRateLimitError`. `ClivlyError.from(result)` turns a
+failed `connect()` result into a throwable.
+
+## Advanced configuration
 
 ### 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.
 
 ```ts
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
-  source: { /* ... */ },
+  source: { /* … */ },
   cursorStore: {
+    // `SyncCursor` is { id: string; time: Date } — serialize `time` yourself.
     get: async (entity) => {
       const raw = await kv.get(`clivly:cursor:${entity}`);
       return raw ? { id: raw.id, time: new Date(raw.time) } : null;
@@ -195,30 +335,131 @@ const clivly = createClivlySDK({
     set: (entity, cursor) =>
       kv.put(
         `clivly:cursor:${entity}`,
-        cursor ? { id: cursor.id, time: cursor.time.toISOString() } : null
+        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); a delta cannot tell absence from
+"unchanged".
 
-## Known limitations
+### Sync ordering
+
+`runSync` pushes **companies first**, then contacts, then deals, then custom
+objects, so contact→company links resolve on the server.
+
+### 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" }
+```
+
+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.
+
+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.
+
+### Retry policy
+
+```ts
+retry: {
+  maxAttempts: 3,   // total attempts including the first; minimum 1
+  baseDelayMs: 500, // doubled each attempt, plus jitter
+}
+```
+
+Network errors, `429` and `5xx` are retried; a `Retry-After` header on a `429`
+is honoured. Other `4xx` responses return immediately.
+
+## Configuration reference
+
+### `createClivlySDK(config)`
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | — | **Required.** `sk_live_…` |
+| `apiUrl` | `string` | `https://api.clivly.com` | Non-default backend |
+| `entities` | `ClivlyEntitiesConfig` | — | From `defineClivlyConfig({ entities })` |
+| `schema` | `DiscoveredTable[]` | — | Use `discoverFromDrizzle(schema)` |
+| `source` | `{ contacts, companies?, deals?, custom? }` | — | Keyed by CRM concept. `contacts` is required when `source` is present |
+| `cursorStore` | `CursorStore` | in-memory | Persist on serverless |
+| `heartbeatIntervalMs` | `number` | `60000` | |
+| `sync.onBoot` | `boolean` | `true` | Only affects `start()` |
+| `sync.intervalMs` | `number` | `heartbeatIntervalMs` | |
+| `sync.batchSize` | `number` | `500` | Rows per page |
+| `retry.maxAttempts` / `retry.baseDelayMs` | `number` | `3` / `500` | |
+| `syncTrigger.path` / `.url` / `.secret` | `string` | — | See above |
+| `verifyToken` | `string` | — | For `createAuthVerifyHandler`. **Nothing calls that endpoint today** |
+| `introspector` | `NamespaceIntrospector` | — | `drizzleIntrospector(db)`. Used only by `doctor()` |
+| `namespaceReady` | `boolean` | `false` | Self-reported; no live check |
+| `env` | `Record<string, string \| undefined>` | `process.env` | For trigger-URL discovery in non-Node runtimes |
+| `framework` / `orm` / `sdkVersion` | `string` | — | Reported for dashboard display |
+| `contactEntity` / `contactFields` | `string` / `string[]` | — | **Deprecated.** Use `entities` |
+| `experimental` | `object` | — | **Not implemented.** `tunnelToken` and `writeBack` are reserved and have no effect |
+
+### `ClivlySDK` methods
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `connect()` | `Promise<ClivlyConnectResult>` | One heartbeat, structured. Never throws |
+| `heartbeat()` | `Promise<boolean>` | One heartbeat, boolean |
+| `start()` | `Promise<void>` | Heartbeat + boot sync + timers. Long-lived hosts only |
+| `stop()` | `void` | Clears the timers |
+| `sync(options?)` | `Promise<void>` | `{ mode?: "delta" \| "full", runId?: string }`. Throws on push failure |
+| `runScheduled(options?)` | `Promise<void>` | One heartbeat + one sync, no timers. Throws on push failure |
+| `createClivlyHandler()` | `(Request) => Promise<Response>` | Mount at a route |
+| `createAuthVerifyHandler(resolveUser)` | `(Request) => Promise<Response>` | `503` unless `verifyToken` is set |
+| `doctor()` | `Promise<DoctorReport>` | `{ ok, checks }` |
+
+### `ClivlyConnectResult.reason`
+
+`ok` · `invalid_api_key` (401) · `forbidden` (403) · `rate_limited` (429) ·
+`server_error` (5xx) · `client_error` (other 4xx) · `network_error` (no
+response).
+
+### Subpath exports
+
+| From `clivly` | From `@clivly/sdk` | Contents |
+| --- | --- | --- |
+| `clivly/sdk` | `@clivly/sdk` | `createClivlySDK`, `defineClivlyConfig`, `createChatSessionHandler`, error classes, all types |
+| `clivly/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector` |
+| `clivly/vite` | `@clivly/sdk/vite` | `clivlyVite` |
+| — | `@clivly/sdk/chat-session` | `createChatSessionHandler` (also on the root) |
+
+## Known limitations
 
-- 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)
+- `start()` is for long-lived runtimes only. On serverless/edge, use
+  `runScheduled()` or `createClivlyHandler()`.
+- `fromDrizzle` is the only generated source path. Non-Drizzle hosts write
+  `fetchPage` by hand.
+- The flat `contactEntity` / `contactFields` config still works but is
+  deprecated in favour of `defineClivlyConfig({ entities: … })`.
+- `config.experimental` (tunnel token, CRM write-back) is **reserved and does
+  nothing today**.
+- `createAuthVerifyHandler` is inert — no Clivly Cloud consumer calls
+  `/clivly/auth/verify` yet.
+
+## Related documentation
+
+- **[Connecting to Clivly Cloud](../../docs/guides/connecting-to-clivly-cloud.md)** — the canonical end-to-end guide
+- [`clivly` CLI README](../cli/README.md) — every command and flag
+- [`@clivly/core` README](../core/README.md) — entity config, `$raw` filters
+- [`STABILITY.md`](../../STABILITY.md) — import tiers before 1.0
+- [`CHANGELOG.md`](../../CHANGELOG.md) — release notes
 
 ## License
 

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.cjs

@@ -65,11 +65,15 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
 	};
 	const meta = {
 		columnKeys: Object.keys(columns),

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/drizzle.mjs

@@ -64,11 +64,15 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${getTableName(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${getTableName(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
 	};
 	const meta = {
 		columnKeys: Object.keys(columns),

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) {
@@ -344,7 +364,7 @@ async function runDoctor(args) {
 			});
 			continue;
 		}
-		const idField = source.idField ?? "id";
+		const idField = meta.idField ?? source.idField ?? "id";
 		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
 		checks.push({
 			name: `Cursor/id columns exist (${source.entity})`,
@@ -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) {
@@ -343,7 +363,7 @@ async function runDoctor(args) {
 			});
 			continue;
 		}
-		const idField = source.idField ?? "id";
+		const idField = meta.idField ?? source.idField ?? "id";
 		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
 		checks.push({
 			name: `Cursor/id columns exist (${source.entity})`,
@@ -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.4",
   "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.4"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",