# SDK de extensões 1.4.0

> O SDK de extensões 1.4.0 do CatSuite: onde baixar, o que vem no pacote, o objeto global cat, os exemplos, os modelos de fluxo e as capacidades do CatBridge.

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

O **SDK de extensões do CatSuite** reúne tudo para criar plugins do aplicativo: o contrato completo da API em TypeScript, o runtime de referência, os esquemas dos arquivos, **quinze exemplos editáveis** e **seis modelos de fluxo**. Esta é a versão **1.4.0 · API v1**, compatível com todas as versões anteriores da API. Esta página mostra onde baixar, o que vem no pacote e como a API está organizada.

| Recurso | Endereço |
|---|---|
| Baixar o SDK (ZIP) | [catsuite-sdk-1.4.0.zip](https://github.com/netcattest/catsuite/releases/download/sdk-1.4.0/catsuite-sdk-1.4.0.zip) |
| Somas de verificação | [SHA256SUMS.txt](https://github.com/netcattest/catsuite/releases/download/sdk-1.4.0/SHA256SUMS.txt) |
| Código no GitHub | [Pasta sdk](https://github.com/netcattest/catsuite/tree/main/sdk) |
| Escrever no VS Code | [CatSuite Studio](https://netcattest.com/catsuite/docs/extensoes/vscode) |
| Escrever no navegador | [IDE web](https://netcattest.com/catsuite/ide) |

> [!NOTA]
> Não é preciso instalar o SDK no aparelho: o motor **QuickJS** roda dentro do aplicativo e o objeto global `cat` já está disponível. O pacote do SDK serve para escrever e validar no computador, com os tipos, os exemplos e os esquemas.

## O que vem no pacote

O ZIP extrai a pasta `catsuite-sdk` com:

| Arquivo ou pasta | Uso |
|---|---|
| `catsuite.d.ts` | Contrato completo da API e tipos para o editor. |
| `sdk.js` | Runtime de referência carregado pelo host QuickJS do CatSuite. |
| `sdk.json` | Versão e estrutura do SDK. |
| `esquemas` | Esquemas de `manifest.json`, projeto, `.catflow` e `.catdata`. |
| `capability-contracts.json` | Contratos tipados das capacidades do CatBridge. |
| `exemplos` | Quinze projetos editáveis, com manifestos e fixtures. |
| `fluxos` | Seis modelos de fluxo e entradas fictícias. |

> [!IMPORTANTE]
> Não inclua `sdk.js` no script da extensão: o aplicativo já fornece o objeto global `cat`. Não há Node.js, DOM, `fetch`, shell ou acesso geral aos arquivos do aparelho.

## Começar

1. Instale o [CatSuite Studio](https://netcattest.com/catsuite/docs/extensoes/vscode) no VS Code e extraia o SDK.
2. Abra uma pasta de `exemplos` como projeto, por exemplo `exemplos/painel`.
3. Edite o arquivo indicado por `entry` no `manifest.json`. Digite `cat.` para explorar a API.
4. Rode **CatSuite: Validar projeto** e a prévia local do Studio.
5. Gere o `.catplug` assinado e importe-o em uma versão do CatSuite com extensões compatíveis. Revise as permissões antes de ativar.

Se preferir não instalar nada, use a [IDE web](https://netcattest.com/catsuite/ide): ela traz os mesmos tipos no autocompletar.

## O objeto global `cat`

Todo o SDK é exposto no objeto global `cat`. A seguir, os grupos da API v1.

### Identidade

- `cat.apiVersion` — sempre `1`.
- `cat.sdkVersion` — a versão do SDK, `"1.4.0"` nesta entrega.

### Eventos e alteração de tráfego

- `cat.events.on(name, handler)` — observa `http.request`, `http.response` e `http.complete`.
- `cat.proxy.onRequest(handler)` e `cat.proxy.onResponse(handler)` — alteram a mensagem antes do encaminhamento. Devolver uma `CatMessage` substitui a original; não devolver nada a mantém.

Os handlers de alteração são **síncronos** e têm prazo de **100 ms**. Cada mensagem informa a `source` (origem), como `proxy`, `network_proxy`, `repetir`, `intruso`, `descobridor`, `extension` e `laboratory`.

### Envios HTTP e APIs externas

- `cat.http.send(request)` — envia uma request para um destino declarado e aprovado.
- `cat.http.cancel(id)` — cancela um envio pelo `id`.
- `cat.http.parseUrl(url)` — separa `scheme`, `hostname`, `port`, `pathname` e `query`.
- `cat.laboratory.capture(request)` — captura uma request no laboratório, sem rede real.
- `cat.external.call(options)` — consulta uma API externa com uma credencial protegida (`credentialId`).

### Interface

- `cat.ui.menu.register(options)` — adiciona itens ao menu de uma mensagem, nos contextos `request` ou `response`.
- `cat.ui.tab.register(options)` — cria uma aba nativa com uma lista de componentes.
- `cat.ui.update(id, components)` — atualiza os componentes de uma aba.

Os componentes são renderizados de forma nativa, sem HTML nem JavaScript visual. Veja a lista completa em [Interface, dados e achados](https://netcattest.com/catsuite/docs/extensoes/interface-e-dados).

### Dados, configurações e recursos

- `cat.storage.get(key)`, `cat.storage.set(key, value)` e `cat.storage.delete(key)` — armazenamento por extensão, com até 10 MiB e 128 KiB por valor.
- `cat.settings.get(key)` — lê uma configuração declarada no manifesto.
- `cat.resources.get(path, mode)` — lê um recurso do pacote como texto ou bytes.

### Achados, comandos e utilidades

- `cat.findings.add(finding)` — registra um achado com severidade, confiança, URL e evidência.
- `cat.commands.register(id, title, handler)` e `cat.commands.execute(id, args)` — registram e executam comandos.
- `cat.tools.repeater.open(request)` — abre uma request no módulo Repetir.
- `cat.i18n.locale` e `cat.i18n.text(value)` — idioma atual e resolução de um texto bilíngue `CatText`.
- `cat.bytes.fromText(text)` e `cat.bytes.toText(bytes)` — conversão entre texto UTF-8 e bytes.
- `cat.log(message, level)` — registra uma mensagem no console da extensão.

## Tipos principais

- `CatText` — um texto bilíngue no formato `{"pt-BR": "...", en: "..."}`.
- `CatMessage` — uma mensagem HTTP, com `headers`, `body`, `url`, `method`, `status`, origem e, quando vem de outra extensão, `pluginOrigin` e `extensionTrail`.
- `CatBody` — o corpo da mensagem, com `bytes`, `complete`, `truncated`, `available`, `mutable` e, quando aplicável, `representation` (`wire` ou `decoded`), `sha256` e `reference`.
- `CatRequest` — uma request para `cat.http.send` ou `cat.external.call`.
- `CatFinding` — um achado, com `severity` (`info`, `low`, `medium`, `high`, `critical`), `confidence` (`observed`, `confirmed`, `hypothesis`) e `status` (`open`, `resolved`, `false_positive`).
- `CatComponent` — um componente de interface. Veja a tabela a seguir.

### Componentes de interface

| Componente | Campos | Desde |
|---|---|---|
| `text` | `text` | v1 |
| `button` | `label`, `command`, `args` | v1 |
| `field` e `filter` | `id`, `label`, `value` | v1 |
| `list` | `items` | v1 |
| `table` | `columns`, `rows` | v1 |
| `http` | `message` | v1 |
| `progress` | `value` | v1 |
| `json` | `label`, `value` | SDK 1.2 |
| `diff` | `label`, `before`, `after` | SDK 1.2 |
| `timeline` | `label`, `items` com `title`, `detail` e `time` | SDK 1.2 |
| `chart` | `label`, `values` com `label` e `value` | SDK 1.2 |
| `graph` | `label`, `nodes` e `edges` com `from` e `to` | SDK 1.2 |

## Fluxos visuais

O SDK 1.2 adicionou as etapas e os parsers de fluxo:

- `cat.pipeline.registerStep(options, handler)` — registra uma etapa que recebe artefatos de entrada e emite artefatos de saída.
- `cat.parsers.register(options, handler)` — registra um parser para tipos MIME específicos.

O `handler` recebe um `CatStepContext` com `inputs`, `config`, `runId`, `nodeId`, `revisionId`, `protection`, `restored`, `signal`, e os métodos `checkpoint(state)`, `emit(kind, data)` e `progress(value)`. A etapa deve observar `ctx.signal.aborted` e pode retomar do estado salvo em `ctx.restored`. O `checkpoint` aceita um JSON de até 32 KiB.

```js
cat.pipeline.registerStep({
  id: 'exemplo.retomar',
  title: {'pt-BR': 'Retomar', en: 'Resume'},
  inputs: ['record'],
  outputs: ['record']
}, async ctx => {
  let feitos = ctx.restored?.feitos || 0;
  for (; feitos < ctx.inputs.length; feitos++) {
    if (ctx.signal.aborted) return;
    ctx.emit('record', ctx.inputs[feitos].data);
    await ctx.checkpoint({feitos: feitos + 1});
  }
});
```

Veja os formatos de artefato, os nós e os modelos em [Fluxos visuais com .catflow](https://netcattest.com/catsuite/docs/fluxos).

## Capacidades do CatBridge

O SDK 1.3 adicionou as capacidades tipadas do [CatBridge](https://netcattest.com/catsuite/docs/catbridge):

- `cat.connectors.capabilities(connectorId)` — lê o catálogo de capacidades do conector.
- `cat.connectors.run(options)` — executa uma capacidade tipada (por exemplo `http.probe`) com os parâmetros aprovados.
- `cat.connectors.cancel(id)` — cancela uma tarefa pelo `id`.

Declare `connector.run` e `requiresSdk: "1.3.0"` ou superior no manifesto. O SDK 1.4 amplia o catálogo com os adaptadores do ecossistema (descoberta de ativos, DNS, portas, fuzzing tipado, TLS, JWT e análise de código), que exigem `.catflow` 5 e contrato 2. Veja [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas).

## Exemplos incluídos

Os quinze exemplos são projetos editáveis, com manifestos e fixtures:

- **Essenciais:** painel e comandos, análise de tráfego, headers, etapa de fluxo e parser JSON.
- **Aurora:** captura, alteração, envio, análise, menu, aba, persistência, API simulada e achados.
- **Identidade:** JWT, candidatos a segredos, hipóteses de autorização e relatório.
- **APIs:** análise estática de JavaScript, endpoints e comparação com OpenAPI.
- **CatBridge:** sondagem HTTP e proveniência dos resultados. A execução real exige conexão, ferramenta disponível e aprovação; a prévia do Studio usa simulação.

Os seis modelos de fluxo acompanham entradas fictícias. Importar um modelo não amplia o escopo nem autoriza envios; as fixtures usam dados fictícios.

> [!AVISO]
> As fixtures e os laboratórios usam dados fictícios e não acessam a rede. A análise de JWT não verifica assinaturas, e indícios de autorização não demonstram acesso indevido. Trate cada sinal como evidência para revisão.

## Continue

- [Referência da API JavaScript](https://netcattest.com/catsuite/docs/extensoes/api)
- [Interface, dados e achados](https://netcattest.com/catsuite/docs/extensoes/interface-e-dados)
- [Manifesto do pacote .catplug](https://netcattest.com/catsuite/docs/extensoes/manifesto)
- [CatSuite Studio para VS Code](https://netcattest.com/catsuite/docs/extensoes/vscode)