clivly 0.8.0 → 0.9.1

package/{view-compiler-ChWr_Lml.mjs → view-compiler-CQx8TRrW.mjs}

@@ -1,3 +1,58 @@
+import { r as identityRefs, t as BASE_REF } from "./projection-D7xmQP4S.mjs";
+//#region ../core/src/projection-sql.ts
+/**
+* SQL generation for projection-backed entities.
+*
+* Base and joins are aliased by their ref key (`base`, then each join's `key`),
+* which is what allows the same table to be joined twice and keeps generated
+* SQL independent of host table names.
+*
+* Pure string generation — no DB access. Identifiers are escaped so output is
+* deterministic and injection-safe.
+*/
+/** Quote a single identifier part, escaping embedded double-quotes. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+/**
+* The identity expression, aliased as `id`. Composite identities concatenate
+* their parts with `::`; validation guarantees every part is NOT NULL and
+* non-text, which is what makes the concatenation collision-free.
+*/
+function identitySql(projection, basePkColumn) {
+	const refs = identityRefs(projection.identity, basePkColumn);
+	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")}) AS ${quoteIdent("id")}`;
+	const [ref] = refs;
+	if (!ref) throw new Error("projection identity resolved to no column");
+	return `${refSql(ref)} AS ${quoteIdent("id")}`;
+}
+function compileProjectionSelect(projection, basePkColumn) {
+	const selectItems = [identitySql(projection, basePkColumn)];
+	const columns = ["id"];
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) {
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(field)}`);
+		columns.push(field);
+	}
+	return {
+		columns,
+		selectItems
+	};
+}
+function compileProjectionJoins(projection) {
+	return projection.joins.map((join) => {
+		const keyword = join.type === "inner" ? "INNER JOIN" : "LEFT JOIN";
+		const on = join.on.map((c) => `${refSql(c.left)} = ${refSql(c.right)}`).join(" AND ");
+		return `${keyword} ${quoteIdent(join.table)} AS ${quoteIdent(join.key)} ON ${on}`;
+	});
+}
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+function compileProjectionFrom(projection) {
+	return `FROM ${quoteIdent(projection.baseTable)} AS ${quoteIdent(BASE_REF)}`;
+}
+//#endregion
 //#region ../core/src/view-compiler.ts
 /**
 * View compiler (Phase 2) — turns a validated entity config into read-only
@@ -22,10 +77,6 @@
 const SOURCE_KEY = "id";
 const DEFAULT_VIEW_PREFIX = "crm_src_";
 const DEFAULT_ROLE = "primary";
-/** Quote a single identifier part, escaping embedded double-quotes. */
-function quoteIdent(name) {
-	return `"${name.replace(/"/g, "\"\"")}"`;
-}
 /** Emit a SQL literal for a scalar filter value. */
 function quoteLiteral(value) {
 	if (typeof value === "number") return String(value);
@@ -106,17 +157,24 @@ function compileRelationship(relName, rel, source, related) {
 		refColumn: refCol
 	};
 }
