# Referência da API JavaScript

> O objeto global cat do SDK 1.4: mensagens HTTP, eventos, hooks de alteração, envios, APIs externas, laboratório, recursos e utilidades.

- Idioma: pt-BR
- URL canônica: https://netcattest.com/catsuite/docs/extensoes/api
- Seção: Extensões
- Atualizado: 2026-10-05
- Outro idioma (en): https://netcattest.com/catsuite/en/docs/extensions/api

Toda extensão recebe o objeto global e congelado `cat`. `cat.apiVersion` vale `1` e `cat.sdkVersion` vale `"1.4.0"`. A API v1 permanece compatível em todas as versões do SDK.

## Mensagens HTTP

Requests e responses chegam como `CatMessage`:

| Campo | Descrição |
|---|---|
| `id` | identificador da mensagem |
| `source` | origem: `proxy`, `network_proxy`, `repetir`, `intruso`, `descobridor`, `extension` ou `laboratory` |
| `session` | sessão do Proxy de Rede, ou `null` |
| `stage` | `request` ou `response` |
| `url`, `method` | destino e método |
| `headers` | lista ordenada de `{name, value}` |
| `body` | `bytes`, `size`, `complete`, `truncated`, `available`, `mutable`, `representation` e `sha256` |
| `status`, `reason` | somente em responses |
| `time` | carimbo de tempo |
| `request` | request original, presente em responses |

`body.representation` indica bytes de transporte (`wire`) ou descomprimidos pelo cliente (`decoded`). O preview editável tem até 32 KiB.

## Eventos

Observadores podem ser assíncronos e exigem `traffic.read`.

```js
cat.events.on('http.request', async message => {
  await cat.storage.set('ultimaUrl', message.url);
});

cat.events.on('http.response', async message => {
  if (message.status >= 500) {
    cat.log({'pt-BR': 'Falha no servidor observada.', en: 'Server failure observed.'}, 'warning');
  }
});
```

Eventos disponíveis: `http.request`, `http.response` e `http.complete`.

## Hooks de alteração

```js
cat.proxy.onRequest(message => {
  if (cat.http.parseUrl(message.url).hostname !== 'api.aurora.test') return;
  message.headers = message.headers.filter(h => h.name.toLowerCase() !== 'x-cat-lab');
  message.headers.push({name: 'X-Cat-Lab', value: 'auditor'});
  return message;
});

cat.proxy.onResponse(message => {
  message.headers.push({name: 'X-Cat-Auditor', value: '1'});
  return message;
});
```

Regras dos hooks, que exigem `traffic.modify`:

- São síncronos e têm até 100 ms por execução. Retornar uma Promise gera `E_HOOK_ASYNC`.
- Não enviam requests, não persistem dados e não atualizam a interface.
- Retornar `undefined` mantém a mensagem; retornar a mensagem aplica a alteração.
- Não altere identidade, origem ou flags de integridade. Headers não aceitam quebra de linha.
- Headers de compressão não podem ser alterados, e só corpos com `mutable: true` aceitam edição.
- A mensagem efetiva é validada antes do envio. Escopos e bloqueios do aplicativo continuam valendo.

## Envios HTTP

```js
const resposta = await cat.http.send({
  id: 'consulta-1',
  url: 'https://api.aurora.test/api/pedidos',
  method: 'GET',
  headers: [{name: 'Accept', value: 'application/json'}]
});
cat.http.cancel('consulta-1');
```

`cat.http.send` exige `http.send` e usa os `targets` do manifesto. Os destinos são verificados antes do envio e depois das alterações, redirects automáticos ficam desativados e o TLS é validado. Há duas chamadas simultâneas por extensão, prazo total de 120 segundos e respostas de até 8 MiB. Envios ao próprio proxy do CatSuite são recusados com `E_PROXY_LOOP`.

## APIs externas

```js
const resposta = await cat.external.call({
  url: 'https://advisories.aurora.test/advisories?code=CACHE-001',
  method: 'GET',
  credentialId: 'minha-chave'
});
```

`cat.external.call` exige `external.call` e usa `externalHosts`. A credencial é configurada na tela da extensão, protegida pelo Android Keystore e adicionada pelo host como `Bearer`. O código nunca recebe o valor secreto.

## Laboratório

```js
const capturada = await cat.laboratory.capture({
  url: 'https://api.aurora.test/api/perfil',
  method: 'GET',
  headers: [{name: 'Accept', value: 'application/json'}]
});
```

Com `settings.laboratory` igual a `true`, o host simula tráfego capturado de `api.aurora.test`, executa os hooks de captura e alteração e também simula `advisories.aurora.test`. O laboratório não realiza conexões externas. Sem o modo laboratório, a chamada falha com `E_LABORATORY`.

## Repetir

```js
cat.tools.repeater.open({url: 'https://api.aurora.test/api/perfil', method: 'GET', headers: []});
```

Abre a mensagem no Repetir. Exige `repeater` e só aceita destinos aprovados.

## Recursos do pacote

```js
const fixtures = JSON.parse(await cat.resources.get('fixtures.json'));
const bytes = await cat.resources.get('assinatura.bin', 'bytes');
```

Lê arquivos do próprio pacote. Textos têm até 128 KiB e recursos binários até 32 KiB. Não há acesso aos arquivos do aparelho.

## Utilidades

| Função | Descrição |
|---|---|
| `cat.http.parseUrl(url)` | retorna `{scheme, hostname, port, pathname, query}` e recusa credenciais na URL |
| `cat.bytes.fromText(texto)` | converte texto UTF-8 em lista de bytes |
| `cat.bytes.toText(bytes)` | converte lista de bytes em texto UTF-8 |
| `cat.i18n.locale` | `pt-BR` ou `en` |
| `cat.i18n.text(valor)` | escolhe o texto do idioma atual em um objeto bilíngue |
| `cat.log(mensagem, nivel)` | registra `info`, `warning` ou `error`, com texto simples ou bilíngue |

## Erros

Falhas usam códigos `E_*` estáveis com descrição traduzida, como `E_PERMISSION`, `E_HOST`, `E_TIMEOUT` e `E_BODY`. Consulte a [lista completa de códigos](https://netcattest.com/catsuite/docs/referencia/erros).

```js
try {
  await cat.http.send({url: 'https://fora-do-escopo.test/'});
} catch (erro) {
  cat.log(String(erro.code || erro.message), 'error');
}
```