@calmlens/sdk 0.11.0 → 0.12.0

package/esm/server.d.ts

@@ -0,0 +1,202 @@
+import { $ as SearchAssetsOptions, A as DeleteAssetContentOptions, At as AssetSafetyHold, B as Lens, C as CdnAssetUrlOptions, Ct as EventType, D as CreateAssetSignedUrlOptions, Dt as AssetSearchMatchField, E as ConnectionOptions, Et as LensType, F as IdempotencyOptions, Ft as MetadataItem, G as ModerateTextOptions, H as ListAssetChildrenOptions, I as ImageTransform, It as PreviewImage, J as MultipartUploadOptions, K as MoveAssetOptions, L as ImageTransformOptions, Lt as ProcessingOptions, M as EnsureLensOptions, Mt as DocumentData, N as EnsureLensesOptions, Nt as ExtractedText, O as CreateFolderOptions, Ot as AssetSearchQuery, P as FolderIdOptions, Pt as ImageData, Q as RetryAssetOptions, R as IterateAssetChildrenOptions, S as CalmLensServerClientOptions, St as EventSeverity, T as CdnTransform, Tt as Page, U as ListAssetsOptions, V as LensTransform, W as ListEventsOptions, X as RequestOptions, Y as MultipartUploadPartOptions, Z as RetrieveAssetOptions, _ as AssetSearchResult, _t as TypedEvent, a as ClassificationLabel, at as UpdateFolderOptions, b as AssetVisibility, bt as EventFactValues, c as ClassificationReport, ct as UploadedAsset, d as Asset, dt as WebhookPayloadInput, et as SignUploadTokenOptions, f as AssetChecksums, ft as GetEventsResponse, g as AssetSearchResponse, gt as EventAsset, h as AssetPage, i as ClassificationCategoryReport, it as UpdateAssetOptions, j as DeleteAssetOptions, jt as AssetSafetyHoldReason, k as CreateMultipartUploadPartOptions, l as Likelihood, lt as VerifyWebhookSignatureOptions, m as AssetContentOptions, mt as Folder, n as ClassificationCategories, nt as SignedUrl, o as ClassificationNotEvaluatedReason, ot as UploadAssetPartOptions, p as AssetChildrenPage, pt as PostAssetSignedUrlResponse, q as MoveFolderOptions, r as ClassificationCategory, rt as SubmitAssetOptions, s as ClassificationQualifierResults, st as UploadPresetSubmitAssetOptions, t as WebhookEventPayload, tt as SignedUploadToken, u as ModerationQualifier, ut as WebhookHeadersInput, v as AssetStatus, vt as EventCategory, w as CdnServeOptions, wt as Order, x as CalmLensAppClientOptions, xt as EventFacts, y as AssetType, yt as EventFact, z as IterateAssetsOptions } from "./WebhookPayload-Cgb32aSH.js";
+import { _ as ProcessingFeatureStage, a as CalmLensErrorDetails, c as ApiErrorCode, d as AgeRange, f as BoundingBox, g as ProcessingFeatureResults, h as ProcessingFeatureId, i as CalmLensErrorCode, l as FlaggedContentAction, m as DetectedPerson, n as CALMLENS_ERROR_CODES, o as CalmLensErrorOptions, p as DetectedFace, r as CalmLensError, s as SdkErrorCode, t as SDK_VERSION, u as FlaggedContentPolicy, v as ProcessingFeatures } from "./index-BgmWj3KL.js";
+//#region src/client/CalmLensServerClient.d.ts
+interface LensCache {
+  readonly ensuredLenses: Map<string, Lens>;
+  readonly pendingEnsureLenses: Map<string, Promise<void>>;
+}
+declare const inspectSymbol: unique symbol;
+/**
+ * The CalmLens API client for your server, authenticated with a project API key. Create one per
+ * project and reuse it; it holds no connections. Every method takes one options object and
+ * throws `CalmLensError` on failure. Browsers and apps upload with `CalmLensAppClient` instead.
+ */
+declare class CalmLensServerClient {
+  #private;
+  /**
+   * Verifies that a webhook delivery came from CalmLens: checks the `v1=` HMAC-SHA256 in
+   * `x-calmlens-signature` over `"<x-calmlens-timestamp>.<raw body>"` and rejects timestamps
+   * more than `toleranceSeconds` (default 300) from now, which stops replayed deliveries.
+   * Also exported as `verifyWebhookSignature`; `parseWebhookEvent` verifies and parses.
+   *
+   * @example
+   * ```ts
+   * const payload = await request.text();
+   * const isValid = await CalmLensServerClient.verifyWebhookSignature({
+   *   payload,
+   *   headers: request.headers,
+   *   secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+   * });
+   * ```
+   */
+  static verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+  constructor(options: CalmLensServerClientOptions, lenses?: LensCache);
+  /**
+   * A client with different cancellation, deadlines or retries for the calls made through it,
+   * sharing this client's credentials and lens cache. This client is unchanged.
+   */
+  withRequestOptions(options: RequestOptions): CalmLensServerClient;
+  /** Keeps the API key out of `console.log`, `util.inspect` and `JSON.stringify`. */
+  [inspectSymbol](): string;
+  toJSON(): {
+    projectId: string;
+    baseUrl: string;
+    cdnBaseUrl: string;
+  };
+  private get projectPath();
+  private request;
+  private submitAsset;
+  get cdn(): {
+    /**
+     * Builds a CDN URL for asset content or a preview, without a request. Private assets
+     * need a signed URL (`assets.createSignedUrl`) or an authenticated request.
+     */
+    getAssetUrl: ({ assetIdentifier, ...options }: CdnAssetUrlOptions) => string;
+    /**
+     * Fetches asset content or a preview from the CDN with the client's API key, and returns
+     * the `Response` as soon as headers arrive, so the body streams. Non-2xx responses are
+     * returned, not thrown; `timeoutMs` covers only the wait for headers.
+     */
+    serve: ({ assetIdentifier, init, ...urlOptions }: CdnServeOptions) => Promise<Response>;
+  };
+  get text(): {
+    /**
+     * Moderates text and waits for the decision. Sends `text` as `text/plain` content named
+     * `text` unless you pass `name`.
+     */
+    moderate: (options: ModerateTextOptions) => Promise<Asset>;
+  };
+  /** Assets: uploads, moderation and management. */
+  get assets(): {
+    /** Searches accessible assets by keyword or a natural-language description. */
+    search: (options: Partial<AssetSearchQuery> & {
+      query: string;
+    }) => Promise<AssetSearchResponse>;
+    /** Lists one page of the project's assets, with optional filter and ordering. */
+    list: (options?: ListAssetsOptions) => Promise<AssetPage>;
+    /**
+     * Yields every asset matching `options`, fetching pages as needed. Assets created or
+     * deleted while iterating can shift pages, so an asset may be skipped or repeated.
+     */
+    iterate: (options?: IterateAssetsOptions) => AsyncGenerator<Asset, void, undefined>;
+    /** Retrieves an asset with its status and moderation report. */
+    retrieve: ({ assetId }: RetrieveAssetOptions) => Promise<Asset>;
+    /** Updates an asset's editable fields. */
+    update: ({ assetId, ...body }: UpdateAssetOptions) => Promise<Asset>;
+    /** Lists one page of the assets extracted from a website or multimedia document. */
+    listChildren: ({ assetId, ...options }?: ListAssetChildrenOptions) => Promise<AssetChildrenPage>;
+    /** Yields every child of an asset, fetching pages as needed. */
+    iterateChildren: (options: IterateAssetChildrenOptions) => AsyncGenerator<Asset, void, undefined>;
+    /**
+     * Uploads an asset and queues it for moderation, returning immediately with status
+     * `pending` (or `uploading` for the first multipart part). Retried safely with an
+     * `Idempotency-Key`.
+     */
+    create: (options: SubmitAssetOptions) => Promise<Asset>;
+    /**
+     * Uploads an asset and waits for its moderation decision. Audio and video still finish
+     * in the background. Retried safely with an `Idempotency-Key`.
+     */
+    moderate: (options: SubmitAssetOptions) => Promise<Asset>;
+    /**
+     * Uploads the next part of a multipart upload. The upload's queue mode, chosen when it
+     * started, applies when the final part arrives; pass `queue` to override it.
+     */
+    uploadPart: ({ assetId, ...options }: UploadAssetPartOptions) => Promise<Asset>;
+    /**
+     * Creates a short-lived signed CDN URL, so browsers can load private content without
+     * an API key.
+     */
+    createSignedUrl: ({ assetId, ...options }: CreateAssetSignedUrlOptions) => Promise<PostAssetSignedUrlResponse>;
+    /** Moves an asset into a folder, or to the project root with `folderId: null`. */
+    move: ({ assetId, folderId }: MoveAssetOptions) => Promise<Asset>;
+    /**
+     * Processes an asset that failed (status `error`) again. It returns to `pending` and is
+     * moderated like a new upload; its content must still be stored.
+     */
+    retry: ({ assetId }: RetryAssetOptions) => Promise<Asset>;
+    /**
+     * Removes an asset's stored content (source, preview and retained extracted text) while
+     * keeping the asset record, metadata and moderation report. The returned asset has
+     * `storageDeletedAt` set; the CDN no longer serves it.
+     */
+    deleteContent: ({ assetId }: DeleteAssetContentOptions) => Promise<Asset>;
+    /** Deletes an asset record together with its stored content. */
+    delete: ({ assetId }: DeleteAssetOptions) => Promise<void>;
+  };
+  /**
+   * Signs upload tokens on your server, so a browser or app can upload through an upload preset
+   * that requires one. Signing happens locally with your API key: it makes no request.
+   */
+  get uploadTokens(): {
+    /**
+     * Signs a single-use token for one upload through `uploadPresetId`. Give `token` to the
+     * browser or app, which passes it to `CalmLensAppClient` as `token`.
+     */
+    sign: (options: SignUploadTokenOptions) => Promise<SignedUploadToken>;
+  };
+  private buildAssets;
+  get events(): {
+    /**
+     * Lists project events after a cursor, oldest first. Call without `after` to get a cursor
+     * for "now", then poll with the returned `cursor`. Webhook deliveries carry the same events
+     * reshaped as `{ id, type, createdAt, projectId, data }`.
+     */
+    list: (options?: ListEventsOptions) => Promise<GetEventsResponse>;
+    /**
+     * Yields pages of events after `after` until no more are waiting. Save each page's
+     * `cursor` to resume later. Without `after`, yields one empty page whose cursor is "now".
+     */
+    pages: (options?: ListEventsOptions) => AsyncGenerator<GetEventsResponse, void, undefined>;
+  };
+  private iterateEventPages;
+  private iteratePages;
+  get folders(): {
+    /** Lists every folder in the project. */
+    list: () => Promise<Folder[]>;
+    retrieve: ({ folderId }: FolderIdOptions) => Promise<Folder>;
+    /** Creates a folder at the project root or inside `parentId`. */
+    create: (options: CreateFolderOptions) => Promise<Folder>;
+    update: ({ folderId, ...body }: UpdateFolderOptions) => Promise<Folder>;
+    /** Deletes an empty folder; throws `folder/not-empty` otherwise. */
+    delete: ({ folderId }: FolderIdOptions) => Promise<void>;
+    /** Moves a folder under `parentId`, or to the project root with `parentId: null`. */
+    move: ({ folderId, parentId }: MoveFolderOptions) => Promise<Folder>;
+  };
+  /**
+   * Create a named lens at any positive version, or update it with a greater version.
+   * Supplying the same definition and version is idempotent.
+   */
+  ensureLens(options: EnsureLensOptions): Promise<Lens>;
+  /**
+   * Create or update several named lenses in one API request.
+   * Each lens follows the same versioning and idempotency rules as ensureLens().
+   */
+  ensureLenses({ lenses }: EnsureLensesOptions): Promise<Lens[]>;
+  private submitEnsureLenses;
+}
+//#endregion
+//#region src/client/CalmLensWebhooks.d.ts
+export declare const WEBHOOK_DELIVERY_HEADER = "x-calmlens-delivery";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "x-calmlens-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-calmlens-signature";
+/** Deliveries whose timestamp is further than this from the receiver's clock are rejected. */
+export declare const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+/**
+ * Verifies a webhook delivery: `x-calmlens-signature` must contain a `v1=` HMAC-SHA256 of
+ * `"<x-calmlens-timestamp>.<raw body>"`, and the timestamp must be within `toleranceSeconds`
+ * (default 300) of now. Returns `false` for anything missing, malformed or stale, and throws
+ * `sdk/invalid-argument` when `payload` is not a raw body (for example, parsed JSON).
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+/**
+ * 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`.
+ *
+ * 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`.
+ */
+export declare function parseWebhookEvent(options: VerifyWebhookSignatureOptions): Promise<WebhookEventPayload>;
+//#endregion
+export { type AgeRange, type ApiErrorCode, type Asset, type AssetChecksums, type AssetChildrenPage, type AssetContentOptions, type AssetPage, type AssetSafetyHold, type AssetSafetyHoldReason, type AssetSearchMatchField, type AssetSearchQuery, type AssetSearchResponse, type AssetSearchResult, type AssetStatus, type AssetType, type AssetVisibility, type BoundingBox, CALMLENS_ERROR_CODES, type CalmLensAppClientOptions, CalmLensError, type CalmLensErrorCode, type CalmLensErrorDetails, type CalmLensErrorOptions, CalmLensServerClient, type CalmLensServerClientOptions, type CdnAssetUrlOptions, type CdnServeOptions, type CdnTransform, type ClassificationCategories, type ClassificationCategory, type ClassificationCategoryReport, type ClassificationLabel, type ClassificationNotEvaluatedReason, type ClassificationQualifierResults, type ClassificationReport, type ConnectionOptions, type CreateAssetSignedUrlOptions, type CreateFolderOptions, type CreateMultipartUploadPartOptions, type DeleteAssetContentOptions, type DeleteAssetOptions, type DetectedFace, type DetectedPerson, type DocumentData, type EnsureLensOptions, type EnsureLensesOptions, type EventAsset, type EventCategory, type EventFact, type EventFactValues, type EventFacts, type EventSeverity, type EventType, type GetEventsResponse as EventsPage, type ExtractedText, type FlaggedContentAction, type FlaggedContentPolicy, type Folder, type FolderIdOptions, type IdempotencyOptions, type ImageData, type ImageTransform, type ImageTransformOptions, type IterateAssetChildrenOptions, type IterateAssetsOptions, type Lens, type LensTransform, type LensType, type Likelihood, type ListAssetChildrenOptions, type ListAssetsOptions, type ListEventsOptions, type MetadataItem, type ModerateTextOptions, type ModerationQualifier, type MoveAssetOptions, type MoveFolderOptions, type MultipartUploadOptions, type MultipartUploadPartOptions, type Order, type Page, type PreviewImage, type ProcessingFeatureId, type ProcessingFeatureResults, type ProcessingFeatureStage, type ProcessingFeatures, type ProcessingOptions, type RequestOptions, type RetrieveAssetOptions, type RetryAssetOptions, SDK_VERSION, type SdkErrorCode, type SearchAssetsOptions, type SignUploadTokenOptions, type SignedUploadToken, type SignedUrl, type SubmitAssetOptions, type TypedEvent, type UpdateAssetOptions, type UpdateFolderOptions, type UploadAssetPartOptions, type UploadPresetSubmitAssetOptions, type UploadedAsset, type VerifyWebhookSignatureOptions, type WebhookEventPayload, type WebhookHeadersInput, type WebhookPayloadInput };

