@calmlens/sdk 0.9.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CalmLens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,9 @@ CalmLens provides content moderation and classification for text, images, docume
 npm install @calmlens/sdk
 ```
 
-Requires Node.js 22 or later (the minimum its dependencies support), or another runtime with `fetch`, Web Crypto and `AbortSignal.any`, such as Bun or Deno.
+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.
+
+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).
 
 Every public SDK operation accepts one options object. This keeps call sites stable as optional fields are added.
 
@@ -71,12 +73,16 @@ new CalmLensClient(options: CalmLensClientOptions)
 - `projectId` (string, required): Your CalmLens project ID
 - `baseUrl` (string, optional): API base URL (defaults to `https://api.calmlens.com/v1`)
 - `cdnBaseUrl` (string, optional): CDN base URL (defaults to `https://cdn.calmlens.com/v1`)
-- `timeoutMs` (positive integer, optional): Deadline for each request, including reading the response body (defaults to `120000`)
+- `fetch` (optional): The `fetch` implementation for every request, for example one with a proxy or instrumentation. Defaults to the global `fetch`
+- `uploadFetch`, `cdnFetch` (optional): Override `fetch` for content uploads or for `cdn.serve` only
+- `timeoutMs` (positive integer, optional): Deadline for each API request attempt, including reading the response body (defaults to `120000`). For `cdn.serve` it ends when response headers arrive
+- `uploadTimeoutMs` (positive integer, optional): Deadline for each binary upload attempt. Unset by default, so large files are never cut off; text content uses `timeoutMs`
+- `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
-- `uploadFetch`, `cdnFetch` (optional): `fetch` implementations for content uploads and CDN requests
-- `requestBackend` (optional): An `api-def` request backend for the JSON API, for example `new FetchRequestBackend(customFetch)`
+- `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
 
-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`.
+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`.
 
 #### Methods
 
@@ -223,6 +229,14 @@ result.items.forEach(asset => {
 });
 ```
 
+To read every matching asset, iterate instead of paging by hand. Pages are fetched as you go; assets created or deleted meanwhile can shift pages, so one may be skipped or repeated.
+
+```typescript
+for await (const asset of client.assets.iterate({ filter: "status==rejected", pageSize: 100 })) {
+  console.log(asset.id);
+}
+```
+
 ##### assets.listChildren(options)
 
 List assets extracted from a website or multimedia document.
@@ -233,6 +247,10 @@ const children = await client.assets.listChildren({
   pageIndex: 0,
   pageSize: 20,
 });
+
+for await (const child of client.assets.iterateChildren({ assetId: parentAssetId })) {
+  console.log(child.name);
+}
 ```
 
 ##### assets.createSignedUrl(options)
