@calmlens/sdk 0.10.1 → 0.12.0

package/README.md

@@ -10,9 +10,16 @@ CalmLens provides content moderation and classification for text, images, docume
 npm install @calmlens/sdk
 ```
 
-Requires Node.js 22 or later, or another server runtime with `fetch` and Web Crypto, such as Bun, Deno or Cloudflare Workers. The package ships ES modules and CommonJS with type declarations and loads no other packages at runtime: importing only `verifyWebhookSignature` adds about 5 KB (minified) to a bundle, and the whole client about 25 KB.
+The package has two clients, each with its own import:
 
-Use it on your server. API keys are secret, so `CalmLensClient` refuses to start in a web page; serve private content to browsers with [signed URLs](#assetscreatesignedurloptions).
+| Import | Client | Runs | Authenticates with |
+| --- | --- | --- | --- |
+| `@calmlens/sdk/server` | `CalmLensServerClient` | On your server: Node.js 22 or later, Bun, Deno, Cloudflare Workers | A project API key |
+| `@calmlens/sdk/app` | `CalmLensAppClient` | In browsers and React Native apps | An [upload preset](#browser-and-app-uploads-with-upload-presets), with an optional upload token from your server |
+
+`@calmlens/sdk` itself exports the shared types, `CalmLensError`, the error codes and `SDK_VERSION`. The package ships ES modules and CommonJS with type declarations and loads no other packages at runtime: importing only `verifyWebhookSignature` adds about 5 KB (minified) to a bundle, `CalmLensAppClient` about 19 KB and `CalmLensServerClient` about 28 KB.
+
+API keys are secret, so `CalmLensServerClient` refuses to start in a web page or app. Upload from browsers and apps with `CalmLensAppClient`, and serve private content to them with [signed URLs](#assetscreatesignedurloptions).
 
 Every public SDK operation accepts one options object. This keeps call sites stable as optional fields are added.
 
@@ -21,9 +28,9 @@ Every public SDK operation accepts one options object. This keeps call sites sta
 Create an API key under **Developer → API Keys** in the CalmLens portal. The same page shows your **Project ID**. Keep both on your server.
 
 ```typescript
-import { CalmLensClient } from "@calmlens/sdk";
+import { CalmLensServerClient } from "@calmlens/sdk/server";
 
