@frihet/mcp-server 1.17.0 → 2.0.1

package/dist/tools/clients.js

@@ -13,6 +13,171 @@ const addressSchema = z
 })
     .optional()
     .describe("Client address / Direccion del cliente");
+/**
+ * Splits a concatenated / camelCase / snake_case / kebab-case search query into
+ * space-separated tokens (e.g. "CanariasBlue" -> "Canarias Blue",
+ * "SLCanarias" -> "SL Canarias", "Canarias_Blue" -> "Canarias Blue").
+ */
+function splitCompoundQuery(q) {
+    return q
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const OPTIONAL_CLIENT_STRING_FIELDS = [
+    "email",
+    "phone",
+    "stage",
+    "taxId",
+    "createdAt",
+    "updatedAt",
+];
+/**
+ * Normalizes a client record returned by the Frihet API so it always satisfies
+ * `clientItemOutput` without losing ERP-canonical data:
+ *  - Strips `null` on optional string fields (`email`, `phone`, `stage`, `taxId`,
+ *    `createdAt`, `updatedAt`) so `z.string().optional()` never rejects legacy docs.
+ *  - Backfills `taxId` from legacy `nif` / `cif` / `vatNumber` / `tax_id` when
+ *    `taxId` is absent or null, preserving all original fields.
+ *  - Converts legacy string `address` into `{ street }`.
+ *  - Omits `null` or empty `address` (which otherwise fails `addressOutputSchema`).
+ *  - Maps ERP canonical address keys (`province` -> `state`, `zip` -> `postalCode`,
+ *    `countryCode` -> `country`) because `publicApi.ts` (`normalizeAddress`) stores
+ *    `zip` and `province`, whereas `addressOutputSchema` only declares `postalCode`
+ *    and `state` (and strips unknown keys in `structuredContent`).
+ */
+function normalizeClientRecord(clientRecord) {
+    if (!clientRecord || typeof clientRecord !== "object" || Array.isArray(clientRecord)) {
+        return clientRecord;
+    }
+    const out = { ...clientRecord };
+    for (const field of OPTIONAL_CLIENT_STRING_FIELDS) {
+        if (out[field] === null) {
+            delete out[field];
+        }
+    }
+    if (typeof out.taxId !== "string" || !out.taxId.trim()) {
+        for (const alias of ["nif", "cif", "vatNumber", "tax_id"]) {
+            const candidate = out[alias];
+            if (typeof candidate === "string" && candidate.trim()) {
+                out.taxId = candidate.trim();
+                break;
+            }
+        }
+    }
+    const rawAddress = out.address;
+    const rootStreet = typeof out.street === "string" && out.street.trim() ? out.street.trim() : undefined;
+    const rootCity = typeof out.city === "string" && out.city.trim() ? out.city.trim() : undefined;
+    const rootState = typeof out.state === "string" && out.state.trim()
+        ? out.state.trim()
+        : typeof out.province === "string" && out.province.trim()
+            ? out.province.trim()
+            : undefined;
+    const rootPostalCode = typeof out.postalCode === "string" && out.postalCode.trim()
+        ? out.postalCode.trim()
+        : typeof out.zip === "string" && out.zip.trim()
+            ? out.zip.trim()
+            : undefined;
+    const rootCountry = typeof out.country === "string" && out.country.trim()
+        ? out.country.trim()
+        : typeof out.countryCode === "string" && out.countryCode.trim()
+            ? out.countryCode.trim()
+            : undefined;
+    const buildFlatAddress = (streetOverride) => {
+        const built = {};
+        const st = streetOverride ?? rootStreet;
+        if (st !== undefined)
+            built.street = st;
+        if (rootCity !== undefined)
+            built.city = rootCity;
+        if (rootState !== undefined)
+            built.state = rootState;
+        if (rootPostalCode !== undefined)
+            built.postalCode = rootPostalCode;
+        if (rootCountry !== undefined)
+            built.country = rootCountry;
+        return Object.keys(built).length > 0 ? built : undefined;
+    };
+    if (rawAddress === undefined || rawAddress === null) {
+        if (rawAddress === null) {
+            delete out.address;
+        }
+        const flatAddr = buildFlatAddress();
+        if (flatAddr) {
+            out.address = flatAddr;
+        }
+        return out;
+    }
+    if (typeof rawAddress === "string") {
+        const trimmed = rawAddress.trim();
+        const flatAddr = buildFlatAddress(trimmed || undefined);
+        if (!flatAddr) {
+            delete out.address;
+            return out;
+        }
+        out.address = flatAddr;
+        return out;
+    }
+    if (typeof rawAddress === "object" && !Array.isArray(rawAddress)) {
+        const addrObj = rawAddress;
+        const normalizedAddress = {};
+        for (const [k, v] of Object.entries(addrObj)) {
+            if (v !== null && v !== undefined) {
+                normalizedAddress[k] = v;
+            }
+        }
+        const street = typeof addrObj.street === "string" && addrObj.street.trim()
+            ? addrObj.street.trim()
+            : rootStreet;
+        const city = typeof addrObj.city === "string" && addrObj.city.trim()
+            ? addrObj.city.trim()
+            : rootCity;
+        const state = typeof addrObj.state === "string" && addrObj.state.trim()
+            ? addrObj.state.trim()
+            : typeof addrObj.province === "string" && addrObj.province.trim()
+                ? addrObj.province.trim()
+                : rootState;
+        const postalCode = typeof addrObj.postalCode === "string" && addrObj.postalCode.trim()
+            ? addrObj.postalCode.trim()
+            : typeof addrObj.zip === "string" && addrObj.zip.trim()
+                ? addrObj.zip.trim()
+                : rootPostalCode;
+        const country = typeof addrObj.country === "string" && addrObj.country.trim()
+            ? addrObj.country.trim()
+            : typeof addrObj.countryCode === "string" && addrObj.countryCode.trim()
+                ? addrObj.countryCode.trim()
+                : rootCountry;
+        if (street !== undefined)
+            normalizedAddress.street = street;
+        else
+            delete normalizedAddress.street;
+        if (city !== undefined)
+            normalizedAddress.city = city;
+        else
+            delete normalizedAddress.city;
+        if (state !== undefined)
+            normalizedAddress.state = state;
+        else
+            delete normalizedAddress.state;
+        if (postalCode !== undefined)
+            normalizedAddress.postalCode = postalCode;
+        else
+            delete normalizedAddress.postalCode;
+        if (country !== undefined)
+            normalizedAddress.country = country;
+        else
+            delete normalizedAddress.country;
+        if (Object.keys(normalizedAddress).length === 0) {
+            delete out.address;
+            return out;
+        }
+        out.address = normalizedAddress;
+        return out;
+    }
+    return out;
+}
 export function registerClientTools(server, client) {
     // -- list_clients --
     server.registerTool("list_clients", {
@@ -44,10 +209,93 @@ export function registerClientTools(server, client) {
         },
         outputSchema: paginatedOutput(clientItemOutput, { projectable: true }),
     }, async ({ limit, offset, q, stage, fields, after }) => withToolLogging("list_clients", async () => {
-        const result = await client.listClients({ limit, offset, after, fields, q, stage });
+        const trimmedQ = q?.trim();
+        const trimmedAfter = after?.trim();
+        // Limitation in Frihet-ERP `listResources` (publicApi.ts L8158-8268):
+        // When `search` (`q`) is provided, the backend slices results by `offset`/`limit`
+        // and returns before evaluating `cursorParam` (`after`). Moreover, protected
+        // profiles (Claude `claudeToolResult` and OpenAI `applyOpenAIProfile`) rebuild
+        // `content` from `structuredContent` while `paginatedOutput` is frozen, so a
+        // text-only note would be silently discarded. Fail closed (`isError: true`
+        // without `structuredContent`) so no profile mistakes page 1 for a cursor page.
+        if (trimmedQ && trimmedAfter) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: text search ('q') cannot be combined with cursor pagination ('after') because the ERP backend slices search results by 'offset'/'limit' and ignores 'after'. Use 'offset' and 'limit' when searching with 'q', or omit 'q' when paginating with 'after'. / " +
+                            "Error: la busqueda textual ('q') no se puede combinar con el cursor 'after' porque el backend pagina las busquedas mediante 'offset'/'limit' e ignora 'after'. Usa 'offset' y 'limit' con 'q', u omite 'q' al paginar con 'after'.",
+                    }],
+                isError: true,
+                _meta: { "io.frihet/cursorWithQueryUnsupported": true },
+            };
+        }
+        let result = await client.listClients({ limit, offset, after, fields, q, stage });
+        // When a concatenated / camelCase query (e.g. "CanariasBlue") yields zero total matches,
+        // retry with split tokens ("Canarias Blue") using the same offset/limit/fields/stage.
+        // Guardrails matching publicApi.ts `listResources`:
+        //  1. Never fallback when `after` cursor is supplied with `q`.
+        //  2. Never fallback when the first scan hit the 500-document cap (`truncated === true`),
+        //     since total===0 only reflects the first 500 scanned records.
+        //  3. On page 2+ (`offset > 0`), only fallback when `result.total === 0` explicitly (not
+        //     when `total === undefined`, which indicates an exhausted offset).
+        let usedFallback = false;
+        const splitQ = trimmedQ ? splitCompoundQuery(trimmedQ) : undefined;
+        const isSubsequentPage = (offset !== undefined && offset > 0) || Boolean(after);
+        const initialTruncated = result?.truncated === true;
+        const canFallback = splitQ !== undefined && splitQ !== trimmedQ && !after && !initialTruncated;
+        const hasZeroTotalMatches = Array.isArray(result?.data) &&
+            result.data.length === 0 &&
+            (isSubsequentPage ? result.total === 0 : result.total === 0 || result.total === undefined);
+        if (canFallback && hasZeroTotalMatches) {
+            try {
+                const fallbackResult = await client.listClients({ limit, offset, after, fields, q: splitQ, stage });
+                const fallbackTruncated = fallbackResult?.truncated === true;
+                if (fallbackTruncated ||
+                    (fallbackResult?.data && (fallbackResult.data.length > 0 || (fallbackResult.total !== undefined && fallbackResult.total > 0)))) {
+                    result = fallbackResult;
+                    usedFallback = true;
+                }
+            }
+            catch {
+                // Preserve original response if fallback fails
+            }
+        }
+        const rawEnvelope = (result ?? {});
+        const isTruncated = rawEnvelope.truncated === true;
+        const normalizedData = Array.isArray(result?.data)
+            ? result.data.map((c) => (c && typeof c === "object" ? normalizeClientRecord(c) : c))
+            : [];
+        // Conservative refusal when the ERP 500-document scan cap was saturated (`truncated: true`).
+        // Because `paginatedOutput` is a frozen schema contract and both Claude (`claudeToolResult`)
+        // and OpenAI (`applyOpenAIProfile`) overwrite `content` whenever `structuredContent` is
+        // present, returning `structuredContent` here would hide the truncation warning and present
+        // an incomplete 500-doc scan as exhaustive.
+        if (isTruncated) {
+            const partialCount = typeof result?.total === "number" ? result.total : normalizedData.length;
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: client search hit the ERP 500-document scan cap (truncated=true; ${partialCount} match(es) within the first 500 scanned records) and cannot be returned as an exhaustive result across protected profiles. Narrow 'q' (or filter by 'stage') or paginate without 'q' using 'after'. / ` +
+                            `Error: la busqueda de clientes alcanzo el limite de escaneo de 500 documentos del ERP (truncated=true; ${partialCount} coincidencia(s) en los primeros 500 registros) y no puede devolverse como resultado exhaustivo. Acota 'q' (o filtra por 'stage') o pagina sin 'q' usando 'after'.`,
+                    }],
+                isError: true,
+                _meta: { "io.frihet/searchScanTruncated": true },
+            };
+        }
+        const cleanEnvelope = {
+            data: normalizedData,
+            total: typeof result?.total === "number" ? result.total : normalizedData.length,
+            limit: typeof result?.limit === "number" ? result.limit : (limit ?? 20),
+            offset: typeof result?.offset === "number" ? result.offset : (offset ?? 0),
+            ...(typeof result?.nextCursor === "string" ? { nextCursor: result.nextCursor } : {}),
+        };
+        const notes = [];
+        if (usedFallback) {
+            notes.push(` (criterio aplicado: "${splitQ}")`);
+        }
         return {
-            content: [listContent(formatPaginatedResponse("clients", result))],
-            structuredContent: result,
+            content: [listContent(formatPaginatedResponse("clients", cleanEnvelope) + notes.join(""))],
+            structuredContent: cleanEnvelope,
         };
     }));
     // -- get_client --
@@ -61,7 +309,7 @@ export function registerClientTools(server, client) {
         },
         outputSchema: clientItemOutput,
     }, async ({ id }) => withToolLogging("get_client", async () => {
-        const result = await client.getClient(id);
+        const result = normalizeClientRecord(await client.getClient(id));
         return {
             content: [getContent(formatRecord("Client", result))],
             structuredContent: result,
@@ -85,7 +333,7 @@ export function registerClientTools(server, client) {
         },
         outputSchema: clientItemOutput,
     }, async (input) => withToolLogging("create_client", async () => {
-        const result = await client.createClient(input);
+        const result = normalizeClientRecord(await client.createClient(input));
         const hints = enrichResponse("clients", "create", result);
         return {
             content: [mutateContent(formatRecord("Client created", result) + hints)],
@@ -109,7 +357,7 @@ export function registerClientTools(server, client) {
         },
         outputSchema: clientItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_client", async () => {
-        const result = await client.updateClient(id, data);
+        const result = normalizeClientRecord(await client.updateClient(id, data));
         return {
             content: [mutateContent(formatRecord("Client updated", result))],
             structuredContent: result,

package/dist/tools/deposits.js

@@ -2,7 +2,14 @@
  * Deposit tools for the Frihet MCP server.
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, deleteResultOutput, depositItemOutput, actionResultOutput } from "./shared.js";
+import { applyDepositFields, depositFields, DepositInputError } from "../deposit-contract.js";
+import { withToolLogging, confirmationRequiredError, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, ERROR_CONTENT_ANNOTATIONS, paginatedOutput, deleteResultOutput, depositItemOutput, actionResultOutput } from "./shared.js";
+function depositValidationResponse(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${error.message}`, annotations: ERROR_CONTENT_ANNOTATIONS }],
+    };
+}
 export function registerDepositTools(server, client) {
     // -- list_deposits --
     server.registerTool("list_deposits", {
@@ -69,69 +76,71 @@ export function registerDepositTools(server, client) {
     // -- create_deposit --
     server.registerTool("create_deposit", {
         title: "Create Deposit",
-        description: "Record a new deposit from a client. Requires clientId and amount. " +
-            "Useful for tracking advance payments, retainers, and security deposits. " +
-            "Example: clientId='abc123', amount=500, currency='EUR', description='Project retainer' " +
-            "/ Registra un nuevo deposito de un cliente. Requiere clientId e importe. " +
-            "Util para adelantos, retenciones y depositos de garantia.",
+        description: "Record a deposit in Frihet's bookkeeping; no money is transferred. Requires clientId, clientName, amount, date and description. " +
+            "The API initializes status='active'; status and notes are not writable. " +
+            "Example: clientId='abc123', clientName='Example Client', amount=500, date='2026-10-21', description='Project retainer' " +
+            "/ Registra un depósito contable sin transferir dinero. Requiere clientId, clientName, amount, date y description. " +
+            "La API inicia el estado 'active'; status y notes no son campos editables.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            clientName: z.string().optional().describe("Client name (denormalized) / Nombre del cliente"),
-            amount: z.number().describe("Deposit amount / Importe del deposito"),
-            currency: z.string().optional().describe("Currency code (e.g. 'EUR', 'USD') / Codigo de moneda"),
-            date: z
-                .string()
-                .optional()
-                .describe("Deposit date in ISO 8601 (YYYY-MM-DD) / Fecha del deposito"),
-            description: z.string().optional().describe("Deposit description / Descripcion del deposito"),
-            status: z
-                .string()
-                .optional()
-                .describe("Status (e.g. 'pending', 'applied', 'refunded') / Estado"),
-            paymentMethod: z
-                .string()
-                .optional()
-                .describe("Payment method (e.g. 'bank_transfer', 'card') / Metodo de pago"),
-            reference: z.string().optional().describe("External reference or receipt number / Referencia externa"),
-            notes: z.string().optional().describe("Internal notes / Notas internas"),
-        },
+        inputSchema: z.object({
+            clientId: depositFields.clientId.describe("Client ID / ID del cliente"),
+            clientName: depositFields.clientName.describe("Client name / Nombre del cliente"),
+            amount: depositFields.amount.describe("Positive deposit amount / Importe positivo del depósito"),
+            currency: depositFields.currency.optional().describe("Currency code, defaults to EUR / Moneda, EUR por defecto"),
+            date: depositFields.receivedDate.describe("Received date (YYYY-MM-DD), sent as receivedDate / Fecha de recepción"),
+            description: depositFields.description.describe("Deposit description / Descripción del depósito"),
+            paymentMethod: depositFields.paymentMethod.describe("Payment method (e.g. bank_transfer) / Método de pago"),
+            reference: depositFields.paymentReference.describe("Payment reference, sent as paymentReference / Referencia del pago"),
+        }).strict(),
         outputSchema: depositItemOutput,
     }, async (input) => withToolLogging("create_deposit", async () => {
-        const result = await client.createDeposit(input);
-        const hints = enrichResponse("deposits", "create", result);
-        return {
-            content: [mutateContent(formatRecord("Deposit created", result) + hints)],
-            structuredContent: { ...result },
-        };
+        try {
+            const result = await client.createDeposit(input);
+            const hints = enrichResponse("deposits", "create", result);
+            return {
+                content: [mutateContent(formatRecord("Deposit created", result) + hints)],
+                structuredContent: { ...result },
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- update_deposit --
     server.registerTool("update_deposit", {
         title: "Update Deposit",
         description: "Update an existing deposit using PATCH semantics. Only the provided fields will be changed. " +
-            "Example: id='abc123', amount=750, notes='Updated retainer amount' " +
-            "/ Actualiza un deposito existente. Solo se modifican los campos proporcionados.",
+            "At least one writable field is required; status and notes are not writable. " +
+            "Example: id='abc123', reference='RECEIPT-42' " +
+            "/ Actualiza un depósito existente. Requiere al menos un campo editable; status y notes no se pueden guardar.",
         annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            clientId: z.string().optional().describe("Client ID / ID del cliente"),
-            clientName: z.string().optional().describe("Client name / Nombre del cliente"),
-            amount: z.number().optional().describe("Amount / Importe"),
-            currency: z.string().optional().describe("Currency code / Moneda"),
-            date: z.string().optional().describe("Date (YYYY-MM-DD) / Fecha"),
-            description: z.string().optional().describe("Description / Descripcion"),
-            status: z.string().optional().describe("Status / Estado"),
-            paymentMethod: z.string().optional().describe("Payment method / Metodo de pago"),
-            reference: z.string().optional().describe("Reference / Referencia"),
-            notes: z.string().optional().describe("Notes / Notas"),
-        },
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del depósito"),
+            clientId: depositFields.clientId.optional().describe("Client ID / ID del cliente"),
+            clientName: depositFields.clientName.optional().describe("Client name / Nombre del cliente"),
+            amount: depositFields.amount.optional().describe("Positive amount / Importe positivo"),
+            currency: depositFields.currency.optional().describe("Currency code / Moneda"),
+            date: depositFields.receivedDate.optional().describe("Received date (YYYY-MM-DD) / Fecha de recepción"),
+            description: depositFields.description.optional().describe("Description / Descripción"),
+            paymentMethod: depositFields.paymentMethod.describe("Payment method / Método de pago"),
+            reference: depositFields.paymentReference.describe("Payment reference / Referencia del pago"),
+        }).strict().refine(({ id: _id, ...fields }) => Object.values(fields).some((value) => value !== undefined), { message: "Provide at least one writable deposit field / Indica al menos un campo del depósito" }),
         outputSchema: depositItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_deposit", async () => {
-        const result = await client.updateDeposit(id, data);
-        return {
-            content: [mutateContent(formatRecord("Deposit updated", result))],
-            structuredContent: result,
-        };
+        try {
+            const result = await client.updateDeposit(id, data);
+            return {
+                content: [mutateContent(formatRecord("Deposit updated", result))],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- delete_deposit --
     server.registerTool("delete_deposit", {
@@ -156,62 +165,63 @@ export function registerDepositTools(server, client) {
         title: "Apply Deposit",
         description: "Apply a deposit to an invoice or mark it as used. " +
             "Transitions the deposit status to 'applied'. " +
-            "Example: id='dep_abc123', invoiceId='inv_xyz' " +
-            "/ Aplica un deposito a una factura o lo marca como utilizado.",
+            "ERP requires invoiceId + invoiceNumber + amount on the body; id is the deposit ID; notes is not writable. " +
+            "Example: id='dep_abc123', invoiceId='inv_xyz', invoiceNumber='F-2026-007', amount=150 " +
+            "/ Aplica un deposito a una factura o lo marca como utilizado. Requiere invoiceId, invoiceNumber y amount; notes no se puede guardar.",
         annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            invoiceId: z
-                .string()
-                .optional()
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del deposito"),
+            invoiceId: applyDepositFields.invoiceId
                 .describe("Invoice ID to apply the deposit to / ID de la factura a la que aplicar el deposito"),
-            notes: z.string().optional().describe("Application notes / Notas de aplicacion"),
-        },
+            invoiceNumber: applyDepositFields.invoiceNumber
+                .describe("Invoice number (document number) the deposit applies to / Numero de la factura"),
+            amount: applyDepositFields.amount
+                .describe("Amount of the deposit to apply in EUR / Importe del deposito a aplicar en EUR"),
+        }).strict(),
         outputSchema: actionResultOutput,
     }, async ({ id, ...data }) => withToolLogging("apply_deposit", async () => {
-        const result = await client.applyDeposit(id, data);
-        return {
-            content: [mutateContent(formatRecord("Deposit applied", result))],
-            structuredContent: result,
-        };
+        try {
+            const result = await client.applyDeposit(id, data);
+            return {
+                content: [mutateContent(formatRecord("Deposit applied", result))],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- refund_deposit --
     server.registerTool("refund_deposit", {
-        title: "Refund Deposit",
-        description: "Refund a deposit back to the client. Requires confirm=true. " +
-            "Transitions the deposit status to 'refunded' — a money movement that is not reversible " +
-            "from this tool. " +
-            "Example: id='dep_abc123', reason='Project cancelled', confirm=true " +
-            "/ Devuelve un deposito al cliente. Requiere confirm=true. " +
-            "Es un movimiento de dinero que no se puede revertir desde esta herramienta.",
-        annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            reason: z.string().optional().describe("Reason for the refund / Motivo de la devolucion"),
-            notes: z.string().optional().describe("Refund notes / Notas de la devolucion"),
+        title: "Record Deposit Refund",
+        description: "Record a full or partial deposit refund in Frihet's bookkeeping; no money is transferred. Requires confirm=true. " +
+            "Omit amount to record a refund of the remaining balance. Only a full refund sets status='refunded'. " +
+            "A new call can record another partial refund; after an uncertain result, check get_deposit before retrying. " +
+            "Example: id='dep_abc123', amount=50, confirm=true " +
+            "/ Registra una devolución total o parcial del depósito sin transferir dinero. Requiere confirm=true. " +
+            "Omite amount para registrar la devolución del saldo restante. Solo la devolución total marca el estado 'refunded'. " +
+            "Una nueva llamada puede registrar otra devolución parcial; ante un resultado incierto, consulta get_deposit antes de repetir.",
+        annotations: { ...UPDATE_ANNOTATIONS, destructiveHint: true, idempotentHint: false },
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del depósito"),
+            amount: z.number().positive().optional().describe("Positive refund amount in the deposit currency; omit for the remaining balance / Importe positivo en la moneda del depósito; omite para el saldo restante"),
             confirm: z
                 .boolean()
-                .describe("Must be true to confirm the refund / Debe ser true para confirmar la devolucion"),
-        },
+                .describe("Must be true to record the refund; no money is transferred / Debe ser true para registrar la devolución; no se transfiere dinero"),
+        }).strict(),
         outputSchema: actionResultOutput,
-    }, async ({ id, confirm, ...data }) => withToolLogging("refund_deposit", async () => {
-        if (!confirm) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: confirm=true is required to refund a deposit. " +
-                            "This returns the client's money and sets the deposit to status=refunded; " +
-                            "there is no un-refund tool. Set confirm=true when you are certain. / " +
-                            "Se requiere confirm=true para devolver un deposito. Es un movimiento de dinero irreversible.",
-                    },
-                ],
-                isError: true,
-            };
+    }, async ({ id, confirm, amount }) => withToolLogging("refund_deposit", async () => {
+        if (confirm !== true) {
+            return confirmationRequiredError("Error: confirm=true is required to record a deposit refund. " +
+                "This reduces the recorded remaining balance; no money is transferred and this tool cannot undo the entry. / " +
+                "Se requiere confirm=true para registrar la devolución y reducir el saldo contable. " +
+                "No se transfiere dinero y esta herramienta no permite deshacer el registro.");
         }
-        const result = await client.refundDeposit(id, data);
+        const result = await client.refundDeposit(id, amount === undefined ? {} : { amount });
         return {
-            content: [mutateContent(formatRecord("Deposit refunded", result))],
+            content: [mutateContent(formatRecord("Deposit refund recorded (no money transferred)", result))],
             structuredContent: result,
         };
     }));

package/dist/tools/einvoice.d.ts

@@ -48,19 +48,33 @@ import type { IFrihetClient } from "../client-interface.js";
  * | facturae               | Facturae  | Spain (ES B2G mandatory) | Facturae 3.2.x — AEAT/FACe submission              |
  */
 export declare const eInvoiceFormatSchema: z.ZodEnum<{
+    facturae: "facturae";
     "xrechnung-cii": "xrechnung-cii";
     "xrechnung-ubl": "xrechnung-ubl";
     "facturx-en16931": "facturx-en16931";
+    fatturapa: "fatturapa";
+    "peppol-bis-3": "peppol-bis-3";
+    ubl: "ubl";
+    cii: "cii";
     "facturx-extended": "facturx-extended";
     "facturx-basic": "facturx-basic";
     "facturx-minimum": "facturx-minimum";
+}>;
+export type EInvoiceFormat = z.infer<typeof eInvoiceFormatSchema>;
+/** Export is narrower than dispatch/validation. The ERP public export API
+ * exposes Factur-X EN16931 only; accepting Extended/Basic/Minimum here and
+ * silently mapping them to EN16931 would produce the wrong fiscal profile. */
+export declare const eInvoiceExportFormatSchema: z.ZodEnum<{
+    facturae: "facturae";
+    "xrechnung-cii": "xrechnung-cii";
+    "xrechnung-ubl": "xrechnung-ubl";
+    "facturx-en16931": "facturx-en16931";
     fatturapa: "fatturapa";
+    "peppol-bis-3": "peppol-bis-3";
+    "fa-2-ksef": "fa-2-ksef";
     ubl: "ubl";
     cii: "cii";
-    "peppol-bis-3": "peppol-bis-3";
-    facturae: "facturae";
 }>;
-export type EInvoiceFormat = z.infer<typeof eInvoiceFormatSchema>;
 export declare const sendEInvoiceOutput: z.ZodObject<{
     workflowRunId: z.ZodString;
     status: z.ZodLiteral<"queued">;