funifier-mcp 0.1.0 → 0.2.0

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

@@ -0,0 +1,241 @@
+# Database (Database)
+
+**API Endpoint:** `/v3/database`
+
+## O que é
+
+Acesso direto à base de dados para operações avançadas. Oferece ferramentas para criar índices, executar comandos aggregate (MongoDB), importar dados em lote, e muito mais. Permite extrair relatórios personalizados e realizar manipulações complexas diretamente no banco de dados da gamificação. Cada gamificação tem seu próprio banco de dados.
+
+## ⚠️ Requisito de Permissão Especial
+
+O endpoint `/v3/database` exige que a palavra **`database`** esteja presente no scope da Role do token, **além** das permissões padrão (`read_all`, `write_all`, `delete_all`). Sem ela:
+
+- **POST** retorna `201` mas **NÃO persiste os dados**
+- **GET** retorna `200` com **corpo vazio**
+- **Nenhuma mensagem de erro** é exibida
+
+**Scope mínimo para usar database:** `read_all, write_all, delete_all, database`
+
+Configurar em: `Studio > Security > Roles`
+
+> **Nota:** O jogador precisa fazer login novamente após alteração da Role para obter um token com as novas permissões.
+
+## Quando usar
+
+- Para consultas avançadas com aggregates MongoDB
+- Para criar/gerenciar índices de performance
+- Para operações CRUD em qualquer coleção
+- Para inserção em massa (bulk)
+- Para acessar coleções customizadas (sufixo __c)
+
+## API Endpoints
+
+### Listar Coleções
+**Método:** GET
+**Endpoint:** `/v3/database/collections`
+**Descrição:** Lista todas as coleções existentes no banco.
+
+### Buscar Registro por ID
+**Método:** GET
+**Endpoint:** `/v3/database/:collection/:id`
+**Query Params:**
+- `strict=true` — Preserva tipos BSON (datas como `{ $date }`, etc.)
+- Use `me` como ID para buscar dados do player autenticado
+
+### Listar Dados de uma Coleção (com filtro)
+**Método:** GET
+**Endpoint:** `/v3/database/:collection`
+**Query Params:**
+- `q` — Filtro MongoDB (sintaxe Mongo, NÃO JSON). Inserido dentro de `{ $match: { <q> } }`
+- `strict=true` — Preserva tipos BSON
+- `max_results` — Máximo de resultados (default: 100)
+
+**Header:**
+- `Range: items=0-19` — Paginação (Range-based)
+
+**⚠️ IMPORTANTE:** O parâmetro correto de filtro é `q`, **NÃO** `_filter`. Parâmetros como `_filter`, `_sort`, `_limit` **NÃO existem** neste endpoint e são silenciosamente ignorados.
+
+**Exemplos de `q`:**
+```
+?q=userId:"ricardo@funifier.com"
+?q=userId:"ricardo@funifier.com", type:"daily"
+?q=status:"active", price:{$gte:100}
+?q=_id:"abc123"
+```
+
+**⚠️ Limitação:** O `GET` não suporta `$sort`. Internamente ele executa `{ $match: { <q> } }` via aggregate, sem estágios adicionais. Para queries com ordenação, use o endpoint `aggregate`.
+
+### Contar Registros
+**Método:** GET
+**Endpoint:** `/v3/database/count?collection=:collection&q=:query`
+**Descrição:** Retorna `{ total: N }`.
+
+### Criar Registro (Upsert)
+**Método:** POST
+**Endpoint:** `/v3/database/:collection`
+**Query Params:**
+- `strict=true` — Para preservar tipos BSON na resposta
+
+**Descrição:** Se `_id` não for fornecido, gera automaticamente um GUID curto. Executa triggers `before_create` e `after_create`.
+
+**Exemplo de Body:**
+```json
+{
+  "year": 2010,
+  "fuel": "gasoline",
+  "price": 50000,
+  "name": "Civic",
+  "description": "Honda Civic",
+  "brand": "honda"
+}
+```
+
+### Atualizar Registro (Save/Upsert)
+**Método:** PUT
+**Endpoint:** `/v3/database/:collection`
+**Query Params:**
+- `strict=true` — Para preservar tipos BSON
+
+**Descrição:** Usa `save()` do MongoDB (upsert por `_id`). Executa triggers `before_update` e `after_update`. Se `_id` não existir, gera um novo.
+
+**⚠️ Player password safety:** Se a coleção for `player` e o token não tem permissão de ler senha, o PUT automaticamente preserva a senha existente (não sobrescreve com null).
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "6553e49815865a7a732f5fc7",
+  "year": 2010,
+  "fuel": "gasoline",
+  "price": 50000,
+  "name": "Civic",
+  "description": "Honda Civic",
+  "brand": "honda"
+}
+```
+
+### Excluir Registro(s)
+**Método:** DELETE
+**Endpoint:** `/v3/database/:collection?q=:query`
+
+**Descrição:** O `q` precisa ter pelo menos 3 caracteres. Executa triggers `before_delete` e `after_delete` se total ≤ 20.000 registros. IDs são identificados antes da exclusão para passar aos triggers.
+
+**Exemplos:**
+```
+DELETE /v3/database/checkin__c?q=_id:"abc123"
+DELETE /v3/database/signup__c?q=userId:"test@test.com"
+```
+
+### Executar Agregações
+**Método:** POST
+**Endpoint:** `/v3/database/:collection/aggregate`
+**Query Params:**
+- `q` — Filtro `$match` inicial (opcional, aplicado antes do pipeline)
+- `strict=true` — Preserva tipos BSON
+- `out` — Coleção destino para gravar resultados (deve terminar em `__c`)
+- `out_operation=replace` — Limpa coleção destino antes de gravar
+
+**Header:**
+- `Range: items=0-19` — Paginação
+
+**Descrição:** O `q` é aplicado como primeiro `$match`. Os estágios do body são adicionados em sequência após ele. Usa `allowDiskUse(true)` automaticamente.
+
+**Exemplo — Query com filtro e ordenação:**
+```
+POST /v3/database/body_checkin__c/aggregate?q=userId:"ricardo@funifier.com"&strict=true
+Range: items=0-19
+
+[
+  { "$sort": { "created": -1 } }
+]
+```
+
+**Exemplo — Agregação completa:**
+```
+POST /v3/database/action_log/aggregate?strict=true
+
+[
+  { "$match": { "actionId": "sell", "userId": "jerry" } },
+  { "$group": { "_id": "$userId", "total": { "$sum": "$attributes.price" } } },
+  { "$sort": { "total": -1 } },
+  { "$limit": 10 }
+]
+```
+
+### Inserção em Massa (Bulk)
+**Método:** POST
+**Endpoint:** `/v3/database/:collection/bulk`
+**Query Params:**
+- `async=true` — Processamento assíncrono (para grandes volumes)
+
+**Exemplo de Body:**
+```json
+[
+  { "_id": "car001", "year": 2010, "price": 60000, "name": "Honda Civic", "brand": "honda" },
+  { "_id": "car002", "year": 2012, "price": 70000, "name": "Toyota Corolla", "brand": "toyota" }
+]
+```
+
+### Drop Collection
+**Método:** DELETE
+**Endpoint:** `/v3/database/:collection/drop`
+**⚠️ CUIDADO:** Remove a coleção inteira!
+
+### Listar Índices
+**Método:** GET
+**Endpoint:** `/v3/database/:collection/index`
+
+### Criar Índice
+**Método:** POST
+**Endpoint:** `/v3/database/:collection/index`
+
+**Exemplo de Body:**
+```json
+{ "fuel": 1 }
+```
+
+### Excluir Índice
+**Método:** DELETE
+**Endpoint:** `/v3/database/:collection/index/:index_name`
+
+## Paginação
+
+Usa header `Range` no padrão HTTP Range:
+```
+Range: items=0-9     (primeiros 10)
+Range: items=10-19   (próximos 10)
+Range: items=0-99    (primeiros 100)
+```
+
+Resposta inclui header `Content-Range` com total de registros.
+
+Default sem Range: retorna até 100 registros.
+
+## Strict Mode (BSON Types)
+
+Quando `strict=true`:
+- **Datas** são retornadas como `{ "$date": "2026-03-06T10:00:00.000Z" }` (ISO-8601)
+- **Sem strict**, datas podem vir como timestamps numéricos ou strings
+
+Para **gravar** datas tipadas, enviar como:
+```json
+{ "created": { "$date": "2026-03-06T10:00:00.000Z" } }
+```
+
+> **Regra:** Sempre use `strict=true` em GETs para preservar tipos BSON. Sem ele, datas viram strings/números e quebram queries.
+
+## Criptografia de Campos (v4.0)
+
+Se habilitada (Studio > Security > Field Encryption):
+- Campos marcados são criptografados no POST/PUT e descriptografados no GET
+- Requer token com permissão `readEncryptedValues`
+- Usa AES com chave secreta do tenant
+
+## Validações e Testes
+
+- [ ] Listar coleções retorna resultado
+- [ ] CRUD funciona na coleção alvo
+- [ ] Filtro `q` funciona corretamente
+- [ ] Aggregate com `q` + pipeline retorna dados filtrados e ordenados
+- [ ] Bulk insert registra múltiplos itens
+- [ ] Índices são criados/removidos corretamente
+- [ ] `strict=true` preserva tipos BSON

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

@@ -0,0 +1,111 @@
+# Folder (Pasta)
+
+**Acesso Studio:** `/studio/folder`
+**API Endpoint:** `/v3/folder`
+
+## O que é
+
+Organização de conteúdos e monitoramento do progresso em cursos ou trilhas. Permite criar pastas virtuais para agrupar conteúdos como quizzes, desafios, materiais de estudo e jogos, facilitando o acompanhamento do progresso dos jogadores em jornadas de aprendizagem ou trilhas gamificadas.
+
+## Quando usar
+
+- Para estruturar cursos online
+- Para criar trilhas de capacitação
+- Para acompanhar progresso em treinamentos
+- Para organizar conteúdos em hierarquias (módulos → aulas → conteúdos)
+
+## Checklist de Configuração no Studio
+
+- [ ] Criar estrutura hierárquica de pastas
+- [ ] Definir títulos das pastas
+- [ ] Associar conteúdos às pastas (quizzes, desafios, textos)
+- [ ] Definir tipos de conteúdo (folder_content_type)
+- [ ] Configurar pasta-pai (parent) para hierarquia
+
+## API Endpoints
+
+### Listar Pastas
+**Método:** GET
+**Endpoint:** `/v3/database/folder`
+
+### Criar Pasta
+**Método:** POST
+**Endpoint:** `/v3/folder`
+
+**Exemplo de Body:**
+```json
+{
+  "title": "CoreDrives",
+  "parent": "D0MmmNf"
+}
+```
+
+### Deletar Pasta
+**Método:** DELETE
+**Endpoint:** `/v3/folder/:id`
+
+### Obter Breadcrumb
+**Método:** POST
+**Endpoint:** `/v3/folder/breadcrumb`
+
+**Exemplo de Body:**
+```json
+{
+  "folder": "CD1"
+}
+```
+
+### Listar Tipos de Conteúdo
+**Método:** GET
+**Endpoint:** `/v3/database/folder_content_type`
+
+### Criar/Atualizar Tipo de Conteúdo
+**Método:** PUT
+**Endpoint:** `/v3/database/folder_content_type`
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "text",
+  "input": "formulary",
+  "form": [
+    { "name": "title", "type": "string", "title": "Title" },
+    { "name": "content", "type": "text", "title": "Content" }
+  ],
+  "title": "Text",
+  "entity": "text__c"
+}
+```
+
+## Casos de Uso Comuns
+
+- **Curso Online:** Pasta raiz "Curso de Vendas" → Subpastas "Módulo 1", "Módulo 2" → Conteúdos (textos, vídeos, quizzes)
+- **Trilha de Capacitação:** Pastas representam etapas; cada etapa contém materiais e avaliações
+- **Catálogo de Produtos:** Pastas como categorias; conteúdos como fichas de produto
+- **Onboarding:** Pastas representam fases do onboarding; progresso monitora completude
+
+## Progresso do Jogador
+
+O Folder monitora automaticamente o progresso do jogador dentro da árvore de diretórios. Isso permite:
+
+- Saber que um jogador completou X% de um curso
+- Registrar action logs ao progredir (aciona técnicas de jogos)
+- Criar desafios vinculados à completude de um folder (ex: "Complete o curso para ganhar 500 XP")
+
+## Integração com Outras Técnicas
+
+| Técnica | Integração |
+|---------|-----------|
+| **Challenge** | Desafio completado quando jogador termina todos os itens de um folder |
+| **Quiz** | Quizzes podem ser conteúdos dentro de um folder |
+| **Point** | Pontos concedidos ao progredir no folder |
+| **Achievement** | Conquista desbloqueada ao completar 100% do folder |
+
+## Validações e Testes
+
+- [ ] Pasta aparece na lista
+- [ ] Hierarquia pai-filho funciona
+- [ ] Breadcrumb retorna caminho correto
+- [ ] Conteúdos são associados corretamente
+- [ ] Progresso do jogador é calculado corretamente
+- [ ] Action log é gerado ao progredir

