--- url: https://docs.ogmabox.com/pl/plugins/frontend-sdk.md description: >- Dokumentacja API wtyczek frontendu Ogma, integracji iframe, wywołań mostu, paneli interfejsu, poleceń i komunikacji z aplikacją hosta. --- # Dokumentacja referencyjna SDK frontendu wtyczek {#plugin-frontend-sdk-reference} Kod frontendu wtyczki działa w izolowanej ramce iframe. Ten dokument stanowi dokumentację niskiego poziomu. Wprowadzenie na wyższym poziomie znajdziesz w [README.md](./README.md). *** ## Model bezpieczeństwa {#security-model} | Właściwość | Wartość | |----------|-------| | Piaskownica iframe | Tylko `allow-scripts` (bez `allow-same-origin`) | | CSP `script-src` | Wymaga nonce; ładowany jest tylko skrypt punktu wejścia | | CSP `connect-src` | `'self'` — wtyczka może wysyłać POST do `/plugins/{id}/api/*` i odpytywać `/plugins/{id}/events/poll` | | CSP `default-src` | `'none'` | | Dostęp do nadrzędnego DOM | Zablokowany (brak `allow-same-origin`) | | Ciasteczka sesji Ogma | Niedostępne dla wtyczki | | Komunikacja między wtyczkami | Niedostępna | Wywołania mostu dotyczące danych są autoryzowane po stronie serwera przy każdym żądaniu; operacje wyświetlania i nawigacji obsługuje interfejs hosta. Pamięć podręczna uprawnień widoczna na karcie Uprawnienia służy wyłącznie do prezentacji; nie kontroluje dostępu do danych. *** ## Protokół mostu {#bridge-protocol} Kod JS wtyczki komunikuje się z hostem Ogma przez `postMessage`. Host znajduje się w `PluginsView.vue` i obsługuje komunikaty `bridge_request`. ### Struktura żądania {#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 } ``` Maksymalny łączny rozmiar komunikatu: 65 536 bajtów. ### Struktura odpowiedzi {#response-envelope} ```ts interface BridgeResponse { type: 'bridge_response' requestId: string ok: boolean result?: unknown error?: string code?: string } ``` ### Korzystanie z SDK (zalecane) {#using-the-sdk-recommended} Nie wysyłaj ręcznie surowych żądań mostu `postMessage`. Używaj globalnego obiektu `ogmaSDK`: ```js ogmaSDK.ready(function(sdk) { sdk.meta.get().then(function(meta) { sdk.log.info("running as " + meta.pluginId); }); }); ``` SDK obsługuje całą komunikację przez most, w tym korelację żądań, zarządzanie sessionId i rozstrzyganie obiektów Promise. *** ## Dokumentacja poleceń {#command-reference} ### `ogma.meta.get` {#ogma-meta-get} Nie wymaga danych wejściowych. Zwraca `{ pluginId, packageId, name, version, ogmaVersion }`. ### `ogma.requests.get` {#ogma-requests-get} Dane wejściowe: `{ id: string }` Zwraca projekcję wpisu HTTP. Pola: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Ta projekcja nie zawiera nagłówków ani bajtów treści. Wymaga: `read_http_history` (przyznawane automatycznie). ### `ogma.requests.getRaw` {#ogma-requests-getraw} Dane wejściowe: `{ id: string }`. Wywołuj przez `sdk.requests.getRaw(id)`. Zwraca `requestBodyBase64`, `responseBodyBase64`, długości po dekodowaniu (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` i `maxBodyBytes`. Mimo nazwy ta operacja zwraca bajty treści, a nie pełną surową wiadomość HTTP. Obsługiwane kodowania treści są dekodowane przed utworzeniem projekcji. Każda treść jest ograniczona do 256 KiB; przed przetwarzaniem kompletnego zasobu sprawdź flagi obcięcia. Wymaga: `read_http_history` (przyznawane automatycznie). ### `ogma.requests.search` {#ogma-requests-search} Dane wejściowe: `{ limit?: number, offset?: number, query?: string }` `query` obsługuje wyrażenia filtrów HTTPQL. Maksymalny `limit`: 20. Zwraca `{ items: [...], total: number, limit: number, offset: number }`. Wymaga: `read_http_history` (przyznawane automatycznie). ### `ogma.findings.list` {#ogma-findings-list} Dane wejściowe: `{ limit?: number, offset?: number }` Zwraca `{ items: [...], total: number, limit: number, offset: number }`, z maksymalnie 20 ustaleniami na stronę. Elementy są podsumowaniami; pola obejmują `id`, `title`, `severity`, `status`, `reporter`, `tags` i `created_at`. Wymaga: `read_findings` (przyznawane automatycznie). ### `ogma.scope.getActive` {#ogma-scope-getactive} Bez danych wejściowych. Zwraca aktywną zapisaną konfigurację zakresu testów lub `null`. Wymaga: `read_scope` (przyznawane automatycznie). ### `ogma.projects.getCurrent` {#ogma-projects-getcurrent} Bez danych wejściowych. Zwraca `{ id, name, status }` lub `null`. Wymaga: `read_projects` (przyznawane automatycznie). ### `ogma.log` {#ogma-log} Dane wejściowe: `{ message: string }` Zapisuje do bufora dziennika wtyczki. ### `ogma.ui.resize` {#ogma-ui-resize} Dane wejściowe: `{ height: number }` (maksymalnie 2000) Żąda od hosta ustawienia wysokości ramki iframe. ### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem} Dane wejściowe: `{ name: string, path: string }` (nazwa do 64 znaków, ścieżka do 256 znaków) Rejestruje nawigację wewnątrz panelu wtyczki. Maksymalnie 20 pozycji na wtyczkę. Zarejestruj odpowiadające im treści stron przez `sdk.navigation.addPage(path, { title, body })`; wybranie pozycji wyświetla tę stronę wewnątrz ramki iframe, a nie nową trasę na głównym poziomie obszaru roboczego Ogma. ### `ogma.backend.call` {#ogma-backend-call} Dane wejściowe: `{ method: string, args: unknown[] }` Wywołuje procedurę obsługi RPC backendu zarejestrowaną przez `sdk.api.register(method, fn)`. Maksymalna długość nazwy metody wynosi 64 znaki. Zwraca wartość zwróconą przez procedurę obsługi backendu, zserializowaną do JSON. ### `ogma.backend.onEvent` {#ogma-backend-onevent} Dane wejściowe: niewymagane. Wyłącznie potwierdza wywołanie. Do faktycznego pobierania zdarzeń używaj `ogma.events.poll`. ### `ogma.events.poll` {#ogma-events-poll} Dane wejściowe: `{ since: number }` (indeks z ostatniego odpytania; zacznij od 0) Zwraca `{ events: [{ event: string, args: unknown[] }], next_since: number }`. ### `ogma.navigation.addPage` {#ogma-navigation-addpage} Dane wejściowe: `{ path: string, title?: string }` Most potwierdza ścieżkę strony. Wstrzyknięte SDK dodatkowo przyjmuje `{ body: HTMLElement }` jako opcję w `sdk.navigation.addPage(path, options)`, dołącza treść wewnątrz ramki iframe i przełącza widoczność stron, gdy host wybierze odpowiadającą im pozycję paska bocznego. Węzeł DOM pozostaje lokalny; nie jest serializowany i przesyłany przez most. ### `ogma.window.showToast` {#ogma-window-showtoast} Dane wejściowe: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }` Wyświetla krótkie powiadomienie w panelu wtyczki. Czas trwania w ms (maksymalnie 10000, domyślnie 3000). ### `ogma.commands.register` {#ogma-commands-register} Dane wejściowe: `{ id: string, name: string }` Rejestruje polecenie wtyczki w magazynie poleceń hosta. Wykonanie przez hosta wysyła z powrotem do ramki iframe komunikat `plugin_command` zawierający `commandId` i kontekst; wtyczka musi zapewnić odpowiadającą mu funkcję zwrotną. Sama rejestracja nie wykonuje polecenia. ### `ogma.menu.registerItem` {#ogma-menu-registeritem} Dane wejściowe: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }` Rejestruje pozycję menu kontekstowego powiązaną z poleceniem wtyczki. Najpierw zarejestruj polecenie. Domyślną etykietą jest zarejestrowana nazwa polecenia, a w razie jej braku — jego identyfikator; pominięte `type` ma domyślną wartość `Request`. Most hosta nie wykorzystuje `leadingIcon`. ### Funkcje pomocnicze motywu {#theme-helpers} Wstrzyknięte SDK udostępnia również `sdk.theme.get()` i `sdk.theme.onChange(callback)`. Odczytują one motyw ramki iframe i subskrybują aktualizacje motywu hosta bez osobnego polecenia mostu danych. Używaj ich, aby interfejs wtyczki był spójny z jasnym lub ciemnym wyglądem Ogma. *** ## Kody błędów {#error-codes} | Kod | Znaczenie | |------|---------| | `PERMISSION_DENIED` | Wtyczka nie ma wymaganego uprawnienia. | | `PLUGIN_DISABLED` | Wtyczka nie jest obecnie włączona. | | `UNKNOWN_COMMAND` | Polecenie nie znajduje się na liście obsługiwanych. | | `INVALID_PAYLOAD` | Brakuje wymaganego pola danych wejściowych lub ma ono niewłaściwy typ. | | `NOT_FOUND` | Żądany zasób nie istnieje. | | `LIMIT_EXCEEDED` | Osiągnięto limit liczby elementów na wtyczkę (np. pozycji paska bocznego). | | `SERVER_ERROR` | Błąd wewnętrzny. Sprawdź dzienniki wtyczki. | *** ## Lista obsługiwanych poleceń {#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`.