> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triglit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nodes

> Entenda os nodes do Triglit e como criar automações com unidades de ação

**Nodes** são unidades de ação dentro de um workflow. Cada node executa uma tarefa específica e pode passar dados para os próximos nodes através do contexto de execução.

## O que é um Node?

Um node é uma unidade de processamento que:

* Recebe dados do contexto de execução
* Executa uma ação específica
* Pode modificar o contexto
* Pode pausar a execução (nodes pausáveis)
* Retorna um resultado que é adicionado ao contexto

## Estrutura de um Node

```json theme={null}
{
  "id": "node-1",
  "type": "transform",
  "config": {
    "transformType": "expression",
    "expression": "input.value * 2"
  },
  "position": {
    "x": 100,
    "y": 200
  }
}
```

### Propriedades

* **`id`**: Identificador único do node no workflow
* **`type`**: Tipo do node (ex: `transform`, `condition`, `input`)
* **`config`**: Configuração específica do tipo de node
* **`position`**: Posição no editor visual (opcional)

## Nodes Built-in

### Input Node

Aguarda entrada do usuário ou sistema externo.

```json theme={null}
{
  "type": "input",
  "config": {
    "prompt": "Digite seu nome:",
    "inputType": "text",
    "required": true,
    "timeoutMs": 300000
  }
}
```

**Características:**

* ⏸️ **Pausável**: Para a execução até receber entrada
* 🔄 **Retomável**: Execução pode ser retomada com dados
* ⏱️ **Timeout**: Configurável em milissegundos

**Tipos de input:**

* `text`: Texto livre
* `number`: Número
* `email`: Email válido
* `url`: URL válida
* `boolean`: Sim/Não

### Wait Node

Pausa a execução por um tempo determinado.

```json theme={null}
{
  "type": "wait",
  "config": {
    "delayMs": 5000
  }
}
```

**Características:**

* ⏸️ **Pausável**: Para a execução pelo tempo especificado
* ⏱️ **Delay**: Tempo em milissegundos

### Condition Node

Avalia condições e determina o próximo node.

```json theme={null}
{
  "type": "condition",
  "config": {
    "condition": "input.amount > 100",
    "trueBranch": "node-process",
    "falseBranch": "node-reject"
  }
}
```

**Características:**

* 🔀 **Roteamento**: Direciona o fluxo baseado em condições
* 📊 **Expressões**: Suporta expressões JavaScript
* ✅ **Múltiplas condições**: Pode ter várias branches

### Transform Node

Transforma dados usando expressões ou mapeamentos.

```json theme={null}
{
  "type": "transform",
  "config": {
    "transformType": "expression",
    "expression": "input.toUpperCase()"
  }
}
```

**Tipos de transformação:**

* **`expression`**: Expressão JavaScript
* **`map`**: Mapeamento de campos
* **`filter`**: Filtrar arrays
* **`reduce`**: Reduzir arrays

### Trigger Nodes

Nodes que representam pontos de entrada do workflow.

#### Webhook Trigger

```json theme={null}
{
  "type": "trigger_webhook",
  "config": {
    "_triggerId": "trigger_123",
    "path": "/meu-webhook"
  }
}
```

#### Schedule Trigger

```json theme={null}
{
  "type": "trigger_schedule",
  "config": {
    "_triggerId": "trigger_456",
    "cron": "0 0 * * *"
  }
}
```

## Custom Nodes

Você pode criar nodes personalizados que são executados em seus próprios servidores.

### Como Funciona

1. **Registro**: Node é registrado no Triglit
2. **Configuração**: Define endpoint e parâmetros
3. **Execução**: Triglit chama seu endpoint via webhook
4. **Resposta**: Seu servidor retorna o resultado

### Exemplo de Custom Node

```json theme={null}
{
  "type": "custom",
  "config": {
    "nodeId": "custom-node-123",
    "endpoint": "https://api.seudominio.com/triglit/custom-nodes",
    "method": "POST",
    "params": {
      "action": "process-payment"
    }
  }
}
```

