@viso-lol/sdk 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,685 @@
+// src/bytes.ts
+/** Copies a view's bytes: a view may cover only part of a buffer, or a shared buffer. */
+function viewBytes(view) {
+	return new Uint8Array(view.buffer, view.byteOffset, view.byteLength).slice();
+}
+/** A function, not an inline check, so TypeScript does not narrow `aborted` across awaits. */
+function isAborted(signal) {
+	return signal?.aborted === true;
+}
+// src/errors.ts
+/** An error response from the API: `{ error: { code, message, details?, requestId } }`. */
+var VisoError = class extends Error {
+	/** Stable machine-readable code, for example `images.file_exists`. */
+	code;
+	/** HTTP status. */
+	status;
+	/** Include it when reporting a problem. */
+	requestId;
+	details;
+	headers;
+	constructor(init) {
+		super(init.message);
+		this.name = "VisoError";
+		this.code = init.code;
+		this.status = init.status;
+		this.requestId = init.requestId;
+		this.details = init.details;
+		this.headers = init.headers ?? new Headers();
+	}
+};
+/** The request never got a response: network failure or timeout. */
+var VisoConnectionError = class extends Error {
+	/** True when the SDK gave up after `timeoutMs`. */
+	timeout;
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "VisoConnectionError";
+		this.timeout = options.timeout ?? false;
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Builds a `VisoError` from any failed response, including non-JSON ones from proxies. */
+async function errorFromResponse(response) {
+	const headerRequestId = response.headers.get("x-request-id");
+	const text = await response.text().catch(() => "");
+	let body;
+	try {
+		body = JSON.parse(text);
+	} catch {
+		body = void 0;
+	}
+	const envelope = isRecord(body) && isRecord(body["error"]) ? body["error"] : void 0;
+	const code = envelope?.["code"];
+	const message = envelope?.["message"];
+	const requestId = envelope?.["requestId"];
+	const details = envelope?.["details"];
+	return new VisoError({
+		code: typeof code === "string" ? code : "internal",
+		status: response.status,
+		message: typeof message === "string" ? message : `The API answered ${response.status} ${response.statusText}`.trim(),
+		requestId: typeof requestId === "string" ? requestId : headerRequestId,
+		details: isRecord(details) ? details : void 0,
+		headers: response.headers
+	});
+}
+// src/images-input.ts
+function isBinary(source) {
+	return source instanceof Blob || source instanceof ArrayBuffer || ArrayBuffer.isView(source);
+}
+function toBlob(source) {
+	if (source instanceof Blob) return source;
+	if (source instanceof ArrayBuffer) return new Blob([source]);
+	return new Blob([viewBytes(source)]);
+}
+function base64ToBlob(base64) {
+	const data = base64.startsWith("data:") ? base64.slice(base64.indexOf(",") + 1) : base64;
+	const binary = atob(data);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return new Blob([bytes]);
+}
+/**
+* Face endpoints take JSON (`{ base64 }` or `{ fileId }` images) or multipart (image
+* files). Bytes go as multipart, which avoids base64's 33% overhead; options then travel
+* as JSON-encoded form fields so that, for example, the external ID `"123"` stays a string.
+*/
+function faceBody(images, options) {
+	const sources = Object.entries(images);
+	if (!sources.some(([, source]) => isBinary(source))) return { json: {
+		...options,
+		...images
+	} };
+	const form = new FormData();
+	for (const [field, source] of sources) if (isBinary(source)) form.append(field, toBlob(source), field);
+	else if ("fileId" in source) form.append(field, source.fileId);
+	else form.append(field, base64ToBlob(source.base64), field);
+	for (const [name, value] of Object.entries(options)) if (value !== void 0) form.append(name, JSON.stringify(value));
+	return { form };
+}
+// src/pagination.ts
+function paginate(fetchPage, firstCursor) {
+	const first = fetchPage(firstCursor);
+	async function* items() {
+		let page = await first;
+		while (true) {
+			yield* page.data;
+			if (page.nextCursor === null) return;
+			page = await fetchPage(page.nextCursor);
+		}
+	}
+	return Object.assign(first, { [Symbol.asyncIterator]: items });
+}
+// src/resources/face.ts
+const segment$1 = encodeURIComponent;
+var FacesResource = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	/** Detects faces in the image and stores them in the collection, largest first. */
+	index(collectionId, params, options) {
+		const { image, ...rest } = params;
+		return this.#client.request({
+			method: "POST",
+			path: `/face/collections/${segment$1(collectionId)}/faces`,
+			...faceBody({ image }, rest),
+			options
+		});
+	}
+	/** Faces of a collection, oldest first. Iterate with `for await` to read every page. */
+	list(collectionId, params = {}, options) {
+		return paginate((cursor) => this.#client.request({
+			method: "GET",
+			path: `/face/collections/${segment$1(collectionId)}/faces`,
+			query: {
+				externalId: params.externalId,
+				limit: params.limit,
+				cursor
+			},
+			options
+		}), params.cursor);
+	}
+	delete(collectionId, faceId, options) {
+		return this.#client.request({
+			method: "DELETE",
+			path: `/face/collections/${segment$1(collectionId)}/faces/${segment$1(faceId)}`,
+			options
+		});
+	}
+	/** Searches the collection for faces similar to a stored face. */
+	search(collectionId, faceId, params = {}, options) {
+		return this.#client.request({
+			method: "POST",
+			path: `/face/collections/${segment$1(collectionId)}/faces/${segment$1(faceId)}/search`,
+			json: params,
+			options
+		});
+	}
+};
+var CollectionsResource = class {
+	faces;
+	#client;
+	constructor(client) {
+		this.#client = client;
+		this.faces = new FacesResource(client);
+	}
+	create(params, options) {
+		return this.#client.request({
+			method: "POST",
+			path: "/face/collections",
+			json: params,
+			options
+		});
+	}
+	list(options) {
+		return paginate(() => this.#client.request({
+			method: "GET",
+			path: "/face/collections",
+			options
+		}));
+	}
+	get(collectionId, options) {
+		return this.#client.request({
+			method: "GET",
+			path: `/face/collections/${segment$1(collectionId)}`,
+			options
+		});
+	}
+	/** Deletion is accepted at once and finishes in the background. */
+	delete(collectionId, options) {
+		return this.#client.request({
+			method: "DELETE",
+			path: `/face/collections/${segment$1(collectionId)}`,
+			options
+		});
+	}
+	/** Searches the collection for the largest face in the image. */
+	search(collectionId, params, options) {
+		const { image, ...rest } = params;
+		return this.#client.request({
+			method: "POST",
+			path: `/face/collections/${segment$1(collectionId)}/search`,
+			...faceBody({ image }, rest),
+			options
+		});
+	}
+};
+var FaceResource = class {
+	collections;
+	#client;
+	constructor(client) {
+		this.#client = client;
+		this.collections = new CollectionsResource(client);
+	}
+	/** Finds faces with their box, landmarks, pose and quality, plus requested attributes. */
+	detect(params, options) {
+		const { image, ...rest } = params;
+		return this.#client.request({
+			method: "POST",
+			path: "/face/detect",
+			...faceBody({ image }, rest),
+			options
+		});
+	}
+	/** Compares the largest face in `source` with every face in `target`. */
+	compare(params, options) {
+		const { source, target, ...rest } = params;
+		return this.#client.request({
+			method: "POST",
+			path: "/face/compare",
+			...faceBody({
+				source,
+				target
+			}, rest),
+			options
+		});
+	}
+};
+// src/resources/images.ts
+const segment = encodeURIComponent;
+var BucketsResource = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	create(params, options) {
+		return this.#client.request({
+			method: "POST",
+			path: "/images/buckets",
+			json: params,
+			options
+		});
+	}
+	list(options) {
+		return paginate(() => this.#client.request({
+			method: "GET",
+			path: "/images/buckets",
+			options
+		}));
+	}
+	get(bucketId, options) {
+		return this.#client.request({
+			method: "GET",
+			path: `/images/buckets/${segment(bucketId)}`,
+			options
+		});
+	}
+	/** Changing visibility or cache lifetime purges the bucket's cached files. */
+	update(bucketId, params, options) {
+		return this.#client.request({
+			method: "PATCH",
+			path: `/images/buckets/${segment(bucketId)}`,
+			json: params,
+			options
+		});
+	}
+	/** Deletes the bucket and every file in it; stored bytes are removed in the background. */
+	delete(bucketId, options) {
+		return this.#client.request({
+			method: "DELETE",
+			path: `/images/buckets/${segment(bucketId)}`,
+			options
+		});
+	}
+};
+var FilesResource = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	/**
+	* Files ordered by path. The promise resolves to the first page (with `folders` when
+	* `delimiter` is `/`); `for await` iterates the files of every page.
+	*/
+	list(params, options) {
+		const { bucketId, cursor: firstCursor, ...query } = params;
+		return paginate((cursor) => this.#client.request({
+			method: "GET",
+			path: `/images/buckets/${segment(bucketId)}/files`,
+			query: {
+				...query,
+				cursor
+			},
+			options
+		}), firstCursor);
+	}
+	get(fileId, options) {
+		return this.#client.request({
+			method: "GET",
+			path: `/images/files/${segment(fileId)}`,
+			options
+		});
+	}
+	delete(fileId, options) {
+		return this.#client.request({
+			method: "DELETE",
+			path: `/images/files/${segment(fileId)}`,
+			options
+		});
+	}
+	/** Deletes up to 100 files of a bucket at once. */
+	deleteMany(params, options) {
+		const { bucketId, ...json } = params;
+		return this.#client.request({
+			method: "POST",
+			path: `/images/buckets/${segment(bucketId)}/files/delete`,
+			json,
+			options
+		});
+	}
+	/** A time-limited CDN URL, required for files in private buckets. */
+	createSignedUrl(fileId, params = {}, options) {
+		return this.#client.request({
+			method: "POST",
+			path: `/images/files/${segment(fileId)}/signed-url`,
+			json: params,
+			options
+		});
+	}
+};
+function contentTypeOf(params) {
+	if (params.contentType !== void 0) return params.contentType;
+	return params.body instanceof Blob && params.body.type !== "" ? params.body.type : void 0;
+}
+var ImagesResource = class {
+	buckets;
+	files;
+	#client;
+	constructor(client) {
+		this.#client = client;
+		this.buckets = new BucketsResource(client);
+		this.files = new FilesResource(client);
+	}
+	/**
+	* Uploads a file from your server. Bytes are sent as the raw request body; streams are
+	* forwarded as they are read. The file type is detected from its content.
+	*/
+	upload(params, options) {
+		return this.#client.request({
+			method: "POST",
+			path: `/images/buckets/${segment(params.bucketId)}/files`,
+			query: {
+				path: params.path,
+				name: params.name,
+				overwrite: params.overwrite === void 0 ? void 0 : String(params.overwrite)
+			},
+			body: ArrayBuffer.isView(params.body) ? viewBytes(params.body) : params.body,
+			contentType: contentTypeOf(params),
+			options
+		});
+	}
+	/**
+	* A single-use URL a browser can `PUT` one image to without an API key. Create it on
+	* your server and pass `uploadUrl` to `uploadToSignedUrl` in the browser.
+	*/
+	createUploadUrl(params, options) {
+		const { bucketId, ...json } = params;
+		return this.#client.request({
+			method: "POST",
+			path: `/images/buckets/${segment(bucketId)}/upload-urls`,
+			json,
+			options
+		});
+	}
+};
+// src/resources/usage.ts
+var UsageResource = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	/** The team's quotas, the project's recent requests and the per-key rate limit. */
+	get(options) {
+		return this.#client.request({
+			method: "GET",
+			path: "/usage",
+			options
+		});
+	}
+};
+// src/retry.ts
+const BASE_DELAY_MS = 500;
+const MAX_BACKOFF_MS = 8e3;
+/** Never wait longer than this for one retry, whatever `Retry-After` says. */
+const MAX_RETRY_AFTER_MS = 6e4;
+/** Methods that are safe to repeat when the outcome of a request is unknown. */
+const IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"PUT",
+	"DELETE"
+]);
+/**
+* 429 and 503 mean the request was not processed (the API refunds quota on 503), so they
+* are retried for any method. Other 5xx and network errors may have had side effects, so
+* only idempotent methods retry them.
+*/
+function isRetryableStatus(status, method) {
+	if (status === 429 || status === 503) return true;
+	return status >= 500 && IDEMPOTENT_METHODS.has(method);
+}
+function isRetryableConnectionError(method) {
+	return IDEMPOTENT_METHODS.has(method);
+}
+/** `Retry-After` in milliseconds (delta seconds or an HTTP date), or `undefined`. */
+function parseRetryAfter(value, now = Date.now()) {
+	if (value === null || value.trim() === "") return;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(value);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+/** Exponential backoff with jitter for retry `attempt` (0-based), honoring `Retry-After`. */
+function retryDelay(attempt, retryAfter = null, random = Math.random) {
+	const fromHeader = parseRetryAfter(retryAfter);
+	if (fromHeader !== void 0) return Math.min(fromHeader, MAX_RETRY_AFTER_MS);
+	const backoff = Math.min(MAX_BACKOFF_MS, BASE_DELAY_MS * 2 ** attempt);
+	return Math.round(backoff * (.75 + random() * .25));
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+// src/client.ts
+const VERSION = "0.1.0";
+const DEFAULT_BASE_URL = "https://api.viso.lol/v1";
+function environmentVariable(name) {
+	const process = Reflect.get(globalThis, "process");
+	if (typeof process !== "object" || process === null) return;
+	const env = Reflect.get(process, "env");
+	if (typeof env !== "object" || env === null) return;
+	const value = Reflect.get(env, name);
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/** Read through `globalThis` so the SDK type-checks without the DOM library (Workers). */
+function isBrowser() {
+	const browserWindow = Reflect.get(globalThis, "window");
+	return typeof browserWindow === "object" && browserWindow !== null && Reflect.get(browserWindow, "document") !== void 0;
+}
+/** Streams can be read once, so requests that send one are never retried. */
+function isReplayable(body) {
+	return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+}
+/**
+* Combines the caller's signal with a per-attempt timeout. `timedOut()` tells our own
+* timeout apart from the caller aborting.
+*/
+function attemptSignal(timeoutMs, signal) {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort(/* @__PURE__ */ new Error(`Request timed out after ${timeoutMs} ms.`));
+	}, timeoutMs);
+	const onAbort = () => controller.abort(signal?.reason);
+	if (signal?.aborted === true) onAbort();
+	else signal?.addEventListener("abort", onAbort, { once: true });
+	return {
+		signal: controller.signal,
+		timedOut: () => timedOut,
+		done: () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		}
+	};
+}
+/**
+* The viso.lol API client.
+*
+* ```ts
+* const viso = new Viso({ apiKey: process.env.VISO_API_KEY });
+* const { faces } = await viso.face.detect({ image: await file.arrayBuffer() });
+* ```
+*/
+var Viso = class {
+	face;
+	images;
+	usage;
+	baseUrl;
+	maxRetries;
+	timeoutMs;
+	#apiKey;
+	#fetch;
+	constructor(options = {}) {
+		const apiKey = options.apiKey ?? environmentVariable("VISO_API_KEY");
+		if (apiKey === void 0 || apiKey === "") throw new Error("Missing API key. Pass `apiKey` or set the VISO_API_KEY environment variable.");
+		if (isBrowser() && options.dangerouslyAllowBrowser !== true) throw new Error("The viso.lol SDK is running in a browser, which would expose your secret API key. Call the API from your server, and upload from browsers with signed upload URLs (`uploadToSignedUrl`). For local experiments only, pass `dangerouslyAllowBrowser: true`.");
+		this.#apiKey = apiKey;
+		this.baseUrl = (options.baseUrl ?? environmentVariable("VISO_BASE_URL") ?? "https://api.viso.lol/v1").trim().replace(/\/+$/, "");
+		this.maxRetries = options.maxRetries ?? 2;
+		this.timeoutMs = options.timeoutMs ?? 6e4;
+		const customFetch = options.fetch;
+		this.#fetch = customFetch ?? ((input, init) => fetch(input, init));
+		this.face = new FaceResource(this);
+		this.images = new ImagesResource(this);
+		this.usage = new UsageResource(this);
+	}
+	/** Sends a request, retrying when it is safe, and returns the parsed JSON body. */
+	request(request) {
+		const url = new URL(`${this.baseUrl}${request.path}`);
+		for (const [name, value] of Object.entries(request.query ?? {})) if (value !== void 0) url.searchParams.set(name, String(value));
+		const headers = new Headers({
+			Authorization: `Bearer ${this.#apiKey}`,
+			Accept: "application/json"
+		});
+		let body;
+		if (request.json !== void 0) {
+			headers.set("Content-Type", "application/json");
+			body = JSON.stringify(request.json);
+		} else if (request.form !== void 0) body = request.form;
+		else if (request.body !== void 0) {
+			headers.set("Content-Type", request.contentType ?? "application/octet-stream");
+			body = request.body;
+		}
+		const options = request.options ?? {};
+		return this.#attempt({
+			url,
+			method: request.method,
+			headers,
+			body,
+			signal: options.signal,
+			timeoutMs: options.timeoutMs ?? this.timeoutMs,
+			maxRetries: isReplayable(body) ? options.maxRetries ?? this.maxRetries : 0,
+			attempt: 0
+		});
+	}
+	async #attempt(state) {
+		const { url, method, body, signal } = state;
+		const abort = attemptSignal(state.timeoutMs, signal);
+		const init = {
+			method,
+			headers: state.headers,
+			signal: abort.signal
+		};
+		if (body !== void 0) {
+			init.body = body;
+			if (!isReplayable(body)) init.duplex = "half";
+		}
+		const canRetry = state.attempt < state.maxRetries;
+		const retry = async (retryAfter = null) => {
+			await sleep(retryDelay(state.attempt, retryAfter), signal);
+			return this.#attempt({
+				...state,
+				attempt: state.attempt + 1
+			});
+		};
+		let response;
+		try {
+			response = await this.#fetch(url, init);
+		} catch (error) {
+			abort.done();
+			if (isAborted(signal)) throw signal?.reason;
+			if (canRetry && isRetryableConnectionError(method)) return retry();
+			const timeout = abort.timedOut();
+			throw new VisoConnectionError(timeout ? `The request to ${url.pathname} timed out after ${state.timeoutMs} ms.` : `Could not reach the viso.lol API at ${url.origin}.`, {
+				cause: error,
+				timeout
+			});
+		}
+		try {
+			if (response.ok) return await response.json();
+			if (!canRetry || !isRetryableStatus(response.status, method)) throw await errorFromResponse(response);
+			await response.body?.cancel();
+		} finally {
+			abort.done();
+		}
+		return retry(response.headers.get("Retry-After"));
+	}
+};
+// src/upload.ts
+function withName(uploadUrl, body, name) {
+	const fileName = name ?? (typeof File !== "undefined" && body instanceof File ? body.name : "");
+	if (fileName === "") return uploadUrl;
+	const url = new URL(uploadUrl);
+	url.searchParams.set("name", fileName.slice(0, 255));
+	return url.toString();
+}
+function contentType(body) {
+	return body instanceof Blob && body.type !== "" ? body.type : "application/octet-stream";
+}
+function isXhrConstructor(value) {
+	return typeof value === "function";
+}
+/** `XMLHttpRequest` reports upload progress; `fetch` cannot. */
+function browserXhr() {
+	const value = Reflect.get(globalThis, "XMLHttpRequest");
+	return isXhrConstructor(value) ? value : void 0;
+}
+function viaXhr(XhrClass, url, body, options) {
+	return new Promise((resolve, reject) => {
+		const xhr = new XhrClass();
+		xhr.open("PUT", url);
+		xhr.setRequestHeader("Content-Type", contentType(body));
+		xhr.upload.addEventListener("progress", (event) => {
+			options.onProgress?.({
+				loaded: event.loaded,
+				total: event.lengthComputable ? event.total : null
+			});
+		});
+		xhr.addEventListener("load", () => {
+			const headers = new Headers();
+			const requestId = xhr.getResponseHeader("x-request-id");
+			if (requestId !== null) headers.set("x-request-id", requestId);
+			resolve(new Response(xhr.responseText, {
+				status: xhr.status,
+				headers
+			}));
+		});
+		xhr.addEventListener("error", () => reject(new VisoConnectionError("The upload failed.")));
+		xhr.addEventListener("timeout", () => reject(new VisoConnectionError("The upload timed out.", { timeout: true })));
+		xhr.addEventListener("abort", () => reject(options.signal?.reason));
+		options.signal?.addEventListener("abort", () => xhr.abort(), { once: true });
+		xhr.send(body instanceof Blob ? body : new Blob([toBytes(body)]));
+	});
+}
+function toBytes(body) {
+	return body instanceof ArrayBuffer ? new Uint8Array(body) : viewBytes(body);
+}
+/**
+* Uploads one file to a signed upload URL created on your server with
+* `viso.images.createUploadUrl()`. Safe in browsers: the URL is the credential and it
+* works once. Uploads are not retried automatically; a rejected upload (wrong type, too
+* large) leaves the URL usable for another attempt.
+*/
+async function uploadToSignedUrl(uploadUrl, body, options = {}) {
+	if (isAborted(options.signal)) throw options.signal?.reason;
+	const url = withName(uploadUrl, body, options.name);
+	let response;
+	const XhrClass = options.fetch === void 0 ? browserXhr() : void 0;
+	if (XhrClass !== void 0) response = await viaXhr(XhrClass, url, body, options);
+	else {
+		const send = options.fetch ?? ((input, init) => fetch(input, init));
+		try {
+			response = await send(url, {
+				method: "PUT",
+				headers: { "Content-Type": contentType(body) },
+				body: body instanceof Blob ? body : toBytes(body),
+				signal: options.signal ?? null
+			});
+		} catch (error) {
+			if (isAborted(options.signal)) throw options.signal?.reason;
+			throw new VisoConnectionError("The upload failed.", { cause: error });
+		}
+	}
+	if (!response.ok) throw await errorFromResponse(response);
+	return await response.json();
+}
+export { DEFAULT_BASE_URL, VERSION, Viso, VisoConnectionError, VisoError, uploadToSignedUrl };
+
+//# sourceMappingURL=index.js.map