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:

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:

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

DataStore permite consultar Tabelas De/Para 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:

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:

const nextValue = await sequences.getSequenceNextValue('ORDER_NUMBER');

Tabelas de Apoio

SqlTables permite inserir, consultar, atualizar e remover linhas em Tabelas de Apoio associadas à automação.

Esse helper deve ser usado apenas no runtime gerenciado com sqlTables.enabled=true, porque depende do SQLite montado pela plataforma.

Exemplo conceitual:

const sqlTables = new SqlTables(event);
const row = await sqlTables.insertRow('customer-cache', {
  document: '12345678900',
  name: 'Cliente exemplo',
});

await sqlTables.updateRow('customer-cache', row.rowId, {
  name: 'Cliente atualizado',
});

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 Tabelas de Apoio quando o dado tiver estrutura relacional própria;
• use Sequences apenas quando a geração de identificador realmente pertence à plataforma;
• ative interceptação HTTP com intenção clara de observabilidade.