---
url: https://docs.ogmabox.com/id/plugins/frontend-sdk.md
description: >-
  Referensi API plugin frontend Ogma, integrasi iframe, pemanggilan bridge,
  panel UI, perintah, dan komunikasi host.
---

# Referensi SDK Frontend Plugin {#plugin-frontend-sdk-reference}

Kode frontend plugin berjalan di dalam iframe sandbox. Dokumen ini adalah referensi tingkat rendah. Untuk pengantar tingkat lebih tinggi, lihat [README.md](./README.md).

***

## Model keamanan {#security-model}

| Properti | Nilai |
|----------|-------|
| Sandbox iframe | Hanya `allow-scripts` (tanpa `allow-same-origin`) |
| CSP `script-src` | Dikendalikan nonce; hanya skrip titik masuk yang dimuat |
| CSP `connect-src` | `'self'` - plugin dapat melakukan POST ke `/plugins/{id}/api/*` dan polling `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Akses DOM induk | Diblokir (tanpa `allow-same-origin`) |
| Cookie sesi Ogma | Tidak dapat diakses plugin |
| Komunikasi antarplugin | Tidak tersedia |

Pemanggilan bridge data diotorisasi di sisi server pada setiap permintaan; tindakan tampilan dan navigasi ditangani UI host. Cache izin yang ditampilkan di tab Izin hanya untuk tampilan; cache ini tidak mengendalikan akses data.

***

## Protokol bridge {#bridge-protocol}

JS plugin berkomunikasi dengan host Ogma melalui `postMessage`. Host berada di `PluginsView.vue` dan menangani pesan `bridge_request`.

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

Ukuran total pesan maksimum: 65.536 byte.

### Envelope respons {#response-envelope}

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

### Menggunakan SDK (direkomendasikan) {#using-the-sdk-recommended}

Jangan mengirim permintaan bridge `postMessage` dalam bentuk mentah secara manual. Gunakan global `ogmaSDK`:

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

SDK membungkus seluruh komunikasi bridge dan menangani korelasi permintaan, pengelolaan sessionId, dan penyelesaian Promise.

***

## Referensi perintah {#command-reference}

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

Tidak memerlukan payload.

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

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

Payload: `{ id: string }`

Mengembalikan proyeksi entri HTTP. Kolom: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Proyeksi ini tidak menyertakan header atau byte isi.

Memerlukan: `read_http_history` (diberikan otomatis).

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

Payload: `{ id: string }`. Panggil melalui `sdk.requests.getRaw(id)`.

Mengembalikan `requestBodyBase64`, `responseBodyBase64`, panjang hasil dekodenya (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated`, dan `maxBodyBytes`. Meskipun namanya demikian, operasi ini mengembalikan byte isi, bukan pesan HTTP lengkap dalam format transmisi. Pengodean konten yang didukung didekode sebelum proyeksi. Setiap isi dibatasi hingga 256 KiB; periksa penanda pemotongan sebelum memproses aset lengkap.

Memerlukan: `read_http_history` (diberikan otomatis).

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

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

`query` mendukung ekspresi filter HTTPQL. `limit` maksimum: 20. Mengembalikan `{ items: [...], total: number, limit: number, offset: number }`.

Memerlukan: `read_http_history` (diberikan otomatis).

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

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

Mengembalikan `{ items: [...], total: number, limit: number, offset: number }`, dengan paling banyak 20 temuan per halaman. Item berupa ringkasan; kolom mencakup `id`, `title`, `severity`, `status`, `reporter`, `tags`, dan `created_at`.

Memerlukan: `read_findings` (diberikan otomatis).

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

Tanpa payload. Mengembalikan prasetel cakupan aktif atau `null`.

Memerlukan: `read_scope` (diberikan otomatis).

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

Tanpa payload. Mengembalikan `{ id, name, status }` atau `null`.

Memerlukan: `read_projects` (diberikan otomatis).

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

Payload: `{ message: string }`

Menulis ke buffer log plugin.

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

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

Meminta host menetapkan tinggi iframe.

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

Payload: `{ name: string, path: string }` (nama maksimum 64 karakter, path maksimum 256 karakter)

Mendaftarkan navigasi dalam panel plugin. Maksimum 20 item per plugin. Daftarkan isi halaman yang sesuai dengan `sdk.navigation.addPage(path, { title, body })`; memilih item menampilkan halaman tersebut di dalam iframe, bukan rute ruang kerja Ogma tingkat teratas yang baru.

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

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

Memanggil handler RPC backend yang didaftarkan melalui `sdk.api.register(method, fn)`. Panjang maksimum nama metode adalah 64 karakter.

Mengembalikan apa pun yang dikembalikan handler backend, diserialisasi sebagai JSON.

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

Payload: tidak diperlukan.

Hanya dikonfirmasi. Gunakan `ogma.events.poll` untuk pengambilan peristiwa sebenarnya.

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

Payload: `{ since: number }` (indeks dari polling terakhir; mulai dari 0)

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

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

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

Bridge mengonfirmasi path halaman. SDK yang disisipkan juga menerima `{ body: HTMLElement }` sebagai opsi untuk `sdk.navigation.addPage(path, options)`, melampirkan isi di dalam iframe, dan mengganti visibilitas halaman ketika host memilih item bilah sisi yang sesuai. Simpul DOM tetap lokal; tidak diserialisasi melalui bridge.

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

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

Menampilkan toast di panel plugin. Durasi dalam ms (maksimum 10000, default 3000).

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

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

Mendaftarkan perintah plugin pada store perintah host. Eksekusi host mengirim pesan `plugin_command` yang berisi `commandId` dan konteks kembali ke iframe; plugin harus menyediakan callback yang sesuai. Pendaftaran saja tidak mengeksekusi perintah.

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

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

Mendaftarkan item menu konteks yang terikat ke perintah plugin. Daftarkan perintah terlebih dahulu. Label secara default adalah nama perintah yang terdaftar, lalu ID-nya; `type` yang tidak disertakan secara default adalah `Request`. `leadingIcon` tidak digunakan oleh bridge host.

### Helper Tema {#theme-helpers}

SDK yang disisipkan juga menyediakan `sdk.theme.get()` dan `sdk.theme.onChange(callback)`. Keduanya membaca tema iframe dan berlangganan pembaruan tema host tanpa perintah bridge data terpisah. Gunakan untuk menjaga UI plugin konsisten dengan tampilan terang/gelap Ogma.

***

## Kode kesalahan {#error-codes}

| Kode | Makna |
|------|---------|
| `PERMISSION_DENIED` | Plugin tidak memiliki izin yang diperlukan. |
| `PLUGIN_DISABLED` | Plugin saat ini tidak diaktifkan. |
| `UNKNOWN_COMMAND` | Perintah tidak ada dalam daftar yang didukung. |
| `INVALID_PAYLOAD` | Kolom payload wajib tidak ada atau memiliki tipe yang salah. |
| `NOT_FOUND` | Sumber daya yang diminta tidak ada. |
| `LIMIT_EXCEEDED` | Batas jumlah per plugin tercapai (misalnya item bilah sisi). |
| `SERVER_ERROR` | Kesalahan internal. Periksa log plugin. |

***

## Daftar perintah yang didukung {#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`.