@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/client.js

@@ -11,11 +11,83 @@
  * (`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 { rejectRedirectResponse } from "./fetch-no-redirect.js";
+import { safeRequestId, sanitizeServerRemediation } from "./redaction.js";
 import { logApiCall, logRetry } from "./logger.js";
+import { parseRetryAfter } from "./retry-after.js";
+import { fiscalModeloQuery } from "./fiscal-period.js";
+import { normalizeApplyDepositBody, normalizeDepositBody } from "./deposit-contract.js";
 const BASE_URL = "https://api.frihet.io/v1";
 const MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY_MS = 1000;
 const REQUEST_TIMEOUT_MS = 30000;
+/** Total time one logical call may spend sleeping on 429s before it is deferred to the caller. */
+const RETRY_BUDGET_MS = 30000;
+/** setTimeout fires immediately above this (32-bit signed); a larger wait must defer, never sleep. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * 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;
+/** One exhaustive translation at the HTTP boundary. Never send the MCP's
+ * lowercase convenience values to the strict API. Factur-X Extended, Basic
+ * and Minimum are intentionally absent: collapsing them to EN16931 would lie
+ * about the generated profile. */
+const E_INVOICE_EXPORT_API_FORMAT = {
+    facturae: "Facturae",
+    "xrechnung-cii": "XRechnung-CII",
+    "xrechnung-ubl": "XRechnung-UBL",
+    "facturx-en16931": "Factur-X",
+    fatturapa: "FatturaPA",
+    "peppol-bis-3": "PEPPOL-BIS-3",
+    "fa-2-ksef": "FA-2-KSeF",
+    ubl: "UBL",
+    cii: "CII",
+};
+// Only the existing guards below can attest that a request was never sent.
+// Provider error codes, copied errors and public properties cannot forge this
+// process-local provenance. Both runtimes use this fetch-only client.
+const LOCAL_VALIDATION_ERRORS = new WeakSet();
+export function isLocalInputValidationError(error) {
+    return typeof error === "object" && error !== null && LOCAL_VALIDATION_ERRORS.has(error);
+}
+export function toApiEInvoiceExportFormat(format) {
+    if (!Object.hasOwn(E_INVOICE_EXPORT_API_FORMAT, format)) {
+        const error = new FrihetApiError(400, "unsupported_einvoice_export_format", "Unsupported e-invoice export format. Factur-X export supports the EN16931 profile only.");
+        LOCAL_VALIDATION_ERRORS.add(error);
+        throw error;
+    }
+    return E_INVOICE_EXPORT_API_FORMAT[format];
+}
+/**
+ * Encode one caller-supplied path segment. `encodeURIComponent` leaves "." and
+ * ".." unchanged and URL parsing resolves them as dot-segments, so either value
+ * would change the route a request reaches; an empty value would drop the
+ * segment. Every id interpolated into a request path goes through here, and
+ * those three values are refused before any request is sent.
+ */
+function pathSegment(value) {
+    const segment = String(value);
+    if (segment === "" || segment === "." || segment === "..") {
+        const error = new FrihetApiError(400, "invalid_path_segment", 'Invalid identifier: an id cannot be empty, "." or "..".');
+        LOCAL_VALIDATION_ERRORS.add(error);
+        throw error;
+    }
+    return encodeURIComponent(segment);
+}
 /**
  * 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 +127,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,31 +157,170 @@ 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;
+    requestId;
+    constructor(statusCode, errorCode, message, detail, 
+    /** Backend correlation id (`meta.requestId` or `X-Request-Id`); carried for diagnostics, never echoed to agents. */
+    requestId) {
+        super(statusCode === 403
+            ? sanitizeServerRemediation(message, errorCode) ?? errorCode
+            : message ?? errorCode);
         this.statusCode = statusCode;
         this.errorCode = errorCode;
+        this.detail = detail;
+        this.requestId = requestId;
         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;
+    // publicApi error envelopes carry `meta: { requestId }` (Frihet-ERP
+    // functions/src/publicApi.ts, e.g. the 401/404 branches).
+    const meta = typeof record?.meta === "object" && record.meta !== null
+        ? record.meta
+        : undefined;
+    const requestId = safeRequestId(meta?.requestId);
+    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 } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+}
 export class FrihetClient {
     apiKey;
     baseUrl;
     timeoutMs;
+    retryBudgetMs;
+    sleepFn;
+    nowFn;
     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;
+        const budget = options?.retryBudgetMs;
+        // NaN/negative would make every `> budget` comparison pass or fail silently.
+        this.retryBudgetMs =
+            typeof budget === "number" && Number.isFinite(budget) && budget >= 0
+                ? Math.min(budget, MAX_TIMER_MS)
+                : RETRY_BUDGET_MS;
+        this.sleepFn = options?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.nowFn = options?.now ?? Date.now;
     }
     // ------------------------------------------------------------------ HTTP
     // ------------------------------------------------------------------
-    async request(method, path, body, query, retryCount = 0, idempotencyKey) {
+    async request(method, path, body, query, retryCount = 0, idempotencyKey, waitedMs = 0) {
         const url = new URL(`${this.baseUrl}${path}`);
         // Resolved once, at the top of the call chain: a caller-supplied key wins,
         // otherwise mutations get a freshly minted one. The resolved value is then
@@ -143,67 +353,251 @@ export class FrihetClient {
         try {
             response = await fetch(url.toString(), {
                 method,
+                redirect: "manual",
                 headers,
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
-            });
+            }).then(rejectRedirectResponse);
         }
         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.");
             }
-            const retryAfter = response.headers.get("Retry-After");
-            const delayMs = retryAfter
-                ? parseInt(retryAfter, 10) * 1000
-                : DEFAULT_RETRY_DELAY_MS * Math.pow(2, retryCount);
-            logRetry(method, path, retryCount, delayMs);
-            await this.sleep(delayMs);
-            return this.request(method, path, body, query, retryCount + 1, resolvedIdempotencyKey);
+            // Release the discarded 429 body before waiting so the socket is freed.
+            // (requestDocument has already drained it in readBoundedBody.)
+            await response.body?.cancel().catch(() => undefined);
+            const delayMs = this.rateLimitDelayMs(response.headers.get("Retry-After"), retryCount, waitedMs, method, path);
+            await this.sleepFn(delayMs);
+            return this.request(method, path, body, query, retryCount + 1, resolvedIdempotencyKey, waitedMs + delayMs);
         }
         // Error responses
         if (!response.ok) {
             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, errorBody.requestId ?? safeRequestId(response.headers.get("x-request-id")));
         }
         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;
     }
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    /** 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 (resolvedIdempotencyKey) {
+            headers["Idempotency-Key"] = resolvedIdempotencyKey;
+        }
+        return fetch(url.toString(), {
+            method,
+            redirect: "manual",
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal,
+        }).then(rejectRedirectResponse);
+    }
+    /** 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, waitedMs = 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.");
+                }
+                clearTimeout(timeoutId);
+                const delayMs = this.rateLimitDelayMs(response.headers.get("Retry-After"), retryCount, waitedMs, method, path);
+                await this.sleepFn(delayMs);
+                return this.requestDocument(method, path, body, query, idempotencyKey, maxBytesForContentType, retryCount + 1, waitedMs + delayMs);
+            }
+            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, errorBody.requestId ?? safeRequestId(response.headers.get("x-request-id")));
+            }
+            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);
+        }
+    }
+    /**
+     * Wait before the next 429 retry: the server's `Retry-After` when it parses
+     * (RFC 9110 §10.2.3), otherwise exponential backoff. Either wait that does
+     * not fit the remaining cumulative budget is deferred to the caller; a server
+     * wait is never shortened into an early retry.
+     */
+    rateLimitDelayMs(retryAfter, retryCount, waitedMs, method, path) {
+        const serverMs = parseRetryAfter(retryAfter, this.nowFn());
+        const delayMs = serverMs ?? DEFAULT_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        if (waitedMs + delayMs > this.retryBudgetMs) {
+            throw new FrihetApiError(429, "rate_limit_deferred", serverMs !== null
+                ? `Rate limited: the server asks to wait ${Math.ceil(serverMs / 1000)} seconds, which exceeds this operation's retry budget. Retry after that time; nothing was retried early.`
+                : "Rate limited: the next backoff wait exceeds this operation's retry budget. Retry later.");
+        }
+        logRetry(method, path, retryCount, delayMs, serverMs === null ? "backoff" : "retry_after");
+        return delayMs;
     }
     /**
      * Wrapper for endpoints whose backend wraps the payload in a `{ data, meta }`
@@ -220,15 +614,20 @@ 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
      * deliberately distinct from {@link requestPaginated}, which keeps the
-     * `{ data: [...] , meta }` shape intact for list endpoints. If the body is
+     * list rows and pagination fields while omitting transport metadata. If the body is
      * not an envelope (legacy endpoints that return the item directly), it is
      * returned unchanged so existing callers keep working.
      */