package/esm/server.js

@@ -0,0 +1,361 @@
+import { a as invalidConfig, i as invalidArgument, n as CalmLensError, r as SDK_ERROR_CODES, t as CALMLENS_ERROR_CODES } from "./CalmLensError-CihGG26K.js";
+import { i as isReactNativeRuntime, r as isBrowserRuntime, t as SDK_VERSION } from "./src-CJhrILvM.js";
+import { a as parseWebhookEvent, i as WEBHOOK_TIMESTAMP_HEADER, l as stringifyJsonCanonical, n as WEBHOOK_SIGNATURE_HEADER, o as verifyWebhookSignature, r as WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, s as signUploadTokenWithApiKey, t as WEBHOOK_DELIVERY_HEADER } from "./CalmLensWebhooks-DShmAal4.js";
+import { a as toTextAssetOptions, c as validateRequestOptions, l as validateServerClientOptions, n as encodePathSegment, o as transformSelector, t as appendCdnSelector } from "./CalmLensUtils-Cx32j2zt.js";
+import { a as newIdempotencyKey, i as invalidPayload, n as expectAsset, o as prepareSubmitAssetOptions, s as resolveConnectionOptions, t as CalmLensConnection } from "./CalmLensConnection-wLNy0OIP.js";
+//#region src/client/CalmLensServerClient.ts
+const getEnsureLensCacheKey = (options) => stringifyJsonCanonical({
+	identifier: options.identifier,
+	name: options.name,
+	description: options.description ?? null,
+	type: options.type,
+	active: options.active,
+	transforms: options.transforms ?? null,
+	version: options.version
+});
+const requireId = (value, name) => encodePathSegment(value, name);
+const inspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+/**
+* The CalmLens API client for your server, authenticated with a project API key. Create one per
+* project and reuse it; it holds no connections. Every method takes one options object and
+* throws `CalmLensError` on failure. Browsers and apps upload with `CalmLensAppClient` instead.
+*/
+var CalmLensServerClient = class CalmLensServerClient {
+	#apiKey;
+	#settings;
+	#lenses;
+	#connection;
+	/**
+	* Verifies that a webhook delivery came from CalmLens: checks the `v1=` HMAC-SHA256 in
+	* `x-calmlens-signature` over `"<x-calmlens-timestamp>.<raw body>"` and rejects timestamps
+	* more than `toleranceSeconds` (default 300) from now, which stops replayed deliveries.
+	* Also exported as `verifyWebhookSignature`; `parseWebhookEvent` verifies and parses.
+	*
+	* @example
+	* ```ts
+	* const payload = await request.text();
+	* const isValid = await CalmLensServerClient.verifyWebhookSignature({
+	*   payload,
+	*   headers: request.headers,
+	*   secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+	* });
+	* ```
+	*/
+	static async verifyWebhookSignature(options) {
+		return verifyWebhookSignature(options);
+	}
+	constructor(options, lenses) {
+		validateServerClientOptions(options);
+		if ((isBrowserRuntime() || isReactNativeRuntime()) && !options.dangerouslyAllowBrowser) throw invalidConfig("CalmLensServerClient is running in a browser or app, where anyone could read the API key. Call CalmLens from your server, upload from the browser or app with CalmLensAppClient, or set dangerouslyAllowBrowser: true for trusted internal tools.");
+		const { apiKey, ...rest } = options;
+		this.#apiKey = apiKey;
+		this.#settings = {
+			...resolveConnectionOptions(rest),
+			cdnBaseUrl: (rest.cdnBaseUrl ?? `https://cdn.calmlens.com/v1`).replace(/\/+$/, "")
+		};
+		this.#lenses = lenses ?? {
+			ensuredLenses: /* @__PURE__ */ new Map(),
+			pendingEnsureLenses: /* @__PURE__ */ new Map()
+		};
+		this.#connection = new CalmLensConnection(this.#settings, apiKey);
+	}
+	/**
+	* A client with different cancellation, deadlines or retries for the calls made through it,
+	* sharing this client's credentials and lens cache. This client is unchanged.
+	*/
+	withRequestOptions(options) {
+		validateRequestOptions(options);
+		return new CalmLensServerClient({
+			...this.#settings,
+			...options,
+			apiKey: this.#apiKey
+		}, this.#lenses);
+	}
+	/** Keeps the API key out of `console.log`, `util.inspect` and `JSON.stringify`. */
+	[inspectSymbol]() {
+		const { projectId, baseUrl } = this.#settings;
+		return `CalmLensServerClient { projectId: ${JSON.stringify(projectId)}, baseUrl: ${JSON.stringify(baseUrl)} }`;
+	}
+	toJSON() {
+		const { projectId, baseUrl, cdnBaseUrl } = this.#settings;
+		return {
+			projectId,
+			baseUrl,
+			cdnBaseUrl
+		};
+	}
+	get projectPath() {
+		return `/projects/${encodeURIComponent(this.#settings.projectId)}`;
+	}
+	request(method, path, options = {}) {
+		return this.#connection.json(method, path, options);
+	}
+	async submitAsset(options, queue) {
+		const body = prepareSubmitAssetOptions(options);
+		const uploadsPath = `${this.projectPath}/assets`;
+		if ("content" in body || "part" in body) return expectAsset(await this.#connection.submitRawUpload(uploadsPath, body, queue));
+		const { idempotencyKey, ...fields } = body;
+		const data = await this.#connection.json("POST", uploadsPath, {
+			query: { queue },
+			body: fields,
+			idempotencyKey: idempotencyKey ?? newIdempotencyKey()
+		});
+		return expectAsset(data);
+	}
+	get cdn() {
+		return {
+			/**
+			* Builds a CDN URL for asset content or a preview, without a request. Private assets
+			* need a signed URL (`assets.createSignedUrl`) or an authenticated request.
+			*/
+			getAssetUrl: ({ assetIdentifier, ...options }) => {
+				const resource = options.resource ?? "content";
+				const { projectId } = this.#settings;
+				const url = `${this.#settings.cdnBaseUrl}/assets/${encodeURIComponent(projectId)}/${requireId(assetIdentifier, "Asset identifier")}/${resource}`;
+				return appendCdnSelector(url, options);
+			},
+			/**
+			* Fetches asset content or a preview from the CDN with the client's API key, and returns
+			* the `Response` as soon as headers arrive, so the body streams. Non-2xx responses are
+			* returned, not thrown; `timeoutMs` covers only the wait for headers.
+			*/
+			serve: async ({ assetIdentifier, init, ...urlOptions }) => {
+				const url = this.cdn.getAssetUrl({
+					assetIdentifier,
+					...urlOptions
+				});
+				const method = init?.method?.toUpperCase() ?? "GET";
+				const { response } = await this.#connection.transport.send({
+					method,
+					url,
+					init,
+					timeoutMs: this.#connection.timeoutMs,
+					deadline: "headers",
+					fetch: this.#settings.cdnFetch
+				}, { allowHttpErrors: true });
+				return response;
+			}
+		};
+	}
+	get text() {
+		return { 
+		/**
+		* Moderates text and waits for the decision. Sends `text` as `text/plain` content named
+		* `text` unless you pass `name`.
+		*/
+moderate: async (options) => this.buildAssets().moderate(toTextAssetOptions(options)) };
+	}
+	/** Assets: uploads, moderation and management. */
+	get assets() {
+		return this.buildAssets();
+	}
+	/**
+	* Signs upload tokens on your server, so a browser or app can upload through an upload preset
+	* that requires one. Signing happens locally with your API key: it makes no request.
+	*/
+	get uploadTokens() {
+		return { 
+		/**
+		* Signs a single-use token for one upload through `uploadPresetId`. Give `token` to the
+		* browser or app, which passes it to `CalmLensAppClient` as `token`.
+		*/
+sign: async (options) => {
+			return signUploadTokenWithApiKey(this.#apiKey, options);
+		} };
+	}
+	buildAssets() {
+		return {
+			/** Searches accessible assets by keyword or a natural-language description. */
+			search: async (options) => this.request("GET", `${this.projectPath}/assets/search`, { query: options }),
+			/** Lists one page of the project's assets, with optional filter and ordering. */
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/assets/page`, { query: {
+				...options,
+				pageIndex: options.pageIndex ?? 0
+			} }),
+			/**
+			* Yields every asset matching `options`, fetching pages as needed. Assets created or
+			* deleted while iterating can shift pages, so an asset may be skipped or repeated.
+			*/
+			iterate: (options = {}) => this.iteratePages((pageIndex) => this.buildAssets().list({
+				...options,
+				pageIndex
+			})),
+			/** Retrieves an asset with its status and moderation report. */
+			retrieve: async ({ assetId }) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}`),
+			/** Updates an asset's editable fields. */
+			update: async ({ assetId, ...body }) => this.request("PATCH", `/assets/${requireId(assetId, "Asset ID")}`, { body }),
+			/** Lists one page of the assets extracted from a website or multimedia document. */
+			listChildren: async ({ assetId, ...options } = {}) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}/children`, { query: {
+				...options,
+				pageIndex: options.pageIndex ?? 0
+			} }),
+			/** Yields every child of an asset, fetching pages as needed. */
+			iterateChildren: (options) => {
+				requireId(options?.assetId, "Asset ID");
+				return this.iteratePages((pageIndex) => this.buildAssets().listChildren({
+					...options,
+					pageIndex
+				}));
+			},
+			/**
+			* Uploads an asset and queues it for moderation, returning immediately with status
+			* `pending` (or `uploading` for the first multipart part). Retried safely with an
+			* `Idempotency-Key`.
+			*/
+			create: async (options) => this.submitAsset(options, true),
+			/**
+			* Uploads an asset and waits for its moderation decision. Audio and video still finish
+			* in the background. Retried safely with an `Idempotency-Key`.
+			*/
+			moderate: async (options) => {
+				if (options && "content" in options && "plainText" in options.content && (typeof options.content.plainText !== "string" || !options.content.plainText.trim())) throw invalidPayload("Text to moderate must be a non-empty string");
+				return this.submitAsset(options, false);
+			},
+			/**
+			* Uploads the next part of a multipart upload. The upload's queue mode, chosen when it
+			* started, applies when the final part arrives; pass `queue` to override it.
+			*/
+			uploadPart: async ({ assetId, ...options }) => {
+				const encodedAssetId = requireId(assetId, "Asset ID");
+				return expectAsset(await this.#connection.uploadPart(`/assets/${encodedAssetId}/part`, options));
+			},
+			/**
+			* Creates a short-lived signed CDN URL, so browsers can load private content without
+			* an API key.
+			*/
+			createSignedUrl: async ({ assetId, ...options }) => {
+				const encodedAssetId = requireId(assetId, "Asset ID");
+				if (options.lens && options.transform) throw invalidArgument("Specify either a lens or a transform, not both");
+				return this.request("POST", `/assets/${encodedAssetId}/signed-url`, { body: {
+					resource: options.resource ?? "content",
+					expiresInSeconds: options.expiresInSeconds ?? 900,
+					lens: options.lens,
+					transform: transformSelector(options.transform)
+				} });
+			},
+			/** Moves an asset into a folder, or to the project root with `folderId: null`. */
+			move: async ({ assetId, folderId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/move`, { body: { folderId } }),
+			/**
+			* Processes an asset that failed (status `error`) again. It returns to `pending` and is
+			* moderated like a new upload; its content must still be stored.
+			*/
+			retry: async ({ assetId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/retry`),
+			/**
+			* Removes an asset's stored content (source, preview and retained extracted text) while
+			* keeping the asset record, metadata and moderation report. The returned asset has
+			* `storageDeletedAt` set; the CDN no longer serves it.
+			*/
+			deleteContent: async ({ assetId }) => this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}/content`),
+			/** Deletes an asset record together with its stored content. */
+			delete: async ({ assetId }) => {
+				await this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}`);
+			}
+		};
+	}
+	get events() {
+		return {
+			/**
+			* Lists project events after a cursor, oldest first. Call without `after` to get a cursor
+			* for "now", then poll with the returned `cursor`. Webhook deliveries carry the same events
+			* reshaped as `{ id, type, createdAt, projectId, data }`.
+			*/
+			list: async (options = {}) => this.request("GET", `${this.projectPath}/events`, { query: { ...options } }),
+			/**
+			* Yields pages of events after `after` until no more are waiting. Save each page's
+			* `cursor` to resume later. Without `after`, yields one empty page whose cursor is "now".
+			*/
+			pages: (options = {}) => this.iterateEventPages(options)
+		};
+	}
+	async *iterateEventPages(options) {
+		let after = options.after;
+		for (;;) {
+			const page = await this.events.list({
+				...options,
+				after
+			});
+			yield page;
+			if (!page.hasMore || page.cursor === after) return;
+			after = page.cursor;
+		}
+	}
+	async *iteratePages(listPage) {
+		for (let pageIndex = 0;; pageIndex++) {
+			const page = await listPage(pageIndex);
+			yield* page.items;
+			if (!page.hasMore || page.items.length === 0) return;
+		}
+	}
+	get folders() {
+		return {
+			/** Lists every folder in the project. */
+			list: async () => (await this.request("GET", `${this.projectPath}/folders`)).folders,
+			retrieve: async ({ folderId }) => this.request("GET", `/folders/${requireId(folderId, "Folder ID")}`),
+			/** Creates a folder at the project root or inside `parentId`. */
+			create: async (options) => this.request("POST", `${this.projectPath}/folders`, { body: options }),
+			update: async ({ folderId, ...body }) => this.request("PATCH", `/folders/${requireId(folderId, "Folder ID")}`, { body }),
+			/** Deletes an empty folder; throws `folder/not-empty` otherwise. */
+			delete: async ({ folderId }) => {
+				await this.request("DELETE", `/folders/${requireId(folderId, "Folder ID")}`);
+			},
+			/** Moves a folder under `parentId`, or to the project root with `parentId: null`. */
+			move: async ({ folderId, parentId }) => this.request("POST", `/folders/${requireId(folderId, "Folder ID")}/move`, { body: { parentId } })
+		};
+	}
+	/**
+	* Create a named lens at any positive version, or update it with a greater version.
+	* Supplying the same definition and version is idempotent.
+	*/
+	async ensureLens(options) {
+		if (!options?.identifier) throw invalidArgument("Lens identifier is required");
+		const [lens] = await this.ensureLenses({ lenses: [options] });
+		return lens;
+	}
+	/**
+	* Create or update several named lenses in one API request.
+	* Each lens follows the same versioning and idempotency rules as ensureLens().
+	*/
+	async ensureLenses({ lenses }) {
+		if (!Array.isArray(lenses) || lenses.length === 0) throw invalidArgument("At least one lens is required");
+		if (lenses.some((option) => !option?.identifier)) throw invalidArgument("Lens identifier is required");
+		const { ensuredLenses, pendingEnsureLenses } = this.#lenses;
+		const missingOptions = [];
+		const missingKeys = /* @__PURE__ */ new Set();
+		for (const option of lenses) {
+			const cacheKey = getEnsureLensCacheKey(option);
+			if (!ensuredLenses.has(cacheKey) && !missingKeys.has(cacheKey)) {
+				missingKeys.add(cacheKey);
+				missingOptions.push(option);
+			}
+		}
+		if (missingOptions.length > 0) {
+			const batchCacheKey = JSON.stringify([...missingKeys].sort());
+			let pending = pendingEnsureLenses.get(batchCacheKey);
+			if (!pending) {
+				pending = this.submitEnsureLenses(missingOptions);
+				pendingEnsureLenses.set(batchCacheKey, pending);
+				pending.then(() => pendingEnsureLenses.delete(batchCacheKey), () => pendingEnsureLenses.delete(batchCacheKey));
+			}
+			await pending;
+		}
+		return lenses.map((option) => {
+			const lens = ensuredLenses.get(getEnsureLensCacheKey(option));
+			if (!lens) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `CalmLens did not return lens "${option.identifier}"` });
+			return lens;
+		});
+	}
+	async submitEnsureLenses(options) {
+		const result = await this.request("PUT", `${this.projectPath}/lenses`, { body: { lenses: options } });
+		const returned = Array.isArray(result?.lenses) ? result.lenses : [];
+		if (returned.length !== options.length) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected ${options.length} lenses but CalmLens returned ${returned.length}` });
+		const { ensuredLenses } = this.#lenses;
+		for (const [index, lens] of returned.entries()) {
+			const optionsForLens = options[index];
+			if (lens?.identifier !== optionsForLens.identifier) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected lens "${optionsForLens.identifier}" at position ${index}` });
+			for (const [cacheKey, cachedLens] of ensuredLenses) if (cachedLens.identifier === optionsForLens.identifier) ensuredLenses.delete(cacheKey);
+			ensuredLenses.set(getEnsureLensCacheKey(optionsForLens), lens);
+		}
+	}
+};
+//#endregion
+export { CALMLENS_ERROR_CODES, CalmLensError, CalmLensServerClient, SDK_VERSION, WEBHOOK_DELIVERY_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, WEBHOOK_TIMESTAMP_HEADER, parseWebhookEvent, verifyWebhookSignature };

package/esm/src-CJhrILvM.js

@@ -0,0 +1,22 @@
+import "./CalmLensError-CihGG26K.js";
+//#endregion
+//#region src/client/CalmLensVersion.ts
+/** This SDK's version, from its package.json. */
+const SDK_VERSION = "0.12.0";
+const runtimeName = () => {
+	const runtime = globalThis;
+	if (isReactNativeRuntime()) return "react-native";
+	if (runtime.Bun?.version) return `bun/${runtime.Bun.version}`;
+	if (runtime.Deno?.version?.deno) return `deno/${runtime.Deno.version.deno}`;
+	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return "workerd";
+	if (runtime.process?.versions?.node) return `node/${runtime.process.versions.node}`;
+	return "unknown";
+};
+/** The `User-Agent` the SDK sends from server runtimes, e.g. `calmlens-js/0.10.0 (node/22.12.0)`. */
+const getUserAgent = () => `calmlens-js/${SDK_VERSION} (${runtimeName()})`;
+/** True in a web page, where API keys would be visible to every visitor. */
+const isBrowserRuntime = () => typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+/** True in a React Native app, where an API key ships inside the app for anyone to extract. */
+const isReactNativeRuntime = () => globalThis.navigator?.product === "ReactNative";
+//#endregion
+export { isReactNativeRuntime as i, getUserAgent as n, isBrowserRuntime as r, SDK_VERSION as t };