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

package/package.json

@@ -1,6 +1,154 @@
 {
   "name": "@midsummer-ai/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.1723",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Midsummer's handles for an app's code: its Database, Storage, Queues, Vector DB, AI, Email and Agents, with stand-ins for tests.",
+  "repository": {
+    "type": "sol",
+    "url": "https://midsummer.new/orbit/midsummer/midsummer",
+    "directory": "platform/sdk"
+  },
+  "homepage": "https://docs.midsummer.new",
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "import": "./index.mjs"
+    },
+    "./stand-in": {
+      "types": "./stand-in.d.mts",
+      "import": "./stand-in.mjs"
+    },
+    "./contract": {
+      "types": "./contract.d.mts",
+      "import": "./contract.mjs"
+    },
+    "./wire": {
+      "types": "./wire.d.mts",
+      "import": "./wire.mjs"
+    },
+    "./s3": {
+      "types": "./s3.d.mts",
+      "import": "./s3.mjs"
+    },
+    "./socket": {
+      "types": "./socket.d.mts",
+      "import": "./socket.mjs"
+    },
+    "./ai": {
+      "types": "./ai/index.d.mts",
+      "import": "./ai/index.mjs"
+    },
+    "./ai/stand-in": {
+      "types": "./ai/stand-in.d.mts",
+      "import": "./ai/stand-in.mjs"
+    },
+    "./ai/contract": {
+      "types": "./ai/contract.d.mts",
+      "import": "./ai/contract.mjs"
+    },
+    "./client": {
+      "types": "./client.d.mts",
+      "import": "./client.mjs"
+    },
+    "./server": {
+      "types": "./database/server.d.mts",
+      "import": "./database/server.mjs"
+    },
+    "./database/build": {
+      "types": "./database/build.d.mts",
+      "import": "./database/build.mjs"
+    },
+    "./database/stand-in": {
+      "types": "./database/stand-in.d.mts",
+      "import": "./database/stand-in.mjs"
+    },
+    "./database/contract": {
+      "types": "./database/contract.d.mts",
+      "import": "./database/contract.mjs"
+    },
+    "./database/errors": {
+      "types": "./database/errors.d.mts",
+      "import": "./database/errors.mjs"
+    },
+    "./database": {
+      "types": "./database/client.d.mts",
+      "import": "./database/client.mjs"
+    },
+    "./agents": {
+      "types": "./agents/index.d.mts",
+      "import": "./agents/index.mjs"
+    },
+    "./agents/stand-in": {
+      "types": "./agents/stand-in.d.mts",
+      "import": "./agents/stand-in.mjs"
+    },
+    "./agents/contract": {
+      "types": "./agents/contract.d.mts",
+      "import": "./agents/contract.mjs"
+    },
+    "./queues": {
+      "types": "./queues/index.d.mts",
+      "import": "./queues/index.mjs"
+    },
+    "./queues/stand-in": {
+      "types": "./queues/stand-in.d.mts",
+      "import": "./queues/stand-in.mjs"
+    },
+    "./queues/contract": {
+      "types": "./queues/contract.d.mts",
+      "import": "./queues/contract.mjs"
+    },
+    "./queues/wire": {
+      "types": "./queues/wire.d.mts",
+      "import": "./queues/wire.mjs"
+    },
+    "./email": {
+      "types": "./email/index.d.mts",
+      "import": "./email/index.mjs"
+    },
+    "./email/stand-in": {
+      "types": "./email/stand-in.d.mts",
+      "import": "./email/stand-in.mjs"
+    },
+    "./email/contract": {
+      "types": "./email/contract.d.mts",
+      "import": "./email/contract.mjs"
+    },
+    "./email/client": {
+      "types": "./email/client.d.mts",
+      "import": "./email/client.mjs"
+    },
+    "./email/smtp": {
+      "types": "./email/smtp.d.mts",
+      "import": "./email/smtp.mjs"
+    },
+    "./vector": {
+      "types": "./vector/index.d.mts",
+      "import": "./vector/index.mjs"
+    },
+    "./vector/stand-in": {
+      "types": "./vector/stand-in.d.mts",
+      "import": "./vector/stand-in.mjs"
+    },
+    "./vector/contract": {
+      "types": "./vector/contract.d.mts",
+      "import": "./vector/contract.mjs"
+    },
+    "./vector/wire": {
+      "types": "./vector/wire.d.mts",
+      "import": "./vector/wire.mjs"
+    }
+  },
+  "files": [
+    "**/*.mjs",
+    "**/*.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "acorn": "8.15.0",
+    "zod": "4.1.12"
+  },
+  "sideEffects": false
+}

