@seedgrid/ai-toolkit 0.3.1 → 0.3.3

package/seedgridKB/SeedGrid/Produtos/Pulse/SDKs.md

@@ -0,0 +1,287 @@
+---
+tags: [seedgrid, produto, pulse, sdk, publisher, subscriber]
+fonte: seedgrid-products/seedgrid-pulse/components
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse — SDKs
+
+Dois lados independentes, cada um com sua credencial e seu transporte. Copie/instale **só o lado que precisa**. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · exemplos prontos: [[SeedGrid/Produtos/Pulse/Exemplos|Exemplos]].
+
+| | **Publisher** | **Subscriber** |
+|---|---|---|
+| Papel | publicar mensagens e emitir token curto | conectar, assinar, receber, `ack`/`result` |
+| Roda em | backend confiável (API, worker, job) | navegador, app, agente |
+| Credencial | chave **`project`** (`x-api-key`) 🔒 | token curto (`getToken`) **ou** chave `client` (agente) |
+| Transporte | REST `POST /api/v1/messages` | WebSocket (reconecta sozinho) |
+| Regra de ouro | a chave **nunca** vai ao cliente | **nenhuma** chave no navegador/app |
+
+## Publishers (`components/publishers/`)
+
+| Linguagem | Pacote / coordenada | Versão (manifesto) | Entrada |
+|---|---|---|---|
+| Java 17+ | `br.com.seedgrid:seedgrid-pulse-publisher` (Maven Central) | `2026.10.0` | `PulsePublisher.builder().baseUrl().projectKey().build()` |
+| Next.js (server-only) | `@seedgrid/pulse-publisher-next` | `2026.09.0` | `createPulsePublisher({ baseUrl, projectKey })` |
+| Dart | `seedgrid_pulse_publisher` | `2026.9.1` | `PulsePublisher.create(baseUrl:, projectKey:)` |
+| PHP | `seedgrid/pulse-publisher` (Composer) | — | `HttpPulsePublisher::create(baseUrl:, projectKey:)` |
+| Rust | `seedgrid-pulse-publisher-rust` | `0.2.0` | `PulsePublisher::builder(url, key).build()?` |
+| Delphi | fonte em `src/` (XE6+/FPC) | — | `NewPulsePublisher(url, key)` |
+
+Todos oferecem: `publish(...)` com helpers de destino (`toUser`, `toGroup`, `toAccount`, e grupo+usuário), `deliveryMode`, `deliveryPolicy`, `metadata` e `issueConnectToken(...)`.
+
+Java:
+
+```java
+PulsePublisher publisher = PulsePublisher.builder()
+    .baseUrl(System.getenv("PULSE_BASE_URL"))
+    .projectKey(System.getenv("PULSE_PROJECT_KEY"))
+    .build();
+
+publisher.publish(PublishMessageInput.toUser(
+    "orders", "order.updated", "usr_7f3a9c1e", Map.of("orderId", "o-1")));
+
+// rota autenticada do SEU backend, para o navegador:
+ConnectToken token = publisher.issueConnectToken(
+    new IssueConnectTokenInput(sessao.publicId(), Duration.ofMinutes(5), List.of("orders")));
+```
+
+Next.js:
+
+```ts
+import "server-only";
+import { createPulsePublisher, message } from "@seedgrid/pulse-publisher-next";
+
+export const pulse = createPulsePublisher({
+  baseUrl: process.env.PULSE_BASE_URL!,
+  projectKey: process.env.PULSE_PROJECT_KEY!, // nunca NEXT_PUBLIC_*
+});
+
+await pulse.publish(message.toUser("orders", "order.updated", usuario.publicId, { orderId }));
+const token = await pulse.issueConnectToken({ subject: usuario.publicId, ttlSeconds: 300 });
+```
+
+PHP:
+
+```php
+$publisher = HttpPulsePublisher::create(baseUrl: getenv('PULSE_BASE_URL'), projectKey: getenv('PULSE_PROJECT_KEY'));
+$publisher->publish(PublishMessageInput::toUser('orders', 'order.updated', 'usr_7f3a9c1e', ['orderId' => 'o-1']));
+```
+
+Dart:
+
+```dart
+final publisher = PulsePublisher.create(
+  baseUrl: Platform.environment['PULSE_BASE_URL']!,
+  projectKey: Platform.environment['PULSE_PROJECT_KEY']!,
+);
+final result = await publisher.publish(
+  PublishMessageInput.toUser('orders', 'order.updated', 'usr_7f3a9c1e', {'orderId': 'o-1'}),
+);
+print(result.messageId);
+publisher.close();
+```
+
+Rust:
+
+```rust
+let publisher = PulsePublisher::builder(base_url, project_key).build()?;
+let result = publisher
+    .publish(PublishMessageInput::to_user("orders", "order.updated", "usr_7f3a9c1e", json!({ "orderId": "o-1" })))
+    .await?;
+println!("{}", result.message_id);
+```
+
+Delphi:
+
+```pascal
+Config := TPulsePublisherConfig.Create(GetEnvironmentVariable('PULSE_BASE_URL'), GetEnvironmentVariable('PULSE_PROJECT_KEY'));
+Publisher := TPulsePublisher.Create(Config, TIndyPulseHttpTransport.Create); // Delphi moderno: transporte NetHttp
+R := Publisher.Publish(TPublishMessageInput.ToUser('orders', 'order.updated', 'usr_7f3a9c1e', '{"orderId":"o-1"}'));
+Writeln(R.MessageId);
+```
+
+Variáveis recomendadas no backend: `PULSE_BASE_URL`, `PULSE_PROJECT_KEY` 🔒. Os exemplos completos de cada SDK ficam em `examples/` (ou `example/`) da pasta do pacote.
+
+### Publicar com modo e política de entrega
+
+`deliveryMode` escolhe o ciclo de vida da mensagem e `deliveryPolicy` diz **como insistir** (tentativas, validade, espaçamento). Os dois são opcionais e independentes; o significado campo a campo está em [[SeedGrid/Produtos/Pulse/Protocolo-e-API#deliveryPolicy: campo a campo|Protocolo e API]]. Omitidos, vale `notification` e os padrões do servidor. Um job que o consumidor precisa **executar** usa `processed` (único modo com `result`, retry de execução e DLQ):
+
+Java:
+
+```java
+publisher.publish(PublishMessageInput.builder()
+    .channel("render").event("render.requested").toUser("agent:render-node-7")
+    .data(Map.of("jobId", "job_9f2"))
+    .deliveryMode(DeliveryMode.PROCESSED)
+    .deliveryPolicy(DeliveryPolicy.builder()
+        .maxAttempts(5).ttlSeconds(300).resultTimeoutSeconds(120)
+        .retryBaseMs(200).retryMaxMs(2000)
+        .retryStrategy(RetryStrategy.EXPONENTIAL)
+        .build())
+    .build());
+```
+
+Next.js:
+
+```ts
+await pulse.publish({
+  channel: "render",
+  event: "render.requested",
+  target: { user: "agent:render-node-7" },
+  data: { jobId: "job_9f2" },
+  deliveryMode: "processed",
+  deliveryPolicy: { maxAttempts: 5, ttlSeconds: 300, resultTimeoutSeconds: 120, retryBaseMs: 200, retryMaxMs: 2000, retryStrategy: "exponential" },
+  metadata: { correlationId: "report-4471", source: "report-api" },
+});
+```
+
+PHP:
+
+```php
+$input = PublishMessageInput::toUser('render', 'render.requested', 'agent:render-node-7', ['jobId' => 'job_9f2'])
+    ->withDeliveryMode(DeliveryMode::Processed)
+    ->withDeliveryPolicy(new DeliveryPolicy(
+        maxAttempts: 5, ttlSeconds: 300, retryBaseMs: 200, retryMaxMs: 2000,
+        retryStrategy: RetryStrategy::Exponential,
+        resultTimeoutSeconds: 120, // último parâmetro do construtor
+    ))
+    ->withMetadata(new Metadata(correlationId: 'report-4471', source: 'report-api'));
+$publisher->publish($input);
+```
+
+Dart:
+
+```dart
+await publisher.publish(
+  PublishMessageInput.toUser('render', 'render.requested', 'agent:render-node-7', {'jobId': 'job_9f2'})
+      .withDeliveryMode(DeliveryMode.processed)
+      .withDeliveryPolicy(const DeliveryPolicy(
+        maxAttempts: 5, ttlSeconds: 300, retryBaseMs: 200, retryMaxMs: 2000,
+        retryStrategy: RetryStrategy.exponential,
+        resultTimeoutSeconds: 120,
+      ))
+      .withCorrelationId('report-4471'),
+);
+```
+
+Rust:
+
+```rust
+publisher.publish(
+    PublishMessageInput::to_user("render", "render.requested", "agent:render-node-7", json!({ "jobId": "job_9f2" }))
+        .with_delivery_mode(DeliveryMode::Processed)
+        .with_delivery_policy(DeliveryPolicy {
+            max_attempts: Some(5),
+            ttl_seconds: Some(300),
+            result_timeout_seconds: Some(120),
+            retry_base_ms: Some(200),
+            retry_max_ms: Some(2000),
+            retry_strategy: Some(RetryStrategy::Exponential),
+        }),
+).await?;
+```
+
+Delphi (campo `0`/`rsUnset` = omitir):
+
+```pascal
+Policy := TDeliveryPolicy.Empty;
+Policy.MaxAttempts := 5;
+Policy.TtlSeconds := 300;
+Policy.ResultTimeoutSeconds := 120;
+Policy.RetryBaseMs := 200;
+Policy.RetryMaxMs := 2000;
+Policy.RetryStrategy := rsExponential;
+R := Publisher.Publish(TPublishMessageInput.ToUser('render', 'render.requested', 'agent:render-node-7', '{"jobId":"job_9f2"}')
+  .WithDeliveryMode(dmProcessed)
+  .WithDeliveryPolicy(Policy));
+```
+
+Valores inválidos (`0`, `retryMaxMs < retryBaseMs`, estratégia desconhecida) voltam como **422** `INVALID_MESSAGE_REQUEST` e viram a exceção de validação do SDK (por exemplo `PulseValidationException`). Valores acima dos tetos do servidor **não** dão erro: são reduzidos ao teto.
+
+`resultTimeoutSeconds` (SDKs a partir do Pulse 0.3.0) é o prazo, em segundos, para o consumidor devolver o `result` depois do `ack`; só vale com `processed`. Omitido, vale o padrão do servidor (`0` = sem prazo). Cuidado: um prazo curto reentrega a tarefa ainda em execução, então use um valor maior que o pior caso e deduplique por `messageId`. Os SDKs não validam o valor (o servidor responde 422 para `0`). Notas por linguagem: PHP recebe o parâmetro **no fim** do construtor de `DeliveryPolicy`; no Rust, literais de `DeliveryPolicy` precisam do campo (ou `..Default::default()`); no Delphi, `ResultTimeoutSeconds = 0` omite o campo; no Java o construtor antigo continua existindo. Semântica completa: [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]].
+
+## Subscribers (`components/subscribers/`)
+
+| Plataforma | Pacote | Versão | Camada de framework |
+|---|---|---|---|
+| React / JS | `@seedgrid/pulse-subscriber-react` (npm) | `3.0.0` | hook `usePulseSubscriber` + core `PulseSubscriberClient` |
+| Angular 17+ | `@seedgrid/pulse-subscriber-angular` | `2.0.0` | `PulseSubscriberService` (Observables) + `providePulseSubscriber()` |
+| Flutter / Dart | `seedgrid_pulse_subscriber` | `2.0.0` | streams `states`, `messages` |
+| Rust | `seedgrid-pulse-subscriber-rust` | `0.2.0` | callbacks `on_message`, `on_state_change` |
+| Delphi | fonte em `src/` (Indy) | — | `IPulseSubscriber` (`NewPulseSubscriberIndy`) |
+
+Capacidades comuns: autenticação **só no handshake**; reconexão automática (backoff com jitter); **replay** do backlog ao reconectar (a assinatura é reenviada); `ack` (recebimento) e `reportResult` (execução); deduplicação por `messageId` opcional; `auth-error` ao receber `4403` (sem reconectar).
+
+> **Paridade (Confirmado — comparação dos SDKs em 2026-10):** `unsubscribe`, listas `subscribedChannels/Groups` e `autoAck` existem em React, Flutter e Delphi. O **Angular ainda não os tem** (guarda só a última assinatura); o exemplo Angular contorna isso.
+
+### React
+
+```tsx
+const { messages, connectionState, ack } = usePulseSubscriber({
+  getToken: async () => (await fetch("/api/realtime/connect", { method: "POST" })).json(),
+  subscription: { channels: ["orders"], groups: ["tenant:15"] },
+});
+```
+
+### Angular
+
+```ts
+providePulseSubscriber(() => {
+  const http = inject(HttpClient);
+  return {
+    getToken: () => firstValueFrom(http.post<PulseConnectToken>("/api/realtime/connect", {})),
+    subscription: { channels: ["orders"] },
+  };
+});
+// componente: inject(PulseSubscriberService).messages$ / state$ / ack({ messageId })
+```
+
+### Flutter
+
+```dart
+final subscriber = PulseSubscriber();
+subscriber.messages.listen((m) async { if (m.requiresAck) await subscriber.ack(AckInput(m.messageId)); });
+await subscriber.connect(ConnectInput(getToken: () async => PulseConnectToken.fromJson(await meuBackend.post('/api/realtime/connect'))));
+await subscriber.subscribe(const SubscribeInput(channels: ['orders']));
+```
+
+### Rust (agente, chave `client`)
+
+```rust
+let subscriber = PulseSubscriber::new();
+subscriber.on_message(|m| println!("{} em {}", m.event, m.channel));
+subscriber.connect(ConnectInput::new("http://localhost:18080", "<chave client>")).await?;
+subscriber.subscribe(SubscribeInput::channels(["orders"])).await?;
+```
+
+### Delphi
+
+```pascal
+FSub := NewPulseSubscriberIndy;
+FSub.UseAutoAck(True);
+FSub.OnMessage(App.OnMsg);
+FSub.Connect(TConnectInput.CreateWithToken(App.BuscarToken)); // ou TConnectInput.Create(url, chaveClient)
+FSub.Subscribe(TSubscribeInput.ForChannels(['orders']));
+```
+
+## Fluxo de ponta a ponta (navegador)
+
+```text
+ navegador ──(sessão)──▶ POST /api/realtime/connect   [rota do SEU backend]
+                                   │ issueConnectToken(subject = usuário da sessão)  [chave project]
+                                   ▼
+ navegador ◀── { token, expiresAt, connectUrl }
+ navegador ──WebSocket (access_token=pct_…)──▶ Pulse ──▶ message / ack / result
+```
+
+## Ack × result
+
+- `ack` confirma o **recebimento**; `result` informa o **resultado de execução** (`success`/`retryable`/`permanent`).
+- Só mensagens `processed` esperam `result`; em `notification`/`acknowledged` o servidor o recusa com `result_not_applicable`. Com `autoAck`/auto-ack nos SDKs que o têm, o SDK envia `ack` e, para `processed`, `result:success` depois que o seu handler retorna sem erro.
+- Entrega é at-least-once: **deduplique por `messageId`**.
+
+## Instalação a partir do fonte
+
+Nem todos os SDKs estão em registro público (Confirmado nos commits: Java em Maven Central, React no npm). Para os demais use dependência por caminho/cópia do fonte, como fazem os [[SeedGrid/Produtos/Pulse/Exemplos|exemplos]] (ex.: Flutter com `path: sdk/subscriber`). Cada SDK traz `INSTALLATION.md`, `CONFIGURATION.md`, `SECURITY.md`, `TROUBLESHOOTING.md` e `TESTING.md`.

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Configuracao.md

@@ -0,0 +1,128 @@
+---
+tags: [seedgrid, produto, pulse, servidor, configuracao, variaveis]
+fonte: seedgrid-products/seedgrid-pulse/backend (src/config.rs, env.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — variáveis de ambiente
+
+Todas as variáveis do **servidor**. As da UI estão em [[SeedGrid/Produtos/Pulse/UI/Configuracao|Configuração da UI]]. Arquitetura atual: **login-tenancy, banco único** — a separação entre clientes é lógica, por `company_id`. Sem `POSTGRES_URL` o servidor sobe em modo memória/dev com a plataforma desabilitada.
+
+Convenção: 🔒 = segredo (nunca em repositório/log); valores de exemplo são placeholders, **não** padrões.
+
+## Runtime (HTTP, WebSocket, CORS)
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `HTTP_HOST` | `127.0.0.1` | IP de bind. Em container use `0.0.0.0`. |
+| `HTTP_PORT` | `8080` | Porta HTTP. |
+| `WS_PATH` | `/ws` | Path do WebSocket legado (o endpoint do protocolo é `/api/v1/connect`). |
+| `CORS_ALLOWED_ORIGINS` | vazio | Lista separada por vírgula. Vazio = nenhuma origem liberada. |
+| `WS_HEARTBEAT_INTERVAL_SECONDS` | `30` | Heartbeat do WebSocket. |
+| `WS_IDLE_TIMEOUT_SECONDS` | `90` | Fecha conexão ociosa. |
+
+## Credenciais do Pulse 🔒
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_SERVER_KEY` | — | Chave **administrativa** (contas/chaves, métricas) em `x-api-key`. **Não publica** (403). Só em ENV; fica só com a operação do Pulse. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` | — | Segredo HMAC-SHA256 que assina o token curto de conexão. Sem ele, `POST /api/v1/connect-tokens` responde 503. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_PREVIOUS_SECRET` | — | Segredo anterior, aceito só na verificação (rotação sem derrubar tokens válidos). |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_TTL_SECS` | `300` | Validade do token quando o pedido não informa `ttlSeconds`. É a janela para **conectar**. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_MAX_TTL_SECS` | `900` | Teto: pedido acima → 422. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_KEY` | `600` | Emissões/min por chave `project`; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_SUBJECT` | `30` | Emissões/min por `subject` na mesma chave; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_PUBLIC_WS_URL` | — | Endereço **público** do WebSocket devolvido em `connectUrl`. Ausente = campo omitido. |
+
+Quem usa cada credencial: [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]].
+
+## Persistência e mensageria
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `POSTGRES_URL` | — | **Interruptor da plataforma.** Sem ela, security/login-tenancy/audit/apikeys ficam desligados. 🔒 |
+| `POSTGRES_RUN_MIGRATIONS` | `true` | Roda migrations na subida. |
+| `DELIVERY_STORE_BACKEND` | `memory` | `memory` \| `postgres`. Em produção, `postgres`. |
+| `BROKER_PROVIDER` | `memory` | `memory` \| `redis` \| `nats` \| `rabbitmq` (fallback `EVENT_BUS_BACKEND`). Valor desconhecido cai em `memory`. Detalhes e variáveis por provider: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]. |
+| `PRESENCE_BACKEND` | `memory` | `memory` \| `redis`. Multi-réplica ⇒ `redis`. |
+| `BROKER_REDIS_URL` | — | URL Redis-compatível (fallback `REDIS_URL`). 🔒 |
+| `BROKER_REDIS_CHANNEL` | `seedgrid:pulse:events` | Canal pub/sub (fallback `REDIS_PUBSUB_CHANNEL`). |
+| `BROKER_NATS_URL` | — | URL do NATS (`nats://host:4222`; fallback `NATS_URL`). Obrigatória com `nats`. 🔒 |
+| `BROKER_NATS_SUBJECT` | `seedgrid.pulse.events` | Subject do pub/sub. |
+| `BROKER_RABBITMQ_URL` | — | URL AMQP (fallbacks `RABBITMQ_URL`, `AMQP_URL`). Obrigatória com `rabbitmq`. 🔒 |
+| `BROKER_RABBITMQ_EXCHANGE` | `seedgrid.pulse.events` | Exchange fanout. |
+
+As URLs Redis-compatíveis servem para Valkey e Dragonfly sem mudar mais nada; ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+
+## Entrega (retry, TTL, limpeza)
+
+Os pares `*_CAP` são o **teto** que uma configuração por mensagem pode pedir; omitidos, assumem o valor base. Todos (exceto o intervalo de limpeza) são editáveis em runtime em **Configurações**.
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `DELIVERY_RETRY_STRATEGY` | `exponential` | `exponential` (qualquer outro valor = `fixed`: atraso constante de `DELIVERY_RETRY_BASE_MS`). |
+| `DELIVERY_RETRY_BASE_MS` | `300` | Backoff base. |
+| `DELIVERY_RETRY_MAX_MS` | `5000` | Backoff máximo. |
+| `DELIVERY_MAX_ATTEMPTS` | `20` | Tentativas de execução por mensagem (modo `processed`). |
+| `DELIVERY_TTL_SECONDS` | `86400` | TTL da mensagem (1 dia). |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS` | `0` (sem prazo) | **Prazo de execução** padrão (modo `processed`): segundos entre o `ack` e o `result`. `0` desliga. Estourado, vale como `retryable` com motivo `result_timeout`. Editável em Configurações, sem reinício. |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP` | `86400` (ou o padrão, se maior) | Teto do prazo que o publisher pode pedir; `0` **proíbe** o prazo de execução. |
+| `DELIVERY_RETRY_BASE_MS_CAP` / `DELIVERY_RETRY_MAX_MS_CAP` / `DELIVERY_MAX_ATTEMPTS_CAP` / `DELIVERY_TTL_SECONDS_CAP` | = valor base | Tetos para o override por mensagem. |
+| `DELIVERY_CLEANUP_INTERVAL_SECONDS` | `60` | Intervalo da varredura de retenção (`DELIVERY_CLEANUP_RETENTION_DAYS`) e da limpeza automática da lixeira. **Não** controla a expiração por TTL, que tem verificador próprio (a cada `ceil(DELIVERY_RETRY_BASE_MS/1000)` s, mínimo 1 s). Exige reinício. |
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` (nunca apaga) | **Dias** que uma mensagem em estado final (`completed`/`dead_letter`/`expired`) é mantida. `0` desliga a varredura: o histórico é prova. Obsoleta: `DELIVERY_CLEANUP_RETENTION_SECONDS` (lida só se a de dias não existir). |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` (só manual) | Dias na lixeira antes da limpeza automática. Cada limpeza vai ao audit como `system:pulse`. |
+
+Detalhes e as regras de lixeira: [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].
+
+## Security (login, JWT, RBAC)
+
+Habilitado com `POSTGRES_URL` **e** as chaves RSA. Nomes alinhados à extension Java `security` ([[SeedGrid/Extensions/security/Configuracao|Configuração do security]]).
+
+| Variável | Descrição |
+|---|---|
+| `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` | Caminhos do par RSA (primários). 🔒 |
+| `SECURITY_JWT_PRIVATE_KEY_PEM` / `SECURITY_JWT_PUBLIC_KEY_PEM` | PEM inline (secundário). 🔒 |
+| `SECURITY_JWT_ISSUER` / `SECURITY_JWT_KID` | Issuer e `kid` do JWT. |
+| `SECURITY_JWT_TTL` | Validade do access token, ISO-8601 (`PT8H`). |
+| `SECURITY_REFRESH_TOKEN_TTL` | Validade do refresh token (`P30D`). |
+| `SECURITY_PASSWORD_MIN_SIZE` / `_EXPIRATION_DAYS` / `_MAX_HISTORY` | Política de senha. |
+| `SECURITY_ENCRYPTION_KEY` | AES-256 (base64) da cripto de campo; obrigatória se usar TOTP. 🔒 |
+| `SECURITY_FRONTEND_BASE_URL` | Base da UI nos links de e-mail. |
+| `SEEDGRID_SECURITY_FIRST_ADMIN_USER_EMAIL` / `_NAME` / `_INITIAL_PASSWORD` | Bootstrap do primeiro admin. 🔒 |
+| `SEEDGRID_SECURITY_DEFAULT_COMPANY_CNPJ` / `_CORPORATE_NAME` / `_TRADE_NAME` | Company da plataforma (razão social e fantasia são obrigatórias no bootstrap). |
+
+### 2FA
+
+Desligado por padrão. `SEEDGRID_SECURITY_2F_ENABLED=true` liga; `_ALLOWED_METHODS` (`EMAIL,TOTP`), `_DEFAULT_METHOD` (`TOTP`), `_EMAIL_CODE_TTL`, `_SESSION_TTL`, `_VERIFY_MAX_ATTEMPTS` (5), `_TOTP_ISSUER` (`SeedGrid`; vale trocar para `SeedGrid Pulse`), `_TOTP_DIGITS` (6), `_TOTP_PERIOD` (30), `_TOTP_WINDOW` (1), `_BACKUP_CODES_COUNT` (10). WhatsApp: `SEEDGRID_SECURITY_2F_WHATSAPP_CHANNEL_ID` mais um provider em `SEEDGRID_WHATSAPP_API` (`evolution`/`cloud`) com credenciais ([[SeedGrid/Extensions/whatsapp/Configuracao|whatsapp]]).
+
+### E-mail (SMTP)
+
+`SECURITY_MAILER_USERNAME` e `_PASSWORD` ligam o SMTP real (🔒); `_HOST` (`smtp.gmail.com`), `_PORT` (587), `_START_TLS` (`REQUIRED`), `_FROM`. **Sem usuário e senha o e-mail só vai para o log** — confirmação, reset de senha e 2FA por e-mail não chegam.
+
+## Login-tenancy
+
+`SEEDGRID_LOGIN_TENANCY_APP_CODE` (`seedgrid-app`; use `seedgrid-pulse`), `_APP_NAME`, `_DATABASE_MIGRATE_AT_START` (`true`), `_DATABASE_BASELINE_ON_MIGRATE` (`true`), `_FOUNDATION_STATUS_ENABLED`, `_FOUNDATION_HEALTH_ENABLED`, `_BOOTSTRAP_ENABLED`, `_BOOTSTRAP_ADMIN_ENABLED`. Não existe flag "enabled": a dependência ativa o baseline. `SEEDGRID_SHOW_DEV_MESSAGE` (`false`) inclui detalhe interno nos erros — **nunca em produção**. Ver [[SeedGrid/Extensions/login-tenancy/Configuracao|login-tenancy]].
+
+## Audit
+
+`SEEDGRID_AUDIT_ENABLED` (`true`), `AUDIT_STRATEGY` (`JPA` = Postgres \| `MONGODB`), `SEEDGRID_AUDIT_DB_*` só para banco de auditoria separado, `SEEDGRID_AUDIT_MONGODB_URI`/`_DATABASE`. No deploy padrão as migrations de audit rodam no mesmo banco. A leitura é escopada por `company_id` via headers internos sobrescritos pelo JWT — não os repasse de proxy. Ver [[SeedGrid/Extensions/audit/Configuracao|audit]].
+
+## API keys
+
+`SEEDGRID_APIKEYS_PREFIX_LENGTH` (`8`), `SEEDGRID_APIKEYS_KEY_BYTES` (`32`). Ver [[SeedGrid/Extensions/apikeys/Configuracao|apikeys]].
+
+## Observabilidade
+
+`RUST_LOG` (ex.: `info`). Métricas: `GET /metrics` (JSON) e `GET /metrics/prometheus`; Prometheus e Grafana vêm no compose.
+
+## Variáveis removidas (não configure)
+
+As de multitenancy por subdomínio (`DOMAIN_SUFFIX`, `SEEDGRID_MULTITENANCY_*`, `PRODUCT_PREFIX`, `MULTITENANCY_MAILER_*`) foram eliminadas e são ignoradas. Backup (`BACKUP_*`) e billing (`SEEDGRID_BILLING_*`) não se aplicam ao Pulse hoje.
+
+## Pegadinhas
+
+- A chave de servidor nunca vai para produto nenhum nem para o serviço da UI.
+- Variável definida no EasyPanel **vence** o padrão de código: ao mudar um padrão, confira o ambiente.
+- `0` em retenção/limpeza significa **desligado** (não "apagar tudo").

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Instalacao.md