@@ -248,13 +647,21 @@ export class FrihetClient {
         }
         return raw;
     }
-    /** Wrapper for paginated endpoints — validates response shape has `data` array. */
+    /** Validate list rows and emit only the declared MCP pagination envelope. */
     async requestPaginated(method, path, body, query) {
         const result = await this.request(method, path, body, query);
         if (!result || !Array.isArray(result.data)) {
             throw new FrihetApiError(200, 'invalid_response', 'API returned invalid paginated response');
         }
-        return result;
+        // API transport metadata is not part of the closed MCP page contract.
+        // Keep rows untouched and preserve every declared pagination field.
+        return {
+            data: result.data,
+            total: result.total,
+            limit: result.limit,
+            offset: result.offset,
+            ...(result.nextCursor !== undefined ? { nextCursor: result.nextCursor } : {}),
+        };
     }
     // ---------------------------------------------------------------- Public
     // ----------------------------------------------------------------
@@ -274,16 +681,30 @@ export class FrihetClient {
         });
     }
     async getInvoice(id) {
-        return this.requestUnwrapped("GET", `/invoices/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/invoices/${pathSegment(id)}`);
     }
     async createInvoice(data) {
         return this.requestUnwrapped("POST", "/invoices", data);
     }
     async updateInvoice(id, data) {
-        return this.requestUnwrapped("PATCH", `/invoices/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/invoices/${pathSegment(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/${pathSegment(id)}`);
     }
     async searchInvoices(query, params) {
         return this.requestPaginated("GET", "/invoices", undefined, {
@@ -312,16 +733,16 @@ export class FrihetClient {
         });
     }
     async getExpense(id) {
-        return this.requestUnwrapped("GET", `/expenses/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/expenses/${pathSegment(id)}`);
     }
     async createExpense(data) {
         return this.requestUnwrapped("POST", "/expenses", data);
     }
     async updateExpense(id, data) {
-        return this.requestUnwrapped("PATCH", `/expenses/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/expenses/${pathSegment(id)}`, data);
     }
     async deleteExpense(id) {
-        return this.request("DELETE", `/expenses/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/expenses/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Clients
     // ----------------------------------------------------------------
@@ -336,16 +757,16 @@ export class FrihetClient {
         });
     }
     async getClient(id) {
-        return this.requestUnwrapped("GET", `/clients/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/clients/${pathSegment(id)}`);
     }
     async createClient(data) {
         return this.requestUnwrapped("POST", "/clients", data);
     }
     async updateClient(id, data) {
-        return this.requestUnwrapped("PATCH", `/clients/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/clients/${pathSegment(id)}`, data);
     }
     async deleteClient(id) {
-        return this.request("DELETE", `/clients/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/clients/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Products
     // ----------------------------------------------------------------
@@ -356,20 +777,22 @@ 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) {
-        return this.requestUnwrapped("GET", `/products/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/products/${pathSegment(id)}`);
     }
     async createProduct(data) {
         return this.requestUnwrapped("POST", "/products", data);
     }
     async updateProduct(id, data) {
-        return this.requestUnwrapped("PATCH", `/products/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/products/${pathSegment(id)}`, data);
     }
     async deleteProduct(id) {
-        return this.request("DELETE", `/products/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/products/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Quotes
     // ----------------------------------------------------------------
@@ -387,16 +810,22 @@ export class FrihetClient {
         });
     }
     async getQuote(id) {
-        return this.requestUnwrapped("GET", `/quotes/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/quotes/${pathSegment(id)}`);
     }
     async createQuote(data) {
         return this.requestUnwrapped("POST", "/quotes", data);
     }
     async updateQuote(id, data) {
-        return this.requestUnwrapped("PATCH", `/quotes/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/quotes/${pathSegment(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/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Vendors
     // ----------------------------------------------------------------
@@ -410,35 +839,96 @@ export class FrihetClient {
         });
     }
     async getVendor(id) {
-        return this.requestUnwrapped("GET", `/vendors/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/vendors/${pathSegment(id)}`);
     }
     async createVendor(data) {
         return this.requestUnwrapped("POST", "/vendors", data);
     }
     async updateVendor(id, data) {
-        return this.requestUnwrapped("PATCH", `/vendors/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/vendors/${pathSegment(id)}`, data);
     }
     async deleteVendor(id) {
-        return this.request("DELETE", `/vendors/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/vendors/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Invoice Actions
     // ----------------------------------------------------------------
     async sendInvoice(id, to) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(id)}/send`, to ? { to } : undefined);
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(id)}/send`, to ? { recipientEmail: to } : undefined);
     }
     async markInvoicePaid(id, paidDate) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(id)}/paid`, paidDate ? { paidDate } : undefined);
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(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 raw bytes
+        // (functions/src/publicApi.ts:6149-6167); there is no pre-signed-URL or JSON
+        // success contract to emulate.
+        const url = `/invoices/${pathSegment(id)}/pdf`;
+        const doc = await this.requestDocument("GET", url, undefined, undefined, undefined, (contentType) => {
+            const norm = normalizedContentType(contentType);
+            return norm === "application/pdf"
+                || norm === "application/octet-stream"
+                || norm === "binary/octet-stream"
+                ? MAX_PDF_BYTES
+                : MAX_ERROR_BYTES;
+        });
+        const normType = normalizedContentType(doc.contentType);
+        if (normType !== "application/pdf" && normType !== "application/octet-stream" && normType !== "binary/octet-stream") {
+            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");
+        }
+        if (doc.sizeBytes > MAX_PDF_BYTES) {
+            throw new FrihetApiError(413, "payload_too_large", `Invoice PDF exceeds maximum allowed size of ${MAX_PDF_BYTES} bytes`);
+        }
+        return {
+            id,
+            contentType: "application/pdf",
+            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/${pathSegment(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.
@@ -453,74 +943,117 @@ export class FrihetClient {
      * which is the property that matters here.
      */
     async createCreditNote(invoiceId, data, idempotencyKey) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/credit-note`, data, undefined, idempotencyKey);
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(invoiceId)}/credit-note`, data, undefined, idempotencyKey);
     }
     async applyLateFee(invoiceId, data) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/late-fee`, data ?? {});
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(invoiceId)}/late-fee`, data ?? {});
     }
     // ---------------------------------------------------------------- Quote Actions
     // ----------------------------------------------------------------
     async sendQuote(id, to) {
-        return this.requestUnwrapped("POST", `/quotes/${encodeURIComponent(id)}/send`, to ? { to } : undefined);
+        return this.requestUnwrapped("POST", `/quotes/${pathSegment(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/${pathSegment(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/${pathSegment(id)}`, data);
+        return normalizeWebhookRecord(result);
     }
     async deleteWebhook(id) {
-        return this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/webhooks/${pathSegment(id)}`);
+    }
+    // ---------------------------------------------------------------- Cross-resource search
+    // ----------------------------------------------------------------
+    //
+    // GET /v1/search/global?q=<term>&types=a,b,c&limit=&offset=  (publicApi.ts:4476)
+    //
+    // Read-only fan-out across invoices / expenses / vendors / clients / products.
+    // All five collections are workspace-scoped via users/{userId}/..., so the
+    // tenant boundary is preserved by Firestore subcollection paths — same as
+    // every other list/search endpoint on the server. No mutation counterpart;
+    // no auth boundary different from any other read tool.
+    async globalSearch(params) {
+        const typesCsv = params.types && params.types.length > 0 ? params.types.join(",") : undefined;
+        const result = await this.request("GET", "/search/global", undefined, {
+            q: params.q,
+            types: typesCsv,
+            limit: params.limit,
+            offset: params.offset,
+        });
+        return {
+            data: result.data,
+            total: result.total,
+            limit: result.limit,
+            offset: result.offset,
+            hasMore: result.hasMore,
+            query: result.query,
+            types: result.types,
+            ...(result.truncated !== undefined ? { truncated: result.truncated } : {}),
+        };
     }
     // ---------------------------------------------------------------- CRM: Contacts
     // ----------------------------------------------------------------
     async listClientContacts(clientId, params) {
-        return this.requestPaginated("GET", `/clients/${encodeURIComponent(clientId)}/contacts`, undefined, {
+        return this.requestPaginated("GET", `/clients/${pathSegment(clientId)}/contacts`, undefined, {
             limit: params?.limit,
             offset: params?.offset,
         });
     }
     async createClientContact(clientId, data) {
-        return this.requestUnwrapped("POST", `/clients/${encodeURIComponent(clientId)}/contacts`, data);
+        return this.requestUnwrapped("POST", `/clients/${pathSegment(clientId)}/contacts`, data);
     }
     async deleteClientContact(clientId, contactId) {
-        return this.request("DELETE", `/clients/${encodeURIComponent(clientId)}/contacts/${encodeURIComponent(contactId)}`);
+        return this.request("DELETE", `/clients/${pathSegment(clientId)}/contacts/${pathSegment(contactId)}`);
     }
     // ---------------------------------------------------------------- CRM: Activities
     // ----------------------------------------------------------------
     async listClientActivities(clientId, params) {
-        return this.requestPaginated("GET", `/clients/${encodeURIComponent(clientId)}/activities`, undefined, {
+        return this.requestPaginated("GET", `/clients/${pathSegment(clientId)}/activities`, undefined, {
             limit: params?.limit,
             offset: params?.offset,
         });
     }
     async logClientActivity(clientId, data) {
-        return this.requestUnwrapped("POST", `/clients/${encodeURIComponent(clientId)}/activities`, data);
+        return this.requestUnwrapped("POST", `/clients/${pathSegment(clientId)}/activities`, data);
     }
     // ---------------------------------------------------------------- CRM: Notes
     // ----------------------------------------------------------------
     async listClientNotes(clientId, params) {
-        return this.requestPaginated("GET", `/clients/${encodeURIComponent(clientId)}/notes`, undefined, {
+        return this.requestPaginated("GET", `/clients/${pathSegment(clientId)}/notes`, undefined, {
             limit: params?.limit,
             offset: params?.offset,
         });
     }
     async createClientNote(clientId, data) {
-        return this.requestUnwrapped("POST", `/clients/${encodeURIComponent(clientId)}/notes`, data);
+        return this.requestUnwrapped("POST", `/clients/${pathSegment(clientId)}/notes`, data);
     }
     async deleteClientNote(clientId, noteId) {
-        return this.request("DELETE", `/clients/${encodeURIComponent(clientId)}/notes/${encodeURIComponent(noteId)}`);
+        return this.request("DELETE", `/clients/${pathSegment(clientId)}/notes/${pathSegment(noteId)}`);
     }
     // ---------------------------------------------------------------- Deposits
     // ----------------------------------------------------------------
@@ -537,22 +1070,22 @@ export class FrihetClient {
         });
     }
     async getDeposit(id) {
-        return this.requestUnwrapped("GET", `/deposits/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/deposits/${pathSegment(id)}`);
     }
     async createDeposit(data) {
-        return this.requestUnwrapped("POST", "/deposits", data);
+        return this.requestUnwrapped("POST", "/deposits", normalizeDepositBody(data, false));
     }
     async updateDeposit(id, data) {
-        return this.requestUnwrapped("PATCH", `/deposits/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/deposits/${pathSegment(id)}`, normalizeDepositBody(data, true));
     }
     async deleteDeposit(id) {
-        return this.request("DELETE", `/deposits/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/deposits/${pathSegment(id)}`);
     }
     async applyDeposit(id, data) {
-        return this.requestUnwrapped("POST", `/deposits/${encodeURIComponent(id)}/apply`, data ?? {});
+        return this.requestUnwrapped("POST", `/deposits/${pathSegment(id)}/apply`, normalizeApplyDepositBody(data));
     }
     async refundDeposit(id, data) {
-        return this.requestUnwrapped("POST", `/deposits/${encodeURIComponent(id)}/refund`, data ?? {});
+        return this.requestUnwrapped("POST", `/deposits/${pathSegment(id)}/refund`, data ?? {});
     }
     // ---------------------------------------------------------------- E-Invoicing
     // ----------------------------------------------------------------
@@ -563,7 +1096,7 @@ export class FrihetClient {
         // get_einvoice_status's outputSchema (eInvoiceStatusOutput) expects the
         // flat status object, same single-object envelope convention as the rest
         // of the /v1 REST surface.
-        return this.requestUnwrapped("GET", `/einvoice/status/${encodeURIComponent(workflowRunId)}`);
+        return this.requestUnwrapped("GET", `/einvoice/status/${pathSegment(workflowRunId)}`);
     }
     async validateEInvoiceXml(params) {
         return this.requestUnwrapped("POST", "/einvoice/validate", params);
@@ -576,22 +1109,26 @@ export class FrihetClient {
     // New per-invoice endpoints: /v1/invoices/:id/einvoice/export, /face/*, /ticketbai/*
     // 404 responses propagate to tool handlers which fall back to stub responses.
     async exportEInvoice(params) {
-        const { invoiceId, ...body } = params;
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/einvoice/export`, body);
+        const { invoiceId, format, signed } = params;
+        const body = {
+            format: toApiEInvoiceExportFormat(format),
+            ...(signed === undefined ? {} : { signed }),
+        };
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(invoiceId)}/einvoice/export`, body);
     }
     async faceSubmit(params) {
         const { invoiceId, mode } = params;
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/face/submit`, { mode });
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(invoiceId)}/face/submit`, { mode });
     }
     async faceStatus(params) {
-        return this.request("GET", `/invoices/${encodeURIComponent(params.invoiceId)}/face/status`);
+        return this.request("GET", `/invoices/${pathSegment(params.invoiceId)}/face/status`);
     }
     async ticketbaiSubmit(params) {
         const { invoiceId, sandbox } = params;
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/ticketbai/submit`, { sandbox });
+        return this.requestUnwrapped("POST", `/invoices/${pathSegment(invoiceId)}/ticketbai/submit`, { sandbox });
     }
     async ticketbaiStatus(params) {
-        return this.request("GET", `/invoices/${encodeURIComponent(params.invoiceId)}/ticketbai/status`);
+        return this.request("GET", `/invoices/${pathSegment(params.invoiceId)}/ticketbai/status`);
     }
     // kSeFSubmit intentionally omitted — ksef_submit tool is always-stub (public KSeF endpoint not yet exposed; transport infra-ready in Frihet-ERP).
     // ---------------------------------------------------------------- Stay (Vacation Rental)
