@kaijinlab/ogma-sdk

TypeScript type definitions for the Ogma plugin SDK.

---

This package provides TypeScript type definitions for the Ogma plugin SDK. It has no runtime code -- types only.

Install

npm install --save-dev @kaijinlab/ogma-sdk

Quick start

import type { OgmaBackendSdk, HttpRequest, HttpResponse } from '@kaijinlab/ogma-sdk';

async function init(sdk: OgmaBackendSdk): Promise<void> {
  sdk.console.log('Plugin started');

  sdk.events.onInterceptResponse(function (req: HttpRequest, resp?: HttpResponse): void {
    if (!resp) return;

    const host = req.getHost();
    const status = resp.getCode();
    const ct = resp.getHeader('content-type') ?? '';

    sdk.console.log(`${status} ${host} -- ${ct}`);
  });
}

// Expose init to the Ogma runtime
(globalThis as unknown as Record<string, unknown>).init = init;

Build with esbuild:

npx esbuild src/backend.ts --bundle --format=iife --platform=neutral \
  --external:@kaijinlab/ogma-sdk --outfile=dist/backend.js

The --external:@kaijinlab/ogma-sdk flag tells esbuild not to bundle this package. The SDK is types-only -- the actual implementation is provided by the Ogma runtime.

---

SDK reference

sdk.console

sdk.console.log(message: string): void
sdk.console.warn(message: string): void
sdk.console.error(message: string): void

Logs appear in Settings > Plugins > [your plugin] > Logs.

---

sdk.events

sdk.events.onInterceptRequest(callback: (req: HttpRequest) => void | Promise<void>): void
sdk.events.onInterceptResponse(callback: (req: HttpRequest, resp?: HttpResponse) => void): void
sdk.events.onProjectChange(callback: () => void): void
sdk.events.onCurrentRuleChange(callback: () => void): void
sdk.events.onUpstream(callback: (req: RequestSpec) => RequestSpec | void): void

---

sdk.requests

// Fetch a single history entry
sdk.requests.get(id: string): Promise<{ request: HttpRequest; response?: HttpResponse } | undefined>

// Search HTTP history with HTTPQL
sdk.requests.search(opts?: { q?: string; limit?: number; offset?: number }): Promise<SearchResult[]>

// Send an outbound HTTP request
sdk.requests.send(spec: RequestSpec): Promise<{ response: HttpResponse }>

Requires the send_requests permission to call sdk.requests.send().

---

sdk.findings

sdk.findings.create(spec: CreateFindingSpec): Promise<Finding>
sdk.findings.get(id: string): Promise<Finding | undefined>
sdk.findings.list(opts?: ListFindingsOptions): Promise<{ findings: Finding[]; total: number }>
sdk.findings.update(id: string, patch: Partial<CreateFindingSpec>): Promise<Finding>
sdk.findings.exists(key: string | { dedupeKey: string }): Promise<boolean>

Requires the write_findings permission. Calls to sdk.findings.create() must be made inside an event callback (onInterceptRequest or onInterceptResponse).

interface CreateFindingSpec {
  title: string;
  severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
  description: string;
  dedupe_key?: string; // prevents duplicate findings per host/check
  entry_id?: string;   // links the finding to an HTTP entry
}

---

sdk.storage

Persistent key-value store scoped to your plugin. Survives restarts.

sdk.storage.get(key: string): Promise<string | null>
sdk.storage.set(key: string, value: string): Promise<void>
sdk.storage.delete(key: string): Promise<void>
sdk.storage.keys(): Promise<string[]>
sdk.storage.clear(): Promise<void>

---

sdk.api

Bridge between your backend and frontend.

// Register a function callable from the frontend
sdk.api.register(name: string, fn: (...args: unknown[]) => unknown | Promise<unknown>): void

// Send an event to the frontend
sdk.api.send(event: string, ...args: unknown[]): void

In the frontend, receive events with sdk.backend.onEvent() and call backend functions with sdk.backend.call(name, ...args).

---

sdk.env

Read environment variables defined in Settings > Environment.

sdk.env.getVar(name: string): string | undefined

Requires the read_env_vars permission.

---

sdk.scope

sdk.scope.getActive(): Promise<ScopePreset | null>
sdk.scope.inScope(url: string): Promise<boolean>

---

sdk.projects

sdk.projects.getCurrent(): Promise<OgmaProject | null>

---

HttpRequest methods

Method	Returns	Description
getId()	string | null	History entry ID
getHost()	string	Hostname, e.g. example.com
getPort()	number	Port number
getMethod()	string	HTTP method
getPath()	string	URL path
getQuery()	string	Query string (without ?)
getUrl()	string	Full URL
getHeaders()	Record<string, string>	All request headers
getHeader(name)	string | undefined	Single header, case-insensitive
getBody()	string | null	Request body

HttpResponse methods

Method	Returns	Description
getId()	string | null	History entry ID
getCode()	number	HTTP status code
getHeaders()	Record<string, string>	All response headers
getHeader(name)	string | undefined	Single header, case-insensitive
getBody()	string | null	Response body
getRoundtripTime()	number	Round-trip time in milliseconds
getCreatedAt()	number	Unix timestamp (ms)

---

Plugin constraints

• No import or require in backend plugins. Bundle everything into a single file.
• No fetch or XMLHttpRequest. Use sdk.requests.send() for outbound requests.
• No localStorage in frontend plugins. Use sdk.storage for persistence.
• Backend script size limit: 256 KB.

---

Plugin permissions

Declare all permissions your plugin uses in manifest.json:

Permission	Required for
write_findings	sdk.findings.create(), sdk.findings.update()
read_http_history	sdk.requests.search(), sdk.requests.get()
send_requests	sdk.requests.send()
ui_extension	Any frontend entry point
read_env_vars	sdk.env.getVar()

---

Plugin examples

• Request Counter -- minimal plain JavaScript plugin
• Security Headers Checker -- TypeScript + esbuild

Browse the full registry: awesome-ogma-plugins

---

Contributing

Type corrections and additions are welcome. Open an issue or a pull request.

Before submitting, verify the types compile:

npx tsc --noEmit --strict --moduleResolution node index.d.ts

---

License

AGPL-3.0-only