funifier-mcp 0.2.0 → 0.2.4

package/datasource-funifier-docs/knowledge/modules/csv-data.md

@@ -1,30 +1,30 @@
-# CSV Data (Dados CSV)
-
-**API Endpoint:** `/v3/csv`
-
-## O que é
-
-Importação e exportação de dados no formato CSV. Permite importar ou exportar dados de forma fácil e segura, seja via upload manual ou FTP. Suporta arquivos criptografados para segurança no trânsito das informações.
-
-## Quando usar
-
-- Para importar listas de jogadores em massa
-- Para exportar relatórios de desempenho
-- Para migrar dados de sistemas externos
-- Para importação segura via FTP com criptografia
-
-## API Endpoints
-
-### Importar CSV
-**Método:** POST
-**Endpoint:** `/v3/csv`
-
-### Exportar CSV
-**Método:** GET
-**Endpoint:** `/v3/csv`
-
-## Validações e Testes
-
-- [ ] Importação processa arquivo corretamente
-- [ ] Dados importados aparecem nas coleções corretas
-- [ ] Exportação gera arquivo CSV válido
+# CSV Data (Dados CSV)
+
+**API Endpoint:** `/v3/csv`
+
+## O que é
+
+Importação e exportação de dados no formato CSV. Permite importar ou exportar dados de forma fácil e segura, seja via upload manual ou FTP. Suporta arquivos criptografados para segurança no trânsito das informações.
+
+## Quando usar
+
+- Para importar listas de jogadores em massa
+- Para exportar relatórios de desempenho
+- Para migrar dados de sistemas externos
+- Para importação segura via FTP com criptografia
+
+## API Endpoints
+
+### Importar CSV
+**Método:** POST
+**Endpoint:** `/v3/csv`
+
+### Exportar CSV
+**Método:** GET
+**Endpoint:** `/v3/csv`
+
+## Validações e Testes
+
+- [ ] Importação processa arquivo corretamente
+- [ ] Dados importados aparecem nas coleções corretas
+- [ ] Exportação gera arquivo CSV válido

package/datasource-funifier-docs/knowledge/modules/custom-object.md

@@ -1,53 +1,53 @@
-# Custom Object (Objeto Customizado)
-
-## O que é
-
-Criação de objetos personalizados para necessidades específicas. Permite criar e gerenciar coleções personalizadas no banco de dados (sufixo `__c`), que podem ser acessadas via API, triggers, schedulers e páginas personalizadas. Ideal para quando os módulos padrão não atendem a todos os requisitos do projeto.
-
-## Quando usar
-
-- Para cadastrar entidades específicas do negócio (produtos, imóveis, etc.)
-- Para criar listas customizadas (pontos turísticos, categorias, etc.)
-- Para armazenar dados que não se encaixam nos módulos padrão
-
-## API Endpoints
-
-Objetos customizados são acessados via o módulo Database:
-
-### Listar Objetos
-**Método:** GET
-**Endpoint:** `/v3/database/<nome>__c`
-
-### Criar Objeto
-**Método:** POST
-**Endpoint:** `/v3/database/<nome>__c`
-
-**Exemplo (coleção car__c):**
-```json
-{
-  "_id": "car001",
-  "name": "Civic",
-  "brand": "Honda",
-  "price": 50000
-}
-```
-
-### Atualizar Objeto
-**Método:** PUT
-**Endpoint:** `/v3/database/<nome>__c`
-
-### Excluir Objeto
-**Método:** DELETE
-**Endpoint:** `/v3/database/<nome>__c?q=_id:'car001'`
-
-## Boas Práticas
-
-- Sempre usar sufixo `__c` no nome da coleção
-- Definir `_id` único para cada objeto
-- Criar índices para campos usados em consultas frequentes
-
-## Validações e Testes
-
-- [ ] Coleção customizada aparece em GET /v3/database/collections
-- [ ] CRUD funciona corretamente
-- [ ] Triggers com entity `<nome>__c` funcionam
+# Custom Object (Objeto Customizado)
+
+## O que é
+
+Criação de objetos personalizados para necessidades específicas. Permite criar e gerenciar coleções personalizadas no banco de dados (sufixo `__c`), que podem ser acessadas via API, triggers, schedulers e páginas personalizadas. Ideal para quando os módulos padrão não atendem a todos os requisitos do projeto.
+
+## Quando usar
+
+- Para cadastrar entidades específicas do negócio (produtos, imóveis, etc.)
+- Para criar listas customizadas (pontos turísticos, categorias, etc.)
+- Para armazenar dados que não se encaixam nos módulos padrão
+
+## API Endpoints
+
+Objetos customizados são acessados via o módulo Database:
+
+### Listar Objetos
+**Método:** GET
+**Endpoint:** `/v3/database/<nome>__c`
+
+### Criar Objeto
+**Método:** POST
+**Endpoint:** `/v3/database/<nome>__c`
+
+**Exemplo (coleção car__c):**
+```json
+{
+  "_id": "car001",
+  "name": "Civic",
+  "brand": "Honda",
+  "price": 50000
+}
+```
+
+### Atualizar Objeto
+**Método:** PUT
+**Endpoint:** `/v3/database/<nome>__c`
+
+### Excluir Objeto
+**Método:** DELETE
+**Endpoint:** `/v3/database/<nome>__c?q=_id:'car001'`
+
+## Boas Práticas
+
+- Sempre usar sufixo `__c` no nome da coleção
+- Definir `_id` único para cada objeto
+- Criar índices para campos usados em consultas frequentes
+
+## Validações e Testes
+
+- [ ] Coleção customizada aparece em GET /v3/database/collections
+- [ ] CRUD funciona corretamente
+- [ ] Triggers com entity `<nome>__c` funcionam

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

@@ -1,241 +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
+# 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