mcp-wordpress 2.4.2 → 2.5.1

package/dist/src/utils/debug.js

@@ -0,0 +1,235 @@
+/**
+ * Debug Utility for MCP Server
+ *
+ * This module provides debug logging that only outputs when DEBUG mode is enabled.
+ * This prevents console.log from interfering with MCP STDIO communication.
+ */
+import { config } from "../config/Config.js";
+import { ConfigHelpers } from "../config/Config.js";
+// Check if debug mode is enabled
+const isDebugMode = () => ConfigHelpers.shouldDebug();
+// Get current timestamp
+const getTimestamp = () => new Date().toISOString();
+// Format log message with timestamp and level
+const formatMessage = (level, args) => {
+    const timestamp = getTimestamp();
+    const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+    return `${prefix} ${args
+        .map((arg) => (typeof arg === "object" ? JSON.stringify(arg, null, 2) : String(arg)))
+        .join(" ")}`;
+};
+// Handle circular references in objects
+const safeStringify = (obj) => {
+    try {
+        return JSON.stringify(obj, (key, value) => {
+            if (value instanceof Error) {
+                return {
+                    name: value.name,
+                    message: value.message,
+                    stack: value.stack,
+                };
+            }
+            return value;
+        }, 2);
+    }
+    catch (_error) {
+        return "[Object with circular reference]";
+    }
+};
+/**
+ * Debug logger that only outputs in debug mode
+ */
+export const debug = {
+    log: (...args) => {
+        if (isDebugMode()) {
+            console.error(formatMessage("debug", args)); // Use stderr for debug to avoid STDIO interference
+        }
+    },
+    info: (...args) => {
+        if (isDebugMode()) {
+            console.error(formatMessage("info", args));
+        }
+    },
+    warn: (...args) => {
+        if (isDebugMode()) {
+            console.error(formatMessage("warn", args));
+        }
+    },
+    error: (...args) => {
+        if (isDebugMode()) {
+            console.error(formatMessage("error", args));
+        }
+    },
+};
+/**
+ * Silent logger for production use
+ */
+export const silent = {
+    log: () => { },
+    warn: () => { },
+    error: () => { },
+    info: () => { },
+};
+/**
+ * Enhanced structured logger
+ */
+class StructuredLoggerImpl {
+    context;
+    enabled;
+    constructor(context = {}, enabled = isDebugMode()) {
+        this.context = context;
+        this.enabled = enabled;
+    }
+    output(level, args) {
+        if (!this.enabled)
+            return;
+        const debugInfo = {
+            timestamp: Date.now(),
+            level,
+            message: args.map((arg) => (typeof arg === "object" ? safeStringify(arg) : String(arg))).join(" "),
+            ...(Object.keys(this.context).length > 0 && { context: this.context }),
+        };
+        console.error(safeStringify(debugInfo));
+    }
+    log(...args) {
+        this.output("debug", args);
+    }
+    info(...args) {
+        this.output("info", args);
+    }
+    warn(...args) {
+        this.output("warn", args);
+    }
+    error(...args) {
+        this.output("error", args);
+    }
+    logStructured(info) {
+        if (!this.enabled)
+            return;
+        const enhancedInfo = {
+            ...info,
+            context: { ...this.context, ...info.context },
+        };
+        console.error(safeStringify(enhancedInfo));
+    }
+    child(context) {
+        return new StructuredLoggerImpl({ ...this.context, ...context }, this.enabled);
+    }
+}
+/**
+ * Create a structured logger instance
+ */
+export const createStructuredLogger = (context = {}) => {
+    return new StructuredLoggerImpl(context);
+};
+/**
+ * Default logger instance
+ */
+export const logger = debug;
+/**
+ * Create a logger with context
+ */
+export const createLogger = (context = {}) => {
+    return createStructuredLogger(context);
+};
+export const startTimer = (label) => {
+    const start = Date.now();
+    return {
+        end() {
+            return Date.now() - start;
+        },
+        endWithLog(message = "Operation") {
+            const duration = Date.now() - start;
+            debug.info(`${message} completed in ${duration}ms${label ? ` [${label}]` : ""}`);
+            return duration;
+        },
+    };
+};
+/**
+ * Log error with stack trace
+ */
+export const logError = (error, context) => {
+    if (typeof error === "string") {
+        debug.error(error, context);
+    }
+    else {
+        debug.error(`${error.name}: ${error.message}`, {
+            stack: error.stack,
+            ...context,
+        });
+    }
+};
+/**
+ * Conditional logging
+ */
+export const logIf = (condition, level = "debug") => {
+    if (!condition)
+        return silent;
+    const loggers = {
+        log: debug.log,
+        info: debug.info,
+        warn: debug.warn,
+        error: debug.error,
+    };
+    return loggers[level] || debug.log;
+};
+/**
+ * Type-safe environment variable getter with security logging
+ */
+export const getEnvVar = (key, defaultValue) => {
+    const value = process.env[key];
+    if (value === undefined && defaultValue !== undefined) {
+        // Don't log sensitive environment variable names in production
+        const isSecretVar = /password|secret|token|key|auth/i.test(key);
+        if (!isSecretVar || !config().app.isProduction) {
+            debug.warn(`Environment variable ${key} not found, using default`);
+        }
+        return defaultValue;
+    }
+    return value;
+};
+/**
+ * Validate required environment variables with secure error messages
+ */
+export const validateEnvVars = (required) => {
+    const missing = required.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+        // In production, don't expose which specific env vars are missing
+        const errorMessage = config().app.isProduction
+            ? `Missing ${missing.length} required environment variable(s)`
+            : `Missing required environment variables: ${missing.join(", ")}`;
+        const error = new Error(errorMessage);
+        logError(error);
+        throw error;
+    }
+};
+/**
+ * Sanitize environment variable for logging
+ */
+export const sanitizeEnvValue = (key, value) => {
+    const sensitiveKeys = /password|secret|token|key|auth|credential/i;
+    if (sensitiveKeys.test(key)) {
+        if (!value || value.length === 0) {
+            return "[EMPTY]";
+        }
+        return `[REDACTED:${value.length}chars]`;
+    }
+    return value;
+};
+/**
+ * Get sanitized environment summary for debugging
+ */
+export const getEnvSummary = (keys) => {
+    const summary = {};
+    for (const key of keys) {
+        const value = process.env[key];
+        if (value !== undefined) {
+            summary[key] = sanitizeEnvValue(key, value);
+        }
+        else {
+            summary[key] = "[NOT_SET]";
+        }
+    }
+    return summary;
+};
+//# sourceMappingURL=debug.js.map

