funifier-mcp 0.3.9 → 0.3.10

package/dist/mcp/tools/permissions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.test.js","sourceRoot":"","sources":["../../../src/mcp/tools/permissions.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Funifier AI toolkit — MCP server, API client, and Claude Code skills for the Funifier gamification platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,4 +72,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/skills/funifier/SKILL.md

@@ -36,6 +36,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation | `references/create-trigger.md` |
 | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation | `references/create-scheduler.md` |
 | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards | `references/create-aggregate.md` |
+| Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates | `references/date-handling.md` |
 | Create a Funifier challenge — missions with action rules and point rewards | `references/create-challenge.md` |
 | Create a Funifier action — define trackable player behaviors with attributes | `references/create-action.md` |
 | Create a Funifier point category — XP, coins, or custom metrics | `references/create-point.md` |

package/skills/funifier/references/create-aggregate.md

@@ -74,8 +74,12 @@ If search returns insufficient results, read these directly:
 | `point_category` | Tipos de ponto — `_id`, `category`, `shortName` |
 | `catalog_item` | Loja virtual — `_id`, `catalogId`, `name`, `requires` |
 
+Se o pipeline filtrar ou criar campos de data, leia também `references/date-handling.md` antes de montar o payload.
+
 ### Expressões de data Funifier
 
+Para regras completas de criação/edição/consulta de datas via REST, triggers, schedulers, aggregate e prepared aggregate, leia `references/date-handling.md`.
+
 | Expressão | Significado |
 |---|---|
 | `{"$date": "-0d-"}` | Início do dia atual |
@@ -84,6 +88,8 @@ If search returns insufficient results, read these directly:
 | `{"$date": "-0y-"}` | Início do ano atual |
 | `{"$date": "-1d-"}` | Início do dia anterior |
 
+**Importante:** em aggregate direto e prepared aggregate, prefira expressões relativas Funifier dentro de `$date` (`-0M-`, `-0M+`) ou timestamps em milissegundos para datas absolutas. Para datas absolutas parametrizadas em prepared aggregate, normalize no `script` com `DateUtil.parse(...)` e substitua diretamente em `$gte`/`$lte`.
+
 ---
 
 ## Steps

package/skills/funifier/references/date-handling.md

