@clivly/sdk 0.9.0 → 0.9.2

package/README.md

@@ -1,9 +1,10 @@
 # @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 your app to Clivly Cloud. The SDK reports your schema for entity mapping
+and mirrors your contacts and companies over outbound HTTPS. Long-lived Node
+hosts can opt into WebSocket presence, which replaces the periodic HTTP
+liveness heartbeat while the socket is ready and falls back automatically if it
+is not.
 
 Clivly never connects to your database — the SDK runs inside your app and is the
 only thing that touches your data.
@@ -69,6 +70,9 @@ export default createClivlySDK({
       cursorField: "updatedAt",
     }),
   },
+  presence: {
+    transport: "websocket", // long-lived Node hosts only; HTTP fallback is automatic
+  },
 });
 ```
 
@@ -96,13 +100,44 @@ 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 |
+| Long-lived Node server, Vite dev | `clivlyVite(sdk)` or `await sdk.start()` | The keep-alive loop persists; optionally use WebSocket presence |
 | 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.
 
+### WebSocket presence
+
+HTTP is the default presence transport. To replace the 60-second HTTP liveness
+cadence on a long-lived Node host, opt in:
+
+```ts
+createClivlySDK({
+  // ...the rest of your configuration
+  presence: {
+    transport: "websocket",
+    deploymentId: process.env.CLIVLY_DEPLOYMENT_ID, // optional
+  },
+});
+```
+
+`start()` performs its initial HTTP check-in, then opens an authenticated
+outbound socket. When the server confirms it is ready, the socket becomes the
+liveness signal and the periodic HTTP heartbeat pauses. A closed or unavailable
+socket reconnects with backoff while the SDK resumes HTTP heartbeat
+automatically. This does not alter `sync.intervalMs`; it only changes presence.
+
+Keep the default HTTP transport for serverless and edge runtimes. They cannot
+retain a WebSocket across invocations, so use `runScheduled()` or
+`createClivlyHandler()` there.
+
+For rollout reliability, enabled WebSocket presence emits bounded lifecycle
+metrics (event, transport, outcome, state, duration and attempt). It never
+includes credentials, organization or deployment identifiers, host URLs, row
+data, error messages, or stack traces. See
+[SECURITY.md](../../SECURITY.md#telemetry).
+
 ### Entities vs. sources — the distinction that bites
 
 ```ts
@@ -394,10 +429,12 @@ is honoured. Other `4xx` responses return immediately.
 | `apiKey` | `string` | — | **Required.** `sk_live_…` |
 | `apiUrl` | `string` | `https://api.clivly.com` | Non-default backend |
 | `entities` | `ClivlyEntitiesConfig` | — | From `defineClivlyConfig({ entities })` |
-| `schema` | `DiscoveredTable[]` | — | Use `discoverFromDrizzle(schema)` |
+| `schema` | `DiscoveredTable[]` | — | Use `discoverFromDrizzle(schema)`. It reports keys, types, nullability and FK edges alongside column names; [derived objects](#derived-objects) cannot be authored without them, so prefer it over a hand-written array |
 | `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` | |
+| `heartbeatIntervalMs` | `number` | `60000` | HTTP presence cadence and default sync cadence; paused when opt-in WebSocket presence is ready |
+| `presence.transport` | `"http" \\| "websocket"` | `"http"` | WebSocket is for long-lived Node hosts; HTTP resumes during reconnect/fallback |
+| `presence.deploymentId` | `string` | platform-derived | Optional release identity for a WebSocket deployment |
 | `sync.onBoot` | `boolean` | `true` | Only affects `start()` |
 | `sync.intervalMs` | `number` | `heartbeatIntervalMs` | |
 | `sync.batchSize` | `number` | `500` | Rows per page |
@@ -417,7 +454,7 @@ is honoured. Other `4xx` responses return immediately.
 | --- | --- | --- |
 | `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 |
+| `start()` | `Promise<void>` | Heartbeat + boot sync + timers. Long-lived hosts only; opens opt-in WebSocket presence |
 | `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 |
@@ -436,14 +473,44 @@ response).
 | 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/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector`, `buildUniqueConstraints` |
 | `clivly/vite` | `@clivly/sdk/vite` | `clivlyVite` |
 | — | `@clivly/sdk/chat-session` | `createChatSessionHandler` (also on the root) |
 
+## Derived objects
+
+A custom object can be derived from a base table plus explicit joins, instead of
+mapping exactly one table — an `Enrollment` built from `enrollments` joined to
+`students` and `courses`. You declare one on an entity in `clivly.config.ts`,
+alongside the object it materializes into; `validateEntitiesConfig` checks it in
+CI.
+
+Two things have to line up:
+
+- **Discovery must be rich enough.** `discoverFromDrizzle` sends primary keys,
+  unique constraints, nullability, column types and foreign-key edges.
+  Validation is fail-closed, so if your config hand-writes `schema` as
+  `{ name, columns }` pairs, every table is rejected with *"has no key/column
+  metadata — upgrade `@clivly/sdk` and re-run discovery"*. Pass
+  `discoverFromDrizzle(schema)` and redeploy so a fresh heartbeat carries the
+  richer payload — and re-run it after schema changes, since projections
+  validate against the last reported snapshot.
+- **The server must have the capability enabled.** Authoring sits behind
+  `CLIVLY_PROJECTION_MAPPINGS=true` while the surface settles. Reading and
+  syncing an existing derived object is never gated.
+
+> Requires `clivly@0.9.0` / `@clivly/sdk@0.9.0` or later for the discovery
+> metadata. Earlier versions reported names only, so no host app could author a
+> derived object.
+
+Full guide: [`docs/guides/derived-objects.md`](../../docs/guides/derived-objects.md).
+
 ## Known limitations
 
 - `start()` is for long-lived runtimes only. On serverless/edge, use
   `runScheduled()` or `createClivlyHandler()`.
+- WebSocket presence is opt-in and long-lived Node-only. It does not replace
+  HTTP presence on serverless or edge hosts.
 - `fromDrizzle` is the only generated source path. Non-Drizzle hosts write
   `fetchPage` by hand.
 - The flat `contactEntity` / `contactFields` config still works but is

package/dist/chat-session.d.cts

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

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { m as NamespaceIntrospector, p as SyncSource } from "./types-QPbki8ur.cjs";
+import { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.cjs";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, 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-QPbki8ur.mjs";
+import { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.mjs";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
 //#region src/drizzle.d.ts