@clivly/sdk 0.9.6 → 0.10.0

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 = [
@@ -990,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 = [];
@@ -1249,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;
 }
@@ -1269,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 } : {}
 		};
 	});
 }
@@ -1309,6 +1558,24 @@ function timingSafeEqual(a, b) {
 }
 const RUN_ID_HEADER = "x-clivly-run-id";
 const SIGNATURE_HEADER = "x-clivly-signature";
+/**
+* An error the mounted trigger route should answer with a specific HTTP
+* status, rather than the generic 500 it uses for a genuinely unhandled
+* error. A fail-safe rejection (e.g. an unresolvable sample `entityKey`) is a
+* configuration mismatch the caller can fix — surfacing it as "your app
+* crashed" sends a developer hunting through their own sync handler instead.
+*/
+var TriggerRequestError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+	}
+};
+function triggerErrorStatus(error) {
+	return error instanceof TriggerRequestError ? error.status : 500;
+}
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
 const SECONDS_PER_MS = 1e3;
@@ -1490,9 +1757,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;
@@ -1564,18 +1837,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 = {
@@ -1588,7 +1901,7 @@ function createClivlySDK(config) {
 	};
 	const runSampleSync = async (entityKey, runId) => {
 		const resolved = resolveSampleSource(config, entityKey);
-		if (!resolved) throw new Error(`Clivly sync: sample entityKey "${entityKey}" did not resolve to a configured source`);
+		if (!resolved) throw new TriggerRequestError(400, `Clivly sync: no source is configured for entity "${entityKey}". The dashboard maps this table, but clivly.config declares no matching entity — add it to \`entities\`, or remove the mapping in Integrations → Mapping.`);
 		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]));
 	};
@@ -1601,6 +1914,20 @@ function createClivlySDK(config) {
 			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`, {
@@ -1799,7 +2126,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;
@@ -1813,7 +2140,9 @@ function createClivlySDK(config) {
 	const parseTriggerBody = (rawBody) => {
 		if (!rawBody) return {};
 		try {
-			return JSON.parse(rawBody);
+			const parsed = JSON.parse(rawBody);
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			return parsed;
 		} catch {
 			return {};
 		}
@@ -1846,7 +2175,7 @@ function createClivlySDK(config) {
 				ok: false,
 				runId,
 				error: error instanceof Error ? error.message : String(error)
-			}, 500);
+			}, triggerErrorStatus(error));
 		}
 	};
 	const start = async () => {
@@ -1893,7 +2222,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);
@@ -1927,6 +2256,7 @@ function createClivlySDK(config) {
 		ping,
 		doctor,
 		describeSyncTrigger,
+		describeRemoteProjections,
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,

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

@@ -18,6 +18,26 @@ 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.
@@ -378,6 +398,17 @@ interface SyncTriggerDescription {
    */
   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
@@ -413,6 +444,15 @@ 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.
    *
@@ -497,4 +537,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-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 };
+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 };

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

@@ -18,6 +18,26 @@ 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.
@@ -378,6 +398,17 @@ interface SyncTriggerDescription {
    */
   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
@@ -413,6 +444,15 @@ 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.
    *
@@ -497,4 +537,4 @@ interface ClivlySDK {
   }): Promise<void>;
 }
 //#endregion
-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 };
+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 };

package/dist/vite.d.cts

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