@adonis-agora/telescope 0.1.0

package/dist/src/alerts/alerter.js

@@ -0,0 +1,248 @@
+import { NewExceptionTracker } from './new_exception_tracker.js';
+import { durationToMs } from './parse_duration.js';
+/** Stack frames carried in a `new-exception` alert (the Slack channel re-clips). */
+const ALERT_STACK_FRAME_LIMIT = 12;
+/**
+ * Wires a source of exception {@link Entry} objects → rule evaluation → channels.
+ *
+ * Two evaluation paths, both driven by {@link evaluate} (called once per poll with
+ * the exception entries observed since the last poll):
+ *  1. The `new-exception` rule fires the FIRST time a family hash is seen within
+ *     its window (and again after the window elapses / a {@link resolveFamily}),
+ *     deduped by {@link NewExceptionTracker} and rate-limited by the per-family
+ *     cooldown.
+ *  2. The `exception-rate` rule fires when the running count of exception entries
+ *     in its trailing window crosses the threshold, rate-limited by a per-rule
+ *     cooldown.
+ *
+ * Every fired alert fans out to ALL configured channels concurrently; one channel
+ * failing never blocks the others. NEVER throws into the caller: a channel failure
+ * is warn-logged (rate-limited per channel) and otherwise swallowed.
+ */
+export class Alerter {
+    deps;
+    now;
+    logger;
+    tracker;
+    /** Per-rule-index last-fired wall time for the rate-rule cooldown. */
+    lastFiredAt = new Map();
+    /** Per-family last-fired wall time for the `new-exception` cooldown. */
+    lastFiredFamily = new Map();
+    /** Channels we've already warned about (rate-limit failure logs by name). */
+    warnedChannels = new Set();
+    /** Sliding-window timestamps of recent exception entries (rate rule). */
+    recentExceptions = [];
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.logger = deps.logger ?? ((message) => console.warn(message));
+        this.tracker = new NewExceptionTracker(deps.maxFamilies);
+    }
+    /**
+     * Evaluate every rule over a freshly-observed batch of exception entries. Safe
+     * to call with an empty batch (rate rules still re-check their window against
+     * already-recorded timestamps). Never throws into the caller.
+     */
+    async evaluate(exceptionEntries) {
+        if (!this.deps.alerts.enabled)
+            return;
+        const nowMs = this.now();
+        try {
+            // Record each exception at its OWN event time (not poll time), so the
+            // rate window reflects when errors actually happened. The poller feeds
+            // entries oldest-first, so timestamps stay ascending for the cutoff shift.
+            for (const entry of exceptionEntries) {
+                this.recentExceptions.push(entry.createdAt.getTime());
+            }
+            await this.evaluateNewException(exceptionEntries, nowMs);
+            await this.evaluateExceptionRate(nowMs);
+        }
+        catch (error) {
+            // A bug in evaluation must never break the caller's poll loop.
+            this.logger(`Telescope alert evaluation failed: ${asMessage(error)}`);
+        }
+    }
+    /**
+     * Explicitly forget a family so its next occurrence pages again immediately —
+     * the "resolved → re-occurred" path. Also clears its cooldown.
+     */
+    resolveFamily(familyHash) {
+        this.tracker.resolve(familyHash);
+        this.lastFiredFamily.delete(familyHash);
+    }
+    /** Number of error families currently tracked (test/observability seam). */
+    get trackedFamilies() {
+        return this.tracker.size;
+    }
+    async evaluateNewException(entries, nowMs) {
+        const result = this.findRule('new-exception');
+        if (result === null)
+            return;
+        const windowMs = durationToMs(result.rule.window);
+        // Count occurrences per family once (O(n)) instead of re-scanning the batch
+        // per entry (O(n²)). This is the count within this poll batch.
+        const occurrencesByFamily = new Map();
+        for (const entry of entries) {
+            if (entry.familyHash === null)
+                continue;
+            occurrencesByFamily.set(entry.familyHash, (occurrencesByFamily.get(entry.familyHash) ?? 0) + 1);
+        }
+        for (const entry of entries) {
+            if (entry.familyHash === null)
+                continue;
+            const isNew = this.tracker.observe(entry.familyHash, nowMs, windowMs);
+            if (!isNew)
+                continue;
+            if (this.familyInCooldown(entry.familyHash, nowMs))
+                continue;
+            this.lastFiredFamily.set(entry.familyHash, nowMs);
+            const occurrences = occurrencesByFamily.get(entry.familyHash) ?? 1;
+            await this.dispatch(this.buildNewExceptionPayload(result.rule, entry, occurrences, nowMs));
+        }
+    }
+    async evaluateExceptionRate(nowMs) {
+        const result = this.findRule('exception-rate');
+        if (result === null)
+            return;
+        const { rule, index } = result;
+        const windowMs = durationToMs(rule.window);
+        // Drop timestamps that have aged out of the window.
+        const cutoff = nowMs - windowMs;
+        while (this.recentExceptions.length > 0 && this.recentExceptions[0] < cutoff) {
+            this.recentExceptions.shift();
+        }
+        const value = this.recentExceptions.length;
+        if (value < rule.threshold)
+            return;
+        if (this.inCooldown(index, nowMs))
+            return;
+        this.lastFiredAt.set(index, nowMs);
+        await this.dispatch(this.buildRatePayload(rule, value, rule.threshold, nowMs));
+    }
+    /** Find a configured rule of `type` with its array index, or `null`. */
+    findRule(type) {
+        for (let index = 0; index < this.deps.alerts.rules.length; index++) {
+            const rule = this.deps.alerts.rules[index];
+            if (rule !== undefined && rule.type === type) {
+                return { rule: rule, index };
+            }
+        }
+        return null;
+    }
+    inCooldown(index, nowMs) {
+        const last = this.lastFiredAt.get(index);
+        if (last === undefined)
+            return false;
+        return nowMs - last < this.deps.alerts.cooldownMs;
+    }
+    familyInCooldown(familyHash, nowMs) {
+        const last = this.lastFiredFamily.get(familyHash);
+        if (last === undefined)
+            return false;
+        return nowMs - last < this.deps.alerts.cooldownMs;
+    }
+    buildRatePayload(rule, value, threshold, nowMs) {
+        return {
+            rule,
+            value,
+            threshold,
+            firedAt: new Date(nowMs).toISOString(),
+            instanceId: this.deps.alerts.instanceId,
+            ...(this.deps.alerts.dashboardUrl !== null
+                ? { dashboardUrl: this.deps.alerts.dashboardUrl }
+                : {}),
+        };
+    }
+    buildNewExceptionPayload(rule, entry, occurrences, nowMs) {
+        return {
+            rule,
+            value: occurrences,
+            threshold: 1,
+            firedAt: new Date(nowMs).toISOString(),
+            instanceId: this.deps.alerts.instanceId,
+            exception: buildExceptionContext(entry, occurrences),
+            ...(this.deps.alerts.dashboardUrl !== null
+                ? { dashboardUrl: this.deps.alerts.dashboardUrl }
+                : {}),
+        };
+    }
+    /**
+     * Fan the payload out to every channel concurrently. Each channel's failure is
+     * isolated (`Promise.allSettled`) and warn-logged ONCE per channel name so a
+     * persistently-down destination doesn't flood the logs. Never rejects.
+     */
+    async dispatch(payload) {
+        const results = await Promise.allSettled(this.deps.alerts.channels.map((channel) => channel.send(payload)));
+        results.forEach((result, index) => {
+            if (result.status === 'rejected') {
+                this.warnChannelFailure(this.deps.alerts.channels[index], result.reason);
+            }
+        });
+    }
+    warnChannelFailure(channel, reason) {
+        if (channel === undefined)
+            return;
+        if (this.warnedChannels.has(channel.name))
+            return;
+        this.warnedChannels.add(channel.name);
+        this.logger(`Telescope alert channel '${channel.name}' failed: ${asMessage(reason)}`);
+    }
+}
+/** Build the rich exception context from an exception {@link Entry}. */
+function buildExceptionContext(entry, occurrences) {
+    const content = asContentRecord(entry.content);
+    return {
+        familyHash: entry.familyHash ?? '',
+        class: pickString(content, ['class', 'name']) ?? 'Error',
+        message: pickString(content, ['message']) ?? '',
+        stack: clipStackFrames(pickString(content, ['stack']) ?? null),
+        route: pickString(content, ['route', 'uri', 'url']),
+        method: pickString(content, ['method']),
+        statusCode: pickNumber(content, ['statusCode', 'status']),
+        user: userFromTags(entry.tags),
+        occurrences,
+        entryId: entry.id,
+    };
+}
+function asContentRecord(content) {
+    return typeof content === 'object' && content !== null
+        ? content
+        : {};
+}
+/** First string-valued field among `keys`, or `null`. */
+function pickString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return null;
+}
+/** First number-valued field among `keys`, or `null`. */
+function pickNumber(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'number')
+            return value;
+    }
+    return null;
+}
+/** Keep at most the first N stack frames; `null` passes through. */
+function clipStackFrames(stack) {
+    if (stack === null)
+        return null;
+    return stack.split('\n').slice(0, ALERT_STACK_FRAME_LIMIT).join('\n');
+}
+/** Extract the user id from a `user:<id>` tag, or `null` when none is present. */
+function userFromTags(tags) {
+    for (const tag of tags) {
+        if (tag.startsWith('user:')) {
+            return tag.slice('user:'.length);
+        }
+    }
+    return null;
+}
+function asMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=alerter.js.map

