Skip to main content

Plugin SDK Reference

API reference for @radarboard/plugin-sdk — descriptors, PluginAPI, intents, MCP tools, and testing.

./types

resolvePresentationConfig()

Normalise the descriptor’s presentation field into the full object form.

pluginHasAlternateMode()

Check whether a plugin supports more than one presentation mode.

pluginHasPermission()

Check if a plugin has a specific permission.

pluginSupportsNotifications()

Returns true if the plugin declares a notifications integration in its descriptor.

pluginSupportsTicker()

Returns true if the plugin declares a ticker integration in its descriptor.

isPluginNotificationIntegrationEnabled()

Checks whether the plugin’s notification integration is enabled, considering user config and descriptor defaults.

isPluginTickerIntegrationEnabled()

Checks whether the plugin’s ticker integration is enabled, considering user config and descriptor defaults.

PresentationMode

All possible presentation modes for a plugin overlay.
  • "side-panel" — slides in from the right (most common)
  • "fullscreen" — takes over the viewport
  • "modal" — centered dialog
  • "mini-hud" — small floating widget

PluginPresentationConfig

Structured presentation config — declares a default mode and optional alternates. Use this instead of a plain PresentationMode string when you want users to switch between modes (e.g. side-panel ↔ fullscreen). Example:

ResolvedPresentationConfig

Resolved presentation config — always the full object form.

PluginIntentHandler

An action a plugin can receive from other plugins or the assistant. Register intent handlers in your descriptor to let other plugins or the AI assistant send data into your plugin. The intent bus resolves matching handlers by payload kind and presents them in the “Send to…” menu. Example:

ResolvedIntentTarget

A resolved target returned by the intent bus for UI rendering.

PluginDescriptor

The public contract every plugin must export from its entry point. The descriptor declares everything Radarboard needs to register, render, and manage a plugin — identity, UI, tools, settings, and lifecycle hooks. Extends: ExtensionMeta Example:

PluginServiceDefinition

A service a plugin exposes for cross-plugin RPC calls. Other plugins invoke services via api.rpc.call(pluginId, action, params). The params are validated at runtime against the declared Zod schema. Example:

PluginRpcResult

Result of an RPC call.

PluginPermission

Capabilities a plugin may request access to.

PluginLifecycleCleanup

Cleanup function returned from a lifecycle hook.

PluginLifecycleHooks

Optional hooks called at specific stages of a plugin’s lifecycle (init, activate, deactivate, destroy).

PluginMigration

A data migration for upgrading plugin DB schema between versions. Migrations run automatically when the plugin’s stored version is older than the descriptor’s version. List in ascending semver order. Example:

PluginSettingType

The supported input types for plugin user-configurable settings.

PluginSettingDefinition

Describes one user-configurable option for a plugin. Each setting renders as a form field in the plugin’s settings panel. Values are stored in the plugin DB under _config:<key>. Example:

PluginUserConfig

User-level overrides for a plugin’s behavior, stored in the plugin DB.

PluginRadarboardSurfaceConfig

Per-surface configuration for a plugin’s integration into a shared Radarboard surface.

PluginRadarboardIntegrationConfig

Declares which shared Radarboard surfaces (notifications, ticker) a plugin integrates with.

PluginConnectionType

How a plugin can connect to an external data source.
  • "mcp" — via an MCP server (e.g. a locally running server)
  • "oauth" — via OAuth redirect flow
  • "api_key" — via a manually entered API token

PluginDataSource

Declares an external service a plugin can pull data from. Plugins can connect to external APIs, MCP servers, or OAuth providers. The user configures connections in the plugin settings UI. Example:

PluginWidgetContribution

A dashboard widget contributed by a plugin. Plugins can embed widgets in the main grid. The widget is registered as "<pluginId>__<widgetId>" and uses the shared template engine. Example:

PluginAPI

Runtime API injected into every plugin via PluginRenderProps. Provides scoped database access, notifications, hotkeys, event bus, cross-plugin communication (intents + RPC), and project data. Example:

PluginRenderProps

Props passed to every plugin’s main component. Your overlay component receives this as its only prop. Destructure api to access the full PluginAPI. Example:

McpToolDefinition

Defines an MCP tool that the AI assistant can invoke on behalf of the user. Tools are automatically namespaced as "<pluginId>__<name>" when registered. The execute function receives Zod-validated params and the plugin’s API. Example:

./registry

registerPlugin()

Register a plugin descriptor into the global registry. Silently skips re-registration (for HMR); throws if the description is too long.

getPlugin()

Get a registered plugin by ID, or undefined if not found.

getAllPlugins()

Get all registered plugins as an array.

./intent-bus

No documented exports.

./crud-helpers

createCrudHelper()

Create a typed CRUD helper scoped to a DB key prefix. The prefix is used as "<prefix>:<id>" for each item key. For example, createCrudHelper(api, "task") stores items as "task:abc123".
Example:

Identifiable

An entity with a string id field.

CrudHelper

CRUD operations for a keyed collection in the plugin DB. All operations are type-safe and scoped to a single key prefix.

./testing

createMockPluginAPI()

Create a mock PluginAPI backed by an in-memory Map. Useful for testing MCP tools and plugin logic.

createTestPluginHost()

Create a test plugin host that registers descriptors and provides scoped, tracked PluginAPIs with real intent dispatch. Usage:

TrackedPluginAPI

A mock PluginAPI that records all calls (notifications, events, close) for test assertions. Extends: PluginAPI

TestPluginHost

Test harness that registers plugin descriptors and provides scoped, tracked APIs with real intent dispatch.