@marinoscar/platform-api 0.1.0-next.19 → 0.1.0-next.21

package/dist/alerts/alerts.metrics.d.ts

@@ -0,0 +1,60 @@
+import { OnModuleInit } from '@nestjs/common';
+import type { BatchObservableResult, ObservableGauge } from '@opentelemetry/api';
+import { MetricsHostService, type AppGaugeContext, type AppMetricDef } from '../otel-core/index';
+import type { AlertsPrisma } from './data/alerts-db';
+/**
+ * One alerts metric's declaration, its `key` a literal.
+ *
+ * @typeParam Key - the metric's code key.
+ * @stability experimental
+ */
+export interface AlertsAppMetricDef<Key extends string> extends AppMetricDef {
+    /** The metric's code key. */
+    readonly key: Key;
+}
+/**
+ * The alerts metrics: the `app.alerts.transitions` counter (`to` = `fired` or
+ * `resolved`, and the severity) and the `app.alerts.firing` gauge (incidents
+ * firing now, by severity). Neither carries a rule or label value.
+ * Register with `registerAppMetrics(ALERTS_APP_METRICS)` before the metrics
+ * host is built.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics([...PLATFORM_APP_METRICS, ...ALERTS_APP_METRICS]);
+ * ```
+ *
+ * @stability experimental
+ */
+export declare const ALERTS_APP_METRICS: readonly [AlertsAppMetricDef<'alertsTransitions'>, AlertsAppMetricDef<'alertsFiring'>];
+/** How long one firing count is reused across collections. */
+export declare const ALERTS_GAUGE_CACHE_TTL_MS = 30000;
+/**
+ * Records the transition counter and observes the firing gauge. Never throws:
+ * a metrics failure must not fail an evaluation.
+ *
+ * @stability experimental
+ */
+export declare class AlertsMetrics implements OnModuleInit {
+    private readonly prisma;
+    private readonly logger;
+    private readonly metrics;
+    private registered;
+    private cache;
+    constructor(prisma: AlertsPrisma, metrics?: MetricsHostService);
+    /** Registers the firing gauge. */
+    onModuleInit(): void;
+    /**
+     * Counts one transition.
+     *
+     * @param to - `fired` or `resolved`.
+     * @param level - the incident's severity.
+     */
+    transition(to: 'fired' | 'resolved', level: string): void;
+    /** Registers the gauge once, only when gauges are on for this process. */
+    registerGauge(): void;
+    /** The batch callback. Never throws. */
+    observe(result: BatchObservableResult, gauge: ObservableGauge, context: AppGaugeContext): Promise<void>;
+    private counts;
+}
+//# sourceMappingURL=alerts.metrics.d.ts.map

package/dist/alerts/alerts.metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.metrics.d.ts","sourceRoot":"","sources":["../../src/alerts/alerts.metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,YAAY,EAAY,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIjF,OAAO,EACL,kBAAkB,EAElB,KAAK,eAAe,EACpB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,GAAG,SAAS,MAAM,CAAE,SAAQ,YAAY;IAC1E,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAiBrH,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;GAKG;AACH,qBACa,aAAc,YAAW,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANlD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAqE;gBAGtC,MAAM,EAAE,YAAY,EAClD,OAAO,CAAC,EAAE,kBAAkB;IAK1C,kCAAkC;IAClC,YAAY,IAAI,IAAI;IAIpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQzD,0EAA0E;IAC1E,aAAa,IAAI,IAAI;IAarB,wCAAwC;IAClC,OAAO,CAAC,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YAU/F,MAAM;CASrB"}

package/dist/alerts/alerts.metrics.js

