create-bunspace 0.2.5 → 0.3.1

package/dist/templates/telegram-bot/core/src/utils/message-builder.ts

@@ -0,0 +1,180 @@
+import telegramFormat from '@flla/telegram-format'
+import type { Formatter } from '@flla/telegram-format'
+
+// Get the formatters from the main module
+const { html } = telegramFormat
+
+/**
+ * MessageBuilder - Fluent API for building formatted Telegram messages
+ *
+ * Provides a consistent way to build messages without worrying about:
+ * - Proper escaping of special characters
+ * - Format consistency (Markdown vs HTML)
+ * - Parse errors from malformed entities
+ *
+ * @example
+ * ```typescript
+ * const message = MessageBuilder.markdown()
+ *   .title('User Information')
+ *   .newline()
+ *   .line('User ID', '123456', { code: true })
+ *   .line('Username', '@john_doe')
+ *   .build()
+ * ```
+ */
+export class MessageBuilder {
+  private parts: string[] = []
+  private listDepth = 0
+
+  private constructor(
+    private formatter: Formatter,
+    private parseModeValue: 'Markdown' | 'HTML' | 'MarkdownV2'
+  ) {}
+
+  /**
+   * Create an HTML message builder (default)
+   * HTML is simpler and more reliable than MarkdownV2
+   */
+  static markdown(): MessageBuilder {
+    return new MessageBuilder(html as unknown as Formatter, 'HTML')
+  }
+
+  /**
+   * Create an HTML message builder
+   */
+  static html(): MessageBuilder {
+    return new MessageBuilder(html as unknown as Formatter, 'HTML')
+  }
+
+  /**
+   * Add a title/heading (bold)
+   */
+  title(text: string): this {
+    this.parts.push(this.formatter.bold(text))
+    return this
+  }
+
+  /**
+   * Add a section heading (underline/italic)
+   */
+  section(text: string): this {
+    this.parts.push(this.formatter.underline(text))
+    return this
+  }
+
+  /**
+   * Add a key-value line
+   * @param key - The label/key
+   * @param value - The value
+   * @param opts - Options for formatting the value
+   */
+  line(key: string, value: string, opts?: { code?: boolean; bold?: boolean }): this {
+    let formattedValue = value
+    if (opts?.code) {
+      formattedValue = this.formatter.monospace(value)
+    } else if (opts?.bold) {
+      formattedValue = this.formatter.bold(value)
+    }
+    this.parts.push(`${key}: ${formattedValue}`)
+    return this
+  }
+
+  /**
+   * Add a code block
+   */
+  codeBlock(text: string, language?: string): this {
+    this.parts.push(this.formatter.monospaceBlock(text, language))
+    return this
+  }
+
+  /**
+   * Add a list item
+   */
+  listItem(text: string, depth: number = 0): this {
+    const indent = '  '.repeat(depth)
+    const bullet = this.listDepth > 0 ? '•' : `${this.listDepth + 1}.`
+    this.parts.push(`${indent}${bullet} ${text}`)
+    return this
+  }
+
+  /**
+   * Add a sublist (increase indentation)
+   */
+  startSublist(): this {
+    this.listDepth++
+    return this
+  }
+
+  /**
+   * End sublist (decrease indentation)
+   */
+  endSublist(): this {
+    if (this.listDepth > 0) this.listDepth--
+    return this
+  }
+
+  /**
+   * Add a newline
+   */
+  newline(): this {
+    this.parts.push('\n')
+    return this
+  }
+
+  /**
+   * Add raw text (escaped, no formatting)
+   */
+  text(text: string): this {
+    this.parts.push(this.formatter.escape(text))
+    return this
+  }
+
+  /**
+   * Add a horizontal rule (separator)
+   */
+  separator(): this {
+    this.parts.push(this.parseModeValue === 'HTML' ? '<hr>' : '---')
+    return this
+  }
+
+  /**
+   * Build the final message string
+   * @returns The formatted message ready to send
+   */
+  build(): string {
+    return this.parts.join('\n').trim()
+  }
+
+  /**
+   * Get the parse_mode for Telegraf
+   * Note: Telegraf accepts 'Markdown' for both Markdown and MarkdownV2
+   */
+  getParseMode(): 'Markdown' | 'HTML' {
+    return this.parseModeValue === 'MarkdownV2' ? 'Markdown' : this.parseModeValue
+  }
+}
+
+/**
+ * Quick escape helper for raw text
+ */
+export function escapeText(text: string): string {
+  const formatter = html as unknown as Formatter
+  return formatter.escape(text)
+}
+
+/**
+ * Format mode type
+ */
+export type FormatType = 'html'
+
+/**
+ * Quick format helpers
+ */
+export const fmt = {
+  bold: (text: string) => (html as unknown as Formatter).bold(text),
+  italic: (text: string) => (html as unknown as Formatter).italic(text),
+  underline: (text: string) => (html as unknown as Formatter).underline(text),
+  code: (text: string) => (html as unknown as Formatter).monospace(text),
+  link: (text: string, url: string) => (html as unknown as Formatter).url(text, url),
+  escape: (text: string) => (html as unknown as Formatter).escape(text),
+}

