@clivly/sdk 0.2.0 → 0.3.0-next.1

package/dist/{types-DWt-ytBQ.d.mts → namespace-probe-DIBgCQca.d.cts}

@@ -1,18 +1,39 @@
 import { ClivlyEntitiesConfig } from "@clivly/core";
 
 //#region src/drizzle-meta.d.ts
-declare const DRIZZLE_META: unique symbol;
+declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
   /** Drizzle property keys of every column on the source table. */
   columnKeys: string[];
+  /** Schema-v2 typed column metadata derived from the Drizzle table. */
+  columnsMeta?: DiscoveredColumn[];
   cursorField: string;
   idField: string;
+  /** The backing table's real name, so discovery can key metadata by table. */
+  tableName?: string;
 }
 //#endregion
 //#region src/types.d.ts
+interface DiscoveredColumn {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  /** The column this FK points at, when it is a foreign key. */
+  references?: {
+    table: string;
+    column: string;
+  };
+  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
+  type?: string;
+}
 interface DiscoveredTable {
   columns: string[];
+  /** Schema-v2 typed column metadata (types, PK/FK, nullability). */
+  columnsMeta?: DiscoveredColumn[];
   name: string;
+  /** Approximate source row count, when cheaply derivable. */
+  rowCount?: number;
 }
 interface ClivlySDKConfig {
   /** Org-scoped API token (sk_live_…) from Settings → API keys. */
@@ -60,7 +81,18 @@ interface ClivlySDKConfig {
   framework?: string;
   /** Heartbeat cadence in ms. Defaults to 60s. */
   heartbeatIntervalMs?: number;
-  /** Whether the crm_* namespace exists in the host DB (self-reported). */
+  /**
+   * Optional live namespace probe, used on-demand by `doctor()`'s "Namespace
+   * reachable" check to verify every required source table + column is
+   * genuinely reachable. Not consulted by the heartbeat. Build one with
+   * `drizzleIntrospector(db)` from `@clivly/sdk/drizzle`.
+   */
+  introspector?: NamespaceIntrospector;
+  /**
+   * Self-reported readiness sent on every heartbeat as-is (no live check).
+   * For a real reachability check, configure `introspector` and run
+   * `doctor()`.
+   */
   namespaceReady?: boolean;
   orm?: string;
   /**
@@ -80,6 +112,10 @@ interface ClivlySDKConfig {
   source?: {
     contacts: SyncSource;
     companies?: SyncSource;
+    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    custom?: Array<SyncSource & {
+      objectType: string;
+    }>;
   };
   sync?: {
     onBoot?: boolean;
@@ -91,6 +127,29 @@ interface ClivlySDKConfig {
     intervalMs?: number;
     batchSize?: number;
   };
+  /**
+   * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
+   *
+   * Without it, cloud mode is push-only — Clivly can watch the app but can't
+   * start anything, so the dashboard's "Run sync" has nothing to call. With it,
+   * the SDK reports `url` on each heartbeat and requires every trigger request to
+   * be signed with `secret`.
+   */
+  syncTrigger?: {
+    /**
+     * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
+     * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
+     * heartbeat; a URL set in the dashboard overrides it.
+     */
+    url?: string;
+    /**
+     * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
+     * sync. When set, `createClivlyHandler()` rejects any request that isn't
+     * validly signed. Leave unset only if the route is already unreachable from
+     * the public internet.
+     */
+    secret?: string;
+  };
   /**
    * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
    * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
@@ -178,10 +237,16 @@ interface ClivlySDK {
    */
   createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
   /**
-   * A fetch handler to mount at a route and drive from an external scheduler
-   * (Cloudflare Workers cron, an uptime ping, etc.). Each request runs one
-   * `runScheduled()` and returns JSON: 200 when the sync succeeded, 500 otherwise.
-   * The ergonomic serverless entry point alongside `runScheduled()`.
+   * A fetch handler to mount at a route. Each request runs one `runScheduled()`
+   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
+   *
+   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
+   * requests are HMAC-signed and carry a run id), and the host's own scheduler
+   * (Workers cron, an uptime ping — no body).
+   *
+   * When `syncTrigger.secret` is set the handler rejects unsigned or
+   * badly-signed requests with 401. When it isn't, the route stays open to
+   * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
   /** Validate this setup end-to-end (read-only) before the first sync. */
@@ -200,6 +265,7 @@ interface ClivlySDK {
    */
   runScheduled(options?: {
     mode?: SyncMode;
+    runId?: string;
   }): Promise<void>;
   /**
    * Send the initial heartbeat and start the keep-alive loop. For long-lived
@@ -218,7 +284,16 @@ interface ClivlySDK {
    */
   sync(options?: {
     mode?: SyncMode;
+    runId?: string;
   }): Promise<void>;
 }
 //#endregion
-export { ClivlyUser as a, DoctorCheck as c, ClivlySDKConfig as i, DoctorReport as l, ClivlyConnectResult as n, CursorStore as o, ClivlySDK as r, DiscoveredTable as s, ClivlyConnectReason as t, SyncSource as u };
+//#region src/namespace-probe.d.ts
+interface NamespaceIntrospector {
+  /** All base table names in the reachable schema. */
+  listTables(): Promise<string[]>;
+  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
+  sampleSelect(table: string): Promise<void>;
+}
+//#endregion
+export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };

package/dist/vite.cjs

@@ -0,0 +1,38 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/vite.ts
+/**
+* Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+* boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+* (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+* server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+* does not persist on serverless/edge builds, so production on Workers/Lambda
+* should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+* instead. See docs/guides/connecting-to-clivly-cloud.md.
+*
+* Vite is an optional peer dependency imported type-only (`import type`), so
+* the built bundle carries no runtime dependency on Vite.
+*/
+function clivlyVite(sdk, options = {}) {
+	const label = options.name ?? "clivly";
+	return {
+		name: "clivly",
+		apply: "serve",
+		configureServer(server) {
+			const { logger } = server.config;
+			const boot = async () => {
+				const result = await sdk.connect();
+				if (result.ok) {
+					const org = result.org?.name ?? result.org?.id;
+					logger.info(`${label}: connected${org ? ` to ${org}` : ""}`);
+				} else logger.warn(`${label}: not connected (${result.reason})`);
+				await sdk.start();
+			};
+			boot().catch((error) => {
+				logger.error(`${label}: startup failed — ${error instanceof Error ? error.message : String(error)}`);
+			});
+			server.httpServer?.once("close", () => sdk.stop());
+		}
+	};
+}
+//#endregion
+exports.clivlyVite = clivlyVite;

package/dist/vite.d.cts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-DIBgCQca.cjs";
+import { Plugin } from "vite";
+
+//#region src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };

package/dist/vite.d.mts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-DFpvfl7T.mjs";
+import { Plugin } from "vite";
+
+//#region src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };

package/dist/vite.mjs

@@ -0,0 +1,37 @@
+//#region src/vite.ts
+/**
+* Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+* boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+* (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+* server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+* does not persist on serverless/edge builds, so production on Workers/Lambda
+* should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+* instead. See docs/guides/connecting-to-clivly-cloud.md.
+*
+* Vite is an optional peer dependency imported type-only (`import type`), so
+* the built bundle carries no runtime dependency on Vite.
+*/
+function clivlyVite(sdk, options = {}) {
+	const label = options.name ?? "clivly";
+	return {
+		name: "clivly",
+		apply: "serve",
+		configureServer(server) {
+			const { logger } = server.config;
+			const boot = async () => {
+				const result = await sdk.connect();
+				if (result.ok) {
+					const org = result.org?.name ?? result.org?.id;
+					logger.info(`${label}: connected${org ? ` to ${org}` : ""}`);
+				} else logger.warn(`${label}: not connected (${result.reason})`);
+				await sdk.start();
+			};
+			boot().catch((error) => {
+				logger.error(`${label}: startup failed — ${error instanceof Error ? error.message : String(error)}`);
+			});
+			server.httpServer?.once("close", () => sdk.stop());
+		}
+	};
+}
+//#endregion
+export { clivlyVite };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0-next.1",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -26,6 +26,16 @@
         "types": "./dist/drizzle.d.cts",
         "default": "./dist/drizzle.cjs"
       }
+    },
+    "./vite": {
+      "import": {
+        "types": "./dist/vite.d.mts",
+        "default": "./dist/vite.mjs"
+      },
+      "require": {
+        "types": "./dist/vite.d.cts",
+        "default": "./dist/vite.cjs"
+      }
     }
   },
   "files": [
@@ -35,14 +45,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.2.0"
+    "@clivly/core": "0.3.0-next.1"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.30"
+    "drizzle-orm": ">=0.30",
+    "vite": ">=5"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -50,6 +64,7 @@
     "drizzle-orm": "^0.45.2",
     "tsdown": "^0.21.9",
     "typescript": "^6",
+    "vite": "^8.0.8",
     "vitest": "^3.2.0"
   },
   "scripts": {