@energio/holded-mcp 1.0.0

package/dist/services/api.js

@@ -0,0 +1,441 @@
+/**
+ * Holded API client with authentication, error handling, and retry logic
+ */
+import axios from "axios";
+import FormDataLib from "form-data";
+import { API_ENDPOINTS } from "../constants.js";
+let apiKey;
+let axiosInstance;
+/**
+ * Debug mode - set HOLDED_DEBUG=true to enable request logging
+ */
+const DEBUG = process.env.HOLDED_DEBUG === 'true';
+/**
+ * Retry configuration
+ */
+const RETRY_CONFIG = {
+    /** Maximum number of retry attempts */
+    maxRetries: 3,
+    /** Initial delay in milliseconds before first retry */
+    initialDelayMs: 1000,
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: 10000,
+    /** Multiplier for exponential backoff */
+    backoffMultiplier: 2,
+    /** HTTP status codes that should trigger a retry */
+    retryableStatuses: [429, 500, 502, 503, 504],
+};
+/**
+ * Rate limiting configuration
+ * Set HOLDED_RATE_LIMIT_PER_SECOND to control request rate (default: 10 req/sec)
+ */
+const RATE_LIMIT_CONFIG = {
+    /** Maximum requests per second (configurable via env) */
+    requestsPerSecond: parseInt(process.env.HOLDED_RATE_LIMIT_PER_SECOND || '10', 10),
+    /** Enabled by default, set HOLDED_DISABLE_RATE_LIMIT=true to disable */
+    enabled: process.env.HOLDED_DISABLE_RATE_LIMIT !== 'true',
+};
+/**
+ * Token bucket for rate limiting
+ * Exported for testing purposes
+ */
+export class TokenBucket {
+    tokens;
+    lastRefill;
+    capacity;
+    refillRate; // tokens per millisecond
+    constructor(requestsPerSecond) {
+        this.capacity = requestsPerSecond;
+        this.tokens = requestsPerSecond;
+        this.lastRefill = Date.now();
+        this.refillRate = requestsPerSecond / 1000; // tokens per ms
+    }
+    /**
+     * Refill tokens based on time elapsed
+     */
+    refill() {
+        const now = Date.now();
+        const timePassed = now - this.lastRefill;
+        const tokensToAdd = timePassed * this.refillRate;
+        this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    /**
+     * Try to consume a token, wait if not available
+     */
+    async consume() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // Calculate wait time for next token
+        const tokensNeeded = 1 - this.tokens;
+        const waitMs = Math.ceil(tokensNeeded / this.refillRate);
+        if (DEBUG) {
+            console.error(`[Rate Limit] Waiting ${waitMs}ms for next available token`);
+        }
+        await sleep(waitMs);
+        // Refill and consume
+        this.refill();
+        this.tokens -= 1;
+    }
+    /**
+     * Get current token count (for testing)
+     */
+    getTokens() {
+        return this.tokens;
+    }
+    /**
+     * Get capacity (for testing)
+     */
+    getCapacity() {
+        return this.capacity;
+    }
+}
+/**
+ * Global rate limiter instance
+ */
+let rateLimiter = null;
+/**
+ * Initialize rate limiter if enabled
+ */
+function getRateLimiter() {
+    if (!RATE_LIMIT_CONFIG.enabled) {
+        return null;
+    }
+    if (!rateLimiter) {
+        rateLimiter = new TokenBucket(RATE_LIMIT_CONFIG.requestsPerSecond);
+    }
+    return rateLimiter;
+}
+/**
+ * Sleep for a specified number of milliseconds
+ * Exported for testing purposes
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Calculate delay for retry with exponential backoff and jitter
+ * Exported for testing purposes
+ */
+export function calculateRetryDelay(attempt, retryAfterHeader) {
+    // If server specifies Retry-After, use that
+    if (retryAfterHeader) {
+        const retryAfterSeconds = parseInt(retryAfterHeader, 10);
+        if (!isNaN(retryAfterSeconds)) {
+            return retryAfterSeconds * 1000;
+        }
+    }
+    // Exponential backoff with jitter
+    const exponentialDelay = RETRY_CONFIG.initialDelayMs * Math.pow(RETRY_CONFIG.backoffMultiplier, attempt);
+    const jitter = Math.random() * 0.3 * exponentialDelay; // Add up to 30% jitter
+    const delay = Math.min(exponentialDelay + jitter, RETRY_CONFIG.maxDelayMs);
+    return Math.round(delay);
+}
+/**
+ * Check if an error is retryable based on status code
+ * Exported for testing purposes
+ */
+export function isRetryableError(error) {
+    if (axios.isAxiosError(error)) {
+        const status = error.response?.status;
+        if (status && RETRY_CONFIG.retryableStatuses.includes(status)) {
+            return true;
+        }
+        // Also retry on network errors
+        if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get Retry-After header value if present
+ * Exported for testing purposes
+ */
+export function getRetryAfterHeader(error) {
+    return error.response?.headers?.["retry-after"];
+}
+/**
+ * Initialize the API client with the Holded API key
+ */
+export function initializeApi(key) {
+    apiKey = key;
+    axiosInstance = axios.create({
+        timeout: 30000,
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            key: apiKey,
+        },
+    });
+}
+/**
+ * Get the API key from environment or throw error
+ */
+export function getApiKey() {
+    if (!apiKey) {
+        const envKey = process.env.HOLDED_API_KEY;
+        if (!envKey) {
+            throw new Error("HOLDED_API_KEY environment variable is required. " +
+                "Get your API key from https://app.holded.com/api");
+        }
+        initializeApi(envKey);
+    }
+    return apiKey;
+}
+/**
+ * Get the axios instance, initializing if needed
+ */
+function getAxiosInstance() {
+    if (!axiosInstance) {
+        getApiKey(); // This will initialize the instance
+    }
+    return axiosInstance;
+}
+/**
+ * Get the base URL for a specific API module
+ */
+function getBaseUrl(module) {
+    switch (module) {
+        case "invoicing":
+            return API_ENDPOINTS.INVOICING;
+        case "crm":
+            return API_ENDPOINTS.CRM;
+        case "projects":
+            return API_ENDPOINTS.PROJECTS;
+        case "accounting":
+            return API_ENDPOINTS.ACCOUNTING;
+        case "team":
+            return API_ENDPOINTS.TEAM;
+    }
+}
+/**
+ * Make an API request to the Holded API with automatic retry for transient errors
+ *
+ * Retries automatically on:
+ * - 429 (Rate limit exceeded)
+ * - 500, 502, 503, 504 (Server errors)
+ * - Network timeout errors
+ *
+ * Uses exponential backoff with jitter between retries.
+ * Includes proactive rate limiting to prevent hitting API limits.
+ */
+export async function makeApiRequest(module, endpoint, method = "GET", data, params) {
+    const client = getAxiosInstance();
+    const baseUrl = getBaseUrl(module);
+    const url = `${baseUrl}/${endpoint}`;
+    const config = {
+        method,
+        url,
+        params,
+    };
+    if (data && (method === "POST" || method === "PUT")) {
+        config.data = data;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+        try {
+            // Apply rate limiting before making request
+            const limiter = getRateLimiter();
+            if (limiter) {
+                await limiter.consume();
+            }
+            const response = await client.request(config);
+            return response.data;
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry
+            if (attempt < RETRY_CONFIG.maxRetries && isRetryableError(error)) {
+                const retryAfter = axios.isAxiosError(error) ? getRetryAfterHeader(error) : undefined;
+                const delay = calculateRetryDelay(attempt, retryAfter);
+                // Log retry attempt (only in debug mode)
+                if (DEBUG) {
+                    const status = axios.isAxiosError(error) ? error.response?.status : "unknown";
+                    console.error(`[Holded API] Request failed with status ${status}, retrying in ${delay}ms (attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries})`);
+                }
+                await sleep(delay);
+                continue;
+            }
+            // Not retryable or max retries exceeded
+            throw error;
+        }
+    }
+    // Should not reach here, but throw last error just in case
+    throw lastError;
+}
+/**
+ * Make a multipart/form-data API request for file uploads with automatic retry
+ *
+ * Retries automatically on transient errors (rate limit, server errors).
+ * Includes proactive rate limiting to prevent hitting API limits.
+ */
+export async function makeMultipartApiRequest(module, endpoint, fileBuffer, fileName, setMain) {
+    const key = getApiKey();
+    const baseUrl = getBaseUrl(module);
+    const url = `${baseUrl}/${endpoint}`;
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+        // Create fresh FormData for each attempt (can't reuse after sending)
+        const formData = new FormDataLib();
+        formData.append("file", fileBuffer, fileName);
+        if (setMain !== undefined) {
+            formData.append("setMain", String(setMain));
+        }
+        // Create a new axios instance for multipart requests
+        const client = axios.create({
+            timeout: 60000, // Longer timeout for file uploads
+            headers: {
+                key,
+                ...formData.getHeaders(), // This sets Content-Type with boundary
+            },
+        });
+        try {
+            // Apply rate limiting before making request
+            const limiter = getRateLimiter();
+            if (limiter) {
+                await limiter.consume();
+            }
+            const response = await client.post(url, formData);
+            return response.data;
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry
+            if (attempt < RETRY_CONFIG.maxRetries && isRetryableError(error)) {
+                const retryAfter = axios.isAxiosError(error) ? getRetryAfterHeader(error) : undefined;
+                const delay = calculateRetryDelay(attempt, retryAfter);
+                if (DEBUG) {
+                    const status = axios.isAxiosError(error) ? error.response?.status : "unknown";
+                    console.error(`[Holded API] Multipart request failed with status ${status}, retrying in ${delay}ms (attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries})`);
+                }
+                await sleep(delay);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError;
+}
+/**
+ * Handle API errors and return user-friendly messages with actionable remediation hints
+ *
+ * Error codes per Holded API documentation:
+ * - 400: Bad request
+ * - 401: Unauthorized (invalid API key)
+ * - 403: Forbidden
+ * - 404: Resource not found
+ * - 409: Conflict
+ * - 410: Gone (e.g., booking slot no longer available)
+ * - 422: Validation failed
+ * - 429: Rate limit exceeded
+ * - 500: Server error
+ */
+export function handleApiError(error) {
+    if (axios.isAxiosError(error)) {
+        const axiosError = error;
+        if (axiosError.response) {
+            const status = axiosError.response.status;
+            const data = axiosError.response.data;
+            const errorMessage = data?.message || data?.error || data?.info || "";
+            const url = axiosError.config?.url || "";
+            const method = axiosError.config?.method?.toUpperCase() || "";
+            switch (status) {
+                case 400:
+                    return `Error: Bad request to ${method} ${url}. ${errorMessage || "The request parameters are invalid."}\n\nRemediation:\n- Verify all required parameters are provided\n- Check parameter types match the API specification\n- Ensure date/timestamp formats are correct (Unix timestamps)\n- Review nested object structures (e.g., stock updates, addresses)`;
+                case 401:
+                    return `Error: Unauthorized request to ${url}.\n\nRemediation:\n- Verify HOLDED_API_KEY environment variable is set correctly\n- Check your API key is valid at https://app.holded.com/api\n- Ensure the API key has not expired\n- Confirm you're using the correct key header format`;
+                case 403:
+                    return `Error: Forbidden access to ${url}. ${errorMessage || "You don't have permission to access this resource."}\n\nRemediation:\n- Verify your API key has the necessary permissions\n- Check if your Holded account has access to this feature\n- Ensure the resource belongs to your organization\n- Contact Holded support if you believe you should have access`;
+                case 404:
+                    return `Error: Resource not found at ${url}. ${errorMessage || "The requested resource does not exist."}\n\nRemediation:\n- Verify the ID is correct and exists in your Holded account\n- Use list endpoints to find valid IDs (e.g., holded_invoicing_list_contacts)\n- Check for typos in the ID parameter\n- Ensure the resource wasn't deleted\n- Confirm you're using the correct document type for documents`;
+                case 409:
+                    return `Error: Conflict with ${method} ${url}. ${errorMessage || "The resource may already exist or conflicts with the current state."}\n\nRemediation:\n- Check if a resource with the same unique identifier already exists\n- Verify the resource hasn't been modified since you last read it\n- For numbering series, ensure the format doesn't conflict with existing series\n- Try using update instead of create if the resource exists`;
+                case 410:
+                    // Specific error for booking slots - per Holded CRM API v1.0
+                    return `Error: Resource no longer available at ${url}. ${errorMessage || "The resource has been removed or is no longer accessible."}\n\nRemediation:\n- For bookings: Use holded_crm_get_available_slots to find current available time slots\n- The time slot may have been booked by another user\n- Try selecting a different date/time\n- Refresh your list of available resources`;
+                case 422:
+                    return `Error: Validation failed for ${method} ${url}. ${errorMessage || "The request data is invalid."}\n\nRemediation:\n- Review the error message for specific field validation issues\n- Check required fields are present: ${errorMessage}\n- Verify field types (strings vs numbers, especially for timestamps)\n- For accounting entries: Ensure debits equal credits\n- For stock updates: Use correct nested object structure\n- For emails: Ensure email addresses are valid\n- For dates: Use Unix timestamps (seconds since epoch) as integers`;
+                case 429:
+                    return `Error: Rate limit exceeded. ${errorMessage || "Too many requests sent to the API."}\n\nRemediation:\n- Wait a few seconds before retrying\n- The request will automatically retry with exponential backoff\n- Consider reducing request frequency\n- Adjust HOLDED_RATE_LIMIT_PER_SECOND environment variable (default: 10 req/sec)\n- Batch operations when possible to reduce API calls`;
+                case 500:
+                    return `Error: Holded server error at ${url}. ${errorMessage || "An internal error occurred on the Holded server."}\n\nRemediation:\n- The request will automatically retry\n- Try again in a few moments\n- If the error persists, contact Holded support\n- Check Holded status page for any ongoing incidents`;
+                case 502:
+                case 503:
+                case 504:
+                    return `Error: Holded service temporarily unavailable (${status}). ${errorMessage}\n\nRemediation:\n- The request will automatically retry with exponential backoff\n- Wait a few minutes and try again\n- Check if Holded is performing maintenance\n- Monitor Holded status page for service updates`;
+                default:
+                    return `Error: API request failed with status ${status} for ${method} ${url}. ${errorMessage}\n\nRemediation:\n- Review the Holded API documentation for this endpoint\n- Check the API response for specific error details\n- Contact Holded support if the issue persists`;
+            }
+        }
+        else if (axiosError.code === "ECONNABORTED") {
+            return `Error: Request timed out after ${axiosError.config?.timeout || 30000}ms.\n\nRemediation:\n- The operation took too long to complete\n- For file uploads: Check file size is reasonable\n- Try again with a stable internet connection\n- If timeout persists, the Holded API may be slow - try during off-peak hours`;
+        }
+        else if (axiosError.code === "ENOTFOUND" || axiosError.code === "ECONNREFUSED") {
+            return `Error: Unable to connect to Holded API.\n\nRemediation:\n- Check your internet connection\n- Verify DNS resolution is working\n- Check if you're behind a firewall or proxy\n- Ensure api.holded.com is accessible from your network\n- Try accessing https://api.holded.com in a browser`;
+        }
+    }
+    return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}\n\nRemediation:\n- Check the error message above for details\n- Review your input parameters\n- Ensure all required dependencies are installed\n- Enable debug mode (HOLDED_DEBUG=true) for more details`;
+}
+/**
+ * Format a successful response with optional truncation
+ */
+export function formatResponse(data, characterLimit = 25000) {
+    let text = JSON.stringify(data, null, 2);
+    let truncated = false;
+    if (text.length > characterLimit) {
+        // Try to truncate the data array if it exists
+        if (Array.isArray(data)) {
+            const halfLength = Math.max(1, Math.floor(data.length / 2));
+            const truncatedData = data.slice(0, halfLength);
+            text = JSON.stringify({
+                data: truncatedData,
+                truncated: true,
+                message: `Response truncated from ${data.length} to ${halfLength} items. Use pagination parameters to see more results.`,
+            }, null, 2);
+            truncated = true;
+        }
+        else {
+            const suffix = "\n... (response truncated)";
+            text = text.substring(0, characterLimit - suffix.length) + suffix;
+            truncated = true;
+        }
+    }
+    return { text, truncated };
+}
+/**
+ * Build pagination query parameters
+ */
+export function buildPaginationParams(page) {
+    const params = {};
+    if (page !== undefined && page > 0) {
+        params.page = page;
+    }
+    return params;
+}
+/**
+ * Safely convert API response to Record<string, unknown> for structuredContent
+ * Handles cases where API might return string, object, array, or other types
+ */
+export function toStructuredContent(response) {
+    if (typeof response === "string") {
+        return { message: response, success: true };
+    }
+    if (response && typeof response === "object" && !Array.isArray(response)) {
+        return response;
+    }
+    // For arrays or other types, wrap in a data property
+    return { data: response, success: true };
+}
+/**
+ * Reset internal state for testing purposes only
+ */
+export function _resetForTesting() {
+    rateLimiter = null;
+    axiosInstance = undefined;
+    apiKey = undefined;
+}
+//# sourceMappingURL=api.js.map

package/dist/services/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/services/api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAwD,MAAM,OAAO,CAAC;AAC7E,OAAO,WAAW,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,IAAI,MAA0B,CAAC;AAC/B,IAAI,aAAwC,CAAC;AAE7C;;GAEG;AACH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,MAAM,CAAC;AAElD;;GAEG;AACH,MAAM,YAAY,GAAG;IACnB,uCAAuC;IACvC,UAAU,EAAE,CAAC;IACb,uDAAuD;IACvD,cAAc,EAAE,IAAI;IACpB,oDAAoD;IACpD,UAAU,EAAE,KAAK;IACjB,yCAAyC;IACzC,iBAAiB,EAAE,CAAC;IACpB,oDAAoD;IACpD,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,MAAM,iBAAiB,GAAG;IACxB,yDAAyD;IACzD,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,IAAI,EAAE,EAAE,CAAC;IACjF,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,MAAM;CAC1D,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAS;IACf,UAAU,CAAS;IACV,QAAQ,CAAS;IACjB,UAAU,CAAS,CAAC,yBAAyB;IAE9D,YAAY,iBAAyB;QACnC,IAAI,CAAC,QAAQ,GAAG,iBAAiB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,iBAAiB,GAAG,IAAI,CAAC,CAAC,gBAAgB;IAC9D,CAAC;IAED;;OAEG;IACK,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QACzC,MAAM,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAEjD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,qCAAqC;QACrC,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAEzD,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,wBAAwB,MAAM,6BAA6B,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QAEpB,qBAAqB;QACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAED;;GAEG;AACH,IAAI,WAAW,GAAuB,IAAI,CAAC;AAE3C;;GAEG;AACH,SAAS,cAAc;IACrB,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,IAAI,WAAW,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,gBAAyB;IAC5E,4CAA4C;IAC5C,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,iBAAiB,GAAG,QAAQ,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,CAAC;YAC9B,OAAO,iBAAiB,GAAG,IAAI,CAAC;QAClC,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,MAAM,gBAAgB,GAAG,YAAY,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACzG,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,gBAAgB,CAAC,CAAC,uBAAuB;IAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,GAAG,MAAM,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IAE3E,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;QACtC,IAAI,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,+BAA+B;QAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,OAAO,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,aAAa,CAAuB,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,GAAG,GAAG,CAAC;IACb,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,OAAO,EAAE,KAAK;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,kBAAkB;YAC1B,GAAG,EAAE,MAAM;SACZ;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mDAAmD;gBACjD,kDAAkD,CACrD,CAAC;QACJ,CAAC;QACD,aAAa,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB;IACvB,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,SAAS,EAAE,CAAC,CAAC,oCAAoC;IACnD,CAAC;IACD,OAAO,aAAc,CAAC;AACxB,CAAC;AAOD;;GAEG;AACH,SAAS,UAAU,CAAC,MAAiB;IACnC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,WAAW;YACd,OAAO,aAAa,CAAC,SAAS,CAAC;QACjC,KAAK,KAAK;YACR,OAAO,aAAa,CAAC,GAAG,CAAC;QAC3B,KAAK,UAAU;YACb,OAAO,aAAa,CAAC,QAAQ,CAAC;QAChC,KAAK,YAAY;YACf,OAAO,aAAa,CAAC,UAAU,CAAC;QAClC,KAAK,MAAM;YACT,OAAO,aAAa,CAAC,IAAI,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAiB,EACjB,QAAgB,EAChB,SAA4C,KAAK,EACjD,IAAc,EACd,MAAgC;IAEhC,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IAErC,MAAM,MAAM,GAAuB;QACjC,MAAM;QACN,GAAG;QACH,MAAM;KACP,CAAC;IAEF,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACpE,IAAI,CAAC;YACH,4CAA4C;YAC5C,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;YACjC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAI,MAAM,CAAC,CAAC;YACjD,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;YAElB,2BAA2B;YAC3B,IAAI,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjE,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACtF,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAEvD,yCAAyC;gBACzC,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;oBAC9E,OAAO,CAAC,KAAK,CAAC,2CAA2C,MAAM,iBAAiB,KAAK,eAAe,OAAO,GAAG,CAAC,IAAI,YAAY,CAAC,UAAU,GAAG,CAAC,CAAC;gBACjJ,CAAC;gBAED,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnB,SAAS;YACX,CAAC;YAED,wCAAwC;YACxC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,2DAA2D;IAC3D,MAAM,SAAS,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAiB,EACjB,QAAgB,EAChB,UAAkB,EAClB,QAAgB,EAChB,OAAiB;IAEjB,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IAErC,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACpE,qEAAqE;QACrE,MAAM,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC;QACnC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9C,CAAC;QAED,qDAAqD;QACrD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC1B,OAAO,EAAE,KAAK,EAAE,kCAAkC;YAClD,OAAO,EAAE;gBACP,GAAG;gBACH,GAAG,QAAQ,CAAC,UAAU,EAAE,EAAE,uCAAuC;aAClE;SACF,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,4CAA4C;YAC5C,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;YACjC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAI,GAAG,EAAE,QAAQ,CAAC,CAAC;YACrD,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;YAElB,2BAA2B;YAC3B,IAAI,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjE,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACtF,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAEvD,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;oBAC9E,OAAO,CAAC,KAAK,CAAC,qDAAqD,MAAM,iBAAiB,KAAK,eAAe,OAAO,GAAG,CAAC,IAAI,YAAY,CAAC,UAAU,GAAG,CAAC,CAAC;gBAC3J,CAAC;gBAED,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnB,SAAS;YACX,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,KAAyF,CAAC;QAE7G,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;YACtC,MAAM,YAAY,GAAG,IAAI,EAAE,OAAO,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;YAE9D,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,GAAG;oBACN,OAAO,yBAAyB,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,qCAAqC,yPAAyP,CAAC;gBAEnW,KAAK,GAAG;oBACN,OAAO,kCAAkC,GAAG,2OAA2O,CAAC;gBAE1R,KAAK,GAAG;oBACN,OAAO,8BAA8B,GAAG,KAAK,YAAY,IAAI,oDAAoD,sPAAsP,CAAC;gBAE1W,KAAK,GAAG;oBACN,OAAO,gCAAgC,GAAG,KAAK,YAAY,IAAI,wCAAwC,4SAA4S,CAAC;gBAEtZ,KAAK,GAAG;oBACN,OAAO,wBAAwB,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,qEAAqE,ySAAyS,CAAC;gBAElb,KAAK,GAAG;oBACN,6DAA6D;oBAC7D,OAAO,0CAA0C,GAAG,KAAK,YAAY,IAAI,2DAA2D,oPAAoP,CAAC;gBAE3X,KAAK,GAAG;oBACN,OAAO,gCAAgC,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,8BAA8B,2HAA2H,YAAY,6SAA6S,CAAC;gBAE9hB,KAAK,GAAG;oBACN,OAAO,+BAA+B,YAAY,IAAI,oCAAoC,wSAAwS,CAAC;gBAErY,KAAK,GAAG;oBACN,OAAO,iCAAiC,GAAG,KAAK,YAAY,IAAI,kDAAkD,+LAA+L,CAAC;gBAEpT,KAAK,GAAG,CAAC;gBACT,KAAK,GAAG,CAAC;gBACT,KAAK,GAAG;oBACN,OAAO,kDAAkD,MAAM,MAAM,YAAY,sNAAsN,CAAC;gBAE1S;oBACE,OAAO,yCAAyC,MAAM,QAAQ,MAAM,IAAI,GAAG,KAAK,YAAY,gLAAgL,CAAC;YACjR,CAAC;QACH,CAAC;aAAM,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAC9C,OAAO,kCAAkC,UAAU,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,iPAAiP,CAAC;QAChU,CAAC;aAAM,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACjF,OAAO,2RAA2R,CAAC;QACrS,CAAC;IACH,CAAC;IAED,OAAO,qCAAqC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,2MAA2M,CAAC;AAChT,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO,EACP,iBAAyB,KAAK;IAE9B,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,IAAI,IAAI,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QACjC,8CAA8C;QAC9C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5D,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YAChD,IAAI,GAAG,IAAI,CAAC,SAAS,CACnB;gBACE,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,2BAA2B,IAAI,CAAC,MAAM,OAAO,UAAU,wDAAwD;aACzH,EACD,IAAI,EACJ,CAAC,CACF,CAAC;YACF,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,4BAA4B,CAAC;YAC5C,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;YAClE,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAa;IAEb,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzE,OAAO,QAAmC,CAAC;IAC7C,CAAC;IACD,qDAAqD;IACrD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,WAAW,GAAG,IAAI,CAAC;IACnB,aAAa,GAAG,SAAS,CAAC;IAC1B,MAAM,GAAG,SAAS,CAAC;AACrB,CAAC"}

package/dist/tools/accounting/account-balances.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Account Balances tool for Holded API
+ *
+ * Computes accurate, date-scoped per-account debit/credit/balance totals
+ * by aggregating from individual daily ledger entries with cross-fiscal-year
+ * leak filtering.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LedgerEntryLine, AccountBalance } from "../../types.js";
+/**
+ * Filter out cross-fiscal-year leaked entries from daily ledger results.
+ *
+ * Detection uses two signals:
+ * 1. Entries sharing the same timestamp as the opening balance entry are candidates.
+ * 2. Candidates are confirmed as leaked if their entryNumber also appears at a
+ *    different timestamp (duplicate = different fiscal year).
+ * 3. Fallback: candidates at the opening timestamp whose type is not "opening" or
+ *    "vat_regularization" are excluded even without a duplicate entryNumber.
+ *
+ * Exported for unit testing.
+ */
+export declare function filterLeakedEntries(entries: LedgerEntryLine[], includeOpening: boolean): {
+    filtered: LedgerEntryLine[];
+    leakedCount: number;
+    openingExcluded: boolean;
+};
+/**
+ * Aggregate daily ledger entries into per-account debit/credit totals.
+ *
+ * Exported for unit testing.
+ */
+export declare function aggregateByAccount(entries: LedgerEntryLine[]): Map<number, {
+    debit: number;
+    credit: number;
+}>;
+/**
+ * Format account balances as markdown
+ */
+export declare function formatAccountBalancesMarkdown(accounts: AccountBalance[]): string;
+/**
+ * Register the account balances tool.
+ */
+export declare function registerAccountBalancesTools(server: McpServer): void;
+//# sourceMappingURL=account-balances.d.ts.map

package/dist/tools/accounting/account-balances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-balances.d.ts","sourceRoot":"","sources":["../../../src/tools/accounting/account-balances.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA6DtE;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EAAE,EAC1B,cAAc,EAAE,OAAO,GACtB;IAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CA2EhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAchD;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CAqBhF;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2GpE"}