funifier-mcp 0.1.0 → 0.2.0

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

@@ -0,0 +1,132 @@
+# Swap (Troca)
+
+**Acesso Studio:** `/studio/swap`
+**API Endpoint:** `/v3/swap`
+
+## O que é
+
+Negociação e troca de objetos ou pontos entre jogadores. Permite que jogadores façam ofertas públicas de troca, negociando objetos ou pontos. Outros jogadores podem aceitar ou propor novas condições (contra propostas), incentivando a colaboração e interação.
+
+## Quando usar
+
+- Para criar mercados de troca (ex: figurinhas)
+- Para permitir negociação entre jogadores
+- Para incentivar interação social na gamificação
+
+## Dependências
+
+- **Virtual Good** e/ou **Point**: itens/pontos para troca devem existir
+- **Player**: jogadores devem estar cadastrados
+
+## Checklist de Configuração no Studio
+
+- [ ] Verificar se jogadores possuem itens/pontos para troca
+- [ ] Configurar interface de marketplace para os jogadores
+
+## API Endpoints
+
+### Listar Trocas
+**Método:** GET
+**Endpoint:** `/v3/database/swap`
+
+### Criar Troca
+**Método:** POST
+**Endpoint:** `/v3/swap`
+
+**Exemplo de Body:**
+```json
+{
+  "seller": "tom",
+  "rewards": [
+    {
+      "total": 1,
+      "type": 2,
+      "item": "DTj7lVn"
+    }
+  ],
+  "requires": [
+    {
+      "total": 2,
+      "type": 0,
+      "item": "coin"
+    }
+  ]
+}
+```
+
+### Deletar Troca
+**Método:** DELETE
+**Endpoint:** `/v3/swap/:id`
+
+### Realizar Troca (Adquirir)
+**Método:** POST
+**Endpoint:** `/v3/swap/acquire`
+
+**Exemplo de Body:**
+```json
+{
+  "buyer": "jerry",
+  "swap": "650c67f88325771ffaa78a24"
+}
+```
+
+### Receber Recompensas da Troca
+**Método:** POST
+**Endpoint:** `/v3/swap/receive`
+
+**Exemplo de Body:**
+```json
+{
+  "swap": "650c67f88325771ffaa78a24"
+}
+```
+
+### Listar Contra Propostas
+**Método:** POST
+**Endpoint:** `/v3/database/swap_counter_offer/aggregate`
+
+### Criar Contra Proposta
+**Método:** POST
+**Endpoint:** `/v3/swap/counter/offer`
+
+**Exemplo de Body:**
+```json
+{
+  "swap": "650c683c8325771ffaa78a3f",
+  "buyer": "jerry",
+  "offer": [
+    {
+      "total": 1,
+      "type": 0,
+      "item": "coin"
+    }
+  ]
+}
+```
+
+### Deletar Contra Proposta
+**Método:** DELETE
+**Endpoint:** `/v3/swap/counter/offer/:id`
+
+### Aceitar Contra Proposta
+**Método:** POST
+**Endpoint:** `/v3/swap/counter/offer/accept`
+
+**Exemplo de Body:**
+```json
+{
+  "offer": "650c69aa8325771ffaa78b1b"
+}
+```
+
+### Receber Recompensas de Contra Proposta
+**Método:** POST
+**Endpoint:** `/v3/swap/counter/offer/receive`
+
+## Validações e Testes
+
+- [ ] Troca aparece na lista de swaps
+- [ ] Comprador consegue adquirir a troca
+- [ ] Vendedor recebe recompensas após troca
+- [ ] Contra proposta é criada e listada corretamente
+- [ ] Aceitar contra proposta funciona

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

