প্লাগইনের ফ্রন্টএন্ড SDK রেফারেন্স

প্লাগইনের ফ্রন্টএন্ড কোড স্যান্ডবক্স করা iframe-এ চলে। এই নথি নিচের স্তরের রেফারেন্স। উচ্চতর স্তরের পরিচিতির জন্য README.md দেখুন।

নিরাপত্তা মডেল

বৈশিষ্ট্য	মান
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 সামলায়। অনুমতি ট্যাবের ক্যাশ শুধু দেখানোর জন্য; এটি তথ্যের অ্যাক্সেস নিয়ন্ত্রণ করে না।

ব্রিজ প্রোটোকল

প্লাগইনের JS postMessage দিয়ে Ogma হোস্টে যোগাযোগ করে। হোস্ট 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 ব্যবহার (প্রস্তাবিত)

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

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

sdk.api.register(method, fn) দিয়ে নিবন্ধিত ব্যাকএন্ড RPC হ্যান্ডলার কল করে। মেথডের নামের সর্বোচ্চ দৈর্ঘ্য 64 অক্ষর।

ব্যাকএন্ড হ্যান্ডলারের ফেরত দেওয়া মান JSON সিরিয়ালাইজ করে ফেরত দেয়।

`ogma.backend.onEvent`

পেলোড: দরকার নেই।

শুধু স্বীকৃতি দেয়। প্রকৃত ইভেন্ট পেতে ogma.events.poll ব্যবহার করুন।

`ogma.events.poll`

পেলোড: { since: number } (আগের poll-এর সূচক; 0 থেকে শুরু করুন)

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

`ogma.navigation.addPage`

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

ব্রিজ পৃষ্ঠার পাথ স্বীকার করে। ইনজেক্ট করা SDK অতিরিক্তভাবে sdk.navigation.addPage(path, options)-এর বিকল্পে { body: HTMLElement } গ্রহণ করে, iframe-এর মধ্যে বডি যুক্ত করে এবং হোস্ট সংশ্লিষ্ট সাইডবার উপাদান বাছলে দৃশ্যমান পৃষ্ঠা বদলায়। DOM নোড স্থানীয় থাকে; ব্রিজ দিয়ে সিরিয়ালাইজ করা হয় না।

`ogma.window.showToast`

পেলোড: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

প্লাগইন প্যানেলে সাময়িক বিজ্ঞপ্তি দেখায়। সময় মিলিসেকেন্ডে (সর্বোচ্চ 10000, ডিফল্ট 3000)।

`ogma.commands.register`

পেলোড: { id: string, name: string }

হোস্টের কমান্ড স্টোরে প্লাগইন কমান্ড নিবন্ধন করে। হোস্ট চালালে commandId ও প্রসঙ্গসহ plugin_command বার্তা iframe-এ পাঠায়; প্লাগইনকে সংশ্লিষ্ট কলব্যাক দিতে হবে। শুধু নিবন্ধন করলে কমান্ড চলে না।

`ogma.menu.registerItem`

পেলোড: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

প্লাগইন কমান্ডের সঙ্গে যুক্ত প্রসঙ্গ মেনুর উপাদান নিবন্ধন করে। আগে কমান্ড নিবন্ধন করুন। ডিফল্ট লেবেল কমান্ডের নিবন্ধিত নাম, তারপর তার ID। type না দিলে ডিফল্ট Request। হোস্ট ব্রিজ leadingIcon ব্যবহার করে না।

থিমের সহায়ক

ইনজেক্ট করা SDK sdk.theme.get() ও sdk.theme.onChange(callback)-ও দেয়। আলাদা তথ্য ব্রিজ কমান্ড ছাড়াই iframe-এর থিম পড়ে এবং হোস্টের থিম হালনাগাদে সাবস্ক্রাইব করে। Ogma-র লাইট/ডার্ক চেহারার সঙ্গে প্লাগইন UI সামঞ্জস্য রাখতে ব্যবহার করুন।

ত্রুটির কোড

কোড	অর্থ
`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`

থিমের সহায়ক

ত্রুটির কোড

সমর্থিত কমান্ডের তালিকা