مرجع SDK الواجهة الأمامية للإضافات

تعمل شيفرة الواجهة الأمامية للإضافة داخل إطار iframe معزول. هذا المستند مرجع منخفض المستوى. للحصول على مقدّمة أعلى مستوى، راجع README.md.

نموذج الأمان

الخاصية	القيمة
عزل 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	لا تستطيع الإضافة الوصول إليها
التواصل بين الإضافات	غير متاح

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

بروتوكول الجسر

تتواصل شيفرة JS الخاصة بالإضافة مع مضيف Ogma عبر postMessage. يوجد المضيف في PluginsView.vue ويتولّى معالجة رسائل bridge_request.

غلاف الطلب

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 بايت.

غلاف الاستجابة

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

استخدام SDK (موصى به)

لا ترسل طلبات الجسر الخام باستخدام postMessage يدويًا. استخدم الكائن العام ogmaSDK:

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

يتولّى SDK تغليف جميع اتصالات الجسر وربط الطلبات وإدارة sessionId وتسوية كائنات Promise.

مرجع الأوامر

`ogma.meta.get`

لا تتطلّب حمولة.

تُرجع { pluginId, packageId, name, version, ogmaVersion }.

`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`

الحمولة: { id: string }. استدعها عبر sdk.requests.getRaw(id).

تُرجع requestBodyBase64 وresponseBodyBase64 وطوليهما بعد فك الترميز (requestBodyLength وresponseBodyLength) وrequestBodyTruncated وresponseBodyTruncated وmaxBodyBytes. رغم التسمية، تُرجع هذه العملية بايتات الجسم، لا رسالة HTTP خام كاملة. تُفك ترميزات المحتوى المدعومة قبل إسقاط البيانات. الحد الأقصى لكل جسم هو 256 KiB؛ تحقّق من مؤشرات الاقتطاع قبل معالجة أصل كامل.

تتطلّب: read_http_history (يُمنح تلقائيًا).

`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`

