@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