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


---

# 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/sdk/platform-services.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.