@clivly/sdk 0.9.1 → 0.9.3

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
@@ -397,7 +432,9 @@ is honoured. Other `4xx` responses return immediately.
 | `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 |
@@ -416,14 +453,28 @@ is honoured. Other `4xx` responses return immediately.
 | Method | Returns | Notes |
 | --- | --- | --- |
 | `connect()` | `Promise<ClivlyConnectResult>` | One heartbeat, structured. Never throws |
+| `ping()` | `Promise<ClivlyConnectResult>` | Zero-write reachability probe. Same shape as `connect()`, but records no heartbeat — and it alone returns `workspace` |
 | `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 |
 | `createClivlyHandler()` | `(Request) => Promise<Response>` | Mount at a route |
 | `createAuthVerifyHandler(resolveUser)` | `(Request) => Promise<Response>` | `503` unless `verifyToken` is set |
 | `doctor()` | `Promise<DoctorReport>` | `{ ok, checks }` |
+| `ensureSchema()` | `Promise<EnsureSchemaResult \| null>` | Declares your custom object types **and** the mappings that make them receive rows. `null` = could not deliver; **rejects** if Clivly refuses the config |
+| `ensureCustomObjects()` | `Promise<{ slug, id, created }[] \| null>` | Object types only, no mappings. Superseded by `ensureSchema()` |
+
+`clivly push-schema` calls `ensureSchema()` for you, so you rarely need it
+directly — reach for it when you want config-as-code to run from your own
+deploy script or a CI step.
+
+The `null`-vs-throw split is deliberate. `null` means the request never landed
+(network, or a Clivly older than the route), which is worth a retry. A rejection
+means Clivly understood the config and declined it — most often because an
+entity would overwrite a mapping someone edited in the dashboard — which is
+worth reading, not retrying. A config-declared mapping is owned by your config;
+a dashboard-edited one is never silently overwritten.
 
 ### `ClivlyConnectResult.reason`
 
@@ -431,6 +482,17 @@ is honoured. Other `4xx` responses return immediately.
 `server_error` (5xx) · `client_error` (other 4xx) · `network_error` (no
 response).
 
+### `ClivlyConnectResult.workspace`
+
+`ping()` also returns `workspace` — the setup ladder for the org behind your key
+(`IntegrationState` from `@clivly/core`), computed by the server so the CLI and
+the dashboard cannot disagree about how far setup has got. This is what
+`clivly status` prints under **Workspace**.
+
+It is `undefined` or `null` when the server predates the field or could not read
+it. Treat that as *unknown*, never as *nothing is set up* — an old server, a
+rejected key and a dead network all mean the question went unanswered.
+
 ### Subpath exports
 
 | From `clivly` | From `@clivly/sdk` | Contents |
@@ -444,21 +506,27 @@ response).
 
 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 build one in the Clivly dashboard, not in code.
-
-The SDK's only job is to report enough schema for it: `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, the dashboard will refuse to author a
-projection against those tables with *"has no key/column metadata — upgrade
-`@clivly/sdk` and re-run discovery"*.
-
-The fix is to pass `discoverFromDrizzle(schema)` and redeploy, so a fresh
-heartbeat carries the richer payload. Re-run it after schema changes too:
-projections validate against the last reported snapshot.
-
-> Requires `clivly@0.9.0` / `@clivly/sdk@0.9.0` or later. Earlier versions
-> reported names only, so no host app could author a derived object.
+`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).
 
@@ -466,6 +534,8 @@ Full guide: [`docs/guides/derived-objects.md`](../../docs/guides/derived-objects
 
 - `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-Cgwxd4h_.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-Cgwxd4h_.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-Cgwxd4h_.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-Cgwxd4h_.mjs";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
 //#region src/drizzle.d.ts