@clivly/sdk 0.9.2 → 0.9.3

package/README.md

@@ -453,6 +453,7 @@ 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; opens opt-in WebSocket presence |
 | `stop()` | `void` | Clears the timers |
@@ -461,6 +462,19 @@ is honoured. Other `4xx` responses return immediately.
 | `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`
 
@@ -468,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 |

package/dist/chat-session.d.cts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-DxG4rHyo.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-DxG4rHyo.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 { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.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 { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.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

package/dist/index.cjs

@@ -1702,6 +1702,7 @@ function createClivlySDK(config) {
 				reason: "ok",
 				retryable: false,
 				org: body?.org,
+				workspace: body?.workspace ?? null,
 				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
 			};
 		}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DxG4rHyo.cjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-Cgwxd4h_.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-DxG4rHyo.mjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable } from "./types-Cgwxd4h_.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -1701,6 +1701,7 @@ function createClivlySDK(config) {
 				reason: "ok",
 				retryable: false,
 				org: body?.org,
+				workspace: body?.workspace ?? null,
 				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
 			};
 		}

package/dist/{types-DxG4rHyo.d.cts → types-Cgwxd4h_.d.cts}

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -309,6 +309,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */

package/dist/{types-DxG4rHyo.d.mts → types-Cgwxd4h_.d.mts}

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -309,6 +309,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-DxG4rHyo.cjs";
+import { a as ClivlySDK } from "./types-Cgwxd4h_.cjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-DxG4rHyo.mjs";
+import { a as ClivlySDK } from "./types-Cgwxd4h_.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/package.json

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