@frihet/mcp-server 1.17.0 → 2.0.1

package/dist/client-interface.d.ts

@@ -126,6 +126,21 @@ export interface IFrihetClient {
     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<{
+        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;
@@ -206,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";
@@ -387,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;
@@ -429,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: {
@@ -480,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;
@@ -509,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;
@@ -533,10 +543,6 @@ export interface IFrihetClient {
     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?: {

package/dist/client.d.ts

@@ -63,11 +63,30 @@ export interface XmlDocument {
 }
 /** `/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;
     readonly detail?: 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. */
+    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 {
     /**
@@ -76,17 +95,22 @@ export interface FrihetClientOptions {
      */
     timeoutMs?: number;
     /**
-     * Internal second factor for API keys provisioned by Frihet OAuth Workers.
-     * Ordinary dashboard/API keys must omit it. The value is sent only to the
-     * already-normalized API origin and is never included in logs or errors.
+     * 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.
      */
-    oauthServiceSecret?: string;
+    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 oauthServiceSecret?;
+    private readonly retryBudgetMs;
+    private readonly sleepFn;
+    private readonly nowFn;
     constructor(apiKey: string, baseUrl?: string, options?: FrihetClientOptions);
     private request;
     /** Fetch a raw response. The caller owns timeout and body consumption. */
@@ -101,7 +125,13 @@ export declare class FrihetClient {
      * A 429 may retry, matching the generic JSON client path.
      */
     private requestDocument;
-    private sleep;
+    /**
+     * 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:
@@ -130,12 +160,12 @@ export declare 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.
      */
     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;
@@ -280,6 +310,21 @@ export declare class FrihetClient {
     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<{
+        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;
@@ -357,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";
@@ -580,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;
@@ -625,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?: {
@@ -663,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;
@@ -687,10 +727,6 @@ export declare class FrihetClient {
     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?: {