---
url: https://docs.ogmabox.com/hi/plugins/frontend-sdk.md
description: >-
  Ogma फ्रंटएंड प्लगइन API, iframe एकीकरण, ब्रिज कॉल, UI पैनल, कमांड और होस्ट
  संचार का संदर्भ।
---

# प्लगइन फ्रंटएंड 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'` - प्लगइन `/plugins/{id}/api/*` पर POST कर सकता है और `/plugins/{id}/events/poll` को पोल कर सकता है |
| CSP `default-src` | `'none'` |
| पैरेंट DOM तक पहुँच | अवरुद्ध (`allow-same-origin` नहीं) |
| Ogma सत्र की कुकी | प्लगइन के लिए पहुँच योग्य नहीं |
| प्लगइन के बीच संचार | उपलब्ध नहीं |

डेटा ब्रिज कॉल की अनुमति हर अनुरोध पर सर्वर में जाँची जाती है; प्रदर्शन और नेविगेशन की कार्रवाइयाँ होस्ट UI संभालता है। अनुमतियाँ टैब में दिखाया गया अनुमति कैश केवल प्रदर्शन के लिए है; यह डेटा तक पहुँच को नियंत्रित नहीं करता।

***

## ब्रिज प्रोटोकॉल {#bridge-protocol}

प्लगइन का JS, `postMessage` के ज़रिए Ogma होस्ट से संवाद करता है। होस्ट `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 KiB है; पूरे एसेट को प्रोसेस करने से पहले ट्रंकेशन फ़्लैग जाँचें।

आवश्यक अनुमति: `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[] }`

`sdk.api.register(method, fn)` से रजिस्टर किए गए बैकएंड RPC हैंडलर को कॉल करता है। मेथड नाम की अधिकतम लंबाई 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` संदेश iframe को वापस भेजा जाता है, जिसमें `commandId` और संदर्भ शामिल होते हैं; प्लगइन को संबंधित कॉलबैक देना होगा। केवल रजिस्टर करने से कमांड नहीं चलती।

### `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 की थीम पढ़ते हैं और अलग डेटा ब्रिज कमांड के बिना होस्ट की थीम अपडेट के लिए सब्सक्राइब करते हैं। प्लगइन UI को 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`.