# 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](https://docs.tunnelhub.io/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](https://docs.tunnelhub.io/sdk/choosing-a-flow)
* [Fluxos de integração](https://docs.tunnelhub.io/sdk/integration-flows)
* [Helpers de plataforma](https://docs.tunnelhub.io/sdk/platform-services)
* [Build, deploy e testes](https://docs.tunnelhub.io/sdk/logging-and-testing)
* [Estrutura de projeto e runtime](https://docs.tunnelhub.io/sdk/project-structure-and-runtime)