pingflux 1.0.0

package/dist/core/emitter.d.ts

@@ -0,0 +1,44 @@
+import { EventEmitter } from "events";
+import { PingfluxEvent } from "../interfaces";
+export declare class PingfluxEmitter extends EventEmitter {
+    constructor();
+    /**
+     * Emit an "up" event — target is reachable and within the latency threshold.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("up", (e) => console.log(`${e.target} is up (${e.latency}ms)`));
+     */
+    emitUp(data: PingfluxEvent): void;
+    /**
+     * Emit a "down" event — target is unreachable with no specific error.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("down", (e) => console.log(`${e.target} is down`));
+     */
+    emitDown(data: PingfluxEvent): void;
+    /**
+     * Emit a "slow" event — target is reachable but latency exceeds the threshold.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("slow", (e) => console.log(`${e.target} is slow (${e.latency}ms)`));
+     */
+    emitSlow(data: PingfluxEvent): void;
+    /**
+     * Emit a "probe_error" event — probe failed with a specific error message.
+     * Uses a dedicated "probe_error" channel instead of Node's built-in "error"
+     * event to avoid conflicts with EventEmitter's crash-on-unhandled-error behavior.
+     *
+     * @param data - The probe result event payload. `data.error` contains the error message.
+     *
+     * @example
+     * emitter.on("probe_error", (e) => console.error(`${e.target} error: ${e.error}`));
+     */
+    emitError(data: PingfluxEvent): void;
+}
+//# sourceMappingURL=emitter.d.ts.map

package/dist/core/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/core/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,qBAAa,eAAgB,SAAQ,YAAY;;IAM/C;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAIjC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAInC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAInC;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;CAGrC"}

package/dist/core/emitter.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PingfluxEmitter = void 0;
+const events_1 = require("events");
+class PingfluxEmitter extends events_1.EventEmitter {
+    constructor() {
+        super();
+        this.on("error", () => { });
+    }
+    /**
+     * Emit an "up" event — target is reachable and within the latency threshold.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("up", (e) => console.log(`${e.target} is up (${e.latency}ms)`));
+     */
+    emitUp(data) {
+        this.emit("up", data);
+    }
+    /**
+     * Emit a "down" event — target is unreachable with no specific error.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("down", (e) => console.log(`${e.target} is down`));
+     */
+    emitDown(data) {
+        this.emit("down", data);
+    }
+    /**
+     * Emit a "slow" event — target is reachable but latency exceeds the threshold.
+     *
+     * @param data - The probe result event payload.
+     *
+     * @example
+     * emitter.on("slow", (e) => console.log(`${e.target} is slow (${e.latency}ms)`));
+     */
+    emitSlow(data) {
+        this.emit("slow", data);
+    }
+    /**
+     * Emit a "probe_error" event — probe failed with a specific error message.
+     * Uses a dedicated "probe_error" channel instead of Node's built-in "error"
+     * event to avoid conflicts with EventEmitter's crash-on-unhandled-error behavior.
+     *
+     * @param data - The probe result event payload. `data.error` contains the error message.
+     *
+     * @example
+     * emitter.on("probe_error", (e) => console.error(`${e.target} error: ${e.error}`));
+     */
+    emitError(data) {
+        this.emit("probe_error", data);
+    }
+}
+exports.PingfluxEmitter = PingfluxEmitter;
+//# sourceMappingURL=emitter.js.map

package/dist/core/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/core/emitter.ts"],"names":[],"mappings":";;;AAAA,mCAAsC;AAGtC,MAAa,eAAgB,SAAQ,qBAAY;IAC/C;QACE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAmB;QACxB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAmB;QAC1B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAmB;QAC1B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAmB;QAC3B,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;CACF;AAvDD,0CAuDC"}

package/dist/core/monitor.d.ts

