@clivly/sdk 0.9.1 → 0.9.3

package/dist/index.cjs

@@ -2,6 +2,49 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_drizzle_meta = require("./drizzle-meta-CdCs30q3.cjs");
 const require_chat_session = require("./chat-session.cjs");
 let _clivly_core_entity_config = require("@clivly/core/entity-config");
+let _clivly_core_mappings_config = require("@clivly/core/mappings-config");
+//#region src/deployment-identity.ts
+const MAX_DEPLOYMENT_ID_LENGTH = 128;
+const PLATFORM_DEPLOYMENT_KEYS = [
+	"VERCEL_DEPLOYMENT_ID",
+	"RAILWAY_DEPLOYMENT_ID",
+	"FLY_MACHINE_VERSION",
+	"RENDER_GIT_COMMIT"
+];
+const COMMIT_KEYS = [
+	"VERCEL_GIT_COMMIT_SHA",
+	"GIT_COMMIT_SHA",
+	"GITHUB_SHA"
+];
+function firstNonBlank(values) {
+	for (const value of values) {
+		const trimmed = value?.trim();
+		if (trimmed) return trimmed;
+	}
+	return null;
+}
+function hashLocalIdentity(value) {
+	let hash = 0;
+	for (const character of value) hash = (hash * 31 + (character.codePointAt(0) ?? 0)) % Number.MAX_SAFE_INTEGER;
+	return Math.floor(hash).toString(36);
+}
+/**
+* Resolve the release identity used to choose a presence room.
+*
+* The order is intentionally explicit: a deployment id distinguishes two
+* rolling revisions more precisely than their shared commit, while the local
+* fallback keeps developers' machines out of a shared room.
+*/
+function resolveDeploymentId(env, configured) {
+	const deploymentId = firstNonBlank([
+		configured,
+		...PLATFORM_DEPLOYMENT_KEYS.map((key) => env[key]),
+		...COMMIT_KEYS.map((key) => env[key])
+	]);
+	if (deploymentId) return deploymentId.slice(0, MAX_DEPLOYMENT_ID_LENGTH);
+	return `local-${hashLocalIdentity(firstNonBlank([env.HOSTNAME]) ?? "unidentified-host")}`;
+}
+//#endregion
 //#region src/entity-source.ts
 const CONCEPT_KEYS = {
 	contact: "contacts",
@@ -37,7 +80,7 @@ function expectedSourceKey(concept) {
 }
 //#endregion
 //#region src/concept-coverage.ts
-const CHECK_NAME = "Entity → source coverage";
+const CHECK_NAME$1 = "Entity → source coverage";
 function configuredKeys(config) {
 	const src = config.source;
 	if (!src) return [];
@@ -53,14 +96,14 @@ function checkConceptCoverage(config) {
 	const entities = config.entities?.entities ?? {};
 	const keys = Object.keys(entities);
 	if (keys.length === 0) return {
-		name: CHECK_NAME,
+		name: CHECK_NAME$1,
 		ok: false,
 		skipped: true,
 		detail: "No entities configured — nothing to cross-check."
 	};
 	const unresolved = keys.filter((key) => resolveEntitySource(config, key) === null);
 	if (unresolved.length === 0) return {
-		name: CHECK_NAME,
+		name: CHECK_NAME$1,
 		ok: true,
 		detail: `${keys.length} entit${keys.length === 1 ? "y" : "ies"} resolve to a configured source.`
 	};
@@ -75,7 +118,7 @@ function checkConceptCoverage(config) {
 		return `"${key}" has concept "${concept}" but no \`source.${expectedSourceKey(concept)}\` is configured — it will never sync.`;
 	});
 	return {
-		name: CHECK_NAME,
+		name: CHECK_NAME$1,
 		ok: false,
 		detail: `${problems.join(" ")} Configured source keys: ${listed}. \`source\` is keyed by CRM concept, not by entity key.`
 	};
@@ -89,6 +132,7 @@ function slugify(value) {
 }
 function checkCustomObjectSlugs(config) {
 	const custom = config.source?.custom ?? [];
+	const declared = config.entities ? (0, _clivly_core_entity_config.customObjectDeclarations)(config.entities) : [];
 	if (custom.length === 0) return {
 		name: "Custom object slugs",
 		ok: false,
@@ -111,10 +155,17 @@ function checkCustomObjectSlugs(config) {
 		ok: false,
 		detail: problems.join(" ")
 	};
+	const declaredSlugs = new Set(declared.map((d) => d.slug));
+	const undeclared = custom.map((source) => source.objectType).filter((slug) => !declaredSlugs.has(slug));
+	if (undeclared.length === 0) return {
+		name: "Custom object slugs",
+		ok: true,
+		detail: "Declared in clivly.config — `clivly push-schema` creates them."
+	};
 	return {
 		name: "Custom object slugs",
 		ok: true,
-		detail: `Ensure these object types exist in Clivly: ${custom.map((source) => source.objectType).join(", ")}.`
+		detail: `Ensure these object types exist in Clivly: ${undeclared.join(", ")}. Declare them with \`objectType\` in clivly.config and \`clivly push-schema\` will create them for you.`
 	};
 }
 //#endregion
@@ -278,6 +329,75 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+//#region src/readiness.ts
+/**
+* Ask Clivly whether it can actually receive what this config pushes.
+*
+* Every other doctor check is local — the config loads, the tables are readable,
+* the key is set — and a workspace can pass all of them while storing nothing,
+* because whether a mapping exists to receive an entity is a fact only the
+* server holds. `clivly status` reported "7 of 7 passed" against exactly that
+* workspace. This is the rung that asks.
+*/
+/**
+* The entities to ask about, in the exact terms the sync pushes them.
+*
+* `source` is the resolved `SyncSource.entity` — the value that arrives at
+* `ingestPush` as `input.source` and is compared against `mapping.sourceTable`.
+* It is NOT the entity config's own `source` field, which names a host table;
+* the two are routinely conflated, and using the wrong one would report every
+* correctly mapped workspace as unmapped.
+*/
+function readinessEntitiesFromConfig(config) {
+	const entities = [];
+	for (const key of Object.keys(config.entities?.entities ?? {})) {
+		const resolved = resolveEntitySource(config, key);
+		if (!resolved) continue;
+		const objectTypeSlug = resolved.source.objectType;
+		entities.push({
+			source: resolved.source.entity,
+			concept: resolved.concept,
+			...resolved.concept === "custom" && objectTypeSlug ? { objectTypeSlug } : {}
+		});
+	}
+	return entities;
+}
+const CHECK_NAME = "Entities mapped in Clivly";
+/**
+* Turn a readiness answer into a doctor check.
+*
+* `null` means the server did not answer — older, unreachable, or the key was
+* rejected — and is reported as skipped, not failed. Reporting unknown as broken
+* would fail doctor for a workspace that is fine, which is the crying-wolf
+* failure mode that trains people to stop reading the ladder.
+*/
+function mappingReadinessCheck(requested, result) {
+	if (requested.length === 0) return {
+		name: CHECK_NAME,
+		ok: false,
+		skipped: true,
+		detail: "No entities to check."
+	};
+	if (!result) return {
+		name: CHECK_NAME,
+		ok: false,
+		skipped: true,
+		detail: "Clivly did not answer — this workspace's mappings could not be checked."
+	};
+	const unmapped = result.entities.filter((entity) => !entity.mapped);
+	if (unmapped.length === 0) return {
+		name: CHECK_NAME,
+		ok: true,
+		detail: `${result.entities.length} entit${result.entities.length === 1 ? "y has" : "ies have"} an active mapping.`
+	};
+	const names = unmapped.map((entity) => entity.objectTypeSlug ? `"${entity.source}" → "${entity.objectTypeSlug}"` : `"${entity.source}"`).join(", ");
+	return {
+		name: CHECK_NAME,
+		ok: false,
+		detail: `No active mapping receives ${names}, so rows pushed for ${unmapped.length === 1 ? "it" : "them"} are dropped. Map them in Integrations → Mapping in Clivly, then sync again.`
+	};
+}
+//#endregion
 //#region src/doctor.ts
 const TEMPORAL_CURSOR_TYPES = [
 	"timestamp",
@@ -407,7 +527,7 @@ async function sampleFetchChecks(sources) {
 * hides the rest. `ok` is the AND of all non-skipped checks.
 */
 async function runDoctor(args) {
-	const { config, probe } = args;
+	const { config, probe, readiness } = args;
 	const checks = [];
 	const sources = configuredSources(config);
 	const hasKey = Boolean(config.apiKey);
@@ -443,12 +563,409 @@ async function runDoctor(args) {
 	});
 	checks.push(checkCustomObjectSlugs(config));
 	checks.push(await namespaceCheck(config));
+	const requested = readinessEntitiesFromConfig(config);
+	const readinessResult = readiness && requested.length > 0 ? await readiness(requested) : null;
+	checks.push(mappingReadinessCheck(requested, readinessResult));
 	return {
 		ok: checks.every((check) => check.skipped || check.ok),
 		checks
 	};
 }
 //#endregion
+//#region src/host-environment.ts
+const KNOWN = [
+	"local_dev",
+	"preview",
+	"production"
+];
+const PLATFORM_ENVIRONMENTS = [
+	{
+		key: "VERCEL_ENV",
+		toEnvironment: (value) => {
+			if (value === "production") return "production";
+			if (value === "preview") return "preview";
+			return value === "development" ? "local_dev" : void 0;
+		}
+	},
+	{
+		key: "CF_PAGES_BRANCH",
+		toEnvironment: (value) => value === "main" || value === "master" ? "production" : "preview"
+	},
+	{
+		key: "RAILWAY_ENVIRONMENT_NAME",
+		toEnvironment: (value) => value === "production" ? "production" : "preview"
+	}
+];
+function fromNodeEnv(value) {
+	if (value === "production") return "production";
+	return value === "development" || value === "test" ? "local_dev" : void 0;
+}
+/**
+* Resolve the environment to report. An explicitly configured value wins, since
+* someone stated it on purpose; otherwise infer from the platform, then from
+* `NODE_ENV`. Returns `undefined` when nothing places the app.
+*/
+function detectHostEnvironment(env, configured) {
+	const stated = KNOWN.find((known) => known === configured);
+	if (stated) return stated;
+	for (const source of PLATFORM_ENVIRONMENTS) {
+		const raw = env[source.key]?.trim();
+		if (raw) {
+			const resolved = source.toEnvironment(raw);
+			if (resolved) return resolved;
+		}
+	}
+	return fromNodeEnv(env.NODE_ENV?.trim());
+}
+//#endregion
+//#region src/presence-machine.ts
+const PRESENCE_BACKOFF_BASE_MS = 1e3;
+const PRESENCE_BACKOFF_MAX_MS = 3e4;
+function effectsFor(state, overrides = {}) {
+	return {
+		connect: false,
+		httpHeartbeat: state !== "connected" && state !== "stopped",
+		retryInMs: null,
+		sendGoodbye: false,
+		...overrides
+	};
+}
+function retryDelay(attempt, jitter) {
+	const capped = Math.min(PRESENCE_BACKOFF_BASE_MS * 2 ** attempt, PRESENCE_BACKOFF_MAX_MS);
+	return Math.round(capped * (1 - Math.max(0, Math.min(1, jitter)) * .5));
+}
+/**
+* Decide the next presence action without performing I/O.
+*
+* `stopped` is absorbing, and fallback is derived from state rather than from
+* individual branches, so a delayed event cannot resurrect a stopped client or
+* silence HTTP while the socket is unconfirmed.
+*/
+function presenceReduce(context, event, jitter) {
+	if (context.state === "stopped") return {
+		context,
+		effects: effectsFor("stopped")
+	};
+	if (context.state === "unsupported" && event.type !== "stop") return {
+		context,
+		effects: effectsFor("unsupported")
+	};
+	if (event.type === "stop") return {
+		context: {
+			attempt: context.attempt,
+			state: "stopped"
+		},
+		effects: effectsFor("stopped", { sendGoodbye: context.state === "connected" })
+	};
+	if (event.type === "start" && context.state === "idle") return {
+		context: {
+			attempt: context.attempt,
+			state: "connecting"
+		},
+		effects: effectsFor("connecting", { connect: true })
+	};
+	if (event.type === "unsupportedServer") return {
+		context: {
+			attempt: context.attempt,
+			state: "unsupported"
+		},
+		effects: effectsFor("unsupported")
+	};
+	if (event.type === "ready" && context.state === "connecting") return {
+		context: {
+			attempt: 0,
+			state: "connected"
+		},
+		effects: effectsFor("connected")
+	};
+	if (event.type === "retryDue" && context.state === "backoff") return {
+		context: {
+			attempt: context.attempt,
+			state: "connecting"
+		},
+		effects: effectsFor("connecting", { connect: true })
+	};
+	if ((event.type === "ticketFailed" || event.type === "socketClosed") && (context.state === "connecting" || context.state === "connected")) {
+		const attempt = context.attempt + 1;
+		return {
+			context: {
+				attempt,
+				state: "backoff"
+			},
+			effects: effectsFor("backoff", { retryInMs: retryDelay(attempt, jitter) })
+		};
+	}
+	return {
+		context,
+		effects: effectsFor(context.state)
+	};
+}
+//#endregion
+//#region src/presence-client.ts
+const PRESENCE_PING_INTERVAL_MS = 3e4;
+const UNSUPPORTED_TICKET_STATUSES = /* @__PURE__ */ new Set([404, 501]);
+function ticketUrl(options) {
+	return new URL("/clivly/sdk/presence/ticket", options.apiUrl).toString();
+}
+function metricsUrl(options) {
+	return new URL("/clivly/sdk/presence/events", options.apiUrl).toString();
+}
+function socketUrl(options, ticket) {
+	const url = new URL("/clivly/sdk/presence", options.apiUrl);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	url.searchParams.set("deploymentId", options.deploymentId);
+	url.searchParams.set("ticket", ticket);
+	if (options.environment) url.searchParams.set("environment", options.environment);
+	return url.toString();
+}
+/**
+* Run the pure presence machine against the network and timers it requests.
+*
+* Every listener captures a connection sequence. Once a socket is replaced or
+* the client stops, events from that socket are ignored before reaching the
+* reducer, mirroring the room's generation fence on the client side.
+*/
+function createPresenceClient(options) {
+	let context = {
+		attempt: 0,
+		state: "idle"
+	};
+	let connectionSequence = 0;
+	let socket = null;
+	let pingTimer = null;
+	let retryTimer = null;
+	let fallbackStartedAt = null;
+	const instanceId = crypto.randomUUID();
+	const reportMetric = (event, fields) => {
+		try {
+			options.fetcher(metricsUrl(options), {
+				body: JSON.stringify({
+					event,
+					...fields
+				}),
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${options.token}`
+				},
+				method: "POST"
+			}).catch(() => {});
+		} catch {}
+	};
+	const clearPingTimer = () => {
+		if (pingTimer) {
+			clearInterval(pingTimer);
+			pingTimer = null;
+		}
+	};
+	const clearRetryTimer = () => {
+		if (retryTimer) {
+			clearTimeout(retryTimer);
+			retryTimer = null;
+		}
+	};
+	const startPinging = () => {
+		if (pingTimer) return;
+		pingTimer = setInterval(() => {
+			if (context.state === "connected") socket?.send(JSON.stringify({ type: "ping" }));
+		}, PRESENCE_PING_INTERVAL_MS);
+	};
+	const reportFallbackTransition = (previousState, event) => {
+		const enteredFallback = previousState !== "backoff" && context.state === "backoff";
+		const enteredUnsupported = previousState !== "unsupported" && context.state === "unsupported";
+		if (enteredFallback && fallbackStartedAt === null) {
+			fallbackStartedAt = Date.now();
+			reportMetric("fallback_started", { transport: "http" });
+		}
+		if (enteredUnsupported) {
+			clearRetryTimer();
+			reportMetric("fallback_started", {
+				outcome: "unsupported",
+				transport: "http"
+			});
+		}
+		if (event.type === "ready" && fallbackStartedAt !== null) {
+			reportMetric("fallback_duration", {
+				durationMs: Date.now() - fallbackStartedAt,
+				transport: "http"
+			});
+			fallbackStartedAt = null;
+		}
+	};
+	const dispatch = async (event) => {
+		const previousState = context.state;
+		const next = presenceReduce(context, event, Math.random());
+		context = next.context;
+		reportFallbackTransition(previousState, event);
+		options.onHttpHeartbeat(next.effects.httpHeartbeat);
+		if (previousState === "connected" && context.state !== "connected") clearPingTimer();
+		if (previousState !== "connected" && context.state === "connected") startPinging();
+		if (next.effects.sendGoodbye) socket?.send(JSON.stringify({ type: "goodbye" }));
+		if (next.effects.retryInMs !== null) {
+			clearRetryTimer();
+			retryTimer = setTimeout(async () => {
+				retryTimer = null;
+				await dispatch({ type: "retryDue" });
+			}, next.effects.retryInMs);
+		}
+		if (next.effects.connect) await connect();
+	};
+	const failTicketIfCurrent = async (sequence, event = "ticketFailed") => {
+		if (sequence === connectionSequence) await dispatch({ type: event });
+	};
+	const requestTicket = async (sequence) => {
+		try {
+			const response = await options.fetcher(ticketUrl(options), {
+				headers: { authorization: `Bearer ${options.token}` },
+				method: "POST"
+			});
+			if (sequence !== connectionSequence) return null;
+			if (!response?.ok) {
+				await failTicketIfCurrent(sequence, response && UNSUPPORTED_TICKET_STATUSES.has(response.status) ? "unsupportedServer" : "ticketFailed");
+				return null;
+			}
+			if (sequence !== connectionSequence) return null;
+			const body = await response.json();
+			if (sequence !== connectionSequence) return null;
+			if (typeof body.ticket === "string" && body.ticket !== "") return body.ticket;
+			await failTicketIfCurrent(sequence);
+			return null;
+		} catch {
+			await failTicketIfCurrent(sequence);
+			return null;
+		}
+	};
+	const connect = async () => {
+		const sequence = connectionSequence + 1;
+		connectionSequence = sequence;
+		reportMetric("connection_attempt", {
+			attempt: context.attempt,
+			transport: "websocket"
+		});
+		if (context.attempt > 0) reportMetric("reconnect", {
+			attempt: context.attempt,
+			transport: "websocket"
+		});
+		const ticket = await requestTicket(sequence);
+		if (!(ticket && sequence === connectionSequence && context.state !== "stopped")) return;
+		const nextSocket = options.socketFactory(socketUrl(options, ticket));
+		socket = nextSocket;
+		nextSocket.addEventListener("open", async () => {
+			if (sequence !== connectionSequence) return;
+			const hello = options.getHello();
+			nextSocket.send(JSON.stringify({
+				deploymentId: options.deploymentId,
+				issues: hello.issues,
+				instanceId,
+				sdk: hello.sdk,
+				type: "hello"
+			}));
+			await dispatch({ type: "socketOpen" });
+		});
+		nextSocket.addEventListener("message", async (event) => {
+			if (sequence !== connectionSequence) return;
+			const data = event.data;
+			if (typeof data !== "string") return;
+			try {
+				if (JSON.parse(data).type === "ready") await dispatch({ type: "ready" });
+			} catch {}
+		});
+		nextSocket.addEventListener("close", async () => {
+			if (sequence !== connectionSequence) return;
+			connectionSequence += 1;
+			socket = null;
+			await dispatch({ type: "socketClosed" });
+		});
+	};
+	return {
+		start: async () => {
+			await dispatch({ type: "start" });
+		},
+		stop: async () => {
+			connectionSequence += 1;
+			clearRetryTimer();
+			await dispatch({ type: "stop" });
+			if (fallbackStartedAt !== null) {
+				reportMetric("fallback_duration", {
+					durationMs: Date.now() - fallbackStartedAt,
+					transport: "http"
+				});
+				fallbackStartedAt = null;
+			}
+			clearPingTimer();
+			socket?.close(1e3, "goodbye");
+			socket = null;
+		}
+	};
+}
+//#endregion
+//#region src/presence-support.ts
+/**
+* This stays HTTP until the production gate in docs/presence-rollout-gate.md
+* has recorded a passing seven-day window. The later default-on rollout is a
+* one-line change here; all capability and escape-hatch behavior is stable.
+*/
+const DEFAULT_TRANSPORT = "http";
+function resolvePresenceTransport(host, configured) {
+	if (configured) return {
+		reason: "explicit configuration",
+		transport: configured
+	};
+	const environmentTransport = host.env.CLIVLY_PRESENCE_TRANSPORT;
+	if (environmentTransport === "http" || environmentTransport === "websocket") return {
+		reason: "CLIVLY_PRESENCE_TRANSPORT environment override",
+		transport: environmentTransport
+	};
+	if (host.serverless) return {
+		reason: "serverless hosts cannot retain a socket",
+		transport: "http"
+	};
+	if (!host.hasWebSocket) return {
+		reason: "WebSocket is unavailable in this host",
+		transport: "http"
+	};
+	return {
+		reason: "SDK default",
+		transport: DEFAULT_TRANSPORT
+	};
+}
+//#endregion
+//#region src/push-outcome.ts
+function isCount(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+/**
+* A message describing a push that stored nothing, or `null` when there is
+* nothing to report.
+*
+* Deliberately silent unless the server reported all three counts as numbers: an
+* older cloud answers 200 without them, and warning on an unrecognised shape
+* would fire on every push against it.
+*/
+function describeSilentPush(target, body) {
+	if (typeof body !== "object" || body === null) return null;
+	const { source, objectType } = target;
+	const { received, upserted, archived } = body;
+	if (!(isCount(received) && isCount(upserted) && isCount(archived))) return null;
+	if (received === 0 || upserted > 0 || archived > 0) return null;
+	return `Clivly sync: pushed ${received} row(s) for ${objectType ? `"${source}" → "${objectType}"` : `"${source}"`} and none were stored — no active mapping in this workspace targets it, so the rows were dropped. Map it in Integrations → Mapping, then sync again.`;
+}
+//#endregion
+//#region src/self-check.ts
+function selfCheck(input) {
+	const issues = [];
+	if (input.reportsTriggerUrl && !input.hasTriggerSecret) issues.push({
+		code: "trigger_route_unauthenticated",
+		message: "Your app's sync route is reachable but is not checking signatures.",
+		fix: "Set CLIVLY_SYNC_TRIGGER_SECRET in the environment your app runs in, then restart it."
+	});
+	if (input.lastPushFailed) issues.push({
+		code: "sync_push_failing",
+		message: input.lastPushError ? `Your app could not send its data: ${input.lastPushError}` : "Your app could not send its data to Clivly.",
+		fix: "Check your app's logs for the failing sync, then run `npx clivly doctor`."
+	});
+	return issues;
+}
+//#endregion
 //#region src/sync.ts
 const DEFAULT_ID_FIELD = "id";
 function isAfter(candidate, current) {
@@ -902,16 +1419,41 @@ function createClivlySDK(config) {
 	const apiUrl = (config.apiUrl ?? DEFAULT_API_URL).replace(TRAILING_SLASH, "");
 	const heartbeatIntervalMs = config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
 	const syncIntervalMs = config.sync?.intervalMs ?? heartbeatIntervalMs;
+	const serverless = isLikelyServerless();
+	const presenceEnabled = resolvePresenceTransport({
+		env: config.env ?? process.env,
+		hasWebSocket: typeof WebSocket === "function",
+		serverless
+	}, config.presence?.transport).transport === "websocket";
+	const deploymentId = presenceEnabled ? resolveDeploymentId(config.env ?? process.env, config.presence?.deploymentId) : null;
 	const timers = {
 		heartbeat: null,
 		sync: null
 	};
+	let presenceClient = null;
+	let httpHeartbeatActive = true;
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
 	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
 	let observedUrl;
 	let lastPushFailure = null;
+	let lastPush = { failed: false };
+	const warnedSilentTargets = /* @__PURE__ */ new Set();
+	const warnIfSilent = async (target, response) => {
+		if (typeof response.json !== "function") return;
+		let outcome;
+		try {
+			outcome = describeSilentPush(target, await response.json());
+		} catch {
+			return;
+		}
+		if (!outcome) return;
+		const key = `${target.source} ${target.objectType ?? ""}`;
+		if (warnedSilentTargets.has(key)) return;
+		warnedSilentTargets.add(key);
+		console.warn(outcome);
+	};
 	const createPush = (runId) => async (path, body) => {
 		const response = await fetcher(`${apiUrl}${path}`, {
 			method: "POST",
@@ -922,7 +1464,13 @@ function createClivlySDK(config) {
 			},
 			body: JSON.stringify(body)
 		});
-		if (response?.ok) return true;
+		if (response?.ok) {
+			await warnIfSilent({
+				source: body.source,
+				objectType: body.objectType
+			}, response);
+			return true;
+		}
 		lastPushFailure ??= { status: response?.status ?? null };
 		return false;
 	};
@@ -974,7 +1522,15 @@ function createClivlySDK(config) {
 		if (!await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode, void 0, runId)) failed.push(config.source.contacts.entity);
 		if (config.source.deals && !await syncOne(config.source.deals, SYNC_DEALS_PATH, mode, void 0, runId)) failed.push(config.source.deals.entity);
 		failed.push(...await syncCustomSources(config.source.custom, mode, runId));
-		if (failed.length > 0) throw new Error(describePushFailure(failed));
+		if (failed.length > 0) {
+			const message = describePushFailure(failed);
+			lastPush = {
+				failed: true,
+				error: message
+			};
+			throw new Error(message);
+		}
+		lastPush = { failed: false };
 	};
 	const runSampleSync = async (entityKey, runId) => {
 		const resolved = resolveSampleSource(config, entityKey);
@@ -982,33 +1538,129 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw new Error(describePushFailure([resolved.source.entity]));
 	};
-	const sendHeartbeat = () => fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
-		method: "POST",
-		headers: {
-			"content-type": "application/json",
-			authorization: `Bearer ${config.apiKey}`
-		},
-		body: JSON.stringify({
-			framework: config.framework,
-			orm: config.orm,
-			sdkVersion: config.sdkVersion,
-			contactEntity: resolveContactEntity(config),
-			namespaceReady: config.namespaceReady ?? false,
-			schema: buildSchema(config),
-			...(() => {
-				const url = resolveTriggerUrl({
-					configuredUrl: config.syncTrigger?.url,
-					configuredPath: config.syncTrigger?.path,
-					env: config.env ?? process.env,
-					observedUrl
-				});
-				return url ? { syncTrigger: { url } } : {};
-			})()
-		})
-	});
+	const sendHeartbeat = () => {
+		const triggerUrl = resolveTriggerUrl({
+			configuredUrl: config.syncTrigger?.url,
+			configuredPath: config.syncTrigger?.path,
+			env: config.env ?? process.env,
+			observedUrl
+		});
+		return fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify({
+				...deploymentId ? { deploymentId } : {},
+				framework: config.framework,
+				orm: config.orm,
+				sdkVersion: config.sdkVersion,
+				contactEntity: resolveContactEntity(config),
+				namespaceReady: config.namespaceReady ?? false,
+				schema: buildSchema(config),
+				heartbeatIntervalMs,
+				environment: detectHostEnvironment(config.env ?? process.env, config.environment),
+				issues: selfCheck({
+					hasTriggerSecret: Boolean(config.syncTrigger?.secret),
+					reportsTriggerUrl: Boolean(triggerUrl),
+					lastPushFailed: lastPush.failed,
+					lastPushError: lastPush.error
+				}),
+				...triggerUrl ? { syncTrigger: { url: triggerUrl } } : {}
+			})
+		});
+	};
 	const heartbeat = async () => {
 		return (await sendHeartbeat())?.ok ?? false;
 	};
+	const startHeartbeatInterval = () => {
+		if (timers.heartbeat) return;
+		timers.heartbeat = setInterval(() => {
+			heartbeat().catch(() => {});
+		}, heartbeatIntervalMs);
+		timers.heartbeat.unref?.();
+	};
+	const stopHeartbeatInterval = () => {
+		if (timers.heartbeat) {
+			clearInterval(timers.heartbeat);
+			timers.heartbeat = null;
+		}
+	};
+	/**
+	* Create any custom object types this config declares that the workspace does
+	* not have yet, so `clivly.config.ts` is self-contained — no dashboard visit
+	* and no server-generated id pasted into the file. Keyed by entity slug.
+	*
+	* Create-only and idempotent server-side: existing slugs resolve to their
+	* current id untouched, and nothing is renamed or removed. Returns `null` if
+	* the request never landed, so callers can distinguish "nothing to do" (an
+	* empty array) from "could not reach Clivly".
+	*/
+	const ensureCustomObjects = async () => {
+		const objects = config.entities ? (0, _clivly_core_entity_config.customObjectDeclarations)(config.entities) : [];
+		if (objects.length === 0) return [];
+		const response = await fetcher(`${apiUrl}/clivly/sdk/object-types`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify({ objects })
+		});
+		if (!response?.ok) return null;
+		return (await response.json()).objectTypes ?? [];
+	};
+	const readSchemaError = async (response) => {
+		if (response?.status !== 400) return null;
+		try {
+			const body = await response.json();
+			return typeof body.message === "string" ? body.message : null;
+		} catch {
+			return null;
+		}
+	};
+	/**
+	* Declare this host's whole schema: its custom object types AND the mappings
+	* that make them receive rows.
+	*
+	* `ensureCustomObjects` above creates the object and nothing else, which left
+	* config-as-code ending at an empty container and a sync that stored nothing.
+	* This is the call that finishes it.
+	*
+	* Returns `null` when the request never landed — including against a server
+	* old enough not to have the route — so a caller can tell "nothing to do"
+	* from "could not reach Clivly", and fall back to the objects-only endpoint.
+	*/
+	const ensureSchema = async () => {
+		const objects = config.entities ? (0, _clivly_core_entity_config.customObjectDeclarations)(config.entities) : [];
+		const mappings = config.entities ? (0, _clivly_core_mappings_config.entitiesToMappings)(config.entities) : [];
+		if (objects.length === 0 && mappings.length === 0) return {
+			objectTypes: [],
+			mappings: []
+		};
+		const response = await fetcher(`${apiUrl}/clivly/sdk/schema`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify({
+				objects,
+				mappings
+			})
+		});
+		if (!response?.ok) {
+			const message = await readSchemaError(response);
+			if (message) throw new Error(message);
+			return null;
+		}
+		const body = await response.json();
+		return {
+			objectTypes: body.objectTypes ?? [],
+			mappings: body.mappings ?? []
+		};
+	};
 	const connect = async () => {
 		const response = await sendHeartbeat();
 		if (response === null) return {
@@ -1050,6 +1702,7 @@ function createClivlySDK(config) {
 				reason: "ok",
 				retryable: false,
 				org: body?.org,
+				workspace: body?.workspace ?? null,
 				..."appLastSeenAt" in body ? { appLastSeenAt: body.appLastSeenAt ?? null } : {}
 			};
 		}
@@ -1060,9 +1713,31 @@ function createClivlySDK(config) {
 			retryable: isRetryableStatus(response.status)
 		};
 	};
+	const probeReadiness = async (entities) => {
+		const response = await fetcher(`${apiUrl}/clivly/sdk/readiness`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify({ entities })
+		});
+		if (!response?.ok) return null;
+		try {
+			const body = await response.json();
+			if (typeof body?.ready !== "boolean" || !Array.isArray(body.entities)) return null;
+			return {
+				ready: body.ready,
+				entities: body.entities
+			};
+		} catch {
+			return null;
+		}
+	};
 	const doctor = () => runDoctor({
 		config,
-		probe: ping
+		probe: ping,
+		readiness: probeReadiness
 	});
 	const runScheduled = async (options) => {
 		await heartbeat();
@@ -1116,14 +1791,48 @@ function createClivlySDK(config) {
 		}
 	};
 	const start = async () => {
-		if (isLikelyServerless()) console.warn("clivly.start() uses a setInterval keep-alive loop, which does not persist on serverless/edge runtimes — it will stop ticking after the first response. Call clivly.runScheduled() from a scheduled/cron trigger, or mount clivly.createClivlyHandler() at a route instead.");
+		if (serverless) console.warn("clivly.start() uses a setInterval keep-alive loop, which does not persist on serverless/edge runtimes — it will stop ticking after the first response. Call clivly.runScheduled() from a scheduled/cron trigger, or mount clivly.createClivlyHandler() at a route instead.");
 		await heartbeat();
 		if (config.sync?.onBoot !== false) await runSync().catch(() => {});
-		if (!timers.heartbeat) {
-			timers.heartbeat = setInterval(() => {
-				heartbeat().catch(() => {});
-			}, heartbeatIntervalMs);
-			timers.heartbeat.unref?.();
+		startHeartbeatInterval();
+		if (presenceEnabled && deploymentId && !serverless && !presenceClient) try {
+			presenceClient = createPresenceClient({
+				apiUrl,
+				deploymentId,
+				environment: detectHostEnvironment(config.env ?? process.env, config.environment),
+				fetcher,
+				getHello: () => ({
+					issues: selfCheck({
+						hasTriggerSecret: Boolean(config.syncTrigger?.secret),
+						reportsTriggerUrl: Boolean(resolveTriggerUrl({
+							configuredUrl: config.syncTrigger?.url,
+							configuredPath: config.syncTrigger?.path,
+							env: config.env ?? process.env,
+							observedUrl
+						})),
+						lastPushFailed: lastPush.failed,
+						lastPushError: lastPush.error
+					}),
+					sdk: {
+						framework: config.framework ?? null,
+						orm: config.orm ?? null,
+						version: config.sdkVersion ?? null
+					}
+				}),
+				onHttpHeartbeat: (active) => {
+					if (active) {
+						startHeartbeatInterval();
+						if (!httpHeartbeatActive) heartbeat().catch(() => {});
+					} else stopHeartbeatInterval();
+					httpHeartbeatActive = active;
+				},
+				socketFactory: (url) => new WebSocket(url),
+				token: config.apiKey
+			});
+			await presenceClient.start();
+		} catch (error) {
+			presenceClient = null;
+			console.warn("Clivly presence socket unavailable; using HTTP heartbeat", error);
 		}
 		if (!timers.sync && config.source) {
 			timers.sync = setInterval(() => {
@@ -1132,11 +1841,10 @@ function createClivlySDK(config) {
 			timers.sync.unref?.();
 		}
 	};
-	const stop = () => {
-		if (timers.heartbeat) {
-			clearInterval(timers.heartbeat);
-			timers.heartbeat = null;
-		}
+	const stop = async () => {
+		await presenceClient?.stop();
+		presenceClient = null;
+		stopHeartbeatInterval();
 		if (timers.sync) {
 			clearInterval(timers.sync);
 			timers.sync = null;
@@ -1154,6 +1862,8 @@ function createClivlySDK(config) {
 		start,
 		stop,
 		heartbeat,
+		ensureCustomObjects,
+		ensureSchema,
 		connect,
 		ping,
 		doctor,
@@ -1170,9 +1880,21 @@ exports.ClivlyNetworkError = ClivlyNetworkError;
 exports.ClivlyRateLimitError = ClivlyRateLimitError;
 exports.createChatSessionHandler = require_chat_session.createChatSessionHandler;
 exports.createClivlySDK = createClivlySDK;
+Object.defineProperty(exports, "customObjectDeclarations", {
+	enumerable: true,
+	get: function() {
+		return _clivly_core_entity_config.customObjectDeclarations;
+	}
+});
 Object.defineProperty(exports, "defineClivlyConfig", {
 	enumerable: true,
 	get: function() {
 		return _clivly_core_entity_config.defineClivlyConfig;
 	}
 });
+Object.defineProperty(exports, "validateEntitiesConfig", {
+	enumerable: true,
+	get: function() {
+		return _clivly_core_entity_config.validateEntitiesConfig;
+	}
+});