JavaScript SDK reference
Look up the options and behaviour of each part of the JavaScript and TypeScript SDK. Install the package and moderate your first upload from the SDK page; the guides it links explain the concepts every SDK shares.
Package
| Import | Contents |
|---|---|
calmlens | Shared types, CalmLensError, CALMLENS_ERROR_CODES, SDK_VERSION, CDN_RESOURCES and getAssetInfo |
calmlens/server | CalmLensServerClient, parseWebhookEvent, verifyWebhookSignature and the webhook header constants |
calmlens/app | CalmLensAppClient and everything calmlens exports |
calmlens/react, calmlens/react-native, calmlens/vue, calmlens/svelte, calmlens/elements | The upload widget and CalmLensAsset for each UI library |
calmlens/ui | The framework-free core the components share |
calmlens/file-icons | The file-type icons the upload widget draws |
calmlens/styles.css | The components' stylesheet, for Vue, Svelte and the custom elements |
calmlens/testing | Offline mocks and test helpers |
calmlens/test-inputs | Test input generators |
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. The main, /server and /app entry points never load the testing helpers. react, vue and svelte are optional peer dependencies: install the one you use.
Core model types (Asset, Folder, Lens, AssetPage, EventsPage, ClassificationReport) and request types are exported from the package root.
Server client
import { CalmLensServerClient } from "calmlens/server";
const client = new CalmLensServerClient({
apiKey: process.env.CALMLENS_API_KEY!,
projectId: process.env.CALMLENS_PROJECT_ID!,
});Client options
| Option | Default | Meaning |
|---|---|---|
apiKey | Required | Your project API key. |
projectId | Required | Your project ID. |
baseUrl | https://api.calmlens.com/v1 | API base URL. |
cdnBaseUrl | https://cdn.calmlens.com/v1 | CDN base URL. |
fetch | The global fetch | The fetch used for every request, for example one with a proxy or instrumentation. |
uploadFetch, cdnFetch | fetch | Overrides for content uploads, or for cdn.serve only. |
timeoutMs | 120000 | Deadline for each API request attempt, including reading the response body. For cdn.serve it ends when the response headers arrive. |
uploadTimeoutMs | None | Deadline for each binary upload attempt, so large files are never cut off. Text content uses timeoutMs. |
maxRetries | 2 | Retries for requests that are safe to repeat; 0 turns them off. See Retries and idempotency. |
maxResponseBytes | 32 MiB | Largest JSON response the client reads. |
partSizeBytes | 8 MiB | Content larger than this is uploaded in parts of this size; from 5 MiB to 64 MiB. See Multipart uploads. |
signal | None | An AbortSignal that cancels every request this client makes. |
dangerouslyAllowBrowser | false | 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 checked before anything else is set up. A missing apiKey or projectId, a timeoutMs that is not a positive integer, or a baseUrl or cdnBaseUrl that is not an absolute HTTP(S) URL throws sdk/invalid-config. The client keeps its API key out of console.log, util.inspect and JSON.stringify.
Request budgets
client.withRequestOptions({ signal, timeoutMs, uploadTimeoutMs, maxRetries }) returns a client that applies those options to one operation without changing the original. It shares the original's credentials and lens cache.
const scoped = client.withRequestOptions({ signal: request.signal, timeoutMs: 30_000 });
const asset = await scoped.assets.retrieve({ assetId });Requests never follow redirects, so the API key is never sent to another origin. From server runtimes, requests send User-Agent: calmlens-js/<version> (<runtime>/<version>); SDK_VERSION holds the version.
Assets
The asset object
Every asset method resolves to the stored Asset, a plain object with camelCase keys exactly as the API returns it:
const asset = await client.text.classify({ text: "Great photo!", externalId: "comment-42" });
asset.id; // string
asset.classification.status; // "queued" | "processing" | "completed" | "failed"
asset.classification.failureReason; // "file-too-large" | "processing-error" | ... | null
asset.classification.moderation.status; // "pending" | "allowed" | "limited" | "age-restricted" | "blocked" | "purged"
asset.classification.moderation.categories?.violence?.score; // the policy score, from 0 to 1
asset.classification.moderation.categories?.violence?.action; // "allow" | "limit" | "age-restrict" | "block" | "purge"
asset.classification.moderation.raw?.categories.harassment.status; // "evaluated" | "partial" | "not-evaluated"
asset.content.status; // "temporary" | "stored" | "removed"
asset.content.removalReason; // "policy" | "retention" | "requested" | "parent-removed" | "disposed" | null
asset.type; // "plaintext-document" for text
asset.createdAt; // milliseconds since the Unix epochid, projectId, name, type, createdAt, updatedAt, upload, classification and content are always present. classification.moderation.categories holds each assessed category's policy score and action, and classification.moderation.raw its detection findings; raw is absent until findings are available, and optional detections appear only when requested. The latest applied review in classification.moderation.manualReviews takes precedence over the automated decision. See Asset lifecycle and moderation for every status and failure reason, Asset types and limits for type, and Reading classification results for the report.
Create and classify
assets.create(options) queues processing and returns the created asset at once. assets.classify(options) takes the same options and waits for classification. text.classify({ text, ...options }) sends text as text/plain content named text unless you pass name.
| Option | Meaning |
|---|---|
name | Required. The asset's name. |
content | Binary or plain-text content with its MIME type, such as { plainText: "hello", type: "text/plain" } or { data: file, type: file.type }. See Content payloads. |
url | An external URL to fetch instead of sending content. |
part | The first part of a multipart upload. |
externalId, description, metadata, tags, folderId | Your ID, a description, metadata fields, tags and the folder to store the asset in. |
visibility | public or private. Public retained content can be requested directly from the CDN; private content needs a signed asset URL or an authorised request. |
uploadPresetId | Applies an upload preset's folder, visibility, file types and size limit. |
processingOptions.keepContentAfterProcessing | Keep the content after processing. By default it is removed once classification finishes. |
processingOptions.storeSensitiveMetadata | Overrides the project setting for this upload. When false, embedded image metadata (EXIF, XMP and IPTC) is removed before the image is stored, and content.metadata leaves out the creator and location. When true, the image is stored as uploaded. |
processingOptions.features | Optional analyses, each turned on with enabled: true, such as ocr. Link detection is on unless turned off with enabled: false. See Processing features. |
authorId, context | The author and earlier posts of a reply. See Replies in a conversation. |
idempotencyKey | Your own key for safe retries across processes. See Retries and idempotency. |
const document = await client.assets.create({
name: "document.pdf",
content: { base64: pdfBase64, type: "application/pdf" },
description: "Important document",
visibility: "private",
});
const page = await client.assets.create({
name: "website-content",
url: "https://example.com/page",
});With OCR on, the image's own report includes the text pass, and the retained text is stored in the image's content.extractedText; no separate text child is created. Removing the image's content also removes the extracted text.
Content payloads
content and multipart part accept one of:
| Form | Use it for |
|---|---|
{ plainText: string } | Text content only |
{ base64: string } | Base64-encoded bytes |
{ uint8Array: number[] | Uint8Array } | Bytes |
{ buffer: Buffer | ArrayBuffer } | Bytes |
{ data: Blob | File | Response | ReadableStream } | Files, fetched responses and streams |
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. The SDK sends the bytes as the raw request body, with upload details in the query string, never as multipart form data.
Use a concrete MIME type such as image/png, application/pdf or text/plain. The SDK rejects application/octet-stream and multipart/* types. Content is checked before it is sent, with the same codes the API uses, such as 400 upload-payload/invalid, 415 upload/unsupported-type and, for content of known size over the upload limit, 413 upload/too-large.
Replies in a conversation
For a reply or comment in a thread, pass its authorId and the earlier posts in context.items, oldest first. Author IDs are your own opaque identifiers. The SDK sends only the posts CalmLens uses: the most recent 5 that fit in 2,000 characters, always including the most recent post.
const reply = await client.text.classify({
text: "Same to you",
authorId: "user-2",
context: {
items: [
{ text: "Has anyone tried the new update?", authorId: "user-1" },
{ text: "You would say that", authorId: "user-3" },
],
},
});
reply.context; // the posts CalmLens used, or null once the content is removedThe same options work on assets.create() and assets.classify() for images, documents, audio and video. See Threaded moderation.
Retrieve and wait for a decision
assets.retrieve({ assetId }) fetches one asset.
assets.waitForDecision({ assetId, timeoutMs?, signal? }) retrieves the asset at once, then again after 0.5 seconds, waiting 1.5 times longer each time, up to 2 seconds between checks, and returns it once classification.status is completed or failed. It rejects with sdk/timeout after timeoutMs (60000 by default), and with sdk/cancelled when signal aborts. Use it after assets.create, or with an asset ID you stored earlier; webhooks report decisions without polling.
const queued = await client.assets.create({ name: "photo.jpg", content: { data: blob, type: "image/jpeg" } });
const decided = await client.assets.waitForDecision({ assetId: queued.id, timeoutMs: 30_000 });List and iterate
assets.list({ cursor?, pageSize?, sort?, filter? }) returns one page: { items, hasMore, nextCursor }. sort is a comma-separated list of createdAt and id, each descending when prefixed with -, such as "-createdAt,id" (newest first by default). List one folder's assets with filter: "folderId==fldr_…", or the project root's with folderId==null. To page by hand, pass nextCursor as cursor with the same filter and sort until hasMore is false.
assets.iterate(options) takes the same options and fetches pages as you go:
for await (const asset of client.assets.iterate({
filter: "classification.moderation.status==blocked",
pageSize: 100,
})) {
console.log(asset.id);
}Inserting or deleting other assets does not shift the cursor position. Lists are not snapshots: assets may still be deleted or change filter membership while you page. See Pagination and filtering for filter expressions, and Asset search for assets.search.
assets.listChildren({ assetId, ... }) and assets.iterateChildren({ assetId }) list the assets extracted from a website or document. See Child assets. assets.listTimeline({ assetId, ... }) and assets.iterateTimeline({ assetId }) page through an audio or video asset's findings timeline.
assets.search({ query, mode?, pageSize? }) returns the best pageSize matches, 1 to 20 (default 10), without a cursor.
Move and retry
assets.move({ assetId, folderId }) moves an asset into a folder, or to the project root with folderId: null.
assets.retry({ assetId }) processes a failed asset again. It returns in processing and is moderated like a new upload, so handle the result the same way. The content must still be stored; otherwise it throws 409 asset/content-unavailable and you need to upload it again.
Explain a decision
To decide quickly, moderation can skip questions whose answers could not change any action, so a report with classification.moderation.explanationComplete set to false can credit a different rule, or show a different policy score, than a complete one. assets.explain({ assetId }) answers those questions and returns the asset with explanationComplete set to true; every action stays as decided. See Complete policy evidence.
It throws 409 asset/not-decided for an asset without a decision, and 409 asset/policy-changed when the project's policy has changed since the decision. Pass rerun: true to moderate the asset again with the current policy instead: the asset returns in processing and can reach a different decision. A re-run throws 409 asset/reviewed for an asset a reviewer has decided.
Record a reviewer's decision
assets.decide({ assetId, decision, note, confirmPurge? }) replaces the policy's decision. classification.moderation.status becomes decision, the decision and its note (required, up to 1,499 characters) join classification.moderation.manualReviews, and the matching asset.<status> event is sent with the API key as its actor. Purging needs confirmPurge: true and the assets:delete permission, and permanently deletes the stored content. See POST /.
await client.assets.decide({
assetId,
decision: "blocked",
note: "Spam reported by three members",
});| Error | When |
|---|---|
| 409 asset/processing | The asset is still uploading or processing. |
| 409 asset/decision-not-allowed | An asset pending moderation is allowed, limited or age-restricted; it can only be blocked or purged. |
| 409 asset/decision-unchanged | The asset already has that status. |
| 409 asset/content-purged | Purged content is given any decision but blocked. |
Multipart uploads
assets.create and assets.classify upload content larger than partSizeBytes (8 MiB by default) in parts when its size is known and it can be read again: bytes, base64, a Blob or a File. Each part has its own Idempotency-Key (<key>:part-<n>) and is retried on its own, a part CalmLens already has is skipped, and the call returns the finished asset. Call it again with the same idempotencyKey to resume an upload that failed; an idempotencyKey for an upload in parts can be up to 240 characters. ReadableStream and Response content is sent in one request. App clients send every part with the upload token that started the upload.
To send the parts yourself, for example while you produce a file, start a multipart upload by passing part to assets.create or assets.classify, then send later parts with assets.uploadPart({ assetId, part }). partNumber defaults to 1 and isFinal to false when you start an upload.
- An upload started with
createis queued when its final part arrives; one started withclassifywaits for the decision. CalmLens saves the choice, so later parts can come from another process that knows only the asset ID. PasswaittouploadPartto override it for the final part. - Pass
totalSizeInBytesnext topartwhen you know the file's size, so CalmLens rejects an upload that could never finish before you send the rest. - Every part but the final one must be at least 5 MiB. If you send base64, split the original bytes first, then encode each part; never split one base64 string.
- Images sent in one request can be up to 10 MiB, and images in parts up to 20 MiB at any size below that, down to one final part.
- A
ReadableStreampart must include its exactsizeInBytes, so CalmLens can stream it without buffering. - Retained multipart image originals stay in private storage; deliver them and their transforms through CDN URLs.
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 },
});A single part with isFinal: true sent through assets.classify uploads and waits for the decision in one call.
Folders
| Method | Behaviour |
|---|---|
folders.list({ parentId?, cursor?, pageSize?, sort? }) | One page of immediate child folders, of the project root when parentId is omitted. Returns items, the visible ancestors of the listed folders, hasMore and nextCursor. pageSize is 1 to 100 (default 50). Sorted by name, or by one other field with sort, such as "-createdAt" for newest first (name or createdAt). |
folders.iterate({ parentId?, pageSize?, sort? }) | Every folder folders.list would return, fetching pages as you go. |
folders.retrieve({ folderId }) | One folder. |
folders.create({ name, parentId? }) | A folder at the root or under parentId. |
folders.update({ folderId, name }) | Rename a folder. |
folders.move({ folderId, parentId }) | Move a folder, or to the root with parentId: null. Needs Manage project (project:manage). Moving it into itself or a descendant throws 409 folder/parent-cycle. |
folders.delete({ folderId }) | Delete an empty folder. A folder with assets or child folders throws 409 folder/not-empty. |
Policies
Moderation policies belong to the project's organisation, and its projects share them. Every change sends the policy's revision; a policy changed since is refused with 409 policy/revision-conflict, so retrieve it again before retrying.
for await (const policy of client.policies.iterate()) console.log(policy.id, policy.preset?.mode);
const assigned = await client.policies.retrieveAssigned();
const kids = await client.policies.create({ presetId: "children-platform", name: "Kids section" });
const updated = await client.policies.update({
policyId: kids.id,
revision: kids.revision,
description: "Stricter rules for the kids section",
});
await client.policies.assign({ policyId: updated.id });| Method | Behaviour |
|---|---|
policies.list({ cursor?, pageSize?, sort? }) / policies.iterate() | A page of the organisation's policies, oldest first by default (sort by createdAt and id), or every policy. |
policies.retrieve({ policyId }) | One policy. |
policies.create({ name, settings } | { presetId, name? }) | A policy from settings defining every category, or a copy of a built-in preset. |
policies.update({ policyId, revision, name?, description?, settings? }) | Change a policy; later moderation uses it. |
policies.reset({ policyId, revision, presetVersion }) | Restore the settings of the preset release a pinned or copy policy is pinned to; send its preset.version. |
policies.upgrade({ policyId, revision, presetVersion }) | Move a pinned or copy policy whose settings are unchanged to the latest release; send its preset.latestVersion. |
policies.setAutomaticUpdates({ policyId, enabled, revision, presetVersion }) | Switch the organisation's own preset policy between live, following every preset release, and pinned. |
policies.delete({ policyId }) | Delete a policy. One a project or upload preset still uses throws 409 policy/in-use. |
policies.retrieveAssigned() | The policy the project moderates with. |
policies.assign({ policyId }) | Choose the policy the project moderates with. |
Lenses
ensureLens(definition) creates a project lens with that identifier, or changes the existing one to the definition you send, so you can run it on every deploy. The client skips the request when it has already ensured the same definition.
const lens = await client.ensureLens({
identifier: "picmagic-normal",
name: "PicMagic normal",
type: "image",
active: true,
transform: { fit: "scale-down", width: 1024, format: "png" },
});
const image = await client.cdn.serve({ assetId, lens: lens.identifier });ensureLenses({ lenses }) ensures several together: new definitions go in one request, or in consecutive requests of up to 100 each, in order. When a definition changes, the CDN stops serving files made with the earlier one. See Custom lenses.
| Method | Behaviour |
|---|---|
lenses.list({ cursor?, pageSize?, sort? }) / lenses.iterate() | A page of the project's lenses, newest first by default (sort by createdAt and id), or every lens. The built-in lenses aren't listed. |
lenses.create(definition) | Create a lens whose identifier is new to the project. One the project already uses throws 409 lens/identifier-taken. |
lenses.retrieve({ lensId }) | One lens. An ID that isn't one of the project's lenses throws 404 lens/not-found. |
lenses.update({ lensId, name?, description?, type?, active?, transform? }) | Change a lens. The CDN serves the new transform from then on. |
lenses.delete({ lensId }) | Delete a lens. URLs that select it stop being served. |
CDN
cdn.getAssetUrl(options) builds an asset's CDN URL without a request. cdn.serve(options) fetches it with the client's API key. Both take:
| Option | Meaning |
|---|---|
assetId or externalId | Required, exactly one. The asset ID, or the external ID it was uploaded with (ext: in the URL). |
projectId | Defaults to the client's project. |
resource | rendered (the displayable file), preview (its still), original (the uploaded file), placeholder, hls (the stream's master playlist), embed or info. Without it, getAssetUrl returns the asset URL, which every resource is a path beneath, and serve fetches rendered. |
lens | A named lens, for rendered or preview. The SDK adds the @ prefix the URL uses, such as /rendered/@picmagic-normal. |
transform | A direct transform for rendered or preview: an options object such as { format: "png", width: 1024 }, or an options string for one path segment, such as "blur=12,fit=cover,width=1024". With a lens, its options replace the lens's options of the same name. |
viewerClaims | { region?, ageConfirmed? }, sent as an unsigned query and left out when they are the defaults; see Viewer claims. |
A lens or transform on another resource, or without one, throws sdk/invalid-argument. The CDN refuses them on rendered PDFs, video and audio with 400 transform/invalid.
cdn.serve returns the Response as soon as headers arrive, so you can stream the body, for example return new Response(response.body, response). Non-2xx responses are returned rather than thrown. Pass init for extra fetch options such as method: "HEAD". It reads private assets when the key has the assets:download permission; give browsers and apps a signed asset URL instead.
The placeholder is a small blurred PNG made from the asset's ThumbHash, served publicly whatever the asset's visibility or moderation status, for example in place of an age-restricted image.
An age-restricted asset is delivered only when the request carries viewerClaims: { ageConfirmed: true }, even with a signed URL or API key; otherwise the CDN returns 403 viewer/age-confirmation-required. Set it only where your app has decided the viewer may see age-restricted content, and leave it false in processing jobs. See Age-restricted assets and Viewer region.
const restrictedUrl = client.cdn.getAssetUrl({
assetId,
resource: "rendered",
viewerClaims: { ageConfirmed: true },
});Signed asset URLs
cdn.signAssetUrl({ assetId | externalId, expiresIn?, original?, projectId?, resource?, lens?, transform?, viewerClaims? }) signs a private asset's URL on your server and resolves to { url, expiresAt }, with expiresAt in milliseconds since the Unix epoch. expiresIn is 1 to 86400 seconds (900 by default). Every resource is a path beneath the URL; /original only with original: true, and otherwise the CDN refuses it with 403 signed-url/original-not-granted. The grant binds the project, the asset, original access and the expiry: a resource, lens, transform or viewerClaims you pass is appended as getAssetUrl appends it, so you can change them later without signing again. See Signed asset URLs.
const { url, expiresAt } = await client.cdn.signAssetUrl({ assetId, expiresIn: 900 });
const thumbnail = `${url}/rendered/@thumbnail`;The options are checked before anything is sent. It is not retried: it carries no Idempotency-Key.
Display info
cdn.getAssetInfo(url, { viewerClaims?, signal? }) reads an asset URL's display info, public or signed, from its info resource: id, projectId, type, externalUrl, content (format, width, height, durationSeconds, pageCount, rendered, preview, hls) and availability (available, age-restricted or unavailable) for the viewer claims, which default to those the URL carries. It sends no API key, as a browser would. A refusal throws CalmLensError with the CDN's code, such as 403 signed-url/expired. getAssetInfo(url, options), exported from calmlens, does the same in browsers and takes a fetch option. Pass the result to CalmLensAsset as info, so a server render shows the asset itself.
URLs in the browser
CalmLensAppClient has cdn.getAssetUrl with the same options. It builds public asset URLs from the client's projectId (or one you pass per call) and its cdnBaseUrl (default https://cdn.calmlens.com/v1), with no API key and no request. Private assets need a URL your server signs.
const placeholder = client.cdn.getAssetUrl({ assetId, resource: "placeholder" });App client
CalmLensAppClient uploads from browsers and apps through an upload preset, without an API key.
import { CalmLensAppClient } from "calmlens/app";
const client = new CalmLensAppClient({
uploadPresetId: "preset_4Lk8Qw2Xm9Rt5Vb3Nc7P",
// Only for presets that require a token: called once per new upload
token: () =>
fetch("/api/upload-token", { method: "POST" })
.then((response) => response.json())
.then((body) => body.token),
});
const asset = await client.assets.classify({
name: file.name,
content: { data: file, type: file.type },
});It takes uploadPresetId (required), token (a string, or a function that returns one or a promise of one), projectId and cdnBaseUrl for cdn.getAssetUrl, and the server client's baseUrl, fetch, uploadFetch, timeoutMs, uploadTimeoutMs, maxRetries, maxResponseBytes, partSizeBytes and signal. Passing apiKey throws sdk/invalid-config.
It has assets.create, assets.classify, assets.uploadPart and assets.retrieve for its own uploads, each returning an UploadedAsset with the upload's upload and classification state; see Uploading from a browser. The client fetches a new token for each upload and reuses it for that upload's parts and status checks.
In React Native and Expo apps, which send no Origin header, 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 .
Upload tokens
On your server, client.uploadTokens.sign({ uploadPresetId, externalId?, expiresIn? }) signs a single-use token for one upload. Signing is local and makes no request. Tokens last 10 minutes by default and up to 3600 seconds. It resolves to { token, expiresAt }, with expiresAt in milliseconds since the Unix epoch. See Upload tokens.
Webhooks
parseWebhookEvent(options) verifies a delivery and returns the parsed event. verifyWebhookSignature(options), also a static method of CalmLensServerClient, takes the same options and returns a boolean.
| Option | Meaning |
|---|---|
payload | Required. The raw request body as a string, Uint8Array, Buffer or ArrayBuffer. Parsed JSON throws sdk/invalid-argument, because serialising it again can change the signed bytes. |
secret | Required. The connector's signing secret. |
headers | A Headers object or Node's req.headers, read when signature and timestamp are omitted. |
signature, timestamp | The x-calmlens-signature and x-calmlens-timestamp header values. |
toleranceSeconds | Largest allowed clock difference, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS (300) by default. |
now | The current time as a Date or milliseconds, for tests. |
A delivery is valid when the 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. parseWebhookEvent throws sdk/invalid-webhook-signature for a missing, wrong or stale signature and sdk/invalid-webhook-payload for a verified body that isn't a CalmLens event. The header names are exported as WEBHOOK_DELIVERY_HEADER, WEBHOOK_TIMESTAMP_HEADER and WEBHOOK_SIGNATURE_HEADER. See Webhooks for the payload and headers.
The event is typed as an extensible WebhookEventPayload: event types and fact keys may be ones your SDK version doesn't know, and fact values are unknown, so validate the facts your handler uses. isTestWebhookEvent(event) is true for a test send, which carries the { key: "test", value: true } fact. Deliveries can arrive out of order, so store the highest assetSequence you have applied for each asset. isNewerAssetEvent(event, lastSequence) is false for an event whose assetSequence isn't higher than lastSequence, and true for a newer one, an event that isn't about an asset, or when lastSequence is null or undefined.
For Express, use express.raw({ type: "application/json" }) on the route so req.body is the unparsed Buffer:
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);
}
});For Fastify, register a raw body parser for the route, such as fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => done(null, body)), then pass payload: request.body and headers: request.headers.
Events feed
events.list({ cursor?, pageSize?, types?, assetId? }) reads the project's events, oldest first, without a public webhook URL. It resolves to an EventsPage of { items, nextCursor, hasMore }; each item has id, projectId, type, severity, title, description, assetId, asset, facts and createdAt, the same shape webhooks deliver.
- Without
cursor, it returns no events and anextCursorfor the current time, so you see only events created after you start reading. - With
cursor, it returns up topageSizeevents (1 to 100, default 50) created after that cursor. When there are none,nextCursoris the cursor you passed; it is nevernull. - An unknown or malformed cursor fails with 400 cursor/invalid.
events.pages({ cursor, pageSize }) follows the cursor until no more events are waiting. Save the latest nextCursor to resume after a restart. See Reading the feed.
Errors
Every failure is a CalmLensError, whether the API returned an error or the request never completed:
import { CALMLENS_ERROR_CODES, CalmLensError } from "calmlens";
try {
await client.assets.retrieve({ assetId });
} catch (error) {
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;
}| 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 Retry-After (on 429 and 409 idempotency/request-in-progress). |
details | Structured diagnostics from the API, such as validation issues. |
cause | The underlying error, for transport failures. |
error.isNotFound() is true for 404. error.isRetryable() is true for transport failures, timeouts (including waitForDecision's deadline), 429, 500, 502, 503, 504 and 409 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.
The SDK raises these codes itself:
| Code | Meaning |
|---|---|
sdk/invalid-argument | A method argument is missing or invalid, such as an empty assetId. |
sdk/invalid-config | The client options are invalid. |
sdk/transport-error | The request could not complete: DNS, TLS, refused or reset connections, truncated bodies or 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, or a page that repeats a cursor the iterator already used. |
sdk/http-error | An HTTP failure without a CalmLens error body, such as from a proxy, or a redirect, which the SDK never follows. |
sdk/response-too-large | A response larger than maxResponseBytes. |
sdk/invalid-webhook-signature, sdk/invalid-webhook-payload | Thrown by parseWebhookEvent. |
See Error handling for API error codes and recovery.
Retries and idempotency
The client retries a request when repeating it is safe: reads, and creates and uploads, which always carry an Idempotency-Key header. It retries failures before any response, timeouts, 429, 500, 502, 503, 504 and 409 idempotency/request-in-progress, up to maxRetries times with jittered exponential backoff. It waits for Retry-After when the API sends one, up to 60 seconds; a longer wait is 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.classify, text.classify and assets.uploadPart generate a 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:
await client.text.classify({
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 409 idempotency/key-reused. See Retrying requests safely.
Forward compatibility
The SDK does not validate responses against its types, so fields and values added to the API later reach your code unchanged. AssetClassificationStatus, AssetModerationStatus, AssetModerationDecision, AssetContentStatus, AssetContentRemovalReason, AssetType and AssetVisibility include string for that reason: handle values you don't know, for example by treating an unknown status as not ready. Event types and fact keys are typed for the ones your SDK version knows; keep a default branch when you switch on them.