OmniRoute/docs/i18n/ha/docs/frameworks/PLUGIN_SDK.md

OmniRoute Plugin SDK (Hausa)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Farawa Cikin Sauri

import { definePlugin } from "omniroute/plugins/sdk";

export default definePlugin({
  name: "my-plugin",
  priority: 50,
  onRequest: async (ctx) => {
    console.log(`Request ${ctx.requestId} for ${ctx.model}`);
  },
  onResponse: async (ctx, response) => {
    console.log(`Response for ${ctx.requestId}`);
    return response;
  },
  onError: async (ctx, error) => {
    console.error(`Error: ${error.message}`);
  },
});

Manazartar API

definePlugin(def: PluginDefinition): Plugin

Aikin factory wanda ke ƙirƙirar abin Plugin tare da tsoffin ƙimomi.

Sigogi:

• name (string, wajibi) — Sunan plugin a tsarin kebab-case
• priority (number, na zaɓi, tsoho: 100) — Mafi ƙarancin ƙima ne ke fara aiki
• enabled (boolean, na zaɓi, tsoho: true) — A fara a kunne?
• onRequest (function, na zaɓi) — Yana aiki kafin chat handler
• onResponse (function, na zaɓi) — Yana aiki bayan chat handler
• onError (function, na zaɓi) — Yana aiki idan kuskure ya faru a handler

blockRequest(response?): BlockingHookResult

Toshe buƙatar sannan, idan ana so, a mayar da amsa ta musamman.

onRequest: (ctx) => {
  if (!ctx.headers["authorization"]) {
    return blockRequest({ error: "Unauthorized", status: 401 });
  }
};

modifyBody(body): PluginResult

Gyara jikin buƙatar kafin ya isa ga provider.

onRequest: (ctx) => {
  return modifyBody({ ...ctx.body, temperature: 0.7 });
};

addMetadata(metadata): PluginResult

Haɗa metadata zuwa mahallin buƙatar.

onRequest: (ctx) => {
  return addMetadata({ source: "my-plugin", version: "1.0.0" });
};

Mahallin Plugin (PluginContext)

Fili	Nau'i	Bayani
requestId	string	Mai gano buƙata na musamman
model	string	Sunan model ɗin da aka nema
provider	string	ID na provider da aka nufa
body	Record<string, unknown>	Jikin buƙata
headers	Record<string, string>	Headers na buƙata
metadata	Record<string, unknown>	Metadata mai iya sauyawa
timestamp	number	Lokacin buƙata

Manifest (plugin.json)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A sample plugin",
  "author": "your-name",
  "main": "index.js",
  "hooks": {
    "onRequest": { "enabled": true, "priority": 50 },
    "onResponse": true,
    "onError": false
  },
  "requires": {
    "permissions": ["network", "file-read"]
  },
  "enabledByDefault": false,
  "configSchema": {
    "apiKey": {
      "type": "string",
      "description": "API key for external service"
    },
    "maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
    "debug": { "type": "boolean", "default": false },
    "mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
  }
}

Fifikon Hook

Ana iya saita hooks tare da fifiko (ƙarami = yana fara aiki):

{
  "hooks": {
    "onRequest": { "enabled": true, "priority": 10 },
    "onResponse": { "enabled": true, "priority": 100 }
  }
}

Ko kuma a matsayin booleans masu sauƙi (tsohon fifiko 100):

{
  "hooks": {
    "onRequest": true,
    "onResponse": true
  }
}

Tsarin Izini

Plugins suna aiki a cikin mahallin VM mai killacewa. Samun dama ga albarkatun waje yana buƙatar takamaiman izini:

Izini	Abubuwan da yake ba da dama
network	fetch, AbortController, Headers, Request, Response
file-read	fs.readFile, fs.readdir, fs.stat
file-write	fs.writeFile, fs.mkdir, fs.rm
env	Wakilin process.env mai izinin karantawa kawai
exec	child_process.exec, child_process.execSync

Idan babu izini, globals masu alaƙa da shi ba za su kasance samuwa a cikin sandbox ba.

Tsarin Config

Ƙayyade saitunan da za a iya daidaitawa a cikin configSchema:

{
  "configSchema": {
    "apiKey": { "type": "string", "description": "External API key" },
    "maxRetries": { "type": "number", "min": 1, "max": 10, "default": 3 },
    "debug": { "type": "boolean", "default": false },
    "mode": { "type": "string", "enum": ["fast", "slow"], "default": "fast" }
  }
}

Nau'ikan filaye: string, number, boolean, select

Zaɓuɓɓukan filaye: default, min, max, enum, description

Ana adana ƙimomin config a cikin ma'ajiyar bayanai kuma ana iya samun damar su ta shafin config na dashboard.

Abubuwan da aka Gina a Ciki

Event	Lokacin da yake faruwa	Payload
onRequest	Kafin chat handler	Mahallin request
onResponse	Bayan chat handler	Bayanan response
onError	Lokacin kuskuren handler	Abun kuskure
onModelSelect	An zaɓi model don routing	Bayanin model
onComboResolve	An warware combo routing	Manufofin combo
onRateLimit	An kai iyakar rate	Bayanin iyaka
onQuotaExhaust	Quota ya ƙare	Bayanin quota
onProviderError	Provider ya mayar da kuskure	Cikakkun bayanan kuskure
onStreamStart	An fara SSE stream	Bayanin stream
onStreamEnd	SSE stream ya ƙare	Ƙididdigar stream
onInstall	An girka plugin	{ name, version, manifest }
onActivate	An kunna plugin	{ name, version, manifest }
onDeactivate	An kashe plugin	{ name, version, manifest }
onUninstall	An cire plugin (kafin a goge fayiloli)	{ name, version, manifest }

Misalai

Mai Rubuta Bayanan Request

import { definePlugin } from "omniroute/plugins/sdk";

export default definePlugin({
  name: "request-logger",
  onRequest: async (ctx) => {
    console.log(`[${new Date().toISOString()}] ${ctx.method} ${ctx.model} -> ${ctx.provider}`);
  },
});

Mai Iyakance Rate

import { definePlugin, blockRequest } from "omniroute/plugins/sdk";

const requests = new Map<string, number[]>();

export default definePlugin({
  name: "rate-limiter",
  priority: 10,
  onRequest: async (ctx) => {
    const key = ctx.headers["x-api-key"] || "anonymous";
    const now = Date.now();
    const window = 60000; // Minti 1
    const maxRequests = 100;

    const timestamps = (requests.get(key) || []).filter((t) => t > now - window);
    timestamps.push(now);
    requests.set(key, timestamps);

    if (timestamps.length > maxRequests) {
      return blockRequest({ error: "Rate limit exceeded", status: 429 });
    }
  },
});

Mai Sauya Response

import { definePlugin } from "omniroute/plugins/sdk";

export default definePlugin({
  name: "response-transformer",
  onResponse: async (ctx, response) => {
    if (response.choices) {
      response.choices = response.choices.map((c: any) => ({
        ...c,
        message: { ...c.message, content: c.message.content.trim() },
      }));
    }
    return response;
  },
});