@@ -0,0 +1,172 @@
+# funifier-date-handling
+
+Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates
+
+---
+
+## Formato do payload (obrigatório)
+
+Funifier armazena código como **strings JSON escapadas**. Ao montar o payload do `funifier_save`:
+
+- **Quebra de linha** → `\n` (nunca newline literal dentro da string)
+- **Aspas duplas** dentro do código → `\"`
+- **Backslash** → `\\` (regex `\b` vira `\\b`; dentro de Groovy com string-building pode exigir `\\\\b`)
+- **Tab** → `\t` (se usar)
+- **Pipelines de aggregate** vão como **string JSON** (não objeto aninhado) — serialize o array inteiro
+
+A regra prática: monte o objeto em JavaScript normalmente e passe por `JSON.stringify` — o MCP faz isso automaticamente quando você entrega o payload como JSON. **Nunca** cole código multilinha cru no meio do JSON.
+
+### Exemplo 1 — custom-page (html + angularjs script)
+
+```json
+{
+  "title": "Ciclos",
+  "slug": "studio/custom/ciclos",
+  "html": "<div class=\"row\">\n  <div class=\"col-md-12\">\n    <h2>Ciclos</h2>\n  </div>\n</div>\n",
+  "script": "$scope.all = [];\n$scope.loading = false;\n\n$scope.list = function () {\n  $scope.loading = true;\n};\n$scope.list();\n"
+}
+```
+
+### Exemplo 2 — aggregate preparado (pipeline JSON + script Groovy)
+
+```json
+{
+  "_id": "extrato",
+  "title": "Extrato de Pontos",
+  "collection": "extrato",
+  "aggregate": "[\n  {\n    \"$match\": { \"player\": \"$param:player\" }\n  },\n  {\n    \"$sort\": { \"time\": -1 }\n  }\n]",
+  "script": "void prepare(aggregations, params) {\n    if (context.get(\"player\") != null) {\n        params.put(\"player\", context.get(\"player\"));\n    } else {\n        params.put(\"player\", \"NAO_EXISTE\");\n    }\n}\n"
+}
+```
+
+Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"` escapados), **não** um array nativo. Mesma regra vale para `script` em triggers/schedulers/aggregates e `html`/`script` em custom-pages.
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "date dates bson extended-json aggregate prepared DateUtil strict timestamp timezone"
+```
+
+Then read the most relevant results with `funifier_read_doc path=<path>`.
+
+## Primary docs for this skill
+
+If search returns insufficient results, read these directly:
+
+- `funifier_read_doc path=guides/database-access`
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=modules/database`
+
+## Steps
+
+## Regra de ouro
+
+Use **BSON Extended JSON** para persistir datas em objetos customizados:
+
+```json
+{
+  "startsAt": { "$date": "2026-05-28T13:30:00.000Z" },
+  "created": { "$date": "2026-05-28T13:30:00.000Z" }
+}
+```
+
+Evite salvar data como string ISO solta quando o campo será filtrado como data. String não compara corretamente com BSON Date em consultas Mongo.
+
+---
+
+## Criar/editar datas via REST ou funifier_database
+
+- Gere datas em UTC (`toISOString()` no JavaScript).
+- Ao criar/editar documentos, envie campos de data como `{ "$date": "<ISO UTC>" }`.
+- Em updates via `PUT /v3/database/<collection>`, reenvie o documento completo: o endpoint faz **full replace**.
+- Use `strict=true` ao ler quando precisar confirmar tipos BSON preservados na resposta.
+
+```json
+{
+  "_id": "cycle_2026_05",
+  "name": "Ciclo Maio",
+  "startsAt": { "$date": "2026-05-01T00:00:00.000Z" },
+  "endsAt": { "$date": "2026-05-31T23:59:59.999Z" }
+}
+```
+
+Não salve assim se o campo será filtrado como data:
+
+```json
+{ "startsAt": "2026-05-01T00:00:00.000Z" }
+```
+
+---
+
+## Triggers e schedulers
+
+Scripts Groovy de triggers, schedulers e prepared aggregates já importam `DateUtil` e `JsonUtil` nos runners. Se o script precisa calcular/comparar datas, normalize explicitamente com `DateUtil.parse(...)`, `new Date()` ou `DateUtil.fromKeyword(...)`.
+
+```groovy
+void trigger(event, entity, player, database) {
+  entity.createdAt = new Date()
+  entity.startsAt = DateUtil.parse('2026-05-01T00:00:00.000Z')
+  entity.endsAt = DateUtil.fromKeyword('+7d+')
+}
+```
+
+---
+
+## Aggregate direto
+
+Prefira períodos relativos com `$date`, que passam pelo `FunifierMarshaller` e são convertidos por `DateUtil.fromKeyword`:
+
+```json
+[
+  {
+    "$match": {
+      "time": {
+        "$gte": { "$date": "-0M-" },
+        "$lte": { "$date": "-0M+" }
+      }
+    }
+  }
+]
+```
+
+Não generalize para `q` de GET/list/count/delete: esses caminhos montam a query string diretamente.
+
+Para data absoluta em aggregate direto, prefira timestamp em milissegundos dentro de `$date` ou teste o formato na instância antes de documentar como padrão.
+
+---
+
+## Prepared aggregate (`/v3/find/<id>`)
+
+Regras extras:
+
+1. O campo `aggregate` salvo no recurso é uma **string JSON serializada**, não array nativo.
+2. Parâmetros só são substituídos quando aparecem como string literal `"$param:nome"`.
+
+Para datas relativas, use parâmetros dentro de `$date` (`"$date":"$param:start"`) e preencha `params.start` com keywords como `-0M-`.
+
+Para datas absolutas, normalize no `script` para `Date` e substitua diretamente em `$gte`/`$lte`:
+
+```json
+{
+  "aggregate": "[{"$match":{"soldAt":{"$gte":"$param:start","$lte":"$param:end"}}}]",
+  "script": "void prepare(aggregations, params) {\n  Date start = params.startIso ? DateUtil.parse(params.startIso) : DateUtil.fromKeyword('-0M-')\n  Date end = params.endIso ? DateUtil.parse(params.endIso) : DateUtil.fromKeyword('-0M+')\n  if (start == null || end == null) throw new IllegalArgumentException('Invalid date params')\n  params.put('start', start)\n  params.put('end', end)\n}\n"
+}
+```
+
+Não coloque o parâmetro convertido para `Date` dentro de `{ "$date": "$param:start" }`.
+
+---
+
+## Checklist
+
+- [ ] Salvar Date como `{ "$date": "<ISO UTC>" }`, nunca string solta.
+- [ ] Preservar todos os campos em `PUT`.
+- [ ] Usar keywords Funifier (`-0d-`, `-0M-`, `-0M+`, `+1d+`) apenas em caminhos que passam pelo `FunifierMarshaller`.
+- [ ] Em prepared aggregate, salvar `aggregate` como string JSON serializada.
+- [ ] Em prepared aggregate, usar `"$param:nome"` exatamente como string.
+- [ ] Para data absoluta em prepared aggregate, converter no `script` com `DateUtil.parse`, validar `null`, e substituir o `Date` diretamente em `$gte`/`$lte`.
+- [ ] Testar aggregate direto antes de salvar como prepared aggregate.