package/dist/src/alerts/alerter.js.map

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

package/dist/src/alerts/define_config.d.ts

@@ -0,0 +1,68 @@
+import { type AlertChannel } from './alert_channel.js';
+import type { AlertRule, ResolvedAlerts } from './alert_rule.js';
+import type { SlackChannelOptions } from './slack_format.js';
+/**
+ * A declarative channel descriptor — the JSON-friendly form usable directly in
+ * `config/telescope_alerts.ts`. Resolved into a runtime {@link AlertChannel} by
+ * {@link resolveConfig}. For anything custom (email, PagerDuty, …), pass a
+ * pre-built `AlertChannel` object instead (the union below accepts both).
+ */
+export type ChannelSpec = {
+    type: 'slack';
+    url: string;
+    options?: SlackChannelOptions;
+} | {
+    type: 'webhook';
+    url: string;
+} | {
+    type: 'console';
+};
+/** Either a declarative spec or a ready-made channel object. */
+export type ChannelConfig = ChannelSpec | AlertChannel;
+/**
+ * The shape of `config/telescope_alerts.ts`. Everything is optional with sane
+ * defaults: alerting is on, polls every 30s, fires on a brand-new exception family
+ * (re-firing only after a 15m cooldown), and logs to the console channel.
+ */
+export interface TelescopeAlertsConfig {
+    /** Master switch. When `false`, no alerting runs. Default `true`. */
+    enabled?: boolean;
+    /**
+     * Delivery destinations. Each fired alert is sent to every channel concurrently;
+     * one channel failing never blocks the others. Accepts declarative specs
+     * (`{ type: 'slack', url }`) or pre-built `AlertChannel` objects. Default:
+     * a single `console` channel.
+     */
+    channels?: ChannelConfig[];
+    /**
+     * Rules to evaluate. Default: a single `new-exception` rule over a 1h window.
+     */
+    rules?: AlertRule[];
+    /**
+     * External Telescope dashboard URL (e.g. `https://telescope.example.com/`). When
+     * set, channels that support deep links (Slack) build a link to the offending
+     * entry. Optional.
+     */
+    dashboardUrl?: string;
+    /** Poll cadence for the exception source, as a duration string. Default `'30s'`. */
+    every?: string;
+    /** Re-notify suppression per rule/family, as a duration string. Default `'15m'`. */
+    cooldown?: string;
+    /** Reporting instance identifier carried on every payload. Default `'telescope'`. */
+    instanceId?: string;
+}
+/** The default rule set — page on a brand-new exception family within the hour. */
+export declare const DEFAULT_RULES: AlertRule[];
+/**
+ * Identity helper giving `config/telescope_alerts.ts` full type-checking, mirroring
+ * the AdonisJS `defineConfig` convention.
+ */
+export declare function defineConfig(config: TelescopeAlertsConfig): TelescopeAlertsConfig;
+/**
+ * Validate + normalize a (possibly partial) config into the {@link ResolvedAlerts}
+ * the {@link Alerter} acts on. Durations are normalized to ms (an unparseable one
+ * throws — fail closed at boot). With no channels configured a `console` channel
+ * is used so an alert is never silently dropped.
+ */
+export declare function resolveConfig(config?: TelescopeAlertsConfig): ResolvedAlerts;
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/alerts/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/alerts/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAM7D;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,eAAO,MAAM,aAAa,EAAE,SAAS,EAA8C,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,CAEjF;AAoBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,qBAA0B,GAAG,cAAc,CAsBhF"}