package/predict-Drfm_8pO.mjs

@@ -0,0 +1,179 @@
+//#region src/database/client/predict.mjs
+const SKIP = Symbol("a row not cached");
+const plain = (v) => Object.fromEntries(Object.entries(v ?? {}).filter(([k]) => !k.startsWith("_")));
+const copy = (v) => v == null ? v : structuredClone(v);
+/** The token's `sub` (not verified: the units do that). */
+const userOf = (token) => {
+	try {
+		const parts = String(token).split(".");
+		return JSON.parse(atob(parts[parts.length === 3 ? 1 : 0].replace(/-/gu, "+").replace(/_/gu, "/"))).sub ?? null;
+	} catch {
+		return null;
+	}
+};
+var Predictor = class {
+	/** `functions`: the app's functions module (its `mutations`), or the mutations object itself. */
+	constructor(g, functions) {
+		this.g = g;
+		this.fns = functions.mutations ?? functions;
+		this.pending = [];
+		this.layer = /* @__PURE__ */ new Map();
+		this.stats = {
+			predicted: 0,
+			skipped: 0,
+			refusedHere: 0,
+			rolledBack: 0
+		};
+	}
+	/** Called by `mutation` before it sends: `{ end(answer) }`, or null when nothing was predicted. */
+	begin(name, args, route = "") {
+		if (typeof this.fns[name] !== "function") return null;
+		const e = {
+			name,
+			args: copy(args),
+			route,
+			answered: false,
+			writes: null,
+			need: null
+		};
+		this.pending.push(e);
+		this.update();
+		if (!e.writes) {
+			this.pending.splice(this.pending.indexOf(e), 1);
+			return null;
+		}
+		this.stats.predicted += 1;
+		return { end: (a) => this.end(e, a) };
+	}
+	end(e, a) {
+		if (!this.pending.includes(e)) return;
+		if (!a?.ok) {
+			this.stats.rolledBack += 1;
+			this.pending.splice(this.pending.indexOf(e), 1);
+			this.update();
+			return;
+		}
+		e.answered = true;
+		e.need = /* @__PURE__ */ new Map();
+		const wrote = new Map((a.wrote ?? []).map((r) => [`${r.t}/${r.id}`, r.v]));
+		for (const key of [...e.writes.keys()]) {
+			const held = this.g.rows.get(key);
+			if (!held) {
+				e.writes.delete(key);
+				continue;
+			}
+			e.need.set(key, wrote.get(key) ?? held.v + 1);
+		}
+		this.caughtUp(e);
+		setTimeout(() => {
+			const k = this.pending.indexOf(e);
+			if (k >= 0) {
+				this.pending.splice(k, 1);
+				this.update();
+			}
+		}, 5e3).unref?.();
+		this.update();
+	}
+	/** A watch settled (connection.mjs `settled`): answered predictions whose rows caught up go; the rest run again. */
+	saw(w) {
+		if (w.q.k !== "g" || !this.pending.length) return;
+		for (const e of [...this.pending]) if (e.answered) this.caughtUp(e);
+		this.update();
+	}
+	caughtUp(e) {
+		for (const [key, v] of e.need) if ((this.g.rows.get(key)?.v ?? 0) >= v) {
+			e.need.delete(key);
+			e.writes.delete(key);
+		}
+		if (!e.writes.size) this.pending.splice(this.pending.indexOf(e), 1);
+	}
+	/** Runs every waiting prediction again, in order, and shows the result (only rows whose value changed are told). */
+	update() {
+		const layer = /* @__PURE__ */ new Map();
+		for (const e of this.pending) {
+			if (!e.answered) e.writes = this.run(e, layer);
+			for (const [key, value] of e.writes ?? []) layer.set(key, value);
+		}
+		const g = this.g, changed = [];
+		for (const key of this.layer.keys()) if (!layer.has(key)) {
+			g.overlay.delete(key);
+			changed.push(key);
+		}
+		for (const [key, value] of layer) if (!this.layer.has(key) || JSON.stringify(this.layer.get(key)) !== JSON.stringify(value)) {
+			g.overlay.set(key, value);
+			changed.push(key);
+		}
+		this.layer = layer;
+		for (const key of changed) g.notifyRow(key);
+	}
+	/** One run of a mutation over the cache: its writes, or null (a row not cached, or the function threw). */
+	run(e, layer) {
+		const g = this.g, writes = /* @__PURE__ */ new Map();
+		const read = (tb, id) => {
+			const key = `${tb}/${id}`;
+			if (writes.has(key)) return copy(writes.get(key));
+			if (layer.has(key)) return copy(layer.get(key));
+			if (g.overlay.has(key) && !this.layer.has(key)) return copy(g.overlay.get(key));
+			let mine = null;
+			for (const m of [g.waiting, g.unconfirmed]) for (const { op } of m.values()) if (op.k === "s" && `${op.tb}/${op.id}` === key && (!mine || op.i > mine.i)) mine = op;
+			if (mine) return {
+				...copy(mine.value),
+				_id: id
+			};
+			const held = g.rows.get(key) ?? g.store?.row?.(key);
+			if (held) return copy(held.value);
+			throw SKIP;
+		};
+		const db = {
+			user: userOf(g.token),
+			server: false,
+			get: (tb, id) => read(tb, String(id)),
+			set: (tb, id, value) => {
+				writes.set(`${tb}/${id}`, {
+					...plain(value),
+					_id: String(id)
+				});
+			},
+			delete: (tb, id) => {
+				writes.set(`${tb}/${id}`, null);
+			},
+			credit: (tb, id, f, n) => {
+				let row;
+				try {
+					row = read(tb, String(id));
+				} catch (x) {
+					if (x === SKIP) return;
+					throw x;
+				}
+				db.set(tb, id, {
+					...row ?? {},
+					[f]: (Number(row?.[f]) || 0) + n
+				});
+			},
+			range: (tb, index, o = {}) => {
+				if (o.join) throw SKIP;
+				const key = `${g.unitOf(e.route)}|${JSON.stringify({
+					k: "r",
+					tb,
+					index,
+					...o
+				})}`;
+				const w = g.watches.get(key);
+				if (w?.state) return copy(w.state.ids.map((id) => w.state.rows.get(id)));
+				const old = g.store?.views?.get(key)?.view;
+				if (old) return copy(old);
+				throw SKIP;
+			}
+		};
+		try {
+			this.fns[e.name](db, copy(e.args) ?? {});
+			return writes;
+		} catch (x) {
+			if (x === SKIP) this.stats.skipped += 1;
+			else this.stats.refusedHere += 1;
+			return null;
+		}
+	}
+};
+//#endregion
+export { Predictor };

