@calmlens/sdk 0.9.1 → 0.10.0

package/esm/testing.d.ts

@@ -1,5 +1,13 @@
-import { A as GetAssetResponse, C as RetryAssetOptions, D as UploadAssetPartOptions, E as UpdateFolderOptions, F as AssetBinaryPayloadInput, I as Lens, K as Asset, L as Folder, M as GetEventsResponse, N as PostAssetSignedUrlResponse, S as RetrieveAssetOptions, T as UpdateAssetOptions, _ as MoveAssetOptions, a as CreateAssetSignedUrlOptions, c as DeleteAssetContentOptions, d as EnsureLensesOptions, f as FolderIdOptions, g as ModerateTextOptions, h as ListEventsOptions, i as CdnServeOptions, j as GetAssetsPageResponse, k as GetAssetChildrenResponse, l as DeleteAssetOptions, m as ListAssetsOptions, n as CalmLensClientOptions, o as CreateFolderOptions, p as ListAssetChildrenOptions, q as AssetStatus, r as CdnAssetUrlOptions, u as EnsureLensOptions, v as MoveFolderOptions, w as SubmitAssetOptions } from "./CalmLensTypes-CZqyni4p.js";
+import { A as ModerateTextOptions, B as UpdateFolderOptions, C as IterateAssetChildrenOptions, D as ListAssetChildrenOptions, G as AssetSearchQuery, I as RetrieveAssetOptions, J as PostAssetSignedUrlResponse, K as WebhookEventPayload, L as RetryAssetOptions, M as MoveFolderOptions, O as ListAssetsOptions, Q as TypedEvent, R as SubmitAssetOptions, T as Lens, V as UploadAssetPartOptions, X as Folder, Y as AssetBinaryPayloadInput, Z as Event, _ as DeleteAssetOptions, a as AssetSearchResponse, at as ClassificationCategory, b as FolderIdOptions, d as CdnAssetUrlOptions, f as CdnServeOptions, g as DeleteAssetContentOptions, i as AssetPage, j as MoveAssetOptions, k as ListEventsOptions, m as CreateFolderOptions, n as AssetChildrenPage, p as CreateAssetSignedUrlOptions, q as GetEventsResponse, s as AssetStatus, t as Asset, u as CalmLensClientOptions, v as EnsureLensOptions, w as IterateAssetsOptions, y as EnsureLensesOptions, z as UpdateAssetOptions } from "./CalmLensTypes-BfweJTMS.js";
 import * as zod from "zod";
