funifier-mcp 0.2.0 → 0.2.4

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

@@ -1,189 +1,189 @@
-# Trigger (Trigger)
-
-**Acesso Studio:** `/studio/trigger`
-**API Endpoint:** `/v3/trigger`
-
-## O que é
-
-Execução automática de códigos JAVA quando eventos específicos acontecem na gamificação. Permite programar ações customizadas disparadas por eventos, como o cadastro de um jogador ou a realização de uma compra. As triggers dão liberdade para alterar o comportamento padrão dos módulos, integrar com sistemas externos ou implementar automações em tempo real.
-
-## Quando usar
-
-- Para enviar emails automáticos (ex: boas-vindas)
-- Para integrar com APIs externas (Zapier, CRM, etc.)
-- Para alterar pontuação com regras especiais
-- Para executar lógica de negócio personalizada
-- **Importante:** usar apenas quando as configurações padrão não atendem
-
-## Checklist de Configuração no Studio
-
-- [ ] Definir nome e descrição da trigger
-- [ ] Definir entidade observada (player, challenge, action, achievement, etc.)
-- [ ] Definir evento (before_create, after_create, before_win, after_win, etc.)
-- [ ] Escrever script Java com método `void trigger(event, entity, player, database)`
-- [ ] Testar trigger em ambiente de homologação
-
-## Eventos Disponíveis
-
-| Prefixo | Sufixo | Descrição |
-|---------|--------|-----------|
-| before_ | create | Antes de criar |
-| after_ | create | Depois de criar |
-| before_ | update | Antes de atualizar |
-| after_ | delete | Depois de deletar |
-| before_ | win | Antes de conquistar |
-| after_ | win | Depois de conquistar |
-
-## Entidades Disponíveis
-
-- `player`, `action`, `challenge`, `achievement`, `level`, `catalog_item`, `lottery`, `mystery_box`, `competition`, `question_log`, `<custom>__c`
-
-## API Endpoints
-
-### Listar Triggers
-**Método:** GET
-**Endpoint:** `/v3/trigger`
-
-### Criar Trigger
-**Método:** POST
-**Endpoint:** `/v3/trigger`
-
-**Exemplo de Body:**
-```json
-{
-  "name": "Make the player's name uppercase",
-  "_id": "DTv7uHc",
-  "description": "Before creating the player, change the letters of the name to uppercase",
-  "entity": "player",
-  "event": "before_create",
-  "script": "void trigger(event, entity, player, database){ entity.name = entity.name.toUpperCase(); }"
-}
-```
-
-### Deletar Trigger
-**Método:** DELETE
-**Endpoint:** `/v3/trigger/:id`
-
-## Script Runtime Environment (Wrapper Class)
-
-O script da trigger **não é standalone** — ele é inserido dentro de uma classe Java wrapper gerada pelo Funifier, idêntica à do Public Endpoint (ver `public.md` para a lista completa de imports).
-
-### Regras
-
-1. **NÃO use `import`** — todos os imports já estão no wrapper (Unirest, Groovy JSON, Funifier entities/utils, Apache HTTP, Simple Java Mail, etc.)
-2. Se precisar de uma classe não importada, use o nome completo: `com.example.MinhaClasse`
-3. **`manager`** (ManagerFactory) está disponível como campo da classe
-4. **Timeout padrão de 10 segundos** — pode ser customizado via campo `timeout` (em **segundos**) na API: `POST /v3/trigger` com `{"_id": "trigger_id", "timeout": 30}`. Este campo não aparece no Studio.
-5. Scripts rodam em **Groovy** — cuidado com `$` em GStrings (usar `String.valueOf((char)0x24)` para operadores MongoDB)
-6. Use apenas **ASCII em comentários** — UTF-8 especial pode causar parse errors
-
-> 📖 Ver `public.md` → **Script Runtime Environment** para a lista completa de imports e bibliotecas disponíveis.
-
-## Parâmetros do Script
-
-- `event` (String): evento acionado
-- `entity` (Object): objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
-- `player` (String): ID do jogador
-- `database` (Object): utilitário para acessar o banco de dados
-
-### ⚠️ CRITICAL: `entity` Type Depends on the Trigger Entity
-
-O tipo do parâmetro `entity` varia conforme a entidade da trigger:
-
-| Trigger Entity | Tipo de `entity` | Como acessar campos |
-|---|---|---|
-| `player` | `com.funifier.engine.player.Player` (objeto Java) | `entity.id`, `entity.name`, `entity.email`, `entity.extra` |
-| `<custom>__c` | `java.util.Map` (documento MongoDB) | `entity.get("campo")`, `entity.put("campo", valor)` |
-| `action` | `com.funifier.engine.action.ActionLog` | `entity.userId`, `entity.actionId`, `entity.attributes` |
-| `achievement` | `com.funifier.engine.achievement.Achievement` | `entity.achievementId`, `entity.userId` |
-
-**Erros comuns:**
-- ❌ `entity.get("_id")` em trigger de `player` → `MissingMethodException: No signature of method: Player.get()`
-- ✅ `entity.id` em trigger de `player`
-- ❌ `entity.id` em trigger de `signup__c` → campo não existe no Map
-- ✅ `entity.get("_id")` em trigger de `signup__c`
-
-**Player fields (via `PlayerManager.java`):**
-```
-entity.id        → String (_id do player)
-entity.name      → String
-entity.email     → String
-entity.password  → String (hash BCrypt)
-entity.extra     → Map<String, Object> (campos customizados)
-entity.image     → Image object
-entity.business  → boolean
-entity.developer → boolean
-```
-
-**Fonte:** `PlayerManager.delete()` chama `TriggerRunner.run()` com `new Object[] { event, playerObject, playerId, gameDao }` — logo `entity` é o objeto `Player` completo, não um Map.
-
-## Verificando Logs de Trigger (Studio)
-
-Para ver se uma trigger executou com sucesso ou com erro:
-
-1. Acessar **Studio** → menu lateral → **Triggers**
-2. Na lista de triggers, cada uma tem um botão **🔥 Logs** na coluna OPERAÇÕES
-3. Clicar em **Logs** abre um modal com:
-   - **Log Id**: identificador da trigger
-   - **Executou em**: data/hora da última execução
-   - **Tempo de resposta**: tempo de execução em ms
-   - **Erros**: se houve erro, mostra a exception completa em vermelho
-4. Se não houver seção "Erros", a trigger executou com sucesso
-
-**Dica:** Após alterar uma trigger via API (`POST /v3/trigger`), teste-a e verifique o log no Studio para confirmar que não há erros de compilação ou runtime.
-
-## Utilitários Disponíveis no Contexto
-
-| Classe/Método | Descrição |
-|---|---|
-| `Guid.newShortGuid()` | Gera um ID curto único (7 chars, ex: `FnwjKEY`) |
-| `Guid.newGuid()` | Gera um GUID completo |
-| `newShortGuid()` | ❌ **NÃO FUNCIONA** — precisa do prefixo `Guid.` |
-| `com.funifier.engine.util.BCrypt.hashpw(pwd, BCrypt.gensalt())` | Hash de senha BCrypt |
-| `new Date().getTime()` | Timestamp atual em milissegundos |
-| `manager` | ManagerFactory — acesso a todos os managers |
-
-> ⚠️ `System.currentTimeMillis()` é BLOQUEADO pelo SecureASTCustomizer. Usar `new Date().getTime()`.
-
-## Managers Disponíveis
-
-- `manager.getPlayerManager()` - findById, insert, delete
-- `manager.getActionManager()` - findActionById, track, trackSynchronous
-- `manager.getCatalogManager()` - findItemById, purchase, undoPurchase
-- `manager.getLotteryManager()` - find, insertTicket, execute
-- `manager.getAchievementManager()` - addAchievement
-- `manager.getJongoConnection()` - acesso direto ao MongoDB
-
-## Envio de Email
-
-As triggers podem enviar emails usando o servidor SMTP configurado na gamificação. As classes do Simple Java Mail e utilitários Funifier já estão disponíveis no contexto (não precisa importar).
-
-### Classes disponíveis
-- `EmailBuilder` / `MailerBuilder` — Simple Java Mail (construir e enviar)
-- `com.funifier.engine.mail.MailContext` — config SMTP da gamificação
-- `com.funifier.controller.Configuration` — acesso à configuração atual
-- `com.funifier.engine.util.MustacheUtils` — parse de templates com variáveis `{{campo}}`
-
-### Exemplo básico
-```java
-Email email = EmailBuilder.startingBlank()
-    .from("App", "noreply@funifier.com")
-    .to(nome, emailDestinatario)
-    .withSubject("Assunto")
-    .withHTMLText("<h1>Olá</h1>")
-    .buildEmail();
-
-com.funifier.engine.mail.MailContext ctx = com.funifier.controller.Configuration.getCurrentConfiguration().getMailContext();
-MailerBuilder.withSMTPServer(ctx.hostName, ctx.smtpPort, ctx.authUser, ctx.authPassword)
-    .buildMailer()
-    .sendMail(email);
-```
-
-> 📖 Para o pattern completo com templates editáveis e Mustache, ver `patterns.md` → **Email Template Pattern**
-
-## Validações e Testes
-
-- [ ] Trigger aparece na lista GET /v3/trigger
-- [ ] Evento é disparado corretamente
-- [ ] Script executa sem erros
-- [ ] Testar em staging antes de produção
+# Trigger (Trigger)
+
+**Acesso Studio:** `/studio/trigger`
+**API Endpoint:** `/v3/trigger`
+
+## O que é
+
+Execução automática de códigos JAVA quando eventos específicos acontecem na gamificação. Permite programar ações customizadas disparadas por eventos, como o cadastro de um jogador ou a realização de uma compra. As triggers dão liberdade para alterar o comportamento padrão dos módulos, integrar com sistemas externos ou implementar automações em tempo real.
+
+## Quando usar
+
+- Para enviar emails automáticos (ex: boas-vindas)
+- Para integrar com APIs externas (Zapier, CRM, etc.)
+- Para alterar pontuação com regras especiais
+- Para executar lógica de negócio personalizada
+- **Importante:** usar apenas quando as configurações padrão não atendem
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir nome e descrição da trigger
+- [ ] Definir entidade observada (player, challenge, action, achievement, etc.)
+- [ ] Definir evento (before_create, after_create, before_win, after_win, etc.)
+- [ ] Escrever script Java com método `void trigger(event, entity, player, database)`
+- [ ] Testar trigger em ambiente de homologação
+
+## Eventos Disponíveis
+
+| Prefixo | Sufixo | Descrição |
+|---------|--------|-----------|
+| before_ | create | Antes de criar |
+| after_ | create | Depois de criar |
+| before_ | update | Antes de atualizar |
+| after_ | delete | Depois de deletar |
+| before_ | win | Antes de conquistar |
+| after_ | win | Depois de conquistar |
+
+## Entidades Disponíveis
+
+- `player`, `action`, `challenge`, `achievement`, `level`, `catalog_item`, `lottery`, `mystery_box`, `competition`, `question_log`, `<custom>__c`
+
+## API Endpoints
+
+### Listar Triggers
+**Método:** GET
+**Endpoint:** `/v3/trigger`
+
+### Criar Trigger
+**Método:** POST
+**Endpoint:** `/v3/trigger`
+
+**Exemplo de Body:**
+```json
+{
+  "name": "Make the player's name uppercase",
+  "_id": "DTv7uHc",
+  "description": "Before creating the player, change the letters of the name to uppercase",
+  "entity": "player",
+  "event": "before_create",
+  "script": "void trigger(event, entity, player, database){ entity.name = entity.name.toUpperCase(); }"
+}
+```
+
+### Deletar Trigger
+**Método:** DELETE
+**Endpoint:** `/v3/trigger/:id`
+
+## Script Runtime Environment (Wrapper Class)
+
+O script da trigger **não é standalone** — ele é inserido dentro de uma classe Java wrapper gerada pelo Funifier, idêntica à do Public Endpoint (ver `public.md` para a lista completa de imports).
+
+### Regras
+
+1. **NÃO use `import`** — todos os imports já estão no wrapper (Unirest, Groovy JSON, Funifier entities/utils, Apache HTTP, Simple Java Mail, etc.)
+2. Se precisar de uma classe não importada, use o nome completo: `com.example.MinhaClasse`
+3. **`manager`** (ManagerFactory) está disponível como campo da classe
+4. **Timeout padrão de 10 segundos** — pode ser customizado via campo `timeout` (em **segundos**) na API: `POST /v3/trigger` com `{"_id": "trigger_id", "timeout": 30}`. Este campo não aparece no Studio.
+5. Scripts rodam em **Groovy** — cuidado com `$` em GStrings (usar `String.valueOf((char)0x24)` para operadores MongoDB)
+6. Use apenas **ASCII em comentários** — UTF-8 especial pode causar parse errors
+
+> 📖 Ver `public.md` → **Script Runtime Environment** para a lista completa de imports e bibliotecas disponíveis.
+
+## Parâmetros do Script
+
+- `event` (String): evento acionado
+- `entity` (Object): objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
+- `player` (String): ID do jogador
+- `database` (Object): utilitário para acessar o banco de dados
+
+### ⚠️ CRITICAL: `entity` Type Depends on the Trigger Entity
+
+O tipo do parâmetro `entity` varia conforme a entidade da trigger:
+
+| Trigger Entity | Tipo de `entity` | Como acessar campos |
+|---|---|---|
+| `player` | `com.funifier.engine.player.Player` (objeto Java) | `entity.id`, `entity.name`, `entity.email`, `entity.extra` |
+| `<custom>__c` | `java.util.Map` (documento MongoDB) | `entity.get("campo")`, `entity.put("campo", valor)` |
+| `action` | `com.funifier.engine.action.ActionLog` | `entity.userId`, `entity.actionId`, `entity.attributes` |
+| `achievement` | `com.funifier.engine.achievement.Achievement` | `entity.achievementId`, `entity.userId` |
+
+**Erros comuns:**
+- ❌ `entity.get("_id")` em trigger de `player` → `MissingMethodException: No signature of method: Player.get()`
+- ✅ `entity.id` em trigger de `player`
+- ❌ `entity.id` em trigger de `signup__c` → campo não existe no Map
+- ✅ `entity.get("_id")` em trigger de `signup__c`
+
+**Player fields (via `PlayerManager.java`):**
+```
+entity.id        → String (_id do player)
+entity.name      → String
+entity.email     → String
+entity.password  → String (hash BCrypt)
+entity.extra     → Map<String, Object> (campos customizados)
+entity.image     → Image object
+entity.business  → boolean
+entity.developer → boolean
+```
+
+**Fonte:** `PlayerManager.delete()` chama `TriggerRunner.run()` com `new Object[] { event, playerObject, playerId, gameDao }` — logo `entity` é o objeto `Player` completo, não um Map.
+
+## Verificando Logs de Trigger (Studio)
+
+Para ver se uma trigger executou com sucesso ou com erro:
+
+1. Acessar **Studio** → menu lateral → **Triggers**
+2. Na lista de triggers, cada uma tem um botão **🔥 Logs** na coluna OPERAÇÕES
+3. Clicar em **Logs** abre um modal com:
+   - **Log Id**: identificador da trigger
+   - **Executou em**: data/hora da última execução
+   - **Tempo de resposta**: tempo de execução em ms
+   - **Erros**: se houve erro, mostra a exception completa em vermelho
+4. Se não houver seção "Erros", a trigger executou com sucesso
+
+**Dica:** Após alterar uma trigger via API (`POST /v3/trigger`), teste-a e verifique o log no Studio para confirmar que não há erros de compilação ou runtime.
+
+## Utilitários Disponíveis no Contexto
+
+| Classe/Método | Descrição |
+|---|---|
+| `Guid.newShortGuid()` | Gera um ID curto único (7 chars, ex: `FnwjKEY`) |
+| `Guid.newGuid()` | Gera um GUID completo |
+| `newShortGuid()` | ❌ **NÃO FUNCIONA** — precisa do prefixo `Guid.` |
+| `com.funifier.engine.util.BCrypt.hashpw(pwd, BCrypt.gensalt())` | Hash de senha BCrypt |
+| `new Date().getTime()` | Timestamp atual em milissegundos |
+| `manager` | ManagerFactory — acesso a todos os managers |
+
+> ⚠️ `System.currentTimeMillis()` é BLOQUEADO pelo SecureASTCustomizer. Usar `new Date().getTime()`.
+
+## Managers Disponíveis
+
+- `manager.getPlayerManager()` - findById, insert, delete
+- `manager.getActionManager()` - findActionById, track, trackSynchronous
+- `manager.getCatalogManager()` - findItemById, purchase, undoPurchase
+- `manager.getLotteryManager()` - find, insertTicket, execute
+- `manager.getAchievementManager()` - addAchievement
+- `manager.getJongoConnection()` - acesso direto ao MongoDB
+
+## Envio de Email
+
+As triggers podem enviar emails usando o servidor SMTP configurado na gamificação. As classes do Simple Java Mail e utilitários Funifier já estão disponíveis no contexto (não precisa importar).
+
+### Classes disponíveis
+- `EmailBuilder` / `MailerBuilder` — Simple Java Mail (construir e enviar)
+- `com.funifier.engine.mail.MailContext` — config SMTP da gamificação
+- `com.funifier.controller.Configuration` — acesso à configuração atual
+- `com.funifier.engine.util.MustacheUtils` — parse de templates com variáveis `{{campo}}`
+
+### Exemplo básico
+```java
+Email email = EmailBuilder.startingBlank()
+    .from("App", "noreply@funifier.com")
+    .to(nome, emailDestinatario)
+    .withSubject("Assunto")
+    .withHTMLText("<h1>Olá</h1>")
+    .buildEmail();
+
+com.funifier.engine.mail.MailContext ctx = com.funifier.controller.Configuration.getCurrentConfiguration().getMailContext();
+MailerBuilder.withSMTPServer(ctx.hostName, ctx.smtpPort, ctx.authUser, ctx.authPassword)
+    .buildMailer()
+    .sendMail(email);
+```
+
+> 📖 Para o pattern completo com templates editáveis e Mustache, ver `patterns.md` → **Email Template Pattern**
+
+## Validações e Testes
+
+- [ ] Trigger aparece na lista GET /v3/trigger
+- [ ] Evento é disparado corretamente
+- [ ] Script executa sem erros
+- [ ] Testar em staging antes de produção