@calmlens/sdk 0.16.2 → 0.17.1

package/esm/CalmLensServerClient-fQEYKLw4.js

@@ -0,0 +1,586 @@
+import { A as invalidArgument, O as CalmLensError, b as validateServerClientOptions, c as DEFAULT_CDN_BASE_URL, d as pollForDecision, g as transformSelector, h as toTextAssetOptions, j as invalidConfig, k as SDK_ERROR_CODES, l as encodePathSegment, o as isBrowserRuntime, s as isReactNativeRuntime, u as getAssetUrl, v as validateBatchAssetsOptions, x as validateSignedUrlOptions, y as validateRequestOptions } from "./ModerationContextLimits-D1x_WAtP.js";
+import { a as getMockHooks, c as prepareSubmitAssetOptions, l as resolveConnectionOptions, o as invalidPayload, r as expectAsset, s as newIdempotencyKey, t as CalmLensConnection } from "./CalmLensConnection-iyNQHA8L.js";
+import { n as sha256Hex, r as timingSafeEqual, t as hmacSha256Hex } from "./CryptoUtils-B_x8lMIx-DhuWGzqn.js";
+// src/contract/JsonUtils.js
+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]]));
+});
+// src/contract/UploadToken.js
+const UPLOAD_TOKEN_PREFIX = "clut_";
+const UPLOAD_TOKEN_MAX_TTL_SECONDS = 3600;
+const SIGNING_CONTEXT = "calmlens-upload-token:v1:";
+const toBase64Url = (value) => btoa(String.fromCharCode(...new TextEncoder().encode(value))).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+/**
+* The part of an API key a token names so the backend can find the key's hash. The same rule as
+* the stored `keyPrefix`: the fixed `clsk_<region>_` part plus four random characters.
+*/
+const uploadTokenKeyPrefix = (apiKey) => apiKey.substring(0, apiKey.startsWith("clsk_") ? 13 : 8);
+/** The signing secret: the SHA-256 of the API key, which the backend stores instead of the key. */
+const signingSecret = (apiKey) => sha256Hex(apiKey);
+/** Signs `claims` with `apiKey` and returns the token. */
+const signUploadToken = async (claims, apiKey) => {
+	const body = toBase64Url(JSON.stringify(claims));
+	const signature = await hmacSha256Hex(await signingSecret(apiKey), SIGNING_CONTEXT + body);
+	return `${UPLOAD_TOKEN_PREFIX}${body}.${signature}`;
+};
+// src/client/CalmLensUploadTokens.ts
+/**
+* Signs a single-use upload token with `apiKey`, locally. `CalmLensServerClient` and
+* `MockCalmLensServerClient` share it so both check options the same way. `@calmlens/sdk/testing`
+* exports it as `signUploadToken`, whose fixed `now` (milliseconds since the epoch) and `nonce`
+* give the same token every time, for comparing with known tokens in tests.
+*/
+const signUploadTokenWithApiKey = async (apiKey, options, { now = Date.now(), nonce = crypto.randomUUID() } = {}) => {
+	if (!options || typeof options !== "object") throw invalidArgument("Options are required");
+	const { uploadPresetId, externalId, expiresInSeconds = 600 } = options;
+	encodePathSegment(uploadPresetId, "Upload preset ID");
+	if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 3600) throw invalidArgument(`expiresInSeconds must be a whole number from 1 to ${UPLOAD_TOKEN_MAX_TTL_SECONDS}`);
+	if (externalId !== void 0 && (typeof externalId !== "string" || !externalId)) throw invalidArgument("externalId must be a non-empty string");
+	const expiresAt = now + expiresInSeconds * 1e3;
+	return {
+		token: await signUploadToken({
+			v: 1,
+			u: uploadPresetId,
+			k: uploadTokenKeyPrefix(apiKey),
+			e: expiresAt,
+			n: nonce,
+			...externalId === void 0 ? {} : { x: externalId }
+		}, apiKey),
+		expiresAt
+	};
+};
+// 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. Unknown event types, fact values and fields remain available.
+*
+* 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
+		});
+	}
+	if (!isWebhookEvent(event)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, { message: "Webhook body is not a CalmLens event" });
+	return event;
+}
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const isOptional = (value, type, nullable) => value === void 0 || nullable && value === null || typeof value === type;
+/**
+* Whether `value` is a webhook body, by the rules of shared/WebhookPayload's
+* RECEIVED_WEBHOOK_EVENT_PAYLOAD_SCHEMA: the fields CalmLens always sends, and the types of the
+* other known fields when present. Each fact needs a string `key` and a `value` (any JSON
+* value, `null` included). Unknown fields and fact values are accepted.
+*/
+const isWebhookEvent = (value) => {
+	if (!isObject(value) || typeof value.id !== "string" || typeof value.type !== "string" || typeof value.projectId !== "string" || typeof value.createdAt !== "number") return false;
+	const { severity, title, description, assetId, asset, facts } = value;
+	return isOptional(severity, "string", false) && isOptional(title, "string", false) && isOptional(description, "string", true) && isOptional(assetId, "string", true) && (asset === void 0 || asset === null || isObject(asset) && typeof asset.id === "string") && (facts === void 0 || Array.isArray(facts) && facts.every((fact) => isObject(fact) && typeof fact.key === "string" && "value" in fact && isOptional(fact.url, "string", false)));
+};
+/**
+* Whether a webhook event is a test send from the portal or the CLI rather than a real event: it
+* carries the registered `{ key: "test", value: true }` fact.
+*/
+const isTestWebhookEvent = (event) => Array.isArray(event?.facts) && event.facts.some((fact) => fact?.key === "test" && fact.value === true);
+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 requireId = (value, name) => encodePathSegment(value, name);
+/**
+* Iterators stop rather than loop: a page that says more follow must not hand back a cursor this
+* iteration has already sent, which would repeat the same pages forever.
+*/
+const assertNewCursor = (sent, cursor) => {
+	if (sent.has(cursor)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, {
+		message: "The API returned a cursor it had already returned, with more pages to follow",
+		details: { cursor }
+	});
+	sent.add(cursor);
+};
+const inspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+/**
+* The CalmLens API client for your server, authenticated with a project API key. Create one per
+* project and reuse it; it holds no connections. Every method takes one options object and
+* throws `CalmLensError` on failure. Browsers and apps upload with `CalmLensAppClient` instead.
+*/
+var CalmLensServerClient = class CalmLensServerClient {
+	#apiKey;
+	#settings;
+	#lenses;
+	#connection;
+	/**
+	* 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.
+	* Also exported as `verifyWebhookSignature`; `parseWebhookEvent` verifies and parses.
+	*
+	* @example
+	* ```ts
+	* const payload = await request.text();
+	* const isValid = await CalmLensServerClient.verifyWebhookSignature({
+	*   payload,
+	*   headers: request.headers,
+	*   secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+	* });
+	* ```
+	*/
+	static async verifyWebhookSignature(options) {
+		return verifyWebhookSignature(options);
+	}
+	constructor(options, lenses) {
+		validateServerClientOptions(options);
+		if ((isBrowserRuntime() || isReactNativeRuntime()) && !options.dangerouslyAllowBrowser) throw invalidConfig("CalmLensServerClient is running in a browser or app, where anyone could read the API key. Call CalmLens from your server, upload from the browser or app with CalmLensAppClient, or set dangerouslyAllowBrowser: true for trusted internal tools.");
+		const { apiKey, ...rest } = options;
+		this.#apiKey = apiKey;
+		this.#settings = {
+			...resolveConnectionOptions(rest),
+			cdnBaseUrl: (rest.cdnBaseUrl ?? getMockHooks(rest)?.defaultCdnBaseUrl ?? DEFAULT_CDN_BASE_URL).replace(/\/+$/, "")
+		};
+		this.#lenses = lenses ?? {
+			ensuredLenses: /* @__PURE__ */ new Map(),
+			pendingEnsureLenses: /* @__PURE__ */ new Map()
+		};
+		this.#connection = new CalmLensConnection(this.#settings, apiKey);
+	}
+	/**
+	* A client with different cancellation, deadlines or retries for the calls made through it,
+	* sharing this client's credentials and lens cache. This client is unchanged.
+	*/
+	withRequestOptions(options) {
+		validateRequestOptions(options);
+		return new CalmLensServerClient({
+			...this.#settings,
+			...options,
+			apiKey: this.#apiKey
+		}, this.#lenses);
+	}
+	/** Keeps the API key out of `console.log`, `util.inspect` and `JSON.stringify`. */
+	[inspectSymbol]() {
+		const { projectId, baseUrl } = this.#settings;
+		return `CalmLensServerClient { projectId: ${JSON.stringify(projectId)}, baseUrl: ${JSON.stringify(baseUrl)} }`;
+	}
+	toJSON() {
+		const { projectId, baseUrl, cdnBaseUrl } = this.#settings;
+		return {
+			projectId,
+			baseUrl,
+			cdnBaseUrl
+		};
+	}
+	get projectPath() {
+		return `/projects/${encodeURIComponent(this.#settings.projectId)}`;
+	}
+	request(method, path, options = {}) {
+		return this.#connection.json(method, path, options);
+	}
+	async submitAsset(options, queue) {
+		const body = prepareSubmitAssetOptions(options, { deferUploadChecks: this.#connection.deferUploadChecks });
+		const uploadsPath = `${this.projectPath}/assets`;
+		if ("content" in body || "part" in body) return expectAsset(await this.#connection.submitRawUpload(uploadsPath, body, queue));
+		const { idempotencyKey, ...fields } = body;
+		const data = await this.#connection.json("POST", uploadsPath, {
+			query: { queue },
+			body: fields,
+			idempotencyKey: idempotencyKey ?? newIdempotencyKey()
+		});
+		return expectAsset(data);
+	}
+	get cdn() {
+		return {
+			/**
+			* Builds a CDN URL for asset content or a preview, without a request. Private assets
+			* need a signed URL (`assets.createSignedUrl`) or an authenticated request; public
+			* age-restricted assets additionally require `viewerClaims.ageConfirmed: true`.
+			*/
+			getAssetUrl: ({ assetIdentifier, ...options }) => {
+				const { projectId, cdnBaseUrl } = this.#settings;
+				return getAssetUrl({
+					projectId,
+					cdnBaseUrl,
+					assetIdentifier,
+					...options
+				});
+			},
+			/**
+			* Fetches asset content or a preview from the CDN with the client's API key, and returns
+			* the `Response` as soon as headers arrive, so the body streams. Non-2xx responses are
+			* returned, not thrown; `timeoutMs` covers only the wait for headers.
+			*/
+			serve: async ({ assetIdentifier, init, ...urlOptions }) => {
+				const url = this.cdn.getAssetUrl({
+					assetIdentifier,
+					...urlOptions
+				});
+				const method = init?.method?.toUpperCase() ?? "GET";
+				const { response } = await this.#connection.transport.send({
+					method,
+					url,
+					init,
+					timeoutMs: this.#connection.timeoutMs,
+					deadline: "headers",
+					fetch: this.#settings.cdnFetch
+				}, { allowHttpErrors: true });
+				return response;
+			}
+		};
+	}
+	get text() {
+		return { 
+		/**
+		* Moderates text and waits for the decision. Sends `text` as `text/plain` content named
+		* `text` unless you pass `name`.
+		*/
+classify: async (options) => this.buildAssets().classify(toTextAssetOptions(options)) };
+	}
+	/** Assets: uploads, moderation and management. */
+	get assets() {
+		return this.buildAssets();
+	}
+	/**
+	* Signs upload tokens on your server, so a browser or app can upload through an upload preset
+	* that requires one. Signing happens locally with your API key: it makes no request.
+	*/
+	get uploadTokens() {
+		return { 
+		/**
+		* Signs a single-use token for one upload through `uploadPresetId`. Give `token` to the
+		* browser or app, which passes it to `CalmLensAppClient` as `token`.
+		*/
+sign: async (options) => {
+			return signUploadTokenWithApiKey(this.#apiKey, options, this.#connection.hooks?.uploadTokenTime());
+		} };
+	}
+	buildAssets() {
+		return {
+			/** Searches accessible assets by keyword or a natural-language description. */
+			search: async (options) => this.request("GET", `${this.projectPath}/assets/search`, { query: options }),
+			/** Lists one page of the project's assets, with optional filter and ordering. */
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/assets`, { query: options }),
+			/**
+			* Yields every asset matching `options`, fetching pages as needed. The cursor keeps the position
+			* stable when other assets are inserted or deleted.
+			*/
+			iterate: (options = {}) => this.iteratePages((cursor) => this.buildAssets().list({
+				...options,
+				cursor
+			})),
+			/** Retrieves an asset with its status and classification results. */
+			retrieve: async ({ assetId }) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}`),
+			/** Updates an asset's editable fields. */
+			update: async ({ assetId, ...body }) => this.request("PATCH", `/assets/${requireId(assetId, "Asset ID")}`, { body }),
+			/** Lists one page of the assets extracted from a website or multimedia document. */
+			listChildren: async ({ assetId, ...options } = {}) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}/children`, { query: options }),
+			/** Yields every child of an asset, fetching pages as needed. */
+			iterateChildren: (options) => {
+				requireId(options?.assetId, "Asset ID");
+				return this.iteratePages((cursor) => this.buildAssets().listChildren({
+					...options,
+					cursor
+				}));
+			},
+			/**
+			* Uploads an asset and queues it for moderation, returning immediately with processing
+			* status `processing` (or `uploading` for the first multipart part). Retried safely with an
+			* `Idempotency-Key`.
+			*/
+			create: async (options) => this.submitAsset(options, true),
+			/**
+			* Uploads an asset and waits for its moderation decision. Audio and video still finish
+			* in the background. Retried safely with an `Idempotency-Key`.
+			*/
+			classify: async (options) => {
+				if (options && "content" in options && "plainText" in options.content && (typeof options.content.plainText !== "string" || !options.content.plainText.trim())) throw invalidPayload("Text to classify must be a non-empty string");
+				return this.submitAsset(options, false);
+			},
+			/**
+			* Uploads the next part of a multipart upload. The upload's queue mode, chosen when it
+			* started, applies when the final part arrives; pass `queue` to override it.
+			*/
+			uploadPart: async ({ assetId, ...options }) => {
+				const encodedAssetId = requireId(assetId, "Asset ID");
+				return expectAsset(await this.#connection.uploadPart(`/assets/${encodedAssetId}/part`, options));
+			},
+			/**
+			* Creates a short-lived signed CDN URL, so browsers can load private content without
+			* an API key.
+			*/
+			createSignedUrl: async ({ assetId, ...options }) => {
+				const encodedAssetId = requireId(assetId, "Asset ID");
+				validateSignedUrlOptions(options);
+				return this.request("POST", `/assets/${encodedAssetId}/signed-url`, { body: {
+					viewerClaims: options.viewerClaims,
+					resource: options.resource,
+					expiresInSeconds: options.expiresInSeconds ?? 900,
+					lens: options.lens,
+					transform: transformSelector(options.transform)
+				} });
+			},
+			/** Moves an asset into a folder, or to the project root with `folderId: null`. */
+			move: async ({ assetId, folderId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/move`, { body: { folderId } }),
+			/**
+			* Processes an asset that failed (classification status `failed`) again. It returns to
+			* `processing` and is
+			* moderated like a new upload; its content must still be stored.
+			*/
+			retry: async ({ assetId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/retry`),
+			/**
+			* Records a reviewer's decision, replacing the policy's: the asset's moderation status
+			* becomes `decision`, the note joins its review history and the matching `asset.<status>`
+			* event is sent. An asset still pending moderation can only be blocked or purged. Purging
+			* needs `confirmPurge: true` and permanently deletes the stored content.
+			*/
+			decide: async ({ assetId, ...body }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/decision`, { body }),
+			/**
+			* Completes the policy evidence behind a decided asset's moderation decision: the report's
+			* `classification.moderation.evidence` becomes `full` and every action stays as
+			* decided. With `rerun: true` the asset is moderated again with the project's current policy
+			* and returns in `processing`; use it when the policy has changed since the decision
+			* (`asset/policy-changed`).
+			*/
+			explain: async ({ assetId, rerun }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/explain`, { body: rerun ? { rerun } : {} }),
+			/**
+			* Waits until an asset's `classification.moderation.status` is no longer `pending` (`allowed`,
+			* `limited`, `age-restricted`, `blocked` or `purged`), or its `classification.status` is `failed`, and returns that asset, checking every few seconds. Rejects with `sdk/timeout` if there is no
+			* decision within `timeoutMs` (default 60000). Webhooks report decisions without polling.
+			*/
+			waitForDecision: async ({ assetId, ...options }) => {
+				requireId(assetId, "Asset ID");
+				const client = options.signal ? this.withRequestOptions({ signal: options.signal }) : this;
+				return pollForDecision(() => client.assets.retrieve({ assetId }), options, this.#connection.sleep, this.#connection.hooks?.now);
+			},
+			/**
+			* Removes an asset's stored content (source, preview and retained extracted text) while
+			* keeping the asset record, metadata and classification results. The returned asset has
+			* `content.status` set to `removed` and `content.removalReason` to `requested`; the CDN no longer serves it.
+			*/
+			deleteContent: async ({ assetId }) => this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}/content`),
+			/** Deletes an asset record together with its stored content. */
+			delete: async ({ assetId }) => {
+				await this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}`);
+			},
+			/**
+			* Deletes up to 500 assets (`operation: "delete"`) or removes their stored content
+			* (`"remove-content"`) in one request. Every asset must exist in the project and the key
+			* needs `assets:delete` for its folder, or nothing is queued. Resolves with
+			* `{ queued: true }` once queued; the work runs in the background and records
+			* `asset.deleted` or `asset.content-removed` for each asset. Assets under a safety hold
+			* are skipped. Not retried: it carries no `Idempotency-Key`.
+			*/
+			batch: async ({ assetIds, operation }) => {
+				validateBatchAssetsOptions({
+					assetIds,
+					operation
+				});
+				return this.request("POST", `${this.projectPath}/assets/batch`, { body: {
+					assetIds,
+					operation
+				} });
+			}
+		};
+	}
+	get events() {
+		return {
+			/**
+			* Lists project events after a cursor, oldest first. Call without `cursor` to get a cursor
+			* for "now", then poll with each response's `nextCursor`. Webhook deliveries carry the same
+			* events reshaped as `{ id, type, createdAt, projectId, data }`.
+			*/
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/events`, { query: { ...options } }),
+			/**
+			* Yields pages of events after `cursor` until no more are waiting. Save each page's
+			* `nextCursor` to resume later. Without `cursor`, yields one empty page whose `nextCursor`
+			* is "now".
+			*/
+			pages: (options = {}) => this.iterateEventPages(options)
+		};
+	}
+	async *iterateEventPages(options) {
+		let cursor = options.cursor;
+		const sent = new Set(cursor === void 0 ? [] : [cursor]);
+		for (;;) {
+			const page = await this.events.list({
+				...options,
+				cursor
+			});
+			if (page.hasMore) assertNewCursor(sent, page.nextCursor);
+			yield page;
+			if (!page.hasMore) return;
+			cursor = page.nextCursor;
+		}
+	}
+	async *iteratePages(listPage) {
+		let cursor;
+		const sent = /* @__PURE__ */ new Set();
+		for (;;) {
+			const page = await listPage(cursor);
+			const more = !!page.nextCursor && page.hasMore && page.items.length > 0;
+			if (more) assertNewCursor(sent, page.nextCursor);
+			yield* page.items;
+			if (!more) return;
+			cursor = page.nextCursor;
+		}
+	}
+	get folders() {
+		return {
+			/**
+			* Lists one page of child folders, sorted by name unless `ordering` says otherwise. Pass
+			* `nextCursor` as `cursor` for the next page; fetch a branch when it is opened.
+			*/
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/folders`, { query: options }),
+			retrieve: async ({ folderId }) => this.request("GET", `/folders/${requireId(folderId, "Folder ID")}`),
+			/** Creates a folder at the project root or inside `parentId`. */
+			create: async (options) => this.request("POST", `${this.projectPath}/folders`, { body: options }),
+			update: async ({ folderId, ...body }) => this.request("PATCH", `/folders/${requireId(folderId, "Folder ID")}`, { body }),
+			/** Deletes an empty folder; throws `folder/not-empty` otherwise. */
+			delete: async ({ folderId }) => {
+				await this.request("DELETE", `/folders/${requireId(folderId, "Folder ID")}`);
+			},
+			/** Moves a folder under `parentId`, or to the project root with `parentId: null`. */
+			move: async ({ folderId, parentId }) => this.request("POST", `/folders/${requireId(folderId, "Folder ID")}/move`, { body: { parentId } })
+		};
+	}
+	/**
+	* Hash lists hold PDQ hashes of images the project never wants again. Image uploads are
+	* compared with every list: `flag` lists record matches, `block` lists also block close ones.
+	*/
+	get hashLists() {
+		return {
+			/** Lists one page of the project's hash lists, newest first. */
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/hash-lists`, { query: options }),
+			retrieve: async ({ hashListId }) => this.request("GET", `/hash-lists/${requireId(hashListId, "Hash list ID")}`),
+			create: async (options) => this.request("POST", `${this.projectPath}/hash-lists`, { body: options }),
+			/** Renames a list or changes its action; the new action applies to later uploads. */
+			update: async ({ hashListId, ...body }) => this.request("PATCH", `/hash-lists/${requireId(hashListId, "Hash list ID")}`, { body }),
+			/** Deletes the list and every entry in it. */
+			delete: async ({ hashListId }) => {
+				await this.request("DELETE", `/hash-lists/${requireId(hashListId, "Hash list ID")}`);
+			},
+			/** Lists one page of a list's entries, newest first. */
+			listEntries: async ({ hashListId, ...query }) => this.request("GET", `/hash-lists/${requireId(hashListId, "Hash list ID")}/entries`, { query }),
+			/** Adds a hash, or an image asset's hash; a hash already in the list returns its entry. */
+			addEntry: async ({ hashListId, ...body }) => this.request("POST", `/hash-lists/${requireId(hashListId, "Hash list ID")}/entries`, { body }),
+			removeEntry: async ({ entryId }) => {
+				await this.request("DELETE", `/hash-list-entries/${requireId(entryId, "Hash list entry ID")}`);
+			}
+		};
+	}
+	/**
+	* 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 invalidArgument("Lens identifier is required");
+		const [lens] = await this.ensureLenses({ lenses: [options] });
+		return lens;
+	}
+	/**
+	* Create or update several named lenses. New definitions are sent in one API request, or in
+	* consecutive requests of at most {@link ENSURE_LENSES_MAX_PER_REQUEST} definitions, in order.
+	* Each lens follows the same versioning and idempotency rules as ensureLens().
+	*/
+	async ensureLenses({ lenses }) {
+		if (!Array.isArray(lenses) || lenses.length === 0) throw invalidArgument("At least one lens is required");
+		if (lenses.some((option) => !option?.identifier)) throw invalidArgument("Lens identifier is required");
+		const { ensuredLenses, pendingEnsureLenses } = this.#lenses;
+		const missingOptions = [];
+		const missingKeys = /* @__PURE__ */ new Set();
+		for (const option of lenses) {
+			const cacheKey = getEnsureLensCacheKey(option);
+			if (!ensuredLenses.has(cacheKey) && !missingKeys.has(cacheKey)) {
+				missingKeys.add(cacheKey);
+				missingOptions.push(option);
+			}
+		}
+		if (missingOptions.length > 0) {
+			const batchCacheKey = JSON.stringify([...missingKeys].sort());
+			let pending = pendingEnsureLenses.get(batchCacheKey);
+			if (!pending) {
+				pending = this.submitEnsureLenses(missingOptions);
+				pendingEnsureLenses.set(batchCacheKey, pending);
+				pending.then(() => pendingEnsureLenses.delete(batchCacheKey), () => pendingEnsureLenses.delete(batchCacheKey));
+			}
+			await pending;
+		}
+		return lenses.map((option) => {
+			const lens = ensuredLenses.get(getEnsureLensCacheKey(option));
+			if (!lens) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `CalmLens did not return lens "${option.identifier}"` });
+			return lens;
+		});
+	}
+	async submitEnsureLenses(options) {
+		for (let start = 0; start < options.length; start += 100) await this.submitEnsureLensesChunk(options.slice(start, start + 100));
+	}
+	async submitEnsureLensesChunk(options) {
+		const result = await this.request("PUT", `${this.projectPath}/lenses`, { body: { lenses: options } });
+		const returned = Array.isArray(result?.lenses) ? result.lenses : [];
+		if (returned.length !== options.length) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected ${options.length} lenses but CalmLens returned ${returned.length}` });
+		const { ensuredLenses } = this.#lenses;
+		for (const [index, lens] of returned.entries()) {
+			const optionsForLens = options[index];
+			if (lens?.identifier !== optionsForLens.identifier) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected lens "${optionsForLens.identifier}" at position ${index}` });
+			for (const [cacheKey, cachedLens] of ensuredLenses) if (cachedLens.identifier === optionsForLens.identifier) ensuredLenses.delete(cacheKey);
+			ensuredLenses.set(getEnsureLensCacheKey(optionsForLens), lens);
+		}
+	}
+};
+export { WEBHOOK_TIMESTAMP_HEADER as a, verifyWebhookSignature as c, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS as i, signUploadTokenWithApiKey as l, WEBHOOK_DELIVERY_HEADER as n, isTestWebhookEvent as o, WEBHOOK_SIGNATURE_HEADER as r, parseWebhookEvent as s, CalmLensServerClient as t, stringifyJsonCanonical as u };