# Criando sua primeira automação

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 conversão.

```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`.

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.

## 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.

## Próximos passos

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