---
url: https://docs.ogmabox.com/nl/plugins/frontend-sdk.md
description: >-
  Naslagwerk voor Ogma-API's voor frontendplugins, iframe-integratie,
  bridgeaanroepen, interfacepanelen, opdrachten en communicatie met de host.
---

# Naslagwerk voor de frontend-SDK van plugins {#plugin-frontend-sdk-reference}

De frontendcode van plugins wordt uitgevoerd in een afgeschermd iframe. Dit document is het naslagwerk op laag niveau. Zie [README.md](./README.md) voor een inleiding op hoger niveau.

***

## Beveiligingsmodel {#security-model}

| Eigenschap | Waarde |
|----------|-------|
| Iframe-sandbox | Alleen `allow-scripts` (geen `allow-same-origin`) |
| CSP `script-src` | Afgeschermd met een nonce; alleen het toegangspuntscript wordt geladen |
| CSP `connect-src` | `'self'` - de plugin kan POST-verzoeken versturen naar `/plugins/{id}/api/*` en `/plugins/{id}/events/poll` pollen |
| CSP `default-src` | `'none'` |
| Toegang tot de bovenliggende DOM | Geblokkeerd (geen `allow-same-origin`) |
| Ogma-sessiecookies | Niet toegankelijk voor de plugin |
| Communicatie tussen plugins | Niet beschikbaar |

Aanroepen via de gegevensbridge worden bij elk verzoek aan de serverzijde geautoriseerd; weergave- en navigatieacties worden door de hostinterface afgehandeld. De machtigingscache op het tabblad Rechten dient alleen voor weergave en wordt niet gebruikt om toegang tot gegevens te controleren.

***

## Bridgeprotocol {#bridge-protocol}

JavaScript van plugins communiceert met de Ogma-host via `postMessage`. De host bevindt zich in `PluginsView.vue` en verwerkt `bridge_request`-berichten.

### Verzoekenvelop {#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
}
```

Maximale totale berichtgrootte: 65 536 bytes.

### Responsenvelop {#response-envelope}

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

### De SDK gebruiken (aanbevolen) {#using-the-sdk-recommended}

Verstuur geen ruwe `postMessage`-bridgeverzoeken handmatig. Gebruik de globale variabele `ogmaSDK`:

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

De SDK omvat alle bridgecommunicatie en verzorgt verzoekcorrelatie, sessionId-beheer en het afhandelen van Promises.

***

## Naslagwerk voor opdrachten {#command-reference}

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

Geen payload vereist.

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

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

Payload: `{ id: string }`

Retourneert een projectie van een HTTP-item. Velden: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Deze projectie bevat geen headers of bodybytes.

Vereist: `read_http_history` (automatisch verleend).

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

Payload: `{ id: string }`. Roep dit aan via `sdk.requests.getRaw(id)`.

Retourneert `requestBodyBase64`, `responseBodyBase64`, hun gedecodeerde lengtes (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` en `maxBodyBytes`. Ondanks de naam retourneert deze bewerking bodybytes, geen volledig ruw HTTP-bericht. Ondersteunde inhoudscoderingen worden vóór de projectie gedecodeerd. Elke body is beperkt tot 256 KiB; controleer de afkappingsindicatoren voordat je een volledige asset verwerkt.

Vereist: `read_http_history` (automatisch verleend).

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

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

`query` ondersteunt HTTPQL-filterexpressies. Maximale `limit`: 20. Retourneert `{ items: [...], total: number, limit: number, offset: number }`.

Vereist: `read_http_history` (automatisch verleend).

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

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

Retourneert `{ items: [...], total: number, limit: number, offset: number }`, met maximaal 20 bevindingen per pagina. De items zijn samenvattingen; de velden omvatten `id`, `title`, `severity`, `status`, `reporter`, `tags` en `created_at`.

Vereist: `read_findings` (automatisch verleend).

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

Geen payload. Retourneert de actieve scopevoorinstelling of `null`.