package/datasource-funifier-docs/knowledge/modules/kpi-formulas.md

@@ -0,0 +1,23 @@
+# KPI Formulas (Fórmulas de KPI)
+
+## O que é
+
+Configuração de regras e cálculos avançados para avaliar ações dos jogadores. Permite criar fórmulas customizadas para avaliação de desempenho e resultados, indo além das regras padrão dos outros módulos.
+
+## Quando usar
+
+- Para cálculos avançados de desempenho que os módulos padrão não atendem
+- Para fórmulas considerando múltiplos critérios (quantidade, valor, tempo)
+- Para regras avançadas de rankings
+- **Importante:** usar com critério, apenas quando recursos padrão não atendem
+
+## Checklist de Configuração
+
+- [ ] Definir a fórmula de cálculo
+- [ ] Vincular aos desafios ou rankings relevantes
+- [ ] Testar com dados reais
+
+## Validações e Testes
+
+- [ ] Fórmula retorna resultados esperados
+- [ ] Cálculo funciona com diferentes combinações de dados

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

@@ -0,0 +1,45 @@
+# LastMile (Última Milha)
+
+**Acesso Studio:** `/studio/lastmile`
+**API Endpoint:** `/v3/lastmile`
+
+## O que é
+
+Envio de mensagens motivacionais quando o jogador está próximo de uma meta. Permite configurar mensagens automáticas para engajar e lembrar os jogadores sobre metas e desafios que estão prestes a serem concluídos, aumentando a taxa de finalização.
+
+## Quando usar
+
+- Para lembrar jogadores que estão perto de completar desafios
+- Para aumentar taxa de conclusão de metas
+- Para enviar mensagens motivacionais personalizadas
+- Para engajar jogadores que estão a 80-90% de uma meta
+
+## Dependências
+
+- **Challenge**: desafios devem existir para monitorar progresso
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir condição de disparo (% de progresso)
+- [ ] Definir mensagem motivacional
+- [ ] Vincular ao desafio ou meta específica
+
+## API Endpoints
+
+### Listar LastMile
+**Método:** GET
+**Endpoint:** `/v3/lastmile`
+
+### Criar LastMile
+**Método:** POST
+**Endpoint:** `/v3/lastmile`
+
+### Deletar LastMile
+**Método:** DELETE
+**Endpoint:** `/v3/lastmile/:id`
+
+## Validações e Testes
+
+- [ ] Configuração de LastMile aparece na lista
+- [ ] Mensagem é disparada ao atingir % configurado
+- [ ] Jogador recebe notificação corretamente

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

