# 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 e tabelas de conversão

`DataStore` permite consultar tabelas de conversão 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');
```

## 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 `Sequences` apenas quando a geração de identificador realmente pertence à plataforma;
* ative interceptação HTTP com intenção clara de observabilidade.