الحمولة: { 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`

لا توجد حمولة. تُرجع إعداد النطاق المسبق النشط أو null.

تتطلّب: read_scope (يُمنح تلقائيًا).

`ogma.projects.getCurrent`

لا توجد حمولة. تُرجع { id, name, status } أو null.

تتطلّب: read_projects (يُمنح تلقائيًا).

`ogma.log`

الحمولة: { message: string }

تكتب في مخزن سجلات الإضافة.

`ogma.ui.resize`

الحمولة: { height: number } (الحد الأقصى 2000)

تطلب من المضيف ضبط ارتفاع iframe.

`ogma.ui.sidebar.registerItem`

الحمولة: { name: string, path: string } (الحد الأقصى للاسم 64 محرفًا وللمسار 256 محرفًا)

تسجّل عناصر التنقّل داخل لوحة الإضافة. الحد الأقصى 20 عنصرًا لكل إضافة. سجّل أجسام الصفحات المقابلة باستخدام sdk.navigation.addPage(path, { title, body })؛ يؤدي اختيار العنصر إلى عرض تلك الصفحة داخل iframe، لا إلى إنشاء مسار جديد على المستوى الأعلى في مساحة عمل Ogma.

`ogma.backend.call`

الحمولة: { method: string, args: unknown[] }

تستدعي معالج RPC خلفيًا مسجّلًا عبر sdk.api.register(method, fn). الحد الأقصى لطول اسم الطريقة هو 64 محرفًا.

تُرجع القيمة التي أعادها المعالج الخلفي، بعد تسلسلها بصيغة JSON.

`ogma.backend.onEvent`

الحمولة: غير مطلوبة.

يُقرّ بها فقط. استخدم ogma.events.poll لاسترجاع الأحداث فعليًا.

`ogma.events.poll`

الحمولة: { since: number } (الفهرس من آخر استطلاع؛ ابدأ من 0)

تُرجع { events: [{ event: string, args: unknown[] }], next_since: number }.

`ogma.navigation.addPage`

الحمولة: { path: string, title?: string }

يقرّ الجسر بمسار الصفحة. يقبل SDK المحقون أيضًا { body: HTMLElement } كخيار لـsdk.navigation.addPage(path, options)، ويُلحق الجسم داخل iframe، ويبدّل ظهور الصفحات عندما يختار المضيف عنصر الشريط الجانبي المقابل. تبقى عقدة DOM محلية؛ ولا تُسلسَل عبر الجسر.

`ogma.window.showToast`

الحمولة: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

تعرض إشعارًا عابرًا في لوحة الإضافة. المدة بالمللي ثانية (الحد الأقصى 10000، والقيمة الافتراضية 3000).

`ogma.commands.register`

الحمولة: { id: string, name: string }

تسجّل أمر الإضافة في مخزن أوامر المضيف. يرسل التنفيذ من المضيف رسالة plugin_command تتضمّن commandId والسياق إلى iframe؛ ويجب على الإضافة توفير دالة الاستدعاء الراجع المقابلة. التسجيل وحده لا ينفّذ الأمر.

`ogma.menu.registerItem`

الحمولة: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

تسجّل عنصر قائمة سياقية مرتبطًا بأمر إضافة. سجّل الأمر أولًا. تكون التسمية افتراضيًا اسم الأمر المسجّل، أو معرّفه إذا لم يتوفّر الاسم؛ وعند إغفال type تكون قيمته الافتراضية Request. لا يستخدم جسر المضيف leadingIcon.

أدوات مساعدة للمظهر

يوفّر SDK المحقون أيضًا sdk.theme.get() وsdk.theme.onChange(callback). تقرأ هاتان الطريقتان مظهر iframe وتشتركان في تحديثات المظهر من المضيف دون أمر منفصل لجسر البيانات. استخدمهما لإبقاء واجهة الإضافة متّسقة مع المظهر الفاتح أو الداكن في Ogma.

رموز الأخطاء

الرمز	المعنى
`PERMISSION_DENIED`	تفتقر الإضافة إلى الصلاحية المطلوبة.
`PLUGIN_DISABLED`	الإضافة غير مفعّلة حاليًا.
`UNKNOWN_COMMAND`	الأمر غير موجود في قائمة الأوامر المدعومة.
`INVALID_PAYLOAD`	حقل مطلوب في الحمولة مفقود أو نوعه غير صحيح.
`NOT_FOUND`	المورد المطلوب غير موجود.
`LIMIT_EXCEEDED`	تم بلوغ الحد الأقصى لعدد العناصر لكل إضافة (مثل عناصر الشريط الجانبي).
`SERVER_ERROR`	خطأ داخلي. راجع سجلات الإضافة.

قائمة الأوامر المدعومة

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.

مرجع SDK الواجهة الأمامية للإضافات ​

نموذج الأمان ​

بروتوكول الجسر ​

غلاف الطلب ​

غلاف الاستجابة ​

استخدام SDK (موصى به) ​

مرجع الأوامر ​

ogma.meta.get ​

ogma.requests.get ​

ogma.requests.getRaw ​

ogma.requests.search ​

ogma.findings.list ​

ogma.scope.getActive ​

ogma.projects.getCurrent ​

ogma.log ​

ogma.ui.resize ​

ogma.ui.sidebar.registerItem ​

ogma.backend.call ​

ogma.backend.onEvent ​

ogma.events.poll ​

ogma.navigation.addPage ​

ogma.window.showToast ​

ogma.commands.register ​

ogma.menu.registerItem ​

أدوات مساعدة للمظهر ​

رموز الأخطاء ​

قائمة الأوامر المدعومة ​

مرجع SDK الواجهة الأمامية للإضافات

نموذج الأمان

بروتوكول الجسر

غلاف الطلب

غلاف الاستجابة

استخدام SDK (موصى به)

مرجع الأوامر

`ogma.meta.get`

`ogma.requests.get`

`ogma.requests.getRaw`

`ogma.requests.search`

`ogma.findings.list`

`ogma.scope.getActive`

`ogma.projects.getCurrent`

`ogma.log`

`ogma.ui.resize`

`ogma.ui.sidebar.registerItem`

`ogma.backend.call`

`ogma.backend.onEvent`

`ogma.events.poll`

`ogma.navigation.addPage`

`ogma.window.showToast`

`ogma.commands.register`

`ogma.menu.registerItem`

أدوات مساعدة للمظهر

رموز الأخطاء

قائمة الأوامر المدعومة