funifier-mcp 0.2.0 → 0.2.3

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

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