Vereist: `read_scope` (automatisch verleend).

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

Geen payload. Retourneert `{ id, name, status }` of `null`.

Vereist: `read_projects` (automatisch verleend).

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

Payload: `{ message: string }`

Schrijft naar de logbuffer van de plugin.

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

Payload: `{ height: number }` (maximaal 2000)

Verzoekt de host om de hoogte van het iframe in te stellen.

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

Payload: `{ name: string, path: string }` (naam maximaal 64 tekens, pad maximaal 256 tekens)

Registreert navigatie binnen het pluginpaneel. Maximaal 20 items per plugin. Registreer bijbehorende pagina-inhoud met `sdk.navigation.addPage(path, { title, body })`; wanneer je het item kiest, wordt die pagina binnen het iframe getoond, niet als een nieuwe Ogma-werkruimteroute op het hoogste niveau.

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

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

Roept een backend-RPC-handler aan die is geregistreerd via `sdk.api.register(method, fn)`. De methodenaam mag maximaal 64 tekens lang zijn.

Retourneert de waarde die de backendhandler heeft geretourneerd, geserialiseerd als JSON.

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

Payload: niet vereist.

Wordt alleen bevestigd. Gebruik `ogma.events.poll` om daadwerkelijk gebeurtenissen op te halen.

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

Payload: `{ since: number }` (index van de laatste poll; begin bij 0)

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

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

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

De bridge bevestigt het paginapad. De geïnjecteerde SDK accepteert daarnaast `{ body: HTMLElement }` als optie voor `sdk.navigation.addPage(path, options)`, voegt de inhoud binnen het iframe toe en schakelt de zichtbaarheid van pagina's om wanneer de host het bijbehorende zijbalkitem selecteert. De DOM-node blijft lokaal en wordt niet via de bridge geserialiseerd.

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

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

Toont een toastmelding in het pluginpaneel. Duur in ms (maximaal 10000, standaard 3000).

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

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

Registreert de pluginopdracht in de opdrachtenstore van de host. Bij uitvoering door de host wordt een `plugin_command`-bericht met `commandId` en context teruggestuurd naar het iframe; de plugin moet de bijbehorende callback leveren. Registratie alleen voert de opdracht niet uit.

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

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

Registreert een contextmenu-item dat aan een pluginopdracht is gekoppeld. Registreer eerst de opdracht. Het label gebruikt standaard de geregistreerde naam van de opdracht en valt terug op de ID als er geen naam beschikbaar is; als `type` wordt weggelaten, is de standaardwaarde `Request`. `leadingIcon` wordt niet gebruikt door de hostbridge.

### Themahulpfuncties {#theme-helpers}

De geïnjecteerde SDK biedt ook `sdk.theme.get()` en `sdk.theme.onChange(callback)`. Deze lezen het iframe-thema en abonneren zich op themawijzigingen van de host zonder een afzonderlijke gegevensbridgeopdracht. Gebruik ze om de plugininterface af te stemmen op de lichte of donkere weergave van Ogma.

***

## Foutcodes {#error-codes}

| Code | Betekenis |
|------|---------|
| `PERMISSION_DENIED` | De plugin heeft niet de vereiste machtiging. |
| `PLUGIN_DISABLED` | De plugin is momenteel niet ingeschakeld. |
| `UNKNOWN_COMMAND` | De opdracht staat niet in de lijst met ondersteunde opdrachten. |
| `INVALID_PAYLOAD` | Een verplicht payloadveld ontbreekt of heeft het verkeerde type. |
| `NOT_FOUND` | De opgevraagde resource bestaat niet. |
| `LIMIT_EXCEEDED` | Een aantalslimiet per plugin is bereikt (bijvoorbeeld voor zijbalkitems). |
| `SERVER_ERROR` | Interne fout. Controleer de pluginlogs. |

***

## Lijst met ondersteunde opdrachten {#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`.