@moxn/kb-migrate 0.5.0 → 0.6.0

package/dist/api-error.d.ts

@@ -12,3 +12,10 @@ export declare function formatApiError(status: number, body: {
     details?: unknown;
     [key: string]: unknown;
 } | null | undefined): string;
+/**
+ * Parse a response body that should be JSON. When it isn't — typically the
+ * Vercel Auth wall's HTML page on a protected deployment — say what arrived
+ * (status, content-type) instead of surfacing a raw `JSON.parse` error like
+ * `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`.
+ */
+export declare function readJson<T = any>(response: Response): Promise<T>;

package/dist/api-error.js

@@ -17,3 +17,24 @@ export function formatApiError(status, body) {
             : '';
     return detail ? `API error ${status}: ${detail}` : `API error: ${status}`;
 }
+/**
+ * Parse a response body that should be JSON. When it isn't — typically the
+ * Vercel Auth wall's HTML page on a protected deployment — say what arrived
+ * (status, content-type) instead of surfacing a raw `JSON.parse` error like
+ * `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`.
+ */
+export async function readJson(response) {
+    try {
+        return (await response.json());
+    }
+    catch (cause) {
+        if (!(cause instanceof SyntaxError))
+            throw cause;
+        const contentType = response.headers?.get?.('content-type') ?? 'no content-type';
+        const where = response.url ? ` from ${response.url}` : '';
+        const hint = /html/i.test(contentType)
+            ? ' — an HTML page usually means the Vercel protection wall: set MOXN_VERCEL_BYPASS, with MOXN_BASE_URL on this origin'
+            : '';
+        throw new Error(`Expected JSON${where} but got a non-JSON response (HTTP ${response.status}, ${contentType})${hint}`);
+    }
+}

package/dist/client-http.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client-http.test.js

@@ -0,0 +1,89 @@
+/**
+ * kb-migrate's HTTP client against a Vercel-protected deployment (staging).
+ *
+ * `export-local` against https://staging.moxn.dev failed with
+ * `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`: kb-migrate never
+ * sent the protection-bypass header, and the auth wall's HTML page reached a
+ * bare `response.json()`. The client now attaches the SAME
+ * `vercelBypassHeaders` kb-cli uses (@moxn/auth — env-gated, scoped to
+ * MOXN_BASE_URL's origin, so signed storage URLs never see the secret), and a
+ * non-JSON body is reported as what it is.
+ */
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { MoxnClient } from './client.js';
+const STAGING = 'https://staging.moxn.dev';
+const HEADER = 'x-vercel-protection-bypass';
+function jsonResponse(body) {
+    return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+function headersOf(init) {
+    return new Headers(init?.headers).has(HEADER)
+        ? { [HEADER]: new Headers(init?.headers).get(HEADER) }
+        : {};
+}
+describe('MoxnClient — Vercel protection bypass', () => {
+    const saved = { ...process.env };
+    let fetchSpy;
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        process.env = { ...saved };
+    });
+    function client() {
+        return new MoxnClient({
+            apiUrl: STAGING,
+            apiKey: 'k',
+            basePath: '/',
+            onConflict: 'skip',
+            dryRun: false,
+        });
+    }
+    it('attaches the bypass header to requests for the MOXN_BASE_URL origin only', async () => {
+        process.env.MOXN_VERCEL_BYPASS = 'bypass-secret';
+        process.env.MOXN_BASE_URL = STAGING;
+        fetchSpy.mockImplementation(async (url) => String(url).startsWith(STAGING)
+            ? jsonResponse({ documents: [], pagination: { hasMore: false } })
+            : new Response('blob', { status: 200 }));
+        await client().listDocuments('/qa');
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-bypass-'));
+        await client().downloadFile('https://storage.example/signed/f.png', path.join(dir, 'f.png'));
+        const [apiCall, storageCall] = fetchSpy.mock.calls;
+        expect(String(apiCall[0])).toContain(`${STAGING}/api/v1/kb/documents`);
+        expect(headersOf(apiCall[1])).toEqual({ [HEADER]: 'bypass-secret' });
+        // The API key still rides alongside.
+        expect(new Headers(apiCall[1].headers).get('x-api-key')).toBe('k');
+        // A different origin (signed storage URL) never receives the secret.
+        expect(headersOf(storageCall[1])).toEqual({});
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('sends no bypass header when MOXN_VERCEL_BYPASS is unset', async () => {
+        delete process.env.MOXN_VERCEL_BYPASS;
+        process.env.MOXN_BASE_URL = STAGING;
+        fetchSpy.mockResolvedValue(jsonResponse({ documents: [], pagination: { hasMore: false } }));
+        await client().listDocuments('/qa');
+        expect(headersOf(fetchSpy.mock.calls[0][1])).toEqual({});
+    });
+    it('reports a non-JSON (auth-wall HTML) body by status + content-type, not a raw JSON.parse error', async () => {
+        fetchSpy.mockResolvedValue(new Response('<!DOCTYPE html><html>Vercel Authentication</html>', {
+            status: 200,
+            headers: { 'content-type': 'text/html; charset=utf-8' },
+        }));
+        const err = await client()
+            .listDocuments('/qa')
+            .then(() => null, (e) => e);
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).not.toMatch(/Unexpected token/);
+        expect(err.message).toMatch(/non-JSON/i);
+        expect(err.message).toContain('200');
+        expect(err.message).toContain('text/html');
+        expect(err.message).toMatch(/MOXN_VERCEL_BYPASS/);
+    });
+});