package/queues/contract.d.mts

@@ -0,0 +1,13 @@
+import { Queues } from "./index.mjs";
+//#region src/queues/contract.d.ts
+interface QueueCase {
+  /** A line of the specification. */
+  readonly name: string;
+  run(world: {
+    readonly queues: Queues;
+    advance(ms: number): void;
+  }): Promise<void>;
+}
+declare const queuesContract: ReadonlyArray<QueueCase>;
+//#endregion
+export { QueueCase, queuesContract };

package/queues/contract.mjs

@@ -0,0 +1,278 @@
+import { QueueError } from "./index.mjs";
+//#region src/queues/contract.ts
+/**
+* Queues' contract: what every engine promises, as cases any test runner can run. The Stand-in runs
+* them in this package; the platform runs the same cases against its own engine, through the wire.
+* A behaviour that is not a case here is not promised.
+*
+*   for (const c of queuesContract) test(c.name, () => { const time = clockAt(T0); return c.run({ queues: queues(makeEngine(time.now)), advance: time.advance }) })
+*
+* Each case gets Queues with nothing in them over an engine whose clock it moves with `advance`, and
+* throws when the engine breaks the promise. Expected values are written out, never computed with the
+* SDK's own code.
+*/
+const SECOND = 1e3;
+const queuesContract = [
+	{
+		name: "a Message sent is received once with its body, and acked it is gone",
+		async run({ queues }) {
+			const emails = queues.queue("emails");
+			const { id } = await emails.send({
+				to: "ada@example.com",
+				n: [1, 2]
+			});
+			const [delivery, ...rest] = await emails.receive();
+			equal(rest.length, 0, "deliveries beyond the one sent");
+			equal(delivery?.id, id, "the delivery's id");
+			equal(delivery?.body, {
+				to: "ada@example.com",
+				n: [1, 2]
+			}, "the body");
+			equal(delivery?.attempt, 1, "the attempt");
+			equal((await emails.receive()).length, 0, "deliveries while the first is in flight");
+			await emails.ack(delivery.receipt);
+			equal(await emails.stats(), {
+				depth: 0,
+				ready: 0,
+				inFlight: 0,
+				delayed: 0,
+				dead: 0
+			}, "the stats once acked");
+		}
+	},
+	{
+		name: "Messages sent in a batch are received in the order sent, up to the limit asked for",
+		async run({ queues }) {
+			const q = queues.queue("orders");
+			await q.sendBatch([
+				"a",
+				"b",
+				"c",
+				"d"
+			].map((body) => ({ body })));
+			equal((await q.receive({ limit: 3 })).map((d) => d.body), [
+				"a",
+				"b",
+				"c"
+			], "the first three");
+			equal((await q.receive({ limit: 3 })).map((d) => d.body), ["d"], "the rest");
+		}
+	},
+	{
+		name: "a Message not acked within its visibility window is delivered again, and the old receipt does nothing",
+		async run({ queues, advance }) {
+			const q = queues.queue("jobs");
+			await q.send("work");
+			const [first] = await q.receive({ visibilitySeconds: 30 });
+			advance(29 * SECOND);
+			equal((await q.receive()).length, 0, "deliveries before the window ends");
+			advance(1 * SECOND);
+			const [second] = await q.receive();
+			equal(second?.attempt, 2, "the second delivery's attempt");
+			await q.ack(first.receipt);
+			await q.retry(first.receipt, { delaySeconds: 0 });
+			equal(await q.stats(), {
+				depth: 1,
+				ready: 0,
+				inFlight: 1,
+				delayed: 0,
+				oldestSentAt: Date.UTC(2026, 9, 27, 12),
+				dead: 0
+			}, "the stats after acking and retrying the ended delivery");
+			await q.ack(second.receipt);
+			equal((await q.stats()).depth, 0, "the depth after acking the current one");
+		}
+	},
+	{
+		name: "a receipt whose visibility window has ended does nothing, before the Message is delivered again too",
+		async run({ queues, advance }) {
+			const q = queues.queue("jobs");
+			await q.send("work");
+			const [first] = await q.receive({ visibilitySeconds: 30 });
+			advance(30 * SECOND);
+			await q.ack(first.receipt);
+			await q.retry(first.receipt, { delaySeconds: 600 });
+			const [second] = await q.receive();
+			equal(second?.attempt, 2, "the delivery after a late ack and a late retry");
+		}
+	},
+	{
+		name: "a retried Message waits 10 seconds after its first delivery, 20 after its second, and as long as asked when a delay is given",
+		async run({ queues, advance }) {
+			const q = queues.queue("jobs");
+			await q.send("work");
+			await q.retry((await q.receive())[0].receipt);
+			advance(9 * SECOND);
+			equal((await q.receive()).length, 0, "deliveries 9 seconds after the first retry");
+			advance(1 * SECOND);
+			const [second] = await q.receive();
+			equal(second?.attempt, 2, "the attempt 10 seconds after");
+			await q.retry(second.receipt);
+			advance(19 * SECOND);
+			equal((await q.receive()).length, 0, "deliveries 19 seconds after the second retry");
+			advance(1 * SECOND);
+			const [third] = await q.receive();
+			equal(third?.attempt, 3, "the attempt 20 seconds after");
+			await q.retry(third.receipt, { delaySeconds: 0 });
+			equal((await q.receive())[0]?.attempt, 4, "the attempt after a retry with no delay");
+		}
+	},
+	{
+		name: "the backoff stops growing at 10 minutes",
+		async run({ queues, advance }) {
+			const q = queues.queue("jobs");
+			await q.send("work");
+			for (let attempt = 1; attempt <= 8; attempt += 1) {
+				const [delivery] = await q.receive({ maxAttempts: 100 });
+				equal(delivery?.attempt, attempt, `delivery ${attempt}`);
+				await q.retry(delivery.receipt);
+				advance(600 * SECOND);
+			}
+		}
+	},
+	{
+		name: "a Message delivered maxAttempts times moves to the dead-letter Queue when retried or left, keeping its body and id",
+		async run({ queues, advance }) {
+			const q = queues.queue("payments");
+			const { id: retried } = await q.send({ charge: 1 });
+			const { id: left } = await q.send({ charge: 2 }, { delaySeconds: 1 });
+			for (let attempt = 1; attempt <= 2; attempt += 1) {
+				const [delivery] = await q.receive({
+					maxAttempts: 2,
+					limit: 1
+				});
+				await q.retry(delivery.receipt, { delaySeconds: 0 });
+			}
+			advance(1 * SECOND);
+			await q.receive({
+				maxAttempts: 1,
+				visibilitySeconds: 5
+			});
+			advance(5 * SECOND);
+			equal((await q.receive()).length, 0, "deliveries of either from the Queue itself");
+			equal(await q.stats(), {
+				depth: 0,
+				ready: 0,
+				inFlight: 0,
+				delayed: 0,
+				dead: 2
+			}, "the Queue's stats");
+			equal((await q.deadLetter.receive()).map((d) => [d.id, d.body]), [[retried, { charge: 1 }], [left, { charge: 2 }]], "the dead-letter Queue's Messages");
+			equal(q.deadLetter.name, "payments.dead", "the dead-letter Queue's name");
+		}
+	},
+	{
+		name: "a dead-letter Queue's Messages are retried there and never move on",
+		async run({ queues }) {
+			const q = queues.queue("payments");
+			await q.send("x");
+			await q.retry((await q.receive({ maxAttempts: 1 }))[0].receipt);
+			for (let i = 0; i < 3; i += 1) await q.deadLetter.retry((await q.deadLetter.receive({ maxAttempts: 1 }))[0].receipt, { delaySeconds: 0 });
+			equal((await q.deadLetter.stats()).depth, 1, "the dead-letter Queue's depth");
+		}
+	},
+	{
+		name: "a Message sent with a delay is received only once the delay is over, and counts as delayed until then",
+		async run({ queues, advance }) {
+			const q = queues.queue("reminders");
+			await q.send("later", { delaySeconds: 60 });
+			equal(await q.stats(), {
+				depth: 1,
+				ready: 0,
+				inFlight: 0,
+				delayed: 1,
+				oldestSentAt: Date.UTC(2026, 9, 27, 12),
+				dead: 0
+			}, "the stats while delayed");
+			advance(59 * SECOND);
+			equal((await q.receive()).length, 0, "deliveries a second early");
+			advance(1 * SECOND);
+			equal((await q.receive()).map((d) => d.body), ["later"], "deliveries once due");
+		}
+	},
+	{
+		name: "stats count ready, in-flight and delayed Messages and say when the oldest was sent",
+		async run({ queues, advance }) {
+			const q = queues.queue("events");
+			await q.send(1);
+			advance(5 * SECOND);
+			await q.sendBatch([{ body: 2 }, {
+				body: 3,
+				delaySeconds: 30
+			}]);
+			await q.receive({ limit: 1 });
+			equal(await q.stats(), {
+				depth: 3,
+				ready: 1,
+				inFlight: 1,
+				delayed: 1,
+				oldestSentAt: Date.UTC(2026, 9, 27, 12),
+				dead: 0
+			}, "the stats");
+		}
+	},
+	{
+		name: "a send with a key already sent to that Queue answers the first id and sends nothing; another Queue keeps its own keys",
+		async run({ queues }) {
+			const q = queues.queue("welcome");
+			const first = await q.send("hi", { key: "user:ada" });
+			equal((await q.send("hi again", { key: "user:ada" })).id, first.id, "the id of the second send");
+			equal((await q.stats()).depth, 1, "the depth");
+			await queues.queue("other").send("hi", { key: "user:ada" });
+			equal((await queues.queue("other").stats()).depth, 1, "the other Queue's depth");
+		}
+	},
+	{
+		name: "Queues are apart: what one holds, another never delivers",
+		async run({ queues }) {
+			await queues.queue("a").send("for a");
+			equal((await queues.queue("b").receive()).length, 0, "deliveries from b");
+			equal((await queues.queue("a").receive()).map((d) => d.body), ["for a"], "deliveries from a");
+		}
+	},
+	{
+		name: "a bad name, body, delay, limit or receipt is invalid",
+		async run({ queues }) {
+			fails(() => queues.queue("Has Spaces"), "a name with spaces");
+			fails(() => queues.queue("a.dead"), "a name with a dot");
+			const q = queues.queue("ok");
+			await rejects(q.send(void 0), "an undefined body");
+			await rejects(q.send("x".repeat(131071)), "a body over 128 KiB as JSON");
+			await rejects(q.send("x", { delaySeconds: 43201 }), "a delay over 12 hours");
+			await rejects(q.send("x", { key: "" }), "an empty key");
+			await rejects(q.receive({ limit: 101 }), "a limit over 100");
+			await rejects(q.receive({ visibilitySeconds: 0 }), "a visibility of 0");
+			await rejects(q.ack("not a receipt"), "a receipt with spaces");
+			await rejects(q.sendBatch([]), "an empty batch");
+		}
+	}
+];
+function equal(actual, expected, what) {
+	const a = JSON.stringify(sorted(actual)), e = JSON.stringify(sorted(expected));
+	if (a !== e) throw new Error(`${what}: expected ${e}, got ${a}`);
+}
+function sorted(value) {
+	if (Array.isArray(value)) return value.map(sorted);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([k, v]) => [k, sorted(v)]));
+	return value;
+}
+function fails(run, what) {
+	try {
+		run();
+	} catch (error) {
+		if (error instanceof QueueError && error.code === "invalid") return;
+		throw error;
+	}
+	throw new Error(`${what}: expected invalid`);
+}
+async function rejects(promise, what) {
+	try {
+		await promise;
+	} catch (error) {
+		if (error instanceof QueueError && error.code === "invalid") return;
+		throw error;
+	}
+	throw new Error(`${what}: expected invalid`);
+}
+//#endregion
+export { queuesContract };