@@ -0,0 +1,135 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AlertsMetrics_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlertsMetrics = exports.ALERTS_GAUGE_CACHE_TTL_MS = exports.ALERTS_APP_METRICS = void 0;
+const common_1 = require("@nestjs/common");
+const alerts_1 = require("@marinoscar/platform-contract/alerts");
+const index_1 = require("../core/index");
+const index_2 = require("../otel-core/index");
+const severity = { kind: 'enum', values: [...alerts_1.ALERT_SEVERITIES] };
+/**
+ * The alerts metrics: the `app.alerts.transitions` counter (`to` = `fired` or
+ * `resolved`, and the severity) and the `app.alerts.firing` gauge (incidents
+ * firing now, by severity). Neither carries a rule or label value.
+ * Register with `registerAppMetrics(ALERTS_APP_METRICS)` before the metrics
+ * host is built.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics([...PLATFORM_APP_METRICS, ...ALERTS_APP_METRICS]);
+ * ```
+ *
+ * @stability experimental
+ */
+exports.ALERTS_APP_METRICS = [
+    {
+        key: 'alertsTransitions',
+        name: 'app.alerts.transitions',
+        kind: 'counter',
+        unit: '{transition}',
+        description: 'Alert incidents that fired or resolved, by direction and severity.',
+        attributes: { to: { kind: 'enum', values: ['fired', 'resolved'] }, severity },
+    },
+    {
+        key: 'alertsFiring',
+        name: 'app.alerts.firing',
+        kind: 'gauge',
+        unit: '{incident}',
+        description: 'Alert incidents firing now, by severity.',
+        attributes: { severity },
+    },
+];
+/** How long one firing count is reused across collections. */
+exports.ALERTS_GAUGE_CACHE_TTL_MS = 30_000;
+/**
+ * Records the transition counter and observes the firing gauge. Never throws:
+ * a metrics failure must not fail an evaluation.
+ *
+ * @stability experimental
+ */
+let AlertsMetrics = AlertsMetrics_1 = class AlertsMetrics {
+    prisma;
+    logger = new common_1.Logger(AlertsMetrics_1.name);
+    metrics;
+    registered = false;
+    cache = null;
+    constructor(prisma, metrics) {
+        this.prisma = prisma;
+        this.metrics = metrics ?? new index_2.MetricsHostService();
+    }
+    /** Registers the firing gauge. */
+    onModuleInit() {
+        this.registerGauge();
+    }
+    /**
+     * Counts one transition.
+     *
+     * @param to - `fired` or `resolved`.
+     * @param level - the incident's severity.
+     */
+    transition(to, level) {
+        try {
+            this.metrics.add('alertsTransitions', 1, { to, severity: level });
+        }
+        catch (error) {
+            this.logger.debug(`Could not count an alert transition: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Registers the gauge once, only when gauges are on for this process. */
+    registerGauge() {
+        if (this.registered)
+            return;
+        try {
+            const context = this.metrics.gaugeContext();
+            if (!context)
+                return;
+            const gauge = (0, index_2.createRegisteredGauge)(context.meter, 'alertsFiring');
+            context.meter.addBatchObservableCallback((result) => this.observe(result, gauge, context), [gauge]);
+            this.registered = true;
+        }
+        catch (error) {
+            this.logger.debug(`Could not register the alerts gauge: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** The batch callback. Never throws. */
+    async observe(result, gauge, context) {
+        try {
+            if (!context.gateOpen())
+                return;
+            const counts = await this.counts(context.now());
+            for (const level of alerts_1.ALERT_SEVERITIES)
+                result.observe(gauge, counts[level], { severity: level });
+        }
+        catch (error) {
+            this.logger.debug(`Alerts gauge callback skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async counts(nowMs) {
+        if (this.cache && nowMs - this.cache.at < exports.ALERTS_GAUGE_CACHE_TTL_MS)
+            return this.cache.value;
+        const entries = await Promise.all(alerts_1.ALERT_SEVERITIES.map(async (level) => [level, await this.prisma.alertIncident.count({ where: { state: 'firing', severity: level } })]));
+        const value = Object.fromEntries(entries);
+        this.cache = { at: nowMs, value };
+        return value;
+    }
+};
+exports.AlertsMetrics = AlertsMetrics;
+exports.AlertsMetrics = AlertsMetrics = AlertsMetrics_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __param(1, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [Object, index_2.MetricsHostService])
+], AlertsMetrics);
+//# sourceMappingURL=alerts.metrics.js.map

package/dist/alerts/alerts.metrics.js.map

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

package/dist/alerts/alerts.module.d.ts

@@ -0,0 +1,35 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type AlertsModuleOptions } from './alerts.options';
+/**
+ * The alerts slice: rules over telemetry metrics, worker-node events and
+ * fleet health; incidents with a pending/firing/resolved state machine;
+ * notifications and optional webhooks on a transition; the admin routes under
+ * `/api/admin/alerts`.
+ *
+ * @stability experimental
+ */
+export declare class AlertsModule {
+    /**
+     * The slice for one app. Requires the core `PlatformHostModule`
+     * (`PLATFORM_PRISMA`), the global settings and notifications modules, the
+     * jobs module (for `JobsService` and the handler registry), the composed
+     * `alerts` fragment, and `registerAlertsEmailTemplates()` plus
+     * `registerNotifications(ALERTS_NOTIFICATIONS)` in the app's notification
+     * manifest. Pass the configured telemetry module in `imports` to enable the
+     * metric and verdict kinds; without it they report the store unavailable.
+     *
+     * @param options - see {@link AlertsModuleOptions}.
+     * @returns the dynamic module. It exports the rules, incidents and evaluation services.
+     * @throws Error when an option is out of range.
+     *
+     * @example
+     * ```ts
+     * export const alertsModule = AlertsModule.forRoot({ imports: [TelemetryModule] });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options?: AlertsModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=alerts.module.d.ts.map

package/dist/alerts/alerts.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.module.d.ts","sourceRoot":"","sources":["../../src/alerts/alerts.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAA4B,MAAM,gBAAgB,CAAC;AAatF,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAQxF;;;;;;;GAOG;AACH,qBACa,YAAY;IACvB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa;CA+BjE"}

package/dist/alerts/alerts.module.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AlertsModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlertsModule = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../nodes/index");
+const alerts_context_service_1 = require("./alerts-context.service");
+const alerts_admin_controller_1 = require("./alerts-admin.controller");
+const alerts_dispatch_service_1 = require("./alerts-dispatch.service");
+const alerts_evaluation_service_1 = require("./alerts-evaluation.service");
+const alerts_event_listener_1 = require("./alerts-event.listener");
+const alerts_incidents_service_1 = require("./alerts-incidents.service");
+const alerts_rules_service_1 = require("./alerts-rules.service");
+const alerts_seed_service_1 = require("./alerts-seed.service");
+const alerts_constants_1 = require("./alerts.constants");
+const alerts_metrics_1 = require("./alerts.metrics");
+const alerts_options_1 = require("./alerts.options");
+const alerts_evaluate_event_handler_1 = require("./handlers/alerts-evaluate-event.handler");
+const alerts_evaluate_handler_1 = require("./handlers/alerts-evaluate.handler");
+const alerts_incidents_purge_handler_1 = require("./handlers/alerts-incidents-purge.handler");
+const builtin_kinds_1 = require("./kinds/builtin-kinds");
+const alerts_evaluate_task_1 = require("./tasks/alerts-evaluate.task");
+const alerts_purge_task_1 = require("./tasks/alerts-purge.task");
+/**
+ * The alerts slice: rules over telemetry metrics, worker-node events and
+ * fleet health; incidents with a pending/firing/resolved state machine;
+ * notifications and optional webhooks on a transition; the admin routes under
+ * `/api/admin/alerts`.
+ *
+ * @stability experimental
+ */
+let AlertsModule = AlertsModule_1 = class AlertsModule {
+    /**
+     * The slice for one app. Requires the core `PlatformHostModule`
+     * (`PLATFORM_PRISMA`), the global settings and notifications modules, the
+     * jobs module (for `JobsService` and the handler registry), the composed
+     * `alerts` fragment, and `registerAlertsEmailTemplates()` plus
+     * `registerNotifications(ALERTS_NOTIFICATIONS)` in the app's notification
+     * manifest. Pass the configured telemetry module in `imports` to enable the
+     * metric and verdict kinds; without it they report the store unavailable.
+     *
+     * @param options - see {@link AlertsModuleOptions}.
+     * @returns the dynamic module. It exports the rules, incidents and evaluation services.
+     * @throws Error when an option is out of range.
+     *
+     * @example
+     * ```ts
+     * export const alertsModule = AlertsModule.forRoot({ imports: [TelemetryModule] });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, alerts_options_1.resolveAlertsModuleOptions)(options);
+        (0, builtin_kinds_1.registerBuiltinAlertKinds)();
+        const tasks = [
+            ...(resolved.evaluateTask ? [alerts_evaluate_task_1.AlertsEvaluateTask] : []),
+            ...(resolved.purgeTask ? [alerts_purge_task_1.AlertsPurgeTask] : []),
+        ];
+        const providers = [
+            { provide: alerts_constants_1.ALERTS_OPTIONS, useValue: resolved },
+            index_1.NodeLifecycleService,
+            alerts_metrics_1.AlertsMetrics,
+            alerts_context_service_1.AlertContextService,
+            alerts_dispatch_service_1.AlertsDispatchService,
+            alerts_evaluation_service_1.AlertsEvaluationService,
+            alerts_rules_service_1.AlertsRulesService,
+            alerts_incidents_service_1.AlertsIncidentsService,
+            alerts_seed_service_1.AlertsSeedService,
+            alerts_event_listener_1.AlertsEventListener,
+            alerts_evaluate_handler_1.AlertsEvaluateHandler,
+            alerts_evaluate_event_handler_1.AlertsEvaluateEventHandler,
+            alerts_incidents_purge_handler_1.AlertsIncidentsPurgeHandler,
+            ...tasks,
+        ];
+        return {
+            module: AlertsModule_1,
+            imports: [...resolved.imports],
+            controllers: [alerts_admin_controller_1.AlertsAdminController],
+            providers,
+            exports: [alerts_constants_1.ALERTS_OPTIONS, alerts_rules_service_1.AlertsRulesService, alerts_incidents_service_1.AlertsIncidentsService, alerts_evaluation_service_1.AlertsEvaluationService, alerts_metrics_1.AlertsMetrics],
+        };
+    }
+};
+exports.AlertsModule = AlertsModule;
+exports.AlertsModule = AlertsModule = AlertsModule_1 = __decorate([
+    (0, common_1.Module)({})
+], AlertsModule);
+//# sourceMappingURL=alerts.module.js.map

package/dist/alerts/alerts.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.module.js","sourceRoot":"","sources":["../../src/alerts/alerts.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAsF;AAEtF,0CAAsD;AACtD,qEAA+D;AAC/D,uEAAkE;AAClE,uEAAkE;AAClE,2EAAsE;AACtE,mEAA8D;AAC9D,yEAAoE;AACpE,iEAA4D;AAC5D,+DAA0D;AAC1D,yDAAoD;AACpD,qDAAiD;AACjD,qDAAwF;AACxF,4FAAsF;AACtF,gFAA2E;AAC3E,8FAAwF;AACxF,yDAAkE;AAClE,uEAAkE;AAClE,iEAA4D;AAE5D;;;;;;;GAOG;AAEI,IAAM,YAAY,oBAAlB,MAAM,YAAY;IACvB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,UAA+B,EAAE;QAC9C,MAAM,QAAQ,GAAG,IAAA,2CAA0B,EAAC,OAAO,CAAC,CAAC;QACrD,IAAA,yCAAyB,GAAE,CAAC;QAC5B,MAAM,KAAK,GAAoB;YAC7B,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,yCAAkB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,mCAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACjD,CAAC;QACF,MAAM,SAAS,GAAe;YAC5B,EAAE,OAAO,EAAE,iCAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE;YAC/C,4BAAoB;YACpB,8BAAa;YACb,4CAAmB;YACnB,+CAAqB;YACrB,mDAAuB;YACvB,yCAAkB;YAClB,iDAAsB;YACtB,uCAAiB;YACjB,2CAAmB;YACnB,+CAAqB;YACrB,0DAA0B;YAC1B,4DAA2B;YAC3B,GAAG,KAAK;SACT,CAAC;QACF,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC9B,WAAW,EAAE,CAAC,+CAAqB,CAAC;YACpC,SAAS;YACT,OAAO,EAAE,CAAC,iCAAc,EAAE,yCAAkB,EAAE,iDAAsB,EAAE,mDAAuB,EAAE,8BAAa,CAAC;SAC9G,CAAC;IACJ,CAAC;CACF,CAAA;AArDY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,YAAY,CAqDxB"}

package/dist/alerts/alerts.options.d.ts

@@ -0,0 +1,64 @@
+import type { DynamicModule, ForwardReference, Type } from '@nestjs/common';
+import { ALERTS_OPTIONS } from './alerts.constants';
+export { ALERTS_OPTIONS };
+/**
+ * A module the slice needs from the app: the configured telemetry module
+ * (`TelemetryQueryService`, `TELEMETRY_SQL_DIALECT`, `TelemetrySchemaService`,
+ * `TelemetryDashboardService`), when the app has one.
+ *
+ * @stability experimental
+ */
+export type AlertsImport = Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference;
+/**
+ * `AlertsModule.forRoot` options.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface AlertsModuleOptions {
+    /** Which crons this process runs. Each defaults to on. */
+    tasks?: {
+        /** The every-minute evaluation (`alerts.evaluate`). */
+        evaluate?: boolean;
+        /** The daily purge of resolved incidents (`alerts.incidents_purge`). */
+        purge?: boolean;
+    };
+    /** Days a RESOLVED incident is kept (whole days, 1 to 3650). Default 90. */
+    incidentRetentionDays?: number;
+    /** Milliseconds one rule may take to evaluate before it is abandoned (1 000 to 110 000). Default 20 000. */
+    evaluationBudgetMs?: number;
+    /** Seed the disabled starter rules at start. Default `true`. */
+    seedStarterRules?: boolean;
+    /** Modules to import: normally the app's configured telemetry module. */
+    imports?: AlertsImport[];
+}
+/**
+ * The options after defaults and validation.
+ *
+ * @stability experimental
+ */
+export interface ResolvedAlertsModuleOptions {
+    /** Whether the evaluation cron runs here. */
+    readonly evaluateTask: boolean;
+    /** Whether the purge cron runs here. */
+    readonly purgeTask: boolean;
+    /** Retention of resolved incidents, in days. */
+    readonly incidentRetentionDays: number;
+    /** Per-rule evaluation budget, in milliseconds. */
+    readonly evaluationBudgetMs: number;
+    /** Whether the starter rules are seeded. */
+    readonly seedStarterRules: boolean;
+    /** The imports. */
+    readonly imports: readonly AlertsImport[];
+}
+/**
+ * Applies the defaults and validates.
+ *
+ * @param options - the app's options.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the option when one is out of range.
+ *
+ * @stability experimental
+ */
+export declare function resolveAlertsModuleOptions(options?: AlertsModuleOptions): ResolvedAlertsModuleOptions;
+//# sourceMappingURL=alerts.options.d.ts.map

package/dist/alerts/alerts.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.options.d.ts","sourceRoot":"","sources":["../../src/alerts/alerts.options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC;AAErG;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,KAAK,CAAC,EAAE;QACN,uDAAuD;QACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,wEAAwE;QACxE,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,4GAA4G;IAC5G,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yEAAyE;IACzE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,mBAAwB,GAAG,2BAA2B,CAiBzG"}

package/dist/alerts/alerts.options.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALERTS_OPTIONS = void 0;
+exports.resolveAlertsModuleOptions = resolveAlertsModuleOptions;
+const alerts_constants_1 = require("./alerts.constants");
+Object.defineProperty(exports, "ALERTS_OPTIONS", { enumerable: true, get: function () { return alerts_constants_1.ALERTS_OPTIONS; } });
+/**
+ * Applies the defaults and validates.
+ *
+ * @param options - the app's options.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the option when one is out of range.
+ *
+ * @stability experimental
+ */
+function resolveAlertsModuleOptions(options = {}) {
+    const retention = options.incidentRetentionDays ?? 90;
+    if (!Number.isInteger(retention) || retention < 1 || retention > 3650) {
+        throw new Error(`AlertsModule.forRoot: incidentRetentionDays must be a whole number from 1 to 3650 (got ${retention})`);
+    }
+    const budget = options.evaluationBudgetMs ?? 20_000;
+    if (!Number.isInteger(budget) || budget < 1_000 || budget > 110_000) {
+        throw new Error(`AlertsModule.forRoot: evaluationBudgetMs must be a whole number from 1000 to 110000 (got ${budget})`);
+    }
+    return Object.freeze({
+        evaluateTask: options.tasks?.evaluate !== false,
+        purgeTask: options.tasks?.purge !== false,
+        incidentRetentionDays: retention,
+        evaluationBudgetMs: budget,
+        seedStarterRules: options.seedStarterRules !== false,
+        imports: Object.freeze([...(options.imports ?? [])]),
+    });
+}
+//# sourceMappingURL=alerts.options.js.map

package/dist/alerts/alerts.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.options.js","sourceRoot":"","sources":["../../src/alerts/alerts.options.ts"],"names":[],"mappings":";;;AAoEA,gEAiBC;AAnFD,yDAAoD;AAE3C,+FAFA,iCAAc,OAEA;AAuDvB;;;;;;;;GAQG;AACH,SAAgB,0BAA0B,CAAC,UAA+B,EAAE;IAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,qBAAqB,IAAI,EAAE,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,0FAA0F,SAAS,GAAG,CAAC,CAAC;IAC1H,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,kBAAkB,IAAI,MAAM,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,KAAK,IAAI,MAAM,GAAG,OAAO,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,4FAA4F,MAAM,GAAG,CAAC,CAAC;IACzH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,YAAY,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,KAAK,KAAK;QAC/C,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK;QACzC,qBAAqB,EAAE,SAAS;QAChC,kBAAkB,EAAE,MAAM;QAC1B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,KAAK,KAAK;QACpD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;KACrD,CAAC,CAAC;AACL,CAAC"}

package/dist/alerts/alerts.permissions.d.ts

@@ -0,0 +1,27 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares.
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability experimental
+ */
+export type AlertsPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The alerts slice's permissions, keyed by the `PERMISSIONS` constant name the
+ * reference app derives from them. System scope, granted to `admin`.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(ALERTS_PERMISSIONS);
+ * ```
+ *
+ * @stability experimental
+ */
+export declare const ALERTS_PERMISSIONS: {
+    /** `alerts:read`: view alert rules, incidents and the firing summary. */
+    readonly ALERTS_READ: AlertsPermissionDeclaration<'alerts:read'>;
+    /** `alerts:write`: create, edit and delete rules; test them; acknowledge incidents. */
+    readonly ALERTS_WRITE: AlertsPermissionDeclaration<'alerts:write'>;
+};
+//# sourceMappingURL=alerts.permissions.d.ts.map

package/dist/alerts/alerts.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.permissions.d.ts","sourceRoot":"","sources":["../../src/alerts/alerts.permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC,aAAa,CAAC,CAAC;IACjE,uFAAuF;IACvF,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAC,cAAc,CAAC,CAAC;CAcpE,CAAC"}

package/dist/alerts/alerts.permissions.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALERTS_PERMISSIONS = void 0;
+/**
+ * The alerts slice's permissions, keyed by the `PERMISSIONS` constant name the
+ * reference app derives from them. System scope, granted to `admin`.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(ALERTS_PERMISSIONS);
+ * ```
+ *
+ * @stability experimental
+ */
+exports.ALERTS_PERMISSIONS = {
+    ALERTS_READ: {
+        id: 'alerts:read',
+        description: 'View alert rules, incidents and the firing summary',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    ALERTS_WRITE: {
+        id: 'alerts:write',
+        description: 'Create, edit and delete alert rules; test them; acknowledge incidents',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+//# sourceMappingURL=alerts.permissions.js.map

package/dist/alerts/alerts.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.permissions.js","sourceRoot":"","sources":["../../src/alerts/alerts.permissions.ts"],"names":[],"mappings":";;;AAWA;;;;;;;;;;GAUG;AACU,QAAA,kBAAkB,GAK3B;IACF,WAAW,EAAE;QACX,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,YAAY,EAAE;QACZ,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE,uEAAuE;QACpF,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC"}