Skip to main content
FDOInterface is the TypeScript interface that describes the full public contract for FDO plugins. When you extend FDO_SDK, your class is expected to satisfy this interface. You can also use FDOInterface directly for type-checking purposes.

​
Complete example

import { FDO_SDK, PluginRegistry } from "@anikitenko/fdo-sdk";
import type { FDOInterface, PluginMetadata, PluginCapability } from "@anikitenko/fdo-sdk";

class MyPlugin extends FDO_SDK implements FDOInterface {
  public metadata: PluginMetadata = {
    id: "acme-dashboard",
    name: "ACME Dashboard",
    version: "2.1.0",
    author: "acme",
    description: "Displays ACME platform metrics inside FDO.",
    icon: "dashboard",
  };

  declareCapabilities(): PluginCapability[] {
    return ["storage.json", "system.process.exec"];
  }

  init(): void {
    PluginRegistry.registerHandler("acme.refresh", async () => {
      const store = PluginRegistry.useStore("json");
      store.set("last-refresh", new Date().toISOString());
      return { ok: true };
    });
  }

  render(): string {
    const store = PluginRegistry.useStore("json");
    const lastRefresh = store.get<string>("last-refresh") ?? "never";
    return `
      <div style="padding: 1rem; font-family: sans-serif;">
        <h2>ACME Dashboard</h2>
        <p>Last refreshed: ${lastRefresh}</p>
        <button onclick="window.createBackendReq('acme.refresh', {})">Refresh</button>
      </div>
    `;
  }

  renderOnLoad(): string {
    return `() => {
      console.log("ACME Dashboard UI loaded");
    }`;
  }
}

export default new MyPlugin();

​
FDOInterface

export interface FDOInterface {
  declareCapabilities?(): PluginCapability[];
  init(): void;
  render(): string;
  renderOnLoad?(): string;
}

​
Methods

init(): void
Called by the FDO host after the plugin loads. Use this method to register handlers, configure stores, and perform any one-time setup. Must not be async — return void.Throwing from init() causes the host to receive a failure payload with an error message.
render(): string
Called by the FDO host to retrieve the plugin’s UI. Return a complete HTML string. Must be synchronous — returning a Promise causes a runtime error.The host renders the returned string inside a sandboxed iframe.
renderOnLoad?(): string
Override this method to return a JavaScript function string that the host executes after the plugin UI loads in the iframe. Must be synchronous.The default implementation (from FDO_SDK) returns '() => {}'.
declareCapabilities?(): PluginCapability[]
Override this method to declare which capabilities your plugin intends to use. The SDK compares your declarations against the capabilities the host has granted, and logs a warning for any declared capabilities that have not been granted.This is a preflight check for auditing and debugging — it does not grant capabilities itself.
declareCapabilities(): PluginCapability[] {
  return ["storage.json", "system.process.exec"];
}

​
PluginMetadata

export interface PluginMetadata {
  id?: string;
  name: string;
  version: string;
  author: string;
  description: string;
  icon: string;
}
Attach a metadata property to your plugin class to identify it to the FDO host. The SDK validates metadata shape at runtime.

​
Fields

​
id
string
Optional unique identifier for your plugin. When provided, the SDK uses this directly as the plugin’s storage scope and log scope (slugified). When omitted, the SDK derives an identifier from author and name.
​
name
string
required
Human-readable display name for your plugin.
​
version
string
required
Plugin version. Use semantic versioning (major.minor.patch).
​
author
string
required
Plugin author or organization name.
​
description
string
required
Short description of what the plugin does. Displayed in the FDO plugin browser.
​
icon
string
required
BlueprintJS v6 icon name to use for the plugin in the FDO UI.
The icon field must be a valid BlueprintJS v6 icon name (e.g., "cube", "dashboard", "code", "cog"). The SDK validates this at runtime using the built-in isBlueprintV6IconName utility. An invalid icon name causes metadata validation to fail.
public metadata: PluginMetadata = {
  id: "acme-dashboard",
  name: "ACME Dashboard",
  version: "1.0.0",
  author: "acme",
  description: "Displays ACME platform metrics inside FDO.",
  icon: "dashboard",
};

