@calmlens/sdk 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,555 @@
-# 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
+```
+
+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`)
+
+#### 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)
+
+Submit an asset and wait for classification to finish. Accepts the same options as `assets.create()` for text, images, documents, and URLs.
+
+```typescript
+async assets.moderate(options: SubmitAssetOptions): Promise<Asset>
+```
+
+##### 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(),
+});
+```
+
+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).
+
+## 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, "metadata": null }
+}
+```
+
+Each delivery has these headers:
+
+| 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>")>` |
+
+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`.
+
+## 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:
+
+```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 same feed is available in code: `client.events.list({ after, limit })` returns events oldest first with a `cursor` to pass back.
+
+## 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).
+
+### 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.
+
+`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.