@calmlens/sdk 0.9.0 → 0.10.0

package/cjs/CalmLensWebhooks-DJnaLpRy.js

@@ -0,0 +1,741 @@
+//#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 isReadableStream = (value) => typeof value === "object" && value !== null && "getReader" in value && typeof value.getReader === "function";
+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 assetDataToUint8Array = async (data) => {
+	if (data instanceof Response) return new Uint8Array(await data.arrayBuffer());
+	if (isReadableStream(data)) return new Uint8Array(await new Response(data).arrayBuffer());
+	if (data instanceof Blob) return new Uint8Array(await data.arrayBuffer());
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	return data;
+};
+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]]));
+});
+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.`;
+const DOMAIN = "calmlens.com";
+//#endregion
+//#region src/client/CalmLensErrorCodes.ts
+/** Error codes the CalmLens API documents, by name. */
+const API_ERROR_CODES = {
+	MISSING_TOKEN: "auth/missing-token",
+	INVALID_API_KEY: "auth/invalid-api-key",
+	API_KEY_PROJECT_MISMATCH: "auth/project-mismatch",
+	API_KEY_NOT_ACCEPTED: "auth/api-key-not-accepted",
+	FILE_TOO_LARGE: "upload/file-too-large",
+	IMAGE_REQUIRES_MULTIPART_UPLOAD: "upload/image-requires-multipart-upload",
+	MULTIPART_IMAGE_TOO_SMALL: "upload/multipart-image-too-small",
+	MULTIPART_IMAGE_TOO_LARGE: "upload/multipart-image-too-large",
+	IMAGE_EXCEEDED_MAX_DIMENSIONS: "upload/image-exceeded-max-dimensions",
+	UPLOAD_LIMIT_EXCEEDED: "upload/limit-exceeded",
+	INVALID_UPLOAD_MIME_TYPE: "upload/invalid-mime-type",
+	INVALID_EVENT_CURSOR: "events/invalid-cursor",
+	INVALID_UPLOAD_PAYLOAD: "upload/invalid-payload",
+	USE_UPLOAD_PART: "upload/use-upload-part",
+	UPLOAD_NOT_OPEN: "upload/not-open",
+	INVALID_UPLOAD_PART_NUMBER: "upload/invalid-part-number",
+	UPLOAD_MISSING: "upload/missing",
+	UPLOAD_SIZE_MISMATCH: "upload/size-mismatch",
+	INVALID_IDEMPOTENCY_KEY: "idempotency/invalid-key",
+	IDEMPOTENCY_KEY_REUSED: "idempotency/key-reused",
+	IDEMPOTENT_REQUEST_IN_PROGRESS: "idempotency/request-in-progress",
+	ASSET_NOT_FOUND: "asset/not-found",
+	PROJECT_NOT_FOUND: "project/not-found",
+	ASSET_UPDATE_FAILED: "asset/update-failed",
+	ASSET_SAFETY_HELD: "asset/safety-held",
+	ASSET_NOT_RETRYABLE: "asset/not-retryable",
+	ASSET_CONTENT_UNAVAILABLE: "asset/content-unavailable",
+	SUPPORT_TICKET_NOT_FOUND: "support/ticket-not-found",
+	DUPLICATE_EXTERNAL_ID: "asset/duplicate-external-id",
+	FOLDER_NOT_FOUND: "folder/not-found",
+	DUPLICATE_FOLDER_NAME: "folder/duplicate-name",
+	FOLDER_NOT_EMPTY: "folder/not-empty",
+	FOLDER_PARENT_CYCLE: "folder/parent-cycle",
+	LENS_VERSION_CONFLICT: "lens/version-conflict"
+};
+/** The HTTP status and default message the API returns with each documented error code. */
+const API_ERROR_DEFINITIONS = {
+	"auth/missing-token": {
+		status: 401,
+		message: "Authentication required. Send your project API key in the X-Api-Key header."
+	},
+	"auth/invalid-api-key": {
+		status: 401,
+		message: "The API key is invalid, revoked or expired. Create a key under Developer → API Keys."
+	},
+	"auth/project-mismatch": {
+		status: 403,
+		message: "This API key belongs to a different project. Use a key created for the project that owns this resource."
+	},
+	"auth/api-key-not-accepted": {
+		status: 403,
+		message: "API keys are only accepted by the public API at /v1."
+	},
+	"upload/file-too-large": {
+		status: 400,
+		message: "File size exceeds limit. Maximum direct image size is 10MB, audio/video size is 50MiB, and other files is 5GB."
+	},
+	"upload/image-requires-multipart-upload": {
+		status: 400,
+		message: "Images of 10MB or more must use a multipart upload."
+	},
+	"upload/multipart-image-too-small": {
+		status: 400,
+		message: "Multipart image uploads must total at least 10MB."
+	},
+	"upload/multipart-image-too-large": {
+		status: 400,
+		message: "Multipart image uploads cannot exceed 20MB."
+	},
+	"upload/image-exceeded-max-dimensions": {
+		status: 400,
+		message: "Image exceeds maximum dimensions. Maximum dimensions are 12,000px."
+	},
+	"upload/limit-exceeded": {
+		status: 403,
+		message: "Upload limit exceeded. You have used all your free uploads. Please upgrade to Plus or Pro for unlimited uploads."
+	},
+	"upload/invalid-mime-type": {
+		status: 400,
+		message: "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."
+	},
+	"events/invalid-cursor": {
+		status: 400,
+		message: "The events cursor is invalid. Use the cursor from a previous response, or omit it to start from now."
+	},
+	"upload/invalid-payload": {
+		status: 400,
+		message: "Upload payload is invalid."
+	},
+	"upload/use-upload-part": {
+		status: 409,
+		message: "Use uploadPart for multipart upload parts after the first part"
+	},
+	"upload/not-open": {
+		status: 409,
+		message: "Asset is not accepting additional parts"
+	},
+	"upload/invalid-part-number": {
+		status: 409,
+		message: "Multipart upload part number is invalid."
+	},
+	"upload/missing": {
+		status: 409,
+		message: "Multipart upload state is missing"
+	},
+	"upload/size-mismatch": {
+		status: 400,
+		message: "The uploaded parts do not add up to the totalSizeInBytes declared when the multipart upload started."
+	},
+	"idempotency/invalid-key": {
+		status: 400,
+		message: "The Idempotency-Key header must be 1 to 255 printable ASCII characters, such as a UUID."
+	},
+	"idempotency/key-reused": {
+		status: 409,
+		message: "This Idempotency-Key was already used for a different request. Use a new key for each distinct request."
+	},
+	"idempotency/request-in-progress": {
+		status: 409,
+		message: "A request with this Idempotency-Key is still being processed. Retry after the Retry-After delay to receive its result."
+	},
+	"asset/not-found": {
+		status: 404,
+		message: "Asset not found"
+	},
+	"project/not-found": {
+		status: 404,
+		message: "Project not found"
+	},
+	"asset/update-failed": {
+		status: 500,
+		message: "Failed to update asset"
+	},
+	"asset/safety-held": {
+		status: 423,
+		message: "Asset access is restricted by a safety hold."
+	},
+	"asset/not-retryable": {
+		status: 409,
+		message: "Only assets that failed to process (status error) can be retried."
+	},
+	"asset/content-unavailable": {
+		status: 409,
+		message: "This asset's content is no longer stored, so it can't be processed again. Upload it again instead."
+	},
+	"support/ticket-not-found": {
+		status: 404,
+		message: "Support ticket not found."
+	},
+	"asset/duplicate-external-id": {
+		status: 409,
+		message: "An asset with this externalId already exists in the project."
+	},
+	"folder/not-found": {
+		status: 404,
+		message: "Folder not found"
+	},
+	"folder/duplicate-name": {
+		status: 409,
+		message: "A folder with this name already exists in this location."
+	},
+	"folder/not-empty": {
+		status: 409,
+		message: "Folder must be empty before it can be deleted."
+	},
+	"folder/parent-cycle": {
+		status: 409,
+		message: "A folder cannot be moved inside itself or one of its descendants."
+	},
+	"lens/version-conflict": {
+		status: 409,
+		message: "Lens updates require a version greater than the current version."
+	}
+};
+//#endregion
+//#region src/client/CalmLensError.ts
+/** Codes for failures the SDK detects itself, before or instead of an API error response. */
+const SDK_ERROR_CODES = {
+	/** The request could not be completed: DNS, TLS, a refused or reset connection, a truncated body. */
+	TRANSPORT_ERROR: "sdk/transport-error",
+	/** The request did not finish within `timeoutMs`. */
+	TIMEOUT: "sdk/timeout",
+	/** The caller's `AbortSignal` cancelled the request. */
+	CANCELLED: "sdk/cancelled",
+	/** A successful response whose body is not the JSON the operation returns. */
+	INVALID_RESPONSE: "sdk/invalid-response",
+	/** An HTTP failure without a CalmLens error body, for example from a proxy. */
+	HTTP_ERROR: "sdk/http-error",
+	/** A response body larger than `maxResponseBytes`. */
+	RESPONSE_TOO_LARGE: "sdk/response-too-large",
+	/** A method argument is missing or invalid, for example an empty asset ID. */
+	INVALID_ARGUMENT: "sdk/invalid-argument",
+	/** The client options are invalid, for example a missing API key. */
+	INVALID_CONFIG: "sdk/invalid-config",
+	/** No `fetch` implementation is available in this runtime. */
+	NO_FETCH: "sdk/no-fetch",
+	/** A webhook delivery whose signature or timestamp did not verify. */
+	INVALID_WEBHOOK_SIGNATURE: "sdk/invalid-webhook-signature",
+	/** A verified webhook delivery whose body is not a webhook event. */
+	INVALID_WEBHOOK_PAYLOAD: "sdk/invalid-webhook-payload"
+};
+/** Every error code the SDK can throw: the documented API codes and the SDK's own `sdk/*` codes. */
+const CALMLENS_ERROR_CODES = {
+	...API_ERROR_CODES,
+	...SDK_ERROR_CODES
+};
+const BRAND = Symbol.for("calmlens.sdk.CalmLensError");
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+const RETRYABLE_CODES = /* @__PURE__ */ new Set([SDK_ERROR_CODES.TRANSPORT_ERROR, API_ERROR_CODES.IDEMPOTENT_REQUEST_IN_PROGRESS]);
+/**
+* Every failure the SDK reports, whether the API returned an error or the request never
+* completed. Branch on `code`; `status`, `requestId`, `headers` and `retryAfter` describe the
+* HTTP response when there was one, and `cause` holds the underlying error.
+*
+* `instanceof CalmLensError` and `CalmLensError.isCalmLensError(value)` both recognise errors
+* from any copy of the SDK, so they work when ESM and CommonJS builds are loaded side by side.
+*/
+var CalmLensError = class CalmLensError extends Error {
+	constructor(code, options = {}) {
+		const id = typeof code === "string" ? code : code.id;
+		const defaultMessage = typeof code === "string" ? void 0 : code.defaultMessage;
+		super(`[calmlens] ${options.message ?? defaultMessage ?? id}`, { cause: options.cause });
+		this.name = "CalmLensError";
+		this.code = id;
+		this.status = options.status;
+		this.details = options.details;
+		this.requestId = options.requestId;
+		this.headers = options.headers;
+		this.retryAfter = options.retryAfter;
+		Object.defineProperty(this, BRAND, { value: true });
+	}
+	/** True for any `CalmLensError`, including one created by another copy or build of the SDK. */
+	static isCalmLensError(value) {
+		return typeof value === "object" && value !== null && value[BRAND] === true;
+	}
+	static [Symbol.hasInstance](value) {
+		return CalmLensError.isCalmLensError(value);
+	}
+	/** The resource does not exist or is not visible to this API key. */
+	isNotFound() {
+		return this.status === 404;
+	}
+	/**
+	* Whether repeating the same request may succeed: transport failures, throttling (429),
+	* gateway errors (502, 503, 504) and idempotent requests still in progress. Only repeat a
+	* create or upload with the same `idempotencyKey`.
+	*/
+	isRetryable() {
+		return RETRYABLE_CODES.has(this.code) || this.status !== void 0 && RETRYABLE_STATUSES.has(this.status);
+	}
+};
+const invalidArgument = (message, details) => new CalmLensError(SDK_ERROR_CODES.INVALID_ARGUMENT, {
+	message,
+	details
+});
+const invalidConfig = (message) => new CalmLensError(SDK_ERROR_CODES.INVALID_CONFIG, { message });
+//#endregion
+//#region src/client/CalmLensUtils.ts
+const assertHttpUrl = (name, value) => {
+	if (value === void 0) return;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {}
+	if (!url || url.protocol !== "https:" && url.protocol !== "http:") throw invalidConfig(`${name} must be an absolute http(s) URL`);
+};
+const assertInteger = (name, value, minimum) => {
+	if (value !== void 0 && (!Number.isSafeInteger(value) || value < minimum)) throw invalidConfig(minimum === 0 ? `${name} must be a non-negative integer` : `${name} must be a positive integer`);
+};
+/**
+* Checks client options before the client sets anything up. `CalmLensClient` and
+* `MockCalmLensClient` share it so both reject the same configuration.
+*/
+const validateClientOptions = (options) => {
+	if (!options || typeof options !== "object") throw invalidConfig("Client options are required");
+	if (!options.apiKey || typeof options.apiKey !== "string") throw invalidConfig("API key is required");
+	if (!options.projectId) throw invalidConfig("Project ID is required");
+	try {
+		encodePathSegment(options.projectId, "Project ID");
+	} catch (error) {
+		throw invalidConfig(error.message.replace(/^\[calmlens\] /, ""));
+	}
+	if ("requestBackend" in options) throw invalidConfig("requestBackend is no longer supported; pass a fetch implementation as fetch");
+	validateRequestOptions(options);
+	assertInteger("maxResponseBytes", options.maxResponseBytes, 1);
+	for (const name of [
+		"fetch",
+		"uploadFetch",
+		"cdnFetch"
+	]) if (options[name] !== void 0 && typeof options[name] !== "function") throw invalidConfig(`${name} must be a function`);
+	assertHttpUrl("baseUrl", options.baseUrl);
+	assertHttpUrl("cdnBaseUrl", options.cdnBaseUrl);
+};
+/** Checks the options `withRequestOptions` accepts. */
+const validateRequestOptions = (options) => {
+	assertInteger("timeoutMs", options.timeoutMs, 1);
+	assertInteger("uploadTimeoutMs", options.uploadTimeoutMs, 1);
+	assertInteger("maxRetries", options.maxRetries, 0);
+};
+const toTextAssetOptions = ({ text, name, ...options }) => {
+	if (typeof text !== "string" || !text.trim()) throw new CalmLensError(API_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"
+		}
+	};
+};
+/**
+* Encodes an identifier as one URL path segment. `.` and `..` are rejected because URL
+* resolution would treat them as relative segments and send the request to another route.
+*/
+const encodePathSegment = (value, name) => {
+	if (typeof value !== "string" || !value) throw invalidArgument(`${name} is required`);
+	if (value === "." || value === "..") throw invalidArgument(`${name} cannot be "." or ".."`);
+	return encodeURIComponent(value);
+};
+/** Appends a CDN lens (`/@name`) or direct transform selector to an asset URL. */
+const appendCdnSelector = (url, options) => {
+	if (options.lens && options.transform) throw invalidArgument("Specify either a lens or a transform, not both");
+	if (options.lens) return `${url}/@${encodePathSegment(options.lens, "Lens")}`;
+	if (!options.transform) return url;
+	const transform = options.transform.replace(/^\/+/, "");
+	if (transform.includes("..") || transform.includes("?") || transform.includes("#")) throw invalidArgument("Transform cannot contain \"..\", \"?\" or \"#\"");
+	return `${url}/${encodeURI(transform)}`;
+};
+const appendQueryValue = (parts, key, value) => {
+	if (value === void 0 || value === null) return;
+	if (Array.isArray(value)) {
+		for (const [index, item] of value.entries()) appendQueryValue(parts, `${key}[${index}]`, item);
+		return;
+	}
+	if (typeof value === "object") {
+		for (const [field, item] of Object.entries(value)) appendQueryValue(parts, `${key}[${field}]`, item);
+		return;
+	}
+	parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+};
+/**
+* Serialises a query object the way the API parses it (qs bracket notation), for example
+* `ordering[0][field]=createdAt&ordering[0][direction]=DESC`. Every key and value is
+* percent-encoded and missing values are omitted.
+*/
+const stringifyQuery = (query) => {
+	const parts = [];
+	for (const [key, value] of Object.entries(query)) appendQueryValue(parts, key, value);
+	return parts.join("&");
+};
+//#endregion
+//#region ../shared/src/CryptoUtils.ts
+const encoder = new TextEncoder();
+/** Lowercase hex of `bytes`, two characters per byte. */
+const bytesToHex = (bytes) => Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/** HMAC-SHA256 of `message` keyed with `secret` (both UTF-8 encoded), as lowercase hex. */
+const hmacSha256Hex = async (secret, message) => {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return bytesToHex(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+};
+/**
+* Compares two strings without leaking, through timing, where they first differ. Strings of
+* different lengths are unequal immediately (the length itself is not secret here).
+*/
+const timingSafeEqual = (a, b) => {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+};
+//#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";
+/** Deliveries whose timestamp is further than this from the receiver's clock are rejected. */
+const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+const readHeader = (headers, name) => {
+	if (!headers) return void 0;
+	if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+	const record = headers;
+	const key = Object.keys(record).find((candidate) => candidate.toLowerCase() === name);
+	const value = key === void 0 ? void 0 : record[key];
+	return Array.isArray(value) ? value.join(",") : value ?? void 0;
+};
+/** The raw body as text. Parsed objects are refused: re-serializing JSON changes the signed bytes. */
+const payloadToText = (payload) => {
+	if (typeof payload === "string") return payload;
+	if (payload instanceof ArrayBuffer || ArrayBuffer.isView(payload)) {
+		const view = ArrayBuffer.isView(payload) ? new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength) : new Uint8Array(payload);
+		return new TextDecoder("utf-8", { fatal: false }).decode(view);
+	}
+	throw invalidArgument("Webhook payload must be the raw request body as a string, Uint8Array/Buffer or ArrayBuffer, not parsed JSON");
+};
+/**
+* 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, malformed or stale, and throws
+* `sdk/invalid-argument` when `payload` is not a raw body (for example, parsed JSON).
+*/
+async function verifyWebhookSignature(options) {
+	const { payload, secret, toleranceSeconds = 300, now, headers } = options;
+	const body = payloadToText(payload);
+	const signature = options.signature ?? readHeader(headers, "x-calmlens-signature");
+	const timestamp = options.timestamp ?? readHeader(headers, "x-calmlens-timestamp");
+	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 expected = await hmacSha256Hex(secret, `${timestampText}.${body}`);
+	let matched = false;
+	for (const candidate of candidates) if (timingSafeEqual(expected, candidate)) matched = true;
+	return matched;
+}
+/**
+* Verifies a webhook delivery and parses its body. Throws `sdk/invalid-webhook-signature`
+* when the signature or timestamp does not verify, and `sdk/invalid-webhook-payload` when a
+* verified body is not a webhook event. Narrow the result on `type` for typed `data.facts`.
+*
+* Event types and fact keys added to CalmLens after this SDK version are returned as they are,
+* so keep a default branch when you switch on `type`.
+*/
+async function parseWebhookEvent(options) {
+	if (!await verifyWebhookSignature(options)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_SIGNATURE, { message: "Webhook signature or timestamp did not verify" });
+	let event;
+	try {
+		event = JSON.parse(payloadToText(options.payload));
+	} catch (cause) {
+		throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, {
+			message: "Webhook body is not JSON",
+			cause
+		});
+	}
+	const candidate = event;
+	if (!candidate || typeof candidate !== "object" || typeof candidate.id !== "string" || typeof candidate.type !== "string" || typeof candidate.projectId !== "string" || !candidate.data || typeof candidate.data !== "object") throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, { message: "Webhook body is not a CalmLens event" });
+	return event;
+}
+//#endregion
+Object.defineProperty(exports, "API_ERROR_CODES", {
+	enumerable: true,
+	get: function() {
+		return API_ERROR_CODES;
+	}
+});
+Object.defineProperty(exports, "API_ERROR_DEFINITIONS", {
+	enumerable: true,
+	get: function() {
+		return API_ERROR_DEFINITIONS;
+	}
+});
+Object.defineProperty(exports, "CALMLENS_ERROR_CODES", {
+	enumerable: true,
+	get: function() {
+		return CALMLENS_ERROR_CODES;
+	}
+});
+Object.defineProperty(exports, "CalmLensError", {
+	enumerable: true,
+	get: function() {
+		return CalmLensError;
+	}
+});
+Object.defineProperty(exports, "DOMAIN", {
+	enumerable: true,
+	get: function() {
+		return DOMAIN;
+	}
+});
+Object.defineProperty(exports, "MAX_IMAGE_UPLOAD_BYTES", {
+	enumerable: true,
+	get: function() {
+		return MAX_IMAGE_UPLOAD_BYTES;
+	}
+});
+Object.defineProperty(exports, "MIN_MULTIPART_IMAGE_UPLOAD_BYTES", {
+	enumerable: true,
+	get: function() {
+		return MIN_MULTIPART_IMAGE_UPLOAD_BYTES;
+	}
+});
+Object.defineProperty(exports, "SDK_ERROR_CODES", {
+	enumerable: true,
+	get: function() {
+		return SDK_ERROR_CODES;
+	}
+});
+Object.defineProperty(exports, "WEBHOOK_DELIVERY_HEADER", {
+	enumerable: true,
+	get: function() {
+		return WEBHOOK_DELIVERY_HEADER;
+	}
+});
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", {
+	enumerable: true,
+	get: function() {
+		return WEBHOOK_SIGNATURE_HEADER;
+	}
+});
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_TOLERANCE_SECONDS", {
+	enumerable: true,
+	get: function() {
+		return WEBHOOK_SIGNATURE_TOLERANCE_SECONDS;
+	}
+});
+Object.defineProperty(exports, "WEBHOOK_TIMESTAMP_HEADER", {
+	enumerable: true,
+	get: function() {
+		return WEBHOOK_TIMESTAMP_HEADER;
+	}
+});
+Object.defineProperty(exports, "appendCdnSelector", {
+	enumerable: true,
+	get: function() {
+		return appendCdnSelector;
+	}
+});
+Object.defineProperty(exports, "assetDataToUint8Array", {
+	enumerable: true,
+	get: function() {
+		return assetDataToUint8Array;
+	}
+});
+Object.defineProperty(exports, "assetToData", {
+	enumerable: true,
+	get: function() {
+		return assetToData;
+	}
+});
+Object.defineProperty(exports, "encodePathSegment", {
+	enumerable: true,
+	get: function() {
+		return encodePathSegment;
+	}
+});
+Object.defineProperty(exports, "getAssetPayloadByteLength", {
+	enumerable: true,
+	get: function() {
+		return getAssetPayloadByteLength;
+	}
+});
+Object.defineProperty(exports, "getRawBase64", {
+	enumerable: true,
+	get: function() {
+		return getRawBase64;
+	}
+});
+Object.defineProperty(exports, "getRejectedUploadMimeTypeError", {
+	enumerable: true,
+	get: function() {
+		return getRejectedUploadMimeTypeError;
+	}
+});
+Object.defineProperty(exports, "hmacSha256Hex", {
+	enumerable: true,
+	get: function() {
+		return hmacSha256Hex;
+	}
+});
+Object.defineProperty(exports, "invalidArgument", {
+	enumerable: true,
+	get: function() {
+		return invalidArgument;
+	}
+});
+Object.defineProperty(exports, "invalidConfig", {
+	enumerable: true,
+	get: function() {
+		return invalidConfig;
+	}
+});
+Object.defineProperty(exports, "isRejectedUploadMimeType", {
+	enumerable: true,
+	get: function() {
+		return isRejectedUploadMimeType;
+	}
+});
+Object.defineProperty(exports, "parseWebhookEvent", {
+	enumerable: true,
+	get: function() {
+		return parseWebhookEvent;
+	}
+});
+Object.defineProperty(exports, "stringifyJsonCanonical", {
+	enumerable: true,
+	get: function() {
+		return stringifyJsonCanonical;
+	}
+});
+Object.defineProperty(exports, "stringifyQuery", {
+	enumerable: true,
+	get: function() {
+		return stringifyQuery;
+	}
+});
+Object.defineProperty(exports, "toTextAssetOptions", {
+	enumerable: true,
+	get: function() {
+		return toTextAssetOptions;
+	}
+});
+Object.defineProperty(exports, "validateAssetPayload", {
+	enumerable: true,
+	get: function() {
+		return validateAssetPayload;
+	}
+});
+Object.defineProperty(exports, "validateClientOptions", {
+	enumerable: true,
+	get: function() {
+		return validateClientOptions;
+	}
+});
+Object.defineProperty(exports, "validateRequestOptions", {
+	enumerable: true,
+	get: function() {
+		return validateRequestOptions;
+	}
+});
+Object.defineProperty(exports, "verifyWebhookSignature", {
+	enumerable: true,
+	get: function() {
+		return verifyWebhookSignature;
+	}
+});