latitude-mcp-server 1.0.0

package/dist/utils/logger.util.js

@@ -0,0 +1,344 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+/**
+ * Format a timestamp for logging
+ * @returns Formatted timestamp [HH:MM:SS]
+ */
+function getTimestamp() {
+    const now = new Date();
+    return `[${now.toISOString().split('T')[1].split('.')[0]}]`;
+}
+/**
+ * Safely convert object to string with size limits
+ * @param obj Object to stringify
+ * @param maxLength Maximum length of the resulting string
+ * @returns Safely stringified object
+ */
+function safeStringify(obj, maxLength = 1000) {
+    try {
+        const str = JSON.stringify(obj);
+        if (str.length <= maxLength) {
+            return str;
+        }
+        return `${str.substring(0, maxLength)}... (truncated, ${str.length} chars total)`;
+    }
+    catch {
+        return '[Object cannot be stringified]';
+    }
+}
+/**
+ * Extract essential values from larger objects for logging
+ * @param obj The object to extract values from
+ * @param keys Keys to extract (if available)
+ * @returns Object containing only the specified keys
+ */
+function extractEssentialValues(obj, keys) {
+    const result = {};
+    keys.forEach((key) => {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            result[key] = obj[key];
+        }
+    });
+    return result;
+}
+/**
+ * Format source path consistently using the standardized format:
+ * [module/file.ts@function] or [module/file.ts]
+ *
+ * @param filePath File path (with or without src/ prefix)
+ * @param functionName Optional function name
+ * @returns Formatted source path according to standard pattern
+ */
+function formatSourcePath(filePath, functionName) {
+    // Always strip 'src/' prefix for consistency
+    const normalizedPath = filePath.replace(/^src\//, '');
+    return functionName
+        ? `[${normalizedPath}@${functionName}]`
+        : `[${normalizedPath}]`;
+}
+/**
+ * Check if debug logging is enabled for a specific module
+ *
+ * This function parses the DEBUG environment variable to determine if a specific
+ * module should have debug logging enabled. The DEBUG variable can be:
+ * - 'true' or '1': Enable all debug logging
+ * - Comma-separated list of modules: Enable debug only for those modules
+ * - Module patterns with wildcards: e.g., 'controllers/*' enables all controllers
+ *
+ * Examples:
+ * - DEBUG=true
+ * - DEBUG=controllers/*,services/aws.sso.auth.service.ts
+ * - DEBUG=transport,utils/formatter*
+ *
+ * @param modulePath The module path to check against DEBUG patterns
+ * @returns true if debug is enabled for this module, false otherwise
+ */
+function isDebugEnabledForModule(modulePath) {
+    const debugEnv = process.env.DEBUG;
+    if (!debugEnv) {
+        return false;
+    }
+    // If debug is set to true or 1, enable all debug logging
+    if (debugEnv === 'true' || debugEnv === '1') {
+        return true;
+    }
+    // Parse comma-separated debug patterns
+    const debugPatterns = debugEnv.split(',').map((p) => p.trim());
+    // Check if the module matches any pattern
+    return debugPatterns.some((pattern) => {
+        // Convert glob-like patterns to regex
+        // * matches anything within a path segment
+        // ** matches across path segments
+        const regexPattern = pattern
+            .replace(/\*/g, '.*') // Convert * to regex .*
+            .replace(/\?/g, '.'); // Convert ? to regex .
+        const regex = new RegExp(`^${regexPattern}$`);
+        return (regex.test(modulePath) ||
+            // Check for pattern matches without the 'src/' prefix
+            regex.test(modulePath.replace(/^src\//, '')));
+    });
+}
+// Generate a unique session ID for this process
+const SESSION_ID = crypto.randomUUID();
+// Get the package name from environment variables or default to 'mcp-server'
+const getPkgName = () => {
+    try {
+        // Try to get it from package.json first if available
+        const packageJsonPath = path.resolve(process.cwd(), 'package.json');
+        if (fs.existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            if (packageJson.name) {
+                // Extract the last part of the name if it's scoped
+                const match = packageJson.name.match(/(@[\w-]+\/)?(.+)/);
+                return match ? match[2] : packageJson.name;
+            }
+        }
+    }
+    catch {
+        // Silently fail and use default
+    }
+    // Fallback to environment variable or default
+    return process.env.PACKAGE_NAME || 'mcp-server';
+};
+// MCP logs directory setup
+const HOME_DIR = os.homedir();
+const MCP_DATA_DIR = path.join(HOME_DIR, '.mcp', 'data');
+const CLI_NAME = getPkgName();
+// Ensure the MCP data directory exists
+if (!fs.existsSync(MCP_DATA_DIR)) {
+    fs.mkdirSync(MCP_DATA_DIR, { recursive: true });
+}
+// Create the log file path with session ID
+const LOG_FILENAME = `${CLI_NAME}.${SESSION_ID}.log`;
+const LOG_FILEPATH = path.join(MCP_DATA_DIR, LOG_FILENAME);
+// Write initial log header
+fs.writeFileSync(LOG_FILEPATH, `# ${CLI_NAME} Log Session\n` +
+    `Session ID: ${SESSION_ID}\n` +
+    `Started: ${new Date().toISOString()}\n` +
+    `Process ID: ${process.pid}\n` +
+    `Working Directory: ${process.cwd()}\n` +
+    `Command: ${process.argv.join(' ')}\n\n` +
+    `## Log Entries\n\n`, 'utf8');
+// Logger singleton to track initialization
+let isLoggerInitialized = false;
+/**
+ * Logger class for consistent logging across the application.
+ *
+ * RECOMMENDED USAGE:
+ *
+ * 1. Create a file-level logger using the static forContext method:
+ *    ```
+ *    const logger = Logger.forContext('controllers/myController.ts');
+ *    ```
+ *
+ * 2. For method-specific logging, create a method logger:
+ *    ```
+ *    const methodLogger = Logger.forContext('controllers/myController.ts', 'myMethod');
+ *    ```
+ *
+ * 3. Avoid using raw string prefixes in log messages. Instead, use contextualized loggers.
+ *
+ * 4. For debugging objects, use the debugResponse method to log only essential properties.
+ *
+ * 5. Set DEBUG environment variable to control which modules show debug logs:
+ *    - DEBUG=true (enable all debug logs)
+ *    - DEBUG=controllers/*,services/* (enable for specific module groups)
+ *    - DEBUG=transport,utils/formatter* (enable specific modules, supports wildcards)
+ */
+class Logger {
+    constructor(context, modulePath = '') {
+        this.context = context;
+        this.modulePath = modulePath;
+        // Log initialization message only once
+        if (!isLoggerInitialized) {
+            this.info(`Logger initialized with session ID: ${Logger.sessionId}`);
+            this.info(`Logs will be saved to: ${Logger.logFilePath}`);
+            isLoggerInitialized = true;
+        }
+    }
+    /**
+     * Create a contextualized logger for a specific file or component.
+     * This is the preferred method for creating loggers.
+     *
+     * @param filePath The file path (e.g., 'controllers/aws.sso.auth.controller.ts')
+     * @param functionName Optional function name for more specific context
+     * @returns A new Logger instance with the specified context
+     *
+     * @example
+     * // File-level logger
+     * const logger = Logger.forContext('controllers/myController.ts');
+     *
+     * // Method-level logger
+     * const methodLogger = Logger.forContext('controllers/myController.ts', 'myMethod');
+     */
+    static forContext(filePath, functionName) {
+        return new Logger(formatSourcePath(filePath, functionName), filePath);
+    }
+    /**
+     * Create a method level logger from a context logger
+     * @param method Method name
+     * @returns A new logger with the method context
+     */
+    forMethod(method) {
+        return Logger.forContext(this.modulePath, method);
+    }
+    _formatMessage(message) {
+        return this.context ? `${this.context} ${message}` : message;
+    }
+    _formatArgs(args) {
+        // If the first argument is an object and not an Error, safely stringify it
+        if (args.length > 0 &&
+            typeof args[0] === 'object' &&
+            args[0] !== null &&
+            !(args[0] instanceof Error)) {
+            args[0] = safeStringify(args[0]);
+        }
+        return args;
+    }
+    _log(level, message, ...args) {
+        // Skip debug messages if not enabled for this module
+        if (level === 'debug' && !isDebugEnabledForModule(this.modulePath)) {
+            return;
+        }
+        const timestamp = getTimestamp();
+        const prefix = `${timestamp} [${level.toUpperCase()}]`;
+        let logMessage = `${prefix} ${this._formatMessage(message)}`;
+        const formattedArgs = this._formatArgs(args);
+        if (formattedArgs.length > 0) {
+            // Handle errors specifically
+            if (formattedArgs[0] instanceof Error) {
+                const error = formattedArgs[0];
+                logMessage += ` Error: ${error.message}`;
+                if (error.stack) {
+                    logMessage += `\n${error.stack}`;
+                }
+                // If there are more args, add them after the error
+                if (formattedArgs.length > 1) {
+                    logMessage += ` ${formattedArgs
+                        .slice(1)
+                        .map((arg) => typeof arg === 'string' ? arg : safeStringify(arg))
+                        .join(' ')}`;
+                }
+            }
+            else {
+                logMessage += ` ${formattedArgs
+                    .map((arg) => typeof arg === 'string' ? arg : safeStringify(arg))
+                    .join(' ')}`;
+            }
+        }
+        // Write to log file
+        try {
+            fs.appendFileSync(Logger.logFilePath, `${logMessage}\n`, 'utf8');
+        }
+        catch (err) {
+            // If we can't write to the log file, log the error to console
+            console.error(`Failed to write to log file: ${err}`);
+        }
+        // Only output to console if not in test environment or if debug is enabled
+        if (process.env.NODE_ENV !== 'test' || process.env.DEBUG === 'true') {
+            if (process.env.NODE_ENV === 'test') {
+                console[level](logMessage);
+            }
+            else {
+                console.error(logMessage);
+            }
+        }
+    }
+    info(message, ...args) {
+        this._log('info', message, ...args);
+    }
+    warn(message, ...args) {
+        this._log('warn', message, ...args);
+    }
+    error(message, ...args) {
+        this._log('error', message, ...args);
+    }
+    debug(message, ...args) {
+        this._log('debug', message, ...args);
+    }
+    /**
+     * Log essential information about an API response
+     * @param message Log message
+     * @param response API response object
+     * @param essentialKeys Keys to extract from the response
+     */
+    debugResponse(message, response, essentialKeys) {
+        const essentialInfo = extractEssentialValues(response, essentialKeys);
+        this.debug(message, essentialInfo);
+    }
+    /**
+     * Get the current session ID
+     * @returns The UUID for the current logging session
+     */
+    static getSessionId() {
+        return Logger.sessionId;
+    }
+    /**
+     * Get the current log file path
+     * @returns The path to the current log file
+     */
+    static getLogFilePath() {
+        return Logger.logFilePath;
+    }
+}
+exports.Logger = Logger;
+Logger.sessionId = SESSION_ID;
+Logger.logFilePath = LOG_FILEPATH;

package/dist/utils/toon.util.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Convert data to TOON format with JSON fallback.
+ *
+ * TOON (Token-Oriented Object Notation) is 30-60% more token-efficient than JSON
+ * for tabular data, making it ideal for LLM responses.
+ *
+ * @param data - The data to convert
+ * @param jsonFallback - JSON string to return if TOON encoding fails
+ * @returns TOON formatted string, or JSON fallback on failure
+ *
+ * @example
+ * const json = JSON.stringify(data, null, 2);
+ * const output = await toToonOrJson(data, json);
+ */
+export declare function toToonOrJson(data: unknown, jsonFallback: string): Promise<string>;

package/dist/utils/toon.util.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toToonOrJson = toToonOrJson;
+const logger_util_js_1 = require("./logger.util.js");
+const logger = logger_util_js_1.Logger.forContext('utils/toon.util.ts');
+/**
+ * Cached TOON encoder to avoid repeated dynamic imports
+ */
+let toonEncode = null;
+/**
+ * Dynamically loads the TOON encoder module.
+ * Uses dynamic import because @toon-format/toon is an ESM-only package.
+ *
+ * @returns Promise resolving to the encode function or null if loading fails
+ */
+async function loadToonEncoder() {
+    const methodLogger = logger.forMethod('loadToonEncoder');
+    // Return cached encoder if available
+    if (toonEncode) {
+        return toonEncode;
+    }
+    try {
+        methodLogger.debug('Loading TOON encoder module...');
+        // Dynamic import for ESM module in CommonJS project
+        const toon = await import('@toon-format/toon');
+        toonEncode = toon.encode;
+        methodLogger.debug('TOON encoder loaded successfully');
+        return toonEncode;
+    }
+    catch (error) {
+        methodLogger.error('Failed to load TOON encoder', error);
+        return null;
+    }
+}
+/**
+ * Convert data to TOON format with JSON fallback.
+ *
+ * TOON (Token-Oriented Object Notation) is 30-60% more token-efficient than JSON
+ * for tabular data, making it ideal for LLM responses.
+ *
+ * @param data - The data to convert
+ * @param jsonFallback - JSON string to return if TOON encoding fails
+ * @returns TOON formatted string, or JSON fallback on failure
+ *
+ * @example
+ * const json = JSON.stringify(data, null, 2);
+ * const output = await toToonOrJson(data, json);
+ */
+async function toToonOrJson(data, jsonFallback) {
+    const methodLogger = logger.forMethod('toToonOrJson');
+    try {
+        const encode = await loadToonEncoder();
+        if (!encode) {
+            methodLogger.debug('TOON encoder not available, using JSON fallback');
+            return jsonFallback;
+        }
+        const result = encode(data, { indent: 2 });
+        methodLogger.debug('Successfully converted to TOON format');
+        return result;
+    }
+    catch (error) {
+        methodLogger.error('TOON encoding failed, using JSON fallback', error);
+        return jsonFallback;
+    }
+}

package/dist/utils/transport.util.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Interface for IP API credentials.
+ * Note: API token is optional for the free tier.
+ */
+export interface IpApiCredentials {
+    apiToken?: string;
+}
+/**
+ * Interface for HTTP request options
+ */
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Retrieves IP API credentials from configuration.
+ * Specifically checks for IPAPI_API_TOKEN.
+ * @returns IpApiCredentials object containing the API token if found.
+ */
+export declare function getIpApiCredentials(): IpApiCredentials;
+/**
+ * Fetches data specifically from the ip-api.com endpoint.
+ * Handles URL construction, authentication (if token provided), and query parameters.
+ * Relies on the generic fetchApi function for the actual HTTP request.
+ *
+ * @param path The specific IP address or path component (e.g., "8.8.8.8"). Empty string for current IP.
+ * @param options Additional options like HTTP method, headers, body, and ip-api specific params.
+ * @param options.useHttps - Use HTTPS (requires paid plan for ip-api.com). Defaults to false.
+ * @param options.fields - Specific fields to request from ip-api.com.
+ * @param options.lang - Language code for response data.
+ * @returns The response data parsed as type T.
+ * @throws {McpError} If the request fails, including network errors, API errors, or parsing issues.
+ */
+export declare function fetchIpApi<T>(path: string, options?: RequestOptions & {
+    useHttps?: boolean;
+    fields?: string[];
+    lang?: string;
+}): Promise<T>;
+/**
+ * Generic and reusable function to fetch data from any API endpoint.
+ * Handles standard HTTP request setup, response checking, basic error handling, and logging.
+ *
+ * @param url The full URL to fetch data from.
+ * @param options Request options including method, headers, and body.
+ * @returns The response data parsed as type T.
+ * @throws {McpError} If the request fails, including network errors, non-OK HTTP status, or JSON parsing issues.
+ */
+export declare function fetchApi<T>(url: string, options?: RequestOptions): Promise<T>;

package/dist/utils/transport.util.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIpApiCredentials = getIpApiCredentials;
+exports.fetchIpApi = fetchIpApi;
+exports.fetchApi = fetchApi;
+const logger_util_js_1 = require("./logger.util.js");
+const config_util_js_1 = require("./config.util.js");
+const error_util_js_1 = require("./error.util.js");
+// Create a contextualized logger for this file
+const transportLogger = logger_util_js_1.Logger.forContext('utils/transport.util.ts');
+// Log transport utility initialization
+transportLogger.debug('Transport utility initialized');
+/**
+ * Retrieves IP API credentials from configuration.
+ * Specifically checks for IPAPI_API_TOKEN.
+ * @returns IpApiCredentials object containing the API token if found.
+ */
+function getIpApiCredentials() {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/transport.util.ts', 'getIpApiCredentials');
+    const apiToken = config_util_js_1.config.get('IPAPI_API_TOKEN');
+    if (!apiToken) {
+        methodLogger.debug('No IP API token found (IPAPI_API_TOKEN). Using free tier.');
+        return {}; // Return empty object if no token
+    }
+    else {
+        methodLogger.debug('Using IP API token from configuration.');
+        return { apiToken };
+    }
+}
+/**
+ * Fetches data specifically from the ip-api.com endpoint.
+ * Handles URL construction, authentication (if token provided), and query parameters.
+ * Relies on the generic fetchApi function for the actual HTTP request.
+ *
+ * @param path The specific IP address or path component (e.g., "8.8.8.8"). Empty string for current IP.
+ * @param options Additional options like HTTP method, headers, body, and ip-api specific params.
+ * @param options.useHttps - Use HTTPS (requires paid plan for ip-api.com). Defaults to false.
+ * @param options.fields - Specific fields to request from ip-api.com.
+ * @param options.lang - Language code for response data.
+ * @returns The response data parsed as type T.
+ * @throws {McpError} If the request fails, including network errors, API errors, or parsing issues.
+ */
+async function fetchIpApi(path, options = {}) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/transport.util.ts', 'fetchIpApi');
+    // Get credentials (token might be undefined)
+    const credentials = getIpApiCredentials();
+    // Determine protocol based on options
+    const protocol = options.useHttps ? 'https' : 'http';
+    const baseUrl = `${protocol}://ip-api.com/json`;
+    // Format path for URL
+    const normalizedPath = path ? `/${path}` : '';
+    let url = `${baseUrl}${normalizedPath}`;
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    // Add API token if present
+    if (credentials.apiToken) {
+        queryParams.set('key', credentials.apiToken);
+        methodLogger.debug('API token added to query parameters.');
+    }
+    // Add fields parameter
+    if (options.fields?.length) {
+        queryParams.set('fields', options.fields.join(','));
+        methodLogger.debug(`Requesting fields: ${options.fields.join(',')}`);
+    }
+    // Add language parameter
+    if (options.lang) {
+        queryParams.set('lang', options.lang);
+        methodLogger.debug(`Requesting language: ${options.lang}`);
+    }
+    // Append query string if needed
+    const queryString = queryParams.toString();
+    if (queryString) {
+        url += `?${queryString}`;
+    }
+    methodLogger.debug(`Constructed URL: ${url}`);
+    // Delegate the actual fetch call to the generic fetchApi
+    return fetchApi(url, {
+        method: options.method,
+        headers: options.headers,
+        body: options.body,
+    });
+}
+/**
+ * Generic and reusable function to fetch data from any API endpoint.
+ * Handles standard HTTP request setup, response checking, basic error handling, and logging.
+ *
+ * @param url The full URL to fetch data from.
+ * @param options Request options including method, headers, and body.
+ * @returns The response data parsed as type T.
+ * @throws {McpError} If the request fails, including network errors, non-OK HTTP status, or JSON parsing issues.
+ */
+async function fetchApi(url, options = {}) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/transport.util.ts', 'fetchApi');
+    // Prepare standard request options
+    const requestOptions = {
+        method: options.method || 'GET',
+        headers: {
+            // Standard headers, allow overrides via options.headers
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...options.headers,
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    };
+    methodLogger.debug(`Executing API call: ${requestOptions.method} ${url}`);
+    const startTime = performance.now(); // Track performance
+    try {
+        const response = await fetch(url, requestOptions);
+        const endTime = performance.now();
+        const duration = (endTime - startTime).toFixed(2);
+        methodLogger.debug(`API call completed in ${duration}ms with status: ${response.status} ${response.statusText}`, { url, status: response.status });
+        // Check if the response status is OK (2xx)
+        if (!response.ok) {
+            const errorText = await response.text(); // Get error body for context
+            methodLogger.error(`API error response (${response.status}):`, errorText);
+            // Classify standard HTTP errors
+            if (response.status === 401) {
+                // Use createAuthInvalidError for consistency, even if ip-api uses keys
+                throw (0, error_util_js_1.createAuthInvalidError)('Authentication failed. Check API token if required.');
+            }
+            else if (response.status === 403) {
+                // Use createAuthInvalidError or a more specific permission error if needed
+                throw (0, error_util_js_1.createAuthInvalidError)('Permission denied for the requested resource.');
+            }
+            else if (response.status === 404) {
+                throw (0, error_util_js_1.createApiError)('Resource not found at the specified URL.', response.status, errorText);
+            }
+            else {
+                // Generic API error for other non-2xx statuses
+                throw (0, error_util_js_1.createApiError)(`API request failed with status ${response.status}: ${response.statusText}`, response.status, errorText);
+            }
+        }
+        // Attempt to parse the response body as JSON
+        try {
+            const responseData = await response.json();
+            methodLogger.debug('Response body successfully parsed as JSON.');
+            return responseData;
+        }
+        catch (parseError) {
+            methodLogger.error('Failed to parse API response JSON:', parseError);
+            // Throw a specific error for JSON parsing failure
+            throw (0, error_util_js_1.createApiError)(`Failed to parse API response JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`, response.status, // Include original status for context
+            parseError);
+        }
+    }
+    catch (error) {
+        const endTime = performance.now();
+        const duration = (endTime - startTime).toFixed(2);
+        methodLogger.error(`API call failed after ${duration}ms for ${url}:`, error);
+        // Rethrow if it's already an McpError (e.g., from status checks or parsing)
+        if (error instanceof error_util_js_1.McpError) {
+            throw error;
+        }
+        // Handle potential network errors (TypeError in fetch)
+        if (error instanceof TypeError) {
+            throw (0, error_util_js_1.createApiError)(`Network error during API call: ${error.message}`, undefined, // No specific HTTP status for network errors
+            error);
+        }
+        // Wrap any other unexpected errors
+        throw (0, error_util_js_1.createUnexpectedError)(`Unexpected error during API call: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}

package/eslint.config.mjs

@@ -0,0 +1,46 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettierPlugin from 'eslint-plugin-prettier';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+	{
+		ignores: ['node_modules/**', 'dist/**', 'examples/**'],
+	},
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+	{
+		plugins: {
+			prettier: prettierPlugin,
+		},
+		rules: {
+			'prettier/prettier': 'error',
+			indent: ['error', 'tab', { SwitchCase: 1 }],
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{ argsIgnorePattern: '^_' },
+			],
+		},
+		languageOptions: {
+			parserOptions: {
+				ecmaVersion: 'latest',
+				sourceType: 'module',
+			},
+			globals: {
+				node: 'readonly',
+				jest: 'readonly',
+			},
+		},
+	},
+	// Special rules for test files
+	{
+		files: ['**/*.test.ts'],
+		rules: {
+			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/no-require-imports': 'off',
+			'@typescript-eslint/no-unsafe-function-type': 'off',
+			'@typescript-eslint/no-unused-vars': 'off',
+		},
+	},
+	eslintConfigPrettier,
+);