@@ -0,0 +1,98 @@
+# Leaderboard (Ranking)
+
+**Acesso Studio:** `/studio/leaderboard`
+**API Endpoint:** `/v3/leaderboard`
+
+## O que é
+
+Criação e gestão de rankings. Permite comparar o desempenho dos jogadores utilizando diferentes critérios, como pontos, tempo, ou métricas customizadas. Rankings podem ser individuais, por equipes, por período ou por status.
+
+## Quando usar
+
+- Para criar competição saudável entre jogadores
+- Para dar visibilidade ao desempenho
+- Para motivar através de comparação social
+- Para rankings semanais, mensais ou em tempo real
+
+## Dependências
+
+- **Point** ou **Action**: o critério de ranking deve estar configurado
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir título e descrição
+- [ ] Definir tipo de principal (0 = jogador, 1 = equipe)
+- [ ] Definir operação (tipo de métrica, item, ordenação)
+- [ ] Definir período (semanal, mensal, tempo real)
+- [ ] Vincular técnicas de jogo
+
+## API Endpoints
+
+### Listar Leaderboards
+**Método:** GET
+**Endpoint:** `/v3/leaderboard`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "title": "Top Players",
+    "description": "Players with the most points xp in the week",
+    "principalType": 0,
+    "operation": {
+      "type": 3,
+      "achievement_type": 0,
+      "item": "xp",
+      "filters": [],
+      "sort": -1,
+      "sub": false
+    },
+    "period": {
+      "type": 0,
+      "timeAmount": 1,
+      "timeScale": 6
+    },
+    "techniques": ["GT03"],
+    "_id": "DTjTvZ5"
+  }
+]
+```
+
+### Criar Leaderboard
+**Método:** POST
+**Endpoint:** `/v3/leaderboard`
+(Body igual ao exemplo de resposta acima)
+
+### Deletar Leaderboard
+**Método:** DELETE
+**Endpoint:** `/v3/leaderboard/:id`
+
+### Obter Lista de Líderes
+**Método:** POST
+**Endpoint:** `/v3/leaderboard/:id/leader/aggregate?period=&live=true`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "_id": "tom_D0zCMvq",
+    "total": 30,
+    "position": 1,
+    "move": "up",
+    "player": "tom",
+    "name": "Tom",
+    "boardId": "DTjTvZ5"
+  }
+]
+```
+
+### Resetar Cache
+**Método:** GET
+**Endpoint:** `/v3/leaderboard/reset`
+
+## Validações e Testes
+
+- [ ] Leaderboard aparece na lista GET /v3/leaderboard
+- [ ] Lista de líderes retorna jogadores ordenados
+- [ ] Período está configurado corretamente
+- [ ] Cache pode ser resetado com sucesso

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

