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

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.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/primeiros-passos/creating-your-first-automation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.