package/dist/client.d.ts

@@ -36,12 +36,59 @@ export interface ImportMarkdownResult {
     sectionIds?: string[];
     /** The branch the upsert landed on (for branch-scoped follow-ups like tags). */
     branchId?: string;
+    /**
+     * The permissions a CREATED document got. Absent on update/skip (an import
+     * never re-permissions an existing document) and from servers that predate
+     * the importer permission fields.
+     */
+    permissions?: {
+        defaultPermission: 'edit' | 'read' | 'none';
+        aiAccess: 'edit' | 'read' | 'none';
+    };
+}
+/**
+ * The warning (if any) for an import whose `--default-permission` /
+ * `--ai-access` did not take effect: an existing document is never
+ * re-permissioned by a re-import, and a server that predates the fields
+ * creates documents with its defaults without echoing `permissions`.
+ */
+export declare function importPermissionWarning(requested: {
+    defaultPermission?: string;
+    aiAccess?: string;
+}, result: Pick<ImportMarkdownResult, 'outcome' | 'permissions'>): string | undefined;
+/**
+ * One item of a `read` tool response, narrowed to the fields the export uses.
+ * `kind` is absent on an error item and on older md reads.
+ */
+export interface ReadDocumentItem {
+    type: string;
+    documentId: string;
+    error?: string;
+    kind?: string;
+    /** report: the HTML; slides: the deck-marker HTML. */
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    /** kind='file' only. */
+    file?: {
+        filename: string;
+        download: {
+            url: string;
+        };
+    };
+    /** kind='slides' only. */
+    deck?: {
+        themeCss?: string | null;
+    };
 }
 export declare class MoxnClient {
     private apiUrl;
     private apiKey;
     private defaultPermission?;
     private aiAccess?;
+    /** Every request goes through {@link moxnFetch} (bypass-header aware). */
+    private fetch;
     constructor(options: MigrationOptions | ExportOptions);
     /**
      * Migrate a single document
@@ -58,6 +105,13 @@ export declare class MoxnClient {
      * update by the server.
      */
     migrateDocument(doc: ExtractedDocument, basePath: string, onConflict: 'skip' | 'update', dryRun: boolean): Promise<MigrationResult>;
+    /**
+     * {@link importPermissionWarning} for this client's requested permissions,
+     * logged once and returned as a spreadable `{ warning }`.
+     */
+    permissionWarningFor(result: Pick<ImportMarkdownResult, 'outcome' | 'permissions'>, sourcePath: string): {
+        warning?: string;
+    };
     /**
      * List all documents, optionally filtered by path prefix.
      * Handles pagination automatically.
@@ -79,6 +133,13 @@ export declare class MoxnClient {
     getDocumentMarkdown(documentId: string, opts?: {
         forEdit?: boolean;
     }): Promise<DocumentMarkdownResponse | null>;
+    /**
+     * Read one document through the `read` tool (`/api/v1/kb/tools`) — the same
+     * serialization agents and the CLI see. The export uses it for the kinds the
+     * grammar export has no body for (report / file / slides). Returns the single
+     * read item: a document shape carrying `kind`, or an `{ error }` item.
+     */
+    readDocument(documentId: string): Promise<ReadDocumentItem>;
     /**
      * Build a `storageKey → signedDownloadUrl` map for a document's media, by
      * reusing the `get_document_content` export action (the blocks read, which

package/dist/client.js

@@ -2,13 +2,40 @@
  * API client for Moxn KB
  */
 import * as fs from 'fs/promises';
-import { formatApiError } from './api-error.js';
+import { formatApiError, readJson } from './api-error.js';
+import { moxnFetch } from './http.js';
 import { sectionsToGrammarMarkdown, buildImportFrontMatter, } from './blocks-to-grammar.js';
+/**
+ * The warning (if any) for an import whose `--default-permission` /
+ * `--ai-access` did not take effect: an existing document is never
+ * re-permissioned by a re-import, and a server that predates the fields
+ * creates documents with its defaults without echoing `permissions`.
+ */
+export function importPermissionWarning(requested, result) {
+    const asked = [
+        requested.defaultPermission &&
+            `--default-permission ${requested.defaultPermission}`,
+        requested.aiAccess && `--ai-access ${requested.aiAccess}`,
+    ].filter(Boolean);
+    if (asked.length === 0 || result.outcome === 'skipped')
+        return undefined;
+    if (result.outcome === 'updated') {
+        return `${asked.join(', ')} not applied: this updated an existing document, whose permissions are left as they were (change them in the app)`;
+    }
+    if (!result.permissions) {
+        return `${asked.join(', ')}: the server did not apply them (it predates importer permissions) — the document was created with the server defaults`;
+    }
+    return undefined;
+}
 export class MoxnClient {
     apiUrl;
     apiKey;
     defaultPermission;
     aiAccess;
+    /** Every request goes through {@link moxnFetch} (bypass-header aware). */
+    fetch(url, init = {}) {
+        return moxnFetch(url, init);
+    }
     constructor(options) {
         this.apiUrl = options.apiUrl.replace(/\/$/, '');
         this.apiKey = options.apiKey;
@@ -72,6 +99,7 @@ export class MoxnClient {
                 sectionIds: result.sectionIds,
                 references: doc.references,
                 sourcePageId: doc.metadata?.notionPageId,
+                ...this.permissionWarningFor(result, doc.sourcePath),
                 duration: Date.now() - startTime,
             };
         }
@@ -85,6 +113,17 @@ export class MoxnClient {
             };
         }
     }
