@clivly/sdk 0.10.8 → 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.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/index.cjs

@@ -394,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 = [];
@@ -407,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 } : {}
 		});
@@ -1614,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;
@@ -1836,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;
@@ -1936,7 +1962,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -1944,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.mjs

@@ -393,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 = [];
@@ -406,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 } : {}
 		});
@@ -1613,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;
@@ -1835,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;
@@ -1935,7 +1961,7 @@ function createClivlySDK(config) {
 				failed: true,
 				error: message
 			};
-			throw new Error(message);
+			throw pushFailureError(message);
 		}
 		lastPush = { failed: false };
 	};
@@ -1943,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.10.8",
+  "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.8"
+    "@clivly/core": "0.10.9"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",