@clivly/sdk 0.9.5 → 0.9.7

package/README.md

@@ -330,6 +330,19 @@ 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.
+
+**From `0.9.7` the same setting is what runs derived objects, not just previews
+them.** An object authored in Clivly's dashboard starts syncing on your app's
+next run, with no per-object entry in `clivly.config.ts` — `introspector` is the
+one line that makes it possible, and `npx clivly init` now scaffolds it. Without
+it, dashboard-authored objects are fetched and then skipped; nothing errors, and
+`clivly status` reports it. See [Derived objects](#derived-objects).
+
 ## Common errors and troubleshooting
 
 | Symptom | Cause | Fix |
@@ -468,6 +481,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()` |
 
@@ -512,27 +526,41 @@ rejected key and a dead network all mean the question went unanswered.
 
 A custom object can be derived from a base table plus explicit joins, instead of
 mapping exactly one table — an `Enrollment` built from `enrollments` joined to
-`students` and `courses`. You declare one on an entity in `clivly.config.ts`,
-alongside the object it materializes into; `validateEntitiesConfig` checks it in
-CI.
+`students` and `courses`.
+
+There are two ways to author one, and from `0.9.7` the first needs no code:
+
+- **In Clivly's dashboard.** It starts syncing on your app's next run. The only
+  requirement is `introspector: drizzleIntrospector(db)` in your config, which
+  `npx clivly init` scaffolds — Clivly never connects to your database, so your
+  app needs a handle to run the query with. Each sync fetches your org's active
+  objects, **revalidates every one against the schema your app itself
+  discovered** before compiling any SQL, runs them, and pushes the rows. That
+  revalidation is what confines a dashboard-authored object to the tables you
+  passed to `discoverFromDrizzle`, and nothing wider.
+- **In `clivly.config.ts`.** Declare the projection on an entity alongside the
+  object it materializes into; `validateEntitiesConfig` checks it in CI. Useful
+  when you want the definition reviewed in your repo.
 
-Two things have to line up:
+Two things have to line up either way:
 
 - **Discovery must be rich enough.** `discoverFromDrizzle` sends primary keys,
   unique constraints, nullability, column types and foreign-key edges.
   Validation is fail-closed, so if your config hand-writes `schema` as
-  `{ name, columns }` pairs, every table is rejected with *"has no key/column
-  metadata — upgrade `@clivly/sdk` and re-run discovery"*. Pass
-  `discoverFromDrizzle(schema)` and redeploy so a fresh heartbeat carries the
-  richer payload — and re-run it after schema changes, since projections
-  validate against the last reported snapshot.
+  `{ name, columns }` pairs, every table is rejected with *"was discovered
+  without column types or unique keys"*. Pass `discoverFromDrizzle(schema)` and
+  redeploy so a fresh heartbeat carries the richer payload — and re-run it after
+  schema changes, since projections validate against the last reported snapshot.
 - **The server must have the capability enabled.** Authoring sits behind
   `CLIVLY_PROJECTION_MAPPINGS=true` while the surface settles. Reading and
   syncing an existing derived object is never gated.
 
-> Requires `clivly@0.9.0` / `@clivly/sdk@0.9.0` or later for the discovery
-> metadata. Earlier versions reported names only, so no host app could author a
-> derived object.
+> **Requires `0.9.7` or later.** Every earlier version — `0.9.0` included, despite
+> what this file used to claim — dropped the unique-key half of the discovery
+> payload on the heartbeat, so validation failed closed and *no* host app could
+> author a derived object at any version. `0.9.7` fixes that and is also the
+> first release where a dashboard-authored object syncs without a per-object
+> config entry.
 
 Full guide: [`docs/guides/derived-objects.md`](../../docs/guides/derived-objects.md).
 

package/dist/chat-session.d.cts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-Dz1LQYvQ.cjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-B7HKG2Ph.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-B7HKG2Ph.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

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_drizzle_meta = require("./drizzle-meta-CdCs30q3.cjs");
+let _clivly_core = require("@clivly/core");
 let _clivly_core_drizzle = require("@clivly/core/drizzle");
 let drizzle_orm = require("drizzle-orm");
-let _clivly_core = require("@clivly/core");
 //#region src/drizzle-projection.ts
 /** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
 function refToken(ref) {
@@ -39,10 +39,12 @@ function fromDrizzleProjection(db, projection, opts) {
 	const client = db;
 	const known = /* @__PURE__ */ new Set([_clivly_core.BASE_REF, ...projection.joins.map((j) => j.key)]);
 	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
-	const cursorRef = parseRef(opts.cursorField);
-	assertKnownRef(cursorRef, known, "cursorField");
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
 	const identityExpr = (0, _clivly_core.compileProjectionIdentity)(projection, opts.basePkColumn ?? "");
+	const fromClause = [(0, _clivly_core.compileProjectionFrom)(projection), ...(0, _clivly_core.compileProjectionJoins)(projection)].join(" ");
+	if (opts.cursorField === void 0) return fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
 	const cursorToken = refToken(cursorRef);
 	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
 	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
@@ -54,11 +56,7 @@ function fromDrizzleProjection(db, projection, opts) {
 		emitted.add(token);
 		selectItems.push(`${refSql(binding.from)} AS ${(0, _clivly_core.quoteIdent)(token)}`);
 	}
-	const head = [
-		`select ${selectItems.join(", ")}`,
-		(0, _clivly_core.compileProjectionFrom)(projection),
-		...(0, _clivly_core.compileProjectionJoins)(projection)
-	].join(" ");
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
 		cursorField: cursorToken,
@@ -71,6 +69,49 @@ function fromDrizzleProjection(db, projection, opts) {
 		}
 	};
 }
+/**
+* The identity-only paging path `fromDrizzleProjection` takes when
+* `cursorField` is omitted. Deliberately not a generalisation of the
+* timestamp path above — it selects no timestamp cursor, pages on the
+* identity expression alone, and always reports `cursorField`/`idField` as
+* `"id"`, the alias every row carries either way.
+*/
+function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts) {
+	const selectItems = [`${identityExpr} AS ${(0, _clivly_core.quoteIdent)("id")}`];
+	const emitted = /* @__PURE__ */ new Set();
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${(0, _clivly_core.quoteIdent)(token)}`);
+	}
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: "id",
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? drizzle_orm.sql` where ${drizzle_orm.sql.raw(identityExpr)} > ${since.id}` : drizzle_orm.sql``;
+			const query = drizzle_orm.sql`${drizzle_orm.sql.raw(head)}${where} order by ${drizzle_orm.sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
+//#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.ts
 function inferIdField(table) {
@@ -134,6 +175,16 @@ 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);
+		},
+		projectionSource(projection, opts) {
+			return fromDrizzleProjection(db, projection, {
+				entity: opts.objectType,
+				objectType: opts.objectType,
+				...opts.basePkColumn ? { basePkColumn: opts.basePkColumn } : {}
+			});
 		}
 	};
 }

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.cjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-B7HKG2Ph.cjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
@@ -37,8 +37,14 @@ interface FromDrizzleProjectionOptions {
    * The column to keyset-paginate on, as a ref token (`"base.updated_at"`) or
    * a `ProjectionRef`. A projection spans several tables, so there is no
    * single table to infer a cursor from.
+   *
+   * Omit it to page by identity alone — the mode a dashboard-authored
+   * projection uses, since it has no timestamp column and no UI to nominate
+   * one. `checkIdentitySafety` (`@clivly/core`) already proves the identity
+   * uniquely identifies a row, which makes it a sound keyset cursor with no
+   * timestamp involved.
    */
-  cursorField: string | ProjectionRef;
+  cursorField?: string | ProjectionRef;
   /** The source name rows are pushed under. */
   entity: string;
   /**

package/dist/drizzle.d.mts

@@ -1,7 +1,7 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.mjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-B7HKG2Ph.mjs";
+import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
-import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 //#region src/drizzle-projection.d.ts
 /**
  * Build a `SyncSource` that actually executes a projection's joins.
@@ -37,8 +37,14 @@ interface FromDrizzleProjectionOptions {
    * The column to keyset-paginate on, as a ref token (`"base.updated_at"`) or
    * a `ProjectionRef`. A projection spans several tables, so there is no
    * single table to infer a cursor from.
+   *
+   * Omit it to page by identity alone — the mode a dashboard-authored
+   * projection uses, since it has no timestamp column and no UI to nominate
+   * one. `checkIdentitySafety` (`@clivly/core`) already proves the identity
+   * uniquely identifies a row, which makes it a sound keyset cursor with no
+   * timestamp involved.
    */
-  cursorField: string | ProjectionRef;
+  cursorField?: string | ProjectionRef;
   /** The source name rows are pushed under. */
   entity: string;
   /**

package/dist/drizzle.mjs

@@ -1,7 +1,7 @@
 import { t as DRIZZLE_META } from "./drizzle-meta-DNqzkREf.mjs";
+import { BASE_REF, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, quoteIdent } from "@clivly/core";
 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";
 //#region src/drizzle-projection.ts
 /** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
 function refToken(ref) {
@@ -38,10 +38,12 @@ function fromDrizzleProjection(db, projection, opts) {
 	const client = db;
 	const known = /* @__PURE__ */ new Set([BASE_REF, ...projection.joins.map((j) => j.key)]);
 	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
-	const cursorRef = parseRef(opts.cursorField);
-	assertKnownRef(cursorRef, known, "cursorField");
 	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
 	const identityExpr = compileProjectionIdentity(projection, opts.basePkColumn ?? "");
+	const fromClause = [compileProjectionFrom(projection), ...compileProjectionJoins(projection)].join(" ");
+	if (opts.cursorField === void 0) return fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
 	const cursorToken = refToken(cursorRef);
 	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
 	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
@@ -53,11 +55,7 @@ function fromDrizzleProjection(db, projection, opts) {
 		emitted.add(token);
 		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
 	}
-	const head = [
-		`select ${selectItems.join(", ")}`,
-		compileProjectionFrom(projection),
-		...compileProjectionJoins(projection)
-	].join(" ");
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
 		cursorField: cursorToken,
@@ -70,6 +68,49 @@ function fromDrizzleProjection(db, projection, opts) {
 		}
 	};
 }
+/**
+* The identity-only paging path `fromDrizzleProjection` takes when
+* `cursorField` is omitted. Deliberately not a generalisation of the
+* timestamp path above — it selects no timestamp cursor, pages on the
+* identity expression alone, and always reports `cursorField`/`idField` as
+* `"id"`, the alias every row carries either way.
+*/
+function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromClause, opts) {
+	const selectItems = [`${identityExpr} AS ${quoteIdent("id")}`];
+	const emitted = /* @__PURE__ */ new Set();
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
+	}
+	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: "id",
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? sql` where ${sql.raw(identityExpr)} > ${since.id}` : sql``;
+			const query = sql`${sql.raw(head)}${where} order by ${sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
+//#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.ts
 function inferIdField(table) {
@@ -133,6 +174,16 @@ 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);
+		},
+		projectionSource(projection, opts) {
+			return fromDrizzleProjection(db, projection, {
+				entity: opts.objectType,
+				objectType: opts.objectType,
+				...opts.basePkColumn ? { basePkColumn: opts.basePkColumn } : {}
+			});
 		}
 	};
 }