+    /**
+     * {@link importPermissionWarning} for this client's requested permissions,
+     * logged once and returned as a spreadable `{ warning }`.
+     */
+    permissionWarningFor(result, sourcePath) {
+        const warning = importPermissionWarning({ defaultPermission: this.defaultPermission, aiAccess: this.aiAccess }, result);
+        if (!warning)
+            return {};
+        console.warn(`  ⚠ ${warning}: ${sourcePath}`);
+        return { warning };
+    }
     // ──────────────────────────────────────────────
     // Export methods
     // ──────────────────────────────────────────────
@@ -112,14 +151,14 @@ export class MoxnClient {
                 params.set('modifiedAfter', dateFilter.modifiedAfter);
             if (dateFilter?.modifiedBefore)
                 params.set('modifiedBefore', dateFilter.modifiedBefore);
-            const response = await fetch(`${this.apiUrl}/api/v1/kb/documents?${params}`, {
+            const response = await this.fetch(`${this.apiUrl}/api/v1/kb/documents?${params}`, {
                 headers: { 'x-api-key': this.apiKey },
             });
             if (!response.ok) {
                 const error = await response.text();
                 throw new Error(`Failed to list documents: ${response.status} ${error}`);
             }
-            const data = await response.json();
+            const data = await readJson(response);
             allDocs.push(...data.documents);
             if (!data.pagination.hasMore)
                 break;
@@ -131,14 +170,14 @@ export class MoxnClient {
      * Get full document detail with sections and content.
      */
     async getDocument(documentId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}`, {
             headers: { 'x-api-key': this.apiKey },
         });
         if (!response.ok) {
             const error = await response.text();
             throw new Error(`Failed to get document ${documentId}: ${response.status} ${error}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Get a document's GRAMMAR markdown (front-matter + body + `:::image/:::csv/
@@ -150,7 +189,7 @@ export class MoxnClient {
      * address sections stably.
      */
     async getDocumentMarkdown(documentId, opts) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/export`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/export`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -166,9 +205,38 @@ export class MoxnClient {
             const body = await response.text();
             throw new Error(`Failed to get document markdown ${documentId}: ${response.status} ${body}`);
         }
-        const data = await response.json();
+        const data = await readJson(response);
         return (data.result?.document ?? null);
     }
+    /**
+     * Read one document through the `read` tool (`/api/v1/kb/tools`) — the same
+     * serialization agents and the CLI see. The export uses it for the kinds the
+     * grammar export has no body for (report / file / slides). Returns the single
+     * read item: a document shape carrying `kind`, or an `{ error }` item.
+     */
+    async readDocument(documentId) {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/tools`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                tool: 'read',
+                params: { items: [{ type: 'document', documentId }] },
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(formatApiError(response.status, body));
+        }
+        const data = await readJson(response);
+        const item = data.result?.items?.[0];
+        if (!item) {
+            throw new Error(`read returned no item for document ${documentId}`);
+        }
+        return item;
+    }
     /**
      * Build a `storageKey → signedDownloadUrl` map for a document's media, by
      * reusing the `get_document_content` export action (the blocks read, which
@@ -178,7 +246,7 @@ export class MoxnClient {
      * Returns an empty map when the document has no resolvable media.
      */
     async getDocumentMediaUrls(documentId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/export`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/export`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -190,7 +258,7 @@ export class MoxnClient {
             const body = await response.text();
             throw new Error(`Failed to get document content ${documentId}: ${response.status} ${body}`);
         }
-        const data = await response.json();
+        const data = await readJson(response);
         const doc = data.result?.document;
         const map = new Map();
         if (!doc)
@@ -215,7 +283,7 @@ export class MoxnClient {
      *   onConflict 'update' → replace_document (full-set PUT)
      */
     async importMarkdown(input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/import`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/import`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -226,20 +294,25 @@ export class MoxnClient {
                 markdown: input.markdown,
                 path: input.path,
                 onConflict: input.onConflict,
+                // Applied by the server to a document this import CREATES.
+                ...(this.defaultPermission
+                    ? { defaultPermission: this.defaultPermission }
+                    : {}),
+                ...(this.aiAccess ? { aiAccess: this.aiAccess } : {}),
             }),
         });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
             throw new Error(formatApiError(response.status, body));
         }
-        const data = await response.json();
+        const data = await readJson(response);
         return data.result;
     }
     /**
      * Download a file from a URL to a local path.
      */
     async downloadFile(url, destPath) {
-        const response = await fetch(url);
+        const response = await this.fetch(url);
         if (!response.ok) {
             throw new Error(`Failed to download ${url}: ${response.status}`);
         }
@@ -338,7 +411,7 @@ export class MoxnClient {
                 block.type === 'url' &&
                 block.url) {
                 try {
-                    const response = await fetch(block.url);
+                    const response = await this.fetch(block.url);
                     if (!response.ok)
                         throw new Error(`HTTP ${response.status}`);
                     const data = Buffer.from(await response.arrayBuffer());
@@ -364,7 +437,7 @@ export class MoxnClient {
         // 1. Get presigned upload URL
         const { key, uploadUrl } = await this.getUploadUrl(mimeType, filename);
         // 2. PUT file to presigned URL
-        const response = await fetch(uploadUrl, {
+        const response = await this.fetch(uploadUrl, {
             method: 'PUT',
             headers: { 'Content-Type': mimeType },
             body: new Uint8Array(data),
@@ -375,7 +448,7 @@ export class MoxnClient {
         return { key };
     }
     async getUploadUrl(type, filename) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/upload`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/upload`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -387,7 +460,7 @@ export class MoxnClient {
             const body = await response.text();
             throw new Error(`Upload URL request failed: ${response.status} ${body}`);
         }
-        const data = await response.json();
+        const data = await readJson(response);
         return { key: data.key, uploadUrl: data.uploadUrl };
     }
     // ──────────────────────────────────────────────
@@ -397,7 +470,7 @@ export class MoxnClient {
      * Create a KB database.
      */
     async createDatabase(input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -409,13 +482,13 @@ export class MoxnClient {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to create database: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Add a column to a KB database.
      */
     async addDatabaseColumn(databaseId, input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/columns`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/columns`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -427,13 +500,13 @@ export class MoxnClient {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to add column: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Add a document to a KB database.
      */
     async addDocumentToDatabase(databaseId, documentId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/documents`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/documents`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -453,7 +526,7 @@ export class MoxnClient {
      * Create a tag (with automatic ancestor creation).
      */
     async createTag(input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/tags`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/tags`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -473,13 +546,13 @@ export class MoxnClient {
             }
             throw new Error(body.error || `Failed to create tag: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Assign a tag to a document.
      */
     async assignTag(documentId, tagId, branchId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}/tags`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}/tags`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -497,7 +570,7 @@ export class MoxnClient {
      * Returns { created, skipped, errors }.
      */
     async createReferences(documentId, references) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}/references`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}/references`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -509,51 +582,51 @@ export class MoxnClient {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to create references: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * List all KB databases for the tenant.
      */
     async listDatabases() {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases`, {
             headers: { 'x-api-key': this.apiKey },
         });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to list databases: ${response.status}`);
         }
-        const data = await response.json();
+        const data = await readJson(response);
         return data.databases;
     }
     /**
      * Get fully resolved database with columns, options, and document property values.
      */
     async resolveDatabase(databaseId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/resolve`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/resolve`, {
             headers: { 'x-api-key': this.apiKey },
         });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to resolve database: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Get Notion database mapping for a KB database.
      */
     async getNotionDatabaseMapping(kbDatabaseId) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases/by-kb-database/${kbDatabaseId}`, { headers: { 'x-api-key': this.apiKey } });
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases/by-kb-database/${kbDatabaseId}`, { headers: { 'x-api-key': this.apiKey } });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to get database mapping: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Create or upsert a Notion database mapping.
      */
     async createNotionDatabaseMapping(input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -565,13 +638,13 @@ export class MoxnClient {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to create database mapping: ${response.status}`);
         }
-        return response.json();
+        return readJson(response);
     }
     /**
      * Set a scalar property value on a document in a database.
      */
     async setPropertyValue(databaseId, documentId, columnName, value) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/properties`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/databases/${databaseId}/properties`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -591,7 +664,7 @@ export class MoxnClient {
      * Create or upsert a Notion page → KB document mapping.
      */
     async createNotionPageMapping(input) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/notion-mappings`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -609,14 +682,14 @@ export class MoxnClient {
      * Returns a Map of notionDatabaseId → kbDatabaseId.
      */
     async getAllDatabaseMappings() {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases`, {
+        const response = await this.fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases`, {
             headers: { 'x-api-key': this.apiKey },
         });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
             throw new Error(body.error || `Failed to get database mappings: ${response.status}`);
         }
-        const data = await response.json();
+        const data = await readJson(response);
         const map = new Map();
         for (const mapping of data.mappings) {
             map.set(mapping.notionDatabaseId, mapping.kbDatabaseId);