0.0.0Version

165Tests

14Suites

0Failures

⚠Pre-kick-off

★ START HERE

Quick Start

Clone → install → run · si falta .env la app te guía (mock o Telegram)

☞ GUÍA COMPLETA

☞ GITHUB REPO

☞ TUI DASHBOARD GUIDE

☞ PROMPTS & AGENTES

install Bun first if needed → bun.sh git clone https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk.git cd heteronimos-semi-asistidos-sdk && bun install bun run lint && bun run test bun run dev

No necesitas configurar .env antes de arrancar: la consola te pregunta si quieres crearlo y te ofrece modo mock; el dashboard entra en mock automáticamente y te deja configurar desde el Config Panel. En modo mock, el panel [5] Commands permite ejecutar comandos directamente desde la UI y ver las respuestas del bot en tiempo real.

Dos arquetipos: headless (examples/console-app/) e interactive (examples/dashboard/ — TUI admin panel). Detalles completos en la guía de Quick Start.

CORE

Architecture — Bot-of-Bots

Each bot is a BotPlugin. The public entrypoint is src/index.ts; the core wires, prefixes, syncs, and broadcasts.

 ┌──────────────────────────────────────────────┐
 │  main.ts                                     │
 │                                              │
 │  plugins[] ──→ registerPlugins(bot, plugins) │
 │                    │                         │
 │         ┌──────────┼──────────┐              │
 │         ▼          ▼          ▼              │
 │    commands    menus     onMessage           │
 │    (prefixed)  (inline)  (fallback)          │
 │         │          │          │              │
 │         └──────────┼──────────┘              │
 │                    ▼                         │
 │             syncCommands()                   │
 │             ┌─ diff local vs Telegram        │
 │             ├─ prompt on changes             │
 │             └─ broadcast update              │
 └──────────────────────────────────────────────┘

bot-handler command-handler menu-handler chat-tracker logger

INTERFACE

BotPlugin — Create Your Own Bot

Implement BotPlugin, register in main.ts, done.

BotPlugin interface { name: string; pluginCode: string; # prefix for all commands commands(): CommandDefinition[]; menus?(): MenuDefinition[]; # optional inline keyboards onMessage?(ctx): string; # optional fallback handler }

Commands are auto-prefixed: pluginCode_command
e.g. pluginCode "rb" → /rb_aleph, /rb_menu, /rb_join

Example — minimal plugin

import type { BotPlugin } from "heteronimos-semi-asistidos-sdk"; export class MyBot implements BotPlugin { name = "my-bot"; pluginCode = "mb"; commands() { return [{ command: "hello", description: "Say hello", buildText: (ctx) => Hello, ${ctx.from?.first_name}!, }]; } }

examples/console-app/main.ts import { registerPlugins } from "heteronimos-semi-asistidos-sdk"; const plugins = [new MyBot()]; registerPlugins(bot, plugins, tracker);

Core Modules

command-handler

CommandDefinition · handleCommand() generic sequence · registerCommands() · toBotFatherFormat() · syncCommandsWithTelegram() with diff (+/~/-)

menu-handler

MenuDefinition · NavButton / UrlButton · registerMenu() auto-wires /command + callback queries · inline keyboard pages

chat-tracker

Persists chat IDs to .chats.json · middleware auto-tracking · broadcast(bot, msg) to all known chats

logger

LOG_LEVEL env (debug|info|warn|error) · scoped [timestamp] [LEVEL] [scope] · child() sub-loggers · colored output

Quick Reference

Sin .env la app arranca en modo mock — ver Quick Start.

Stack

Bun TypeScript grammY Telegram Bot API

License: AIPL — Animus Iocandi Public License
Org: Escrivivir.co

DEMO

RabbitBot — Example Plugin

pluginCode = "rb" · 4 commands · 1 menu (2 pages) · onMessage handler

☞ TRY THE BOT

/rb_aleph next Fibonacci-date event · /rb_join join link · /rb_quit quit · /rb_alephs all events · /rb_menu inline keyboard

Channel: A cyborg-driven chat room

GROUPS

Groups & Privacy Mode

Para que el bot reciba todos los mensajes en grupos, desactiva Privacy Mode en BotFather

Por defecto, Telegram bots tienen Privacy Mode activado — en grupos solo reciben:

• Mensajes que empiezan con / (comandos)
• Respuestas a mensajes del propio bot
• Mensajes que @mencionan al bot por su username

Si necesitas que el bot reciba todos los mensajes del grupo (para handlers onMessage):

@BotFather → /setprivacy → selecciona tu bot → Disable

Importante: Después de cambiar este ajuste, elimina y vuelve a añadir el bot a cada grupo para que el cambio surta efecto.

Menú `/` en grupos: El SDK registra los comandos con scopes default y all_group_chats automáticamente, para que el menú de comandos aparezca tanto en chats privados como en grupos y supergrupos.

Webhooks residuales: Al arrancar, el SDK verifica si hay un webhook activo y lo elimina automáticamente para garantizar que el long-polling funcione correctamente.

AI

Prompts & Agentes Expertos

Sesiones guiadas con IA · El agente se caracteriza según el lore que le proporcionas

☞ VER TODOS LOS PROMPTS

hacker-devops — Un hacker DevOps experimentado analiza la codebase en 5 fases: revisión inquisitiva → adaptación por rol → plan de ataque → offboarding → cierre. Invócalo con @workspace /hacker-devops y añade lore al final para especializar al agente.

Tip: los prompts viven en .github/prompts/ — puedes copiarlos y pegarlos en cualquier agente de IA, no solo Copilot.

Contributing

1. Check BACKLOG.md for open tasks (🗒) 2. Fork → branch from main → feat/ fix/ docs/
3. Implement → bun run lint → bun run test
4. Update docs + backlog when a contributor-facing phase closes
5. Open a PR against main — reference the backlog item #

Session handoff: finish with bun run lint and bun run test, update BACKLOG.md if a phase is done, and keep GH Pages aligned with README.md and related specs/docs.

heteronimos-semi-asistidos-sdk · v0.0.0 · 165 tests passing · Escrivivir.co · AIPL