---
url: https://docs.ogmabox.com/bn/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`-এ 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}

হাতে Raw `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` ফেরত দেয়। নাম সত্ত্বেও এটি বডির বাইট ফেরত দেয়, সম্পূর্ণ Raw 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 }`

প্রতি পৃষ্ঠায় সর্বোচ্চ 20 ফলাফলসহ `{ items: [...], total: number, limit: number, offset: number }` ফেরত দেয়। উপাদানগুলো সারসংক্ষেপ; ফিল্ডে `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 }` (আগের poll-এর সূচক; 0 থেকে শুরু করুন)

`{ events: [{ event: string, args: unknown[] }], next_since: number }` ফেরত দেয়।

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

পেলোড: `{ path: string, title?: string }`

ব্রিজ পৃষ্ঠার পাথ স্বীকার করে। ইনজেক্ট করা SDK অতিরিক্তভাবে `sdk.navigation.addPage(path, options)`-এর বিকল্পে `{ body: HTMLElement }` গ্রহণ করে, 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 }`

হোস্টের কমান্ড স্টোরে প্লাগইন কমান্ড নিবন্ধন করে। হোস্ট চালালে `commandId` ও প্রসঙ্গসহ `plugin_command` বার্তা 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-র লাইট/ডার্ক চেহারার সঙ্গে প্লাগইন UI সামঞ্জস্য রাখতে ব্যবহার করুন।

***

## ত্রুটির কোড {#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`।