funifier-mcp 0.3.20 → 0.3.21

package/datasource-funifier-docs/knowledge/guides/server-utils.md

@@ -0,0 +1,718 @@
+# Server-side Utils — Referência
+
+## 1. Visão Geral
+
+### 1.1 O que é este documento
+
+Este documento descreve as classes utilitárias do pacote `com.funifier.engine.util` do `funifier-service` disponíveis em código server-side — triggers, schedulers e public endpoints. São classes **puramente estáticas**: todos os métodos são chamados pelo nome totalmente qualificado (ou nome curto, quando pré-importado pelo runtime) sem instanciação.
+
+### 1.2 Como referenciar no código
+
+Em triggers e schedulers, as classes do pacote `com.funifier.engine.util` são pré-importadas pelo runner. Use o **nome curto** diretamente:
+
+```groovy
+void trigger(event, entity, player, database) {
+    String json = JsonUtil.toJson(entity)         // OK — nome curto
+    boolean ok = CpfUtil.isValid(entity.cpf)      // OK — nome curto
+}
+```
+
+Se por algum motivo um nome curto não funcionar (Public Endpoint tem sandbox mais restrito), use o FQN:
+
+```groovy
+String json = com.funifier.engine.util.JsonUtil.toJson(entity)
+```
+
+> ⚠️ No **Public Endpoint**, o sandbox bloqueia `BCrypt` e `HttpUtil` com nome qualificado `com.*`. Use somente `JsonUtil` e `StringUtil` por nome curto nesse contexto. Para os demais, prefira Trigger ou Scheduler. Consulte `guides/java-libraries.md` §1.5 para a tabela completa do sandbox.
+
+### 1.3 Índice de decisão
+
+| Necessidade | Classe | Seção |
+|---|---|---|
+| Serializar/parsear JSON | `JsonUtil` | §2 |
+| Verificar string nula/vazia/em branco | `StringUtil` | §3 |
+| Validar CPF (formato String ou número) | `CpfUtil` | §4 |
+| Formatar número como moeda | `FormatterUtil` | §5 |
+| Parsear inteiros/doubles com segurança | `ParserUtil` | §6 |
+| Avaliar expressão inline `{{= ... }}` | `ExpressionUtils` | §7 |
+| Renderizar template Mustache `{{var}}` | `MustacheUtils` | §8 |
+| Comparar objetos e gerar changelog | `DiffUtil` | §9 |
+| Criptografar campo com chave simétrica (AES) | `AesCrypt` | §10 |
+| Hash/verificar senha (Blowfish) | `BCrypt` | §11 |
+| Criptografar bloco de dados com PGP/RSA | `PgpCrypt` | §12 |
+| Gerar QR code para TOTP / 2FA | `OtpAuthUtil` | §13 |
+| Fazer requisição HTTP externa (GET/POST) | `HttpUtil` | §14 |
+| Ler URL como string / limpar parâmetros Funifier | `UrlUtil` | §15 |
+| Gerar arquivo Excel (XLSX) a partir de lista | `ExcelUtil` | §16 |
+| Paginar resultado de aggregate Jongo | `PaginationUtil` | §17 |
+| Converter InputStream em arquivo temporário | `FileUtil` | §18 |
+| Datas e cálculo de períodos | `DateUtil` | §19 |
+| Internos do motor (não usar diretamente) | — | §20 |
+
+---
+
+## 2. JsonUtil
+
+**FQN:** `com.funifier.engine.util.JsonUtil`
+
+Serialização e desserialização JSON baseada em Jackson. Pré-importada pelo runner — disponível em todos os runtimes incluindo Public Endpoint.
+
+> `guides/java-libraries.md` §2 cobre os métodos básicos com mais exemplos contextuais (triggers, Public Endpoint). Este documento consolida a API completa.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `toJson(Object obj)` | `String` | Objeto → JSON indentado; campos null incluídos |
+| `toJsonRemoveNullFields(Object obj)` | `String` | Objeto → JSON sem campos null |
+| `toBsonStrictMode(Object obj)` | `String` | Objeto → BSON strict mode (null map values incluídos) |
+| `toBsonStrictModeList(List<Object> list)` | `String` | Lista → BSON strict mode |
+| `fromJson(String json, Class<T> valueType)` | `T` | JSON → objeto tipado |
+| `fromJson(String json, Class<T> valueType, boolean showError)` | `T` | JSON → objeto tipado; controla log de erros |
+| `fromJson(String json)` | `DBObject` | JSON → `DBObject` MongoDB |
+| `fromJsonToMap(String json)` | `Map<String, Object>` | JSON → Map |
+| `fromFunifierBson(String json)` | `Object` | Parseia BSON Funifier (com suporte a `$date`, `$oid`) |
+| `fromFunifierBsonWithParams(String json, HashMap<String, Object> params)` | `Object` | Parseia BSON Funifier substituindo `$param` |
+
+### Exemplos
+
+```groovy
+// Serializar entity para string
+String json = JsonUtil.toJson(entity)
+
+// Parsear JSON recebido
+Map<String, Object> data = JsonUtil.fromJsonToMap('{"name":"João","age":30}')
+
+// Converter para tipo específico
+Player p = JsonUtil.fromJson(jsonStr, Player.class)
+
+// Sem campos null (útil para salvar no banco)
+String compact = JsonUtil.toJsonRemoveNullFields(entity)
+```
+
+---
+
+## 3. StringUtil
+
+**FQN:** `com.funifier.engine.util.StringUtil`
+
+Verificações simples de string nula/vazia/em branco. Útil como guarda antes de processar campos textuais.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `isEmpty(String s)` | `boolean` | `true` se `null` ou `length < 1` |
+| `isBlank(String s)` | `boolean` | `true` se `null`, vazio ou apenas espaços |
+
+### Exemplos
+
+```groovy
+void trigger(event, entity, player, database) {
+    if (StringUtil.isBlank(entity.email)) {
+        throw new RuntimeException("E-mail obrigatório")
+    }
+}
+```
+
+---
+
+## 4. CpfUtil
+
+**FQN:** `com.funifier.engine.util.CpfUtil`
+
+Validação e conversão de CPF brasileiro. Aceita string formatada (`"123.456.789-09"`), string pura (`"12345678909"`) ou número (`Long`).
+
+> ⚠️ **CNPJ:** o método `isValidCNPJ` está comentado na fonte atual — **não disponível**. Use validação própria para CNPJ.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `isValid(Object cpf)` | `boolean` | Valida CPF (`String` ou `Number`); `false` se null |
+| `toLong(Object cpf)` | `long` | Converte CPF para `long` (remove `.` e `-`); `0L` se null |
+
+### Exemplos
+
+```groovy
+void trigger(event, entity, player, database) {
+    def cpf = entity.cpf
+    if (!CpfUtil.isValid(cpf)) {
+        throw new RuntimeException("CPF inválido: " + cpf)
+    }
+    long cpfNumerico = CpfUtil.toLong(cpf)   // 12345678909L
+    entity.cpfLong = cpfNumerico
+}
+```
+
+```groovy
+// Funciona com string formatada
+CpfUtil.isValid("695.494.861-68")   // true
+CpfUtil.toLong("695.494.861-68")    // 69549486168L
+
+// Funciona com long
+CpfUtil.isValid(69549486168L)        // true
+```
+
+---
+
+## 5. FormatterUtil
+
+**FQN:** `com.funifier.engine.util.FormatterUtil`
+
+Formatação de número como moeda com suporte a locale e padrão de formato.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `numberCurrency(Object input, String currency, String locale, String format)` | `String` | Formata `input` como moeda |
+
+- **`currency`**: código ISO 4217 — ex. `"BRL"`, `"USD"`, `"EUR"`
+- **`locale`**: código de país — ex. `"BR"`, `"US"`, `"DE"`
+- **`format`**: padrão `DecimalFormat` — ex. `"#,##0.00"` (ou `""` para usar o padrão da moeda/locale)
+
+### Exemplos
+
+```groovy
+// R$ 1.234,56
+String valor = FormatterUtil.numberCurrency(1234.56, "BRL", "BR", "#,##0.00")
+
+// $1,234.56
+String usd = FormatterUtil.numberCurrency(1234.56, "USD", "US", "#,##0.00")
+
+// Usando padrão padrão da moeda
+String padrao = FormatterUtil.numberCurrency(entity.preco, "BRL", "BR", "")
+```
+
+---
+
+## 6. ParserUtil
+
+**FQN:** `com.funifier.engine.util.ParserUtil`
+
+Conversão e arredondamento de números com proteção contra exceções.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `parseInt(String i)` | `int` | Converte string para int; retorna `0` se inválido |
+| `formatDouble(double precoDouble, String format)` | `Double` | Formata double com padrão `DecimalFormat`; retorna `null` se erro |
+| `setDoubleDecimalScale(double value, int scale)` | `double` | Arredonda para N casas decimais (HALF_UP); retorna original se erro |
+
+### Exemplos
+
+```groovy
+int qty = ParserUtil.parseInt(entity.quantity)        // "3" → 3; "abc" → 0
+
+double preco = ParserUtil.setDoubleDecimalScale(10.56789, 2)  // → 10.57
+
+Double formatted = ParserUtil.formatDouble(1234.5678, "#,##0.00")  // → 1234.57
+```
+
+---
+
+## 7. ExpressionUtils
+
+**FQN:** `com.funifier.engine.util.ExpressionUtils`
+
+Avalia blocos de expressão `{{= expr }}` em templates, com sandbox Groovy. Os blocos `{{var}}` comuns (Mustache) são deixados intactos. Útil para mensagens dinâmicas com cálculos.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `evaluateInline(String template, Map<String, Object> params, List<String> exceptions)` | `String` | Substitui cada `{{= expr }}` pelo resultado; erros vão para `exceptions` |
+
+**Funções disponíveis dentro das expressões:**
+
+| Função | Comportamento |
+|--------|--------------|
+| `round(x)` | Arredonda para inteiro mais próximo |
+| `round(x, places)` | Arredonda para N casas (HALF_UP) |
+| `ceil(x)` | Teto (inteiro) |
+| `floor(x)` | Piso (inteiro) |
+| `abs(x)` | Valor absoluto |
+| `add(a, b)` | Soma |
+| `subtract(a, b)` | Subtração |
+| `dateFormat(d, pattern)` | Formata Date com `SimpleDateFormat` |
+
+> ⚠️ O sandbox não permite `import`, acesso a `System`, `File`, etc. Apenas aritmética, comparação e as funções acima.
+
+### Exemplos
+
+```groovy
+Map params = [progress: [percent_completed: 75.6, time: [total: 10, spent: 6]]]
+List errors = []
+
+String msg = ExpressionUtils.evaluateInline(
+    "Você completou {{= round(progress.percent_completed) }}% — faltam {{= progress.time.total - progress.time.spent }} dias",
+    params,
+    errors
+)
+// → "Você completou 76% — faltam 4 dias"
+
+if (!errors.isEmpty()) {
+    println("Erros: " + errors)
+}
+```
+
+---
+
+## 8. MustacheUtils
+
+**FQN:** `com.funifier.engine.util.MustacheUtils`
+
+Renderização de templates Mustache (`{{variavel}}`). Para expressões matemáticas use `ExpressionUtils` (§7). Ambos podem ser combinados: `ExpressionUtils` processa `{{= ... }}` primeiro, depois `MustacheUtils` resolve `{{var}}`.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `parse(String template, T values)` | `String` | Renderiza template Mustache com `values` (Map ou objeto) |
+
+### Exemplos
+
+```groovy
+Map data = [name: "João", points: 150, badge: "Ouro"]
+String html = MustacheUtils.parse("Olá {{name}}, você tem {{points}} pontos e conquistou o badge {{badge}}!", data)
+// → "Olá João, você tem 150 pontos e conquistou o badge Ouro!"
+```
+
+```groovy
+// Combinando com ExpressionUtils para mensagens ricas
+String template = "Parabéns {{name}}! Você chegou a {{= round(progress) }}% da meta."
+Map params = [name: "Maria", progress: 87.3]
+List errors = []
+String result = MustacheUtils.parse(ExpressionUtils.evaluateInline(template, params, errors), params)
+// → "Parabéns Maria! Você chegou a 87% da meta."
+```
+
+---
+
+## 9. DiffUtil
+
+**FQN:** `com.funifier.engine.util.DiffUtil`
+
+Compara dois objetos (Maps, POJOs, listas) e retorna as diferenças em vários formatos. Útil para gerar changelogs de auditoria ou rastrear alterações em documentos customizados.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `diff(Object old, Object new)` | `List<Difference>` | Diferenças com config padrão |
+| `diff(Object old, Object new, Config config)` | `List<Difference>` | Diferenças com config customizada |
+| `diffAsMap(Object old, Object new, Config config)` | `Map<String, Map<String, Object>>` | `{path: {old: ..., new: ...}}` |
+| `diffAsJson(Object old, Object new, Config config)` | `String` | JSON compacto do map |
+| `diffAsJsonPretty(Object old, Object new, Config config)` | `String` | JSON indentado do map |
+| `diffAsList(Object old, Object new, Config config)` | `List<Map<String, Object>>` | `[{path:, old:, new:}]` |
+| `diffAsListJson(Object old, Object new, Config config)` | `String` | JSON compacto da lista |
+| `diffAsListJsonPretty(Object old, Object new, Config config)` | `String` | JSON indentado da lista |
+| `buildChangelogFromSequence(List<?> data)` | `List<Map<String, Object>>` | Changelog de sequência de versões |
+| `buildChangelogFromSequence(List<?> data, String sortBy)` | `List<Map<String, Object>>` | Com ordenação por campo |
+| `buildChangelogFromSequence(List<?> data, Config config)` | `List<Map<String, Object>>` | Com config |
+| `buildChangelogFromSequence(List<?> data, String sortBy, Config config)` | `List<Map<String, Object>>` | Com ordenação e config |
+
+**`Config` — construtor fluente:**
+
+```groovy
+DiffUtil.Config config = DiffUtil.Config.defaultConfig()
+    .ignoreCase(true)
+    .ignoreWhitespace(true)
+    .ignoreNulls(true)
+    .ignoreOrder(false)
+    .maxDepth(10)
+    .ignoreFields(["updatedAt", "_id"] as Set)
+    .ignoreChangesInPaths(["metadata"] as Set)
+```
+
+**`Difference` — campos:**
+- `getPath()` — caminho do campo alterado (ex. `"address.city"`, `"tags[0]"`)
+- `getOldValue()` — valor anterior
+- `getNewValue()` — valor novo
+
+### Exemplos
+
+```groovy
+void trigger(event, entity, player, database) {
+    // Recuperar versão anterior do banco
+    def oldDoc = database.get(entity._id, "order__c")
+
+    // Gerar diff entre versão antiga e nova
+    DiffUtil.Config cfg = DiffUtil.Config.defaultConfig().ignoreFields(["_id", "updatedAt"] as Set)
+    String changes = DiffUtil.diffAsJson(oldDoc, entity, cfg)
+
+    // Guardar no log de auditoria
+    def auditEntry = [orderId: entity._id, changedAt: new Date(), changes: changes]
+    database.insert(auditEntry, "order_audit__c")
+}
+```
+
+```groovy
+// Changelog de uma sequência de versões
+List versions = database.query("{}", "product_history__c")
+List changelog = DiffUtil.buildChangelogFromSequence(versions, "version")
+// Cada item: {campos do objeto + "changes": {path: {old:, new:}}}
+```
+
+---
+
+## 10. AesCrypt
+
+**FQN:** `com.funifier.engine.util.AesCrypt`
+
+Criptografia simétrica AES/ECB/PKCS5Padding. Deriva uma chave de 16 bytes via SHA-1 da senha fornecida. Útil para proteger campos sensíveis em coleções customizadas.
+
+> 🔐 **Gestão de segredos:** **nunca** hardcode a chave (`secret`) no script versionado. Guarde-a em uma coleção de configuração protegida ou injete via variável de ambiente/configuração de instância. AES/ECB não é autenticado — para alta segurança considere PGP (§12).
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `encrypt(String strToEncrypt, String secret)` | `String` | Criptografa string e retorna Base64; `null` se erro |
+| `decrypt(String strToDecrypt, String secret)` | `String` | Descriptografa Base64 e retorna string; `null` se erro |
+| `encryptFields(Object object, List<String> fields, String secret)` | `Object` | Criptografa campos específicos (dot-notation JSONPath) no objeto |
+| `decryptFields(Object object, List<String> fields, String secret)` | `Object` | Descriptografa campos específicos no objeto |
+
+### Exemplos
+
+```groovy
+// Criptografar um campo ao salvar
+void trigger(event, entity, player, database) {
+    // Ler chave de configuração (NUNCA hardcode aqui)
+    def config = database.get("enc_config", "app_config__c")
+    String secret = config.aesKey
+
+    String encrypted = AesCrypt.encrypt(entity.taxId, secret)
+    entity.taxId = encrypted
+    // entity é salvo pelo motor após o trigger
+}
+```
+
+```groovy
+// Criptografar múltiplos campos de um Map
+Map payload = [cpf: "123.456.789-09", rg: "12.345.678-9", name: "João"]
+String secret = config.secret
+Map encrypted = AesCrypt.encryptFields(payload, ["cpf", "rg"], secret)
+// encrypted.cpf e encrypted.rg são Base64; encrypted.name permanece em claro
+```
+
+---
+
+## 11. BCrypt
+
+**FQN:** `com.funifier.engine.util.BCrypt`
+
+Hash Blowfish de senhas (OpenBSD bcrypt). Padrão para senhas de players na plataforma Funifier.
+
+> 🔐 **Gestão de segredos:** `BCrypt` é para hash de senha, não para criptografia reversível. Use `AesCrypt` se precisar recuperar o valor original.
+>
+> ⚠️ `BCrypt` está bloqueado no sandbox do Public Endpoint. Use somente em Trigger ou Scheduler.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `hashpw(String password, String salt)` | `String` | Hash da senha com salt; retorna hash no formato `$2a$...` |
+| `gensalt()` | `String` | Gera salt com 10 rounds (padrão) |
+| `gensalt(int log_rounds)` | `String` | Gera salt com N rounds (`4`–`31`); cada `+1` dobra o tempo |
+| `gensalt(int log_rounds, SecureRandom random)` | `String` | Controle total de rounds e fonte aleatória |
+| `checkpw(String plaintext, String hashed)` | `boolean` | Verifica senha em claro contra hash |
+
+### Exemplos
+
+```groovy
+// Criar jogador com senha hasheada (trigger after_create)
+void trigger(event, entity, player, database) {
+    if (entity.password != null) {
+        entity.password = BCrypt.hashpw(entity.password, BCrypt.gensalt())
+    }
+}
+```
+
+```groovy
+// Verificar senha em login customizado
+boolean valid = BCrypt.checkpw(senhaInformada, hashArmazenado)
+```
+
+> Veja também `guides/java-libraries.md` §7 para mais contexto sobre uso de BCrypt com autenticação de players.
+
+---
+
+## 12. PgpCrypt
+
+**FQN:** `com.funifier.engine.util.PgpCrypt`
+
+Criptografia assimétrica PGP/RSA (BouncyCastle). Útil para criptografar dados que precisam ser descriptografados por um terceiro (ex: arquivo CSV com dados sensíveis para integração externa).
+
+> 🔐 **Gestão de chaves:** as chaves ASCII armored (privada e pública) são strings longas — **nunca** armazene a chave privada em script versionado. Guarde em coleção de configuração restrita ou em variável de ambiente da instância. A chave privada deve ser protegida por passphrase.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `encrypt(String publicKey, byte[] data)` | `byte[]` | Criptografa bytes com chave pública ASCII armored |
+| `decrypt(String secretKey, String password, byte[] pgpEncryptedData)` | `byte[]` | Descriptografa com chave secreta ASCII armored e passphrase |
+| `generateKeyPair()` | `KeyPair` | Gera par RSA 1024-bit |
+| `exportKeyPair(OutputStream secretOut, OutputStream publicOut, KeyPair pair, String identity, char[] passPhrase, boolean armor)` | `void` | Exporta par para streams (ASCII armored ou binário) |
+| `getPublicKey(String keydata)` | `PGPPublicKey` | Obtém chave pública de string ASCII armored |
+| `getSecretKey(String keydata)` | `PGPSecretKey` | Obtém chave secreta de string ASCII armored |
+| `getPrivateKey(PGPSecretKey secKey, char[] pass)` | `PGPPrivateKey` | Extrai chave privada de `PGPSecretKey` com passphrase |
+
+### Exemplos
+
+```groovy
+// Gerar e exportar par de chaves (executar uma vez, guardar as strings)
+KeyPair kp = PgpCrypt.generateKeyPair()
+ByteArrayOutputStream sec = new ByteArrayOutputStream()
+ByteArrayOutputStream pub = new ByteArrayOutputStream()
+PgpCrypt.exportKeyPair(sec, pub, kp, "admin@empresa.com", "minha-passphrase".toCharArray(), true)
+String secretKey = sec.toString()   // guardar de forma segura
+String publicKey = pub.toString()   // pode ser compartilhada
+
+// Criptografar dados para envio a integração externa
+byte[] dados = FileUtil.stream2file(inputStream, "relatorio", "csv").bytes
+byte[] encriptado = PgpCrypt.encrypt(publicKey, dados)
+
+// Descriptografar (quem tem a chave privada)
+byte[] original = PgpCrypt.decrypt(secretKey, "minha-passphrase", encriptado)
+```
+
+---
+
+## 13. OtpAuthUtil
+
+**FQN:** `com.funifier.engine.util.OtpAuthUtil`
+
+Utilitário para autenticação de dois fatores (TOTP / Google Authenticator). Na versão atual do `funifier-service`, o único método ativo é a geração de QR code.
+
+> ⚠️ **Métodos TOTP comentados:** `generateSecretKey()`, `getTOTPCode()`, `validateTOTPCode()` e `getGoogleAuthenticatorBarCode()` estão **comentados na fonte atual** e não podem ser chamados. A geração e validação de TOTP deve ser implementada pelo script do desenvolvedor ou via biblioteca externa disponível no classpath.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `createQRCode(String barCodeData, OutputStream out, int height, int width)` | `void` | Gera QR code PNG a partir de uma string (ex: URL `otpauth://totp/...`) e escreve no `out` |
+
+### Exemplos
+
+```groovy
+// Gerar QR code de uma URL TOTP (a URL deve ser construída manualmente)
+String account   = "usuario@empresa.com"
+String issuer    = "MinhaApp"
+String secretKey = "QDWSM3OYBPGTEVSPB5FKVDM3CSNCWHVK"   // base32, 20 bytes
+
+String barCodeUrl = "otpauth://totp/"
+    + java.net.URLEncoder.encode(account, "UTF-8").replace("+", "%20")
+    + "?secret=" + java.net.URLEncoder.encode(secretKey, "UTF-8").replace("+", "%20")
+    + "&issuer=" + java.net.URLEncoder.encode(issuer, "UTF-8").replace("+", "%20")
+
+ByteArrayOutputStream out = new ByteArrayOutputStream()
+OtpAuthUtil.createQRCode(barCodeUrl, out, 300, 300)
+byte[] qrPng = out.toByteArray()  // salvar ou servir via Public Endpoint
+```
+
+---
+
+## 14. HttpUtil
+
+**FQN:** `com.funifier.engine.util.HttpUtil`
+
+Requisições HTTP síncronas com Apache HttpClient (timeout 5s). Útil para chamar APIs externas a partir de triggers ou schedulers.
+
+> ⚠️ Bloqueado no sandbox do Public Endpoint. Use somente em Trigger ou Scheduler. Para o Public Endpoint, prefira `java.net.URL` (§15) ou `Unirest` (ver `guides/java-libraries.md`).
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `getClientIP(HttpServletRequest request)` | `String` | IP real do cliente (respeita cabeçalhos de proxy: `X-Forwarded-For`, etc.) |
+| `get(String strUrl, String parameters)` | `HttpResponse` | GET com query string; lança `Exception` se falhar |
+| `post(String strUrl, Object obj)` | `HttpResponse` | POST com body JSON serializado; timeout 5s |
+
+### Exemplos
+
+```groovy
+// Chamar API externa em trigger
+void trigger(event, entity, player, database) {
+    try {
+        def response = HttpUtil.get("https://api.externa.com/v1/dados", "id=" + entity._id)
+        int status = response.getStatusLine().getStatusCode()
+        if (status == 200) {
+            String body = org.apache.http.util.EntityUtils.toString(response.getEntity())
+            Map data = JsonUtil.fromJsonToMap(body)
+            entity.dadosExternos = data
+        }
+    } catch (Exception e) {
+        println("Erro HTTP: " + e.getMessage())
+    }
+}
+```
+
+```groovy
+// POST para webhook externo
+Map payload = [event: "player_registered", playerId: entity._id]
+HttpUtil.post("https://webhook.empresa.com/funifier", payload)
+```
+
+---
+
+## 15. UrlUtil
+
+**FQN:** `com.funifier.engine.util.UrlUtil`
+
+Leitura de URL e limpeza de parâmetros internos Funifier.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `readFromUrl(String url)` | `String` | Lê conteúdo da URL como string UTF-8; `null` se erro |
+| `removeFunifierParameteres(String url)` | `String` | Remove parâmetros `funifier_*` da query string; recursivo |
+
+### Exemplos
+
+```groovy
+// Ler arquivo de texto de URL pública
+String csv = UrlUtil.readFromUrl("https://storage.empresa.com/dados.csv")
+if (csv != null) {
+    // processar csv
+}
+```
+
+```groovy
+// Limpar URL de redirecionamento externo
+String url = "https://app.com/page?id=123&funifier_token=abc&other=x"
+String clean = UrlUtil.removeFunifierParameteres(url)
+// → "https://app.com/page?id=123&other=x"
+```
+
+---
+
+## 16. ExcelUtil
+
+**FQN:** `com.funifier.engine.util.ExcelUtil`
+
+Geração de arquivo XLSX (Excel) a partir de uma lista de Maps. Os cabeçalhos são extraídos das chaves do primeiro Map; as colunas são auto-dimensionadas.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `generateExcelFromObjects(List<Map<String, Object>> listRows, String sheetName)` | `byte[]` | Gera XLSX; retorna `null` se lista vazia ou erro |
+
+### Exemplos
+
+```groovy
+// Gerar Excel de relatório a partir de aggregate
+void execute() {
+    def rows = manager.getJongoConnection()
+        .getCollection("achievement")
+        .aggregate("{$match: {type: 0}}")
+        .and("{$group: {_id: '$player', total: {$sum: '$total'}}}")
+        .as(HashMap.class)
+        .toList()
+
+    List<Map<String, Object>> data = rows.collect { row ->
+        [player: row._id, pontos: row.total]
+    }
+
+    byte[] xlsx = ExcelUtil.generateExcelFromObjects(data, "Pontuação")
+
+    // Salvar o arquivo via FileUtil para servir ou enviar
+    // (ou usar FileUtil + UrlUtil se precisar enviar externamente)
+}
+```
+
+---
+
+## 17. PaginationUtil
+
+**FQN:** `com.funifier.engine.util.PaginationUtil`
+
+Paginação de results de aggregate Jongo. Usa `$facet` internamente para calcular total e página de uma só vez.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `getPageResult(Aggregate a, String range, long _skip, long _limit)` | `Map<String, Object>` | Pagina aggregate; swallows erros → retorna lista vazia |
+| `getPageResultThrowsException(Aggregate a, String range, long _skip, long _limit)` | `Map<String, Object>` | Pagina aggregate; lança exceção em erros de sintaxe |
+| `getRange(String rangeHeader, long skip, long limit)` | `long[]` | Parseia header `Range: items=skip-limit` → `[skip, limit]` |
+
+**Constantes:** `PaginationUtil.RESULT_KEY = "result"`, `COUNT_KEY = "count"`, `RANGE_KEY = "range"`
+
+**Map retornado por `getPageResult`:**
+- `"result"` → `List<Object>` com os documentos da página
+- `"count"` → total de documentos (antes da paginação)
+- `"range"` → string no formato `"items skip-limit/count"`
+
+### Exemplos
+
+```groovy
+// Paginar aggregate de players em um Public Endpoint
+def agg = manager.getJongoConnection()
+    .getCollection("player")
+    .aggregate("{$match: {active: true}}")
+
+String rangeHeader = request.getHeader("Range")   // "items=0-24"
+Map page = PaginationUtil.getPageResult(agg, rangeHeader, 0L, 25L)
+
+List players = page[PaginationUtil.RESULT_KEY]
+Object total = page[PaginationUtil.COUNT_KEY]
+```
+
+---
+
+## 18. FileUtil
+
+**FQN:** `com.funifier.engine.util.FileUtil`
+
+Conversão de `InputStream` em arquivo temporário. O arquivo é marcado como `deleteOnExit`.
+
+### Métodos públicos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `stream2file(InputStream inStream, String fileName, String extension)` | `File` | Cria arquivo temp `fileName-<uuid>.<extension>` com conteúdo do stream |
+
+### Exemplos
+
+```groovy
+// Processar CSV recebido como stream
+File tempFile = FileUtil.stream2file(csvInputStream, "import", "csv")
+String content = tempFile.text  // Groovy sugar — lê todo o arquivo
+
+// Converter para byte[] para PgpCrypt ou ExcelUtil
+byte[] bytes = tempFile.bytes
+```
+
+---
+
+## 19. DateUtil — Cross-link
+
+`DateUtil` (`com.funifier.engine.util.DateUtil`) pertence ao tema de **datas e períodos Funifier**. A API completa — `parse`, `fromKeyword`, `fromKeyword(String)`, formatação, aritmética de datas — está documentada em:
+
+- **Skill:** `funifier-date-handling` (via skill router)
+- **Guia Java:** `guides/java-libraries.md` §4
+
+**Não** duplique a API de `DateUtil` aqui. Para uso de datas em triggers, schedulers e aggregates, consulte esses documentos.
+
+---
+
+## 20. Internos do Motor — OUT
+
+As classes abaixo são usadas pelo próprio motor Funifier e **não devem ser instanciadas ou chamadas diretamente** pelo código do desenvolvedor. São listadas aqui apenas para referência — caso você as encontre em stack traces ou no classpath.
+
+| Classe | Papel no motor |
+|--------|----------------|
+| `FunifierMarshaller` | Conversão BSON ↔ objetos; usado pelo motor nas queries e aggregates |
+| `FunifierBSONCallback` | Parser BSON personalizado para o `fromFunifierBson` do `JsonUtil` |
+| `FunifierBsonWithParamsCallback` | Parser BSON com substituição de `$param` |
+| `Entity` | Superclasse de entidades do motor (PlayerStatus, etc.) |
+| `OptionModel` | Modelo de opção genérico para campos de seleção |
+| `SearchUtil` | Utilitário de busca textual interno do motor |
+| `MysqlUtil` | Acesso a MySQL em integrações legadas (não usar) |
+| `HttpClientFunifier` | Cliente HTTP interno do motor |
+| `X509Util` | Utilitário de certificado X.509 para infraestrutura TLS interna |