+//#region ../shared/src/TestTriggers.d.ts
+type ClassificationTestSignal = ClassificationCategory | "sexual.involving-minors" | "violence.graphic";
+//#endregion
+//#region ../shared/src/MediaTestTriggers.d.ts
+export declare const MEDIA_TEST_SIGNALS: readonly ["sexual", "violence", "self-harm", "harassment", "hate", "criminal-activity", "violence.graphic"];
+/** Read this aloud, or render it as large, high-contrast text in a video frame. */
+export declare function generateMediaTestCode(signal: ClassificationTestSignal, projectId: string): string;
+//#endregion
 //#region ../shared/src/Permissions.d.ts
 declare const GRANT_SCHEMA: zod.ZodObject<{
   actions: zod.ZodArray<zod.ZodEnum<{
@@ -101,13 +109,15 @@ interface MockCalmLensClientOptions extends CalmLensClientOptions {
     imageStorage?: MockImageStorage;
     createId?: () => string;
     now?: () => number;
+    /** Status `assets.create` returns. Defaults to `pending`. */
     queuedStatus?: AssetStatus;
+    /** Status `assets.moderate` and `text.moderate` return. Defaults to `approved`. */
     analyzedStatus?: AssetStatus;
     signedUrlBaseUrl?: string;
   };
 }
 /** A `MockCalmLensClient` method, named like its path on the client. */
-type MockCalmLensOperation = "assets.list" | "assets.retrieve" | "assets.update" | "assets.listChildren" | "assets.create" | "assets.moderate" | "assets.uploadPart" | "assets.createSignedUrl" | "assets.move" | "assets.retry" | "assets.deleteContent" | "assets.delete" | "text.moderate" | "cdn.serve" | "events.list" | "folders.list" | "folders.retrieve" | "folders.create" | "folders.update" | "folders.delete" | "folders.move" | "ensureLens" | "ensureLenses";
+type MockCalmLensOperation = "assets.list" | "assets.search" | "assets.retrieve" | "assets.update" | "assets.listChildren" | "assets.create" | "assets.moderate" | "assets.uploadPart" | "assets.createSignedUrl" | "assets.move" | "assets.retry" | "assets.deleteContent" | "assets.delete" | "text.moderate" | "cdn.serve" | "events.list" | "folders.list" | "folders.retrieve" | "folders.create" | "folders.update" | "folders.delete" | "folders.move" | "ensureLens" | "ensureLenses";
 /** One recorded call: the method and the options object it was given, exactly as passed. */
 interface MockCalmLensCall {
   operation: MockCalmLensOperation;
@@ -119,8 +129,16 @@ interface MockCalmLensCall {
  * deadline (`sdk/timeout`); any `Error` is thrown as given.
  */
 type MockRequestFailure = "transport-error" | "timeout" | Error;
+/** An event to add to the mock feed; omitted fields get defaults. */
+type MockEventInput = Partial<Omit<TypedEvent, "type">> & {
+  type: TypedEvent["type"];
+};
+/**
+ * An in-memory stand-in for `CalmLensClient` with the same methods, validation and error
+ * codes. API errors carry the HTTP status, a `requestId` and response headers like the real
+ * client's, so error handling can be tested without a network.
+ */
 export declare class MockCalmLensClient {
-  private readonly options;
   readonly databaseStorage: MockDatabaseStorage;
   readonly imageStorage: MockImageStorage;
   private readonly createId;
@@ -130,7 +148,13 @@ export declare class MockCalmLensClient {
   private readonly apiKeyGrants;
   private readonly signedUrlBaseUrl;
   private readonly cdnBaseUrl;
+  private readonly projectId;
   private readonly lenses;
+  private readonly eventFeed;
+  /** The queue mode each open multipart upload was started with, as the API saves it. */
+  private readonly uploadQueues;
+  private readonly idempotentResults;
+  private requestCount;
   private readonly pendingFailures;
   /** Every call made through this client, oldest first. */
   readonly calls: MockCalmLensCall[];
@@ -145,26 +169,61 @@ export declare class MockCalmLensClient {
   }): void;
   /** Calls recorded for one operation, oldest first. */
   callsTo(operation: MockCalmLensOperation): MockCalmLensCall[];
+  /**
+   * Adds an event to the feed `events.list` reads, as if CalmLens had recorded it. Returns the
+   * stored event; pass it to `toWebhookEventPayload` to build a matching webhook body.
+   */
+  enqueueEvent(input: MockEventInput): TypedEvent;
+  /** An API error as the real client throws it: status, default message and request ID. */
+  private apiError;
+  private assertValidUploadMimeType;
+  private invalidPayload;
   private findOwnAsset;
   private begin;
+  private jsonResponse;
   get cdn(): {
     getAssetUrl: ({ assetIdentifier, ...options }: CdnAssetUrlOptions) => string;
+    /**
+     * Serves stored content like the CDN: `200` with `Content-Type`, `Content-Length`,
+     * `ETag` and `X-Request-Id`, or a JSON error body with `404`/`403`. Never throws for
+     * HTTP errors, like the real client.
+     */
     serve: (serveOptions: CdnServeOptions) => Promise<Response>;
   };
   get events(): {
-    /** The mock does not record events; it always returns an empty page at "now". */
+    /**
+     * Reads the mock feed like the API: without `after`, no events and a cursor for "now";
+     * with `after`, up to `limit` events added since, oldest first. Add events with
+     * `enqueueEvent`.
+     */
     list: (options?: ListEventsOptions) => Promise<GetEventsResponse>;
+    pages: (options?: ListEventsOptions) => AsyncGenerator<GetEventsResponse, void, undefined>;
   };
+  private listEvents;
+  private iterateEventPages;
+  private iteratePages;
   get text(): {
     moderate: (options: ModerateTextOptions) => Promise<Asset>;
   };
   get assets(): {
-    list: (options?: ListAssetsOptions) => Promise<GetAssetsPageResponse>;
-    retrieve: (options: RetrieveAssetOptions) => Promise<GetAssetResponse>;
-    listChildren: (childrenOptions?: ListAssetChildrenOptions) => Promise<GetAssetChildrenResponse>;
+    /**
+     * Matches `query` (case-insensitively) against each asset's name, ID, external ID,
+     * description and tags, best match first. Mock scores are 1 for an exact match and 0.5
+     * otherwise; `mode` is accepted but there is no semantic search.
+     */
+    search: (options: Partial<AssetSearchQuery> & {
+      query: string;
+    }) => Promise<AssetSearchResponse>;
+    /** Lists assets with the real client's paging, `ordering`, `folderId` and `filter`. */
+    list: (options?: ListAssetsOptions) => Promise<AssetPage>;
+    iterate: (options?: IterateAssetsOptions) => AsyncGenerator<Asset, void, undefined>;
+    retrieve: (options: RetrieveAssetOptions) => Promise<Asset>;
+    listChildren: (childrenOptions?: ListAssetChildrenOptions) => Promise<AssetChildrenPage>;
+    iterateChildren: (options: IterateAssetChildrenOptions) => AsyncGenerator<Asset, void, undefined>;
     update: (options: UpdateAssetOptions) => Promise<Asset>;
     create: (options: SubmitAssetOptions) => Promise<Asset>;
     moderate: (options: SubmitAssetOptions) => Promise<Asset>;
+    /** Continues a multipart upload: parts must arrive in order while it is `uploading`. */
     uploadPart: (options: UploadAssetPartOptions) => Promise<Asset>;
     createSignedUrl: (signedUrlOptions: CreateAssetSignedUrlOptions) => Promise<PostAssetSignedUrlResponse>;
     move: (options: MoveAssetOptions) => Promise<Asset>;
@@ -183,11 +242,27 @@ export declare class MockCalmLensClient {
   ensureLens(options: EnsureLensOptions): Promise<Lens>;
   private ensureLensDefinition;
   ensureLenses(options: EnsureLensesOptions): Promise<Lens[]>;
+  /** Replays the first result for a reused idempotency key, like the API. */
+  private withIdempotency;
   private moderateAsset;
   private createAsset;
   private resolveFolder;
+  private findOwnFolder;
   private assertUniqueFolderName;
   private getSizeInBytes;
 }
 //#endregion
-export type { MockCalmLensCall, MockCalmLensClientOptions, MockCalmLensOperation, MockDatabaseStorage, MockImageStorage, MockRequestFailure, MockStoredContent };
+//#region src/testing/MockWebhooks.d.ts
+/** The JSON body of a webhook delivery for a stored event (or an event from `events.list`). */
+export declare const toWebhookEventPayload: (event: Event) => WebhookEventPayload;
+/** `v1=<hex HMAC-SHA256 of "<timestamp>.<body>">`, the `x-calmlens-signature` header value. */
+export declare const createWebhookSignatureHeader: (secret: string, timestamp: number | string, body: string) => Promise<string>;
+/** Headers for one signed delivery of `body`, as CalmLens sends them. */
+export declare const createWebhookHeaders: (options: {
+  secret: string;
+  body: string;
+  deliveryId: string;
+  timestampSeconds?: number;
+}) => Promise<Record<string, string>>;
+//#endregion
+export type { MockCalmLensCall, MockCalmLensClientOptions, MockCalmLensOperation, MockDatabaseStorage, MockEventInput, MockImageStorage, MockRequestFailure, MockStoredContent };