<Card title="Guia de Custom Nodes" icon="puzzle-piece" href="/guides/custom-nodes">
  Aprenda a criar e usar custom nodes
</Card>

## Node Registry

O **Node Registry** é um endpoint da API que fornece um catálogo completo de todos os nodes disponíveis (built-in e customizados) para seu tenant, incluindo schemas detalhados de configuração, entrada e saída.

Use o Node Registry para:

* Descobrir quais nodes estão disponíveis
* Obter schemas para validação e renderização de formulários
* Construir editores de workflows dinâmicos
* Validar configurações de nodes antes de salvar

<Card title="Referência: Node Registry" icon="code" href="/api-reference/node-registry">
  Veja a documentação completa do Node Registry API
</Card>

## Contexto de Execução

Nodes compartilham dados através do **contexto de execução**:

```json theme={null}
{
  "data": {
    "input": { "name": "João", "age": 30 },
    "node-1": { "result": "JOÃO" },
    "node-2": { "processed": true }
  },
  "metadata": {
    "runId": "run_123",
    "entityId": "entity_456",
    "executedNodes": ["node-1", "node-2"]
  }
}
```

### Acessando Dados

Nodes podem acessar dados de nodes anteriores:

```javascript theme={null}
// No node "node-2", acesse dados de "node-1"
context.data["node-1"].result

// Ou use o alias "input" para o último resultado
context.data.input
```

## Ordem de Execução

Nodes são executados em **ordem topológica** baseada nas edges:

```
node-1 → node-2 → node-3
         ↓
       node-4
```

Neste exemplo:

1. `node-1` executa primeiro
2. `node-2` e `node-4` executam em paralelo (após node-1)
3. `node-3` executa após node-2

## Nodes Pausáveis

Alguns nodes podem **pausar** a execução:

* **`input`**: Aguarda entrada externa
* **`wait`**: Aguarda tempo determinado
* **`waitForEvent`**: Aguarda evento externo

### Retomando Execução

Quando um node pausa, você recebe um **resume token**:

```json theme={null}
{
  "runId": "run_123",
  "status": "paused",
  "resumeToken": "resume_abc123",
  "pausedAtNode": "node-input-1"
}
```

Para retomar:

```bash theme={null}
POST /v1/gateway/runs/{runId}/resume
{
  "resumeToken": "resume_abc123",
  "resumeData": {
    "input": "dados do usuário"
  }
}
```

## Tratamento de Erros

Nodes podem falhar. O Triglit oferece:

* **Retry automático**: Configurável por node
* **Error handling**: Nodes de tratamento de erro
* **DLQ**: Dead Letter Queue para falhas persistentes

### Exemplo de Error Handling

```json theme={null}
{
  "type": "try-catch",
  "config": {
    "tryBranch": "node-process",
    "catchBranch": "node-error-handler"
  }
}
```

## Boas Práticas

<AccordionGroup>
  <Accordion title="IDs Descritivos">
    Use IDs descritivos: `validate-order` em vez de `node-1`.
  </Accordion>

  <Accordion title="Configuração Clara">
    Documente o propósito de cada node na configuração.
  </Accordion>

  <Accordion title="Reutilização">
    Crie nodes reutilizáveis quando possível (custom nodes).
  </Accordion>

  <Accordion title="Validação">
    Valide dados de entrada antes de processar.
  </Accordion>

  <Accordion title="Idempotência">
    Torne nodes idempotentes quando possível para permitir retries seguros.
  </Accordion>
</AccordionGroup>

## Limitações

* **Tamanho de dados**: 1MB por node no contexto
* **Timeout**: 5 minutos por node (configurável)
* **Retries**: Máximo de 3 tentativas por padrão

<Tip>
  Para operações pesadas, considere usar custom nodes que executam em seus próprios servidores com mais recursos.
</Tip>