@calmlens/sdk 0.15.0 → 0.16.2

package/README.md

@@ -216,15 +216,14 @@ List assets in your project with pagination.
 
 ```typescript
 async assets.list(options: {
-  pageIndex?: number;
+  cursor?: string;
   pageSize?: number;
-  ordering?: Array<{ field: string; direction: "ASC" | "DESC" }>;
+  ordering?: Array<{ field: "createdAt" | "id"; direction: "ASC" | "DESC" }>;
   filter?: string | null;
 }): Promise<{
   items: Asset[];
-  total: number;
   hasMore: boolean;
-  pageIndex: number;
+  nextCursor: string | null;
   pageSize: number;
 }>
 ```
@@ -232,17 +231,16 @@ async assets.list(options: {
 **Example:**
 ```typescript
 const result = await client.assets.list({
-  pageIndex: 0,
   pageSize: 20
 });
 
-console.log(`Found ${result.total} assets`);
+console.log(`Received ${result.items.length} assets`);
 result.items.forEach(asset => {
   console.log(`${asset.name}: ${asset.moderation.status}`);
 });
 ```
 
-To read every matching asset, iterate instead of paging by hand. Pages are fetched as you go; assets created or deleted meanwhile can shift pages, so one may be skipped or repeated.
+To read every matching asset, iterate instead of paging by hand. Pages are fetched as you go using continuation cursors. Inserting or deleting other assets does not shift the cursor position. To page manually, pass `nextCursor` as `cursor` with the same filters and ordering until it is null. Lists are not snapshots; assets may still be deleted or change filter membership during traversal.
 
 ```typescript
 for await (const asset of client.assets.iterate({ filter: "moderation.status==rejected", pageSize: 100 })) {
@@ -257,7 +255,6 @@ List assets extracted from a website or multimedia document.
 ```typescript
 const children = await client.assets.listChildren({
   assetId: parentAssetId,
-  pageIndex: 0,
   pageSize: 20,
 });
 
@@ -511,7 +508,7 @@ const asset = await client.assets.moderate({ name: file.name, content: { data: f
 
 The client has `assets.create`, `assets.moderate`, `assets.uploadPart` and `assets.retrieve`, for its own uploads, and each returns an `UploadedAsset`. It fetches a new token for each upload and reuses that token for the upload's parts and status checks.
 
-The same client works in React Native and Expo apps. Mobile apps send no `Origin` header, so 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](https://github.com/CalmLens/CalmLens/tree/main/examples/mobile-uploads-expo).
+The same client works in React Native and Expo apps. Mobile apps send no `Origin` header, so 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](https://github.com/CalmLens/sdks/tree/main/examples/mobile-uploads-expo).
 
 On your server, sign a single-use token for each upload with `CalmLensServerClient`. Signing is local and makes no request:
 
@@ -704,7 +701,7 @@ Each delivery has these headers (the names are exported as constants):
 
 Verify the exact raw request body before parsing it; re-serializing parsed JSON can change the signed bytes. `parseWebhookEvent` verifies the delivery and returns the parsed event, or throws `sdk/invalid-webhook-signature` (bad signature or a timestamp more than `WEBHOOK_SIGNATURE_TOLERANCE_SECONDS`, 5 minutes, from your clock, which stops replays) or `sdk/invalid-webhook-payload`. `verifyWebhookSignature` takes the same options and returns a boolean. Both accept the body as a string, `Uint8Array`/`Buffer` or `ArrayBuffer`, and read the two headers from `headers` (a `Headers` object or Node's `req.headers`) when you don't pass `signature` and `timestamp`.
 
-The result is typed as `WebhookEventPayload`; narrow it on `type` to get that event type's typed `data.facts` (`EventType` and `EventFacts<Type>` are exported too, and [the webhooks guide](https://calmlens.com/docs/guides/webhooks#event-types) lists every type). Deliveries are retried, so make your handler idempotent by `event.id`.
+The result is typed as an extensible `WebhookEventPayload`. Event types and fact keys may be unfamiliar, and fact values are `unknown`; validate the facts your handler uses. Extra fields remain available. The [webhooks guide](https://calmlens.com/docs/guides/webhooks#event-types) lists current event types. Deliveries are retried, so make your handler idempotent by `event.id`.
 
 **Fetch API** (Next.js route handlers, Remix, Cloudflare Workers, Bun, Deno):
 
@@ -810,3 +807,26 @@ Requests send `User-Agent: calmlens-js/<version> (<runtime>/<version>)` from ser
 ## 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).
+
+### Test-input images
+
+The optional `@calmlens/sdk/test-inputs` entry generates and recognises the same
+project-specific colour grids used by the CalmLens portal:
+
+```ts
+import { paintTestImage, detectTestImage } from "@calmlens/sdk/test-inputs";
+
+const width = 512;
+const height = 512;
+const rgba = paintTestImage("violence", projectTestInputKey, width, height);
+const signal = detectTestImage({ width, height, rgba }, projectTestInputKey);
+// signal === "violence"
+```
+
+Encode the returned RGBA bytes with your image library to download a PNG. To
+recognise a downloaded image, decode it into RGBA first. These helpers have no
+DOM, image-codec, or Cloudflare dependencies. The grid tolerates resizing and
+lossy compression; cropping, rotation, and severe colour changes are unsupported.
+The entry also exports `generateTestTextCode` and `detectTestTrigger` for text
+test inputs. Use your project's test input key; another project's key does not
+activate its test signals.

package/cjs/{CalmLensConnection-DoemramF.js → CalmLensConnection-5Hj3trGr.js}

@@ -1,5 +1,5 @@
-const require_CalmLensVersion = require("./CalmLensVersion-CuxKdijk.js");
-const require_CalmLensUtils = require("./CalmLensUtils-Cv1Ylp9-.js");
+const require_CalmLensVersion = require("./CalmLensVersion-BGpB9t4-.js");
+const require_CalmLensUtils = require("./CalmLensUtils-BeIl1N6N.js");
 //#region src/client/CalmLensConnection.ts
 const DEFAULT_TIMEOUT_MS = 12e4;
 const DEFAULT_MAX_RETRIES = 2;

package/cjs/{CalmLensUtils-Cv1Ylp9-.js → CalmLensUtils-BeIl1N6N.js}

@@ -1,4 +1,5 @@
-const require_CalmLensVersion = require("./CalmLensVersion-CuxKdijk.js");
+const require_CalmLensVersion = require("./CalmLensVersion-BGpB9t4-.js");
+//#region src/contract/SharedConstants-Dn7ZJF5S.js
 const MAX_IMAGE_UPLOAD_BYTES = /* @__PURE__ */ (() => 20971520)();
 const MIN_MULTIPART_IMAGE_UPLOAD_BYTES = /* @__PURE__ */ (() => 10485760)();
 const REJECTED_UPLOAD_MIME_TYPE_SET = /* @__PURE__ */ new Set([
@@ -15,7 +16,7 @@ const isRejectedUploadMimeType = (mimeType) => REJECTED_UPLOAD_MIME_TYPE_SET.has
 const getRejectedUploadMimeTypeError = (mimeType) => `${normalizeUploadMimeType(mimeType)} is not a valid upload file type. Uploads must use a concrete file MIME type that CalmLens can store and process, such as image/png, image/jpeg, application/pdf, or text/plain.`;
 const DOMAIN = "calmlens.com";
 //#endregion
-//#region ../shared/src/AssetPayload.ts
+//#region src/contract/AssetPayload.js
 const uint8ArrayInputToNumbers = (value) => {
 	if (Array.isArray(value)) return value;
 	return Array.from(value);
@@ -505,15 +506,14 @@ const serializeTransform = (transform) => {
 };
 /** Returns the selector string the API and CDN accept for a string or structured transform. */
 const transformSelector = (transform) => transform === void 0 || typeof transform === "string" ? transform : serializeTransform(transform);
-/** Appends a CDN lens (`/@name`) or direct transform selector to an asset URL. */
+/** Appends a CDN lens (`/@name`) followed by any direct transform selector to an asset URL. */
 const appendCdnSelector = (url, options) => {
-	if (options.lens && options.transform) throw require_CalmLensVersion.invalidArgument("Specify either a lens or a transform, not both");
-	if (options.lens) return `${url}/@${encodePathSegment(options.lens, "Lens")}`;
+	if (options.lens) url = `${url}/@${encodePathSegment(options.lens, "Lens")}`;
 	if (!options.transform) return url;
-	if (typeof options.transform !== "string") return `${url}/${serializeTransform(options.transform)}`;
+	if (typeof options.transform !== "string") return `${url}${options.lens ? "," : "/"}${serializeTransform(options.transform)}`;
 	const transform = options.transform.replace(/^\/+/, "");
 	if (transform.includes("..") || transform.includes("?") || transform.includes("#")) throw require_CalmLensVersion.invalidArgument("Transform cannot contain \"..\", \"?\" or \"#\"");
-	return `${url}/${encodeURI(transform).replace(/%5B/g, "[").replace(/%5D/g, "]")}`;
+	return `${url}${options.lens ? "," : "/"}${encodeURI(transform).replace(/%5B/g, "[").replace(/%5D/g, "]")}`;
 };
 const appendQueryValue = (parts, key, value) => {
 	if (value === void 0 || value === null) return;

package/cjs/{CalmLensVersion-CuxKdijk.js → CalmLensVersion-BGpB9t4-.js}

@@ -1,6 +1,7 @@
 //#region src/client/CalmLensErrorCodes.ts
 /** Error codes the CalmLens API documents, by name. */
 const API_ERROR_CODES = {
+	INVALID_CURSOR: "validation/invalid-cursor",
 	MISSING_TOKEN: "auth/missing-token",
 	INVALID_API_KEY: "auth/invalid-api-key",
 	API_KEY_PROJECT_MISMATCH: "auth/project-mismatch",
@@ -63,6 +64,10 @@ const API_ERROR_CODES = {
 };
 /** The HTTP status and default message the API returns with each documented error code. */
 const API_ERROR_DEFINITIONS = {
+	"validation/invalid-cursor": {
+		status: 400,
+		message: "The cursor is invalid or belongs to a different query."
+	},
 	"auth/missing-token": {
 		status: 401,
 		message: "Authentication required. Send your project API key in the X-Api-Key header."
@@ -390,7 +395,7 @@ const invalidConfig = (message) => new CalmLensError(SDK_ERROR_CODES.INVALID_CON
 //#endregion
 //#region src/client/CalmLensVersion.ts
 /** This SDK's version, from its package.json. */
-const SDK_VERSION = "0.15.0";
+const SDK_VERSION = "0.16.2";
 const runtimeName = () => {
 	const runtime = globalThis;
 	if (isReactNativeRuntime()) return "react-native";

package/cjs/{CalmLensWebhooks-qrL-Zdu3.js → CalmLensWebhooks-CogUYk8-.js}

@@ -1,12 +1,12 @@
-const require_CalmLensVersion = require("./CalmLensVersion-CuxKdijk.js");
-const require_CalmLensUtils = require("./CalmLensUtils-Cv1Ylp9-.js");
-//#region ../shared/src/JsonUtils.ts
+const require_CalmLensVersion = require("./CalmLensVersion-BGpB9t4-.js");
+const require_CalmLensUtils = require("./CalmLensUtils-BeIl1N6N.js");
+//#region src/contract/JsonUtils.js
 const stringifyJsonCanonical = (value) => JSON.stringify(value, (_key, nestedValue) => {
 	if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) return nestedValue;
 	return Object.fromEntries(Object.keys(nestedValue).sort().map((key) => [key, nestedValue[key]]));
 });
 //#endregion
-//#region ../shared/src/CryptoUtils.ts
+//#region src/contract/CryptoUtils-Cb7_Afa0.js
 const encoder = new TextEncoder();
 /** Lowercase hex of `bytes`, two characters per byte. */
 const bytesToHex = (bytes) => Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -31,7 +31,7 @@ const timingSafeEqual = (a, b) => {
 	return difference === 0;
 };
 //#endregion
-//#region ../shared/src/UploadToken.ts
+//#region src/contract/UploadToken.js
 const UPLOAD_TOKEN_PREFIX = "clut_";
 const UPLOAD_TOKEN_MAX_TTL_SECONDS = 3600;
 const SIGNING_CONTEXT = "calmlens-upload-token:v1:";
@@ -124,7 +124,7 @@ async function verifyWebhookSignature(options) {
 /**
 * Verifies a webhook delivery and parses its body. Throws `sdk/invalid-webhook-signature`
 * when the signature or timestamp does not verify, and `sdk/invalid-webhook-payload` when a
-* verified body is not a webhook event. Narrow the result on `type` for typed `data.facts`.
+* verified body is not a webhook event. Unknown event types, fact values and fields remain available.
 *
 * Event types and fact keys added to CalmLens after this SDK version are returned as they are,
 * so keep a default branch when you switch on `type`.
@@ -141,7 +141,7 @@ async function parseWebhookEvent(options) {
 		});
 	}
 	const candidate = event;
-	if (!candidate || typeof candidate !== "object" || typeof candidate.id !== "string" || typeof candidate.type !== "string" || typeof candidate.projectId !== "string" || !candidate.data || typeof candidate.data !== "object") throw new require_CalmLensVersion.CalmLensError(require_CalmLensVersion.SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, { message: "Webhook body is not a CalmLens event" });
+	if (!candidate || typeof candidate !== "object" || typeof candidate.id !== "string" || typeof candidate.type !== "string" || typeof candidate.projectId !== "string" || !candidate.data || typeof candidate.data !== "object" || Array.isArray(candidate.data)) throw new require_CalmLensVersion.CalmLensError(require_CalmLensVersion.SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, { message: "Webhook body is not a CalmLens event" });
 	return event;
 }
 //#endregion