funifier-mcp 0.1.0 → 0.2.3

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

@@ -0,0 +1,101 @@
+# Player (Jogador)
+
+**Acesso Studio:** `/studio/player`
+**API Endpoint:** `/v3/player`
+
+## O que é
+
+Cadastro e gerenciamento dos participantes da gamificação. Permite cadastrar e detalhar cada jogador, incluindo nome, login, email, equipes, amigos, foto, avatar e informações adicionais como telefone, integração com redes sociais e data de aniversário. Também é possível definir senha para cada jogador.
+
+## Quando usar
+
+- Em todo projeto de gamificação (obrigatório)
+- Para cadastrar participantes da gamificação
+- Para associar jogadores a equipes
+- Para armazenar informações extras (departamento, cargo, etc.)
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir o _id do jogador (login)
+- [ ] Definir nome do jogador
+- [ ] Definir email (se necessário para notificações)
+- [ ] Associar a equipes (se aplicável)
+- [ ] Definir campos extras no campo "extra" (departamento, cargo, etc.)
+- [ ] Definir senha (se autenticação for necessária)
+
+## API Endpoints
+
+### Listar Jogadores
+**Método:** GET
+**Endpoint:** `/v3/player`
+**Descrição:** Retorna todos os jogadores cadastrados.
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "_id": "jerry",
+    "name": "Jerry",
+    "email": "jerry@yourdomain.com",
+    "extra": { "company": "Tom & Jerry Inc." },
+    "created": 1694990893810,
+    "updated": 1694990893880
+  }
+]
+```
+
+### Criar e Atualizar Jogador
+**Método:** POST
+**Endpoint:** `/v3/player`
+**Descrição:** Cria um novo jogador com atributos personalizados ou atualiza um jogador existente.
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "jerry",
+  "name": "Jerry",
+  "email": "jerry@yourdomain.com",
+  "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" }
+  },
+  "teams": ["cartoon"],
+  "friends": ["tom", "spike"],
+  "extra": {
+    "country": "USA",
+    "company": "Tom & Jerry Inc."
+  }
+}
+```
+
+### Excluir Jogador
+**Método:** DELETE
+**Endpoint:** `/v3/player/:id`
+**Descrição:** Remove o jogador e todas as suas informações.
+
+### Consultar Status do Jogador
+**Método:** GET
+**Endpoint:** `/v3/player/:id/status`
+**Descrição:** Retorna estatísticas do jogador (pontos, nível, desafios, itens).
+
+**Exemplo de Resposta:**
+```json
+{
+  "name": "Jerry",
+  "total_challenges": 0,
+  "total_points": 0,
+  "level_progress": {
+    "percent_completed": 0,
+    "next_level": { "level": "Apprentice", "minPoints": 10 }
+  },
+  "_id": "jerry"
+}
+```
+
+## Validações e Testes
+
+- [ ] Jogador aparece na lista GET /v3/player
+- [ ] Status do jogador retorna dados corretos via GET /v3/player/:id/status
+- [ ] Campos extras estão acessíveis no objeto "extra"
+- [ ] Equipes do jogador estão corretas no array "teams"

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

@@ -0,0 +1,67 @@
+# Point (Ponto)
+
+**Acesso Studio:** `/studio/point`
+**API Endpoint:** `/v3/point`
+
+## O que é
+
+Configuração dos diferentes tipos de pontuação que os jogadores podem conquistar. Permite criar e personalizar unidades de medida de progresso, como XP, moedas virtuais, pontos de conhecimento ou métricas customizadas. Os pontos são fundamentais para recompensar ações, mensurar desempenho e alimentar outros módulos como rankings, lojas virtuais e desafios.
+
+## Quando usar
+
+- Em todo projeto de gamificação (obrigatório)
+- Para criar moedas virtuais de troca (ex: coins)
+- Para criar pontos de experiência (ex: XP)
+- Para criar métricas customizadas (ex: karma, conhecimento)
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir _id do ponto (letras minúsculas, ex: xp, coin, karma)
+- [ ] Definir category (nome amigável, ex: "Experience Points")
+- [ ] Definir shortName (abreviação, ex: "XP")
+- [ ] Configurar antes dos Challenges (Points são dependência)
+
+## API Endpoints
+
+### Listar Pontos
+**Método:** GET
+**Endpoint:** `/v3/point`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "category": "Exchangeable Coins",
+    "shortName": "Coins",
+    "extra": {},
+    "techniques": ["GT75"],
+    "_id": "coin"
+  }
+]
+```
+
+### Criar Ponto
+**Método:** POST
+**Endpoint:** `/v3/point`
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "xp",
+  "category": "Experience Points",
+  "shortName": "XP",
+  "extra": {},
+  "techniques": ["GT01"]
+}
+```
+
+### Excluir Ponto
+**Método:** DELETE
+**Endpoint:** `/v3/point/:id`
+
+## Validações e Testes
+
+- [ ] Ponto aparece na lista GET /v3/point
+- [ ] _id é único e sem caracteres especiais
+- [ ] shortName está curto e representativo
+- [ ] Ponto é criado ANTES de challenges que o referenciam

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

