@clivly/sdk 0.9.0 → 0.9.1

package/README.md

@@ -394,7 +394,7 @@ 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` | |
@@ -436,10 +436,32 @@ 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 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.
+
+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

package/package.json

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