@@ -362,12 +380,16 @@ const response = await client.cdn.serve({
 });
 ```
 
+`serve` returns the `Response` as soon as headers arrive, so you can stream the body (for example `return new Response(response.body, response)`); `timeoutMs` covers only the wait for headers. Non-2xx responses are returned rather than thrown. Pass `init` for extra `fetch` options such as `method: "HEAD"`.
+
 Private CDN content cannot be read directly with API keys. Use a short-lived signed URL for application clients.
 
 ##### Multipart upload flow
 
 Use `create` with `part` to start multipart uploads, and `uploadPart` for subsequent chunks. `partNumber` defaults to `1` and `isFinal` defaults to `false` when starting an upload.
 
+The queue mode is chosen when the upload starts and saved by CalmLens: an upload started with `create` is queued when its final part arrives, one started with `moderate` waits for the decision. Later parts can come from another process that only knows the asset ID. Pass `queue` to `uploadPart` to override the saved choice for the final part. Pass `totalSizeInBytes` when you start the upload if you know the file's size, so CalmLens rejects an upload that could never finish before you send the rest.
+
 Image upload sizes use distinct direct and multipart paths:
 
 - Direct image uploads must be smaller than `10MB`.
@@ -376,7 +398,7 @@ Image upload sizes use distinct direct and multipart paths:
 
 Each non-final multipart part must be at least `5MiB`; only the final part may be smaller. If you send base64, split the original bytes first, then base64-encode each part. Do not split one full base64 string into substrings.
 
-Payloads can be sent as `{ plainText: string }` (text content only), `{ base64: string }`, `{ uint8Array: number[] | Uint8Array }`, `{ buffer: Buffer | ArrayBuffer }`, `{ data: Blob | Response | ReadableStream }`. Use `{ data: file }` for `File` objects. Upload metadata is URL query data and the SDK sends the binary payload as the raw request body without constructing multipart form data. Multipart `ReadableStream` uploads must include the exact `sizeInBytes` so CalmLens can stream each part without buffering it.
+Payloads can be sent as `{ plainText: string }` (text content only), `{ base64: string }`, `{ uint8Array: number[] | Uint8Array }`, `{ buffer: Buffer | ArrayBuffer }`, `{ data: Blob | Response | ReadableStream }`. Use `{ data: file }` for `File` objects. To upload a file from disk in Node.js without reading it into memory, pass `{ data: await openAsBlob(path), type }` (`openAsBlob` from `node:fs`); unlike a stream, a `Blob` can be sent again if a retry is needed. Upload metadata is URL query data and the SDK sends the binary payload as the raw request body without constructing multipart form data. Multipart `ReadableStream` uploads must include the exact `sizeInBytes` so CalmLens can stream each part without buffering it.
 
 Use a concrete asset MIME type such as `image/png`, `application/pdf`, or `text/plain`. The SDK rejects ambiguous/container request MIME types such as `application/octet-stream` and `multipart/*`.
 
@@ -425,37 +447,21 @@ console.log(analyzed.status);
 
 ##### verifyWebhookSignature(options)
 
-Verify that a webhook delivery came from CalmLens and is fresh. Also exported as a standalone `verifyWebhookSignature` function.
+Verify that a webhook delivery came from CalmLens and is fresh. Also exported as a standalone `verifyWebhookSignature` function; see [Webhooks](#webhooks) for `parseWebhookEvent`, which verifies and parses in one step.
 
 ```typescript
 static async verifyWebhookSignature(options: {
-  payload: string | object;        // raw request body (pass the string, not parsed JSON)
-  signature: string | null | undefined; // x-calmlens-signature header
-  timestamp: string | number | null | undefined; // x-calmlens-timestamp header
+  payload: string | Uint8Array | ArrayBuffer; // the raw request body (a Buffer works too)
+  signature?: string | null;          // x-calmlens-signature header
+  timestamp?: string | number | null; // x-calmlens-timestamp header
+  headers?: Headers | Record<string, string | string[] | undefined>; // read when signature/timestamp are omitted
   secret: string;
-  toleranceSeconds?: number;       // default 300
-  now?: Date | number;             // default Date.now(), for tests
+  toleranceSeconds?: number;          // default WEBHOOK_SIGNATURE_TOLERANCE_SECONDS (300)
+  now?: Date | number;                // default Date.now(), for tests
 }): Promise<boolean>
 ```
 
-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.
-
-**Example:**
-```typescript
-// In your webhook handler (Fetch API Request)
-const payload = await request.text();
-const isValid = await CalmLensClient.verifyWebhookSignature({
-  payload,
-  signature: request.headers.get('x-calmlens-signature'),
-  timestamp: request.headers.get('x-calmlens-timestamp'),
-  secret: WEBHOOK_SECRET,
-});
-
-if (!isValid) {
-  return new Response('Unauthorized', { status: 401 });
-}
-const event: WebhookEventPayload = JSON.parse(payload);
-```
+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.
 
 ## Asset Types
 
@@ -499,26 +505,74 @@ See the [moderation report guide](https://calmlens.com/docs/guides/moderation-re
 
 ## Error Handling
 
-The SDK throws errors for common issues:
+Every failure is a `CalmLensError`, whether the API returned an error or the request never completed. Branch on its stable `code`:
 
 ```typescript
+import { CALMLENS_ERROR_CODES, CalmLensError } from "@calmlens/sdk";
+
 try {
-  const asset = await client.assets.create({
-    name: "test.jpg",
-    // Missing required content, URL, or multipart part
-  });
+  await client.assets.retrieve({ assetId });
 } catch (error) {
-  console.error(error.message); // "Either file content, URL, or multipart part is required"
+  if (!CalmLensError.isCalmLensError(error)) throw error;
+  if (error.code === CALMLENS_ERROR_CODES.ASSET_NOT_FOUND) return undefined;
+  console.error(error.code, error.status, error.requestId, error.details);
+  throw error;
 }
 ```
 
-Public API failures are normalized to `CalmLensError`. Use its stable `code` property for control flow and `details` for diagnostics.
+| Property | Meaning |
+| --- | --- |
+| `code` | A stable identifier such as `asset/not-found` or `sdk/timeout`. `CALMLENS_ERROR_CODES` lists the documented ones |
+| `status` | The HTTP status, when the API responded |
+| `requestId` | The `X-Request-Id` response header. Include it when you contact support |
+| `headers` | The response headers, when the API responded |
+| `retryAfter` | Seconds to wait, from the `Retry-After` header (on `429` and `idempotency/request-in-progress`) |
+| `details` | Structured diagnostics from the API, such as validation issues and `traceId` |
+| `cause` | The underlying error, for transport failures |
+
+`error.isNotFound()` is true for `404`, and `error.isRetryable()` for transport failures, `429`, `502`, `503`, `504` and `idempotency/request-in-progress`. `instanceof CalmLensError` and `CalmLensError.isCalmLensError(error)` recognise errors from any copy of the SDK, including the ES module and CommonJS builds loaded side by side.
+
+Codes the SDK raises itself:
+
+| Code | Meaning |
+| --- | --- |
+| `sdk/invalid-argument` | A method argument is missing or invalid, for example an empty `assetId` |
+| `sdk/invalid-config` | The client options are invalid |
+| `sdk/transport-error` | The request could not be completed (DNS, TLS, refused or reset connections, truncated bodies, decompression errors) |
+| `sdk/timeout` | A deadline passed |
+| `sdk/cancelled` | Your `AbortSignal` cancelled the request |
+| `sdk/invalid-response` | A successful response whose body is not the expected JSON |
+| `sdk/http-error` | An HTTP failure without a CalmLens error body, for example from a proxy |
+| `sdk/response-too-large` | A response larger than `maxResponseBytes` |
+| `sdk/invalid-webhook-signature`, `sdk/invalid-webhook-payload` | Thrown by `parseWebhookEvent` |
+
+Upload content is checked before it is sent with the same codes the API uses, such as `upload/invalid-payload` and `upload/invalid-mime-type`.
+
+## Retries and idempotency
+
+The client retries a request when repeating it is safe: reads (`GET`), and creates and uploads, which always carry an `Idempotency-Key` header. It retries failures that happened before any response, `429`, `502`, `503`, `504` and `idempotency/request-in-progress`, up to `maxRetries` times (default 2) with jittered exponential backoff, waiting for `Retry-After` when the API sends one (up to 60 seconds; longer waits are returned to you as the error's `retryAfter`). Other writes, such as `assets.move`, and uploads of a `ReadableStream`, which the first attempt consumed, are never retried.
+
+`assets.create`, `assets.moderate`, `text.moderate` and `assets.uploadPart` generate a new key for each call and reuse it for their own retries, so a retry returns the original response instead of creating a second asset. To retry safely across processes or restarts, pass your own key:
+
+```typescript
+await client.text.moderate({
+  text: comment.body,
+  externalId: `comment-${comment.id}`,
+  idempotencyKey: `comment-${comment.id}`,
+});
+```
+
+The API keeps a response for 24 hours. Reusing a key for a different request fails with `idempotency/key-reused`.
+
+## Forward compatibility
+
+The SDK does not validate responses against its types, so fields and values added to the API later reach your code unchanged. `AssetStatus`, `AssetType` and `AssetVisibility` include `string` for that reason: handle values you don't know (for example, treat an unknown status as "not ready"). Event types and fact keys are typed for the ones this version knows; keep a default branch when you switch on them.
 
 ## Testing
 
-`@calmlens/sdk/testing` exports a matching object-parameter `MockCalmLensClient`, in-memory storage implementations, and mock API key helpers for local unit testing without network requests.
+`@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.
 
-The main `@calmlens/sdk` entry point does not load or export testing helpers to keep production bundles minimal. Keep `/testing` imports in test files.
+The main `@calmlens/sdk` entry point does 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";
@@ -531,6 +585,8 @@ const client = new MockCalmLensClient({
 
 `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`).
 
+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
@@ -543,6 +599,17 @@ await postComment(client, "hello");
 expect(client.callsTo("text.moderate")[0]?.options).toMatchObject({ text: "hello" });
 ```
 
+To test a webhook handler, build a signed delivery the way CalmLens sends it:
+
+```typescript
+import { createWebhookHeaders, toWebhookEventPayload } from "@calmlens/sdk/testing";
+
+const event = client.enqueueEvent({ type: "asset.classified", assetId: asset.id });
+const body = JSON.stringify(toWebhookEventPayload(event));
+const headers = await createWebhookHeaders({ secret, body, deliveryId: "delivery-1" });
+const response = await app.request("/api/webhooks/calmlens", { method: "POST", body, headers });
+```
+
 For `mockOptions`, deterministic timestamps and IDs, storage inspection, and testing recipes, see the [JavaScript SDK Testing Guide](https://calmlens.com/docs/sdk/javascript/testing).
 
 ## Webhooks
@@ -574,23 +641,53 @@ Each delivery has these headers (the names are exported as constants):
 | `x-calmlens-timestamp` | `WEBHOOK_TIMESTAMP_HEADER` | Unix time in seconds when the delivery was signed |
 | `x-calmlens-signature` | `WEBHOOK_SIGNATURE_HEADER` | `v1=<lowercase hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>` |
 
+Verify the exact raw request body before parsing it; re-serializing parsed JSON can change the signed bytes. `parseWebhookEvent` verifies the delivery and returns the parsed event, or throws `sdk/invalid-webhook-signature` (bad signature or a timestamp more than `WEBHOOK_SIGNATURE_TOLERANCE_SECONDS`, 5 minutes, from your clock, which stops replays) or `sdk/invalid-webhook-payload`. `verifyWebhookSignature` takes the same options and returns a boolean. Both accept the body as a string, `Uint8Array`/`Buffer` or `ArrayBuffer`, and read the two headers from `headers` (a `Headers` object or Node's `req.headers`) when you don't pass `signature` and `timestamp`.
+
+The result is typed as `WebhookEventPayload`; narrow it on `type` to get that event type's typed `data.facts` (`EventType` and `EventFacts<Type>` are exported too, and [the webhooks guide](https://calmlens.com/docs/guides/webhooks#event-types) lists every type). Deliveries are retried, so make your handler idempotent by `event.id`.
+
+**Fetch API** (Next.js route handlers, Remix, Cloudflare Workers, Bun, Deno):
+
 ```typescript
-import {
-  verifyWebhookSignature,
-  WEBHOOK_SIGNATURE_HEADER,
-  WEBHOOK_TIMESTAMP_HEADER,
-} from "@calmlens/sdk";
+import { CalmLensError, parseWebhookEvent } from "@calmlens/sdk";
+
+export async function POST(request: Request) {
+  let event;
+  try {
+    event = await parseWebhookEvent({
+      payload: await request.text(),
+      headers: request.headers,
+      secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+    });
+  } catch (error) {
+    if (CalmLensError.isCalmLensError(error)) return new Response("Invalid delivery", { status: 401 });
+    throw error;
+  }
+  // Queue the work, keyed by event.id, then respond quickly.
+  return new Response(null, { status: 204 });
+}
+```
+
+**Express**: use `express.raw()` for this route so `req.body` is the unparsed `Buffer`:
 
-const payload = await request.text();
-const valid = await verifyWebhookSignature({
-  payload,
-  signature: request.headers.get(WEBHOOK_SIGNATURE_HEADER),
-  timestamp: request.headers.get(WEBHOOK_TIMESTAMP_HEADER),
-  secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+```typescript
+app.post("/api/webhooks/calmlens", express.raw({ type: "application/json" }), async (req, res) => {
+  try {
+    const event = await parseWebhookEvent({
+      payload: req.body,
+      headers: req.headers,
+      secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+    });
+    // ...
+    res.sendStatus(204);
+  } catch {
+    res.sendStatus(401);
+  }
 });
 ```
 
-Verify the exact raw request body with `verifyWebhookSignature` before parsing it; re-serializing parsed JSON can change the signed bytes. Deliveries more than 5 minutes old (or ahead of your clock) are rejected to prevent replays. The body type is exported as `WebhookEventPayload`; narrow it on `type` to get that event type's typed `data.facts` (`EventType` and `EventFacts<Type>` are exported too, and [the webhooks guide](https://calmlens.com/docs/guides/webhooks#event-types) lists every type).
+**Hono**: `payload: await c.req.text()`, `headers: c.req.raw.headers`.
+
+**Fastify**: register a raw body parser for the route, for example `fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => done(null, body))`, then pass `payload: request.body` and `headers: request.headers`.
 
 ## Command-line tool
 
@@ -621,19 +718,18 @@ The same feed is available in code with [`events.list`](#events-feed).
 - Keep passing the latest `cursor` as `after` until `hasMore` is `false`, then wait before polling again. Store the cursor if you want to resume after a restart.
 - An unknown or malformed cursor fails with the `CalmLensError` code `events/invalid-cursor`.
 
+`client.events.pages({ after, limit })` follows the cursor for you: it yields each page until no more events are waiting.
+
 ```typescript
 let { cursor } = await client.events.list(); // no events, cursor = "now"
 
 async function drainEvents() {
-  let hasMore = true;
-  while (hasMore) {
-    const page = await client.events.list({ after: cursor, limit: 100 });
+  for await (const page of client.events.pages({ after: cursor, limit: 100 })) {
     for (const event of page.events) {
       // narrow on event.type to read its typed facts
       console.log(event.type, event.facts);
     }
-    cursor = page.cursor;
-    hasMore = page.hasMore;
+    cursor = page.cursor; // save it to resume after a restart
   }
 }
 
@@ -642,13 +738,13 @@ setInterval(drainEvents, 5_000);
 
 Events carry `facts: { key, value, url? }[]`; webhook deliveries carry the same events reshaped as `{ id, type, createdAt, projectId, data }`.
 
-## Request budgets and errors
+## Request budgets
 
-Set `timeoutMs` (default 120000) or `signal` on the client. Use `client.withRequestOptions({ signal, timeoutMs: 30000 })` to scope them to an operation without changing the original client. Multipart state is shared between scoped clients. Deadlines include response-body reads; authenticated default REST, upload and CDN requests reject redirects. Custom non-Fetch backends own their redirect/cancellation policies.
+Set `timeoutMs` (default 120000), `uploadTimeoutMs`, `maxRetries` or `signal` on the client. Use `client.withRequestOptions({ signal, timeoutMs: 30000 })` to scope them to an operation without changing the original client; the scoped client shares the original's credentials and lens cache. `timeoutMs` applies to each attempt and includes reading the response body; binary uploads have no deadline unless you set `uploadTimeoutMs`, and `cdn.serve`'s deadline ends when headers arrive, so large transfers are never cut off. Requests never follow redirects, so the API key is never sent to another origin.
 
-`CalmLensError` exposes `code`, optional HTTP `status`, `details` and native `cause`. Every failure to complete a request (DNS, TLS, refused or reset connections, truncated bodies, decompression errors) is `sdk/transport-error`, with the underlying error as `cause`; deadlines are `sdk/timeout`, cancellation `sdk/cancelled`, successful responses whose body is not the expected JSON `sdk/invalid-response`, and HTTP failures without an API error body `sdk/http-error`. `cdn.serve` returns the `Response` once headers arrive, so errors while you read its body come from your `fetch`. API error codes/messages are preserved. Core model types (`Asset`, `Folder`, `Lens`, `AssetPage`, `EventsPage`, `ClassificationReport`) and request types are exported from the package root.
+Requests send `User-Agent: calmlens-js/<version> (<runtime>/<version>)` from server runtimes; `SDK_VERSION` exports the version. Core model types (`Asset`, `Folder`, `Lens`, `AssetPage`, `EventsPage`, `ClassificationReport`) and request types are exported from the package root.
 
-`text.moderate` is a convenience wrapper around asset moderation: it supplies `text/plain` content and defaults the asset name to `text`. `assets.create` queues processing; `assets.moderate` waits for classification. The old asset analyze method is removed.
+`text.moderate` is a convenience wrapper around asset moderation: it supplies `text/plain` content and defaults the asset name to `text`. `assets.create` queues processing; `assets.moderate` waits for classification.
 
 ## Releasing