package/dist/src/alerts/define_config.js

@@ -0,0 +1,57 @@
+import { consoleChannel, slackChannel, webhookChannel, } from './alert_channel.js';
+import { durationToMs } from './parse_duration.js';
+const DEFAULT_INTERVAL = '30s';
+const DEFAULT_COOLDOWN = '15m';
+const DEFAULT_INSTANCE_ID = 'telescope';
+/** The default rule set — page on a brand-new exception family within the hour. */
+export const DEFAULT_RULES = [{ type: 'new-exception', window: '1h' }];
+/**
+ * Identity helper giving `config/telescope_alerts.ts` full type-checking, mirroring
+ * the AdonisJS `defineConfig` convention.
+ */
+export function defineConfig(config) {
+    return config;
+}
+/** Narrow a {@link ChannelConfig} to a ready-made {@link AlertChannel}. */
+function isChannel(config) {
+    return typeof config.send === 'function';
+}
+/** Resolve one declarative spec (or pass-through object) to an {@link AlertChannel}. */
+function resolveChannel(config) {
+    if (isChannel(config))
+        return config;
+    switch (config.type) {
+        case 'slack':
+            return slackChannel(config.url, config.options);
+        case 'webhook':
+            return webhookChannel(config.url);
+        case 'console':
+            return consoleChannel();
+    }
+}
+/**
+ * Validate + normalize a (possibly partial) config into the {@link ResolvedAlerts}
+ * the {@link Alerter} acts on. Durations are normalized to ms (an unparseable one
+ * throws — fail closed at boot). With no channels configured a `console` channel
+ * is used so an alert is never silently dropped.
+ */
+export function resolveConfig(config = {}) {
+    const channels = (config.channels ?? [{ type: 'console' }]).map(resolveChannel);
+    const rules = config.rules !== undefined && config.rules.length > 0 ? config.rules : DEFAULT_RULES;
+    // Validate every rule window at boot — a typo surfaces here, not silently never.
+    for (const rule of rules) {
+        durationToMs(rule.window);
+    }
+    return {
+        enabled: config.enabled ?? true,
+        channels,
+        dashboardUrl: typeof config.dashboardUrl === 'string' && config.dashboardUrl.trim() !== ''
+            ? config.dashboardUrl
+            : null,
+        intervalMs: durationToMs(config.every ?? DEFAULT_INTERVAL),
+        cooldownMs: durationToMs(config.cooldown ?? DEFAULT_COOLDOWN),
+        instanceId: config.instanceId ?? DEFAULT_INSTANCE_ID,
+        rules,
+    };
+}
+//# sourceMappingURL=define_config.js.map

