@clivly/sdk 0.7.3 → 0.7.4

package/README.md

@@ -5,106 +5,221 @@ 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.
 
-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.
+Clivly never connects to your database — the SDK runs inside your app and is the
+only thing that touches your data.
 
-## Install
+> **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
 ```
 
-Clivly's stable packages publish on npm's `latest` tag. Use `@next` only when
-you are intentionally validating a prerelease build.
+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.
 
-Add `drizzle-orm` when you use `clivly/drizzle`, and
-`vite` when you use the Vite/TanStack Start plugin.
+> `@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`.
 
-## Usage
+> **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 { db, participants, accounts } from "./db";
+import { discoverFromDrizzle, fromDrizzle } from "clivly/drizzle";
+import * as schema from "./db/schema";
+import { db } 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: {
+    users: {
       concept: "contact",
-      source: "participants",
+      source: "users",
       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!, // sk_live_… from Settings → API keys
+export default createClivlySDK({
+  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… — never ships to a browser
   entities,
+  schema: discoverFromDrizzle(schema),
   source: {
-    contacts: fromDrizzle(db, participants, { entity: "participants", cursorField: "updatedAt" }),
-    companies: fromDrizzle(db, accounts, { entity: "accounts", cursorField: "updatedAt" }),
+    contacts: fromDrizzle(db, schema.users, {
+      entity: "users",
+      cursorField: "updatedAt",
+    }),
   },
-  sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
 });
+```
 
-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
+```ts
+// somewhere that runs at boot
+import clivly from "./clivly.config";
 
-// Optional: let Clivly's dashboard start a sync in this app.
-const remote = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!,
+const result = await clivly.connect();
+if (!result.ok) throw new Error(`Clivly: ${result.reason}`);
+
+await clivly.start(); // long-lived hosts only — see below
+```
+
+`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.
+
+## Step-by-step configuration
+
+### Choose the runtime entry point
+
+The single most consequential decision in the setup.
+
+| 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? }` |
+
+`start()` emits a console warning when it detects a serverless runtime, because
+there it stops ticking after the first response.
+
+### Entities vs. sources — the distinction that bites
+
+```ts
+const entities = defineClivlyConfig({
+  entities: {
+    participants: {              // ← your entity key, arbitrary
+      concept: "contact",        // ← CRM concept
+      source: "participants",    // ← a HOST TABLE NAME
+      fields: { name: "full_name", email: "email" },
+    },
+  },
+});
+
+createClivlySDK({
   entities,
-  source: { /* … */ },
-  syncTrigger: {
-    path: "/api/clivly/tick",
-    url: process.env.CLIVLY_SYNC_TRIGGER_URL,
-    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET, // whsec_… from Integrations → Remote sync
+  source: {                      // ← keyed by CRM CONCEPT, never by entity key
+    contacts: fromDrizzle(db, participants, { … }),
   },
 });
+```
 
-export async function POST(request: Request) {
-  return remote.createClivlyHandler()(request);
-}
+`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.
+
+### Sources
+
+`fromDrizzle` generates the keyset-paginated `fetchPage` the SDK needs,
+inferring the tie-breaker id from the table's primary key — pass `idField` to
+override.
+
+```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
+})
+```
+
+`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
+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(/* … */);
+    },
+  },
+},
+```
+
+### 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
+},
+```
+
+```ts
+// mount it — this is a plain (Request) => Promise<Response>
+export const POST = (request: Request) => clivly.createClivlyHandler()(request);
 ```
 
-`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 `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.
 
-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.
+`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.
 
-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`.
+## 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 Vite plugin:
+### Vite / TanStack Start
 
 ```ts
+// vite.config.ts
+import { defineConfig } from "vite";
 import { clivlyVite } from "clivly/vite";
 import clivly from "./clivly.config";
-import { defineConfig } from "vite";
 
 export default defineConfig({
   plugins: [clivlyVite(clivly)],
@@ -112,59 +227,99 @@ export default defineConfig({
 ```
 
 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.
+the heartbeat and sync loop, and `stop()` on shutdown. It is **dev-server
+only**; use `runScheduled()` or `createClivlyHandler()` for serverless
+production runtimes.
+
+### Serverless / edge
 
-> **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.
+```ts
+// Cloudflare Workers
+export default {
+  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
+  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping
+};
+```
 
-## Verify your setup
+`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.
 
-Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
+## Verify the integration
 
 ```bash
-npx clivly ping     # CLIVLY_SECRET_KEY + API reachability
-npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
+npx clivly status                                     # the whole ladder
+npx clivly status --config ./apps/web/clivly.config.ts # in a monorepo
 ```
 
-In a monorepo, pass the app config explicitly:
+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:
 
-```bash
-npx clivly doctor --config ./apps/web/clivly.config.ts
+```ts
+import { drizzleIntrospector } from "clivly/drizzle";
+
+createClivlySDK({ /* … */, introspector: drizzleIntrospector(db) });
 ```
 
-Or in code: `await clivly.doctor()` returns `{ ok, checks }` — the same six read-only checks.
+## Common errors and troubleshooting
 
-## Serverless / edge
+| 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) |
 
-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:
+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"*.
 
-```ts
-// Cloudflare Workers
-export default {
-  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
-  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping / external scheduler
-};
-```
+Errors are also available as classes: `ClivlyError`, `ClivlyAuthError`,
+`ClivlyNetworkError`, `ClivlyRateLimitError`. `ClivlyError.from(result)` turns a
+failed `connect()` result into a throwable.
 
-`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`.
+## Advanced configuration
 
 ### Persisting the delta cursor
 
-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:
+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({
@@ -172,22 +327,32 @@ const clivly = createClivlySDK({
   entities,
   source: { /* … */ },
   cursorStore: {
-    // `SyncCursor` is { id: string; time: Date } — serialize `time` (e.g. ISO string).
+    // `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;
     },
     set: (entity, cursor) =>
-      kv.put(`clivly:cursor:${entity}`, cursor && { id: cursor.id, time: cursor.time.toISOString() }),
+      kv.put(
+        `clivly:cursor:${entity}`,
+        cursor && { id: cursor.id, time: cursor.time.toISOString() }
+      ),
   },
 });
 ```
 
-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).
+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".
+
+### Sync ordering
 
-## Many-to-many company membership
+`runSync` pushes **companies first**, then contacts, then deals, then custom
+objects, so contact→company links resolve on the server.
+
+### Many-to-many company membership
 
 If a mapping links contacts to companies through a join table
 (`via: { through: … }`), that entity's source must return **one row per
@@ -208,18 +373,94 @@ 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
 
 - `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
-
-- 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)
+- `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
+
+MIT

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

@@ -364,7 +364,7 @@ function cursorColumnChecks(sources) {
 			});
 			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})`,

package/dist/index.mjs

@@ -363,7 +363,7 @@ function cursorColumnChecks(sources) {
 			});
 			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})`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.7.3",
+  "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.3"
+    "@clivly/core": "0.7.4"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",