JavaScript API reference

Every extension receives the global, frozen cat object. cat.apiVersion is 1 and cat.sdkVersion is "1.4.0". API v1 stays compatible across every SDK version.

HTTP messages #

Requests and responses arrive as CatMessage:

body.representation tells whether bytes are on the wire (wire) or decompressed by the client (decoded). The editable preview is up to 32 KiB.

Events #

Observers may be asynchronous and require traffic.read.

cat.events.on('http.request', async message => {
  await cat.storage.set('lastUrl', 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');
  }
});

Available events: http.request, http.response and http.complete.

Mutation hooks #

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;
});

Hook rules, which require traffic.modify:

• They are synchronous and get up to 100 ms per run. Returning a Promise raises E_HOOK_ASYNC.
• They do not send requests, persist data or update the interface.
• Returning undefined keeps the message; returning the message applies the change.
• Do not change identity, origin or integrity flags. Headers do not accept line breaks.
• Compression headers cannot be changed, and only bodies with mutable: true can be edited.
• The effective message is validated before sending. App scopes and blocks still apply.

HTTP sends #

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

cat.http.send requires http.send and uses the manifest targets. Destinations are checked before sending and after changes, automatic redirects are disabled and TLS is validated. There are two concurrent calls per extension, a 120-second total timeout and responses up to 8 MiB. Sends to CatSuite’s own proxy are rejected with E_PROXY_LOOP.

External APIs #

const response = await cat.external.call({
  url: 'https://advisories.aurora.test/advisories?code=CACHE-001',
  method: 'GET',
  credentialId: 'my-key'
});

cat.external.call requires external.call and uses externalHosts. The credential is configured on the extension screen, protected by Android Keystore and added by the host as Bearer. Your code never receives the secret value.

Laboratory #

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

With settings.laboratory set to true, the host simulates captured traffic from api.aurora.test, runs the capture and mutation hooks and also simulates advisories.aurora.test. The laboratory makes no external connections. Without laboratory mode the call fails with E_LABORATORY.

Repeater #

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

Opens the message in Repeater. Requires repeater and only accepts approved destinations.

Package resources #

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

Reads files from the package itself. Text is limited to 128 KiB and binary resources to 32 KiB. There is no access to device files.

Utilities #

Errors #

Failures use stable E_* codes with translated descriptions, such as E_PERMISSION, E_HOST, E_TIMEOUT and E_BODY. See the complete list of codes.

try {
  await cat.http.send({url: 'https://out-of-scope.test/'});
} catch (error) {
  cat.log(String(error.code || error.message), 'error');
}