--- url: https://docs.ogmabox.com/uk/plugins/frontend-sdk.md description: >- Довідник API інтерфейсу плагінів Ogma, інтеграції iframe, викликів мосту, панелей, команд і взаємодії з хостом. --- # Довідник SDK інтерфейсу плагінів {#plugin-frontend-sdk-reference} Код інтерфейсу плагіна виконується в ізольованому iframe. Цей документ — низькорівневий довідник. Вступ вищого рівня наведено в [README.md](./README.md). *** ## Модель безпеки {#security-model} | Властивість | Значення | |----------|-------| | Ізоляція iframe | Лише `allow-scripts` (без `allow-same-origin`) | | CSP `script-src` | Контроль через nonce; завантажується лише скрипт точки входу | | CSP `connect-src` | `'self'` — плагін може виконувати POST до `/plugins/{id}/api/*` і опитувати `/plugins/{id}/events/poll` | | CSP `default-src` | `'none'` | | Доступ до батьківського DOM | Заблоковано (немає `allow-same-origin`) | | Cookie сеансу Ogma | Недоступні плагіну | | Взаємодія між плагінами | Недоступна | Виклики мосту даних авторизуються на сервері для кожного запиту; дії відображення й навігації опрацьовує інтерфейс хоста. Кеш дозволів на вкладці дозволів призначено лише для показу; він не обмежує доступ до даних. *** ## Протокол мосту {#bridge-protocol} JavaScript плагіна взаємодіє з хостом Ogma через `postMessage`. Хост міститься в `PluginsView.vue` й опрацьовує повідомлення `bridge_request`. ### Оболонка запиту {#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 } ``` Максимальний загальний розмір повідомлення: 65 536 байтів. ### Оболонка відповіді {#response-envelope} ```ts interface BridgeResponse { type: 'bridge_response' requestId: string ok: boolean result?: unknown error?: string code?: string } ``` ### Використання SDK (рекомендовано) {#using-the-sdk-recommended} Не надсилайте запити мосту `postMessage` вручну напряму. Використовуйте глобальний `ogmaSDK`: ```js ogmaSDK.ready(function(sdk) { sdk.meta.get().then(function(meta) { sdk.log.info("running as " + meta.pluginId); }); }); ``` SDK обгортає всю взаємодію мосту й опрацьовує зіставлення запитів, керування sessionId та завершення Promise. *** ## Довідник команд {#command-reference} ### `ogma.meta.get` {#ogma-meta-get} Вхідні дані не потрібні. Повертає `{ pluginId, packageId, name, version, ogmaVersion }`. ### `ogma.requests.get` {#ogma-requests-get} Вхідні дані: `{ id: string }` Повертає проєкцію запису HTTP. Поля: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Проєкція не містить заголовків або байтів тіл. Потребує: `read_http_history` (надається автоматично). ### `ogma.requests.getRaw` {#ogma-requests-getraw} Вхідні дані: `{ id: string }`. Викликайте через `sdk.requests.getRaw(id)`. Повертає `requestBodyBase64`, `responseBodyBase64`, їхні декодовані довжини (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` і `maxBodyBytes`. Попри назву, операція повертає байти тіл, а не повне необроблене повідомлення HTTP. Підтримувані кодування вмісту декодуються перед проєкцією. Кожне тіло обмежене 256 КіБ; перевіряйте прапорці усічення перед опрацюванням повного ресурсу. Потребує: `read_http_history` (надається автоматично). ### `ogma.requests.search` {#ogma-requests-search} Вхідні дані: `{ limit?: number, offset?: number, query?: string }` `query` підтримує фільтри HTTPQL. Максимум `limit`: 20. Повертає `{ items: [...], total: number, limit: number, offset: number }`. Потребує: `read_http_history` (надається автоматично). ### `ogma.findings.list` {#ogma-findings-list} Вхідні дані: `{ limit?: number, offset?: number }` Повертає `{ items: [...], total: number, limit: number, offset: number }`, щонайбільше 20 знахідок на сторінку. Елементи — стислі відомості; поля включають `id`, `title`, `severity`, `status`, `reporter`, `tags` і `created_at`. Потребує: `read_findings` (надається автоматично). ### `ogma.scope.getActive` {#ogma-scope-getactive} Без вхідних даних. Повертає активний набір налаштувань області або `null`. Потребує: `read_scope` (надається автоматично). ### `ogma.projects.getCurrent` {#ogma-projects-getcurrent} Без вхідних даних. Повертає `{ id, name, status }` або `null`. Потребує: `read_projects` (надається автоматично). ### `ogma.log` {#ogma-log} Вхідні дані: `{ message: string }` Записує до буфера журналу плагіна. ### `ogma.ui.resize` {#ogma-ui-resize} Вхідні дані: `{ height: number }` (максимум 2000) Просить хост задати висоту iframe. ### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem} Вхідні дані: `{ name: string, path: string }` (назва щонайбільше 64 символи, шлях щонайбільше 256 символів) Реєструє навігацію всередині панелі плагіна. Максимум 20 елементів на плагін. Реєструйте відповідні тіла сторінок через `sdk.navigation.addPage(path, { title, body })`; вибір елемента показує сторінку всередині iframe, а не новий маршрут верхнього рівня робочого простору Ogma. ### `ogma.backend.call` {#ogma-backend-call} Вхідні дані: `{ method: string, args: unknown[] }` Викликає серверний обробник RPC, зареєстрований через `sdk.api.register(method, fn)`. Максимальна довжина назви методу — 64 символи. Повертає результат серверного обробника, серіалізований у JSON. ### `ogma.backend.onEvent` {#ogma-backend-onevent} Вхідні дані не потрібні. Лише підтверджує виклик. Для фактичного отримання подій використовуйте `ogma.events.poll`. ### `ogma.events.poll` {#ogma-events-poll} Вхідні дані: `{ since: number }` (індекс останнього опитування; почніть із 0) Повертає `{ events: [{ event: string, args: unknown[] }], next_since: number }`. ### `ogma.navigation.addPage` {#ogma-navigation-addpage} Вхідні дані: `{ path: string, title?: string }` Міст підтверджує шлях сторінки. Впроваджений SDK додатково приймає `{ body: HTMLElement }` як параметр `sdk.navigation.addPage(path, options)`, приєднує тіло всередині iframe й перемикає видимість сторінки, коли хост вибирає відповідний елемент бічної панелі. Вузол DOM залишається локальним і не серіалізується через міст. ### `ogma.window.showToast` {#ogma-window-showtoast} Вхідні дані: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }` Показує сповіщення на панелі плагіна. Тривалість у мс (максимум 10000, типово 3000). ### `ogma.commands.register` {#ogma-commands-register} Вхідні дані: `{ id: string, name: string }` Реєструє команду плагіна в сховищі команд хоста. Виконання хостом надсилає повідомлення `plugin_command` із `commandId` і контекстом назад до iframe; плагін має надати відповідний обробник. Сама реєстрація не виконує команду. ### `ogma.menu.registerItem` {#ogma-menu-registeritem} Вхідні дані: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }` Реєструє елемент контекстного меню, пов’язаний із командою плагіна. Спочатку зареєструйте команду. Назва за замовчуванням — зареєстрована назва команди, потім її ID; пропущений `type` означає `Request`. `leadingIcon` не використовується мостом хоста. ### Допоміжні функції теми {#theme-helpers} Впроваджений SDK також надає `sdk.theme.get()` і `sdk.theme.onChange(callback)`. Вони читають тему iframe й підписуються на оновлення теми хоста без окремої команди мосту даних. Використовуйте їх для узгодження інтерфейсу плагіна зі світлим і темним виглядом Ogma. *** ## Коди помилок {#error-codes} | Код | Значення | |------|---------| | `PERMISSION_DENIED` | Плагін не має потрібного дозволу. | | `PLUGIN_DISABLED` | Плагін зараз не ввімкнений. | | `UNKNOWN_COMMAND` | Команди немає в підтримуваному списку. | | `INVALID_PAYLOAD` | Обов’язкове поле вхідних даних відсутнє або має неправильний тип. | | `NOT_FOUND` | Запитаний ресурс не існує. | | `LIMIT_EXCEEDED` | Досягнуто ліміту кількості для плагіна (наприклад, елементів бічної панелі). | | `SERVER_ERROR` | Внутрішня помилка. Перевірте журнали плагіна. | *** ## Список підтримуваних команд {#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`.