@calmlens/sdk 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,655 @@
-# Temporary Holding Version
+# @calmlens/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official JavaScript/TypeScript SDK for CalmLens API
+
+CalmLens provides content moderation and classification for text, images, documents and websites, plus optional storage and CDN delivery. This SDK makes it easy to integrate CalmLens into your JavaScript/TypeScript applications.
+
+## Installation
+
+```bash
+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.
+
+Every public SDK operation accepts one options object. This keeps call sites stable as optional fields are added.
+
+## Quick Start
+
+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";
+
+const client = new CalmLensClient({
+  apiKey: process.env.CALMLENS_API_KEY!,
+  projectId: process.env.CALMLENS_PROJECT_ID!,
+});
+
+// Text (comments, captions, bios): waits for the decision
+const comment = await client.text.moderate({ text: "Great photo!", externalId: "comment-42" });
+
+if (comment.status === "approved") {
+  // publish it; if comment.report?.flagged is true, also queue it for review
+} else {
+  // "rejected": don't publish it
+}
+
+// Images and documents: queued, resolved by webhook or assets.retrieve()
+const image = await client.assets.create({
+  name: "photo.jpg",
+  content: { data: file, type: "image/jpeg" },
+  externalId: "post-7",
+});
+console.log(image.status); // "pending"
+```
+
+| `status` | `report.flagged` | Meaning |
+| --- | --- | --- |
+| `approved` | `false` | Safe to show. |
+| `approved` | `true` | Show it, but your policy asked to be alerted. |
+| `rejected` | `true` | Your policy hid or purged it. Don't show it. |
+| `pending` | — | Still being classified. |
+| `error` | — | Processing failed. |
+
+See [How CalmLens works](https://calmlens.com/docs/how-it-works) and [Testing your integration](https://calmlens.com/docs/guides/testing) for test inputs that trigger rejections safely.
+
+## API Reference
+
+### CalmLensClient
+
+The main client class for interacting with the CalmLens API.
+
+#### Constructor
+
+```typescript
+new CalmLensClient(options: CalmLensClientOptions)
+```
+
+**Options:**
+- `apiKey` (string, required): Your CalmLens API key
+- `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`)
+- `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)`
+
+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`.
+
+#### Methods
+
+##### assets.create(options)
+
+Queue an asset for processing and return the created asset immediately.
+
+```typescript
+async assets.create(options: SubmitAssetOptions): Promise<Asset>
+```
+
+**Options:**
+- `name` (string, required): Name of the asset
+- `content` (optional): Binary or plain-text content and its concrete MIME type, e.g. `{ plainText: "hello", type: "text/plain" }` or `{ data: file, type: file.type }`
+- `url` (string, optional): External URL to fetch instead of sending content
+- `part` (optional): First part of a sequential multipart upload
+- `description` (string, optional): Description of the asset
+- `processingOptions.keepContentAfterProcessing` (boolean, optional): Retain content after processing
+- `visibility` (string, optional): "public" or "private"
+
+**Example:**
+```typescript
+// Submit from file content
+const asset = await client.assets.create({
+  name: "document.pdf",
+  content: {
+    base64: "JVBERi0xLjQKJcfs...",
+    type: "application/pdf",
+  },
+  description: "Important document",
+  visibility: "private"
+});
+
+// Submit from URL
+const asset = await client.assets.create({
+  name: "website-content",
+  url: "https://example.com/page",
+  description: "Web page to moderate"
+});
+```
+
+##### assets.moderate(options) and text.moderate(options)
+
+Submit an asset and wait for classification to finish. Accepts the same options as `assets.create()` for text, images, documents, and URLs. `text.moderate({ text, name?, externalId?, ... })` is a shortcut that sends `text` as `text/plain` content named `text` by default.
+
+```typescript
+async assets.moderate(options: SubmitAssetOptions): Promise<Asset>
+async text.moderate(options: ModerateTextOptions): Promise<Asset>
+```
+
+Both resolve to the stored `Asset`, a plain object with camelCase keys exactly as the API returns it:
+
+```typescript
+const asset = await client.text.moderate({ text: "Great photo!", externalId: "comment-42" });
+asset.id;            // string
+asset.status;        // "approved" | "rejected" | "error"; "pending" for audio and video, which always run in the background
+asset.type;          // "plaintext-document" for text
+asset.report?.flagged;                       // boolean
+asset.report?.score;                         // number, the overall score
+asset.report?.categories.harassment.status;  // "evaluated" | "partial" | "not-evaluated"
+asset.moderationAction;                      // the policy action applied, if any
+asset.createdAt;     // milliseconds since the Unix epoch
+```
+
+Always present: `id`, `projectId`, `name`, `type`, `status`, `createdAt` and `updatedAt`. Every other field may be `null` or missing: `report` is absent when processing failed (`status: "error"`) or has not finished, `moderationAction` when no policy action applied, `externalId`, `description`, `metadata`, `folderId`, `visibility` and `processingOptions` when you did not set them, and `sizeInBytes`, `fileFormat`, `imageData`, `documentData`, `previewImage` and `extractedText` when they do not apply to the content. Inside a report, a category's `score` and `likelihood` exist only when its `status` is `evaluated` or `partial` (see [Moderation Reports](#moderation-reports)).
+
+##### assets.retrieve(options)
+
+Retrieve details of a specific asset.
+
+```typescript
+async assets.retrieve(options: { assetId: string }): Promise<Asset>
+```
+
+**Example:**
+```typescript
+const asset = await client.assets.retrieve({ assetId: "asset-uuid-here" });
+console.log(asset.status);
+console.log(asset.report); // Classification results
+```
+
+##### ensureLens(options)
+
+Create a project-scoped named lens, or update it safely. A lens can start at any positive version. Repeating the exact same version and definition is idempotent; any other update must use a version greater than the current one. A stale or conflicting version throws `lens/version-conflict`.
+
+```typescript
+const lens = await client.ensureLens({
+  identifier: "picmagic-normal",
+  name: "PicMagic normal",
+  type: "image",
+  active: true,
+  version: 1,
+  transforms: [
+    {
+      type: "imageTransform",
+      options: { fit: "scale-down", width: 1024, format: "png" },
+    },
+  ],
+});
+
+const image = await client.cdn.serve({
+  assetIdentifier: assetId,
+  lens: lens.identifier,
+});
+```
+
+For several lenses, use `ensureLenses()` to perform all ensures in one request. Each lens keeps the same independent versioning rules.
+
+```typescript
+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.
+
+##### assets.list(options)
+
+List assets in your project with pagination.
+
+```typescript
+async assets.list(options: {
+  pageIndex?: number;
+  pageSize?: number;
+  ordering?: Array<{ field: string; direction: "ASC" | "DESC" }>;
+  filter?: string | null;
+}): Promise<{
+  items: Asset[];
+  total: number;
+  hasMore: boolean;
+  pageIndex: number;
+  pageSize: number;
+}>
+```
+
+**Example:**
+```typescript
+const result = await client.assets.list({
+  pageIndex: 0,
+  pageSize: 20
+});
+
+console.log(`Found ${result.total} assets`);
+result.items.forEach(asset => {
+  console.log(`${asset.name}: ${asset.status}`);
+});
+```
+
+##### assets.listChildren(options)
+
+List assets extracted from a website or multimedia document.
+
+```typescript
+const children = await client.assets.listChildren({
+  assetId: parentAssetId,
+  pageIndex: 0,
+  pageSize: 20,
+});
+```
+
+##### assets.createSignedUrl(options)
+
+Create a short-lived URL for private CDN content or previews.
+
+```typescript
+const signed = await client.assets.createSignedUrl({
+  assetId,
+  resource: "preview",
+  lens: "thumbnail",
+  expiresInSeconds: 900,
+});
+```
+
+##### assets.move(options)
+
+Move an asset into a folder, or to the project root by passing `null`.
+
+```typescript
+// Move asset to a folder
+await client.assets.move({
+  assetId: "asset-uuid",
+  folderId: "folder-uuid",
+});
+
+// Move asset to project root
+await client.assets.move({
+  assetId: "asset-uuid",
+  folderId: null,
+});
+```
+
+##### assets.retry(options)
+
+Process an asset that failed (status `error`) again. It returns to `pending` and is moderated like a
+new upload, so handle the result the same way (webhook or polling). Its content must still be stored:
+otherwise this throws `asset/content-unavailable`, and you need to upload it again.
+
+```typescript
+const asset = await client.assets.retry({ assetId: "asset-uuid" });
+// asset.status === "pending"
+```
+
+##### folders.list()
+
+List all folders in the current project.
+
+```typescript
+const folders = await client.folders.list();
+```
+
+##### folders.retrieve(options)
+
+Retrieve details of a specific folder by ID.
+
+```typescript
+const folder = await client.folders.retrieve({ folderId: "folder-uuid" });
+```
+
+##### folders.create(options)
+
+Create a folder at the project root or nested under another folder.
+
+```typescript
+// Create root folder
+const marketing = await client.folders.create({ name: "Marketing" });
+
+// Create nested subfolder
+const launch = await client.folders.create({
+  name: "Launch 2026",
+  parentId: marketing.id,
+});
+```
+
+##### folders.update(options)
+
+Rename an existing folder.
+
+```typescript
+const updated = await client.folders.update({
+  folderId: "folder-uuid",
+  name: "New Name",
+});
+```
+
+##### folders.move(options)
+
+Move a folder under another folder, or to the project root by passing `parentId: null`. Moving a folder into itself or a descendant throws `folder/parent-cycle`.
+
+```typescript
+// Move folder to another parent
+await client.folders.move({
+  folderId: child.id,
+  parentId: anotherParent.id,
+});
+
+// Move folder to project root
+await client.folders.move({
+  folderId: child.id,
+  parentId: null,
+});
+```
+
+##### folders.delete(options)
+
+Delete an empty folder. If the folder still contains assets or child folders, this throws `folder/not-empty`.
+
+```typescript
+await client.folders.delete({ folderId: "folder-uuid" });
+```
+
+##### cdn.getAssetUrl(options) and cdn.serve(options)
+
+`getAssetUrl` constructs a CDN URL without fetching it. `serve` fetches the resource and sends the client's API key.
+
+```typescript
+const url = client.cdn.getAssetUrl({
+  assetIdentifier: assetId,
+  resource: "content",
+  lens: "thumbnail",
+});
+
+const response = await client.cdn.serve({
+  assetIdentifier: assetId,
+  resource: "content",
+});
+```
+
+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.
+
+Image upload sizes use distinct direct and multipart paths:
+
+- Direct image uploads must be smaller than `10MB`.
+- Multipart image uploads must total between `10MB` and `20MB`, inclusive. CalmLens accumulates the uploaded parts and rejects a final image outside that range; callers do not need to provide a total-size field.
+- Retained multipart image originals remain in private backing storage. Public or authorized delivery and transformations use CalmLens CDN URLs.
+
+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.
+
+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/*`.
+
+**Example (queued finalization):**
+```typescript
+const uploading = await client.assets.create({
+  name: "large-image.png",
+  part: {
+    uint8Array: firstPartBytes,
+    type: "image/png"
+  }
+});
+
+await client.assets.uploadPart({
+  assetId: uploading.id,
+  part: {
+    base64: secondPartBase64,
+    partNumber: 2,
+  },
+});
+
+const completed = await client.assets.uploadPart({
+  assetId: uploading.id,
+  part: {
+    base64: finalPartBase64,
+    partNumber: 3,
+    isFinal: true,
+  },
+});
+```
+
+**Example (single-call synchronous analysis):**
+```typescript
+const analyzed = await client.assets.moderate({
+  name: "large-image.png",
+  part: {
+    base64: finalPartBase64,
+    type: "image/png",
+    isFinal: true
+  }
+});
+console.log(analyzed.status);
+```
+
+#### Static Methods
+
+##### verifyWebhookSignature(options)
+
+Verify that a webhook delivery came from CalmLens and is fresh. Also exported as a standalone `verifyWebhookSignature` function.
+
+```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
+  secret: string;
+  toleranceSeconds?: number;       // default 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);
+```
+
+## Asset Types
+
+Assets can be of the following types:
+- `image` - Images (JPEG, PNG, GIF, WebP, etc.)
+- `video` - Video files (MP4, WebM, etc.)
+- `audio` - Audio files (MP3, WAV, etc.)
+- `plaintext-document` - Plain-text formats such as TXT, JSON, CSV, and YAML
+- `multimedia-document` - Documents such as PDF, DOCX, DOC, RTF, and ODT
+- `website` - Web pages and URLs
+- `file` - Other supported binary files
+
+## Asset Status
+
+Assets progress through these statuses:
+- `uploading` - Multipart upload is accepting more parts
+- `pending` - Asset is being processed
+- `approved` - Processing completed and delivery is allowed; an `alert` action can still leave `report.flagged` set to `true`
+- `rejected` - A hide, purge, child-asset, or manual rejection decision was applied
+- `error` - Processing failed
+
+## Moderation Reports
+
+Completed reports always contain the six parent categories: `sexual`, `violence`, `self-harm`, `harassment`, `hate`, and `criminal-activity`. Category-specific detail is nested under `qualifiers`, for example `violence.qualifiers.graphic`. Reports have no `subcategories` field or dedicated minor-safety placeholder. Retired generic qualifier IDs are rejected.
+
+Always narrow on a category's `status` before reading `score`. An `evaluated` or `partial` result includes `score` and `likelihood`; a `not-evaluated` result includes a reason and represents unknown coverage, not a safe zero score.
+
+```typescript
+const violence = asset.report?.categories.violence;
+if (violence?.status === 'evaluated' || violence?.status === 'partial') {
+  console.log(violence.score);
+}
+```
+
+See the [moderation report guide](https://calmlens.com/docs/guides/moderation-reports) for aggregation, provider coverage, OCR merging, and policy actions. General Sexual Content moderation does not estimate age or provide dedicated CSAM detection.
+
+## Asset Visibility
+
+- `public` - Retained content can be requested directly from the CDN
+- `private` - Retained content requires a signed URL or an authenticated owner session
+
+## Error Handling
+
+The SDK throws errors for common issues:
+
+```typescript
+try {
+  const asset = await client.assets.create({
+    name: "test.jpg",
+    // Missing required content, URL, or multipart part
+  });
+} catch (error) {
+  console.error(error.message); // "Either file content, URL, or multipart part is required"
+}
+```
+
+Public API failures are normalized to `CalmLensError`. Use its stable `code` property for control flow and `details` for diagnostics.
+
+## 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.
+
+The main `@calmlens/sdk` entry point does not load or export testing helpers to keep production bundles minimal. Keep `/testing` imports in test files.
+
+```typescript
+import { MockCalmLensClient, createMockApiKey } from "@calmlens/sdk/testing";
+
+const client = new MockCalmLensClient({
+  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`).
+
+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 });
+
+client.failNextRequest("timeout", { operation: "text.moderate" });
+await expect(postComment(client, "hello")).rejects.toMatchObject({ code: "sdk/timeout" });
+
+await postComment(client, "hello");
+expect(client.callsTo("text.moderate")[0]?.options).toMatchObject({ text: "hello" });
+```
+
+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
+
+A `webhook` connector POSTs each event to your URL as JSON:
+
+```json
+{
+  "id": "…",
+  "type": "asset.flagged",
+  "createdAt": 1760000000000,
+  "projectId": "…",
+  "data": {
+    "severity": "high",
+    "title": "…",
+    "description": null,
+    "assetId": "…",
+    "asset": null,
+    "facts": [{ "key": "asset-name", "value": "photo.jpg" }]
+  }
+}
+```
+
+Each delivery has these headers (the names are exported as constants):
+
+| Header | Constant | Value |
+|---|---|---|
+| `x-calmlens-delivery` | `WEBHOOK_DELIVERY_HEADER` | Delivery ID (the same across retries) |
+| `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>")>` |
+
+```typescript
+import {
+  verifyWebhookSignature,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+} from "@calmlens/sdk";
+
+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!,
+});
+```
+
+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).
+
+## Command-line tool
+
+Install the standalone [CalmLens CLI](https://calmlens.com/docs/guides/local-development) through Homebrew, a platform download or npm. Webhook connectors must use public HTTPS URLs, so during development use it to forward events to a local handler instead. Each event is sent with the same body, headers and signature as a real delivery:
+
+```bash
+npx calmlens listen --forward-to http://localhost:3000/api/webhooks/calmlens --env-file .env.local
+```
+
+The CLI reads `CALMLENS_API_KEY`, `CALMLENS_PROJECT_ID` and `CALMLENS_WEBHOOK_SECRET` from the environment or `--env-file`; without a secret it prints a generated one for your app. `npx calmlens trigger [harassment|hate|criminal-activity|clean]` moderates a harmless test input so events appear (one upload each). Run `npx calmlens --help` for all options. To install the command globally, use `npm install -g calmlens`. The CLI is released separately from the SDK.
+
+The same feed is available in code with [`events.list`](#events-feed).
+
+## Events feed
+
+`client.events.list({ after?, limit? })` reads the project's events, oldest first, without a public webhook URL. It resolves to an `EventsPage`:
+
+```typescript
+{
+  events: TypedEvent[]; // { id, projectId, type, severity, title, description?, assetId?, asset?, facts, createdAt, updatedAt }
+  cursor: string;       // pass back as `after` to continue after the last event returned
+  hasMore: boolean;     // true when more events are already waiting after `cursor`
+}
+```
+
+- Without `after` (or with an empty string), it returns **no events** and a `cursor` for the current time, so you only see events created after you start reading. It does not return history.
+- With `after`, it returns up to `limit` events (default 50) created after that cursor. When there are none, `cursor` is the `after` you passed.
+- 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`.
+
+```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 (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;
+  }
+}
+
+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
+
+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.
+
+`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.
+
+`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.
+
+## Releasing
+
+Stable releases are published automatically from `main` when packed SDK contents differ from npm `latest` and an SDK Changeset is present. Contributors must run `bun run changeset` to choose the release type and write release notes. CI updates and commits this package's `CHANGELOG.md` automatically. See the repository's [.changeset release guide](../../.changeset/README.md).