npm package: @sitio-io/berrante
Description: Lightweight JavaScript library for sending system notifications directly to Telegram. No servers, no dashboards, just alerts.
Author: Sitio
Latest version: 0.1.0

# Berrante 🛠️ Instrumento | Telegram Telemetry

> *Lightweight JavaScript library for sending system notifications directly to Telegram. No servers, no dashboards, just alerts.*

## Quick Start

```bash
npm install @sitio-io/berrante
```

```javascript
import { berrante } from '@sitio-io/berrante';

berrante.init({
  botToken: process.env.BERRANTE_BOT_TOKEN,
  chatId: process.env.BERRANTE_CHAT_ID,
});

berrante.info('Hello from Berrante!');
```

## O que é?

Biblioteca JavaScript zero-dependency que envia notificações do seu código diretamente para um chat do Telegram via Bot API. Ideal para projetos pequenos que precisam de telemetria imediata sem infraestrutura complexa.

**Use cases:**
- Erros em workers/background jobs
- Alertas de falha em rotas críticas
- Notificações de "processo iniciou/finalizou"
- Debugging em produção (sem acesso ao terminal)

## Instalação

```bash
npm install @sitio-io/berrante
```

## Configuração

Crie seu bot no [@BotFather](https://t.me/botfather), copie o token, e descubra seu `chat_id` (envie `/start` para o bot e acesse `https://api.telegram.org/bot<TOKEN>/getUpdates`).

```javascript
import { berrante } from '@sitio-io/berrante';

berrante.init({
  botToken: process.env.BERRANTE_BOT_TOKEN,
  chatId: process.env.BERRANTE_CHAT_ID,
  project: 'minha-api', // opcional: aparece em todas mensagens
  disabled: process.env.NODE_ENV === 'test' // opcional: silencia em testes
});
```

## API

### `berrante.init(config)`
Configuração global. Chame uma vez no entrypoint da aplicação.

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `botToken` | `string` | Sim | Token do BotFather |
| `chatId` | `string` | Sim | ID do chat/grupo (ex: `-100123456` ou `123456789`) |
| `project` | `string` | Não | Prefixo nas mensagens (ex: `[minha-api]`) |
| `disabled` | `boolean` | Não | Desativa envios (default: `false`) |
| `timeout` | `number` | Não | Timeout do fetch em ms (default: 5000) |
| `debug` | `boolean` | Não | Loga no console quando enviar/receber erro (default: `false`) |

### `berrante.error(message, meta?)`
Envia notificação de erro crítico. 🔴

```javascript
berrante.error('Falha na conexão com DB', {
  error: err.message,
  stack: err.stack
});
```

### `berrante.warn(message, meta?)`
Envia alerta de atenção. 🟡

```javascript
berrante.warn('Job demorou mais que o esperado', {
  duration: 45000
});
```

### `berrante.info(message, meta?)`
Envia notificação informativa. 🔵

```javascript
berrante.info('Webhook recebido da Stripe', {
  eventId: evt.id
});
```

### `berrante.success(message, meta?)`
Envia notificação de sucesso. 🟢

```javascript
berrante.success('Deploy finalizado', {
  commit: 'a1b2c3d'
});
```

### `berrante.send(level, message, meta?)`
Método avançado para quando o nível precisa ser dinâmico.

```javascript
const level = severity > 5 ? 'error' : 'warn';
berrante.send(level, 'Anomalia detectada', { severity });
```

**Parâmetros:**
- `level`: `'error' | 'warn' | 'info' | 'success'` — define o emoji (🔴 🟡 🔵 🟢)
- `message`: `string` — texto principal (limite 4096 chars)
- `meta`: `object` — dados extras (serão formatados como `<pre>JSON</pre>` no Telegram)

### `berrante.silence()`
Desabilita envios temporariamente (útil para manutenção).

### `berrante.wake()`
Reativa os envios.

## Uso Prático

### 1. Capturando erros em Workers/Queues

```javascript
async function processPayment(job) {
  try {
    await executePayment(job.data);
    berrante.success('Pagamento processado', { id: job.id });
  } catch (error) {
    berrante.error('Falha no worker de pagamento', {
      jobId: job.id,
      error: error.message,
      attempts: job.attemptsMade
    });
    throw error; // rethrow para retry
  }
}
```

### 2. Monitorando rotas específicas (Express)

```javascript
import express from 'express';

// Middleware de erro global
app.use((err, req, res, next) => {
  berrante.error(`Erro em ${req.method} ${req.path}`, {
    error: err.message,
    user: req.user?.id,
    body: req.body
  });

  res.status(500).send('Internal Server Error');
});

// Notificação de rota crítica chamada
app.post('/webhook/payment', async (req, res) => {
  berrante.info('Webhook de pagamento recebido', {
    provider: req.body.provider,
    amount: req.body.amount
  });

  await processWebhook(req.body);
  res.json({ received: true });
});
```

### 3. Alerta de falha em cron jobs

```javascript
import cron from 'node-cron';

cron.schedule('0 9 * * *', async () => {
  try {
    await generateDailyReport();
    berrante.success('Relatório diário gerado');
  } catch (error) {
    berrante.error('Falha no job diário', { error: error.message });
  }
});
```

### 4. Com Async Context (sem poluir o código principal)

```javascript
// Em um arquivo de config
export const telemetry = berrante;

// Em qualquer lugar do código
import { telemetry } from './config';

function criticalFunction() {
  // ... lógica ...
  telemetry.info('Processo X executado');
}
```

## Tratamento de Erros

A lib **nunca lança exceções** para não quebrar sua aplicação. Se o Telegram estiver fora do ar, o erro é logado no console (stderr) mas silenciado.

Para debug, habilite modo verbose:

```javascript
berrante.init({
  botToken: 'xxx',
  chatId: 'xxx',
  debug: true // loga no console quando enviar/receber erro
});
```

## Limitações

- **Rate limit**: Respeita automaticamente 1 msg/segundo (burst) e 20 msgs/minuto (Telegram flood control). Mensagens excedentes são enfileiradas e enviadas gradualmente.
- **Tamanho**: Mensagens > 4096 caracteres são truncadas.
- **Síncrono**: Os métodos são async mas não bloqueantes (fire-and-forget). Se precisar confirmar envio: `await berrante.error(...)`.

## Do Campo
> *"O berrante serve para avisar, não para fazer barulho o dia todo."*

Use `error` para o que quebra, `warn` para o que desperta preocupação, e `info` com moderação para não silenciar o que é importante.

---
## Publicação

### npm
1. Certifique-se de estar logado: `npm login`
2. Publique: `npm publish --access public`

### GitHub Packages
Para publicar no GitHub Packages, configure o campo `publishConfig` no seu `package.json` para apontar para o seu registry do GitHub e siga as instruções da documentação do GitHub para autenticação via `~/.npmrc`.