@clivly/sdk 0.8.0 → 0.9.0

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

@@ -10,6 +10,8 @@ interface DrizzleSourceMeta {
   idField: string;
   /** The backing table's real name, so discovery can key metadata by table. */
   tableName?: string;
+  /** Every unique key on the table, each as its DB column names. */
+  uniqueConstraints?: string[][];
 }
 //#endregion
 //#region src/namespace-probe.d.ts
@@ -41,6 +43,13 @@ interface DiscoveredTable {
   name: string;
   /** Approximate source row count, when cheaply derivable. */
   rowCount?: number;
+  /**
+   * Every unique key on the table, each as its DB column names. Primary keys
+   * are included (a PK is a unique key). Absent on v1 hosts and for
+   * hand-declared tables — consumers must treat absence as "unknown", never
+   * as "no unique keys".
+   */
+  uniqueConstraints?: string[][];
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */
@@ -225,14 +234,33 @@ interface DoctorCheck {
   ok: boolean;
   /** True when the check could not run (e.g. a hand-written source). */
   skipped?: boolean;
+  /**
+   * True when the setup works but carries a risk worth stating.
+   *
+   * Distinct from `ok: false`, which means "this is broken, fix it before you
+   * rely on it". A warning is for a configuration that will run and sync, yet
+   * behaves in a way the developer probably did not intend — the cursor check
+   * below is the motivating case: syncing from an `id` column succeeds, mirrors
+   * every insert, and silently never re-syncs an edited row.
+   *
+   * Warnings do not fail `doctor`. Reporting them as failures would train
+   * people to ignore a red ladder on a working setup, which is worse than not
+   * reporting them at all.
+   */
+  warn?: boolean;
 }
 interface DoctorReport {
   checks: DoctorCheck[];
   /** AND of every non-skipped check's `ok`. */
   ok: boolean;
 }
-type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "server_too_old" | "network_error";
 interface ClivlyConnectResult {
+  /**
+   * When the org's app last heartbeated, or null if it never has. Set only by
+   * `ping()` — `connect()` IS a heartbeat, so the question is meaningless there.
+   */
+  appLastSeenAt?: string | null;
   ok: boolean;
   /** Org resolved from a successful heartbeat, when the server returns it. */
   org?: {
@@ -310,6 +338,14 @@ interface ClivlySDK {
    * loop and back-compat; use `connect()` when you need the failure reason.
    */
   heartbeat(): Promise<boolean>;
+  /**
+   * Read-only diagnostic probe. Proves the API key is valid and Clivly is
+   * reachable, and resolves the org — without reporting anything about the
+   * host app. Use this for `clivly status` and other diagnostics; use
+   * `connect()` only from the running app, which is entitled to report its
+   * own state.
+   */
+  ping(): Promise<ClivlyConnectResult>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

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

@@ -10,6 +10,8 @@ interface DrizzleSourceMeta {
   idField: string;
   /** The backing table's real name, so discovery can key metadata by table. */
   tableName?: string;
+  /** Every unique key on the table, each as its DB column names. */
+  uniqueConstraints?: string[][];
 }
 //#endregion
 //#region src/namespace-probe.d.ts
@@ -41,6 +43,13 @@ interface DiscoveredTable {
   name: string;
   /** Approximate source row count, when cheaply derivable. */
   rowCount?: number;
+  /**
+   * Every unique key on the table, each as its DB column names. Primary keys
+   * are included (a PK is a unique key). Absent on v1 hosts and for
+   * hand-declared tables — consumers must treat absence as "unknown", never
+   * as "no unique keys".
+   */
+  uniqueConstraints?: string[][];
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */
@@ -225,14 +234,33 @@ interface DoctorCheck {
   ok: boolean;
   /** True when the check could not run (e.g. a hand-written source). */
   skipped?: boolean;
+  /**
+   * True when the setup works but carries a risk worth stating.
+   *
+   * Distinct from `ok: false`, which means "this is broken, fix it before you
+   * rely on it". A warning is for a configuration that will run and sync, yet
+   * behaves in a way the developer probably did not intend — the cursor check
+   * below is the motivating case: syncing from an `id` column succeeds, mirrors
+   * every insert, and silently never re-syncs an edited row.
+   *
+   * Warnings do not fail `doctor`. Reporting them as failures would train
+   * people to ignore a red ladder on a working setup, which is worse than not
+   * reporting them at all.
+   */
+  warn?: boolean;
 }
 interface DoctorReport {
   checks: DoctorCheck[];
   /** AND of every non-skipped check's `ok`. */
   ok: boolean;
 }
-type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "server_too_old" | "network_error";
 interface ClivlyConnectResult {
+  /**
+   * When the org's app last heartbeated, or null if it never has. Set only by
+   * `ping()` — `connect()` IS a heartbeat, so the question is meaningless there.
+   */
+  appLastSeenAt?: string | null;
   ok: boolean;
   /** Org resolved from a successful heartbeat, when the server returns it. */
   org?: {
@@ -310,6 +338,14 @@ interface ClivlySDK {
    * loop and back-compat; use `connect()` when you need the failure reason.
    */
   heartbeat(): Promise<boolean>;
+  /**
+   * Read-only diagnostic probe. Proves the API key is valid and Clivly is
+   * reachable, and resolves the org — without reporting anything about the
+   * host app. Use this for `clivly status` and other diagnostics; use
+   * `connect()` only from the running app, which is entitled to report its
+   * own state.
+   */
+  ping(): Promise<ClivlyConnectResult>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-DTaz5mLi.cjs";
+import { a as ClivlySDK } from "./types-QPbki8ur.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-DTaz5mLi.mjs";
+import { a as ClivlySDK } from "./types-QPbki8ur.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/package.json

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