@calmlens/sdk 0.0.0-stage → 0.5.0

package/bin/calmlens.js

@@ -0,0 +1,1323 @@
+#!/usr/bin/env node
+let node_util = require("node:util");
+let api_def = require("api-def");
+let sendable_error = require("sendable-error");
+let node_crypto = require("node:crypto");
+//#region ../shared/src/AssetPayload.ts
+const uint8ArrayInputToNumbers = (value) => {
+	if (Array.isArray(value)) return value;
+	return Array.from(value);
+};
+const bufferInputToBytes = (value) => {
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	return Uint8Array.from(value);
+};
+const BASE64_PART_BOUNDARY_ERROR = "Invalid base64 part. For multipart uploads, split the original bytes first, then base64-encode each part. Do not split one full base64 string into substrings.";
+const MULTIPART_PART_TOO_SMALL_ERROR = `Multipart upload parts must be at least 5MiB except the final part.`;
+const getRawBase64 = (value) => {
+	const markerIndex = value.indexOf(";base64,");
+	if (markerIndex === -1) return value;
+	return value.slice(markerIndex + 8);
+};
+const validateBase64PayloadString = (payload, options) => {
+	const raw = getRawBase64(payload.base64).replace(/\s/g, "");
+	if (options?.multipart && raw.length % 4 !== 0) return {
+		ok: false,
+		error: BASE64_PART_BOUNDARY_ERROR
+	};
+	return { ok: true };
+};
+const assetToData = (payload) => {
+	if ("plainText" in payload && payload.plainText !== void 0) return new TextEncoder().encode(payload.plainText);
+	if ("data" in payload && payload.data) return payload.data;
+	if ("buffer" in payload) {
+		if (payload.buffer instanceof ArrayBuffer) return payload.buffer;
+		return bufferInputToBytes(payload.buffer);
+	}
+	if (payload.uint8Array !== void 0) return Uint8Array.from(uint8ArrayInputToNumbers(payload.uint8Array));
+	if (payload.base64 === void 0) throw new Error("Invalid asset payload");
+	const raw = getRawBase64(payload.base64);
+	if (typeof Buffer !== "undefined") return Uint8Array.from(Buffer.from(raw, "base64"));
+	const binary = atob(raw);
+	return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+};
+const getAssetPayloadByteLength = (payload) => {
+	if ("plainText" in payload && payload.plainText !== void 0) return new TextEncoder().encode(payload.plainText).byteLength;
+	if ("data" in payload && payload.data) {
+		if (payload.data instanceof Blob) return payload.data.size;
+		if (payload.data instanceof Response) {
+			const contentLength = payload.data.headers.get("content-length");
+			return contentLength ? Number(contentLength) : void 0;
+		}
+		return;
+	}
+	if ("buffer" in payload && payload.buffer) return payload.buffer.byteLength;
+	if (payload.uint8Array !== void 0) {
+		if (Array.isArray(payload.uint8Array)) return payload.uint8Array.length;
+		return payload.uint8Array.byteLength;
+	}
+	if (payload.base64 === void 0) return;
+	const raw = getRawBase64(payload.base64).replace(/\s/g, "");
+	const padding = raw.endsWith("==") ? 2 : raw.endsWith("=") ? 1 : 0;
+	return Math.max(0, Math.floor(raw.length * 3 / 4) - padding);
+};
+const validateAssetPayload = (payload, options) => {
+	if ("base64" in payload && payload.base64 !== void 0) {
+		const validation = validateBase64PayloadString(payload, options);
+		if (!validation.ok) return {
+			ok: false,
+			error: validation.error
+		};
+	}
+	const byteLength = getAssetPayloadByteLength(payload);
+	if (options?.multipart && !options.isFinal && byteLength !== void 0 && byteLength < 5242880) return {
+		ok: false,
+		error: MULTIPART_PART_TOO_SMALL_ERROR
+	};
+	return { ok: true };
+};
+//#endregion
+//#region ../shared/src/JsonUtils.ts
+const stringifyJsonCanonical = (value) => JSON.stringify(value, (_key, nestedValue) => {
+	if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) return nestedValue;
+	return Object.fromEntries(Object.keys(nestedValue).sort().map((key) => [key, nestedValue[key]]));
+});
+//#endregion
+//#region ../shared/src/PublicErrorCodes.ts
+const PUBLIC_ERROR_CODES = {
+	MISSING_TOKEN: new sendable_error.ErrorCode({
+		id: "auth/missing-token",
+		defaultMessage: "Authentication required. Send your project API key in the X-Api-Key header.",
+		status: 401
+	}),
+	INVALID_API_KEY: new sendable_error.ErrorCode({
+		id: "auth/invalid-api-key",
+		defaultMessage: "The API key is invalid, revoked or expired. Create a key under Developer → API Keys.",
+		status: 401
+	}),
+	API_KEY_PROJECT_MISMATCH: new sendable_error.ErrorCode({
+		id: "auth/project-mismatch",
+		defaultMessage: "This API key belongs to a different project. Use a key created for the project that owns this resource.",
+		status: 403
+	}),
+	API_KEY_NOT_ACCEPTED: new sendable_error.ErrorCode({
+		id: "auth/api-key-not-accepted",
+		defaultMessage: "API keys are only accepted by the public API at /v1.",
+		status: 403
+	}),
+	FILE_TOO_LARGE: new sendable_error.ErrorCode({
+		id: "upload/file-too-large",
+		defaultMessage: "File size exceeds limit. Maximum direct image size is 10MB, audio/video size is 50MiB, and other files is 5GB.",
+		status: 400
+	}),
+	IMAGE_REQUIRES_MULTIPART_UPLOAD: new sendable_error.ErrorCode({
+		id: "upload/image-requires-multipart-upload",
+		defaultMessage: "Images of 10MB or more must use a multipart upload.",
+		status: 400
+	}),
+	MULTIPART_IMAGE_TOO_SMALL: new sendable_error.ErrorCode({
+		id: "upload/multipart-image-too-small",
+		defaultMessage: "Multipart image uploads must total at least 10MB.",
+		status: 400
+	}),
+	MULTIPART_IMAGE_TOO_LARGE: new sendable_error.ErrorCode({
+		id: "upload/multipart-image-too-large",
+		defaultMessage: "Multipart image uploads cannot exceed 20MB.",
+		status: 400
+	}),
+	IMAGE_EXCEEDED_MAX_DIMENSIONS: new sendable_error.ErrorCode({
+		id: "upload/image-exceeded-max-dimensions",
+		defaultMessage: "Image exceeds maximum dimensions. Maximum dimensions are 12,000px.",
+		status: 400
+	}),
+	UPLOAD_LIMIT_EXCEEDED: new sendable_error.ErrorCode({
+		id: "upload/limit-exceeded",
+		defaultMessage: "Upload limit exceeded. You have used all your free uploads. Please upgrade to Plus or Pro for unlimited uploads.",
+		status: 403
+	}),
+	INVALID_UPLOAD_MIME_TYPE: new sendable_error.ErrorCode({
+		id: "upload/invalid-mime-type",
+		defaultMessage: "Upload file type is not supported. Uploads must use a concrete file MIME type that CalmLens can store and process, such as image/png, image/jpeg, application/pdf, or text/plain.",
+		status: 400
+	}),
+	INVALID_EVENT_CURSOR: new sendable_error.ErrorCode({
+		id: "events/invalid-cursor",
+		defaultMessage: "The events cursor is invalid. Use the cursor from a previous response, or omit it to start from now.",
+		status: 400
+	}),
+	INVALID_UPLOAD_PAYLOAD: new sendable_error.ErrorCode({
+		id: "upload/invalid-payload",
+		defaultMessage: "Upload payload is invalid.",
+		status: 400
+	}),
+	USE_UPLOAD_PART: new sendable_error.ErrorCode({
+		id: "upload/use-upload-part",
+		defaultMessage: "Use uploadPart for multipart upload parts after the first part",
+		status: 409
+	}),
+	UPLOAD_NOT_OPEN: new sendable_error.ErrorCode({
+		id: "upload/not-open",
+		defaultMessage: "Asset is not accepting additional parts",
+		status: 409
+	}),
+	INVALID_UPLOAD_PART_NUMBER: new sendable_error.ErrorCode({
+		id: "upload/invalid-part-number",
+		defaultMessage: "Multipart upload part number is invalid.",
+		status: 409
+	}),
+	UPLOAD_MISSING: new sendable_error.ErrorCode({
+		id: "upload/missing",
+		defaultMessage: "Multipart upload state is missing",
+		status: 409
+	}),
+	ASSET_NOT_FOUND: new sendable_error.ErrorCode({
+		id: "asset/not-found",
+		defaultMessage: "Asset not found",
+		status: 404
+	}),
+	PROJECT_NOT_FOUND: new sendable_error.ErrorCode({
+		id: "project/not-found",
+		defaultMessage: "Project not found",
+		status: 404
+	}),
+	ASSET_UPDATE_FAILED: new sendable_error.ErrorCode({
+		id: "asset/update-failed",
+		defaultMessage: "Failed to update asset",
+		status: 500
+	}),
+	ASSET_SAFETY_HELD: new sendable_error.ErrorCode({
+		id: "asset/safety-held",
+		defaultMessage: "Asset access is restricted by a safety hold.",
+		status: 423
+	}),
+	ASSET_NOT_RETRYABLE: new sendable_error.ErrorCode({
+		id: "asset/not-retryable",
+		defaultMessage: "Only assets that failed to process (status error) can be retried.",
+		status: 409
+	}),
+	ASSET_CONTENT_UNAVAILABLE: new sendable_error.ErrorCode({
+		id: "asset/content-unavailable",
+		defaultMessage: "This asset's content is no longer stored, so it can't be processed again. Upload it again instead.",
+		status: 409
+	}),
+	SUPPORT_TICKET_NOT_FOUND: new sendable_error.ErrorCode({
+		id: "support/ticket-not-found",
+		defaultMessage: "Support ticket not found.",
+		status: 404
+	}),
+	DUPLICATE_EXTERNAL_ID: new sendable_error.ErrorCode({
+		id: "asset/duplicate-external-id",
+		defaultMessage: "An asset with this externalId already exists in the project.",
+		status: 409
+	}),
+	FOLDER_NOT_FOUND: new sendable_error.ErrorCode({
+		id: "folder/not-found",
+		defaultMessage: "Folder not found",
+		status: 404
+	}),
+	DUPLICATE_FOLDER_NAME: new sendable_error.ErrorCode({
+		id: "folder/duplicate-name",
+		defaultMessage: "A folder with this name already exists in this location.",
+		status: 409
+	}),
+	FOLDER_NOT_EMPTY: new sendable_error.ErrorCode({
+		id: "folder/not-empty",
+		defaultMessage: "Folder must be empty before it can be deleted.",
+		status: 409
+	}),
+	FOLDER_PARENT_CYCLE: new sendable_error.ErrorCode({
+		id: "folder/parent-cycle",
+		defaultMessage: "A folder cannot be moved inside itself or one of its descendants.",
+		status: 409
+	}),
+	LENS_VERSION_CONFLICT: new sendable_error.ErrorCode({
+		id: "lens/version-conflict",
+		defaultMessage: "Lens updates require a version greater than the current version.",
+		status: 409
+	})
+};
+PUBLIC_ERROR_CODES.MISSING_TOKEN, PUBLIC_ERROR_CODES.INVALID_API_KEY, PUBLIC_ERROR_CODES.API_KEY_PROJECT_MISMATCH;
+const MAX_IMAGE_UPLOAD_BYTES = /* @__PURE__ */ (() => 20971520)();
+const MIN_MULTIPART_IMAGE_UPLOAD_BYTES = /* @__PURE__ */ (() => 10485760)();
+const REJECTED_UPLOAD_MIME_TYPE_SET = /* @__PURE__ */ new Set([
+	"application/octet-stream",
+	"multipart/form-data",
+	"multipart/mixed",
+	"multipart/alternative",
+	"multipart/related",
+	"multipart/signed",
+	"multipart/encrypted"
+]);
+const normalizeUploadMimeType = (mimeType) => mimeType.toLowerCase().split(";")[0]?.trim() || mimeType.toLowerCase().trim();
+const isRejectedUploadMimeType = (mimeType) => REJECTED_UPLOAD_MIME_TYPE_SET.has(normalizeUploadMimeType(mimeType));
+const getRejectedUploadMimeTypeError = (mimeType) => `${normalizeUploadMimeType(mimeType)} is not a valid upload file type. Uploads must use a concrete file MIME type that CalmLens can store and process, such as image/png, image/jpeg, application/pdf, or text/plain.`;
+//#endregion
+//#region src/client/CalmLensError.ts
+const SDK_ERRORS = { NO_CDN_FETCH: {
+	id: "sdk/no-cdn-fetch",
+	defaultMessage: "No fetch implementation is available for CDN requests"
+} };
+var CalmLensError = class extends Error {
+	constructor(errorCode, options) {
+		const code = "getId" in errorCode ? errorCode.getId() : errorCode.id;
+		const defaultMessage = "getDefaultMessage" in errorCode ? errorCode.getDefaultMessage() : errorCode.defaultMessage;
+		super(`[calmlens] ${options?.message ?? defaultMessage ?? code}`, { cause: options?.cause });
+		this.name = "CalmLensError";
+		this.code = code;
+		this.details = options?.details;
+		this.status = options?.status;
+	}
+};
+const calmLensError = (errorCode, options) => new CalmLensError(errorCode, options);
+//#endregion
+//#region src/client/CalmLensUtils.ts
+const toTextAssetOptions = ({ text, name, ...options }) => {
+	if (typeof text !== "string" || !text.trim()) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: "Text to moderate must be a non-empty string" });
+	return {
+		...options,
+		name: name ?? "text",
+		content: {
+			plainText: text,
+			type: "text/plain"
+		}
+	};
+};
+//#endregion
+//#region src/client/CalmLensWebhooks.ts
+const WEBHOOK_DELIVERY_HEADER = "x-calmlens-delivery";
+const WEBHOOK_TIMESTAMP_HEADER = "x-calmlens-timestamp";
+const WEBHOOK_SIGNATURE_HEADER = "x-calmlens-signature";
+/** The JSON body of a webhook delivery for a stored event. */
+const toWebhookEventPayload = (event) => ({
+	id: event.id,
+	type: event.type,
+	createdAt: event.createdAt,
+	projectId: event.projectId,
+	data: {
+		severity: event.severity,
+		title: event.title,
+		description: event.description ?? null,
+		assetId: event.assetId ?? null,
+		asset: event.asset ?? null,
+		facts: event.facts
+	}
+});
+const encoder = new TextEncoder();
+const hmacSha256Hex = async (secret, message) => {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+	return Array.from(new Uint8Array(signature), (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+/** Constant-time comparison of two strings of the same length. */
+const timingSafeEqual = (a, b) => {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+};
+/** `v1=<hex HMAC-SHA256 of "<timestamp>.<body>">`, the `x-calmlens-signature` header value. */
+const createWebhookSignatureHeader = async (secret, timestamp, body) => `v1=${await hmacSha256Hex(secret, `${timestamp}.${body}`)}`;
+/** Headers for one signed delivery of `body`. */
+const createWebhookHeaders = async (options) => {
+	const timestamp = options.timestampSeconds ?? Math.floor(Date.now() / 1e3);
+	return {
+		"content-type": "application/json",
+		[WEBHOOK_DELIVERY_HEADER]: options.deliveryId,
+		[WEBHOOK_TIMESTAMP_HEADER]: String(timestamp),
+		[WEBHOOK_SIGNATURE_HEADER]: await createWebhookSignatureHeader(options.secret, timestamp, options.body)
+	};
+};
+/**
+* Verifies a webhook delivery: `x-calmlens-signature` must contain a `v1=` HMAC-SHA256 of
+* `"<x-calmlens-timestamp>.<raw body>"`, and the timestamp must be within `toleranceSeconds`
+* (default 300) of now. Returns `false` for anything missing or malformed.
+*/
+async function verifyWebhookSignature({ payload, signature, timestamp, secret, toleranceSeconds = 300, now }) {
+	if (!secret || !signature || timestamp === null || timestamp === void 0) return false;
+	const timestampText = String(timestamp).trim();
+	if (!/^\d+$/.test(timestampText)) return false;
+	const nowMs = now === void 0 ? Date.now() : now instanceof Date ? now.getTime() : now;
+	if (Math.abs(Math.floor(nowMs / 1e3) - Number(timestampText)) > toleranceSeconds) return false;
+	const candidates = signature.split(",").map((part) => part.trim()).filter((part) => part.startsWith("v1=")).map((part) => part.slice(3).toLowerCase());
+	if (candidates.length === 0) return false;
+	const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+	const expected = await hmacSha256Hex(secret, `${timestampText}.${body}`);
+	let matched = false;
+	for (const candidate of candidates) if (timingSafeEqual(expected, candidate)) matched = true;
+	return matched;
+}
+//#endregion
+//#region src/client/CalmLensClient.ts
+const toBlobPartBytes = (value) => {
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	return Uint8Array.from(value);
+};
+const normalizePayloadForRequest = (payload) => {
+	if ("base64" in payload && payload.base64) return {
+		...payload,
+		base64: getRawBase64(payload.base64)
+	};
+	if ("uint8Array" in payload && payload.uint8Array) {
+		const { uint8Array, ...rest } = payload;
+		return {
+			...rest,
+			data: new Blob([toBlobPartBytes(uint8Array)])
+		};
+	}
+	if ("buffer" in payload && payload.buffer) {
+		const { buffer, ...rest } = payload;
+		return {
+			...rest,
+			data: new Blob([toBlobPartBytes(buffer)])
+		};
+	}
+	return payload;
+};
+const normalizeMetadataForMultipart = (metadata) => {
+	if (!Array.isArray(metadata)) return metadata;
+	return Object.fromEntries(metadata.map((item, index) => [index, item]));
+};
+const normalizeMetadataOptionsForRequest = (options) => {
+	if (!("metadata" in options) || !Array.isArray(options.metadata)) return options;
+	return {
+		...options,
+		metadata: normalizeMetadataForMultipart(options.metadata)
+	};
+};
+const normalizeAssetOptionsForRequest = (options) => {
+	const normalizedOptions = normalizeMetadataOptionsForRequest(options);
+	if ("part" in normalizedOptions) return {
+		...normalizedOptions,
+		part: normalizePayloadForRequest(normalizedOptions.part)
+	};
+	if ("content" in normalizedOptions && !("plainText" in normalizedOptions.content)) return {
+		...normalizedOptions,
+		content: normalizePayloadForRequest(normalizedOptions.content)
+	};
+	return normalizedOptions;
+};
+const toRawUploadBody = (payload) => {
+	const data = assetToData(normalizePayloadForRequest(payload));
+	if (data instanceof Response) {
+		if (!data.body) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Response upload data must have a body" });
+		return data.body;
+	}
+	if (data instanceof ArrayBuffer || data instanceof Blob) return data;
+	if ("getReader" in data) return data;
+	return new Blob([toBlobPartBytes(data)]);
+};
+const setOptionalQueryValue = (params, key, value) => {
+	if (value !== void 0 && value !== null) params.set(key, typeof value === "string" ? value : JSON.stringify(value));
+};
+const assertValidUploadMimeType = (mimeType) => {
+	if (isRejectedUploadMimeType(mimeType)) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_MIME_TYPE, {
+		message: getRejectedUploadMimeTypeError(mimeType),
+		details: { mimeType }
+	});
+};
+const isImageMimeType = (mimeType) => mimeType.toLowerCase().startsWith("image/");
+const prepareSubmitAssetOptions = (options) => {
+	if (!("content" in options) && !("url" in options) && !("part" in options)) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Either file content, URL, or multipart part is required" });
+	if (!options.name) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset name is required" });
+	if (!("part" in options) && "isFinal" in options) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: "isFinal is only valid for multipart uploads" });
+	if ("part" in options && options.part.partNumber && options.part.partNumber > 1) throw calmLensError(PUBLIC_ERROR_CODES.USE_UPLOAD_PART);
+	if ("content" in options) {
+		assertValidUploadMimeType(options.content.type);
+		if (!("plainText" in options.content)) {
+			const validation = validateAssetPayload(options.content);
+			if (!validation.ok) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: validation.error });
+		}
+	}
+	if ("part" in options) {
+		assertValidUploadMimeType(options.part.type);
+		const partSizeInBytes = options.part.sizeInBytes ?? getAssetPayloadByteLength(options.part);
+		if (isImageMimeType(options.part.type) && partSizeInBytes !== void 0) {
+			if (partSizeInBytes > MAX_IMAGE_UPLOAD_BYTES) throw calmLensError(PUBLIC_ERROR_CODES.MULTIPART_IMAGE_TOO_LARGE);
+			if (options.part.isFinal && partSizeInBytes < MIN_MULTIPART_IMAGE_UPLOAD_BYTES) throw calmLensError(PUBLIC_ERROR_CODES.MULTIPART_IMAGE_TOO_SMALL);
+		}
+		const validation = validateAssetPayload(options.part, {
+			multipart: true,
+			isFinal: options.part.isFinal
+		});
+		if (!validation.ok) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: validation.error });
+	}
+	return options;
+};
+const appendCdnSelector = (url, options) => {
+	if (options.lens && options.transform) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Specify either a lens or a transform, not both" });
+	if (options.lens) return `${url}/@${encodeURIComponent(options.lens)}`;
+	if (!options.transform) return url;
+	return `${url}/${encodeURI(options.transform.replace(/^\/+/, ""))}`;
+};
+const getEnsureLensCacheKey = (options) => stringifyJsonCanonical({
+	identifier: options.identifier,
+	name: options.name,
+	description: options.description ?? null,
+	type: options.type,
+	active: options.active,
+	transforms: options.transforms ?? null,
+	version: options.version
+});
+const withApiKeyHeader = (init, apiKey) => {
+	const headers = new Headers(init?.headers);
+	headers.set("X-Api-Key", apiKey);
+	return {
+		...init,
+		redirect: "error",
+		headers: Object.fromEntries(headers.entries())
+	};
+};
+const requestSignal = (options, signal) => {
+	const signals = [
+		options.signal,
+		signal,
+		AbortSignal.timeout(options.timeoutMs ?? 12e4)
+	].filter((value) => value != null);
+	return AbortSignal.any(signals);
+};
+const safeFetch = (fetchImpl, options) => (async (input, init) => {
+	const signal = requestSignal(options, init?.signal ?? (input instanceof Request ? input.signal : void 0));
+	try {
+		signal.throwIfAborted();
+		return await fetchImpl(input, {
+			...init,
+			redirect: "error",
+			signal
+		});
+	} catch (cause) {
+		throw calmLensError({ id: signal.aborted ? signal.reason?.name === "TimeoutError" ? "sdk/timeout" : "sdk/cancelled" : "sdk/transport-error" }, {
+			message: signal.aborted ? "Request aborted" : "Request failed",
+			cause
+		});
+	}
+});
+const createApi = (options) => {
+	return new api_def.Api({
+		name: "Calm Lens",
+		baseUrl: options.baseUrl,
+		middleware: [
+			(0, api_def.RequestCoalescingMiddleware)(),
+			{ beforeSend: (context) => {
+				context.updateHeaders({ "X-Api-Key": options.apiKey });
+			} },
+			{ [api_def.RequestEvent.ERROR]: (context) => {
+				if (context.error) throw normalizeApiError(context.error);
+			} }
+		],
+		requestBackend: options.requestBackend ? Object.assign(Object.create(options.requestBackend), "fetch" in options.requestBackend && typeof options.requestBackend.fetch === "function" ? { fetch: safeFetch(options.requestBackend.fetch, options) } : {}) : new api_def.FetchRequestBackend(safeFetch(globalThis.fetch, options))
+	});
+};
+const isApiErrorPayload = (value) => {
+	return !!value && typeof value === "object" && typeof value.code === "string";
+};
+const normalizeApiError = (error) => {
+	let cause = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (cause instanceof Error && !seen.has(cause)) {
+		seen.add(cause);
+		if (cause instanceof CalmLensError) return cause;
+		if (cause.name === "AbortError" || cause.name === "TimeoutError") return calmLensError({ id: cause.name === "TimeoutError" ? "sdk/timeout" : "sdk/cancelled" }, {
+			message: "Request aborted",
+			cause
+		});
+		cause = cause.cause;
+	}
+	const response = error instanceof Error ? (0, api_def.getErrorResponse)(error) : void 0;
+	if (error instanceof Error && (0, api_def.isRequestError)(error) && isApiErrorPayload(response?.data)) {
+		const { code, message, details, traceId } = response.data;
+		return calmLensError({
+			id: code,
+			defaultMessage: message
+		}, {
+			message,
+			status: response?.status,
+			cause: error,
+			details: {
+				...details,
+				traceId,
+				network: true
+			}
+		});
+	}
+	if (error instanceof CalmLensError) return error;
+	return calmLensError({ id: response ? response.ok ? "sdk/invalid-response" : "sdk/http-error" : "sdk/transport-error" }, {
+		message: response ? `HTTP ${response.status}` : error.message,
+		status: response?.status,
+		cause: error
+	});
+};
+const createEndpoints = (api) => {
+	const getFolders = api.endpoint().paramsOf().responseOf().build({
+		id: "getFolders",
+		method: "get",
+		path: "/projects/:projectId/folders"
+	});
+	const getFolder = api.endpoint().paramsOf().responseOf().build({
+		id: "getFolder",
+		method: "get",
+		path: "/folders/:folderId"
+	});
+	const postFolder = api.endpoint().paramsOf().bodyOf().responseOf().build({
+		id: "postFolder",
+		method: "post",
+		path: "/projects/:projectId/folders"
+	});
+	const patchFolder = api.endpoint().paramsOf().bodyOf().responseOf().build({
+		id: "patchFolder",
+		method: "patch",
+		path: "/folders/:folderId"
+	});
+	const deleteFolder = api.endpoint().paramsOf().responseOf().build({
+		id: "deleteFolder",
+		method: "delete",
+		path: "/folders/:folderId"
+	});
+	const moveFolder = api.endpoint().paramsOf().bodyOf().responseOf().build({
+		id: "moveFolder",
+		method: "post",
+		path: "/folders/:folderId/move"
+	});
+	const getAssetsPage = api.endpoint().queryOf().paramsOf().responseOf().build({
+		id: "getAssetsPage",
+		method: "get",
+		path: "/projects/:projectId/assets/page"
+	});
+	const getAsset = api.endpoint().paramsOf().responseOf().build({
+		id: "getAsset",
+		method: "get",
+		path: "/assets/:assetId"
+	});
+	const getAssetChildren = api.endpoint().paramsOf().queryOf().responseOf().build({
+		id: "getAssetChildren",
+		method: "get",
+		path: "/assets/:assetId/children"
+	});
+	const patchAsset = api.endpoint().paramsOf().bodyOf().responseOf().build({
+		id: "patchAsset",
+		method: "patch",
+		path: "/assets/:assetId"
+	});
+	const postUploadAsset = api.endpoint().bodyOf({ encoding: "multipart/form-data" }).paramsOf().queryOf().responseOf().build({
+		id: "postUploadAsset",
+		method: "post",
+		path: "/projects/:projectId/assets"
+	});
+	const postAssetSignedUrl = api.endpoint().bodyOf().paramsOf().responseOf().build({
+		id: "postAssetSignedUrl",
+		method: "post",
+		path: "/assets/:assetId/signed-url"
+	});
+	const postAssetPart = api.endpoint().bodyOf({ encoding: "multipart/form-data" }).paramsOf().queryOf().responseOf().build({
+		id: "postAssetPart",
+		method: "post",
+		path: "/assets/:assetId/part"
+	});
+	const moveAsset = api.endpoint().paramsOf().bodyOf().responseOf().build({
+		id: "moveAsset",
+		method: "post",
+		path: "/assets/:assetId/move"
+	});
+	const retryAsset = api.endpoint().paramsOf().responseOf().build({
+		id: "retryAsset",
+		method: "post",
+		path: "/assets/:assetId/retry"
+	});
+	const getEvents = api.endpoint().paramsOf().queryOf().responseOf().build({
+		id: "getEvents",
+		method: "get",
+		path: "/projects/:projectId/events"
+	});
+	return {
+		getFolders,
+		getFolder,
+		postFolder,
+		patchFolder,
+		deleteFolder,
+		moveFolder,
+		getAssetsPage,
+		getAsset,
+		getAssetChildren,
+		patchAsset,
+		postUploadAsset,
+		postAssetSignedUrl,
+		postAssetPart,
+		moveAsset,
+		retryAsset,
+		ensureLens: api.endpoint().bodyOf().paramsOf().responseOf().build({
+			id: "ensureLens",
+			method: "put",
+			path: "/lenses/:lensIdentifier"
+		}),
+		ensureLenses: api.endpoint().bodyOf().paramsOf().responseOf().build({
+			id: "ensureLenses",
+			method: "put",
+			path: "/projects/:projectId/lenses"
+		}),
+		getEvents
+	};
+};
+var CalmLensClient = class CalmLensClient {
+	/**
+	* Verifies that a webhook delivery came from CalmLens: checks the `v1=` HMAC-SHA256 in
+	* `x-calmlens-signature` over `"<x-calmlens-timestamp>.<raw body>"` and rejects timestamps
+	* more than `toleranceSeconds` (default 300) from now, which stops replayed deliveries.
+	*
+	* @param options.payload - The raw request body, exactly as received (verify before parsing)
+	* @param options.signature - The 'x-calmlens-signature' header value
+	* @param options.timestamp - The 'x-calmlens-timestamp' header value
+	* @param options.secret - The connector's signing secret
+	* @param options.toleranceSeconds - Allowed clock distance in seconds (default 300)
+	* @param options.now - Override the current time (Date or epoch milliseconds), for tests
+	* @returns Promise<boolean> - True if the signature is valid and fresh, false otherwise
+	*
+	* @example
+	* ```javascript
+	* // In your webhook handler (e.g. a Fetch API Request)
+	* const payload = await request.text();
+	* const isValid = await CalmLensClient.verifyWebhookSignature({
+	*   payload,
+	*   signature: request.headers.get('x-calmlens-signature'),
+	*   timestamp: request.headers.get('x-calmlens-timestamp'),
+	*   secret: WEBHOOK_SECRET,
+	* });
+	*
+	* if (!isValid) {
+	*   return new Response('Unauthorized', { status: 401 });
+	* }
+	* const event = JSON.parse(payload); // { id, type, createdAt, projectId, data }
+	* ```
+	*/
+	static async verifyWebhookSignature(options) {
+		return verifyWebhookSignature(options);
+	}
+	constructor(options) {
+		this.options = options;
+		this.ensuredLenses = /* @__PURE__ */ new Map();
+		this.pendingEnsureLenses = /* @__PURE__ */ new Map();
+		this.multipartImageUploadSizes = /* @__PURE__ */ new Map();
+		this.multipartUploadQueues = /* @__PURE__ */ new Map();
+		if (!options.apiKey) throw calmLensError({ id: "upload/invalid-payload" }, { message: "API key is required" });
+		if (!options.projectId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Project ID is required" });
+		if (options.timeoutMs !== void 0 && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) throw calmLensError({ id: "upload/invalid-payload" }, { message: "timeoutMs must be a positive integer" });
+		this.options = { ...options };
+		this.options.baseUrl = this.options.baseUrl ?? `https://api.calmlens.com/v1`;
+		this.options.cdnBaseUrl = this.options.cdnBaseUrl ?? `https://cdn.calmlens.com/v1`;
+		this.api = createApi(this.options);
+		this.endpoints = createEndpoints(this.api);
+	}
+	/** Scope cancellation/timeout to an operation without changing this client's defaults. */
+	withRequestOptions(options) {
+		const client = new CalmLensClient({
+			...this.options,
+			...options
+		});
+		client.multipartUploadQueues = this.multipartUploadQueues;
+		client.multipartImageUploadSizes = this.multipartImageUploadSizes;
+		return client;
+	}
+	getUploadFetch() {
+		const requestBackendFetch = this.options.requestBackend?.fetch;
+		const fetchImpl = this.options.uploadFetch ?? requestBackendFetch ?? globalThis.fetch;
+		if (!fetchImpl) throw calmLensError(SDK_ERRORS.NO_CDN_FETCH);
+		return safeFetch(fetchImpl, this.options);
+	}
+	async submitRawAssetUpload(options, queue) {
+		const query = new URLSearchParams();
+		query.set("name", options.name);
+		query.set("queue", String(queue));
+		setOptionalQueryValue(query, "description", options.description);
+		setOptionalQueryValue(query, "processingOptions", options.processingOptions);
+		setOptionalQueryValue(query, "visibility", options.visibility);
+		setOptionalQueryValue(query, "metadata", options.metadata);
+		setOptionalQueryValue(query, "externalId", options.externalId);
+		setOptionalQueryValue(query, "externalUrl", options.externalUrl);
+		setOptionalQueryValue(query, "folderId", options.folderId);
+		const isMultipart = "part" in options;
+		const payload = isMultipart ? options.part : options.content;
+		query.set("contentType", payload.type);
+		setOptionalQueryValue(query, "sizeInBytes", payload.sizeInBytes ?? getAssetPayloadByteLength(payload));
+		if (isMultipart) {
+			const part = payload;
+			const multipartOptions = options;
+			query.set("partNumber", String(part.partNumber ?? 1));
+			query.set("isFinal", String(part.isFinal ?? false));
+			setOptionalQueryValue(query, "sizeInBytes", part.sizeInBytes ?? multipartOptions.sizeInBytes);
+		}
+		const baseUrl = this.options.baseUrl.replace(/\/$/, "");
+		const path = isMultipart ? "assets/multipart-upload" : "assets/upload";
+		const url = `${baseUrl}/projects/${encodeURIComponent(this.options.projectId)}/${path}?${query}`;
+		const response = await this.getUploadFetch()(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": payload.type,
+				"X-Api-Key": this.options.apiKey,
+				"X-CalmLens-Upload": isMultipart ? "part" : "content"
+			},
+			body: toRawUploadBody(payload),
+			duplex: "half"
+		});
+		const asset = await this.parseRawUploadResponse(response);
+		if (isMultipart && asset.status === "uploading") {
+			this.multipartUploadQueues.set(asset.id, queue);
+			if (isImageMimeType(payload.type)) this.multipartImageUploadSizes.set(asset.id, asset.sizeInBytes ?? 0);
+		}
+		return asset;
+	}
+	async submitRawAssetPart(assetId, part, queue) {
+		const query = new URLSearchParams({
+			queue: String(queue),
+			partNumber: String(part.partNumber),
+			isFinal: String(part.isFinal ?? false)
+		});
+		setOptionalQueryValue(query, "sizeInBytes", part.sizeInBytes ?? getAssetPayloadByteLength(part));
+		const url = `${this.options.baseUrl.replace(/\/$/, "")}/assets/${encodeURIComponent(assetId)}/part?${query}`;
+		const response = await this.getUploadFetch()(url, {
+			method: "POST",
+			headers: {
+				"X-Api-Key": this.options.apiKey,
+				"X-CalmLens-Upload": "part"
+			},
+			body: toRawUploadBody(part),
+			duplex: "half"
+		});
+		const asset = await this.parseRawUploadResponse(response);
+		if (asset.status === "uploading") this.multipartImageUploadSizes.set(asset.id, asset.sizeInBytes ?? 0);
+		else {
+			this.multipartImageUploadSizes.delete(assetId);
+			this.multipartUploadQueues.delete(assetId);
+		}
+		return asset;
+	}
+	async parseRawUploadResponse(response) {
+		let data;
+		try {
+			data = await response.json();
+		} catch (cause) {
+			throw calmLensError({ id: cause instanceof Error && ["TimeoutError", "AbortError"].includes(cause.name) ? cause.name === "TimeoutError" ? "sdk/timeout" : "sdk/cancelled" : response.ok ? "sdk/invalid-response" : "sdk/http-error" }, {
+				message: `Invalid JSON response (HTTP ${response.status})`,
+				status: response.status,
+				cause
+			});
+		}
+		if (!response.ok) {
+			if (isApiErrorPayload(data)) throw calmLensError({
+				id: data.code,
+				defaultMessage: data.message
+			}, {
+				message: data.message,
+				status: response.status,
+				details: {
+					...data.details,
+					traceId: data.traceId,
+					network: true
+				}
+			});
+			throw calmLensError({ id: "sdk/http-error" }, {
+				message: `HTTP ${response.status}`,
+				status: response.status
+			});
+		}
+		if (!data || typeof data !== "object" || !("id" in data) || typeof data.id !== "string" || !data.id || !("status" in data) || ![
+			"uploading",
+			"pending",
+			"approved",
+			"rejected",
+			"error"
+		].includes(String(data.status))) throw calmLensError({ id: "sdk/invalid-response" }, {
+			message: "Expected an asset response",
+			status: response.status
+		});
+		return data;
+	}
+	get cdn() {
+		return {
+			/**
+			* Create a CDN URL for asset content or previews.
+			* Private assets require an authenticated request or signed URL.
+			*/
+			getAssetUrl: ({ assetIdentifier, ...options }) => {
+				if (!assetIdentifier) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset identifier is required" });
+				const resource = options.resource ?? "content";
+				const url = `${this.options.cdnBaseUrl.replace(/\/$/, "")}/assets/${encodeURIComponent(this.options.projectId)}/${encodeURIComponent(assetIdentifier)}/${resource}`;
+				return appendCdnSelector(url, options);
+			},
+			/**
+			* Fetch asset content or previews from the CDN.
+			* Private assets are authenticated with the client's API key.
+			*/
+			serve: async ({ assetIdentifier, init, ...urlOptions }) => {
+				const fetchImpl = this.options.cdnFetch ?? globalThis.fetch;
+				if (!fetchImpl) throw calmLensError(SDK_ERRORS.NO_CDN_FETCH);
+				return safeFetch(fetchImpl, this.options)(this.cdn.getAssetUrl({
+					assetIdentifier,
+					...urlOptions
+				}), withApiKeyHeader(init, this.options.apiKey));
+			}
+		};
+	}
+	get text() {
+		return { moderate: async (options) => this.assets.moderate(toTextAssetOptions(options)) };
+	}
+	get assets() {
+		return {
+			/**
+			* List all assets for a project
+			* @param options - Pagination and filtering options
+			* @returns Promise with paginated assets
+			*/
+			list: async (options) => {
+				return (await this.endpoints.getAssetsPage.submit({
+					params: { projectId: this.options.projectId },
+					query: {
+						...options,
+						pageIndex: options.pageIndex ?? 0
+					}
+				})).data;
+			},
+			/**
+			* Retrieve a specific asset by ID
+			* @param assetId - The asset ID
+			* @returns Promise with asset data
+			*/
+			retrieve: async ({ assetId }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				return (await this.endpoints.getAsset.submit({ params: { assetId } })).data;
+			},
+			update: async ({ assetId, ...body }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				return (await this.endpoints.patchAsset.submit({
+					params: { assetId },
+					body
+				})).data;
+			},
+			/**
+			* Get child assets of a parent asset
+			* @param assetId - The parent asset ID
+			* @param options - Pagination options
+			* @returns Promise with paginated child assets
+			*/
+			listChildren: async ({ assetId, ...options }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				return (await this.endpoints.getAssetChildren.submit({
+					params: { assetId },
+					query: {
+						...options,
+						pageIndex: options.pageIndex ?? 0
+					}
+				})).data;
+			},
+			/**
+			* Submit a new asset for processing (queued asynchronously)
+			* The asset will be queued for classification and returned immediately.
+			* @param options - Asset submission options
+			* @returns Promise with created asset
+			*/
+			create: async (options) => {
+				const body = prepareSubmitAssetOptions(options);
+				if ("content" in body || "part" in body) return await this.submitRawAssetUpload(body, true);
+				return (await this.endpoints.postUploadAsset.submit({
+					body: normalizeAssetOptionsForRequest(body),
+					params: { projectId: this.options.projectId },
+					query: { queue: true }
+				})).data;
+			},
+			/**
+			* Submit a new asset and moderate it synchronously
+			* The asset will be classified immediately before the response is returned.
+			* This may take longer but ensures the asset is fully processed.
+			* @param options - Asset submission options
+			* @returns Promise with created and analyzed asset
+			*/
+			moderate: async (options) => {
+				if ("content" in options && "plainText" in options.content && (typeof options.content.plainText !== "string" || !options.content.plainText.trim())) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: "Text to moderate must be a non-empty string" });
+				const body = prepareSubmitAssetOptions(options);
+				if ("content" in body || "part" in body) return await this.submitRawAssetUpload(body, false);
+				return (await this.endpoints.postUploadAsset.submit({
+					body: normalizeAssetOptionsForRequest(body),
+					params: { projectId: this.options.projectId },
+					query: { queue: false }
+				})).data;
+			},
+			/**
+			* Upload a part for a multipart upload
+			* @param assetId - The asset ID
+			* @param part - The part to upload
+			* @returns Promise with asset data
+			*/
+			uploadPart: async ({ assetId, part }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				if (!part) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Part options are required" });
+				const validation = validateAssetPayload(part, {
+					multipart: true,
+					isFinal: part.isFinal
+				});
+				if (!validation.ok) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: validation.error });
+				const existingImageSizeInBytes = this.multipartImageUploadSizes.get(assetId);
+				const partSizeInBytes = part.sizeInBytes ?? getAssetPayloadByteLength(part);
+				if (existingImageSizeInBytes !== void 0 && partSizeInBytes !== void 0) {
+					const totalSizeInBytes = existingImageSizeInBytes + partSizeInBytes;
+					if (totalSizeInBytes > MAX_IMAGE_UPLOAD_BYTES) throw calmLensError(PUBLIC_ERROR_CODES.MULTIPART_IMAGE_TOO_LARGE);
+					if (part.isFinal && totalSizeInBytes < MIN_MULTIPART_IMAGE_UPLOAD_BYTES) throw calmLensError(PUBLIC_ERROR_CODES.MULTIPART_IMAGE_TOO_SMALL);
+				}
+				return await this.submitRawAssetPart(assetId, part, this.multipartUploadQueues.get(assetId) ?? false);
+			},
+			/**
+			* Create a short-lived signed CDN URL for an asset.
+			* This is useful for private assets where clients should not send app
+			* auth cookies or API keys to the CDN on every media request.
+			*/
+			createSignedUrl: async ({ assetId, ...options }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				if (options.lens && options.transform) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Specify either a lens or a transform, not both" });
+				return (await this.endpoints.postAssetSignedUrl.submit({
+					body: {
+						resource: options.resource ?? "content",
+						expiresInSeconds: options.expiresInSeconds ?? 900,
+						lens: options.lens,
+						transform: options.transform
+					},
+					params: { assetId }
+				})).data;
+			},
+			move: async ({ assetId, folderId }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				return (await this.endpoints.moveAsset.submit({
+					params: { assetId },
+					body: { folderId }
+				})).data;
+			},
+			/**
+			* Processes an asset that failed (status `error`) again. It returns to `pending` and is
+			* moderated like a new upload; its content must still be stored.
+			*/
+			retry: async ({ assetId }) => {
+				if (!assetId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Asset ID is required" });
+				return (await this.endpoints.retryAsset.submit({ params: { assetId } })).data;
+			}
+		};
+	}
+	get events() {
+		return { 
+		/**
+		* List project events after a cursor, oldest first. Call without `after` to get a cursor
+		* for "now", then poll with the returned `cursor`. Webhook deliveries carry the same events
+		* reshaped as `{ id, type, createdAt, projectId, data }`.
+		*/
+list: async (options = {}) => {
+			return (await this.endpoints.getEvents.submit({
+				params: { projectId: this.options.projectId },
+				query: options
+			})).data;
+		} };
+	}
+	get folders() {
+		return {
+			list: async () => {
+				return (await this.endpoints.getFolders.submit({ params: { projectId: this.options.projectId } })).data.folders;
+			},
+			retrieve: async ({ folderId }) => {
+				if (!folderId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Folder ID is required" });
+				return (await this.endpoints.getFolder.submit({ params: { folderId } })).data;
+			},
+			create: async (options) => {
+				return (await this.endpoints.postFolder.submit({
+					params: { projectId: this.options.projectId },
+					body: options
+				})).data;
+			},
+			update: async ({ folderId, ...body }) => {
+				if (!folderId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Folder ID is required" });
+				return (await this.endpoints.patchFolder.submit({
+					params: { folderId },
+					body
+				})).data;
+			},
+			delete: async ({ folderId }) => {
+				if (!folderId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Folder ID is required" });
+				await this.endpoints.deleteFolder.submit({ params: { folderId } });
+			},
+			move: async ({ folderId, parentId }) => {
+				if (!folderId) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Folder ID is required" });
+				return (await this.endpoints.moveFolder.submit({
+					params: { folderId },
+					body: { parentId }
+				})).data;
+			}
+		};
+	}
+	/**
+	* Create a named lens at any positive version, or update it with a greater version.
+	* Supplying the same definition and version is idempotent.
+	*/
+	async ensureLens(options) {
+		if (!options.identifier) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Lens identifier is required" });
+		const [lens] = await this.ensureLenses({ lenses: [options] });
+		return lens;
+	}
+	/**
+	* Create or update several named lenses in one API request.
+	* Each lens follows the same versioning and idempotency rules as ensureLens().
+	*/
+	async ensureLenses({ lenses }) {
+		if (lenses.length === 0) throw calmLensError({ id: "upload/invalid-payload" }, { message: "At least one lens is required" });
+		if (lenses.some((option) => !option.identifier)) throw calmLensError({ id: "upload/invalid-payload" }, { message: "Lens identifier is required" });
+		const missingOptions = [];
+		const missingKeys = /* @__PURE__ */ new Set();
+		for (const option of lenses) {
+			const cacheKey = getEnsureLensCacheKey(option);
+			if (!this.ensuredLenses.has(cacheKey) && !missingKeys.has(cacheKey)) {
+				missingKeys.add(cacheKey);
+				missingOptions.push(option);
+			}
+		}
+		if (missingOptions.length === 0) return lenses.map((option) => this.ensuredLenses.get(getEnsureLensCacheKey(option)));
+		const batchCacheKey = JSON.stringify([...missingKeys].sort());
+		let pending = this.pendingEnsureLenses.get(batchCacheKey);
+		if (!pending) {
+			pending = this.submitEnsureLenses(missingOptions);
+			this.pendingEnsureLenses.set(batchCacheKey, pending);
+			pending.then(() => this.pendingEnsureLenses.delete(batchCacheKey), () => this.pendingEnsureLenses.delete(batchCacheKey));
+		}
+		await pending;
+		return lenses.map((option) => this.ensuredLenses.get(getEnsureLensCacheKey(option)));
+	}
+	async submitEnsureLenses(options) {
+		const result = await this.endpoints.ensureLenses.submit({
+			body: { lenses: options },
+			params: { projectId: this.options.projectId }
+		});
+		for (const [index, lens] of result.data.lenses.entries()) {
+			const optionsForLens = options[index];
+			if (!optionsForLens) throw calmLensError({ id: "sdk/invalid-response" }, { message: "CalmLens returned an unexpected lens response" });
+			for (const [cacheKey, cachedLens] of this.ensuredLenses) if (cachedLens.identifier === optionsForLens.identifier) this.ensuredLenses.delete(cacheKey);
+			this.ensuredLenses.set(getEnsureLensCacheKey(optionsForLens), lens);
+		}
+	}
+};
+//#endregion
+//#region src/cli/listen.ts
+const FORWARD_TIMEOUT_MS = 1e4;
+const MAX_BACKOFF_MS = 3e4;
+/** Fatal errors stop the CLI instead of retrying: they need the user to change something. */
+const FATAL_ERROR_CODES = new Set([
+	PUBLIC_ERROR_CODES.MISSING_TOKEN,
+	PUBLIC_ERROR_CODES.INVALID_API_KEY,
+	PUBLIC_ERROR_CODES.API_KEY_PROJECT_MISMATCH,
+	PUBLIC_ERROR_CODES.PROJECT_NOT_FOUND
+].map((code) => code.getId()));
+const createLocalSigningSecret = () => `whsec_local_${(0, node_crypto.randomBytes)(24).toString("hex")}`;
+const forwardEvent = async (event, options) => {
+	const body = JSON.stringify(toWebhookEventPayload(event));
+	const startedAt = Date.now();
+	try {
+		const headers = await createWebhookHeaders({
+			secret: options.secret,
+			body,
+			deliveryId: `cli_${(0, node_crypto.randomUUID)()}`
+		});
+		const response = await (options.fetchImpl ?? fetch)(options.forwardTo, {
+			method: "POST",
+			headers,
+			body,
+			signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS)
+		});
+		return {
+			ok: response.ok,
+			status: response.status,
+			durationMs: Date.now() - startedAt
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error.cause?.code ?? (error instanceof Error ? error.message : String(error)),
+			durationMs: Date.now() - startedAt
+		};
+	}
+};
+const formatTime = (date) => date.toTimeString().slice(0, 8);
+const formatForwardLine = (event, result, now = /* @__PURE__ */ new Date()) => {
+	const outcome = result.status ? `${result.status}${result.ok ? "" : " (handler returned an error)"}` : `failed: ${result.error}${result.error === "ECONNREFUSED" ? " (is your server running?)" : ""}`;
+	return `${formatTime(now)}  ${event.type.padEnd(16)}  ${event.id}  → ${outcome} [${result.durationMs}ms]`;
+};
+const sleep = (ms, signal) => new Promise((resolve) => {
+	if (signal?.aborted) return resolve();
+	const timer = setTimeout(resolve, ms);
+	signal?.addEventListener("abort", () => {
+		clearTimeout(timer);
+		resolve();
+	}, { once: true });
+});
+/**
+* Forwards new events until `signal` aborts. Resolves normally on abort; rejects with the
+* underlying error for fatal API errors (bad key, wrong project).
+*/
+const listen = async (options) => {
+	const { client, signal } = options;
+	const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+	const intervalMs = options.intervalMs ?? 2e3;
+	const eventTypes = new Set(options.eventTypes ?? []);
+	let { cursor } = await client.events.list({});
+	options.onReady?.();
+	let failures = 0;
+	while (!signal?.aborted) try {
+		const page = await client.events.list({
+			after: cursor,
+			limit: 100
+		});
+		if (failures > 0) log(`${formatTime(/* @__PURE__ */ new Date())}  Reconnected to CalmLens.`);
+		failures = 0;
+		for (const event of page.events) {
+			if (eventTypes.size > 0 && !eventTypes.has(event.type)) continue;
+			log(formatForwardLine(event, await forwardEvent(event, options)));
+		}
+		cursor = page.cursor;
+		if (!page.hasMore) await sleep(intervalMs, signal);
+	} catch (error) {
+		if (error instanceof CalmLensError && FATAL_ERROR_CODES.has(error.code)) throw error;
+		failures++;
+		const backoffMs = Math.min(MAX_BACKOFF_MS, intervalMs * 2 ** failures);
+		if (failures === 1) {
+			const message = error instanceof Error ? error.message : String(error);
+			log(`${formatTime(/* @__PURE__ */ new Date())}  Couldn't reach CalmLens (${message}). Retrying…`);
+		}
+		await sleep(backoffMs, signal);
+	}
+};
+//#endregion
+//#region src/cli/index.ts
+const HELP = `CalmLens CLI
+
+Usage:
+  calmlens listen --forward-to <url> [options]
+  calmlens trigger [harassment|hate|criminal-activity|clean] [options]
+
+Run it with \`npx calmlens\`, or install it with \`npm install -g calmlens\`.
+
+Commands:
+  listen    Forward your project's events to a local webhook handler with the same body
+            ({ id, type, createdAt, projectId, data }) and headers (x-calmlens-timestamp,
+            x-calmlens-signature: v1=...) as real deliveries. No public URL needed.
+  trigger   Moderate a harmless test comment so CalmLens creates real events. Each trigger
+            counts as one upload.
+
+Options:
+  --forward-to <url>     Local webhook URL, e.g. http://localhost:3000/api/webhooks/calmlens
+  --events <types>       Comma-separated event types to forward (default: all)
+  --secret <secret>      Signing secret (default: $CALMLENS_WEBHOOK_SECRET, or a generated one)
+  --api-key <key>        Project API key (default: $CALMLENS_API_KEY)
+  --project-id <id>      Project ID (default: $CALMLENS_PROJECT_ID)
+  --env-file <path>      Load environment variables from a file, e.g. .env.local
+  --interval <seconds>   Seconds between checks for new events (default: 2)
+  --api-url <url>        API base URL (default: $CALMLENS_API_URL or https://api.calmlens.com/v1)
+  -h, --help             Show this help
+`;
+const TRIGGER_KINDS = [
+	"harassment",
+	"hate",
+	"criminal-activity",
+	"clean"
+];
+const fail = (message) => {
+	process.stderr.write(`${message}\n`);
+	process.exit(1);
+};
+const describeError = (error) => {
+	if (error instanceof CalmLensError) return `${error.message.replace(/^\[calmlens\] /, "")} (${error.code})`;
+	return error instanceof Error ? error.message : String(error);
+};
+const main = async () => {
+	const { values, positionals } = (0, node_util.parseArgs)({
+		allowPositionals: true,
+		options: {
+			"forward-to": { type: "string" },
+			events: { type: "string" },
+			secret: { type: "string" },
+			"api-key": { type: "string" },
+			"project-id": { type: "string" },
+			"env-file": { type: "string" },
+			interval: { type: "string" },
+			"api-url": { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	const [command, argument] = positionals;
+	if (values.help || !command || command === "help") {
+		process.stdout.write(HELP);
+		return;
+	}
+	if (values["env-file"]) try {
+		process.loadEnvFile(values["env-file"]);
+	} catch {
+		fail(`Couldn't read ${values["env-file"]}.`);
+	}
+	const apiKey = values["api-key"] ?? process.env.CALMLENS_API_KEY;
+	const projectId = values["project-id"] ?? process.env.CALMLENS_PROJECT_ID;
+	if (!apiKey || !projectId) fail("Set CALMLENS_API_KEY and CALMLENS_PROJECT_ID (or pass --api-key and --project-id).\nBoth are on the Developer → API Keys page of the CalmLens portal.");
+	const baseUrl = values["api-url"] ?? process.env.CALMLENS_API_URL;
+	const client = new CalmLensClient({
+		apiKey,
+		projectId,
+		...baseUrl ? { baseUrl } : {}
+	});
+	if (command === "listen") {
+		const forwardTo = values["forward-to"];
+		if (!forwardTo) fail("listen needs --forward-to <url>, e.g. http://localhost:3000/api/webhooks/calmlens");
+		const intervalSeconds = Number(values.interval ?? 2);
+		if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1) fail("--interval must be at least 1 second.");
+		const configuredSecret = values.secret ?? process.env.CALMLENS_WEBHOOK_SECRET;
+		const secret = configuredSecret ?? createLocalSigningSecret();
+		const eventTypes = values.events?.split(",").map((type) => type.trim()).filter(Boolean);
+		const controller = new AbortController();
+		process.once("SIGINT", () => controller.abort());
+		process.once("SIGTERM", () => controller.abort());
+		try {
+			await listen({
+				client,
+				forwardTo,
+				secret,
+				eventTypes,
+				intervalMs: intervalSeconds * 1e3,
+				signal: controller.signal,
+				onReady: () => {
+					process.stdout.write([
+						`Forwarding CalmLens events for project ${projectId} to ${forwardTo}`,
+						configuredSecret ? "Signing with your CALMLENS_WEBHOOK_SECRET." : `Signing secret: ${secret}\n  Set CALMLENS_WEBHOOK_SECRET to this value in your app, or pass --secret.`,
+						eventTypes?.length ? `Event types: ${eventTypes.join(", ")}` : "Event types: all",
+						"Upload something (or run `npx calmlens trigger`) to see events. Press Ctrl+C to stop.",
+						""
+					].join("\n"));
+				}
+			});
+		} catch (error) {
+			fail(error instanceof CalmLensError ? `CalmLens rejected the request: ${describeError(error)}` : `Couldn't reach CalmLens: ${describeError(error)}`);
+		}
+		return;
+	}
+	if (command === "trigger") {
+		const kind = argument ?? "harassment";
+		if (!TRIGGER_KINDS.includes(kind)) fail(`Unknown trigger "${kind}". Use one of: ${TRIGGER_KINDS.join(", ")}.`);
+		const text = kind === "clean" ? "Hello from the CalmLens CLI" : `<!calmlens-test ${projectId.slice(-8)} ${kind}>`;
+		try {
+			const asset = await client.assets.moderate({
+				name: `cli-trigger-${kind}`,
+				content: {
+					plainText: text,
+					type: "text/plain"
+				}
+			});
+			process.stdout.write(`Created asset ${asset.id}: status ${asset.status}${asset.report?.flagged ? ", flagged" : ""}.\n`);
+		} catch (error) {
+			fail(`Trigger failed: ${describeError(error)}`);
+		}
+		return;
+	}
+	fail(`Unknown command "${command}".\n\n${HELP}`);
+};
+main().catch((error) => fail(describeError(error)));
+//#endregion