-function compileEntityView(config, entityKey, options = {}) {
-	const entity = config.entities[entityKey];
-	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
-	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
-	const src = entity.source;
+/** SELECT items for a legacy single-table entity: source key, then fields. */
+function legacySelect(entity, src) {
 	const selectItems = [`${quoteIdent(src)}.${quoteIdent(SOURCE_KEY)} AS ${quoteIdent("id")}`];
 	const columns = ["id"];
 	for (const [field, column] of Object.entries(entity.fields)) {
 		selectItems.push(`${quoteIdent(src)}.${quoteIdent(column)} AS ${quoteIdent(field)}`);
 		columns.push(field);
 	}
+	return {
+		columns,
+		selectItems
+	};
+}
+/**
+* Relationship JOINs for a legacy entity. Appends each relationship's ref
+* column to `columns`/`selectItems` in place, preserving the existing order.
+*/
+function legacyJoins(config, entity, columns, selectItems) {
 	const joins = [];
 	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) {
 		const compiled = compileRelationship(relName, rel, entity, config.entities[rel.entity]);
@@ -126,12 +184,39 @@ function compileEntityView(config, entityKey, options = {}) {
 			columns.push(compiled.refColumn);
 		}
 	}
-	const conditions = compileFilterConditions(src, entity.filter);
-	if (options.orgScope) conditions.push(`${quoteIdent(src)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
+	return joins;
+}
+/**
+* Translate a driver error from executing a compiled view into something
+* actionable, or `undefined` when it is not one we recognise (caller rethrows).
+*
+* The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+* and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+* (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+* compiler cannot catch this itself because the host executes the SQL.
+*/
+function explainViewExecutionError(error) {
+	if (typeof error !== "object" || error === null) return;
+	const { code, routine } = error;
+	const message = error instanceof Error ? error.message : "";
+	if (!(code === "22023" && (routine === "parseRelOptionsInternal" || message.includes("security_invoker")))) return;
+	return "CREATE VIEW … WITH (security_invoker = true) requires Postgres 15+. Pass `securityInvoker: false` to compile without it — but note the view then runs with its owner's privileges instead of the querying role's, which bypasses row-level security (RLS) on the underlying tables. Prefer upgrading Postgres if you rely on RLS to separate tenants.";
+}
+function compileEntityView(config, entityKey, options = {}) {
+	const entity = config.entities[entityKey];
+	if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
+	const viewName = `${options.viewPrefix ?? "crm_src_"}${entityKey}`;
+	const src = entity.source;
+	const projection = entity.projection;
+	const filterTable = projection ? BASE_REF : src;
+	const { selectItems, columns } = projection ? compileProjectionSelect(projection, SOURCE_KEY) : legacySelect(entity, src);
+	const joins = projection ? compileProjectionJoins(projection) : legacyJoins(config, entity, columns, selectItems);
+	const conditions = compileFilterConditions(filterTable, entity.filter);
+	if (options.orgScope) conditions.push(`${quoteIdent(filterTable)}.${quoteIdent(options.orgScope.column)} = ${quoteLiteral(options.orgScope.value)}`);
 	const lines = [
 		options.securityInvoker ?? true ? `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} WITH (security_invoker = true) AS` : `CREATE OR REPLACE VIEW ${quoteIdent(viewName)} AS`,
 		`SELECT ${selectItems.join(", ")}`,
-		`FROM ${quoteIdent(src)}`,
+		projection ? compileProjectionFrom(projection) : `FROM ${quoteIdent(src)}`,
 		...joins
 	];
 	if (conditions.length > 0) lines.push(`WHERE ${conditions.join(" AND ")}`);
@@ -182,4 +267,4 @@ async function explainEntitiesConfig(config, run, options = {}) {
 	return results;
 }
 //#endregion
-export { explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };
+export { explainViewExecutionError as a, explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };

package/{view-compiler-BWz0sGdm.d.cts → view-compiler-CcUwzZut.d.mts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.mjs";
 //#region ../core/src/view-compiler.d.ts
 declare const DEFAULT_VIEW_PREFIX = "crm_src_";
 interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
   sql: string;
   viewName: string;
 }
+/**
+ * Translate a driver error from executing a compiled view into something
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
+ *
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+ * compiler cannot catch this itself because the host executes the SQL.
+ */
+declare function explainViewExecutionError(error: unknown): string | undefined;
 declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
 declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
  */
 declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
 //#endregion
-export { compileEntityView as a, ExplainResult as i, CompiledView as n, compileEntityViews as o, DEFAULT_VIEW_PREFIX as r, explainEntitiesConfig as s, CompileOptions as t };
+export { compileEntityView as a, explainViewExecutionError as c, ExplainResult as i, CompiledView as n, compileEntityViews as o, DEFAULT_VIEW_PREFIX as r, explainEntitiesConfig as s, CompileOptions as t };

package/{view-compiler-Bn_EJJMO.d.mts → view-compiler-DqAdVxLq.d.cts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-DoUCXtq5.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.cjs";
 //#region ../core/src/view-compiler.d.ts
 declare const DEFAULT_VIEW_PREFIX = "crm_src_";
 interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
   sql: string;
   viewName: string;
 }
+/**
+ * Translate a driver error from executing a compiled view into something
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
+ *
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
+ * compiler cannot catch this itself because the host executes the SQL.
+ */
+declare function explainViewExecutionError(error: unknown): string | undefined;
 declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
 declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
  */
 declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
 //#endregion
-export { compileEntityView as a, ExplainResult as i, CompiledView as n, compileEntityViews as o, DEFAULT_VIEW_PREFIX as r, explainEntitiesConfig as s, CompileOptions as t };
+export { compileEntityView as a, explainViewExecutionError as c, ExplainResult as i, CompiledView as n, compileEntityViews as o, DEFAULT_VIEW_PREFIX as r, explainEntitiesConfig as s, CompileOptions as t };

package/vite.d.cts

@@ -1,4 +1,4 @@
-import { t as ClivlySDK } from "./types-CsL0rFYh.cjs";
+import { o as ClivlySDK } from "./namespace-probe-aRFmpU85.cjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 interface ClivlyViteOptions {

package/vite.d.mts

@@ -1,4 +1,4 @@
-import { t as ClivlySDK } from "./types-CsL0rFYh.mjs";
+import { o as ClivlySDK } from "./namespace-probe-BkUs8raG.mjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 interface ClivlyViteOptions {

package/drizzle-B89tLo4T.mjs

@@ -1,31 +0,0 @@
-import { Table, getTableColumns, getTableName, is } from "drizzle-orm";
-//#region ../core/src/drizzle.ts
-/**
-* Derive Clivly's discovery shape (table + column names) from a Drizzle schema
-* object — the `* as schema` you pass to `drizzle(client, { schema })`. This
-* delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
-* `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
-* against your entity config.
-*
-* Column names are the real database column names (e.g. `full_name`), not the
-* Drizzle property keys (`fullName`). Non-table values in the schema object
-* (relations, enums, helpers) are ignored.
-*
-* `drizzle-orm` is an **optional peer dependency** — you only need it installed
-* when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
-* stays dependency-free.
-*/
-function discoverFromDrizzle(schema) {
-	const tables = [];
-	for (const value of Object.values(schema)) {
-		if (!is(value, Table)) continue;
-		const columns = getTableColumns(value);
-		tables.push({
-			name: getTableName(value),
-			columns: Object.values(columns).map((column) => column.name)
-		});
-	}
-	return tables;
-}
-//#endregion
-export { discoverFromDrizzle as t };

package/drizzle-CFOr9dU9.d.mts

@@ -1,20 +0,0 @@
-import { u as DiscoveredSchemaTable } from "./entity-config-DoUCXtq5.mjs";
-//#region ../core/src/drizzle.d.ts
-/**
- * Derive Clivly's discovery shape (table + column names) from a Drizzle schema
- * object — the `* as schema` you pass to `drizzle(client, { schema })`. This
- * delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
- * `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
- * against your entity config.
- *
- * Column names are the real database column names (e.g. `full_name`), not the
- * Drizzle property keys (`fullName`). Non-table values in the schema object
- * (relations, enums, helpers) are ignored.
- *
- * `drizzle-orm` is an **optional peer dependency** — you only need it installed
- * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
- * stays dependency-free.
- */
-declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
-//#endregion
-export { discoverFromDrizzle as t };

package/drizzle-DiReZf6d.cjs

@@ -1,36 +0,0 @@
-let drizzle_orm = require("drizzle-orm");
-//#region ../core/src/drizzle.ts
-/**
-* Derive Clivly's discovery shape (table + column names) from a Drizzle schema
-* object — the `* as schema` you pass to `drizzle(client, { schema })`. This
-* delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
-* `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
-* against your entity config.
-*
-* Column names are the real database column names (e.g. `full_name`), not the
-* Drizzle property keys (`fullName`). Non-table values in the schema object
-* (relations, enums, helpers) are ignored.
-*
-* `drizzle-orm` is an **optional peer dependency** — you only need it installed
-* when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
-* stays dependency-free.
-*/
-function discoverFromDrizzle(schema) {
-	const tables = [];
-	for (const value of Object.values(schema)) {
-		if (!(0, drizzle_orm.is)(value, drizzle_orm.Table)) continue;
-		const columns = (0, drizzle_orm.getTableColumns)(value);
-		tables.push({
-			name: (0, drizzle_orm.getTableName)(value),
-			columns: Object.values(columns).map((column) => column.name)
-		});
-	}
-	return tables;
-}
-//#endregion
-Object.defineProperty(exports, "discoverFromDrizzle", {
-	enumerable: true,
-	get: function() {
-		return discoverFromDrizzle;
-	}
-});

package/drizzle-DmeKSqeF.d.cts

@@ -1,20 +0,0 @@
-import { u as DiscoveredSchemaTable } from "./entity-config-DoUCXtq5.cjs";
-//#region ../core/src/drizzle.d.ts
-/**
- * Derive Clivly's discovery shape (table + column names) from a Drizzle schema
- * object — the `* as schema` you pass to `drizzle(client, { schema })`. This
- * delivers the "reads your schema" promise for Drizzle hosts: no hand-authored
- * `DiscoveredTable[]`. Feed the result to the SDK's `schema` option, or diff it
- * against your entity config.
- *
- * Column names are the real database column names (e.g. `full_name`), not the
- * Drizzle property keys (`fullName`). Non-table values in the schema object
- * (relations, enums, helpers) are ignored.
- *
- * `drizzle-orm` is an **optional peer dependency** — you only need it installed
- * when you import this entry (`@clivly/core/drizzle`); the rest of `@clivly/core`
- * stays dependency-free.
- */
-declare function discoverFromDrizzle(schema: Record<string, unknown>): DiscoveredSchemaTable[];
-//#endregion
-export { discoverFromDrizzle as t };

package/types-CsL0rFYh.d.cts

@@ -1,155 +0,0 @@
-//#region ../sdk/src/drizzle-meta.d.ts
-declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
-interface DrizzleSourceMeta {
-  /** Drizzle property keys of every column on the source table. */
-  columnKeys: string[];
-  /** Schema-v2 typed column metadata derived from the Drizzle table. */
-  columnsMeta?: DiscoveredColumn[];
-  cursorField: string;
-  idField: string;
-  /** The backing table's real name, so discovery can key metadata by table. */
-  tableName?: string;
-}
-//#endregion
-//#region ../sdk/src/types.d.ts
-interface DiscoveredColumn {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  /** The column this FK points at, when it is a foreign key. */
-  references?: {
-    table: string;
-    column: string;
-  };
-  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
-  type?: string;
-}
-interface ClivlyUser {
-  email: string;
-  id: string;
-  name?: string;
-}
-interface DoctorCheck {
-  /** Human-readable outcome — what passed, or why it failed. */
-  detail: string;
-  /** Short label, e.g. "API key present". */
-  name: string;
-  /** True when the check passed. Ignored when `skipped` is true. */
-  ok: boolean;
-  /** True when the check could not run (e.g. a hand-written source). */
-  skipped?: boolean;
-}
-interface DoctorReport {
-  checks: DoctorCheck[];
-  /** AND of every non-skipped check's `ok`. */
-  ok: boolean;
-}
-type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
-interface ClivlyConnectResult {
-  ok: boolean;
-  /** Org resolved from a successful heartbeat, when the server returns it. */
-  org?: {
-    id?: string;
-    name?: string;
-  };
-  reason: ClivlyConnectReason;
-  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
-  retryable: boolean;
-  /** HTTP status, or null when the request never completed (network error). */
-  status: number | null;
-}
-interface SyncCursor {
-  /** The row's id, breaking ties when timestamps collide. */
-  id: string;
-  /** The row's cursor-field value (typically `updated_at`). */
-  time: Date;
-}
-interface SyncSource {
-  cursorField: string;
-  entity: string;
-  fetchPage(args: {
-    since: SyncCursor | null;
-    limit: number;
-  }): Promise<Record<string, unknown>[]>;
-  /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
-  idField?: string;
-  /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
-  [DRIZZLE_META]?: DrizzleSourceMeta;
-}
-type SyncMode = "delta" | "full";
-interface ClivlySDK {
-  /**
-   * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
-   * `status` (null on network failure), a coarse `reason`, whether it's
-   * `retryable`, and the resolved `org` when the server returns it. Never throws
-   * — inspect the result, or turn a failure into an exception with
-   * `ClivlyError.from(result)`. Prefer this over `heartbeat()` for onboarding,
-   * health checks, and one-shot serverless calls.
-   */
-  connect(): Promise<ClivlyConnectResult>;
-  /**
-   * Build the `/clivly/auth/verify` handler the developer mounts in their app.
-   * Clivly's cloud calls it to validate a CRM user's identity against the host
-   * app's session. Pass a resolver that reads the host session from the request.
-   *
-   * The handler authenticates the caller against `config.verifyToken` (presented
-   * as `Authorization: Bearer <token>`) before invoking the resolver, so the
-   * endpoint can't be used by third parties to probe host sessions. It fails
-   * closed with HTTP 503 if `verifyToken` is unset (a missing config value, not a
-   * server fault — so it won't trip the host's 5xx error alerting).
-   */
-  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
-  /**
-   * A fetch handler to mount at a route. Each request runs one `runScheduled()`
-   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
-   *
-   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
-   * requests are HMAC-signed and carry a run id), and the host's own scheduler
-   * (Workers cron, an uptime ping — no body).
-   *
-   * When `syncTrigger.secret` is set the handler rejects unsigned or
-   * badly-signed requests with 401. When it isn't, the route stays open to
-   * anyone who can reach it — set a secret if it's publicly routable.
-   */
-  createClivlyHandler(): (req: Request) => Promise<Response>;
-  /** Validate this setup end-to-end (read-only) before the first sync. */
-  doctor(): Promise<DoctorReport>;
-  /**
-   * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
-   * loop and back-compat; use `connect()` when you need the failure reason.
-   */
-  heartbeat(): Promise<boolean>;
-  /**
-   * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
-   * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s
-   * `setInterval` loop can't persist between invocations — call this from a
-   * scheduled/cron trigger. Throws if a sync push fails (so the run is marked
-   * failed); heartbeat is best-effort.
-   */
-  runScheduled(options?: {
-    mode?: SyncMode;
-    runId?: string;
-  }): Promise<void>;
-  /**
-   * Send the initial heartbeat and start the keep-alive loop. For long-lived
-   * hosts only — on serverless/edge the interval can't persist, so prefer
-   * `runScheduled()` / `createClivlyHandler()`. Emits a warning if a serverless
-   * runtime is detected.
-   */
-  start(): Promise<void>;
-  /** Stop the keep-alive loop. */
-  stop(): void;
-  /**
-   * Sync all configured sources now. `delta` (default) pages changed rows since
-   * the last cursor; `full` pushes each complete entity so the server can
-   * reconcile leavers (archive-on-leave). Throws if a push fails, so callers see
-   * the failure — the background keep-alive loop swallows and retries instead.
-   */
-  sync(options?: {
-    mode?: SyncMode;
-    runId?: string;
-  }): Promise<void>;
-}
-//#endregion
-export { SyncSource as n, ClivlySDK as t };

package/types-CsL0rFYh.d.mts

@@ -1,155 +0,0 @@
-//#region ../sdk/src/drizzle-meta.d.ts
-declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
-interface DrizzleSourceMeta {
-  /** Drizzle property keys of every column on the source table. */
-  columnKeys: string[];
-  /** Schema-v2 typed column metadata derived from the Drizzle table. */
-  columnsMeta?: DiscoveredColumn[];
-  cursorField: string;
-  idField: string;
-  /** The backing table's real name, so discovery can key metadata by table. */
-  tableName?: string;
-}
-//#endregion
-//#region ../sdk/src/types.d.ts
-interface DiscoveredColumn {
-  isForeignKey?: boolean;
-  isPrimaryKey?: boolean;
-  name: string;
-  nullable?: boolean;
-  /** The column this FK points at, when it is a foreign key. */
-  references?: {
-    table: string;
-    column: string;
-  };
-  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
-  type?: string;
-}
-interface ClivlyUser {
-  email: string;
-  id: string;
-  name?: string;
-}
-interface DoctorCheck {
-  /** Human-readable outcome — what passed, or why it failed. */
-  detail: string;
-  /** Short label, e.g. "API key present". */
-  name: string;
-  /** True when the check passed. Ignored when `skipped` is true. */
-  ok: boolean;
-  /** True when the check could not run (e.g. a hand-written source). */
-  skipped?: boolean;
-}
-interface DoctorReport {
-  checks: DoctorCheck[];
-  /** AND of every non-skipped check's `ok`. */
-  ok: boolean;
-}
-type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
-interface ClivlyConnectResult {
-  ok: boolean;
-  /** Org resolved from a successful heartbeat, when the server returns it. */
-  org?: {
-    id?: string;
-    name?: string;
-  };
-  reason: ClivlyConnectReason;
-  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
-  retryable: boolean;
-  /** HTTP status, or null when the request never completed (network error). */
-  status: number | null;
-}
-interface SyncCursor {
-  /** The row's id, breaking ties when timestamps collide. */
-  id: string;
-  /** The row's cursor-field value (typically `updated_at`). */
-  time: Date;
-}
-interface SyncSource {
-  cursorField: string;
-  entity: string;
-  fetchPage(args: {
-    since: SyncCursor | null;
-    limit: number;
-  }): Promise<Record<string, unknown>[]>;
-  /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
-  idField?: string;
-  /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
-  [DRIZZLE_META]?: DrizzleSourceMeta;
-}
-type SyncMode = "delta" | "full";
-interface ClivlySDK {
-  /**
-   * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
-   * `status` (null on network failure), a coarse `reason`, whether it's
-   * `retryable`, and the resolved `org` when the server returns it. Never throws
-   * — inspect the result, or turn a failure into an exception with
-   * `ClivlyError.from(result)`. Prefer this over `heartbeat()` for onboarding,
-   * health checks, and one-shot serverless calls.
-   */
-  connect(): Promise<ClivlyConnectResult>;
-  /**
-   * Build the `/clivly/auth/verify` handler the developer mounts in their app.
-   * Clivly's cloud calls it to validate a CRM user's identity against the host
-   * app's session. Pass a resolver that reads the host session from the request.
-   *
-   * The handler authenticates the caller against `config.verifyToken` (presented
-   * as `Authorization: Bearer <token>`) before invoking the resolver, so the
-   * endpoint can't be used by third parties to probe host sessions. It fails
-   * closed with HTTP 503 if `verifyToken` is unset (a missing config value, not a
-   * server fault — so it won't trip the host's 5xx error alerting).
-   */
-  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
-  /**
-   * A fetch handler to mount at a route. Each request runs one `runScheduled()`
-   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
-   *
-   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
-   * requests are HMAC-signed and carry a run id), and the host's own scheduler
-   * (Workers cron, an uptime ping — no body).
-   *
-   * When `syncTrigger.secret` is set the handler rejects unsigned or
-   * badly-signed requests with 401. When it isn't, the route stays open to
-   * anyone who can reach it — set a secret if it's publicly routable.
-   */
-  createClivlyHandler(): (req: Request) => Promise<Response>;
-  /** Validate this setup end-to-end (read-only) before the first sync. */
-  doctor(): Promise<DoctorReport>;
-  /**
-   * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
-   * loop and back-compat; use `connect()` when you need the failure reason.
-   */
-  heartbeat(): Promise<boolean>;
-  /**
-   * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
-   * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s
-   * `setInterval` loop can't persist between invocations — call this from a
-   * scheduled/cron trigger. Throws if a sync push fails (so the run is marked
-   * failed); heartbeat is best-effort.
-   */
-  runScheduled(options?: {
-    mode?: SyncMode;
-    runId?: string;
-  }): Promise<void>;
-  /**
-   * Send the initial heartbeat and start the keep-alive loop. For long-lived
-   * hosts only — on serverless/edge the interval can't persist, so prefer
-   * `runScheduled()` / `createClivlyHandler()`. Emits a warning if a serverless
-   * runtime is detected.
-   */
-  start(): Promise<void>;
-  /** Stop the keep-alive loop. */
-  stop(): void;
-  /**
-   * Sync all configured sources now. `delta` (default) pages changed rows since
-   * the last cursor; `full` pushes each complete entity so the server can
-   * reconcile leavers (archive-on-leave). Throws if a push fails, so callers see
-   * the failure — the background keep-alive loop swallows and retries instead.
-   */
-  sync(options?: {
-    mode?: SyncMode;
-    runId?: string;
-  }): Promise<void>;
-}
-//#endregion
-export { SyncSource as n, ClivlySDK as t };