-const client = new CalmLensClient({
+const client = new CalmLensServerClient({
   apiKey: process.env.CALMLENS_API_KEY!,
   projectId: process.env.CALMLENS_PROJECT_ID!,
 });
@@ -58,14 +65,14 @@ See [How CalmLens works](https://calmlens.com/docs/how-it-works) and [Testing yo
 
 ## API Reference
 
-### CalmLensClient
+### CalmLensServerClient
 
-The main client class for interacting with the CalmLens API.
+The client for your server, with every API method. Import it from `@calmlens/sdk/server`.
 
 #### Constructor
 
 ```typescript
-new CalmLensClient(options: CalmLensClientOptions)
+new CalmLensServerClient(options: CalmLensServerClientOptions)
 ```
 
 **Options:**
@@ -80,7 +87,7 @@ new CalmLensClient(options: CalmLensClientOptions)
 - `maxRetries` (integer, optional): Retries for failed requests that are safe to repeat (defaults to `2`, `0` disables them). See [Retries and idempotency](#retries-and-idempotency)
 - `maxResponseBytes` (positive integer, optional): Largest JSON response the client reads (defaults to 32 MiB)
 - `signal` (AbortSignal, optional): Cancels every request made by this client
-- `dangerouslyAllowBrowser` (boolean, optional): Lets the client run in a web page. Only for trusted internal tools: anyone who can open the page can read the API key
+- `dangerouslyAllowBrowser` (boolean, optional): Lets the client run in a web page or app. Only for trusted internal tools: anyone who can open the page can read the API key
 
 Options are validated before anything else is set up: a missing `apiKey` or `projectId`, a `timeoutMs` that is not a positive integer, or a `baseUrl`/`cdnBaseUrl` that is not an absolute `http(s)` URL throws a `CalmLensError` with the code `sdk/invalid-config`. The client keeps its API key out of `console.log`, `util.inspect` and `JSON.stringify`.
 
@@ -101,6 +108,7 @@ async assets.create(options: SubmitAssetOptions): Promise<Asset>
 - `part` (optional): First part of a sequential multipart upload
 - `description` (string, optional): Description of the asset
 - `processingOptions.keepContentAfterProcessing` (boolean, optional): Retain content after processing
+- `processingOptions.features` (object, optional): Optional analyses to run, each turned on with `enabled: true`: `ocr`, and in beta `personDetection` and `faceDetection` (with `ageEstimation`). Person and face results are returned in `asset.report.features`. See [People and faces](https://calmlens.com/docs/guides/people-and-faces).
 - `visibility` (string, optional): "public" or "private"
 
 **Example:**
@@ -195,7 +203,7 @@ For several lenses, use `ensureLenses()` to perform all ensures in one request.
 const [normal, uhd] = await client.ensureLenses({ lenses: [normalLens, uhdLens] });
 ```
 
-The CDN uses named lenses with an `@` prefix in URLs, such as `/content/@picmagic-normal`. The SDK adds it automatically when you supply `lens`. Use `transform` for one-off direct transforms, for example `client.cdn.serve({ assetIdentifier: assetId, transform: "imageTransform[format=png,width=1024]" })`. Supply either `lens` or `transform`, not both. The resolved lens version is part of CalmLens's CDN cache and ETag identity, so changing a lens with the next version invalidates prior derived output.
+The CDN uses named lenses with an `@` prefix in URLs, such as `/content/@picmagic-normal`. The SDK adds it automatically when you supply `lens`. Use `transform` for one-off direct transforms, either as structured steps, for example `client.cdn.serve({ assetIdentifier: assetId, transform: { type: "imageTransform", options: { format: "png", width: 1024 } } })`, or as a selector string such as `"imageTransform[format=png,width=1024]"`. Pass an array of steps to chain transforms. `assets.createSignedUrl` accepts the same forms. Supply either `lens` or `transform`, not both. The resolved lens version is part of CalmLens's CDN cache and ETag identity, so changing a lens with the next version invalidates prior derived output.
 
 ##### assets.list(options)
 
@@ -463,6 +471,42 @@ static async verifyWebhookSignature(options: {
 
 It returns `true` only when the `x-calmlens-signature` header contains a `v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"` (one match in a comma-separated list is enough) and the timestamp is within `toleranceSeconds` of now. Passing parsed JSON as `payload` throws `sdk/invalid-argument`: re-serializing it can change the signed bytes.
 
+## Browser and app uploads with upload presets
+
+`CalmLensAppClient` uploads from a browser or app through an upload preset, without an API key. Create presets in the portal under Developer → Upload presets.
+
+```ts
+import { CalmLensAppClient } from "@calmlens/sdk/app";
+
+// In the browser: no API key
+const client = new CalmLensAppClient({
+  uploadPresetId: "your-upload-preset-id",
+  // Only for presets that require a token: called once per new upload
+  token: () => fetch("/api/upload-token", { method: "POST" }).then((r) => r.json()).then((b) => b.token),
+});
+
+const asset = await client.assets.moderate({ name: file.name, content: { data: file, type: file.type } });
+// asset.status is present when the preset shows decisions to uploaders
+```
+
+**Options:** `uploadPresetId` (required), `token` (a string, or a function that returns one or a promise of one), plus `baseUrl`, `fetch`, `uploadFetch`, `timeoutMs`, `uploadTimeoutMs`, `maxRetries`, `maxResponseBytes` and `signal` as for `CalmLensServerClient`. Passing `apiKey` throws `sdk/invalid-config`.
+
+The client has `assets.create`, `assets.moderate`, `assets.uploadPart` and `assets.retrieve`, for its own uploads, and each returns an `UploadedAsset`. It fetches a new token for each upload and reuses that token for the upload's parts and status checks.
+
+The same client works in React Native and Expo apps. Mobile apps send no `Origin` header, so use a preset that requires a token and leave its allowed sites empty. Pass the picked file's bytes, for example `content: { buffer: await new File(uri).arrayBuffer(), type }` with `expo-file-system`. See the [Calmsnap example](https://github.com/CalmLens/CalmLens/tree/main/examples/mobile-uploads-expo).
+
+On your server, sign a single-use token for each upload with `CalmLensServerClient`. Signing is local and makes no request:
+
+```ts
+const { token, expiresAt } = await client.uploadTokens.sign({
+  uploadPresetId: "your-upload-preset-id",
+  externalId: "post-42", // optional
+  expiresInSeconds: 600, // optional, up to 3600
+});
+```
+
+Server uploads can also pass `uploadPresetId` to `assets.create` or `assets.moderate` to apply a preset's folder, visibility, file types and size limit. See [Upload presets](https://calmlens.com/docs/guides/upload-presets).
+
 ## Asset Types
 
 Assets can be of the following types:
@@ -570,27 +614,27 @@ The SDK does not validate responses against its types, so fields and values adde
 
 ## Testing
 
-`@calmlens/sdk/testing` exports a matching object-parameter `MockCalmLensClient`, in-memory storage implementations, mock API key helpers, webhook delivery builders and `generateMediaTestCode`, for testing without network requests.
+`@calmlens/sdk/testing` exports `MockCalmLensServerClient`, an in-memory stand-in for `CalmLensServerClient`,, in-memory storage implementations, mock API key helpers, webhook delivery builders and `generateMediaTestCode`, for testing without network requests.
 
-The main `@calmlens/sdk` entry point does not load or export testing helpers, to keep production bundles small. Keep `/testing` imports in test files.
+The `@calmlens/sdk`, `/server` and `/app` entry points do not load or export testing helpers, to keep production bundles small. Keep `/testing` imports in test files.
 
 ```typescript
-import { MockCalmLensClient, createMockApiKey } from "@calmlens/sdk/testing";
+import { MockCalmLensServerClient, createMockApiKey } from "@calmlens/sdk/testing";
 
-const client = new MockCalmLensClient({
+const client = new MockCalmLensServerClient({
   apiKey: createMockApiKey(),
   projectId: crypto.randomUUID(),
 });
 ```
 
-`MockCalmLensClient` accepts the same options as `CalmLensClient` (`apiKey`, `projectId`, `baseUrl`, `cdnBaseUrl`, `timeoutMs`, ...) and validates them the same way, plus `mockOptions`. `cdn.getAssetUrl` uses `cdnBaseUrl` (default `mock://calmlens/v1`).
+`MockCalmLensServerClient` accepts the same options as `CalmLensServerClient` (`apiKey`, `projectId`, `baseUrl`, `cdnBaseUrl`, `timeoutMs`, ...) and validates them the same way, plus `mockOptions`. `cdn.getAssetUrl` uses `cdnBaseUrl` (default `mock://calmlens/v1`).
 
 It behaves like the API where tests depend on it: errors carry the API's code, HTTP `status`, a `requestId` and `headers`; `assets.list` applies `ordering`, `folderId` and simple `filter` expressions (comparisons joined by `;` and `,`; anything else throws `sdk/invalid-argument` rather than returning wrong results); `assets.search` matches names, IDs, external IDs, descriptions and tags; multipart parts must arrive in order and the queue mode chosen at the start applies to the final part; a reused `idempotencyKey` replays the first result; and `cdn.serve` returns CDN-like responses with JSON error bodies. `client.enqueueEvent({ type, ... })` adds an event that `events.list` and `events.pages` then return.
 
 Every call is recorded in `client.calls` as `{ operation, options }`, where `operation` is the method path (`"text.moderate"`, `"assets.retrieve"`, `"events.list"`, ...) and `options` is the object you passed. `client.callsTo(operation)` filters them. To test failure handling, `client.failNextRequest()` makes the next call throw the same `CalmLensError` the real client throws when the network fails (`sdk/transport-error`); pass `"timeout"` for `sdk/timeout`, or any `Error` to throw it as is, and `{ operation }` to fail only that method. Each queued failure is used once.
 
 ```typescript
-const client = new MockCalmLensClient({ apiKey: createMockApiKey(), projectId, timeoutMs: 5_000 });
+const client = new MockCalmLensServerClient({ apiKey: createMockApiKey(), projectId, timeoutMs: 5_000 });
 
 client.failNextRequest("timeout", { operation: "text.moderate" });
 await expect(postComment(client, "hello")).rejects.toMatchObject({ code: "sdk/timeout" });
@@ -648,7 +692,7 @@ The result is typed as `WebhookEventPayload`; narrow it on `type` to get that ev
 **Fetch API** (Next.js route handlers, Remix, Cloudflare Workers, Bun, Deno):
 
 ```typescript
-import { CalmLensError, parseWebhookEvent } from "@calmlens/sdk";
+import { CalmLensError, parseWebhookEvent } from "@calmlens/sdk/server";
 
 export async function POST(request: Request) {
   let event;

package/cjs/CalmLensConnection-CYtBP-vu.js

@@ -0,0 +1,516 @@
+const require_CalmLensError = require("./CalmLensError-CKwMKV0S.js");
+const require_src = require("./src-Dsc8Pn6v.js");
+const require_CalmLensUtils = require("./CalmLensUtils-Dg3s4loH.js");
+//#region src/client/CalmLensTransport.ts
+/** Retry delays grow from this base, doubling per attempt, with jitter. */
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 8e3;
+/** A `Retry-After` longer than this is returned to the caller instead of waited out. */
+const RETRY_AFTER_MAX_MS = 6e4;
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+const timeoutReason = () => {
+	const reason = /* @__PURE__ */ new Error("The operation timed out.");
+	reason.name = "TimeoutError";
+	return reason;
+};
+/**
+* Links the callers' signals and a per-attempt deadline. `AbortSignal.any` holds its sources
+* weakly, so a long-lived caller signal doesn't collect a listener per streamed response;
+* runtimes without it get explicit listeners that `release` removes.
+*/
+const createAttemptSignal = (signals, timeoutMs) => {
+	const callers = signals.filter((signal) => signal !== void 0);
+	const deadline = new AbortController();
+	let timedOut = false;
+	let signal;
+	let onAbort;
+	if (typeof AbortSignal.any === "function") signal = AbortSignal.any([...callers, deadline.signal]);
+	else {
+		const controller = new AbortController();
+		signal = controller.signal;
+		onAbort = (event) => controller.abort(event.target.reason);
+		for (const source of [...callers, deadline.signal]) if (source.aborted) controller.abort(source.reason);
+		else source.addEventListener("abort", onAbort, { once: true });
+	}
+	let timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
+		timedOut = true;
+		deadline.abort(timeoutReason());
+	}, timeoutMs);
+	return {
+		signal,
+		isTimedOut: () => timedOut,
+		isCancelled: () => callers.some((caller) => caller.aborted),
+		clearDeadline: () => {
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+		},
+		release: () => {
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+			if (onAbort) for (const caller of callers) caller.removeEventListener("abort", onAbort);
+		}
+	};
+};
+/**
+* A redirect the SDK must not follow: it would send the API key to another origin. Browsers report
+* a manual redirect as an opaque response; other runtimes return the 3xx with its Location.
+*/
+const isRedirect = (response) => response.type === "opaqueredirect" || response.status >= 300 && response.status < 400 && response.headers.has("location");
+/** Turns anything thrown while sending or reading a request into a `CalmLensError`. */
+const toFailure = (cause, attempt) => {
+	if (require_CalmLensError.CalmLensError.isCalmLensError(cause)) return cause;
+	if (attempt.isCancelled()) return new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.CANCELLED, {
+		message: "Request cancelled",
+		cause
+	});
+	if (attempt.isTimedOut()) return new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.TIMEOUT, {
+		message: "Request timed out",
+		cause
+	});
+	return new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.TRANSPORT_ERROR, {
+		message: "Request failed",
+		cause
+	});
+};
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+	if (signal?.aborted) {
+		reject(new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.CANCELLED, { message: "Request cancelled" }));
+		return;
+	}
+	const onAbort = () => {
+		clearTimeout(timer);
+		reject(new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.CANCELLED, { message: "Request cancelled" }));
+	};
+	const timer = setTimeout(() => {
+		signal?.removeEventListener("abort", onAbort);
+		resolve();
+	}, ms);
+	signal?.addEventListener("abort", onAbort, { once: true });
+});
+/** Exponential backoff with jitter: half the delay is fixed, the other half random. */
+const getRetryDelayMs = (attempt, random = Math.random) => {
+	const delay = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
+	return Math.round(delay / 2 + random() * (delay / 2));
+};
+/** Parses `Retry-After` as seconds or an HTTP date, in seconds from `now`. */
+const parseRetryAfter = (value, now = Date.now()) => {
+	if (!value) return void 0;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) return Number(trimmed);
+	const date = Date.parse(trimmed);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, Math.ceil((date - now) / 1e3));
+};
+/** Bodies that can be sent again unchanged. Streams are consumed by the first attempt. */
+const isReplayableBody = (body) => body === void 0 || body === null || typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof URLSearchParams;
+const isApiErrorPayload = (value) => !!value && typeof value === "object" && typeof value.code === "string";
+/** Reads at most `limit` bytes of a body, failing with `sdk/response-too-large` beyond that. */
+const readBody = async (response, limit) => {
+	const declared = Number(response.headers.get("content-length"));
+	const tooLarge = () => new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.RESPONSE_TOO_LARGE, {
+		message: `Response body exceeds ${limit} bytes`,
+		status: response.status,
+		requestId: response.headers.get("x-request-id") ?? void 0,
+		headers: response.headers
+	});
+	if (Number.isFinite(declared) && declared > limit) {
+		await response.body?.cancel().catch(() => {});
+		throw tooLarge();
+	}
+	if (!response.body) return /* @__PURE__ */ new Uint8Array(0);
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > limit) {
+			await reader.cancel().catch(() => {});
+			throw tooLarge();
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+};
+const responseInfo = (response) => ({
+	status: response.status,
+	requestId: response.headers.get("x-request-id") ?? void 0,
+	headers: response.headers,
+	retryAfter: parseRetryAfter(response.headers.get("retry-after"))
+});
+/** The `CalmLensError` for a non-2xx response whose body has been read. */
+const toHttpError = (response, bytes) => {
+	let data;
+	try {
+		data = JSON.parse(new TextDecoder().decode(bytes));
+	} catch {}
+	if (isApiErrorPayload(data)) {
+		const { code, message, details, traceId } = data;
+		return new require_CalmLensError.CalmLensError(code, {
+			message: message ?? code,
+			...responseInfo(response),
+			details: details || traceId ? {
+				...details,
+				...traceId ? { traceId } : {}
+			} : void 0
+		});
+	}
+	return new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.HTTP_ERROR, {
+		message: `HTTP ${response.status}`,
+		...responseInfo(response)
+	});
+};
+/** Sends requests with the client's credentials, deadlines, retries and response limits. */
+var CalmLensTransport = class {
+	constructor(settings) {
+		this.settings = settings;
+	}
+	headersFor(request) {
+		const headers = new Headers(request.init?.headers);
+		for (const [name, value] of Object.entries(request.headers ?? {})) headers.set(name, value);
+		if (!headers.has("accept") && request.deadline === "body") headers.set("accept", "application/json");
+		if (this.settings.apiKey) headers.set("x-api-key", this.settings.apiKey);
+		if (!require_src.isBrowserRuntime()) headers.set("user-agent", require_src.getUserAgent());
+		if (request.idempotencyKey) headers.set("idempotency-key", request.idempotencyKey);
+		return Object.fromEntries(headers.entries());
+	}
+	canRetry(request) {
+		return this.settings.maxRetries > 0 && (request.method === "GET" || request.method === "HEAD" || !!request.idempotencyKey) && isReplayableBody(request.body);
+	}
+	/**
+	* Sends a request and returns the response, retrying transport failures, 429, 502–504 and
+	* `idempotency/request-in-progress` when the request is safe to repeat. Non-2xx responses
+	* throw unless `allowHttpErrors` is set. Call `release` once the body has been read.
+	*/
+	async send(request, { allowHttpErrors = false } = {}) {
+		const fetchImpl = request.fetch ?? this.settings.fetch;
+		const retryable = this.canRetry(request);
+		const headers = this.headersFor(request);
+		for (let attemptNumber = 0;; attemptNumber++) {
+			const canRetryAgain = retryable && attemptNumber < this.settings.maxRetries;
+			const attempt = createAttemptSignal([this.settings.signal, request.init?.signal ?? void 0], request.timeoutMs);
+			let response;
+			try {
+				if (attempt.signal.aborted) throw attempt.signal.reason;
+				response = await fetchImpl(request.url, {
+					...request.init,
+					method: request.method,
+					headers,
+					body: request.body,
+					redirect: "manual",
+					signal: attempt.signal,
+					duplex: "half"
+				});
+				if (isRedirect(response)) {
+					await response.body?.cancel().catch(() => {});
+					throw new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.TRANSPORT_ERROR, { message: `Unexpected redirect (HTTP ${response.status})` });
+				}
+			} catch (cause) {
+				attempt.release();
+				const failure = toFailure(cause, attempt);
+				if (canRetryAgain && failure.code === require_CalmLensError.SDK_ERROR_CODES.TRANSPORT_ERROR) {
+					await sleep(getRetryDelayMs(attemptNumber), this.settings.signal);
+					continue;
+				}
+				throw failure;
+			}
+			if (request.deadline === "headers") attempt.clearDeadline();
+			if (response.ok) return {
+				response,
+				attempt
+			};
+			if (allowHttpErrors) {
+				const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+				const delayMs = retryAfter !== void 0 ? retryAfter * 1e3 : getRetryDelayMs(attemptNumber);
+				if (!canRetryAgain || !RETRYABLE_STATUSES.has(response.status) || delayMs > RETRY_AFTER_MAX_MS) return {
+					response,
+					attempt
+				};
+				attempt.release();
+				await response.body?.cancel().catch(() => {});
+				await sleep(delayMs, this.settings.signal);
+				continue;
+			}
+			let error;
+			try {
+				error = toHttpError(response, await readBody(response, this.settings.maxResponseBytes));
+			} catch (cause) {
+				error = toFailure(cause, attempt);
+			} finally {
+				attempt.release();
+			}
+			const retryDelayMs = error.retryAfter !== void 0 ? error.retryAfter * 1e3 : getRetryDelayMs(attemptNumber);
+			if (canRetryAgain && retryDelayMs <= RETRY_AFTER_MAX_MS && (error.status !== void 0 && RETRYABLE_STATUSES.has(error.status) || error.code === require_CalmLensError.API_ERROR_CODES.IDEMPOTENT_REQUEST_IN_PROGRESS)) {
+				await sleep(retryDelayMs, this.settings.signal);
+				continue;
+			}
+			throw error;
+		}
+	}
+	/** Sends a request and parses its JSON response body. */
+	async json(request) {
+		const { response, attempt } = await this.send(request);
+		try {
+			const bytes = await readBody(response, this.settings.maxResponseBytes);
+			if (bytes.byteLength === 0 && (response.status === 204 || request.method === "DELETE")) return;
+			try {
+				return JSON.parse(new TextDecoder().decode(bytes));
+			} catch (cause) {
+				throw new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.INVALID_RESPONSE, {
+					message: `Invalid JSON response (HTTP ${response.status})`,
+					...responseInfo(response),
+					cause
+				});
+			}
+		} catch (cause) {
+			throw toFailure(cause, attempt);
+		} finally {
+			attempt.release();
+		}
+	}
+};
+//#endregion
+//#region src/client/CalmLensConnection.ts
+const DEFAULT_TIMEOUT_MS = 12e4;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RESPONSE_BYTES = 33554432;
+/**
+* Bytes as a fetch body. They're sent as they are rather than in a Blob: React Native can't
+* build a Blob from bytes, and every fetch accepts a Uint8Array.
+*/
+const toBodyBytes = (value) => value.buffer instanceof ArrayBuffer ? value : Uint8Array.from(value);
+const toRawUploadBody = (payload) => {
+	const data = require_CalmLensUtils.assetToData(payload);
+	if (data instanceof Response) {
+		if (!data.body) throw new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.INVALID_UPLOAD_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 toBodyBytes(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 (require_CalmLensUtils.isRejectedUploadMimeType(mimeType)) throw new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.INVALID_UPLOAD_MIME_TYPE, {
+		message: require_CalmLensUtils.getRejectedUploadMimeTypeError(mimeType),
+		details: { mimeType }
+	});
+};
+const isImageMimeType = (mimeType) => mimeType.toLowerCase().startsWith("image/");
+const invalidPayload = (message) => new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message });
+/** Checks upload options before anything is sent. */
+const prepareSubmitAssetOptions = (options) => {
+	if (!options || typeof options !== "object") throw require_CalmLensError.invalidArgument("Asset options are required");
+	if (!("content" in options) && !("url" in options) && !("part" in options)) throw invalidPayload("Either file content, URL, or multipart part is required");
+	if (!options.name) throw invalidPayload("Asset name is required");
+	if (!("part" in options) && "isFinal" in options) throw invalidPayload("isFinal is only valid for multipart uploads");
+	if ("part" in options && options.part.partNumber && options.part.partNumber > 1) throw new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.USE_UPLOAD_PART, { message: "Use uploadPart for multipart upload parts after the first part" });
+	if ("content" in options) {
+		assertValidUploadMimeType(options.content.type);
+		if (!("plainText" in options.content)) {
+			const validation = require_CalmLensUtils.validateAssetPayload(options.content);
+			if (!validation.ok) throw invalidPayload(validation.error);
+		}
+	}
+	if ("part" in options) {
+		assertValidUploadMimeType(options.part.type);
+		const partSizeInBytes = options.part.sizeInBytes ?? require_CalmLensUtils.getAssetPayloadByteLength(options.part);
+		if (isImageMimeType(options.part.type) && partSizeInBytes !== void 0) {
+			if (partSizeInBytes > require_CalmLensUtils.MAX_IMAGE_UPLOAD_BYTES) throw new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.MULTIPART_IMAGE_TOO_LARGE, { message: "Multipart image uploads cannot exceed 20MB." });
+			if (options.part.isFinal && partSizeInBytes < require_CalmLensUtils.MIN_MULTIPART_IMAGE_UPLOAD_BYTES) throw new require_CalmLensError.CalmLensError(require_CalmLensError.API_ERROR_CODES.MULTIPART_IMAGE_TOO_SMALL, { message: "Multipart image uploads must total at least 10MB." });
+		}
+		const validation = require_CalmLensUtils.validateAssetPayload(options.part, {
+			multipart: true,
+			isFinal: options.part.isFinal
+		});
+		if (!validation.ok) throw invalidPayload(validation.error);
+	}
+	return options;
+};
+const newIdempotencyKey = () => require_CalmLensUtils.randomUuid();
+/** Text content is small, so it keeps the API deadline; binary files may be arbitrarily large. */
+const isTextPayload = (payload) => "plainText" in payload;
+const isAsset = (data) => !!data && typeof data === "object" && typeof data.id === "string" && !!data.id && typeof data.status === "string";
+const isUploadedAsset = (data) => !!data && typeof data === "object" && typeof data.id === "string" && !!data.id;
+const expectUploadedAsset = (data) => {
+	if (!isUploadedAsset(data)) throw new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.INVALID_RESPONSE, {
+		message: "Expected an uploaded asset response",
+		status: 200
+	});
+	return data;
+};
+const expectAsset = (data) => {
+	if (!isAsset(data)) throw new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.INVALID_RESPONSE, {
+		message: "Expected an asset response",
+		status: 200
+	});
+	return data;
+};
+/** Fills in the default API base URL and drops trailing slashes. */
+const resolveConnectionOptions = (options) => ({
+	...options,
+	baseUrl: (options.baseUrl ?? `https://api.calmlens.com/v1`).replace(/\/+$/, "")
+});
+/** One client's transport, base URL and deadlines, and the requests both clients make. */
+var CalmLensConnection = class {
+	constructor(options, apiKey) {
+		this.options = options;
+		const resolveFetch = () => {
+			const fetchImpl = this.options.fetch ?? globalThis.fetch;
+			if (typeof fetchImpl !== "function") throw new require_CalmLensError.CalmLensError(require_CalmLensError.SDK_ERROR_CODES.NO_FETCH, { message: "No fetch implementation is available; pass one as the fetch option" });
+			return fetchImpl;
+		};
+		this.transport = new CalmLensTransport({
+			apiKey,
+			fetch: ((input, init) => resolveFetch()(input, init)),
+			signal: options.signal,
+			maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+			maxResponseBytes: options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES
+		});
+	}
+	get timeoutMs() {
+		return this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+	url(path, query) {
+		const search = query ? require_CalmLensUtils.stringifyQuery(query) : "";
+		return `${this.options.baseUrl}${path}${search ? `?${search}` : ""}`;
+	}
+	/** A JSON request whose deadline covers reading the response. */
+	json(method, path, { query, body, headers, idempotencyKey } = {}) {
+		return this.transport.json({
+			method,
+			url: this.url(path, query),
+			headers: body === void 0 ? headers : {
+				...headers,
+				"Content-Type": "application/json"
+			},
+			body: body === void 0 ? void 0 : JSON.stringify(body),
+			idempotencyKey,
+			timeoutMs: this.timeoutMs,
+			deadline: "body"
+		});
+	}
+	upload(url, payload, headers, idempotencyKey) {
+		return this.transport.json({
+			method: "POST",
+			url,
+			headers,
+			body: toRawUploadBody(payload),
+			idempotencyKey,
+			timeoutMs: isTextPayload(payload) ? this.timeoutMs : this.options.uploadTimeoutMs,
+			deadline: "body",
+			fetch: this.options.uploadFetch
+		});
+	}
+	/**
+	* Uploads file content or a first multipart part to `uploadsPath` (`.../assets`), as raw
+	* bytes with the options in the query.
+	*/
+	submitRawUpload(uploadsPath, options, queue, authHeaders = {}) {
+		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);
+		setOptionalQueryValue(query, "uploadPresetId", options.uploadPresetId);
+		const isMultipart = "part" in options;
+		const payload = isMultipart ? options.part : options.content;
+		query.set("contentType", payload.type);
+		setOptionalQueryValue(query, "sizeInBytes", payload.sizeInBytes ?? require_CalmLensUtils.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);
+			setOptionalQueryValue(query, "totalSizeInBytes", multipartOptions.totalSizeInBytes);
+		}
+		const path = isMultipart ? "multipart-upload" : "upload";
+		return this.upload(this.url(`${uploadsPath}/${path}?${query}`), payload, {
+			...authHeaders,
+			"Content-Type": payload.type,
+			"X-CalmLens-Upload": isMultipart ? "part" : "content"
+		}, options.idempotencyKey ?? newIdempotencyKey());
+	}
+	/** Uploads the next part of a multipart upload to `partPath` (`.../assets/{id}/part`). */
+	uploadPart(partPath, { part, queue, idempotencyKey }, authHeaders = {}) {
+		if (!part) throw require_CalmLensError.invalidArgument("Part options are required");
+		const validation = require_CalmLensUtils.validateAssetPayload(part, {
+			multipart: true,
+			isFinal: part.isFinal
+		});
+		if (!validation.ok) throw invalidPayload(validation.error);
+		const query = new URLSearchParams({
+			partNumber: String(part.partNumber),
+			isFinal: String(part.isFinal ?? false)
+		});
+		if (queue !== void 0) query.set("queue", String(queue));
+		setOptionalQueryValue(query, "sizeInBytes", part.sizeInBytes ?? require_CalmLensUtils.getAssetPayloadByteLength(part));
+		return this.upload(this.url(`${partPath}?${query}`), part, {
+			...authHeaders,
+			"X-CalmLens-Upload": "part"
+		}, idempotencyKey ?? newIdempotencyKey());
+	}
+};
+//#endregion
+Object.defineProperty(exports, "CalmLensConnection", {
+	enumerable: true,
+	get: function() {
+		return CalmLensConnection;
+	}
+});
+Object.defineProperty(exports, "expectAsset", {
+	enumerable: true,
+	get: function() {
+		return expectAsset;
+	}
+});
+Object.defineProperty(exports, "expectUploadedAsset", {
+	enumerable: true,
+	get: function() {
+		return expectUploadedAsset;
+	}
+});
+Object.defineProperty(exports, "invalidPayload", {
+	enumerable: true,
+	get: function() {
+		return invalidPayload;
+	}
+});
+Object.defineProperty(exports, "newIdempotencyKey", {
+	enumerable: true,
+	get: function() {
+		return newIdempotencyKey;
+	}
+});
+Object.defineProperty(exports, "prepareSubmitAssetOptions", {
+	enumerable: true,
+	get: function() {
+		return prepareSubmitAssetOptions;
+	}
+});
+Object.defineProperty(exports, "resolveConnectionOptions", {
+	enumerable: true,
+	get: function() {
+		return resolveConnectionOptions;
+	}
+});