@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/client.js

@@ -11,11 +11,34 @@
  * (`req.query.cursor`, functions/src/publicApi.ts in Frihet-ERP). `after`
  * is never sent on the wire. See src/__tests__/pagination-cursor-param.test.ts.
  */
+import { sanitizeServerRemediation } from "./redaction.js";
 import { logApiCall, logRetry } from "./logger.js";
 const BASE_URL = "https://api.frihet.io/v1";
+const OAUTH_CLOUD_FUNCTION_BASE_URL = "https://europe-west1-gen-lang-client-0335716041.cloudfunctions.net/publicApi/api/v1";
+const OAUTH_SERVICE_TRUSTED_BASE_URLS = new Set([
+    BASE_URL,
+    OAUTH_CLOUD_FUNCTION_BASE_URL,
+]);
 const MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY_MS = 1000;
 const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * Hard size caps for document responses. Enforced TWICE: precheck on
+ * `Content-Length` (so an honest server doesn't waste bandwidth) and after
+ * streaming (so a missing/lying `Content-Length` still can't trigger an
+ * unbounded allocation).
+ *
+ *  - PDF: 25 MiB — generous for any ERP-issued invoice PDF, including
+ *    embedded logos, Facturae XML attachments, and stamp signatures.
+ *  - XML:  5 MiB — UBL / Facturae / PEPPOL documents stay well under 1 MiB
+ *    in practice; 5 MiB absorbs any historical / annex-laden outlier.
+ *
+ * Anything larger is rejected with `413 payload_too_large` BEFORE we allocate
+ * — the user sees a clean error, the worker doesn't OOM.
+ */
+export const MAX_PDF_BYTES = 25 * 1024 * 1024;
+export const MAX_XML_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_BYTES = 64 * 1024;
 /**
  * HTTP methods for which the backend treats the request as a mutation and
  * therefore accepts (and for some endpoints REQUIRES) an `Idempotency-Key`
@@ -55,12 +78,11 @@ const SOURCE_USER_AGENT = "frihet-mcp-server";
 /**
  * Fresh idempotency key, always a syntactically valid UUID v4.
  *
- * `crypto.randomUUID` is a global on the Cloudflare Workers runtime and on
- * Node >= 19. On Node 18 — our declared `engines` floor — `globalThis.crypto`
- * is behind `--experimental-global-webcrypto`, so the fallback is a REAL code
- * path there, not a theoretical one. It therefore has to produce a UUID and
- * not an ad-hoc string: the backend documents "UUID v4 recommended", and
- * src/__tests__/idempotency-key-contract.test.ts asserts the shape.
+ * `crypto.randomUUID` is global on Cloudflare Workers and the supported Node
+ * runtime. The fallback remains defense in depth for constrained embedders and
+ * tests that intentionally remove the global; it must still produce a UUID,
+ * not an ad-hoc string. The backend recommends UUID v4 and the contract test
+ * asserts the shape.
  */
 function newIdempotencyKey() {
     const c = globalThis.crypto;
@@ -86,27 +108,159 @@ function normalizeIdempotencyKey(key) {
     const trimmed = key?.trim();
     return trimmed ? trimmed : undefined;
 }
+function normalizedContentType(contentType) {
+    return contentType.split(";", 1)[0].trim().toLowerCase();
+}
+function isXmlContentType(contentType) {
+    const normalized = normalizedContentType(contentType);
+    return normalized === "application/xml" || normalized === "text/xml" || normalized.endsWith("+xml");
+}
+function hasPdfSignature(bytes) {
+    return bytes.byteLength >= 5 &&
+        bytes[0] === 0x25 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x44 &&
+        bytes[3] === 0x46 &&
+        bytes[4] === 0x2d;
+}
+function attachmentFilename(contentDisposition) {
+    if (!contentDisposition)
+        return undefined;
+    const encoded = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+    const quoted = contentDisposition.match(/filename="([^"]+)"/i)?.[1];
+    const plain = contentDisposition.match(/filename=([^;]+)/i)?.[1];
+    const candidate = (encoded ?? quoted ?? plain)?.trim();
+    if (!candidate)
+        return undefined;
+    try {
+        return decodeURIComponent(candidate).split(/[\\/]/).pop();
+    }
+    catch {
+        return candidate.split(/[\\/]/).pop();
+    }
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function decodeUtf8(bytes, label) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+    }
+    catch {
+        throw new FrihetApiError(200, "invalid_response", `${label} is not valid UTF-8`);
+    }
+}
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Encode bytes without relying on Node's Buffer in browser/Worker runtimes. */
+function encodeBase64(bytes) {
+    let encoded = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const hasSecond = index + 1 < bytes.length;
+        const hasThird = index + 2 < bytes.length;
+        const second = hasSecond ? bytes[index + 1] : 0;
+        const third = hasThird ? bytes[index + 2] : 0;
+        const chunk = (first << 16) | (second << 8) | third;
+        encoded += BASE64_ALPHABET[(chunk >>> 18) & 0x3f];
+        encoded += BASE64_ALPHABET[(chunk >>> 12) & 0x3f];
+        encoded += hasSecond ? BASE64_ALPHABET[(chunk >>> 6) & 0x3f] : "=";
+        encoded += hasThird ? BASE64_ALPHABET[chunk & 0x3f] : "=";
+    }
+    return encoded;
+}
 export class FrihetApiError extends Error {
     statusCode;
     errorCode;
-    constructor(statusCode, errorCode, message) {
-        super(message ?? errorCode);
+    detail;
+    constructor(statusCode, errorCode, message, detail) {
+        super(statusCode === 403
+            ? sanitizeServerRemediation(message, errorCode) ?? errorCode
+            : message ?? errorCode);
         this.statusCode = statusCode;
         this.errorCode = errorCode;
+        this.detail = detail;
         this.name = "FrihetApiError";
     }
 }
+/**
+ * Enforce the webhook secret's one-time write echo and normalize the one
+ * Firestore Timestamp that the ERP webhook route currently emits without its
+ * usual serializer. Invalid timestamp objects are preserved so the strict MCP
+ * output schema fails closed instead of fabricating a value.
+ */
+function normalizeWebhookRecord(webhook, allowedSecret) {
+    const normalized = { ...webhook };
+    if (typeof allowedSecret !== "string" ||
+        typeof normalized.secret !== "string" ||
+        normalized.secret !== allowedSecret) {
+        delete normalized.secret;
+    }
+    const lastTriggeredAt = normalized.lastTriggeredAt;
+    if (lastTriggeredAt !== null &&
+        typeof lastTriggeredAt === "object" &&
+        !Array.isArray(lastTriggeredAt)) {
+        const timestamp = lastTriggeredAt;
+        const seconds = timestamp._seconds;
+        const nanoseconds = timestamp._nanoseconds;
+        if (typeof seconds === "number" &&
+            Number.isInteger(seconds) &&
+            Number.isFinite(seconds) &&
+            typeof nanoseconds === "number" &&
+            Number.isInteger(nanoseconds) &&
+            nanoseconds >= 0 &&
+            nanoseconds < 1_000_000_000) {
+            const date = new Date(seconds * 1000 + Math.floor(nanoseconds / 1_000_000));
+            if (Number.isFinite(date.getTime())) {
+                normalized.lastTriggeredAt = date.toISOString();
+            }
+        }
+    }
+    return normalized;
+}
+function normalizeApiError(value, statusCode, statusText) {
+    const fallbackError = `http_${statusCode}`;
+    const record = typeof value === "object" && value !== null
+        ? value
+        : undefined;
+    const error = typeof record?.error === "string" && record.error.trim()
+        ? record.error
+        : fallbackError;
+    const message = typeof record?.message === "string"
+        ? record.message
+        : (error !== fallbackError ? error : statusText || fallbackError);
+    return {
+        error,
+        message,
+        ...(typeof record?.detail === "string" ? { detail: record.detail } : {}),
+    };
+}
 export class FrihetClient {
     apiKey;
     baseUrl;
     timeoutMs;
+    oauthServiceSecret;
     constructor(apiKey, baseUrl, options) {
         if (!apiKey) {
             throw new Error("FRIHET_API_KEY is required. Set it as an environment variable or pass it to the constructor.");
         }
+        const resolvedBaseUrl = baseUrl ?? BASE_URL;
         this.apiKey = apiKey;
-        this.baseUrl = baseUrl ?? BASE_URL;
+        this.baseUrl = resolvedBaseUrl;
         this.timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
+        if (options?.oauthServiceSecret !== undefined) {
+            if (new TextEncoder().encode(options.oauthServiceSecret).byteLength < 32
+                || /[\r\n\0]/u.test(options.oauthServiceSecret)) {
+                throw new Error("OAuth API-key service authentication is not configured");
+            }
+            // A dashboard/API-key caller may still use a custom API base. The
+            // internal OAuth second factor may not: pin its authority at the sink so
+            // a future caller cannot exfiltrate both credentials by changing only
+            // constructor input while leaving the approved fetch fingerprint intact.
+            if (!OAUTH_SERVICE_TRUSTED_BASE_URLS.has(resolvedBaseUrl)) {
+                throw new Error("OAuth API-key service authority is not trusted");
+            }
+            this.oauthServiceSecret = options.oauthServiceSecret;
+        }
     }
     // ------------------------------------------------------------------ HTTP
     // ------------------------------------------------------------------
@@ -133,6 +287,9 @@ export class FrihetClient {
             "X-Frihet-Source": SOURCE_MARKER,
             "User-Agent": SOURCE_USER_AGENT,
         };
+        if (this.oauthServiceSecret) {
+            headers["x-frihet-oauth-key"] = this.oauthServiceSecret;
+        }
         if (resolvedIdempotencyKey) {
             headers["Idempotency-Key"] = resolvedIdempotencyKey;
         }
@@ -146,23 +303,23 @@ export class FrihetClient {
                 headers,
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
+                redirect: "error",
             });
         }
         catch (error) {
+            clearTimeout(timeoutId);
             const durationMs = Math.round(Date.now() - startTime);
             if (error instanceof Error && error.name === "AbortError") {
                 logApiCall(method, path, 408, durationMs);
                 throw new FrihetApiError(408, "request_timeout", `Request timed out after ${this.timeoutMs / 1000} seconds`);
             }
             logApiCall(method, path, 0, durationMs);
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
+            throw new FrihetApiError(503, "network_error", "The network request failed before Frihet could confirm its outcome.");
         }
         const durationMs = Math.round(Date.now() - startTime);
         // Rate limit handling
         if (response.status === 429) {
+            clearTimeout(timeoutId);
             logApiCall(method, path, 429, durationMs);
             if (retryCount >= MAX_RETRIES) {
                 throw new FrihetApiError(429, "rate_limit_exceeded", "Rate limit exceeded after multiple retries. Please try again later.");
@@ -180,28 +337,207 @@ export class FrihetClient {
             logApiCall(method, path, response.status, durationMs);
             let errorBody;
             try {
-                errorBody = (await response.json());
+                errorBody = normalizeApiError(await response.json(), response.status, response.statusText);
             }
             catch {
-                errorBody = {
-                    error: `http_${response.status}`,
-                    message: response.statusText,
-                };
+                errorBody = normalizeApiError(undefined, response.status, response.statusText);
             }
-            throw new FrihetApiError(response.status, errorBody.error, errorBody.message ?? errorBody.error);
+            clearTimeout(timeoutId);
+            throw new FrihetApiError(response.status, errorBody.error, errorBody.message ?? errorBody.error, typeof errorBody.detail === "string" ? errorBody.detail : undefined);
         }
         logApiCall(method, path, response.status, durationMs);
         // 204 No Content (e.g. DELETE)
         if (response.status === 204) {
+            clearTimeout(timeoutId);
             return undefined;
         }
-        const data = await response.json();
+        let data;
+        try {
+            // Keep the request AbortSignal live through body consumption. A server
+            // can send 2xx headers after committing a write and then stall or truncate
+            // the JSON body; clearing the timer at headers would let this hang forever
+            // and make a committed mutation look safely retryable.
+            data = await response.json();
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            const timedOut = error instanceof Error && error.name === "AbortError";
+            throw new FrihetApiError(timedOut ? 408 : response.status, timedOut ? "response_timeout" : "invalid_response_after_success", timedOut
+                ? `Response body timed out after ${this.timeoutMs / 1000} seconds`
+                : "Frihet returned an unreadable success response after processing the request.");
+        }
+        clearTimeout(timeoutId);
         // Basic response validation
         if (data === null || data === undefined) {
-            throw new FrihetApiError(response.status, 'invalid_response', 'API returned empty response');
+            throw new FrihetApiError(response.status, "invalid_response_after_success", "Frihet returned an empty success response after processing the request.");
         }
         return data;
     }
+    /** Fetch a raw response. The caller owns timeout and body consumption. */
+    async fetchRaw(method, path, body, query, idempotencyKey, signal) {
+        const resolvedIdempotencyKey = normalizeIdempotencyKey(idempotencyKey) ??
+            (MUTATING_METHODS.has(method) ? newIdempotencyKey() : undefined);
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = {
+            "X-API-Key": this.apiKey,
+            "Content-Type": "application/json",
+            // CRITICAL: do NOT set `Accept: application/json` here. The PDF / XML
+            // endpoints must be allowed to return their native content type;
+            // forcing `Accept: application/json` would make the server negotiate
+            // an error envelope instead of the document bytes.
+            Accept: "*/*",
+            "X-Frihet-Source": SOURCE_MARKER,
+            "User-Agent": SOURCE_USER_AGENT,
+        };
+        if (this.oauthServiceSecret) {
+            headers["x-frihet-oauth-key"] = this.oauthServiceSecret;
+        }
+        if (resolvedIdempotencyKey) {
+            headers["Idempotency-Key"] = resolvedIdempotencyKey;
+        }
+        return fetch(url.toString(), {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal,
+            redirect: "error",
+        });
+    }
+    /** Consume one response body without ever retaining more than `maxBytes`. */
+    async readBoundedBody(response, maxBytes, controller) {
+        const declaredLengthRaw = response.headers.get("content-length")?.trim();
+        const declaredLength = declaredLengthRaw && /^\d+$/.test(declaredLengthRaw)
+            ? Number(declaredLengthRaw)
+            : Number.NaN;
+        if (Number.isSafeInteger(declaredLength) && declaredLength > maxBytes) {
+            controller.abort();
+            try {
+                await response.body?.cancel();
+            }
+            catch { /* best effort */ }
+            throw new FrihetApiError(413, "payload_too_large", `Document response exceeds ${maxBytes} bytes (Content-Length: ${declaredLength})`);
+        }
+        if (!response.body) {
+            throw new FrihetApiError(response.status, "invalid_response", "Response body is null");
+        }
+        const reader = response.body.getReader();
+        const chunks = [];
+        let totalBytes = 0;
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                if (!value)
+                    continue;
+                totalBytes += value.byteLength;
+                if (totalBytes > maxBytes) {
+                    controller.abort();
+                    try {
+                        await reader.cancel("document response exceeded size limit");
+                    }
+                    catch { /* best effort */ }
+                    throw new FrihetApiError(413, "payload_too_large", `Document response exceeds ${maxBytes} bytes during streaming`);
+                }
+                chunks.push(value);
+            }
+        }
+        catch (error) {
+            if (error instanceof FrihetApiError || isAbortError(error))
+                throw error;
+            try {
+                await reader.cancel("document stream failed");
+            }
+            catch { /* best effort */ }
+            controller.abort();
+            throw new FrihetApiError(response.status, "stream_failed", `Failed while reading document response: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const flat = new Uint8Array(totalBytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            flat.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return flat;
+    }
+    /**
+     * Bounded document fetch — ONE call, ONE Response, dispatch on Content-Type.
+     *
+     * Success and error bodies use the same bounded reader. The abort timer stays
+     * active until the body is complete, and a normal success performs one GET.
+     * A 429 may retry, matching the generic JSON client path.
+     */
+    async requestDocument(method, path, body, query, idempotencyKey, maxBytesForContentType, retryCount = 0) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const startedAt = Date.now();
+        try {
+            const response = await this.fetchRaw(method, path, body, query, idempotencyKey, controller.signal);
+            const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+            const maxBytes = response.ok ? maxBytesForContentType(contentType) : MAX_ERROR_BYTES;
+            const bytes = await this.readBoundedBody(response, maxBytes, controller);
+            const durationMs = Math.round(Date.now() - startedAt);
+            if (response.status === 429) {
+                logApiCall(method, path, 429, durationMs);
+                if (retryCount >= MAX_RETRIES) {
+                    throw new FrihetApiError(429, "rate_limit_exceeded", "Rate limit exceeded after multiple retries. Please try again later.");
+                }
+                const retryAfter = response.headers.get("Retry-After");
+                const parsedRetryAfter = retryAfter ? Number.parseInt(retryAfter, 10) : Number.NaN;
+                const delayMs = Number.isFinite(parsedRetryAfter)
+                    ? parsedRetryAfter * 1000
+                    : DEFAULT_RETRY_DELAY_MS * Math.pow(2, retryCount);
+                logRetry(method, path, retryCount, delayMs);
+                clearTimeout(timeoutId);
+                await this.sleep(delayMs);
+                return this.requestDocument(method, path, body, query, idempotencyKey, maxBytesForContentType, retryCount + 1);
+            }
+            if (!response.ok) {
+                logApiCall(method, path, response.status, durationMs);
+                let errorBody = normalizeApiError(undefined, response.status, response.statusText);
+                try {
+                    errorBody = normalizeApiError(JSON.parse(decodeUtf8(bytes, "API error response")), response.status, response.statusText);
+                }
+                catch (error) {
+                    if (error instanceof FrihetApiError && error.errorCode !== "invalid_response")
+                        throw error;
+                }
+                throw new FrihetApiError(response.status, errorBody.error, errorBody.message ?? errorBody.error, typeof errorBody.detail === "string" ? errorBody.detail : undefined);
+            }
+            logApiCall(method, path, response.status, durationMs);
+            const filename = attachmentFilename(response.headers.get("content-disposition"));
+            return {
+                contentType,
+                bytes,
+                sizeBytes: bytes.byteLength,
+                ...(filename ? { filename } : {}),
+            };
+        }
+        catch (error) {
+            if (isAbortError(error)) {
+                const durationMs = Math.round(Date.now() - startedAt);
+                logApiCall(method, path, 408, durationMs);
+                throw new FrihetApiError(408, "request_timeout", `Request timed out after ${this.timeoutMs / 1000} seconds`);
+            }
+            if (error instanceof FrihetApiError)
+                throw error;
+            const durationMs = Math.round(Date.now() - startedAt);
+            logApiCall(method, path, 0, durationMs);
+            throw new FrihetApiError(503, "network_error", "The network request failed before Frihet could confirm its outcome.");
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
@@ -220,10 +556,15 @@ export class FrihetClient {
      * output schema (id/clientName/items/success all read as `undefined`). This
      * unwraps to `body.data`. Every create/update/action mutation routes through
      * here for exactly this reason; single-object reads (`getInvoice`/…) have since
-     * #64. `deleteX` methods deliberately keep `request` (they return `void` — the
-     * tool discards the body and synthesizes `{ success, id }`, so there is nothing
-     * to unwrap). Only unwraps a non-array-object `data` (see guard below), so an
+     * #64. Most `deleteX` methods keep `request` (they return `void` — the tool
+     * discards the body and synthesizes `{ success, id }`, so there is nothing to
+     * unwrap). `deleteInvoice`/`deleteQuote` are the EXCEPTION and route through
+     * here: their backend answers 204 for a real delete but 200 + `{ data, meta }`
+     * when it soft-CANCELS a non-draft document instead (see those methods).
+     * Only unwraps a non-array-object `data` (see guard below), so an
      * array-`data` list envelope and any non-enveloped body pass through unchanged.
+     * A 204 yields `undefined` from `request`, which falls through untouched — that
+     * `undefined` is what tells the delete tools "destroyed, not cancelled".
      *
      * Only unwraps when the body is an object carrying a `data` property that is
      * itself a (non-array) object — i.e. a genuine single-object envelope. It is
@@ -282,8 +623,22 @@ export class FrihetClient {
     async updateInvoice(id, data) {
         return this.requestUnwrapped("PATCH", `/invoices/${encodeURIComponent(id)}`, data);
     }
+    /**
+     * DELETE /invoices/{id} — NOT an unconditional destroy.
+     *
+     * The backend refuses to destroy a non-draft invoice (VeriFactu hash-chain
+     * integrity) and soft-CANCELS it instead, and it distinguishes the two
+     * outcomes on the wire (`publicApi.ts` DELETE branch):
+     *   - 204 No Content            → the draft row was really removed
+     *   - 200 + `{ data: { id, status: 'cancelled', previousStatus,
+     *     cancelledVia }, meta }` → the document still exists, now cancelled
+     *
+     * This used to be typed `Promise<void>` and the body was thrown away, so the
+     * tool reported "deleted successfully" for a document that was still there.
+     * Resolves to the unwrapped soft-cancel payload on 200, `undefined` on 204.
+     */
     async deleteInvoice(id) {
-        return this.request("DELETE", `/invoices/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("DELETE", `/invoices/${encodeURIComponent(id)}`);
     }
     async searchInvoices(query, params) {
         return this.requestPaginated("GET", "/invoices", undefined, {
@@ -356,7 +711,9 @@ export class FrihetClient {
             cursor: params?.after,
             fields: params?.fields,
             q: params?.q,
-            isActive: params?.isActive !== undefined ? (params.isActive ? 1 : 0) : undefined,
+            // Public API accepts the literal strings "true"/"false". Numeric 1/0
+            // makes `isActive=true` evaluate as false in the backend parser.
+            isActive: params?.isActive !== undefined ? String(params.isActive) : undefined,
         });
     }
     async getProduct(id) {
@@ -395,8 +752,14 @@ export class FrihetClient {
     async updateQuote(id, data) {
         return this.requestUnwrapped("PATCH", `/quotes/${encodeURIComponent(id)}`, data);
     }
+    /**
+     * DELETE /quotes/{id} — same two-outcome contract as {@link deleteInvoice}:
+     * the backend soft-CANCELS a non-draft quote (200 + body), destroys only a
+     * clean draft with no delivery/response/attachment/conversion evidence (204),
+     * and refuses a protected draft with 409.
+     */
     async deleteQuote(id) {
-        return this.request("DELETE", `/quotes/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("DELETE", `/quotes/${encodeURIComponent(id)}`);
     }
     // ---------------------------------------------------------------- Vendors
     // ----------------------------------------------------------------
@@ -424,21 +787,72 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Invoice Actions
     // ----------------------------------------------------------------
     async sendInvoice(id, to) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(id)}/send`, to ? { to } : undefined);
+        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(id)}/send`, to ? { recipientEmail: to } : undefined);
     }
     async markInvoicePaid(id, paidDate) {
         return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(id)}/paid`, paidDate ? { paidDate } : undefined);
     }
     async getInvoicePdf(id) {
-        // get_invoice_pdf's outputSchema (pdfResultOutput) expects the flat
-        // { id, url?, contentType? } item, same as every other single-object read.
-        return this.requestUnwrapped("GET", `/invoices/${encodeURIComponent(id)}/pdf`);
+        // One fetch, one Response: validate MIME and signature only after the
+        // bounded stream completes. The ERP endpoint has always returned bytes;
+        // there is no pre-signed-URL JSON success contract to emulate.
+        const url = `/invoices/${encodeURIComponent(id)}/pdf`;
+        const doc = await this.requestDocument("GET", url, undefined, undefined, undefined, (contentType) => normalizedContentType(contentType) === "application/pdf"
+            ? MAX_PDF_BYTES
+            : MAX_ERROR_BYTES);
+        if (normalizedContentType(doc.contentType) !== "application/pdf") {
+            throw new FrihetApiError(200, "invalid_response", `Invoice PDF endpoint returned unexpected Content-Type: ${doc.contentType}`);
+        }
+        if (!hasPdfSignature(doc.bytes)) {
+            throw new FrihetApiError(200, "invalid_response", "Invoice PDF response is malformed");
+        }
+        return {
+            id,
+            contentType: doc.contentType,
+            sizeBytes: doc.sizeBytes,
+            base64: encodeBase64(doc.bytes),
+            ...(doc.filename ? { filename: doc.filename } : {}),
+        };
     }
     async getInvoiceEInvoice(invoiceId) {
-        // get_invoice_einvoice's outputSchema expects the flat { xml, filename, format }
-        // item. requestUnwrapped is a no-op if the body isn't an object envelope
-        // (e.g. a bare XML string), so this is safe either way.
-        return this.requestUnwrapped("GET", `/invoices/${encodeURIComponent(invoiceId)}/xml`);
+        // Stored e-invoices are either XML or Factur-X PDF. Select the size cap
+        // from the actual MIME before reading and preserve the request identity.
+        const url = `/invoices/${encodeURIComponent(invoiceId)}/xml`;
+        const doc = await this.requestDocument("GET", url, undefined, undefined, undefined, (contentType) => {
+            const normalized = normalizedContentType(contentType);
+            if (normalized === "application/pdf")
+                return MAX_PDF_BYTES;
+            if (isXmlContentType(contentType))
+                return MAX_XML_BYTES;
+            return MAX_ERROR_BYTES;
+        });
+        const normalized = normalizedContentType(doc.contentType);
+        if (normalized === "application/pdf") {
+            if (!hasPdfSignature(doc.bytes)) {
+                throw new FrihetApiError(200, "invalid_response", "Factur-X PDF response is malformed");
+            }
+            return {
+                id: invoiceId,
+                contentType: doc.contentType,
+                sizeBytes: doc.sizeBytes,
+                base64: encodeBase64(doc.bytes),
+                ...(doc.filename ? { filename: doc.filename } : {}),
+            };
+        }
+        if (!isXmlContentType(doc.contentType)) {
+            throw new FrihetApiError(200, "invalid_response", `E-invoice endpoint returned unexpected Content-Type: ${doc.contentType}`);
+        }
+        const xmlText = decodeUtf8(doc.bytes, "E-invoice XML response");
+        if (!xmlText.trimStart().startsWith("<")) {
+            throw new FrihetApiError(200, "invalid_response", "E-invoice XML response is malformed");
+        }
+        return {
+            id: invoiceId,
+            contentType: doc.contentType,
+            xml: xmlText,
+            sizeBytes: doc.sizeBytes,
+            ...(doc.filename ? { filename: doc.filename } : {}),
+        };
     }
     /**
      * `POST /v1/invoices/:id/credit-note` — creates a rectificativa DRAFT.
@@ -461,24 +875,38 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Quote Actions
     // ----------------------------------------------------------------
     async sendQuote(id, to) {
-        return this.requestUnwrapped("POST", `/quotes/${encodeURIComponent(id)}/send`, to ? { to } : undefined);
+        return this.requestUnwrapped("POST", `/quotes/${encodeURIComponent(id)}/send`, to ? { recipientEmail: to } : undefined);
     }
     // ---------------------------------------------------------------- Webhooks
     // ----------------------------------------------------------------
-    async listWebhooks(params) {
-        return this.requestPaginated("GET", "/webhooks", undefined, {
-            limit: params?.limit,
-            offset: params?.offset,
-        });
+    async listWebhooks() {
+        const result = await this.request("GET", "/webhooks");
+        if (result === null ||
+            typeof result !== "object" ||
+            !("data" in result) ||
+            !("total" in result) ||
+            !Array.isArray(result.data) ||
+            typeof result.total !== "number") {
+            throw new FrihetApiError(200, "invalid_response", "API returned invalid webhook list response");
+        }
+        // `/webhooks` is deliberately unpaginated. Keep its `{ data, total }`
+        // contract and discard only the transport-level `meta` sibling.
+        return {
+            data: result.data.map((webhook) => normalizeWebhookRecord(webhook)),
+            total: result.total,
+        };
     }
     async getWebhook(id) {
-        return this.requestUnwrapped("GET", `/webhooks/${encodeURIComponent(id)}`);
+        const result = await this.requestUnwrapped("GET", `/webhooks/${encodeURIComponent(id)}`);
+        return normalizeWebhookRecord(result);
     }
     async createWebhook(data) {
-        return this.requestUnwrapped("POST", "/webhooks", data);
+        const result = await this.requestUnwrapped("POST", "/webhooks", data);
+        return normalizeWebhookRecord(result, typeof data.secret === "string" ? data.secret : undefined);
     }
     async updateWebhook(id, data) {
-        return this.requestUnwrapped("PATCH", `/webhooks/${encodeURIComponent(id)}`, data);
+        const result = await this.requestUnwrapped("PATCH", `/webhooks/${encodeURIComponent(id)}`, data);
+        return normalizeWebhookRecord(result);
     }
     async deleteWebhook(id) {
         return this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
@@ -938,7 +1366,8 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", "/banking/rules", data);
     }
     // ---------------------------------------------------------------- HR (Leaves + Attendance + Anomalies)
-    // NOTE: /v1/leaves, /v1/time-entries, /v1/anomalies — D4-A parallel deploy. 404 propagates until backend ships.
+    // The ERP routes are live. Single-object family reports use the standard
+    // `{ data, meta }` response envelope and must be unwrapped exactly once.
     async listLeaves(params) {
         return this.requestPaginated("GET", "/leaves", undefined, {
             employeeId: params?.employeeId,
@@ -969,7 +1398,7 @@ export class FrihetClient {
         return this.requestUnwrapped("PATCH", `/time-entries/${encodeURIComponent(entryId)}/clock-out`, {});
     }
     async getOvertimeReport(params) {
-        return this.request("GET", "/time-entries/overtime", undefined, {
+        return this.requestUnwrapped("GET", "/time-entries/overtime", undefined, {
             period: params.period,
             employeeId: params.employeeId,
         });
@@ -990,15 +1419,16 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", `/webhooks/${encodeURIComponent(id)}/test`, data ?? {});
     }
     // ---------------------------------------------------------------- Payroll
-    // NOTE: /v1/payroll/prep/* — D4-A parallel deploy. 404 propagates until backend ships.
+    // These live read routes return normalized payroll-preparation records in
+    // the standard single-object `{ data, meta }` envelope.
     async exportPayroll(params) {
-        return this.request("GET", "/payroll/prep/export", undefined, {
+        return this.requestUnwrapped("GET", "/payroll/prep/export", undefined, {
             format: params.format,
             month: params.month,
         });
     }
     async getPayrollChecklist(params) {
-        return this.request("GET", "/payroll/prep/employees", undefined, {
+        return this.requestUnwrapped("GET", "/payroll/prep/employees", undefined, {
             month: params.month,
         });
     }
@@ -1011,20 +1441,22 @@ export class FrihetClient {
         return this.requestUnwrapped("PATCH", "/onboarding/persona", data);
     }
     // ---------------------------------------------------------------- Permissions
-    // NOTE: /v1/permissions/* — D4-A parallel deploy. 404 propagates until backend ships.
+    // These are standard ERP family responses: unwrap their single-object
+    // `{ data, meta }` envelope before handing the payload to MCP output schemas.
     async getPermissionsMatrix() {
-        return this.request("GET", "/permissions/matrix");
+        return this.requestUnwrapped("GET", "/permissions/matrix");
     }
     async getMyPermissions() {
-        return this.request("GET", "/permissions/me");
+        return this.requestUnwrapped("GET", "/permissions/me");
     }
     // ---------------------------------------------------------------- Period Close
-    // NOTE: /v1/periods/* — D4-A parallel deploy. 404 propagates until backend ships.
+    // Period reads are live and enveloped. Fiscal close/reopen writes remain
+    // honest ERP 501 responses and are intentionally unchanged here.
     async getCurrentPeriod(params) {
-        if (params?.periodId) {
-            return this.request("GET", `/periods/${encodeURIComponent(params.periodId)}`);
+        if (params?.fiscalYear) {
+            return this.requestUnwrapped("GET", `/periods/${encodeURIComponent(params.fiscalYear)}`);
         }
-        return this.request("GET", "/periods/current");
+        return this.requestUnwrapped("GET", "/periods/current");
     }
     async closePeriod(data) {
         return this.requestUnwrapped("POST", "/periods/close", data);