@anteros/core 0.0.41 → 0.0.42

package/tests/messages.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect, afterAll } from "bun:test";
+import { normalizeMessages } from "../lib/messages";
+import { MAX_FILE_BYTES } from "../lib/attachment";
+
+/** A tiny local file server — the `file: { url }` path downloads through `fetch`. */
+const servers: Array<ReturnType<typeof Bun.serve>> = [];
+function serve(body: Uint8Array | string, contentType = "application/pdf") {
+    const server = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: () => new Response(body as any, { headers: { "Content-Type": contentType } }),
+    });
+    servers.push(server);
+    return `http://127.0.0.1:${server.port}/report.pdf`;
+}
+
+afterAll(() => {
+    for (const server of servers) server.stop(true);
+});
+
+const first = async (input: any) => (await normalizeMessages(input))[0] as any;
+
+describe("normalizeMessages — the shapes it accepts", () => {
+    it("turns a string into one user turn", async () => {
+        expect(await normalizeMessages("hi")).toEqual([{ role: "user", content: "hi" }]);
+    });
+
+    it("accepts a single message — with or without an array", async () => {
+        const message = { role: "user", content: "hi" } as const;
+        expect(await normalizeMessages(message)).toEqual([{ role: "user", content: "hi" }]);
+        expect(await normalizeMessages([message])).toEqual([{ role: "user", content: "hi" }]);
+    });
+
+    it("keeps a whole conversation in order", async () => {
+        const messages = await normalizeMessages([
+            { role: "user", content: "hi" },
+            { role: "assistant", content: "hello" },
+            { role: "user", content: "and?" },
+        ]);
+        expect(messages.map((message) => message.role)).toEqual(["user", "assistant", "user"]);
+        expect((messages[1] as any).content).toBe("hello");
+    });
+
+    it("keeps only the canonical fields — a stray key never reaches the wire", async () => {
+        const [message] = await normalizeMessages([{ role: "user", content: "hi", threadId: "t", bogus: 1 } as any]);
+        expect(message).toEqual({ role: "user", content: "hi" });
+    });
+});
+
+describe("normalizeMessages — content parts", () => {
+    it("keeps text, image and file parts, url or base64", async () => {
+        const [message] = await normalizeMessages([{
+            role: "user",
+            content: [
+                { type: "text", text: "look" },
+                { type: "image", url: "https://example.com/a.png" },
+                { type: "image", data: "AAAA", mimeType: "image/png" },
+                { type: "file", name: "a.pdf", data: "BBBB", mimeType: "application/pdf" },
+            ],
+        }] as any);
+
+        expect((message as any).content).toEqual([
+            { type: "text", text: "look" },
+            { type: "image", url: "https://example.com/a.png" },
+            { type: "image", mimeType: "image/png", data: "AAAA" },
+            { type: "file", name: "a.pdf", mimeType: "application/pdf", data: "BBBB" },
+        ]);
+    });
+
+    it("joins a system message written as parts", async () => {
+        const [message] = await normalizeMessages([
+            { role: "system", content: [{ type: "text", text: "a" }, { type: "text", text: "b" }] },
+        ] as any);
+        expect(message).toEqual({ role: "system", content: "a\nb" });
+    });
+
+    it("downloads a remote file and inlines it as base64", async () => {
+        const url = serve("%PDF-1.7 payload");
+        const [message] = await normalizeMessages([
+            { role: "user", content: [{ type: "file", url, name: "invoice.pdf" }] },
+        ] as any);
+
+        const part: any = (message as any).content[0];
+        expect(part.type).toBe("file");
+        expect(part.name).toBe("invoice.pdf");
+        // The URL is gone — the payload travels as base64, which every provider takes
+        expect(part.url).toBeUndefined();
+        expect(Buffer.from(part.data, "base64").toString()).toBe("%PDF-1.7 payload");
+    });
+
+    it("leaves a remote image as a URL — the provider fetches it", async () => {
+        const message: any = await first([{ role: "user", content: [{ type: "image", url: "https://example.com/a.png" }] }]);
+        expect(message.content[0].url).toBe("https://example.com/a.png");
+        expect(message.content[0].data).toBeUndefined();
+    });
+
+    it("refuses a part without a payload, an unknown address, or an unsupported scheme", async () => {
+        const cases = [
+            [{ type: "image" }],
+            [{ type: "file", name: "a.pdf" }],
+            [{ type: "image", url: "ftp://example.com/a.png" }],
+            [{ type: "image", url: "./local.png" }],
+        ];
+        for (const content of cases) {
+            const error: any = await normalizeMessages([{ role: "user", content }] as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses a file that is too large", async () => {
+        const url = serve(new Uint8Array(MAX_FILE_BYTES + 1));
+        const error: any = await normalizeMessages([
+            { role: "user", content: [{ type: "file", url, name: "huge.pdf" }] },
+        ] as any).catch((err) => err);
+        expect(error.code).toBe("AGENT_FILE_TOO_LARGE");
+    });
+});
+
+describe("normalizeMessages — tool parts", () => {
+    it("hoists `tool-call` parts onto the assistant message", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "tool-call", id: "call_1", name: "forecast", arguments: { city: "Paris" } }],
+        }] as any);
+
+        expect(message).toEqual({
+            role: "assistant",
+            content: null,
+            toolCalls: [{ id: "call_1", name: "forecast", args: { city: "Paris" } }],
+        });
+    });
+
+    it("merges inline calls with the ones declared as `toolCalls`", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "text", text: "let me check" }, { type: "tool-call", id: "b", name: "two" }],
+            toolCalls: [{ id: "a", name: "one", args: {} }],
+        }] as any) as any[];
+
+        expect(message.content).toBe("let me check");
+        expect(message.toolCalls.map((call: any) => call.id)).toEqual(["a", "b"]);
+    });
+
+    it("keeps a raw `argsText` when the caller had one", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "tool-call", id: "c", name: "f", argsText: '{"city":"Lyon"}', arguments: { city: "Lyon" } }],
+        }] as any) as any[];
+        expect(message.toolCalls[0]).toEqual({ id: "c", name: "f", args: { city: "Lyon" }, argsText: '{"city":"Lyon"}' });
+    });
+
+    it("turns a `tool-result` part into the `tool` message it means", async () => {
+        const messages = await normalizeMessages([{
+            role: "user",
+            content: [
+                { type: "text", text: "and?" },
+                { type: "tool-result", id: "call_1", name: "forecast", result: { celsius: 21 } },
+                { type: "tool-result", id: "call_2", name: "boom", error: "timeout" },
+            ],
+        }] as any) as any[];
+
+        expect(messages.map((message) => message.role)).toEqual(["user", "tool", "tool"]);
+        expect(messages[0].content).toEqual([{ type: "text", text: "and?" }]);
+        expect(messages[1]).toEqual({
+            role: "tool", toolCallId: "call_1", name: "forecast", content: '{"celsius":21}',
+        });
+        expect(messages[2]).toEqual({
+            role: "tool", toolCallId: "call_2", name: "boom", content: "Error: timeout", isError: true,
+        });
+    });
+
+    it("expands a `tool` message carrying several results", async () => {
+        const messages = await normalizeMessages([{
+            role: "tool",
+            content: [
+                { type: "tool-result", id: "a", result: "one" },
+                { type: "tool-result", id: "b", result: "two" },
+            ],
+        }] as any) as any[];
+
+        expect(messages).toEqual([
+            { role: "tool", toolCallId: "a", name: "tool", content: "one" },
+            { role: "tool", toolCallId: "b", name: "tool", content: "two" },
+        ]);
+    });
+
+    it("keeps a `tool` message written the classic way", async () => {
+        const [message] = await normalizeMessages([
+            { role: "tool", toolCallId: "call_1", name: "forecast", content: "21°C" },
+        ] as any);
+        expect(message).toEqual({ role: "tool", toolCallId: "call_1", name: "forecast", content: "21°C" });
+    });
+});
+
+describe("normalizeMessages — what it refuses", () => {
+    it("refuses an unknown role and a message without one", async () => {
+        for (const input of [[{ role: "robot", content: "hi" }], [{ content: "hi" }], [null]]) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+            expect(error.status).toBe(400);
+        }
+    });
+
+    it("refuses a part the role cannot carry", async () => {
+        const cases: any[] = [
+            [{ role: "user", content: [{ type: "tool-call", id: "a", name: "f" }] }],
+            [{ role: "assistant", content: [{ type: "image", url: "https://example.com/a.png" }] }],
+            [{ role: "system", content: [{ type: "image", url: "https://example.com/a.png" }] }],
+            [{ role: "tool", content: [{ type: "text", text: "no" }] }],
+            [{ role: "tool", content: "orphan" }], // no `toolCallId`
+            [{ role: "user", content: [{ type: "tool-result" }] }], // no id
+        ];
+        for (const input of cases) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses a message without content", async () => {
+        for (const role of ["user", "system", "tool"]) {
+            const error: any = await normalizeMessages([{ role }] as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses an empty content array rather than sending an empty turn", async () => {
+        for (const input of [
+            [{ role: "user", content: [] }],
+            [{ role: "tool", content: [] }],
+            [{ role: "developer", content: [] }],
+        ]) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+
+        // An assistant turn with no text is legitimate — a tool call carries the turn
+        expect(await normalizeMessages([{ role: "assistant", content: [] }] as any))
+            .toEqual([{ role: "assistant", content: null }]);
+    });
+});
+
+describe("normalizeMessages — developer role and names", () => {
+    it("keeps the `developer` role and a message name", async () => {
+        const messages = await normalizeMessages([
+            { role: "developer", content: "answer concisely", name: "policy" },
+            { role: "user", content: "hi", name: "ada" },
+        ] as any);
+
+        expect(messages[0]).toEqual({ role: "developer", content: "answer concisely", name: "policy" });
+        expect(messages[1]).toEqual({ role: "user", content: "hi", name: "ada" });
+    });
+
+    it("keeps the raw thinking blocks of a replayed assistant turn", async () => {
+        const thinking = [{ type: "thinking", thinking: "…", signature: "sig" }];
+        const [message] = await normalizeMessages([{ role: "assistant", content: "done", thinking }] as any) as any[];
+        expect(message.thinking).toEqual(thinking);
+    });
+});

package/tests/replication-control.test.ts

@@ -102,7 +102,7 @@ describe("replication seed", () => {
         const preMarker = `pre-${crypto.randomUUID()}`;
         await rest.insertOne("orders", { title: preMarker });
 
-        const res = await seedReplication(TEST_TENANT, "latest");
+        const res = await seedReplication(TEST_TENANT, "latest", { collection: "orders" });
         expect(res.seeded).toBe(1);
 
         await replicateTenant(TEST_TENANT);
@@ -118,7 +118,7 @@ describe("replication seed", () => {
 
     it("seeds from an explicit date", async () => {
         await resetReplication(TEST_TENANT);
-        const res = await seedReplication(TEST_TENANT, "2020-01-01T00:00:00Z");
+        const res = await seedReplication(TEST_TENANT, "2020-01-01T00:00:00Z", { collection: "orders" });
         expect(res.seeded).toBe(1);
 
         const state = await getReplicationState(TEST_TENANT, DEST_ID, "orders");

package/tests/replication-meta.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import os from "node:os";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncCollections } from "../database/collection";
+import { syncWorkflows } from "../lib/workflow";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+import { syncAgents } from "../lib/agents";
+import { MongoAgentMemory } from "../lib/agentMemory";
+import { AGENT_THREADS } from "./fixtures/replication-meta/agents/chat.agent";
+import type { ReplicationMetaName } from "../types/replication";
+
+const DIR = "packages/core/tests/fixtures/replication-meta";
+
+/** Everything replicated: declared collection + the six framework collections */
+const ALL_T = "rm-default";
+const ALL_T_DB = "mongodb://localhost:27017/_RM_DEFAULT_SRC";
+const ALL_T_DEST = "mongodb://localhost:27017/_RM_DEFAULT_DEST";
+
+/** Nothing but the declared collection */
+const OFF_T = "rm-alloff";
+const OFF_T_DB = "mongodb://localhost:27017/_RM_ALLOFF_SRC";
+const OFF_T_DEST = "mongodb://localhost:27017/_RM_ALLOFF_DEST";
+
+let rest: InstanceType<typeof useRest>;
+let dest: MongoClient;
+let destOff: MongoClient;
+
+const target = (slug: string) => dest.db().collection(slug);
+const targetOff = (slug: string) => destOff.db().collection(slug);
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [
+            {
+                id: ALL_T,
+                dir: DIR,
+                database: { uri: ALL_T_DB },
+                // Opt-in retention, so the destination's copy is pruned the same way
+                audit: { retention: "30d" },
+                replication: {
+                    runOnBoot: false,
+                    schedule: { interval: "1h" },
+                    destinations: [{ id: "backup", uri: ALL_T_DEST }],
+                },
+            },
+            {
+                id: OFF_T,
+                dir: DIR,
+                database: { uri: OFF_T_DB },
+                replication: {
+                    runOnBoot: false,
+                    schedule: { interval: "1h" },
+                    exclude: ["audit", "workflows", "locks", "replication", "vars", "memory"],
+                    destinations: [{ id: "backup", uri: OFF_T_DEST }],
+                },
+            },
+        ],
+    });
+
+    await syncTenants();
+    await syncCollections();
+    await syncWorkflows();
+    await syncAgents(); // publishes the agent memory collections (`cfg.agentMemories`)
+    await startReplication();
+
+    rest = new useRest({ tenant_id: ALL_T });
+    dest = new MongoClient(ALL_T_DEST, { serverSelectionTimeoutMS: 3000 });
+    destOff = new MongoClient(OFF_T_DEST, { serverSelectionTimeoutMS: 3000 });
+    await dest.connect();
+    await destOff.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    for (const uri of [ALL_T_DB, ALL_T_DEST, OFF_T_DB, OFF_T_DEST]) {
+        try {
+            const client = new MongoClient(uri);
+            await client.connect();
+            await client.db().dropDatabase();
+            await client.close();
+        } catch (_) {}
+    }
+    cfg.agents = [];
+    cfg.agentMemories = [];
+    try { await dest.close(); } catch (_) {}
+    try { await destOff.close(); } catch (_) {}
+});
+
+describe("replication — framework collections", () => {
+    it("replicates them by default (audit, workflows, locks, replication, vars, memory)", async () => {
+        const marker = `meta-${crypto.randomUUID()}`;
+
+        await rest.audit.addActivities([{
+            internal: true,
+            trace: { id: crypto.randomUUID() },
+            meta: {},
+            operation: {
+                tenant: ALL_T, action: marker, collection: "orders",
+                status: "success", input: null, result: null, error: null, duration: 0, transaction: false,
+            },
+            ts: new Date(),
+        } as any]);
+        await rest.workflow.run("run", { marker });
+        await rest.vars.set("config", marker, "META-1");
+        await rest.lock(`meta-${marker}`);
+        await rest.insertOne("orders", { title: marker });
+        // An agent conversation — the collection this tenant named for its memory
+        await new MongoAgentMemory({ collection: AGENT_THREADS }).save(
+            "chat-1",
+            [{ role: "user", content: marker }] as any,
+            { rest, tenant: ALL_T, resourceId: "u1" },
+        );
+
+        // A first run picks the state document it writes, hence the second one
+        await replicateTenant(ALL_T);
+        await replicateTenant(ALL_T);
+
+        expect(await target("_audit_").findOne({ "operation.action": marker })).toBeDefined();
+        expect(await target("_workflows_").findOne({ workflowId: "run" })).toBeDefined();
+        expect(await target("_vars_").findOne({ ns: "config", key: marker })).toBeDefined();
+        expect(await target("_locks_").findOne({ name: `meta-${marker}` })).toBeDefined();
+        expect(await target("_replication_").findOne({ type: "state", tenant: ALL_T })).toBeDefined();
+        expect(await target(AGENT_THREADS).findOne({ _id: "u1:chat-1" as any })).toBeDefined();
+        expect(await target("orders").findOne({ title: marker })).toBeDefined();
+
+        await rest.unlock(`meta-${marker}`);
+    }, 30_000);
+
+    it("propagates a cleared thread to the destination (tombstone)", async () => {
+        // The thread replicated by the previous test is deleted at the source: no
+        // date cursor can see a deletion, so the store leaves a tombstone.
+        await new MongoAgentMemory({ collection: AGENT_THREADS }).clear("chat-1", { rest, tenant: ALL_T, resourceId: "u1" });
+
+        await replicateTenant(ALL_T);
+
+        expect(await target(AGENT_THREADS).findOne({ _id: "u1:chat-1" as any })).toBeNull();
+        // The tombstone is consumed and purged
+        expect(await rest.db.collection("_replication_").countDocuments({ type: "delete", collection: AGENT_THREADS })).toBe(0);
+    }, 30_000);
+
+    it("uses each collection's own date key (audit is read on `ts`)", async () => {
+        const state: any = await rest.db.collection("_replication_")
+            .findOne({ type: "state", tenant: ALL_T, collection: "_audit_" });
+        expect(state).toBeDefined();
+        expect(state.key).toBe("ts");
+        // The state says which process is doing the work (`reusePort` / forked workers)
+        expect(state.pid).toBe(process.pid);
+        expect(state.hostname).toBe(os.hostname());
+    });
+
+    it("mirrors the audit retention on the destination", async () => {
+        const ttl: any = (await target("_audit_").listIndexes().toArray())
+            .find((i: any) => i.name === "_audit_ttl_");
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(30 * 86400);
+    }, 30_000);
+
+    it("leaves out only what `exclude` names", async () => {
+        const tenant: any = cfg.tenants?.find((t) => t.id === ALL_T);
+        const marker = `noaudit-${crypto.randomUUID()}`;
+        tenant.replication.exclude = ["audit", "memory"];
+
+        await rest.audit.addActivities([{
+            internal: true, trace: { id: crypto.randomUUID() }, meta: {},
+            operation: {
+                tenant: ALL_T, action: marker, collection: "orders",
+                status: "success", input: null, result: null, error: null, duration: 0, transaction: false,
+            },
+            ts: new Date(),
+        } as any]);
+        await rest.vars.set("config", marker, "still-replicated");
+        await new MongoAgentMemory({ collection: AGENT_THREADS }).save(
+            "chat-2",
+            [{ role: "user", content: marker }] as any,
+            { rest, tenant: ALL_T, resourceId: "u1" },
+        );
+
+        await replicateTenant(ALL_T);
+
+        expect(await target("_audit_").findOne({ "operation.action": marker })).toBeNull();      // excluded
+        expect(await target(AGENT_THREADS).findOne({ _id: "u1:chat-2" as any })).toBeNull();     // excluded
+        expect(await target("_vars_").findOne({ ns: "config", key: marker })).toBeDefined();     // still there
+
+        delete tenant.replication.exclude;
+    }, 30_000);
+
+    it("replicates nothing from the framework when every name is excluded", async () => {
+        const offRest = new useRest({ tenant_id: OFF_T });
+        const marker = `alloff-${crypto.randomUUID()}`;
+
+        await offRest.audit.addActivities([{
+            internal: true, trace: { id: crypto.randomUUID() }, meta: {},
+            operation: {
+                tenant: OFF_T, action: marker, collection: "orders",
+                status: "success", input: null, result: null, error: null, duration: 0, transaction: false,
+            },
+            ts: new Date(),
+        } as any]);
+        await offRest.vars.set("config", marker, "not-replicated");
+        await offRest.insertOne("orders", { title: marker });
+        await new MongoAgentMemory({ collection: AGENT_THREADS }).save(
+            "chat-3",
+            [{ role: "user", content: marker }] as any,
+            { rest: offRest, tenant: OFF_T, resourceId: "u1" },
+        );
+
+        await replicateTenant(OFF_T);
+        await replicateTenant(OFF_T);
+
+        // The declared collection still replicates…
+        expect(await targetOff("orders").findOne({ title: marker })).toBeDefined();
+        // …but the framework collections do not exist on that destination
+        expect(await targetOff("_audit_").countDocuments({})).toBe(0);
+        expect(await targetOff("_vars_").countDocuments({})).toBe(0);
+        expect(await targetOff("_workflows_").countDocuments({})).toBe(0);
+        expect(await targetOff(AGENT_THREADS).countDocuments({})).toBe(0);
+    }, 30_000);
+
+    it("propagates a delete on a collection whose key is a number", async () => {
+        const doc: any = await rest.insertOne("counters", { seq: 100, title: "numeric-key" });
+        await replicateTenant(ALL_T);
+        expect(await target("counters").findOne({ title: "numeric-key" })).toBeDefined();
+
+        await rest.deleteOne("counters", doc._id);
+        await replicateTenant(ALL_T);
+        // The tombstone guard compares the key to a date by default: a numeric key
+        // used to silently skip the delete
+        expect(await target("counters").findOne({ title: "numeric-key" })).toBeNull();
+    }, 30_000);
+
+    it("keeps the `exclude` list typed", () => {
+        const names: ReplicationMetaName[] = ["audit", "workflows", "locks", "replication", "vars", "memory"];
+        expect(names.length).toBe(6);
+
+        // @ts-expect-error — a declared collection slug is not a framework collection
+        const wrong: ReplicationMetaName[] = ["orders"];
+        expect(wrong.length).toBe(1);
+    });
+});

package/tests/upload.test.ts

@@ -5,6 +5,7 @@ import { formatConfig, cfg } from "../server/config";
 import { syncTenants } from "../database/tenant";
 import { getFileCollection } from "../database/file";
 import { useRest } from "../database/rest";
+import { createApi } from "../lib/api";
 
 const TENANT = "up-test";
 const DB = "mongodb://localhost:27017/_DB_UP_TEST";
@@ -75,7 +76,7 @@ describe("upload — audit trail", () => {
         form.append("file", pngFile("audited.png"));
         form.append("label", "audited");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
         const body: any = await res.json();
 
@@ -101,10 +102,10 @@ describe("upload — audit trail", () => {
         const form = new FormData();
         form.append("file", pngFile("deleted.png"));
         const uploaded: any = await (
-            await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form })
+            await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form })
         ).json();
 
-        const res = await fetch(`${url}/files/${TENANT}/${SLUG}/${uploaded._id}`, { method: "DELETE" });
+        const res = await fetch(`${url}/api/${TENANT}/files/${SLUG}/${uploaded._id}`, { method: "DELETE" });
         expect(res.status).toBe(200);
 
         const logged: any = await auditEntry("deleteFile");
@@ -122,7 +123,7 @@ describe("upload — single file (unchanged contract)", () => {
         form.append("file", pngFile("one.png"));
         form.append("label", "single");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
 
         const body: any = await res.json();
@@ -130,7 +131,7 @@ describe("upload — single file (unchanged contract)", () => {
         expect(body._id).toBeString();
         expect(body._file.name).toBe("one.png");
         expect(body._file.mimetype).toBe("image/png");
-        expect(body._file.url).toContain(`/files/${TENANT}/${SLUG}/`);
+        expect(body._file.url).toContain(`/api/${TENANT}/files/${SLUG}/`);
         expect(body.createdAt).toBeString();
         expect(body.updatedAt).toBeString();
 
@@ -148,7 +149,7 @@ describe("upload — single file (unchanged contract)", () => {
         const form = new FormData();
         form.append("upload", pngFile("alt.png"));
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
         const body: any = await res.json();
         expect(Array.isArray(body)).toBe(false);
@@ -164,7 +165,7 @@ describe("upload — multiple files", () => {
         form.append("file", pngFile("c.png"));
         form.append("label", "batch");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
 
         const body: any = await res.json();
@@ -178,7 +179,7 @@ describe("upload — multiple files", () => {
         for (const id of ids) {
             const doc: any = await rest.findOne(SLUG, id);
             expect(doc.label).toBe("batch");
-            expect(doc._file.url).toContain(`/files/${TENANT}/${SLUG}/`);
+            expect(doc._file.url).toContain(`/api/${TENANT}/files/${SLUG}/`);
             // Uploads carry timestamps (required by the replication cursor)
             expect(doc.createdAt).toBeString();
             expect(doc.updatedAt).toBeString();
@@ -189,7 +190,7 @@ describe("upload — multiple files", () => {
         const form = new FormData();
         form.append("label", "nofile");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(400);
         const body: any = await res.json();
         expect(body.code).toBe("FILE_REQUIRED");
@@ -200,7 +201,7 @@ describe("upload — multiple files", () => {
         form.append("file", pngFile("ok.png"));
         form.append("file", new File([Buffer.from("nope")], "bad.exe", { type: "application/x-msdownload" }));
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(400);
         const body: any = await res.json();
         expect(body.code).toBe("MIMETYPE_NOT_ALLOWED");
@@ -214,7 +215,7 @@ describe("upload — custom field types (toBson, like collections)", () => {
         form.append("label", "dated");
         form.append("takenAt", "2024-05-01T10:00:00.000Z");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
         const body: any = await res.json();
 
@@ -227,7 +228,7 @@ describe("upload — custom field types (toBson, like collections)", () => {
         const form = new FormData();
         form.append("file", pngFile("2024-01-01")); // ← a file literally named like a date
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
         const body: any = await res.json();
         expect(body._file.name).toBe("2024-01-01");
@@ -237,3 +238,34 @@ describe("upload — custom field types (toBson, like collections)", () => {
         expect(typeof raw._file.name).toBe("string");
     });
 });
+
+describe("api.files — the in-process facade", () => {
+    it("builds a file URL, with the transformations the route understands", () => {
+        const api = createApi(rest);
+
+        expect(api.files.url(SLUG, "f1.png")).toBe(`/api/${TENANT}/files/${SLUG}/f1.png`);
+        expect(api.files.url(SLUG, "f1.png", { width: 200, format: "webp" }))
+            .toBe(`/api/${TENANT}/files/${SLUG}/f1.png?w=200&format=webp`);
+        expect(api.files.url(SLUG, "f1.png", { width: 200, height: 100, format: "avif", quality: 70 }))
+            .toBe(`/api/${TENANT}/files/${SLUG}/f1.png?w=200&h=100&format=avif&q=70`);
+    });
+
+    it("deletes the binary and the document — the same path as the route", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("to-delete.png"));
+        const uploaded: any = await (
+            await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form })
+        ).json();
+
+        const fs = await import("node:fs/promises");
+        const storage = getFileCollection(SLUG, TENANT)?.storage as any;
+        const dir = `${process.cwd()}/${storage?.path ?? "storage"}/${TENANT}/${SLUG}`;
+        expect((await fs.readdir(dir)).some((name) => name.startsWith(uploaded._id))).toBe(true);
+
+        const result = await createApi(rest).files.delete(SLUG, uploaded._id);
+
+        expect(result).toEqual({ message: "File deleted", ok: true });
+        expect(await rest.findOne(SLUG, uploaded._id)).toBeNull();
+        expect((await fs.readdir(dir)).some((name) => name.startsWith(uploaded._id))).toBe(false);
+    });
+});