mikrotik-telegram 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `mikrotik-telegram` are documented here.
+
+The project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-12
+
+### Added
+
+- RouterOS REST transport with typed CRUD helpers.
+- MikroTik hotspot, profile, session, script, scheduler, and voucher services.
+- Telegram command registry with role checks and expiring confirmations.
+- Runtime adapters for Node.js, Bun, webhooks, workers, serverless, cron, and polling.
+- Alert, automation, protected action, and audit logging utilities.
+- Zod-validated environment configuration.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Netpulse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# mikrotik-telegram
+
+[![npm version](https://img.shields.io/npm/v/mikrotik-telegram?logo=npm)](https://www.npmjs.com/package/mikrotik-telegram)
+[![npm downloads](https://img.shields.io/npm/dm/mikrotik-telegram?logo=npm)](https://www.npmjs.com/package/mikrotik-telegram)
+[![Node.js](https://img.shields.io/node/v/mikrotik-telegram?logo=node.js)](https://nodejs.org/)
+[![License](https://img.shields.io/npm/l/mikrotik-telegram)](./LICENSE)
+
+Typed, runtime-neutral automation for MikroTik RouterOS REST and Telegram operations.
+
+This package is designed as an independent library. It does not import Next.js, React, database code, application routes, the legacy RouterOS socket client, or the legacy Telegram bot. Install it from npm in any compatible Node.js, Bun, worker, serverless, or webhook project.
+
+## What it includes
+
+- REST transport with typed CRUD helpers and timeout handling.
+- Hotspot users, profiles, active sessions, scripts, and schedulers.
+- Voucher batches with validation, duplicate checks, and dry-run mode.
+- Telegram commands with aliases, role checks, and expiring confirmations.
+- Webhook, polling, worker, cron, Node.js, and Bun runtime adapters.
+- Router, traffic, and stock anomaly evaluation with cooldown/escalation.
+- Protected actions with role and batch-size guardrails.
+- JSON/CSV audit export for operational traceability.
+
+## Requirements
+
+- Node.js `>=20`, Bun, or a runtime providing `fetch`, `Request`, and `Response`.
+- MikroTik RouterOS with REST enabled.
+- Zod is installed automatically as a production dependency.
+
+## Install
+
+```bash
+npm install mikrotik-telegram
+# or
+pnpm add mikrotik-telegram
+# or
+bun add mikrotik-telegram
+```
+
+## Quick start
+
+```ts
+import { createConfigFromEnv, createRuntime } from 'mikrotik-telegram';
+
+const config = createConfigFromEnv(process.env);
+const runtime = createRuntime(config);
+
+const response = await runtime.handleUpdate({
+  update_id: 1,
+  message: {
+    message_id: 1,
+    text: '/status',
+    chat: { id: '123456789', type: 'private' },
+  },
+});
+
+console.log(response?.text);
+```
+
+## Environment configuration
+
+```env
+MIKROTIK_HOST=192.168.1.64
+MIKROTIK_USER=netpulse-bot
+MIKROTIK_PASSWORD=replace-me
+MIKROTIK_HTTP_PORT=443
+MIKROTIK_HTTPS=true
+MIKROTIK_TIMEOUT_MS=10000
+
+TELEGRAM_BOT_TOKEN=replace-me
+TELEGRAM_ALLOWED_CHAT_IDS=123456789,987654321
+TELEGRAM_ADMIN_CHAT_IDS=123456789
+TELEGRAM_OPERATOR_CHAT_IDS=987654321
+TELEGRAM_WEBHOOK_SECRET=use-at-least-16-characters
+TELEGRAM_CONFIRMATION_TTL_SECONDS=60
+```
+
+Use a dedicated RouterOS user with the minimum required policy. Never commit `.env` files or expose the bot token in logs.
+
+## Advanced RouterOS usage
+
+The service layer is available without Telegram. This is useful for dashboards, external APIs, cron jobs, and custom workflows.
+
+```ts
+import {
+  MikroTikService,
+  RouterOsRestClient,
+} from 'mikrotik-telegram';
+
+const client = new RouterOsRestClient({
+  host: process.env.MIKROTIK_HOST!,
+  port: 443,
+  username: process.env.MIKROTIK_USER!,
+  password: process.env.MIKROTIK_PASSWORD!,
+  https: true,
+  timeoutMs: 10_000,
+});
+
+const mikrotik = new MikroTikService(client);
+
+const preview = await mikrotik.generateVouchers({
+  count: 25,
+  prefix: 'EVENT',
+  profile: 'guest-2h',
+  limitUptime: '2h',
+  dryRun: true,
+});
+
+const users = await mikrotik.listHotspotUsers({ profile: 'guest-2h', limit: 100 });
+console.log({ preview, users });
+```
+
+## Telegram webhook
+
+```ts
+import { createConfigFromEnv, createRuntime, createWebhookHandler } from 'mikrotik-telegram';
+
+const runtime = createRuntime(createConfigFromEnv(process.env));
+export const POST = createWebhookHandler(runtime.handleUpdate, {
+  secret: process.env.TELEGRAM_WEBHOOK_SECRET,
+});
+```
+
+## Protected operations
+
+Destructive actions should be exposed through a protected action instead of being called directly from an untrusted command.
+
+```ts
+import { createProtectedAction } from 'mikrotik-telegram';
+
+const disconnect = createProtectedAction(
+  'disconnect-session',
+  async (input: { sessionId: string }) => ({
+    ok: true,
+    data: await mikrotik.disconnectSession(input.sessionId),
+  }),
+  {
+    requiredRole: 'operator',
+    requiresConfirmation: true,
+    maxBatchSize: 1,
+    confirm: async () => ({ ok: true }),
+  },
+);
+```
+
+## Runtime support
+
+The library owns RouterOS and Telegram behavior but does not own your web framework or process lifecycle.
+
+| Runtime | Entry point |
+| --- | --- |
+| Node.js / Bun | `createNodeBot()` / `createBunBot()` |
+| Fetch-compatible webhook | `createWebhookHandler()` |
+| Serverless | `createServerlessHandler()` |
+| Worker | `createWorkerHandler()` / `createWorkerRuntime()` |
+| Cron | `createCronRunner()` |
+| Long polling | `runPolling()` |
+
+## Security model
+
+- Chat allowlists are checked before command execution.
+- Roles are ordered as `viewer < operator < admin`.
+- Confirmation records are chat-bound and expire automatically.
+- Destructive batches can enforce a maximum size.
+- RouterOS and Telegram credentials stay in caller-managed configuration.
+- Audit records can be exported as JSON or CSV.
+
+## API surface
+
+The public entry point exports configuration, REST transport, services, command registry, runtime adapters, alerting, automation, protected actions, types, and audit helpers from `src/index.ts`.
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- `MAJOR`: breaking API or behavior changes.
+- `MINOR`: backwards-compatible features and new exports.
+- `PATCH`: backwards-compatible fixes, security patches, and documentation corrections.
+
+The npm package is currently `0.1.0`, so the API may still evolve before `1.0.0`. Releases should update `version` in `package.json`, add a changelog entry, run the checks below, and publish a new immutable npm version.
+
+## Local package checks
+
+These commands run from this directory and do not require the root application configuration:
+
+```bash
+npm install
+npm run build
+npm pack --dry-run
+```
+
+The contract suite uses Bun: `bun install`, `bun run build`, and `bun test`.
+
+## Publishing
+
+```bash
+npm login
+npm run build
+npm pack --dry-run
+npm publish --access public
+```
+
+The published tarball contains only `dist`, `README.md`, and `LICENSE`; source tests and the parent application are excluded.

package/dist/actions.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export type ActionExecutionResult<TData = unknown> = {
+    readonly ok: boolean;
+    readonly data?: TData;
+    readonly error?: string;
+};
+export type ActionContext = {
+    readonly chatId: string;
+    readonly userId?: string;
+    readonly role: 'admin' | 'operator' | 'viewer';
+};
+export type ProtectedActionOptions<TInput, TData> = {
+    readonly requiredRole: ActionContext['role'];
+    readonly requiresConfirmation?: boolean;
+    readonly maxBatchSize?: number;
+    readonly confirm?: (input: TInput, context: ActionContext) => Promise<ActionExecutionResult<void>>;
+};
+export declare function createProtectedAction<TInput, TData>(name: string, action: (input: TInput, context: ActionContext) => Promise<ActionExecutionResult<TData>>, options: ProtectedActionOptions<TInput, TData>): (input: TInput, context: ActionContext) => Promise<ActionExecutionResult<TData>>;
+export type RouterActionCatalog = {
+    readonly health: () => Promise<ActionExecutionResult<unknown>>;
+    readonly disconnectUser: (input: {
+        sessionId: string;
+        reason?: string;
+    }) => Promise<ActionExecutionResult<unknown>>;
+    readonly banUser: (input: {
+        address?: string;
+        user?: string;
+        comment?: string;
+        timeout?: string;
+    }) => Promise<ActionExecutionResult<unknown>>;
+};
+export declare function createRouterActionCatalog(actions: Partial<RouterActionCatalog>): RouterActionCatalog;
+export declare const ProtectedActionInputSchema: z.ZodObject<{
+    address: z.ZodOptional<z.ZodString>;
+    user: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/actions.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export function createProtectedAction(name, action, options) {
+    const roleWeight = { viewer: 1, operator: 2, admin: 3 };
+    return async (input, context) => {
+        if (roleWeight[context.role] < roleWeight[options.requiredRole]) {
+            return { ok: false, error: `Role insuffisant pour ${name}.` };
+        }
+        const inputList = Array.isArray(input?.ids)
+            ? input.ids.length
+            : undefined;
+        if (options.maxBatchSize !== undefined && inputList !== undefined && inputList > options.maxBatchSize) {
+            return { ok: false, error: `Lot destructif trop large pour ${name}. Maximum autorisé: ${options.maxBatchSize}.` };
+        }
+        if (options.requiresConfirmation) {
+            const confirmation = options.confirm ? await options.confirm(input, context) : { ok: true };
+            if (!confirmation.ok) {
+                return { ok: false, error: confirmation.error || `Confirmation refusée pour ${name}.` };
+            }
+        }
+        return action(input, context);
+    };
+}
+export function createRouterActionCatalog(actions) {
+    const catalog = {
+        health: actions.health ?? (async () => ({ ok: true, data: { status: 'healthy' } })),
+        disconnectUser: actions.disconnectUser ?? (async (input) => ({ ok: true, data: { success: true, id: input.sessionId, operation: 'disconnect-session' } })),
+        banUser: actions.banUser ?? (async (input) => ({ ok: true, data: { success: true, address: input.address || input.user, ruleId: 'generated' } })),
+    };
+    return {
+        health: () => catalog.health(),
+        disconnectUser: (input) => catalog.disconnectUser(input),
+        banUser: (input) => catalog.banUser(input),
+    };
+}
+export const ProtectedActionInputSchema = z.object({
+    address: z.string().trim().min(1).optional(),
+    user: z.string().trim().min(1).optional(),
+    comment: z.string().max(255).optional(),
+    timeout: z.string().trim().min(1).optional(),
+});

package/dist/alerts.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import type { HotspotProfile, SystemHealth, TrafficMetrics } from './types';
+export declare const AlertSeveritySchema: z.ZodEnum<{
+    info: "info";
+    warning: "warning";
+    critical: "critical";
+}>;
+export type AlertSeverity = z.infer<typeof AlertSeveritySchema>;
+export interface Alert {
+    readonly key: string;
+    readonly severity: AlertSeverity;
+    readonly title: string;
+    readonly message: string;
+    readonly createdAt: string;
+    readonly resolved?: boolean;
+}
+export interface AlertThresholds {
+    readonly cpuWarningPercent: number;
+    readonly cpuCriticalPercent: number;
+    readonly freeMemoryWarningBytes: number;
+    readonly freeMemoryCriticalBytes: number;
+    readonly freeStorageWarningBytes: number;
+    readonly criticalStockMultiplier: number;
+}
+export declare const DefaultAlertThresholds: AlertThresholds;
+export interface RouterSnapshot {
+    readonly online: boolean;
+    readonly health?: SystemHealth;
+    readonly activeSessions?: number;
+}
+export interface AlertEvaluation {
+    readonly alerts: readonly Alert[];
+    readonly resolvedKeys: readonly string[];
+}
+export declare function evaluateRouterAnomalies(snapshot: RouterSnapshot, thresholds?: AlertThresholds, now?: Date): AlertEvaluation;
+export declare function evaluateStockAnomalies(profiles: readonly HotspotProfile[], now?: Date): AlertEvaluation;
+export declare function evaluateTrafficAnomalies(metrics: TrafficMetrics, now?: Date): AlertEvaluation;
+export interface AlertState {
+    readonly lastEmittedAt: Readonly<Record<string, number>>;
+}
+export declare class AlertEngine {
+    private readonly cooldownMs;
+    private readonly now;
+    private readonly lastEmittedAt;
+    private readonly repeatCount;
+    constructor(cooldownMs?: number, now?: () => number);
+    filter(alerts: readonly Alert[]): AlertEvaluation;
+    reset(key?: string): void;
+    snapshot(): AlertState;
+}

package/dist/alerts.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+export const AlertSeveritySchema = z.enum(['info', 'warning', 'critical']);
+export const DefaultAlertThresholds = {
+    cpuWarningPercent: 70,
+    cpuCriticalPercent: 90,
+    freeMemoryWarningBytes: 32 * 1024 * 1024,
+    freeMemoryCriticalBytes: 16 * 1024 * 1024,
+    freeStorageWarningBytes: 64 * 1024 * 1024,
+    criticalStockMultiplier: 1,
+};
+export function evaluateRouterAnomalies(snapshot, thresholds = DefaultAlertThresholds, now = new Date()) {
+    const alerts = [];
+    const add = (key, severity, title, message) => alerts.push({ key, severity, title, message, createdAt: now.toISOString() });
+    if (!snapshot.online)
+        add('router.offline', 'critical', 'Routeur hors ligne', 'Le routeur ne répond plus aux contrôles de disponibilité REST.');
+    if (snapshot.health) {
+        const health = snapshot.health;
+        if (health.cpuLoadPercent >= thresholds.cpuCriticalPercent)
+            add('router.cpu.critical', 'critical', 'CPU critique', `Charge CPU à ${health.cpuLoadPercent}%.`);
+        else if (health.cpuLoadPercent >= thresholds.cpuWarningPercent)
+            add('router.cpu.warning', 'warning', 'CPU élevé', `Charge CPU à ${health.cpuLoadPercent}%.`);
+        if (health.freeMemoryBytes <= thresholds.freeMemoryCriticalBytes)
+            add('router.memory.critical', 'critical', 'Mémoire critique', `Mémoire libre: ${health.freeMemoryBytes} octets.`);
+        else if (health.freeMemoryBytes <= thresholds.freeMemoryWarningBytes)
+            add('router.memory.warning', 'warning', 'Mémoire faible', `Mémoire libre: ${health.freeMemoryBytes} octets.`);
+        if (health.freeStorageBytes <= thresholds.freeStorageWarningBytes)
+            add('router.storage.warning', 'warning', 'Stockage faible', `Stockage libre: ${health.freeStorageBytes} octets.`);
+    }
+    return { alerts, resolvedKeys: [] };
+}
+export function evaluateStockAnomalies(profiles, now = new Date()) {
+    const alerts = profiles.filter((profile) => profile.sharedUsers !== undefined && profile.sharedUsers <= 0).map((profile) => ({
+        key: `profile.stock.${profile.id}`, severity: 'warning', title: 'Profil sans capacité configurée',
+        message: `Le profil ${profile.name} ne possède pas de capacité partagée positive.`, createdAt: now.toISOString(),
+    }));
+    return { alerts, resolvedKeys: [] };
+}
+export function evaluateTrafficAnomalies(metrics, now = new Date()) {
+    const alerts = [];
+    const add = (key, severity, title, message) => alerts.push({
+        key, severity, title, message, createdAt: now.toISOString(),
+    });
+    if (!metrics.online) {
+        add('traffic.offline', 'critical', 'Flux hors ligne', 'Le routeur n’est plus en mesure de signaler les usages réseau.');
+    }
+    if (metrics.rxBytesPerSecond !== undefined && metrics.rxBytesPerSecond > 8_000_000) {
+        add('traffic.download.warning', 'warning', 'Téléchargement élevé', `Le trafic entrant est de ${metrics.rxBytesPerSecond} octets/s.`);
+    }
+    if (metrics.txBytesPerSecond !== undefined && metrics.txBytesPerSecond > 8_000_000) {
+        add('traffic.upload.warning', 'warning', 'Téléversement élevé', `Le trafic sortant est de ${metrics.txBytesPerSecond} octets/s.`);
+    }
+    if (metrics.totalSessions !== undefined && metrics.peakSessions !== undefined && metrics.totalSessions >= Math.max(1, metrics.peakSessions * 0.8)) {
+        add('traffic.sessions.warning', 'warning', 'Sessions proches du seuil', `Sessions actives: ${metrics.totalSessions} / pic attendu: ${metrics.peakSessions}.`);
+    }
+    return { alerts, resolvedKeys: [] };
+}
+export class AlertEngine {
+    cooldownMs;
+    now;
+    lastEmittedAt = new Map();
+    repeatCount = new Map();
+    constructor(cooldownMs = 15 * 60_000, now = Date.now) {
+        this.cooldownMs = cooldownMs;
+        this.now = now;
+    }
+    filter(alerts) {
+        const emitted = [];
+        for (const alert of alerts) {
+            const previous = this.lastEmittedAt.get(alert.key);
+            const repeats = this.repeatCount.get(alert.key) ?? 0;
+            const nextRepeat = previous !== undefined && this.now() - previous < this.cooldownMs ? repeats + 1 : 0;
+            if (previous !== undefined && this.now() - previous < this.cooldownMs) {
+                this.repeatCount.set(alert.key, nextRepeat);
+                if (nextRepeat < 2)
+                    continue;
+            }
+            else {
+                this.repeatCount.set(alert.key, 0);
+            }
+            const escalated = {
+                ...alert,
+                severity: alert.severity === 'warning' && nextRepeat >= 2 ? 'critical' : alert.severity,
+                title: alert.severity === 'warning' && nextRepeat >= 2 ? `${alert.title} (escalade)` : alert.title,
+                message: alert.severity === 'warning' && nextRepeat >= 2 ? `Répétition détectée: ${alert.message}` : alert.message,
+            };
+            this.lastEmittedAt.set(alert.key, this.now());
+            emitted.push(escalated);
+        }
+        return { alerts: emitted, resolvedKeys: [] };
+    }
+    reset(key) {
+        if (key) {
+            this.lastEmittedAt.delete(key);
+            this.repeatCount.delete(key);
+            return;
+        }
+        this.lastEmittedAt.clear();
+        this.repeatCount.clear();
+    }
+    snapshot() {
+        return { lastEmittedAt: Object.fromEntries(this.lastEmittedAt) };
+    }
+}

package/dist/audit.d.ts

@@ -0,0 +1,20 @@
+export type AuditStatus = 'success' | 'failure' | 'pending';
+export interface AuditEntry {
+    readonly timestamp: string;
+    readonly action: string;
+    readonly actor?: string;
+    readonly resource?: string;
+    readonly status: AuditStatus;
+    readonly metadata?: Record<string, unknown>;
+}
+export declare class AuditLogger {
+    private readonly namespace;
+    private readonly entries;
+    constructor(namespace: string);
+    log(input: Omit<AuditEntry, 'timestamp'>): AuditEntry;
+    snapshot(): readonly AuditEntry[];
+    reset(): void;
+    get scope(): string;
+}
+export declare function createAuditLogger(namespace?: string): AuditLogger;
+export declare function exportAuditLog(entries: readonly AuditEntry[], format?: 'json' | 'csv'): string;

package/dist/audit.js

@@ -0,0 +1,44 @@
+export class AuditLogger {
+    namespace;
+    entries = [];
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    log(input) {
+        const entry = {
+            ...input,
+            timestamp: new Date().toISOString(),
+        };
+        this.entries.push(entry);
+        return entry;
+    }
+    snapshot() {
+        return [...this.entries];
+    }
+    reset() {
+        this.entries.length = 0;
+    }
+    get scope() {
+        return this.namespace;
+    }
+}
+export function createAuditLogger(namespace = 'default') {
+    return new AuditLogger(namespace);
+}
+export function exportAuditLog(entries, format = 'json') {
+    if (format === 'csv') {
+        const rows = [
+            ['timestamp', 'action', 'actor', 'resource', 'status', 'metadata'],
+            ...entries.map((entry) => [
+                entry.timestamp,
+                entry.action,
+                entry.actor ?? '',
+                entry.resource ?? '',
+                entry.status,
+                JSON.stringify(entry.metadata ?? {}),
+            ]),
+        ];
+        return rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(',')).join('\n');
+    }
+    return JSON.stringify(entries, null, 2);
+}

package/dist/automation.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import type { Alert } from './alerts';
+export declare const AutomationActionSchema: z.ZodEnum<{
+    "health-check": "health-check";
+    "stock-check": "stock-check";
+    cleanup: "cleanup";
+    "cleanup-sessions": "cleanup-sessions";
+    backup: "backup";
+    report: "report";
+    "daily-report": "daily-report";
+    "weekly-report": "weekly-report";
+    "router-sync": "router-sync";
+}>;
+export type AutomationAction = z.infer<typeof AutomationActionSchema>;
+export declare const AutomationRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    action: z.ZodEnum<{
+        "health-check": "health-check";
+        "stock-check": "stock-check";
+        cleanup: "cleanup";
+        "cleanup-sessions": "cleanup-sessions";
+        backup: "backup";
+        report: "report";
+        "daily-report": "daily-report";
+        "weekly-report": "weekly-report";
+        "router-sync": "router-sync";
+    }>;
+    intervalMs: z.ZodNumber;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    runImmediately: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AutomationRule = z.infer<typeof AutomationRuleSchema>;
+export interface AutomationContext {
+    readonly now: Date;
+    readonly execute: (action: AutomationAction, rule: AutomationRule) => Promise<AutomationResult>;
+}
+export interface AutomationResult {
+    readonly ruleId: string;
+    readonly action: AutomationAction;
+    readonly success: boolean;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly error?: string;
+    readonly alerts?: readonly Alert[];
+}
+export declare class AutomationEngine {
+    private readonly rules;
+    register(input: AutomationRule): AutomationRule;
+    unregister(id: string): boolean;
+    pause(id: string): AutomationRule;
+    resume(id: string): AutomationRule;
+    list(): readonly AutomationRule[];
+    run(id: string, context: AutomationContext): Promise<AutomationResult>;
+    runDue(context: AutomationContext): Promise<readonly AutomationResult[]>;
+    private getEntry;
+}

package/dist/automation.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export const AutomationActionSchema = z.enum([
+    'health-check',
+    'stock-check',
+    'cleanup',
+    'cleanup-sessions',
+    'backup',
+    'report',
+    'daily-report',
+    'weekly-report',
+    'router-sync',
+]);
+export const AutomationRuleSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1).max(100),
+    action: AutomationActionSchema,
+    intervalMs: z.number().int().positive(),
+    enabled: z.boolean().default(true),
+    runImmediately: z.boolean().default(false),
+});
+export class AutomationEngine {
+    rules = new Map();
+    register(input) {
+        const rule = AutomationRuleSchema.parse(input);
+        this.rules.set(rule.id, { rule });
+        return rule;
+    }
+    unregister(id) {
+        return this.rules.delete(z.string().min(1).parse(id));
+    }
+    pause(id) {
+        const entry = this.getEntry(id);
+        entry.rule = { ...entry.rule, enabled: false };
+        return entry.rule;
+    }
+    resume(id) {
+        const entry = this.getEntry(id);
+        entry.rule = { ...entry.rule, enabled: true };
+        return entry.rule;
+    }
+    list() {
+        return [...this.rules.values()].map((entry) => entry.rule);
+    }
+    async run(id, context) {
+        const entry = this.getEntry(id);
+        const startedAt = context.now.toISOString();
+        if (!entry.rule.enabled)
+            return { ruleId: id, action: entry.rule.action, success: false, startedAt, finishedAt: context.now.toISOString(), error: 'Automation désactivée.' };
+        try {
+            const result = await context.execute(entry.rule.action, entry.rule);
+            entry.lastRunAt = context.now.getTime();
+            return { ...result, ruleId: id, action: entry.rule.action, startedAt, finishedAt: new Date().toISOString() };
+        }
+        catch (error) {
+            entry.lastRunAt = context.now.getTime();
+            return { ruleId: id, action: entry.rule.action, success: false, startedAt, finishedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async runDue(context) {
+        const now = context.now.getTime();
+        const due = [...this.rules.values()].filter((entry) => entry.rule.enabled && (entry.rule.runImmediately || entry.lastRunAt === undefined || now - entry.lastRunAt >= entry.rule.intervalMs));
+        return Promise.all(due.map((entry) => this.run(entry.rule.id, context)));
+    }
+    getEntry(id) {
+        const entry = this.rules.get(z.string().min(1).parse(id));
+        if (!entry)
+            throw new Error(`Automation inconnue: ${id}`);
+        return entry;
+    }
+}