---
url: https://docs.ogmabox.com/ar/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`) |
| ملفات تعريف الارتباط لجلسة Ogma | لا تستطيع الإضافة الوصول إليها |
| التواصل بين الإضافات | غير متاح |

يُتحقّق من صلاحية استدعاءات جسر البيانات على جانب الخادم لكل طلب؛ وتتولّى واجهة المستخدم المضيفة إجراءات العرض والتنقّل. ذاكرة الصلاحيات المؤقتة المعروضة في علامة تبويب الصلاحيات مخصّصة للعرض فقط؛ ولا تتحكّم في الوصول إلى البيانات.

***

## بروتوكول الجسر {#bridge-protocol}

تتواصل شيفرة JS الخاصة بالإضافة مع مضيف 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 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[] }`

تستدعي معالج 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 }`

تسجّل عنصر قائمة سياقية مرتبطًا بأمر إضافة. سجّل الأمر أولًا. تكون التسمية افتراضيًا اسم الأمر المسجّل، أو معرّفه إذا لم يتوفّر الاسم؛ وعند إغفال `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`.