funifier-mcp 0.3.19 → 0.3.21

package/datasource-funifier-docs/knowledge/guides/trigger-examples.md

@@ -34,7 +34,7 @@ Este documento reúne exemplos de produção de triggers Funifier — código Gr
 
 Todas herdadas de `triggers-guide.md` §1.5 — releia antes de copiar qualquer exemplo. As mais relevantes aqui:
 
-> ⚠️ **`throw` não cancela persistência** → rejeição é em `after_create` + `database.delete` (§8, e `triggers-guide.md` §8).
+> ⚠️ **`throw` só cancela em `before_*` de coleção de banco (`/v3/database/{collection}`), e apenas em instâncias atualizadas.** No restante (player, action, `after_*`, bulk) a rejeição é em `after_create` + `database.delete` (§8, e `triggers-guide.md` §8). A interrupção é **version-dependent** — confirme com a sonda de `triggers-guide.md` §8 antes de depender dela.
 > ⚠️ **Em Groovy use `.id`, não `._id`** → todos os exemplos abaixo seguem essa regra.
 > ⚠️ **Nunca `track` a mesma ação que disparou o trigger** → loop infinito; filtre por `entity.actionId` no início (§10).
 
@@ -247,13 +247,13 @@ void trigger(event, entity, player, database) {
 ## 7. `custom__c | before_create` — Normalizar Campos
 
 Quando usar: enriquecer/normalizar um documento `__c` antes de salvar.
-Não usar quando: precisa **rejeitar** o documento → §8 (`before_create` não rejeita).
+Não usar quando: precisa **rejeitar** o documento de forma portável → §8 (`after_create` + delete funciona em qualquer instância).
 Depende de: —
 Disponível em: Trigger.
 
 ### Descrição
 
-`before_create` **não rejeita** (`triggers-guide.md` §8) — apenas normaliza email/nome/ID antes de persistir. Métodos auxiliares extraídos para clareza.
+Normaliza email/nome/ID antes de persistir. Métodos auxiliares extraídos para clareza. **Nota:** em instâncias atualizadas, um `throw` aqui também **rejeita** o documento (modo estrito — `triggers-guide.md` §8, Modo A), mas isso é version-dependent; para rejeição garantida em qualquer instância, use o padrão `after_create` do §8.
 
 ### Uso
 
@@ -288,7 +288,7 @@ String extractNumeric(Object value) {
 
 ### Armadilhas conhecidas
 
-- **Esperar que `before_create` rejeite valores inválidos** → não rejeita; o documento salva. Correção: validar/rejeitar em `after_create` (§8).
+- **Contar com `throw` no `before_create` em qualquer instância** → só rejeita no modo estrito (instâncias atualizadas; `triggers-guide.md` §8). Para portabilidade, valide/rejeite em `after_create` (§8) ou confirme o suporte com a sonda de §8 antes.
 
 ---
 
@@ -301,7 +301,7 @@ Disponível em: Trigger.
 
 ### Descrição
 
-O documento já foi salvo (`triggers-guide.md` §1.5). Se inválido, deleta e devolve a mensagem no `entity`. `BusinessException` centraliza o cleanup das múltiplas validações.
+Padrão **portável** (funciona em toda instância, atualizada ou não): o documento já foi salvo (`triggers-guide.md` §1.5, Modo B). Se inválido, deleta e devolve a mensagem no `entity`. `BusinessException` centraliza o cleanup das múltiplas validações. Em instâncias atualizadas, a mesma validação pode rodar em `before_create` com `throw` (Modo A — aborta antes de salvar e não exige delete), mas o `after_create` abaixo é a escolha segura quando o suporte é desconhecido.
 
 ### Uso
 
@@ -346,7 +346,7 @@ public class BusinessException extends Exception {
 
 ### Armadilhas conhecidas
 
-- **Usar `before_create` aqui** → `throw` não impede o save (`triggers-guide.md` §8). Correção: `after_create` + delete.
+- **Usar `before_create` aqui sem confirmar suporte** → `throw` só impede o save no modo estrito (version-dependent; `triggers-guide.md` §8). Em instância antiga o documento salva. Correção: `after_create` + delete, ou sondar o suporte antes (§8 do guia).
 - **Esquecer `entity.clear()`** → o documento rejeitado mantém os dados. Correção: limpar e devolver só `message`.
 
 ---

package/datasource-funifier-docs/knowledge/guides/triggers-guide.md

@@ -13,7 +13,7 @@ Este documento descreve os conceitos de triggers Funifier — assinatura do scri
 - Consulte ao **criar uma trigger** e precisar entender `event`, `entity`, `script`.
 - Consulte ao precisar saber **quais variáveis** o script recebe (`event`, `entity`, `player`, `database`, `manager`, `context`).
 - Consulte ao escolher o **evento certo** (incl. eventos de bulk/CSV).
-- Consulte ao precisar **rejeitar uma criação** ou entender por que `throw` não cancela.
+- Consulte ao precisar **rejeitar/abortar uma operação** — incluindo o novo modo estrito (`before_*` de coleções de banco interrompem via `throw`) e por que `throw` não cancela nos demais casos.
 - Consulte ao precisar ler a **origem de uma conquista** (`context.extra`).
 
 ### 1.3 Quando NÃO consultar
@@ -33,12 +33,12 @@ Este documento descreve os conceitos de triggers Funifier — assinatura do scri
 | Escolher a entidade | Entidades disponíveis | §5 |
 | Saber o tipo do `entity` para cada combinação | Combinações Evento × Entidade | §6 |
 | Saber qual ação/conquista originou o evento | `context.extra` (cadeia de conquistas) | §7 |
-| Rejeitar uma criação inválida | Regra de persistência + BusinessException | §8 |
+| Abortar/rejeitar uma operação | Modo estrito (`before_*` de banco via `throw`) ou `after_create` + delete | §8 |
 | Processar import/insert em lote | `entity` como List (bulk) | §9 |
 
 ### 1.5 Restrições globais críticas
 
-> ⚠️ **`throw` NÃO cancela a persistência.** O Funifier persiste o documento; lançar exceção não faz rollback (`trigger-examples.md`). Consequência: tentativas de "bloquear" criação com `throw` falham silenciosamente. → `before_create` serve só para **enriquecer** (normalizar, defaults, metadados); para **rejeitar**, use `after_create` + `database.delete(...)` (§8).
+> ⚠️ **`throw` cancela a operação APENAS em `before_create`/`before_update`/`before_delete` de coleções de banco (`POST`/`PUT`/`DELETE /v3/database/{collection}`).** Nesses três eventos o `DatabaseRest` roda a trigger em **modo estrito** (`TriggerManager.executeStrict`): qualquer exceção lançada no script aborta a operação — o documento **não** é gravado/removido e a API responde **HTTP 500** com `{ "message": "<mensagem>", "statusCode": 500 }` (§8). **Em todo o resto** — player, action, swap, quiz, achievement disparados pelos managers, eventos `*_bulk`/`csv_*` (inclusive bulk insert em coleção de banco), e qualquer evento `after_*` — `throw` **NÃO** cancela: o documento persiste e a exceção só vai para o `trigger_log`. → Nesses casos, para rejeitar, use `after_create` + `database.delete(...)` (§8). ⚠️ O modo estrito é **version-dependent** — nem toda instância recebeu a atualização; **sonde antes de depender dele** (§8) ou use o `after_create` por padrão.
 
 > ⚠️ **Em Groovy, acesse o ID com `entity.id`, não `entity._id`.** Consequência: `_id` retorna `null` (`patterns.md` §10). → Use `.id` em código; `_id` só no JSON/documento. Vale para `entity`, `player`, `ActionLog`, `Achievement`.
 
@@ -168,7 +168,7 @@ Eventos definem **quando** a trigger roda. Os oficiais aparecem no dropdown do S
 
 ### Armadilhas conhecidas
 
-- **`before_create` esperando bloquear via `throw`** → não cancela (§1.5/§8).
+- **`before_create` esperando bloquear via `throw`** → só cancela em coleções de banco (`/v3/database/{collection}`); para player/action/etc. não cancela (§1.5/§8).
 - **`POST` esperando acionar `before_update`** → `POST` dispara `before_create` (§1.5).
 
 ---
@@ -277,19 +277,39 @@ Exemplo de uso em `trigger-examples.md` (Exemplo 2 — taggear conquista com ori
 
 ---
 
-## 8. Regra de Persistência e Rejeição de Criação
+## 8. Abortar uma Operação e Rejeitar Documentos
 
-Quando usar: ao precisar validar e **rejeitar** uma criação inválida.
-Não usar quando: só precisa enriquecer/normalizar → use `before_create` (mutação direta).
-Depende de: `database.delete(...)`, BusinessException (definida no próprio script).
+Quando usar: ao precisar validar e **rejeitar/abortar** uma operação.
+Não usar quando: só precisa enriquecer/normalizar → mutação direta no `before_create`.
+Depende de: modo estrito (`executeStrict` — `modules/trigger.md` §2.5.1) ou `database.delete(...)` + BusinessException.
 Disponível em: Trigger.
 
 ### Descrição
 
-O Funifier persiste o documento; `throw` não cancela (§1.5). Portanto: `before_create` enriquece; **rejeição** se faz em `after_create`, deletando o documento já salvo e devolvendo a mensagem no `entity`.
+Existem **dois modos**, e qual vale depende de **onde** a trigger roda:
+
+**Modo A — estrito (`throw` aborta).** Vale **só** para `before_create`/`before_update`/`before_delete` de **coleções de banco** acionadas pela Database API (`POST`/`PUT`/`DELETE /v3/database/{collection}`). O `DatabaseRest` roda essas triggers via `TriggerManager.executeStrict`: lançar exceção no script **aborta a operação** — o documento não é gravado/removido e a API devolve **HTTP 500** com `{ "message": "<mensagem>", "statusCode": 500 }` (corpo `CallbackMessage`). É o caminho preferido para rejeitar documentos `__c`.
+
+**Modo B — persistência garantida (`throw` não cancela).** Vale para **todo o resto**: player, action, swap, quiz, achievement disparados pelos managers; eventos `after_*`; e os eventos de lote (`*_bulk`/`csv_*`, inclusive bulk insert em coleção de banco). Aqui o Funifier persiste o documento antes de rodar a trigger e `throw` não faz rollback — a rejeição se faz em `after_create`, deletando o documento já salvo e devolvendo a mensagem no `entity`.
 
 ### Uso
 
+**Modo A — `before_create`/`before_update`/`before_delete` de coleção `__c` (Database API):**
+
+```groovy
+void trigger(event, entity, player, database) {
+    // entity é um HashMap do documento __c (em before_delete, é a lista de ids)
+    if (entity.get("email") == null) {
+        throw new RuntimeException("E-mail é obrigatório");   // aborta o POST; volta como message no 500
+    }
+    entity.put("email", entity.get("email").toString().toLowerCase());  // enriquecimento normal persiste
+}
+```
+
+> ⚠️ No modo estrito, **qualquer** exceção aborta — inclusive `TimeoutException` (estouro do `timeout`, default 5s) e erros de sandbox. Um `before_*` frágil (NPE, token bloqueado) **bloqueia todas as gravações** naquela coleção. Mantenha o script enxuto e proteja com null-checks. Apenas a **primeira** mensagem é devolvida.
+
+**Modo B — `after_create` (rejeição com cleanup), para qualquer entidade:**
+
 ```groovy
 void trigger(event, entity, player, database) {
     try {
@@ -313,10 +333,53 @@ public class BusinessException extends Exception {
 
 `BusinessException` centraliza o cleanup quando há múltiplas validações. Para uma validação simples, o `database.delete` + `entity.clear()` + `entity.put("message", ...)` direto basta.
 
+### ⚠️ Disponibilidade — recurso version-dependent
+
+O **Modo A (estrito)** depende da versão do Funifier Engine da instância: `executeStrict` foi adicionado no `DatabaseRest` em uma atualização recente e **nem toda instância já recebeu**. Em uma instância antiga, um `before_create` com `throw` numa coleção de banco **não aborta** — o documento é salvo (comporta-se como Modo B). Portanto:
+
+- **Nunca assuma** que o Modo A está disponível. Antes de entregar uma trigger que depende dele, **sonde** a instância conectada (abaixo) ou, na dúvida, use o **Modo B** (`after_create` + delete), que funciona em qualquer versão.
+- Ao gerar código para o usuário, **declare explicitamente** qual modo está usando e que o Modo A exige instância atualizada.
+
+### Como detectar suporte (sonda)
+
+Cria uma trigger descartável que sempre lança exceção, tenta um insert e observa o resultado — depois limpa tudo:
+
+```
+# 1. cria a trigger-sonda numa coleção de teste
+funifier_save type=trigger payload={
+  "name": "__probe_strict_mode__",
+  "entity": "probe_strict__c",
+  "event": "before_create",
+  "active": true,
+  "script": "void trigger(event, entity, player, database){ throw new RuntimeException(\"__STRICT_PROBE_BLOCKED__\"); }"
+}
+# guarde o _id retornado da trigger
+
+# 2. tenta inserir um documento na coleção de teste (passa por DatabaseRest.insert → executeStrict)
+funifier_database action=insert collection=probe_strict__c payload={"probe": true}
+```
+
+Interpretação:
+
+| Resultado do insert | Conclusão |
+|---|---|
+| Erro **HTTP 500** com `message` contendo `__STRICT_PROBE_BLOCKED__` | **Modo A suportado** — `throw` em `before_*` de banco interrompe. |
+| Sucesso (documento criado) | **Modo A NÃO suportado** (instância antiga) — use o Modo B. |
+
+```
+# 3. limpeza — sempre execute, qualquer que seja o resultado
+funifier_database action=delete collection=probe_strict__c filter={"probe": true}   # remove o doc, se foi salvo
+funifier_delete type=trigger id=<_id da trigger-sonda>
+```
+
+> Se a sonda não puder ser executada (sem permissão de escrita / ambiente de produção sensível), **assuma o Modo B** e avise o usuário que o Modo A não foi confirmado.
+
 ### Armadilhas conhecidas
 
-- **Usar `before_create` + `throw` para rejeitar** → o documento persiste mesmo assim. Correção: `after_create` + delete (`trigger-examples.md` Exemplo 5b).
-- **Esquecer `entity.clear()`** → o documento rejeitado retém dados (sensíveis, no caso de signup). Correção: limpar e devolver só `message`.
+- **Esperar que `throw` aborte fora do modo estrito** (player, action, eventos `after_*`, bulk) → o documento persiste mesmo assim. Correção: `after_create` + delete (`trigger-examples.md` Exemplo 5b).
+- **Assumir o Modo A sem sondar** → em instância antiga o documento é salvo apesar do `throw`, e o erro passa despercebido. Correção: sondar (acima) ou usar Modo B por padrão.
+- **`before_create` frágil em coleção de banco** → como ele agora roda em modo estrito, um erro acidental (NPE/timeout) passa a **derrubar todos os inserts** da coleção. Correção: null-check defensivo e lógica simples.
+- **Esquecer `entity.clear()`** (modo B) → o documento rejeitado retém dados (sensíveis, no caso de signup). Correção: limpar e devolver só `message`.
 
 ---
 

package/datasource-funifier-docs/knowledge/index.md

@@ -106,6 +106,7 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
 | Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
 | Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
+| Server-side Utils | `guides/server-utils.md` | Classes utilitárias do pacote `com.funifier.engine.util` | CpfUtil, AesCrypt, BCrypt, PgpCrypt, OtpAuthUtil, DiffUtil, ExpressionUtils, MustacheUtils, StringUtil, FormatterUtil, ParserUtil, HttpUtil, UrlUtil, ExcelUtil, PaginationUtil, FileUtil — use quando precisar validar CPF, criptografar campo, renderizar template, comparar objetos, gerar Excel ou fazer HTTP em código server-side |
 | Permission Audit | `guides/permission-audit.md` | Auditoria de permissões de API | Cross-check código↔Funifier: manifest de chamadas → missing scopes, excess tokens, danger findings; gramática de scope (SecurityFilter), keyword `database`, auth context, remediação |
 
 ---

package/datasource-funifier-docs/knowledge/modules/trigger.md

@@ -25,7 +25,7 @@ Quem dispara o módulo (encontrado no código — `getTriggerManager().execute(.
 - `AchievementManager.evaluateLevelUp` — `(level, before/after_win)` no instante do level up.
 - `CharacterStarManager.evaluateLevelUp` — `(character_star_stats_level, before/after_win)`.
 - `DatabaseManager.bulkInsert` — `(<collection>, before_bulk)`, `(<collection>, before_create)`, `(<collection>, after_create)` por item, `(<collection>, after_bulk)` no final.
-- `DatabaseRest.insert/update/delete` — `(<collection>, before_create|after_create|before_update|after_update|before_delete|after_delete)`.
+- `DatabaseRest.insert/update/delete` — `(<collection>, before_create|after_create|before_update|after_update|before_delete|after_delete)`. **Os três eventos `before_*` rodam em modo estrito** via `TriggerManager.executeStrict(...)` (não `execute`): se o script registrar qualquer exceção, a operação é abortada (§2.5.1).
 - `CatalogManager.purchase` / `PurchaseManager.buy` — `(catalog_item, before_purchase_validation)`, `(catalog_item, before_win)`, `(catalog_item, after_win)`.
 - `SwapManager.*` — `(swap, before/after_create|delete|win)`, `(swap, before_acquire_validation)`, `(swap_counter_offer, ...)`.
 - `MysteryBoxManager.execute` — `(mystery_box, before_win)`, `(mystery_box, before_lose)`, `(mystery_box, before_win_reward)`, `(mystery_box, after_win|after_lose)`.
@@ -169,6 +169,34 @@ flowchart LR
       Exception (catch-all)              → exceptions.add; future.cancel(true); shutdownNow
 ```
 
+### 2.5.1 `execute` vs `executeStrict` — interrupção do fluxo (modo estrito)
+
+O `TriggerRunner.run(...)` sempre **coleta** as exceções do script na lista `exceptions` do `Map` de retorno — ele nunca propaga. Quem decide o que fazer com essa lista é o método do `TriggerManager` que foi chamado:
+
+| Método | Quem chama | Comportamento com `exceptions` não-vazia |
+|---|---|---|
+| `execute(...)` | Todos os disparos (action, achievement, swap, quiz, bulk/CSV, `after_*`, etc.) | **Ignora** — apenas grava no `trigger_log` e segue o loop. A persistência **não** é afetada. |
+| `executeStrict(...)` | **Somente** `DatabaseRest.insert/update/delete` nos eventos `before_create`/`before_update`/`before_delete` | **Aborta** — relança `exceptions.get(0)` como `FunifierException` (`Response.Status.INTERNAL_SERVER_ERROR`). |
+
+`executeStrict` (em `TriggerManager`):
+
+```
+[1] Para cada trigger de (entity, event):
+[2]   result = runner.run(...)                       # mesma execução do execute()
+[3]   List exceptions = result.get("exceptions")
+[4]   Se exceptions != null && !exceptions.isEmpty():
+[5]     throw new FunifierException(exceptions.get(0), INTERNAL_SERVER_ERROR)
+```
+
+Consequências para coleções de banco (`/v3/database/{collection}`) nos eventos `before_*`:
+
+- **Qualquer** entrada em `exceptions` aborta a operação — não só um `throw` explícito do script, mas também `TimeoutException` (estouro do `timeout`, default 5s), `SecurityException` (token bloqueado pelo `SecureASTCustomizer`) e `CompilationFailedException`. Um `before_*` frágil (NPE, erro de sandbox) **bloqueia todas as gravações** naquela coleção.
+- A operação não acontece: o documento **não** é gravado (create/update) nem removido (delete).
+- A resposta HTTP é gerada pelo `FunifierExceptionMapper` → **500** com corpo `CallbackMessage`: `{ "message": "<exceptions[0]>", "statusCode": 500, "data": null }` (o mapper sempre força `INTERNAL_SERVER_ERROR`, ignorando o status passado ao `FunifierException`). Apenas a **primeira** mensagem é devolvida.
+- **Não vale para bulk:** `DatabaseManager.bulkInsert` continua usando `execute(...)` (não estrito) para `before_bulk`/`before_create` por item — inserts em lote **não** são interrompidos por `throw`.
+
+> ⚠️ **Disponibilidade version-dependent.** `executeStrict` foi adicionado ao `DatabaseRest` em uma atualização recente do Engine e **nem toda instância já recebeu**. Em uma instância antiga, `DatabaseRest` ainda chama `execute(...)` e o `before_*` não interrompe. Antes de gerar/depender de uma trigger que aborta via `throw`, confirme o suporte com a sonda de feature em `guides/triggers-guide.md` §8.
+
 ### 2.6 Sub-pipeline — `getScript(trigger)` — wrapper de imports
 
 `TriggerRunner.getScript` constrói um script que envelopa o `trigger.script` do usuário em uma classe `FunifierTrigger` Groovy com: