@clivly/sdk 0.9.2 → 0.9.4

package/README.md

@@ -453,6 +453,7 @@ is honoured. Other `4xx` responses return immediately.
 | Method | Returns | Notes |
 | --- | --- | --- |
 | `connect()` | `Promise<ClivlyConnectResult>` | One heartbeat, structured. Never throws |
+| `ping()` | `Promise<ClivlyConnectResult>` | Zero-write reachability probe. Same shape as `connect()`, but records no heartbeat — and it alone returns `workspace` |
 | `heartbeat()` | `Promise<boolean>` | One heartbeat, boolean |
 | `start()` | `Promise<void>` | Heartbeat + boot sync + timers. Long-lived hosts only; opens opt-in WebSocket presence |
 | `stop()` | `void` | Clears the timers |
@@ -461,6 +462,19 @@ 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 }` |
+| `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()` |
+
+`clivly push-schema` calls `ensureSchema()` for you, so you rarely need it
+directly — reach for it when you want config-as-code to run from your own
+deploy script or a CI step.
+
+The `null`-vs-throw split is deliberate. `null` means the request never landed
+(network, or a Clivly older than the route), which is worth a retry. A rejection
+means Clivly understood the config and declined it — most often because an
+entity would overwrite a mapping someone edited in the dashboard — which is
+worth reading, not retrying. A config-declared mapping is owned by your config;
+a dashboard-edited one is never silently overwritten.
 
 ### `ClivlyConnectResult.reason`
 
@@ -468,6 +482,17 @@ is honoured. Other `4xx` responses return immediately.
 `server_error` (5xx) · `client_error` (other 4xx) · `network_error` (no
 response).
 
+### `ClivlyConnectResult.workspace`
+
+`ping()` also returns `workspace` — the setup ladder for the org behind your key
+(`IntegrationState` from `@clivly/core`), computed by the server so the CLI and
+the dashboard cannot disagree about how far setup has got. This is what
+`clivly status` prints under **Workspace**.
+
+It is `undefined` or `null` when the server predates the field or could not read
+it. Treat that as *unknown*, never as *nothing is set up* — an old server, a
+rejected key and a dead network all mean the question went unanswered.
+
 ### Subpath exports
 
 | From `clivly` | From `@clivly/sdk` | Contents |

package/dist/chat-session.d.cts

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

@@ -2,6 +2,76 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 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/drizzle-projection.ts
+/** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
+function refToken(ref) {
+	return `${ref.table}.${ref.column}`;
+}
+function refSql(ref) {
+	return `${(0, _clivly_core.quoteIdent)(ref.table)}.${(0, _clivly_core.quoteIdent)(ref.column)}`;
+}
+function parseRef(value) {
+	if (typeof value !== "string") return value;
+	const dot = value.indexOf(".");
+	if (dot <= 0 || dot === value.length - 1) throw new Error(`fromDrizzleProjection: cursorField "${value}" must be a ref token like "base.updated_at".`);
+	return {
+		table: value.slice(0, dot),
+		column: value.slice(dot + 1)
+	};
+}
+/**
+* Refs address tables symbolically — `base` or a join key — never by table name,
+* which is what stops a projection reaching a table it did not declare. An
+* unresolvable ref would otherwise compile to SQL referencing a missing alias
+* and fail at the database with a message that never mentions the config.
+*/
+function assertKnownRef(ref, known, context) {
+	if (!known.has(ref.table)) throw new Error(`fromDrizzleProjection: ${context} names unknown ref "${ref.table}" — expected "${[...known].join("\", \"")}".`);
+}
+function normalizeRows(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("fromDrizzleProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+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 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"')`;
+	const selectItems = [`${identityExpr} AS ${(0, _clivly_core.quoteIdent)("id")}`, `${cursorRead} AS ${(0, _clivly_core.quoteIdent)(cursorToken)}`];
+	const emitted = /* @__PURE__ */ new Set([cursorToken]);
+	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(", ")}`,
+		(0, _clivly_core.compileProjectionFrom)(projection),
+		...(0, _clivly_core.compileProjectionJoins)(projection)
+	].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: cursorToken,
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? drizzle_orm.sql` where (${drizzle_orm.sql.raw(cursorExpr)}, ${drizzle_orm.sql.raw(identityExpr)}) > (${since.time.toISOString()}::timestamptz, ${since.id})` : drizzle_orm.sql``;
+			const query = drizzle_orm.sql`${drizzle_orm.sql.raw(head)}${where} order by ${drizzle_orm.sql.raw(cursorExpr)} asc, ${drizzle_orm.sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
 //#region src/drizzle.ts
 function inferIdField(table) {
 	const columns = (0, drizzle_orm.getTableColumns)(table);
@@ -14,14 +84,6 @@ function inferIdField(table) {
 	const kind = primaryKeys.length === 0 ? "no" : "a composite";
 	throw new Error(`fromDrizzle: table "${(0, drizzle_orm.getTableName)(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
 }
-/**
-* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
-* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
-* `idField` defaults to the table's single-column primary key.
-*
-* `drizzle-orm` is an optional peer dependency — installed only when you import
-* `@clivly/sdk/drizzle`.
-*/
 function fromDrizzle(db, table, opts) {
 	const drizzleDb = db;
 	const idField = opts.idField ?? inferIdField(table);
@@ -38,7 +100,8 @@ function fromDrizzle(db, table, opts) {
 		entity: opts.entity,
 		cursorField: cursorColumnName,
 		idField: idColumnName,
-		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit),
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType }
 	};
 	const uniqueConstraints = (0, _clivly_core_drizzle.buildUniqueConstraints)(table);
 	const meta = {
@@ -89,3 +152,4 @@ Object.defineProperty(exports, "discoverFromDrizzle", {
 });
 exports.drizzleIntrospector = drizzleIntrospector;
 exports.fromDrizzle = fromDrizzle;
+exports.fromDrizzleProjection = fromDrizzleProjection;

package/dist/drizzle.d.cts

@@ -1,23 +1,99 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.cjs";
+import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.cjs";
+import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
+//#region src/drizzle-projection.d.ts
+/**
+ * Build a `SyncSource` that actually executes a projection's joins.
+ *
+ * `fromDrizzle` emits a single-table select, so a projection entity paired with
+ * it pushed raw base-table rows and every joined field mirrored empty — the
+ * declared joins were inert, and the only symptom was a dry run reporting a
+ * missing column whose name was correct.
+ *
+ * The row shape is the contract the cloud already relies on. A projection's
+ * `fields` are ref *tokens* (`client_name -> "cl.full_name"`, from
+ * `projectionFields`), and `cloud-ingest` reads `row[token]` verbatim plus
+ * `row.id` for `sourceRef`. So this aliases every binding by its token rather
+ * than by its field name.
+ *
+ * That is the one deliberate difference from the view compiler, which aliases
+ * by field name because the sync engine reads the compiled view directly. FROM,
+ * JOIN and the identity expression all come from `@clivly/core`, so both paths
+ * join identically and produce the same `id` for the same row.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`. The `db` only needs `.execute()`, the same surface
+ * `drizzleIntrospector` requires.
+ */
+interface FromDrizzleProjectionOptions {
+  /**
+   * The base table's primary key, required only when `identity` is `base_pk`
+   * without an explicit column. Unlike `fromDrizzle` there is no `Table` object
+   * to infer it from — a projection names tables as strings.
+   */
+  basePkColumn?: string;
+  /**
+   * 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.
+   */
+  cursorField: string | ProjectionRef;
+  /** The source name rows are pushed under. */
+  entity: string;
+  /**
+   * The custom object slug. Accepted here so the result is directly assignable
+   * to `source.custom` — bolting it on with a spread afterwards drops the
+   * non-enumerable drizzle metadata.
+   */
+  objectType?: string;
+}
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions): SyncSource;
+//#endregion
 //#region src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
 }
+interface FromDrizzleOptions {
+  cursorField: string;
+  entity: string;
+  idField?: string;
+  /**
+   * Custom-object slug, for sources destined for `source.custom`.
+   *
+   * Pass it here rather than attaching it afterwards. `source.custom` is typed
+   * `Array<SyncSource & { objectType: string }>`, so before this option existed
+   * the only way to satisfy that type was to bolt the property on post-hoc —
+   * and the idiomatic spread (`{ ...fromDrizzle(...), objectType }`) copies only
+   * ENUMERABLE own properties, silently dropping the non-enumerable
+   * `DRIZZLE_META` below. `doctor` would then report a `fromDrizzle` source as
+   * "hand-written" and skip its cursor/id column checks, which is both a lost
+   * check and a false explanation.
+   */
+  objectType?: string;
+}
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
  * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
  * `idField` defaults to the table's single-column primary key.
  *
+ * Pass `objectType` for custom objects — the result is then directly assignable
+ * to `source.custom` with no spread or mutation.
+ *
  * `drizzle-orm` is an optional peer dependency — installed only when you import
  * `@clivly/sdk/drizzle`.
  */
-declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
-  entity: string;
-  cursorField: string;
-  idField?: string;
-}): SyncSource;
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema
@@ -25,4 +101,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { type FromDrizzleProjectionOptions, buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/dist/drizzle.d.mts

@@ -1,23 +1,99 @@
-import { _ as NamespaceIntrospector, g as SyncSource } from "./types-DxG4rHyo.mjs";
+import { _ as NamespaceIntrospector, g as SyncSource } from "./types-Dz1LQYvQ.mjs";
 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.
+ *
+ * `fromDrizzle` emits a single-table select, so a projection entity paired with
+ * it pushed raw base-table rows and every joined field mirrored empty — the
+ * declared joins were inert, and the only symptom was a dry run reporting a
+ * missing column whose name was correct.
+ *
+ * The row shape is the contract the cloud already relies on. A projection's
+ * `fields` are ref *tokens* (`client_name -> "cl.full_name"`, from
+ * `projectionFields`), and `cloud-ingest` reads `row[token]` verbatim plus
+ * `row.id` for `sourceRef`. So this aliases every binding by its token rather
+ * than by its field name.
+ *
+ * That is the one deliberate difference from the view compiler, which aliases
+ * by field name because the sync engine reads the compiled view directly. FROM,
+ * JOIN and the identity expression all come from `@clivly/core`, so both paths
+ * join identically and produce the same `id` for the same row.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`. The `db` only needs `.execute()`, the same surface
+ * `drizzleIntrospector` requires.
+ */
+interface FromDrizzleProjectionOptions {
+  /**
+   * The base table's primary key, required only when `identity` is `base_pk`
+   * without an explicit column. Unlike `fromDrizzle` there is no `Table` object
+   * to infer it from — a projection names tables as strings.
+   */
+  basePkColumn?: string;
+  /**
+   * 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.
+   */
+  cursorField: string | ProjectionRef;
+  /** The source name rows are pushed under. */
+  entity: string;
+  /**
+   * The custom object slug. Accepted here so the result is directly assignable
+   * to `source.custom` — bolting it on with a spread afterwards drops the
+   * non-enumerable drizzle metadata.
+   */
+  objectType?: string;
+}
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions): SyncSource;
+//#endregion
 //#region src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
 }
+interface FromDrizzleOptions {
+  cursorField: string;
+  entity: string;
+  idField?: string;
+  /**
+   * Custom-object slug, for sources destined for `source.custom`.
+   *
+   * Pass it here rather than attaching it afterwards. `source.custom` is typed
+   * `Array<SyncSource & { objectType: string }>`, so before this option existed
+   * the only way to satisfy that type was to bolt the property on post-hoc —
+   * and the idiomatic spread (`{ ...fromDrizzle(...), objectType }`) copies only
+   * ENUMERABLE own properties, silently dropping the non-enumerable
+   * `DRIZZLE_META` below. `doctor` would then report a `fromDrizzle` source as
+   * "hand-written" and skip its cursor/id column checks, which is both a lost
+   * check and a false explanation.
+   */
+  objectType?: string;
+}
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
  * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
  * `idField` defaults to the table's single-column primary key.
  *
+ * Pass `objectType` for custom objects — the result is then directly assignable
+ * to `source.custom` with no spread or mutation.
+ *
  * `drizzle-orm` is an optional peer dependency — installed only when you import
  * `@clivly/sdk/drizzle`.
  */
-declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
-  entity: string;
-  cursorField: string;
-  idField?: string;
-}): SyncSource;
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema
@@ -25,4 +101,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { type FromDrizzleProjectionOptions, buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/dist/drizzle.mjs

@@ -1,6 +1,76 @@
 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";
+//#region src/drizzle-projection.ts
+/** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
+function refToken(ref) {
+	return `${ref.table}.${ref.column}`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+function parseRef(value) {
+	if (typeof value !== "string") return value;
+	const dot = value.indexOf(".");
+	if (dot <= 0 || dot === value.length - 1) throw new Error(`fromDrizzleProjection: cursorField "${value}" must be a ref token like "base.updated_at".`);
+	return {
+		table: value.slice(0, dot),
+		column: value.slice(dot + 1)
+	};
+}
+/**
+* Refs address tables symbolically — `base` or a join key — never by table name,
+* which is what stops a projection reaching a table it did not declare. An
+* unresolvable ref would otherwise compile to SQL referencing a missing alias
+* and fail at the database with a message that never mentions the config.
+*/
+function assertKnownRef(ref, known, context) {
+	if (!known.has(ref.table)) throw new Error(`fromDrizzleProjection: ${context} names unknown ref "${ref.table}" — expected "${[...known].join("\", \"")}".`);
+}
+function normalizeRows(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("fromDrizzleProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+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 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"')`;
+	const selectItems = [`${identityExpr} AS ${quoteIdent("id")}`, `${cursorRead} AS ${quoteIdent(cursorToken)}`];
+	const emitted = /* @__PURE__ */ new Set([cursorToken]);
+	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(", ")}`,
+		compileProjectionFrom(projection),
+		...compileProjectionJoins(projection)
+	].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: cursorToken,
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? sql` where (${sql.raw(cursorExpr)}, ${sql.raw(identityExpr)}) > (${since.time.toISOString()}::timestamptz, ${since.id})` : sql``;
+			const query = sql`${sql.raw(head)}${where} order by ${sql.raw(cursorExpr)} asc, ${sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
 //#region src/drizzle.ts
 function inferIdField(table) {
 	const columns = getTableColumns(table);
@@ -13,14 +83,6 @@ function inferIdField(table) {
 	const kind = primaryKeys.length === 0 ? "no" : "a composite";
 	throw new Error(`fromDrizzle: table "${getTableName(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
 }
-/**
-* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
-* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
-* `idField` defaults to the table's single-column primary key.
-*
-* `drizzle-orm` is an optional peer dependency — installed only when you import
-* `@clivly/sdk/drizzle`.
-*/
 function fromDrizzle(db, table, opts) {
 	const drizzleDb = db;
 	const idField = opts.idField ?? inferIdField(table);
@@ -37,7 +99,8 @@ function fromDrizzle(db, table, opts) {
 		entity: opts.entity,
 		cursorField: cursorColumnName,
 		idField: idColumnName,
-		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit),
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType }
 	};
 	const uniqueConstraints = buildUniqueConstraints$1(table);
 	const meta = {
@@ -74,4 +137,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/dist/index.cjs

@@ -125,11 +125,16 @@ function checkConceptCoverage(config) {
 }
 //#endregion
 //#region src/custom-slug.ts
+const SLUG_PATTERN = /^[a-z][a-z0-9_-]*$/;
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
 function slugify(value) {
 	return value.toLowerCase().trim().replace(NON_ALNUM, "-").replace(EDGE_HYPHENS, "");
 }
+function suggestionFor(declared) {
+	const candidate = slugify(declared);
+	return candidate !== declared && SLUG_PATTERN.test(candidate) ? ` Did you mean "${candidate}"?` : "";
+}
 function checkCustomObjectSlugs(config) {
 	const custom = config.source?.custom ?? [];
 	const declared = config.entities ? (0, _clivly_core_entity_config.customObjectDeclarations)(config.entities) : [];
@@ -143,12 +148,11 @@ function checkCustomObjectSlugs(config) {
 	const seen = /* @__PURE__ */ new Map();
 	for (const source of custom) {
 		const declared = source.objectType;
-		const canonical = slugify(declared);
-		if (canonical === "") problems.push(`"${source.entity}" has an empty objectType.`);
-		else if (canonical !== declared) problems.push(`"${declared}" is not a slug — the dashboard would store it as "${canonical}".`);
-		const prior = seen.get(canonical);
-		if (prior && canonical !== "") problems.push(`duplicate slug "${canonical}" declared by "${prior}" and "${source.entity}".`);
-		else seen.set(canonical, source.entity);
+		if (declared === "") problems.push(`"${source.entity}" has an empty objectType.`);
+		else if (!SLUG_PATTERN.test(declared)) problems.push(`"${declared}" is not a valid object type slug — use lowercase letters, digits, "-" or "_", starting with a letter.${suggestionFor(declared)}`);
+		const prior = seen.get(declared);
+		if (prior && declared !== "") problems.push(`duplicate slug "${declared}" declared by "${prior}" and "${source.entity}".`);
+		else seen.set(declared, source.entity);
 	}
 	if (problems.length > 0) return {
 		name: "Custom object slugs",
@@ -255,10 +259,20 @@ async function runMappingDryRun(config, entityKey) {
 		detail: `"${resolved.source.entity}" is empty — nothing to map yet.`
 	};
 	const missing = Object.entries(fields).filter(([, column]) => !(column in row)).map(([field, column]) => `${field} → ${column}`);
+	if (missing.length === 0) return {
+		name,
+		ok: true,
+		detail: `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.`
+	};
+	if (config.entities?.entities?.[entityKey]?.projection !== void 0 && missing.length === Object.keys(fields).length) return {
+		name,
+		ok: false,
+		detail: `Row from "${resolved.source.entity}" carries none of the projection's columns (${missing.join(", ")}) — the source performs no joins, so the projection is declared but never executed. Build it with \`fromDrizzleProjection\` from \`clivly/drizzle\`, which runs the joins and returns rows keyed by ref token.`
+	};
 	return {
 		name,
-		ok: missing.length === 0,
-		detail: missing.length === 0 ? `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.` : `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
+		ok: false,
+		detail: `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
 	};
 }
 //#endregion
@@ -467,9 +481,27 @@ async function mappingDryRunChecks(config) {
 	return checks;
 }
 /**
+* Why a source has no `DRIZZLE_META`, without asserting more than we know.
+*
+* There are two ways to get here and they are indistinguishable at runtime: the
+* source really was hand-written, or it came from `fromDrizzle` and a spread
+* stripped the metadata, which is non-enumerable. The second is easy to fall
+* into precisely where `objectType` is present — `source.custom` is typed
+* `Array<SyncSource & { objectType: string }>`, so attaching that property with
+* `{ ...fromDrizzle(...), objectType }` used to be the only way to satisfy it.
+*
+* Flatly calling such a source "hand-written" sent developers looking for one
+* that does not exist. Where `objectType` is present, name the likelier cause
+* and the fix instead of guessing wrong with confidence.
+*/
+function missingMetaDetail(source) {
+	const skipped = "column check skipped";
+	if (source.objectType === void 0) return `"${source.entity}" is a hand-written source — ${skipped}.`;
+	return `"${source.entity}" has no drizzle metadata — ${skipped}. If it came from \`fromDrizzle\`, a spread such as \`{ ...fromDrizzle(...), objectType }\` dropped it; pass \`objectType\` to \`fromDrizzle\` instead.`;
+}
+/**
 * Confirm each drizzle source actually has the cursor and id columns the sync
-* pages on. Hand-written sources have no column metadata, so they are skipped
-* rather than failed.
+* pages on. Sources with no column metadata are skipped rather than failed.
 */
 function cursorColumnChecks(sources) {
 	const checks = [];
@@ -480,7 +512,7 @@ function cursorColumnChecks(sources) {
 				name: `Cursor/id columns exist (${source.entity})`,
 				ok: false,
 				skipped: true,
-				detail: `"${source.entity}" is a hand-written source — column check skipped.`
+				detail: missingMetaDetail(source)
 			});
 			continue;
 		}
@@ -1119,11 +1151,16 @@ function observedTriggerUrl(req) {
 		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
 	} catch {}
 }
+const PLACEHOLDER_BRACKETS = /[<>]/;
+function isPlaceholderUrl(value) {
+	return PLACEHOLDER_BRACKETS.test(value);
+}
 /**
 * Decide which trigger URL to report, in precedence order:
 *
 *   1. `configuredUrl` — an explicit `syncTrigger.url`. Someone typed this on
-*      purpose, so it beats anything inferred.
+*      purpose, so it beats anything inferred. An unedited placeholder is not
+*      "on purpose" and is skipped.
 *   2. platform env origin + `configuredPath` — available at boot, before any
 *      request has arrived. Needs the path because platform variables only give
 *      an origin.
@@ -1133,7 +1170,7 @@ function observedTriggerUrl(req) {
 * doesn't need to know about it.
 */
 function resolveTriggerUrl(args) {
-	if (args.configuredUrl) return args.configuredUrl;
+	if (args.configuredUrl && !isPlaceholderUrl(args.configuredUrl)) return args.configuredUrl;
 	const origin = originFromPlatformEnv(args.env);
 	if (origin && args.configuredPath) return `${origin}${args.configuredPath.startsWith("/") ? args.configuredPath : `/${args.configuredPath}`}`;
 	return args.observedUrl;
@@ -1702,6 +1739,7 @@ function createClivlySDK(config) {
 				reason: "ok",
 				retryable: false,
 				org: body?.org,
+				workspace: body?.workspace ?? null,
 				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
 			};
 		}
@@ -1891,6 +1929,7 @@ Object.defineProperty(exports, "defineClivlyConfig", {
 		return _clivly_core_entity_config.defineClivlyConfig;
 	}
 });
