---
url: https://docs.ogmabox.com/it/plugins/frontend-sdk.md
description: >-
  Riferimento delle API dei plugin frontend Ogma, integrazione degli iframe,
  chiamate del bridge, pannelli dell’interfaccia, comandi e comunicazione con
  l’applicazione principale.
---

# Riferimento dell’SDK frontend per i plugin {#plugin-frontend-sdk-reference}

Il codice frontend dei plugin viene eseguito in un iframe con isolamento sandbox. Questo documento è il riferimento di basso livello. Per un’introduzione di livello superiore, consulta [README.md](./README.md).

***

## Modello di sicurezza {#security-model}

| Proprietà | Valore |
|----------|-------|
| Sandbox dell’iframe | Solo `allow-scripts` (senza `allow-same-origin`) |
| CSP `script-src` | Vincolata a un nonce; viene caricato solo lo script del punto di ingresso |
| CSP `connect-src` | `'self'` - il plugin può inviare POST a `/plugins/{id}/api/*` e interrogare periodicamente `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Accesso al DOM della pagina principale | Bloccato (senza `allow-same-origin`) |
| Cookie di sessione Ogma | Inaccessibili al plugin |
| Comunicazione tra plugin | Non disponibile |

Le chiamate dati del bridge vengono autorizzate sul server a ogni richiesta; le azioni di visualizzazione e navigazione vengono gestite dall’interfaccia dell’applicazione principale. La cache delle autorizzazioni mostrata nella scheda Autorizzazioni è solo informativa; non controlla l’accesso ai dati.

***

## Protocollo del bridge {#bridge-protocol}

Il JavaScript del plugin comunica con l’applicazione principale Ogma tramite `postMessage`. Il componente principale si trova in `PluginsView.vue` e gestisce i messaggi `bridge_request`.

### Struttura della richiesta {#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
}
```

Dimensione totale massima del messaggio: 65 536 byte.

### Struttura della risposta {#response-envelope}

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

### Uso dell’SDK (consigliato) {#using-the-sdk-recommended}

Non inviare manualmente richieste grezze al bridge tramite `postMessage`. Usa l’oggetto globale `ogmaSDK`:

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

L’SDK incapsula tutta la comunicazione del bridge e gestisce la correlazione delle richieste, la gestione di sessionId e la risoluzione delle promesse.

***

## Riferimento dei comandi {#command-reference}

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

Non è richiesto alcun payload.

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

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

Payload: `{ id: string }`

Restituisce una voce HTTP proiettata. Campi: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Questa proiezione non include intestazioni o byte del corpo.

Richiede: `read_http_history` (concessa automaticamente).

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

Payload: `{ id: string }`. Effettua la chiamata tramite `sdk.requests.getRaw(id)`.

Restituisce `requestBodyBase64`, `responseBodyBase64`, le loro lunghezze decodificate (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` e `maxBodyBytes`. Nonostante il nome, questa operazione restituisce i byte del corpo, non un messaggio HTTP grezzo completo. Le codifiche del contenuto supportate vengono decodificate prima della proiezione. Ogni corpo è limitato a 256 KiB; verifica gli indicatori di troncamento prima di elaborare una risorsa completa.

Richiede: `read_http_history` (concessa automaticamente).

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

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

`query` supporta espressioni di filtro HTTPQL. Valore massimo di `limit`: 20. Restituisce `{ items: [...], total: number, limit: number, offset: number }`.

Richiede: `read_http_history` (concessa automaticamente).

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

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

Restituisce `{ items: [...], total: number, limit: number, offset: number }`, con al massimo 20 rilievi di sicurezza per pagina. Gli elementi sono riepiloghi; i campi includono `id`, `title`, `severity`, `status`, `reporter`, `tags` e `created_at`.

Richiede: `read_findings` (concessa automaticamente).

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

Nessun payload. Restituisce la preimpostazione di ambito attiva o `null`.

Richiede: `read_scope` (concessa automaticamente).

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

Nessun payload. Restituisce `{ id, name, status }` o `null`.

Richiede: `read_projects` (concessa automaticamente).

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

Payload: `{ message: string }`

Scrive nel buffer dei log del plugin.

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

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

Richiede all’applicazione principale di impostare l’altezza dell’iframe.

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

Payload: `{ name: string, path: string }` (nome massimo di 64 caratteri, percorso massimo di 256 caratteri)

Registra la navigazione all’interno del pannello del plugin. Massimo 20 elementi per plugin. Registra i corpi delle pagine corrispondenti con `sdk.navigation.addPage(path, { title, body })`; scegliendo l’elemento, quella pagina viene visualizzata nell’iframe, non come nuova rotta di livello superiore dell’area di lavoro Ogma.

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

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

Chiama un gestore RPC backend registrato tramite `sdk.api.register(method, fn)`. La lunghezza massima del nome del metodo è di 64 caratteri.

Restituisce ciò che il gestore backend ha restituito, serializzato come JSON.

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

Payload: non richiesto.

Viene solo confermata la ricezione. Usa `ogma.events.poll` per recuperare effettivamente gli eventi.

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

Payload: `{ since: number }` (indice dell’ultima interrogazione; inizia da 0)

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

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

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

Il bridge conferma la ricezione del percorso della pagina. L’SDK iniettato accetta anche `{ body: HTMLElement }` come opzione di `sdk.navigation.addPage(path, options)`, inserisce il corpo nell’iframe e cambia la visibilità della pagina quando l’applicazione principale seleziona l’elemento corrispondente della barra laterale. Il nodo DOM resta locale; non viene serializzato tramite il bridge.

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

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

Mostra una notifica temporanea nel pannello del plugin. Durata in ms (massimo 10000, valore predefinito 3000).

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

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

Registra il comando del plugin nello store dei comandi dell’applicazione principale. L’esecuzione da parte dell’applicazione principale invia all’iframe un messaggio `plugin_command` contenente `commandId` e il contesto; il plugin deve fornire il callback corrispondente. La sola registrazione non esegue il comando.

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

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

Registra una voce del menu contestuale collegata a un comando del plugin. Registra prima il comando. L’etichetta usa per impostazione predefinita il nome registrato del comando e, in sua assenza, il suo ID; se `type` viene omesso, il valore predefinito è `Request`. Il bridge dell’applicazione principale non utilizza `leadingIcon`.

### Funzioni di supporto per il tema {#theme-helpers}

L’SDK iniettato offre anche `sdk.theme.get()` e `sdk.theme.onChange(callback)`. Queste funzioni leggono il tema dell’iframe e si iscrivono agli aggiornamenti del tema dell’applicazione principale senza un comando dati del bridge separato. Usale per mantenere l’interfaccia del plugin coerente con l’aspetto chiaro/scuro di Ogma.

***

## Codici di errore {#error-codes}

| Codice | Significato |
|------|---------|
| `PERMISSION_DENIED` | Il plugin non dispone dell’autorizzazione richiesta. |
| `PLUGIN_DISABLED` | Il plugin non è attualmente abilitato. |
| `UNKNOWN_COMMAND` | Il comando non è nell’elenco di quelli supportati. |
| `INVALID_PAYLOAD` | Un campo obbligatorio del payload manca o ha un tipo errato. |
| `NOT_FOUND` | La risorsa richiesta non esiste. |
| `LIMIT_EXCEEDED` | È stato raggiunto un limite di quantità per plugin (ad esempio, per le voci della barra laterale). |
| `SERVER_ERROR` | Errore interno. Controlla i log del plugin. |

***

## Elenco dei comandi supportati {#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`.