---
url: https://docs.ogmabox.com/pt/plugins/frontend-sdk.md
description: >-
  Referência das APIs de plugins de frontend do Ogma, integração de iframes,
  chamadas da ponte, painéis de interface, comandos e comunicação com o
  aplicativo principal.
---

# Referência do SDK de frontend para plugins {#plugin-frontend-sdk-reference}

O código de frontend dos plugins é executado em um iframe com isolamento de sandbox. Este documento é a referência de baixo nível. Para uma introdução de alto nível, consulte [README.md](./README.md).

***

## Modelo de segurança {#security-model}

| Propriedade | Valor |
|----------|-------|
| Sandbox do iframe | Somente `allow-scripts` (sem `allow-same-origin`) |
| CSP `script-src` | Restringida por nonce; somente o script do ponto de entrada é carregado |
| CSP `connect-src` | `'self'` - o plugin pode enviar POST para `/plugins/{id}/api/*` e consultar periodicamente `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Acesso ao DOM da página principal | Bloqueado (sem `allow-same-origin`) |
| Cookies de sessão do Ogma | Inacessíveis ao plugin |
| Comunicação entre plugins | Não disponível |

As chamadas de dados da ponte são autorizadas no servidor a cada requisição; a interface do aplicativo principal trata as ações de exibição e navegação. O cache de permissões mostrado na aba Permissões é apenas informativo; ele não controla o acesso aos dados.

***

## Protocolo da ponte {#bridge-protocol}

O JavaScript do plugin se comunica com o aplicativo principal do Ogma por `postMessage`. O componente principal fica em `PluginsView.vue` e trata mensagens `bridge_request`.

### Envelope de requisição {#request-envelope}

```ts
interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}
```

Tamanho total máximo da mensagem: 65 536 bytes.

### Envelope de resposta {#response-envelope}

```ts
interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}
```

### Uso do SDK (recomendado) {#using-the-sdk-recommended}

Não envie manualmente requisições brutas à ponte por `postMessage`. Use o objeto global `ogmaSDK`:

```js
ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});
```

O SDK encapsula toda a comunicação da ponte e trata a correlação de requisições, o gerenciamento de sessionId e a resolução de promessas.

***

## Referência de comandos {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

Não é necessário payload.

Retorna `{ pluginId, packageId, name, version, ogmaVersion }`.

### `ogma.requests.get` {#ogma-requests-get}

Payload: `{ id: string }`

Retorna uma entrada HTTP projetada. Campos: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Essa projeção não inclui cabeçalhos nem bytes do corpo.

Exige: `read_http_history` (concedida automaticamente).

### `ogma.requests.getRaw` {#ogma-requests-getraw}

Payload: `{ id: string }`. Faça a chamada por `sdk.requests.getRaw(id)`.

Retorna `requestBodyBase64`, `responseBodyBase64`, seus comprimentos decodificados (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` e `maxBodyBytes`. Apesar do nome, essa operação retorna bytes do corpo, não uma mensagem HTTP bruta completa. As codificações de conteúdo compatíveis são decodificadas antes da projeção. Cada corpo é limitado a 256 KiB; verifique os indicadores de truncamento antes de processar um recurso completo.

Exige: `read_http_history` (concedida automaticamente).

### `ogma.requests.search` {#ogma-requests-search}

Payload: `{ limit?: number, offset?: number, query?: string }`

`query` aceita expressões de filtro HTTPQL. Valor máximo de `limit`: 20. Retorna `{ items: [...], total: number, limit: number, offset: number }`.

Exige: `read_http_history` (concedida automaticamente).

### `ogma.findings.list` {#ogma-findings-list}

Payload: `{ limit?: number, offset?: number }`

Retorna `{ items: [...], total: number, limit: number, offset: number }`, com no máximo 20 achados por página. Os itens são resumos; os campos incluem `id`, `title`, `severity`, `status`, `reporter`, `tags` e `created_at`.

Exige: `read_findings` (concedida automaticamente).

### `ogma.scope.getActive` {#ogma-scope-getactive}

Sem payload. Retorna a predefinição de escopo ativa ou `null`.

Exige: `read_scope` (concedida automaticamente).

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

Sem payload. Retorna `{ id, name, status }` ou `null`.

Exige: `read_projects` (concedida automaticamente).

### `ogma.log` {#ogma-log}

Payload: `{ message: string }`

Grava no buffer de logs do plugin.

