@frihet/mcp-server 1.17.0 → 2.0.1

package/dist/client.js

@@ -11,17 +11,20 @@
  * (`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 { 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 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;
+/** 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
@@ -39,6 +42,52 @@ const REQUEST_TIMEOUT_MS = 30000;
 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`
@@ -172,13 +221,17 @@ export class FrihetApiError extends Error {
     statusCode;
     errorCode;
     detail;
-    constructor(statusCode, errorCode, message, 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";
     }
 }
@@ -222,6 +275,12 @@ function normalizeApiError(value, statusCode, statusText) {
     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;
@@ -232,13 +291,16 @@ function normalizeApiError(value, statusCode, statusText) {
         error,
         message,
         ...(typeof record?.detail === "string" ? { detail: record.detail } : {}),
+        ...(requestId ? { requestId } : {}),
     };
 }
 export class FrihetClient {
     apiKey;
     baseUrl;
     timeoutMs;
-    oauthServiceSecret;
+    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.");
@@ -247,24 +309,18 @@ export class FrihetClient {
         this.apiKey = apiKey;
         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;
-        }
+        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
@@ -287,9 +343,6 @@ 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;
         }
@@ -300,11 +353,11 @@ export class FrihetClient {
         try {
             response = await fetch(url.toString(), {
                 method,
+                redirect: "manual",
                 headers,
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
-                redirect: "error",
-            });
+            }).then(rejectRedirectResponse);
         }
         catch (error) {
             clearTimeout(timeoutId);
@@ -324,13 +377,12 @@ export class FrihetClient {
             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) {
@@ -343,7 +395,7 @@ export class FrihetClient {
                 errorBody = normalizeApiError(undefined, response.status, response.statusText);
             }
             clearTimeout(timeoutId);
-            throw new FrihetApiError(response.status, errorBody.error, errorBody.message ?? errorBody.error, typeof errorBody.detail === "string" ? errorBody.detail : undefined);
+            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)
@@ -395,19 +447,16 @@ 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;
         }
         return fetch(url.toString(), {
             method,
+            redirect: "manual",
             headers,
             body: body ? JSON.stringify(body) : undefined,
             signal,
-            redirect: "error",
-        });
+        }).then(rejectRedirectResponse);
     }
     /** Consume one response body without ever retaining more than `maxBytes`. */
     async readBoundedBody(response, maxBytes, controller) {
@@ -476,7 +525,7 @@ export class FrihetClient {
      * 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) {
+    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();
@@ -491,15 +540,10 @@ export class FrihetClient {
                 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);
+                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);
@@ -511,7 +555,7 @@ export class FrihetClient {
                     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);
+                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"));
@@ -538,8 +582,22 @@ export class FrihetClient {
             clearTimeout(timeoutId);
         }
     }
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    /**
+     * 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 }`
@@ -569,7 +627,7 @@ export class FrihetClient {
      * 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.
      */
@@ -589,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
     // ----------------------------------------------------------------
@@ -615,13 +681,13 @@ 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.
@@ -638,7 +704,7 @@ export class FrihetClient {
      * Resolves to the unwrapped soft-cancel payload on 200, `undefined` on 204.
      */
     async deleteInvoice(id) {
-        return this.requestUnwrapped("DELETE", `/invoices/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("DELETE", `/invoices/${pathSegment(id)}`);
     }
     async searchInvoices(query, params) {
         return this.requestPaginated("GET", "/invoices", undefined, {
@@ -667,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
     // ----------------------------------------------------------------
@@ -691,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
     // ----------------------------------------------------------------
@@ -717,16 +783,16 @@ export class FrihetClient {
         });
     }
     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
     // ----------------------------------------------------------------
@@ -744,13 +810,13 @@ 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}:
@@ -759,7 +825,7 @@ export class FrihetClient {
      * and refuses a protected draft with 409.
      */
     async deleteQuote(id) {
-        return this.requestUnwrapped("DELETE", `/quotes/${encodeURIComponent(id)}`);
+        return this.requestUnwrapped("DELETE", `/quotes/${pathSegment(id)}`);
     }
     // ---------------------------------------------------------------- Vendors
     // ----------------------------------------------------------------
@@ -773,42 +839,52 @@ 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 ? { recipientEmail: 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) {
         // 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") {
+        // 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: doc.contentType,
+            contentType: "application/pdf",
             sizeBytes: doc.sizeBytes,
             base64: encodeBase64(doc.bytes),
             ...(doc.filename ? { filename: doc.filename } : {}),
@@ -817,7 +893,7 @@ export class FrihetClient {
     async getInvoiceEInvoice(invoiceId) {
         // 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 url = `/invoices/${pathSegment(invoiceId)}/xml`;
         const doc = await this.requestDocument("GET", url, undefined, undefined, undefined, (contentType) => {
             const normalized = normalizedContentType(contentType);
             if (normalized === "application/pdf")
@@ -867,15 +943,15 @@ 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 ? { recipientEmail: to } : undefined);
+        return this.requestUnwrapped("POST", `/quotes/${pathSegment(id)}/send`, to ? { recipientEmail: to } : undefined);
     }
     // ---------------------------------------------------------------- Webhooks
     // ----------------------------------------------------------------
@@ -897,7 +973,7 @@ export class FrihetClient {
         };
     }
     async getWebhook(id) {
-        const result = await this.requestUnwrapped("GET", `/webhooks/${encodeURIComponent(id)}`);
+        const result = await this.requestUnwrapped("GET", `/webhooks/${pathSegment(id)}`);
         return normalizeWebhookRecord(result);
     }
     async createWebhook(data) {
@@ -905,50 +981,79 @@ export class FrihetClient {
         return normalizeWebhookRecord(result, typeof data.secret === "string" ? data.secret : undefined);
     }
     async updateWebhook(id, data) {
-        const result = await 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
     // ----------------------------------------------------------------
@@ -965,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
     // ----------------------------------------------------------------
@@ -991,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);
@@ -1004,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)
@@ -1040,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);
@@ -1056,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)
     // ----------------------------------------------------------------
@@ -1069,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, {
@@ -1083,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)
     // ----------------------------------------------------------------
@@ -1098,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, {
@@ -1144,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, {
@@ -1159,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
@@ -1174,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).
@@ -1202,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, {
@@ -1232,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,
         });
     }
@@ -1268,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.
@@ -1297,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.
@@ -1318,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.
@@ -1337,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,
         });
@@ -1348,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,
         });
@@ -1356,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,
@@ -1383,19 +1498,19 @@ 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.requestUnwrapped("GET", "/time-entries/overtime", undefined, {
@@ -1416,7 +1531,7 @@ 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
     // These live read routes return normalized payroll-preparation records in
@@ -1432,17 +1547,13 @@ export class FrihetClient {
             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
     // 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.requestUnwrapped("GET", "/permissions/matrix");
     }
@@ -1454,7 +1565,7 @@ export class FrihetClient {
     // honest ERP 501 responses and are intentionally unchanged here.
     async getCurrentPeriod(params) {
         if (params?.fiscalYear) {
-            return this.requestUnwrapped("GET", `/periods/${encodeURIComponent(params.fiscalYear)}`);
+            return this.requestUnwrapped("GET", `/periods/${pathSegment(params.fiscalYear)}`);
         }
         return this.requestUnwrapped("GET", "/periods/current");
     }
@@ -1462,7 +1573,7 @@ export class FrihetClient {
         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