package/dist/src/utils/debug.js.map

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

package/dist/src/utils/enhancedError.d.ts

@@ -0,0 +1,61 @@
+export interface ErrorContext {
+    operation: string;
+    parameters?: Record<string, unknown>;
+    suggestions?: string[];
+    troubleshooting?: string[];
+}
+/**
+ * Enhanced error handling with helpful messages and suggestions
+ */
+export declare class EnhancedError extends Error {
+    suggestions: string[];
+    troubleshooting: string[];
+    context: ErrorContext;
+    constructor(message: string, context: ErrorContext);
+    /**
+     * Format error message with suggestions
+     */
+    toString(): string;
+}
+/**
+ * Common error handlers with context-aware suggestions
+ */
+export declare class ErrorHandlers {
+    /**
+     * Handle post not found errors
+     */
+    static postNotFound(postId: number, originalError: unknown): EnhancedError;
+    /**
+     * Handle authentication errors
+     */
+    static authenticationFailed(originalError: unknown): EnhancedError;
+    /**
+     * Handle site parameter missing errors
+     */
+    static siteParameterMissing(availableSites: string[]): EnhancedError;
+    /**
+     * Handle site not found errors
+     */
+    static siteNotFound(siteId: string, availableSites: string[]): EnhancedError;
+    /**
+     * Handle permission errors
+     */
+    static permissionDenied(operation: string, originalError: unknown): EnhancedError;
+    /**
+     * Handle network/connection errors
+     */
+    static connectionError(originalError: unknown): EnhancedError;
+    /**
+     * Handle validation errors
+     */
+    static validationError(field: string, value: unknown, expectedType: string): EnhancedError;
+    /**
+     * Handle rate limiting errors
+     */
+    static rateLimitExceeded(originalError: unknown): EnhancedError;
+    /**
+     * Generic error handler with basic suggestions
+     */
+    static generic(operation: string, originalError: unknown): EnhancedError;
+}
+//# sourceMappingURL=enhancedError.d.ts.map

