@futurewindai/wotchi 0.1.0-beta.1

package/dist/cjs/core/fingerprint.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDynamicSegments = normalizeDynamicSegments;
+exports.fingerprintSafeErrorEvent = fingerprintSafeErrorEvent;
+const node_crypto_1 = require("node:crypto");
+const redact_js_1 = require("./redact.js");
+const stack_frame_js_1 = require("./stack-frame.js");
+const UUID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+const HEX_PATTERN = /\b(?:0x)?[0-9a-f]{8,}\b/gi;
+const NUMBER_PATTERN = /\b\d+\b/g;
+function normalizeDynamicSegments(value) {
+    return value
+        .replace(UUID_PATTERN, "<uuid>")
+        .replace(HEX_PATTERN, "<hex>")
+        .replace(NUMBER_PATTERN, "<number>")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+const safeText = (value) => {
+    const redacted = (0, redact_js_1.redactValue)(value, { maxStringLength: 4_000 });
+    return typeof redacted === "string" ? redacted : "[unreadable value]";
+};
+const encodePart = (value) => `${value.length}:${value}`;
+function fingerprintSafeErrorEvent(event) {
+    const service = normalizeDynamicSegments(safeText(event.service));
+    const environment = normalizeDynamicSegments(safeText(event.environment));
+    const errorName = normalizeDynamicSegments(safeText(event.error.name));
+    const message = normalizeDynamicSegments(safeText(event.error.message));
+    const method = normalizeDynamicSegments(safeText(event.request?.method ?? ""));
+    const route = normalizeDynamicSegments(safeText(event.request?.route ?? ""));
+    const frame = normalizeDynamicSegments((0, stack_frame_js_1.selectApplicationFrame)(event.error.stack) ?? "");
+    const canonical = [service, environment, errorName, message, method, route, frame]
+        .map(encodePart)
+        .join("|");
+    return (0, node_crypto_1.createHash)("sha256").update(canonical, "utf8").digest("hex");
+}

package/dist/cjs/core/group-store.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGroupStore = createGroupStore;
+const normalize_js_1 = require("./normalize.js");
+const rolling_window_js_1 = require("./rolling-window.js");
+const cloneSafeEvent = (event) => {
+    const context = event.context === undefined ? undefined : (0, normalize_js_1.normalizeUnknown)(event.context);
+    return {
+        id: event.id,
+        timestamp: event.timestamp,
+        service: event.service,
+        environment: event.environment,
+        ...(event.release === undefined ? {} : { release: event.release }),
+        error: { ...event.error },
+        ...(event.request === undefined ? {} : { request: { ...event.request } }),
+        ...(context === undefined ? {} : { context: context }),
+    };
+};
+function createGroupStore(options) {
+    if (!Number.isSafeInteger(options.maxGroups) || options.maxGroups <= 0) {
+        throw new RangeError("maxGroups must be a positive integer");
+    }
+    const now = options.now ?? Date.now;
+    const groups = new Map();
+    let evicted = 0;
+    const snapshot = (group) => ({
+        fingerprint: group.fingerprint,
+        firstSeenAt: new Date(group.firstSeenMs).toISOString(),
+        lastSeenAt: new Date(group.lastSeenMs).toISOString(),
+        totalCount: group.totalCount,
+        windowCount: group.window.count(group.lastSeenMs),
+        sample: cloneSafeEvent(group.sample),
+        ...(group.lastAlertedMs === undefined
+            ? {}
+            : { lastAlertedAt: new Date(group.lastAlertedMs).toISOString() }),
+        severity: group.severity,
+    });
+    const evictLeastRecent = () => {
+        let candidate;
+        for (const group of groups.values()) {
+            if (candidate === undefined || group.lastSeenMs < candidate.lastSeenMs) {
+                candidate = group;
+            }
+        }
+        if (candidate !== undefined) {
+            groups.delete(candidate.fingerprint);
+            evicted += 1;
+        }
+    };
+    const record = (fingerprint, event, severity = "medium") => {
+        const timestamp = now();
+        let group = groups.get(fingerprint);
+        if (group === undefined) {
+            if (groups.size >= options.maxGroups) {
+                evictLeastRecent();
+            }
+            group = {
+                fingerprint,
+                firstSeenMs: timestamp,
+                lastSeenMs: timestamp,
+                totalCount: 0,
+                sample: cloneSafeEvent(event),
+                severity,
+                window: (0, rolling_window_js_1.createRollingWindow)({
+                    maxEvents: options.maxEventsPerWindow,
+                    windowMs: options.windowMs,
+                    now,
+                }),
+            };
+            groups.set(fingerprint, group);
+        }
+        group.lastSeenMs = timestamp;
+        group.totalCount += 1;
+        group.severity = severity;
+        group.window.add(timestamp);
+        return snapshot(group);
+    };
+    return {
+        record,
+        get: (fingerprint) => {
+            const group = groups.get(fingerprint);
+            return group === undefined ? undefined : snapshot(group);
+        },
+        markAlerted: (fingerprint, timestamp = now()) => {
+            const group = groups.get(fingerprint);
+            if (group === undefined) {
+                return undefined;
+            }
+            group.lastAlertedMs = timestamp;
+            return snapshot(group);
+        },
+        size: () => groups.size,
+        groupsEvicted: () => evicted,
+    };
+}

package/dist/cjs/core/incident-builder.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildIncidentAlert = buildIncidentAlert;
+const titleCase = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+const suggestedActions = (group) => {
+    const text = `${group.sample.error.name} ${group.sample.error.message}`.toLowerCase();
+    if (text.includes("database") || text.includes("query") || text.includes("sql")) {
+        return [
+            "Check database availability, connection saturation, and recent schema changes.",
+            "Check the affected query and its dependency health before increasing capacity.",
+        ];
+    }
+    if (text.includes("timeout") || text.includes("timed out")) {
+        return [
+            "Check upstream latency, timeout settings, and recent dependency changes.",
+            "Check whether retries or a dependency outage are increasing request pressure.",
+        ];
+    }
+    if (text.includes("auth") || text.includes("permission") || text.includes("unauthor")) {
+        return [
+            "Check authentication configuration, credentials, and recent access-policy changes.",
+            "Check whether the affected route is receiving an unexpected caller or token.",
+        ];
+    }
+    return [
+        "Check the application logs and the selected stack frame for the first failing operation.",
+        "Check recent deployments, dependency health, and the affected request path.",
+    ];
+};
+function buildIncidentAlert(group, decision) {
+    const message = group.sample.error.message;
+    const errorName = group.sample.error.name;
+    return {
+        id: `wotchi-${group.fingerprint}-${group.lastSeenAt}`,
+        fingerprint: group.fingerprint,
+        title: `Wotchi — ${titleCase(decision.severity)} incident`,
+        severity: decision.severity,
+        summary: `Observed ${group.windowCount} occurrences of ${errorName}: ${message}.`,
+        suggestedActions: suggestedActions(group),
+        firstSeenAt: group.firstSeenAt,
+        lastSeenAt: group.lastSeenAt,
+        occurrences: group.windowCount,
+        service: group.sample.service,
+        environment: group.sample.environment,
+    };
+}

package/dist/cjs/core/incident-policy.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateIncidentPolicy = evaluateIncidentPolicy;
+const hasCooldown = (group, now, cooldownMs) => {
+    if (group.lastAlertedAt === undefined) {
+        return false;
+    }
+    const lastAlerted = Date.parse(group.lastAlertedAt);
+    return Number.isFinite(lastAlerted) && now - lastAlerted < cooldownMs;
+};
+const hasUnavailableResponse = (group) => group.sample.request?.statusCode === 503;
+function evaluateIncidentPolicy(input) {
+    const eventKind = input.eventKind ?? "error";
+    const isCritical = eventKind === "process-monitor";
+    const isHigh = input.group.windowCount >= 20 || hasUnavailableResponse(input.group);
+    const severity = isCritical
+        ? "critical"
+        : isHigh
+            ? "high"
+            : eventKind === "manual"
+                ? (input.manualSeverity ?? "low")
+                : "medium";
+    const eligible = isCritical ||
+        isHigh ||
+        eventKind === "manual" ||
+        input.group.windowCount >= input.alertThreshold;
+    return {
+        shouldAlert: eligible && !hasCooldown(input.group, input.now, input.cooldownMs),
+        severity,
+    };
+}

package/dist/cjs/core/normalize.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUnknown = normalizeUnknown;
+exports.normalizeError = normalizeError;
+const UNREADABLE_VALUE = "[unreadable value]";
+const MAX_DEPTH_VALUE = "[MaxDepth]";
+const CIRCULAR_VALUE = "[Circular]";
+const MAX_KEYS_VALUE = "[MaxKeys]";
+const defaultLimits = {
+    maxDepth: 5,
+    maxKeys: 100,
+    maxStringLength: 500,
+    maxStackLength: 4_000,
+};
+const boundedLimit = (value, fallback) => Number.isSafeInteger(value) && value > 0 ? value : fallback;
+const normalizeLimits = (limits) => ({
+    maxDepth: boundedLimit(limits?.maxDepth ?? defaultLimits.maxDepth, defaultLimits.maxDepth),
+    maxKeys: boundedLimit(limits?.maxKeys ?? defaultLimits.maxKeys, defaultLimits.maxKeys),
+    maxStringLength: boundedLimit(limits?.maxStringLength ?? defaultLimits.maxStringLength, defaultLimits.maxStringLength),
+    maxStackLength: boundedLimit(limits?.maxStackLength ?? defaultLimits.maxStackLength, defaultLimits.maxStackLength),
+});
+const truncate = (value, limit) => value.slice(0, limit);
+const readProperty = (value, key) => {
+    try {
+        return value[key];
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+};
+const normalizePrimitive = (value, limits) => {
+    if (value === null) {
+        return null;
+    }
+    switch (typeof value) {
+        case "string":
+            return truncate(value, limits.maxStringLength);
+        case "boolean":
+            return value;
+        case "number":
+            return Number.isFinite(value) ? value : "[non-finite number]";
+        case "undefined":
+            return "[undefined]";
+        case "bigint":
+            return "[bigint]";
+        case "symbol":
+            return "[symbol]";
+        case "function":
+            return "[function]";
+        default:
+            return UNREADABLE_VALUE;
+    }
+};
+const normalizeValue = (value, depth, state, limits) => {
+    if (value === null || typeof value !== "object") {
+        return normalizePrimitive(value, limits);
+    }
+    if (depth >= limits.maxDepth) {
+        return MAX_DEPTH_VALUE;
+    }
+    if (state.seen.has(value)) {
+        return CIRCULAR_VALUE;
+    }
+    state.seen.add(value);
+    if (Array.isArray(value)) {
+        const result = [];
+        let length;
+        try {
+            length = Math.min(value.length, limits.maxKeys - state.keysVisited);
+        }
+        catch {
+            return UNREADABLE_VALUE;
+        }
+        for (let index = 0; index < length; index += 1) {
+            if (state.keysVisited >= limits.maxKeys) {
+                break;
+            }
+            state.keysVisited += 1;
+            result.push(normalizeValue(readProperty(value, String(index)), depth + 1, state, limits));
+        }
+        return result;
+    }
+    let keys;
+    try {
+        keys = Object.keys(value);
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+    const result = {};
+    for (const key of keys) {
+        if (state.keysVisited >= limits.maxKeys - 1) {
+            result["[truncated]"] = MAX_KEYS_VALUE;
+            break;
+        }
+        state.keysVisited += 1;
+        result[truncate(key, limits.maxStringLength)] = normalizeValue(readProperty(value, key), depth + 1, state, limits);
+    }
+    return result;
+};
+function normalizeUnknown(value, limits) {
+    const normalizedLimits = normalizeLimits(limits);
+    try {
+        return normalizeValue(value, 0, { seen: new WeakSet(), keysVisited: 0 }, normalizedLimits);
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+}
+const safeStringProperty = (value, key, fallback, limit) => {
+    const property = readProperty(value, key);
+    return typeof property === "string" ? truncate(property, limit) : fallback;
+};
+function normalizeError(error, limits) {
+    const normalizedLimits = normalizeLimits(limits);
+    let isError;
+    try {
+        isError = error instanceof Error;
+    }
+    catch {
+        isError = false;
+    }
+    if (isError && error !== null && typeof error === "object") {
+        const name = safeStringProperty(error, "name", "Error", normalizedLimits.maxStringLength);
+        const message = safeStringProperty(error, "message", UNREADABLE_VALUE, normalizedLimits.maxStringLength);
+        const stack = safeStringProperty(error, "stack", "", normalizedLimits.maxStackLength);
+        const code = safeStringProperty(error, "code", "", normalizedLimits.maxStringLength);
+        return {
+            name: name || "Error",
+            message,
+            ...(stack ? { stack } : {}),
+            ...(code ? { code } : {}),
+        };
+    }
+    const normalized = normalizeUnknown(error, normalizedLimits);
+    const message = typeof normalized === "string" ? normalized : UNREADABLE_VALUE;
+    return { name: "UnknownError", message };
+}

package/dist/cjs/core/notification-queue.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotificationQueue = createNotificationQueue;
+const DEFAULT_FLUSH_TIMEOUT_MS = 5_000;
+function createNotificationQueue(options) {
+    if (!Number.isSafeInteger(options.maxPendingAlerts) || options.maxPendingAlerts <= 0) {
+        throw new RangeError("maxPendingAlerts must be a positive integer");
+    }
+    if (options.concurrency !== 1) {
+        throw new RangeError("concurrency must be 1");
+    }
+    const pendingJobs = [];
+    let drainPromise;
+    let resolveDrain;
+    let activeJobs = 0;
+    let queued = 0;
+    let dropped = 0;
+    let sent = 0;
+    let failures = 0;
+    const notifyFailure = (error, notifier) => {
+        failures += 1;
+        try {
+            options.onNotifierError?.(error, notifier);
+        }
+        catch {
+            // Diagnostics callbacks cannot be allowed to affect the host application.
+        }
+    };
+    const resolveDrainWaiters = () => {
+        if (activeJobs !== 0 || pendingJobs.length !== 0) {
+            return;
+        }
+        resolveDrain?.();
+        drainPromise = undefined;
+        resolveDrain = undefined;
+    };
+    const processJob = async (job) => {
+        for (const notifier of job.notifiers) {
+            try {
+                await notifier.send(job.alert);
+                sent += 1;
+            }
+            catch (error) {
+                notifyFailure(error, notifier);
+            }
+        }
+    };
+    const pump = () => {
+        while (activeJobs < options.concurrency && pendingJobs.length > 0) {
+            const job = pendingJobs.shift();
+            if (job === undefined) {
+                break;
+            }
+            activeJobs += 1;
+            void processJob(job).finally(() => {
+                activeJobs -= 1;
+                pump();
+                resolveDrainWaiters();
+            });
+        }
+    };
+    const enqueue = (alert, notifiers) => {
+        if (pendingJobs.length >= options.maxPendingAlerts) {
+            dropped += 1;
+            return false;
+        }
+        pendingJobs.push({ alert, notifiers: [...notifiers] });
+        queued += 1;
+        pump();
+        return true;
+    };
+    const flush = (timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS) => {
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+            return Promise.reject(new RangeError("timeoutMs must be a positive integer"));
+        }
+        if (activeJobs === 0 && pendingJobs.length === 0) {
+            return Promise.resolve();
+        }
+        const drain = drainPromise ??
+            new Promise((resolve) => {
+                resolveDrain = resolve;
+            });
+        drainPromise = drain;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Wotchi notification queue flush timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            void drain.then(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    };
+    return {
+        enqueue,
+        flush,
+        pending: () => pendingJobs.length,
+        alertsQueued: () => queued,
+        alertsDropped: () => dropped,
+        alertsSent: () => sent,
+        notifierFailures: () => failures,
+    };
+}

package/dist/cjs/core/process-monitor.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWotchiProcessMonitor = registerWotchiProcessMonitor;
+function registerWotchiProcessMonitor(client) {
+    const listener = (error, origin) => {
+        try {
+            client.captureEvent({
+                level: "error",
+                kind: "process-monitor",
+                message: "Uncaught process exception",
+                error,
+                context: { processOrigin: origin },
+            });
+        }
+        catch {
+            // Process monitoring must never alter the host process crash behavior.
+        }
+    };
+    globalThis.process.on("uncaughtExceptionMonitor", listener);
+    let registered = true;
+    return {
+        unregister() {
+            if (!registered) {
+                return;
+            }
+            registered = false;
+            globalThis.process.off("uncaughtExceptionMonitor", listener);
+        },
+    };
+}

package/dist/cjs/core/redact.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTED = void 0;
+exports.redactValue = redactValue;
+exports.redactError = redactError;
+const normalize_js_1 = require("./normalize.js");
+exports.REDACTED = "[REDACTED]";
+const DEFAULT_KEYS = [
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "password",
+    "passwd",
+    "secret",
+    "apiKey",
+    "api_key",
+    "token",
+    "accessToken",
+    "access_token",
+    "refreshToken",
+    "refresh_token",
+    "privateKey",
+    "private_key",
+    "clientSecret",
+    "client_secret",
+    "cardNumber",
+    "cvv",
+    "cvc",
+    "pin",
+];
+const normalizeKey = (key) => key.toLowerCase().replace(/[-_]/g, "");
+const defaultKeySet = new Set(DEFAULT_KEYS.map(normalizeKey));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const luhnValid = (digits) => {
+    let sum = 0;
+    let double = false;
+    for (let index = digits.length - 1; index >= 0; index -= 1) {
+        let digit = Number(digits[index]);
+        if (double) {
+            digit *= 2;
+            if (digit > 9) {
+                digit -= 9;
+            }
+        }
+        sum += digit;
+        double = !double;
+    }
+    return sum % 10 === 0;
+};
+const redactCardLikeValues = (value) => value.replace(/\b\d[\d -]{11,25}\d\b/g, (candidate) => {
+    const digits = candidate.replace(/[ -]/g, "");
+    return digits.length >= 13 && digits.length <= 19 && luhnValid(digits) ? exports.REDACTED : candidate;
+});
+const redactString = (value, maxStringLength) => {
+    let result = value;
+    result = result.replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/gi, exports.REDACTED);
+    result = result.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${exports.REDACTED}`);
+    result = result.replace(/\b(?:authorization|password|passwd|secret|token|api[-_]?key)\s*[:=]\s*[^\s,;]+/gi, (match) => `${match.slice(0, match.search(/[:=]/))}: ${exports.REDACTED}`);
+    result = result.replace(/\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, exports.REDACTED);
+    result = result.replace(/\b(?:github_pat|ghp|xox[baprs]-|sk|pk|AKIA)[A-Za-z0-9_-]{8,}\b/gi, exports.REDACTED);
+    result = redactCardLikeValues(result);
+    return result.slice(0, maxStringLength);
+};
+const normalizedOption = (value, fallback) => Number.isSafeInteger(value) && value !== undefined && value > 0 ? value : fallback;
+const redactNormalized = (value, sensitiveKeys, options, depth, keysVisited) => {
+    if (typeof value === "string") {
+        return redactString(value, options.maxStringLength);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (depth >= options.maxDepth) {
+        return "[MaxDepth]";
+    }
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const item of value) {
+            if (keysVisited.value >= options.maxKeys) {
+                break;
+            }
+            keysVisited.value += 1;
+            result.push(redactNormalized(item, sensitiveKeys, options, depth + 1, keysVisited));
+        }
+        return result;
+    }
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (keysVisited.value >= options.maxKeys) {
+            break;
+        }
+        keysVisited.value += 1;
+        const normalizedKey = normalizeKey(key);
+        result[key] = sensitiveKeys.has(normalizedKey)
+            ? exports.REDACTED
+            : typeof child === "string" && normalizedKey === "stack"
+                ? redactString(child, options.maxStackLength)
+                : redactNormalized(child, sensitiveKeys, options, depth + 1, keysVisited);
+    }
+    return result;
+};
+const redactionLimits = (options) => ({
+    maxDepth: normalizedOption(options.maxDepth, 5),
+    maxKeys: normalizedOption(options.maxKeys, 100),
+    maxStringLength: normalizedOption(options.maxStringLength, 500),
+    maxStackLength: normalizedOption(options.maxStackLength, 4_000),
+});
+const sensitiveKeySet = (options) => {
+    const keys = new Set(defaultKeySet);
+    for (const key of options.redactKeys ?? []) {
+        if (typeof key === "string" && key.trim().length > 0) {
+            keys.add(normalizeKey(key.trim()));
+        }
+    }
+    return keys;
+};
+function redactValue(value, options = {}) {
+    const limits = redactionLimits(options);
+    const normalized = (0, normalize_js_1.normalizeUnknown)(value, {
+        maxDepth: limits.maxDepth,
+        maxKeys: limits.maxKeys,
+        maxStringLength: limits.maxStringLength,
+        maxStackLength: limits.maxStackLength,
+    });
+    return redactNormalized(normalized, sensitiveKeySet(options), limits, 0, { value: 0 });
+}
+function redactError(error, options = {}) {
+    const redacted = redactValue(error, options);
+    if (!isRecord(redacted)) {
+        return { name: "UnknownError", message: exports.REDACTED };
+    }
+    const name = typeof redacted.name === "string" ? redacted.name : "UnknownError";
+    const message = typeof redacted.message === "string" ? redacted.message : exports.REDACTED;
+    const stack = typeof redacted.stack === "string" ? redacted.stack : undefined;
+    const code = typeof redacted.code === "string" ? redacted.code : undefined;
+    return {
+        name,
+        message,
+        ...(stack === undefined ? {} : { stack }),
+        ...(code === undefined ? {} : { code }),
+    };
+}

package/dist/cjs/core/rolling-window.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRollingWindow = createRollingWindow;
+function createRollingWindow(options) {
+    if (!Number.isSafeInteger(options.maxEvents) || options.maxEvents <= 0) {
+        throw new RangeError("maxEvents must be a positive integer");
+    }
+    if (!Number.isSafeInteger(options.windowMs) || options.windowMs <= 0) {
+        throw new RangeError("windowMs must be a positive integer");
+    }
+    const now = options.now ?? Date.now;
+    const buffer = new Array(options.maxEvents);
+    let head = 0;
+    let length = 0;
+    const readNow = (timestamp) => {
+        const value = timestamp ?? now();
+        return Number.isFinite(value) ? value : now();
+    };
+    const purge = (timestamp) => {
+        while (length > 0) {
+            const oldest = buffer[head];
+            if (oldest === undefined || timestamp - oldest < options.windowMs) {
+                break;
+            }
+            buffer[head] = undefined;
+            head = (head + 1) % options.maxEvents;
+            length -= 1;
+        }
+    };
+    const add = (timestamp) => {
+        const value = readNow(timestamp);
+        purge(value);
+        const index = (head + length) % options.maxEvents;
+        if (length === options.maxEvents) {
+            buffer[head] = undefined;
+            head = (head + 1) % options.maxEvents;
+            length -= 1;
+        }
+        buffer[index] = value;
+        length += 1;
+    };
+    const timestamps = (timestamp) => {
+        const value = readNow(timestamp);
+        purge(value);
+        const result = [];
+        for (let index = 0; index < length; index += 1) {
+            const entry = buffer[(head + index) % options.maxEvents];
+            if (entry !== undefined) {
+                result.push(entry);
+            }
+        }
+        return result;
+    };
+    return {
+        add,
+        count: (timestamp) => timestamps(timestamp).length,
+        size: (timestamp) => timestamps(timestamp).length,
+        timestamps,
+    };
+}