@clivly/sdk 0.9.5 → 0.9.7

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { customObjectDeclarations, customObjectDeclarations as customObjectDeclarations$1, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 import { entitiesToMappings } from "@clivly/core/mappings-config";
+import { primaryKeyColumns, projectionSchema, validateProjection } from "@clivly/core";
 //#region src/deployment-identity.ts
 const MAX_DEPLOYMENT_ID_LENGTH = 128;
 const PLATFORM_DEPLOYMENT_KEYS = [
@@ -573,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);
@@ -981,6 +991,240 @@ function describeSilentPush(target, body) {
 	return `Clivly sync: pushed ${received} row(s) for ${objectType ? `"${source}" → "${objectType}"` : `"${source}"`} and none were stored — no active mapping in this workspace targets it, so the rows were dropped. Map it in Integrations → Mapping, then sync again.`;
 }
 //#endregion
+//#region src/remote-projections.ts
+const SYNC_CUSTOM_PATH$1 = "/clivly/sdk/sync/custom";
+const MISSING_INTROSPECTOR = "this app cannot run dashboard-authored derived objects yet — add `introspector: drizzleIntrospector(db)` to clivly.config.ts";
+/**
+* Turn definitions fetched from the cloud into runnable sync sources.
+*
+* Revalidates every projection locally against the schema THIS app discovered,
+* never against the cloud's stored copy. Two reasons, and both matter:
+*
+* 1. Security. `checkTablesExist`/`checkRefs` bound every table and column ref
+*    to the schema passed in, so validating against the locally-discovered
+*    schema makes the blast radius exactly the namespace the developer handed
+*    to `discoverFromDrizzle`. Trusting the cloud's verdict instead would let a
+*    compromised cloud read any table in the database.
+* 2. Truth. The stored copy can be stale. A column dropped in the host app
+*    becomes a readable quarantine here instead of a raw Postgres error out of
+*    `sql.raw` at execution time.
+*/
+function resolveRemoteProjections(args) {
+	const { entries, introspector, schema } = args;
+	return entries.map((entry) => resolveOne(entry, schema, introspector));
+}
+/**
+* The base table's PK, resolved from the schema THIS app discovered — never
+* from the cloud's copy.
+*
+* `validateProjection` proved its uniqueness case against this exact source
+* (`primaryKeyColumns` over the locally-discovered schema, see
+* `projection-validate.ts`). Compiling a *different* column — the cloud's
+* `basePkColumn`, which can go stale the moment a host renames a PK and the
+* `updatedAt`-only ETag never invalidates — would defeat that proof and
+* revive the raw-Postgres-error failure mode local revalidation exists to
+* prevent. Only relevant when the identity is `base_pk` with no explicit
+* column; every other identity kind ignores `basePkColumn` entirely.
+*/
+function resolveLocalBasePk(projection, schema) {
+	if (projection.identity.kind !== "base_pk" || projection.identity.column) return;
+	const baseTable = schema.find((t) => t.name === projection.baseTable);
+	if (!baseTable) return;
+	return primaryKeyColumns(baseTable)[0];
+}
+function resolveOne(entry, schema, introspector) {
+	const parsed = projectionSchema.safeParse(entry.projection);
+	if (!parsed.success) return {
+		id: entry.id,
+		status: "invalid",
+		reason: `projection did not parse: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+	};
+	const projection = parsed.data;
+	const errors = validateProjection(projection, schema, entry.entityKey);
+	if (errors.length > 0) return {
+		id: entry.id,
+		status: "invalid",
+		reason: errors.map((e) => `${e.path}: ${e.message}`).join("; ")
+	};
+	if (!introspector?.projectionSource) return {
+		id: entry.id,
+		status: "skipped",
+		reason: MISSING_INTROSPECTOR
+	};
+	try {
+		const basePkColumn = resolveLocalBasePk(projection, schema) ?? entry.basePkColumn;
+		const source = introspector.projectionSource(projection, {
+			objectType: entry.objectType,
+			...basePkColumn ? { basePkColumn } : {}
+		});
+		return {
+			id: entry.id,
+			status: "ok",
+			source
+		};
+	} catch (error) {
+		return {
+			id: entry.id,
+			status: "failed",
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+const PROJECTIONS_PATH = "/clivly/sdk/projections";
+const PROJECTIONS_REPORT_PATH = "/clivly/sdk/projections/report";
+const MAX_REASON = 2e3;
+/**
+* Merge what resolution decided with what the push actually did.
+*
+* A `status: "ok"` outcome means the projection *resolved*, not that its rows
+* landed. If the push then failed, the object did not sync and must not be
+* reported as healthy — so the push result wins for those.
+*/
+function buildRemoteProjectionReport(args) {
+	return {
+		...args.runId ? { runId: args.runId } : {},
+		results: args.outcomes.map((outcome) => {
+			if (outcome.status !== "ok") return {
+				id: outcome.id,
+				status: outcome.status,
+				reason: outcome.reason.slice(0, MAX_REASON)
+			};
+			const result = args.pushed.get(outcome.source.entity);
+			if (result?.ok) return {
+				id: outcome.id,
+				status: "ok",
+				rows: result.count
+			};
+			return {
+				id: outcome.id,
+				status: "failed",
+				reason: (result?.reason ?? "the push to Clivly failed; rows were read but not stored").slice(0, MAX_REASON)
+			};
+		})
+	};
+}
+function createRemoteProjectionFetcher(args) {
+	let etag = null;
+	let cached = [];
+	return { async fetch() {
+		try {
+			const response = await args.fetcher(`${args.apiUrl}${PROJECTIONS_PATH}`, { headers: {
+				authorization: `Bearer ${args.apiKey}`,
+				...etag ? { "if-none-match": etag } : {}
+			} });
+			if (response.status === 304) return cached;
+			if (!response.ok) return [];
+			const body = await response.json();
+			etag = body.etag ?? null;
+			cached = body.projections ?? [];
+			return cached;
+		} catch {
+			return [];
+		}
+	} };
+}
+const REMOTE_PAGE_SIZE = 500;
+/**
+* Page one source to exhaustion, keyset-paging on identity alone (the id
+* field, no timestamp). Split out of `pushRemoteProjections` so that
+* function's own cognitive complexity stays under the lint threshold — this
+* is the piece that can throw (a `fetchPage` execution error), kept separate
+* from push-failure handling below.
+*/
+async function fetchAllPages(source, pageSize) {
+	const idField = source.idField ?? "id";
+	const all = [];
+	let since = null;
+	for (;;) {
+		const rows = await source.fetchPage({
+			since,
+			limit: pageSize
+		});
+		if (rows.length === 0) break;
+		all.push(...rows);
+		const last = rows.at(-1);
+		const nextId = String(last?.[idField]);
+		if (since && nextId === since.id) break;
+		since = { id: nextId };
+		if (rows.length < pageSize) break;
+	}
+	return all;
+}
+/**
+* Page a remote projection by identity and push one `full` batch.
+*
+* `full` rather than `delta` because only a full push lets the server archive
+* rows that dropped out when a join or filter stopped matching — a delta cannot
+* express absence. And identity rather than a timestamp because a
+* dashboard-authored projection has no watermark column, while validation has
+* already proven the identity unique.
+*
+* `pageSize` defaults to `REMOTE_PAGE_SIZE` and exists so a test can force a
+* short page without either mutating the exported constant or constructing a
+* fixture hundreds of rows deep.
+*
+* Returns one entry per source, keyed by `source.entity`. `count` and `ok`
+* are independent: `count` is how many rows were pushed (0 for a projection
+* that legitimately matches nothing this run), `ok` is whether the push
+* itself succeeded. A caller that folds failures into a report must branch
+* on `ok`, never on `count === 0` — a correctly-working, legitimately-empty
+* projection has `ok: true, count: 0` and is not a failure.
+*
+* Each source's paging-and-push is wrapped individually: a projection can
+* validate cleanly and still fail at execution — permission denied, a type
+* error, a column dropped between validation and this run — and `fetchPage`
+* throwing is the realistic shape of that. Quarantine that one source as
+* `{ count: 0, ok: false, reason }` and keep going. The design's promise is
+* one bad object never takes down the others or the run's report; letting a
+* throw here escape the loop would break that promise for every source
+* queued after the failing one.
+*
+* Paging and pushing are caught separately, on purpose: `reason` is set only
+* when paging itself threw (no rows were ever read), so the reported cause
+* names execution — not the push, which is what actually failed when
+* `args.push` returns `false`. Conflating the two sent an author whose
+* projection can't even run to look at their push credentials instead of
+* their SQL.
+*/
+async function pushRemoteProjections(args) {
+	const pageSize = args.pageSize ?? REMOTE_PAGE_SIZE;
+	const pushed = /* @__PURE__ */ new Map();
+	for (const source of args.sources) {
+		let all;
+		try {
+			all = await fetchAllPages(source, pageSize);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			pushed.set(source.entity, {
+				count: 0,
+				ok: false,
+				reason: `the projection failed to execute: ${message}`.slice(0, MAX_REASON)
+			});
+			continue;
+		}
+		try {
+			const ok = await args.push(SYNC_CUSTOM_PATH$1, {
+				source: source.entity,
+				rows: all,
+				mode: "full",
+				fetched: all.length,
+				cursor: null,
+				objectType: source.objectType
+			});
+			pushed.set(source.entity, {
+				count: all.length,
+				ok
+			});
+		} catch {
+			pushed.set(source.entity, {
+				count: 0,
+				ok: false
+			});
+		}
+	}
+	return pushed;
+}
+//#endregion
 //#region src/self-check.ts
 function selfCheck(input) {
 	const issues = [];
@@ -1240,12 +1484,25 @@ function resolveContactEntity(config) {
 }
 function collectSchemaMeta(config) {
 	const byTable = /* @__PURE__ */ new Map();
-	for (const table of config.schema ?? []) if (table.columnsMeta) byTable.set(table.name, table.columnsMeta);
+	const merge = (name, meta) => {
+		const existing = byTable.get(name);
+		byTable.set(name, {
+			columnsMeta: meta.columnsMeta ?? existing?.columnsMeta,
+			uniqueConstraints: meta.uniqueConstraints ?? existing?.uniqueConstraints
+		});
+	};
+	for (const table of config.schema ?? []) if (table.columnsMeta || table.uniqueConstraints) merge(table.name, {
+		columnsMeta: table.columnsMeta,
+		uniqueConstraints: table.uniqueConstraints
+	});
 	const sources = [];
 	if (config.source) sources.push(config.source.contacts, config.source.companies, config.source.deals, ...config.source.custom ?? []);
 	for (const source of sources) {
 		const meta = source?.[DRIZZLE_META];
-		if (meta?.tableName && meta.columnsMeta) byTable.set(meta.tableName, meta.columnsMeta);
+		if (meta?.tableName && (meta.columnsMeta || meta.uniqueConstraints)) merge(meta.tableName, {
+			columnsMeta: meta.columnsMeta,
+			uniqueConstraints: meta.uniqueConstraints
+		});
 	}
 	return byTable;
 }
@@ -1260,12 +1517,13 @@ function buildSchema(config) {
 	if (config.contactEntity && !byName.has(config.contactEntity)) byName.set(config.contactEntity, new Set(config.contactFields ?? []));
 	const metaByTable = collectSchemaMeta(config);
 	return [...byName].map(([name, columns]) => {
-		const columnsMeta = metaByTable.get(name);
-		if (columnsMeta) for (const col of columnsMeta) columns.add(col.name);
+		const meta = metaByTable.get(name);
+		for (const col of meta?.columnsMeta ?? []) columns.add(col.name);
 		return {
 			name,
 			columns: [...columns],
-			...columnsMeta ? { columnsMeta } : {}
+			...meta?.columnsMeta ? { columnsMeta: meta.columnsMeta } : {},
+			...meta?.uniqueConstraints ? { uniqueConstraints: meta.uniqueConstraints } : {}
 		};
 	});
 }
@@ -1445,6 +1703,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
@@ -1472,9 +1739,15 @@ function createClivlySDK(config) {
 	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	const remoteProjections = createRemoteProjectionFetcher({
+		apiKey: config.apiKey,
+		apiUrl,
+		fetcher
+	});
 	let observedUrl;
 	let lastPushFailure = null;
 	let lastPush = { failed: false };
+	let lastRemoteOutcomes = [];
 	const warnedSilentTargets = /* @__PURE__ */ new Set();
 	const warnIfSilent = async (target, response) => {
 		if (typeof response.json !== "function") return;
@@ -1546,18 +1819,58 @@ function createClivlySDK(config) {
 		for (const customSource of customSources ?? []) if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
 		return failed;
 	};
+	const syncRemoteSources = async (sources, runId) => {
+		const pushed = await pushRemoteProjections({
+			push: createPush(runId),
+			sources
+		});
+		const failed = [];
+		for (const [entity, result] of pushed) if (!result.ok) failed.push(entity);
+		return {
+			failed,
+			pushed
+		};
+	};
+	const reportRemoteOutcomes = async (outcomes, pushed, runId) => {
+		if (outcomes.length === 0) return;
+		try {
+			const report = buildRemoteProjectionReport({
+				outcomes,
+				pushed,
+				runId
+			});
+			await fetcher(`${apiUrl}${PROJECTIONS_REPORT_PATH}`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${config.apiKey}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(report)
+			});
+		} catch {}
+	};
 	const runSync = async (options) => {
-		if (!config.source) return;
+		const remoteOutcomes = resolveRemoteProjections({
+			entries: await remoteProjections.fetch(),
+			introspector: config.introspector,
+			schema: buildSchema(config)
+		});
+		lastRemoteOutcomes = remoteOutcomes;
+		const remoteSources = remoteOutcomes.filter((o) => o.status === "ok").map((o) => o.source);
+		if (!config.source && remoteSources.length === 0 && remoteOutcomes.length === 0) return;
 		lastPushFailure = null;
 		const mode = options?.mode ?? "delta";
 		const runId = options?.runId;
 		const failed = [];
-		if (config.source.companies) {
+		if (config.source?.companies) {
 			if (!await syncOne(config.source.companies, SYNC_COMPANIES_PATH, mode, void 0, runId)) failed.push(config.source.companies.entity);
 		}
-		if (!await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode, void 0, runId)) failed.push(config.source.contacts.entity);
-		if (config.source.deals && !await syncOne(config.source.deals, SYNC_DEALS_PATH, mode, void 0, runId)) failed.push(config.source.deals.entity);
-		failed.push(...await syncCustomSources(config.source.custom, mode, runId));
+		if (config.source?.contacts && !await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode, void 0, runId)) failed.push(config.source.contacts.entity);
+		if (config.source?.deals && !await syncOne(config.source.deals, SYNC_DEALS_PATH, mode, void 0, runId)) failed.push(config.source.deals.entity);
+		failed.push(...await syncCustomSources(config.source?.custom, mode, runId));
+		const remote = await syncRemoteSources(remoteSources, runId);
+		failed.push(...remote.failed);
+		await reportRemoteOutcomes(lastRemoteOutcomes, remote.pushed, runId);
 		if (failed.length > 0) {
 			const message = describePushFailure(failed);
 			lastPush = {
@@ -1574,13 +1887,31 @@ 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 describeRemoteProjections = () => {
+		const counts = {
+			failed: 0,
+			invalid: 0,
+			ok: 0,
+			skipped: 0
+		};
+		for (const outcome of lastRemoteOutcomes) counts[outcome.status] += 1;
+		return {
+			capable: Boolean(config.introspector?.projectionSource),
+			ran: lastRemoteOutcomes.length > 0,
+			...counts
+		};
+	};
+	const sendHeartbeat = () => {
+		const triggerUrl = describeSyncTrigger().resolved;
 		return fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
 			method: "POST",
 			headers: {
@@ -1777,7 +2108,7 @@ function createClivlySDK(config) {
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
-		if (config.source) await runSync(options);
+		if (config.source || config.introspector) await runSync(options);
 	};
 	const triggerRequestAllowed = async (req, rawBody) => {
 		const secret = config.syncTrigger?.secret;
@@ -1808,6 +2139,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,
@@ -1870,7 +2202,7 @@ function createClivlySDK(config) {
 			presenceClient = null;
 			console.warn("Clivly presence socket unavailable; using HTTP heartbeat", error);
 		}
-		if (!timers.sync && config.source) {
+		if (!timers.sync && (config.source || config.introspector)) {
 			timers.sync = setInterval(() => {
 				runSync().catch(() => {});
 			}, syncIntervalMs);
@@ -1903,6 +2235,8 @@ function createClivlySDK(config) {
 		connect,
 		ping,
 		doctor,
+		describeSyncTrigger,
+		describeRemoteProjections,
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,

package/dist/{types-Dz1LQYvQ.d.cts → types-B7HKG2Ph.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,43 @@ interface DrizzleSourceMeta {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Build a runnable sync source from a projection, for derived objects
+   * authored in the dashboard rather than in `clivly.config.ts`.
+   *
+   * Optional for the same reason `runProjection` is: an introspector may be
+   * hand-written. Absent, remote projections report `skipped` with a reason
+   * naming this method, rather than failing the run.
+   *
+   * This is deliberately the only route to a database handle for remote
+   * projections. `drizzleIntrospector(db)` already closes over the
+   * connection, so `introspector:` is the single config line that turns
+   * dashboard-authored objects on — and the SDK core never holds a raw
+   * client.
+   */
+  projectionSource?(projection: ProjectionMapping, opts: {
+    basePkColumn?: string;
+    objectType: string;
+  }): SyncSource & {
+    objectType: 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 +384,31 @@ 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;
+}
+/** @see ClivlySDK.describeRemoteProjections */
+interface RemoteProjectionsDescription {
+  /** False when no `introspector` is configured — nothing can run. */
+  capable: boolean;
+  failed: number;
+  invalid: number;
+  ok: number;
+  /** False until a sync has run in this process. */
+  ran: boolean;
+  skipped: number;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -382,6 +444,27 @@ 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 dashboard-authored derived objects,
+   * right now. Counts rather than the outcomes themselves: this reports
+   * health, and the per-object reasons already travel to the dashboard, which
+   * is where an author fixes them.
+   *
+   * Read by `clivly status`.
+   */
+  describeRemoteProjections(): RemoteProjectionsDescription;
+  /**
+   * 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 +537,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 { SyncSource as _, ClivlySDK as a, CreateChatSessionHandlerOptions as c, DoctorCheck as d, DoctorReport as f, RemoteProjectionsDescription 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, SyncTriggerDescription as v, NamespaceIntrospector as y };