package/dist/src/utils/enhancedError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhancedError.d.ts","sourceRoot":"","sources":["../../../src/utils/enhancedError.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,YAAY,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;IAQlD;;OAEG;IACH,QAAQ,IAAI,MAAM;CAmBnB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,aAAa;IAqB1E;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,aAAa,EAAE,OAAO,GAAG,aAAa;IAqBlE;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,aAAa;IAgBpE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,aAAa;IAiB5E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,aAAa;IAmBjF;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,aAAa,EAAE,OAAO,GAAG,aAAa;IAmB7D;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa;IAiB1F;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,aAAa,EAAE,OAAO,GAAG,aAAa;IAmB/D;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,aAAa;CAkBzE"}

package/dist/src/utils/enhancedError.js

@@ -0,0 +1,221 @@
+import { getErrorMessage } from "./error.js";
+/**
+ * Enhanced error handling with helpful messages and suggestions
+ */
+export class EnhancedError extends Error {
+    suggestions;
+    troubleshooting;
+    context;
+    constructor(message, context) {
+        super(message);
+        this.name = "EnhancedError";
+        this.context = context;
+        this.suggestions = context.suggestions || [];
+        this.troubleshooting = context.troubleshooting || [];
+    }
+    /**
+     * Format error message with suggestions
+     */
+    toString() {
+        let message = `❌ ${this.message}`;
+        if (this.suggestions.length > 0) {
+            message += `\n\n💡 **Suggestions:**\n`;
+            this.suggestions.forEach((suggestion) => {
+                message += `• ${suggestion}\n`;
+            });
+        }
+        if (this.troubleshooting.length > 0) {
+            message += `\n🔧 **Troubleshooting:**\n`;
+            this.troubleshooting.forEach((step) => {
+                message += `• ${step}\n`;
+            });
+        }
+        return message;
+    }
+}
+/**
+ * Common error handlers with context-aware suggestions
+ */
+export class ErrorHandlers {
+    /**
+     * Handle post not found errors
+     */
+    static postNotFound(postId, originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError(`Post with ID ${postId} not found`, {
+            operation: "get_post",
+            parameters: { postId },
+            suggestions: [
+                "Check if the post ID is correct",
+                "Verify the post exists and is published",
+                "Try listing posts first with wp_list_posts to see available posts",
+                "Check if you have permission to view this post",
+            ],
+            troubleshooting: [
+                "Use wp_list_posts to see all available posts",
+                "Check the post status - it might be draft, private, or trashed",
+                "Verify your user permissions for viewing posts",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+    /**
+     * Handle authentication errors
+     */
+    static authenticationFailed(originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError("Authentication failed", {
+            operation: "authenticate",
+            suggestions: [
+                "Check your WordPress credentials (username and app password)",
+                "Verify the WordPress site URL is correct",
+                "Ensure application passwords are enabled on your WordPress site",
+                "Try regenerating your application password",
+            ],
+            troubleshooting: [
+                "Go to your WordPress admin → Users → Profile → Application Passwords",
+                "Create a new application password with a descriptive name",
+                "Make sure the WordPress site URL ends with wp-json/wp/v2",
+                "Check if your site has any security plugins blocking REST API",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+    /**
+     * Handle site parameter missing errors
+     */
+    static siteParameterMissing(availableSites) {
+        return new EnhancedError("Multiple sites configured - site parameter required", {
+            operation: "site_selection",
+            suggestions: [
+                "Add --site parameter to specify which site to use",
+                `Available sites: ${availableSites.join(", ")}`,
+                'Example: wp_list_posts --site="your-site-id"',
+            ],
+            troubleshooting: [
+                "Check your mcp-wordpress.config.json for configured sites",
+                "Use the site ID from your configuration file",
+                "Site IDs are defined in the 'id' field of each site config",
+            ],
+        });
+    }
+    /**
+     * Handle site not found errors
+     */
+    static siteNotFound(siteId, availableSites) {
+        return new EnhancedError(`Site with ID '${siteId}' not found`, {
+            operation: "site_selection",
+            parameters: { siteId },
+            suggestions: [
+                `Available sites: ${availableSites.join(", ")}`,
+                "Check the spelling of the site ID",
+                "Verify the site is configured in mcp-wordpress.config.json",
+            ],
+            troubleshooting: [
+                "Open mcp-wordpress.config.json to see configured sites",
+                "Check the 'id' field for each site configuration",
+                "Ensure the site ID matches exactly (case-sensitive)",
+            ],
+        });
+    }
+    /**
+     * Handle permission errors
+     */
+    static permissionDenied(operation, originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError(`Permission denied for ${operation}`, {
+            operation,
+            suggestions: [
+                "Check if your user has the required permissions",
+                "Verify you're logged in with the correct user account",
+                "Contact your WordPress administrator for permission changes",
+            ],
+            troubleshooting: [
+                "Check your user role in WordPress admin → Users",
+                "Verify the required capabilities for this operation",
+                "Try using an administrator account",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+    /**
+     * Handle network/connection errors
+     */
+    static connectionError(originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError("Failed to connect to WordPress site", {
+            operation: "connection",
+            suggestions: [
+                "Check your internet connection",
+                "Verify the WordPress site URL is correct and accessible",
+                "Check if the site is temporarily down",
+            ],
+            troubleshooting: [
+                "Try accessing the site in your browser",
+                "Check if the REST API is enabled: visit yoursite.com/wp-json/",
+                "Verify there are no firewall or security plugins blocking access",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+    /**
+     * Handle validation errors
+     */
+    static validationError(field, value, expectedType) {
+        return new EnhancedError(`Invalid ${field}: expected ${expectedType}, got ${typeof value}`, {
+            operation: "validation",
+            parameters: { field, value, expectedType },
+            suggestions: [
+                `Provide a valid ${expectedType} for ${field}`,
+                "Check the parameter format and type",
+                "Refer to the tool documentation for correct parameter format",
+            ],
+            troubleshooting: [
+                "Review the tool's parameter requirements",
+                "Check for typos in parameter names",
+                "Ensure parameter values match the expected type",
+            ],
+        });
+    }
+    /**
+     * Handle rate limiting errors
+     */
+    static rateLimitExceeded(originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError("Rate limit exceeded", {
+            operation: "rate_limit",
+            suggestions: [
+                "Wait a few minutes before trying again",
+                "Reduce the frequency of requests",
+                "Use pagination for large operations",
+            ],
+            troubleshooting: [
+                "Check your WordPress hosting plan limits",
+                "Consider upgrading your hosting plan for higher limits",
+                "Implement delays between requests",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+    /**
+     * Generic error handler with basic suggestions
+     */
+    static generic(operation, originalError) {
+        const errorMessage = getErrorMessage(originalError);
+        return new EnhancedError(`Failed to ${operation}`, {
+            operation,
+            suggestions: [
+                "Check your WordPress credentials and permissions",
+                "Verify the site is accessible and functioning",
+                "Try the operation again after a brief wait",
+            ],
+            troubleshooting: [
+                "Test your connection with a simpler operation first",
+                "Check WordPress admin for any issues",
+                "Review the WordPress error logs",
+                `Original error: ${errorMessage}`,
+            ],
+        });
+    }
+}
+//# sourceMappingURL=enhancedError.js.map

package/dist/src/utils/enhancedError.js.map

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

package/dist/src/utils/error.d.ts

@@ -0,0 +1,17 @@
+export declare const __errorUtilsLogger: import("./logger.js").Logger;
+export declare function getErrorMessage(error: unknown): string;
+export declare function isError(error: unknown): error is Error;
+export declare function logAndReturn<T>(error: unknown, defaultValue: T): T;
+/**
+ * Enhanced error handler for consistent tool error handling
+ */
+export declare function handleToolError(error: unknown, operation: string, context?: Record<string, unknown>): never;
+/**
+ * Validates required parameters
+ */
+export declare function validateRequired(params: Record<string, unknown> | unknown, required: string[]): void;
+/**
+ * Validates site parameter for multi-site configurations
+ */
+export declare function validateSite(site: string | undefined, availableSites: string[]): string;
+//# sourceMappingURL=error.d.ts.map

package/dist/src/utils/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/utils/error.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,kBAAkB,8BAAS,CAAC;AAEzC,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CActD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAQlE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAqC3G;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAWpG;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAevF"}

package/dist/src/utils/error.js

@@ -0,0 +1,108 @@
+/**
+ * Error handling utilities
+ */
+import { LoggerFactory } from "./logger.js";
+import { config } from "../config/Config.js";
+const logger = LoggerFactory.server().child({ component: "ErrorUtils" });
+// Environment flag to control legacy console logging noise. Default enabled to preserve
+// backward compatibility and existing test expectations. Set LEGACY_ERROR_LOGS=0 to disable
+// the direct console.error side-channel (structured logger still emits).
+const LEGACY_ERROR_LOGS_ENABLED = config().error.legacyLogsEnabled;
+// Internal helper to avoid sprinkling conditionals
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function legacyConsoleError(...args) {
+    if (LEGACY_ERROR_LOGS_ENABLED) {
+        console.error(...args);
+    }
+}
+// Test hook: exported only for instrumentation in unit tests (tree-shakeable)
+// @__PURE__ This constant has no side effects and can be dropped in production builds
+export const __errorUtilsLogger = logger;
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    if (error && typeof error === "object" && "message" in error) {
+        return String(error.message);
+    }
+    return "Unknown error occurred";
+}
+export function isError(error) {
+    return error instanceof Error;
+}
+export function logAndReturn(error, defaultValue) {
+    const message = getErrorMessage(error);
+    // Legacy console logging (can be disabled via LEGACY_ERROR_LOGS=0)
+    legacyConsoleError("Error occurred:", message);
+    logger.warn("Error occurred - returning default value", {
+        error: message,
+    });
+    return defaultValue;
+}
+/**
+ * Enhanced error handler for consistent tool error handling
+ */
+export function handleToolError(error, operation, context) {
+    const message = getErrorMessage(error);
+    const errObj = error instanceof Error ? error : new Error(message);
+    // Legacy console logging (can be disabled via LEGACY_ERROR_LOGS=0)
+    legacyConsoleError(`Error in ${operation}:`, errObj);
+    if (context) {
+        legacyConsoleError("Context:", context);
+    }
+    logger.error(`Error in ${operation}`, {
+        error: message,
+        ...(context && { context }),
+    });
+    if (error instanceof Error && error.stack) {
+        logger.debug("Error stack trace", { stack: error.stack });
+    }
+    // Provide more specific error messages based on error content
+    if (message.includes("ECONNREFUSED") || message.includes("ENOTFOUND")) {
+        throw new Error(`Connection failed during ${operation}. Please check your WordPress site URL and network connection.`);
+    }
+    if (message.includes("401") || message.includes("Unauthorized")) {
+        throw new Error(`Authentication failed during ${operation}. Please check your WordPress credentials.`);
+    }
+    if (message.includes("403") || message.includes("Forbidden")) {
+        throw new Error(`Permission denied during ${operation}. Please check your user permissions.`);
+    }
+    if (message.includes("429") || message.includes("Too Many Requests")) {
+        throw new Error(`Rate limit exceeded during ${operation}. Please try again later.`);
+    }
+    throw new Error(`Failed to ${operation}: ${message}`);
+}
+/**
+ * Validates required parameters
+ */
+export function validateRequired(params, required) {
+    // Runtime guard: ensure params is a non-null object (tests expect throw on invalid input)
+    if (params === null || typeof params !== "object") {
+        throw new Error("Parameters must be an object");
+    }
+    // Only treat undefined or null as missing; accept legitimate falsy values: 0, false, ""
+    const obj = params;
+    const missing = required.filter((key) => obj[key] === undefined || obj[key] === null);
+    if (missing.length > 0) {
+        throw new Error(`Missing required parameters: ${missing.join(", ")}`);
+    }
+}
+/**
+ * Validates site parameter for multi-site configurations
+ */
+export function validateSite(site, availableSites) {
+    if (!site) {
+        if (availableSites.length === 1) {
+            return availableSites[0];
+        }
+        throw new Error(`Site parameter is required when multiple sites are configured. Available sites: ${availableSites.join(", ")}`);
+    }
+    if (!availableSites.includes(site)) {
+        throw new Error(`Site '${site}' not found. Available sites: ${availableSites.join(", ")}`);
+    }
+    return site;
+}
+//# sourceMappingURL=error.js.map