+exports.isPlaceholderUrl = isPlaceholderUrl;
 Object.defineProperty(exports, "validateEntitiesConfig", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -1,6 +1,9 @@
-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-DxG4rHyo.cjs";
+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 { 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
+declare function isPlaceholderUrl(value: string): boolean;
+//#endregion
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -31,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, 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, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

package/dist/index.d.mts

@@ -1,6 +1,9 @@
-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-DxG4rHyo.mjs";
+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 { 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
+declare function isPlaceholderUrl(value: string): boolean;
+//#endregion
 //#region src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -31,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, 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, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

package/dist/index.mjs

@@ -124,11 +124,16 @@ function checkConceptCoverage(config) {
 }
 //#endregion
 //#region src/custom-slug.ts
+const SLUG_PATTERN = /^[a-z][a-z0-9_-]*$/;
 const NON_ALNUM = /[^a-z0-9]+/g;
 const EDGE_HYPHENS = /(^-|-$)/g;
 function slugify(value) {
 	return value.toLowerCase().trim().replace(NON_ALNUM, "-").replace(EDGE_HYPHENS, "");
 }
+function suggestionFor(declared) {
+	const candidate = slugify(declared);
+	return candidate !== declared && SLUG_PATTERN.test(candidate) ? ` Did you mean "${candidate}"?` : "";
+}
 function checkCustomObjectSlugs(config) {
 	const custom = config.source?.custom ?? [];
 	const declared = config.entities ? customObjectDeclarations$1(config.entities) : [];
@@ -142,12 +147,11 @@ function checkCustomObjectSlugs(config) {
 	const seen = /* @__PURE__ */ new Map();
 	for (const source of custom) {
 		const declared = source.objectType;
-		const canonical = slugify(declared);
-		if (canonical === "") problems.push(`"${source.entity}" has an empty objectType.`);
-		else if (canonical !== declared) problems.push(`"${declared}" is not a slug — the dashboard would store it as "${canonical}".`);
-		const prior = seen.get(canonical);
-		if (prior && canonical !== "") problems.push(`duplicate slug "${canonical}" declared by "${prior}" and "${source.entity}".`);
-		else seen.set(canonical, source.entity);
+		if (declared === "") problems.push(`"${source.entity}" has an empty objectType.`);
+		else if (!SLUG_PATTERN.test(declared)) problems.push(`"${declared}" is not a valid object type slug — use lowercase letters, digits, "-" or "_", starting with a letter.${suggestionFor(declared)}`);
+		const prior = seen.get(declared);
+		if (prior && declared !== "") problems.push(`duplicate slug "${declared}" declared by "${prior}" and "${source.entity}".`);
+		else seen.set(declared, source.entity);
 	}
 	if (problems.length > 0) return {
 		name: "Custom object slugs",
@@ -254,10 +258,20 @@ async function runMappingDryRun(config, entityKey) {
 		detail: `"${resolved.source.entity}" is empty — nothing to map yet.`
 	};
 	const missing = Object.entries(fields).filter(([, column]) => !(column in row)).map(([field, column]) => `${field} → ${column}`);
+	if (missing.length === 0) return {
+		name,
+		ok: true,
+		detail: `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.`
+	};
+	if (config.entities?.entities?.[entityKey]?.projection !== void 0 && missing.length === Object.keys(fields).length) return {
+		name,
+		ok: false,
+		detail: `Row from "${resolved.source.entity}" carries none of the projection's columns (${missing.join(", ")}) — the source performs no joins, so the projection is declared but never executed. Build it with \`fromDrizzleProjection\` from \`clivly/drizzle\`, which runs the joins and returns rows keyed by ref token.`
+	};
 	return {
 		name,
-		ok: missing.length === 0,
-		detail: missing.length === 0 ? `Mapped ${Object.keys(fields).length} field(s) from a real "${resolved.source.entity}" row.` : `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
+		ok: false,
+		detail: `Row from "${resolved.source.entity}" is missing mapped column(s): ${missing.join(", ")}.`
 	};
 }
 //#endregion
@@ -466,9 +480,27 @@ async function mappingDryRunChecks(config) {
 	return checks;
 }
 /**
+* Why a source has no `DRIZZLE_META`, without asserting more than we know.
+*
+* There are two ways to get here and they are indistinguishable at runtime: the
+* source really was hand-written, or it came from `fromDrizzle` and a spread
+* stripped the metadata, which is non-enumerable. The second is easy to fall
+* into precisely where `objectType` is present — `source.custom` is typed
+* `Array<SyncSource & { objectType: string }>`, so attaching that property with
+* `{ ...fromDrizzle(...), objectType }` used to be the only way to satisfy it.
+*
+* Flatly calling such a source "hand-written" sent developers looking for one
+* that does not exist. Where `objectType` is present, name the likelier cause
+* and the fix instead of guessing wrong with confidence.
+*/
+function missingMetaDetail(source) {
+	const skipped = "column check skipped";
+	if (source.objectType === void 0) return `"${source.entity}" is a hand-written source — ${skipped}.`;
+	return `"${source.entity}" has no drizzle metadata — ${skipped}. If it came from \`fromDrizzle\`, a spread such as \`{ ...fromDrizzle(...), objectType }\` dropped it; pass \`objectType\` to \`fromDrizzle\` instead.`;
+}
+/**
 * Confirm each drizzle source actually has the cursor and id columns the sync
-* pages on. Hand-written sources have no column metadata, so they are skipped
-* rather than failed.
+* pages on. Sources with no column metadata are skipped rather than failed.
 */
 function cursorColumnChecks(sources) {
 	const checks = [];
@@ -479,7 +511,7 @@ function cursorColumnChecks(sources) {
 				name: `Cursor/id columns exist (${source.entity})`,
 				ok: false,
 				skipped: true,
-				detail: `"${source.entity}" is a hand-written source — column check skipped.`
+				detail: missingMetaDetail(source)
 			});
 			continue;
 		}
@@ -1118,11 +1150,16 @@ function observedTriggerUrl(req) {
 		return new URL(`${proto}://${host}${requestUrl.pathname}`).toString();
 	} catch {}
 }
+const PLACEHOLDER_BRACKETS = /[<>]/;
+function isPlaceholderUrl(value) {
+	return PLACEHOLDER_BRACKETS.test(value);
+}
 /**
 * Decide which trigger URL to report, in precedence order:
 *
 *   1. `configuredUrl` — an explicit `syncTrigger.url`. Someone typed this on
-*      purpose, so it beats anything inferred.
+*      purpose, so it beats anything inferred. An unedited placeholder is not
+*      "on purpose" and is skipped.
 *   2. platform env origin + `configuredPath` — available at boot, before any
 *      request has arrived. Needs the path because platform variables only give
 *      an origin.
@@ -1132,7 +1169,7 @@ function observedTriggerUrl(req) {
 * doesn't need to know about it.
 */
 function resolveTriggerUrl(args) {
-	if (args.configuredUrl) return args.configuredUrl;
+	if (args.configuredUrl && !isPlaceholderUrl(args.configuredUrl)) return args.configuredUrl;
 	const origin = originFromPlatformEnv(args.env);
 	if (origin && args.configuredPath) return `${origin}${args.configuredPath.startsWith("/") ? args.configuredPath : `/${args.configuredPath}`}`;
 	return args.observedUrl;
@@ -1701,6 +1738,7 @@ function createClivlySDK(config) {
 				reason: "ok",
 				retryable: false,
 				org: body?.org,
+				workspace: body?.workspace ?? null,
 				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
 			};
 		}
@@ -1872,4 +1910,4 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig };
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

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

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -309,6 +309,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */
@@ -325,6 +331,14 @@ interface SyncSource {
   }): Promise<Record<string, unknown>[]>;
   /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
   idField?: string;
+  /**
+   * Custom-object slug this source mirrors into. Only meaningful for entries in
+   * `source.custom`, whose element type narrows it to required — declared here
+   * because the sync and readiness paths read `source.objectType` off a plain
+   * `SyncSource`, so leaving it off left the property required by one type,
+   * absent from another, and read by the runtime.
+   */
+  objectType?: string;
   /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
   [DRIZZLE_META]?: DrizzleSourceMeta;
 }

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

@@ -1,4 +1,4 @@
-import { ClivlyEntitiesConfig } from "@clivly/core";
+import { ClivlyEntitiesConfig, IntegrationState } from "@clivly/core";
 //#region src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -309,6 +309,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */
@@ -325,6 +331,14 @@ interface SyncSource {
   }): Promise<Record<string, unknown>[]>;
   /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
   idField?: string;
+  /**
+   * Custom-object slug this source mirrors into. Only meaningful for entries in
+   * `source.custom`, whose element type narrows it to required — declared here
+   * because the sync and readiness paths read `source.objectType` off a plain
+   * `SyncSource`, so leaving it off left the property required by one type,
+   * absent from another, and read by the runtime.
+   */
+  objectType?: string;
   /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
   [DRIZZLE_META]?: DrizzleSourceMeta;
 }

package/dist/vite.d.cts

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