### `ogma.ui.resize` {#ogma-ui-resize}

Payload: `{ height: number }` (máximo 2000)

Solicita ao aplicativo principal que defina a altura do iframe.

### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem}

Payload: `{ name: string, path: string }` (nome de até 64 caracteres, caminho de até 256 caracteres)

Registra a navegação dentro do painel do plugin. Máximo de 20 itens por plugin. Registre os corpos das páginas correspondentes com `sdk.navigation.addPage(path, { title, body })`; escolher o item exibe essa página dentro do iframe, não uma nova rota de nível superior do espaço de trabalho do Ogma.

### `ogma.backend.call` {#ogma-backend-call}

Payload: `{ method: string, args: unknown[] }`

Chama um handler RPC do backend registrado por `sdk.api.register(method, fn)`. O comprimento máximo do nome do método é de 64 caracteres.

Retorna o que o handler do backend tiver retornado, serializado como JSON.

### `ogma.backend.onEvent` {#ogma-backend-onevent}

Payload: não é necessário.

Apenas confirma o recebimento. Use `ogma.events.poll` para obter os eventos de fato.

### `ogma.events.poll` {#ogma-events-poll}

Payload: `{ since: number }` (índice da última consulta; comece em 0)

Retorna `{ events: [{ event: string, args: unknown[] }], next_since: number }`.

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

Payload: `{ path: string, title?: string }`

A ponte confirma o recebimento do caminho da página. O SDK injetado também aceita `{ body: HTMLElement }` como opção de `sdk.navigation.addPage(path, options)`, insere o corpo dentro do iframe e alterna a visibilidade da página quando o aplicativo principal seleciona o item correspondente da barra lateral. O nó DOM permanece local; ele não é serializado pela ponte.

### `ogma.window.showToast` {#ogma-window-showtoast}

Payload: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }`

Exibe uma notificação temporária no painel do plugin. Duração em ms (máximo 10000, padrão 3000).

### `ogma.commands.register` {#ogma-commands-register}

Payload: `{ id: string, name: string }`

Registra o comando do plugin no store de comandos do aplicativo principal. A execução pelo aplicativo principal envia de volta ao iframe uma mensagem `plugin_command` com `commandId` e contexto; o plugin deve fornecer o callback correspondente. O registro, por si só, não executa o comando.

### `ogma.menu.registerItem` {#ogma-menu-registeritem}

Payload: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

Registra um item de menu de contexto vinculado a um comando do plugin. Registre o comando primeiro. O rótulo usa por padrão o nome registrado do comando e, na ausência dele, seu ID; se `type` for omitido, o padrão é `Request`. A ponte do aplicativo principal não utiliza `leadingIcon`.

### Funções auxiliares de tema {#theme-helpers}

O SDK injetado também oferece `sdk.theme.get()` e `sdk.theme.onChange(callback)`. Essas funções leem o tema do iframe e se inscrevem nas atualizações de tema do aplicativo principal sem um comando separado de dados da ponte. Use-as para manter a interface do plugin consistente com a aparência clara/escura do Ogma.

***

## Códigos de erro {#error-codes}

| Código | Significado |
|------|---------|
| `PERMISSION_DENIED` | O plugin não tem a permissão exigida. |
| `PLUGIN_DISABLED` | O plugin não está habilitado no momento. |
| `UNKNOWN_COMMAND` | O comando não está na lista de comandos compatíveis. |
| `INVALID_PAYLOAD` | Um campo obrigatório do payload está ausente ou tem o tipo incorreto. |
| `NOT_FOUND` | O recurso solicitado não existe. |
| `LIMIT_EXCEEDED` | Um limite de quantidade por plugin foi atingido (por exemplo, de itens da barra lateral). |
| `SERVER_ERROR` | Erro interno. Verifique os logs do plugin. |

***

## Lista de comandos compatíveis {#supported-commands-list}

`ogma.meta.get`, `ogma.log`, `ogma.ui.resize`, `ogma.ui.sidebar.registerItem`, `ogma.requests.get`, `ogma.requests.getRaw`, `ogma.requests.search`, `ogma.findings.list`, `ogma.scope.getActive`, `ogma.projects.getCurrent`, `ogma.backend.call`, `ogma.backend.onEvent`, `ogma.events.poll`, `ogma.navigation.addPage`, `ogma.window.showToast`, `ogma.commands.register`, `ogma.menu.registerItem`.