service-keepalive 1.0.0

package/dist/index.js

@@ -0,0 +1,1121 @@
+import { EventEmitter } from 'events';
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { pathToFileURL } from 'url';
+
+// src/keepalive.ts
+
+// src/utils/duration.ts
+var TIME_UNITS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1e3,
+  sec: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  m: 60 * 1e3,
+  min: 60 * 1e3,
+  minute: 60 * 1e3,
+  minutes: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  hr: 60 * 60 * 1e3,
+  hour: 60 * 60 * 1e3,
+  hours: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3,
+  day: 24 * 60 * 60 * 1e3,
+  days: 24 * 60 * 60 * 1e3
+};
+var DURATION_REGEX = /^(\s*(\d+(?:\.\d+)?)\s*([a-zA-Z]+)\s*)+$/;
+var DURATION_PART_REGEX = /(\d+(?:\.\d+)?)\s*([a-zA-Z]+)/g;
+function parseDuration(value, fieldName = "Duration") {
+  if (value === null || value === void 0) {
+    throw new TypeError(`${fieldName} must be provided as a string or number.`);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || Number.isNaN(value)) {
+      throw new RangeError(`${fieldName} must be a finite number, received ${value}.`);
+    }
+    if (value <= 0) {
+      throw new RangeError(`${fieldName} must be greater than 0, received ${value}.`);
+    }
+    return Math.round(value);
+  }
+  if (typeof value !== "string") {
+    throw new TypeError(`${fieldName} must be a string or number, received ${typeof value}.`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new RangeError(`${fieldName} cannot be an empty string.`);
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const parsedNumber = Number(trimmed);
+    if (parsedNumber <= 0) {
+      throw new RangeError(`${fieldName} must be greater than 0.`);
+    }
+    return parsedNumber;
+  }
+  if (!DURATION_REGEX.test(trimmed)) {
+    throw new RangeError(
+      `Invalid ${fieldName} format: "${value}". Expected formats like "10s", "1m", "5m", "1h", "500ms".`
+    );
+  }
+  let totalMs = 0;
+  let match;
+  DURATION_PART_REGEX.lastIndex = 0;
+  while ((match = DURATION_PART_REGEX.exec(trimmed)) !== null) {
+    const amountStr = match[1];
+    const unitStr = match[2];
+    if (!amountStr || !unitStr) {
+      throw new RangeError(`Failed parsing ${fieldName} segment "${match[0]}".`);
+    }
+    const amount = parseFloat(amountStr);
+    const unit = unitStr.toLowerCase();
+    const multiplier = TIME_UNITS[unit];
+    if (!multiplier) {
+      throw new RangeError(
+        `Unknown time unit "${unit}" in ${fieldName}. Supported units: ms, s, m, h, d.`
+      );
+    }
+    if (amount < 0 || !Number.isFinite(amount)) {
+      throw new RangeError(`Invalid amount "${amount}" for unit "${unit}" in ${fieldName}.`);
+    }
+    totalMs += amount * multiplier;
+  }
+  const rounded = Math.round(totalMs);
+  if (rounded <= 0) {
+    throw new RangeError(`${fieldName} must evaluate to greater than 0ms.`);
+  }
+  return rounded;
+}
+function formatDuration(ms) {
+  if (ms < 1e3) {
+    return `${Math.round(ms)}ms`;
+  }
+  const seconds = Math.floor(ms / 1e3 % 60);
+  const minutes = Math.floor(ms / (1e3 * 60) % 60);
+  const hours = Math.floor(ms / (1e3 * 60 * 60) % 24);
+  const days = Math.floor(ms / (1e3 * 60 * 60 * 24));
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+  return parts.length > 0 ? parts.join(" ") : `${ms}ms`;
+}
+
+// src/utils/redact.ts
+var SENSITIVE_HEADER_PATTERNS = [
+  /authorization/i,
+  /cookie/i,
+  /token/i,
+  /secret/i,
+  /password/i,
+  /api[_-]?key/i,
+  /auth/i,
+  /session/i,
+  /credential/i,
+  /private[_-]?key/i
+];
+var SENSITIVE_QUERY_PARAMS = [
+  "token",
+  "key",
+  "api_key",
+  "apikey",
+  "secret",
+  "password",
+  "passwd",
+  "auth",
+  "access_token",
+  "bearer",
+  "session"
+];
+function redactHeaders(headers) {
+  if (!headers) return {};
+  const sanitized = {};
+  for (const [key, value] of Object.entries(headers)) {
+    const isSensitive = SENSITIVE_HEADER_PATTERNS.some((pattern) => pattern.test(key));
+    if (isSensitive) {
+      sanitized[key] = "[REDACTED]";
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+function redactUrl(urlStr) {
+  try {
+    const url = new URL(urlStr);
+    let modified = false;
+    for (const param of SENSITIVE_QUERY_PARAMS) {
+      if (url.searchParams.has(param)) {
+        url.searchParams.set(param, "[REDACTED]");
+        modified = true;
+      }
+    }
+    return modified ? url.toString() : urlStr;
+  } catch {
+    return urlStr;
+  }
+}
+
+// src/logger.ts
+var COLORS = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m"
+};
+function supportsColor() {
+  if (typeof process === "undefined") return false;
+  if ("NO_COLOR" in process.env && process.env["NO_COLOR"] !== "") return false;
+  if ("FORCE_COLOR" in process.env && process.env["FORCE_COLOR"] !== "0") return true;
+  return Boolean(process.stdout && process.stdout.isTTY);
+}
+var isColorSupported = supportsColor();
+function colorize(text, color) {
+  if (!isColorSupported) return text;
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+function formatTimestamp(date = /* @__PURE__ */ new Date()) {
+  const pad = (n) => n.toString().padStart(2, "0");
+  const h = pad(date.getHours());
+  const m = pad(date.getMinutes());
+  const s = pad(date.getSeconds());
+  return `${h}:${m}:${s}`;
+}
+var Logger = class {
+  logLevel;
+  prefix;
+  constructor(options = {}) {
+    this.logLevel = options.logLevel ?? "normal";
+    this.prefix = options.prefix;
+  }
+  setLevel(level) {
+    this.logLevel = level;
+  }
+  setPrefix(prefix) {
+    this.prefix = prefix;
+  }
+  shouldLog(level) {
+    if (this.logLevel === "quiet") {
+      return level === "quiet";
+    }
+    if (this.logLevel === "normal") {
+      return level !== "verbose";
+    }
+    return true;
+  }
+  formatLine(content, timeColor = "gray") {
+    const timeStr = colorize(`[${formatTimestamp()}]`, timeColor);
+    const prefixStr = this.prefix ? colorize(`[${this.prefix}] `, "cyan") : "";
+    return `${timeStr} ${prefixStr}${content}`;
+  }
+  info(message, ...args) {
+    if (!this.shouldLog("normal")) return;
+    const formatted = this.formatLine(message);
+    if (args.length > 0) {
+      console.log(formatted, ...args);
+    } else {
+      console.log(formatted);
+    }
+  }
+  success(message, ...args) {
+    if (!this.shouldLog("normal")) return;
+    const symbol = colorize("\u2713", "green");
+    const formatted = this.formatLine(`${symbol} ${colorize(message, "green")}`);
+    if (args.length > 0) {
+      console.log(formatted, ...args);
+    } else {
+      console.log(formatted);
+    }
+  }
+  warn(message, ...args) {
+    if (!this.shouldLog("normal")) return;
+    const symbol = colorize("\u26A0", "yellow");
+    const formatted = this.formatLine(`${symbol} ${colorize(message, "yellow")}`);
+    if (args.length > 0) {
+      console.warn(formatted, ...args);
+    } else {
+      console.warn(formatted);
+    }
+  }
+  error(message, ...args) {
+    const symbol = colorize("\u2717", "red");
+    const formatted = this.formatLine(`${symbol} ${colorize(message, "red")}`, "red");
+    if (args.length > 0) {
+      console.error(formatted, ...args);
+    } else {
+      console.error(formatted);
+    }
+  }
+  retry(message, ...args) {
+    if (!this.shouldLog("normal")) return;
+    const symbol = colorize("\u21BB", "yellow");
+    const formatted = this.formatLine(`${symbol} ${colorize(message, "yellow")}`);
+    if (args.length > 0) {
+      console.log(formatted, ...args);
+    } else {
+      console.log(formatted);
+    }
+  }
+  debug(message, ...args) {
+    if (!this.shouldLog("verbose")) return;
+    const label = colorize("[DEBUG]", "dim");
+    const formatted = this.formatLine(`${label} ${colorize(message, "dim")}`);
+    if (args.length > 0) {
+      console.debug(formatted, ...args);
+    } else {
+      console.debug(formatted);
+    }
+  }
+};
+
+// src/http-client.ts
+function isStatusSuccessful(status, expected) {
+  if (typeof expected === "function") {
+    return expected(status);
+  }
+  if (Array.isArray(expected) && expected.length > 0) {
+    return expected.includes(status);
+  }
+  return status >= 200 && status < 300;
+}
+async function executePing(options) {
+  const {
+    serviceName,
+    url,
+    method = "GET",
+    headers = {},
+    body = null,
+    timeoutMs,
+    attempt = 1,
+    expectedStatusCodes,
+    externalSignal
+  } = options;
+  const controller = new AbortController();
+  let timeoutId = null;
+  let didTimeout = false;
+  const onExternalAbort = () => {
+    controller.abort(new Error("Operation cancelled"));
+  };
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort(new Error("Operation cancelled"));
+    } else {
+      externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+  }
+  timeoutId = setTimeout(() => {
+    didTimeout = true;
+    controller.abort(new Error(`Request timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+  const requestHeaders = {
+    "User-Agent": "service-keepalive/1.0.0",
+    Accept: "*/*",
+    ...headers
+  };
+  const startTime = performance.now();
+  const timestamp = /* @__PURE__ */ new Date();
+  try {
+    const fetchOptions = {
+      method,
+      headers: requestHeaders,
+      signal: controller.signal
+    };
+    if (body && method !== "GET" && method !== "HEAD") {
+      fetchOptions.body = body;
+    }
+    const response = await fetch(url, fetchOptions);
+    const durationMs = Math.round(performance.now() - startTime);
+    const isOk = isStatusSuccessful(response.status, expectedStatusCodes);
+    try {
+      if (response.body) {
+        await response.text();
+      }
+    } catch {
+    }
+    const resHeaders = {};
+    response.headers.forEach((val, key) => {
+      resHeaders[key] = val;
+    });
+    return {
+      serviceName,
+      url,
+      method,
+      status: response.status,
+      statusText: response.statusText || `${response.status}`,
+      ok: isOk,
+      durationMs,
+      attempt,
+      timestamp,
+      headers: redactHeaders(resHeaders),
+      error: isOk ? void 0 : `HTTP ${response.status} ${response.statusText || "Error"}`
+    };
+  } catch (err) {
+    const durationMs = Math.round(performance.now() - startTime);
+    let errorMessage = "Unknown network error";
+    if (didTimeout) {
+      errorMessage = `Request timed out after ${timeoutMs}ms`;
+    } else if (err instanceof Error) {
+      if (err.name === "AbortError" || err.message.includes("aborted")) {
+        errorMessage = externalSignal?.aborted ? "Request cancelled by user" : `Request timed out after ${timeoutMs}ms`;
+      } else {
+        errorMessage = err.message;
+      }
+    }
+    return {
+      serviceName,
+      url,
+      method,
+      status: 0,
+      statusText: "Network Error",
+      ok: false,
+      durationMs,
+      attempt,
+      timestamp,
+      error: errorMessage
+    };
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    if (externalSignal) {
+      externalSignal.removeEventListener("abort", onExternalAbort);
+    }
+  }
+}
+
+// src/retry.ts
+function calculateBackoff(options) {
+  const {
+    attempt,
+    baseDelayMs,
+    strategy = "exponential",
+    maxDelayMs = 6e4,
+    jitter = true
+  } = options;
+  if (attempt <= 0) return 0;
+  let delay = baseDelayMs;
+  switch (strategy) {
+    case "exponential":
+      delay = baseDelayMs * Math.pow(2, attempt - 1);
+      break;
+    case "linear":
+      delay = baseDelayMs * attempt;
+      break;
+    case "fixed":
+    default:
+      delay = baseDelayMs;
+      break;
+  }
+  delay = Math.min(delay, maxDelayMs);
+  if (jitter) {
+    const jitterFactor = 0.8 + Math.random() * 0.4;
+    delay = Math.round(delay * jitterFactor);
+  } else {
+    delay = Math.round(delay);
+  }
+  return Math.max(0, delay);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    if (signal?.aborted) {
+      return reject(new Error("Operation aborted"));
+    }
+    let timer = null;
+    const onAbort = () => {
+      if (timer) clearTimeout(timer);
+      reject(new Error("Operation aborted"));
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    timer = setTimeout(() => {
+      if (signal) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve2();
+    }, ms);
+  });
+}
+
+// src/keepalive.ts
+var KeepAlive = class extends EventEmitter {
+  config;
+  running = false;
+  timer = null;
+  inFlightAbortController = null;
+  logger = null;
+  constructor(options) {
+    super();
+    this.config = this.resolveConfig(options);
+  }
+  resolveConfig(options) {
+    if (!options || typeof options !== "object") {
+      throw new TypeError("KeepAlive options must be an object.");
+    }
+    if (!options.url || typeof options.url !== "string") {
+      throw new TypeError("url is required and must be a string.");
+    }
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(options.url);
+      if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error("Protocol must be http or https");
+      }
+    } catch {
+      throw new Error(`Invalid URL: "${options.url}". Must be a valid http:// or https:// URL.`);
+    }
+    const name = options.name ?? parsedUrl.hostname;
+    const intervalMs = parseDuration(options.interval ?? "10m", "interval");
+    const timeoutMs = parseDuration(options.timeout ?? "30s", "timeout");
+    const method = options.method?.toUpperCase() ?? "GET";
+    const retries = Math.max(0, options.retries ?? 3);
+    const retryDelayMs = parseDuration(options.retryDelay ?? "5s", "retryDelay");
+    const maxRetryDelayMs = parseDuration(options.maxRetryDelay ?? "60s", "maxRetryDelay");
+    const retryStrategy = options.retryStrategy ?? "exponential";
+    const retryJitter = options.retryJitter ?? true;
+    const unrefTimer = options.unrefTimer ?? false;
+    const logLevel = options.logLevel ?? "normal";
+    let loggerInstance = null;
+    if (options.logger !== false) {
+      if (options.logger && typeof options.logger === "object") {
+        loggerInstance = options.logger;
+      } else {
+        loggerInstance = new Logger({ logLevel, prefix: name });
+      }
+    }
+    this.logger = loggerInstance;
+    return {
+      name,
+      url: options.url,
+      intervalMs,
+      timeoutMs,
+      method,
+      headers: options.headers ?? {},
+      body: options.body ?? null,
+      retries,
+      retryDelayMs,
+      retryStrategy,
+      retryJitter,
+      maxRetryDelayMs,
+      expectedStatusCodes: options.expectedStatusCodes ?? ((s) => s >= 200 && s < 300),
+      logger: loggerInstance,
+      logLevel,
+      unrefTimer
+    };
+  }
+  /**
+   * Returns whether the keep-alive scheduler is actively running.
+   */
+  isRunning() {
+    return this.running;
+  }
+  /**
+   * Returns the resolved service configuration.
+   */
+  getConfig() {
+    return Object.freeze({ ...this.config });
+  }
+  /**
+   * Starts the keep-alive scheduler.
+   * Performs an immediate ping, then continues at the configured interval.
+   */
+  start() {
+    if (this.running) {
+      this.logger?.debug(`Service [${this.config.name}] is already running.`);
+      return this;
+    }
+    this.running = true;
+    this.inFlightAbortController = new AbortController();
+    this.logger?.info(
+      `Starting keep-alive for ${redactUrl(this.config.url)} (interval: ${formatDuration(this.config.intervalMs)}, timeout: ${formatDuration(this.config.timeoutMs)})`
+    );
+    this.emit("start", this.config.name);
+    void this.runPingLoop();
+    return this;
+  }
+  /**
+   * Stops the keep-alive scheduler and aborts any active requests or wait timers.
+   */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.inFlightAbortController) {
+      this.inFlightAbortController.abort();
+      this.inFlightAbortController = null;
+    }
+    this.logger?.info(`Stopped keep-alive for ${this.config.name}.`);
+    this.emit("stop", this.config.name);
+  }
+  /**
+   * Executes a single ping cycle with retries without starting the recurring scheduler.
+   */
+  async pingOnce() {
+    const abortController = new AbortController();
+    return this.executePingWithRetries(abortController.signal);
+  }
+  /**
+   * Core scheduling loop. Executes a ping cycle, then schedules the next interval.
+   */
+  async runPingLoop() {
+    if (!this.running) return;
+    try {
+      this.inFlightAbortController = new AbortController();
+      await this.executePingWithRetries(this.inFlightAbortController.signal);
+    } catch (err) {
+      if (this.running) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)), this.config.name);
+      }
+    } finally {
+      this.inFlightAbortController = null;
+    }
+    if (!this.running) return;
+    this.timer = setTimeout(() => {
+      void this.runPingLoop();
+    }, this.config.intervalMs);
+    if (this.config.unrefTimer && this.timer && typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+  }
+  /**
+   * Executes the ping request, retrying on failure up to configured retry attempts.
+   */
+  async executePingWithRetries(signal) {
+    const maxAttempts = 1 + this.config.retries;
+    let lastResult = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      if (signal?.aborted) {
+        break;
+      }
+      this.logger?.info(`Pinging ${redactUrl(this.config.url)}`);
+      this.emit("ping", {
+        name: this.config.name,
+        url: this.config.url,
+        attempt
+      });
+      const result = await executePing({
+        serviceName: this.config.name,
+        url: this.config.url,
+        method: this.config.method,
+        headers: this.config.headers,
+        body: this.config.body,
+        timeoutMs: this.config.timeoutMs,
+        attempt,
+        expectedStatusCodes: this.config.expectedStatusCodes,
+        externalSignal: signal
+      });
+      lastResult = result;
+      if (result.ok) {
+        this.logger?.success(`${result.status} ${result.statusText} - ${result.durationMs}ms`);
+        if (this.config.logLevel === "verbose" && result.headers) {
+          this.logger?.debug(`Response headers: ${JSON.stringify(redactHeaders(result.headers))}`);
+        }
+        this.emit("success", result);
+        return result;
+      }
+      const errorDetail = result.error || `HTTP ${result.status}`;
+      this.logger?.error(`Request failed - ${errorDetail}`);
+      if (attempt < maxAttempts && (!signal || !signal.aborted)) {
+        const delayMs = calculateBackoff({
+          attempt,
+          baseDelayMs: this.config.retryDelayMs,
+          strategy: this.config.retryStrategy,
+          maxDelayMs: this.config.maxRetryDelayMs,
+          jitter: this.config.retryJitter
+        });
+        const retryInfo = {
+          serviceName: this.config.name,
+          url: this.config.url,
+          attempt,
+          maxRetries: this.config.retries,
+          delayMs,
+          error: errorDetail
+        };
+        if (this.logger && "retry" in this.logger && typeof this.logger.retry === "function") {
+          this.logger.retry(
+            `Retrying ${attempt}/${this.config.retries} in ${formatDuration(delayMs)}...`
+          );
+        } else {
+          this.logger?.warn(
+            `Retrying ${attempt}/${this.config.retries} in ${formatDuration(delayMs)}...`
+          );
+        }
+        this.emit("retry", retryInfo);
+        try {
+          await sleep(delayMs, signal);
+        } catch {
+          break;
+        }
+      }
+    }
+    const finalResult = lastResult ?? {
+      serviceName: this.config.name,
+      url: this.config.url,
+      method: this.config.method,
+      status: 0,
+      statusText: "Failed",
+      ok: false,
+      durationMs: 0,
+      attempt: maxAttempts,
+      timestamp: /* @__PURE__ */ new Date(),
+      error: "All retry attempts exhausted"
+    };
+    this.emit("failure", finalResult);
+    return finalResult;
+  }
+  // Type-safe event emitter methods
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+};
+var MultiKeepAlive = class extends EventEmitter {
+  services = [];
+  serviceMap = /* @__PURE__ */ new Map();
+  logger = null;
+  constructor(options) {
+    super();
+    if (!options || !Array.isArray(options.services) || options.services.length === 0) {
+      throw new TypeError(
+        'MultiKeepAlive requires a "services" array containing at least one service.'
+      );
+    }
+    const { defaults = {}, logger, logLevel = "normal" } = options;
+    if (logger !== false) {
+      if (logger && typeof logger === "object") {
+        this.logger = logger;
+      } else {
+        this.logger = new Logger({ logLevel, prefix: "MultiKeepAlive" });
+      }
+    }
+    for (const serviceConfig of options.services) {
+      const mergedConfig = {
+        ...defaults,
+        ...serviceConfig,
+        headers: {
+          ...defaults.headers,
+          ...serviceConfig.headers
+        },
+        logLevel: serviceConfig.logLevel ?? defaults.logLevel ?? logLevel,
+        logger: serviceConfig.logger !== void 0 ? serviceConfig.logger : logger
+      };
+      const instance = new KeepAlive(mergedConfig);
+      const name = instance.getConfig().name;
+      if (this.serviceMap.has(name)) {
+        throw new Error(
+          `Duplicate service name detected: "${name}". Each service must have a unique name.`
+        );
+      }
+      this.services.push(instance);
+      this.serviceMap.set(name, instance);
+      this.forwardEvents(instance);
+    }
+  }
+  forwardEvents(instance) {
+    instance.on("start", (name) => this.emit("start", name));
+    instance.on("stop", (name) => this.emit("stop", name));
+    instance.on(
+      "ping",
+      (info) => this.emit("ping", info)
+    );
+    instance.on("success", (result) => this.emit("success", result));
+    instance.on("failure", (result) => this.emit("failure", result));
+    instance.on("retry", (info) => this.emit("retry", info));
+    instance.on("error", (err, name) => this.emit("error", err, name));
+  }
+  /**
+   * Starts all configured services.
+   */
+  start() {
+    this.logger?.info(`Starting keep-alive scheduler for ${this.services.length} services...`);
+    for (const service of this.services) {
+      service.start();
+    }
+    return this;
+  }
+  /**
+   * Stops all running services.
+   */
+  async stop() {
+    this.logger?.info(`Stopping all services...`);
+    await Promise.all(this.services.map((s) => s.stop()));
+    this.logger?.info(`All services stopped successfully.`);
+  }
+  /**
+   * Pings all services once in parallel and returns their results.
+   */
+  async pingOnce() {
+    return Promise.all(this.services.map((s) => s.pingOnce()));
+  }
+  /**
+   * Returns whether any of the services are currently running.
+   */
+  isRunning() {
+    return this.services.some((s) => s.isRunning());
+  }
+  /**
+   * Returns the list of all registered KeepAlive instances.
+   */
+  getServices() {
+    return [...this.services];
+  }
+  /**
+   * Returns a specific KeepAlive instance by service name.
+   */
+  getService(name) {
+    return this.serviceMap.get(name);
+  }
+  // Type-safe event emitter methods
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+};
+var CONFIG_CANDIDATES = [
+  "keepalive.config.json",
+  ".keepaliverc.json",
+  ".keepaliverc",
+  "keepalive.config.js",
+  "keepalive.config.mjs",
+  "keepalive.config.cjs"
+];
+function parseHeaderPairs(headers) {
+  if (!headers || !Array.isArray(headers)) return {};
+  const result = {};
+  for (const item of headers) {
+    const separatorIdx = item.indexOf(":") !== -1 ? item.indexOf(":") : item.indexOf("=");
+    if (separatorIdx === -1) {
+      throw new Error(
+        `Invalid header format "${item}". Expected format "Header-Name: Value" or "Header-Name=Value".`
+      );
+    }
+    const key = item.substring(0, separatorIdx).trim();
+    const val = item.substring(separatorIdx + 1).trim();
+    if (!key) {
+      throw new Error(`Header key cannot be empty in "${item}".`);
+    }
+    result[key] = val;
+  }
+  return result;
+}
+async function loadConfigFile(customPath) {
+  let targetPath = null;
+  if (customPath) {
+    const resolved = resolve(process.cwd(), customPath);
+    if (!existsSync(resolved)) {
+      throw new Error(`Config file not found at: ${resolved}`);
+    }
+    targetPath = resolved;
+  } else {
+    for (const candidate of CONFIG_CANDIDATES) {
+      const candidatePath = resolve(process.cwd(), candidate);
+      if (existsSync(candidatePath)) {
+        targetPath = candidatePath;
+        break;
+      }
+    }
+  }
+  if (!targetPath) return null;
+  try {
+    if (targetPath.endsWith(".json") || targetPath.endsWith(".keepaliverc")) {
+      const raw = readFileSync(targetPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      return normalizeRawConfig(parsed);
+    }
+    if (targetPath.endsWith(".js") || targetPath.endsWith(".mjs") || targetPath.endsWith(".cjs")) {
+      const moduleUrl = pathToFileURL(targetPath).href;
+      const imported = await import(moduleUrl);
+      const config = imported.default || imported;
+      return normalizeRawConfig(config);
+    }
+    throw new Error(`Unsupported configuration file format: ${targetPath}`);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse configuration file "${targetPath}": ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function normalizeRawConfig(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Configuration must be a valid JSON or JS object.");
+  }
+  const obj = raw;
+  if (Array.isArray(obj["services"])) {
+    const services = obj["services"];
+    if (services.length === 0) {
+      throw new Error('Config "services" array cannot be empty.');
+    }
+    return {
+      services,
+      defaults: obj["defaults"] || void 0,
+      logLevel: obj["logLevel"] || void 0
+    };
+  }
+  if (typeof obj["url"] === "string") {
+    return {
+      services: [obj],
+      logLevel: obj["logLevel"] || void 0
+    };
+  }
+  throw new Error(
+    'Configuration must contain either a "url" property or a "services" array of target endpoints.'
+  );
+}
+function loadEnvConfig() {
+  const env = process.env;
+  const config = {};
+  if (env["KEEPALIVE_URL"]) config.url = env["KEEPALIVE_URL"];
+  if (env["KEEPALIVE_INTERVAL"]) config.interval = env["KEEPALIVE_INTERVAL"];
+  if (env["KEEPALIVE_TIMEOUT"]) config.timeout = env["KEEPALIVE_TIMEOUT"];
+  if (env["KEEPALIVE_METHOD"]) config.method = env["KEEPALIVE_METHOD"].toUpperCase();
+  if (env["KEEPALIVE_RETRIES"]) config.retries = parseInt(env["KEEPALIVE_RETRIES"], 10);
+  if (env["KEEPALIVE_RETRY_DELAY"]) config.retryDelay = env["KEEPALIVE_RETRY_DELAY"];
+  if (env["KEEPALIVE_HEADERS"]) {
+    try {
+      config.headers = JSON.parse(env["KEEPALIVE_HEADERS"]);
+    } catch {
+      const pairs = env["KEEPALIVE_HEADERS"].split(",").map((s) => s.trim());
+      config.headers = parseHeaderPairs(pairs);
+    }
+  }
+  if (env["KEEPALIVE_QUIET"] === "true" || env["KEEPALIVE_QUIET"] === "1") {
+    config.logLevel = "quiet";
+  } else if (env["KEEPALIVE_VERBOSE"] === "true" || env["KEEPALIVE_VERBOSE"] === "1") {
+    config.logLevel = "verbose";
+  }
+  return config;
+}
+async function resolveRuntimeConfig(cliOptions) {
+  const fileConfig = await loadConfigFile(cliOptions.config || process.env["KEEPALIVE_CONFIG"]);
+  const envConfig = loadEnvConfig();
+  let logLevel = "normal";
+  if (cliOptions.quiet) {
+    logLevel = "quiet";
+  } else if (cliOptions.verbose) {
+    logLevel = "verbose";
+  } else if (fileConfig?.logLevel) {
+    logLevel = fileConfig.logLevel;
+  } else if (envConfig.logLevel) {
+    logLevel = envConfig.logLevel;
+  }
+  const cliHeaders = parseHeaderPairs(cliOptions.headers);
+  if (fileConfig && fileConfig.services.length > 1 && !cliOptions.url) {
+    return {
+      services: fileConfig.services,
+      defaults: {
+        ...fileConfig.defaults,
+        logLevel
+      },
+      logLevel
+    };
+  }
+  const primaryServiceFromFile = fileConfig?.services[0];
+  const targetUrl = cliOptions.url || primaryServiceFromFile?.url || envConfig.url;
+  if (!targetUrl) {
+    throw new Error(
+      "Missing target URL. Provide --url <url>, set KEEPALIVE_URL, or define a config file."
+    );
+  }
+  const interval = cliOptions.interval || primaryServiceFromFile?.interval || envConfig.interval || "10m";
+  const timeout = cliOptions.timeout || primaryServiceFromFile?.timeout || envConfig.timeout || "30s";
+  const method = (cliOptions.method || primaryServiceFromFile?.method || envConfig.method || "GET").toUpperCase();
+  const retries = cliOptions.retries !== void 0 ? typeof cliOptions.retries === "string" ? parseInt(cliOptions.retries, 10) : cliOptions.retries : primaryServiceFromFile?.retries !== void 0 ? primaryServiceFromFile.retries : envConfig.retries !== void 0 ? envConfig.retries : 3;
+  const retryDelay = cliOptions.retryDelay || primaryServiceFromFile?.retryDelay || envConfig.retryDelay || "5s";
+  const headers = {
+    ...envConfig.headers ?? {},
+    ...fileConfig?.defaults?.headers ?? {},
+    ...primaryServiceFromFile?.headers ?? {},
+    ...cliHeaders
+  };
+  const name = primaryServiceFromFile?.name;
+  return {
+    url: targetUrl,
+    name,
+    interval,
+    timeout,
+    method,
+    headers,
+    retries,
+    retryDelay,
+    logLevel
+  };
+}
+
+// src/cli.ts
+var VERSION = "1.0.0";
+function parseArgs(argv) {
+  const options = {
+    headers: []
+  };
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-V" || arg === "--version") {
+      options.version = true;
+    } else if (arg === "-q" || arg === "--quiet") {
+      options.quiet = true;
+    } else if (arg === "-v" || arg === "--verbose") {
+      options.verbose = true;
+    } else if (arg === "--once") {
+      options.once = true;
+    } else if (arg === "-u" || arg === "--url") {
+      options.url = args[++i];
+    } else if (arg.startsWith("--url=")) {
+      options.url = arg.split("=")[1];
+    } else if (arg === "-i" || arg === "--interval") {
+      options.interval = args[++i];
+    } else if (arg.startsWith("--interval=")) {
+      options.interval = arg.split("=")[1];
+    } else if (arg === "-t" || arg === "--timeout") {
+      options.timeout = args[++i];
+    } else if (arg.startsWith("--timeout=")) {
+      options.timeout = arg.split("=")[1];
+    } else if (arg === "-m" || arg === "--method") {
+      options.method = args[++i];
+    } else if (arg.startsWith("--method=")) {
+      options.method = arg.split("=")[1];
+    } else if (arg === "-r" || arg === "--retries") {
+      options.retries = args[++i];
+    } else if (arg.startsWith("--retries=")) {
+      options.retries = arg.split("=")[1];
+    } else if (arg === "--retry-delay") {
+      options.retryDelay = args[++i];
+    } else if (arg.startsWith("--retry-delay=")) {
+      options.retryDelay = arg.split("=")[1];
+    } else if (arg === "-H" || arg === "--header") {
+      const headerVal = args[++i];
+      if (headerVal) options.headers?.push(headerVal);
+    } else if (arg.startsWith("--header=")) {
+      const headerVal = arg.split("=")[1];
+      if (headerVal) options.headers?.push(headerVal);
+    } else if (arg === "-c" || arg === "--config") {
+      options.config = args[++i];
+    } else if (arg.startsWith("--config=")) {
+      options.config = arg.split("=")[1];
+    } else if (!arg.startsWith("-") && !options.url) {
+      options.url = arg;
+    }
+  }
+  return options;
+}
+function printHelp() {
+  console.log(`
+\x1B[1m\x1B[36mservice-keepalive\x1B[0m v${VERSION}
+Lightweight HTTP keep-alive utility to prevent idle spin-down on services with inbound traffic wakeups.
+
+\x1B[1mUSAGE:\x1B[0m
+  $ npx service-keepalive [options]
+  $ npx service-keepalive <url> [options]
+
+\x1B[1mOPTIONS:\x1B[0m
+  -u, --url <url>             Target service URL (e.g. https://example.onrender.com/health)
+  -i, --interval <duration>   Interval between pings (e.g. 10s, 1m, 5m, 10m, 1h) [default: 10m]
+  -t, --timeout <duration>    Request timeout duration (e.g. 10s, 30s, 1m) [default: 30s]
+  -m, --method <method>       HTTP method (GET, POST, HEAD, etc.) [default: GET]
+  -r, --retries <number>      Number of retry attempts on failure [default: 3]
+      --retry-delay <duration> Base delay between retries [default: 5s]
+  -H, --header <key:value>    Custom request header (can be used multiple times)
+  -c, --config <path>         Path to JSON or JS config file [default: keepalive.config.json]
+      --once                  Execute a single ping and exit (useful for cron jobs / CI)
+  -q, --quiet                 Suppress standard output; only log failures
+  -v, --verbose               Enable verbose debug logging
+  -V, --version               Output version number
+  -h, --help                  Display this help message
+
+\x1B[1mEXAMPLES:\x1B[0m
+  $ npx service-keepalive --url https://api.example.com/health --interval 10m
+  $ npx service-keepalive -u https://api.example.com/health -H "Authorization: Bearer mytoken"
+  $ npx service-keepalive --config keepalive.config.json
+  $ npx service-keepalive --url https://api.example.com/health --once
+
+\x1B[1mENVIRONMENT VARIABLES:\x1B[0m
+  KEEPALIVE_URL, KEEPALIVE_INTERVAL, KEEPALIVE_TIMEOUT, KEEPALIVE_METHOD,
+  KEEPALIVE_RETRIES, KEEPALIVE_HEADERS, KEEPALIVE_CONFIG, KEEPALIVE_QUIET, KEEPALIVE_VERBOSE
+
+\x1B[1mNOTE:\x1B[0m
+  This tool runs externally (on your machine, VPS, Docker container, or CI runner).
+  Always ensure compliance with your hosting provider's Terms of Service.
+`);
+}
+async function runCli(argv = process.argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+  if (options.version) {
+    console.log(`service-keepalive v${VERSION}`);
+    return 0;
+  }
+  try {
+    const config = await resolveRuntimeConfig(options);
+    let runner;
+    if ("services" in config) {
+      runner = new MultiKeepAlive(config);
+    } else {
+      runner = new KeepAlive(config);
+    }
+    let isShuttingDown = false;
+    const shutdown = async (signal) => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+      console.log(`
+Received ${signal}. Stopping keep-alive...`);
+      await runner.stop();
+      console.log("Stopped successfully.");
+      process.exit(0);
+    };
+    process.once("SIGINT", () => void shutdown("SIGINT"));
+    process.once("SIGTERM", () => void shutdown("SIGTERM"));
+    if (options.once) {
+      if (runner instanceof MultiKeepAlive) {
+        const results = await runner.pingOnce();
+        const allOk = results.every((r) => r.ok);
+        return allOk ? 0 : 1;
+      } else {
+        const result = await runner.pingOnce();
+        return result.ok ? 0 : 1;
+      }
+    }
+    runner.start();
+    return new Promise(() => {
+    });
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+
+export { KeepAlive, Logger, MultiKeepAlive, calculateBackoff, executePing, formatDuration, formatTimestamp, isStatusSuccessful, loadConfigFile, loadEnvConfig, normalizeRawConfig, parseArgs, parseDuration, parseHeaderPairs, printHelp, redactHeaders, redactUrl, resolveRuntimeConfig, runCli, sleep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map