package/dist/src/alerts/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/alerts/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAC/B,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAC/B,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAiDxC,mFAAmF;AACnF,MAAM,CAAC,MAAM,aAAa,GAAgB,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAEpF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA6B;IACxD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2EAA2E;AAC3E,SAAS,SAAS,CAAC,MAAqB;IACtC,OAAO,OAAQ,MAAuB,CAAC,IAAI,KAAK,UAAU,CAAC;AAC7D,CAAC;AAED,wFAAwF;AACxF,SAAS,cAAc,CAAC,MAAqB;IAC3C,IAAI,SAAS,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAClD,KAAK,SAAS;YACZ,OAAO,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpC,KAAK,SAAS;YACZ,OAAO,cAAc,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAAgC,EAAE;IAC9D,MAAM,QAAQ,GAAmB,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChG,MAAM,KAAK,GACT,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;IAEvF,iFAAiF;IACjF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,QAAQ;QACR,YAAY,EACV,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE;YAC1E,CAAC,CAAC,MAAM,CAAC,YAAY;YACrB,CAAC,CAAC,IAAI;QACV,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,gBAAgB,CAAC;QAC1D,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QAC7D,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,mBAAmB;QACpD,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/src/alerts/exception_source.d.ts

@@ -0,0 +1,44 @@
+import type { TelescopeStore } from '../store.js';
+import type { Alerter } from './alerter.js';
+export interface ExceptionPollerDeps {
+    store: TelescopeStore;
+    alerter: Alerter;
+    /** Poll cadence in ms. */
+    intervalMs: number;
+    /** Wall-clock seam (ms). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Failure log sink. Defaults to `console.warn`. */
+    logger?: (message: string) => void;
+}
+/**
+ * The hook point. Telescope's headless `@adonis-agora/telescope` core does not expose a
+ * "new entry" event, so — by design, to avoid modifying core — this poller reads
+ * the {@link TelescopeStore} on an interval for `exception` entries recorded since
+ * the previous poll (a high-water-mark on `createdAt`) and feeds them to the
+ * {@link Alerter}. Polling keeps the hook fully testable (drive {@link pollOnce}
+ * directly) and decoupled from any specific watcher.
+ *
+ * The unref'd timer means the poller never keeps the process alive on its own.
+ * Every poll is wrapped so a store failure is logged, not thrown.
+ */
+export declare class ExceptionPoller {
+    private readonly deps;
+    private readonly now;
+    private readonly logger;
+    private timer;
+    /** High-water mark: only entries strictly newer than this are new to us. */
+    private since;
+    constructor(deps: ExceptionPollerDeps);
+    /** Start the unref'd poll interval. Idempotent. */
+    start(): void;
+    /** Stop the poll interval. Idempotent. */
+    stop(): void;
+    /**
+     * Read exception entries recorded since the last poll, advance the high-water
+     * mark, and hand them to the alerter. Exposed for deterministic tests. Never
+     * throws — a store failure is logged and the watermark is left untouched so the
+     * next poll retries the same window.
+     */
+    pollOnce(): Promise<void>;
+}
+//# sourceMappingURL=exception_source.d.ts.map

