---
url: https://docs.ogmabox.com/es/plugins/frontend-sdk.md
description: >-
  Referencia de las API de plugins de frontend de Ogma, integración de iframes,
  llamadas del puente, paneles de interfaz, comandos y comunicación con la
  aplicación principal.
---

# Referencia del SDK de frontend para plugins {#plugin-frontend-sdk-reference}

El código de frontend de los plugins se ejecuta en un iframe con aislamiento de sandbox. Este documento es la referencia de bajo nivel. Para una introducción de alto nivel, consulta [README.md](./README.md).

***

## Modelo de seguridad {#security-model}

| Propiedad | Valor |
|----------|-------|
| Sandbox del iframe | Solo `allow-scripts` (sin `allow-same-origin`) |
| CSP `script-src` | Restringida mediante nonce; solo se carga el script del punto de entrada |
| CSP `connect-src` | `'self'` - el plugin puede enviar POST a `/plugins/{id}/api/*` y consultar periódicamente `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Acceso al DOM de la página principal | Bloqueado (sin `allow-same-origin`) |
| Cookies de sesión de Ogma | Inaccesibles para el plugin |
| Comunicación entre plugins | No disponible |

Las llamadas de datos del puente se autorizan en el servidor en cada solicitud; la interfaz de la aplicación principal gestiona las acciones de visualización y navegación. La caché de permisos que aparece en la pestaña Permisos es solo informativa; no controla el acceso a los datos.

***

## Protocolo del puente {#bridge-protocol}

El JavaScript del plugin se comunica con la aplicación principal de Ogma mediante `postMessage`. El componente principal se encuentra en `PluginsView.vue` y procesa mensajes `bridge_request`.

### Sobre de solicitud {#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
}
```

Tamaño total máximo del mensaje: 65 536 bytes.

### Sobre de respuesta {#response-envelope}

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

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

No envíes manualmente solicitudes sin procesar al puente mediante `postMessage`. Utiliza el objeto global `ogmaSDK`:

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

El SDK encapsula toda la comunicación del puente y gestiona la correlación de solicitudes, la gestión de sessionId y la resolución de promesas.

***

## Referencia de comandos {#command-reference}

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

No se requiere carga útil.

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

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

Carga útil: `{ id: string }`

Devuelve una entrada HTTP proyectada. Campos: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Esta proyección no incluye cabeceras ni bytes del cuerpo.

Requiere: `read_http_history` (concedido automáticamente).

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

Carga útil: `{ id: string }`. Llámalo mediante `sdk.requests.getRaw(id)`.

Devuelve `requestBodyBase64`, `responseBodyBase64`, sus longitudes decodificadas (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` y `maxBodyBytes`. A pesar del nombre, esta operación devuelve los bytes del cuerpo, no un mensaje HTTP completo sin procesar. Las codificaciones de contenido compatibles se decodifican antes de la proyección. Cada cuerpo se limita a 256 KiB; comprueba los indicadores de truncamiento antes de procesar un recurso completo.

Requiere: `read_http_history` (concedido automáticamente).

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

Carga útil: `{ limit?: number, offset?: number, query?: string }`

`query` admite expresiones de filtro HTTPQL. Valor máximo de `limit`: 20. Devuelve `{ items: [...], total: number, limit: number, offset: number }`.

Requiere: `read_http_history` (concedido automáticamente).

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

Carga útil: `{ limit?: number, offset?: number }`

Devuelve `{ items: [...], total: number, limit: number, offset: number }`, con un máximo de 20 hallazgos por página. Los elementos son resúmenes; sus campos incluyen `id`, `title`, `severity`, `status`, `reporter`, `tags` y `created_at`.

Requiere: `read_findings` (concedido automáticamente).

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

Sin carga útil. Devuelve el ajuste predefinido de alcance activo o `null`.

Requiere: `read_scope` (concedido automáticamente).

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

Sin carga útil. Devuelve `{ id, name, status }` o `null`.

Requiere: `read_projects` (concedido automáticamente).

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

Carga útil: `{ message: string }`

Escribe en el búfer de registros del plugin.

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

Carga útil: `{ height: number }` (máximo 2000)

Solicita a la aplicación principal que establezca la altura del iframe.

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

Carga útil: `{ name: string, path: string }` (nombre de hasta 64 caracteres, ruta de hasta 256 caracteres)

Registra la navegación dentro del panel del plugin. Máximo de 20 elementos por plugin. Registra los cuerpos de las páginas correspondientes con `sdk.navigation.addPage(path, { title, body })`; al seleccionar el elemento se muestra esa página dentro del iframe, no una nueva ruta de nivel superior del espacio de trabajo de Ogma.

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

Carga útil: `{ method: string, args: unknown[] }`

Llama a un manejador RPC del backend registrado mediante `sdk.api.register(method, fn)`. La longitud máxima del nombre del método es de 64 caracteres.

Devuelve lo que haya devuelto el manejador del backend, serializado como JSON.

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

Carga útil: no se requiere.

Solo se confirma la recepción. Utiliza `ogma.events.poll` para obtener realmente los eventos.

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

Carga útil: `{ since: number }` (índice de la última consulta; comienza en 0)

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

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

Carga útil: `{ path: string, title?: string }`

El puente confirma la recepción de la ruta de la página. El SDK inyectado también acepta `{ body: HTMLElement }` como opción de `sdk.navigation.addPage(path, options)`, incorpora el cuerpo dentro del iframe y cambia la visibilidad de la página cuando la aplicación principal selecciona el elemento correspondiente de la barra lateral. El nodo DOM permanece local; no se serializa a través del puente.

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

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

Muestra una notificación emergente en el panel del plugin. Duración en ms (máximo 10000, valor predeterminado 3000).

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

Carga útil: `{ id: string, name: string }`

Registra el comando del plugin en el almacén de comandos de la aplicación principal. La ejecución desde la aplicación principal envía al iframe un mensaje `plugin_command` que contiene `commandId` y el contexto; el plugin debe proporcionar el callback correspondiente. El registro por sí solo no ejecuta el comando.

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

Carga útil: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

Registra un elemento de menú contextual vinculado a un comando del plugin. Registra primero el comando. La etiqueta toma por defecto el nombre registrado del comando y, en su defecto, su ID; si se omite `type`, se utiliza `Request`. El puente de la aplicación principal no utiliza `leadingIcon`.

### Utilidades de tema {#theme-helpers}

El SDK inyectado también proporciona `sdk.theme.get()` y `sdk.theme.onChange(callback)`. Estas funciones leen el tema del iframe y se suscriben a las actualizaciones del tema de la aplicación principal sin un comando de datos del puente independiente. Utilízalas para mantener la interfaz del plugin coherente con la apariencia clara u oscura de Ogma.

***

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

| Código | Significado |
|------|---------|
| `PERMISSION_DENIED` | El plugin no tiene el permiso necesario. |
| `PLUGIN_DISABLED` | El plugin no está habilitado actualmente. |
| `UNKNOWN_COMMAND` | El comando no figura en la lista de comandos compatibles. |
| `INVALID_PAYLOAD` | Falta un campo obligatorio de la carga útil o tiene un tipo incorrecto. |
| `NOT_FOUND` | El recurso solicitado no existe. |
| `LIMIT_EXCEEDED` | Se ha alcanzado un límite de cantidad por plugin (por ejemplo, de elementos de la barra lateral). |
| `SERVER_ERROR` | Error interno. Revisa los registros del plugin. |

***

## Lista de comandos compatibles {#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`.