Referência da API JavaScript

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:

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.

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 #

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 #

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 #

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 #

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 #

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 #

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 #

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.

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