@orboto/mcp 0.178.0

package/dist/tools/doc-revisions.js

@@ -0,0 +1,133 @@
+/**
+ * ORB-916 - doc revision history MCP tools (epic ORB-911 Phase 5).
+ *
+ * - orboto_list_doc_revisions - GET /docs/:id/revisions  (cursor-paged)
+ * - orboto_get_doc_revision - GET /docs/:id/revisions/:rid
+ * - orboto_restore_doc_revision - POST /docs/:id/revisions/:rid/restore
+ *
+ * Revisions are auto-captured by PATCH /docs/:id every time the title
+ * or body changes, so by the time an agent wants to roll back there's
+ * usually a long history to walk. The list endpoint is cursor-paged
+ * (newest-first by editedAt DESC + id tiebreak) - the tool surfaces
+ * `nextCursor` in structuredContent so the caller can page through if
+ * the default 25-row page isn't enough.
+ *
+ * Restore writes a new revision capturing the current body before
+ * rolling back, so the restore itself is also undoable.
+ */
+import { z } from 'zod';
+import { resolveDocId } from './docs.js';
+// ---------------------------------------------------------------------------
+// orboto_list_doc_revisions
+// ---------------------------------------------------------------------------
+export const listDocRevisionsToolConfig = {
+    title: 'List the revision history of a doc page',
+    description: 'Return saved revisions for a doc page, newest-first. Each row carries the revision id, title at snapshot time, editor user id, and editedAt timestamp; the body content is NOT in this list (use orboto_get_doc_revision to fetch one). Cursor-paged - pass `cursor` to walk older pages.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        limit: z.number().int().min(1).max(100).optional().describe('Page size. Defaults to API default (25).'),
+        cursor: z.string().optional().describe('Opaque cursor from a previous call\'s nextCursor.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListDocRevisionsHandler(client) {
+    return async ({ docId, limit, cursor }) => {
+        docId = await resolveDocId(client, docId);
+        const qs = new URLSearchParams();
+        if (limit !== undefined)
+            qs.set('limit', String(limit));
+        if (cursor)
+            qs.set('cursor', cursor);
+        const query = qs.toString();
+        const path = `/docs/${docId}/revisions${query ? `?${query}` : ''}`;
+        const page = await client.get(path);
+        if (page.items.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No revisions on this doc yet.' }],
+                structuredContent: { revisions: [], nextCursor: null },
+            };
+        }
+        const lines = page.items.map((r) => {
+            const editor = r.editedBy ?? '(unknown)';
+            return `- ${r.editedAt}  ·  ${r.title}  ·  by ${editor}  ·  id: ${r.id}`;
+        });
+        if (page.nextCursor) {
+            lines.push('', `(more available - pass cursor: ${page.nextCursor})`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                revisions: page.items.map((r) => ({
+                    id: r.id,
+                    docId: r.docId,
+                    title: r.title,
+                    editedBy: r.editedBy,
+                    editedAt: r.editedAt,
+                })),
+                nextCursor: page.nextCursor,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_get_doc_revision
+// ---------------------------------------------------------------------------
+export const getDocRevisionToolConfig = {
+    title: 'Get a single doc revision',
+    description: 'Return the full content + title of one saved revision. Use this to diff against the current doc before deciding whether to restore.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        revisionId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetDocRevisionHandler(client) {
+    return async ({ docId, revisionId }) => {
+        docId = await resolveDocId(client, docId);
+        const rev = await client.get(`/docs/${docId}/revisions/${revisionId}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# ${rev.title}\nRevision ${rev.id}  ·  editedAt: ${rev.editedAt}\n\n${rev.content || '_(empty)_'}`,
+                }],
+            structuredContent: {
+                id: rev.id,
+                docId: rev.docId,
+                title: rev.title,
+                content: rev.content,
+                editedBy: rev.editedBy,
+                editedAt: rev.editedAt,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_restore_doc_revision
+// ---------------------------------------------------------------------------
+export const restoreDocRevisionToolConfig = {
+    title: 'Restore a doc page to a saved revision',
+    description: 'Roll back the doc to the saved revision. The API snapshots the CURRENT body to a fresh revision row first, so the restore itself is also undoable. Returns the post-restore doc state.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        revisionId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeRestoreDocRevisionHandler(client) {
+    return async ({ docId, revisionId }) => {
+        docId = await resolveDocId(client, docId);
+        const doc = await client.post(`/docs/${docId}/revisions/${revisionId}/restore`, {});
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Restored doc ${doc.id} to revision ${revisionId}.\n  title: ${doc.title}\n  updatedAt: ${doc.updatedAt}`,
+                }],
+            structuredContent: {
+                docId: doc.id,
+                restoredFromRevisionId: revisionId,
+                title: doc.title,
+                updatedAt: doc.updatedAt,
+            },
+        };
+    };
+}

package/dist/tools/doc-revisions.test.js

@@ -0,0 +1,103 @@
+/**
+ * ORB-916 - doc-revisions tool tests.
+ *
+ * - list - happy + empty + nextCursor follow-up
+ * - get - happy
+ * - restore - happy + 404 bubble-up
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeListDocRevisionsHandler, makeGetDocRevisionHandler, makeRestoreDocRevisionHandler, } from './doc-revisions.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const DOC_ID = 'd0000000-0000-0000-0000-000000000001';
+const REV_ID = 'a0000000-0000-0000-0000-000000000111';
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const REVISION_LIST_ROW = {
+    id: REV_ID,
+    docId: DOC_ID,
+    title: 'Previous title',
+    editedBy: 'u1',
+    editedAt: '2026-05-17T12:00:00.000Z',
+};
+describe('orboto_list_doc_revisions', () => {
+    it('GETs /docs/:id/revisions with cursor + limit when supplied', async () => {
+        const calls = stubJSON([{ json: { items: [REVISION_LIST_ROW], nextCursor: null } }]);
+        await makeListDocRevisionsHandler(client)({
+            docId: DOC_ID,
+            limit: 50,
+            cursor: 'eyJ0IjoiZXhhbXBsZSJ9',
+        });
+        expect(calls[0].url).toContain(`/docs/${DOC_ID}/revisions`);
+        expect(calls[0].url).toContain('limit=50');
+        expect(calls[0].url).toContain('cursor=eyJ0IjoiZXhhbXBsZSJ9');
+    });
+    it('surfaces nextCursor in the structuredContent + the text body', async () => {
+        stubJSON([{ json: { items: [REVISION_LIST_ROW], nextCursor: 'NEXT' } }]);
+        const res = await makeListDocRevisionsHandler(client)({ docId: DOC_ID });
+        expect(res.content[0].text).toContain('NEXT');
+        expect(res.structuredContent).toMatchObject({ nextCursor: 'NEXT' });
+    });
+    it('reports the empty-history case explicitly', async () => {
+        stubJSON([{ json: { items: [], nextCursor: null } }]);
+        const res = await makeListDocRevisionsHandler(client)({ docId: DOC_ID });
+        expect(res.content[0].text).toContain('No revisions');
+        expect(res.structuredContent).toMatchObject({ revisions: [], nextCursor: null });
+    });
+});
+describe('orboto_get_doc_revision', () => {
+    it('GETs the full revision row including content', async () => {
+        stubJSON([{ json: { ...REVISION_LIST_ROW, content: '# Previous title\n\nOld body.' } }]);
+        const res = await makeGetDocRevisionHandler(client)({ docId: DOC_ID, revisionId: REV_ID });
+        expect(res.structuredContent).toMatchObject({
+            id: REV_ID,
+            content: '# Previous title\n\nOld body.',
+        });
+        expect(res.content[0].text).toContain('Old body.');
+    });
+});
+describe('orboto_restore_doc_revision', () => {
+    it('POSTs to /docs/:id/revisions/:rid/restore and surfaces the restored doc', async () => {
+        const calls = stubJSON([{
+                json: {
+                    id: DOC_ID, spaceId: 's1', parentDocId: null, title: 'Previous title',
+                    content: '# Previous title', slug: 'previous', visibility: 'workspace',
+                    icon: null, sortOrder: 0, updatedAt: '2026-05-17T13:30:00.000Z',
+                },
+            }]);
+        const res = await makeRestoreDocRevisionHandler(client)({ docId: DOC_ID, revisionId: REV_ID });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/docs/${DOC_ID}/revisions/${REV_ID}/restore`,
+        });
+        expect(res.structuredContent).toMatchObject({
+            docId: DOC_ID,
+            restoredFromRevisionId: REV_ID,
+        });
+    });
+    it('bubbles up a 404 from an unknown revision id', async () => {
+        stubJSON([{ ok: false, status: 404, json: { error: 'Not found' } }]);
+        await expect(makeRestoreDocRevisionHandler(client)({ docId: DOC_ID, revisionId: 'b0000000-0000-0000-0000-000000000999' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/docs-ai.js

@@ -0,0 +1,171 @@
+/**
+ * ORB-799 - docs-AI surface (ask + ingest).
+ *
+ * Three tools that mirror the wrapper's `ask-docs` / `ingest-url` /
+ * `ingest-file` subcommands. Together they're the foundation for any
+ * agent that needs to "remember this URL" / "add this PDF to our
+ * wiki" workflows.
+ *
+ * - orboto_ask_docs - RAG Q&A across wiki docs, returns answer +
+ *                         citations. Requires both `configured` and
+ *                         `embeddingsConfigured` on `/ai/status`
+ *                         (RAG retrieval needs an embedding-capable
+ *                         provider).
+ * - orboto_ingest_url - fetch + extract + create doc from a public
+ *                         URL via the Readability-fallback pipeline.
+ * - orboto_ingest_file - upload + extract + create doc from a local
+ *                         file (PDF / DOCX / Markdown / plain text).
+ *                         Uses the multipart-upload route, so the MCP
+ *                         tool receives the bytes as a base64 string
+ *                         to avoid the model needing local FS access.
+ *
+ * AI-gated note: the `ai_status` tool exists for pre-flight. We do NOT
+ * pre-check inside the handlers - the API returns the same gating
+ * error regardless and a pre-check would double the latency of every
+ * call. Models are expected to call `orboto_ai_status` once per
+ * session if they're unsure of workspace shape.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// orboto_ask_docs
+// ---------------------------------------------------------------------------
+export const askDocsToolConfig = {
+    title: 'Ask a question against the wiki (RAG)',
+    description: 'Run a natural-language question against the wiki via the workspace\'s RAG pipeline. Returns an `answer` (Markdown) + `citations` array `[{index, title, link, spaceName}]`. The model is the workspace\'s configured AI provider; retrieval requires the embedding provider too - call `orboto_ai_status` to verify both before relying on this. Restrict to a single doc space with `spaceId` when scoping a query (e.g. "only the runbooks space"). Latency is dominated by retrieval + LLM round-trip; expect 2-10s.',
+    inputSchema: z.object({
+        question: z.string().min(3),
+        spaceId: z.string().min(1).optional().describe('Limit RAG retrieval to one doc space - key (e.g. ORB-S1), name, or UUID.'),
+        limit: z.number().int().min(1).max(20).optional().describe('Max chunks to retrieve (default: 5).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeAskDocsHandler(client) {
+    return async ({ question, spaceId, limit }) => {
+        const body = { question, limit: limit ?? 5 };
+        if (spaceId)
+            body.spaceId = spaceId;
+        const res = await client.post('/ai/ask-docs', body);
+        const lines = [res.answer.trim()];
+        if (res.citations.length > 0) {
+            lines.push('', 'Sources:');
+            for (const c of res.citations) {
+                const spaceTag = c.spaceName ? `[${c.spaceName}] ` : '';
+                lines.push(`  [${c.index}] ${spaceTag}${c.title}  ${c.link}`);
+            }
+        }
+        lines.push('', `(retrieval mode: ${res.mode})`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                answer: res.answer,
+                citations: res.citations,
+                mode: res.mode,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_ingest_url
+// ---------------------------------------------------------------------------
+export const ingestUrlToolConfig = {
+    title: 'Ingest a public URL into a wiki space',
+    description: 'Fetch a public URL, run Readability extraction, store the result as a Markdown doc in `spaceId`. Optionally nest under `parentDocId` to keep the tree tidy. Sets `readabilityFallback: true` when the page didn\'t look like a recognisable article (the body falls back to full-page text - a flag the caller should surface to the operator for review).',
+    inputSchema: z.object({
+        url: z.string().url(),
+        spaceId: z.string().uuid().describe('Target doc space - find IDs via `orboto_list_doc_spaces`.'),
+        parentDocId: z.string().uuid().optional().describe('Optional parent doc to nest under.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeIngestUrlHandler(client) {
+    return async ({ url, spaceId, parentDocId }) => {
+        const body = { url };
+        if (parentDocId)
+            body.parentDocId = parentDocId;
+        const res = await client.post(`/spaces/${spaceId}/docs/ingest-url`, body);
+        const lines = [
+            `Created doc: ${res.title}`,
+            `  id: ${res.docId}`,
+            `  slug: ${res.slug}`,
+            `  fetched ${Math.round(res.fetchedBytes / 1024)} KB → ${res.markdownChars} chars of markdown`,
+        ];
+        if (res.readabilityFallback) {
+            lines.push('  ! Readability couldn\'t identify a main article - body is full-page text. Review before relying.');
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                docId: res.docId,
+                title: res.title,
+                slug: res.slug,
+                fetchedBytes: res.fetchedBytes,
+                markdownChars: res.markdownChars,
+                readabilityFallback: res.readabilityFallback === true,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_ingest_file
+// ---------------------------------------------------------------------------
+function mimetypeFor(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith('.pdf'))
+        return 'application/pdf';
+    if (lower.endsWith('.docx'))
+        return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    if (lower.endsWith('.md') || lower.endsWith('.markdown'))
+        return 'text/markdown';
+    return 'text/plain';
+}
+export const ingestFileToolConfig = {
+    title: 'Ingest a local file into a wiki space (multipart upload)',
+    description: 'Upload a file (PDF / DOCX / Markdown / plain text) into `spaceId` via multipart. The model passes the bytes as a base64 `contentBase64` field (so this works without local FS access on the agent side). Use `filename` to give the doc a meaningful title - the backend sniffs the mimetype but also uses the filename for display. Optional `parentDocId` nests under an existing doc.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid(),
+        filename: z.string().min(1).describe('Display filename, e.g. "ADR-12-secrets-rotation.pdf".'),
+        contentBase64: z.string().min(1).describe('File content, base64-encoded.'),
+        parentDocId: z.string().uuid().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeIngestFileHandler(client) {
+    return async ({ spaceId, filename, contentBase64, parentDocId }) => {
+        let arrayBuffer;
+        try {
+            // See attach.ts for the Buffer → ArrayBuffer copy rationale.
+            const buf = Buffer.from(contentBase64, 'base64');
+            arrayBuffer = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(arrayBuffer).set(buf);
+        }
+        catch {
+            throw new Error('contentBase64 is not valid base64.');
+        }
+        if (arrayBuffer.byteLength === 0) {
+            throw new Error('contentBase64 decoded to 0 bytes - refuse to upload an empty file.');
+        }
+        const form = new FormData();
+        form.append('file', new Blob([arrayBuffer], { type: mimetypeFor(filename) }), filename);
+        if (parentDocId)
+            form.append('parentDocId', parentDocId);
+        const res = await client.postMultipart(`/spaces/${spaceId}/docs/ingest-file`, form);
+        const lines = [
+            `Created doc: ${res.title}`,
+            `  id: ${res.docId}`,
+            `  slug: ${res.slug}`,
+            `  format: ${res.kind}`,
+            `  uploaded ${Math.round(res.sizeBytes / 1024)} KB → ${res.markdownChars} chars of markdown`,
+        ];
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                docId: res.docId,
+                title: res.title,
+                slug: res.slug,
+                kind: res.kind,
+                sizeBytes: res.sizeBytes,
+                markdownChars: res.markdownChars,
+            },
+        };
+    };
+}

package/dist/tools/docs-ai.test.js

@@ -0,0 +1,160 @@
+/**
+ * ORB-799 - docs-AI tools tests.
+ *
+ * `orboto_ask_docs` happy + AI-not-configured-style 400.
+ * `orboto_ingest_url` happy + readability-fallback flag.
+ * `orboto_ingest_file` happy + empty-bytes refusal.
+ *
+ * The multipart upload's wire format is verified by inspecting the
+ * FormData body the fetch mock receives - we read the form-fields
+ * back to assert filename + parent.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeAskDocsHandler, makeIngestUrlHandler, makeIngestFileHandler, } from './docs-ai.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+describe('orboto_ask_docs', () => {
+    it('POSTs question + limit + spaceId, returns answer + citations', async () => {
+        const calls = stubJSON([
+            { json: {
+                    answer: 'The retry backoff is 200ms × 2^n.',
+                    citations: [
+                        { index: 1, title: 'Queue worker', link: '/docs/queue', spaceName: 'Runbooks' },
+                    ],
+                    mode: 'rag',
+                } },
+        ]);
+        const res = await makeAskDocsHandler(client)({
+            question: 'What is the queue retry backoff?',
+            spaceId: '11111111-2222-3333-4444-555555555555',
+            limit: 3,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/ai/ask-docs',
+            body: {
+                question: 'What is the queue retry backoff?',
+                spaceId: '11111111-2222-3333-4444-555555555555',
+                limit: 3,
+            },
+        });
+        expect(res.content[0].text).toContain('200ms');
+        expect(res.structuredContent).toMatchObject({
+            answer: 'The retry backoff is 200ms × 2^n.',
+            mode: 'rag',
+        });
+    });
+    it('surfaces a 400 (AI not configured) as OrbotoApiError', async () => {
+        stubJSON([
+            { ok: false, status: 400, json: { error: 'ai_provider_not_configured' } },
+        ]);
+        await expect(makeAskDocsHandler(client)({ question: 'anything' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_ingest_url', () => {
+    it('POSTs url + parentDocId to the space ingest route', async () => {
+        const calls = stubJSON([
+            { json: {
+                    docId: 'd1', title: 'Hello', slug: 'hello',
+                    fetchedBytes: 12345, markdownChars: 678, readabilityFallback: false,
+                } },
+        ]);
+        const res = await makeIngestUrlHandler(client)({
+            url: 'https://example.com/article',
+            spaceId: '11111111-2222-3333-4444-555555555555',
+            parentDocId: '99999999-8888-7777-6666-555555555555',
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/spaces/11111111-2222-3333-4444-555555555555/docs/ingest-url',
+            body: {
+                url: 'https://example.com/article',
+                parentDocId: '99999999-8888-7777-6666-555555555555',
+            },
+        });
+        expect(res.structuredContent).toMatchObject({
+            docId: 'd1', title: 'Hello', readabilityFallback: false,
+        });
+    });
+    it('surfaces readabilityFallback=true in both text + structured', async () => {
+        stubJSON([
+            { json: {
+                    docId: 'd1', title: 'Page', slug: 'page',
+                    fetchedBytes: 200, markdownChars: 50, readabilityFallback: true,
+                } },
+        ]);
+        const res = await makeIngestUrlHandler(client)({
+            url: 'https://example.com/odd',
+            spaceId: '11111111-2222-3333-4444-555555555555',
+        });
+        expect(res.content[0].text).toMatch(/Readability/);
+        expect(res.structuredContent).toMatchObject({ readabilityFallback: true });
+    });
+});
+describe('orboto_ingest_file', () => {
+    it('POSTs multipart with filename + decoded content', async () => {
+        // Capture the multipart body via the fetch mock - FormData is
+        // opaque to JSON.parse, so we don't decode it; we only assert the
+        // route, method, and the JSON response shape.
+        const calls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            calls.push({
+                url: url.toString(),
+                method: init?.method ?? 'GET',
+                bodyType: init?.body?.constructor?.name ?? 'undefined',
+            });
+            return {
+                ok: true, status: 200, statusText: 'OK',
+                json: async () => ({
+                    docId: 'd9', title: 'note.md', slug: 'note',
+                    kind: 'markdown', sizeBytes: 11, markdownChars: 9,
+                }),
+                text: async () => '',
+            };
+        });
+        const base64 = Buffer.from('hello world').toString('base64');
+        const res = await makeIngestFileHandler(client)({
+            spaceId: '11111111-2222-3333-4444-555555555555',
+            filename: 'note.md',
+            contentBase64: base64,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/spaces/11111111-2222-3333-4444-555555555555/docs/ingest-file',
+            bodyType: 'FormData',
+        });
+        expect(res.structuredContent).toMatchObject({
+            docId: 'd9', title: 'note.md', kind: 'markdown',
+        });
+    });
+    it('refuses an empty base64 payload', async () => {
+        await expect(makeIngestFileHandler(client)({
+            spaceId: '11111111-2222-3333-4444-555555555555',
+            filename: 'empty.txt',
+            contentBase64: '',
+        })).rejects.toThrow();
+    });
+});