package/skills/funifier/references/debug.md

@@ -47,6 +47,8 @@ If search returns insufficient results, read these directly:
 | Challenge não avança | Action não existe ou operator/total errado | `funifier_list type=action search=<id>` |
 | Compra falha sem erro | Saldo insuficiente ou `requires` errado | Checar ponto do jogador: `GET /v3/player/<id>/status` |
 | `/v3/database` retorna vazio | Scope `database` ausente na role | Adicionar `database` ao scope via Security |
+| Filtro por data não encontra registros | Campo foi salvo como string ISO ou parâmetro ISO foi usado dentro de `$date` sem normalização | Salvar como `{ "$date": "<ISO UTC>" }`; em prepared aggregate converter ISO com `DateUtil.parse` no script |
+| Prepared aggregate com data absoluta falha/retorna vazio | `"$param:start"` dentro de `{ "$date": ... }` recebeu string ISO | Converter no `script` para `Date` e usar `"$gte":"$param:start"` diretamente |
 
 ---
 

package/skills/funifier/references/implement-frontend.md

@@ -34,6 +34,7 @@ If search returns insufficient results, read these directly:
 - **Senha do player no banco deve ser BCrypt** (`$2a$...`) — texto plano causa `"Invalid salt version"`
 - **Scope `database`** é obrigatório na role para usar `/v3/database` — sem ele escrita retorna 201 mas não persiste
 - **Header `Range: items=0-1000`** para listas sem paginação explícita
+- **Datas em objetos de negócio:** enviar como `{ "$date": new Date(value).toISOString() }`, não string solta, quando o campo será consultado como data.
 
 ### Auth flow
 
@@ -72,6 +73,7 @@ const basicToken = 'Basic ' + btoa('API_KEY:APP_SECRET');
 - `funifier_read_doc path=modules/auth`
 - `funifier_read_doc path=modules/patterns`
 - `funifier_read_doc path=guides/aggregates` (para relatórios)
+- Se criar, editar ou filtrar datas, leia `references/date-handling.md`.
 
 ### 2. Implementar autenticação
 
@@ -101,6 +103,22 @@ const report = await fetch('/v3/database/achievement/aggregate', {
 });
 ```
 
+### Datas no frontend
+
+```javascript
+const payload = {
+  _id: 'cycle_2026_05',
+  startsAt: { $date: new Date('2026-05-01T00:00:00.000Z').toISOString() },
+  endsAt: { $date: new Date('2026-05-31T23:59:59.999Z').toISOString() }
+};
+
+await fetch('/v3/database/cycle__c?strict=true', {
+  method: 'POST',
+  headers: { ...headers, 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload)
+});
+```
+
 ### 5. Hospedar no Funifier (opcional)
 
 Para arquivos estáticos, leia `funifier_read_doc path=modules/static-repo`.