​
PluginCapability

export type FilesystemScopeCapability = `system.fs.scope.${string}`;
export type ProcessScopeCapability = `system.process.scope.${string}`;

export type PluginCapability =
  | "storage.json"
  | "sudo.prompt"
  | "system.hosts.write"
  | "system.process.exec"
  | FilesystemScopeCapability
  | ProcessScopeCapability;
PluginCapability is the union type of all capability strings that the FDO host can grant to your plugin. Capabilities gate access to privileged SDK features.
CapabilityDescription
"storage.json"Enables the persistent "json" store via PluginRegistry.useStore("json").
"sudo.prompt"Allows the plugin to prompt the user for elevated (sudo) credentials.
"system.hosts.write"Allows the plugin to request host-file modifications via privileged actions.
"system.process.exec"Allows the plugin to request process execution via privileged actions.
`system.fs.scope.${string}`Scoped filesystem access. The scope string identifies the allowed directory prefix.
`system.process.scope.${string}`Scoped process execution. The scope string identifies the allowed command or tool.
Use declareCapabilities() in your plugin class to declare which capabilities you intend to use. This enables preflight auditing and helps the FDO host verify your plugin’s requirements before granting access.

​
PluginHandler

export type PluginHandler<TInput = unknown, TOutput = unknown> =
  (data: TInput) => TOutput | Promise<TOutput>;
The type signature for all message handlers registered via PluginRegistry.registerHandler(). Handlers may be synchronous or asynchronous.
​
data
TInput
required
The payload sent by the UI or host. Type it with a generic if you know the shape.
Returns: TOutput | Promise<TOutput> — the handler’s result, which the SDK returns to the caller. 
import type { PluginHandler } from "@anikitenko/fdo-sdk";

const greetHandler: PluginHandler<{ name: string }, { message: string }> = async (data) => {
  return { message: `Hello, ${data.name}!` };
};

PluginRegistry.registerHandler("my-plugin.greet", greetHandler);

​
QuickAction

export type QuickAction = {
  name: string;
  message_type: string;
  subtitle?: string;
  icon?: string;
};
Defines a quick action entry that appears in the FDO command palette or quick-launch surface. Return an array of QuickAction from defineQuickActions() in your plugin class (using the QuickActionMixin).
​
name
string
required
Display name for the quick action.
​
message_type
string
required
The handler name to invoke when the user selects this quick action.
​
subtitle
string
Optional secondary description shown beneath the action name.
​
icon
string
Optional BlueprintJS v6 icon name for the action entry.
The icon field in QuickAction must be a valid BlueprintJS v6 icon name if provided. Pass the same icon names you use in PluginMetadata.icon.
defineQuickActions(): QuickAction[] {
  return [
    {
      name: "Refresh Dashboard",
      message_type: "acme.refresh",
      subtitle: "Pull latest metrics from the ACME API",
      icon: "refresh",
    },
    {
      name: "Open Settings",
      message_type: "acme.settings.open",
      icon: "cog",
    },
  ];
}

​
SidePanelConfig

export type SidePanelConfig = {
  icon: string;
  label: string;
  submenu_list: {
    id: string;
    name: string;
    message_type: string;
  }[];
};
Defines the side panel entry that appears in the FDO navigation rail. Return a SidePanelConfig from defineSidePanel() in your plugin class (using the SidePanelMixin).
​
icon
string
required
BlueprintJS v6 icon name for the side panel entry in the navigation rail.
​
label
string
required
Display label for the side panel entry.
​
submenu_list
object[]
required
The icon field must be a valid BlueprintJS v6 icon name. The FDO host validates this when rendering the navigation rail.
defineSidePanel(): SidePanelConfig {
  return {
    icon: "dashboard",
    label: "ACME",
    submenu_list: [
      {
        id: "acme-overview",
        name: "Overview",
        message_type: "acme.view.overview",
      },
      {
        id: "acme-metrics",
        name: "Metrics",
        message_type: "acme.view.metrics",
      },
    ],
  };
}