package/dist/src/alerts/exception_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception_source.d.ts","sourceRoot":"","sources":["../../../src/alerts/exception_source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAOd,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,KAAK,CAA+C;IAC5D,4EAA4E;IAC5E,OAAO,CAAC,KAAK,CAAO;gBAES,IAAI,EAAE,mBAAmB;IAOtD,mDAAmD;IACnD,KAAK,IAAI,IAAI;IAUb,0CAA0C;IAC1C,IAAI,IAAI,IAAI;IAOZ;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBhC"}

package/dist/src/alerts/exception_source.js

@@ -0,0 +1,79 @@
+import { EntryType } from '../entry.js';
+/** Cap on entries pulled per poll — a coarse alert check never needs more. */
+const POLL_SCAN_CAP = 1_000;
+/**
+ * The hook point. Telescope's headless `@adonis-agora/telescope` core does not expose a
+ * "new entry" event, so — by design, to avoid modifying core — this poller reads
+ * the {@link TelescopeStore} on an interval for `exception` entries recorded since
+ * the previous poll (a high-water-mark on `createdAt`) and feeds them to the
+ * {@link Alerter}. Polling keeps the hook fully testable (drive {@link pollOnce}
+ * directly) and decoupled from any specific watcher.
+ *
+ * The unref'd timer means the poller never keeps the process alive on its own.
+ * Every poll is wrapped so a store failure is logged, not thrown.
+ */
+export class ExceptionPoller {
+    deps;
+    now;
+    logger;
+    timer = null;
+    /** High-water mark: only entries strictly newer than this are new to us. */
+    since;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.logger = deps.logger ?? ((message) => console.warn(message));
+        // Start from "now" so we never alert on the entire pre-existing backlog at boot.
+        this.since = new Date(this.now());
+    }
+    /** Start the unref'd poll interval. Idempotent. */
+    start() {
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => {
+            this.pollOnce().catch((error) => {
+                this.logger(`Telescope alert poll failed: ${asMessage(error)}`);
+            });
+        }, this.deps.intervalMs);
+        this.timer.unref?.();
+    }
+    /** Stop the poll interval. Idempotent. */
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Read exception entries recorded since the last poll, advance the high-water
+     * mark, and hand them to the alerter. Exposed for deterministic tests. Never
+     * throws — a store failure is logged and the watermark is left untouched so the
+     * next poll retries the same window.
+     */
+    async pollOnce() {
+        let entries;
+        try {
+            entries = await this.deps.store.list({
+                type: EntryType.Exception,
+                after: this.since,
+                limit: POLL_SCAN_CAP,
+            });
+        }
+        catch (error) {
+            this.logger(`Telescope alert poll failed: ${asMessage(error)}`);
+            return;
+        }
+        if (entries.length > 0) {
+            // `list` returns newest-first; advance the mark to the newest seen.
+            const newest = entries[0];
+            if (newest !== undefined)
+                this.since = newest.createdAt;
+        }
+        // Feed oldest-first so occurrence ordering / first-seen detection is natural.
+        await this.deps.alerter.evaluate([...entries].reverse());
+    }
+}
+function asMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=exception_source.js.map

