@calmlens/sdk 0.12.0 → 0.13.0

package/esm/CalmLensConnection-wLNy0OIP.js

@@ -1,475 +0,0 @@
-import { i as invalidArgument, n as CalmLensError, o as API_ERROR_CODES, r as SDK_ERROR_CODES } from "./CalmLensError-CihGG26K.js";
-import { n as getUserAgent, r as isBrowserRuntime } from "./src-CJhrILvM.js";
-import { _ as getRejectedUploadMimeTypeError, d as assetToData, f as getAssetPayloadByteLength, g as MIN_MULTIPART_IMAGE_UPLOAD_BYTES, h as MAX_IMAGE_UPLOAD_BYTES, i as stringifyQuery, p as validateAssetPayload, r as randomUuid, v as isRejectedUploadMimeType } from "./CalmLensUtils-Cx32j2zt.js";
-//#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/CalmLensConnection.ts
-const DEFAULT_TIMEOUT_MS = 12e4;
-const DEFAULT_MAX_RETRIES = 2;
-const DEFAULT_MAX_RESPONSE_BYTES = 33554432;
-/**
-* Bytes as a fetch body. They're sent as they are rather than in a Blob: React Native can't
-* build a Blob from bytes, and every fetch accepts a Uint8Array.
-*/
-const toBodyBytes = (value) => value.buffer instanceof ArrayBuffer ? value : Uint8Array.from(value);
-const toRawUploadBody = (payload) => {
-	const data = assetToData(payload);
-	if (data instanceof Response) {
-		if (!data.body) throw new CalmLensError(API_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message: "Response upload data must have a body" });
-		return data.body;
-	}
-	if (data instanceof ArrayBuffer || data instanceof Blob) return data;
-	if ("getReader" in data) return data;
-	return toBodyBytes(data);
-};
-const setOptionalQueryValue = (params, key, value) => {
-	if (value !== void 0 && value !== null) params.set(key, typeof value === "string" ? value : JSON.stringify(value));
-};
-const assertValidUploadMimeType = (mimeType) => {
-	if (isRejectedUploadMimeType(mimeType)) throw new CalmLensError(API_ERROR_CODES.INVALID_UPLOAD_MIME_TYPE, {
-		message: getRejectedUploadMimeTypeError(mimeType),
-		details: { mimeType }
-	});
-};
-const isImageMimeType = (mimeType) => mimeType.toLowerCase().startsWith("image/");
-const invalidPayload = (message) => new CalmLensError(API_ERROR_CODES.INVALID_UPLOAD_PAYLOAD, { message });
-/** Checks upload options before anything is sent. */
-const prepareSubmitAssetOptions = (options) => {
-	if (!options || typeof options !== "object") throw invalidArgument("Asset options are required");
-	if (!("content" in options) && !("url" in options) && !("part" in options)) throw invalidPayload("Either file content, URL, or multipart part is required");
-	if (!options.name) throw invalidPayload("Asset name is required");
-	if (!("part" in options) && "isFinal" in options) throw invalidPayload("isFinal is only valid for multipart uploads");
-	if ("part" in options && options.part.partNumber && options.part.partNumber > 1) throw new CalmLensError(API_ERROR_CODES.USE_UPLOAD_PART, { message: "Use uploadPart for multipart upload parts after the first part" });
-	if ("content" in options) {
-		assertValidUploadMimeType(options.content.type);
-		if (!("plainText" in options.content)) {
-			const validation = validateAssetPayload(options.content);
-			if (!validation.ok) throw invalidPayload(validation.error);
-		}
-	}
-	if ("part" in options) {
-		assertValidUploadMimeType(options.part.type);
-		const partSizeInBytes = options.part.sizeInBytes ?? getAssetPayloadByteLength(options.part);
-		if (isImageMimeType(options.part.type) && partSizeInBytes !== void 0) {
-			if (partSizeInBytes > MAX_IMAGE_UPLOAD_BYTES) throw new CalmLensError(API_ERROR_CODES.MULTIPART_IMAGE_TOO_LARGE, { message: "Multipart image uploads cannot exceed 20MB." });
-			if (options.part.isFinal && partSizeInBytes < MIN_MULTIPART_IMAGE_UPLOAD_BYTES) throw new CalmLensError(API_ERROR_CODES.MULTIPART_IMAGE_TOO_SMALL, { message: "Multipart image uploads must total at least 10MB." });
-		}
-		const validation = validateAssetPayload(options.part, {
-			multipart: true,
-			isFinal: options.part.isFinal
-		});
-		if (!validation.ok) throw invalidPayload(validation.error);
-	}
-	return options;
-};
-const newIdempotencyKey = () => randomUuid();
-/** Text content is small, so it keeps the API deadline; binary files may be arbitrarily large. */
-const isTextPayload = (payload) => "plainText" in payload;
-const isAsset = (data) => !!data && typeof data === "object" && typeof data.id === "string" && !!data.id && typeof data.status === "string";
-const isUploadedAsset = (data) => !!data && typeof data === "object" && typeof data.id === "string" && !!data.id;
-const expectUploadedAsset = (data) => {
-	if (!isUploadedAsset(data)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, {
-		message: "Expected an uploaded asset response",
-		status: 200
-	});
-	return data;
-};
-const expectAsset = (data) => {
-	if (!isAsset(data)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, {
-		message: "Expected an asset response",
-		status: 200
-	});
-	return data;
-};
-/** Fills in the default API base URL and drops trailing slashes. */
-const resolveConnectionOptions = (options) => ({
-	...options,
-	baseUrl: (options.baseUrl ?? `https://api.calmlens.com/v1`).replace(/\/+$/, "")
-});
-/** One client's transport, base URL and deadlines, and the requests both clients make. */
-var CalmLensConnection = class {
-	constructor(options, apiKey) {
-		this.options = options;
-		const resolveFetch = () => {
-			const fetchImpl = this.options.fetch ?? globalThis.fetch;
-			if (typeof fetchImpl !== "function") throw new CalmLensError(SDK_ERROR_CODES.NO_FETCH, { message: "No fetch implementation is available; pass one as the fetch option" });
-			return fetchImpl;
-		};
-		this.transport = new CalmLensTransport({
-			apiKey,
-			fetch: ((input, init) => resolveFetch()(input, init)),
-			signal: options.signal,
-			maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
-			maxResponseBytes: options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES
-		});
-	}
-	get timeoutMs() {
-		return this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-	}
-	url(path, query) {
-		const search = query ? stringifyQuery(query) : "";
-		return `${this.options.baseUrl}${path}${search ? `?${search}` : ""}`;
-	}
-	/** A JSON request whose deadline covers reading the response. */
-	json(method, path, { query, body, headers, idempotencyKey } = {}) {
-		return this.transport.json({
-			method,
-			url: this.url(path, query),
-			headers: body === void 0 ? headers : {
-				...headers,
-				"Content-Type": "application/json"
-			},
-			body: body === void 0 ? void 0 : JSON.stringify(body),
-			idempotencyKey,
-			timeoutMs: this.timeoutMs,
-			deadline: "body"
-		});
-	}
-	upload(url, payload, headers, idempotencyKey) {
-		return this.transport.json({
-			method: "POST",
-			url,
-			headers,
-			body: toRawUploadBody(payload),
-			idempotencyKey,
-			timeoutMs: isTextPayload(payload) ? this.timeoutMs : this.options.uploadTimeoutMs,
-			deadline: "body",
-			fetch: this.options.uploadFetch
-		});
-	}
-	/**
-	* Uploads file content or a first multipart part to `uploadsPath` (`.../assets`), as raw
-	* bytes with the options in the query.
-	*/
-	submitRawUpload(uploadsPath, options, queue, authHeaders = {}) {
-		const query = new URLSearchParams();
-		query.set("name", options.name);
-		query.set("queue", String(queue));
-		setOptionalQueryValue(query, "description", options.description);
-		setOptionalQueryValue(query, "processingOptions", options.processingOptions);
-		setOptionalQueryValue(query, "visibility", options.visibility);
-		setOptionalQueryValue(query, "metadata", options.metadata);
-		setOptionalQueryValue(query, "externalId", options.externalId);
-		setOptionalQueryValue(query, "externalUrl", options.externalUrl);
-		setOptionalQueryValue(query, "folderId", options.folderId);
-		setOptionalQueryValue(query, "uploadPresetId", options.uploadPresetId);
-		const isMultipart = "part" in options;
-		const payload = isMultipart ? options.part : options.content;
-		query.set("contentType", payload.type);
-		setOptionalQueryValue(query, "sizeInBytes", payload.sizeInBytes ?? getAssetPayloadByteLength(payload));
-		if (isMultipart) {
-			const part = payload;
-			const multipartOptions = options;
-			query.set("partNumber", String(part.partNumber ?? 1));
-			query.set("isFinal", String(part.isFinal ?? false));
-			setOptionalQueryValue(query, "sizeInBytes", part.sizeInBytes ?? multipartOptions.sizeInBytes);
-			setOptionalQueryValue(query, "totalSizeInBytes", multipartOptions.totalSizeInBytes);
-		}
-		const path = isMultipart ? "multipart-upload" : "upload";
-		return this.upload(this.url(`${uploadsPath}/${path}?${query}`), payload, {
-			...authHeaders,
-			"Content-Type": payload.type,
-			"X-CalmLens-Upload": isMultipart ? "part" : "content"
-		}, options.idempotencyKey ?? newIdempotencyKey());
-	}
-	/** Uploads the next part of a multipart upload to `partPath` (`.../assets/{id}/part`). */
-	uploadPart(partPath, { part, queue, idempotencyKey }, authHeaders = {}) {
-		if (!part) throw invalidArgument("Part options are required");
-		const validation = validateAssetPayload(part, {
-			multipart: true,
-			isFinal: part.isFinal
-		});
-		if (!validation.ok) throw invalidPayload(validation.error);
-		const query = new URLSearchParams({
-			partNumber: String(part.partNumber),
-			isFinal: String(part.isFinal ?? false)
-		});
-		if (queue !== void 0) query.set("queue", String(queue));
-		setOptionalQueryValue(query, "sizeInBytes", part.sizeInBytes ?? getAssetPayloadByteLength(part));
-		return this.upload(this.url(`${partPath}?${query}`), part, {
-			...authHeaders,
-			"X-CalmLens-Upload": "part"
-		}, idempotencyKey ?? newIdempotencyKey());
-	}
-};
-//#endregion
-export { newIdempotencyKey as a, invalidPayload as i, expectAsset as n, prepareSubmitAssetOptions as o, expectUploadedAsset as r, resolveConnectionOptions as s, CalmLensConnection as t };

package/esm/src-CJhrILvM.js

@@ -1,22 +0,0 @@
-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 };