@@ -0,0 +1,253 @@
+# Public (Endpoints Públicos)
+
+**Acesso Studio:** `/studio/public`
+**API Endpoint:** `/v3/public`
+
+## O que é
+
+Criação e gerenciamento de endpoints públicos personalizados. Esses endpoints são ideais para integração com plataformas externas (como Circle, Zapier, Typeform), pois não exigem autenticação via token. A autenticação é feita via `apikey` incluída na URL pública no formato: `/v3/pub/{apikey}/{slug}`.
+
+## Quando usar
+
+- Para receber dados de formulários externos (Typeform, Google Forms)
+- Para integrar com automações (Zapier, Make)
+- Para criar webhooks de recebimento
+- Para endpoints que não requerem autenticação por token
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir _id (slug) do endpoint
+- [ ] Definir título e descrição
+- [ ] Definir método HTTP (GET, POST, etc.)
+- [ ] Escrever script Java com método `public Object handle(Object payload)`
+- [ ] Ativar endpoint (active: true)
+- [ ] Testar via URL pública
+
+## API Endpoints
+
+### Listar Public Endpoints
+**Método:** GET
+**Endpoint:** `/v3/database/public_endpoint`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "_id": "recebe_email",
+    "title": "Recebe Email",
+    "description": "Recebe email e registra na colecao email__c",
+    "active": true,
+    "method": "POST",
+    "script": "public Object handle(Object payload) { payload._id = payload.email; manager.getJongoConnection().getCollection(\"email__c\").save(payload); Map<String, Object> response = new HashMap<>(); response.put(\"email\", payload.email); return response; }",
+    "sample": "{ \"email\": \"user@email.com\" }",
+    "extra": {}
+  }
+]
+```
+
+### Criar Public Endpoint
+**Método:** POST
+**Endpoint:** `/v3/public`
+
+### Executar Public Endpoint
+**Método:** POST (ou conforme configurado)
+**Endpoint:** `/v3/pub/{apikey}/{slug}`
+**Descrição:** Executa o endpoint público. Não requer token de autenticação.
+
+## Script Runtime Environment (Wrapper Class)
+
+O script que você escreve no Studio **não é standalone** — ele é inserido dentro de uma classe Java wrapper gerada automaticamente pelo Funifier. Isso tem implicações importantes:
+
+### Estrutura do Wrapper
+
+```java
+// --- Imports automáticos (NÃO escreva import no seu script) ---
+import groovyx.net.http.*
+import static groovyx.net.http.Method.*
+import static groovyx.net.http.ContentType.*
+import groovy.json.*
+import groovy.transform.TimedInterrupt
+import java.util.concurrent.TimeUnit
+import java.util.Arrays
+import java.util.Scanner
+import org.apache.http.HttpResponse
+import org.apache.http.client.HttpClient
+import org.apache.http.client.methods.HttpGet
+import org.apache.http.client.methods.HttpPost
+import org.apache.http.impl.client.HttpClientBuilder
+import org.apache.commons.io.IOUtils
+import java.lang.StringBuffer
+import java.io.*
+import com.fasterxml.jackson.core.JsonProcessingException
+// Unirest (HTTP client)
+import com.mashape.unirest.http.HttpResponse
+import com.mashape.unirest.http.JsonNode
+import com.mashape.unirest.http.Unirest
+import com.mashape.unirest.http.exceptions.UnirestException
+import com.mashape.unirest.request.GetRequest
+import com.mashape.unirest.request.HttpRequestWithBody
+// Mail (Simple Java Mail)
+import org.simplejavamail.email.Email
+import org.simplejavamail.email.EmailBuilder
+import org.simplejavamail.mailer.MailerBuilder
+// Funifier entities
+import com.funifier.engine.action.*
+import com.funifier.engine.achievement.*
+import com.funifier.engine.lottery.*
+import com.funifier.engine.challenge.*
+import com.funifier.engine.constant.*
+import com.funifier.engine.guid.*
+import com.funifier.engine.level.*
+import com.funifier.engine.notify.*
+import com.funifier.engine.player.*
+import com.funifier.engine.point.*
+import com.funifier.engine.team.*
+import com.funifier.engine.catalog.*
+import com.funifier.engine.mail.*
+// Funifier utils
+import com.funifier.engine.util.DateUtil
+import com.funifier.engine.util.JsonUtil
+import com.funifier.engine.util.HttpUtil
+import com.funifier.engine.util.HttpClientFunifier
+import com.funifier.engine.util.MustacheUtils
+import com.funifier.controller.ManagerFactory
+
+@TimedInterrupt(value = 5L, unit = TimeUnit.SECONDS)
+class FunifierPublicEndpoint {
+    ManagerFactory manager = null;
+    void setManager(ManagerFactory c) { manager = c; }
+
+    // --- SEU SCRIPT É INSERIDO AQUI ---
+}
+```
+
+### Regras para escrever scripts
+
+1. **NÃO use `import`** — todos os imports necessários já estão no wrapper. Se precisar de uma classe não importada, use o nome completo (fully qualified): `com.example.MinhaClasse`
+2. **O método principal é `public Object handle(Object payload)`** — este é o entry point
+3. **`manager` está disponível** como campo da classe (ManagerFactory)
+4. **Timeout padrão de 10 segundos** — o executor limita a execução. **Pode ser customizado** via campo `timeout` (em segundos) no objeto do endpoint — ver seção "Campo timeout" abaixo. Nota: o `@TimedInterrupt(5s)` no wrapper Groovy é uma segunda camada de proteção
+5. **Groovy, não Java puro** — o script roda em Groovy, então features como GString, closures e tipagem dinâmica funcionam
+6. **Cuidado com `$` em GStrings** — operadores MongoDB (`$set`, `$inc`) e strings com `$` são interpretados como variáveis Groovy. Use `String.valueOf((char)0x24)` para escapar:
+   ```groovy
+   def d = String.valueOf((char)0x24)  // = "$"
+   def setCmd = '{"' + d + 'set": {"name": "Novo Nome"}}'
+   ```
+7. **Use apenas ASCII em comentários** — caracteres UTF-8 especiais (em dash `—`, acentos em comentários) podem causar erros de parse no Groovy
+8. **`instanceof` é bloqueado** pelo SecureASTCustomizer — use `getClass().getName()` ou try/catch
+9. **NÃO use `groovy.json.JsonSlurper`** para parsear JSON que será retornado na response — o `LazyMap` do JsonSlurper causa `ClassCastException: [B incompatible with [C` quando o Funifier tenta serializar. Use `JsonUtil.fromJsonToMap(jsonString)` em vez de `slurper.parseText(jsonString)`
+10. **Player.extra é público** — acesse direto com `player.extra`, não com `player.getExtra()` (método não existe)
+11. **Para salvar player:** `manager.getPlayerManager().findById(id)` → modifique → `manager.getPlayerManager().insert(player)` (upsert)
+
+### Campo `timeout` (Customizar timeout do script)
+
+O timeout padrão de **10 segundos** (confirmado no source: `PublicManager.java` linha 255) pode ser insuficiente para endpoints que fazem chamadas HTTP externas (ex: verificar token OAuth, chamar APIs de IA, download de imagens). O campo `timeout` permite aumentar esse limite.
+
+**Campo:** `timeout` (Long, em **segundos**)
+**Padrão:** `null` (usa 10 segundos — source: `PublicManager.java:255`)
+**Nota:** Este campo **não aparece no formulário do Studio** — só pode ser configurado via API.
+
+```bash
+# Exemplo: definir timeout de 30 segundos para o endpoint google_login
+curl -X POST "https://service2.funifier.com/v3/public" \
+  -H "Authorization: Basic <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"_id": "google_login", "timeout": 30}'
+```
+
+**Este campo também existe em Triggers e Schedulers** — mesma estrutura, mesma API (`/v3/trigger`, `/v3/scheduler`).
+
+**Mecanismo de execução (Java):**
+```java
+// O executor usa Executors.newSingleThreadExecutor() com Future.get(timeout, TimeUnit.SECONDS)
+long timeout = 10; // padrão
+if (endpoint.timeout != null && endpoint.timeout > 0) {
+    timeout = endpoint.timeout;
+}
+Object result = future.get(timeout, TimeUnit.SECONDS);
+```
+
+**Nota:** O `@TimedInterrupt(value = 5L, unit = TimeUnit.SECONDS)` no wrapper Groovy é uma segunda camada de proteção. O timeout do executor (campo `timeout`) é a camada principal e deve ser >= ao TimedInterrupt para funcionar corretamente.
+
+**Estrutura da classe PublicEndpoint (Java):**
+```java
+public class PublicEndpoint {
+    public String _id;          // slug (URL identifier)
+    public String apikey;       // gamification apikey
+    public String title;        // friendly name
+    public String description;  // internal description
+    public boolean active;      // enabled/disabled
+    public String method;       // "POST" or "GET" (default: "POST")
+    public String script;       // Groovy script body
+    public Long timeout;        // timeout in SECONDS (null = default 10s)
+    public String sample;       // example payload
+    public Date updated;        // last update timestamp
+    public Map<String, Object> extra; // extra metadata
+}
+```
+
+**Quando usar timeout customizado:**
+- Endpoints que fazem chamadas HTTP externas (OAuth, APIs externas)
+- Endpoints com BCrypt hashing (custo computacional)
+- Endpoints que fazem múltiplas operações em sequência
+- **Recomendação:** 20-30s para endpoints com chamadas externas
+
+### Atualizar Public Endpoint via API
+
+```
+POST /v3/public
+Authorization: Basic <base64(apiKey + ":")>
+Content-Type: application/json
+
+{
+    "_id": "slug_do_endpoint",
+    "title": "Titulo",
+    "description": "Descricao",
+    "active": true,
+    "method": "POST",
+    "script": "public Object handle(Object payload) { ... }",
+    "sample": "{}",
+    "extra": {}
+}
+```
+
+O mesmo endpoint serve para criar e atualizar (upsert por `_id`)
+
+### Bibliotecas HTTP disponíveis
+
+| Biblioteca | Uso recomendado |
+|-----------|----------------|
+| **Unirest** | HTTP client mais simples — `Unirest.post(url).header(...).body(...).asJson()` |
+| **Apache HttpClient** | Alternativa mais verbosa |
+| **groovyx.net.http** | HTTP Builder para Groovy |
+| **HttpUtil / HttpClientFunifier** | Utilitários Funifier |
+
+### Exemplo usando Unirest
+
+```groovy
+public Object handle(Object payload) {
+    def response = Unirest.post("https://api.external.com/endpoint")
+        .header("Content-Type", "application/json")
+        .header("Authorization", "Bearer my-token")
+        .body(JsonUtil.toJson(payload))
+        .asString()
+
+    def result = new groovy.json.JsonSlurper().parseText(response.getBody())
+    return result
+}
+```
+
+> ⚠️ **Triggers e Schedulers usam a mesma estrutura de wrapper** com os mesmos imports pré-disponíveis. A diferença é apenas o método principal: triggers usam `void trigger(event, entity, player, database)` e schedulers usam `void execute()`.
+
+## Boas Práticas
+
+- Não expor dados sensíveis em endpoints públicos
+- Não realizar operações críticas sem validação adicional
+- Validar payload recebido no script Java
+
+## Validações e Testes
+
+- [ ] Endpoint aparece na lista
+- [ ] URL pública é acessível sem token
+- [ ] Script processa payload corretamente
+- [ ] Resposta é retornada conforme esperado

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

@@ -0,0 +1,136 @@
+# Question (Pergunta)
+
+**Acesso Studio:** `/studio/question`
+**API Endpoint:** `/v3/question`
+
+## O que é
+
+Configuração de perguntas e respostas para os jogadores. Permite criar perguntas em diferentes formatos (múltipla escolha, verdadeiro/falso, com mídia), definir respostas corretas ou colher opiniões, e aplicar pesos diferentes para as perguntas. A apresentação pode ser no formato tradicional ou em mini games como caça-palavras e cruzadinhas.
+
+## Quando usar
+
+- Para criar quizzes e avaliações
+- Para pesquisas de opinião
+- Para treinamentos e capacitação
+- Para mini games educativos
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir tipo da pergunta (MULTIPLE_CHOICE, TRUE_FALSE, etc.)
+- [ ] Definir título e texto da pergunta
+- [ ] Criar opções de resposta com grades (pontuação)
+- [ ] Definir se permite uma ou múltiplas respostas (select)
+- [ ] Configurar embaralhamento (shuffle)
+- [ ] Definir peso/grade da pergunta
+
+## API Endpoints
+
+### Listar Perguntas
+**Método:** GET
+**Endpoint:** `/v3/question`
+
+### Criar Pergunta
+**Método:** POST
+**Endpoint:** `/v3/question`
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "64a5b2c2d8dcca49bcf7eb6e",
+  "type": "MULTIPLE_CHOICE",
+  "title": "Visual Components",
+  "question": "In Funifier, what is the small visual components that can be added to a web page to display feedbacks?",
+  "grade": 1,
+  "choices": [
+    { "answer": "1", "label": "Points", "grade": 0, "extra": {} },
+    { "answer": "2", "label": "Badges", "grade": 0, "extra": {} },
+    { "answer": "3", "label": "Challenges", "grade": 0, "extra": {} },
+    { "answer": "4", "label": "Leaderboards", "grade": 0, "extra": {} },
+    { "answer": "5", "label": "Widgets", "grade": 1, "extra": {} }
+  ],
+  "techniques": ["GT05"],
+  "select": "one_answer",
+  "answerNumbering": "uppercase_letters",
+  "shuffle": false,
+  "feedbacks": [],
+  "extra": {}
+}
+```
+
+### Deletar Pergunta
+**Método:** DELETE
+**Endpoint:** `/v3/question/:id`
+
+### Listar Respostas de Jogadores
+**Método:** GET
+**Endpoint:** `/v3/question/log?question=:id`
+
+### Criar Resposta de Jogador
+**Método:** POST
+**Endpoint:** `/v3/question/log`
+
+**Exemplo de Body:**
+```json
+{
+  "question": "64a5b2c2d8dcca49bcf7eb6e",
+  "answer": ["5"],
+  "player": "tom"
+}
+```
+
+### Deletar Resposta
+**Método:** DELETE
+**Endpoint:** `/v3/question/log/:id`
+
+## Tipos de Pergunta
+
+| Tipo | Descrição |
+|------|-----------|
+| `MULTIPLE_CHOICE` | Múltipla escolha (uma ou várias respostas) |
+| `TRUE_FALSE` | Verdadeiro ou Falso |
+| `ESSAY` | Dissertativa (resposta livre) |
+| `CROSSWORD` | Caça-palavras (mini game) |
+| `WORD_SEARCH` | Cruzadinha (mini game) |
+
+## Campos Importantes
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `quiz` | String | ID do quiz pai (vincula pergunta ao quiz) |
+| `type` | String | Tipo da pergunta (ver tabela acima) |
+| `question` | String | Texto da pergunta |
+| `grade` | Number | Peso/pontuação da pergunta |
+| `choices` | Array | Opções de resposta (ver estrutura abaixo) |
+| `select` | String | `one_answer` ou `multiple_answers` |
+| `shuffle` | Boolean | Embaralhar opções |
+| `techniques` | Array | IDs de técnicas de jogos vinculadas |
+
+### Estrutura de Choice (Opção de Resposta)
+
+```json
+{
+  "answer": "1",           // identificador único da opção
+  "label": "Funifier",     // texto exibido
+  "grade": 1,              // pontuação se escolhida (0 = errada)
+  "gradePercent": 100,     // percentual de acerto
+  "gradeCheck": true,      // indica se é resposta correta
+  "extra": {}              // metadados adicionais
+}
+```
+
+## Formatos de Apresentação
+
+Perguntas podem incluir conteúdo rico:
+- Texto com HTML
+- Imagens (campo `image`)
+- Vídeos e áudio (via `extra`)
+- Mini games (caça-palavras, cruzadinha)
+
+## Validações e Testes
+
+- [ ] Pergunta aparece na lista GET /v3/question
+- [ ] Resposta do jogador é registrada corretamente (POST /v3/question/log)
+- [ ] Grade é calculada com base na resposta
+- [ ] Opções de resposta estão corretas
+- [ ] Vinculação com quiz funciona (campo `quiz`)
+- [ ] Registro em lote funciona (POST /v3/question/log/bulk)