---
url: https://docs.ogmabox.com/fa/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'` - افزونه می‌تواند به `/plugins/{id}/api/*` درخواست POST بفرستد و `/plugins/{id}/events/poll` را پایش کند |
| دستور CSP‏ `default-src` | `'none'` |
| دسترسی به DOM والد | مسدود است (بدون `allow-same-origin`) |
| کوکی‌های نشست Ogma | افزونه به آن‌ها دسترسی ندارد |
| ارتباط بین افزونه‌ها | در دسترس نیست |

مجوز فراخوانی‌های پل داده در هر درخواست در سمت سرور بررسی می‌شود؛ اقدامات نمایش و پیمایش را رابط کاربری میزبان مدیریت می‌کند. حافظهٔ نهان مجوزها که در زبانهٔ مجوزها نمایش داده می‌شود فقط برای نمایش است و دسترسی به داده را کنترل نمی‌کند.

***

## پروتکل پل {#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[] }`

یک پردازشگر 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`.