@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1723

package/ai/index.mjs

@@ -0,0 +1,193 @@
+//#region src/ai/index.ts
+var AiError = class extends Error {
+	code;
+	constructor(code, why) {
+		super(why);
+		this.code = code;
+		this.name = "AiError";
+	}
+};
+/** Checks a question before it leaves the caller. */
+function checked(input) {
+	if (Boolean(input.prompt) === Boolean(input.messages)) throw new AiError("invalid", "Give a prompt or messages.");
+	if (input.messages && !input.messages.length) throw new AiError("invalid", "Give at least one message.");
+	if (input.maxTokens !== void 0 && !(Number.isInteger(input.maxTokens) && input.maxTokens >= 1 && input.maxTokens <= 32e3)) throw new AiError("invalid", "maxTokens is a whole number from 1 to 32,000.");
+	if (input.temperature !== void 0 && !(input.temperature >= 0 && input.temperature <= 2)) throw new AiError("invalid", "temperature is from 0 to 2.");
+	return input;
+}
+function ai(engine) {
+	return {
+		async complete(input) {
+			let text = "";
+			for await (const event of engine.ask(checked(input))) if ("text" in event) text += event.text;
+			else return {
+				...event.done,
+				text
+			};
+			throw new AiError("unavailable", "The answer ended early. Try again.");
+		},
+		stream(input) {
+			let settle, fail;
+			const done = new Promise((resolve, reject) => {
+				settle = resolve;
+				fail = reject;
+			});
+			done.catch(() => void 0);
+			let asked;
+			try {
+				asked = checked(input);
+			} catch (error) {
+				fail(error);
+				return {
+					done,
+					[Symbol.asyncIterator]: () => ({ next: () => Promise.reject(error) })
+				};
+			}
+			async function* texts() {
+				try {
+					for await (const event of engine.ask(asked)) if ("text" in event) yield event.text;
+					else return settle(event.done);
+					throw new AiError("unavailable", "The answer ended early. Try again.");
+				} catch (error) {
+					fail(error);
+					throw error;
+				} finally {
+					fail(new AiError("unavailable", "The answer was not read to its end."));
+				}
+			}
+			return {
+				done,
+				[Symbol.asyncIterator]: texts
+			};
+		}
+	};
+}
+/** One line of the wire, checked whole: a piece of text, what the call spent, or why it stopped. Anything else is a broken answer. */
+function parsed(line) {
+	const broken = () => new AiError("unavailable", "The answer could not be read. Try again.");
+	let event;
+	try {
+		event = JSON.parse(line);
+	} catch {
+		throw broken();
+	}
+	const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+	const count = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+	if (!object(event)) throw broken();
+	if (typeof event.text === "string") return { text: event.text };
+	const done = event.done;
+	if (object(done)) {
+		if (typeof done.model !== "string" || !count(done.inputTokens) || !count(done.outputTokens) || typeof done.credits !== "number" || !(done.credits >= 0) || typeof done.catalogue !== "string") throw broken();
+		return { done: {
+			model: done.model,
+			inputTokens: done.inputTokens,
+			outputTokens: done.outputTokens,
+			credits: done.credits,
+			catalogue: done.catalogue
+		} };
+	}
+	const error = event.error;
+	if (object(error) && (error.code === void 0 || typeof error.code === "string") && (error.message === void 0 || typeof error.message === "string")) return { error: {
+		...typeof error.code === "string" ? { code: error.code } : {},
+		...typeof error.message === "string" ? { message: error.message } : {}
+	} };
+	throw broken();
+}
+const CODES = {
+	400: "invalid",
+	401: "forbidden",
+	403: "forbidden",
+	409: "conflict",
+	429: "quota"
+};
+const CODE_NAMES = [
+	"invalid",
+	"forbidden",
+	"quota",
+	"conflict",
+	"unavailable"
+];
+/**
+* The platform's AI Gateway at `origin` (the API's), for the AI key `key`: each call is one POST to
+* `<origin>/v1/ai/ask`, which replies with newline-delimited JSON events as the Model writes.
+*/
+function aiClient(origin, options) {
+	const url = `${origin.replace(/\/+$/, "")}/v1/ai/ask`;
+	const send = options.fetch ?? ((input, init) => fetch(input, init));
+	return { async *ask(input) {
+		const leave = new AbortController();
+		let response;
+		try {
+			response = await send(url, {
+				method: "POST",
+				signal: leave.signal,
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					...input,
+					key: options.key,
+					stream: true
+				})
+			});
+		} catch {
+			throw new AiError("unavailable", "The AI Gateway could not be reached. Try again.");
+		}
+		if (!response.ok || !response.body) {
+			const why = await response.json().then((body) => typeof body.error === "string" ? body.error : void 0, () => void 0);
+			throw new AiError(CODES[response.status] ?? "unavailable", why ?? `The AI Gateway answered ${response.status}.`);
+		}
+		try {
+			yield* eventsOf(response.body);
+		} finally {
+			leave.abort();
+		}
+	} };
+}
+/** The events of one call's newline-delimited JSON, as the AI Gateway streams them; cancelled when the reader leaves. */
+async function* eventsOf(body) {
+	const decoder = new TextDecoder();
+	let pending = "";
+	const reader = body.getReader();
+	try {
+		while (true) {
+			let read;
+			try {
+				read = await reader.read();
+			} catch {
+				throw new AiError("unavailable", "The answer was cut off. Try again.");
+			}
+			pending += read.done ? decoder.decode() : decoder.decode(read.value, { stream: true });
+			let end;
+			while ((end = pending.indexOf("\n")) >= 0) {
+				const line = pending.slice(0, end).trim();
+				pending = pending.slice(end + 1);
+				if (!line) continue;
+				const event = parsed(line);
+				if ("error" in event) throw new AiError(event.error.code && CODE_NAMES.includes(event.error.code) ? event.error.code : "unavailable", event.error.message ?? "The model could not answer. Try again.");
+				yield event;
+				if ("done" in event) return;
+			}
+			if (read.done) throw new AiError("unavailable", "The answer ended early. Try again.");
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+}
+/**
+* What Midsummer hands a Deployment as `context.ai`: the Team's AI Gateway, with no key. Each call
+* streams the events `aiClient` reads.
+*
+*   const answer = await ai(boundAi(context.ai)).complete({ prompt: "Hello" })
+*/
+function boundAi(handle) {
+	return { async *ask(input) {
+		let body;
+		try {
+			body = await handle.ask(input);
+		} catch (error) {
+			throw new AiError("unavailable", error instanceof Error ? error.message : "The AI Gateway could not be reached. Try again.");
+		}
+		yield* eventsOf(body);
+	} };
+}
+//#endregion
+export { AiError, ai, aiClient, boundAi };

package/ai/stand-in.d.mts

@@ -0,0 +1,7 @@
+import { AiEngine } from "./index.mjs";
+//#region src/ai/stand-in.d.ts
+declare function aiStandIn(options?: {
+  readonly models?: ReadonlyArray<string>;
+}): AiEngine;
+//#endregion
+export { aiStandIn };

package/ai/stand-in.mjs

@@ -0,0 +1,41 @@
+import { AiError } from "./index.mjs";
+//#region src/ai/stand-in.ts
+/**
+* AI's Stand-in: Model calls replied to on this computer, for `midsummer dev` and tests, with no
+* Model behind them. It passes the contract (`@midsummer-ai/sdk/ai/contract`); its replies are only
+* an echo of the question, so code can be run end to end without spending credits.
+*
+*   const models = ai(aiStandIn())
+*   await models.complete({ prompt: "Hi" }) // { text: "You asked: Hi", model: "stand-in", credits: 0, … }
+*
+* It offers the Models it is given (`stand-in` unless told), the first the default. Tokens are
+* counted at about four characters a token, and cost nothing.
+*/
+function aiStandIn(options = {}) {
+	const models = options.models?.length ? options.models : ["stand-in"];
+	const tokens = (text) => Math.ceil(text.length / 4);
+	return { async *ask(input) {
+		const model = input.model ?? models[0];
+		if (!models.includes(model)) throw new AiError("invalid", `There is no model ${model}.`);
+		const messages = [...input.system ? [{
+			role: "system",
+			content: input.system
+		}] : [], ...input.messages ?? [{
+			role: "user",
+			content: input.prompt ?? ""
+		}]];
+		const last = messages.filter((message) => message.role !== "system").at(-1);
+		if (last?.role !== "user" || !last.content.trim()) throw new AiError("invalid", "End with a user message that asks something.");
+		const answer = `You asked: ${last.content}`.slice(0, (input.maxTokens ?? 1024) * 4);
+		for (const piece of answer.match(/\S+\s*/g) ?? []) yield { text: piece };
+		yield { done: {
+			model,
+			inputTokens: tokens(messages.map((message) => message.content).join("")),
+			outputTokens: tokens(answer),
+			credits: 0,
+			catalogue: "stand-in"
+		} };
+	} };
+}
+//#endregion
+export { aiStandIn };

package/build-SQ44jwSa.d.mts

@@ -0,0 +1,41 @@
+import { r as Shape, t as IndexDeclaration } from "./schema-f7E9uzUn.mjs";
+//#region src/database/build.d.ts
+/** A file the Database would refuse; the message gives the file, and the line when there is one. */
+declare class Refused extends Error {
+  constructor(message: string);
+}
+interface BuiltFunction {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "action" | "internalQuery" | "internalMutation" | "internalAction";
+  /** The built file it is in, and the export that holds it. */
+  readonly file: string;
+  readonly export: string;
+  /** Its `args` fields and `returns` shape as written, for its types: null where they are not literals. */
+  readonly args: Readonly<Record<string, Shape | null>> | null;
+  readonly returns: Shape | null;
+}
+interface Built {
+  /** The folder's modules as JavaScript, by `<name>.mjs`, each import of the folder naming its built file. */
+  readonly files: Readonly<Record<string, string>>;
+  /** Which author file each built one came from. */
+  readonly from: Readonly<Record<string, string>>;
+  readonly functions: ReadonlyArray<BuiltFunction>;
+  /** The schema's tables by field, and their indexes; null without `schema.ts`. */
+  readonly tables: Readonly<Record<string, Readonly<Record<string, Shape>>>> | null;
+  readonly indexes: Readonly<Record<string, Readonly<Record<string, IndexDeclaration>>>> | null;
+  /** The files of `db/_generated/`. */
+  readonly generated: {
+    readonly "api.mjs": string;
+    readonly "api.d.ts": string;
+    readonly "dataModel.d.ts": string;
+    readonly "server.d.ts": string;
+  };
+}
+/** Whether a file directly in `db/` is a source: types (`.d.ts`) and dotfiles are none. */
+declare const isSource: (name: string) => boolean;
+/** Builds a `db/` folder's sources: `{ <file>: text }`, its top level. Throws `Refused`. */
+declare function buildDatabase(sources: Readonly<Record<string, string>>, strip: (ts: string) => string): Built;
+/** A shape as a TypeScript type. */
+declare function typeOf(shape: Shape | null | undefined): string;
+//#endregion
+export { isSource as a, buildDatabase as i, BuiltFunction as n, typeOf as o, Refused as r, Built as t };

package/client.d.mts

@@ -0,0 +1,45 @@
+import { m as StorageEngine } from "./index-sgdyoA2P.mjs";
+import { S3Credential } from "./s3.mjs";
+import { Transport } from "./wire.mjs";
+import { socket } from "./socket.mjs";
+//#region src/client.d.ts
+declare const SOCKET_PATH = "/storage/socket";
+declare const FRAMES_PATH = "/storage/frames";
+type WebSocketLike = NonNullable<Parameters<typeof socket>[1]["WebSocket"]>;
+type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Storage's engine at `origin` (the API's, `https://api.<site>`) for the Storage Key `key`: one socket,
+ * batched HTTP where it cannot open. `close` ends the connection; the next call opens another.
+ */
+declare function client(origin: string, options: {
+  readonly key: string;
+  readonly secret: string;
+  readonly fetch?: Fetch;
+  readonly WebSocket?: WebSocketLike;
+  readonly clock?: () => number;
+}): StorageEngine & {
+  close(): void;
+};
+/**
+ * A transport over HTTP signed with a Storage Key: each frame is one POST to `url`, replied to by
+ * `serveSigned`, and sent once more when the request or its answer's body fails and the frame is
+ * `repeatable`. A refused key is `forbidden`; a server that cannot be reached, or replies with anything but
+ * a frame, is `unavailable`.
+ */
+declare function signedHttp(url: string, options: {
+  readonly key: string;
+  readonly secret: string;
+  readonly fetch?: Fetch;
+  readonly clock?: () => number;
+}): Transport;
+/**
+ * Serves `signedHttp` transports: a POST of one frame, signed by a key `credentials` knows, gets one
+ * answer frame from `engine` as that key reaches it (`keyed`). Anything else is 405 or 401.
+ */
+declare function serveSigned(options: {
+  readonly engine: StorageEngine;
+  readonly credentials: (accessKeyId: string, named?: ReadonlyArray<string>) => S3Credential | null | Promise<S3Credential | null>;
+  readonly clock?: () => number;
+}): (request: Request) => Promise<Response>;
+//#endregion
+export { FRAMES_PATH, SOCKET_PATH, client, serveSigned, signedHttp };

package/client.mjs

@@ -0,0 +1,106 @@
+import { h as StorageError } from "./names-DfCBKupJ.mjs";
+import { bucketsOf, remote, repeatable, serve } from "./wire.mjs";
+import { keyed, sameHex, sign, socket } from "./socket.mjs";
+//#region src/client.ts
+/**
+* Storage from code holding a Storage Key, as an app reaches it: calls are written as usual and travel
+* over one WebSocket, so a client pays for one request when it connects, not one a call. Where a
+* connection cannot open, they travel as batched HTTP, signed with the same key.
+*
+*   const files = storage(client("https://api.<site>", { key, secret }))
+*   await files.bucket("avatars").put("ada.png", bytes)
+*
+* The calls made in the same turn travel as one batch frame either way. A call whose connection drops
+* before it gets a reply (a server going away on deploy) is sent again on a new connection when the wire
+* says repeating it is safe (`repeatable` in `@midsummer-ai/sdk/wire`), and is otherwise `unavailable`.
+*
+* Signed HTTP is one POST of a frame to `<origin>/storage/frames`, with
+* `authorization: Midsummer-Key key=<id>, time=<ms>, signature=<hex>`: the HMAC-SHA256, under the key's
+* secret, of the time and the frame's SHA-256 (`<time>\n<hex>`). The secret never travels, and a server
+* (`serveSigned`) refuses a signature more than five minutes from its own clock.
+*/
+const SOCKET_PATH = "/storage/socket";
+const FRAMES_PATH = "/storage/frames";
+const SKEW_MS = 3e5;
+/**
+* Storage's engine at `origin` (the API's, `https://api.<site>`) for the Storage Key `key`: one socket,
+* batched HTTP where it cannot open. `close` ends the connection; the next call opens another.
+*/
+function client(origin, options) {
+	const base = origin.replace(/\/+$/, "");
+	const http = signedHttp(`${base}${FRAMES_PATH}`, options);
+	const transport = socket(`${base.replace(/^http/, "ws")}${SOCKET_PATH}`, {
+		...options,
+		connections: 1,
+		fallback: http
+	});
+	return {
+		...remote(transport, { batch: true }),
+		close: () => transport.close()
+	};
+}
+async function sha256(bytes) {
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* A transport over HTTP signed with a Storage Key: each frame is one POST to `url`, replied to by
+* `serveSigned`, and sent once more when the request or its answer's body fails and the frame is
+* `repeatable`. A refused key is `forbidden`; a server that cannot be reached, or replies with anything but
+* a frame, is `unavailable`.
+*/
+function signedHttp(url, options) {
+	const send = options.fetch ?? ((to, init) => fetch(to, init));
+	const clock = options.clock ?? Date.now;
+	return { async send(frame) {
+		const time = clock();
+		const signature = await sign(options.secret, `${time}\n${await sha256(frame)}`);
+		for (let sends = 1;; sends += 1) {
+			const lost = () => {
+				if (sends === 2 || !repeatable(frame)) throw new StorageError("unavailable", "Storage could not be reached");
+			};
+			let response;
+			try {
+				response = await send(url, {
+					method: "POST",
+					headers: {
+						authorization: `Midsummer-Key key=${options.key}, time=${time}, signature=${signature}`,
+						"content-type": "application/octet-stream"
+					},
+					body: frame
+				});
+			} catch {
+				lost();
+				continue;
+			}
+			if (response.status === 401 || response.status === 403) throw new StorageError("forbidden", "Storage refused the key");
+			if (response.status !== 200) throw new StorageError("unavailable", `Storage answered ${response.status}`);
+			try {
+				return new Uint8Array(await response.arrayBuffer());
+			} catch {
+				lost();
+			}
+		}
+	} };
+}
+/**
+* Serves `signedHttp` transports: a POST of one frame, signed by a key `credentials` knows, gets one
+* answer frame from `engine` as that key reaches it (`keyed`). Anything else is 405 or 401.
+*/
+function serveSigned(options) {
+	const clock = options.clock ?? Date.now;
+	return async (request) => {
+		if (request.method !== "POST") return new Response(null, { status: 405 });
+		const said = /^Midsummer-Key key=([^,\s]+), time=(\d+), signature=([0-9a-f]{64})$/.exec(request.headers.get("authorization") ?? "");
+		const frame = new Uint8Array(await request.arrayBuffer());
+		if (!said || Math.abs(clock() - Number(said[2])) > SKEW_MS) return new Response(null, { status: 401 });
+		const credential = await options.credentials(said[1], bucketsOf(frame));
+		if (!credential || !sameHex(await sign(credential.secret, `${said[2]}\n${await sha256(frame)}`), said[3])) return new Response(null, { status: 401 });
+		const answer = await serve(keyed(options.engine, credential))(frame);
+		return new Response(answer, {
+			status: 200,
+			headers: { "content-type": "application/octet-stream" }
+		});
+	};
+}
+//#endregion
+export { FRAMES_PATH, SOCKET_PATH, client, serveSigned, signedHttp };