# TunnelHub

TunnelHub é uma plataforma de integração, automação e gerenciamento de APIs orientada a times que precisam operar fluxos em produção, com observabilidade, segurança e separação por ambiente.

> **Sobre o modelo de uso:** o TunnelHub é usado pela equipe 4success para implementar e operar integrações gerenciadas. Esta documentação é voltada à equipe técnica da 4success, parceiros autorizados e profissionais que precisam compreender a arquitetura e as ferramentas da plataforma.

Hoje a plataforma combina quatro frentes principais:

* Produto web para configurar ambientes, pacotes, Tabelas De/Para, sistemas, automações, APIs, usuários e configurações administrativas.
* SDK em TypeScript para implementar automações com fluxos prontos, logging, delta, parâmetros, Tabelas De/Para e Sequências.
* CLI para autenticar, listar recursos, criar pacotes, criar automações e publicar novas versões.
* MCP para investigação operacional, leitura de recursos e análise de execuções diretamente de clientes compatíveis com Model Context Protocol.

## O que você encontra no TunnelHub

* **Produto**: ambientes, pacotes, Tabelas De/Para, sistemas, automações, Tabelas de Apoio, Sequências, monitoramento e administração.
* **API Management**: definição de APIs, planos de uso, chaves de API, servidores de recursos, clientes e logs de execução.
* **Developer tooling**: CLI, SDK, MCP e skill para agentes com papéis diferentes no ciclo de desenvolvimento e suporte.

## Como navegar nesta documentação

* Se você está começando agora, siga [Criando sua primeira automação](/primeiros-passos/creating-your-first-automation).
* Se você quer entender o modelo do produto, comece por [Conceitos principais](/produto/core-concepts).
* Se você precisa modelar configuração operacional no produto, leia [Tabelas De/Para](/produto/data-stores) e [Sistemas](/produto/systems).
* Se você vai desenvolver integrações, consulte as seções de [CLI](/cli/cli) e [SDK](/sdk/sdk).
* Se você vai investigar execuções ou operar o ambiente via cliente MCP, consulte [MCP](/mcp/mcp).

## Skill para agentes

Se você desenvolve automações com frequência, vale instalar o skill público `tunnelhub-sdk`. Ele ajuda a trabalhar com os fluxos do SDK, parâmetros, sistemas, Tabelas De/Para, Sequências, logging, interceptor HTTP e testes em plataformas de agentes compatíveis.

Instalação:

```bash
npx skills add tunnelhub/agent-skills --skill tunnelhub-sdk -a opencode
```

Instalação global:

```bash
npx skills add tunnelhub/agent-skills --skill tunnelhub-sdk -a opencode -g
```

## Requisitos gerais

* Node.js 22+ para os projetos atuais do monorepo.
* Acesso a uma conta TunnelHub com pelo menos um ambiente.
* Permissões adequadas para criar pacotes, automações, APIs ou usuários, dependendo do seu perfil.

## Principais conceitos

* **Ambiente**: separa configuração e execução, como DEV, QAS e PRD.
* **Pacote**: agrupador lógico de automações, sistemas e artefatos relacionados.
* **Sistema**: definição reutilizável de conexão com serviços externos.
* **Automação**: execução serverless ou em container que processa integrações e gera logs operacionais.
* **Tabela De/Para**: conjunto de dados configurável no produto, usado para mapeamentos, listas de referência e traduções de valores.
* **Tabela de Apoio**: tabela relacional gerenciada pelo produto para dados operacionais estruturados.
* **Sequência**: gerador sequencial para identificadores controlados pela plataforma.

Use esta documentação como referência pública do estado atual da plataforma. Quando houver diferença entre exemplos antigos e o comportamento atual do produto, o produto e o código do repositório são a fonte de verdade.


# Criando sua primeira automação

Tempo estimado: 25 a 40 minutos

Este guia mostra um fluxo atual de onboarding para criar, desenvolver, publicar e acompanhar uma automação no TunnelHub.

## Antes de começar

Você vai precisar de:

* uma conta TunnelHub com acesso a pelo menos um ambiente;
* Node.js 22+ na sua máquina;
* npm ou pnpm;
* permissão para criar pacote e automação no ambiente desejado.

## 1. Instale a CLI

```bash
npm install -g @tunnelhub/cli
```

Depois da instalação, você pode usar `tunnelhub` ou o alias curto `th`.

## 2. Faça login

O fluxo recomendado usa autenticação via navegador:

```bash
tunnelhub login
```

Durante o login, a CLI solicita o `Tenant ID` e abre a autenticação no frontend do TunnelHub. Em casos específicos, existe fallback por usuário e senha:

```bash
tunnelhub login --password
```

Para validar a sessão atual:

```bash
tunnelhub login-check
```

## 3. Descubra seus ambientes

Liste os ambientes disponíveis e identifique o nome ou UUID do ambiente onde você quer trabalhar:

```bash
tunnelhub list-environments
```

Os comandos da CLI aceitam nome ou UUID do ambiente. Internamente, a CLI resolve esse valor para o identificador correto.

## 4. Crie um pacote

Pacotes organizam recursos relacionados, como automações, sistemas e Tabelas De/Para.

```bash
tunnelhub create-package --env DEV
```

O comando é interativo e solicita nome e descrição.

## 5. Crie uma automação

Agora crie a automação com bootstrap local de um template oficial:

```bash
tunnelhub create-automation --env DEV
```

Durante o fluxo, você escolhe:

* o tipo base da automação;
* o pacote;
* nome e descrição;
* período de retenção de logs;
* URL do repositório, se desejar informar.

Os templates atuais cobrem quatro modelos:

* No delta
* No delta batch
* Delta
* Delta batch

Ao final, a CLI:

* cria a automação no TunnelHub;
* baixa um template do GitHub;
* extrai o projeto para uma nova pasta local;
* grava o `service.uuid` no `tunnelhub.yml`.

## 6. Entenda a estrutura do projeto

O projeto gerado normalmente inclui:

* `src/index.ts` como handler principal;
* uma classe de integração que herda um dos flows do SDK;
* `metadata` para definir as colunas visíveis no monitoramento;
* `tunnelhub.yml` com identificação do serviço e configuração de build/deploy;
* testes básicos para execução local.

O desenvolvimento atual deve ser feito com o `@tunnelhub/sdk`, usando um dos fluxos públicos:

* `NoDeltaIntegrationFlow`
* `NoDeltaBatchIntegrationFlow`
* `DeltaIntegrationFlow`
* `BatchDeltaIntegrationFlow`

## 7. Escolha o flow certo

Use esta regra prática:

* **No delta** quando a automação apenas lê e envia dados, sem reconciliar estado;
* **No delta batch** quando o fluxo continua sem delta, mas o volume pede processamento em lote;
* **Delta** quando você precisa comparar origem e destino para decidir entre insert, update e delete;
* **Delta batch** quando esse mesmo cenário de reconciliação precisa operar em lotes.

Se estiver em dúvida, comece pelo flow mais simples que atende o caso.

## 8. Modele no produto antes de codar

Evite valores fixos no código. O padrão atual é configurar no produto:

* **Sistemas** para conexões com serviços externos;
* **Parâmetros** para valores variáveis da automação;
* **Tabelas De/Para** para mapeamentos e regras de negócio configuráveis;
* **Sequências** para geração de identificadores.

No SDK, esses dados chegam no payload de execução e podem ser acessados pelos helpers públicos.

## 9. Implemente a integração

Em alto nível, sua automação precisa:

* carregar dados da origem;
* opcionalmente comparar com o destino, nos fluxos com delta;
* executar insert, update, delete ou send;
* definir os metadados que aparecerão no monitoramento.

Exemplo simplificado de metadados:

```ts
defineMetadata(): Metadata<MyItem>[] {
  return [
    { fieldName: 'id', fieldLabel: 'ID', fieldType: 'TEXT' },
    { fieldName: 'status', fieldLabel: 'Status do item', fieldType: 'TEXT' },
    { fieldName: 'updatedAt', fieldLabel: 'Atualizado em', fieldType: 'DATETIME' },
  ];
}
```

Os metadados controlam como os itens aparecem nos logs de processamento.

## 10. Teste localmente

Os templates incluem testes iniciais. Para testes locais, habilite o modo de teste do SDK quando fizer sentido:

```ts
import { SDK } from '@tunnelhub/sdk';

beforeAll(() => {
  SDK.testMode = true;
});
```

Esse modo evita efeitos colaterais da execução real da plataforma durante os testes.

## 11. Gere o artefato

Antes do deploy, gere o bundle definido no seu projeto. O contrato importante é:

* existir um `tunnelhub.yml` na raiz do projeto;
* o campo `package.artifact` apontar para o ZIP ou artefato publicado;
* o projeto estar pronto para o ambiente de execução configurado.

## 12. Faça o deploy

Com o artefato pronto, publique uma nova versão:

```bash
tunnelhub deploy-automation --env DEV --message "primeiro deploy"
```

Opcionalmente, você pode informar `--automation` e `--publish`.

Em pipelines CI/CD, use `--message` para carregar contexto como SHA, autor do commit ou identificador da execução.

O deploy:

* valida seu `tunnelhub.yml`;
* faz upload do artefato para S3 por URL assinada;
* solicita a criação do deploy na plataforma.

## 13. Configure o disparo

Na tela da automação, você pode configurar os gatilhos suportados hoje:

* webhook;
* agendamento;
* inbound email.

Dependendo do tipo escolhido, a automação pode ser executada manualmente, por URL ou por agenda.

Para gatilhos de agendamento, use **Não executar antes de** quando quiser preparar a agenda antecipadamente e permitir execuções somente a partir de uma data e hora de go-live.

## 14. Acompanhe a execução

Depois do deploy, use a interface web em `Automations > Monitoring` para acompanhar:

* status geral da execução;
* volume processado;
* logs de processamento por item;
* traces técnicos;
* downloads e ações operacionais quando disponíveis.

## 15. Configure notificações de falha

Na aba **Notificações** da automação, adicione os destinatários que devem ser alertados quando uma execução falhar.

