funifier-mcp 0.2.0 → 0.2.3

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

@@ -1,271 +1,271 @@
-# Triggers Funifier
-
-Triggers são códigos JAVA executados dentro do FUNIFIER ENGINE quando um evento específico acontece na gamificação. Oferecem flexibilidade para manipular informações em tempo real, permitindo mudar o comportamento padrão das técnicas de jogos e funcionalidades da plataforma.
-
-**Acesso Studio:** `/studio/trigger`
-**API Endpoint:** `/v3/trigger`
-
-## Configuração de uma Trigger
-
-Uma trigger é composta de três informações essenciais:
-1. **Evento** (`event`): quando a trigger deve ser executada
-2. **Entidade** (`entity`): que tipo de objeto está vinculado ao evento
-3. **Script** (`script`): código Java a ser executado
-
-```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(); }"
-}
-```
-
-## Eventos e Entidades
-
-### Eventos
-
-| Evento | Quando é acionado |
-|--------|-------------------|
-| `before_create` | Antes de criar no banco |
-| `after_create` | Depois de criar no banco |
-| `before_update` | Antes de atualizar |
-| `after_delete` | Depois de deletar |
-| `before_win` | Antes de conquistar |
-| `after_win` | Depois de conquistar |
-
-### Combinações Comuns
-
-| Evento | Entidade | Quando é acionado | Tipo do entity |
-|--------|----------|-------------------|----------------|
-| `before_create` | `player` | Antes de cadastrar jogador | Player |
-| `after_create` | `player` | Depois de cadastrar jogador | Player |
-| `before_update` | `player` | Antes de alterar jogador | Player |
-| `after_delete` | `player` | Depois de remover jogador | Player |
-| `after_create` | `challenge` | Depois de criar desafio | Challenge |
-| `after_win` | `challenge` | Depois de completar desafio | Achievement |
-| `before_create` | `action` | Antes de criar ação | Action |
-| `before_win` | `action` | Antes de registrar action log | ActionLog |
-| `after_win` | `level` | Depois de subir de nível | Achievement |
-| `after_win` | `catalog_item` | Depois de comprar item | Achievement |
-| `after_win` | `lottery` | Depois de ser sorteado | Achievement |
-| `after_win` | `mystery_box` | Depois de ganhar prêmio surpresa | Achievement |
-| `after_win` | `competition` | Depois de vencer competição | Achievement |
-| `after_create` | `question_log` | Depois de responder pergunta | QuestionLog |
-| `before_create` | `achievement` | Antes de registrar recompensa | Achievement |
-| `before_create` | `<custom>__c` | Antes de criar objeto customizado | HashMap |
-
-## Parâmetros do Script
-
-```java
-void trigger(event, entity, player, database) {
-    // event: String com o evento (ex: "before_create")
-    // entity: Objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
-    // player: String com o ID do jogador
-    // database: Objeto para acessar o banco de dados
-}
-```
-
-## Tipos de Objetos (entity)
-
-### Player
-```json
-{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}, "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}}
-```
-
-### ActionLog
-```json
-{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
-```
-
-### Achievement
-```json
-{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
-```
-Tipos: `TYPE_POINT=0`, `TYPE_CHALLENGE=1`, `TYPE_VIRTUAL_GOOD=2`, `TYPE_LEVEL=3`
-
-### Challenge
-```json
-{"challenge": "Watch Video", "active": true, "_id": "DTo8dS3", "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
-```
-
-### Action
-```json
-{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
-```
-
-## Managers Disponíveis
-
-### PlayerManager
-```java
-Player p = manager.getPlayerManager().findById("john");
-manager.getPlayerManager().insert(player);
-manager.getPlayerManager().delete("john");
-```
-
-### ActionManager
-```java
-Action a = manager.getActionManager().findActionById("sell");
-manager.getActionManager().track(actionLog);
-List<Achievement> results = manager.getActionManager().trackSynchronous(actionLog);
-```
-
-### CatalogManager
-```java
-CatalogItem item = manager.getCatalogManager().findItemById("DTj7lVn");
-manager.getCatalogManager().purchase(achievement, true);
-manager.getCatalogManager().undoPurchase("id");
-```
-
-### LotteryManager
-```java
-Lottery l = manager.getLotteryManager().find("DTj0x5z");
-manager.getLotteryManager().insertTicket(ticket);
-manager.getLotteryManager().execute("DTj0x5z");
-```
-
-### AchievementManager
-```java
-Achievement a = new Achievement();
-a.player = "john"; a.total = 10; a.type = 0; a.item = "xp";
-a.time = new Date(); a._id = Guid.newShortGuid();
-manager.getAchievementManager().addAchievement(a);
-```
-
-### Acesso ao Banco de Dados (Jongo)
-```java
-// Salvar
-manager.getJongoConnection().getCollection("email__c").save(payload);
-
-// Buscar
-Object result = manager.getJongoConnection().getCollection("player").findOne("{_id: 'john'}").as(Object.class);
-
-// Deletar
-manager.getJongoConnection().getCollection("car__c").remove("{_id: 'car001'}");
-```
-
-## Exemplos de Código
-
-### Exemplo 1: Duplicar pontos para jogadores de TI
-
-```java
-/* "event": "before_create", "entity": "achievement" */
-void trigger(event, entity, player, database) {
-    if(entity.type == Achievement.TYPE_POINT) {
-        Player currentPlayer = manager.getPlayerManager().findById(player);
-        if("IT".equals(currentPlayer.extra.department)) {
-            entity.total = entity.total * 2;
-        }
-    }
-}
-```
-
-### Exemplo 2: Dar ponto para todos os amigos
-
-```java
-/* "event": "before_create", "entity": "achievement" */
-void trigger(event, entity, player, database) {
-    if(entity.type == Achievement.TYPE_POINT && entity.total >= 100) {
-        Player p = manager.getPlayerManager().findById(player);
-        for(String friend : p.friends) {
-            Achievement a = new Achievement();
-            a.player = friend; a.total = 1; a.type = 0;
-            a.item = entity.item; a.time = new Date();
-            a._id = Guid.newShortGuid();
-            manager.getAchievementManager().addAchievement(a);
-        }
-    }
-}
-```
-
-### Exemplo 3: Enviar email de boas-vindas
-
-```java
-/* "event": "after_create", "entity": "player" */
-void trigger(event, entity, player, database) {
-    long total = manager.getPlayerManager().findTotal();
-    Email email = EmailBuilder
-        .startingBlank()
-        .from("Company", "your@company.com")
-        .to(entity.getName(), entity.email)
-        .withSubject("Welcome!")
-        .withPlainText("Welcome " + entity.name + ", you are member number " + total)
-        .buildEmail();
-    MailerBuilder.withSMTPServer("host", 587, "login", "password")
-        .buildMailer().sendMail(email);
-}
-```
-
-### Exemplo 4: Requisição HTTP com Unirest
-
-```java
-/* "event": "after_win", "entity": "catalog_item" */
-void trigger(event, entity, player, database) {
-    Player buyer = manager.getPlayerManager().findById(entity.player);
-    CatalogItem item = manager.getCatalogManager().findItemById(entity.item);
-    HashMap zap = new HashMap();
-    zap.put("purchase", entity);
-    zap.put("buyer", buyer);
-    zap.put("item", item);
-    HttpResponse<String> response = Unirest.post("https://hooks.zapier.com/hooks/catch/80/b6/")
-        .header("Content-Type", "application/json")
-        .body(JsonUtil.toJson(zap))
-        .asString();
-}
-```
-
-### Exemplo 5: Criar código de convite
-
-```java
-/* "event": "before_create", "entity": "player" */
-void trigger(event, entity, player, database) {
-    String code = Guid.shortTimeMillis();
-    entity.extra.put("code", code);
-}
-```
-
-### Exemplo 6: Consultar objeto no banco
-
-```java
-/* "event": "before_win", "entity": "action" */
-void trigger(event, entity, player, database) {
-    String id = entity.attributes.product;
-    Object product = database.getCollection("product__c").findOne("{_id:#}", id).as(Object.class);
-    entity.attributes.put("price", product.price);
-}
-```
-
-### Exemplo 7: Executar aggregate no banco
-
-```java
-/* "event": "before_win", "entity": "action" */
-void trigger(event, entity, player, database) {
-    org.jongo.MongoCollection collection = database.getCollection("achievement");
-    List<Object> highest = Arrays.asList(
-        collection.aggregate("{\"$match\": {\"type\": 0, \"item\": \"xp\"}}")
-        .and("{\"$group\": {\"_id\": \"$player\", \"total\": {\"$sum\": \"$total\"}}}")
-        .and("{\"$sort\": {\"total\": -1}}")
-        .and("{\"$limit\":1}")
-        .as(Object.class));
-    if(highest != null && highest.size() > 0) {
-        Object highestPointsPlayer = highest.get(0);
-        entity.attributes.put("highest", highestPointsPlayer.total);
-    }
-}
-```
-
-## Bibliotecas Disponíveis
-
-- **org.simplejavamail** - Envio de emails
-- **com.mashape.unirest** - Requisições HTTP
-- **org.jongo** - Acesso ao MongoDB
-- **JsonUtil** - Conversão JSON
-- **Guid** - Geração de IDs únicos
-- **DateUtil** - Cálculos e expressões de data
-
-> **Referência completa:** Para detalhes de todos os managers, entidades e bibliotecas disponíveis em Java, consulte:
-> - `guides/java-managers.md` — Todos os managers e seus métodos
-> - `guides/java-entities.md` — Entidades, campos e coleções MongoDB
-> - `guides/java-libraries.md` — JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo
+# Triggers Funifier
+
+Triggers são códigos JAVA executados dentro do FUNIFIER ENGINE quando um evento específico acontece na gamificação. Oferecem flexibilidade para manipular informações em tempo real, permitindo mudar o comportamento padrão das técnicas de jogos e funcionalidades da plataforma.
+
+**Acesso Studio:** `/studio/trigger`
+**API Endpoint:** `/v3/trigger`
+
+## Configuração de uma Trigger
+
+Uma trigger é composta de três informações essenciais:
+1. **Evento** (`event`): quando a trigger deve ser executada
+2. **Entidade** (`entity`): que tipo de objeto está vinculado ao evento
+3. **Script** (`script`): código Java a ser executado
+
+```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(); }"
+}
+```
+
+## Eventos e Entidades
+
+### Eventos
+
+| Evento | Quando é acionado |
+|--------|-------------------|
+| `before_create` | Antes de criar no banco |
+| `after_create` | Depois de criar no banco |
+| `before_update` | Antes de atualizar |
+| `after_delete` | Depois de deletar |
+| `before_win` | Antes de conquistar |
+| `after_win` | Depois de conquistar |
+
+### Combinações Comuns
+
+| Evento | Entidade | Quando é acionado | Tipo do entity |
+|--------|----------|-------------------|----------------|
+| `before_create` | `player` | Antes de cadastrar jogador | Player |
+| `after_create` | `player` | Depois de cadastrar jogador | Player |
+| `before_update` | `player` | Antes de alterar jogador | Player |
+| `after_delete` | `player` | Depois de remover jogador | Player |
+| `after_create` | `challenge` | Depois de criar desafio | Challenge |
+| `after_win` | `challenge` | Depois de completar desafio | Achievement |
+| `before_create` | `action` | Antes de criar ação | Action |
+| `before_win` | `action` | Antes de registrar action log | ActionLog |
+| `after_win` | `level` | Depois de subir de nível | Achievement |
+| `after_win` | `catalog_item` | Depois de comprar item | Achievement |
+| `after_win` | `lottery` | Depois de ser sorteado | Achievement |
+| `after_win` | `mystery_box` | Depois de ganhar prêmio surpresa | Achievement |
+| `after_win` | `competition` | Depois de vencer competição | Achievement |
+| `after_create` | `question_log` | Depois de responder pergunta | QuestionLog |
+| `before_create` | `achievement` | Antes de registrar recompensa | Achievement |
+| `before_create` | `<custom>__c` | Antes de criar objeto customizado | HashMap |
+
+## Parâmetros do Script
+
+```java
+void trigger(event, entity, player, database) {
+    // event: String com o evento (ex: "before_create")
+    // entity: Objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
+    // player: String com o ID do jogador
+    // database: Objeto para acessar o banco de dados
+}
+```
+
+## Tipos de Objetos (entity)
+
+### Player
+```json
+{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}, "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}}
+```
+
+### ActionLog
+```json
+{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
+```
+
+### Achievement
+```json
+{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
+```
+Tipos: `TYPE_POINT=0`, `TYPE_CHALLENGE=1`, `TYPE_VIRTUAL_GOOD=2`, `TYPE_LEVEL=3`
+
+### Challenge
+```json
+{"challenge": "Watch Video", "active": true, "_id": "DTo8dS3", "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+```
+
+### Action
+```json
+{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
+```
+
+## Managers Disponíveis
+
+### PlayerManager
+```java
+Player p = manager.getPlayerManager().findById("john");
+manager.getPlayerManager().insert(player);
+manager.getPlayerManager().delete("john");
+```
+
+### ActionManager
+```java
+Action a = manager.getActionManager().findActionById("sell");
+manager.getActionManager().track(actionLog);
+List<Achievement> results = manager.getActionManager().trackSynchronous(actionLog);
+```
+
+### CatalogManager
+```java
+CatalogItem item = manager.getCatalogManager().findItemById("DTj7lVn");
+manager.getCatalogManager().purchase(achievement, true);
+manager.getCatalogManager().undoPurchase("id");
+```
+
+### LotteryManager
+```java
+Lottery l = manager.getLotteryManager().find("DTj0x5z");
+manager.getLotteryManager().insertTicket(ticket);
+manager.getLotteryManager().execute("DTj0x5z");
+```
+
+### AchievementManager
+```java
+Achievement a = new Achievement();
+a.player = "john"; a.total = 10; a.type = 0; a.item = "xp";
+a.time = new Date(); a._id = Guid.newShortGuid();
+manager.getAchievementManager().addAchievement(a);
+```
+
+### Acesso ao Banco de Dados (Jongo)
+```java
+// Salvar
+manager.getJongoConnection().getCollection("email__c").save(payload);
+
+// Buscar
+Object result = manager.getJongoConnection().getCollection("player").findOne("{_id: 'john'}").as(Object.class);
+
+// Deletar
+manager.getJongoConnection().getCollection("car__c").remove("{_id: 'car001'}");
+```
+
+## Exemplos de Código
+
+### Exemplo 1: Duplicar pontos para jogadores de TI
+
+```java
+/* "event": "before_create", "entity": "achievement" */
+void trigger(event, entity, player, database) {
+    if(entity.type == Achievement.TYPE_POINT) {
+        Player currentPlayer = manager.getPlayerManager().findById(player);
+        if("IT".equals(currentPlayer.extra.department)) {
+            entity.total = entity.total * 2;
+        }
+    }
+}
+```
+
+### Exemplo 2: Dar ponto para todos os amigos
+
+```java
+/* "event": "before_create", "entity": "achievement" */
+void trigger(event, entity, player, database) {
+    if(entity.type == Achievement.TYPE_POINT && entity.total >= 100) {
+        Player p = manager.getPlayerManager().findById(player);
+        for(String friend : p.friends) {
+            Achievement a = new Achievement();
+            a.player = friend; a.total = 1; a.type = 0;
+            a.item = entity.item; a.time = new Date();
+            a._id = Guid.newShortGuid();
+            manager.getAchievementManager().addAchievement(a);
+        }
+    }
+}
+```
+
+### Exemplo 3: Enviar email de boas-vindas
+
+```java
+/* "event": "after_create", "entity": "player" */
+void trigger(event, entity, player, database) {
+    long total = manager.getPlayerManager().findTotal();
+    Email email = EmailBuilder
+        .startingBlank()
+        .from("Company", "your@company.com")
+        .to(entity.getName(), entity.email)
+        .withSubject("Welcome!")
+        .withPlainText("Welcome " + entity.name + ", you are member number " + total)
+        .buildEmail();
+    MailerBuilder.withSMTPServer("host", 587, "login", "password")
+        .buildMailer().sendMail(email);
+}
+```
+
+### Exemplo 4: Requisição HTTP com Unirest
+
+```java
+/* "event": "after_win", "entity": "catalog_item" */
+void trigger(event, entity, player, database) {
+    Player buyer = manager.getPlayerManager().findById(entity.player);
+    CatalogItem item = manager.getCatalogManager().findItemById(entity.item);
+    HashMap zap = new HashMap();
+    zap.put("purchase", entity);
+    zap.put("buyer", buyer);
+    zap.put("item", item);
+    HttpResponse<String> response = Unirest.post("https://hooks.zapier.com/hooks/catch/80/b6/")
+        .header("Content-Type", "application/json")
+        .body(JsonUtil.toJson(zap))
+        .asString();
+}
+```
+
+### Exemplo 5: Criar código de convite
+
+```java
+/* "event": "before_create", "entity": "player" */
+void trigger(event, entity, player, database) {
+    String code = Guid.shortTimeMillis();
+    entity.extra.put("code", code);
+}
+```
+
+### Exemplo 6: Consultar objeto no banco
+
+```java
+/* "event": "before_win", "entity": "action" */
+void trigger(event, entity, player, database) {
+    String id = entity.attributes.product;
+    Object product = database.getCollection("product__c").findOne("{_id:#}", id).as(Object.class);
+    entity.attributes.put("price", product.price);
+}
+```
+
+### Exemplo 7: Executar aggregate no banco
+
+```java
+/* "event": "before_win", "entity": "action" */
+void trigger(event, entity, player, database) {
+    org.jongo.MongoCollection collection = database.getCollection("achievement");
+    List<Object> highest = Arrays.asList(
+        collection.aggregate("{\"$match\": {\"type\": 0, \"item\": \"xp\"}}")
+        .and("{\"$group\": {\"_id\": \"$player\", \"total\": {\"$sum\": \"$total\"}}}")
+        .and("{\"$sort\": {\"total\": -1}}")
+        .and("{\"$limit\":1}")
+        .as(Object.class));
+    if(highest != null && highest.size() > 0) {
+        Object highestPointsPlayer = highest.get(0);
+        entity.attributes.put("highest", highestPointsPlayer.total);
+    }
+}
+```
+
+## Bibliotecas Disponíveis
+
+- **org.simplejavamail** - Envio de emails
+- **com.mashape.unirest** - Requisições HTTP
+- **org.jongo** - Acesso ao MongoDB
+- **JsonUtil** - Conversão JSON
+- **Guid** - Geração de IDs únicos
+- **DateUtil** - Cálculos e expressões de data
+
+> **Referência completa:** Para detalhes de todos os managers, entidades e bibliotecas disponíveis em Java, consulte:
+> - `guides/java-managers.md` — Todos os managers e seus métodos
+> - `guides/java-entities.md` — Entidades, campos e coleções MongoDB
+> - `guides/java-libraries.md` — JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo