---
url: https://docs.ogmabox.com/fr/plugins/frontend-sdk.md
description: >-
  Référence des API frontend des plugins Ogma, de l'intégration des iframes, des
  appels à la passerelle, des panneaux d'interface, des commandes et de la
  communication avec l'application hôte.
---

# Référence du SDK frontend des plugins {#plugin-frontend-sdk-reference}

Le code frontend des plugins s'exécute dans une iframe isolée. Ce document est la référence de bas niveau. Pour une introduction plus générale, consultez [README.md](./README.md).

***

## Modèle de sécurité {#security-model}

| Propriété | Valeur |
|----------|-------|
| Bac à sable de l'iframe | `allow-scripts` uniquement (sans `allow-same-origin`) |
| CSP `script-src` | Contrôlée par un nonce ; seul le script du point d'entrée est chargé |
| CSP `connect-src` | `'self'` : le plugin peut effectuer des requêtes POST vers `/plugins/{id}/api/*` et interroger périodiquement `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Accès au DOM parent | Bloqué (sans `allow-same-origin`) |
| Cookies de session Ogma | Inaccessibles au plugin |
| Communication entre plugins | Non disponible |

Les appels de données à la passerelle font l'objet d'un contrôle d'autorisation côté serveur à chaque requête ; les actions d'affichage et de navigation sont prises en charge par l'interface hôte. Le cache des permissions présenté dans l'onglet Autorisations sert uniquement à l'affichage ; il ne contrôle pas l'accès aux données.

***

## Protocole de la passerelle {#bridge-protocol}

Le JavaScript du plugin communique avec l'application hôte Ogma via `postMessage`. Le code hôte se trouve dans `PluginsView.vue` et traite les messages `bridge_request`.

### Enveloppe de requête {#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
}
```

Taille totale maximale d'un message : 65 536 octets.

### Enveloppe de réponse {#response-envelope}

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

### Utilisation du SDK (recommandée) {#using-the-sdk-recommended}

N'envoyez pas manuellement de requêtes brutes à la passerelle avec `postMessage`. Utilisez l'objet global `ogmaSDK` :

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

Le SDK encapsule toute la communication avec la passerelle et gère la corrélation des requêtes, le sessionId et la résolution des promesses.

***

## Référence des commandes {#command-reference}

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

Aucune charge utile requise.

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

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

Charge utile : `{ id: string }`

Renvoie une entrée HTTP sous forme de projection. Champs : `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Cette projection n'inclut ni les en-têtes ni les octets du corps.

Permission requise : `read_http_history` (accordée automatiquement).

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

Charge utile : `{ id: string }`. Appelez cette commande via `sdk.requests.getRaw(id)`.

Renvoie `requestBodyBase64`, `responseBodyBase64`, leurs longueurs après décodage (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` et `maxBodyBytes`. Malgré son nom, cette opération renvoie les octets du corps, et non un message HTTP brut complet. Les encodages de contenu pris en charge sont décodés avant la projection. Chaque corps est limité à 256 KiB ; vérifiez les indicateurs de troncature avant de traiter une ressource complète.

Permission requise : `read_http_history` (accordée automatiquement).

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

Charge utile : `{ limit?: number, offset?: number, query?: string }`

`query` accepte les expressions de filtrage HTTPQL. Valeur maximale de `limit` : 20. Renvoie `{ items: [...], total: number, limit: number, offset: number }`.

Permission requise : `read_http_history` (accordée automatiquement).

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

Charge utile : `{ limit?: number, offset?: number }`

Renvoie `{ items: [...], total: number, limit: number, offset: number }`, avec au maximum 20 constats par page. Les éléments sont des résumés ; les champs comprennent `id`, `title`, `severity`, `status`, `reporter`, `tags` et `created_at`.

Permission requise : `read_findings` (accordée automatiquement).

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

Aucune charge utile. Renvoie le préréglage de périmètre actif ou `null`.

Permission requise : `read_scope` (accordée automatiquement).

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