package/dist/templates/telegram-bot/core/tsconfig.json

@@ -2,6 +2,8 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "rootDir": ".",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
     "types": ["bun-types", "node"]
   },
   "include": ["src/**/*.ts"],

package/dist/templates/telegram-bot/docs/automatizacion_integral_de_bots_de_telegram_con_type_script.md

@@ -0,0 +1,326 @@
+# Automatización integral de bots de Telegram con TypeScript
+
+## 1. Objetivo
+
+Construir un **"BotFather personal"** totalmente automatizado que permita, desde **TypeScript**, realizar:
+
+- Creación de bots de Telegram sin intervención manual.
+- Creación de grupos y supergrupos (foros) y gestión de topics.
+- Obtención automática de *bot tokens*, *chat IDs*, *topic IDs* y demás valores críticos.
+- Creación de un repositorio GitHub desde un template.
+- Despliegue automático del bot en **Coolify**, incluyendo variables de entorno y auto‑deploy.
+
+El objetivo final es eliminar el *setup manual* y dejar un pipeline reproducible y escalable.
+
+---
+
+## 2. Qué se puede y NO se puede hacer según la API de Telegram
+
+### 2.1 Bot API (HTTP – bots)
+
+**Disponible:**
+
+- Enviar/recibir mensajes.
+- Gestionar grupos *si el bot ya está añadido*.
+- Crear y gestionar **forum topics** (`createForumTopic`).
+- Obtener información de chats (`getChat`, `getChatMember`).
+- Moderación (ban, pin, permisos, etc.).
+
+**NO disponible (limitaciones duras):**
+
+- ❌ Crear bots.
+- ❌ Crear grupos o supergrupos.
+- ❌ Iniciar conversaciones con usuarios.
+- ❌ Obtener listado de topics existentes.
+
+👉 La Bot API **NO sirve** para el bootstrap inicial.
+
+---
+
+### 2.2 Telegram API (MTProto – cuenta de usuario)
+
+**Disponible:**
+
+- Enviar mensajes como un usuario (incluido a @BotFather).
+- Crear bots interactuando con @BotFather.
+- Crear grupos y supergrupos.
+- Convertir grupos en supergrupos (megagroups).
+- Añadir bots como administradores.
+- Obtener IDs reales de chats.
+
+**Consideraciones:**
+
+- Requiere `api_id` y `api_hash`.
+- Necesita login por código SMS.
+- Es la **única vía** para automatizar la creación completa.
+
+---
+
+## 3. Arquitectura recomendada (TypeScript)
+
+```
+Bootstrap Service (MTProto)
+ ├─ Crear bot vía BotFather
+ ├─ Crear supergrupo
+ ├─ Añadir bot como admin
+ ├─ Extraer IDs y tokens
+ └─ Provisionar infra (GitHub + Coolify)
+
+Bot Runtime (Bot API)
+ └─ Telegraf / grammY
+```
+
+Separar **bootstrap** y **runtime** es clave.
+
+---
+
+## 4. Librerías disponibles en TypeScript
+
+### 4.1 Telegram API (MTProto)
+
+**GramJS (recomendada)**
+
+- Cliente MTProto completo para Node.js.
+- Permite login como usuario.
+- Permite hablar con @BotFather.
+- Permite crear chats y canales.
+
+```ts
+import { TelegramClient } from "telegram";
+import { StringSession } from "telegram/sessions";
+```
+
+Alternativas:
+
+- TDLib (más compleja, overkill).
+- Telethon (Python, no TS).
+
+---
+
+### 4.2 Bot API
+
+**Telegraf**
+
+- Muy madura.
+- Ideal para bots productivos.
+
+**grammY**
+
+- Más moderna.
+- Mejor tipado TS.
+- Más flexible para middlewares.
+
+---
+
+## 5. Flujo técnico detallado (Telegram)
+
+### 5.1 Crear bot automáticamente
+
+Usando **Telegram API** (usuario):
+
+1. Login con `api_id + api_hash`.
+2. Abrir chat con `@BotFather`.
+3. Enviar `/newbot`.
+4. Responder nombre y username.
+5. Parsear el mensaje que contiene el **BOT TOKEN**.
+
+> El token se guarda como variable de entorno.
+
+---
+
+### 5.2 Crear supergrupo (forum)
+
+Usando Telegram API:
+
+- Crear un **megagroup**.
+- Activar modo foro.
+- Obtener `chat_id` (ej: `-100xxxxxxxxxx`).
+
+---
+
+### 5.3 Añadir bot como administrador
+
+- Invitar el bot por username.
+- Asignar permisos:
+  - `can_manage_topics`
+  - `can_delete_messages`
+
+---
+
+### 5.4 Crear topics
+
+Usando **Bot API**:
+
+```http
+POST https://api.telegram.org/bot<TOKEN>/createForumTopic
+```
+
+Payload:
+
+```json
+{
+  "chat_id": -1001234567890,
+  "name": "logs"
+}
+```
+
+Respuesta contiene:
+
+- `message_thread_id` → ID del topic.
+
+---
+
+## 6. Integración con GitHub (TypeScript)
+
+### 6.1 Crear repositorio desde template
+
+HTTP REST:
+
+```http
+POST /repos/{template_owner}/{template_repo}/generate
+```
+
+Payload:
+
+```json
+{
+  "owner": "mi-user",
+  "name": "telegram-bot-prod",
+  "private": true
+}
+```
+
+Resultado:
+
+- Repo creado.
+- Listo para deploy.
+
+---
+
+## 7. Coolify (sección extensa)
+
+### 7.1 Qué aporta Coolify
+
+- Docker builder.
+- Git‑based deploy.
+- Variables de entorno.
+- Auto‑deploy.
+- Logs centralizados.
+
+Perfecto para bots.
+
+---
+
+### 7.2 Autenticación
+
+- Crear **API Token** desde el panel.
+- Todas las llamadas usan:
+
+```
+Authorization: Bearer <COOLIFY_TOKEN>
+```
+
+---
+
+### 7.3 Crear aplicación automáticamente
+
+Endpoint típico:
+
+```http
+POST /applications/private-deploy-key
+```
+
+Payload:
+
+```json
+{
+  "project_uuid": "...",
+  "server_uuid": "...",
+  "environment_uuid": "...",
+  "git_repository": "https://github.com/user/bot",
+  "git_branch": "main",
+  "name": "telegram-bot"
+}
+```
+
+Esto:
+
+- Clona repo.
+- Ejecuta Dockerfile.
+- Despliega.
+
+---
+
+### 7.4 Variables de entorno (CRÍTICO)
+
+Variables típicas:
+
+- `BOT_TOKEN`
+- `CHAT_ID`
+- `LOG_TOPIC_ID`
+- `NODE_ENV=production`
+
+Se pueden crear vía API:
+
+```http
+POST /applications/{uuid}/envs
+```
+
+Esto permite **inyección completa automática**.
+
+---
+
+### 7.5 Auto‑deploy
+
+Opciones:
+
+- GitHub App (recomendado).
+- Webhook manual.
+
+Resultado:
+
+- Push a `main` → deploy automático.
+
+---
+
+### 7.6 Arquitectura final
+
+```
+User Script (TS)
+ ├─ Telegram API
+ ├─ GitHub API
+ └─ Coolify API
+
+Bot Runtime
+ └─ Telegraf / grammY
+```
+
+---
+
+## 8. Conclusión
+
+- **No es posible** hacerlo solo con Bot API.
+- **Sí es posible** usando Telegram API + Bot API.
+- TypeScript tiene tooling suficiente.
+- Coolify es perfectamente automatizable.
+
+Este enfoque permite crear bots, infra y despliegues en **un solo comando**.
+
+---
+
+## 9. Referencias
+
+- Telegram Bot API [https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
+
+- Telegram API (MTProto) [https://core.telegram.org/api](https://core.telegram.org/api)
+
+- GramJS [https://gram.js.org/](https://gram.js.org/)
+
+- Telegraf [https://telegraf.js.org/](https://telegraf.js.org/)
+
+- grammY [https://grammy.dev/](https://grammy.dev/)
+
+- GitHub REST API – Templates [https://docs.github.com/en/rest/repos/repos#create-a-repository-using-a-template](https://docs.github.com/en/rest/repos/repos#create-a-repository-using-a-template)
+
+- Coolify API [https://coolify.io/docs/api-reference](https://coolify.io/docs/api-reference)
+