@@ -0,0 +1,75 @@
+# Team (Equipe)
+
+**Acesso Studio:** `/studio/team`
+**API Endpoint:** `/v3/team`
+
+## O que é
+
+Configuração de grupos ou equipes de jogadores. Permite criar grupos fixos (como "Equipe de Vendas") ou equipes dinâmicas, formadas automaticamente com base em critérios como aniversariantes do dia. Equipes permitem competição ou colaboração entre grupos.
+
+## Quando usar
+
+- Quando há competição ou colaboração entre grupos
+- Para organizar jogadores por departamento, região ou função
+- Para criar rankings por equipe
+- Para atribuir desafios coletivos
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir _id da equipe
+- [ ] Definir nome da equipe
+- [ ] Adicionar descrição e imagem/brasão (opcional)
+- [ ] Adicionar membros à equipe
+- [ ] Definir dono da equipe (owner)
+
+## API Endpoints
+
+### Listar Equipes
+**Método:** GET
+**Endpoint:** `/v3/team`
+
+### Criar Equipe
+**Método:** POST
+**Endpoint:** `/v3/team`
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "sales",
+  "name": "Sales",
+  "description": "Funifier sales team",
+  "image": {
+    "small": {"url": "https://my.funifier.com/images/funny.png"},
+    "medium": {"url": "https://my.funifier.com/images/funny.png"},
+    "original": {"url": "https://my.funifier.com/images/funny.png"}
+  },
+  "extra": { "country": "USA" },
+  "owner": "john"
+}
+```
+
+### Excluir Equipe
+**Método:** DELETE
+**Endpoint:** `/v3/team/:id`
+
+### Adicionar Membro
+**Método:** GET
+**Endpoint:** `/v3/team/:id/member/add/:player`
+
+### Remover Membro
+**Método:** GET
+**Endpoint:** `/v3/team/:team_id/member/remove/:player_id`
+
+### Listar IDs dos Membros
+**Método:** GET
+**Endpoint:** `/v3/team/:team_id/memberids`
+
+### Consultar Status da Equipe
+**Método:** GET
+**Endpoint:** `/v3/team/:id/status`
+
+## Validações e Testes
+
+- [ ] Equipe aparece na lista GET /v3/team
+- [ ] Membros foram adicionados corretamente
+- [ ] Status da equipe reflete pontos e desafios dos membros

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

@@ -0,0 +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

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

@@ -0,0 +1,155 @@
+# Upload (Upload)
+
+**API Endpoint:** `/v3/upload`
+
+## O que é
+
+Upload de arquivos para uso na gamificação. Permite enviar imagens, documentos e outros tipos de arquivos para utilização em avatares, desafios, recursos visuais ou qualquer outra funcionalidade.
+
+## Quando usar
+
+- Para upload de imagens de avatares
+- Para enviar documentos para treinamentos
+- Para adicionar recursos visuais a desafios e itens
+
+## API Endpoints
+
+### Upload de Imagem
+**Método:** POST
+**Endpoint:** `/v3/upload/image`
+**Content-Type:** multipart/form-data
+
+**Campos do FormData:**
+- `file`: conteúdo da imagem (ex: profile-pic.jpg)
+- `extra`: `{ "session": "images" }`
+
+**Headers:**
+- `Authorization: {token}`
+- `Content-Type: undefined` (gerenciado pelo FormData)
+
+**⚠️ O campo `extra` é obrigatório.** Sem ele, a API retorna erro `Field extra is required`.
+
+**Exemplo de Resposta:**
+```json
+{
+  "uploads": [
+    {
+      "bucket": "funifier/games/{apiKey}/images",
+      "extension": ".jpg",
+      "filename": "profile-pic.jpg",
+      "filename_unique": "{id}_original_profile-pic.jpg",
+      "size": 5559,
+      "content_type": "image/jpeg",
+      "thumb": "original",
+      "extra": { "session": "images" },
+      "_id": "6998ecbc434ba010175f4dd1",
+      "time": 1771629756465,
+      "url": "https://s3.amazonaws.com/funifier/games/{apiKey}/images/{id}_original_profile-pic.jpg"
+    }
+  ],
+  "status": "OK"
+}
+```
+
+### Exclusão de Arquivo por ID
+**Método:** DELETE
+**Endpoint:** `/v3/upload/{id}`
+
+Remove o registro do banco de dados e exclui o arquivo físico do storage (S3/Azure/Google Cloud).
+
+**Headers:**
+- `Authorization: {token}`
+
+**Resposta:** `204 No Content`
+
+**Exemplo:**
+```
+DELETE /v3/upload/6998ecbc434ba010175f4dd1
+Authorization: Bearer eyJhbGciOiJIUzUxMiIs...
+```
+
+**Observação:** A exclusão só é feita se o arquivo pertencer ao mesmo `apiKey` da autorização (verificado pela URL do arquivo).
+
+---
+
+### Exclusão de Arquivo por URL
+**Método:** DELETE
+**Endpoint:** `/v3/upload`
+**Content-Type:** application/json
+
+Remove o arquivo pelo campo `url`.
+
+**Body:**
+```json
+{ "url": "https://s3.amazonaws.com/funifier/games/{apiKey}/images/{filename}" }
+```
+
+**Resposta:** `204 No Content`
+
+---
+
+
+### Uso com Player (Avatar)
+
+Para usar a imagem como avatar do jogador, após o upload:
+
+```json
+POST /v3/player
+{
+  "_id": "player_id",
+  "image": {
+    "small": { "url": "URL_DO_UPLOAD" },
+    "medium": { "url": "URL_DO_UPLOAD" },
+    "original": { "url": "URL_DO_UPLOAD" }
+  }
+}
+```
+
+**Nota:** O campo `image` do player deve ter o formato `{ small: { url }, medium: { url }, original: { url } }`. A URL é obtida de `response.uploads[0].url`.
+
+### Upload de Arquivo Genérico
+**Método:** POST
+**Endpoint:** `/v3/upload/file`
+**Content-Type:** multipart/form-data
+
+Suporta **qualquer tipo de arquivo** (não apenas imagens). Aceita múltiplos arquivos.
+
+**Campos:**
+- `file`: arquivo binário (pode repetir para vários)
+- `extra`: string JSON obrigatória (ex: `{"session": "docs"}`)
+
+**cURL:**
+```bash
+curl -X POST "{server}/v3/upload/file" \
+  -H "Authorization: Bearer {token}" \
+  -F 'file=@./documento.pdf;type=application/pdf' \
+  -F 'extra={"session":"docs","name":"manual"}'
+```
+
+### Deletar Upload por URL
+**Método:** DELETE
+**Endpoint:** `/v3/upload/image`
+
+**Body:**
+```json
+{ "url": "https://s3.amazonaws.com/funifier/games/{APIKEY}/images/59359e..._logo.png" }
+```
+
+### Listar Uploads
+**Método:** GET
+**Endpoint:** `/v3/upload`
+
+## Triggers de Upload
+
+O upload dispara triggers `BEFORE_CREATE` e `AFTER_CREATE` na entidade `UPLOAD`. Isso permite:
+- Validar arquivos antes de salvar
+- Processar metadados após upload
+- Integrar com outros módulos
+
+## Validações e Testes
+
+- [ ] Upload de imagem retorna URL válida
+- [ ] Upload de arquivo genérico funciona
+- [ ] URL da imagem é acessível publicamente
+- [ ] Diferentes formatos são aceitos (jpg, png, pdf, etc.)
+- [ ] Delete por URL remove o arquivo

package/datasource-funifier-docs/knowledge/modules/virtual-good.md

@@ -0,0 +1,99 @@
+# Virtual Good (Loja Virtual)
+
+**Acesso Studio:** `/studio/catalog`
+**API Endpoint:** `/v3/virtualgoods`
+
+## O que é
+
+Cadastro e gestão de objetos e benefícios que podem ser adquiridos pelos jogadores. Permite cadastrar produtos físicos, virtuais ou benefícios, estipular preços, quantidades, limites de compra e atributos. Os jogadores trocam pontos ou itens por objetos na loja.
+
+## Quando usar
+
+- Para criar sistema de recompensas tangíveis
+- Para monetizar pontos/moedas virtuais
+- Para dar senso de propriedade e escolha ao jogador
+- Exemplos: camisetas, gift cards, itens virtuais, acessórios de avatar
+
+## Dependências
+
+- **Point**: moeda para compra deve existir
+
+## Checklist de Configuração no Studio
+
+- [ ] Criar catálogo (ex: "gifts", "rewards")
+- [ ] Criar itens dentro do catálogo
+- [ ] Definir preço (requires: tipo de ponto + quantidade)
+- [ ] Definir quantidade em estoque (amount, -1 = ilimitado)
+- [ ] Definir limite de compras por jogador
+- [ ] Ativar item (active: true)
+
+## API Endpoints
+
+### Listar Catálogos
+**Método:** GET
+**Endpoint:** `/v3/virtualgoods/catalog`
+
+### Criar Catálogo
+**Método:** POST
+**Endpoint:** `/v3/virtualgoods/catalog`
+
+**Exemplo de Body:**
+```json
+{
+  "catalog": "Gifts",
+  "extra": {},
+  "i18n": {},
+  "_id": "gifts"
+}
+```
+
+### Listar Itens
+**Método:** GET
+**Endpoint:** `/v3/virtualgoods/item`
+
+### Criar Item
+**Método:** POST
+**Endpoint:** `/v3/virtualgoods/item`
+
+**Exemplo de Body:**
+```json
+{
+  "catalogId": "gifts",
+  "name": "Bike",
+  "description": "Electric bike",
+  "amount": -1,
+  "active": true,
+  "extra": {},
+  "requires": [],
+  "rewards": [],
+  "notifications": [],
+  "i18n": {},
+  "techniques": ["GT08"],
+  "_id": "DTj7lVn"
+}
+```
+
+### Realizar Compra
+**Método:** POST
+**Endpoint:** `/v3/virtualgoods/purchase`
+
+**Exemplo de Body:**
+```json
+{
+  "player": "tom",
+  "item": "DTj7lVn",
+  "total": 1
+}
+```
+
+### Excluir Compra
+**Método:** DELETE
+**Endpoint:** `/v3/virtualgoods/purchase`
+
+## Validações e Testes
+
+- [ ] Catálogo e itens aparecem nas respectivas listas
+- [ ] Jogador consegue comprar item com saldo suficiente
+- [ ] Compra debita pontos corretamente
+- [ ] Estoque é decrementado (se não ilimitado)
+- [ ] Limite de compras por jogador é respeitado

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

@@ -0,0 +1,41 @@
+# WebHook (WebHook)
+
+**API Endpoint:** `/v3/webhook`
+
+## O que é
+
+Notificações automáticas para endpoints externos em tempo real. Permite que a Funifier envie notificações automáticas (payloads) para sistemas externos sempre que eventos importantes ocorrem na gamificação, sem necessidade de polling.
+
+## Quando usar
+
+- Para enviar dados para sistemas de BI quando um desafio é completado
+- Para notificar CRM quando jogador atinge uma meta
+- Para integrar com ferramentas externas (Slack, Teams, etc.)
+- Para sincronizar dados em tempo real com outros sistemas
+
+## Checklist de Configuração
+
+- [ ] Definir URL do endpoint externo
+- [ ] Definir eventos que disparam o webhook
+- [ ] Definir formato do payload
+- [ ] Testar conectividade com endpoint
+
+## API Endpoints
+
+### Listar Webhooks
+**Método:** GET
+**Endpoint:** `/v3/webhook`
+
+### Criar Webhook
+**Método:** POST
+**Endpoint:** `/v3/webhook`
+
+### Deletar Webhook
+**Método:** DELETE
+**Endpoint:** `/v3/webhook/:id`
+
+## Validações e Testes
+
+- [ ] Webhook aparece na lista
+- [ ] Payload é enviado quando evento ocorre
+- [ ] Endpoint externo recebe dados corretamente