@clivly/sdk 0.7.1 → 0.7.2

package/README.md

@@ -1,36 +1,66 @@
 # @clivly/sdk
 
-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.
+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.
 
-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.
+## Which package should I install?
 
-## Install
+For most new integrations, install the consolidated public package:
 
 ```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.
-
-Add `drizzle-orm` when you use `clivly/drizzle`, and
-`vite` when you use the Vite/TanStack Start plugin.
-
-## Usage
+and import from:
 
 ```ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
 import { fromDrizzle } from "clivly/drizzle";
+```
+
+`@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:
+
+```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 { 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: {
@@ -47,62 +77,67 @@ const entities = defineClivlyConfig({
 });
 
 const clivly = createClivlySDK({
-  apiKey: process.env.CLIVLY_SECRET_KEY!, // sk_live_… from Settings → API keys
+  apiKey: process.env.CLIVLY_SECRET_KEY!,
   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(); // rich result: { ok, status, reason, retryable, org? }
-if (!status.ok) throw new Error(`Clivly: ${status.reason}`);
-await clivly.start();      // heartbeat + backfill + interval delta sync
+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.
 
-// Optional: let Clivly's dashboard start a sync in this app.
-const remote = createClivlySDK({
+## Remote sync trigger
+
+If you configure `syncTrigger`, Clivly can ask your app to run a sync from the
+dashboard:
+
+```ts
+const clivly = 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, // whsec_… from Integrations → Remote sync
+    secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
   },
 });
 
 export async function POST(request: Request) {
-  return remote.createClivlyHandler()(request);
+  return 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 `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`.
+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.
 
 ## Vite / TanStack Start
 
-For long-lived Vite dev servers, wire the SDK lifecycle through the Vite plugin:
+For long-lived Vite dev servers, wire the SDK lifecycle through the plugin:
 
 ```ts
-import { clivlyVite } from "clivly/vite";
+import { clivlyVite } from "@clivly/sdk/vite";
 import clivly from "./clivly.config";
 import { defineConfig } from "vite";
 
@@ -111,115 +146,80 @@ 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.
-
-> **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.
+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
 
-Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
+If your instance lives in `clivly.config.ts`, the CLI can validate the setup:
 
 ```bash
-npx clivly ping     # CLIVLY_SECRET_KEY + API reachability
-npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
+npx clivly ping
+npx clivly doctor
 ```
 
-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.
+In code, `await clivly.doctor()` returns the same structured read-only checks.
 
 ## Serverless / edge
 
-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:
+On request-scoped runtimes such as Cloudflare Workers, Vercel, or Lambda, do
+not call `start()`. Use `runScheduled()` or mount `createClivlyHandler()`
+instead:
 
 ```ts
-// Cloudflare Workers
 export default {
-  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
-  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping / external scheduler
+  scheduled: () => clivly.runScheduled(),
+  fetch: clivly.createClivlyHandler(),
 };
 ```
 
-`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`.
+`runScheduled()` throws on a failed push so cron jobs surface failures.
+`createClivlyHandler()` returns `200` on success and `500` on a failed run.
 
 ### 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:
+By default the delta cursor lives in memory. For serverless runtimes, pass a
+persistent `cursorStore`:
 
 ```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() }),
+      kv.put(
+        `clivly:cursor:${entity}`,
+        cursor ? { id: cursor.id, time: cursor.time.toISOString() } : null
+      ),
   },
 });
 ```
 
-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).
-
-## 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
-membership**, each row carrying the join table's foreign-key column.
-
-```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.
+Delta sync is at-least-once. Without a persisted cursor after a cold start,
+rows may be re-sent; they are not silently skipped.
 
 ## 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: ... })`.
+- `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: ... })`.
 
 ## 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)
+- 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)
+
+## License
+
+MIT

package/package.json

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