@clivly/sdk 0.9.5 → 0.9.6

package/README.md

@@ -330,6 +330,12 @@ import { drizzleIntrospector } from "clivly/drizzle";
 createClivlySDK({ /* … */, introspector: drizzleIntrospector(db) });
 ```
 
+Setting `introspector` also lets Clivly's dashboard **preview a derived object**
+before you save it. Clivly never connects to your database, so your app runs
+that query — read-only, capped at 50 rows, through the sync-trigger route you
+already expose. Without it the dashboard says preview is unavailable and names
+this setting rather than failing.
+
 ## Common errors and troubleshooting
 
 | Symptom | Cause | Fix |
@@ -468,6 +474,7 @@ 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 }` |
+| `describeSyncTrigger()` | `SyncTriggerDescription` | `{ configured, resolved }` — the raw `syncTrigger.url` and the URL that would actually be reported. Computed per call: `resolved` can be `undefined` until the mounted route has served its first request |
 | `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()` |
 

package/dist/chat-session.d.cts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-Dz1LQYvQ.cjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-CiFEalbP.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-Dz1LQYvQ.mjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-CiFEalbP.mjs";
 //#region src/chat-session.d.ts
 declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion

package/dist/drizzle.cjs

@@ -3,6 +3,20 @@ const require_drizzle_meta = require("./drizzle-meta-CdCs30q3.cjs");
 let _clivly_core_drizzle = require("@clivly/core/drizzle");
 let drizzle_orm = require("drizzle-orm");
 let _clivly_core = require("@clivly/core");
