funifier-mcp 0.2.0 → 0.2.3

package/datasource-funifier-docs/knowledge/guides/java-libraries.md

@@ -1,330 +1,330 @@
-# Java Libraries — Referência
-
-Bibliotecas e utilitários disponíveis para uso em **triggers**, **schedulers** e **public endpoints**.
-
----
-
-## JsonUtil
-
-**Classe:** `com.funifier.engine.util.JsonUtil`
-
-Utilitário estático para serialização/deserialização JSON (baseado em Jackson).
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `toJson(Object obj)` | String | Converte objeto para JSON string |
-| `toJsonRemoveNullFields(Object obj)` | String | Converte para JSON excluindo campos null |
-| `fromJson(String json, Class<T> valueType)` | T | Converte JSON string para objeto tipado |
-| `fromJsonToMap(String json)` | Map\<String, Object\> | Converte JSON string para Map |
-| `toBsonStrictMode(Object obj)` | String | Converte para BSON strict mode (MongoDB) |
-
-**Exemplos:**
-
-```java
-// Objeto para JSON
-HashMap data = new HashMap();
-data.put("name", "John");
-data.put("score", 100);
-String json = JsonUtil.toJson(data);
-// {"name":"John","score":100}
-
-// JSON para Map
-Map<String, Object> map = JsonUtil.fromJsonToMap("{\"name\":\"John\",\"score\":100}");
-String name = (String) map.get("name");
-
-// JSON para objeto tipado
-Player player = JsonUtil.fromJson(jsonString, Player.class);
-
-// Ignorar campos null
-String cleanJson = JsonUtil.toJsonRemoveNullFields(obj);
-```
-
----
-
-## Guid
-
-**Classe:** `com.funifier.engine.guid.Guid`
-
-Geração de identificadores únicos.
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `newShortGuid()` | String | Gera ID único (MongoDB ObjectId, 24 chars) |
-| `shortTimeMillis()` | String | Gera código baseado no timestamp (base62, ~7 chars) |
-
-**Exemplos:**
-
-```java
-// Gerar ID para novo objeto
-String id = Guid.newShortGuid();
-// Ex: "64a5d92f1b2c3d4e5f6a7b8c"
-
-// Gerar código curto baseado no tempo (útil para códigos de convite)
-String code = Guid.shortTimeMillis();
-// Ex: "y6z3D6H"
-```
-
-**Quando usar cada um:**
-- `newShortGuid()` — Para IDs de objetos (achievements, action logs, etc.)
-- `shortTimeMillis()` — Para códigos legíveis (convites, vouchers, etc.)
-
----
-
-## DateUtil
-
-**Classe:** `com.funifier.engine.util.DateUtil`
-
-Utilitário para cálculos e parsing de datas, incluindo as **expressões de data Funifier**.
-
-### Expressões de Data (Funifier Syntax)
-
-Formato: `[sinal][quantidade][unidade][ajuste]`
-
-**Unidades:** `y`=ano, `M`=mês, `w`=semana, `d`=dia, `h`=hora, `m`=minuto, `s`=segundo
-
-**Ajuste:** `-` = início da unidade (floor), `+` = fim da unidade (ceil), sem ajuste = exato
-
-| Expressão | Significado |
-|-----------|------------|
-| `-0d` | Agora |
-| `-0d-` | Início do dia atual (00:00:00) |
-| `-0d+` | Fim do dia atual (23:59:59) |
-| `-1d` | Exatamente 1 dia atrás |
-| `-1d-` | Início do dia anterior |
-| `-1d+` | Fim do dia anterior |
-| `+1d` | Exatamente 1 dia no futuro |
-| `+1d-` | Início do dia seguinte |
-| `-0w-` | Início da semana atual |
-| `-0w+` | Fim da semana atual |
-| `-0M-` | Primeiro dia do mês (00:00:00) |
-| `-0M+` | Último dia do mês (23:59:59) |
-| `-1M-` | Primeiro dia do mês anterior |
-| `-0y-` | 1 de janeiro do ano atual |
-| `-0y+` | 31 de dezembro do ano atual |
-
-**Encadeamento com `|`:**
-```
--1d+|GMT+3            → fim do dia anterior no fuso GMT+3
--0d-|+5h|+30m|GMT-3   → início do dia + 5h30m no fuso GMT-3
-```
-
-### Métodos
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `fromKeyword(String keyword)` | Date | Converte expressão Funifier em Date |
-| `fromKeyword(String keyword, Date reference)` | Date | Converte com data de referência |
-| `fromKeyword(String keyword, Date reference, String timezone)` | Date | Converte com referência e timezone |
-| `fromKeywordPeriodExpression(String period)` | Date[] | Converte período (ex: "-0M-;-0M+") em [inicio, fim] |
-| `parse(Object date)` | Date | Parse genérico (Date, Long, String, expressão) |
-| `parse(String date, String pattern)` | Date | Parse com padrão SimpleDateFormat |
-| `format(Date date, String pattern)` | String | Formata data com padrão SimpleDateFormat |
-| `between(Date ref, int scale, int amount)` | Date[] | Intervalo [inicio, fim] da unidade |
-| `add(Date ref, int scale, int amount)` | Date | Adiciona unidades à data |
-| `reset(Date date, int scale)` | Date | Trunca data para o início da unidade |
-
-**Escalas (TimeScale):**
-```java
-TimeScale.MILLISECOND = 0;
-TimeScale.SECOND = 1;
-TimeScale.MINUTE = 2;
-TimeScale.HOUR = 3;
-TimeScale.DAY = 4;
-TimeScale.WEEK = 5;
-TimeScale.MONTH = 6;
-TimeScale.YEAR = 7;
-```
-
-**Exemplos:**
-
-```java
-// Usar expressões Funifier
-Date inicioMes = DateUtil.fromKeyword("-0M-");
-Date fimMes = DateUtil.fromKeyword("-0M+");
-Date ontem = DateUtil.fromKeyword("-1d");
-
-// Período completo
-Date[] periodo = DateUtil.fromKeywordPeriodExpression("-0M-;-0M+");
-Date inicio = periodo[0];
-Date fim = periodo[1];
-
-// Parse genérico
-Date d1 = DateUtil.parse("2023-07-05T20:57:33.303Z");
-Date d2 = DateUtil.parse("-1d");
-
-// Formatar data
-String formatted = DateUtil.format(new Date(), "dd/MM/yyyy HH:mm:ss");
-
-// Adicionar tempo
-Date amanha = DateUtil.add(new Date(), TimeScale.DAY, 1);
-Date mesPassado = DateUtil.add(new Date(), TimeScale.MONTH, -1);
-```
-
-> **Referência completa de expressões de data em consultas:** consulte `guides/aggregates.md`.
-
----
-
-## Unirest
-
-**Biblioteca:** `com.mashape.unirest`
-
-Cliente HTTP para fazer requisições a APIs externas.
-
-**Exemplos:**
-
-```java
-// GET
-HttpResponse<String> response = Unirest.get("https://api.example.com/data")
-    .header("Authorization", "Bearer token123")
-    .asString();
-String body = response.getBody();
-int status = response.getStatus();
-
-// POST com JSON
-HashMap payload = new HashMap();
-payload.put("name", "John");
-payload.put("email", "john@email.com");
-
-HttpResponse<String> response = Unirest.post("https://api.example.com/users")
-    .header("Content-Type", "application/json")
-    .body(JsonUtil.toJson(payload))
-    .asString();
-
-// POST form
-HttpResponse<String> response = Unirest.post("https://api.example.com/form")
-    .field("username", "john")
-    .field("password", "secret")
-    .asString();
-
-// PUT
-HttpResponse<String> response = Unirest.put("https://api.example.com/users/1")
-    .header("Content-Type", "application/json")
-    .body(JsonUtil.toJson(payload))
-    .asString();
-
-// DELETE
-HttpResponse<String> response = Unirest.delete("https://api.example.com/users/1")
-    .asString();
-```
-
----
-
-## EmailBuilder (SimpleJavaMail)
-
-**Biblioteca:** `org.simplejavamail`
-
-Envio de emails via SMTP.
-
-**Exemplos:**
-
-```java
-// Enviar email simples
-Email email = EmailBuilder
-    .startingBlank()
-    .from("Company", "noreply@company.com")
-    .to("John", "john@email.com")
-    .withSubject("Welcome!")
-    .withPlainText("Welcome to our platform!")
-    .buildEmail();
-
-MailerBuilder.withSMTPServer("smtp.host.com", 587, "login", "password")
-    .buildMailer()
-    .sendMail(email);
-
-// Email com HTML
-Email email = EmailBuilder
-    .startingBlank()
-    .from("Company", "noreply@company.com")
-    .to("John", "john@email.com")
-    .withSubject("Report")
-    .withHTMLText("<h1>Hello</h1><p>Your monthly report is ready.</p>")
-    .buildEmail();
-
-MailerBuilder.withSMTPServer("smtp.host.com", 587, "login", "password")
-    .buildMailer()
-    .sendMail(email);
-```
-
----
-
-## Jongo (Acesso ao MongoDB)
-
-**Biblioteca:** `org.jongo`
-
-Acesso direto ao MongoDB através do objeto `database` (em triggers) ou `manager.getJongoConnection()`.
-
-### Operações
-
-```java
-// Obter coleção
-org.jongo.MongoCollection collection = database.getCollection("nome_colecao");
-
-// --- INSERT / UPDATE ---
-// Save (insere ou atualiza se _id existir)
-database.getCollection("email__c").save(hashMap);
-
-// --- FIND ---
-// Buscar um documento
-Object result = database.getCollection("player")
-    .findOne("{_id: 'john'}").as(Object.class);
-
-// Buscar com parâmetro (#)
-Object result = database.getCollection("product__c")
-    .findOne("{_id: #}", productId).as(Object.class);
-
-// Buscar vários
-Iterable<Object> results = database.getCollection("action_log")
-    .find("{userId: #}", "john").as(Object.class);
-
-// Buscar com projeção
-Object result = database.getCollection("player")
-    .findOne("{_id: #}", id)
-    .projection("{name: 1, email: 1}")
-    .as(Object.class);
-
-// --- DELETE ---
-database.getCollection("car__c").remove("{_id: 'car001'}");
-
-// --- COUNT ---
-long total = database.getCollection("action_log")
-    .count("{userId: #}", "john");
-
-// --- AGGREGATE ---
-Iterable<Object> result = database.getCollection("achievement")
-    .aggregate("{$match: {type: 0, item: 'xp'}}")
-    .and("{$group: {_id: '$player', total: {$sum: '$total'}}}")
-    .and("{$sort: {total: -1}}")
-    .and("{$limit: 10}")
-    .as(Object.class);
-```
-
-### Parâmetros com `#`
-
-O Jongo usa `#` como placeholder para parâmetros seguros (evita injection):
-
-```java
-// Um parâmetro
-database.getCollection("player").findOne("{_id: #}", playerId).as(Object.class);
-
-// Múltiplos parâmetros
-database.getCollection("action_log")
-    .find("{userId: #, actionId: #}", "john", "sell")
-    .as(Object.class);
-```
-
-> **Referência completa:** consulte `guides/database-access.md` e `guides/aggregates.md`.
-
----
-
-## Resumo Rápido
-
-| Necessidade | O que usar |
-|------------|-----------|
-| Converter objeto para JSON | `JsonUtil.toJson(obj)` |
-| Converter JSON para objeto | `JsonUtil.fromJson(json, Class)` |
-| Gerar ID único | `Guid.newShortGuid()` |
-| Gerar código curto | `Guid.shortTimeMillis()` |
-| Calcular data com expressão | `DateUtil.fromKeyword("-0M-")` |
-| Fazer requisição HTTP | `Unirest.get/post/put/delete(url)` |
-| Enviar email | `EmailBuilder.startingBlank()...` |
-| Acessar MongoDB | `database.getCollection("nome")` |
+# Java Libraries — Referência
+
+Bibliotecas e utilitários disponíveis para uso em **triggers**, **schedulers** e **public endpoints**.
+
+---
+
+## JsonUtil
+
+**Classe:** `com.funifier.engine.util.JsonUtil`
+
+Utilitário estático para serialização/deserialização JSON (baseado em Jackson).
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `toJson(Object obj)` | String | Converte objeto para JSON string |
+| `toJsonRemoveNullFields(Object obj)` | String | Converte para JSON excluindo campos null |
+| `fromJson(String json, Class<T> valueType)` | T | Converte JSON string para objeto tipado |
+| `fromJsonToMap(String json)` | Map\<String, Object\> | Converte JSON string para Map |
+| `toBsonStrictMode(Object obj)` | String | Converte para BSON strict mode (MongoDB) |
+
+**Exemplos:**
+
+```java
+// Objeto para JSON
+HashMap data = new HashMap();
+data.put("name", "John");
+data.put("score", 100);
+String json = JsonUtil.toJson(data);
+// {"name":"John","score":100}
+
+// JSON para Map
+Map<String, Object> map = JsonUtil.fromJsonToMap("{\"name\":\"John\",\"score\":100}");
+String name = (String) map.get("name");
+
+// JSON para objeto tipado
+Player player = JsonUtil.fromJson(jsonString, Player.class);
+
+// Ignorar campos null
+String cleanJson = JsonUtil.toJsonRemoveNullFields(obj);
+```
+
+---
+
+## Guid
+
+**Classe:** `com.funifier.engine.guid.Guid`
+
+Geração de identificadores únicos.
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `newShortGuid()` | String | Gera ID único (MongoDB ObjectId, 24 chars) |
+| `shortTimeMillis()` | String | Gera código baseado no timestamp (base62, ~7 chars) |
+
+**Exemplos:**
+
+```java
+// Gerar ID para novo objeto
+String id = Guid.newShortGuid();
+// Ex: "64a5d92f1b2c3d4e5f6a7b8c"
+
+// Gerar código curto baseado no tempo (útil para códigos de convite)
+String code = Guid.shortTimeMillis();
+// Ex: "y6z3D6H"
+```
+
+**Quando usar cada um:**
+- `newShortGuid()` — Para IDs de objetos (achievements, action logs, etc.)
+- `shortTimeMillis()` — Para códigos legíveis (convites, vouchers, etc.)
+
+---
+
+## DateUtil
+
+**Classe:** `com.funifier.engine.util.DateUtil`
+
+Utilitário para cálculos e parsing de datas, incluindo as **expressões de data Funifier**.
+
+### Expressões de Data (Funifier Syntax)
+
+Formato: `[sinal][quantidade][unidade][ajuste]`
+
+**Unidades:** `y`=ano, `M`=mês, `w`=semana, `d`=dia, `h`=hora, `m`=minuto, `s`=segundo
+
+**Ajuste:** `-` = início da unidade (floor), `+` = fim da unidade (ceil), sem ajuste = exato
+
+| Expressão | Significado |
+|-----------|------------|
+| `-0d` | Agora |
+| `-0d-` | Início do dia atual (00:00:00) |
+| `-0d+` | Fim do dia atual (23:59:59) |
+| `-1d` | Exatamente 1 dia atrás |
+| `-1d-` | Início do dia anterior |
+| `-1d+` | Fim do dia anterior |
+| `+1d` | Exatamente 1 dia no futuro |
+| `+1d-` | Início do dia seguinte |
+| `-0w-` | Início da semana atual |
+| `-0w+` | Fim da semana atual |
+| `-0M-` | Primeiro dia do mês (00:00:00) |
+| `-0M+` | Último dia do mês (23:59:59) |
+| `-1M-` | Primeiro dia do mês anterior |
+| `-0y-` | 1 de janeiro do ano atual |
+| `-0y+` | 31 de dezembro do ano atual |
+
+**Encadeamento com `|`:**
+```
+-1d+|GMT+3            → fim do dia anterior no fuso GMT+3
+-0d-|+5h|+30m|GMT-3   → início do dia + 5h30m no fuso GMT-3
+```
+
+### Métodos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `fromKeyword(String keyword)` | Date | Converte expressão Funifier em Date |
+| `fromKeyword(String keyword, Date reference)` | Date | Converte com data de referência |
+| `fromKeyword(String keyword, Date reference, String timezone)` | Date | Converte com referência e timezone |
+| `fromKeywordPeriodExpression(String period)` | Date[] | Converte período (ex: "-0M-;-0M+") em [inicio, fim] |
+| `parse(Object date)` | Date | Parse genérico (Date, Long, String, expressão) |
+| `parse(String date, String pattern)` | Date | Parse com padrão SimpleDateFormat |
+| `format(Date date, String pattern)` | String | Formata data com padrão SimpleDateFormat |
+| `between(Date ref, int scale, int amount)` | Date[] | Intervalo [inicio, fim] da unidade |
+| `add(Date ref, int scale, int amount)` | Date | Adiciona unidades à data |
+| `reset(Date date, int scale)` | Date | Trunca data para o início da unidade |
+
+**Escalas (TimeScale):**
+```java
+TimeScale.MILLISECOND = 0;
+TimeScale.SECOND = 1;
+TimeScale.MINUTE = 2;
+TimeScale.HOUR = 3;
+TimeScale.DAY = 4;
+TimeScale.WEEK = 5;
+TimeScale.MONTH = 6;
+TimeScale.YEAR = 7;
+```
+
+**Exemplos:**
+
+```java
+// Usar expressões Funifier
+Date inicioMes = DateUtil.fromKeyword("-0M-");
+Date fimMes = DateUtil.fromKeyword("-0M+");
+Date ontem = DateUtil.fromKeyword("-1d");
+
+// Período completo
+Date[] periodo = DateUtil.fromKeywordPeriodExpression("-0M-;-0M+");
+Date inicio = periodo[0];
+Date fim = periodo[1];
+
+// Parse genérico
+Date d1 = DateUtil.parse("2023-07-05T20:57:33.303Z");
+Date d2 = DateUtil.parse("-1d");
+
+// Formatar data
+String formatted = DateUtil.format(new Date(), "dd/MM/yyyy HH:mm:ss");
+
+// Adicionar tempo
+Date amanha = DateUtil.add(new Date(), TimeScale.DAY, 1);
+Date mesPassado = DateUtil.add(new Date(), TimeScale.MONTH, -1);
+```
+
+> **Referência completa de expressões de data em consultas:** consulte `guides/aggregates.md`.
+
+---
+
+## Unirest
+
+**Biblioteca:** `com.mashape.unirest`
+
+Cliente HTTP para fazer requisições a APIs externas.
+
+**Exemplos:**
+
+```java
+// GET
+HttpResponse<String> response = Unirest.get("https://api.example.com/data")
+    .header("Authorization", "Bearer token123")
+    .asString();
+String body = response.getBody();
+int status = response.getStatus();
+
+// POST com JSON
+HashMap payload = new HashMap();
+payload.put("name", "John");
+payload.put("email", "john@email.com");
+
+HttpResponse<String> response = Unirest.post("https://api.example.com/users")
+    .header("Content-Type", "application/json")
+    .body(JsonUtil.toJson(payload))
+    .asString();
+
+// POST form
+HttpResponse<String> response = Unirest.post("https://api.example.com/form")
+    .field("username", "john")
+    .field("password", "secret")
+    .asString();
+
+// PUT
+HttpResponse<String> response = Unirest.put("https://api.example.com/users/1")
+    .header("Content-Type", "application/json")
+    .body(JsonUtil.toJson(payload))
+    .asString();
+
+// DELETE
+HttpResponse<String> response = Unirest.delete("https://api.example.com/users/1")
+    .asString();
+```
+
+---
+
+## EmailBuilder (SimpleJavaMail)
+
+**Biblioteca:** `org.simplejavamail`
+
+Envio de emails via SMTP.
+
+**Exemplos:**
+
+```java
+// Enviar email simples
+Email email = EmailBuilder
+    .startingBlank()
+    .from("Company", "noreply@company.com")
+    .to("John", "john@email.com")
+    .withSubject("Welcome!")
+    .withPlainText("Welcome to our platform!")
+    .buildEmail();
+
+MailerBuilder.withSMTPServer("smtp.host.com", 587, "login", "password")
+    .buildMailer()
+    .sendMail(email);
+
+// Email com HTML
+Email email = EmailBuilder
+    .startingBlank()
+    .from("Company", "noreply@company.com")
+    .to("John", "john@email.com")
+    .withSubject("Report")
+    .withHTMLText("<h1>Hello</h1><p>Your monthly report is ready.</p>")
+    .buildEmail();
+
+MailerBuilder.withSMTPServer("smtp.host.com", 587, "login", "password")
+    .buildMailer()
+    .sendMail(email);
+```
+
+---
+
+## Jongo (Acesso ao MongoDB)
+
+**Biblioteca:** `org.jongo`
+
+Acesso direto ao MongoDB através do objeto `database` (em triggers) ou `manager.getJongoConnection()`.
+
+### Operações
+
+```java
+// Obter coleção
+org.jongo.MongoCollection collection = database.getCollection("nome_colecao");
+
+// --- INSERT / UPDATE ---
+// Save (insere ou atualiza se _id existir)
+database.getCollection("email__c").save(hashMap);
+
+// --- FIND ---
+// Buscar um documento
+Object result = database.getCollection("player")
+    .findOne("{_id: 'john'}").as(Object.class);
+
+// Buscar com parâmetro (#)
+Object result = database.getCollection("product__c")
+    .findOne("{_id: #}", productId).as(Object.class);
+
+// Buscar vários
+Iterable<Object> results = database.getCollection("action_log")
+    .find("{userId: #}", "john").as(Object.class);
+
+// Buscar com projeção
+Object result = database.getCollection("player")
+    .findOne("{_id: #}", id)
+    .projection("{name: 1, email: 1}")
+    .as(Object.class);
+
+// --- DELETE ---
+database.getCollection("car__c").remove("{_id: 'car001'}");
+
+// --- COUNT ---
+long total = database.getCollection("action_log")
+    .count("{userId: #}", "john");
+
+// --- AGGREGATE ---
+Iterable<Object> result = database.getCollection("achievement")
+    .aggregate("{$match: {type: 0, item: 'xp'}}")
+    .and("{$group: {_id: '$player', total: {$sum: '$total'}}}")
+    .and("{$sort: {total: -1}}")
+    .and("{$limit: 10}")
+    .as(Object.class);
+```
+
+### Parâmetros com `#`
+
+O Jongo usa `#` como placeholder para parâmetros seguros (evita injection):
+
+```java
+// Um parâmetro
+database.getCollection("player").findOne("{_id: #}", playerId).as(Object.class);
+
+// Múltiplos parâmetros
+database.getCollection("action_log")
+    .find("{userId: #, actionId: #}", "john", "sell")
+    .as(Object.class);
+```
+
+> **Referência completa:** consulte `guides/database-access.md` e `guides/aggregates.md`.
+
+---
+
+## Resumo Rápido
+
+| Necessidade | O que usar |
+|------------|-----------|
+| Converter objeto para JSON | `JsonUtil.toJson(obj)` |
+| Converter JSON para objeto | `JsonUtil.fromJson(json, Class)` |
+| Gerar ID único | `Guid.newShortGuid()` |
+| Gerar código curto | `Guid.shortTimeMillis()` |
+| Calcular data com expressão | `DateUtil.fromKeyword("-0M-")` |
+| Fazer requisição HTTP | `Unirest.get/post/put/delete(url)` |
+| Enviar email | `EmailBuilder.startingBlank()...` |
+| Acessar MongoDB | `database.getCollection("nome")` |