@clivly/sdk 0.10.7 → 0.10.9

package/dist/chat-session.cjs

@@ -12,8 +12,18 @@ function jsonResponse(body, status) {
 function normalizeApiUrl(apiUrl) {
 	return apiUrl.replace(TRAILING_SLASH, "");
 }
-function resolveOrigin(req) {
-	const headerOrigin = req.headers.get("origin");
+/**
+* The origin *claimed* by the request, for reporting upstream.
+*
+* Falls back to the request URL so Clivly still receives an origin for a
+* non-browser caller. This value is reported, never trusted: only a real
+* `Origin` header is evidence of where a request came from, so the access
+* decision uses {@link trustedOrigin} instead. Keeping the two apart is the
+* point — conflating them let a caller that simply omitted the header be
+* judged against the server's own origin, which is usually in the allowlist.
+*/
+function reportedOrigin(req) {
+	const headerOrigin = trustedOrigin(req);
 	if (headerOrigin) return headerOrigin;
 	try {
 		return new URL(req.url).origin;
@@ -21,6 +31,15 @@ function resolveOrigin(req) {
 		return null;
 	}
 }
+/**
+* The only origin worth an access decision: one the browser set itself.
+*
+* A missing header means "not a browser request we can vouch for", which is
+* untrusted — never the server's own origin.
+*/
+function trustedOrigin(req) {
+	return req.headers.get("origin");
+}
 function isChatSessionRequestBody(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const body = value;
@@ -31,6 +50,17 @@ function isChatSessionRequestBody(value) {
 	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
 	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
 }
+/**
+* Judge a request against the configured allowlist.
+*
+* `origin` must be a *trusted* origin (see {@link trustedOrigin}) — passing
+* the reported one would reinstate the bypass this guards against.
+*
+* An unset allowlist still admits every origin, because requiring it would
+* break every existing deployment on upgrade. The unset case is instead
+* warned about once at construction, so the permissive default is loud
+* rather than silent.
+*/
 function originAllowed(origin, allowedOrigins) {
 	if (!allowedOrigins || allowedOrigins.length === 0) return true;
 	if (!origin) return false;
@@ -38,6 +68,7 @@ function originAllowed(origin, allowedOrigins) {
 }
 function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	if (!allowedOrigins || allowedOrigins.length === 0) console.warn("[clivly] createChatSessionHandler has no allowedOrigins; every origin can open a chat session against this workspace. Pass allowedOrigins to restrict it.");
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
 			status: 405,
@@ -46,8 +77,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 				allow: "POST"
 			}
 		});
-		const origin = resolveOrigin(request);
-		if (!originAllowed(origin, allowedOrigins)) return jsonResponse({ error: "origin_not_allowed" }, 403);
+		if (!originAllowed(trustedOrigin(request), allowedOrigins)) return jsonResponse({ error: "origin_not_allowed" }, 403);
+		const origin = reportedOrigin(request);
 		let body;
 		try {
 			body = await request.json();

package/dist/chat-session.d.cts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-B7HKG2Ph.cjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-CvhxV-IX.cjs";
 //#region src/chat-session.d.ts
 declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion

package/dist/chat-session.d.mts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-B7HKG2Ph.mjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-CvhxV-IX.mjs";
 //#region src/chat-session.d.ts
 declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion

package/dist/chat-session.mjs

@@ -11,8 +11,18 @@ function jsonResponse(body, status) {
 function normalizeApiUrl(apiUrl) {
 	return apiUrl.replace(TRAILING_SLASH, "");
 }
-function resolveOrigin(req) {
-	const headerOrigin = req.headers.get("origin");
+/**
+* The origin *claimed* by the request, for reporting upstream.
+*
+* Falls back to the request URL so Clivly still receives an origin for a
+* non-browser caller. This value is reported, never trusted: only a real
+* `Origin` header is evidence of where a request came from, so the access
+* decision uses {@link trustedOrigin} instead. Keeping the two apart is the
+* point — conflating them let a caller that simply omitted the header be
+* judged against the server's own origin, which is usually in the allowlist.
+*/
+function reportedOrigin(req) {
+	const headerOrigin = trustedOrigin(req);
 	if (headerOrigin) return headerOrigin;
 	try {
 		return new URL(req.url).origin;
@@ -20,6 +30,15 @@ function resolveOrigin(req) {
 		return null;
 	}
 }
+/**
+* The only origin worth an access decision: one the browser set itself.
+*
+* A missing header means "not a browser request we can vouch for", which is
+* untrusted — never the server's own origin.
+*/
+function trustedOrigin(req) {
+	return req.headers.get("origin");
+}
 function isChatSessionRequestBody(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const body = value;
@@ -30,6 +49,17 @@ function isChatSessionRequestBody(value) {
 	if (typeof visitor.email !== "string" || visitor.email.trim().length === 0) return false;
 	return body.visitorToken === void 0 || body.visitorToken === null || typeof body.visitorToken === "string";
 }
+/**
+* Judge a request against the configured allowlist.
+*
+* `origin` must be a *trusted* origin (see {@link trustedOrigin}) — passing
+* the reported one would reinstate the bypass this guards against.
+*
+* An unset allowlist still admits every origin, because requiring it would
+* break every existing deployment on upgrade. The unset case is instead
+* warned about once at construction, so the permissive default is loud
+* rather than silent.
+*/
 function originAllowed(origin, allowedOrigins) {
 	if (!allowedOrigins || allowedOrigins.length === 0) return true;
 	if (!origin) return false;
@@ -37,6 +67,7 @@ function originAllowed(origin, allowedOrigins) {
 }
 function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API_URL, fetchImpl = fetch, resolveUser }) {
 	const sessionUrl = `${normalizeApiUrl(apiUrl)}/clivly/widget/session`;
+	if (!allowedOrigins || allowedOrigins.length === 0) console.warn("[clivly] createChatSessionHandler has no allowedOrigins; every origin can open a chat session against this workspace. Pass allowedOrigins to restrict it.");
 	return async (request) => {
 		if (request.method !== "POST") return new Response(JSON.stringify({ error: "method_not_allowed" }), {
 			status: 405,
@@ -45,8 +76,8 @@ function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl = DEFAULT_API
 				allow: "POST"
 			}
 		});
-		const origin = resolveOrigin(request);
-		if (!originAllowed(origin, allowedOrigins)) return jsonResponse({ error: "origin_not_allowed" }, 403);
+		if (!originAllowed(trustedOrigin(request), allowedOrigins)) return jsonResponse({ error: "origin_not_allowed" }, 403);
+		const origin = reportedOrigin(request);
 		let body;
 		try {
 			body = await request.json();

package/dist/drizzle.cjs

@@ -59,6 +59,7 @@ function fromDrizzleProjection(db, projection, opts) {
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: cursorToken,
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
@@ -88,6 +89,7 @@ function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromC
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: "id",
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { _ as SyncSource, y as NamespaceIntrospector } from "./types-B7HKG2Ph.cjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-CvhxV-IX.cjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { _ as SyncSource, y as NamespaceIntrospector } from "./types-B7HKG2Ph.mjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-CvhxV-IX.mjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";

package/dist/drizzle.mjs

@@ -58,6 +58,7 @@ function fromDrizzleProjection(db, projection, opts) {
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: cursorToken,
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
@@ -87,6 +88,7 @@ function fromDrizzleProjectionByIdentity(client, projection, identityExpr, fromC
 	const head = [`select ${selectItems.join(", ")}`, fromClause].join(" ");
 	return {
 		entity: opts.entity,
+		pushSource: projection.baseTable,
 		cursorField: "id",
 		idField: "id",
 		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },

package/dist/index.cjs

@@ -79,6 +79,43 @@ function resolveEntitySource(config, entityKey) {
 function expectedSourceKey(concept) {
 	return CONCEPT_KEYS[concept] ?? "custom";
 }
+/**
+* The `source` label a push must carry for the server to find its mapping.
+*
+* `entity` is the SDK's own name for a source — the cursor-store key, and what
+* the developer wrote in `config.source`. It is NOT always what the server
+* filed the mapping under: for a projection, `ensureSchema` stores
+* `sourceTable` as `projection.baseTable`, because a projection entity's key
+* doubles as a kebab-case object slug and cannot also be the snake_case
+* `projection.entityKey`.
+*
+* Pushing under `entity` therefore dropped 100% of a projection's rows while
+* every local signal said the setup was correct. One function so the three
+* push sites cannot drift apart again.
+*/
+function pushSourceOf(source) {
+	return source.pushSource ?? source.entity;
+}
+/**
+* The push label for a custom source, resolved against the config.
+*
+* `fromDrizzleProjection` stamps `pushSource` itself, but a projection source
+* can equally be hand-built — `fromDrizzle` with an overridden `fetchPage` is
+* what the README's own example leads you to, and next-finance did exactly
+* that. Such a source has no `pushSource`, so the label has to come from the
+* one place that is true either way: the entity's declared
+* `projection.baseTable`.
+*
+* Matched on the source's `entity`, which for a custom source is also the
+* config entity key (that is what `resolveEntitySource` above pairs them by).
+* Falls back to `pushSourceOf`, so a non-projection custom source and an
+* already-stamped one both keep their current label.
+*/
+function customPushSource(config, source) {
+	if (source.pushSource) return source.pushSource;
+	const entities = config.entities?.entities;
+	return (entities?.[source.entity] ?? Object.values(entities ?? {}).find((e) => e.source === source.entity))?.projection?.baseTable ?? source.entity;
+}
 //#endregion
 //#region src/concept-coverage.ts
 const CHECK_NAME$1 = "Entity → source coverage";
@@ -357,11 +394,15 @@ function errorMessage(error) {
 /**
 * The entities to ask about, in the exact terms the sync pushes them.
 *
-* `source` is the resolved `SyncSource.entity` — the value that arrives at
+* `source` is whatever the push will actually send — the value that arrives at
 * `ingestPush` as `input.source` and is compared against `mapping.sourceTable`.
+* Usually that is `SyncSource.entity`, but a projection pushes under its base
+* table, so this asks `customPushSource` rather than reading `entity` directly.
+*
 * 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.
+* the two are routinely conflated, and using the wrong one reports a correctly
+* mapped workspace as unmapped — which is exactly what happened to every
+* projection until this used the push label.
 */
 function readinessEntitiesFromConfig(config) {
 	const entities = [];
@@ -370,7 +411,7 @@ function readinessEntitiesFromConfig(config) {
 		if (!resolved) continue;
 		const objectTypeSlug = resolved.source.objectType;
 		entities.push({
-			source: resolved.source.entity,
+			source: customPushSource(config, resolved.source),
 			concept: resolved.concept,
 			...resolved.concept === "custom" && objectTypeSlug ? { objectTypeSlug } : {}
 		});
@@ -1205,7 +1246,7 @@ async function pushRemoteProjections(args) {
 		}
 		try {
 			const ok = await args.push(SYNC_CUSTOM_PATH$1, {
-				source: source.entity,
+				source: pushSourceOf(source),
 				rows: all,
 				mode: "full",
 				fetched: all.length,
@@ -1280,7 +1321,7 @@ async function syncSource(args) {
 		if (rows.length === 0) break;
 		const capped = maxRows === void 0 ? rows : rows.slice(0, maxRows);
 		if (!await push(path, {
-			source: source.entity,
+			source: pushSourceOf(source),
 			rows: capped,
 			mode: "delta",
 			fetched: rows.length,
@@ -1324,7 +1365,7 @@ async function fullSyncSource(args) {
 		ok: true
 	};
 	const ok = await push(path, {
-		source: source.entity,
+		source: pushSourceOf(source),
 		rows: all,
 		mode: "full",
 		fetched: all.length,
@@ -1577,6 +1618,18 @@ var TriggerRequestError = class extends Error {
 function triggerErrorStatus(error) {
 	return error instanceof TriggerRequestError ? error.status : 500;
 }
+const SENTENCE_END_RE = /[.!?]$/;
+async function readPushFailureMessage(response) {
+	if (!response || typeof response.json !== "function") return null;
+	try {
+		const body = await response.json();
+		if (typeof body !== "object" || body === null) return null;
+		const { message } = body;
+		return typeof message === "string" && message.trim().length > 0 ? message : null;
+	} catch {
+		return null;
+	}
+}
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
 const SECONDS_PER_MS = 1e3;
@@ -1799,17 +1852,27 @@ function createClivlySDK(config) {
 			}, response);
 			return true;
 		}
-		lastPushFailure ??= { status: response?.status ?? null };
+		lastPushFailure ??= {
+			status: response?.status ?? null,
+			message: await readPushFailureMessage(response)
+		};
 		return false;
 	};
 	const describePushFailure = (entities) => {
 		const base = `Clivly sync: push failed for ${entities.join(", ")}`;
 		const status = lastPushFailure?.status ?? null;
+		const serverMessage = lastPushFailure?.message ?? null;
 		let cause;
 		if (status === 401 || status === 403) cause = "the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this org";
 		else if (status === null) cause = `couldn't reach Clivly at ${apiUrl} — check network access and CLIVLY_API_URL`;
+		else if (serverMessage) cause = `Clivly returned HTTP ${status}: ${serverMessage}`;
 		else cause = `Clivly returned HTTP ${status}`;
-		return `${base}: ${cause}. Run \`clivly doctor\` to diagnose.`;
+		const separator = SENTENCE_END_RE.test(cause) ? "" : ".";
+		return `${base}: ${cause}${separator} Run \`clivly doctor\` to diagnose.`;
+	};
+	const pushFailureError = (message) => {
+		const status = lastPushFailure?.status ?? null;
+		return status !== null && status >= CLIENT_ERROR_FLOOR && status < RETRYABLE_STATUS_FLOOR ? new TriggerRequestError(status, message) : new Error(message);
 	};
 	const syncOne = async (source, path, mode, objectType, runId, batchSizeOverride, maxRowsOverride, persistCursor = true) => {
 		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
@@ -1835,7 +1898,10 @@ function createClivlySDK(config) {
 	};
 	const syncCustomSources = async (customSources, mode, runId) => {
 		const failed = [];
-		for (const customSource of customSources ?? []) if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
+		for (const customSource of customSources ?? []) {
+			customSource.pushSource = customPushSource(config, customSource);
+			if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
+		}
 		return failed;
 	};
 	const syncRemoteSources = async (sources, runId) => {
@@ -1896,7 +1962,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -1904,7 +1970,7 @@ function createClivlySDK(config) {
 		const resolved = resolveSampleSource(config, entityKey);
 		if (!resolved) throw new TriggerRequestError(400, `Clivly sync: no source is configured for entity "${entityKey}". The dashboard maps this table, but clivly.config declares no matching entity — add it to \`entities\`, or remove the mapping in Integrations → Mapping.`);
 		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]));
+		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-B7HKG2Ph.cjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-CvhxV-IX.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-B7HKG2Ph.mjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-CvhxV-IX.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts

package/dist/index.mjs

@@ -78,6 +78,43 @@ function resolveEntitySource(config, entityKey) {
 function expectedSourceKey(concept) {
 	return CONCEPT_KEYS[concept] ?? "custom";
 }
+/**
+* The `source` label a push must carry for the server to find its mapping.
+*
+* `entity` is the SDK's own name for a source — the cursor-store key, and what
+* the developer wrote in `config.source`. It is NOT always what the server
+* filed the mapping under: for a projection, `ensureSchema` stores
+* `sourceTable` as `projection.baseTable`, because a projection entity's key
+* doubles as a kebab-case object slug and cannot also be the snake_case
+* `projection.entityKey`.
+*
+* Pushing under `entity` therefore dropped 100% of a projection's rows while
+* every local signal said the setup was correct. One function so the three
+* push sites cannot drift apart again.
+*/
+function pushSourceOf(source) {
+	return source.pushSource ?? source.entity;
+}
+/**
+* The push label for a custom source, resolved against the config.
+*
+* `fromDrizzleProjection` stamps `pushSource` itself, but a projection source
+* can equally be hand-built — `fromDrizzle` with an overridden `fetchPage` is
+* what the README's own example leads you to, and next-finance did exactly
+* that. Such a source has no `pushSource`, so the label has to come from the
+* one place that is true either way: the entity's declared
+* `projection.baseTable`.
+*
+* Matched on the source's `entity`, which for a custom source is also the
+* config entity key (that is what `resolveEntitySource` above pairs them by).
+* Falls back to `pushSourceOf`, so a non-projection custom source and an
+* already-stamped one both keep their current label.
+*/
+function customPushSource(config, source) {
+	if (source.pushSource) return source.pushSource;
+	const entities = config.entities?.entities;
+	return (entities?.[source.entity] ?? Object.values(entities ?? {}).find((e) => e.source === source.entity))?.projection?.baseTable ?? source.entity;
+}
 //#endregion
 //#region src/concept-coverage.ts
 const CHECK_NAME$1 = "Entity → source coverage";
@@ -356,11 +393,15 @@ function errorMessage(error) {
 /**
 * The entities to ask about, in the exact terms the sync pushes them.
 *
-* `source` is the resolved `SyncSource.entity` — the value that arrives at
+* `source` is whatever the push will actually send — the value that arrives at
 * `ingestPush` as `input.source` and is compared against `mapping.sourceTable`.
+* Usually that is `SyncSource.entity`, but a projection pushes under its base
+* table, so this asks `customPushSource` rather than reading `entity` directly.
+*
 * 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.
+* the two are routinely conflated, and using the wrong one reports a correctly
+* mapped workspace as unmapped — which is exactly what happened to every
+* projection until this used the push label.
 */
 function readinessEntitiesFromConfig(config) {
 	const entities = [];
@@ -369,7 +410,7 @@ function readinessEntitiesFromConfig(config) {
 		if (!resolved) continue;
 		const objectTypeSlug = resolved.source.objectType;
 		entities.push({
-			source: resolved.source.entity,
+			source: customPushSource(config, resolved.source),
 			concept: resolved.concept,
 			...resolved.concept === "custom" && objectTypeSlug ? { objectTypeSlug } : {}
 		});
@@ -1204,7 +1245,7 @@ async function pushRemoteProjections(args) {
 		}
 		try {
 			const ok = await args.push(SYNC_CUSTOM_PATH$1, {
-				source: source.entity,
+				source: pushSourceOf(source),
 				rows: all,
 				mode: "full",
 				fetched: all.length,
@@ -1279,7 +1320,7 @@ async function syncSource(args) {
 		if (rows.length === 0) break;
 		const capped = maxRows === void 0 ? rows : rows.slice(0, maxRows);
 		if (!await push(path, {
-			source: source.entity,
+			source: pushSourceOf(source),
 			rows: capped,
 			mode: "delta",
 			fetched: rows.length,
@@ -1323,7 +1364,7 @@ async function fullSyncSource(args) {
 		ok: true
 	};
 	const ok = await push(path, {
-		source: source.entity,
+		source: pushSourceOf(source),
 		rows: all,
 		mode: "full",
 		fetched: all.length,
@@ -1576,6 +1617,18 @@ var TriggerRequestError = class extends Error {
 function triggerErrorStatus(error) {
 	return error instanceof TriggerRequestError ? error.status : 500;
 }
+const SENTENCE_END_RE = /[.!?]$/;
+async function readPushFailureMessage(response) {
+	if (!response || typeof response.json !== "function") return null;
+	try {
+		const body = await response.json();
+		if (typeof body !== "object" || body === null) return null;
+		const { message } = body;
+		return typeof message === "string" && message.trim().length > 0 ? message : null;
+	} catch {
+		return null;
+	}
+}
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const SIGNATURE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
 const SECONDS_PER_MS = 1e3;
@@ -1798,17 +1851,27 @@ function createClivlySDK(config) {
 			}, response);
 			return true;
 		}
-		lastPushFailure ??= { status: response?.status ?? null };
+		lastPushFailure ??= {
+			status: response?.status ?? null,
+			message: await readPushFailureMessage(response)
+		};
 		return false;
 	};
 	const describePushFailure = (entities) => {
 		const base = `Clivly sync: push failed for ${entities.join(", ")}`;
 		const status = lastPushFailure?.status ?? null;
+		const serverMessage = lastPushFailure?.message ?? null;
 		let cause;
 		if (status === 401 || status === 403) cause = "the API key was rejected — check CLIVLY_API_KEY is set to a valid key for this org";
 		else if (status === null) cause = `couldn't reach Clivly at ${apiUrl} — check network access and CLIVLY_API_URL`;
+		else if (serverMessage) cause = `Clivly returned HTTP ${status}: ${serverMessage}`;
 		else cause = `Clivly returned HTTP ${status}`;
-		return `${base}: ${cause}. Run \`clivly doctor\` to diagnose.`;
+		const separator = SENTENCE_END_RE.test(cause) ? "" : ".";
+		return `${base}: ${cause}${separator} Run \`clivly doctor\` to diagnose.`;
+	};
+	const pushFailureError = (message) => {
+		const status = lastPushFailure?.status ?? null;
+		return status !== null && status >= CLIENT_ERROR_FLOOR && status < RETRYABLE_STATUS_FLOOR ? new TriggerRequestError(status, message) : new Error(message);
 	};
 	const syncOne = async (source, path, mode, objectType, runId, batchSizeOverride, maxRowsOverride, persistCursor = true) => {
 		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
@@ -1834,7 +1897,10 @@ function createClivlySDK(config) {
 	};
 	const syncCustomSources = async (customSources, mode, runId) => {
 		const failed = [];
-		for (const customSource of customSources ?? []) if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
+		for (const customSource of customSources ?? []) {
+			customSource.pushSource = customPushSource(config, customSource);
+			if (!await syncOne(customSource, SYNC_CUSTOM_PATH, mode, customSource.objectType, runId)) failed.push(customSource.entity);
+		}
 		return failed;
 	};
 	const syncRemoteSources = async (sources, runId) => {
@@ -1895,7 +1961,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -1903,7 +1969,7 @@ function createClivlySDK(config) {
 		const resolved = resolveSampleSource(config, entityKey);
 		if (!resolved) throw new TriggerRequestError(400, `Clivly sync: no source is configured for entity "${entityKey}". The dashboard maps this table, but clivly.config declares no matching entity — add it to \`entities\`, or remove the mapping in Integrations → Mapping.`);
 		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]));
+		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,

package/dist/{types-B7HKG2Ph.d.cts → types-CvhxV-IX.d.cts}

@@ -376,6 +376,22 @@ interface SyncSource {
    * absent from another, and read by the runtime.
    */
   objectType?: string;
+  /**
+   * The `source` label a push carries, when it differs from `entity`.
+   *
+   * Only a projection sets this, and only because a projection entity has no
+   * choice but to carry two names: its entity key doubles as the custom-object
+   * slug and must be kebab-case, while `projection.entityKey` is validated by
+   * `/^[a-z][a-z0-9_]*$/` and rejects hyphens. The server resolves that by
+   * storing the mapping's `sourceTable` as `projection.baseTable` — so a push
+   * labelled with the entity key matched no mapping and every row was dropped,
+   * while `push-schema` reported the mapping created and exited 0.
+   *
+   * Deliberately NOT folded into `entity`: that value is also the cursor-store
+   * key, so redefining it would silently reset the sync cursor of every
+   * existing projection and re-push its whole history.
+   */
+  pushSource?: string;
   /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
   [DRIZZLE_META]?: DrizzleSourceMeta;
 }

package/dist/{types-B7HKG2Ph.d.mts → types-CvhxV-IX.d.mts}

@@ -376,6 +376,22 @@ interface SyncSource {
    * absent from another, and read by the runtime.
    */
   objectType?: string;
+  /**
+   * The `source` label a push carries, when it differs from `entity`.
+   *
+   * Only a projection sets this, and only because a projection entity has no
+   * choice but to carry two names: its entity key doubles as the custom-object
+   * slug and must be kebab-case, while `projection.entityKey` is validated by
+   * `/^[a-z][a-z0-9_]*$/` and rejects hyphens. The server resolves that by
+   * storing the mapping's `sourceTable` as `projection.baseTable` — so a push
+   * labelled with the entity key matched no mapping and every row was dropped,
+   * while `push-schema` reported the mapping created and exited 0.
+   *
+   * Deliberately NOT folded into `entity`: that value is also the cursor-store
+   * key, so redefining it would silently reset the sync cursor of every
+   * existing projection and re-push its whole history.
+   */
+  pushSource?: string;
   /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
   [DRIZZLE_META]?: DrizzleSourceMeta;
 }

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-B7HKG2Ph.cjs";
+import { a as ClivlySDK } from "./types-CvhxV-IX.cjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-B7HKG2Ph.mjs";
+import { a as ClivlySDK } from "./types-CvhxV-IX.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 interface ClivlyViteOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.10.7",
+  "version": "0.10.9",
   "private": false,
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
   "license": "MIT",
@@ -49,10 +49,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@clivly/core": "0.10.7"
+    "@clivly/core": "0.10.9"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",