npm - opencode-skills-collection - Versions diffs - 4.0.52 → 4.0.54 - Mend

opencode-skills-collection 4.0.52 → 4.0.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1176) hide show

package/bundled-skills/telegram/SKILL.md CHANGED Viewed

@@ -20,9 +20,9 @@ tools:
 # Telegram Bot API - Integracao Profissional
-## Overview
+## Detailed Guide
-Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhooks, inline keyboards, grupos, canais. Boilerplates Node.js e Python.
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 ## When to Use This Skill
@@ -39,545 +39,6 @@ Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhoo
 - A simpler, more specific tool can handle the request
 - The user needs general-purpose assistance without domain expertise
-## How It Works
-Skill para implementar bots profissionais no Telegram usando a Bot API oficial. Suporta Node.js/TypeScript e Python.
-### Overview
-A Telegram Bot API permite criar bots que interagem com usuarios via mensagens, comandos, inline keyboards, pagamentos e muito mais. Bots sao criados pelo @BotFather e autenticados via token unico.
-**Base URL:** `https://api.telegram.org/bot<TOKEN>/METHOD_NAME`
-**Metodos HTTP:** GET e POST
-**Formatos de parametros:** query string, application/x-www-form-urlencoded, application/json, multipart/form-data (uploads)
-**Limite de arquivos:** 50MB download, 20MB upload (via multipart), 50MB via URL
-**Portas suportadas para webhooks:** 443, 80, 88, 8443
-**Pre-requisitos:**
-- Conta no Telegram
-- Bot criado via @BotFather (fornece o token)
-- Token no formato: `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
-Se o usuario nao tem um bot criado, oriente a conversar com @BotFather no Telegram e enviar `/newbot`.
----
-## Decision Tree
-```
-O usuario precisa criar um bot?
-├── SIM → Secao "Setup com BotFather" abaixo
-└── NAO → Qual linguagem?
-    ├── Node.js/TypeScript
-    └── Python
-    → O que quer fazer?
-       ├── Enviar mensagens → Secao "Tipos de Mensagem"
-       ├── Receber mensagens → Secao "Receber Updates"
-       ├── Teclados interativos → Secao "Keyboards"
-       ├── Gerenciar grupos/canais → references/chat-management.md
-       ├── Webhook setup → references/webhook-setup.md
-       ├── Inline mode → references/advanced-features.md
-       ├── Pagamentos → references/advanced-features.md
-       ├── Bot de atendimento com IA → Secao "Automacao com IA"
-       └── Referencia completa da API → references/api-reference.md
-```
-Para iniciar um projeto do zero com boilerplate pronto:
-```bash
-python scripts/setup_project.py --language nodejs --path ./meu-bot-telegram
-## Ou
-python scripts/setup_project.py --language python --path ./meu-bot-telegram
-```
-Para testar se o token do bot funciona:
-```bash
-python scripts/test_bot.py --token "SEU_TOKEN"
-```
-Para enviar uma mensagem de teste:
-```bash
-python scripts/send_message.py --token "SEU_TOKEN" --chat-id "CHAT_ID" --text "Hello!"
-```
----
-## Setup Com Botfather
-1. Abra o Telegram e busque @BotFather
-2. Envie `/newbot`
-3. Escolha nome de exibicao (ex: "Meu Bot Incrivel")
-4. Escolha username (deve terminar com "bot", ex: `meu_incrivel_bot`)
-5. BotFather retorna o token - guarde com seguranca
-6. Comandos uteis do BotFather:
-   - `/setdescription` - descricao do bot
-   - `/setabouttext` - texto "sobre" do bot
-   - `/setuserpic` - foto de perfil
-   - `/setcommands` - lista de comandos
-   - `/mybots` - gerenciar bots existentes
-   - `/setinline` - habilitar inline mode
-   - `/setprivacy` - modo privacidade em grupos
----
-## Variaveis De Ambiente
-```env
-TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
-```
-## Node.Js/Typescript
-```typescript
-// Instalar: npm install telegraf dotenv
-// Para TypeScript: npm install -D typescript
-import { Telegraf } from 'telegraf';
-import dotenv from 'dotenv';
-dotenv.config();
-const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);
-bot.start((ctx) => {
-  ctx.reply('Ola! Eu sou seu bot. Como posso ajudar?');
-});
-bot.on('text', (ctx) => {
-  if (!ctx.message.text.startsWith('/')) {
-    ctx.reply(`Voce disse: ${ctx.message.text}`);
-  }
-});
-bot.launch();
-```
-## Python
-```python
-## Instalar: Pip Install Python-Telegram-Bot Python-Dotenv
-import os
-from dotenv import load_dotenv
-from telegram import Update
-from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
-load_dotenv()
-async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    await update.message.reply_text('Ola! Eu sou seu bot. Como posso ajudar?')
-async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    await update.message.reply_text(f'Voce disse: {update.message.text}')
-app = Application.builder().token(os.getenv('TELEGRAM_BOT_TOKEN')).build()
-app.add_handler(CommandHandler('start', start))
-app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
-app.run_polling()
-```
-## Sem Biblioteca (Http Puro)
-```python
-import requests
-TOKEN = "SEU_TOKEN"
-BASE = f"https://api.telegram.org/bot{TOKEN}"
-## Verificar Bot
-r = requests.get(f"{BASE}/getMe")
-print(r.json())
-## Enviar Mensagem
-r = requests.post(f"{BASE}/sendMessage", json={
-    "chat_id": "CHAT_ID",
-    "text": "Hello from pure HTTP!",
-    "parse_mode": "HTML"
-})
-print(r.json())
-```
----
-## Tipos De Mensagem
-O Telegram suporta diversos tipos de conteudo. Todos os metodos aceitam `chat_id`, `reply_parameters` (para responder), `reply_markup` (para keyboards), `disable_notification` e `protect_content`.
-## Html (Recomendado)
-await bot.send_message(
-    chat_id=chat_id,
-    text="<b>Negrito</b>, <i>italico</i>, <code>codigo</code>, <a href='https://example.com'>link</a>",
-    parse_mode="HTML"
-)
-## Markdownv2 (Escapar Caracteres Especiais: _ * [ ] ( ) ~ ` > # + - = | { } . !)
-await bot.send_message(
-    chat_id=chat_id,
-    text="*Negrito*, _italico_, `codigo`, [link](https://example\\.com)",
-    parse_mode="MarkdownV2"
-)
-```
-## Foto (Por Url, File_Id Ou Upload)
-await bot.send_photo(chat_id, photo="https://example.com/img.jpg", caption="Legenda aqui")
-## Documento
-await bot.send_document(chat_id, document=open("relatorio.pdf", "rb"), caption="Relatorio mensal")
-## Video
-await bot.send_video(chat_id, video="https://example.com/video.mp4", caption="Assista!")
-## Audio
-await bot.send_audio(chat_id, audio=open("musica.mp3", "rb"), title="Minha Musica")
-## Voz (Ogg Com Opus)
-await bot.send_voice(chat_id, voice=open("audio.ogg", "rb"))
-## Localizacao
-await bot.send_location(chat_id, latitude=-23.5505, longitude=-46.6333)
-## Contato
-await bot.send_contact(chat_id, phone_number="+5511999999999", first_name="Joao")
-## Enquete
-await bot.send_poll(
-    chat_id, question="Qual sua cor favorita?",
-    options=["Azul", "Verde", "Vermelho"],
-    is_anonymous=False
-)
-## Grupo De Midias
-await bot.send_media_group(chat_id, media=[
-    InputMediaPhoto("url1", caption="Foto 1"),
-    InputMediaPhoto("url2"),
-    InputMediaVideo("url3")
-])
-## Acao De Chat (Typing, Upload_Photo, Etc.)
-await bot.send_chat_action(chat_id, action="typing")
-```
-## Node.Js Equivalente
-```typescript
-// Foto
-bot.sendPhoto(chatId, 'https://example.com/img.jpg', { caption: 'Legenda' });
-// Documento
-bot.sendDocument(chatId, fs.createReadStream('relatorio.pdf'), { caption: 'Relatorio' });
-// Localizacao
-bot.sendLocation(chatId, -23.5505, -46.6333);
-// Enquete
-bot.sendPoll(chatId, 'Qual sua cor favorita?', ['Azul', 'Verde', 'Vermelho']);
-```
----
-## Inline Keyboard (Botoes Dentro Da Mensagem)
-```python
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup
-keyboard = InlineKeyboardMarkup([
-    [InlineKeyboardButton("Opcao A", callback_data="opt_a"),
-     InlineKeyboardButton("Opcao B", callback_data="opt_b")],
-    [InlineKeyboardButton("Abrir Site", url="https://example.com")],
-    [InlineKeyboardButton("Compartilhar", switch_inline_query="texto")]
-])
-await bot.send_message(chat_id, "Escolha uma opcao:", reply_markup=keyboard)
-## Handler De Callback
-async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    query = update.callback_query
-    await query.answer()  # Importante: sempre responder o callback
-    await query.edit_message_text(f"Voce escolheu: {query.data}")
-app.add_handler(CallbackQueryHandler(button_callback))
-```
-## Reply Keyboard (Teclado Customizado)
-```python
-from telegram import ReplyKeyboardMarkup, KeyboardButton
-keyboard = ReplyKeyboardMarkup(
-    [[KeyboardButton("Enviar Localizacao", request_location=True)],
-     [KeyboardButton("Enviar Contato", request_contact=True)],
-     ["Opcao 1", "Opcao 2"]],
-    resize_keyboard=True,
-    one_time_keyboard=True
-)
-await bot.send_message(chat_id, "Escolha:", reply_markup=keyboard)
-```
-## Remover Teclado
-```python
-from telegram import ReplyKeyboardRemove
-await bot.send_message(chat_id, "Teclado removido", reply_markup=ReplyKeyboardRemove())
-```
----
-## Receber Updates
-Existem duas formas de receber updates: **Long Polling** e **Webhooks**.
-## Long Polling (Desenvolvimento)
-Mais simples, ideal para desenvolvimento. O bot faz requisicoes periodicas ao servidor do Telegram.
-```python
-## Python-Telegram-Bot Ja Faz Isso Automaticamente
-app.run_polling(allowed_updates=Update.ALL_TYPES)
-```
-```typescript
-// Telegraf com polling
-const bot = new Telegraf(token);
-bot.launch();
-```
-## Webhooks (Producao)
-Para producao, webhooks sao mais eficientes. O Telegram envia updates via POST para sua URL HTTPS.
-Leia `references/webhook-setup.md` para configuracao completa com Express, Flask, ngrok e deploy.
-Setup rapido:
-```python
-## Flask Webhook
-from flask import Flask, request
-import requests
-app = Flask(__name__)
-TOKEN = "SEU_TOKEN"
-BASE = f"https://api.telegram.org/bot{TOKEN}"
-@app.route("/webhook", methods=["POST"])
-def webhook():
-    update = request.get_json()
-    if "message" in update and "text" in update["message"]:
-        chat_id = update["message"]["chat"]["id"]
-        text = update["message"]["text"]
-        requests.post(f"{BASE}/sendMessage", json={
-            "chat_id": chat_id,
-            "text": f"Recebi: {text}"
-        })
-    return "OK", 200
-## Registrar Webhook
-requests.post(f"{BASE}/setWebhook", json={
-    "url": "https://seu-dominio.com/webhook",
-    "allowed_updates": ["message", "callback_query"],
-    "secret_token": "seu_secret_seguro_aqui"
-})
-```
----
-## Comandos Do Bot
-Registre comandos para aparecerem no menu do Telegram:
-```python
-from telegram import BotCommand
-await bot.set_my_commands([
-    BotCommand("start", "Iniciar o bot"),
-    BotCommand("help", "Ver comandos disponiveis"),
-    BotCommand("settings", "Configuracoes"),
-    BotCommand("status", "Ver status do servico"),
-])
-```
-Via HTTP:
-```bash
-curl -X POST "https://api.telegram.org/bot$TOKEN/setMyCommands" \
-  -H "Content-Type: application/json" \
-  -d '{"commands":[{"command":"start","description":"Iniciar o bot"},{"command":"help","description":"Ajuda"}]}'
-```
----
-## Automacao Com Ia
-Padrao para bot de atendimento com IA (Claude, GPT, etc.):
-```python
-from telegram import Update
-from telegram.ext import Application, MessageHandler, filters, ContextTypes
-import anthropic  # ou openai
-client = anthropic.Anthropic()
-user_conversations = {}  # chat_id -> messages history
-async def ai_response(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    chat_id = update.message.chat_id
-    user_text = update.message.text
-    # Indicar que esta digitando
-    await context.bot.send_chat_action(chat_id, "typing")
-    # Manter historico
-    if chat_id not in user_conversations:
-        user_conversations[chat_id] = []
-    user_conversations[chat_id].append({"role": "user", "content": user_text})
-    # Chamar IA
-    response = client.messages.create(
-        model="claude-sonnet-4-20250514",
-        max_tokens=1024,
-        system="Voce e um assistente prestativo. Responda em portugues.",
-        messages=user_conversations[chat_id]
-    )
-    reply = response.content[0].text
-    user_conversations[chat_id].append({"role": "assistant", "content": reply})
-    # Limitar historico (ultimas 20 mensagens)
-    if len(user_conversations[chat_id]) > 20:
-        user_conversations[chat_id] = user_conversations[chat_id][-20:]
-    await update.message.reply_text(reply)
-app = Application.builder().token(TOKEN).build()
-app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, ai_response))
-app.run_polling()
-```
----
-## Editar Texto
-await bot.edit_message_text(
-    chat_id=chat_id,
-    message_id=msg.message_id,
-    text="Texto atualizado!",
-    parse_mode="HTML"
-)
-## Editar Markup (Botoes)
-await bot.edit_message_reply_markup(
-    chat_id=chat_id,
-    message_id=msg.message_id,
-    reply_markup=new_keyboard
-)
-## Deletar Mensagem
-await bot.delete_message(chat_id=chat_id, message_id=msg.message_id)
-## Encaminhar Mensagem
-await bot.forward_message(
-    chat_id=dest_chat_id,
-    from_chat_id=source_chat_id,
-    message_id=msg.message_id
-)
-```
----
-## Tratamento De Erros
-```python
-from telegram.error import TelegramError, BadRequest, TimedOut, NetworkError
-async def safe_send(bot, chat_id, text, **kwargs):
-    """Envio com retry e tratamento de erros."""
-    max_retries = 3
-    for attempt in range(max_retries):
-        try:
-            return await bot.send_message(chat_id, text, **kwargs)
-        except TimedOut:
-            if attempt < max_retries - 1:
-                await asyncio.sleep(2 ** attempt)
-                continue
-            raise
-        except BadRequest as e:
-            if "chat not found" in str(e).lower():
-                print(f"Chat {chat_id} nao encontrado")
-                return None
-            raise
-        except NetworkError:
-            if attempt < max_retries - 1:
-                await asyncio.sleep(2 ** attempt)
-                continue
-            raise
-```
----
-## Rate Limits
-- **Mensagens em chat privado:** ~30 msg/segundo
-- **Mensagens em grupo:** ~20 msg/minuto por grupo
-- **Broadcast geral:** ~30 msg/segundo no total
-- **Bulk notifications:** use `asyncio.sleep(0.05)` entre envios para evitar flood
-Se receber erro 429 (Too Many Requests), respeite o `retry_after` retornado.
----
-## Referencia De Arquivos
-| Topico | Arquivo |
-|--------|---------|
-| Setup de webhooks | `references/webhook-setup.md` |
-| Gerenciamento de chats | `references/chat-management.md` |
-| Recursos avancados | `references/advanced-features.md` |
-| Referencia completa da API | `references/api-reference.md` |
-| Boilerplate Node.js | `assets/boilerplate/nodejs/` |
-| Boilerplate Python | `assets/boilerplate/python/` |
-| Exemplos de payloads | `assets/examples/` |
-## Best Practices
-- Provide clear, specific context about your project and requirements
-- Review all suggestions before applying them to production code
-- Combine with other complementary skills for comprehensive analysis
-## Common Pitfalls
-- Using this skill for tasks outside its domain expertise
-- Applying recommendations without understanding your specific context
-- Not providing enough project context for accurate analysis
-## Related Skills
-- `instagram` - Complementary skill for enhanced analysis
-- `social-orchestrator` - Complementary skill for enhanced analysis
-- `whatsapp-cloud-api` - Complementary skill for enhanced analysis
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.