@calmlens/sdk 0.15.0 → 0.16.0

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,
 });
 
@@ -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-CPdx_acA.js}

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

package/cjs/{CalmLensUtils-Cv1Ylp9-.js → CalmLensUtils-DvhY8-cU.js}

@@ -1,4 +1,4 @@
-const require_CalmLensVersion = require("./CalmLensVersion-CuxKdijk.js");
+const require_CalmLensVersion = require("./CalmLensVersion-CrlGk2gX.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([

package/cjs/{CalmLensVersion-CuxKdijk.js → CalmLensVersion-CrlGk2gX.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.0";
 const runtimeName = () => {
 	const runtime = globalThis;
 	if (isReactNativeRuntime()) return "react-native";

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

@@ -1,5 +1,5 @@
-const require_CalmLensVersion = require("./CalmLensVersion-CuxKdijk.js");
-const require_CalmLensUtils = require("./CalmLensUtils-Cv1Ylp9-.js");
+const require_CalmLensVersion = require("./CalmLensVersion-CrlGk2gX.js");
+const require_CalmLensUtils = require("./CalmLensUtils-DvhY8-cU.js");
 //#region ../shared/src/JsonUtils.ts
 const stringifyJsonCanonical = (value) => JSON.stringify(value, (_key, nestedValue) => {
 	if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) return nestedValue;
@@ -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