reelkit-cli 0.1.0

package/src/testing/conformance.ts

@@ -0,0 +1,396 @@
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { ApiFailure, createClient, download, uploadTo, type Api } from "../api/client";
+import { isPlainText, MAX_UPLOAD_BYTES, type LibraryItem } from "../contract";
+
+// What the suite needs from a server under test: a running instance, and the few things a person or an operator does outside the API.
+export type Harness = {
+  baseUrl: string;
+  // A token for this user, as if they had logged in. The same id is the same user.
+  login(userId?: string): string | Promise<string>;
+  // Adds a published item (with its file) to the library. Items added later count as newer.
+  seedPublished(item: LibraryItem, file: { filename: string; contentType: string; bytes: Uint8Array }): void | Promise<void>;
+  // What the website does when a signed-in user enters the code.
+  approve(userCode: string): unknown;
+  close(): void | Promise<void>;
+};
+export type StartOptions = { voiceoverChars?: number; images?: number };
+
+const PNG = new Uint8Array(Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64"));
+const DATE = /\d{4}-\d{2}-\d{2}/;
+const failure = async (p: Promise<unknown>) => { try { await p; } catch (e) { return e as ApiFailure; } throw new Error("expected a failure"); };
+const put = (url: string, bytes: Uint8Array, contentType: string) => fetch(url, { method: "PUT", headers: { "content-type": contentType }, body: bytes as BodyInit });
+const item = (id: string, kind: LibraryItem["kind"], text: string, tags: string[] = []): LibraryItem => ({ id, kind, title: text, description: text, tags, meta: {}, visibility: "published" });
+const png = (id: string, text: string, tags?: string[]) => [item(id, "image", text, tags), { filename: "p.png", contentType: "image/png", bytes: PNG }] as const;
+const upload = (over: object = {}) => ({ kind: "image" as const, title: "Mine", description: "my cat", tags: ["cat"], meta: {}, filename: "cat.png", contentType: "image/png", bytes: PNG.length, shareable: true, ...over });
+
+// The same black-box tests, run against every implementation of the contract (the fake API here, the real one in the API repo).
+// Whatever one of them does that these tests notice, the other must do too.
+export function runConformance(name: string, start: (opts: StartOptions) => Promise<Harness>) {
+  describe(`${name} conforms to the contract`, () => {
+    const dest = mkdtempSync(join(tmpdir(), "rk-shared-"));
+    let h: Harness;
+    let anon: Api;
+    beforeAll(async () => { h = await start({}); anon = createClient({ baseUrl: h.baseUrl }); });
+    afterAll(async () => { await h.close(); });
+    const as = async (userId: string) => createClient({ baseUrl: h.baseUrl, token: await h.login(userId) });
+
+    describe("the device flow", () => {
+      it("is pending until approved, hands out one working token, then the code is spent", async () => {
+        const start = await anon("deviceStart", { label: "laptop" });
+        expect(start.userCode).toBeTruthy();
+        expect(start.deviceCode).not.toBe(start.userCode);
+        expect(await anon("deviceToken", { deviceCode: start.deviceCode })).toEqual({ status: "pending" });
+        await h.approve(start.userCode);
+        const done = await anon("deviceToken", { deviceCode: start.deviceCode });
+        expect(done.status).toBe("approved");
+        if (done.status !== "approved") return;
+        expect((await createClient({ baseUrl: h.baseUrl, token: done.token })("me", {})).userId).toBeTruthy();
+        expect(await anon("deviceToken", { deviceCode: start.deviceCode })).toEqual({ status: "expired" });
+      });
+
+      it("answers an unknown device code with expired", async () => {
+        expect(await anon("deviceToken", { deviceCode: "no-such-code" })).toEqual({ status: "expired" });
+      });
+
+      it("revoke ends the token", async () => {
+        const api = await as("user-revoke01");
+        await api("me", {});
+        expect(await api("revoke", {})).toEqual({ revoked: true });
+        expect((await failure(api("me", {}))).code).toBe("unauthenticated");
+      });
+
+      it("refuses a missing or unknown token as unauthenticated", async () => {
+        expect((await failure(anon("me", {}))).code).toBe("unauthenticated");
+        expect((await failure(createClient({ baseUrl: h.baseUrl, token: "rk_nope" })("me", {}))).code).toBe("unauthenticated");
+      });
+    });
+
+    describe("me", () => {
+      it("for a user with no activity has empty meters, a reset date and no contributions", async () => {
+        const me = await (await as("user-fresh0001"))("me", {});
+        expect(me.userId).toBe("user-fresh0001");
+        expect(me.handle.length).toBeGreaterThan(0);
+        expect(me.quota.voiceoverChars.used).toBe(0);
+        expect(me.quota.images.used).toBe(0);
+        expect(me.quota.voiceoverChars.limit).toBeGreaterThan(0);
+        expect(me.contributions).toBe(0);
+        const resets = new Date(me.quota.resetsAt);
+        expect(resets.getTime()).toBeGreaterThan(Date.now());
+        expect([resets.getUTCDate(), resets.getUTCHours(), resets.getUTCMinutes()]).toEqual([1, 0, 0]);
+      });
+    });
+
+    describe("uploads", () => {
+      it("upload, PUT, commit: in review so search misses it; the owner can pull it; another user cannot pull or commit it", async () => {
+        const mine = await as("user-up00001"), other = await as("user-up00002");
+        const up = await mine("libraryUpload", upload({ title: "Zebra crossing", description: "stripes zebra" }));
+        expect((await put(up.uploadUrl, PNG, "image/png")).ok).toBe(true);
+        const { item } = await mine("libraryCommit", { id: up.id });
+        expect(item).toMatchObject({ id: up.id, kind: "image", visibility: "review" });
+        expect((await mine("me", {})).contributions).toBe(1);
+        // An item that is not published never appears, whoever searches.
+        expect((await mine("librarySearch", { q: "zebra" })).items.map((i) => i.id)).not.toContain(up.id);
+        expect((await other("librarySearch", { q: "zebra" })).items.map((i) => i.id)).not.toContain(up.id);
+        const pulled = await mine("libraryPull", { id: up.id });
+        await download(pulled.url, join(dest, "mine.png"));
+        expect(new Uint8Array(readFileSync(join(dest, "mine.png")))).toEqual(PNG);
+        expect((await failure(other("libraryPull", { id: up.id }))).code).toBe("not_found");
+        expect((await failure(other("libraryCommit", { id: up.id }))).code).toBe("not_found");
+      });
+
+      it("a private upload is never searchable and nobody else can pull it", async () => {
+        const mine = await as("user-up00003"), other = await as("user-up00004");
+        const up = await mine("libraryUpload", upload({ shareable: false, title: "Hidden gecko", description: "hidden gecko" }));
+        await put(up.uploadUrl, PNG, "image/png");
+        expect((await mine("libraryCommit", { id: up.id })).item.visibility).toBe("private");
+        // Contributions are shared uploads only.
+        expect((await mine("me", {})).contributions).toBe(0);
+        expect((await mine("librarySearch", { q: "gecko" })).items.map((i) => i.id)).not.toContain(up.id);
+        expect((await failure(other("libraryPull", { id: up.id }))).code).toBe("not_found");
+        expect((await mine("libraryPull", { id: up.id })).item.id).toBe(up.id);
+      });
+
+      it("an upload is not an item before commit, and committing twice counts once", async () => {
+        const mine = await as("user-up00005");
+        const up = await mine("libraryUpload", upload());
+        expect((await failure(mine("libraryCommit", { id: up.id }))).code).toBe("invalid_request");
+        await put(up.uploadUrl, PNG, "image/png");
+        expect((await failure(mine("libraryPull", { id: up.id }))).code).toBe("not_found");
+        const first = await mine("libraryCommit", { id: up.id });
+        expect(await mine("libraryCommit", { id: up.id })).toEqual(first);
+        expect((await mine("me", {})).contributions).toBe(1);
+      });
+
+      it("refuses a PUT of the wrong type or length, and commit then has nothing to commit", async () => {
+        const mine = await as("user-up00006");
+        const up = await mine("libraryUpload", upload());
+        expect((await put(up.uploadUrl, PNG, "text/plain")).ok).toBe(false);
+        expect((await put(up.uploadUrl, new Uint8Array(PNG.length + 1), "image/png")).ok).toBe(false);
+        expect((await failure(mine("libraryCommit", { id: up.id }))).code).toBe("invalid_request");
+      });
+
+      it("stores the file under a safe name, which is what pull returns", async () => {
+        const mine = await as("user-up00007");
+        const up = await mine("libraryUpload", upload({ filename: "my photo (1).png" }));
+        await put(up.uploadUrl, PNG, "image/png");
+        await mine("libraryCommit", { id: up.id });
+        expect((await mine("libraryPull", { id: up.id })).filename).toBe("my_photo__1_.png");
+      });
+
+      it.each([
+        ["a name that starts with a symbol", { filename: "!pic.png" }],
+        ["a name that starts with a dot", { filename: ".hidden.png" }],
+        ["a name longer than 128 characters", { filename: `${"a".repeat(125)}.png` }],
+        ["a content type that does not fit the kind", { contentType: "audio/mpeg" }],
+        ["a video type for an image", { contentType: "video/mp4" }],
+        ["an image type for an sfx", { kind: "sfx", contentType: "image/png" }],
+        ["zero bytes", { bytes: 0 }],
+        ["more than 200 MB", { bytes: MAX_UPLOAD_BYTES + 1 }],
+        ["a component", { kind: "component", filename: "X.tsx", contentType: "text/plain" }],
+      ])("refuses %s with invalid_request", async (_what, over) => {
+        const e = await failure((await as("user-up00008"))("libraryUpload", upload(over) as never));
+        expect(e.code).toBe("invalid_request");
+        expect(e.message.length).toBeGreaterThan(0);
+      });
+
+      it("accepts the type that fits each kind and exactly 200 MB", async () => {
+        const mine = await as("user-up00009");
+        for (const [kind, contentType] of [["clip", "video/mp4"], ["overlay", "video/webm"], ["sfx", "audio/mpeg"], ["music", "audio/wav"], ["image", "image/jpeg"]] as const) {
+          await mine("libraryUpload", upload({ kind, contentType, filename: `f.${kind}` }));
+        }
+        await mine("libraryUpload", upload({ bytes: MAX_UPLOAD_BYTES }));
+      });
+    });
+
+    describe("the library", () => {
+      it("a seeded published item is found, pulled and downloaded byte for byte", async () => {
+        const bytes = new Uint8Array(Array.from({ length: 300 }, (_, i) => i % 251));
+        await h.seedPublished(item("sfx-seedwhoosh01", "sfx", "a fast whoosh sweep", ["whoosh"]), { filename: "whoosh.mp3", contentType: "audio/mpeg", bytes });
+        const api = await as("user-lib00001");
+        const found = await api("librarySearch", { q: "whoosh", kind: "sfx" });
+        // Which other items come back, and in what order, is up to the implementation; the kind filter and visibility are not.
+        expect(found.items.map((i) => i.id)).toContain("sfx-seedwhoosh01");
+        expect(found.items.every((i) => i.kind === "sfx" && i.visibility === "published")).toBe(true);
+        expect((await api("librarySearch", { q: "whoosh", kind: "image" })).items.every((i) => i.kind === "image")).toBe(true);
+        const pulled = await api("libraryPull", { id: "sfx-seedwhoosh01" });
+        expect(pulled.filename).toBe("whoosh.mp3");
+        await download(pulled.url, join(dest, "whoosh.mp3"));
+        expect(new Uint8Array(readFileSync(join(dest, "whoosh.mp3")))).toEqual(bytes);
+        expect((await failure(api("libraryPull", { id: "image-nothing" }))).code).toBe("not_found");
+      });
+
+      // What the contract promises about search, and no more: how an implementation scores and which items it returns for a query is its own
+      // business (the fake counts shared words; the API asks a model). The exact results of the fake are tested with the fake.
+      it("search results carry a match from 0 to 1, are ordered by it, honour limit, and nothing unrelated is a strong match", async () => {
+        const api = await as("user-lib00002");
+        await h.seedPublished(...png("image-ord-a", "ordsearch zulu"));
+        await h.seedPublished(...png("image-ord-b", "ordsearch"));
+        await h.seedPublished(...png("image-ord-c", "ordsearch"));
+        await h.seedPublished(...png("image-ord-d", "ordsearch"));
+        const run = async (q: string, limit?: number) => (await api("librarySearch", { q, ...(limit ? { limit } : {}) })).items;
+        for (const q of ["ordsearch", "ordsearch zulu"]) {
+          const items = await run(q);
+          for (const i of items) { expect(i.match).toBeGreaterThanOrEqual(0); expect(i.match).toBeLessThanOrEqual(1); }
+          expect(items.map((i) => i.match)).toEqual([...items.map((i) => i.match)].sort((x, y) => y - x));
+        }
+        expect((await run("ordsearch", 2)).length).toBeLessThanOrEqual(2);
+        expect((await run("ordsearch", 1)).length).toBeLessThanOrEqual(1);
+        // A query that has nothing to do with anything returns nothing, or nothing with a strong match.
+        for (const i of await run("qzxv wibble unrelatedword")) expect(i.match).toBeLessThanOrEqual(0.9);
+      });
+    });
+
+    describe("what the contract refuses and how URLs look", () => {
+      it.each([
+        ["a search with no query", (api: Api) => api("librarySearch", { q: "" })],
+        ["a search limit of 0", (api: Api) => api("librarySearch", { q: "x", limit: 0 })],
+        ["a search limit over 50", (api: Api) => api("librarySearch", { q: "x", limit: 51 })],
+        ["a pull id with a NUL", (api: Api) => api("libraryPull", { id: "image-a\u0000b" })],
+        ["a pull id that is too long", (api: Api) => api("libraryPull", { id: "a".repeat(129) })],
+        ["a pull id that starts with a dash", (api: Api) => api("libraryPull", { id: "-image" })],
+        ["a pull id with a slash", (api: Api) => api("libraryPull", { id: "../x" })],
+        ["a commit id with a NUL", (api: Api) => api("libraryCommit", { id: "image-a\u0000b" })],
+        ["a commit id that is too long", (api: Api) => api("libraryCommit", { id: "a".repeat(129) })],
+        ["a device code with a NUL", (api: Api) => api("deviceToken", { deviceCode: "a\u0000b" })],
+        ["a device code that is too long", (api: Api) => api("deviceToken", { deviceCode: "a".repeat(201) })],
+        ["an empty device code", (api: Api) => api("deviceToken", { deviceCode: "" })],
+        ["an empty voiceover text", (api: Api) => api("voiceover", { text: "" })],
+        ["a voiceover text of only whitespace", (api: Api) => api("voiceover", { text: " \n\t  " })],
+        ["a voiceover text over 5000 characters", (api: Api) => api("voiceover", { text: "a".repeat(5001) })],
+        ["a speed over 1.3", (api: Api) => api("voiceover", { text: "hi", speed: 1.4 })],
+        ["an unknown aspect", (api: Api) => api("images", { prompt: "a", aspect: "4:3" as never, shareable: false, tags: [] })],
+      ])("refuses %s as invalid_request", async (_what, call) => {
+        expect((await failure(call(await as("user-bad000001")))).code).toBe("invalid_request");
+      });
+
+      it("hands out file and upload URLs that do not contain the item id or file name, and a new file URL on every pull", async () => {
+        await h.seedPublished(...png("image-urlcheck001", "urlcheck"));
+        const api = await as("user-url00001");
+        const a = await api("libraryPull", { id: "image-urlcheck001" }), b = await api("libraryPull", { id: "image-urlcheck001" });
+        expect(a.url).not.toBe(b.url);
+        for (const u of [a.url, b.url]) { expect(u).not.toContain("urlcheck001"); expect(u).not.toContain("p.png"); expect((await fetch(u)).ok).toBe(true); }
+        const up = await api("libraryUpload", upload({ filename: "unique-name.png" }));
+        expect(up.uploadUrl).not.toContain(up.id);
+        expect(up.uploadUrl).not.toContain("unique-name");
+      });
+    });
+
+    describe("voices and generation", () => {
+      it("lists voices", async () => {
+        const { voices } = await (await as("user-gen00001"))("voices", {});
+        expect(voices.length).toBeGreaterThan(0);
+        expect(voices[0]!.id).toBeTruthy();
+      });
+
+      it("voiceover returns a file, word timings inside its length, and charges the characters to this user only", async () => {
+        const api = await as("user-gen00002"), other = await as("user-gen00003");
+        const text = "one two three four five";
+        const vo = await api("voiceover", { text });
+        expect(vo.chars).toBe(text.length);
+        expect(vo.words.map((w) => w.word)).toEqual(text.split(" "));
+        expect(vo.words.at(-1)!.endSec).toBeLessThanOrEqual(vo.durationSec + 0.01);
+        await download(vo.url, join(dest, `vo.${vo.ext}`));
+        expect(readFileSync(join(dest, `vo.${vo.ext}`)).length).toBeGreaterThan(0);
+        expect((await api("me", {})).quota.voiceoverChars.used).toBe(text.length);
+        expect((await other("me", {})).quota.voiceoverChars.used).toBe(0);
+      });
+
+      it("voiceover takes Windows line endings, and counts and speaks them as plain newlines", async () => {
+        const api = await as("user-gen00006");
+        const vo = await api("voiceover", { text: "one\r\ntwo\rthree" });
+        expect(vo.chars).toBe("one\ntwo\nthree".length);
+        expect(vo.words.map((w) => w.word)).toEqual(["one", "two", "three"]);
+        expect((await api("me", {})).quota.voiceoverChars.used).toBe("one\ntwo\nthree".length);
+      });
+
+      it("generation needs a login", async () => {
+        expect((await failure(anon("voiceover", { text: "hi" }))).code).toBe("unauthenticated");
+        expect((await failure(anon("images", { prompt: "a", aspect: "9:16", shareable: false, tags: [] }))).code).toBe("unauthenticated");
+      });
+
+      it("images: a private one is only a file; a shareable one also enters the library for review, owned by the caller", async () => {
+        const api = await as("user-gen00004"), other = await as("user-gen00005");
+        const plain = await api("images", { prompt: "a quiet lake", aspect: "16:9", shareable: false, tags: [] });
+        expect(plain.libraryId).toBeUndefined();
+        await download(plain.url, join(dest, `plain.${plain.ext}`));
+        expect(readFileSync(join(dest, `plain.${plain.ext}`)).length).toBeGreaterThan(0);
+        const shared = await api("images", { prompt: "a loud volcano", aspect: "9:16", shareable: true, tags: ["volcano"] });
+        expect(shared.libraryId).toBeTruthy();
+        expect((await api("librarySearch", { q: "volcano" })).items).toEqual([]);
+        expect((await api("libraryPull", { id: shared.libraryId! })).item).toMatchObject({ kind: "image", visibility: "review", tags: expect.arrayContaining(["volcano"]) });
+        expect((await failure(other("libraryPull", { id: shared.libraryId! }))).code).toBe("not_found");
+        expect((await api("me", {})).quota.images.used).toBe(2);
+      });
+
+      it("a shared image's title is the first 60 characters of the prompt, cut on a code point, never inside an emoji", async () => {
+        const api = await as("user-gen00007");
+        const prompt = "\u{1F30B}".repeat(70);
+        const shared = await api("images", { prompt, aspect: "1:1", shareable: true, tags: [] });
+        const { item } = await api("libraryPull", { id: shared.libraryId! });
+        expect(isPlainText(item.title)).toBe(true);
+        expect(Array.from(item.title)).toHaveLength(60);
+        expect(item.description).toBe(prompt);
+      });
+    });
+
+    describe("quota", () => {
+      it("passes exactly at the limit; one over is quota_exceeded with the reset date; other users are unaffected", async () => {
+        const t = await start({ voiceoverChars: 10, images: 1 });
+        try {
+          const api = createClient({ baseUrl: t.baseUrl, token: await t.login("user-quota001") });
+          const other = createClient({ baseUrl: t.baseUrl, token: await t.login("user-quota002") });
+          await api("voiceover", { text: "ten chars!" });
+          const e = await failure(api("voiceover", { text: "x" }));
+          expect(e.code).toBe("quota_exceeded");
+          const me = await api("me", {});
+          expect(me.quota.voiceoverChars).toEqual({ used: 10, limit: 10 });
+          expect(e.message).toContain(me.quota.resetsAt.slice(0, 10));
+          expect(e.message).toMatch(DATE);
+          // A request that does not fit is refused whole, and charged nothing.
+          const small = createClient({ baseUrl: t.baseUrl, token: await t.login("user-quota003") });
+          expect((await failure(small("voiceover", { text: "eleven char" }))).code).toBe("quota_exceeded");
+          expect((await small("me", {})).quota.voiceoverChars.used).toBe(0);
+          await other("voiceover", { text: "ten chars!" });
+
+          await api("images", { prompt: "a cat", aspect: "9:16", shareable: false, tags: [] });
+          const i = await failure(api("images", { prompt: "a dog", aspect: "9:16", shareable: false, tags: [] }));
+          expect(i.code).toBe("quota_exceeded");
+          expect(i.message).toMatch(DATE);
+          expect((await other("me", {})).quota.images.used).toBe(0);
+          await other("images", { prompt: "a bird", aspect: "9:16", shareable: false, tags: [] });
+        } finally { await t.close(); }
+      });
+    });
+
+    describe("the public library", () => {
+      it("needs no login, lists published items newest first in pages without repeats, and with a query leads with the best match", async () => {
+        const t = await start({});
+        try {
+          const ids = Array.from({ length: 30 }, (_, i) => `image-pub-${String(i).padStart(2, "0")}`);
+          // The first one also matches the second query word, so it leads that listing.
+          for (const [i, id] of ids.entries()) await t.seedPublished(...png(id, i === 0 ? "pubpic gold" : "pubpic"));
+          const api = createClient({ baseUrl: t.baseUrl });
+          const walk = async (q?: string) => {
+            const seen: string[] = [];
+            let first;
+            for (let page = 1; page <= 10; page++) {
+              const r = await api("publicLibrary", { ...(q ? { q } : {}), page });
+              first ??= r;
+              expect(r.page).toBe(page);
+              seen.push(...r.items.map((x) => x.id));
+              if (!r.hasMore) break;
+            }
+            return { seen, first: first! };
+          };
+          const all = await walk();
+          expect(all.first.hasMore).toBe(true);
+          expect(all.seen).toEqual([...ids].reverse());
+          expect(new Set(all.seen).size).toBe(30);
+          // With a query a server may rank by meaning (one page, each item with `match`, best first) or list by text (paged, as above).
+          // Either way: the item matching both words leads, nothing repeats, and nothing outside the published set appears.
+          const ranked = await walk("pubpic gold");
+          expect(ranked.seen[0]).toBe(ids[0]);
+          expect(new Set(ranked.seen).size).toBe(ranked.seen.length);
+          expect(ranked.seen.every((id) => ids.includes(id))).toBe(true);
+          const matches = ranked.first.items.map((x) => x.match);
+          if (matches.some((m) => m !== undefined)) {
+            expect(matches.every((m) => typeof m === "number" && m >= 0 && m <= 1)).toBe(true);
+            expect(matches).toEqual([...(matches as number[])].sort((a, b) => b - a));
+            expect(ranked.first.hasMore).toBe(false);
+          } else expect(ranked.seen).toHaveLength(30);
+          // Something in review is not public.
+          const mine = createClient({ baseUrl: t.baseUrl, token: await t.login("user-pub00001") });
+          const up = await mine("libraryUpload", upload({ title: "Pending review", description: "pubpic review" }));
+          await put(up.uploadUrl, PNG, "image/png");
+          await mine("libraryCommit", { id: up.id });
+          expect((await walk()).seen).toHaveLength(30);
+          expect((await api("publicLibrary", { q: "pubpic", kind: "sfx" })).items).toEqual([]);
+        } finally { await t.close(); }
+      });
+
+      it("a published sound effect or image has a preview URL that serves its file; a published music item without a preview has none", async () => {
+        const t = await start({});
+        try {
+          const AUDIO = new Uint8Array([1, 2, 3, 4, 5]);
+          const audio = { filename: "a.mp3", contentType: "audio/mpeg", bytes: AUDIO };
+          await t.seedPublished(item("sfx-prevcheck001", "sfx", "prevcheck whoosh"), audio);
+          await t.seedPublished(item("music-prevcheck001", "music", "prevcheck theme"), audio);
+          await t.seedPublished(...png("image-prevcheck001", "prevcheck picture"));
+          const api = createClient({ baseUrl: t.baseUrl });
+          const by = Object.fromEntries((await api("publicLibrary", { q: "prevcheck" })).items.map((i) => [i.id, i]));
+          expect(Object.keys(by).sort()).toEqual(["image-prevcheck001", "music-prevcheck001", "sfx-prevcheck001"]);
+          const sfxUrl = by["sfx-prevcheck001"]!.previewUrl;
+          expect(sfxUrl).toBeTruthy();
+          const res = await fetch(sfxUrl!);
+          expect(res.ok).toBe(true);
+          expect(new Uint8Array(await res.arrayBuffer())).toEqual(AUDIO);
+          expect((await fetch(by["image-prevcheck001"]!.previewUrl!)).ok).toBe(true);
+          expect(by["music-prevcheck001"]!.previewUrl).toBeUndefined();
+        } finally { await t.close(); }
+      });
+    });
+  });
+}

package/src/testing/fake-api.ts

@@ -0,0 +1,228 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { MAX_UPLOAD_BYTES, routes, type ErrorCode, type LibraryItem, type RouteName, type Voice } from "../contract";
+import { PIXEL_PNG, silentWav } from "./fixtures";
+
+type Blob = { filename: string; contentType: string; bytes: Uint8Array };
+// owner is the uploader's user id; a seeded item has none. An upload is not an item for anyone until it is committed.
+type Stored = { item: LibraryItem; file?: Blob; filename: string; contentType: string; owner?: string; committed: boolean };
+
+export const FAKE_VOICES: Voice[] = [
+  { id: "fakewarm", name: "Warm", description: "Warm, calm narrator", gender: "female", language: "en", kind: "stock" },
+  { id: "fakebold", name: "Bold", description: "Energetic, punchy", gender: "male", language: "en", kind: "stock" },
+];
+const WORD_SEC = 0.4;
+// The kinds whose own file is its public preview: a picture or a short sound effect needs no login to look at or hear, while the full file
+// of long media (music, overlays, clips) and a component's source do not. Any kind with a preview of its own would use that instead
+// (the fake has none).
+const PREVIEW_OF_ORIGINAL: readonly string[] = ["image", "sfx"];
+const MIME_PREFIX: Record<string, string> = { image: "image/", clip: "video/", overlay: "video/", sfx: "audio/", music: "audio/" };
+// The device-flow user of the fake is "tester"; anyone else is named from their id, as the API names a user with no profile.
+const handleOf = (userId: string) => (userId === "u-test" ? "tester" : `user-${userId.slice(0, 8)}`);
+const nextMonthStart = (now = new Date()) => new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+
+// The first `max` characters, counted in code points, so an emoji (a surrogate pair) is never split. The same cut as the API's.
+function cut(text: string, max: number): string {
+  if (text.length <= max) return text;
+  let end = 0, n = 0;
+  while (end < text.length && n < max) { end += text.codePointAt(end)! > 0xffff ? 2 : 1; n++; }
+  return text.slice(0, end);
+}
+
+class Fail extends Error { constructor(public status: number, public code: ErrorCode, message: string) { super(message); } }
+
+function parseBody(raw: Buffer): unknown {
+  try { return JSON.parse(raw.toString("utf8") || "{}"); }
+  catch { throw new Fail(400, "invalid_request", "The request body is not valid JSON."); }
+}
+
+export type FakeApi = Awaited<ReturnType<typeof startFakeApi>>;
+
+// An in-memory stand-in for the Reelkit API. It implements every route in the contract.
+export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLimit?: number; autoApprove?: boolean } = {}) {
+  // token -> the user it belongs to
+  const tokens = new Map<string, string>();
+  const devices = new Map<string, { userCode: string; approved: boolean; userId: string }>();
+  const store = new Map<string, Stored>();
+  // An unguessable token -> the one blob that file URL serves.
+  const blobs = new Map<string, Blob>();
+  // An unguessable token -> the one upload it accepts. `used` is set by the first PUT, accepted or not: the fake is stricter than a
+  // real server needs to be, so a client that retries a PUT, or sends a second one, fails here instead of working by luck.
+  const uploads = new Map<string, { id: string; contentType: string; bytes: number; used: boolean }>();
+  // Totals over every user (for tests of the CLI), and the same counts per user (what a quota is measured against).
+  const usage = { chars: 0, images: 0, pulls: 0, uploads: 0 };
+  const meters = new Map<string, { chars: number; images: number; uploads: number }>();
+  const meter = (userId: string | undefined) => {
+    const id = userId ?? "u-test";
+    if (!meters.has(id)) meters.set(id, { chars: 0, images: 0, uploads: 0 });
+    return meters.get(id)!;
+  };
+  const resetDate = () => nextMonthStart().toISOString();
+  const limits = { chars: opts.voiceoverCharLimit ?? 10_000, images: opts.imageLimit ?? 30 };
+  const ALNUM = "abcdefghijklmnopqrstuvwxyz0123456789";
+  const nextId = (prefix: string) => `${prefix}-${Array.from(randomBytes(12), (b) => ALNUM[b % ALNUM.length]).join("")}`;
+  const secret = () => randomBytes(16).toString("hex");
+  let origin = "";
+  // Every call makes a new URL for its own blob. The URL says nothing about the item behind it.
+  const fileUrl = (blob: Blob) => { const t = secret(); blobs.set(t, blob); return `${origin}/files/${t}`; };
+  const words = (s: string) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+
+  const handlers: Record<RouteName, (input: any, req: { token?: string; userId?: string }) => unknown> = {
+    deviceStart: () => {
+      const deviceCode = nextId("dev"), userCode = nextId("USER").toUpperCase();
+      devices.set(deviceCode, { userCode, approved: Boolean(opts.autoApprove), userId: "u-test" });
+      return { deviceCode, userCode, verificationUrl: `${origin}/device`, intervalSec: 1, expiresInSec: 600 };
+    },
+    deviceToken: ({ deviceCode }) => {
+      const d = devices.get(deviceCode);
+      if (!d) return { status: "expired" };
+      if (!d.approved) return { status: "pending" };
+      devices.delete(deviceCode);
+      const token = nextId("tok");
+      tokens.set(token, d.userId);
+      return { status: "approved", token };
+    },
+    revoke: (_input, { token }) => { if (token) tokens.delete(token); return { revoked: true }; },
+    me: (_input, { userId }) => {
+      const m = meter(userId);
+      return {
+        userId: userId ?? "u-test", handle: handleOf(userId ?? "u-test"),
+        quota: { voiceoverChars: { used: m.chars, limit: limits.chars }, images: { used: m.images, limit: limits.images }, resetsAt: resetDate() },
+        contributions: m.uploads,
+      };
+    },
+    // Search and the public library list published items only; nothing private or in review is ever found.
+    librarySearch: ({ q, kind, limit }) => {
+      const want = words(q);
+      // Best match first; items that match equally well come newest first (the one added last).
+      // match is the share of the query's words the item has, to two decimals.
+      const items = [...store.values()]
+        .filter((s) => s.item.visibility === "published" && (!kind || s.item.kind === kind))
+        .map((s, order) => ({ s, order, score: [...want].filter((w) => words(`${s.item.title} ${s.item.description} ${s.item.tags.join(" ")}`).has(w)).length }))
+        .filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.order - a.order).slice(0, limit ?? 8)
+        .map((x) => ({ ...x.s.item, match: Math.round((x.score / want.size) * 100) / 100 }));
+      return { items };
+    },
+    // A caller may pull an item that is published or that they uploaded themselves. Anything else does not exist for them.
+    libraryPull: ({ id }, { userId }) => {
+      const s = store.get(id);
+      if (!s?.file || !s.committed || (s.item.visibility !== "published" && s.owner !== userId)) throw new Fail(404, "not_found", `No library item with id ${id}.`);
+      usage.pulls++;
+      return { item: s.item, url: fileUrl(s.file), filename: s.filename };
+    },
+    libraryUpload: (input, { userId }) => {
+      // The server's rules for an upload: a safe file name, a content type that fits the kind, a size of 1 byte to 200 MB.
+      const filename = (input.filename as string).replace(/[^A-Za-z0-9._-]/g, "_");
+      if (!/^[A-Za-z0-9]/.test(filename) || filename.length > 128) throw new Fail(400, "invalid_request", "The filename must start with a letter or digit and be at most 128 characters. Rename the file and try again.");
+      if (!(input.contentType as string).toLowerCase().startsWith(MIME_PREFIX[input.kind])) throw new Fail(400, "invalid_request", `A ${input.kind} must have a ${MIME_PREFIX[input.kind]}* content type, not "${input.contentType}".`);
+      if (input.bytes < 1 || input.bytes > MAX_UPLOAD_BYTES) throw new Fail(400, "invalid_request", "The file must be between 1 byte and 200 MB.");
+      const id = nextId(input.kind);
+      const item: LibraryItem = { id, kind: input.kind, title: input.title, description: input.description, tags: input.tags, meta: input.meta, visibility: input.shareable ? "review" : "private" };
+      store.set(id, { item, filename, contentType: input.contentType, owner: userId, committed: false });
+      const token = secret();
+      uploads.set(token, { id, contentType: input.contentType, bytes: input.bytes, used: false });
+      return { id, uploadUrl: `${origin}/upload/${token}` };
+    },
+    libraryCommit: ({ id }, { userId }) => {
+      const s = store.get(id);
+      if (!s || s.owner !== userId) throw new Fail(404, "not_found", `No upload with id ${id}.`);
+      if (!s.file) throw new Fail(400, "invalid_request", `Nothing was uploaded for ${id}. Send the file to the upload URL first.`);
+      // Committing again returns the same item and counts once.
+      if (!s.committed) { s.committed = true; usage.uploads++; if (s.item.visibility === "review") meter(userId).uploads++; }
+      return { item: s.item };
+    },
+    voices: () => ({ voices: FAKE_VOICES }),
+    voiceover: ({ text: raw, voiceId }, { userId }) => {
+      const text = (raw as string).replace(/\r\n?/g, "\n");
+      if (voiceId !== undefined && !FAKE_VOICES.some((v) => v.id === voiceId)) throw new Fail(400, "invalid_request", "That voice is not available. Run `reelkit assets voices` to see the list.");
+      const m = meter(userId);
+      if (m.chars + text.length > limits.chars) throw new Fail(429, "quota_exceeded", `Voiceover quota used up. It resets on ${resetDate().slice(0, 10)}.`);
+      m.chars += text.length;
+      usage.chars += text.length;
+      const list = text.trim().split(/\s+/).map((word: string, i: number) => ({ word, startSec: i * WORD_SEC, endSec: (i + 1) * WORD_SEC }));
+      const durationSec = list.length * WORD_SEC;
+      return { url: fileUrl({ filename: "vo.wav", contentType: "audio/wav", bytes: silentWav(durationSec) }), ext: "wav", contentType: "audio/wav", durationSec, words: list, chars: text.length };
+    },
+    images: ({ prompt, aspect, shareable, tags }, { userId }) => {
+      const m = meter(userId);
+      if (m.images + 1 > limits.images) throw new Fail(429, "quota_exceeded", `Image quota used up. It resets on ${resetDate().slice(0, 10)}.`);
+      m.images++;
+      usage.images++;
+      const id = nextId("image");
+      const file = { filename: "image.png", contentType: "image/png", bytes: PIXEL_PNG };
+      if (shareable) store.set(id, { item: { id, kind: "image", title: cut(prompt, 60), description: prompt, tags, meta: { aspect }, visibility: "review" }, file, filename: file.filename, contentType: file.contentType, owner: userId, committed: true });
+      return { url: fileUrl(file), ext: "png", contentType: "image/png", ...(shareable ? { libraryId: id } : {}) };
+    },
+    publicLibrary: ({ q, kind, page }) => {
+      // Published items only. Newest first; with a query, best match first and equal matches newest first.
+      const want = q ? words(q) : undefined;
+      const score = (i: LibraryItem) => (want ? [...want].filter((w) => words(`${i.title} ${i.description} ${i.tags.join(" ")}`).has(w)).length : 0);
+      const all = [...store.values()]
+        .map((s, order) => ({ s, order, score: score(s.item) }))
+        .filter((x) => x.s.item.visibility === "published" && (!kind || x.s.item.kind === kind) && (!want || x.score > 0))
+        .sort((a, b) => b.score - a.score || b.order - a.order).map((x) => x.s);
+      const p = page ?? 1, size = 24;
+      const items = all.slice((p - 1) * size, p * size).map((s) => (s.file && PREVIEW_OF_ORIGINAL.includes(s.item.kind) ? { ...s.item, previewUrl: fileUrl(s.file) } : s.item));
+      return { items, page: p, hasMore: all.length > p * size };
+    },
+  };
+
+  const server = createServer(async (req, res) => {
+    const send = (status: number, body: unknown) => { res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body)); };
+    try {
+      const url = new URL(req.url ?? "/", origin);
+      const chunks: Buffer[] = [];
+      for await (const c of req) chunks.push(c as Buffer);
+      const raw = Buffer.concat(chunks);
+
+      if (url.pathname.startsWith("/files/")) {
+        const blob = blobs.get(url.pathname.slice("/files/".length));
+        if (!blob) return send(404, { error: { code: "not_found", message: "No such file." } });
+        res.writeHead(200, { "content-type": blob.contentType, "content-length": blob.bytes.length }).end(blob.bytes);
+        return;
+      }
+      if (req.method === "PUT" && url.pathname.startsWith("/upload/")) {
+        const up = uploads.get(url.pathname.slice("/upload/".length));
+        const s = up && store.get(up.id);
+        if (!up || !s) return send(404, { error: { code: "not_found", message: "No such upload." } });
+        // The URL is good for one PUT. Whether that PUT is accepted or refused, a second one is dead, and so is any PUT after commit.
+        // (A real server may be kinder; the contract promises clients no more than this.)
+        if (up.used || s.file) throw new Fail(400, "invalid_request", "This upload URL has already been used.");
+        up.used = true;
+        if (req.headers["content-type"] !== up.contentType) throw new Fail(400, "invalid_request", `The upload must be sent as ${up.contentType}.`);
+        if (raw.length !== up.bytes) throw new Fail(400, "invalid_request", `The upload must be exactly ${up.bytes} bytes.`);
+        s.file = { filename: s.filename, contentType: s.contentType, bytes: new Uint8Array(raw) };
+        return send(200, {});
+      }
+
+      const entry = (Object.entries(routes) as [RouteName, (typeof routes)[RouteName]][])
+        .find(([, r]) => r.method === req.method && `/api/v1${r.path}` === url.pathname);
+      if (!entry) throw new Fail(404, "not_found", `No route ${req.method} ${url.pathname}.`);
+      const [name, r] = entry;
+      const token = (req.headers.authorization ?? "").replace(/^Bearer /, "");
+      const userId = tokens.get(token);
+      if (r.auth && !userId) throw new Fail(401, "unauthenticated", "Not logged in. Run `reelkit auth login`.");
+      const input = r.method === "GET" ? Object.fromEntries(url.searchParams) : parseBody(raw);
+      const parsed = r.req.safeParse(input);
+      if (!parsed.success) throw new Fail(400, "invalid_request", parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
+      send(200, handlers[name](parsed.data, { token: token || undefined, userId }));
+    } catch (e) {
+      if (e instanceof Fail) send(e.status, { error: { code: e.code, message: e.message } });
+      else send(500, { error: { code: "server_error", message: e instanceof Error ? e.message : String(e) } });
+    }
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+
+  return {
+    baseUrl: `${origin}/api/v1`,
+    usage,
+    approve(userCode: string, userId = "u-test") { for (const d of devices.values()) if (d.userCode === userCode) { d.approved = true; d.userId = userId; } },
+    // A ready token, for tests that are not about logging in.
+    login(userId = "u-test") { const t = nextId("tok"); tokens.set(t, userId); return t; },
+    seed(item: LibraryItem, file: Blob) { store.set(item.id, { item, file, filename: file.filename, contentType: file.contentType, committed: true }); },
+    items: () => [...store.values()].map((s) => s.item),
+    close: () => new Promise<void>((r) => { server.closeAllConnections(); server.close(() => r()); }),
+  };
+}