@clivly/sdk 0.9.0 → 0.9.2

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

@@ -86,6 +86,12 @@ interface ClivlySDKConfig {
    * runtimes can supply their own.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Where this app is running: `local_dev`, `preview` or `production`. Reported
+   * on each heartbeat so the dashboard can name the environment it is watching.
+   * Inferred from platform variables and `NODE_ENV` when omitted.
+   */
+  environment?: "local_dev" | "preview" | "production";
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -120,6 +126,17 @@ interface ClivlySDKConfig {
    */
   namespaceReady?: boolean;
   orm?: string;
+  /**
+   * Presence transport override. HTTP remains the default until the recorded
+   * production rollout gate permits a WebSocket default; set `http` explicitly
+   * to keep the legacy transport after that rollout. Operators may also set
+   * `CLIVLY_PRESENCE_TRANSPORT` without changing application code.
+   */
+  presence?: {
+    /** Explicit release identity; platform deployment ids and commit SHAs follow. */
+    deploymentId?: string;
+    transport?: "http" | "websocket";
+  };
   /**
    * Network retry policy for outbound calls (heartbeat + sync push). Transient
    * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
@@ -225,6 +242,26 @@ interface CreateChatSessionHandlerOptions {
    */
   resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
+/** One object type ensured by `ensureSchema`. */
+interface EnsuredObjectTypeResult {
+  /** True when this call created it, false when it already existed. */
+  created: boolean;
+  id: string;
+  slug: string;
+}
+/** One mapping ensured by `ensureSchema`. */
+interface EnsuredMappingResult {
+  created: boolean;
+  /** The config entity key this mapping came from. */
+  entityKey: string;
+  id: string;
+  /** True when an existing config-owned mapping's definition changed. */
+  updated: boolean;
+}
+interface EnsureSchemaResult {
+  mappings: EnsuredMappingResult[];
+  objectTypes: EnsuredObjectTypeResult[];
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -333,6 +370,31 @@ interface ClivlySDK {
   createClivlyHandler(): (req: Request) => Promise<Response>;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
+  /**
+   * Create any custom object types the config declares that this workspace does
+   * not have yet, keyed by entity slug — so `clivly.config.ts` needs no
+   * dashboard-generated id. Create-only and idempotent.
+   *
+   * Resolves to the ensured objects (empty when the config declares none), or
+   * `null` when the request could not be delivered.
+   */
+  ensureCustomObjects(): Promise<{
+    slug: string;
+    id: string;
+    created: boolean;
+  }[] | null>;
+  /**
+   * Declare the whole schema this config describes — custom object types AND
+   * the mappings that make them receive rows. The superset of
+   * `ensureCustomObjects`, which creates the object container and nothing else.
+   *
+   * Resolves to `null` when the request could not be delivered (including
+   * against a server too old to have the route), and REJECTS when Clivly
+   * refuses the config — e.g. an entity that would overwrite a mapping managed
+   * in the dashboard. That distinction matters: unreachable is worth a retry,
+   * refused is worth reading.
+   */
+  ensureSchema(): Promise<EnsureSchemaResult | null>;
   /**
    * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
    * loop and back-compat; use `connect()` when you need the failure reason.
@@ -365,7 +427,7 @@ interface ClivlySDK {
    */
   start(): Promise<void>;
   /** Stop the keep-alive loop. */
-  stop(): void;
+  stop(): Promise<void>;
   /**
    * Sync all configured sources now. `delta` (default) pages changed rows since
    * the last cursor; `full` pushes each complete entity so the server can
@@ -378,4 +440,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-export { ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, ClivlyConnectResult as i, CursorStore as l, NamespaceIntrospector as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, SyncSource as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u };
+export { NamespaceIntrospector as _, ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, SyncSource as g, EnsuredObjectTypeResult as h, ClivlyConnectResult as i, CursorStore as l, EnsuredMappingResult as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, EnsureSchemaResult as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u };

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

@@ -86,6 +86,12 @@ interface ClivlySDKConfig {
    * runtimes can supply their own.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Where this app is running: `local_dev`, `preview` or `production`. Reported
+   * on each heartbeat so the dashboard can name the environment it is watching.
+   * Inferred from platform variables and `NODE_ENV` when omitted.
+   */
+  environment?: "local_dev" | "preview" | "production";
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -120,6 +126,17 @@ interface ClivlySDKConfig {
    */
   namespaceReady?: boolean;
   orm?: string;
+  /**
+   * Presence transport override. HTTP remains the default until the recorded
+   * production rollout gate permits a WebSocket default; set `http` explicitly
+   * to keep the legacy transport after that rollout. Operators may also set
+   * `CLIVLY_PRESENCE_TRANSPORT` without changing application code.
+   */
+  presence?: {
+    /** Explicit release identity; platform deployment ids and commit SHAs follow. */
+    deploymentId?: string;
+    transport?: "http" | "websocket";
+  };
   /**
    * Network retry policy for outbound calls (heartbeat + sync push). Transient
    * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
@@ -225,6 +242,26 @@ interface CreateChatSessionHandlerOptions {
    */
   resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
+/** One object type ensured by `ensureSchema`. */
+interface EnsuredObjectTypeResult {
+  /** True when this call created it, false when it already existed. */
+  created: boolean;
+  id: string;
+  slug: string;
+}
+/** One mapping ensured by `ensureSchema`. */
+interface EnsuredMappingResult {
+  created: boolean;
+  /** The config entity key this mapping came from. */
+  entityKey: string;
+  id: string;
+  /** True when an existing config-owned mapping's definition changed. */
+  updated: boolean;
+}
+interface EnsureSchemaResult {
+  mappings: EnsuredMappingResult[];
+  objectTypes: EnsuredObjectTypeResult[];
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -333,6 +370,31 @@ interface ClivlySDK {
   createClivlyHandler(): (req: Request) => Promise<Response>;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
+  /**
+   * Create any custom object types the config declares that this workspace does
+   * not have yet, keyed by entity slug — so `clivly.config.ts` needs no
+   * dashboard-generated id. Create-only and idempotent.
+   *
+   * Resolves to the ensured objects (empty when the config declares none), or
+   * `null` when the request could not be delivered.
+   */
+  ensureCustomObjects(): Promise<{
+    slug: string;
+    id: string;
+    created: boolean;
+  }[] | null>;
+  /**
+   * Declare the whole schema this config describes — custom object types AND
+   * the mappings that make them receive rows. The superset of
+   * `ensureCustomObjects`, which creates the object container and nothing else.
+   *
+   * Resolves to `null` when the request could not be delivered (including
+   * against a server too old to have the route), and REJECTS when Clivly
+   * refuses the config — e.g. an entity that would overwrite a mapping managed
+   * in the dashboard. That distinction matters: unreachable is worth a retry,
+   * refused is worth reading.
+   */
+  ensureSchema(): Promise<EnsureSchemaResult | null>;
   /**
    * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
    * loop and back-compat; use `connect()` when you need the failure reason.
@@ -365,7 +427,7 @@ interface ClivlySDK {
    */
   start(): Promise<void>;
   /** Stop the keep-alive loop. */
-  stop(): void;
+  stop(): Promise<void>;
   /**
    * Sync all configured sources now. `delta` (default) pages changed rows since
    * the last cursor; `full` pushes each complete entity so the server can
@@ -378,4 +440,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-export { ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, ClivlyConnectResult as i, CursorStore as l, NamespaceIntrospector as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, SyncSource as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u };
+export { NamespaceIntrospector as _, ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, SyncSource as g, EnsuredObjectTypeResult as h, ClivlyConnectResult as i, CursorStore as l, EnsuredMappingResult as m, ChatWidgetVisitor as n, ClivlySDKConfig as o, EnsureSchemaResult as p, ClivlyConnectReason as r, ClivlyUser as s, ChatSessionRequestBody as t, DiscoveredTable as u };

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-QPbki8ur.cjs";
+import { a as ClivlySDK } from "./types-DxG4rHyo.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-QPbki8ur.mjs";
+import { a as ClivlySDK } from "./types-DxG4rHyo.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.0",
+  "version": "0.9.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.9.0"
+    "@clivly/core": "0.9.2"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30 || >=1.0.0-rc.0",