@@ -612,7 +1149,7 @@ export class FrihetClient {
         });
     }
     async getReservation(id) {
-        return this.requestUnwrapped("GET", `/stay/reservations/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/stay/reservations/${pathSegment(id)}`);
     }
     async createReservation(data) {
         return this.requestUnwrapped("POST", "/stay/reservations", data);
@@ -628,7 +1165,7 @@ export class FrihetClient {
         });
     }
     async syncChannel(channelId, direction) {
-        return this.requestUnwrapped("POST", `/stay/channels/${encodeURIComponent(channelId)}/sync`, { direction });
+        return this.requestUnwrapped("POST", `/stay/channels/${pathSegment(channelId)}/sync`, { direction });
     }
     // ---------------------------------------------------------------- POS (Point of Sale)
     // ----------------------------------------------------------------
@@ -641,7 +1178,7 @@ export class FrihetClient {
         });
     }
     async getSale(id) {
-        return this.requestUnwrapped("GET", `/pos/sales/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/pos/sales/${pathSegment(id)}`);
     }
     async listSales(params) {
         return this.requestPaginated("GET", "/pos/sales", undefined, {
@@ -655,7 +1192,7 @@ export class FrihetClient {
         });
     }
     async refundSale(id, data) {
-        return this.requestUnwrapped("POST", `/pos/sales/${encodeURIComponent(id)}/refund`, data ?? {});
+        return this.requestUnwrapped("POST", `/pos/sales/${pathSegment(id)}/refund`, data ?? {});
     }
     // ---------------------------------------------------------------- Kitchen (KDS)
     // ----------------------------------------------------------------
@@ -670,10 +1207,13 @@ export class FrihetClient {
         });
     }
     async getKitchenTicket(id) {
-        return this.requestUnwrapped("GET", `/kitchen/tickets/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/kitchen/tickets/${pathSegment(id)}`);
     }
     async updateKitchenTicket(id, data) {
-        return this.requestUnwrapped("PATCH", `/kitchen/tickets/${encodeURIComponent(id)}`, data);
+        // The public tool accepts one station; the strict REST contract stores an array.
+        const { stationId, ...patch } = data;
+        const body = stationId === undefined ? patch : { ...patch, stationIds: [stationId] };
+        return this.requestUnwrapped("PATCH", `/kitchen/tickets/${pathSegment(id)}`, body);
     }
     async listKitchenStations(params) {
         return this.requestPaginated("GET", "/kitchen/stations", undefined, {
@@ -716,7 +1256,7 @@ export class FrihetClient {
         });
     }
     async getBankAccount(id) {
-        return this.requestUnwrapped("GET", `/banking/accounts/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/banking/accounts/${pathSegment(id)}`);
     }
     async listTransactions(params) {
         return this.requestPaginated("GET", "/banking/transactions", undefined, {
@@ -731,10 +1271,10 @@ export class FrihetClient {
         });
     }
     async categorizeTransaction(id, data) {
-        return this.requestUnwrapped("PATCH", `/banking/transactions/${encodeURIComponent(id)}/categorize`, data);
+        return this.requestUnwrapped("PATCH", `/banking/transactions/${pathSegment(id)}/categorize`, data);
     }
     async matchTransactionToDocument(transactionId, data) {
-        return this.requestUnwrapped("POST", `/banking/transactions/${encodeURIComponent(transactionId)}/match`, data);
+        return this.requestUnwrapped("POST", `/banking/transactions/${pathSegment(transactionId)}/match`, data);
     }
     // ---------------------------------------------------------------- Fiscal
     // RESOLVED (was: "planned — 404 propagates until backend ships"). The
@@ -746,18 +1286,19 @@ export class FrihetClient {
     // NOTE: /v1/fiscal/verifactu/* + /ticketbai/* below remain pending and 404
     // until those backends ship (they keep the raw `request` path for now).
     async getFiscalModeloSummary(modeloCode, period) {
-        return this.requestUnwrapped("GET", `/fiscal/modelo/${encodeURIComponent(modeloCode)}`, undefined, {
-            period,
-        });
+        // The backend reads `?quarter=` (303/130) or `?year=` (390/347) and
+        // silently answers the CURRENT period for any other param, so the param
+        // name comes from the shared rule table, never a generic `?period=`.
+        return this.requestUnwrapped("GET", `/fiscal/modelo/${pathSegment(modeloCode)}`, undefined, fiscalModeloQuery(modeloCode, period));
     }
     async getVerifactuStatus(invoiceId) {
-        return this.requestUnwrapped("GET", `/fiscal/verifactu/${encodeURIComponent(invoiceId)}/status`);
+        return this.requestUnwrapped("GET", `/fiscal/verifactu/${pathSegment(invoiceId)}/status`);
     }
     async resubmitVerifactu(invoiceId) {
-        return this.requestUnwrapped("POST", `/fiscal/verifactu/${encodeURIComponent(invoiceId)}/resubmit`, {});
+        return this.requestUnwrapped("POST", `/fiscal/verifactu/${pathSegment(invoiceId)}/resubmit`, {});
     }
     async getTicketbaiStatus(invoiceId) {
-        return this.request("GET", `/fiscal/ticketbai/${encodeURIComponent(invoiceId)}/status`);
+        return this.request("GET", `/fiscal/ticketbai/${pathSegment(invoiceId)}/status`);
     }
     // ---------------------------------------------------------------- Time Tracking
     // Backend: /v1/time/* endpoints live as of Wave 4-A (Frihet-ERP functions/src/publicApi.ts).
@@ -774,16 +1315,16 @@ export class FrihetClient {
         });
     }
     async getTimeEntry(id) {
-        return this.requestUnwrapped("GET", `/time/entries/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/time/entries/${pathSegment(id)}`);
     }
     async createTimeEntry(data) {
         return this.requestUnwrapped("POST", "/time/entries", data);
     }
     async updateTimeEntry(id, data) {
-        return this.requestUnwrapped("PATCH", `/time/entries/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/time/entries/${pathSegment(id)}`, data);
     }
     async deleteTimeEntry(id) {
-        return this.request("DELETE", `/time/entries/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/time/entries/${pathSegment(id)}`);
     }
     async getTimeSummary(params) {
         return this.requestUnwrapped("GET", "/time/summary", undefined, {
@@ -804,25 +1345,25 @@ export class FrihetClient {
         });
     }
     async getRecurringInvoice(id) {
-        return this.requestUnwrapped("GET", `/recurring/invoices/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("GET", `/recurring/invoices/${pathSegment(id)}`);
     }
     async createRecurringInvoice(data) {
         return this.requestUnwrapped("POST", "/recurring/invoices", data);
     }
     async updateRecurringInvoice(id, data) {
-        return this.requestUnwrapped("PATCH", `/recurring/invoices/${encodeURIComponent(id)}`, data);
+        return this.requestUnwrapped("PATCH", `/recurring/invoices/${pathSegment(id)}`, data);
     }
     async pauseRecurringInvoice(id) {
-        return this.requestUnwrapped("POST", `/recurring/invoices/${encodeURIComponent(id)}/pause`, {});
+        return this.requestUnwrapped("POST", `/recurring/invoices/${pathSegment(id)}/pause`, {});
     }
     async resumeRecurringInvoice(id) {
-        return this.requestUnwrapped("POST", `/recurring/invoices/${encodeURIComponent(id)}/resume`, {});
+        return this.requestUnwrapped("POST", `/recurring/invoices/${pathSegment(id)}/resume`, {});
     }
     async deleteRecurringInvoice(id) {
-        return this.request("DELETE", `/recurring/invoices/${encodeURIComponent(id)}`);
+        return this.request("DELETE", `/recurring/invoices/${pathSegment(id)}`);
     }
     async runRecurringNow(templateId, options) {
-        return this.requestUnwrapped("POST", `/recurring/invoices/${encodeURIComponent(templateId)}/run`, {
+        return this.requestUnwrapped("POST", `/recurring/invoices/${pathSegment(templateId)}/run`, {
             draftOnly: options?.draftOnly ?? true,
         });
     }
@@ -840,10 +1381,10 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", "/team/members/invite", data);
     }
     async updateTeamMemberRole(memberId, role) {
-        return this.requestUnwrapped("PATCH", `/team/members/${encodeURIComponent(memberId)}/role`, { role });
+        return this.requestUnwrapped("PATCH", `/team/members/${pathSegment(memberId)}/role`, { role });
     }
     async removeTeamMember(memberId) {
-        return this.request("DELETE", `/team/members/${encodeURIComponent(memberId)}`);
+        return this.request("DELETE", `/team/members/${pathSegment(memberId)}`);
     }
     // ---------------------------------------------------------------- Gestoria (Wave Fase 1)
     // Backend: /v1/gestoria/* endpoints land with Frihet-ERP Wave Fase 1 closure.
@@ -869,20 +1410,22 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", "/gestoria/templates/bulk-send", data);
     }
     async getGestoriaAgingConsolidated(params) {
-        return this.request("GET", "/gestoria/aging/consolidated", undefined, {
-            ownerUid: params?.ownerUid,
+        return this.requestUnwrapped("POST", "/gestoria/aging", {
+            workspaceIds: params?.workspaceIds,
+            asOf: params?.asOf,
+            bustCache: params?.bustCache,
         });
     }
     // ---------------------------------------------------------------- Audit GL
     // NOTE: /v1/gl/* endpoints proxy Firebase callables (PR #395). 404 until REST shell ships.
     async approveGLEntry(entryId, notes) {
-        return this.requestUnwrapped("POST", `/gl/entries/${encodeURIComponent(entryId)}/approve`, { notes });
+        return this.requestUnwrapped("POST", `/gl/entries/${pathSegment(entryId)}/approve`, { notes });
     }
-    async rejectGLEntry(entryId, reason) {
-        return this.requestUnwrapped("POST", `/gl/entries/${encodeURIComponent(entryId)}/reject`, { reason });
+    async rejectGLEntry(entryId, note) {
+        return this.requestUnwrapped("POST", `/gl/entries/${pathSegment(entryId)}/reject`, { note });
     }
     async getGLEntryAuditLog(entryId) {
-        return this.request("GET", `/gl/entries/${encodeURIComponent(entryId)}/audit-log`);
+        return this.request("GET", `/gl/entries/${pathSegment(entryId)}/audit-log`);
     }
     // ---------------------------------------------------------------- White-label Portal Domain
     // NOTE: /v1/portal/domain/* endpoints proxy Firebase callables (PR #397). 404 until REST shell ships.
@@ -890,10 +1433,10 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", "/portal/domain", data);
     }
     async verifyCustomPortalDomain(data) {
-        return this.requestUnwrapped("POST", `/portal/domain/${encodeURIComponent(data.domain)}/verify`, {});
+        return this.requestUnwrapped("POST", `/portal/domain/${pathSegment(data.domain)}/verify`, {});
     }
     async removeCustomPortalDomain(data) {
-        return this.request("DELETE", `/portal/domain/${encodeURIComponent(data.domain)}`);
+        return this.request("DELETE", `/portal/domain/${pathSegment(data.domain)}`);
     }
     // ---------------------------------------------------------------- Self-onboard + VIES
     // NOTE: /v1/portal/onboard/* endpoints proxy Firebase callables (PR #398). 404 until REST shell ships.
@@ -909,7 +1452,7 @@ export class FrihetClient {
     // ---------------------------------------------------------------- IGIC (Canary Islands)
     // NOTE: /v1/igic/* endpoints (PR #390). 404 until REST shell ships.
     async getIgicModeloSummary(modeloCode, params) {
-        return this.request("GET", `/igic/modelo/${encodeURIComponent(modeloCode)}`, undefined, {
+        return this.request("GET", `/igic/modelo/${pathSegment(modeloCode)}`, undefined, {
             year: params?.year,
             period: params?.period,
         });
@@ -920,7 +1463,7 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Impuesto Sociedades (IS)
     // NOTE: /v1/is/* endpoints (PR #392). 404 until REST shell ships.
     async getISSummary(modeloCode, params) {
-        return this.request("GET", `/is/modelo/${encodeURIComponent(modeloCode)}`, undefined, {
+        return this.request("GET", `/is/modelo/${pathSegment(modeloCode)}`, undefined, {
             year: params?.year,
             installment: params?.installment,
         });
@@ -928,7 +1471,7 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Bank Rules
     // NOTE: /v1/banking/rules Q3-flagged (PR #394). 404 until callable wrapper ships.
     async listBankRules(params) {
-        return this.request("GET", "/banking/rules", undefined, {
+        return this.requestPaginated("GET", "/banking/rules", undefined, {
             isActive: params?.isActive !== undefined ? String(params.isActive) : undefined,
             limit: params?.limit,
             offset: params?.offset,
@@ -938,7 +1481,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,
@@ -954,22 +1498,22 @@ export class FrihetClient {
         return this.requestUnwrapped("POST", "/leaves", data);
     }
     async approveLeave(leaveId, data) {
-        return this.requestUnwrapped("POST", `/leaves/${encodeURIComponent(leaveId)}/approve`, data ?? {});
+        return this.requestUnwrapped("POST", `/leaves/${pathSegment(leaveId)}/approve`, data ?? {});
     }
     async rejectLeave(leaveId, data) {
-        return this.requestUnwrapped("POST", `/leaves/${encodeURIComponent(leaveId)}/reject`, data);
+        return this.requestUnwrapped("POST", `/leaves/${pathSegment(leaveId)}/reject`, data);
     }
     async cancelLeave(leaveId) {
-        return this.requestUnwrapped("POST", `/leaves/${encodeURIComponent(leaveId)}/cancel`, {});
+        return this.requestUnwrapped("POST", `/leaves/${pathSegment(leaveId)}/cancel`, {});
     }
-    async attendanceClockIn(data) {
-        return this.requestUnwrapped("POST", "/time-entries/clock-in", data);
+    async attendanceClockIn(data, idempotencyKey) {
+        return this.requestUnwrapped("POST", "/time-entries/clock-in", data, undefined, idempotencyKey);
     }
-    async attendanceClockOut(entryId) {
-        return this.requestUnwrapped("PATCH", `/time-entries/${encodeURIComponent(entryId)}/clock-out`, {});
+    async attendanceClockOut(entryId, idempotencyKey) {
+        return this.requestUnwrapped("PATCH", `/time-entries/${pathSegment(entryId)}/clock-out`, {}, undefined, idempotencyKey);
     }
     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,
         });
@@ -987,50 +1531,49 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Webhook Trust-Area Extensions
     // NOTE: /v1/webhooks/:id/test — D4-A parallel deploy. 404 propagates until backend ships.
     async testWebhook(id, data) {
-        return this.requestUnwrapped("POST", `/webhooks/${encodeURIComponent(id)}/test`, data ?? {});
+        return this.requestUnwrapped("POST", `/webhooks/${pathSegment(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,
         });
     }
-    // ---------------------------------------------------------------- Onboarding
-    // NOTE: /v1/onboarding/* — D4-A parallel deploy. 404 propagates until backend ships.
-    async getOnboardingStatus() {
-        return this.request("GET", "/onboarding/status");
-    }
-    async setOnboardingPersona(data) {
-        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.
+    //
+    // Note: /v1/onboarding/* methods (getOnboardingStatus, setOnboardingPersona)
+    // were removed when the onboarding family was withdrawn via issue #124.
+    // See src/tools/igic.ts for the rationale and the inline-stub precedent.
     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/${pathSegment(params.fiscalYear)}`);
         }
-        return this.request("GET", "/periods/current");
+        return this.requestUnwrapped("GET", "/periods/current");
     }
     async closePeriod(data) {
         return this.requestUnwrapped("POST", "/periods/close", data);
     }
     async reopenPeriod(data) {
-        return this.requestUnwrapped("POST", `/periods/${encodeURIComponent(data.periodId)}/reopen`, { reason: data.reason });
+        return this.requestUnwrapped("POST", `/periods/${pathSegment(data.periodId)}/reopen`, { reason: data.reason });
     }
 }
 //# sourceMappingURL=client.js.map