@@ -0,0 +1,47 @@
+import { PingfluxEmitter } from "./emitter";
+import { Target, Protocol, PingfluxOptions } from "../interfaces";
+export declare class Monitor {
+    private emitter;
+    private timers;
+    private running;
+    private globalOptions;
+    constructor(emitter: PingfluxEmitter, options?: PingfluxOptions);
+    private targetKey;
+    private runProbe;
+    private runWithRetry;
+    private handle;
+    /**
+     * Start monitoring a target.
+     * Runs the appropriate probe immediately and then on every `interval` ms.
+     * If the same target (same protocol + url) is already being watched, this call is a no-op.
+     *
+     * @param target - The target to monitor.
+     * @returns `true` if monitoring started, `false` if the target was already being watched.
+     *
+     * @example
+     * const added = monitor.watch({ protocol: "https", url: "example.com" });
+     * console.log(added); // true
+     * const duplicate = monitor.watch({ protocol: "https", url: "example.com" });
+     * console.log(duplicate); // false
+     */
+    watch(target: Target): boolean;
+    /**
+     * Stop monitoring a specific target by its exact protocol and url.
+     * If no matching target is found, the call is a no-op.
+     *
+     * @param protocol - The protocol of the target to stop.
+     * @param url - The url of the target to stop.
+     *
+     * @example
+     * monitor.stop("https", "example.com");
+     */
+    stop(protocol: Protocol, url: string): void;
+    /**
+     * Stop all active monitors and clear all internal state.
+     *
+     * @example
+     * monitor.stopAll();
+     */
+    stopAll(): void;
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/core/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/core/monitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAe,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAQ/E,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,aAAa,CAAkB;gBAE3B,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,eAAe;IAO/D,OAAO,CAAC,SAAS;YAIH,QAAQ;YAyBR,YAAY;IAW1B,OAAO,CAAC,MAAM;IA0Bd;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IA0B9B;;;;;;;;;OASG;IACH,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAU3C;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAWhB"}

package/dist/core/monitor.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Monitor = void 0;
+const http_1 = require("../probes/http");
+const tcp_1 = require("../probes/tcp");
+const udp_1 = require("../probes/udp");
+const dns_1 = require("../probes/dns");
+const ping_1 = require("../probes/ping");
+const latency_1 = require("../utils/latency");
+class Monitor {
+    constructor(emitter, options) {
+        this.emitter = emitter;
+        this.timers = new Map();
+        this.running = new Map();
+        this.globalOptions = options ?? {};
+    }
+    targetKey(target) {
+        return `${target.protocol}::${target.url}`;
+    }
+    async runProbe(target) {
+        switch (target.protocol) {
+            case "http":
+            case "https":
+                return (0, http_1.httpProbe)(target.url, target.protocol);
+            case "tcp":
+                return (0, tcp_1.tcpProbe)(target.url);
+            case "udp":
+                return (0, udp_1.udpProbe)(target.url);
+            case "dns":
+                return (0, dns_1.dnsProbe)(target.url);
+            case "ping":
+                return (0, ping_1.pingProbe)(target.url);
+            default:
+                return {
+                    ok: false,
+                    latency: null,
+                    error: "Unknown protocol",
+                    protocol: target.protocol,
+                    target: target.url,
+                    timestamp: Date.now(),
+                };
+        }
+    }
+    async runWithRetry(target, retries) {
+        let lastResult = null;
+        for (let i = 0; i <= retries; i++) {
+            const result = await this.runProbe(target);
+            if (result.ok)
+                return result;
+            lastResult = result;
+            if (i < retries)
+                await new Promise((r) => setTimeout(r, 500));
+        }
+        return lastResult;
+    }
+    handle(result, threshold) {
+        const event = {
+            target: result.target,
+            protocol: result.protocol,
+            latency: result.latency,
+            error: result.error,
+            timestamp: result.timestamp,
+        };
+        if (!result.ok) {
+            if (result.error) {
+                this.emitter.emitError(event);
+            }
+            else {
+                this.emitter.emitDown(event);
+            }
+            return;
+        }
+        if (result.latency !== null && (0, latency_1.isSlowLatency)(result.latency, threshold)) {
+            this.emitter.emitSlow(event);
+            return;
+        }
+        this.emitter.emitUp(event);
+    }
+    /**
+     * Start monitoring a target.
+     * Runs the appropriate probe immediately and then on every `interval` ms.
+     * If the same target (same protocol + url) is already being watched, this call is a no-op.
+     *
+     * @param target - The target to monitor.
+     * @returns `true` if monitoring started, `false` if the target was already being watched.
+     *
+     * @example
+     * const added = monitor.watch({ protocol: "https", url: "example.com" });
+     * console.log(added); // true
+     * const duplicate = monitor.watch({ protocol: "https", url: "example.com" });
+     * console.log(duplicate); // false
+     */
+    watch(target) {
+        const key = this.targetKey(target);
+        if (this.timers.has(key))
+            return false;
+        const interval = target.interval ?? 5000;
+        const threshold = target.threshold ?? this.globalOptions.threshold ?? 1000;
+        const retry = target.retry ?? this.globalOptions.retry ?? 1;
+        const run = async () => {
+            if (this.running.get(key))
+                return;
+            this.running.set(key, true);
+            try {
+                const result = await this.runWithRetry(target, retry);
+                this.handle(result, threshold);
+            }
+            finally {
+                this.running.set(key, false);
+            }
+        };
+        run();
+        const timer = setInterval(run, interval);
+        this.timers.set(key, timer);
+        this.running.set(key, false);
+        return true;
+    }
+    /**
+     * Stop monitoring a specific target by its exact protocol and url.
+     * If no matching target is found, the call is a no-op.
+     *
+     * @param protocol - The protocol of the target to stop.
+     * @param url - The url of the target to stop.
+     *
+     * @example
+     * monitor.stop("https", "example.com");
+     */
+    stop(protocol, url) {
+        const key = `${protocol}::${url}`;
+        const timer = this.timers.get(key);
+        if (timer !== undefined) {
+            clearInterval(timer);
+            this.timers.delete(key);
+            this.running.delete(key);
+        }
+    }
+    /**
+     * Stop all active monitors and clear all internal state.
+     *
+     * @example
+     * monitor.stopAll();
+     */
+    stopAll() {
+        const keys = Array.from(this.timers.keys());
+        for (const key of keys) {
+            const timer = this.timers.get(key);
+            if (timer !== undefined) {
+                clearInterval(timer);
+                this.timers.delete(key);
+                this.running.delete(key);
+            }
+        }
+    }
+}
+exports.Monitor = Monitor;
+//# sourceMappingURL=monitor.js.map

package/dist/core/monitor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Target, PingfluxEvent, EventType, PingfluxOptions, Protocol } from "./interfaces";
+export declare class Pingflux {
+    private emitter;
+    private monitor;
+    constructor(options?: PingfluxOptions);
+    /**
+     * Start monitoring a target.
+     * Runs the probe immediately and then on every `target.interval` ms.
+     * If the same target (same protocol + url) is already being watched, this call is a no-op.
+     *
+     * @param target - The target to monitor.
+     * @returns `true` if monitoring started, `false` if already being watched.
+     *
+     * @example
+     * pf.watch({ protocol: "https", url: "example.com" });
+     * pf.watch({ protocol: "tcp", url: "example.com:443", interval: 10000, threshold: 500 });
+     */
+    watch(target: Target): boolean;
+    /**
+     * Register a listener for a probe event.
+     * Multiple listeners can be registered for the same event.
+     *
+     * @param event - One of `"up"`, `"down"`, `"slow"`, `"probe_error"`.
+     * @param callback - Function called with the probe result payload.
+     *
+     * @example
+     * pf.on("up", (e) => console.log(`${e.target} is up — ${e.latency}ms`));
+     * pf.on("probe_error", (e) => console.error(`${e.target} error: ${e.error}`));
+     */
+    on(event: EventType, callback: (data: PingfluxEvent) => void): void;
+    /**
+     * Remove a previously registered event listener.
+     *
+     * @param event - The event name the listener was registered on.
+     * @param callback - The exact function reference passed to `on()`.
+     *
+     * @example
+     * const handler = (e: PingfluxEvent) => console.log(e);
+     * pf.on("up", handler);
+     * pf.off("up", handler);
+     */
+    off(event: EventType, callback: (data: PingfluxEvent) => void): void;
+    /**
+     * Stop monitoring a specific target.
+     * If no matching target is found, the call is a no-op.
+     *
+     * @param protocol - The protocol of the target to stop.
+     * @param url - The url of the target to stop.
+     *
+     * @example
+     * pf.stop("https", "example.com");
+     * pf.stop("tcp", "example.com:443");
+     */
+    stop(protocol: Protocol, url: string): void;
+    /**
+     * Stop all active monitors and clear all internal state.
+     *
+     * @example
+     * pf.stopAll();
+     */
+    stopAll(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3F,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAU;gBAEb,OAAO,CAAC,EAAE,eAAe;IAKrC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;;;;;OAUG;IACH,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAInE;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAIpE;;;;;;;;;;OAUG;IACH,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI3C;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/dist/index.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pingflux = void 0;
+const monitor_1 = require("./core/monitor");
+const emitter_1 = require("./core/emitter");
+class Pingflux {
+    constructor(options) {
+        this.emitter = new emitter_1.PingfluxEmitter();
+        this.monitor = new monitor_1.Monitor(this.emitter, options);
+    }
+    /**
+     * Start monitoring a target.
+     * Runs the probe immediately and then on every `target.interval` ms.
+     * If the same target (same protocol + url) is already being watched, this call is a no-op.
+     *
+     * @param target - The target to monitor.
+     * @returns `true` if monitoring started, `false` if already being watched.
+     *
+     * @example
+     * pf.watch({ protocol: "https", url: "example.com" });
+     * pf.watch({ protocol: "tcp", url: "example.com:443", interval: 10000, threshold: 500 });
+     */
+    watch(target) {
+        return this.monitor.watch(target);
+    }
+    /**
+     * Register a listener for a probe event.
+     * Multiple listeners can be registered for the same event.
+     *
+     * @param event - One of `"up"`, `"down"`, `"slow"`, `"probe_error"`.
+     * @param callback - Function called with the probe result payload.
+     *
+     * @example
+     * pf.on("up", (e) => console.log(`${e.target} is up — ${e.latency}ms`));
+     * pf.on("probe_error", (e) => console.error(`${e.target} error: ${e.error}`));
+     */
+    on(event, callback) {
+        this.emitter.on(event, callback);
+    }
+    /**
+     * Remove a previously registered event listener.
+     *
+     * @param event - The event name the listener was registered on.
+     * @param callback - The exact function reference passed to `on()`.
+     *
+     * @example
+     * const handler = (e: PingfluxEvent) => console.log(e);
+     * pf.on("up", handler);
+     * pf.off("up", handler);
+     */
+    off(event, callback) {
+        this.emitter.off(event, callback);
+    }
+    /**
+     * Stop monitoring a specific target.
+     * If no matching target is found, the call is a no-op.
+     *
+     * @param protocol - The protocol of the target to stop.
+     * @param url - The url of the target to stop.
+     *
+     * @example
+     * pf.stop("https", "example.com");
+     * pf.stop("tcp", "example.com:443");
+     */
+    stop(protocol, url) {
+        this.monitor.stop(protocol, url);
+    }
+    /**
+     * Stop all active monitors and clear all internal state.
+     *
+     * @example
+     * pf.stopAll();
+     */
+    stopAll() {
+        this.monitor.stopAll();
+    }
+}
+exports.Pingflux = Pingflux;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,4CAAyC;AACzC,4CAAiD;AAGjD,MAAa,QAAQ;IAInB,YAAY,OAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,yBAAe,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,iBAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAc;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;OAUG;IACH,EAAE,CAAC,KAAgB,EAAE,QAAuC;QAC1D,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAgB,EAAE,QAAuC;QAC3D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAI,CAAC,QAAkB,EAAE,GAAW;QAClC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACF;AA/ED,4BA+EC"}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Supported probe protocols.
+ *
+ * - `http` / `https` — HTTP GET request; resolves ok if status < 400
+ * - `tcp` — TCP socket connect; resolves ok on successful connection
+ * - `udp` — UDP packet send/receive; resolves ok if a response is received
+ * - `dns` — DNS A/AAAA record lookup; resolves ok if at least one record found
+ * - `ping` — Raw ICMP echo request; requires root or CAP_NET_RAW on Linux
+ */
+export type Protocol = "http" | "https" | "tcp" | "udp" | "dns" | "ping";
+/**
+ * Event types emitted by Pingflux.
+ *
+ * - `up` — target is reachable and within latency threshold
+ * - `down` — target is unreachable with no specific error
+ * - `slow` — target is reachable but latency exceeds threshold
+ * - `probe_error` — probe failed with a specific error message
+ */
+export type EventType = "up" | "down" | "slow" | "probe_error";
+/**
+ * Internal result returned by each probe function.
+ * Not exposed directly to end users — use `PingfluxEvent` for listener callbacks.
+ */
+export interface ProbeResult {
+    ok: boolean;
+    latency: number | null;
+    error?: string;
+    protocol: Protocol;
+    target: string;
+    timestamp: number;
+}
+/**
+ * A monitoring target.
+ *
+ * @example
+ * // HTTP target with custom interval and threshold
+ * { protocol: "https", url: "example.com", interval: 10000, threshold: 500 }
+ *
+ * @example
+ * // TCP target
+ * { protocol: "tcp", url: "example.com:443" }
+ *
+ * @example
+ * // ICMP ping — requires root or CAP_NET_RAW, url must be a plain IP address
+ * { protocol: "ping", url: "1.1.1.1" }
+ */
+export interface Target {
+    /**
+     * For `http`/`https`: hostname or full URL (e.g. `"example.com"` or `"example.com/health"`).
+     * For `tcp`/`udp`: `"host:port"` format (e.g. `"example.com:443"`).
+     * For `dns`: hostname to resolve (e.g. `"example.com"`).
+     * For `ping`: plain IP address only — hostname resolution is not supported (e.g. `"1.1.1.1"`).
+     */
+    url: string;
+    protocol: Protocol;
+    /** Probe interval in milliseconds. Default: `5000` */
+    interval?: number;
+    /** Latency threshold in milliseconds above which a `slow` event is emitted. Default: `1000` */
+    threshold?: number;
+    /** Number of retries on failure before emitting a `down` or `probe_error` event. Default: `1` */
+    retry?: number;
+}
+/**
+ * Event payload passed to all event listeners.
+ *
+ * @example
+ * pingflux.on("up", (e: PingfluxEvent) => {
+ *   console.log(`${e.protocol}://${e.target} — ${e.latency}ms`);
+ * });
+ */
+export interface PingfluxEvent {
+    target: string;
+    protocol: Protocol;
+    latency: number | null;
+    /** Present only on `probe_error` events. */
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Global options passed to the `Pingflux` constructor.
+ * These apply to all targets unless overridden per-target.
+ *
+ * @example
+ * const pf = new Pingflux({ threshold: 500, retry: 2 });
+ */
+export interface PingfluxOptions {
+    /** Default latency threshold in ms. Default: `1000` */
+    threshold?: number;
+    /** Default retry count on failure. Default: `1` */
+    retry?: number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/interfaces/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":""}

package/dist/probes/dns.d.ts

@@ -0,0 +1,17 @@
+import { ProbeResult } from "../interfaces";
+/**
+ * Probe a host via DNS resolution.
+ * Attempts A record lookup first, then AAAA, then CNAME as a final fallback.
+ * Resolves `ok: true` if any record type is found.
+ *
+ * Note: only A, AAAA, and CNAME record types are checked.
+ * Hosts with exclusively MX, TXT, or other record types will resolve as `ok: false`.
+ *
+ * @param url - Hostname to resolve, optionally with a port suffix (e.g. `"example.com"` or `"example.com:53"`).
+ *
+ * @example
+ * const result = await dnsProbe("example.com");
+ * console.log(result.ok, result.latency);
+ */
+export declare function dnsProbe(url: string): Promise<ProbeResult>;
+//# sourceMappingURL=dns.d.ts.map

package/dist/probes/dns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../src/probes/dns.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmC1D"}