mikrotik-telegram 0.1.0

package/dist/runtime.js

@@ -0,0 +1,46 @@
+import { AuthorizationError } from './errors';
+import { RouterOsRestClient } from './rest-client';
+import { MikroTikService } from './mikrotik-service';
+import { TelegramClient } from './telegram-client';
+import { TelegramCommandRegistry } from './telegram-commands';
+function roleFor(config, chatId) {
+    if (config.security.adminChatIds.includes(chatId))
+        return 'admin';
+    if (config.security.operatorChatIds.includes(chatId))
+        return 'operator';
+    return config.security.defaultRole;
+}
+function contextFromUpdate(config, update) {
+    const message = update.message;
+    if (!message?.text)
+        return undefined;
+    const chatId = String(message.chat.id);
+    return { context: { chatId, userId: message.from ? String(message.from.id) : undefined, username: message.from?.username, role: roleFor(config, chatId), args: {}, positional: [], rawText: message.text }, text: message.text };
+}
+export function createRuntime(config, fetcher = fetch) {
+    const restClient = new RouterOsRestClient({ ...config.mikrotik, fetch: fetcher });
+    const mikrotik = new MikroTikService(restClient);
+    const telegram = new TelegramClient({ token: config.telegram.token, fetch: fetcher });
+    const registry = new TelegramCommandRegistry({ confirmationTtlMs: config.security.confirmationTtlSeconds * 1000 });
+    registry.registerMany([
+        { name: 'start', aliases: ['help'], description: 'Afficher les commandes', minimumRole: 'viewer', execute: async () => ({ text: 'NetPulse MikroTik Bot 2026\n/status · /users · /profiles · /sessions · /generate' }) },
+        { name: 'status', aliases: ['health'], description: 'État matériel du routeur', minimumRole: 'viewer', execute: async () => { const health = await mikrotik.getSystemHealth(); return { text: `🟢 ${health.identity} · ${health.model}\nCPU: ${health.cpuLoadPercent}% · RAM libre: ${Math.round(health.freeMemoryBytes / 1048576)} MB\nLatence REST: ${health.latencyMs} ms` }; } },
+        { name: 'users', description: 'Lister les tickets hotspot', minimumRole: 'viewer', execute: async (context) => { const users = await mikrotik.listHotspotUsers({ profile: context.args.profile, limit: Number(context.args.limit || 20) }); return { text: users.length ? users.map((user) => `• ${user.name} (${user.profile || 'default'})`).join('\n') : 'Aucun ticket trouvé.' }; } },
+        { name: 'profiles', description: 'Lister les profils hotspot', minimumRole: 'viewer', execute: async () => { const profiles = await mikrotik.listProfiles(); return { text: profiles.length ? profiles.map((profile) => `• ${profile.name} · ${profile.rateLimit || 'illimité'}`).join('\n') : 'Aucun profil trouvé.' }; } },
+        { name: 'sessions', description: 'Lister les sessions actives', minimumRole: 'viewer', execute: async () => { const sessions = await mikrotik.listActiveSessions(); return { text: sessions.length ? sessions.map((session) => `• ${session.user} · ${session.address || 'IP inconnue'}`).join('\n') : 'Aucune session active.' }; } },
+        { name: 'generate', description: 'Générer des vouchers', minimumRole: 'operator', execute: async (context) => { const result = await mikrotik.generateVouchers({ count: Number(context.args.count || context.positional[0] || 1), profile: context.args.profile, limitUptime: context.args.duration, comment: context.args.comment }); return { text: `✅ ${result.created} voucher(s) créé(s)\n${result.vouchers.map((voucher) => `${voucher.name} · ${voucher.password}`).join('\n')}` }; } },
+    ]);
+    return {
+        registry, mikrotik,
+        async handleUpdate(update) {
+            const incoming = contextFromUpdate(config, update);
+            if (!incoming)
+                return undefined;
+            if (config.telegram.allowedChatIds.length && !config.telegram.allowedChatIds.includes(incoming.context.chatId))
+                throw new AuthorizationError('Chat Telegram non autorisé.');
+            const response = await registry.execute(incoming.text, incoming.context);
+            await telegram.sendMessage(incoming.context.chatId, response);
+            return response;
+        },
+    };
+}

package/dist/telegram-client.d.ts

