@t4dhg/mcp-factorial 1.1.0 → 2.0.0

package/dist/http-client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP client with retry logic for MCP FactorialHR
+ *
+ * Implements exponential backoff retry for transient failures.
+ */
+/**
+ * Request options for the HTTP client
+ */
+export interface RequestOptions {
+    /** Query parameters */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Request timeout in milliseconds (overrides default) */
+    timeout?: number;
+    /** Maximum retry attempts (overrides default) */
+    maxRetries?: number;
+    /** Skip retry logic */
+    noRetry?: boolean;
+}
+/**
+ * Make an HTTP request with retry logic
+ */
+export declare function factorialRequest<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+/**
+ * Wrapper type for paginated API responses
+ */
+export interface ApiResponse<T> {
+    data: T;
+}
+/**
+ * Wrapper type for list API responses
+ */
+export interface ApiListResponse<T> {
+    data: T[];
+}
+/**
+ * Make a request expecting a single item response
+ */
+export declare function fetchOne<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+/**
+ * Make a request expecting a list response
+ */
+export declare function fetchList<T>(endpoint: string, options?: RequestOptions): Promise<T[]>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC/D,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CA6DZ;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,EAAE,CAAC;CACX;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAGxF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAG3F"}

package/dist/http-client.js

@@ -0,0 +1,146 @@
+/**
+ * HTTP client with retry logic for MCP FactorialHR
+ *
+ * Implements exponential backoff retry for transient failures.
+ */
+import { getConfig, debug, getApiKey } from './config.js';
+import { AuthenticationError, AuthorizationError, NotFoundError, RateLimitError, ServerError, TimeoutError, NetworkError, isRetryableError, } from './errors.js';
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Calculate delay for exponential backoff
+ * @param attempt - Current attempt number (1-based)
+ * @param baseDelay - Base delay in milliseconds
+ * @returns Delay in milliseconds with jitter
+ */
+function getBackoffDelay(attempt, baseDelay = 1000) {
+    const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+    const maxDelay = 10000; // Cap at 10 seconds
+    const delay = Math.min(exponentialDelay, maxDelay);
+    // Add jitter (±20%)
+    const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+    return Math.round(delay + jitter);
+}
+/**
+ * Build URL with query parameters
+ */
+function buildUrl(endpoint, params) {
+    const config = getConfig();
+    const url = new URL(`${config.baseUrl}${endpoint}`);
+    if (params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+    }
+    return url.toString();
+}
+/**
+ * Handle HTTP response and throw appropriate errors
+ */
+async function handleResponse(response, endpoint) {
+    if (response.ok) {
+        const data = (await response.json());
+        debug('Response received', { endpoint, status: response.status });
+        return data;
+    }
+    const errorText = await response.text();
+    debug(`API error (${response.status})`, { endpoint, error: errorText });
+    switch (response.status) {
+        case 401:
+            throw new AuthenticationError(endpoint);
+        case 403:
+            throw new AuthorizationError(endpoint);
+        case 404:
+            throw new NotFoundError(endpoint);
+        case 429: {
+            const retryAfter = response.headers.get('Retry-After');
+            throw new RateLimitError(endpoint, retryAfter ? parseInt(retryAfter, 10) : undefined);
+        }
+        default:
+            if (response.status >= 500) {
+                throw new ServerError(response.status, endpoint, errorText);
+            }
+            throw new Error(`FactorialHR API error (${response.status}): ${errorText}`);
+    }
+}
+/**
+ * Make an HTTP request with retry logic
+ */
+export async function factorialRequest(endpoint, options = {}) {
+    const config = getConfig();
+    const url = buildUrl(endpoint, options.params);
+    const timeout = options.timeout ?? config.timeout;
+    const maxRetries = options.noRetry ? 1 : (options.maxRetries ?? config.maxRetries);
+    debug(`Fetching: ${url}`);
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'x-api-key': getApiKey(),
+                    Accept: 'application/json',
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            return await handleResponse(response, endpoint);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Convert abort to timeout error
+            if (error instanceof Error && error.name === 'AbortError') {
+                lastError = new TimeoutError(timeout, endpoint);
+            }
+            else if (error instanceof Error) {
+                lastError = error;
+            }
+            else {
+                lastError = new NetworkError('An unexpected network error occurred');
+            }
+            // Check if we should retry
+            const shouldRetry = attempt < maxRetries && isRetryableError(lastError);
+            if (shouldRetry) {
+                // Handle rate limit with Retry-After header
+                let delay;
+                if (lastError instanceof RateLimitError && lastError.retryAfter) {
+                    delay = lastError.retryAfter * 1000;
+                }
+                else {
+                    delay = getBackoffDelay(attempt);
+                }
+                debug(`Retry attempt ${attempt}/${maxRetries} after ${delay}ms`, {
+                    error: lastError.message,
+                });
+                await sleep(delay);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    throw lastError ?? new NetworkError('Request failed after all retries');
+}
+/**
+ * Make a request expecting a single item response
+ */
+export async function fetchOne(endpoint, options) {
+    const response = await factorialRequest(endpoint, options);
+    return response.data;
+}
+/**
+ * Make a request expecting a list response
+ */
+export async function fetchList(endpoint, options) {
+    const response = await factorialRequest(endpoint, options);
+    return response.data || [];
+}
+//# sourceMappingURL=http-client.js.map

package/dist/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,6 +4,13 @@
  *
  * Provides access to employee and organizational data from FactorialHR
  * through the Model Context Protocol for use with Claude Code and other MCP clients.
+ *
+ * Features:
+ * - 22 tools for employees, teams, locations, contracts, time off, attendance, documents, and job catalog
+ * - Pagination support for all list operations
+ * - Caching for improved performance
+ * - Retry logic with exponential backoff
+ * - Runtime validation with Zod schemas
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}