Você pode enviar alertas por e-mail, Discord, Microsoft Teams, Google Chat, Slack ou webhook genérico. Para os canais de colaboração, siga as instruções específicas do provedor e informe a URL gerada no produto. No Microsoft Teams, gere a URL com o **Workflows (Power Automate)**, e não com o conector legado **Incoming Webhook**. Escolha também o idioma da mensagem e trate URLs de webhook como segredos. Para instruções e links de configuração de cada canal, consulte [Notificações](https://docs.tunnelhub.io/primeiros-passos/pages/occlNL417jAsMpB5ISDq#notificações).

## Próximos passos

* Leia [Do template ao primeiro deploy](/primeiros-passos/from-template-to-first-deploy).
* Leia [Modelando uma automação no produto](/primeiros-passos/modeling-an-automation-in-the-product).
* Leia [SDK](/sdk/sdk) para escolher o flow correto.
* Leia [Monitoramento](/produto/monitoring) para investigar falhas e execuções.
* Leia [`tunnelhub.yml`](/cli/tunnelhub-yml) para entender o contrato de build e deploy.


# Do template ao primeiro deploy

Esta página conecta o template oficial ao fluxo real de desenvolvimento de uma automação TunnelHub.

## O que a CLI gera

Quando você executa `tunnelhub create-automation --env <ENV>`, a CLI cria a automação na plataforma e baixa um dos templates oficiais para sua máquina.

O projeto gerado costuma incluir:

* `src/index.ts` com o handler principal;
* uma classe de integração no diretório `src/core/` ou equivalente;
* `metadata` com os campos exibidos no monitoramento;
* `__tests__` com exemplos básicos;
* `tunnelhub.yml`;
* scripts de build e teste.

## 1. Abra o handler

O handler normalmente:

* instancia sua classe de integração;
* chama `AutomationExecution.executeAutomation(...)`;
* retorna sucesso HTTP quando a execução termina sem erro fatal.

Esse é o contrato central do runtime público.

## 2. Abra a classe de integração

É nessa classe que você implementa o flow escolhido.

Exemplos de responsabilidade por flow:

* **No delta**: `loadSourceSystemData()` e `sendData()`;
* **No delta batch**: `loadSourceSystemData()` e `sendDataInBatch()`;
* **Delta**: `loadSourceSystemData()`, `loadTargetSystemData()`, `insertAction()`, `updateAction()`, `deleteAction()`;
* **Delta batch**: `loadSourceSystemData()`, `loadTargetSystemData()`, `batchInsertAction()`, `batchUpdateAction()` e `batchDeleteAction()`.

## 3. Defina os metadados

`defineMetadata()` define as colunas visíveis no monitoramento.

Pense nesses campos como contrato operacional para suporte e negócio. Bons metadados ajudam a responder rapidamente:

* qual item falhou;
* qual identificador localizar no sistema de origem;
* qual status funcional estava envolvido.

## 4. Ligue código à configuração de produto

Antes de concluir a implementação, confirme que a automação no portal tem os recursos certos associados:

* systems necessários;
* parâmetros necessários;
* Tabelas De/Para necessárias;
* Sequências necessárias.

No código, o padrão recomendado é localizar systems por `internalName` e usar helpers do SDK em vez de espalhar configuração no projeto.

## 5. Revise o `tunnelhub.yml`

Confirme pelo menos:

* `service.uuid` preenchido;
* `configuration.entrypoint` coerente com o bundle gerado;
* `package.artifact` apontando para o ZIP final.

## 6. Rode testes locais

Os templates incluem um teste inicial. Expanda essa suíte conforme você implementa a integração.

Checklist mínimo:

* handler sobe sem erro;
* classe de integração instancia corretamente;
* metadados são válidos;
* principal caminho feliz da integração está coberto.

## 7. Gere o artefato

O comando exato depende do template, mas o resultado esperado é sempre um ZIP configurado em `package.artifact`.

Antes do deploy, confirme que o arquivo realmente existe no caminho configurado.

## 8. Publique

```bash
tunnelhub deploy-automation --env DEV --message "primeira versão"
```

Se necessário, sobrescreva o UUID com `--automation`.

Em pipelines CI/CD, mantenha o contexto humano no `--message`, por exemplo com SHA e e-mail do autor do commit.

## 9. Valide no produto

Depois do deploy, valide no portal:

* se a nova versão apareceu na automação;
* se os triggers esperados estão configurados;
* se a execução manual ou agendada funciona;
* se os logs e traces fazem sentido.

## Checklist final

* flow escolhido corretamente;
* systems, parâmetros, Tabelas De/Para e Sequências configuradas;
* `tunnelhub.yml` coerente;
* artefato gerado;
* deploy publicado;
* monitoramento validado.


# Modelando uma automação no produto

Boa parte da qualidade de uma automação no TunnelHub vem da modelagem no produto, não apenas do código.

## Ordem recomendada

Um fluxo prático costuma seguir esta sequência:

1. escolher o ambiente;
2. criar ou selecionar um pacote;
3. cadastrar systems;
4. definir parâmetros;
5. criar Tabelas De/Para e Sequências, quando fizer sentido;
6. criar a automação;
7. associar os recursos necessários;
8. configurar triggers e notificações.

## Pacote

Use o pacote como agrupador funcional. Ele deve refletir domínio, cliente, iniciativa ou contexto de manutenção.

## Systems

Cadastre um system quando a automação depender de uma conexão externa reutilizável.

Exemplos comuns:

* API HTTP;
* FTP/SFTP;
* banco de dados;
* SOAP;
* SAP RFC.

Boas práticas:

* usar `internalName` estável;
* separar credenciais por ambiente;
* evitar um mesmo system para contextos sem relação.

## Parâmetros

Use parâmetros para valores variáveis e pequenos estados controlados pela automação.

Exemplos:

* feature flags;
* datas de corte;
* nomes de tabela;
* cursores de sincronização.

Não use parâmetro para tudo. Quando o dado representa conexão, prefira `System`. Quando representa mapeamento de negócio, prefira uma Tabela De/Para.

## Tabelas De/Para

Use Tabelas De/Para quando o negócio precisa manter mapeamentos e listas de referência sem alterar código.

Casos típicos:

* de/para de status;
* códigos de filial;
* mapeamento de categorias;
* IDs legados para IDs externos.

## Sequências

Use Sequências quando a plataforma precisa gerar identificadores centralizados e atômicos.

Casos típicos:

* número de lote;
* identificador incremental;
* chave de negócio controlada.

## Associação com a automação

Uma automação só recebe em runtime os recursos explicitamente associados a ela.

Revise antes do deploy:

* systems corretos associados;
* parâmetros esperados cadastrados;
* Tabelas De/Para corretas disponíveis;
* Sequências corretas criadas.

## Triggers

Hoje, a modelagem pública mais comum inclui:

* webhook;
* scheduled;
* inbound email.

Escolha o trigger conforme a forma de disparo do processo, não conforme a tecnologia da origem.

Use `scheduled` para rotinas recorrentes. Quando a rotina precisa ser configurada antes do go-live, preencha **Não executar antes de** com a data e hora inicial desejada. Assim a agenda pode ficar pronta no produto, mas execuções anteriores ao início planejado serão ignoradas.

## Notificações e retenção

Antes de publicar em produção, revise:

* retenção de logs;
* notificações de falha;
* quem precisa operar essa automação;
* se usuários limitados precisam enxergar a execução.

## Pergunta prática de modelagem

Quando estiver em dúvida sobre onde colocar uma configuração, use esta regra:

* conexão externa: `System`;
* valor variável da automação: `Parameter`;
* regra de negócio configurável: Tabela De/Para;
* contador centralizado: Sequência.


# Conceitos principais

Esta página resume as entidades mais importantes do TunnelHub e como elas se relacionam.

## Estrutura base

* **Tenant/empresa**: unidade principal de conta e isolamento de dados.
* **Usuário**: pessoa com acesso ao portal, à CLI ou a fluxos relacionados à autenticação.
* **Ambiente**: recorte operacional dentro da empresa. É comum existir DEV, QAS e PRD.
* **Pacote**: agrupador funcional usado para organizar automações, systems e outros recursos.

## Recursos de integração

* **System**: conexão reutilizável com banco, HTTP, FTP/SFTP, LDAP, mail, SOAP, SAP RFC, SMB e outros tipos suportados.
* **Automação**: integração executável criada no produto e implementada com o SDK.
* **Deploy**: versão publicada da automação, com histórico e opção de transporte entre ambientes.
* **Trigger**: forma de disparo de uma automação, como webhook, agenda ou inbound email.

## Recursos de dados

* **Tabela De/Para**: conjunto de dados configurável no produto, usado para mapeamentos e regras de negócio.
* **Tabela de conversão**: caso comum de uma Tabela De/Para com pares `fromValue` e `toValue`.
* **Sequência**: gerador sequencial usado para números de negócio ou identificadores.
* **Parâmetro**: valor configurável associado a automações e systems, evitando valores fixos no código.

## Recursos operacionais

* **Execução**: uma execução de automação com status, período, logs e traces.
* **Processing logs**: resultado por item processado, baseado nos metadados definidos pelo SDK.
* **Traces**: logs técnicos e eventos auxiliares da execução.
* **Notificações**: alertas enviados quando a automação falha ou requer atenção.
* **Transport**: fluxo para promover configurações e versões entre ambientes quando aplicável.

## Gestão de APIs

* **API**: definição publicada via API Gateway.
* **Plano de uso**: política de consumo aplicada a clientes e chaves de API.
* **Chave de API**: credencial de consumo para cenários controlados por plano.
* **Servidor de recursos**: conjunto de escopos OAuth usados para proteger endpoints.
* **Cliente**: aplicação consumidora autenticada para fluxos OAuth e machine-to-machine.

## Ferramentas de desenvolvimento

* **CLI**: usada para login, listagem de recursos, bootstrap de automações e deploy.
* **SDK**: base de desenvolvimento das automações.
* **MCP**: interface operacional orientada à leitura para suporte, análise e investigação.

## Fluxo típico

1. criar ou selecionar um ambiente;
2. criar um pacote;
3. cadastrar systems e parâmetros necessários;
4. criar Tabelas De/Para e Sequências quando fizer sentido;
5. criar uma automação a partir de um template;
6. implementar a integração com o SDK;
7. gerar artefato, fazer deploy e executar;
8. monitorar logs, traces, consumo e falhas.


# Usuários e permissões

O TunnelHub possui controle de acesso baseado em roles, permissões e escopos de ambiente.

## Onde gerenciar

O gerenciamento de usuários fica em `Administration > Users`.

Nesta tela você pode:

* criar usuários;
* editar dados e status;
* redefinir escopo de acesso;
* limitar a visibilidade de recursos para usuários restritos.

## Roles mais comuns

Os nomes exatos podem variar conforme o tenant, mas o modelo público gira em torno de três grupos principais:

* **TenantAdmin**: acesso mais amplo, incluindo administração e configuração.
* **TenantUser**: operação do produto sem o mesmo alcance administrativo.
* **TenantLimitedUser**: acesso somente a recursos explicitamente liberados.

Em contextos privilegiados podem existir roles sistêmicas, mas elas não costumam fazer parte do fluxo operacional padrão da maioria dos tenants.

## Escopo por ambiente

Além da role, o acesso também depende dos ambientes liberados para o usuário.

Isso permite, por exemplo:

* operar DEV e QAS sem enxergar PRD;
* limitar produção a um grupo menor;
* separar funções por time ou parceiro.

## Usuários limitados

Usuários limitados são importantes para cenários B2B, parceiros ou times externos.

Eles podem receber acesso granular a:

* automações;
* Tabelas De/Para;
* áreas específicas de monitoramento.

Esse modelo permite expor somente o mínimo necessário para acompanhamento operacional.

## Campos principais ao criar um usuário

* **Usuário**: identificador único do usuário.
* **E-mail**: usado para notificações, onboarding e recuperação de acesso.
* **Role**: define o escopo inicial de permissão.
* **Status**: controla se o acesso está ativo.

Dependendo do tenant, o cadastro também pode considerar idioma, timezone, país e ambientes liberados.

## Boas práticas

* use usuários limitados para acessos externos;
* evite compartilhar contas;
* revise periodicamente os acessos administrativos;
* alinhe automações e Tabelas De/Para liberadas com a necessidade real de negócio.

Consulte também [Roles e escopos](/produto/roles-and-permissions) para uma visão conceitual do modelo.


# Ambientes

Ambientes separam configurações e operação dentro da mesma empresa. O padrão mais comum é trabalhar com DEV, QAS e PRD.

## Para que servem

Cada ambiente possui seu próprio conjunto de:

* pacotes;
* sistemas;
* automações;
* APIs;
* Tabelas De/Para;
* sequências;
* monitoramento associado.

Isso permite promover configurações e código de forma controlada.

## Casos de uso

* desenvolver e validar sem afetar produção;
* usar credenciais e endpoints diferentes por ambiente;
* testar transportes e deploys antes da publicação final;
* controlar exposição de APIs e execuções por etapa.

## No produto

Ambientes são gerenciados na área `Environments` e aparecem como contexto de operação em diversas telas.

Na CLI e no MCP, o ambiente também define o escopo das consultas e operações.

## Boas práticas

* mantenha nomes padronizados e de fácil identificação;
* não reutilize credenciais de produção em DEV;
* trate PRD como ambiente controlado para deploy e execução;
* documente os transportes e promoções entre ambientes.


# Pacotes

Pacotes são agrupadores lógicos dentro do TunnelHub. Eles ajudam a organizar integrações e recursos relacionados por domínio, projeto ou contexto de negócio.

## O que um pacote organiza

Um pacote normalmente concentra:

* automações relacionadas;
* systems usados por essas automações;
* Tabelas De/Para e sequências associadas;
* APIs ou recursos operacionais do mesmo contexto.

## Quando criar um novo pacote

Crie um pacote novo quando houver necessidade de separar:

* uma iniciativa ou módulo de negócio;
* um cliente ou vertical específica;
* responsabilidade entre equipes;
* ciclo de vida de deploy e governança.

## Campos principais

* **Nome**: identificação amigável.
* **Descrição**: contexto funcional do pacote.
* **Ambiente**: escopo onde o pacote existe.

## Pela CLI

Você também pode criar pacotes pela CLI:

```bash
tunnelhub create-package --env DEV
```

## Boas práticas

* use nomes orientados a domínio, não a tecnologia;
* evite pacotes grandes demais sem critério funcional;
* alinhe pacote com responsabilidade e contexto de manutenção.


# Tabelas De/Para

Tabelas De/Para são recursos configuráveis do produto e reutilizáveis por automações, APIs e fluxos operacionais.

Na prática, elas substituem o uso de regras fixas em código quando o time precisa manter mapeamentos, códigos externos, listas de referência ou traduções de valores por ambiente.

O modelo mais comum é um mapeamento simples de valor de origem para valor de destino, usando itens com `fromValue` e `toValue`.

## Como pensar o recurso

* use **Tabela De/Para** como conceito público principal;
* trate o conteúdo como configuração de negócio versionada no produto, não como área improvisada para testes.

## Onde aparece no produto

O recurso existe como área própria no portal e é associado a ambientes e pacotes.

Normalmente, cada Tabela De/Para tem:

* nome amigável;
* `externalCode`, usado como identificador técnico;
* descrição funcional;
* pacote relacionado;
* lista de itens.

## Estrutura dos itens

O modelo mais comum usa duas colunas:

* `fromValue` para o valor de origem;
* `toValue` para o valor de destino.

Esse formato cobre muitos cenários de integração, como:

* status internos para status externos;
* códigos de filial ou centro de custo;
* categorias de produto;
* IDs legados para IDs do sistema alvo.

## Operações disponíveis

No fluxo atual do produto, você pode:

* criar e editar Tabelas De/Para;
* gerenciar itens individualmente;
* remover itens em lote;
* importar carga completa por CSV;
* baixar o conteúdo para revisão externa.

Esse modelo ajuda quando o negócio precisa atualizar um mapa sem esperar deploy de código.

## Uso em automações

No runtime do SDK, o uso mais comum é consultar uma Tabela De/Para por código e aplicar a tradução durante o processamento.

Exemplo conceitual:

```ts
const dataStore = new DataStore(event);
const conversionTable = new ConversionTable(dataStore);
const mappedValue = await conversionTable.getValueFromConversionTable(
  'sales-channel-map',
  order.channel,
  undefined,
  true,
);
```

O ponto importante é que a regra fica no produto, e não espalhada em `if/else` no projeto.

## Tabelas De/Para e usuários limitados

Tabelas De/Para também participam do modelo de visibilidade granular do produto.

Você pode liberar acesso seletivo para usuários limitados quando eles precisam:

* revisar valores de referência;
* operar um conjunto específico de mapeamentos;
* acompanhar apenas uma parte da configuração compartilhada com parceiros.

## Boas práticas

* escolha `externalCode` estável e orientado ao domínio;
* mantenha descrição clara sobre dono funcional e finalidade;
* prefira uma Tabela De/Para por contexto de negócio, em vez de agrupar regras sem relação;
* revise itens obsoletos periodicamente;
* use importação CSV com cuidado, porque carga completa normalmente substitui o conjunto existente.


# Tabelas de Apoio

Tabelas de Apoio são tabelas relacionais gerenciadas pelo TunnelHub para guardar dados operacionais que precisam ser consultados ou alterados por automações.

Use esse recurso quando o dado tem estrutura própria, chave primária, colunas tipadas e precisa ir além de um simples de/para.

## Quando usar

Tabelas de Apoio fazem sentido para cenários como:

* cache operacional compartilhado por execuções;
* controle de processamento por entidade de negócio;
* tabelas auxiliares com várias colunas;
* dados importados por CSV e consumidos por automações;
* estado de integração que precisa ser visível e administrado no produto.

Se o caso for apenas traduzir um valor de origem para um valor de destino, prefira [Tabelas De/Para](/produto/data-stores).

## Modelo de dados

Cada Tabela de Apoio possui:

* `externalCode`, usado por automações e SDK;
* descrição funcional;
* pacote associado;
* lista opcional de usuários limitados;
* `schemaDefinition`, com colunas e tipos;
* `primaryKey`, com uma ou mais colunas;
* `indexesDefinition`, para índices adicionais.

Tipos de coluna suportados:

* `TEXT`;
* `INTEGER`;
* `REAL`;
* `NUMERIC`;
* `BOOLEAN`;
* `DATETIME`.

Além da chave primária definida no schema, o TunnelHub mantém um `rowId` técnico para operações sobre linhas.

## Operações disponíveis

No produto, Tabelas de Apoio permitem:

* criar e editar a definição da tabela;
* listar linhas com paginação, filtros e ordenação;
* inserir, editar e remover linhas;
* importar dados por CSV;
* exportar dados por CSV;
* controlar visibilidade para usuários limitados.

Alterações de schema são tratadas pela plataforma. Mudanças destrutivas ou troca de chave primária podem exigir recriação planejada da tabela.

## Uso em automações

Para usar Tabelas de Apoio em uma automação, associe a tabela à automação no produto e habilite o runtime compatível no `tunnelhub.yml`.

Exemplo:

```yaml
configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs24.x
  memorySize: 1024
  timeout: 60
  runInVpc: true
  sqlTables:
    enabled: true
```

Requisitos quando `sqlTables.enabled` é `true`:

* `runtime` deve ser `nodejs24.x`;
* `runInVpc` deve ser `true`;
* `runtimeEngine` deve ser `LAMBDA` ou `ECS_FARGATE`.

## Uso no SDK

O SDK expõe o helper `SqlTables` para operar linhas durante a execução.

Exemplo conceitual:

```ts
const sqlTables = new SqlTables(event);

const inserted = await sqlTables.insertRow('customer-cache', {
  document: '12345678900',
  name: 'Cliente exemplo',
  active: true,
});

const page = await sqlTables.queryRows('customer-cache', {
  current: 1,
  pageSize: 20,
  filter: {
    document: ['12345678900'],
  },
});

await sqlTables.updateRow('customer-cache', inserted.rowId, {
  name: 'Cliente atualizado',
});
```

O helper acessa o arquivo SQLite montado pela plataforma durante a execução. Ele não deve ser usado fora do runtime gerenciado do TunnelHub.

## Testes locais

Para testes unitários com Jest, defina `SDK.testMode = true` antes de construir a integração. Nesse modo, o construtor de `SqlTables` não valida os requisitos do runtime gerenciado. As operações continuam precisando de mock explícito.

`testMode` não fornece persistência local e não simula SQLite, EFS ou DynamoDB. O exemplo a seguir usa fixtures por `externalCode` e mantém as inserções apenas em memória durante o processo do Jest:

```ts
import fs from 'node:fs';
import path from 'node:path';
import {ProcessorPayload, SDK, SqlTables} from '@tunnelhub/sdk';

type CustomerCacheRow = {
  document: string;
  name: string;
  active: boolean;
};

type MockRow = {
  rowId: string;
  values: CustomerCacheRow;
};

const rowsByTable = new Map<string, MockRow[]>();
let nextRowId = 1;

const testEvent = {
  tenantId: 'test-tenant',
  environmentId: 'test-environment',
  automationId: 'test-automation',
  executionId: 'test-execution',
  systems: [],
  parameters: {},
} as ProcessorPayload;

function getRows(externalCode: string): MockRow[] {
  const rows = rowsByTable.get(externalCode);
  if (rows) return rows;

  const fixturePath = path.join(__dirname, 'data', `${externalCode}.json`);
  const fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8')) as MockRow[];
  const clonedRows = structuredClone(fixture);
  rowsByTable.set(externalCode, clonedRows);
  return clonedRows;
}

describe('CustomerCacheIntegration', () => {
  beforeAll(() => {
    SDK.testMode = true;
  });

  beforeEach(() => {
    jest.spyOn(SqlTables.prototype, 'queryRows').mockImplementation(async (externalCode, request = {}) => {
      const current = request.current ?? 1;
      const pageSize = request.pageSize ?? 20;
      const rows = getRows(externalCode);

      return {
        success: true,
        current,
        pageSize,
        total: rows.length,
        data: rows.slice((current - 1) * pageSize, current * pageSize),
      };
    });

    jest.spyOn(SqlTables.prototype, 'insertRow').mockImplementation(async (externalCode, values) => {
      const row = {rowId: `test-row-${nextRowId++}`, values};
      getRows(externalCode).push(row as MockRow);
      return row;
    });
  });

  afterEach(() => {
    jest.restoreAllMocks();
    rowsByTable.clear();
    nextRowId = 1;
  });

  afterAll(() => {
    SDK.testMode = false;
  });

  test('insere cliente ausente do cache', async () => {
    const sqlTables = new SqlTables(testEvent);

    await sqlTables.insertRow('customer-cache', {document: '12345678900', name: 'Ana', active: true});

    expect(await sqlTables.queryRows('customer-cache')).toEqual({
      success: true,
      current: 1,
      pageSize: 20,
      total: 1,
      data: [
        {
          rowId: 'test-row-1',
          values: {document: '12345678900', name: 'Ana', active: true},
        },
      ],
    });
  });
});
```

Organize as fixtures em `__tests__/data/<externalCode>.json`. Cada arquivo deve conter uma lista de linhas no formato retornado por `queryRows`. Por exemplo, o arquivo `__tests__/data/customer-cache.json` usado no teste de inserção pode conter apenas:

```json
[]
```

Uma fixture vazia representa uma tabela existente sem registros.

O mock é apropriado para testar o fluxo da automação. Ele não reproduz schema, constraints, normalização de tipos nem o comportamento do SQLite. Teste esses cenários com `SqlTables` real, usando um arquivo SQLite preparado ou o runtime gerenciado do TunnelHub.

## Boas práticas

* escolha `externalCode` estável e orientado ao domínio;
* defina uma chave primária natural quando possível;
* modele colunas com tipos claros;
* use índices somente para consultas recorrentes;
* evite armazenar segredos ou credenciais;
* prefira Tabelas de Apoio para dados estruturados e Tabelas De/Para para mapeamentos simples.


# Sistemas

Systems representam conexões reutilizáveis com recursos externos consumidos por automações e APIs.

## Por que usar systems

Em vez de colocar credenciais e endpoints no código, o TunnelHub centraliza esses dados em entidades configuráveis por ambiente.

Isso permite:

* trocar credenciais sem alterar o código da automação;
* separar DEV, QAS e PRD com segurança;
* reutilizar a mesma configuração em múltiplas automações;
* transportar configurações entre ambientes com mais controle.

## Tipos suportados

Os tipos expostos atualmente no produto incluem:

* `DATABASE`
* `FTP`
* `LDAP`
* `MAIL`
* `HTTP`
* `SFTP`
* `SAPRFC`
* `SMB`
* `SOAP`

Dependendo do tipo, a aba de parâmetros muda para refletir o formato de autenticação e conexão esperado.

## Como modelar um system

Além dos campos básicos, cada system normalmente combina:

* `internalName` estável para uso técnico;
* parâmetros tipados conforme o tipo do system;
* parâmetros customizados, quando o contexto pede valores extras;
* status ativo ou inativo;
* vínculo com o ambiente correto.

Trocar o tipo de um system não é um ajuste cosmético: isso muda a estrutura esperada de parâmetros e, em muitos casos, a própria forma de autenticação.

## Campos principais

* **Nome**: nome amigável.
* **Nome interno**: identificador técnico único dentro do ambiente.
* **Tipo**: tipo do system.
* **Status**: ativo ou inativo.
* **Descrição**: contexto funcional.

Dependendo do caso, o produto também permite logo ou imagem e parâmetros customizados adicionais.

## Exemplos de parâmetros por tipo

* **HTTP**: URL base, autenticação, headers ou query string.
* **DATABASE**: tipo do banco, host, porta, usuário, senha e database ou schema.
* **FTP/SFTP**: host, porta, usuário, credencial, timeout e política de reconexão.
* **SOAP**: WSDL URL e autenticação, quando aplicável.
* **SAP RFC**: host, usuário, mandante, número do sistema e trace.

## Uso em automações

Systems precisam ser associados a uma automação para ficarem disponíveis em tempo de execução.

No SDK, eles chegam pelo payload de execução e podem ser acessados pela lista `systems` ou pelos utilitários públicos.

Em projetos mais maduros, o padrão é localizar o system pelo `internalName` e deixar o resto da configuração no produto.

## Boas práticas

* use `internalName` previsível e estável;
* cadastre credenciais por ambiente;
* mantenha descrições claras sobre finalidade e dono da integração;
* desative systems obsoletos em vez de manter configurações ambíguas;
* evite reutilizar um mesmo system para contextos de negócio sem relação.


# Automações

Automações são o núcleo da plataforma de integração do TunnelHub. Elas definem como um fluxo é executado, monitorado e operado ao longo do tempo.

## O que uma automação concentra

Na tela de detalhes, a automação normalmente é organizada em abas como:

* dados básicos;
* gatilhos;
* deploys;
* parâmetros;
* notificações;
* usuários limitados;
* systems;
* Tabelas De/Para;
* histórico de ações.

Dependendo da automação, o produto também expõe execução manual, transporte entre ambientes e histórico de versões.

## Dados básicos

Na configuração básica, o time normalmente define:

* nome e descrição;
* pacote relacionado;
* status;
* URL de repositório, quando deseja rastreabilidade com o código;
* retenção de logs operacionais.

A retenção influencia diretamente a janela disponível para investigação no monitoramento.

## Gatilhos suportados

Atualmente, a plataforma expõe três formas principais de disparo:

* **Webhook**: execução sob demanda por URL.
* **Scheduled**: execução automatizada por agenda.
* **Inbound email**: execução a partir de recebimento de email.

Em gatilhos do tipo **Scheduled**, é possível definir uma data e hora em **Não executar antes de**. Essa opção permite configurar a agenda com antecedência para um go-live sem disparar execuções antes do momento planejado. Disparos anteriores à data configurada são ignorados; a automação passa a executar normalmente quando a próxima ocorrência da agenda for igual ou posterior à data/hora inicial.

Exemplo: uma agenda “de hora em hora” com **Não executar antes de** em `01/07/2026 06:00` começa a considerar execuções a partir de `06:00`, depois `07:00`, `08:00` e assim por diante.

No caso de webhook, o produto pode exigir autenticação conforme a configuração definida. Os modos mais comuns são:

* sem autenticação;
* `BASIC`;
* autenticação por query string;
* autenticação por header.

## Deploys e versões

Cada automação possui histórico de deploys. Esse histórico permite:

* saber quem publicou uma versão;
* acompanhar data e contexto do deploy;
* promover configurações e artefatos entre ambientes por transporte, quando aplicável.

Dependendo do caso, o runtime pode aparecer como `LAMBDA` ou `ECS_FARGATE`.

## Parâmetros e systems associados

Parâmetros permitem externalizar configurações variáveis do código.

Uma automação só recebe em runtime os systems que foram explicitamente associados a ela. Isso reduz acoplamento e melhora o controle operacional.

## Notificações

Você pode configurar notificações automáticas para falhas de execução. Quando uma execução termina com status de erro, o TunnelHub envia um alerta para cada destinatário configurado na aba **Notificações** da automação.

### Como configurar

1. Abra a automação e acesse a aba **Notificações**.
2. Clique em **Adicionar**.
3. Selecione o tipo de notificação.
4. Informe o e-mail ou a URL de destino.
5. Escolha o idioma da mensagem, entre português e inglês.
6. Salve a configuração.

Os canais disponíveis são:

| Canal               | Destinatário                                                                 | Configuração                                                                                                                                                                                                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **E-mail**          | Endereço de e-mail que receberá o alerta.                                    | Informe o endereço do destinatário.                                                                                                                                                                                                                                                                                             |
| **Discord**         | URL de webhook criada para um canal do Discord.                              | Crie e copie a URL do webhook em **Integrações** do servidor. Consulte [Introdução a webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).                                                                                                                                                      |
| **Microsoft Teams** | URL de webhook gerada pelo Workflows (Power Automate) para um canal ou chat. | No Teams, abra **Workflows**, escolha um modelo de alerta por webhook para o canal ou chat, crie o fluxo e copie a URL gerada. Consulte [Criar webhooks de entrada com Workflows](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498). |
| **Google Chat**     | URL de webhook criada para um espaço do Google Chat.                         | Adicione um webhook em **Apps e integrações** do espaço e copie a URL. Consulte [Criar um webhook](https://developers.google.com/workspace/chat/quickstart/webhooks).                                                                                                                                                           |
| **Slack**           | URL de Incoming Webhook associada ao canal de destino.                       | Crie um Incoming Webhook no aplicativo Slack e copie a URL. Consulte [Enviar mensagens usando Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks).                                                                                                                                    |
| **Webhook**         | URL de um endpoint HTTP próprio.                                             | Prepare o endpoint para receber uma requisição `POST` com conteúdo JSON.                                                                                                                                                                                                                                                        |

É possível adicionar mais de um destinatário, inclusive usando canais diferentes. URLs de webhook podem conter tokens ou outros dados que permitem publicar mensagens no canal. Trate-as como segredos e não as exponha em repositórios, tickets, logs ou mensagens públicas.

### Conteúdo do alerta

A apresentação varia conforme o canal, mas as notificações normalmente incluem:

* conta, ambiente, pacote e automação;
* início e fim da execução;
* totais processados e registros com erro;
* mensagem geral de erro;
* link para consultar a execução no monitoramento, quando suportado pelo canal.

No webhook genérico, o TunnelHub envia esses dados em JSON e inclui o header `TunnelHub-Tenant-Id`. O endpoint deve aceitar requisições `POST` com `Content-Type: application/json`.

## Usuários limitados

Automações podem liberar visibilidade seletiva para usuários limitados. Esse recurso é importante quando parceiros ou clientes precisam acompanhar apenas execuções específicas.

## Execução

Depois do deploy, a automação pode ser executada:

* manualmente pelo portal;
* via webhook;
* por agenda;
* por inbound email, quando configurado.

As execuções geram logs de processamento, traces e métricas para investigação.

## Boas práticas

* modele `defineMetadata()` pensando no time que vai operar a execução;
* associe apenas os systems realmente necessários;
* prefira parâmetros, Tabelas De/Para e Sequências a regras rígidas no código;
* revise notificações e retenção de logs antes de colocar a automação em produção.


# Sequências

Sequências são contadores sequenciais controlados pela plataforma. Elas servem para gerar números ou identificadores de forma consistente entre execuções.

## Casos de uso comuns

* números de documento;
* identificadores de lote;
* códigos incrementais de integração;
* chaves que precisam ser atômicas e centralizadas.

## Vantagens

* evita lógica de contagem local em cada automação;
* reduz risco de colisão;
* centraliza a geração no produto;
* simplifica cenários com múltiplas execuções concorrentes.

## Uso no SDK

O SDK possui um helper público para recuperar o próximo valor de uma sequência em runtime.

## Boas práticas

* crie sequências com nomes orientados a negócio;
* não reutilize a mesma sequência para domínios diferentes;
* monitore consumo em fluxos de alto volume quando isso impactar regras externas.


# Monitoramento

Monitoramento é uma das partes mais importantes do TunnelHub. A plataforma foi desenhada para dar visibilidade sobre execuções, falhas e comportamento técnico sem exigir que cada integração implemente sua própria camada operacional do zero.

## Onde acessar

As execuções de automações ficam em `Automations > Monitoring`.

Nesta área você encontra filtros por período, automação, pacote, status e outros critérios operacionais.

No fluxo atual, também é comum trabalhar com:

* janela de tempo explícita;
* filtro por pacote e ambiente;
* opção para esconder execuções bem-sucedidas sem itens processados.

## O que existe em uma execução

Cada execução possui informações como:

* identificador da execução;
* automação e ambiente relacionados;
* horário de início e fim;
* status consolidado;
* quantidade processada e quantidade de erros.

Dependendo do caso, a execução também pode exibir versão do SDK, estratégia de logging, runtime e identificadores técnicos adicionais.

## Logs de processamento

Os logs de processamento mostram o resultado por item processado. Eles são baseados nos metadados definidos pelo SDK e normalmente incluem:

* ação executada;
* status;
* mensagem;
* colunas de negócio definidas por `defineMetadata()`.

Esses logs são a melhor fonte para entender o que aconteceu com cada registro.

## Traces

Os traces mostram informações mais técnicas da execução, incluindo logs emitidos pelo próprio flow e eventos auxiliares da plataforma.

Eles são úteis para:

* investigar falhas de integração;
* medir passos internos do processamento;
* validar comportamento de chamadas externas.

## Como investigar um problema

Um fluxo prático costuma ser:

1. localizar a execução pelo período e status;
2. abrir o detalhe para entender o contexto geral;
3. usar logs de processamento para registros de negócio;
4. usar traces para erros técnicos ou intermitentes;
5. reprocessar a execução quando o cenário permitir.

## Análise assistida

Em alguns cenários, a plataforma também oferece análise assistida por IA para resumir falhas e ajudar no troubleshooting.

Esse recurso não substitui logs e traces. Ele acelera a leitura inicial do incidente.

## Dicas para bons logs

* defina metadados que ajudem o time de negócio a localizar registros;
* evite mensagens genéricas demais;
* use parâmetros, Tabelas De/Para e Sequências para enriquecer o contexto sem valores fixos no código;
* complemente com traces técnicos apenas quando isso gerar valor investigativo.


# Roles e escopos

O modelo de acesso do TunnelHub combina role, escopo por ambiente e visibilidade granular de recursos.

Por isso, a pergunta correta não é apenas "qual perfil esse usuário tem?", mas também "em quais ambientes ele opera?" e "quais recursos estão liberados para ele?".

## Camadas do modelo

Em alto nível, o controle de acesso mistura três camadas:

* **role** para definir a capacidade geral do usuário;
* **ambientes** para limitar onde ele pode operar;
* **escopos específicos** para casos de usuários limitados.

## Roles da plataforma

As roles da plataforma são fixas. Hoje, existem apenas três opções:

* `Administrador`: administração ampla do tenant e acesso às áreas operacionais;
* `Usuário Comum`: operação do produto sem o mesmo alcance administrativo;
* `Usuário Limitado`: acesso restrito a recursos explicitamente liberados.

## Escopo por ambiente

O usuário pode ter acesso a um subconjunto dos ambientes do tenant. Isso é importante para separar DEV, QAS e PRD sem depender apenas de convenção.

Na prática, o mesmo usuário pode:

* operar livremente em DEV;
* ter acesso parcial em QAS;
* não enxergar PRD.

## Usuário limitado

Usuários limitados são úteis para cenários B2B, parceiros, clientes e times externos.

Hoje, esse modelo pode restringir visibilidade de forma granular para recursos como:

* automações;
* Tabelas De/Para;
* telas de monitoramento derivadas desses recursos.

Esse desenho permite compartilhar operação sem expor o tenant inteiro.

## Mudanças de acesso

Ambientes liberados e escopos granulares podem ser ajustados ao longo do tempo. A role, porém, não é mutável na plataforma.

Se for necessário trocar a role de um usuário, ele precisa ser excluído e criado novamente com a role correta.

Ao revisar permissões, vale checar pelo menos quatro pontos:

* role do usuário;
* ambientes liberados;
* automações liberadas, quando for usuário limitado;
* Tabelas De/Para liberadas, quando for usuário limitado.

## Campos que influenciam a operação

Além da role, o cadastro de usuário costuma incluir dados que afetam experiência e governança, como:

* e-mail;
* idioma padrão;
* timezone;
* país;
* tenant e ambientes associados.

## Boas práticas

* escolha a role correta já na criação do usuário;
* use `Usuário Limitado` para acessos externos ou parciais;
* evite compartilhar contas entre pessoas;
* revise acessos administrativos de forma periódica;
* separe ambientes críticos por permissão, não apenas por combinado informal;
* documente internamente quem é responsável por cada liberação granular.

Para o fluxo prático de gestão de usuários, consulte também [Usuários e permissões](/produto/users).


# Visão geral

Recursos de API Management da plataforma

O módulo de API Management do TunnelHub permite publicar, proteger e monitorar APIs a partir de uma interface unificada.

## O que o módulo cobre

* cadastro e manutenção de definições de API;
* importação e exportação de especificações;
* publicação de Swagger público quando aplicável;
* uso de chaves de API e planos de uso;
* autenticação baseada em OAuth/Cognito;
* monitoramento de chamadas e logs de requisição e resposta.

## Recursos principais

* **APIs**: definições gerenciadas no produto.
* **Planos de uso**: políticas de consumo.
* **Chaves de API**: credenciais de uso associadas a planos.
* **Servidores de recursos**: escopos OAuth para proteger recursos.
* **Clientes**: aplicações consumidoras autenticadas.
* **Monitoramento**: histórico e detalhe de chamadas executadas.

## Quando usar

Use API Management quando você precisa:

* expor endpoints com governança centralizada;
* controlar consumo por cliente;
* aplicar autenticação e autorização por escopos;
* investigar chamadas com rastreabilidade operacional.

## Fluxo típico

Em um cenário comum, o trabalho acontece nesta sequência:

1. importar ou cadastrar a definição da API;
2. revisar rotas, documentação e comportamento esperado;
3. decidir se a API será pública, protegida por chave de API ou protegida por OAuth;
4. criar planos de uso, chaves de API, servidores de recursos e clientes quando necessário;
5. publicar e validar a documentação Swagger;
6. acompanhar chamadas e investigar falhas pelo monitoramento.

Consulte [Definições e monitoramento](/api-management/definitions-and-monitoring) para o fluxo operacional mais detalhado do módulo.

## Como pensar a modelagem

Ao desenhar uma API no TunnelHub, vale separar quatro decisões:

* **exposição**: quais recursos realmente precisam ficar acessíveis externamente;
* **consumo**: quem vai chamar a API e em que volume;
* **segurança**: se o cenário pede apenas controle de uso ou autenticação forte por escopo;
* **operação**: como o time vai monitorar chamadas, erros e comportamento do consumidor.

## Boas práticas

* trate a definição da API como parte do contrato do produto, e não apenas como detalhe técnico;
* use chaves de API para identificação e governança de consumo, não como única camada de segurança;
* prefira OAuth com escopos quando houver dados sensíveis ou múltiplos consumidores com perfis diferentes;
* mantenha nomes de planos, chaves e clientes alinhados ao contexto de negócio;
* acompanhe o monitoramento de forma contínua, principalmente após publicação e mudanças de contrato.


# Definições e monitoramento

O módulo de API Management combina duas frentes que andam juntas no dia a dia:

* definição e publicação da API;
* monitoramento das chamadas em produção.

## O que compõe uma definição de API

Na modelagem atual, uma definição de API normalmente reúne:

* nome e descrição;
* pacote relacionado;
* tipo de API, como `REST`, `HTTP` ou `WEBSOCKET`;
* URL de repositório, quando o time quer manter rastreabilidade com o código;
* configuração de documentação e exportação.

## Fluxo típico de definição

Um fluxo comum no produto segue esta ordem:

1. criar ou importar a definição;
2. revisar recursos, métodos e documentação;
3. decidir o modelo de proteção da API;
4. associar planos de uso, chaves de API, servidores de recursos ou clientes;
5. publicar e validar a documentação Swagger;
6. acompanhar chamadas pelo monitoramento.

## Importação e exportação

Além do cadastro manual, o módulo suporta importação e exportação de especificações.

No estado atual do produto, a exportação pode envolver formatos como:

* `OpenAPI 3`;
* `Swagger 2`;
* `JSON` ou `YAML`.

## Publicação de Swagger

Quando a API possui documentação pública habilitada, o produto também pode expor uma página Swagger para facilitar validação por consumidores e times internos.

Esse recurso é útil para:

* validar contrato após importação;
* compartilhar documentação técnica com parceiros;
* alinhar rapidamente payloads, headers e respostas esperadas.

## O que monitorar depois da publicação

Depois que a API entra em uso, o módulo de monitoramento ajuda a responder perguntas como:

* quais endpoints receberam chamadas em um período;
* quais consumidores geraram erro;
* quais métodos e recursos concentram mais falhas;
* qual foi o payload recebido ou devolvido em um caso específico.

## Filtros operacionais

No fluxo atual, o monitoramento de APIs tende a oferecer filtros por:

* intervalo de tempo;
* pacote;
* API;
* método HTTP;
* recurso;
* status;
* chave de API;
* cliente OAuth.

## Detalhe de chamada

Ao abrir uma chamada específica, o time costuma conseguir inspecionar:

* request original;
* headers;
* contexto da requisição;
* response;
* payloads decodificados quando o backend consegue descompactar o conteúdo.

## Boas práticas

* trate a definição como contrato do produto, não apenas como artefato técnico;
* publique documentação suficiente para reduzir dúvidas do consumidor;
* mantenha filtros e nomes orientados ao contexto de negócio;
* use monitoramento continuamente após mudanças de contrato ou autenticação.


# Planos de uso

Planos de uso controlam como consumidores utilizam suas APIs no TunnelHub.

## Para que servem

Eles permitem associar regras de consumo a:

* chaves de API;
* clientes ou parceiros específicos;
* conjuntos de APIs ou estágios publicados.

No produto atual, o vínculo com a API costuma ser feito por estágio publicado, o que ajuda a separar consumo por versão ou contexto operacional.

## Casos de uso comuns

* separar consumidores internos e externos;
* aplicar políticas por parceiro;
* organizar acesso por produto ou contrato;
* controlar a evolução do consumo ao longo do tempo.

## Relação com chaves de API

Chaves de API normalmente são associadas a planos de uso. O plano define o contexto de consumo; a chave identifica o consumidor naquele contexto.

Na prática:

* o plano de uso representa a política;
* a chave de API representa o consumidor;
* a combinação dos dois permite governar acesso e operação.

## Quando criar planos diferentes

Considere separar planos de uso quando houver diferença de:

* tipo de consumidor;
* criticidade do serviço;
* expectativa de volume;
* contrato comercial ou SLA;
* escopo de APIs liberadas.

## O que revisar antes de publicar

Antes de ativar um plano de uso, confirme:

* quais APIs ou estágios ele cobre;
* quais consumidores estarão vinculados a ele;
* se o plano faz sentido para o contexto de negócio;
* se a API também precisa de autenticação adicional por OAuth.

Quando o cenário exigir, revise também limites de throughput, quota e combinação com segurança por escopos.

## Boas práticas

* crie nomes orientados a negócio;
* mantenha uma descrição clara de quem deve usar cada plano;
* evite compartilhar a mesma key entre consumidores diferentes;
* combine planos de uso com autenticação forte quando a API exigir maior segurança;
* revise periodicamente planos antigos ou pouco utilizados.


# Chaves de API

Chaves de API identificam consumidores de APIs e costumam ser usadas em conjunto com planos de uso.

## Quando usar

Elas são úteis para:

* controlar o consumo de um cliente específico;
* diferenciar integrações que usam o mesmo endpoint;
* aplicar políticas de uso via plano de uso.

## O que uma chave de API resolve

Uma chave de API ajuda principalmente em governança e operação. Ela permite:

* saber quem está consumindo a API;
* segmentar consumidores por plano;
* investigar consumo e comportamento por cliente;
* facilitar rotação e substituição de credenciais de uso.

## Importante

Uma chave de API não deve ser tratada como mecanismo único de segurança para dados sensíveis. Para proteção forte, prefira combinar com autenticação baseada em OAuth e escopos.

## No produto

No módulo de APIs, você pode:

* listar chaves de API;
* criar e desativar chaves;
* associar chaves a planos de uso;
* inspecionar o contexto operacional quando necessário.

Em ambientes mais sensíveis, trate a visualização e o compartilhamento dessas chaves como processo controlado, porque o backend pode expor o valor efetivo da credencial dependendo do fluxo usado.

## Quando rotacionar

Considere rotacionar uma chave quando:

* houver suspeita de exposição;
* o consumidor mudar de aplicação ou ambiente;
* a chave deixar de representar corretamente o responsável atual;
* uma política interna exigir renovação periódica.

## Boas práticas

* rotacione chaves quando houver suspeita de exposição;
* use uma chave por consumidor ou aplicação;
* nunca incorpore chaves em código frontend público;
* documente responsabilidade e finalidade de cada chave;
* remova ou desative chaves obsoletas para reduzir risco operacional.


# Autenticação

O TunnelHub suporta diferentes estratégias de autenticação para APIs, incluindo chaves de API e fluxos baseados em OAuth com Cognito.

## Visão geral

As duas camadas mais comuns são:

* **Chave de API + plano de uso** para identificação e controle de consumo;
* **OAuth com escopos** para autenticação e autorização mais robustas.

Essas camadas podem coexistir, mas cumprem papéis diferentes. A chave de API ajuda a identificar e governar consumo; OAuth ajuda a autenticar e autorizar acesso a recursos protegidos.

## Quando usar cada uma

Use apenas chave de API quando o cenário pede principalmente governança de consumo e o risco é menor.

Use OAuth quando:

* a API expõe dados sensíveis;
* existe necessidade de escopos finos;
* há múltiplos clientes com acessos diferentes;
* governança e auditoria são importantes.

Em cenários corporativos, o mais comum é combinar controle de consumo com autenticação forte.

## Servidores de recursos

Servidores de recursos agrupam os escopos OAuth que protegem seus endpoints.

Cada servidor de recursos normalmente define:

* nome amigável;
* identificador único;
* lista de escopos com descrição.

Esses escopos podem ser associados a endpoints protegidos.

## Clientes

Clientes representam aplicações consumidoras autenticadas. Eles são usados para cenários machine-to-machine e outros fluxos controlados pela plataforma.

Ao criar um cliente, você normalmente define:

* identificação do cliente;
* expiração de tokens;
* escopos autorizados.

Dependendo do caso, o fluxo também envolve rotação de segredo do cliente, ativação ou inativação e outros controles operacionais.

## Fluxo prático mínimo

Um fluxo típico para uma API protegida costuma ser:

1. definir a API e seus endpoints;
2. decidir quais rotas exigem OAuth;
3. criar ou revisar o servidor de recursos;
4. criar o cliente consumidor;
5. autorizar os escopos corretos;
6. validar a obtenção de token e a chamada autenticada.

## Geração de token

Dependendo do fluxo configurado, a aplicação consumidora troca suas credenciais por um access token e usa esse token para chamar endpoints protegidos.

Na prática, a documentação da API e a configuração do cliente devem deixar claro:

* endpoint de token;
* grant esperado;
* escopos permitidos;
* formato de envio das credenciais.

## Boas práticas

* modele escopos com granularidade suficiente para refletir o negócio;
* evite compartilhar o mesmo cliente entre consumidores distintos;
* documente claramente quais rotas exigem escopos e quais usam apenas governança por chave;
* revise expiração de tokens conforme criticidade e perfil de integração;
* rotacione segredos de clientes sempre que houver suspeita de exposição.


# Importação de APIs

O TunnelHub permite importar definições de API para acelerar publicação, padronização e governança.

## Objetivo da importação

Importar uma API ajuda a:

* iniciar rapidamente a configuração de uma definição;
* reaproveitar especificações existentes;
* reduzir erros manuais na modelagem;
* alinhar documentação e configuração operacional.

## O que normalmente faz parte do fluxo

* importar a especificação base;
* revisar rotas e configurações;
* associar autenticação quando necessário;
* vincular planos de uso, chaves de API, servidores de recursos e clientes;
* publicar e validar por Swagger ou chamadas reais.

Dependendo do caso, a importação é só o começo. Ainda pode ser necessário revisar tipos de API, documentação pública, estágios, monitoramento e exportação do contrato final.

## Depois da importação

Depois de importar, revise com atenção:

* segurança dos endpoints;
* políticas de consumo;
* publicação de documentação Swagger;
* monitoramento e observabilidade da API.

Também vale validar se o arquivo importado deve ser exportado novamente em outro formato, como OpenAPI 3, Swagger 2, JSON ou YAML, para distribuição ao time consumidor.

## Recomendação

Considere a importação como ponto de partida. A definição final deve refletir a forma como a API será operada no TunnelHub, e não apenas o arquivo original.


# Visão geral

O `@tunnelhub/cli` é a ferramenta de linha de comando para fluxos de desenvolvimento e publicação de automações.

## Quando usar

Use a CLI para:

* autenticar na plataforma;
* listar ambientes, pacotes e automações;
* criar pacotes;
* criar automações com bootstrap de template;
* publicar deploys.

## Escopo atual da CLI

Os comandos públicos instalados hoje são:

* `login`
* `logout`
* `login-check`
* `list-environments`
* `list-packages`
* `create-package`
* `list-automations`
* `create-automation`
* `deploy-automation`

## Instalação

```bash
npm install -g @tunnelhub/cli
```

Pacote no npm: `https://www.npmjs.com/package/@tunnelhub/cli`

Depois da instalação, os dois comandos abaixo funcionam:

```bash
tunnelhub --help
th --help
```

## Fluxo de autenticação

O fluxo principal usa navegador e salva as credenciais localmente para reutilização e refresh automático.

```bash
tunnelhub login
```

Também existe fallback por usuário e senha:

```bash
tunnelhub login --password
```

## Como a CLI trabalha com ambientes

Comandos como `list-packages`, `create-package`, `list-automations` e `create-automation` dependem de `--env`. Você pode informar nome ou UUID do ambiente.

No fluxo interativo com login, `deploy-automation` também usa `--env`.

No fluxo CI/CD com credenciais M2M, use `--environment-id` ou `--env` com o UUID do ambiente.

Os comandos de listagem também aceitam `--json` quando você precisa integrar a saída em script.

## O que acontece ao criar uma automação

Ao executar `create-automation`, a CLI:

* consulta seus pacotes no ambiente escolhido;
* pede os dados da automação;
* cria a automação na plataforma;
* baixa um template oficial do GitHub;
* extrai esse template em uma nova pasta local;
* preenche o `service.uuid` no `tunnelhub.yml`.

## O que acontece no deploy

Ao executar `deploy-automation`, a CLI valida o `tunnelhub.yml`, verifica `package.artifact`, faz upload do artefato para S3 e solicita a criação do deploy.

O parâmetro `--message` é obrigatório. Ele deve carregar o contexto humano do deploy, especialmente em pipelines.

No fluxo CI/CD:

* a credencial é da account e pode ser autorizada para um ou mais ambientes;
* `createdBy` da revisão fica como `api-client:<clientId>`;
* a mensagem do deploy deve trazer o contexto do commit, autor e execução quando isso for relevante.

Exemplo de variáveis de ambiente para CI/CD:

* `TH_API_HOST`
* `TH_CLIENT_ID`
* `TH_CLIENT_SECRET`
* `TH_ENVIRONMENT_ID`
* `TH_AUTOMATION_ID`

Exemplo com GitHub Actions:

```bash
COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
COMMIT_SHA="$(git rev-parse --short HEAD)"

th deploy-automation \
  --environment-id "$TH_ENVIRONMENT_ID" \
  --automation "$TH_AUTOMATION_ID" \
  --message "GitHub Actions deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"
```

Consulte [Deploy via CI/CD](/cli/ci-cd-deployments), [Autenticação e ambientes](/cli/authentication-and-environments), [Comandos e referência](/cli/commands) e [`tunnelhub.yml`](/cli/tunnelhub-yml) para o contrato completo.


# Deploy via CI/CD

Esta página descreve o fluxo recomendado para publicar automações com a CLI em pipelines como GitHub Actions, GitLab CI e Jenkins, sem usar `tunnelhub login`.

O modelo recomendado usa credenciais CI/CD account-level com allowlist de ambientes. A credencial pertence à conta, mas só pode fazer deploy nos UUIDs de ambiente autorizados durante a criação.

## Pré-requisitos

Antes de configurar o pipeline, você precisa:

* ter uma automação já criada no TunnelHub;
* ter o `tunnelhub.yml` configurado com a automação que será publicada;
* saber o UUID de cada ambiente TunnelHub que o pipeline poderá publicar;
* ter permissão para acessar `Administration > Settings`;
* se for usar GitHub Actions, ter permissão para criar GitHub Environments, secrets e variables no repositório.

## 1. Gere a credencial no portal

No portal do TunnelHub:

1. acesse `Administration > Settings`;
2. abra a aba `CI/CD`;
3. clique em `Criar credencial CI/CD`;
4. informe um nome para a credencial;
5. selecione os ambientes autorizados para a credencial;
6. conclua a criação;
7. copie o `Client ID` e o `Client secret` exibidos.

Observações importantes:

* a credencial é da account, mas só pode fazer deploy nos ambientes autorizados na criação;
* você pode liberar ambientes específicos ou usar a opção de todos os ambientes;
* o `Client secret` é exibido apenas uma vez;
* se o secret for perdido ou exposto, use `Regenerar secret` ou `Revogar`;
* para produção, prefira credenciais separadas por ambiente para reduzir blast radius.

## 2. Salve secrets e variables do pipeline

No GitHub Actions, a separação recomendada é:

* `TH_CLIENT_ID`: GitHub Environment Secret;
* `TH_CLIENT_SECRET`: GitHub Environment Secret;
* `TH_ENVIRONMENT_ID`: GitHub Environment Variable;
* `TH_API_HOST`: repositório variable, GitHub Environment Variable ou valor fixo no workflow.

Exemplo de valores:

* `TH_API_HOST`: `https://api.tunnelhub.io`
* `TH_ENVIRONMENT_ID`: UUID de um ambiente TunnelHub autorizado para essa credencial

A automação publicada é inferida automaticamente a partir do `tunnelhub.yml` do projeto.

Se você usar outra plataforma de CI/CD, mantenha a mesma ideia:

* `TH_CLIENT_ID` e `TH_CLIENT_SECRET` como secrets;
* `TH_ENVIRONMENT_ID` como variável por ambiente;
* `TH_API_HOST` como variável ou valor fixo do pipeline.

## 3. Entenda GitHub Environment vs TunnelHub Environment

Esses dois conceitos são diferentes:

* GitHub Environment: controla approvals, protection rules, secrets e variables dentro do GitHub;
* TunnelHub Environment: é o UUID passado para `--environment-id` no deploy.

O vínculo entre os dois acontece pela variável `TH_ENVIRONMENT_ID`.

Exemplo:

* GitHub Environment `production` pode ter `TH_ENVIRONMENT_ID=<uuid-do-ambiente-production-no-tunnelhub>`;
* GitHub Environment `development` pode ter `TH_ENVIRONMENT_ID=<uuid-do-ambiente-development-no-tunnelhub>`.

## 4. Execute o deploy com a CLI

O deploy CI/CD usa a mesma CLI pública, mas autenticada com variáveis de ambiente M2M.

O parâmetro `--message` é obrigatório e deve carregar o contexto humano do deploy.

Os exemplos abaixo usam a mensagem completa do último commit e o e-mail do autor para preencher `--message`.

Antes de executar `deploy-automation`, o workflow precisa gerar o artefato ZIP configurado em `package.artifact` no `tunnelhub.yml`. Os exemplos abaixo usam `corepack` e detectam `pnpm`, `yarn` ou `npm` pelo lockfile do projeto. Ajuste os comandos se o seu repositório usar outro fluxo de build.

### Exemplo 1: `main` publica em `production`

Use este exemplo quando apenas a branch `main` deve publicar, mapeada para o GitHub Environment `production`.

```yaml
name: Deploy TunnelHub Automation

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy-production:
    if: github.ref_name == 'main'
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Enable Corepack
        run: corepack enable

      - name: Install dependencies
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm install --frozen-lockfile
          elif [ -f yarn.lock ]; then
            yarn install --immutable
          else
            npm ci
          fi

      - name: Build deployment artifact
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm build
          elif [ -f yarn.lock ]; then
            yarn build
          else
            npm run build
          fi

      - name: Install TunnelHub CLI
        run: npm install --global @tunnelhub/cli

      - name: Deploy automation
        env:
          TH_API_HOST: https://api.tunnelhub.io
          TH_CLIENT_ID: ${{ secrets.TH_CLIENT_ID }}
          TH_CLIENT_SECRET: ${{ secrets.TH_CLIENT_SECRET }}
          TH_ENVIRONMENT_ID: ${{ vars.TH_ENVIRONMENT_ID }}
        run: |
          COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
          COMMIT_MESSAGE="$(git log -1 --pretty=format:'%B')"
          COMMIT_SHA="$(git rev-parse --short HEAD)"
          DEPLOY_MESSAGE="${COMMIT_MESSAGE}

          Deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"

          tunnelhub deploy-automation \
            --environment-id "$TH_ENVIRONMENT_ID" \
            --message "$DEPLOY_MESSAGE"
```

### Exemplo 2: `develop` publica em `development` e `main` publica em `production`

Use este exemplo quando você quer separar ambientes por branch.

```yaml
name: Deploy TunnelHub Automation

on:
  push:
    branches:
      - develop
      - main
  workflow_dispatch:

jobs:
  deploy-development:
    if: github.ref_name == 'develop'
    runs-on: ubuntu-latest
    environment: development

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Enable Corepack
        run: corepack enable

      - name: Install dependencies
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm install --frozen-lockfile
          elif [ -f yarn.lock ]; then
            yarn install --immutable
          else
            npm ci
          fi

      - name: Build deployment artifact
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm build
          elif [ -f yarn.lock ]; then
            yarn build
          else
            npm run build
          fi

      - name: Install TunnelHub CLI
        run: npm install --global @tunnelhub/cli

      - name: Deploy automation
        env:
          TH_API_HOST: https://api.tunnelhub.io
          TH_CLIENT_ID: ${{ secrets.TH_CLIENT_ID }}
          TH_CLIENT_SECRET: ${{ secrets.TH_CLIENT_SECRET }}
          TH_ENVIRONMENT_ID: ${{ vars.TH_ENVIRONMENT_ID }}
        run: |
          COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
          COMMIT_MESSAGE="$(git log -1 --pretty=format:'%B')"
          COMMIT_SHA="$(git rev-parse --short HEAD)"
          DEPLOY_MESSAGE="${COMMIT_MESSAGE}

          Deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"

          tunnelhub deploy-automation \
            --environment-id "$TH_ENVIRONMENT_ID" \
            --message "$DEPLOY_MESSAGE"

  deploy-production:
    if: github.ref_name == 'main'
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Enable Corepack
        run: corepack enable

      - name: Install dependencies
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm install --frozen-lockfile
          elif [ -f yarn.lock ]; then
            yarn install --immutable
          else
            npm ci
          fi

      - name: Build deployment artifact
        run: |
          if [ -f pnpm-lock.yaml ]; then
            pnpm build
          elif [ -f yarn.lock ]; then
            yarn build
          else
            npm run build
          fi

      - name: Install TunnelHub CLI
        run: npm install --global @tunnelhub/cli

      - name: Deploy automation
        env:
          TH_API_HOST: https://api.tunnelhub.io
          TH_CLIENT_ID: ${{ secrets.TH_CLIENT_ID }}
          TH_CLIENT_SECRET: ${{ secrets.TH_CLIENT_SECRET }}
          TH_ENVIRONMENT_ID: ${{ vars.TH_ENVIRONMENT_ID }}
        run: |
          COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
          COMMIT_MESSAGE="$(git log -1 --pretty=format:'%B')"
          COMMIT_SHA="$(git rev-parse --short HEAD)"
          DEPLOY_MESSAGE="${COMMIT_MESSAGE}

          Deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"

          tunnelhub deploy-automation \
            --environment-id "$TH_ENVIRONMENT_ID" \
            --message "$DEPLOY_MESSAGE"
```

O deploy deve informar `--environment-id` ou `--env` com UUID. O backend valida se esse ambiente está na allowlist da credencial.

## 5. Entenda o que fica salvo na revisão

No deploy via CI/CD, a revisão criada guarda dois tipos de informação:

* `createdBy`: identifica a credencial técnica que autorizou o deploy;
* `message`: registra o contexto humano e operacional do deploy.

Na prática:

* `createdBy` fica como `api-client:<clientId>`;
* `message` deve conter dados como a mensagem do commit, SHA, e-mail do autor, identificador da execução ou o nome do workflow quando isso fizer sentido.

Esse desenho preserva auditoria técnica sem perder rastreabilidade humana.

## 6. Rotação e revogação

Na mesma aba `Administration > Settings > CI/CD`, você pode:

* usar `Regenerar secret` para emitir um novo secret para a credencial existente;
* usar `Revogar` para bloquear novos deploys com essa credencial.

Após regenerar o secret, atualize imediatamente os secrets do pipeline.

Se você usa GitHub Environments separados, atualize cada environment que depende dessa credencial.

Se migrar para credenciais separadas por ambiente, revogue as credenciais antigas assim que o novo fluxo estiver validado.

## Veja também

* [Visão geral da CLI](/cli/cli)
* [Comandos e referência](/cli/commands)
* [Autenticação e ambientes](/cli/authentication-and-environments)
* [`tunnelhub.yml`](/cli/tunnelhub-yml)


# Autenticação e ambientes

Quase todo fluxo da CLI depende de duas coisas: uma sessão válida e a resolução correta do ambiente.

## Fluxo principal de autenticação

O caminho recomendado usa navegador:

```bash
tunnelhub login
```

Nesse fluxo, a CLI:

* solicita o `Tenant ID`;
* abre a autenticação no frontend do TunnelHub;
* recebe tokens ao final do login;
* salva a sessão localmente para reutilização;
* usa refresh automático quando necessário.

## Fallback por usuário e senha

Em cenários específicos, a CLI ainda aceita fallback por usuário e senha:

```bash
tunnelhub login --password
```

Esse modo é útil quando o fluxo por navegador não é o mais prático, mas o padrão recomendado continua sendo autenticação pelo browser.

## Como validar a sessão

```bash
tunnelhub login-check
```

Use esse comando quando você quiser confirmar rapidamente se a sessão ainda é válida antes de listar recursos ou iniciar um deploy.

## Como encerrar a sessão

```bash
tunnelhub logout
```

Esse comando remove as credenciais locais salvas pela CLI.

## Como a CLI resolve ambientes

Comandos como `list-packages`, `create-package`, `list-automations`, `create-automation` e `deploy-automation` usam `--env`.

Você pode informar:

* o nome do ambiente;
* ou o UUID do ambiente.

A CLI resolve esse valor para o identificador correto antes de chamar a API.

## Descobrindo ambientes válidos

```bash
tunnelhub list-environments
```

Se você quiser usar saída de máquina:

```bash
tunnelhub list-environments --json
```

## Recomendações práticas

* prefira nome de ambiente apenas quando a nomenclatura do tenant for estável;
* use UUID em scripts quando quiser reduzir ambiguidade;
* valide a sessão antes de deploys importantes;
* confirme o tenant correto quando estiver em máquina compartilhada.

## Erros comuns

* **Sessão inválida**: execute `tunnelhub login` novamente.
* **Ambiente não encontrado**: valide o nome ou UUID com `tunnelhub list-environments`.
* **Tenant incorreto no login**: confirme se o `Tenant ID` corresponde ao tenant certo antes de autenticar.
* **Sessão antiga em máquina compartilhada**: rode `tunnelhub logout` antes de iniciar novo login.

## Check rápido antes de deploy

1. `tunnelhub login-check`
2. `tunnelhub list-environments`
3. confirmar o valor de `--env`
4. confirmar se o projeto certo contém `tunnelhub.yml`

Consulte também [Comandos e referência](/cli/commands).


# Comandos e referência

Esta página resume o comportamento atual dos comandos públicos da CLI e destaca os pré-requisitos mais importantes de cada fluxo.

## Matriz rápida

| Comando             | Exige login      | Exige `--env`    | Aceita `--json` |
| ------------------- | ---------------- | ---------------- | --------------- |
| `login`             | não              | não              | não             |
| `logout`            | não              | não              | não             |
| `login-check`       | sim              | não              | não             |
| `list-environments` | sim              | não              | sim             |
| `list-packages`     | sim              | sim              | sim             |
| `create-package`    | sim              | sim              | não             |
| `list-automations`  | sim              | sim              | sim             |
| `create-automation` | sim              | sim              | não             |
| `deploy-automation` | depende do fluxo | depende do fluxo | não             |

Para `deploy-automation`:

* no fluxo interativo, exige login e `--env`;
* no fluxo CI/CD M2M, não exige login no navegador e aceita `--environment-id` ou `--env` com UUID.

## Login

```bash
tunnelhub login
```

* abre autenticação via navegador;
* solicita `Tenant ID`;
* salva tokens localmente;
* usa refresh automático quando necessário.

Fallback:

```bash
tunnelhub login --password
```

## Verificação de sessão

```bash
tunnelhub login-check
```

Use para confirmar se as credenciais atuais ainda são válidas.

## Logout

```bash
tunnelhub logout
```

Remove credenciais locais salvas pela CLI.

## Listagem de ambientes

```bash
tunnelhub list-environments
```

Saída de máquina:

```bash
tunnelhub list-environments --json
```

## Listagem de pacotes

```bash
tunnelhub list-packages --env DEV
```

Também é possível usar `--json`.

Importante: `--env` é obrigatório. Você pode informar nome ou UUID do ambiente.

## Criação de pacote

```bash
tunnelhub create-package --env DEV
```

O comando é interativo e hoje exige `--env` no fluxo público atual.

## Listagem de automações

```bash
tunnelhub list-automations --env DEV
```

Também é possível usar `--json`.

Importante: `--env` é obrigatório. Você pode informar nome ou UUID do ambiente.

## Criação de automação

```bash
tunnelhub create-automation --env DEV
```

O comando permite escolher entre quatro templates:

* `NO_DELTA`
* `NO_DELTA_BATCH`
* `DELTA`
* `DELTA_BATCH`

Durante o fluxo, a CLI:

* consulta os pacotes do ambiente escolhido;
* coleta nome, descrição, pacote, retention period e URL de repositório;
* cria a automação na plataforma;
* baixa o template oficial correspondente do GitHub;
* extrai o projeto para uma nova pasta local;
* preenche `service.uuid` no `tunnelhub.yml` gerado.

## Deploy de automação

```bash
tunnelhub deploy-automation --env DEV --message "meu deploy"
```

Opções relevantes:

* `--automation <uuid>` para sobrescrever o `service.uuid` do `tunnelhub.yml`;
* `--environment-id <uuid>` para informar explicitamente o UUID do ambiente;
* `--publish` para solicitar criação de versão publicada.

Requisitos do deploy:

Fluxo com login:

* estar autenticado;
* executar o comando na pasta que contém `tunnelhub.yml`;
* ter `package.artifact` configurado;
* fornecer `--env`;
* fornecer `--message`.

Fluxo CI/CD M2M:

* configurar `TH_API_HOST`, `TH_CLIENT_ID` e `TH_CLIENT_SECRET`;
* executar o comando na pasta que contém `tunnelhub.yml`;
* ter `package.artifact` configurado;
* fornecer `--environment-id` ou `--env` com UUID;
* fornecer `--message`.

O fluxo de deploy faz upload do artefato por URL assinada e depois solicita a criação do deploy na plataforma.

No fluxo CI/CD com credenciais M2M:

* configure `TH_API_HOST`, `TH_CLIENT_ID` e `TH_CLIENT_SECRET`;
* use uma credencial autorizada para o ambiente alvo;
* use `--environment-id` ou `--env` com UUID do ambiente;
* use `--message` para registrar o contexto humano do deploy;
* `createdBy` da revisão ficará como `api-client:<clientId>`.

Exemplo:

```bash
COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
COMMIT_SHA="$(git rev-parse --short HEAD)"

th deploy-automation \
  --environment-id "$TH_ENVIRONMENT_ID" \
  --automation "$TH_AUTOMATION_ID" \
  --message "GitHub Actions deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"
```

## Troubleshooting rápido

* **Não autenticado**: rode `tunnelhub login`.
* **Ambiente inválido**: valide com `tunnelhub list-environments`.
* **`tunnelhub.yml` não encontrado**: execute o comando na raiz correta do projeto.
* **`package.artifact` ausente**: configure o caminho do ZIP antes do deploy.
* **UUID da automação ausente**: preencha `service.uuid` ou use `--automation`.

## Fluxo recomendado

```bash
tunnelhub login
tunnelhub list-environments
tunnelhub create-package --env DEV
tunnelhub create-automation --env DEV
# implementar e gerar artefato
tunnelhub deploy-automation --env DEV --message "primeira versão"
```

Consulte também [Deploy via CI/CD](/cli/ci-cd-deployments), [Autenticação e ambientes](/cli/authentication-and-environments) e [`tunnelhub.yml`](/cli/tunnelhub-yml).


# tunnelhub.yml

`tunnelhub.yml` é o manifesto local usado pelos fluxos de scaffold, build e deploy de projetos TunnelHub.

Em geral, ele responde três perguntas:

* qual recurso esse projeto representa;
* como o artefato deve ser gerado ou publicado;
* qual configuração de runtime acompanha a automação.

## Fonte de verdade pública

Use esta página como referência prática e o schema publicado no SchemaStore como referência estrutural:

* `https://json.schemastore.org/tunnelhub.json`

Se você usa editor com suporte a JSON Schema em YAML, vale associar esse schema ao arquivo para ganhar validação e autocomplete. Alguns campos recém-lançados podem aparecer nesta documentação antes da atualização do schema publicado.

## Exemplo mínimo

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 512
  timeout: 30

package:
  artifact: dist/artifact.zip
```

## Exemplo com campos opcionais

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555
  region: us-east-1

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 1024
  timeout: 120
  lambdaLayers:
    - arn:aws:lambda:us-east-1:123456789012:layer:shared-lib:1
  environmentVariables:
    LOG_LEVEL: info
  vpcConfig:
    subnetIds:
      - subnet-aaaa1111
    securityGroupIds:
      - sg-bbbb2222
    assignPublicIp: false

package:
  artifact: dist/artifact.zip
```

## Bloco `service`

Esse bloco identifica o tipo de recurso e o vínculo com a plataforma.

Campos mais importantes:

* `type`: normalmente `automation` no fluxo público atual;
* `uuid`: UUID da automação no TunnelHub;
* `region`: opcional em cenários que precisam declarar região explicitamente.

Durante `create-automation`, a CLI escreve `service.uuid` automaticamente no template baixado.

## Bloco `configuration`

Esse bloco orienta o runtime do projeto.

Campos mais comuns:

* `runtimeEngine`: como `LAMBDA` ou `ECS_FARGATE`;
* `entrypoint`: função ou arquivo de entrada esperado pelo bundle;
* `runtime`: runtime Node.js alvo;
* `memorySize`: memória esperada;
* `timeout`: tempo máximo de execução.

Também podem aparecer campos opcionais, como:

* `lambdaLayers`;
* `environmentVariables`;
* `runInVpc`;
* `sqlTables`;
* `vpcConfig`.

O schema publicado é a melhor referência para validar combinações e tipos desses campos.

### Tabelas de Apoio

Para usar [Tabelas de Apoio](/produto/sql-tables) em automações, habilite o bloco `sqlTables`:

```yaml
configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs24.x
  memorySize: 1024
  timeout: 60
  runInVpc: true
  sqlTables:
    enabled: true
```

Quando `sqlTables.enabled` é `true`, a automação precisa usar `runtime: nodejs24.x`, `runInVpc: true` e `runtimeEngine: LAMBDA` ou `ECS_FARGATE`.

Nota: a documentação deste campo pode preceder a atualização do schema publicado no SchemaStore. Até que `tunnelhub.json` seja atualizado, editores podem não validar ou autocompletar `configuration.sqlTables`.

## Bloco `package`

Esse bloco é especialmente importante para o deploy da CLI.

Campo crítico:

* `artifact`: caminho do artefato ZIP que será enviado para a plataforma.

Sem esse valor, `deploy-automation` não consegue concluir o fluxo de publicação.

## Quem usa cada parte do arquivo

* **CLI scaffold**: preenche `service.uuid`.
* **CLI deploy**: lê `service.uuid` e `package.artifact`.
* **SDK build tooling**: usa `configuration` para empacotar o projeto corretamente.

## O que é obrigatório na prática

Para o fluxo público atual de automações, o contrato mínimo é:

* `service.type`;
* `service.uuid`;
* `configuration.runtimeEngine`;
* `configuration.entrypoint`;
* `configuration.runtime`;
* `configuration.memorySize`;
* `package.artifact`.

## Erros comuns

* **`tunnelhub.yml` ausente**: execute o deploy na raiz do projeto correto.
* **`service.uuid` ausente**: recrie o projeto com `create-automation` ou informe `--automation` no deploy.
* **`package.artifact` ausente**: configure o caminho do ZIP antes do deploy.
* **artefato em caminho errado**: confirme se o arquivo realmente existe no caminho configurado.
* **bundle incompleto**: garanta que o artefato gerado contenha o que o runtime precisa.

## Relação com o fluxo de trabalho

O ciclo mais comum é:

1. `create-automation` gera o projeto e grava `service.uuid`;
2. o projeto gera o artefato configurado;
3. `deploy-automation` lê `tunnelhub.yml` e publica a nova versão.

Consulte também [Comandos e referência](/cli/commands) e [Criando sua primeira automação](/primeiros-passos/creating-your-first-automation).


# Visão geral

O `@tunnelhub/sdk` é a base pública para implementar automações no TunnelHub.

## O que o SDK entrega

* flows prontos para integrações com e sem delta;
* persistência e comparação de estado em flows delta;
* logging operacional com estratégia inteligente;
* utilitários para parâmetros, systems, Tabelas De/Para e Sequências;
* utilitários de interceptação HTTP, validação e concorrência;
* suporte a build, testes locais e troubleshooting.

## Instalação

```bash
npm install @tunnelhub/sdk
```

## Superfície pública atual

O entrypoint principal exporta, entre outros:

* `AutomationExecution`
* `DeltaIntegrationFlow`
* `BatchDeltaIntegrationFlow`
* `NoDeltaIntegrationFlow`
* `NoDeltaBatchIntegrationFlow`
* `AutomationParameter`
* `DataStore`
* `Sequences`
* `System`
* `setupInterceptor`
* `promiseWithConcurrency`
* `validateMetadata`
* `SDK`

O pacote também possui export separado para build tooling em `@tunnelhub/sdk/building`.

## Como pensar o runtime

Na prática, um projeto TunnelHub costuma combinar:

* um handler em `src/index.ts`;
* uma classe que herda um dos flows do SDK;
* `AutomationExecution.executeAutomation(...)` como ponto central da execução;
* `tunnelhub.yml` para build e deploy.

Consulte [Estrutura de projeto e runtime](/sdk/project-structure-and-runtime) para o fluxo completo.

## Como escolher um flow

* use **No delta** quando o processamento é unidirecional e sem comparação de estado;
* use **No delta batch** para alto volume unidirecional;
* use **Delta** quando precisa detectar insert, update e delete;
* use **Delta batch** quando precisa do modelo delta com processamento em lote.

## Skill para agentes

Além da documentação, existe um skill público chamado `tunnelhub-sdk` para ajudar agentes a trabalhar melhor com o SDK.

Esse skill é especialmente útil para:

* escolher o flow correto;
* trabalhar com parâmetros, systems, Tabelas De/Para e Sequências;
* entender logging, interceptor HTTP e utilitários;
* acelerar troubleshooting e implementação de testes.

Instalação:

```bash
npx skills add tunnelhub/agent-skills --skill tunnelhub-sdk -a opencode
```

Instalação global:

```bash
npx skills add tunnelhub/agent-skills --skill tunnelhub-sdk -a opencode -g
```

## Próximas leituras

* [Como escolher um flow](/sdk/choosing-a-flow)
* [Fluxos de integração](/sdk/integration-flows)
* [Helpers de plataforma](/sdk/platform-services)
* [Build, deploy e testes](/sdk/logging-and-testing)
* [Estrutura de projeto e runtime](/sdk/project-structure-and-runtime)


# Como escolher um flow

O SDK público expõe quatro classes base para automações. A escolha certa depende menos do sistema de origem e mais de como você quer comparar, agrupar e publicar dados.

## Visão rápida

| Flow                          | Quando usar                                                | Pergunta-chave                                        |
| ----------------------------- | ---------------------------------------------------------- | ----------------------------------------------------- |
| `NoDeltaIntegrationFlow`      | envio unidirecional sem comparação de estado               | "eu só preciso ler e enviar?"                         |
| `NoDeltaBatchIntegrationFlow` | envio unidirecional em alto volume                         | "eu preciso processar em lotes?"                      |
| `DeltaIntegrationFlow`        | comparação de origem e destino com insert, update e delete | "eu preciso reconciliar estados?"                     |
| `BatchDeltaIntegrationFlow`   | delta com processamento em lote                            | "eu preciso reconciliar estados e agrupar operações?" |

## `NoDeltaIntegrationFlow`

Use quando a automação apenas lê uma origem e executa uma ação de saída, sem comparar snapshots anteriores.

Cenários comuns:

* envio de eventos para API externa;
* exportação simples para data lake;
* processamento disparado por payload de webhook.

## `NoDeltaBatchIntegrationFlow`

Use quando o cenário continua sendo unidirecional, mas o volume pede agrupamento para reduzir custo, chamadas externas ou tempo de processamento.

Esse flow costuma fazer sentido quando:

* o destino aceita operações em lote;
* o custo por request é relevante;
* o volume por execução é alto.

## `DeltaIntegrationFlow`

Use quando a automação precisa comparar origem e destino para decidir entre:

* insert;
* update;
* delete.

Esse é o flow certo para sincronizações clássicas entre sistemas com reconciliação de estado.

Geralmente, ele pede uma modelagem clara de:

* `keyFields` para identidade do registro;
* `deltaFields` para comparação de mudança;
* ações de insert, update e delete.

## `BatchDeltaIntegrationFlow`

Use quando o cenário é delta, mas o volume exige batching.

Ele combina a lógica de reconciliação com operações agrupadas no destino, o que costuma ser útil em integrações com:

* APIs bulk;
* pipelines analíticos;
* sistemas com custo alto por operação individual.

## Regras práticas de decisão

* se não existe comparação entre origem e destino, comece por **No delta**;
* se existe comparação, comece por **Delta**;
* só vá para as versões **batch** quando houver ganho claro de volume, custo ou throughput;
* não escolha batch apenas por antecipação: a implementação e o troubleshooting tendem a ficar mais complexos.

## Exemplos de cenários

* **Webhook que recebe nota emitida e grava em banco**: `NoDeltaIntegrationFlow`
* **Exportação diária de pedidos para lake**: `NoDeltaBatchIntegrationFlow`
* **Sincronização de usuários entre HR e ERP**: `DeltaIntegrationFlow`
* **Sincronização massiva de catálogo entre duas bases**: `BatchDeltaIntegrationFlow`

## Depois da escolha

Depois de escolher o flow:

1. modele `defineMetadata()` com foco no monitoramento;
2. externalize parâmetros e sistemas no produto;
3. valide se precisa de Tabelas De/Para ou Sequências;
4. planeje build e deploy com `tunnelhub.yml`.

Consulte também [Fluxos de integração](/sdk/integration-flows) e [Helpers de plataforma](/sdk/platform-services).


# Fluxos de integração

O SDK expõe quatro flows públicos. Eles cobrem os cenários principais de sincronização e transferência de dados.

## Tabela rápida

| Flow                          | Quando usar                                  | Métodos centrais                                                                                                                            |
| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `NoDeltaIntegrationFlow`      | envio unidirecional sem comparação de estado | `loadSourceSystemData()`, `sendData()`, `defineMetadata()`                                                                                  |
| `NoDeltaBatchIntegrationFlow` | envio unidirecional em lote                  | `loadSourceSystemData()`, `sendDataInBatch()`, `defineMetadata()`                                                                           |
| `DeltaIntegrationFlow`        | reconciliação com insert, update e delete    | `loadSourceSystemData()`, `loadTargetSystemData()`, `insertAction()`, `updateAction()`, `deleteAction()`, `defineMetadata()`                |
| `BatchDeltaIntegrationFlow`   | reconciliação em lote                        | `loadSourceSystemData()`, `loadTargetSystemData()`, `batchInsertAction()`, `batchUpdateAction()`, `batchDeleteAction()`, `defineMetadata()` |

## 1. NoDeltaIntegrationFlow

Use quando a automação apenas coleta dados de uma origem e envia para um destino, sem comparar estado anterior.

Métodos centrais:

* `loadSourceSystemData()`
* `sendData()`
* `defineMetadata()`

## 2. NoDeltaBatchIntegrationFlow

Use quando o comportamento continua sendo no-delta, mas o volume pede agrupamento.

Métodos centrais:

* `loadSourceSystemData()`
* `sendDataInBatch()`
* `defineMetadata()`

## 3. DeltaIntegrationFlow

Use quando você precisa comparar origem e destino para identificar:

* inserts;
* updates;
* deletes.

Métodos centrais:

* `loadSourceSystemData()`
* `loadTargetSystemData()`
* `insertAction()`
* `updateAction()`
* `deleteAction()`
* `defineMetadata()`

## 4. BatchDeltaIntegrationFlow

Use quando o modelo delta precisa operar com maior volume e chamadas em lote.

Métodos centrais:

* `loadSourceSystemData()`
* `loadTargetSystemData()`
* `batchInsertAction()`
* `batchUpdateAction()`
* `batchDeleteAction()`
* `defineMetadata()`

## Key fields e delta fields

Nos flows delta, você define:

* **key fields** para identificar unicamente um registro;
* **delta fields** para detectar alterações relevantes.

Na prática, `keyFields` define identidade e `deltaFields` define o que conta como mudança relevante.

## Persistência de estado

Os flows delta usam os recursos internos do SDK para persistir o estado anterior da execução. Isso permite comparar snapshots e reduzir lógica manual dentro da integração.

## Metadados

`defineMetadata()` controla como os dados aparecerão no monitoramento.

Boas práticas:

* use labels compreensíveis para operação;
* não use `Action`, `Status` ou `Message` como `fieldLabel`;
* escolha o `fieldType` correto para melhorar filtros e visualização.

## Regras práticas de decisão

* se não existe comparação entre origem e destino, comece por **No delta**;
* se existe comparação, comece por **Delta**;
* só vá para as versões **batch** quando houver ganho claro de volume, custo ou throughput;
* não escolha batch apenas por antecipação.

Para uma visão mais orientada a cenários, consulte [Como escolher um flow](/sdk/choosing-a-flow).


# Helpers de plataforma

O SDK não se limita ao flow principal. Ele também expõe utilitários para ler configuração e estado operacional do TunnelHub.

## Parâmetros

`AutomationParameter` permite:

* ler parâmetros recebidos no evento;
* recuperar parâmetros obrigatórios;
* interpretar booleanos;
* persistir valores dinâmicos entre execuções, quando aplicável.

Esse recurso é útil para feature flags, cursores de sincronização, overrides por ambiente e pequenos estados controlados pelo produto.

Exemplo conceitual:

```ts
const lastCursor = AutomationParameter.getRequiredParameter(event.parameters, 'lastCursor');
```

## Systems

Os systems associados à automação chegam no payload de execução. Eles representam conexões como HTTP, banco de dados, FTP/SFTP, SOAP e outras.

O uso recomendado é localizar o system pelo `internalName` e usar seus parâmetros tipados para a integração.

Exemplo conceitual:

```ts
const erpSystem = event.systems.find((system) => system.internalName === 'ERP_HTTP');
```

Esse padrão reduz acoplamento entre código e credenciais do ambiente.

## Tabelas De/Para

`DataStore` permite consultar Tabelas De/Para e seus itens durante a execução.

Casos comuns:

* mapear status;
* traduzir códigos;
* resolver IDs externos;
* aplicar regra de negócio sem alterar o código.

Exemplo conceitual:

```ts
const dataStore = new DataStore(event);
const conversionTable = new ConversionTable(dataStore);
const mappedValue = await conversionTable.getValueFromConversionTable(
  'sales-channel-map',
  order.channel,
  undefined,
  true,
);
```

## Sequências

`Sequences` permite pedir o próximo valor de uma Sequência diretamente no runtime da automação.

Esse helper é útil quando o destino precisa de identificadores controlados pela plataforma, sem depender de contadores locais no projeto.

Exemplo conceitual:

```ts
const nextValue = await sequences.getSequenceNextValue('ORDER_NUMBER');
```

## Tabelas de Apoio

`SqlTables` permite inserir, consultar, atualizar e remover linhas em Tabelas de Apoio associadas à automação.

Esse helper deve ser usado apenas no runtime gerenciado com `sqlTables.enabled=true`, porque depende do SQLite montado pela plataforma.

Exemplo conceitual:

```ts
const sqlTables = new SqlTables(event);
const row = await sqlTables.insertRow('customer-cache', {
  document: '12345678900',
  name: 'Cliente exemplo',
});

await sqlTables.updateRow('customer-cache', row.rowId, {
  name: 'Cliente atualizado',
});
```

## Interceptor HTTP

`setupInterceptor()` habilita interceptação de chamadas HTTP para ampliar a observabilidade de requisições e respostas.

Isso é útil quando a integração conversa com APIs externas e o time precisa de mais rastreabilidade.

Em projetos orientados a troubleshooting, esse recurso pode reduzir bastante o tempo de investigação.

## Utilitários

O SDK também exporta utilitários como:

* `promiseWithConcurrency()`
* `promiseAllSettled()`
* `validateMetadata()`
* `validateMetadataArray()`

Esses utilitários ajudam a controlar concorrência, validar configurações e simplificar implementações de alto volume.

## Recomendações práticas

* localize systems por `internalName`, nunca por posição na lista;
* prefira parâmetros e Tabelas De/Para a condicionais rígidas no código;
* use Tabelas de Apoio quando o dado tiver estrutura relacional própria;
* use `Sequences` apenas quando a geração de identificador realmente pertence à plataforma;
* ative interceptação HTTP com intenção clara de observabilidade.


# Build, deploy e testes

O SDK atual não cobre apenas runtime. Ele também participa do empacotamento do projeto, da estratégia de logging e dos testes locais.

## Build e empacotamento

O pacote público expõe tooling de build em `@tunnelhub/sdk/building` e o bin `tunnelhub-sdk-esbuild`.

Esse fluxo lê a configuração do projeto, usa `tunnelhub.yml` como referência e normalmente gera um artefato ZIP para deploy.

Na prática, isso ajuda a padronizar:

* entrypoint;
* runtime;
* memória e timeout;
* arquivos incluídos no bundle;
* artefato final esperado pela CLI.

## Estratégia de logging

O SDK escolhe entre logging em tempo real e logging em lote conforme o volume e o perfil da execução.

Em alto nível:

* cargas pequenas tendem a usar logging em tempo real;
* cargas muito grandes tendem a usar modo em lote;
* flows podem ajustar limiares protegidos para adaptar o comportamento.

Esse desenho melhora custo e performance sem exigir lógica manual em cada integração.

## Observabilidade

Os logs da automação alimentam as telas de monitoramento da plataforma. A qualidade dos metadados e das mensagens impacta diretamente a capacidade de suporte e investigação.

Boas práticas:

* incluir identificadores de negócio nos metadados;
* evitar mensagens genéricas demais;
* diferenciar erro técnico de erro funcional;
* usar `setupInterceptor()` apenas quando o ganho investigativo justificar.

## Testes locais

Para testes, o SDK expõe o flag:

```ts
SDK.testMode = true;
```

Esse modo é recomendado para suítes Jest e cenários de mock de serviços AWS ou chamadas externas.

Para `SqlTables`, o modo de teste apenas desativa a validação de runtime no construtor. Faça mock explícito dos métodos usados, como `queryRows` e `insertRow`; ele não cria SQLite local, EFS ou persistência. Consulte [Tabelas de Apoio](/produto/sql-tables#testes-locais) para um exemplo com fixtures JSON e armazenamento em memória.

## Modo verboso

Quando necessário, você pode habilitar:

```ts
SDK.verbose = true;
```

Isso ajuda durante desenvolvimento e depuração local.

## O que vale testar em uma automação

Checklist mínimo:

* handler chama `AutomationExecution.executeAutomation(...)` corretamente;
* flow instancia sem erro com payload mínimo;
* `defineMetadata()` está válida;
* principal caminho feliz da integração está coberto;
* erros relevantes retornam mensagens operacionais úteis.

## Troubleshooting comum

* **parâmetro obrigatório ausente**: valide o cadastro no produto e o helper usado no código;
* **Tabela De/Para ou Sequência não encontrada**: confirme código, ambiente e associação correta;
* **erro de metadata**: revise labels reservadas e tipos inválidos;
* **artefato inconsistente**: confira `tunnelhub.yml`, entrypoint e caminho do ZIP antes do deploy.


# Estrutura de projeto e runtime

Esta página mostra como um projeto TunnelHub costuma ser organizado e como o SDK participa da execução.

## Estrutura típica

Um template oficial normalmente inclui:

* `src/index.ts`;
* uma classe de integração em `src/core/` ou equivalente;
* `metadata`;
* tipos e modelos;
* `__tests__`;
* `tunnelhub.yml`.

## Handler

O handler principal costuma:

* instanciar a classe de integração;
* chamar `AutomationExecution.executeAutomation(...)`;
* retornar sucesso HTTP quando não há erro fatal.

Esse é o ponto de entrada esperado pelo runtime público.

## Classe de integração

Essa classe herda um dos flows do SDK e concentra a lógica principal de negócio:

* extração da origem;
* reconciliação com destino, quando houver delta;
* envio, insert, update ou delete;
* definição de metadados.

## Payload de execução

Em runtime, a automação recebe um payload que costuma incluir pelo menos:

* identificadores de tenant, ambiente, automação e execução;
* systems associados;
* parameters cadastrados;
* payload do trigger, quando aplicável.

É esse contrato que conecta o produto ao código.

## Relação com `tunnelhub.yml`

`tunnelhub.yml` define como o projeto será empacotado e publicado. O runtime depende desse arquivo para localizar o artefato e interpretar a configuração básica do serviço.

## Fluxo completo

1. a CLI cria a automação e baixa um template;
2. o projeto implementa a integração com o SDK;
3. o build gera o artefato definido em `package.artifact`;
4. a CLI publica uma nova versão;
5. o produto executa e monitora a automação.


# Visão geral

O `@tunnelhub/mcp` conecta clientes compatíveis com Model Context Protocol ao TunnelHub para investigação operacional e leitura de recursos da plataforma.

## Casos de uso

Use o MCP para:

* autenticar no TunnelHub pelo navegador;
* consultar a sessão atual e o ambiente ativo;
* listar as sessões salvas localmente;
* listar pacotes, systems, automações e Tabelas De/Para;
* localizar execuções por período;
* abrir logs, traces e resumos de execução;
* consultar APIs, planos de uso, chaves de API, clientes e servidores de recursos;
* investigar consumo e estatísticas do tenant.

O uso mais valioso hoje costuma estar em investigação de execuções e análise de logs operacionais.

## Perfil da ferramenta

O MCP atual é principalmente orientado a leitura e suporte operacional. Ele não substitui o portal para modelagem completa de recursos.

Em outras palavras, ele é ideal para:

* investigar incidentes;
* responder perguntas operacionais rapidamente;
* resumir execuções e falhas;
* consultar dados de ambiente sem navegar manualmente por múltiplas telas.

## Instalação local

O uso principal é via `npx`:

```bash
npx -y @tunnelhub/mcp@latest
```

Se você estiver desenvolvendo localmente:

```bash
pnpm install
pnpm build
node dist/index.js
```

## Modo de execução

O pacote público atual é usado via `stdio`, que é o modo esperado pelos clientes MCP no desktop.

Para a maioria dos times, esse continua sendo o caminho principal.

## Como a autenticação funciona hoje

O fluxo principal continua sendo via ferramentas de sessão do próprio MCP. No primeiro uso, o cliente chama `login_tunnelhub`, o MCP abre o navegador local, você faz login no TunnelHub e a sessão fica salva localmente.

Para o primeiro login, informe `accountName` da empresa. Se houver ambiguidade ou o nome não resolver a empresa correta, repita o fluxo com `tenantId`.

No conjunto público atual, as ferramentas de sessão registradas são:

* `login_tunnelhub`
* `current_session_tunnelhub`
* `list_sessions_tunnelhub`
* `list_environments_tunnelhub`
* `switch_environment_tunnelhub`
* `logout_tunnelhub`

Depois do login, as demais ferramentas passam a usar a sessão ativa e o ambiente atual. `list_sessions_tunnelhub` permite inspecionar as sessões salvas localmente, e `logout_tunnelhub` permite remover a sessão atual ou uma sessão específica.

## Exemplos de perguntas úteis

Alguns exemplos de uso em linguagem natural:

* "Faça login no TunnelHub"
* "Qual sessão está ativa?"
* "Quais sessões estão salvas localmente?"
* "Liste os ambientes disponíveis"
* "Encontre execuções com erro da automação X nas últimas 24 horas."
* "Resuma a execução Y e destaque os principais erros."
* "Mostre os systems do ambiente atual relacionados ao pacote Z."
* "Quais APIs tiveram chamadas com status 500 hoje?"

## Limites práticos

O MCP foi desenhado para operação e investigação, então vale considerar alguns limites:

* muitas consultas dependem de intervalo de tempo explícito;
* detalhes de execução exigem identificadores específicos;
* parte das respostas reflete o backend atual, incluindo nomes técnicos do produto;
* algumas respostas podem incluir dados sensíveis, como payloads de logs de API.

## Próximos passos

* Leia [Runtime e autenticação](/mcp/runtime-and-auth).
* Leia [Catálogo de ferramentas](/mcp/tools).
* Leia [Investigando execuções](/mcp/investigating-executions).


# Runtime e autenticação

O MCP do TunnelHub é publicado hoje para uso via `stdio`.

## Execução local

* transporte `stdio`;
* usado por ferramentas como OpenCode, Claude Desktop e Cursor;
* entrypoint local em `dist/index.js`.

Esse é o modo principal para uso no dia a dia.

## Como a autenticação funciona hoje

No fluxo principal atual, a sessão é criada e gerenciada pelas ferramentas de sessão do próprio MCP.

Fluxo típico:

1. o cliente chama `login_tunnelhub`;
2. o MCP abre o navegador local;
3. você faz login no TunnelHub;
4. a sessão fica salva localmente;
5. as próximas ferramentas passam a usar a sessão ativa.

Se este for o primeiro login, informe `accountName`. Quando o nome da empresa não for suficiente, repita com `tenantId`.

## Ferramentas de sessão

O conjunto atual de ferramentas de sessão inclui:

* `login_tunnelhub`;
* `current_session_tunnelhub`;
* `list_sessions_tunnelhub`;
* `list_environments_tunnelhub`;
* `switch_environment_tunnelhub`;
* `logout_tunnelhub`.

## Ambiente ativo

Depois do login, o MCP usa a sessão ativa e permite listar ambientes disponíveis e trocar o ambiente corrente com `switch_environment_tunnelhub`.

## Persistência local

As sessões ficam salvas localmente para reutilização até que você faça logout da sessão atual ou remova uma sessão específica com `logout_tunnelhub`.

## Variáveis úteis

No modo atual, as configurações mais comuns incluem:

* `OAUTH_CALLBACK_PORT`
* `TUNNELHUB_FRONTEND_URL`
* `FRONTEND_URL`
* `TUNNELHUB_API_HOST`
* `API_HOST`

## Observação prática

Para uso público atual, concentre a configuração no modo `stdio` e nas ferramentas de sessão acima.


# Catálogo de ferramentas

O servidor MCP atual registra grupos de ferramentas para navegação de sessão, recursos da plataforma e monitoramento.

## Sessão e ambiente

* `login_tunnelhub`
* `current_session_tunnelhub`
* `list_sessions_tunnelhub`
* `list_environments_tunnelhub`
* `switch_environment_tunnelhub`
* `logout_tunnelhub`

Essas são as referências públicas para autenticação, navegação de sessão e troca de ambiente no servidor atual.

Observações práticas:

* `login_tunnelhub` aceita `accountName` ou `tenantId`;
* no primeiro login, informe `accountName` quando possível;
* `list_sessions_tunnelhub` lista as sessões salvas, mas não troca a sessão ativa;
* `logout_tunnelhub` pode remover a sessão atual ou uma sessão específica.

## Tenants

* `list_tenants_tunnelhub`
* `get_tenant_tunnelhub`

## Pacotes, systems e Tabelas De/Para

As ferramentas atuais cobrem:

* listagem e detalhe de pacotes;
* listagem e detalhe de systems;
* listagem de Tabelas De/Para e de seus itens.

## Automações e monitoramento

As ferramentas atuais cobrem:

* listagem e detalhe de automações;
* histórico de deploys;
* action logs;
* execução manual;
* busca de execuções por período;
* resumo, logs e traces de uma execução.

Fluxo recomendado para troubleshooting:

1. localizar a execução com `find_execution_tunnelhub`;
2. abrir o resumo com `summarize_execution_tunnelhub`;
3. seguir para `get_execution_traces_tunnelhub` ou `get_execution_logs_tunnelhub`.

## API Gateway

O grupo de APIs cobre:

* listagem e detalhe de APIs;
* planos de uso;
* chaves de API;
* clientes de autenticação;
* servidores de recursos;
* logs de APIs por recurso ou por janela de tempo;
* detalhe de log com payloads decodificados quando possível.

## Estatísticas

O MCP também expõe consultas de estatísticas gerais do tenant, incluindo consumo de execuções.

## Observações operacionais

* consultas de monitoramento dependem de janela de tempo explícita;
* detalhes de execução exigem `automationId`, `executionId` e `executionPeriod`;
* `executionPeriod` deve estar no formato `YYYY-MM`;
* respostas de chaves de API podem incluir dados sensíveis dependendo do backend, então trate essa informação com cuidado;
* logs detalhados de API podem expor payloads de request e response, então higienize qualquer reutilização externa.


# Investigando execuções

O melhor uso do MCP do TunnelHub hoje é investigação operacional.

Em vez de navegar manualmente pelo portal, você pode combinar ferramentas para localizar uma execução, abrir o resumo e seguir para logs ou traces.

## Fluxo recomendado

O fluxo mais seguro costuma ser:

1. localizar a execução por janela de tempo;
2. capturar `automationId`, `executionId` e `executionPeriod`;
3. abrir o resumo da execução;
4. aprofundar em logs ou traces.

## Passo 1: encontrar a execução

Use `find_execution_tunnelhub` quando você já tem uma janela de tempo e quer localizar uma execução específica.

Exemplo de parâmetros:

```json
{
  "startDate": "2026-03-17 00:00:00",
  "endDate": "2026-03-17 23:59:59",
  "automationId": "<automation-id>",
  "status": "ERROR"
}
```

Essa etapa é importante porque as ferramentas de detalhe exigem `executionPeriod` no formato `YYYY-MM`.

## Passo 2: abrir o resumo

Depois de encontrar a execução, use `summarize_execution_tunnelhub` ou `get_execution_tunnelhub`.

Exemplo conceitual:

```json
{
  "automationId": "<automation-id>",
  "executionId": "<execution-id>",
  "executionPeriod": "2026-03"
}
```

O resumo é o melhor ponto de entrada para entender:

* status consolidado;
* mensagens principais;
* volume processado;
* indícios iniciais de falha.

## Passo 3: abrir traces

Quando o problema parece técnico, siga para `get_execution_traces_tunnelhub`.

Use filtros quando quiser reduzir ruído, por exemplo:

* `level`;
* `status`;
* `message`;
* `timestampStart` e `timestampEnd`.

Os traces ajudam mais quando você quer reconstruir a sequência de eventos internos da execução.

## Passo 4: abrir logs de processamento

Quando o problema parece ligado a registros de negócio, use `get_execution_logs_tunnelhub`.

Esse caminho é ideal para responder perguntas como:

* quais itens falharam;
* qual ação foi tentada;
* quais mensagens apareceram por item;
* como os metadados definidos no SDK explicam o erro.

## Quando usar cada ferramenta

* `find_execution_tunnelhub`: localizar a execução certa.
* `summarize_execution_tunnelhub`: obter contexto rápido.
* `get_execution_tunnelhub`: abrir o detalhe estruturado.
* `get_execution_traces_tunnelhub`: investigar comportamento técnico.
* `get_execution_logs_tunnelhub`: investigar itens de negócio.

## Exemplo de pergunta em linguagem natural

Você pode pedir algo como:

"Encontre execuções com erro da automação X hoje, resuma a mais recente e destaque os traces com falha."

O bom resultado depende de informar:

* período;
* automação, quando conhecida;
* status desejado;
* profundidade esperada da análise.

## Cuidados práticos

* sempre informe janela de tempo explícita nas buscas;
* guarde `executionPeriod`, porque ele é obrigatório nas ferramentas de detalhe;
* lembre que logs e traces podem conter dados sensíveis dependendo da automação;
* sanitize qualquer saída antes de reutilizar o conteúdo em documentação pública ou tickets externos.