+//#region src/projection-preview.ts
+/** `db.execute` returns either an array or `{ rows }`, depending on driver. */
+function rowsOf(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("previewProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+async function previewProjection(db, projection, opts) {
+	const client = db;
+	const { sql } = await import("drizzle-orm");
+	return rowsOf(await client.execute(sql.raw((0, _clivly_core.compileProjectionPreview)(projection, opts.limit))));
+}
+//#endregion
 //#region src/drizzle-projection.ts
 /** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
 function refToken(ref) {
@@ -134,6 +148,9 @@ function drizzleIntrospector(db) {
 		},
 		async sampleSelect(table) {
 			await client.execute(drizzle_orm.sql`select 1 from ${drizzle_orm.sql.identifier(table)} limit 1`);
+		},
+		runProjection(projection, opts) {
+			return previewProjection(db, projection, opts);
 		}
 	};
 }

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.cjs";
+import { g as SyncSource, v as NamespaceIntrospector } from "./types-CiFEalbP.cjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.mjs";
+import { g as SyncSource, v as NamespaceIntrospector } from "./types-CiFEalbP.mjs";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";

package/dist/drizzle.mjs

@@ -1,7 +1,21 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
 import { buildColumnsMeta, buildUniqueConstraints, buildUniqueConstraints as buildUniqueConstraints$1, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
-import { BASE_REF, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, quoteIdent } from "@clivly/core";
+import { BASE_REF, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, quoteIdent } from "@clivly/core";
+//#region src/projection-preview.ts
+/** `db.execute` returns either an array or `{ rows }`, depending on driver. */
+function rowsOf(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("previewProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+async function previewProjection(db, projection, opts) {
+	const client = db;
+	const { sql } = await import("drizzle-orm");
+	return rowsOf(await client.execute(sql.raw(compileProjectionPreview(projection, opts.limit))));
+}
+//#endregion
 //#region src/drizzle-projection.ts
 /** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
 function refToken(ref) {
@@ -133,6 +147,9 @@ function drizzleIntrospector(db) {
 		},
 		async sampleSelect(table) {
 			await client.execute(sql`select 1 from ${sql.identifier(table)} limit 1`);
+		},
+		runProjection(projection, opts) {
+			return previewProjection(db, projection, opts);
 		}
 	};
 }

package/dist/index.cjs

@@ -574,12 +574,21 @@ async function runDoctor(args) {
 		ok: entityCount > 0,
 		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
 	});
+	const sourcesDetail = (count, deferred) => {
+		if (deferred) return "Deferred — the coverage check below names the entity and the source key it expected.";
+		return count === 0 ? "No `source.contacts` — nothing to sync." : `${count} source(s) to mirror.`;
+	};
+	const coverage = checkConceptCoverage(config);
+	const coverageOwnsIt = !(coverage.ok || coverage.skipped);
+	const noSources = sources.length === 0;
+	const deferred = noSources && coverageOwnsIt;
 	checks.push({
 		name: "Sources configured",
-		ok: sources.length > 0,
-		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+		ok: !noSources,
+		skipped: deferred,
+		detail: sourcesDetail(sources.length, deferred)
 	});
-	checks.push(checkConceptCoverage(config));
+	checks.push(coverage);
 	checks.push(...cursorColumnChecks(sources));
 	for (const source of sources) {
 		const check = cursorMonotonicityCheck(source);
@@ -1446,6 +1455,15 @@ async function handlePreviewRequest(config, preview) {
 		sampledCount: rows.length
 	}, 200);
 }
+async function handleProjectionPreviewRequest(config, request) {
+	const run = config.introspector?.runProjection;
+	if (!run) return jsonResponse({ error: "This app cannot preview derived objects. Set `introspector: drizzleIntrospector(db)` in clivly.config.ts, on a clivly version that supports runProjection." }, 400);
+	const rows = await run.call(config.introspector, request.projection, { limit: request.limit });
+	return jsonResponse({
+		rows,
+		sampledCount: rows.length
+	}, 200);
+}
 /**
 * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
 * and the auth-verify handler — connects a developer's app to a running Clivly
@@ -1575,13 +1593,17 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
 	};
-	const sendHeartbeat = () => {
-		const triggerUrl = resolveTriggerUrl({
+	const describeSyncTrigger = () => ({
+		configured: config.syncTrigger?.url,
+		resolved: resolveTriggerUrl({
 			configuredUrl: config.syncTrigger?.url,
 			configuredPath: config.syncTrigger?.path,
 			env: config.env ?? process.env,
 			observedUrl
-		});
+		})
+	});
+	const sendHeartbeat = () => {
+		const triggerUrl = describeSyncTrigger().resolved;
 		return fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
 			method: "POST",
 			headers: {
@@ -1809,6 +1831,7 @@ function createClivlySDK(config) {
 		const startedAt = Date.now();
 		try {
 			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -1904,6 +1927,7 @@ function createClivlySDK(config) {
 		connect,
 		ping,
 		doctor,
+		describeSyncTrigger,
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,

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-Dz1LQYvQ.cjs";
+import { _ as SyncTriggerDescription, 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-CiFEalbP.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts
@@ -34,4 +34,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type ConfigValidationError, type ConfigValidationResult, type CreateChatSessionHandlerOptions, type CursorStore, type CustomObjectDeclaration, type DiscoveredSchemaTable, type DiscoveredTable, type DoctorCheck, type DoctorReport, type EnsureSchemaResult, type EnsuredMappingResult, type EnsuredObjectTypeResult, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type ConfigValidationError, type ConfigValidationResult, type CreateChatSessionHandlerOptions, type CursorStore, type CustomObjectDeclaration, type DiscoveredSchemaTable, type DiscoveredTable, type DoctorCheck, type DoctorReport, type EnsureSchemaResult, type EnsuredMappingResult, type EnsuredObjectTypeResult, type SyncTriggerDescription, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

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-Dz1LQYvQ.mjs";
+import { _ as SyncTriggerDescription, 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-CiFEalbP.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts
@@ -34,4 +34,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type ConfigValidationError, type ConfigValidationResult, type CreateChatSessionHandlerOptions, type CursorStore, type CustomObjectDeclaration, type DiscoveredSchemaTable, type DiscoveredTable, type DoctorCheck, type DoctorReport, type EnsureSchemaResult, type EnsuredMappingResult, type EnsuredObjectTypeResult, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, type ClivlyEntitiesConfig, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type ConfigValidationError, type ConfigValidationResult, type CreateChatSessionHandlerOptions, type CursorStore, type CustomObjectDeclaration, type DiscoveredSchemaTable, type DiscoveredTable, type DoctorCheck, type DoctorReport, type EnsureSchemaResult, type EnsuredMappingResult, type EnsuredObjectTypeResult, type SyncTriggerDescription, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

package/dist/index.mjs

@@ -573,12 +573,21 @@ async function runDoctor(args) {
 		ok: entityCount > 0,
 		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
 	});
+	const sourcesDetail = (count, deferred) => {
+		if (deferred) return "Deferred — the coverage check below names the entity and the source key it expected.";
+		return count === 0 ? "No `source.contacts` — nothing to sync." : `${count} source(s) to mirror.`;
+	};
+	const coverage = checkConceptCoverage(config);
+	const coverageOwnsIt = !(coverage.ok || coverage.skipped);
+	const noSources = sources.length === 0;
+	const deferred = noSources && coverageOwnsIt;
 	checks.push({
 		name: "Sources configured",
-		ok: sources.length > 0,
-		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+		ok: !noSources,
+		skipped: deferred,
+		detail: sourcesDetail(sources.length, deferred)
 	});
-	checks.push(checkConceptCoverage(config));
+	checks.push(coverage);
 	checks.push(...cursorColumnChecks(sources));
 	for (const source of sources) {
 		const check = cursorMonotonicityCheck(source);
@@ -1445,6 +1454,15 @@ async function handlePreviewRequest(config, preview) {
 		sampledCount: rows.length
 	}, 200);
 }
+async function handleProjectionPreviewRequest(config, request) {
+	const run = config.introspector?.runProjection;
+	if (!run) return jsonResponse({ error: "This app cannot preview derived objects. Set `introspector: drizzleIntrospector(db)` in clivly.config.ts, on a clivly version that supports runProjection." }, 400);
+	const rows = await run.call(config.introspector, request.projection, { limit: request.limit });
+	return jsonResponse({
+		rows,
+		sampledCount: rows.length
+	}, 200);
+}
 /**
 * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
 * and the auth-verify handler — connects a developer's app to a running Clivly
@@ -1574,13 +1592,17 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
 	};
-	const sendHeartbeat = () => {
-		const triggerUrl = resolveTriggerUrl({
+	const describeSyncTrigger = () => ({
+		configured: config.syncTrigger?.url,
+		resolved: resolveTriggerUrl({
 			configuredUrl: config.syncTrigger?.url,
 			configuredPath: config.syncTrigger?.path,
 			env: config.env ?? process.env,
 			observedUrl
-		});
+		})
+	});
+	const sendHeartbeat = () => {
+		const triggerUrl = describeSyncTrigger().resolved;
 		return fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
 			method: "POST",
 			headers: {
@@ -1808,6 +1830,7 @@ function createClivlySDK(config) {
 		const startedAt = Date.now();
 		try {
 			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -1903,6 +1926,7 @@ function createClivlySDK(config) {
 		connect,
 		ping,
 		doctor,
+		describeSyncTrigger,
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,

package/dist/{types-Dz1LQYvQ.d.cts → types-CiFEalbP.d.cts}

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState, ProjectionMapping } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -18,6 +18,23 @@ interface DrizzleSourceMeta {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Read a few rows through an unsaved projection, for the dashboard's derived
+   * object preview. Rows are keyed by field name.
+   *
+   * Optional because it is the only capability here that needs more than a
+   * table name, and because an introspector may be hand-written. Absent, the
+   * dashboard says preview is unavailable rather than failing — see
+   * `previewProjection`.
+   *
+   * This is what makes preview cost the host an SDK upgrade and nothing else:
+   * `drizzleIntrospector(db)` already closes over the connection, so a config
+   * that set `introspector` for the "Namespace reachable" check gains preview
+   * without touching a line.
+   */
+  runProjection?(projection: ProjectionMapping, opts: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
   /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
   sampleSelect(table: string): Promise<void>;
 }
@@ -347,6 +364,20 @@ interface CursorStore {
   get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
   set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
 }
+/** @see ClivlySDK.describeSyncTrigger */
+interface SyncTriggerDescription {
+  /**
+   * `syncTrigger.url` exactly as configured, placeholder and all. The raw
+   * value, so a caller can say what is in the file rather than what survived
+   * resolution.
+   */
+  configured?: string;
+  /**
+   * The URL that would be reported to Clivly on the next heartbeat, or
+   * `undefined` when nothing resolves. An unedited placeholder never resolves.
+   */
+  resolved?: string;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -382,6 +413,18 @@ interface ClivlySDK {
    * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
+  /**
+   * What this app would tell Clivly about its sync trigger route, right now.
+   *
+   * Computed per call rather than frozen at creation: `resolved` can start as
+   * `undefined` and become a real URL once the mounted route has served its
+   * first request and observed its own origin.
+   *
+   * Exists for `clivly status`, which has to tell "no trigger configured"
+   * apart from "configured, but still the scaffolded placeholder" — a
+   * distinction `resolved` alone erases, since it skips placeholders by design.
+   */
+  describeSyncTrigger(): SyncTriggerDescription;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
   /**
@@ -454,4 +497,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-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 };
+export { SyncTriggerDescription 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, NamespaceIntrospector as v };

package/dist/{types-Dz1LQYvQ.d.mts → types-CiFEalbP.d.mts}

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState, ProjectionMapping } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -18,6 +18,23 @@ interface DrizzleSourceMeta {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Read a few rows through an unsaved projection, for the dashboard's derived
+   * object preview. Rows are keyed by field name.
+   *
+   * Optional because it is the only capability here that needs more than a
+   * table name, and because an introspector may be hand-written. Absent, the
+   * dashboard says preview is unavailable rather than failing — see
+   * `previewProjection`.
+   *
+   * This is what makes preview cost the host an SDK upgrade and nothing else:
+   * `drizzleIntrospector(db)` already closes over the connection, so a config
+   * that set `introspector` for the "Namespace reachable" check gains preview
+   * without touching a line.
+   */
+  runProjection?(projection: ProjectionMapping, opts: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
   /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
   sampleSelect(table: string): Promise<void>;
 }
@@ -347,6 +364,20 @@ interface CursorStore {
   get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
   set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
 }
+/** @see ClivlySDK.describeSyncTrigger */
+interface SyncTriggerDescription {
+  /**
+   * `syncTrigger.url` exactly as configured, placeholder and all. The raw
+   * value, so a caller can say what is in the file rather than what survived
+   * resolution.
+   */
+  configured?: string;
+  /**
+   * The URL that would be reported to Clivly on the next heartbeat, or
+   * `undefined` when nothing resolves. An unedited placeholder never resolves.
+   */
+  resolved?: string;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -382,6 +413,18 @@ interface ClivlySDK {
    * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
+  /**
+   * What this app would tell Clivly about its sync trigger route, right now.
+   *
+   * Computed per call rather than frozen at creation: `resolved` can start as
+   * `undefined` and become a real URL once the mounted route has served its
+   * first request and observed its own origin.
+   *
+   * Exists for `clivly status`, which has to tell "no trigger configured"
+   * apart from "configured, but still the scaffolded placeholder" — a
+   * distinction `resolved` alone erases, since it skips placeholders by design.
+   */
+  describeSyncTrigger(): SyncTriggerDescription;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
   /**
@@ -454,4 +497,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-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 };
+export { SyncTriggerDescription 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, NamespaceIntrospector as v };

package/dist/vite.d.cts

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