clivly 0.3.0-next.4 → 0.3.0-next.6

package/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-CcYne5Je.cjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-CkHCj9tQ.cjs";
 import { Table } from "drizzle-orm";
 
 //#region ../sdk/src/drizzle.d.ts

package/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DjWzU9gG.mjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-CA4Vj40g.mjs";
 import { Table } from "drizzle-orm";
 
 //#region ../sdk/src/drizzle.d.ts

package/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-DMuZpchz.cjs");
 require("./mapping-score-i3p8LWDF.cjs");
 const require_core_entity_heuristics = require("./core-entity-heuristics.cjs");
-const require_sdk = require("./sdk-r4khXzoH.cjs");
+const require_sdk = require("./sdk-D1BHQDf5.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -533,6 +533,71 @@ function isEntrypoint(argv1, moduleUrl, realpath = node_fs.realpathSync) {
 	return resolve(argv1) === resolve(modulePath);
 }
 //#endregion
+//#region src/load-env.ts
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const NEWLINE = /\r?\n/;
+const ESCAPED_NEWLINE = /\\n/g;
+const ESCAPED_CARRIAGE = /\\r/g;
+const TRAILING_COMMENT = /\s#/;
+/**
+* Parse `.env` file text into a flat key→value map. Understands `#` comments
+* (whole-line and trailing on unquoted values), single/double quotes,
+* `export KEY=`, and `\n` escapes inside double quotes. Later duplicate keys
+* win, matching how a shell would source the file top-to-bottom.
+*/
+function parseEnv(content) {
+	const out = {};
+	for (const rawLine of content.split(NEWLINE)) {
+		const line = rawLine.trimStart();
+		if (line === "" || line.startsWith("#")) continue;
+		const match = LINE.exec(line);
+		const key = match?.[1];
+		if (!key) continue;
+		out[key] = parseValue(match[2] ?? "");
+	}
+	return out;
+}
+function parseValue(raw) {
+	const value = raw.trim();
+	if (value === "") return "";
+	const quote = value[0];
+	if (quote === "\"" || quote === "'") {
+		const end = value.indexOf(quote, 1);
+		const inner = end === -1 ? value.slice(1) : value.slice(1, end);
+		return quote === "\"" ? inner.replace(ESCAPED_NEWLINE, "\n").replace(ESCAPED_CARRIAGE, "\r") : inner;
+	}
+	const commentAt = value.search(TRAILING_COMMENT);
+	return (commentAt === -1 ? value : value.slice(0, commentAt)).trim();
+}
+/**
+* Load `.env` then `.env.local` from `cwd` into `env` (default `process.env`),
+* WITHOUT overriding anything already set. Precedence, strongest first:
+* real environment (shell) > `.env.local` > `.env`. This mirrors the framework
+* convention developers already expect (Next.js, Vite), so pointing
+* `CLIVLY_API_URL` at a staging host from the shell still wins over the file.
+*/
+function loadEnv(cwd, env = process.env) {
+	const files = [];
+	const merged = {};
+	for (const name of [".env", ".env.local"]) {
+		const path = (0, node_path.join)(cwd, name);
+		if (!(0, node_fs.existsSync)(path)) continue;
+		files.push(name);
+		try {
+			Object.assign(merged, parseEnv((0, node_fs.readFileSync)(path, "utf8")));
+		} catch {}
+	}
+	const applied = [];
+	for (const [key, value] of Object.entries(merged)) if (env[key] === void 0) {
+		env[key] = value;
+		applied.push(key);
+	}
+	return {
+		applied,
+		files
+	};
+}
+//#endregion
 //#region src/login.ts
 const POLL_INTERVAL_MS = 2e3;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -752,15 +817,25 @@ function placeholderContact(todos) {
 		idField: null
 	};
 }
