funifier-mcp 0.1.0 → 0.2.3

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

@@ -0,0 +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")` |