@@ -0,0 +1,83 @@
+# Level (Nível)
+
+**Acesso Studio:** `/studio/level`
+**API Endpoint:** `/v3/level`
+
+## O que é
+
+Sistema de progressão por níveis. Permite definir a progressão dos jogadores com base em pontos acumulados ou outros critérios, atribuindo títulos ou benefícios a cada nível. Pode-se exigir desafios específicos para desbloquear certos níveis.
+
+## Quando usar
+
+- Para criar senso de progressão e conquista
+- Para desbloquear funcionalidades por nível
+- Para segmentar jogadores por experiência
+- Exemplos: Júnior → Pleno → Sênior; faixas coloridas
+
+## Dependências
+
+- **Point**: a categoria de ponto usada para progressão deve existir antes
+- **Configuração global**: definir qual ponto controla os níveis via `/v3/database/level_config`
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir _id do nível (ex: L0, L1, L2)
+- [ ] Definir nome do nível (ex: "Apprentice", "Master")
+- [ ] Definir descrição motivadora
+- [ ] Definir minPoints (pontuação mínima crescente)
+- [ ] Definir position (ordem sequencial, iniciando em 0)
+- [ ] Configurar categoria de ponto global (level_config)
+
+## API Endpoints
+
+### Listar Níveis
+**Método:** GET
+**Endpoint:** `/v3/level`
+
+### Criar Nível
+**Método:** POST
+**Endpoint:** `/v3/level`
+
+**Exemplo de Body:**
+```json
+{
+  "level": "Apprentice",
+  "position": 0,
+  "description": "It indicates that you are learning and growing.",
+  "minPoints": 10,
+  "notifications": [],
+  "requirements": [],
+  "i18n": {},
+  "extra": {},
+  "techniques": ["GT85"],
+  "_id": "L0"
+}
+```
+
+### Excluir Nível
+**Método:** DELETE
+**Endpoint:** `/v3/level/:id`
+
+### Configurar Ponto Global para Níveis
+**Método:** PUT
+**Endpoint:** `/v3/database/level_config`
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "global",
+  "pointCategory": "xp"
+}
+```
+
+### Atualizar Posições dos Níveis
+**Método:** PUT
+**Endpoint:** `/v3/level/position`
+**Descrição:** Recalcula posições com base no minPoints.
+
+## Validações e Testes
+
+- [ ] Níveis aparecem na lista GET /v3/level
+- [ ] minPoints é crescente entre níveis
+- [ ] level_config aponta para o ponto correto
+- [ ] Ao ganhar pontos suficientes, jogador sobe de nível automaticamente