+function hasMappedFields(entity) {
+	return Object.keys(entity.fields).length > 0;
+}
 function planInit(schema) {
 	const todos = [];
 	const { contact: contactTable, company: companyTable } = selectEntities(schema.tables);
-	const contactDetected = contactTable !== null;
-	const contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contactDetected = contactTable !== null;
+	if (!hasMappedFields(contact)) {
+		contact = placeholderContact(todos);
+		contactDetected = false;
+	}
 	let company = null;
 	if (companyTable) {
-		company = buildEntity(companyTable, "company", todos);
-		if (require_core_entity_heuristics.matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
+		const candidate = buildEntity(companyTable, "company", todos);
+		if (hasMappedFields(candidate)) {
+			company = candidate;
+			if (require_core_entity_heuristics.matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
 	}
 	if (contactTable) {
 		const scored = require_core_entity_heuristics.scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1019,10 +1094,14 @@ const handler = clivly.createClivlyHandler();
 		case "nextjs": return `${preamble}
 export const POST = (request: Request) => handler(request);
 `;
-		case "tanstack-start": return `import { createAPIFileRoute } from "@tanstack/react-start/api";
+		case "tanstack-start": return `import { createFileRoute } from "@tanstack/react-router";
 ${preamble}
-export const APIRoute = createAPIFileRoute("__ROUTE__")({
-  POST: ({ request }) => handler(request),
+export const Route = createFileRoute("__ROUTE__")({
+  server: {
+    handlers: {
+      POST: ({ request }) => handler(request),
+    },
+  },
 });
 `;
 		case "sveltekit": return `import type { RequestHandler } from "./$types";
@@ -1165,13 +1244,33 @@ function resolveConfigPath(cwd, configPath) {
 function firstLine(message) {
 	return message.split("\n")[0]?.trim() ?? "";
 }
+/**
+* Describe why the config failed to load, in one line the developer can act on.
+*
+* A config that fails its own schema validation throws a zod error carrying
+* structured `issues`, but whose `message` is a multi-line JSON dump — its
+* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
+* to a single bracket. Render the issues as `path: message` instead, which is
+* what actually names the entity to fix. Anything else keeps the require-stack
+* trimming `firstLine` exists for.
+*/
+function describeLoadError(error) {
+	const issues = error.issues;
+	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
+		const issue = raw;
+		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+		const message = typeof issue.message === "string" ? issue.message : "invalid value";
+		return path ? `${path}: ${message}` : message;
+	}).join("; ");
+	return firstLine(error?.message ?? String(error));
+}
 async function loadConfigSdk(path, requiredMethod) {
 	const jiti$1 = (0, jiti.createJiti)(require("url").pathToFileURL(__filename).href);
 	let mod;
 	try {
 		mod = await jiti$1.import(path);
 	} catch (error) {
-		throw new Error(firstLine(error.message));
+		throw new Error(describeLoadError(error));
 	}
 	const sdk = mod.default ?? mod;
 	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
@@ -1654,7 +1753,7 @@ function previewMutations(deps, mutations) {
 }
 function printNextSteps(out, authComplete, loginRan) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Set the CLIVLY_* values in .env\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_API_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\n");
 	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
 	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
 	const step = authComplete ? 3 : 4;
@@ -1872,6 +1971,7 @@ function runInitFromArgv(argv, cwd) {
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
+	loadEnv(process.cwd());
 	switch (command) {
 		case "init": return await runInitFromArgv(rest, process.cwd());
 		case "push-schema": return await runPushSchema({

package/index.mjs

@@ -2,7 +2,7 @@
 import { t as CANONICAL_FIELDS } from "./entity-config-D3YpQB0z.mjs";
 import "./mapping-score-CPPvwoZC.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./core-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-DtFmeuwl.mjs";
+import { t as createClivlySDK } from "./sdk-DdzBxgMx.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
@@ -532,6 +532,71 @@ function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 	return resolve(argv1) === resolve(modulePath);
 }
 //#endregion
+//#region src/load-env.ts
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const NEWLINE = /\r?\n/;
+const ESCAPED_NEWLINE = /\\n/g;
+const ESCAPED_CARRIAGE = /\\r/g;
+const TRAILING_COMMENT = /\s#/;
+/**
+* Parse `.env` file text into a flat key→value map. Understands `#` comments
+* (whole-line and trailing on unquoted values), single/double quotes,
+* `export KEY=`, and `\n` escapes inside double quotes. Later duplicate keys
+* win, matching how a shell would source the file top-to-bottom.
+*/
+function parseEnv(content) {
+	const out = {};
+	for (const rawLine of content.split(NEWLINE)) {
+		const line = rawLine.trimStart();
+		if (line === "" || line.startsWith("#")) continue;
+		const match = LINE.exec(line);
+		const key = match?.[1];
+		if (!key) continue;
+		out[key] = parseValue(match[2] ?? "");
+	}
+	return out;
+}
+function parseValue(raw) {
+	const value = raw.trim();
+	if (value === "") return "";
+	const quote = value[0];
+	if (quote === "\"" || quote === "'") {
+		const end = value.indexOf(quote, 1);
+		const inner = end === -1 ? value.slice(1) : value.slice(1, end);
+		return quote === "\"" ? inner.replace(ESCAPED_NEWLINE, "\n").replace(ESCAPED_CARRIAGE, "\r") : inner;
+	}
+	const commentAt = value.search(TRAILING_COMMENT);
+	return (commentAt === -1 ? value : value.slice(0, commentAt)).trim();
+}
+/**
+* Load `.env` then `.env.local` from `cwd` into `env` (default `process.env`),
+* WITHOUT overriding anything already set. Precedence, strongest first:
+* real environment (shell) > `.env.local` > `.env`. This mirrors the framework
+* convention developers already expect (Next.js, Vite), so pointing
+* `CLIVLY_API_URL` at a staging host from the shell still wins over the file.
+*/
+function loadEnv(cwd, env = process.env) {
+	const files = [];
+	const merged = {};
+	for (const name of [".env", ".env.local"]) {
+		const path = join(cwd, name);
+		if (!existsSync(path)) continue;
+		files.push(name);
+		try {
+			Object.assign(merged, parseEnv(readFileSync(path, "utf8")));
+		} catch {}
+	}
+	const applied = [];
+	for (const [key, value] of Object.entries(merged)) if (env[key] === void 0) {
+		env[key] = value;
+		applied.push(key);
+	}
+	return {
+		applied,
+		files
+	};
+}
+//#endregion
 //#region src/login.ts
 const POLL_INTERVAL_MS = 2e3;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -751,15 +816,25 @@ function placeholderContact(todos) {
 		idField: null
 	};
 }
+function hasMappedFields(entity) {
+	return Object.keys(entity.fields).length > 0;
+}
 function planInit(schema) {
 	const todos = [];
 	const { contact: contactTable, company: companyTable } = selectEntities(schema.tables);
-	const contactDetected = contactTable !== null;
-	const contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
+	let contactDetected = contactTable !== null;
+	if (!hasMappedFields(contact)) {
+		contact = placeholderContact(todos);
+		contactDetected = false;
+	}
 	let company = null;
 	if (companyTable) {
-		company = buildEntity(companyTable, "company", todos);
-		if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
+		const candidate = buildEntity(companyTable, "company", todos);
+		if (hasMappedFields(candidate)) {
+			company = candidate;
+			if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
+		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
 	}
 	if (contactTable) {
 		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
@@ -1018,10 +1093,14 @@ const handler = clivly.createClivlyHandler();
 		case "nextjs": return `${preamble}
 export const POST = (request: Request) => handler(request);
 `;
-		case "tanstack-start": return `import { createAPIFileRoute } from "@tanstack/react-start/api";
+		case "tanstack-start": return `import { createFileRoute } from "@tanstack/react-router";
 ${preamble}
-export const APIRoute = createAPIFileRoute("__ROUTE__")({
-  POST: ({ request }) => handler(request),
+export const Route = createFileRoute("__ROUTE__")({
+  server: {
+    handlers: {
+      POST: ({ request }) => handler(request),
+    },
+  },
 });
 `;
 		case "sveltekit": return `import type { RequestHandler } from "./$types";
@@ -1164,13 +1243,33 @@ function resolveConfigPath(cwd, configPath) {
 function firstLine(message) {
 	return message.split("\n")[0]?.trim() ?? "";
 }
+/**
+* Describe why the config failed to load, in one line the developer can act on.
+*
+* A config that fails its own schema validation throws a zod error carrying
+* structured `issues`, but whose `message` is a multi-line JSON dump — its
+* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
+* to a single bracket. Render the issues as `path: message` instead, which is
+* what actually names the entity to fix. Anything else keeps the require-stack
+* trimming `firstLine` exists for.
+*/
+function describeLoadError(error) {
+	const issues = error.issues;
+	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
+		const issue = raw;
+		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+		const message = typeof issue.message === "string" ? issue.message : "invalid value";
+		return path ? `${path}: ${message}` : message;
+	}).join("; ");
+	return firstLine(error?.message ?? String(error));
+}
 async function loadConfigSdk(path, requiredMethod) {
 	const jiti = createJiti(import.meta.url);
 	let mod;
 	try {
 		mod = await jiti.import(path);
 	} catch (error) {
-		throw new Error(firstLine(error.message));
+		throw new Error(describeLoadError(error));
 	}
 	const sdk = mod.default ?? mod;
 	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
@@ -1653,7 +1752,7 @@ function previewMutations(deps, mutations) {
 }
 function printNextSteps(out, authComplete, loginRan) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Set the CLIVLY_* values in .env\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_API_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\n");
 	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
 	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
 	const step = authComplete ? 3 : 4;
@@ -1871,6 +1970,7 @@ function runInitFromArgv(argv, cwd) {
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
+	loadEnv(process.cwd());
 	switch (command) {
 		case "init": return await runInitFromArgv(rest, process.cwd());
 		case "push-schema": return await runPushSchema({

package/{namespace-probe-DjWzU9gG.d.mts → namespace-probe-CA4Vj40g.d.mts}

@@ -179,6 +179,21 @@ interface ClivlyUser {
   id: string;
   name?: string;
 }
+interface ChatWidgetVisitor {
+  email: string;
+  name: string;
+}
+interface ChatSessionRequestBody {
+  visitor: ChatWidgetVisitor;
+  visitorToken?: string | null;
+  widgetId: string;
+}
+interface CreateChatSessionHandlerOptions {
+  allowedOrigins?: string[];
+  apiKey: string;
+  apiUrl?: string;
+  fetchImpl?: typeof fetch;
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -313,4 +328,4 @@ interface NamespaceIntrospector {
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };
+export { ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, SyncSource as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };

package/{namespace-probe-CcYne5Je.d.cts → namespace-probe-CkHCj9tQ.d.cts}

@@ -179,6 +179,21 @@ interface ClivlyUser {
   id: string;
   name?: string;
 }
+interface ChatWidgetVisitor {
+  email: string;
+  name: string;
+}
+interface ChatSessionRequestBody {
+  visitor: ChatWidgetVisitor;
+  visitorToken?: string | null;
+  widgetId: string;
+}
+interface CreateChatSessionHandlerOptions {
+  allowedOrigins?: string[];
+  apiKey: string;
+  apiUrl?: string;
+  fetchImpl?: typeof fetch;
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -313,4 +328,4 @@ interface NamespaceIntrospector {
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };
+export { ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, SyncSource as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.3.0-next.4",
+  "version": "0.3.0-next.6",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",

package/{sdk-r4khXzoH.cjs → sdk-D1BHQDf5.cjs}

@@ -11,7 +11,7 @@ function checkCustomObjectSlugs(config) {
 		name: "Custom object slugs",
 		ok: false,
 		skipped: true,
-		detail: "No custom objects configured."
+		detail: "No custom objects in clivly.config. Objects added in the dashboard need a matching source.custom entry here to sync."
 	};
 	const problems = [];
 	const seen = /* @__PURE__ */ new Map();
@@ -36,6 +36,49 @@ function checkCustomObjectSlugs(config) {
 	};
 }
 //#endregion
+//#region ../sdk/src/fetch-error.ts
+/** Deepest `Error` reachable through the `.cause` chain (the original error if none). */
+function rootError(error) {
+	let current = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (current instanceof Error && current.cause !== void 0 && !seen.has(current)) {
+		seen.add(current);
+		current = current.cause;
+	}
+	return current;
+}
+function codeOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+const CODE_HINTS = {
+	ECONNREFUSED: "the database refused the connection — is Postgres running and is your database URL (e.g. DATABASE_URL) pointing at it?",
+	ENOTFOUND: "the database host couldn't be resolved — check the host in your connection string.",
+	ETIMEDOUT: "the database connection timed out — check the host, port, and firewall.",
+	"28P01": "password authentication failed — check the credentials in your connection string.",
+	"28000": "the database rejected the connection role — check the user in your connection string.",
+	"3D000": "that database does not exist — check the database name in your connection string.",
+	"08006": "the database connection was lost — check that Postgres is reachable."
+};
+const NEWLINE = /\r?\n/;
+/** One-line, single-spaced version of an error message (drops the SQL/params blob). */
+function firstLine(message) {
+	const line = message.split(NEWLINE)[0]?.trim() ?? "";
+	return line === "" ? message.trim() : line;
+}
+/**
+* Build the `detail` string for a failed sample fetch of `entity`.
+* Recognised connection errors get a plain-English hint; everything else
+* surfaces the root cause's first line rather than the wrapper's SQL dump.
+*/
+function describeFetchError(entity, error) {
+	const root = rootError(error);
+	const code = codeOf(root) ?? codeOf(error);
+	const hint = code ? CODE_HINTS[code] : void 0;
+	if (hint) return `Couldn't read "${entity}": ${hint}`;
+	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -187,7 +230,7 @@ async function runDoctor(args) {
 		checks.push({
 			name: `Sample fetch (${source.entity})`,
 			ok: false,
-			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+			detail: describeFetchError(source.entity, error)
 		});
 	}
 	const result = await connect();
@@ -374,6 +417,88 @@ function resolveTriggerUrl(args) {
 	return args.observedUrl;
 }
 //#endregion
+//#region ../sdk/src/chat-session.ts
+const DEFAULT_API_URL$1 = "https://api.clivly.com";
+const JSON_HEADERS = { "content-type": "application/json" };
+const TRAILING_SLASH$1 = /\/$/;
+function jsonResponse$1(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: JSON_HEADERS
+	});
+}
+function normalizeApiUrl(apiUrl) {
+	return apiUrl.replace(TRAILING_SLASH$1, "");
+}
+function resolveOrigin(req) {
+	const headerOrigin = req.headers.get("origin");
+	if (headerOrigin) return headerOrigin;
+	try {
+		return new URL(req.url).origin;
+	} catch {
+		return null;
+	}
+}
+function isChatSessionRequestBody(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const body = value;
+	if (typeof body.widgetId !== "string" || body.widgetId.trim().length === 0) return false;
+	if (typeof body.visitor !== "object" || body.visitor === null || Array.isArray(body.visitor)) return false;
+	const visitor = body.visitor;
+	if (typeof visitor.name !== "string" || visitor.name.trim().length === 0) return false;
+	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
+	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
+}
+function originAllowed(origin, allowedOrigins) {
+	if (!allowedOrigins || allowedOrigins.length === 0) return true;
+	if (!origin) return false;
+	return allowedOrigins.includes(origin);
+}
+function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL$1, fetchImpl = fetch }) {
+	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	return async (request) => {
+		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+			status: 405,
+			headers: {
+				...JSON_HEADERS,
+				allow: "POST"
+			}
+		});
+		const origin = resolveOrigin(request);
+		if (!originAllowed(origin, allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		let body;
+		try {
+			body = await request.json();
+		} catch {
+			return jsonResponse$1({ error: "invalid_json" }, 400);
+		}
+		if (!isChatSessionRequestBody(body)) return jsonResponse$1({ error: "invalid_request" }, 400);
+		try {
+			const upstream = await fetchImpl(sessionUrl, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					"content-type": "application/json",
+					...origin ? { origin } : {}
+				},
+				body: JSON.stringify({
+					widgetId: body.widgetId,
+					visitor: body.visitor,
+					visitorToken: body.visitorToken,
+					origin
+				})
+			});
+			const responseBody = await upstream.text();
+			return new Response(responseBody, {
+				status: upstream.status,
+				headers: { "content-type": upstream.headers.get("content-type") ?? "application/json" }
+			});
+		} catch {
+			return jsonResponse$1({ error: "upstream_unreachable" }, 502);
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/errors.ts
 var ClivlyError = class ClivlyError extends Error {
 	/** HTTP status, or null when the request never completed (network error). */
@@ -912,6 +1037,12 @@ Object.defineProperty(exports, "ClivlyRateLimitError", {
 		return ClivlyRateLimitError;
 	}
 });
+Object.defineProperty(exports, "createChatSessionHandler", {
+	enumerable: true,
+	get: function() {
+		return createChatSessionHandler;
+	}
+});
 Object.defineProperty(exports, "createClivlySDK", {
 	enumerable: true,
 	get: function() {

package/{sdk-DtFmeuwl.mjs → sdk-DdzBxgMx.mjs}

@@ -11,7 +11,7 @@ function checkCustomObjectSlugs(config) {
 		name: "Custom object slugs",
 		ok: false,
 		skipped: true,
-		detail: "No custom objects configured."
+		detail: "No custom objects in clivly.config. Objects added in the dashboard need a matching source.custom entry here to sync."
 	};
 	const problems = [];
 	const seen = /* @__PURE__ */ new Map();
@@ -36,6 +36,49 @@ function checkCustomObjectSlugs(config) {
 	};
 }
 //#endregion
+//#region ../sdk/src/fetch-error.ts
+/** Deepest `Error` reachable through the `.cause` chain (the original error if none). */
+function rootError(error) {
+	let current = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (current instanceof Error && current.cause !== void 0 && !seen.has(current)) {
+		seen.add(current);
+		current = current.cause;
+	}
+	return current;
+}
+function codeOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+const CODE_HINTS = {
+	ECONNREFUSED: "the database refused the connection — is Postgres running and is your database URL (e.g. DATABASE_URL) pointing at it?",
+	ENOTFOUND: "the database host couldn't be resolved — check the host in your connection string.",
+	ETIMEDOUT: "the database connection timed out — check the host, port, and firewall.",
+	"28P01": "password authentication failed — check the credentials in your connection string.",
+	"28000": "the database rejected the connection role — check the user in your connection string.",
+	"3D000": "that database does not exist — check the database name in your connection string.",
+	"08006": "the database connection was lost — check that Postgres is reachable."
+};
+const NEWLINE = /\r?\n/;
+/** One-line, single-spaced version of an error message (drops the SQL/params blob). */
+function firstLine(message) {
+	const line = message.split(NEWLINE)[0]?.trim() ?? "";
+	return line === "" ? message.trim() : line;
+}
+/**
+* Build the `detail` string for a failed sample fetch of `entity`.
+* Recognised connection errors get a plain-English hint; everything else
+* surfaces the root cause's first line rather than the wrapper's SQL dump.
+*/
+function describeFetchError(entity, error) {
+	const root = rootError(error);
+	const code = codeOf(root) ?? codeOf(error);
+	const hint = code ? CODE_HINTS[code] : void 0;
+	if (hint) return `Couldn't read "${entity}": ${hint}`;
+	return `Couldn't read "${entity}": ${firstLine(root instanceof Error ? root.message : String(root?.message ?? root ?? "unknown error"))}`;
+}
+//#endregion
 //#region ../sdk/src/namespace-probe.ts
 /**
 * Verify the tables the integration depends on are genuinely reachable:
@@ -187,7 +230,7 @@ async function runDoctor(args) {
 		checks.push({
 			name: `Sample fetch (${source.entity})`,
 			ok: false,
-			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+			detail: describeFetchError(source.entity, error)
 		});
 	}
 	const result = await connect();
@@ -374,6 +417,88 @@ function resolveTriggerUrl(args) {
 	return args.observedUrl;
 }
 //#endregion
+//#region ../sdk/src/chat-session.ts
+const DEFAULT_API_URL$1 = "https://api.clivly.com";
+const JSON_HEADERS = { "content-type": "application/json" };
+const TRAILING_SLASH$1 = /\/$/;
+function jsonResponse$1(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: JSON_HEADERS
+	});
+}
+function normalizeApiUrl(apiUrl) {
+	return apiUrl.replace(TRAILING_SLASH$1, "");
+}
+function resolveOrigin(req) {
+	const headerOrigin = req.headers.get("origin");
+	if (headerOrigin) return headerOrigin;
+	try {
+		return new URL(req.url).origin;
+	} catch {
+		return null;
+	}
+}
+function isChatSessionRequestBody(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const body = value;
+	if (typeof body.widgetId !== "string" || body.widgetId.trim().length === 0) return false;
+	if (typeof body.visitor !== "object" || body.visitor === null || Array.isArray(body.visitor)) return false;
+	const visitor = body.visitor;
+	if (typeof visitor.name !== "string" || visitor.name.trim().length === 0) return false;
+	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
+	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
+}
+function originAllowed(origin, allowedOrigins) {
+	if (!allowedOrigins || allowedOrigins.length === 0) return true;
+	if (!origin) return false;
+	return allowedOrigins.includes(origin);
+}
+function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL$1, fetchImpl = fetch }) {
+	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	return async (request) => {
+		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+			status: 405,
+			headers: {
+				...JSON_HEADERS,
+				allow: "POST"
+			}
+		});
+		const origin = resolveOrigin(request);
+		if (!originAllowed(origin, allowedOrigins)) return jsonResponse$1({ error: "origin_not_allowed" }, 403);
+		let body;
+		try {
+			body = await request.json();
+		} catch {
+			return jsonResponse$1({ error: "invalid_json" }, 400);
+		}
+		if (!isChatSessionRequestBody(body)) return jsonResponse$1({ error: "invalid_request" }, 400);
+		try {
+			const upstream = await fetchImpl(sessionUrl, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					"content-type": "application/json",
+					...origin ? { origin } : {}
+				},
+				body: JSON.stringify({
+					widgetId: body.widgetId,
+					visitor: body.visitor,
+					visitorToken: body.visitorToken,
+					origin
+				})
+			});
+			const responseBody = await upstream.text();
+			return new Response(responseBody, {
+				status: upstream.status,
+				headers: { "content-type": upstream.headers.get("content-type") ?? "application/json" }
+			});
+		} catch {
+			return jsonResponse$1({ error: "upstream_unreachable" }, 502);
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/errors.ts
 var ClivlyError = class ClivlyError extends Error {
 	/** HTTP status, or null when the request never completed (network error). */
@@ -888,4 +1013,4 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
-export { ClivlyRateLimitError as a, ClivlyNetworkError as i, ClivlyAuthError as n, ClivlyError as r, createClivlySDK as t };
+export { ClivlyRateLimitError as a, ClivlyNetworkError as i, ClivlyAuthError as n, createChatSessionHandler as o, ClivlyError as r, createClivlySDK as t };

package/sdk.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sdk = require("./sdk-r4khXzoH.cjs");
+const require_sdk = require("./sdk-D1BHQDf5.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;
 exports.ClivlyRateLimitError = require_sdk.ClivlyRateLimitError;
+exports.createChatSessionHandler = require_sdk.createChatSessionHandler;
 exports.createClivlySDK = require_sdk.createClivlySDK;

package/sdk.d.cts

@@ -1,5 +1,13 @@
-import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-CcYne5Je.cjs";
+import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-CkHCj9tQ.cjs";
 
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({
+  allowedOrigins,
+  apiKey,
+  apiUrl,
+  fetchImpl
+}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
 //#region ../sdk/src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -30,4 +38,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK };

package/sdk.d.mts

@@ -1,5 +1,13 @@
-import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-DjWzU9gG.mjs";
+import { a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore } from "./namespace-probe-CA4Vj40g.mjs";
 
+//#region ../sdk/src/chat-session.d.ts
+declare function createChatSessionHandler({
+  allowedOrigins,
+  apiKey,
+  apiUrl,
+  fetchImpl
+}: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
 //#region ../sdk/src/errors.d.ts
 declare class ClivlyError extends Error {
   /** HTTP status, or null when the request never completed (network error). */
@@ -30,4 +38,4 @@ declare class ClivlyNetworkError extends ClivlyError {}
  */
 declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
 //#endregion
-export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };
+export { type ChatSessionRequestBody, type ChatWidgetVisitor, ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CreateChatSessionHandlerOptions, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createChatSessionHandler, createClivlySDK };

package/sdk.mjs

@@ -1,2 +1,2 @@
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, r as ClivlyError, t as createClivlySDK } from "./sdk-DtFmeuwl.mjs";
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createClivlySDK };
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, t as createClivlySDK } from "./sdk-DdzBxgMx.mjs";
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK };

package/vite.d.cts

@@ -1,4 +1,4 @@
-import { i as ClivlySDK } from "./namespace-probe-CcYne5Je.cjs";
+import { o as ClivlySDK } from "./namespace-probe-CkHCj9tQ.cjs";
 import { Plugin } from "vite";
 
 //#region ../sdk/src/vite.d.ts

package/vite.d.mts

@@ -1,4 +1,4 @@
-import { i as ClivlySDK } from "./namespace-probe-DjWzU9gG.mjs";
+import { o as ClivlySDK } from "./namespace-probe-CA4Vj40g.mjs";
 import { Plugin } from "vite";
 
 //#region ../sdk/src/vite.d.ts