@calmlens/sdk 0.5.0 → 0.6.0

package/README.md

@@ -10,6 +10,8 @@ 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.
+
 Every public SDK operation accepts one options object. This keeps call sites stable as optional fields are added.
 
 ## Quick Start
@@ -69,6 +71,12 @@ 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`)
+- `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
 
@@ -110,14 +118,31 @@ const asset = await client.assets.create({
 });
 ```
 
-##### assets.moderate(options)
+##### 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.
+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.
@@ -504,7 +529,21 @@ const client = new MockCalmLensClient({
 });
 ```
 
-For configuration options (`mockOptions`), deterministic timestamps and IDs, storage inspection, and testing recipes, see the [JavaScript SDK Testing Guide](https://calmlens.com/docs/sdk/javascript#testing).
+`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
 
@@ -516,40 +555,101 @@ A `webhook` connector POSTs each event to your URL as JSON:
   "type": "asset.flagged",
   "createdAt": 1760000000000,
   "projectId": "…",
-  "data": { "severity": "high", "title": "…", "description": null, "assetId": "…", "asset": null, "metadata": null }
+  "data": {
+    "severity": "high",
+    "title": "…",
+    "description": null,
+    "assetId": "…",
+    "asset": null,
+    "facts": [{ "key": "asset-name", "value": "photo.jpg" }]
+  }
 }
 ```
 
-Each delivery has these headers:
+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>")>` |
 
-| Header | Value |
-|---|---|
-| `x-calmlens-delivery` | Delivery ID (the same across retries) |
-| `x-calmlens-timestamp` | Unix time in seconds when the delivery was signed |
-| `x-calmlens-signature` | `v1=<lowercase hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>` |
+```typescript
+import {
+  verifyWebhookSignature,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+} from "@calmlens/sdk";
 
-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). The header names are exported as `WEBHOOK_SIGNATURE_HEADER`, `WEBHOOK_TIMESTAMP_HEADER` and `WEBHOOK_DELIVERY_HEADER`.
+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
 
-The SDK installs a `calmlens` command. 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:
+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 same package, published under a shorter name.
+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: `client.events.list({ after, limit })` returns events oldest first with a `cursor` to pass back.
+The same feed is available in code with [`events.list`](#events-feed).
 
-## Releasing
+## Events feed
 
-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).
+`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);
+```
 
-### Request budgets and errors
+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`. Transport failures use `sdk/transport-error`, deadlines `sdk/timeout`, cancellation `sdk/cancelled`, malformed successful uploads `sdk/invalid-response`, and unstructured HTTP failures `sdk/http-error`. API error codes/messages are preserved. Core model types (`Asset`, `Folder`, `Lens`, `AssetPage`, `EventsPage`, `ClassificationReport`) and request types are exported from the package root.
+`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).

package/cjs/{CalmLensTypes-DG_kHVqY.d.ts → CalmLensTypes-BpmT60j-.d.ts}

@@ -1245,6 +1245,7 @@ declare const ASSET_SCHEMA: zod.ZodObject<{
       audioTranscribed: zod.ZodBoolean;
       segments: zod.ZodArray<zod.ZodObject<{
         source: zod.ZodEnum<{
+          clip: "clip";
           frame: "frame";
           "frame-text": "frame-text";
           speech: "speech";
@@ -3518,4 +3519,4 @@ interface ModerateTextOptions extends Omit<SubmitAssetCommonOptions, "name" | "v
   name?: string;
 }
 //#endregion
-export { GetEventsResponse as A, EventFacts as B, UpdateAssetOptions as C, GetAssetChildrenResponse as D, VerifyWebhookSignatureOptions as E, Folder as F, AssetType as G, EventType as H, TypedEvent as I, ProcessingOptions as J, AssetVisibility as K, EventCategory as L, RequestErrorCode as M, AssetBinaryPayloadInput as N, GetAssetResponse as O, Lens as P, EventFact as R, SubmitAssetOptions as S, UploadAssetPartOptions as T, Asset as U, EventSeverity as V, AssetStatus as W, MultipartUploadOptions as _, CreateAssetSignedUrlOptions as a, RetrieveAssetOptions as b, EnsureLensOptions as c, ListAssetChildrenOptions as d, ListAssetsOptions as f, MoveFolderOptions as g, MoveAssetOptions as h, CdnServeOptions as i, PostAssetSignedUrlResponse as j, GetAssetsPageResponse as k, EnsureLensesOptions as l, ModerateTextOptions as m, CalmLensClientOptions as n, CreateFolderOptions as o, ListEventsOptions as p, MetadataItem as q, CdnAssetUrlOptions as r, CreateMultipartUploadPartOptions as s, AssetContentOptions as t, FolderIdOptions as u, MultipartUploadPartOptions as v, UpdateFolderOptions as w, RetryAssetOptions as x, RequestOptions as y, EventFactValues as z };
+export { GetEventsResponse as A, EventFactValues as B, UpdateAssetOptions as C, GetAssetChildrenResponse as D, VerifyWebhookSignatureOptions as E, Folder as F, AssetStatus as G, EventSeverity as H, Event as I, MetadataItem as J, AssetType as K, TypedEvent as L, RequestErrorCode as M, AssetBinaryPayloadInput as N, GetAssetResponse as O, Lens as P, EventCategory as R, SubmitAssetOptions as S, UploadAssetPartOptions as T, EventType as U, EventFacts as V, Asset as W, ProcessingOptions as Y, MultipartUploadOptions as _, CreateAssetSignedUrlOptions as a, RetrieveAssetOptions as b, EnsureLensOptions as c, ListAssetChildrenOptions as d, ListAssetsOptions as f, MoveFolderOptions as g, MoveAssetOptions as h, CdnServeOptions as i, PostAssetSignedUrlResponse as j, GetAssetsPageResponse as k, EnsureLensesOptions as l, ModerateTextOptions as m, CalmLensClientOptions as n, CreateFolderOptions as o, ListEventsOptions as p, AssetVisibility as q, CdnAssetUrlOptions as r, CreateMultipartUploadPartOptions as s, AssetContentOptions as t, FolderIdOptions as u, MultipartUploadPartOptions as v, UpdateFolderOptions as w, RetryAssetOptions as x, RequestOptions as y, EventFact as z };

package/cjs/{CalmLensUtils-0QaxbI3A.js → CalmLensUtils-DA1_j5-P.js}

@@ -417,6 +417,27 @@ function _objectWithoutProperties(e, t) {
 //#endregion
 //#region src/client/CalmLensUtils.ts
 const _excluded = ["text", "name"];
+const invalidOptions = (message) => calmLensError({ id: "upload/invalid-payload" }, { message });
+const assertHttpUrl = (name, value) => {
+	if (value === void 0) return;
+	let url;
+	try {
+		url = new URL(value);
+	} catch (_unused) {}
+	if (!url || url.protocol !== "https:" && url.protocol !== "http:") throw invalidOptions(`${name} must be an absolute http(s) URL`);
+};
+/**
+* Checks client options before the client sets anything up. `CalmLensClient` and
+* `MockCalmLensClient` share it so both reject the same configuration.
+*/
+const validateClientOptions = (options) => {
+	if (!options || typeof options !== "object") throw invalidOptions("Client options are required");
+	if (!options.apiKey) throw invalidOptions("API key is required");
+	if (!options.projectId) throw invalidOptions("Project ID is required");
+	if (options.timeoutMs !== void 0 && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) throw invalidOptions("timeoutMs must be a positive integer");
+	assertHttpUrl("baseUrl", options.baseUrl);
+	assertHttpUrl("cdnBaseUrl", options.cdnBaseUrl);
+};
 const toTextAssetOptions = (_ref) => {
 	let { text, name } = _ref, options = _objectWithoutProperties(_ref, _excluded);
 	if (typeof text !== "string" || !text.trim()) throw calmLensError(PUBLIC_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: "Text to moderate must be a non-empty string" });
@@ -549,3 +570,9 @@ Object.defineProperty(exports, "validateAssetPayload", {
 		return validateAssetPayload;
 	}
 });
+Object.defineProperty(exports, "validateClientOptions", {
+	enumerable: true,
+	get: function() {
+		return validateClientOptions;
+	}
+});

package/cjs/index.d.ts

@@ -1,4 +1,4 @@
-import { A as GetEventsResponse, B as EventFacts, C as UpdateAssetOptions, D as GetAssetChildrenResponse, E as VerifyWebhookSignatureOptions, F as Folder, G as AssetType, H as EventType, I as TypedEvent, J as ProcessingOptions, K as AssetVisibility, L as EventCategory, M as RequestErrorCode, O as GetAssetResponse, P as Lens, R as EventFact, S as SubmitAssetOptions, T as UploadAssetPartOptions, U as Asset, V as EventSeverity, W as AssetStatus, _ as MultipartUploadOptions, a as CreateAssetSignedUrlOptions, b as RetrieveAssetOptions, c as EnsureLensOptions, d as ListAssetChildrenOptions, f as ListAssetsOptions, g as MoveFolderOptions, h as MoveAssetOptions, i as CdnServeOptions, j as PostAssetSignedUrlResponse, k as GetAssetsPageResponse, l as EnsureLensesOptions, m as ModerateTextOptions, n as CalmLensClientOptions, o as CreateFolderOptions, p as ListEventsOptions, q as MetadataItem, r as CdnAssetUrlOptions, s as CreateMultipartUploadPartOptions, t as AssetContentOptions, u as FolderIdOptions, v as MultipartUploadPartOptions, w as UpdateFolderOptions, x as RetryAssetOptions, y as RequestOptions, z as EventFactValues } from "./CalmLensTypes-DG_kHVqY.js";
+import { A as GetEventsResponse, B as EventFactValues, C as UpdateAssetOptions, D as GetAssetChildrenResponse, E as VerifyWebhookSignatureOptions, F as Folder, G as AssetStatus, H as EventSeverity, I as Event, J as MetadataItem, K as AssetType, L as TypedEvent, M as RequestErrorCode, O as GetAssetResponse, P as Lens, R as EventCategory, S as SubmitAssetOptions, T as UploadAssetPartOptions, U as EventType, V as EventFacts, W as Asset, Y as ProcessingOptions, _ as MultipartUploadOptions, a as CreateAssetSignedUrlOptions, b as RetrieveAssetOptions, c as EnsureLensOptions, d as ListAssetChildrenOptions, f as ListAssetsOptions, g as MoveFolderOptions, h as MoveAssetOptions, i as CdnServeOptions, j as PostAssetSignedUrlResponse, k as GetAssetsPageResponse, l as EnsureLensesOptions, m as ModerateTextOptions, n as CalmLensClientOptions, o as CreateFolderOptions, p as ListEventsOptions, q as AssetVisibility, r as CdnAssetUrlOptions, s as CreateMultipartUploadPartOptions, t as AssetContentOptions, u as FolderIdOptions, v as MultipartUploadPartOptions, w as UpdateFolderOptions, x as RetryAssetOptions, y as RequestOptions, z as EventFact } from "./CalmLensTypes-BpmT60j-.js";
 import * as zod from "zod";
 //#region ../shared/src/Classification.d.ts
 declare const CLASSIFICATION_CATEGORY_SCHEMA: zod.ZodEnum<{
@@ -1348,6 +1348,7 @@ declare const CLASSIFICATION_REPORT_SCHEMA: zod.ZodObject<{
     audioTranscribed: zod.ZodBoolean;
     segments: zod.ZodArray<zod.ZodObject<{
       source: zod.ZodEnum<{
+        clip: "clip";
         frame: "frame";
         "frame-text": "frame-text";
         speech: "speech";
@@ -2731,6 +2732,15 @@ export declare const WEBHOOK_TIMESTAMP_HEADER = "x-calmlens-timestamp";
 export declare const WEBHOOK_SIGNATURE_HEADER = "x-calmlens-signature";
 /** Deliveries whose timestamp is further than this from the receiver's clock are rejected. */
 export declare const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+/** The JSON body of a webhook delivery for a stored event. */
+export declare const toWebhookEventPayload: (event: Event) => WebhookEventPayload;
+/** Headers for one signed delivery of `body`. */
+export declare const createWebhookHeaders: (options: {
+  secret: string;
+  body: string;
+  deliveryId: string;
+  timestampSeconds?: number;
+}) => Promise<Record<string, string>>;
 /**
  * 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`