package/dist/src/alerts/exception_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception_source.js","sourceRoot":"","sources":["../../../src/alerts/exception_source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,SAAS,EAAE,MAAM,aAAa,CAAC;AAIpD,8EAA8E;AAC9E,MAAM,aAAa,GAAG,KAAK,CAAC;AAa5B;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IAOG;IANZ,GAAG,CAAe;IAClB,MAAM,CAA4B;IAC3C,KAAK,GAA0C,IAAI,CAAC;IAC5D,4EAA4E;IACpE,KAAK,CAAO;IAEpB,YAA6B,IAAyB;QAAzB,SAAI,GAAJ,IAAI,CAAqB;QACpD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAClE,iFAAiF;QACjF,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,mDAAmD;IACnD,KAAK;QACH,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO;QAChC,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACvC,IAAI,CAAC,MAAM,CAAC,gCAAgC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClE,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IAED,0CAA0C;IAC1C,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,OAAgB,CAAC;QACrB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;gBACnC,IAAI,EAAE,SAAS,CAAC,SAAS;gBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,aAAa;aACrB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,gCAAgC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,oEAAoE;YACpE,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC;QAC1D,CAAC;QAED,8EAA8E;QAC9E,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/src/alerts/index.d.ts

@@ -0,0 +1,16 @@
+/** Keep in sync with this package's `version` in package.json. */
+export declare const VERSION = "0.1.0";
+export { consoleChannel, customChannel, slackChannel, webhookChannel, } from './alert_channel.js';
+export type { AlertChannel, ChannelFetch, ConsoleSink } from './alert_channel.js';
+export { formatSlackMessage } from './slack_format.js';
+export type { SlackChannelOptions, SlackMessage } from './slack_format.js';
+export type { AlertPayload, AlertRule, ExceptionAlertContext, ResolvedAlerts, } from './alert_rule.js';
+export { DEFAULT_MAX_FAMILIES, NewExceptionTracker } from './new_exception_tracker.js';
+export { Alerter } from './alerter.js';
+export type { AlerterDeps } from './alerter.js';
+export { ExceptionPoller } from './exception_source.js';
+export type { ExceptionPollerDeps } from './exception_source.js';
+export { durationToMs } from './parse_duration.js';
+export { DEFAULT_RULES, defineConfig, resolveConfig } from './define_config.js';
+export type { ChannelConfig, ChannelSpec, TelescopeAlertsConfig, } from './define_config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/alerts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alerts/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGlF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG3E,YAAY,EACV,YAAY,EACZ,SAAS,EACT,qBAAqB,EACrB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGvF,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,aAAa,EACb,WAAW,EACX,qBAAqB,GACtB,MAAM,oBAAoB,CAAC"}

