@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/client-interface.d.ts

@@ -5,7 +5,7 @@
  * classes satisfy this interface via structural typing. Tool registration
  * functions depend on this interface so they can work with either client.
  */
-import type { PaginatedResponse } from "./types.js";
+import type { CreateWebhookInput, CreateWebhookResult, PaginatedResponse, UpdateWebhookInput, Webhook } from "./types.js";
 export interface IFrihetClient {
     listInvoices(params?: {
         limit?: number;
@@ -21,7 +21,12 @@ export interface IFrihetClient {
     getInvoice(id: string): Promise<Record<string, unknown>>;
     createInvoice(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateInvoice(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteInvoice(id: string): Promise<void>;
+    /**
+     * Resolves to the soft-cancel payload when the backend answered 200 (non-draft
+     * invoice CANCELLED, not destroyed — VeriFactu hash chain), or void/undefined
+     * when it answered 204 (draft really removed). See `FrihetClient.deleteInvoice`.
+     */
+    deleteInvoice(id: string): Promise<Record<string, unknown> | void>;
     searchInvoices(query: string, params?: {
         limit?: number;
         offset?: number;
@@ -83,7 +88,8 @@ export interface IFrihetClient {
     getQuote(id: string): Promise<Record<string, unknown>>;
     createQuote(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateQuote(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteQuote(id: string): Promise<void>;
+    /** Same 200-cancel / 204-destroy contract as {@link IFrihetClient.deleteInvoice}. */
+    deleteQuote(id: string): Promise<Record<string, unknown> | void>;
     listVendors(params?: {
         q?: string;
         limit?: number;
@@ -97,8 +103,8 @@ export interface IFrihetClient {
     deleteVendor(id: string): Promise<void>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
-    getInvoicePdf(id: string): Promise<Record<string, unknown>>;
-    getInvoiceEInvoice(invoiceId: string): Promise<any>;
+    getInvoicePdf(id: string): Promise<import("./client.js").BinaryDocument>;
+    getInvoiceEInvoice(invoiceId: string): Promise<import("./client.js").EInvoiceDocument>;
     createCreditNote(invoiceId: string, data: {
         reason: string;
         reasonDescription?: string;
@@ -110,14 +116,31 @@ export interface IFrihetClient {
         daysOverdue?: number;
     }): Promise<any>;
     sendQuote(id: string, to?: string): Promise<Record<string, unknown>>;
-    listWebhooks(params?: {
+    listWebhooks(): Promise<{
+        data: Webhook[];
+        total: number;
+        _demo?: true;
+        _demoNotice?: string;
+    }>;
+    getWebhook(id: string): Promise<Webhook>;
+    createWebhook(data: CreateWebhookInput): Promise<CreateWebhookResult>;
+    updateWebhook(id: string, data: UpdateWebhookInput): Promise<Webhook>;
+    deleteWebhook(id: string): Promise<void>;
+    globalSearch(params: {
+        q: string;
+        types?: ReadonlyArray<"invoices" | "expenses" | "vendors" | "clients" | "products">;
         limit?: number;
         offset?: number;
-    }): Promise<PaginatedResponse<Record<string, unknown>>>;
-    getWebhook(id: string): Promise<Record<string, unknown>>;
-    createWebhook(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    updateWebhook(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteWebhook(id: string): Promise<void>;
+    }): Promise<{
+        data: Record<string, unknown>[];
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+        query: string;
+        types: ReadonlyArray<"invoices" | "expenses" | "vendors" | "clients" | "products">;
+        truncated?: boolean;
+    }>;
     listClientContacts(clientId: string, params?: {
         limit?: number;
         offset?: number;
@@ -198,14 +221,9 @@ export interface IFrihetClient {
     }>;
     exportEInvoice(params: {
         invoiceId: string;
-        format: string;
+        format: import("./client.js").McpEInvoiceExportFormat;
         signed?: boolean;
-    }): Promise<{
-        xmlUrl: string;
-        filename: string;
-        format: string;
-        signed: boolean;
-    }>;
+    }): Promise<import("./client.js").EInvoiceExportResult>;
     faceSubmit(params: {
         invoiceId: string;
         mode: "mock" | "sandbox" | "production";
@@ -379,7 +397,7 @@ export interface IFrihetClient {
     updateTeamMemberRole(memberId: string, role: string): Promise<Record<string, unknown>>;
     removeTeamMember(memberId: string): Promise<void>;
     approveGLEntry(entryId: string, notes?: string): Promise<Record<string, unknown>>;
-    rejectGLEntry(entryId: string, reason: string): Promise<Record<string, unknown>>;
+    rejectGLEntry(entryId: string, note: string): Promise<Record<string, unknown>>;
     getGLEntryAuditLog(entryId: string): Promise<Record<string, unknown>>;
     addCustomPortalDomain(data: {
         domain: string;
@@ -421,15 +439,13 @@ export interface IFrihetClient {
     }): Promise<import("./types.js").PaginatedResponse<Record<string, unknown>>>;
     createBankRule(data: {
         name: string;
-        conditions: Array<{
+        bankConditions: Array<{
             field: string;
             operator: string;
             value: string;
         }>;
-        actions: Array<{
-            type: string;
-            value: string;
-        }>;
+        action: string;
+        actionConfig: Record<string, unknown>;
         isActive?: boolean;
     }): Promise<Record<string, unknown>>;
     sendGestoriaMessage(data: {
@@ -472,7 +488,9 @@ export interface IFrihetClient {
         };
     }): Promise<Record<string, unknown>>;
     getGestoriaAgingConsolidated(params?: {
-        ownerUid?: string;
+        workspaceIds?: string[];
+        asOf?: string;
+        bustCache?: boolean;
     }): Promise<Record<string, unknown>>;
     listLeaves(params?: {
         employeeId?: string;
@@ -501,8 +519,8 @@ export interface IFrihetClient {
         employeeId: string;
         mood?: string;
         location?: string;
-    }): Promise<Record<string, unknown>>;
-    attendanceClockOut(entryId: string): Promise<Record<string, unknown>>;
+    }, idempotencyKey?: string): Promise<Record<string, unknown>>;
+    attendanceClockOut(entryId: string, idempotencyKey?: string): Promise<Record<string, unknown>>;
     getOvertimeReport(params: {
         period: string;
         employeeId?: string;
@@ -519,20 +537,16 @@ export interface IFrihetClient {
         eventType?: string;
     }): Promise<Record<string, unknown>>;
     exportPayroll(params: {
-        format: "a3" | "contasol" | "sage" | "holded" | "siltra";
+        format: "a3" | "contasol" | "sage" | "siltra";
         month: string;
     }): Promise<Record<string, unknown>>;
     getPayrollChecklist(params: {
         month: string;
     }): Promise<Record<string, unknown>>;
-    getOnboardingStatus(): Promise<Record<string, unknown>>;
-    setOnboardingPersona(data: {
-        persona: "autonomo" | "empresa" | "agencia" | "gestoria";
-    }): Promise<Record<string, unknown>>;
     getPermissionsMatrix(): Promise<Record<string, unknown>>;
     getMyPermissions(): Promise<Record<string, unknown>>;
     getCurrentPeriod(params?: {
-        periodId?: string;
+        fiscalYear?: string;
     }): Promise<Record<string, unknown>>;
     closePeriod(data: {
         type: "monthly" | "quarterly";

package/dist/client.d.ts

@@ -11,11 +11,82 @@
  * (`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 type { PaginatedResponse } from "./types.js";
+import type { CreateWebhookInput, CreateWebhookResult, PaginatedResponse, UpdateWebhookInput, Webhook } from "./types.js";
+/**
+ * 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 declare const MAX_PDF_BYTES: number;
+export declare const MAX_XML_BYTES: number;
+/**
+ * Bounded binary document response. Always base64-encoded because MCP
+ * `structuredContent` is JSON-only — raw `Uint8Array` would coerce to a
+ * sparse object on the wire.
+ */
+export interface BinaryDocument {
+    /** Echoed id from the request (invoice id), so callers can correlate. */
+    id: string;
+    /** Verbatim `Content-Type` from the response (e.g. `application/pdf`). */
+    contentType: string;
+    /** Byte length of the decoded body. Equal to the decoded base64 byte length. */
+    sizeBytes: number;
+    /** Base64-encoded bytes. */
+    base64: string;
+    /** Filename hint parsed from `Content-Disposition`, when present. */
+    filename?: string;
+}
+/**
+ * Bounded XML document response (UBL / CII / Facturae / PEPPOL / FatturaPA /
+ * XRechnung — anything declared `application/xml` or `text/xml`).
+ */
+export interface XmlDocument {
+    /** Echoed id from the request (invoice id). */
+    id: string;
+    /** Strictly decoded UTF-8 XML text. */
+    xml: string;
+    /** Verbatim `Content-Type` from the response. */
+    contentType: string;
+    /** Byte length of the decoded UTF-8 body. */
+    sizeBytes: number;
+    /** Filename hint parsed from `Content-Disposition`, when present. */
+    filename?: string;
+}
+/** `/invoices/:id/xml` serves XML or a Factur-X PDF, depending on storage MIME. */
+export type EInvoiceDocument = XmlDocument | BinaryDocument;
+/** Ergonomic values accepted by the MCP `einvoice_export` tool. This is
+ * deliberately narrower than the asynchronous dispatch/validation format
+ * family: the public export API exposes only the EN16931 Factur-X profile. */
+export type McpEInvoiceExportFormat = "facturae" | "xrechnung-cii" | "xrechnung-ubl" | "facturx-en16931" | "fatturapa" | "peppol-bis-3" | "fa-2-ksef" | "ubl" | "cii";
+/** Exact, case-sensitive enum accepted by the ERP export endpoint. */
+export type ApiEInvoiceExportFormat = "Facturae" | "XRechnung-CII" | "XRechnung-UBL" | "Factur-X" | "FatturaPA" | "PEPPOL-BIS-3" | "FA-2-KSeF" | "UBL" | "CII";
+export interface EInvoiceExportResult {
+    xml: string;
+    contentType: string;
+    filename: string;
+    signed: boolean;
+    format: ApiEInvoiceExportFormat;
+}
+export declare function isLocalInputValidationError(error: unknown): boolean;
+export declare function toApiEInvoiceExportFormat(format: string): ApiEInvoiceExportFormat;
 export declare class FrihetApiError extends Error {
     readonly statusCode: number;
     readonly errorCode: string;
-    constructor(statusCode: number, errorCode: string, message?: string);
+    readonly detail?: string | undefined;
+    /** Backend correlation id (`meta.requestId` or `X-Request-Id`); carried for diagnostics, never echoed to agents. */
+    readonly requestId?: string | undefined;
+    constructor(statusCode: number, errorCode: string, message?: string, detail?: string | undefined, 
+    /** Backend correlation id (`meta.requestId` or `X-Request-Id`); carried for diagnostics, never echoed to agents. */
+    requestId?: string | undefined);
 }
 export interface FrihetClientOptions {
     /**
@@ -23,14 +94,44 @@ export interface FrihetClientOptions {
      * Cloudflare Workers should pass ≤25000 to leave margin under the ~30s limit.
      */
     timeoutMs?: number;
+    /**
+     * Cumulative time one call may sleep across 429 retries. A server-requested
+     * wait that does not fit is never shortened: the call fails with a
+     * `rate_limit_deferred` error carrying the wait to honor. Defaults to 30000.
+     */
+    retryBudgetMs?: number;
+    /** Test seams: timer and wall clock used for 429 waits. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
 }
 export declare class FrihetClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeoutMs;
+    private readonly retryBudgetMs;
+    private readonly sleepFn;
+    private readonly nowFn;
     constructor(apiKey: string, baseUrl?: string, options?: FrihetClientOptions);
     private request;
-    private sleep;
+    /** Fetch a raw response. The caller owns timeout and body consumption. */
+    private fetchRaw;
+    /** Consume one response body without ever retaining more than `maxBytes`. */
+    private readBoundedBody;
+    /**
+     * 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.
+     */
+    private requestDocument;
+    /**
+     * 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.
+     */
+    private rateLimitDelayMs;
     /**
      * Wrapper for endpoints whose backend wraps the payload in a `{ data, meta }`
      * envelope. This is the UNIFORM convention across the Frihet `/v1` REST API:
@@ -46,20 +147,25 @@ export declare 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.
      */
     private requestUnwrapped;
-    /** Wrapper for paginated endpoints — validates response shape has `data` array. */
+    /** Validate list rows and emit only the declared MCP pagination envelope. */
     private requestPaginated;
     listInvoices(params?: {
         limit?: number;
@@ -75,7 +181,21 @@ export declare class FrihetClient {
     getInvoice(id: string): Promise<Record<string, unknown>>;
     createInvoice(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateInvoice(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteInvoice(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteInvoice(id: string): Promise<Record<string, unknown> | undefined>;
     searchInvoices(query: string, params?: {
         limit?: number;
         offset?: number;
@@ -137,7 +257,13 @@ export declare class FrihetClient {
     getQuote(id: string): Promise<Record<string, unknown>>;
     createQuote(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateQuote(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteQuote(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteQuote(id: string): Promise<Record<string, unknown> | undefined>;
     listVendors(params?: {
         q?: string;
         limit?: number;
@@ -151,8 +277,8 @@ export declare class FrihetClient {
     deleteVendor(id: string): Promise<void>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
-    getInvoicePdf(id: string): Promise<Record<string, unknown>>;
-    getInvoiceEInvoice(invoiceId: string): Promise<any>;
+    getInvoicePdf(id: string): Promise<BinaryDocument>;
+    getInvoiceEInvoice(invoiceId: string): Promise<EInvoiceDocument>;
     /**
      * `POST /v1/invoices/:id/credit-note` — creates a rectificativa DRAFT.
      *
@@ -176,14 +302,29 @@ export declare class FrihetClient {
         daysOverdue?: number;
     }): Promise<any>;
     sendQuote(id: string, to?: string): Promise<Record<string, unknown>>;
-    listWebhooks(params?: {
+    listWebhooks(): Promise<{
+        data: Webhook[];
+        total: number;
+    }>;
+    getWebhook(id: string): Promise<Webhook>;
+    createWebhook(data: CreateWebhookInput): Promise<CreateWebhookResult>;
+    updateWebhook(id: string, data: UpdateWebhookInput): Promise<Webhook>;
+    deleteWebhook(id: string): Promise<void>;
+    globalSearch(params: {
+        q: string;
+        types?: ReadonlyArray<"invoices" | "expenses" | "vendors" | "clients" | "products">;
         limit?: number;
         offset?: number;
-    }): Promise<PaginatedResponse<Record<string, unknown>>>;
-    getWebhook(id: string): Promise<Record<string, unknown>>;
-    createWebhook(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    updateWebhook(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    deleteWebhook(id: string): Promise<void>;
+    }): Promise<{
+        data: Record<string, unknown>[];
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+        query: string;
+        types: ReadonlyArray<"invoices" | "expenses" | "vendors" | "clients" | "products">;
+        truncated?: boolean;
+    }>;
     listClientContacts(clientId: string, params?: {
         limit?: number;
         offset?: number;
@@ -261,14 +402,9 @@ export declare class FrihetClient {
     }>;
     exportEInvoice(params: {
         invoiceId: string;
-        format: string;
+        format: McpEInvoiceExportFormat;
         signed?: boolean;
-    }): Promise<{
-        xmlUrl: string;
-        filename: string;
-        format: string;
-        signed: boolean;
-    }>;
+    }): Promise<EInvoiceExportResult>;
     faceSubmit(params: {
         invoiceId: string;
         mode: "mock" | "sandbox" | "production";
@@ -484,10 +620,12 @@ export declare class FrihetClient {
         };
     }): Promise<Record<string, unknown>>;
     getGestoriaAgingConsolidated(params?: {
-        ownerUid?: string;
+        workspaceIds?: string[];
+        asOf?: string;
+        bustCache?: boolean;
     }): Promise<Record<string, unknown>>;
     approveGLEntry(entryId: string, notes?: string): Promise<Record<string, unknown>>;
-    rejectGLEntry(entryId: string, reason: string): Promise<Record<string, unknown>>;
+    rejectGLEntry(entryId: string, note: string): Promise<Record<string, unknown>>;
     getGLEntryAuditLog(entryId: string): Promise<Record<string, unknown>>;
     addCustomPortalDomain(data: {
         domain: string;
@@ -529,15 +667,13 @@ export declare class FrihetClient {
     }): Promise<PaginatedResponse<Record<string, unknown>>>;
     createBankRule(data: {
         name: string;
-        conditions: Array<{
+        bankConditions: Array<{
             field: string;
             operator: string;
             value: string;
         }>;
-        actions: Array<{
-            type: string;
-            value: string;
-        }>;
+        action: string;
+        actionConfig: Record<string, unknown>;
         isActive?: boolean;
     }): Promise<Record<string, unknown>>;
     listLeaves(params?: {
@@ -567,8 +703,8 @@ export declare class FrihetClient {
         employeeId: string;
         mood?: string;
         location?: string;
-    }): Promise<Record<string, unknown>>;
-    attendanceClockOut(entryId: string): Promise<Record<string, unknown>>;
+    }, idempotencyKey?: string): Promise<Record<string, unknown>>;
+    attendanceClockOut(entryId: string, idempotencyKey?: string): Promise<Record<string, unknown>>;
     getOvertimeReport(params: {
         period: string;
         employeeId?: string;
@@ -585,20 +721,16 @@ export declare class FrihetClient {
         eventType?: string;
     }): Promise<Record<string, unknown>>;
     exportPayroll(params: {
-        format: "a3" | "contasol" | "sage" | "holded" | "siltra";
+        format: "a3" | "contasol" | "sage" | "siltra";
         month: string;
     }): Promise<Record<string, unknown>>;
     getPayrollChecklist(params: {
         month: string;
     }): Promise<Record<string, unknown>>;
-    getOnboardingStatus(): Promise<Record<string, unknown>>;
-    setOnboardingPersona(data: {
-        persona: "autonomo" | "empresa" | "agencia" | "gestoria";
-    }): Promise<Record<string, unknown>>;
     getPermissionsMatrix(): Promise<Record<string, unknown>>;
     getMyPermissions(): Promise<Record<string, unknown>>;
     getCurrentPeriod(params?: {
-        periodId?: string;
+        fiscalYear?: string;
     }): Promise<Record<string, unknown>>;
     closePeriod(data: {
         type: "monthly" | "quarterly";