@@ -0,0 +1,19 @@
+import type { CommandResponse } from './types';
+export interface TelegramClientOptions {
+    readonly token: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export interface TelegramSendResult {
+    readonly messageId: number;
+    readonly chatId: string;
+}
+export declare class TelegramClient {
+    private readonly baseUrl;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options: TelegramClientOptions);
+    sendMessage(chatId: string, response: CommandResponse): Promise<TelegramSendResult>;
+    answerCallbackQuery(callbackQueryId: string, text?: string): Promise<void>;
+    private request;
+}

package/dist/telegram-client.js

@@ -0,0 +1,29 @@
+export class TelegramClient {
+    baseUrl;
+    fetcher;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = `https://api.telegram.org/bot${options.token}`;
+        this.fetcher = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    async sendMessage(chatId, response) {
+        const result = await this.request('sendMessage', {
+            chat_id: chatId, text: response.text, parse_mode: response.parseMode,
+            ...(response.buttons ? { reply_markup: { inline_keyboard: response.buttons } } : {}),
+        });
+        return { messageId: result.message_id, chatId };
+    }
+    async answerCallbackQuery(callbackQueryId, text) {
+        await this.request('answerCallbackQuery', { callback_query_id: callbackQueryId, text });
+    }
+    async request(method, body) {
+        const response = await this.fetcher(`${this.baseUrl}/${method}`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const data = await response.json();
+        if (!response.ok || !data.ok)
+            throw new Error(`Telegram API ${method}: ${data.description || response.status}`);
+        return data.result;
+    }
+}

package/dist/telegram-commands.d.ts

@@ -0,0 +1,26 @@
+import type { CommandContext, CommandDefinition, CommandResponse } from './types';
+export interface CommandRegistryOptions {
+    readonly confirmationTtlMs?: number;
+    readonly now?: () => number;
+    readonly idGenerator?: () => string;
+}
+export declare function parseCommand(text: string): {
+    name: string;
+    args: Readonly<Record<string, string>>;
+    positional: readonly string[];
+};
+export declare class TelegramCommandRegistry {
+    private readonly commands;
+    private readonly pending;
+    private readonly confirmationTtlMs;
+    private readonly now;
+    private readonly idGenerator;
+    constructor(options?: CommandRegistryOptions);
+    register(definition: CommandDefinition): this;
+    registerMany(definitions: readonly CommandDefinition[]): this;
+    list(): readonly CommandDefinition[];
+    requestConfirmation(context: CommandContext, command: string): CommandResponse;
+    consumeConfirmation(id: string, chatId: string): string;
+    executeCallback(callbackData: string, chatId: string): Promise<CommandResponse>;
+    execute(text: string, context: Omit<CommandContext, 'args' | 'positional' | 'rawText'>): Promise<CommandResponse>;
+}

package/dist/telegram-commands.js

@@ -0,0 +1,76 @@
+import { AuthorizationError, ConfirmationRequiredError } from './errors';
+const ROLE_WEIGHT = { viewer: 1, operator: 2, admin: 3 };
+export function parseCommand(text) {
+    const tokens = text.trim().split(/\s+/).filter(Boolean);
+    const name = (tokens.shift() || '').replace(/^\//, '').split('@')[0].toLowerCase();
+    const args = {};
+    const positional = [];
+    for (const token of tokens) {
+        const separator = token.indexOf('=');
+        if (separator > 0)
+            args[token.slice(0, separator).toLowerCase()] = token.slice(separator + 1);
+        else
+            positional.push(token);
+    }
+    return { name, args, positional };
+}
+export class TelegramCommandRegistry {
+    commands = new Map();
+    pending = new Map();
+    confirmationTtlMs;
+    now;
+    idGenerator;
+    constructor(options = {}) {
+        this.confirmationTtlMs = options.confirmationTtlMs ?? 60_000;
+        this.now = options.now ?? Date.now;
+        this.idGenerator = options.idGenerator ?? (() => Math.random().toString(36).slice(2, 12));
+    }
+    register(definition) {
+        const names = [definition.name, ...(definition.aliases || [])];
+        for (const name of names)
+            this.commands.set(name.toLowerCase().replace(/^\//, ''), definition);
+        return this;
+    }
+    registerMany(definitions) {
+        definitions.forEach((definition) => this.register(definition));
+        return this;
+    }
+    list() {
+        return [...new Set(this.commands.values())];
+    }
+    requestConfirmation(context, command) {
+        const id = this.idGenerator();
+        this.pending.set(id, { id, chatId: context.chatId, command, expiresAt: this.now() + this.confirmationTtlMs });
+        return { text: `Confirmation requise pour ${command}.`, buttons: [[{ text: 'Confirmer', callbackData: `confirm:${id}` }, { text: 'Annuler', callbackData: `cancel:${id}` }]] };
+    }
+    consumeConfirmation(id, chatId) {
+        const pending = this.pending.get(id);
+        this.pending.delete(id);
+        if (!pending || pending.chatId !== chatId || pending.expiresAt < this.now())
+            throw new ConfirmationRequiredError(id, 'Confirmation absente ou expirée.');
+        return pending.command;
+    }
+    async executeCallback(callbackData, chatId) {
+        if (callbackData.startsWith('confirm:')) {
+            const id = callbackData.slice('confirm:'.length);
+            const command = this.consumeConfirmation(id, chatId);
+            return { text: `Action confirmée: ${command}` };
+        }
+        if (callbackData.startsWith('cancel:')) {
+            const id = callbackData.slice('cancel:'.length);
+            this.pending.delete(id);
+            return { text: 'Action annulée. Aucune modification n’a été effectuée.' };
+        }
+        return { text: 'Callback inconnue.' };
+    }
+    async execute(text, context) {
+        const parsed = parseCommand(text);
+        const definition = this.commands.get(parsed.name);
+        if (!definition)
+            return { text: 'Commande inconnue. Utilisez /help.' };
+        const fullContext = { ...context, ...parsed, rawText: text };
+        if (ROLE_WEIGHT[fullContext.role] < ROLE_WEIGHT[definition.minimumRole])
+            throw new AuthorizationError();
+        return definition.execute(fullContext);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,209 @@
+export type RouterId = string;
+export interface RouterRecord {
+    readonly '.id'?: string;
+    readonly [key: string]: string | undefined;
+}
+export interface RouterPayload {
+    readonly [key: string]: string | number | boolean | null | undefined;
+}
+export type RouterResponse = RouterRecord | RouterRecord[] | string | null;
+export interface SystemHealth {
+    readonly identity: string;
+    readonly model: string;
+    readonly version: string;
+    readonly uptime: string;
+    readonly cpuLoadPercent: number;
+    readonly totalMemoryBytes: number;
+    readonly freeMemoryBytes: number;
+    readonly totalStorageBytes: number;
+    readonly freeStorageBytes: number;
+    readonly latencyMs: number;
+}
+export interface HotspotUser {
+    readonly id: RouterId;
+    readonly name: string;
+    readonly password?: string;
+    readonly profile?: string;
+    readonly comment?: string;
+    readonly limitUptime?: string;
+    readonly uptime?: string;
+}
+export interface HotspotProfile {
+    readonly id: RouterId;
+    readonly name: string;
+    readonly rateLimit?: string;
+    readonly sharedUsers?: number;
+    readonly onLogin?: string;
+}
+export interface ActiveSession {
+    readonly id: RouterId;
+    readonly user: string;
+    readonly address?: string;
+    readonly macAddress?: string;
+    readonly uptime?: string;
+    readonly sessionTimeLeft?: string;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+}
+export interface RouterScript {
+    readonly id: RouterId;
+    readonly name: string;
+    readonly source: string;
+    readonly comment?: string;
+}
+export interface RouterScheduler {
+    readonly id: RouterId;
+    readonly name: string;
+    readonly interval: string;
+    readonly onEvent: string;
+    readonly disabled: boolean;
+}
+export interface MutationResult {
+    readonly success: boolean;
+    readonly id?: RouterId;
+    readonly operation: string;
+}
+export interface BanUserInput {
+    readonly address?: string;
+    readonly user?: string;
+    readonly comment?: string;
+    readonly timeout?: string;
+}
+export interface BanResult extends MutationResult {
+    readonly address?: string;
+    readonly ruleId?: RouterId;
+}
+export interface UnbanUserInput {
+    readonly ruleId?: RouterId;
+    readonly address?: string;
+}
+export interface DeleteUserInput {
+    readonly id: RouterId;
+    readonly reason?: string;
+}
+export interface DisconnectUserInput {
+    readonly sessionId: RouterId;
+    readonly reason?: string;
+}
+export interface UserQuery {
+    readonly name?: string;
+    readonly profile?: string;
+    readonly limit?: number;
+}
+export interface CreateHotspotUserInput {
+    readonly name: string;
+    readonly password: string;
+    readonly profile?: string;
+    readonly comment?: string;
+    readonly limitUptime?: string;
+}
+export interface GenerateVouchersInput {
+    readonly count: number;
+    readonly length?: number;
+    readonly prefix?: string;
+    readonly profile?: string;
+    readonly passwordLength?: number;
+    readonly limitUptime?: string;
+    readonly comment?: string;
+    readonly price?: number;
+    readonly expiresAt?: string;
+    readonly dryRun?: boolean;
+    readonly duplicateCheck?: boolean;
+}
+export interface TrafficMetrics {
+    readonly online: boolean;
+    readonly rxBytesPerSecond?: number;
+    readonly txBytesPerSecond?: number;
+    readonly totalSessions?: number;
+    readonly peakSessions?: number;
+    readonly topUser?: string;
+}
+export interface GeneratedVoucher {
+    readonly name: string;
+    readonly password: string;
+    readonly profile: string;
+    readonly created: boolean;
+    readonly price?: number;
+    readonly expiresAt?: string;
+}
+export interface GenerateVouchersResult {
+    readonly requested: number;
+    readonly created: number;
+    readonly vouchers: readonly GeneratedVoucher[];
+    readonly dryRun: boolean;
+    readonly duplicateSkipped?: number;
+}
+export type UpdateHotspotUserInput = Partial<CreateHotspotUserInput>;
+export interface CreateProfileInput {
+    readonly name: string;
+    readonly rateLimit?: string;
+    readonly sharedUsers?: number;
+    readonly onLogin?: string;
+}
+export type UpdateProfileInput = Partial<CreateProfileInput>;
+export interface CreateScriptInput {
+    readonly name: string;
+    readonly source: string;
+    readonly comment?: string;
+}
+export interface CreateSchedulerInput {
+    readonly name: string;
+    readonly interval: string;
+    readonly onEvent: string;
+    readonly comment?: string;
+    readonly disabled?: boolean;
+}
+export type UpdateSchedulerInput = Partial<CreateSchedulerInput>;
+export interface TelegramUpdate {
+    readonly update_id: number;
+    readonly message?: {
+        readonly message_id: number;
+        readonly text?: string;
+        readonly from?: {
+            readonly id: number;
+            readonly username?: string;
+        };
+        readonly chat: {
+            readonly id: number | string;
+            readonly type: string;
+        };
+    };
+    readonly callback_query?: {
+        readonly id: string;
+        readonly data?: string;
+        readonly from: {
+            readonly id: number;
+            readonly username?: string;
+        };
+        readonly message?: {
+            readonly chat: {
+                readonly id: number | string;
+            };
+        };
+    };
+}
+export type TelegramRole = 'admin' | 'operator' | 'viewer';
+export interface CommandContext {
+    readonly chatId: string;
+    readonly userId?: string;
+    readonly username?: string;
+    readonly role: TelegramRole;
+    readonly args: Readonly<Record<string, string>>;
+    readonly positional: readonly string[];
+    readonly rawText: string;
+}
+export interface CommandResponse {
+    readonly text: string;
+    readonly parseMode?: 'MarkdownV2' | 'HTML';
+    readonly buttons?: readonly (readonly {
+        readonly text: string;
+        readonly callbackData: string;
+    }[])[];
+}
+export interface CommandDefinition {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly description: string;
+    readonly minimumRole: TelegramRole;
+    readonly execute: (context: CommandContext) => Promise<CommandResponse>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mikrotik-telegram",
+  "version": "0.1.0",
+  "description": "Type-safe RouterOS REST automation and Telegram bot package for modern MikroTik operations.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netpulse/netpulse-mikrotik-telegram.git"
+  },
+  "homepage": "https://github.com/netpulse/netpulse-mikrotik-telegram",
+  "bugs": {
+    "url": "https://github.com/netpulse/netpulse-mikrotik-telegram/issues"
+  },
+  "keywords": [
+    "mikrotik",
+    "routeros",
+    "rest",
+    "telegram",
+    "hotspot",
+    "automation",
+    "bun",
+    "node",
+    "serverless"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "test": "bun test src/index.test.ts"
+  },
+  "dependencies": {
+    "zod": "^4.6.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}