package/dist/src/alerts/index.js

@@ -0,0 +1,17 @@
+/** Keep in sync with this package's `version` in package.json. */
+export const VERSION = '0.1.0';
+// — channels —
+export { consoleChannel, customChannel, slackChannel, webhookChannel, } from './alert_channel.js';
+// — slack formatting —
+export { formatSlackMessage } from './slack_format.js';
+// — new-exception dedupe —
+export { DEFAULT_MAX_FAMILIES, NewExceptionTracker } from './new_exception_tracker.js';
+// — alerter (source → tracker → channels) —
+export { Alerter } from './alerter.js';
+// — exception source (the polling hook) —
+export { ExceptionPoller } from './exception_source.js';
+// — duration helper —
+export { durationToMs } from './parse_duration.js';
+// — config —
+export { DEFAULT_RULES, defineConfig, resolveConfig } from './define_config.js';
+//# sourceMappingURL=index.js.map

package/dist/src/alerts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/alerts/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,eAAe;AACf,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B,uBAAuB;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAWvD,2BAA2B;AAC3B,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEvF,4CAA4C;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,0CAA0C;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,sBAAsB;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,aAAa;AACb,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/alerts/new_exception_tracker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Default cap on tracked error families. The map is the ONLY state the
+ * `new-exception` rule keeps, and it must stay bounded so a host that throws a
+ * long tail of unique error families (e.g. message-embedded ids that defeat the
+ * family hash) can never grow it without limit. At the cap we evict the OLDEST
+ * inserted family — the one least likely to still be "recently seen" — which is
+ * the correct bias for a recency-window dedup.
+ */
+declare const DEFAULT_MAX_FAMILIES = 10000;
+/**
+ * Bounded, in-memory "have we seen this error family recently?" tracker backing
+ * the `new-exception` rule. Per-process by design: it lives in process memory, so
+ * in a multi-replica deployment the SAME family may be reported as new once per
+ * pod (documented caveat — acceptable for v1).
+ *
+ * Eviction uses a `Map`'s insertion-order iteration: the first key is the oldest
+ * INSERTED entry. The window check already discards stale last-seen times, so
+ * insertion-order eviction is a sound, O(1) cap with no per-touch bookkeeping.
+ *
+ * Ported verbatim from the aviary telescope core.
+ */
+export declare class NewExceptionTracker {
+    private readonly seen;
+    private readonly maxFamilies;
+    constructor(maxFamilies?: number);
+    /**
+     * Record an observation of `familyHash` at `nowMs` and report whether this is a
+     * NEW family for the `windowMs` window — i.e. it was either never seen or last
+     * seen longer ago than the window (the "re-occurring after being resolved"
+     * signal). Always updates the stored last-seen time so repeat occurrences
+     * refresh the window. Returns `true` only on a genuine first/expired occurrence
+     * (the signal that should fire the alert).
+     */
+    observe(familyHash: string, nowMs: number, windowMs: number): boolean;
+    /**
+     * Forget `familyHash` entirely, so its NEXT occurrence is reported as new again.
+     * This is the explicit "resolve" hook: after an operator marks a family resolved
+     * (or a self-heal job clears it), the very next occurrence pages again without
+     * waiting for the window to elapse.
+     */
+    resolve(familyHash: string): void;
+    /** Forget every tracked family. */
+    clear(): void;
+    /** Number of tracked families (test/observability seam). */
+    get size(): number;
+    /** Evict the oldest entries until the map is within its cap. */
+    private evictIfNeeded;
+}
+export { DEFAULT_MAX_FAMILIES };
+//# sourceMappingURL=new_exception_tracker.d.ts.map

package/dist/src/alerts/new_exception_tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new_exception_tracker.d.ts","sourceRoot":"","sources":["../../../src/alerts/new_exception_tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,QAAA,MAAM,oBAAoB,QAAS,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,GAAE,MAA6B;IAItD;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAWrE;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIjC,mCAAmC;IACnC,KAAK,IAAI,IAAI;IAIb,4DAA4D;IAC5D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gEAAgE;IAChE,OAAO,CAAC,aAAa;CAOtB;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}