@anteros/core 0.0.41 → 0.0.44

package/tests/api-private-fields.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { createApp } from "../server/hono";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { useRest } from "../database/rest";
+
+/**
+ * `api.privateFields` on a **collection reached through a join**.
+ *
+ * `func.omit` walks the whole response, but only with the matchers of the
+ * collection that was queried: an `$include`d document carries the *included*
+ * collection's fields, so that collection's `privateFields` must be applied too
+ * — at the path the join put it, and nowhere else. Same story for a `$lookup`
+ * inside an `aggregate` pipeline.
+ */
+
+const TENANT = "private-fields";
+const DB = "mongodb://localhost:27017/_API_PRIVATE_FIELDS_TEST";
+
+let url = "";
+let server: any;
+let rest: InstanceType<typeof useRest>;
+let internal: InstanceType<typeof useRest>;
+
+async function call(collection: string, action: string, body?: any) {
+    const res = await fetch(`${url}/api/${TENANT}/collections/${collection}/${action}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    return { status: res.status, body: (await res.json()) as any };
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: "src", database: { uri: DB } }],
+    });
+    await syncTenants();
+
+    (cfg as any).collections = [
+        {
+            _tenant_: TENANT,
+            slug: "authors",
+            fields: [
+                { name: "name", type: "string" },
+                { name: "password", type: "string" },
+                { name: "secret_token", type: "string" },
+            ],
+            api: { access: { "*": true }, privateFields: ["password", /^secret_/] },
+        },
+        {
+            _tenant_: TENANT,
+            slug: "posts",
+            fields: [
+                { name: "title", type: "string" },
+                // A public field that happens to match the *included* collection's
+                // matcher — it must survive: only the joined document is masked.
+                { name: "secret_note", type: "string" },
+                { name: "author", type: "relationship", relation: { to: "authors" } },
+                { name: "reviewers", type: "relationship", relation: { to: "authors", hasMany: true } },
+            ],
+            // The collection being queried declares no private field of its own:
+            // only the included one does.
+            api: { access: { "*": true } },
+        },
+    ];
+
+    rest = new useRest({ internal: false, tenant_id: TENANT });
+    internal = new useRest({ internal: true, tenant_id: TENANT });
+
+    const app = createApp();
+    server = Bun.serve({ port: 0, fetch: app.fetch });
+    url = server.url.href.replace(/\/$/, "");
+});
+
+afterAll(async () => {
+    for (const name of ["authors", "posts", "_locks_", "_audit_"]) {
+        try { await rest.db.collection(name).drop(); } catch (_) { /* first run */ }
+    }
+    server?.stop(true);
+});
+
+async function seed() {
+    await rest.db.collection("authors").deleteMany({});
+    await rest.db.collection("posts").deleteMany({});
+    const author = await rest.insertOne("authors", {
+        name: "Ada",
+        password: "s3cret-hash",
+        secret_token: "tok_live_123",
+    });
+    const post = await rest.insertOne("posts", {
+        title: "Hello",
+        secret_note: "public-note",
+        author: author._id,
+        reviewers: [author._id],
+    });
+    return { author, post };
+}
+
+describe("api.privateFields across a join", () => {
+    it("masks the included collection's private fields on `find`", async () => {
+        const { post } = await seed();
+
+        const res = await call("posts", "find", { params: { $match: { _id: post._id }, $include: ["author"] } });
+
+        expect(res.status).toBe(200);
+        const doc = res.body[0];
+        expect(doc.author.name).toBe("Ada");
+        expect(doc.author.password).toBeUndefined();
+        expect(doc.author.secret_token).toBeUndefined();
+    });
+
+    it("masks them on `findOne` too", async () => {
+        const { post } = await seed();
+
+        const res = await call("posts", "findOne", { id: post._id, params: { $include: ["author"] } });
+
+        expect(res.status).toBe(200);
+        expect(res.body.author.name).toBe("Ada");
+        expect(res.body.author.password).toBeUndefined();
+        expect(res.body.author.secret_token).toBeUndefined();
+    });
+
+    it("masks every element of a `hasMany` include", async () => {
+        const { post } = await seed();
+
+        const res = await call("posts", "find", { params: { $match: { _id: post._id }, $include: ["reviewers"] } });
+
+        expect(res.status).toBe(200);
+        const reviewers = res.body[0].reviewers;
+        expect(Array.isArray(reviewers)).toBe(true);
+        expect(reviewers[0].name).toBe("Ada");
+        expect(reviewers[0].password).toBeUndefined();
+        expect(reviewers[0].secret_token).toBeUndefined();
+    });
+
+    it("masks them on a `$lookup` of an `aggregate` pipeline", async () => {
+        const { post } = await seed();
+
+        const res = await call("posts", "aggregate", {
+            pipeline: [
+                { $match: { _id: post._id } },
+                { $lookup: { from: "authors", localField: "author", foreignField: "_id", as: "author" } },
+                { $unwind: "$author" },
+            ],
+        });
+
+        expect(res.status).toBe(200);
+        const doc = res.body[0];
+        expect(doc.author.name).toBe("Ada");
+        expect(doc.author.password).toBeUndefined();
+        expect(doc.author.secret_token).toBeUndefined();
+    });
+
+    it("still masks the queried collection's own private fields", async () => {
+        await seed();
+
+        const res = await call("authors", "find", {});
+
+        expect(res.status).toBe(200);
+        expect(res.body[0].name).toBe("Ada");
+        expect(res.body[0].password).toBeUndefined();
+        expect(res.body[0].secret_token).toBeUndefined();
+    });
+
+    it("masks the join only — the queried collection's own matching field survives", async () => {
+        const { post } = await seed();
+
+        const res = await call("posts", "find", { params: { $match: { _id: post._id }, $include: ["author"] } });
+
+        expect(res.status).toBe(200);
+        expect(res.body[0].secret_note).toBe("public-note");
+    });
+});
+
+describe("api.privateFields and the DB query cache", () => {
+    it("does not mutate the cached result (an internal read still sees every field)", async () => {
+        const { post } = await seed();
+        const params = { $match: { _id: post._id }, $include: ["author"] };
+
+        const viaHttp = await call("posts", "find", { params, options: { useCache: true } });
+        expect(viaHttp.body[0].author.password).toBeUndefined();
+
+        // Same query, same (warm) cache entry, but through the trusted internal API:
+        // the masked fields must still be there — masking is a response concern.
+        const viaRest: any = await internal.find("posts", params, { useCache: true });
+        expect(viaRest[0].author.password).toBe("s3cret-hash");
+        expect(viaRest[0].author.secret_token).toBe("tok_live_123");
+
+        // And the HTTP layer stays consistent on the second, cached response.
+        const again = await call("posts", "find", { params, options: { useCache: true } });
+        expect(again.body[0].author.name).toBe("Ada");
+        expect(again.body[0].author.password).toBeUndefined();
+    });
+});

package/tests/api.test.ts

@@ -537,3 +537,54 @@ describe("watch", () => {
         await stream.close();
     });
 });
+
+/**
+ * `rest` is the **original, fully supported surface** — `api` (the facade) and the
+ * SDK namespaces only *group* it. Nothing is removed when something is added, so a
+ * tenant that wrote `rest.find('orders', …)` never has to migrate: this contract
+ * fails loudly if a method ever disappears.
+ */
+describe("rest — the original surface (contract)", () => {
+    const COLLECTION_METHODS = [
+        "find", "findOne", "insertOne", "insertMany",
+        "updateOne", "findOneAndUpdate", "updateMany",
+        "deleteOne", "deleteMany", "bulkWrite", "bulkUpdate",
+        "aggregate", "countDocuments", "watch",
+        "dropCollection", "dropIndex", "dropIndexes",
+        "runAction",
+    ];
+
+    const FAMILY_METHODS = ["runService", "stats", "workflows", "lock", "unlock"];
+    const SESSION_METHODS = ["startSession", "endSession", "startTransaction", "commitTransaction", "abortTransaction"];
+    const GETTERS = ["db", "audit", "cache", "vars", "workflow"];
+
+    it("keeps every method and every member a tenant may already be using", () => {
+        for (const name of [...COLLECTION_METHODS, ...FAMILY_METHODS, ...SESSION_METHODS]) {
+            expect(typeof (rest as any)[name]).toBe("function");
+        }
+        for (const name of GETTERS) {
+            expect((rest as any)[name]).toBeDefined();
+        }
+        expect(rest.tenant_id).toBe(TEST_TENANT);
+    });
+
+    it("keeps the collection methods working exactly as before — `api` is additive", async () => {
+        const created = await rest.insertOne("items", { title: "legacy-surface", count: 1 });
+        const [found] = await rest.find("items", { $match: { title: "legacy-surface" } });
+        expect(found!.title).toBe("legacy-surface");
+
+        await rest.updateOne("items", created._id, { $set: { count: 2 } });
+        expect((await rest.findOne("items", created._id)).count).toBe(2);
+        expect(await rest.countDocuments("items", { title: "legacy-surface" })).toBe(1);
+        expect(await rest.aggregate("items", [{ $match: { title: "legacy-surface" } }, { $count: "n" }]))
+            .toEqual([{ n: 1 }]);
+
+        await rest.deleteOne("items", created._id);
+        expect(await rest.findOne("items", created._id)).toBeNull();
+    });
+
+    it("keeps `rest.vars` working, as the facade re-exposes the same object", async () => {
+        await rest.vars.set("legacy", "key", "value");
+        expect(await rest.vars.get<string>("legacy", "key")).toBe("value");
+    });
+});

package/tests/attachment.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "bun:test";
+import { deflateRawSync } from "node:zlib";
+import { openZip } from "../lib/zip";
+import { docxText, resolveAttachments, xlsxText, MAX_FILE_BYTES } from "../lib/attachment";
+import { openaiMessages, anthropicMessages } from "../lib/providers";
+
+/**
+ * Attachments — a file becomes text, an image or a document part, and the zip
+ * reader behind `.docx` / `.xlsx` is exercised against **real** archives built by
+ * `makeZip` (the same bytes Office writes: local headers + central directory).
+ */
+
+/** Minimal ZIP writer (deflate or stored) — enough to build a .docx/.xlsx fixture. */
+function makeZip(entries: Record<string, string>, options: { store?: boolean } = {}): Uint8Array {
+    const encoder = new TextEncoder();
+    const locals: Uint8Array[] = [];
+    const central: Uint8Array[] = [];
+    let offset = 0;
+
+    const crcTable = (() => {
+        const table = new Uint32Array(256);
+        for (let i = 0; i < 256; i++) {
+            let c = i;
+            for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            table[i] = c >>> 0;
+        }
+        return table;
+    })();
+
+    const crc32 = (bytes: Uint8Array): number => {
+        let crc = 0xffffffff;
+        for (const byte of bytes) crc = crcTable[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+        return (crc ^ 0xffffffff) >>> 0;
+    };
+
+    for (const [name, content] of Object.entries(entries)) {
+        const raw = encoder.encode(content);
+        const method = options.store ? 0 : 8;
+        const data = options.store ? raw : new Uint8Array(deflateRawSync(raw));
+        const nameBytes = encoder.encode(name);
+        const crc = crc32(raw);
+
+        const local = new Uint8Array(30 + nameBytes.length + data.length);
+        const localView = new DataView(local.buffer);
+        localView.setUint32(0, 0x04034b50, true);
+        localView.setUint16(4, 20, true);           // version
+        localView.setUint16(8, method, true);
+        localView.setUint32(14, crc, true);
+        localView.setUint32(18, data.length, true); // compressed
+        localView.setUint32(22, raw.length, true);  // uncompressed
+        localView.setUint16(26, nameBytes.length, true);
+        local.set(nameBytes, 30);
+        local.set(data, 30 + nameBytes.length);
+        locals.push(local);
+
+        const entry = new Uint8Array(46 + nameBytes.length);
+        const entryView = new DataView(entry.buffer);
+        entryView.setUint32(0, 0x02014b50, true);
+        entryView.setUint16(4, 20, true);           // version made by
+        entryView.setUint16(6, 20, true);           // version needed
+        entryView.setUint16(10, method, true);
+        entryView.setUint32(16, crc, true);
+        entryView.setUint32(20, data.length, true);
+        entryView.setUint32(24, raw.length, true);
+        entryView.setUint16(28, nameBytes.length, true);
+        entryView.setUint32(42, offset, true);      // local header offset
+        entry.set(nameBytes, 46);
+        central.push(entry);
+
+        offset += local.length;
+    }
+
+    const centralSize = central.reduce((total, entry) => total + entry.length, 0);
+    const end = new Uint8Array(22);
+    const endView = new DataView(end.buffer);
+    endView.setUint32(0, 0x06054b50, true);
+    endView.setUint16(8, central.length, true);
+    endView.setUint16(10, central.length, true);
+    endView.setUint32(12, centralSize, true);
+    endView.setUint32(16, offset, true);
+
+    const total = offset + centralSize + 22;
+    const zip = new Uint8Array(total);
+    let cursor = 0;
+    for (const chunk of [...locals, ...central, end]) {
+        zip.set(chunk, cursor);
+        cursor += chunk.length;
+    }
+    return zip;
+}
+
+const DOCX = makeZip({
+    "[Content_Types].xml": "<Types/>",
+    "word/document.xml":
+        '<w:body><w:p><w:r><w:t>Invoice INV-2026-001</w:t></w:r></w:p>'
+        + "<w:p><w:r><w:t>Total: 1 200 &amp; 50 EUR</w:t></w:r></w:p>"
+        + "<w:p><w:r><w:tab/><w:t>Paid</w:t></w:r></w:p></w:body>",
+});
+
+const XLSX = makeZip({
+    "xl/sharedStrings.xml":
+        "<sst><si><t>Product</t></si><si><r><t>Widget</t></r><r><t> A</t></r></si>"
+        + "<si><t>Invoice INV-2026-001</t></si></sst>",
+    "xl/worksheets/sheet1.xml":
+        "<worksheet><sheetData>"
+        + '<row r="1"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c></row>'
+        + '<row r="2"><c r="A2" t="s"><v>2</v></c><c r="B2"><v>99.5</v></c><c r="C2" t="inlineStr"><is><t>x,y</t></is></c></row>'
+        + "</sheetData></worksheet>",
+});
+
+const qr = await resolveAttachments({ name: "photo.png", mimeType: "image/png", data: Buffer.from("PNG!").toString("base64") });
+
+describe("openZip", () => {
+    it("lists and reads the entries of a deflated archive", () => {
+        const zip = openZip(XLSX);
+        expect(zip.names().sort()).toEqual(["xl/sharedStrings.xml", "xl/worksheets/sheet1.xml"]);
+        expect(new TextDecoder().decode(zip.read("xl/sharedStrings.xml")!)).toContain("Invoice");
+        expect(zip.read("nope.xml")).toBeNull();
+    });
+
+    it("reads stored entries too, and refuses a non-archive", () => {
+        const zip = openZip(makeZip({ "a.txt": "hello" }, { store: true }));
+        expect(new TextDecoder().decode(zip.read("a.txt")!)).toBe("hello");
+
+        expect(() => openZip(new TextEncoder().encode("not a zip at all"))).toThrow(/central directory/);
+    });
+});
+
+describe("office extraction", () => {
+    it("extracts the text of a .docx, one line per paragraph", () => {
+        const text = docxText(openZip(DOCX));
+        expect(text).toContain("Invoice INV-2026-001");
+        expect(text).toContain("Total: 1 200 & 50 EUR"); // entities decoded
+        expect(text.split("\n").filter(Boolean)).toHaveLength(3);
+    });
+
+    it("extracts the rows of a .xlsx as CSV, shared strings resolved", () => {
+        const text = xlsxText(openZip(XLSX));
+        expect(text).toContain("### Sheet 1");
+        expect(text).toContain("Product,Widget A");           // concatenated runs
+        expect(text).toContain("Invoice INV-2026-001,99.5");  // shared string + number
+        expect(text).toContain('"x,y"');                      // a value with a comma is quoted
+    });
+});
+
+describe("resolveAttachments", () => {
+    it("turns text formats into a text part naming the file", async () => {
+        const parts = await resolveAttachments(
+            { name: "data.csv", data: Buffer.from("a,b\n1,2").toString("base64") },
+        );
+        expect(parts).toHaveLength(1);
+        expect(parts[0]).toEqual({ type: "text", text: "--- data.csv ---\na,b\n1,2" });
+    });
+
+    it("accepts UTF-8 payloads without base64", async () => {
+        const parts = await resolveAttachments({ name: "notes.md", data: "# Hi", encoding: "utf8" });
+        expect((parts[0] as any).text).toBe("--- notes.md ---\n# Hi");
+    });
+
+    it("keeps an image as an image part", () => {
+        expect(qr[0]).toEqual({ type: "image", data: Buffer.from("PNG!").toString("base64"), mimeType: "image/png" });
+    });
+
+    it("keeps a PDF as a document part", async () => {
+        const parts = await resolveAttachments({ name: "invoice.pdf", data: Buffer.from("%PDF-1.7").toString("base64") });
+        expect(parts[0]).toEqual({
+            type: "file",
+            name: "invoice.pdf",
+            mimeType: "application/pdf",
+            data: Buffer.from("%PDF-1.7").toString("base64"),
+        });
+    });
+
+    it("extracts .docx and .xlsx to text", async () => {
+        const [docx, xlsx] = await resolveAttachments([
+            { name: "invoice.docx", data: Buffer.from(DOCX).toString("base64") },
+            { name: "sales.xlsx", data: Buffer.from(XLSX).toString("base64") },
+        ]);
+
+        expect((docx as any).text).toContain("--- invoice.docx ---");
+        expect((docx as any).text).toContain("Invoice INV-2026-001");
+        expect((xlsx as any).text).toContain("Product,Widget A");
+    });
+
+    it("reads a path on the server — relative to the base dir", async () => {
+        const parts = await resolveAttachments("./fixtures/attachment/data.csv", {
+            baseDir: "packages/core/tests",
+        });
+        expect((parts[0] as any).text).toBe("--- data.csv ---\nref,total\nA-1,99");
+    });
+
+    it("refuses what a model cannot read, and says why", async () => {
+        await expect(resolveAttachments(
+            { name: "legacy.doc", data: Buffer.from("D0CF11E0").toString("base64") },
+        )).rejects.toMatchObject({ code: "AGENT_FILE_UNSUPPORTED" });
+
+        await expect(resolveAttachments(
+            { name: "archive.tar.gz", data: Buffer.from("...").toString("base64") },
+        )).rejects.toThrow(/supported attachments/);
+
+        await expect(resolveAttachments("./fixtures/attachment/missing.pdf", {
+            baseDir: "packages/core/tests",
+        })).rejects.toMatchObject({ code: "AGENT_FILE_NOT_FOUND" });
+    });
+
+    it("refuses a file over the size limit", async () => {
+        const oversized = { name: "big.pdf", data: new Uint8Array(MAX_FILE_BYTES + 1) };
+        await expect(resolveAttachments(oversized)).rejects.toMatchObject({ code: "AGENT_FILE_TOO_LARGE" });
+    });
+});
+
+describe("attachments through a provider", () => {
+    it("maps an image and a PDF to both protocols", () => {
+        const messages = [{
+            role: "user" as const,
+            content: [
+                { type: "text" as const, text: "What is this?" },
+                { type: "image" as const, data: "AAAA", mimeType: "image/png" },
+                { type: "file" as const, name: "invoice.pdf", mimeType: "application/pdf", data: "BBBB" },
+            ],
+        }];
+
+        const openai = openaiMessages(undefined, messages as any)[0];
+        expect(openai.content[0]).toEqual({ type: "text", text: "What is this?" });
+        expect(openai.content[1].image_url.url).toBe("data:image/png;base64,AAAA");
+        expect(openai.content[2]).toEqual({
+            type: "file",
+            file: { filename: "invoice.pdf", file_data: "data:application/pdf;base64,BBBB" },
+        });
+
+        const anthropic = anthropicMessages(messages as any).messages[0];
+        expect(anthropic.content[1]).toEqual({
+            type: "image",
+            source: { type: "base64", media_type: "image/png", data: "AAAA" },
+        });
+        expect(anthropic.content[2]).toEqual({
+            type: "document",
+            source: { type: "base64", media_type: "application/pdf", data: "BBBB" },
+        });
+    });
+});

package/tests/audit-operations.test.ts

@@ -145,7 +145,7 @@ describe("audit — services", () => {
         const before = await internalRest.db.collection(AUDIT_COLLECTION)
             .countDocuments({ "operation.action": "runService" });
 
-        const res = await fetch(`${url}/services/${TENANT}/${SERVICE}/charge`, {
+        const res = await fetch(`${url}/api/${TENANT}/services/${SERVICE}/charge`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ data: { amount: 7 } }),

package/tests/audit-redact.test.ts

@@ -77,10 +77,36 @@ afterAll(async () => {
     delete (cfg.server as any).audit;
 });
 
+// The URL shape, pinned here — every surface moved to `/api/:tenant_id/<family>/…`
+describe("API layout", () => {
+    it("serves nothing on a pre-refactor path", async () => {
+        // `/api/<tenant>/<collection>/<action>` used to be a collection action. No alias
+        // is mounted, so it is a plain 404 — never a silent misroute on another handler.
+        const legacy = await fetch(`${url}/api/${TENANT}/${SLUG}/find`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ $limit: 1 }),
+        });
+        expect(legacy.status).toBe(404);
+
+        // Same for a surface that moved with its own family
+        expect((await fetch(`${url}/services/${TENANT}/billing/charge`, { method: "POST" })).status).toBe(404);
+        expect((await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST" })).status).toBe(404);
+
+        // …and the new shape is what answers
+        const current = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/find`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ $limit: 1 }),
+        });
+        expect(current.status).toBe(200);
+    });
+});
+
 describe("audit redaction — defaults", () => {
     it("masks the password of a login payload (success path)", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/login`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/login`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ payload: { email: "ada@example.com", password: "SuperSecret123!" } }),
@@ -95,7 +121,7 @@ describe("audit redaction — defaults", () => {
 
     it("masks the password of a login payload (failure path)", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/login`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/login`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ payload: { email: "bad", password: "WrongOne!" } }),
@@ -156,7 +182,7 @@ describe("audit redaction — defaults", () => {
 
     it("redacts the request headers and query string", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/find?token=query-secret&page=2`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/find?token=query-secret&page=2`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",

package/tests/audit-run-action.test.ts

@@ -81,7 +81,7 @@ describe("audit — custom actions (runAction)", () => {
 
     it("audits the HTTP route as well, and marks it as not internal", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/greet`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/greet`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ data: { name: "Grace" } }),

package/tests/endpoints.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "bun:test";
+import { endpoints, FAMILIES, isReservedFamily, patterns, segment } from "../lib/endpoints";
+
+/**
+ * The URL of everything — pinned here so a change of shape is a **deliberate**
+ * change (the whole surface moved to `/api/:tenant_id/<family>/…` once already,
+ * and every client, doc and skill had to follow).
+ */
+
+describe("endpoints — the server patterns", () => {
+    it("keeps every surface under `/api/:tenant_id/<family>`", () => {
+        for (const pattern of Object.values(patterns)) {
+            expect(pattern.startsWith("/api/:tenant_id/")).toBe(true);
+        }
+    });
+
+    it("names a family the builders also use", () => {
+        const families = new Set<string>(FAMILIES);
+        for (const pattern of Object.values(patterns)) {
+            const [, , , family] = pattern.split("/");
+            expect(families.has(family!)).toBe(true);
+        }
+    });
+
+    it("registers no pattern that could shadow a collection action", () => {
+        // A collection lives under `/collections/`, so `services`, `vars` or `login`
+        // are usable as collection names — that is the point of the layout.
+        expect(patterns.collection.split("/")[3]).toBe("collections");
+        expect(patterns.login).toBe("/api/:tenant_id/collections/:collection/login");
+    });
+});
+
+describe("endpoints — the builders", () => {
+    it("builds the documented paths", () => {
+        expect(endpoints.collection("v1", "orders", "find")).toBe("/api/v1/collections/orders/find");
+        expect(endpoints.collection("v1", "users", "login")).toBe("/api/v1/collections/users/login");
+        expect(endpoints.service("v1", "billing", "charge")).toBe("/api/v1/services/billing/charge");
+        expect(endpoints.vars("v1", "get")).toBe("/api/v1/vars/get");
+        expect(endpoints.upload("v1", "photos")).toBe("/api/v1/upload/photos");
+        expect(endpoints.file("v1", "photos", "507f1f77.jpg")).toBe("/api/v1/files/photos/507f1f77.jpg");
+        expect(endpoints.agent("v1", "support", "generate")).toBe("/api/v1/agents/support/generate");
+        expect(endpoints.mcp("v1")).toBe("/api/v1/mcp");
+    });
+
+    it("matches the pattern it maps to", () => {
+        const mapped: Array<[string, string]> = [
+            [patterns.collection, endpoints.collection("t", "c", "a")],
+            [patterns.login, endpoints.collection("t", "c", "login")],
+            [patterns.service, endpoints.service("t", "s", "a")],
+            [patterns.vars, endpoints.vars("t", "a")],
+            [patterns.upload, endpoints.upload("t", "c")],
+            [patterns.file, endpoints.file("t", "c", "f")],
+            [patterns.agent, endpoints.agent("t", "ag", "a")],
+            [patterns.mcp, endpoints.mcp("t")],
+        ];
+
+        for (const [pattern, path] of mapped) {
+            const expected = pattern.split("/").slice(1);
+            expect(path.split("/").slice(1)).toHaveLength(expected.length);
+            // Same shape: each `:param` is one segment, the literals are identical
+            for (const [index, part] of expected.entries()) {
+                if (part.startsWith(":")) continue;
+                expect(path.split("/").slice(1)[index]).toBe(part);
+            }
+        }
+    });
+
+    it("encodes a segment, so an id with a slash cannot forge a path", () => {
+        expect(segment("a/b c")).toBe("a%2Fb%20c");
+        expect(endpoints.file("v1", "photos", "../etc/passwd")).toBe("/api/v1/files/photos/..%2Fetc%2Fpasswd");
+    });
+});
+
+describe("endpoints — reserved families", () => {
+    it("recognises what a tenant route must not shadow", () => {
+        for (const family of FAMILIES) expect(isReservedFamily(family)).toBe(true);
+        expect(isReservedFamily("orders")).toBe(false);
+        expect(isReservedFamily("Collections")).toBe(false);
+    });
+});

package/tests/file-collection-replication.test.ts

@@ -21,6 +21,8 @@ beforeAll(async () => {
             dir: "src",
             database: { uri: SRC_DB },
             replication: {
+                // These cases exercise the scan engine (file collections)
+                mode: "scan",
                 runOnBoot: false,
                 schedule: { interval: "1h" },
                 destinations: [{ id: "backup", uri: DEST_DB }],

package/tests/fixtures/agent-tenant/agents/support.agent.ts

@@ -0,0 +1,9 @@
+import { define } from "../../../../index";
+
+/** A second agent of the fixture tenant — no tool, no memory. */
+export default define.Agent({
+    id: "support",
+    description: "Answers support questions.",
+    instructions: "You are a support agent.",
+    provider: { model: "claude-test", protocol: "anthropic", apiKey: "fixture-key" },
+});