@@ -0,0 +1,105 @@
+---
+tags: [seedgrid, produto, pulse, servidor, instalacao, deploy]
+fonte: seedgrid-products/seedgrid-pulse/backend
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — instalação e execução
+
+O **servidor Pulse** é o backend Rust (Axum): API REST, WebSocket, entrega, retry, DLQ, presença e módulos de plataforma. A UI é outro componente: [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Pulse UI]].
+
+Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]] · brokers: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers (Redis, Valkey, Dragonfly, NATS, RabbitMQ)]]
+
+## Modos de execução
+
+| Modo | Quando | Persistência |
+|---|---|---|
+| **Memória** (sem `POSTGRES_URL`) | desenvolvimento rápido, testes | nenhuma; plataforma (login, audit, apikeys) **desabilitada** — só o núcleo realtime |
+| **Postgres** | produção de instância única | mensagens, contas, usuários, audit |
+| **Distribuído** | várias réplicas | Postgres + broker pub/sub + presença em Redis |
+
+Exemplos de `env` (Confirmado — `backend/README.md`):
+
+```env
+# simples
+BROKER_PROVIDER=memory
+PRESENCE_BACKEND=memory
+DELIVERY_STORE_BACKEND=memory
+
+# com Postgres
+DELIVERY_STORE_BACKEND=postgres
+POSTGRES_URL=postgres://<user>:<senha>@<host>:5432/<db>
+
+# distribuído
+BROKER_PROVIDER=redis
+PRESENCE_BACKEND=redis
+DELIVERY_STORE_BACKEND=postgres
+BROKER_REDIS_URL=redis://<host>:6379/0
+```
+
+## Subir com Docker/Podman Compose
+
+Em `backend/`:
+
+```bash
+docker compose up -d --build
+```
+
+Sobe `postgres`, `redis`, `seedgrid-pulse`, `prometheus`, `grafana` e `seedgrid-pulse-ui`. Portas locais (Confirmado — `docker-compose.yml`): API `18080`, Prometheus `19090`, Grafana `13001`, UI `13000`.
+
+O compose de desenvolvimento traz valores de exemplo (chave de servidor, segredo do token, admin inicial). **Troque todos** em qualquer ambiente real. 🔒
+
+## Rodar a partir do fonte
+
+Pré-requisitos: Rust estável recente (edition 2024) e o repositório de crates da plataforma clonado ao lado (path dependencies).
+
+```text
+<raiz>/
+├─ seedgrid-platform/rust/              # crates seedgrid-rust-crate-*
+└─ seedgrid-products/seedgrid-pulse/    # este repo
+```
+
+O prefixo `../../../seedgrid-platform/rust/` está em `backend/Cargo.toml`; ajuste-o se o layout for outro.
+
+```bash
+cd backend
+docker compose up -d postgres redis
+cargo run
+```
+
+O build não precisa de banco (não há `sqlx::query!` verificada em compilação).
+
+## Primeiro acesso
+
+Com `POSTGRES_URL` e o par RSA do JWT, o boot roda as migrations e cria a company da plataforma e o **primeiro admin** a partir de `SEEDGRID_SECURITY_FIRST_ADMIN_USER_*` e `SEEDGRID_SECURITY_DEFAULT_COMPANY_*` ([[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]]). Entre na UI com esse admin, crie a **conta** do seu produto e as **chaves** (Contas → conta → Chaves → Nova chave). O segredo da chave aparece **uma única vez**.
+
+Par RSA do JWT (exemplo):
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
+openssl rsa -pubout -in private.pem -out public.pem
+```
+
+Aponte `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` (ou use PEM inline).
+
+## Imagem e deploy
+
+- Imagem no GHCR: `ghcr.io/seedgrid/seedgrid-pulse-backend` (Confirmado — `.github/workflows/deploy.yml`).
+- `push` em `main` dispara o workflow, que detecta o que mudou, publica a imagem e chama o webhook do EasyPanel (secret `EASYPANEL_DEPLOY_URL_PULSE_BACKEND`). Commit só de documentação **não** redeploya.
+- O container escuta `8080`; use `HTTP_HOST=0.0.0.0` em container.
+- Probes: liveness `GET /health`, readiness `GET /ready` (200/503 com o estado de store, broker e presença).
+- Migrations rodam no boot (`POSTGRES_RUN_MIGRATIONS`, padrão `true`).
+
+## Checklist de produção
+
+- [ ] `POSTGRES_URL` + `DELIVERY_STORE_BACKEND=postgres`.
+- [ ] Mais de uma réplica ⇒ broker pub/sub (`redis`, ou `nats`/`rabbitmq` — ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]) **e** `PRESENCE_BACKEND=redis`.
+- [ ] `SEEDGRID_PULSE_SERVER_KEY` e `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` longos e aleatórios, só em ENV. 🔒
+- [ ] `SEEDGRID_PULSE_PUBLIC_WS_URL` com o endereço público do WebSocket (`wss://…`), se há clientes de navegador.
+- [ ] `CORS_ALLOWED_ORIGINS` com a origem da UI.
+- [ ] Par RSA do JWT próprio; admin inicial trocado.
+- [ ] `SEEDGRID_SHOW_DEV_MESSAGE` desligado (padrão).
+- [ ] Proxy reverso **não** repassa `x-seedgrid-company-id` / `x-seedgrid-all-companies` vindos do cliente.
+- [ ] Retenção do histórico decidida (padrão: nunca apagar) — [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Operacao.md

@@ -0,0 +1,86 @@
+---
+tags: [seedgrid, produto, pulse, servidor, operacao, lixeira, retencao]
+fonte: seedgrid-products/seedgrid-pulse/backend (docs/LIXEIRA-mensagens-e-contas.md, README.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — operação
+
+Lixeira, retenção, auditoria, observabilidade e escala. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]].
+
+## Princípios
+
+- O **histórico de entregas é prova**: por padrão **nunca é apagado sozinho**.
+- Apagar é **sempre ação humana**, com permission própria, confirmação na UI e **audit** (quem, o quê, quantos).
+- A chave de servidor **não apaga nada** (401): toda exclusão tem um autor.
+
+## Lixeira de mensagens
+
+- **Só mensagens `pending`** podem ir para a lixeira (mensagens entregues/processadas são histórico; só saem com a exclusão da conta).
+- Na UI: **Mensagens**, filtro de status **"Na lixeira"**. Mover (`PULSE_MESSAGE_DELETE`), restaurar (volta a `pending`) e limpar de vez (`PULSE_MESSAGE_PURGE`, apaga também as entregas por destinatário).
+- API: `POST /api/v1/messages/trash` · `/trash/restore` · `/trash/purge`, lote de até **1000** ids (`400 BATCH_TOO_LARGE`), resposta `{requested, affected, skipped}`.
+- Mensagem na lixeira não é entregue, não expira por TTL e some das listas padrão.
+- **Descartar** (tela Pendências, `PULSE_BACKLOG_DISCARD`) e **Lixeira** coexistem como ações distintas; só a lixeira tem restaurar e limpar de vez.
+- Tarefas `delivered` sem `result` e sem prazo de execução (as anteriores ao Pulse 0.3.0, ou quando `resultTimeoutSeconds` não foi usado) só saem por **descarte**; veja [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]].
+
+## Lixeira de contas
+
+- A lixeirinha da lista de contas pede confirmação e leva a conta para `pending_delete` (`PULSE_ACCOUNT_DELETE`). A conta **deixa de autenticar** e suas conexões são derrubadas.
+- **Lixeira de contas** (menu): restaurar (volta ao status anterior) ou **apagar definitivamente** (`PULSE_ACCOUNT_PURGE`), que remove a conta, suas chaves e **todas as suas mensagens** em cascata. O diálogo mostra antes quantas chaves e mensagens saem (`GET /accounts/{id}/deletion-summary`).
+- O apagar definitivo **não é uma transação única**: mensagens primeiro, conta por último. Se falhar no meio, a conta continua na lixeira e dá para repetir.
+
+## Retenção e limpeza automática
+
+| Variável | Padrão | Efeito |
+|---|---|---|
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` | Dias que uma mensagem **final** (`completed`/`dead_letter`/`expired`) é mantida. `0` = **nunca apaga**. |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` | Dias na lixeira antes de apagar sozinho. `0` = só manual. Cada limpeza vai ao audit como `system:pulse`. |
+
+As duas **não se sobrepõem**: a primeira atua no histórico (estados finais), a segunda na lixeira (`trashed`). Mensagens `pending` e `delivered` nunca são limpas pela retenção. A obsoleta `DELIVERY_CLEANUP_RETENTION_SECONDS` só vale se a de dias não existir. Ambas são editáveis em **Configurações**, sem redeploy.
+
+> **Mudança de comportamento (2026-10-15):** o padrão era 7 dias e `0` apagava tudo. Ambientes que definem a variável explicitamente (EasyPanel) mantêm o valor definido.
+
+Sem consumidor, uma `pending` não fica para sempre: o TTL (`DELIVERY_TTL_SECONDS`, 1 dia) a expira.
+
+## Ordem das listas e paginação
+
+As telas listam **da mais recente para a mais antiga** (quem acabou de publicar vê a sua primeira): contas por `created_at`, mensagens por `published_at` e entregas por destinatário por `delivered_at`, todas **com desempate por id**. A paginação é 1-based (`page`, `pageSize`; a Auditoria usa `page`/`size` e o backend dela é base 0, convertido pela UI). Até o Pulse 0.2.1 a lista de contas ordenava sem desempate, e contas criadas no mesmo segundo repetiam ou sumiam entre páginas (corrigido no 0.2.2). O **replay** e as pendências devidas continuam em ordem cronológica (do mais antigo ao mais novo), porque entregar na ordem de publicação é o comportamento certo (Confirmado em `delivery/repo.rs`).
+
+## Auditoria
+
+Toda operação destrutiva (mover para lixeira, restaurar, limpar; contas e mensagens) grava em `audit_log` o autor (claim `sub` do JWT, e-mail na descrição), a ação e as contagens, **somente se algo mudou**. Visível em **Segurança → Auditoria** (escopo por `company_id`).
+
+## Observabilidade
+
+| O quê | Onde |
+|---|---|
+| Liveness / readiness | `GET /health` · `GET /ready` (200 `READY` / 503 `NOT_READY`, com store, broker e presença) |
+| Métricas | `GET /metrics` (JSON) · `GET /metrics/prometheus` |
+| Dashboards | Prometheus + Grafana no compose (`SeedGrid Pulse Overview`) |
+| Telas | dashboard, conexões, backlog, DLQ, mensagens, entregas por destinatário |
+
+Métricas úteis: `publish_requests_total`, `delivery_attempts_total`, `delivery_success_total`, `delivery_dead_letter_total`, `delivery_expired_total`, `delivery_result_timeout_total` (prazo de execução estourado), `ack_total`, `ws_connections_opened_total`/`_closed_total`, latências `publish_to_deliver_*` e `deliver_to_ack_*`.
+
+## Escala (várias réplicas)
+
+- Estado durável no **Postgres** (`DELIVERY_STORE_BACKEND=postgres`).
+- Entrega entre instâncias via **broker pub/sub** (`BROKER_PROVIDER`) e presença em Redis (`PRESENCE_BACKEND=redis`): ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+- Revogação de credencial atravessa o broker (tópico `pulse.revocations`) e derruba as conexões em **todas** as instâncias.
+- Limites de emissão de token são **por instância**: com N réplicas o efetivo é até N vezes.
+
+## Diagnóstico rápido
+
+| Sintoma | Verifique |
+|---|---|
+| Publicou e ninguém recebeu | `accountId`/conta ativa; `channel` e `event` batem com o `subscribe`; `user` do destino = `subject` da conexão; entrega fica `pending` até alguém conectar |
+| 403 ao publicar | está usando chave `client` ou a chave de servidor; use a `project` |
+| WebSocket 401 | credencial ausente/revogada; token `pct_` vencido antes de conectar |
+| Conexão fecha com `4403` | chave/conta revogada: não reconecte com a mesma credencial |
+| `connect-tokens` 503 | falta `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` |
+| E-mail/2FA por e-mail não chega | `SECURITY_MAILER_USERNAME`/`_PASSWORD` ausentes (só loga) |
+| Histórico "sumiu" | retenção definida no ambiente (`DELIVERY_CLEANUP_RETENTION_*`) |
+| Réplica B não recebe o que A publicou | broker `memory` em produção multi-réplica |
+
+Testes e CI: `cargo test` (unitários e e2e); com Docker/Podman, `cargo test redis_ -- --ignored`, `postgres_ -- --ignored` e `--test trash_integration -- --ignored --test-threads=1` sobem Postgres/Redis via testcontainers.