@calmlens/sdk 0.12.0 → 0.13.0

package/esm/{CalmLensUtils-Cx32j2zt.js → CalmLensUtils-B4i3Z2He.js}

@@ -1,4 +1,4 @@
-import { a as invalidConfig, i as invalidArgument, n as CalmLensError, o as API_ERROR_CODES } from "./CalmLensError-CihGG26K.js";
+import { c as invalidArgument, l as invalidConfig, n as getUserAgent, o as CalmLensError, r as isBrowserRuntime, s as SDK_ERROR_CODES, u as API_ERROR_CODES } from "./CalmLensVersion-DK4BMEST.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([
@@ -97,6 +97,287 @@ const validateAssetPayload = (payload, options) => {
 	return { ok: true };
 };
 //#endregion
+//#region src/client/CalmLensTransport.ts
+/** Retry delays grow from this base, doubling per attempt, with jitter. */
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 8e3;
+/** A `Retry-After` longer than this is returned to the caller instead of waited out. */
+const RETRY_AFTER_MAX_MS = 6e4;
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+const timeoutReason = () => {
+	const reason = /* @__PURE__ */ new Error("The operation timed out.");
+	reason.name = "TimeoutError";
+	return reason;
+};
+/**
+* Links the callers' signals and a per-attempt deadline. `AbortSignal.any` holds its sources
+* weakly, so a long-lived caller signal doesn't collect a listener per streamed response;
+* runtimes without it get explicit listeners that `release` removes.
+*/
+const createAttemptSignal = (signals, timeoutMs) => {
+	const callers = signals.filter((signal) => signal !== void 0);
+	const deadline = new AbortController();
+	let timedOut = false;
+	let signal;
+	let onAbort;
+	if (typeof AbortSignal.any === "function") signal = AbortSignal.any([...callers, deadline.signal]);
+	else {
+		const controller = new AbortController();
+		signal = controller.signal;
+		onAbort = (event) => controller.abort(event.target.reason);
+		for (const source of [...callers, deadline.signal]) if (source.aborted) controller.abort(source.reason);
+		else source.addEventListener("abort", onAbort, { once: true });
+	}
+	let timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
+		timedOut = true;
+		deadline.abort(timeoutReason());
+	}, timeoutMs);
+	return {
+		signal,
+		isTimedOut: () => timedOut,
+		isCancelled: () => callers.some((caller) => caller.aborted),
+		clearDeadline: () => {
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+		},
+		release: () => {
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+			if (onAbort) for (const caller of callers) caller.removeEventListener("abort", onAbort);
+		}
+	};
+};
+/**
+* A redirect the SDK must not follow: it would send the API key to another origin. Browsers report
+* a manual redirect as an opaque response; other runtimes return the 3xx with its Location.
+*/
+const isRedirect = (response) => response.type === "opaqueredirect" || response.status >= 300 && response.status < 400 && response.headers.has("location");
+/** Turns anything thrown while sending or reading a request into a `CalmLensError`. */
+const toFailure = (cause, attempt) => {
+	if (CalmLensError.isCalmLensError(cause)) return cause;
+	if (attempt.isCancelled()) return new CalmLensError(SDK_ERROR_CODES.CANCELLED, {
+		message: "Request cancelled",
+		cause
+	});
+	if (attempt.isTimedOut()) return new CalmLensError(SDK_ERROR_CODES.TIMEOUT, {
+		message: "Request timed out",
+		cause
+	});
+	return new CalmLensError(SDK_ERROR_CODES.TRANSPORT_ERROR, {
+		message: "Request failed",
+		cause
+	});
+};
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+	if (signal?.aborted) {
+		reject(new CalmLensError(SDK_ERROR_CODES.CANCELLED, { message: "Request cancelled" }));
+		return;
+	}
+	const onAbort = () => {
+		clearTimeout(timer);
+		reject(new CalmLensError(SDK_ERROR_CODES.CANCELLED, { message: "Request cancelled" }));
+	};
+	const timer = setTimeout(() => {
+		signal?.removeEventListener("abort", onAbort);
+		resolve();
+	}, ms);
+	signal?.addEventListener("abort", onAbort, { once: true });
+});
+/** Exponential backoff with jitter: half the delay is fixed, the other half random. */
+const getRetryDelayMs = (attempt, random = Math.random) => {
+	const delay = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
+	return Math.round(delay / 2 + random() * (delay / 2));
+};
+/** Parses `Retry-After` as seconds or an HTTP date, in seconds from `now`. */
+const parseRetryAfter = (value, now = Date.now()) => {
+	if (!value) return void 0;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) return Number(trimmed);
+	const date = Date.parse(trimmed);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, Math.ceil((date - now) / 1e3));
+};
+/** Bodies that can be sent again unchanged. Streams are consumed by the first attempt. */
+const isReplayableBody = (body) => body === void 0 || body === null || typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof URLSearchParams;
+const isApiErrorPayload = (value) => !!value && typeof value === "object" && typeof value.code === "string";
+/** Reads at most `limit` bytes of a body, failing with `sdk/response-too-large` beyond that. */
+const readBody = async (response, limit) => {
+	const declared = Number(response.headers.get("content-length"));
+	const tooLarge = () => new CalmLensError(SDK_ERROR_CODES.RESPONSE_TOO_LARGE, {
+		message: `Response body exceeds ${limit} bytes`,
+		status: response.status,
+		requestId: response.headers.get("x-request-id") ?? void 0,
+		headers: response.headers
+	});
+	if (Number.isFinite(declared) && declared > limit) {
+		await response.body?.cancel().catch(() => {});
+		throw tooLarge();
+	}
+	if (!response.body) return /* @__PURE__ */ new Uint8Array(0);
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > limit) {
+			await reader.cancel().catch(() => {});
+			throw tooLarge();
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+};
+const responseInfo = (response) => ({
+	status: response.status,
+	requestId: response.headers.get("x-request-id") ?? void 0,
+	headers: response.headers,
+	retryAfter: parseRetryAfter(response.headers.get("retry-after"))
+});
+/** The `CalmLensError` for a non-2xx response whose body has been read. */
+const toHttpError = (response, bytes) => {
+	let data;
+	try {
+		data = JSON.parse(new TextDecoder().decode(bytes));
+	} catch {}
+	if (isApiErrorPayload(data)) {
+		const { code, message, details, traceId } = data;
+		return new CalmLensError(code, {
+			message: message ?? code,
+			...responseInfo(response),
+			details: details || traceId ? {
+				...details,
+				...traceId ? { traceId } : {}
+			} : void 0
+		});
+	}
+	return new CalmLensError(SDK_ERROR_CODES.HTTP_ERROR, {
+		message: `HTTP ${response.status}`,
+		...responseInfo(response)
+	});
+};
+/** Sends requests with the client's credentials, deadlines, retries and response limits. */
+var CalmLensTransport = class {
+	constructor(settings) {
+		this.settings = settings;
+	}
+	headersFor(request) {
+		const headers = new Headers(request.init?.headers);
+		for (const [name, value] of Object.entries(request.headers ?? {})) headers.set(name, value);
+		if (!headers.has("accept") && request.deadline === "body") headers.set("accept", "application/json");
+		if (this.settings.apiKey) headers.set("x-api-key", this.settings.apiKey);
+		if (!isBrowserRuntime()) headers.set("user-agent", getUserAgent());
+		if (request.idempotencyKey) headers.set("idempotency-key", request.idempotencyKey);
+		return Object.fromEntries(headers.entries());
+	}
+	canRetry(request) {
+		return this.settings.maxRetries > 0 && (request.method === "GET" || request.method === "HEAD" || !!request.idempotencyKey) && isReplayableBody(request.body);
+	}
+	/**
+	* Sends a request and returns the response, retrying transport failures, 429, 502–504 and
+	* `idempotency/request-in-progress` when the request is safe to repeat. Non-2xx responses
+	* throw unless `allowHttpErrors` is set. Call `release` once the body has been read.
+	*/
+	async send(request, { allowHttpErrors = false } = {}) {
+		const fetchImpl = request.fetch ?? this.settings.fetch;
+		const retryable = this.canRetry(request);
+		const headers = this.headersFor(request);
+		for (let attemptNumber = 0;; attemptNumber++) {
+			const canRetryAgain = retryable && attemptNumber < this.settings.maxRetries;
+			const attempt = createAttemptSignal([this.settings.signal, request.init?.signal ?? void 0], request.timeoutMs);
+			let response;
+			try {
+				if (attempt.signal.aborted) throw attempt.signal.reason;
+				response = await fetchImpl(request.url, {
+					...request.init,
+					method: request.method,
+					headers,
+					body: request.body,
+					redirect: "manual",
+					signal: attempt.signal,
+					duplex: "half"
+				});
+				if (isRedirect(response)) {
+					await response.body?.cancel().catch(() => {});
+					throw new CalmLensError(SDK_ERROR_CODES.TRANSPORT_ERROR, { message: `Unexpected redirect (HTTP ${response.status})` });
+				}
+			} catch (cause) {
+				attempt.release();
+				const failure = toFailure(cause, attempt);
+				if (canRetryAgain && failure.code === SDK_ERROR_CODES.TRANSPORT_ERROR) {
+					await sleep(getRetryDelayMs(attemptNumber), this.settings.signal);
+					continue;
+				}
+				throw failure;
+			}
+			if (request.deadline === "headers") attempt.clearDeadline();
+			if (response.ok) return {
+				response,
+				attempt
+			};
+			if (allowHttpErrors) {
+				const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+				const delayMs = retryAfter !== void 0 ? retryAfter * 1e3 : getRetryDelayMs(attemptNumber);
+				if (!canRetryAgain || !RETRYABLE_STATUSES.has(response.status) || delayMs > RETRY_AFTER_MAX_MS) return {
+					response,
+					attempt
+				};
+				attempt.release();
+				await response.body?.cancel().catch(() => {});
+				await sleep(delayMs, this.settings.signal);
+				continue;
+			}
+			let error;
+			try {
+				error = toHttpError(response, await readBody(response, this.settings.maxResponseBytes));
+			} catch (cause) {
+				error = toFailure(cause, attempt);
+			} finally {
+				attempt.release();
+			}
+			const retryDelayMs = error.retryAfter !== void 0 ? error.retryAfter * 1e3 : getRetryDelayMs(attemptNumber);
+			if (canRetryAgain && retryDelayMs <= RETRY_AFTER_MAX_MS && (error.status !== void 0 && RETRYABLE_STATUSES.has(error.status) || error.code === API_ERROR_CODES.IDEMPOTENT_REQUEST_IN_PROGRESS)) {
+				await sleep(retryDelayMs, this.settings.signal);
+				continue;
+			}
+			throw error;
+		}
+	}
+	/** Sends a request and parses its JSON response body. */
+	async json(request) {
+		const { response, attempt } = await this.send(request);
+		try {
+			const bytes = await readBody(response, this.settings.maxResponseBytes);
+			if (bytes.byteLength === 0 && (response.status === 204 || request.method === "DELETE")) return;
+			try {
+				return JSON.parse(new TextDecoder().decode(bytes));
+			} catch (cause) {
+				throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, {
+					message: `Invalid JSON response (HTTP ${response.status})`,
+					...responseInfo(response),
+					cause
+				});
+			}
+		} catch (cause) {
+			throw toFailure(cause, attempt);
+		} finally {
+			attempt.release();
+		}
+	}
+};
+//#endregion
 //#region src/client/CalmLensUtils.ts
 const assertHttpUrl = (name, value) => {
 	if (value === void 0) return;
@@ -256,5 +537,38 @@ const stringifyQuery = (query) => {
 	for (const [key, value] of Object.entries(query)) appendQueryValue(parts, key, value);
 	return parts.join("&");
 };
+/** Statuses that are a moderation decision; `assets.waitForDecision` returns at the first. */
+const DECIDED_ASSET_STATUSES = [
+	"approved",
+	"rejected",
+	"error"
+];
+const DECISION_POLL_FIRST_DELAY_MS = 500;
+const DECISION_POLL_MAX_DELAY_MS = 5e3;
+const DEFAULT_DECISION_TIMEOUT_MS = 6e4;
+/**
+* Retrieves an asset until it has a decision, waiting 0.5s between checks and 1.5 times longer
+* each time, up to 5s. Rejects with `sdk/timeout` once `timeoutMs` passes without one.
+*/
+const pollForDecision = async (retrieve, { timeoutMs = DEFAULT_DECISION_TIMEOUT_MS, signal }, sleep, now = Date.now) => {
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw invalidArgument("timeoutMs must be a non-negative number");
+	const deadline = now() + timeoutMs;
+	let delay = DECISION_POLL_FIRST_DELAY_MS;
+	for (;;) {
+		if (signal?.aborted) throw new CalmLensError(SDK_ERROR_CODES.CANCELLED, { message: "Request cancelled" });
+		const asset = await retrieve();
+		if (DECIDED_ASSET_STATUSES.includes(asset.status)) return asset;
+		const remaining = deadline - now();
+		if (remaining <= 0) throw new CalmLensError(SDK_ERROR_CODES.TIMEOUT, {
+			message: `Asset ${asset.id} had no moderation decision after ${timeoutMs}ms (status ${asset.status})`,
+			details: {
+				assetId: asset.id,
+				status: asset.status
+			}
+		});
+		await sleep(Math.min(delay, remaining), signal);
+		delay = Math.min(DECISION_POLL_MAX_DELAY_MS, delay * 1.5);
+	}
+};
 //#endregion
-export { getRejectedUploadMimeTypeError as _, toTextAssetOptions as a, validateRequestOptions as c, assetToData as d, getAssetPayloadByteLength as f, MIN_MULTIPART_IMAGE_UPLOAD_BYTES as g, MAX_IMAGE_UPLOAD_BYTES as h, stringifyQuery as i, validateServerClientOptions as l, DOMAIN as m, encodePathSegment as n, transformSelector as o, validateAssetPayload as p, randomUuid as r, validateAppClientOptions as s, appendCdnSelector as t, assetDataToUint8Array as u, isRejectedUploadMimeType as v };
+export { DOMAIN as _, stringifyQuery as a, getRejectedUploadMimeTypeError as b, validateAppClientOptions as c, CalmLensTransport as d, sleep as f, validateAssetPayload as g, getAssetPayloadByteLength as h, randomUuid as i, validateRequestOptions as l, assetToData as m, encodePathSegment as n, toTextAssetOptions as o, assetDataToUint8Array as p, pollForDecision as r, transformSelector as s, appendCdnSelector as t, validateServerClientOptions as u, MAX_IMAGE_UPLOAD_BYTES as v, isRejectedUploadMimeType as x, MIN_MULTIPART_IMAGE_UPLOAD_BYTES as y };

package/esm/{CalmLensError-CihGG26K.js → CalmLensVersion-DK4BMEST.js}

@@ -11,6 +11,7 @@ const API_ERROR_CODES = {
 	MULTIPART_IMAGE_TOO_LARGE: "upload/multipart-image-too-large",
 	IMAGE_EXCEEDED_MAX_DIMENSIONS: "upload/image-exceeded-max-dimensions",
 	UPLOAD_LIMIT_EXCEEDED: "upload/limit-exceeded",
+	SPEND_LIMIT_REACHED: "upload/spend-limit-reached",
 	INVALID_UPLOAD_MIME_TYPE: "upload/invalid-mime-type",
 	INVALID_EVENT_CURSOR: "events/invalid-cursor",
 	INVALID_UPLOAD_PAYLOAD: "upload/invalid-payload",
@@ -89,6 +90,10 @@ const API_ERROR_DEFINITIONS = {
 		status: 403,
 		message: "Upload limit exceeded. You have used all your free uploads. Please upgrade to Plus or Pro for unlimited uploads."
 	},
+	"upload/spend-limit-reached": {
+		status: 402,
+		message: "The project owner's spend limit for this billing period has been reached. Raise the limit in Billing to resume uploads."
+	},
 	"upload/invalid-mime-type": {
 		status: 400,
 		message: "Upload file type is not supported. 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."
@@ -318,4 +323,23 @@ const invalidArgument = (message, details) => new CalmLensError(SDK_ERROR_CODES.
 });
 const invalidConfig = (message) => new CalmLensError(SDK_ERROR_CODES.INVALID_CONFIG, { message });
 //#endregion
-export { invalidConfig as a, invalidArgument as i, CalmLensError as n, API_ERROR_CODES as o, SDK_ERROR_CODES as r, API_ERROR_DEFINITIONS as s, CALMLENS_ERROR_CODES as t };
+//#region src/client/CalmLensVersion.ts
+/** This SDK's version, from its package.json. */
+const SDK_VERSION = "0.13.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 { CALMLENS_ERROR_CODES as a, invalidArgument as c, API_ERROR_DEFINITIONS as d, isReactNativeRuntime as i, invalidConfig as l, getUserAgent as n, CalmLensError as o, isBrowserRuntime as r, SDK_ERROR_CODES as s, SDK_VERSION as t, API_ERROR_CODES as u };

package/esm/{CalmLensWebhooks-DShmAal4.js → CalmLensWebhooks-DyCoEvpf.js}

@@ -1,5 +1,5 @@
-import { i as invalidArgument, n as CalmLensError, r as SDK_ERROR_CODES } from "./CalmLensError-CihGG26K.js";
-import { n as encodePathSegment } from "./CalmLensUtils-Cx32j2zt.js";
+import { c as invalidArgument, o as CalmLensError, s as SDK_ERROR_CODES } from "./CalmLensVersion-DK4BMEST.js";
+import { n as encodePathSegment } from "./CalmLensUtils-B4i3Z2He.js";
 //#region ../shared/src/JsonUtils.ts
 const stringifyJsonCanonical = (value) => JSON.stringify(value, (_key, nestedValue) => {
 	if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) return nestedValue;