Aucune charge utile. Renvoie `{ id, name, status }` ou `null`.

Permission requise : `read_projects` (accordée automatiquement).

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

Charge utile : `{ message: string }`

Écrit dans le tampon des journaux du plugin.

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

Charge utile : `{ height: number }` (maximum : 2000)

Demande à l'application hôte de définir la hauteur de l'iframe.

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

Charge utile : `{ name: string, path: string }` (name : 64 caractères maximum, path : 256 caractères maximum)

Enregistre un élément de navigation dans le panneau du plugin. Maximum : 20 éléments par plugin. Enregistrez les contenus de page correspondants avec `sdk.navigation.addPage(path, { title, body })` ; la sélection de l'élément affiche cette page dans l'iframe, sans créer de nouvelle route de premier niveau dans l'espace de travail Ogma.

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

Charge utile : `{ method: string, args: unknown[] }`

Appelle un gestionnaire RPC backend enregistré via `sdk.api.register(method, fn)`. La longueur maximale du nom de méthode est de 64 caractères.

Renvoie la valeur retournée par le gestionnaire backend, sérialisée en JSON.

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

Charge utile : aucune requise.

Seul un accusé de réception est renvoyé. Utilisez `ogma.events.poll` pour récupérer effectivement les événements.

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

Charge utile : `{ since: number }` (indice issu de la dernière interrogation ; commencez à 0)

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

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

Charge utile : `{ path: string, title?: string }`

La passerelle accuse réception du chemin de la page. Le SDK injecté accepte également `{ body: HTMLElement }` comme option de `sdk.navigation.addPage(path, options)`, attache le contenu dans l'iframe et change la page visible lorsque l'application hôte sélectionne l'élément correspondant de la barre latérale. Le nœud DOM reste local ; il n'est pas sérialisé via la passerelle.

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

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

Affiche une notification temporaire dans le panneau du plugin. Durée en ms (maximum : 10000, valeur par défaut : 3000).

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

Charge utile : `{ id: string, name: string }`

Enregistre la commande du plugin dans le store de commandes de l'application hôte. Lors de l'exécution par l'hôte, un message `plugin_command` contenant `commandId` et le contexte est renvoyé à l'iframe ; le plugin doit fournir la fonction de rappel correspondante. L'enregistrement seul n'exécute pas la commande.

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

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

Enregistre un élément de menu contextuel associé à une commande du plugin. Enregistrez d'abord la commande. Le libellé utilise par défaut le nom enregistré de la commande, puis son identifiant ; si `type` est omis, sa valeur par défaut est `Request`. `leadingIcon` n'est pas utilisé par la passerelle hôte.

### Fonctions utilitaires de thème {#theme-helpers}

Le SDK injecté fournit également `sdk.theme.get()` et `sdk.theme.onChange(callback)`. Ces fonctions lisent le thème de l'iframe et permettent de s'abonner aux mises à jour du thème de l'hôte sans commande de données distincte sur la passerelle. Utilisez-les pour harmoniser l'interface du plugin avec l'apparence claire ou sombre d'Ogma.

***

## Codes d'erreur {#error-codes}

| Code | Signification |
|------|---------|
| `PERMISSION_DENIED` | Le plugin ne dispose pas de la permission requise. |
| `PLUGIN_DISABLED` | Le plugin n'est pas actuellement activé. |
| `UNKNOWN_COMMAND` | La commande ne figure pas dans la liste des commandes prises en charge. |
| `INVALID_PAYLOAD` | Un champ obligatoire de la charge utile est manquant ou son type est incorrect. |
| `NOT_FOUND` | La ressource demandée n'existe pas. |
| `LIMIT_EXCEEDED` | Le nombre maximal autorisé pour ce plugin a été atteint (par exemple, pour les éléments de la barre latérale). |
| `SERVER_ERROR` | Erreur interne. Consultez les journaux du plugin. |

***

## Liste des commandes prises en charge {#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`.