@cloudraker/milliseconds 0.1.0

package/dist/index.cjs

@@ -0,0 +1,456 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/** A brand property, so a duplicated copy of the package in a bundle still matches. */
+const BRAND = "~milliseconds.error";
+/**
+* One error class. Switch on `code`: the union narrows exhaustively and never goes stale
+* when the API adds a code.
+*/
+var MillisecondsError = class extends Error {
+	name = "MillisecondsError";
+	[BRAND] = true;
+	code;
+	/** 0 when the call never reached the API. */
+	status;
+	/** The API's own message, unchanged. `message` adds one hint line. */
+	apiMessage;
+	/** Seconds from the retry-after header. Only 429 rate_limit_exceeded carries it. */
+	retryAfter;
+	rateLimit;
+	response;
+	/** Attempts this call made, including the first. */
+	attempts;
+	/** True for the codes the SDK retries. */
+	retryable;
+	constructor(init) {
+		super(init.message ?? init.apiMessage, init.cause === void 0 ? void 0 : { cause: init.cause });
+		this.code = init.code;
+		this.status = init.status ?? 0;
+		this.apiMessage = init.apiMessage;
+		this.retryAfter = init.retryAfter ?? null;
+		this.rateLimit = init.rateLimit ?? null;
+		this.response = init.response ?? null;
+		this.attempts = init.attempts ?? 1;
+		this.retryable = init.retryable ?? false;
+	}
+};
+function isMillisecondsError(e) {
+	return typeof e === "object" && e !== null && e[BRAND] === true;
+}
+/** Every client-side check throws this: status 0, code client_error, nothing sent. */
+const clientError = (message) => new MillisecondsError({
+	code: "client_error",
+	status: 0,
+	apiMessage: message
+});
+//#endregion
+//#region src/validate.ts
+const MAX_CHARS = 2e4;
+const MAX_TEXTS = 32;
+const MAX_ITEMS = 32;
+const n = (x) => x.toLocaleString("en-US");
+const count = (size) => size === 1 ? "1 entry" : `${n(size)} entries`;
+/** The key is a secret, so a browser bundle needs an explicit opt-in. */
+function checkRuntime(apiKey, allowBrowser) {
+	if (!apiKey) throw clientError("No API key. Pass new DecisionMachine({ apiKey }) or set MS_API_KEY. Get a key at https://console.milliseconds.ai.");
+	if (typeof globalThis === "object" && typeof globalThis.document?.createElement === "function" && !allowBrowser) throw clientError("The API key is a secret. Call the API from your server, or pass dangerouslyAllowBrowser: true when the bundle never reaches a user.");
+}
+/**
+* `texts` is 1 to 32 items, and every text is 1 to 20,000 characters.
+*
+* An empty text is a 400, not the 200-with-empty-results trap. That trap needs `text` and
+* `texts` both absent, and the SDK always sends one of them. This check only replaces a
+* round trip with a local error.
+*/
+function checkInput(input) {
+	if (typeof input === "string") {
+		if (input === "") throw empty("text");
+		if (input.length > MAX_CHARS) throw tooLong("text", input.length);
+		return;
+	}
+	if (input.length === 0) throw clientError("texts is empty. Send at least one text.");
+	if (input.length > MAX_TEXTS) throw clientError(`texts has ${n(input.length)} items. The limit is ${n(MAX_TEXTS)}. Split the batch.`);
+	for (const [i, text] of input.entries()) {
+		if (text === "") throw empty(`texts[${i}]`);
+		if (text.length > MAX_CHARS) throw tooLong(`texts[${i}]`, text.length);
+	}
+}
+const empty = (where) => clientError(`${where} is empty. Send at least one character.`);
+const tooLong = (where, length) => clientError(`${where} is ${n(length)} characters. The limit is ${n(MAX_CHARS)}. Split on paragraphs and send the parts as texts.`);
+/**
+* `statements` and `questions` are 1 to 32 items. The wire message for a body without one
+* is `provide statement or statements, not both`, which names both fields and misleads.
+*/
+function checkSpec(name, value) {
+	if (typeof value === "string") {
+		if (value !== "") return;
+		if (name === "statements") throw clientError("yes-no needs a statement. The wire message for a body without one names both fields and misleads.");
+		throw clientError(`${name} has 0 items. Send 1 to ${MAX_ITEMS}.`);
+	}
+	if (value.length === 0 || value.length > MAX_ITEMS) throw clientError(`${name} has ${n(value.length)} items. Send 1 to ${MAX_ITEMS}.`);
+}
+/**
+* `labels` is 2 to 64, `types` is 1 to 64 and `scale` is 2 to 10. Three limits, because
+* `decide.schema.ts` holds three. One shared rule would reject a legal single-type
+* `entities` call.
+*
+* `decide.schema.ts` bounds the array branch of `labels` and `types` only: the
+* `name -> description` branch is a plain `z.record`, so any number of described labels is
+* legal. `classify-tree` passes `bounded` because its own `superRefine` bounds every level.
+*/
+function checkList(name, value, min, max, capability, bounded = Array.isArray(value)) {
+	const size = Array.isArray(value) ? value.length : Object.keys(value).length;
+	if (bounded ? size >= min && size <= max : size > 0) return;
+	const found = size === 0 ? `${name} is empty.` : `${name} has ${count(size)}.`;
+	throw clientError(`${found} ${capability} needs ${min} to ${max}.`);
+}
+/** `planFor` throws unless the schema is an object with properties. Beat it locally. */
+function checkSchema(schema) {
+	const s = schema;
+	if ((Array.isArray(s?.type) ? s.type.find((t) => t !== "null") : s?.type) !== "object" || typeof s?.properties !== "object" || s.properties === null) throw clientError("The schema must be an object with properties.");
+}
+//#endregion
+//#region src/client.ts
+const USER_AGENT = `cloudraker-milliseconds-js/0.1.0`;
+const DEFAULT_BASE_URL = "https://api.milliseconds.ai";
+const RETRY = /* @__PURE__ */ new Set([
+	"rate_limit_exceeded",
+	"runner_error",
+	"overloaded",
+	"connection_error",
+	"timeout"
+]);
+/** Full jitter, capped at 8 s. */
+const backoff = (n) => Math.random() * Math.min(500 * 2 ** n, 8e3);
+/** Resolves early when the caller aborts. The loop then throws the caller's reason. */
+const sleep = (ms, signal) => new Promise((resolve) => {
+	const timer = setTimeout(resolve, ms);
+	signal?.addEventListener("abort", () => {
+		clearTimeout(timer);
+		resolve();
+	}, { once: true });
+});
+/** Reads an environment variable without assuming `process` exists. */
+function env(name) {
+	try {
+		return globalThis.process?.env?.[name];
+	} catch {
+		return;
+	}
+}
+/** A Promise of the result, with the headers one call away. No Promise subclass. */
+const decision = (p) => {
+	const result = p.then((r) => r.result);
+	return Object.assign(result, { withUsage: () => {
+		result.catch(() => {});
+		return p;
+	} });
+};
+function rateLimitOf(h) {
+	const limitRequests = h.get("x-ratelimit-limit-requests");
+	if (limitRequests === null) return null;
+	const num = (k) => Number(h.get(k)) || 0;
+	return {
+		limitRequests: Number(limitRequests) || 0,
+		remainingRequests: num("x-ratelimit-remaining-requests"),
+		resetRequests: h.get("x-ratelimit-reset-requests") ?? "",
+		limitTokens: num("x-ratelimit-limit-tokens"),
+		remainingTokens: num("x-ratelimit-remaining-tokens"),
+		resetTokens: h.get("x-ratelimit-reset-tokens") ?? ""
+	};
+}
+function usageOf(response) {
+	const h = response.headers;
+	const num = (k) => Number(h.get(k)) || 0;
+	return {
+		inputChars: num("x-input-chars"),
+		inputTokens: num("x-input-tokens"),
+		inferenceMs: num("x-inference-ms"),
+		rateLimit: rateLimitOf(h),
+		headers: h
+	};
+}
+/** The hint line under the API message. Section 8.2 of DESIGN.md holds the copy. */
+function describe(code, status, apiMessage, attempts, ms) {
+	const over = attempts > 1 ? ` after ${attempts} attempts over ${(ms / 1e3).toFixed(1)}s` : "";
+	const tail = apiMessage ? `:\n${apiMessage}` : ".";
+	switch (code) {
+		case "missing_api_key":
+		case "invalid_api_key": return `milliseconds rejected the API key (${status} ${code}).\nKeys start with "sk-ms-". Check MS_API_KEY, or create a key at\nhttps://console.milliseconds.ai.`;
+		case "rate_limit_exceeded": return `rate limited (${status} ${code})${over}${tail}\n  Lower your concurrency, or raise maxRetries. Limits are per organization and\n  shared by every key.`;
+		case "insufficient_quota": return `no token credits left (${status} ${code})${tail}\n  Not retried. A timer retry will not help.`;
+		case "overloaded": return `every inference slot stayed busy (${status} ${code})${over}${tail}\n  This is backpressure, not a fault. Send fewer texts per call, or back off further.\n  A texts batch of 32 asks for 32 slots at once.`;
+		case "runner_error": return `inference failed twice (${status} ${code})${over}${tail}\n  The model, not your request. Retry later, or raise maxRetries.`;
+		case "timeout": return `the request timed out${over}${tail}\n  Raise timeout, or send fewer texts per call.`;
+		case "connection_error": return `could not reach the API${over}${tail}\n  Check baseUrl and the network. maxRetries: 0 fails fast.`;
+		default: return `milliseconds rejected the request (${status} ${code})${tail}${apiMessage.startsWith("labels:") ? "\n  classify needs two or more labels. Describe each one. Described labels score\n  measurably better than bare names." : ""}`;
+	}
+}
+/** One AbortSignal for the attempt: the per-attempt timeout, plus the caller's signal. */
+function attemptSignal(timeout, signal) {
+	const hasAny = typeof AbortSignal.any === "function";
+	if (typeof AbortSignal.timeout === "function" && (!signal || hasAny)) {
+		const t = AbortSignal.timeout(timeout);
+		return {
+			signal: signal ? AbortSignal.any([signal, t]) : t,
+			done: () => {}
+		};
+	}
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), timeout);
+	signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+	return {
+		signal: controller.signal,
+		done: () => clearTimeout(timer)
+	};
+}
+/** Transport: fetch, retries, errors and usage. Every capability is two lines on top. */
+var Client = class {
+	baseUrl;
+	#apiKey;
+	#timeout;
+	#maxRetries;
+	#headers;
+	#fetch;
+	constructor(options = {}) {
+		const apiKey = options.apiKey ?? env("MS_API_KEY");
+		checkRuntime(apiKey, options.dangerouslyAllowBrowser);
+		this.#apiKey = apiKey;
+		this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+		this.#timeout = options.timeout ?? 6e4;
+		this.#maxRetries = options.maxRetries ?? 2;
+		this.#headers = { ...options.headers };
+		this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	/** Escape hatch. Your path, your body, your type, the SDK's auth, retries and errors. */
+	post(path, body, options) {
+		return this.call(path, body, options, (raw) => raw);
+	}
+	/** `unwrap` maps the parsed body to the result. It follows the request, never the response. */
+	call(path, body, options, unwrap) {
+		return decision(this.send(path, body, options ?? {}).then(({ response, raw }) => ({
+			result: unwrap(raw),
+			usage: usageOf(response),
+			response
+		})));
+	}
+	async send(path, body, call) {
+		const url = `${this.baseUrl}${path}`;
+		const maxRetries = call.maxRetries ?? this.#maxRetries;
+		const timeout = call.timeout ?? this.#timeout;
+		const headers = new Headers({
+			"content-type": "application/json",
+			"user-agent": USER_AGENT
+		});
+		for (const [k, v] of Object.entries({
+			...this.#headers,
+			...call.headers
+		})) headers.set(k, v);
+		headers.set("authorization", `Bearer ${this.#apiKey}`);
+		const init = {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		};
+		const started = Date.now();
+		for (let attempt = 1;; attempt++) {
+			if (call.signal?.aborted) throw call.signal.reason;
+			const outcome = await this.attempt(url, init, timeout, call.signal, attempt, started);
+			if (!(outcome instanceof MillisecondsError)) return outcome;
+			if (!outcome.retryable || attempt > maxRetries) throw outcome;
+			const wait = outcome.retryAfter === null ? backoff(attempt - 1) : Math.min(outcome.retryAfter, 60) * 1e3;
+			await sleep(wait, call.signal);
+		}
+	}
+	async attempt(url, init, timeout, signal, attempt, started) {
+		const guard = attemptSignal(timeout, signal);
+		try {
+			const response = await this.#fetch(url, {
+				...init,
+				signal: guard.signal
+			});
+			if (response.ok) return {
+				response,
+				raw: await response.json()
+			};
+			return await httpError(response, attempt, Date.now() - started);
+		} catch (cause) {
+			if (signal?.aborted) throw cause;
+			return transportError(cause, attempt, Date.now() - started);
+		} finally {
+			guard.done();
+		}
+	}
+};
+function transportError(cause, attempts, ms) {
+	const name = cause?.name ?? "";
+	const code = name === "TimeoutError" || name === "AbortError" ? "timeout" : "connection_error";
+	const apiMessage = cause?.message ?? String(cause);
+	return new MillisecondsError({
+		code,
+		status: 0,
+		apiMessage,
+		message: describe(code, 0, apiMessage, attempts, ms),
+		attempts,
+		retryable: true,
+		cause
+	});
+}
+async function httpError(response, attempts, ms) {
+	const body = await response.clone().json().catch(() => null);
+	const code = body?.error?.code ?? (response.status >= 500 ? "internal_error" : "http_error");
+	const apiMessage = body?.error?.message ?? response.statusText;
+	const retryAfter = response.headers.get("retry-after");
+	return new MillisecondsError({
+		code,
+		status: response.status,
+		apiMessage,
+		message: describe(code, response.status, apiMessage, attempts, ms),
+		retryAfter: retryAfter === null ? null : Number(retryAfter) || 0,
+		rateLimit: rateLimitOf(response.headers),
+		response,
+		attempts,
+		retryable: RETRY.has(code) || response.status >= 502 && response.status <= 504
+	});
+}
+//#endregion
+//#region src/schema.ts
+/**
+* Brands a JSON Schema with the type it produces. One cast, no runtime cost.
+*
+* `dm.extract(text, typed<z.infer<typeof S>>(z.toJSONSchema(S)))`
+*/
+const typed = (schema) => schema;
+const CONVERT = "Pass a JSON Schema. zod: typed<z.infer<typeof S>>(z.toJSONSchema(S)). valibot: typed<v.InferOutput<typeof S>>(toJsonSchema(S)). arktype works directly.";
+/**
+* The object to send. A Standard Schema with a converter method (arktype) is converted.
+* A Standard Schema without one cannot be: the SDK has zero dependencies, so it names the
+* one line that converts it instead of importing zod.
+*/
+function toJsonSchema(schema) {
+	const s = schema;
+	const convert = typeof s.toJsonSchema === "function" ? s.toJsonSchema : s.toJSONSchema;
+	if (typeof convert === "function") return convert.call(s);
+	if ("~standard" in s) throw new MillisecondsError({
+		code: "invalid_schema",
+		status: 0,
+		apiMessage: CONVERT
+	});
+	return s;
+}
+//#endregion
+//#region src/decision-machine.ts
+const MODEL = "decision-machine-1";
+/** The batch shape follows the request, never the response. */
+const same = (raw) => raw;
+const key = (name) => (raw) => raw[name];
+/** `text` for one result, `texts` for a batch. The mutual exclusion is impossible here. */
+const inputBody = (input) => typeof input === "string" ? { text: input } : { texts: input };
+/**
+* `decision-machine-1` at api.milliseconds.ai. Every capability is a pure function, so
+* every retry is safe.
+*/
+var DecisionMachine = class extends Client {
+	/** Paths are `${baseUrl}/v1/${model}/<capability>`. */
+	static model = MODEL;
+	/**
+	* Answers each statement with yes or no and a probability. The statements share one
+	* inference call, so extra statements are nearly free.
+	*/
+	yesNo(input, statements, options) {
+		checkInput(input);
+		checkSpec("statements", statements);
+		const { when_true, when_false, ...call } = options ?? {};
+		const body = {
+			...inputBody(input),
+			...typeof statements === "string" ? { statement: statements } : { statements },
+			...when_true === void 0 ? {} : { when_true },
+			...when_false === void 0 ? {} : { when_false }
+		};
+		return this.capability("yes-no", body, input, call, typeof statements === "string" ? same : key("results"));
+	}
+	/** Picks one label and returns the full distribution. Describe each label. */
+	classify(input, labels, options) {
+		checkInput(input);
+		checkList("labels", labels, 2, 64, "classify");
+		return this.capability("classify", {
+			...inputBody(input),
+			labels
+		}, input, options, same);
+	}
+	/**
+	* Runs classify once per level of a nested tree, descending into the winner.
+	*
+	* The per-level `input_chars` and `input_tokens` do not sum to `Usage.inputChars`: the
+	* header counts one pass over the body, and each level re-sends the text.
+	*/
+	classifyTree(input, tree, options) {
+		checkInput(input);
+		checkList("labels", tree, 2, 64, "classify-tree", true);
+		return this.capability("classify-tree", {
+			...inputBody(input),
+			tree
+		}, input, options, same);
+	}
+	/** Places the text on an ordered scale of described levels, low to high. */
+	rate(input, scale, options) {
+		checkInput(input);
+		checkList("scale", scale, 2, 10, "rate");
+		return this.capability("rate", {
+			...inputBody(input),
+			scale
+		}, input, options, same);
+	}
+	/** Quotes the answer out of the text, with its offsets. `answer` is null when nothing fits. */
+	answer(input, questions, options) {
+		checkInput(input);
+		checkSpec("questions", questions);
+		const body = {
+			...inputBody(input),
+			...typeof questions === "string" ? { question: questions } : { questions }
+		};
+		return this.capability("answer", body, input, options, typeof questions === "string" ? same : key("results"));
+	}
+	/**
+	* Fills a JSON Schema from the text. Missing values are null, arrays of objects come back
+	* empty, arrays of scalars come back as strings, and enums are not checked server side.
+	*/
+	extract(input, schema, options) {
+		checkInput(input);
+		const json = toJsonSchema(schema);
+		checkSchema(json);
+		return this.capability("extract", {
+			...inputBody(input),
+			schema: json
+		}, input, options, key("data"));
+	}
+	/** Finds every span matching each type, with offsets, sorted by start. */
+	entities(input, types, options) {
+		checkInput(input);
+		checkList("types", types, 1, 64, "entities");
+		return this.capability("entities", {
+			...inputBody(input),
+			types
+		}, input, options, key("entities"));
+	}
+	/** Checks whether the text says `value` for `field`. */
+	verify(input, field, value, options) {
+		checkInput(input);
+		const body = {
+			...inputBody(input),
+			field: typeof field === "string" ? { name: field } : field,
+			value
+		};
+		return this.capability("verify", body, input, options, same);
+	}
+	/** `{ results }` is unwrapped for a batch, and the per-text envelope for one text. */
+	capability(name, body, input, options, one) {
+		const unwrap = typeof input === "string" ? one : (raw) => (raw.results ?? []).map(one);
+		return this.call(`/v1/${MODEL}/${name}`, body, options, unwrap);
+	}
+};
+//#endregion
+exports.DecisionMachine = DecisionMachine;
+exports.MillisecondsError = MillisecondsError;
+exports.isMillisecondsError = isMillisecondsError;
+exports.typed = typed;