Build a NaaP Plugin

interface ShellContext {
  auth: IAuthService;                  // Authentication and authorisation
  navigate: NavigateFunction;          // Client-side navigation
  eventBus: IEventBus;                 // Inter-plugin communication
  theme: IThemeService;                // Theme management
  notifications: INotificationService; // Toast notifications
  integrations: IIntegrationService;   // AI, storage, email
  logger: ILoggerService;              // Structured logging
  permissions: IPermissionService;     // Permission checking
  tenant?: ITenantService;             // Tenant context
  team?: ITeamContext;                 // Team context
}

const { useEffect, useState } = React;
import { useShell, useAuth } from '@naap/plugin-sdk';

interface OrchestratorRecord {
  ethAddress: string;
  uptimePercent: number;
  rejectedTicketsLast24h: number;
  capacityUtilisation: number;
}

export default function OrchestratorHealthPlugin() {
  const { navigate, notifications, logger } = useShell();
  const { user } = useAuth();
  const [orchestrators, setOrchestrators] = useState<OrchestratorRecord[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function load() {
      try {
        const res = await fetch('/api/v1/orchestrator-health/orchestrators');
        const body = (await res.json()) as {
          success: boolean;
          data?: OrchestratorRecord[];
        };
        if (body.success && body.data) {
          setOrchestrators(body.data);
        }
      } catch (err) {
        logger.error('Failed to load orchestrators', { err });
        notifications.error('Could not load orchestrator data');
      } finally {
        setLoading(false);
      }
    }
    load();
  }, [logger, notifications]);

  if (loading) {
    return <div className="p-8">Loading orchestrator health…</div>;
  }

  return (
    <main className="p-8 space-y-4">
      <header>
        <h1 className="text-2xl font-bold">Orchestrator Health</h1>
        <p className="text-sm text-gray-600">Signed in as {user?.email}</p>
      </header>
      <table className="w-full border-collapse">
        <thead>
          <tr className="border-b">
            <th className="text-left p-2">Address</th>
            <th className="text-left p-2">Uptime</th>
            <th className="text-left p-2">Rejected (24h)</th>
            <th className="text-left p-2">Capacity</th>
          </tr>
        </thead>
        <tbody>
          {orchestrators.map((o) => (
            <tr
              key={o.ethAddress}
              className="border-b hover:bg-gray-50 cursor-pointer"
              onClick={() => navigate(`/orchestrator-health/${o.ethAddress}`)}
            >
              <td className="p-2 font-mono text-sm">{o.ethAddress}</td>
              <td className="p-2">{o.uptimePercent.toFixed(1)}%</td>
              <td className="p-2">{o.rejectedTicketsLast24h}</td>
              <td className="p-2">{(o.capacityUtilisation * 100).toFixed(0)}%</td>
            </tr>
          ))}
        </tbody>
      </table>
    </main>
  );
}

import type { Request, Response } from 'express';
import { db } from '@naap/database';

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  meta?: { page?: number; limit?: number; total?: number };
  error?: { code: string; message: string };
}

interface OrchestratorRecord {
  ethAddress: string;
  uptimePercent: number;
  rejectedTicketsLast24h: number;
  capacityUtilisation: number;
}

export async function listOrchestrators(
  req: Request,
  res: Response<ApiResponse<OrchestratorRecord[]>>,
) {
  try {
    const rows = await db.query(
      `SELECT eth_address, uptime_percent, rejected_24h, capacity_util
       FROM orchestrator_health.orchestrators
       ORDER BY uptime_percent DESC
       LIMIT 100`,
    );

    const data: OrchestratorRecord[] = rows.map((r: any) => ({
      ethAddress: r.eth_address,
      uptimePercent: Number(r.uptime_percent),
      rejectedTicketsLast24h: Number(r.rejected_24h),
      capacityUtilisation: Number(r.capacity_util),
    }));

    res.json({ success: true, data });
  } catch (err) {
    res.status(500).json({
      success: false,
      error: {
        code: 'database_error',
        message: 'Failed to load orchestrators',
      },
    });
  }
}

import { Router } from 'express';
// Import listOrchestrators from ./orchestrators.

const router = Router();

router.get('/orchestrators', listOrchestrators);

export default router;

-- Plugin schema: orchestrator_health
-- Owned exclusively by the orchestrator-health plugin.

CREATE SCHEMA IF NOT EXISTS orchestrator_health;

CREATE TABLE IF NOT EXISTS orchestrator_health.orchestrators (
  eth_address       VARCHAR(42)  PRIMARY KEY,
  uptime_percent    DECIMAL(5,2) NOT NULL DEFAULT 0,
  rejected_24h      INTEGER      NOT NULL DEFAULT 0,
  capacity_util     DECIMAL(4,3) NOT NULL DEFAULT 0,
  last_updated      TIMESTAMP    NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_orch_uptime
  ON orchestrator_health.orchestrators (uptime_percent DESC);

CREATE TABLE IF NOT EXISTS orchestrator_health.health_events (
  id            SERIAL PRIMARY KEY,
  eth_address   VARCHAR(42) NOT NULL,
  event_type    VARCHAR(50) NOT NULL,
  payload       JSONB,
  recorded_at   TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_events_orch
  ON orchestrator_health.health_events (eth_address, recorded_at DESC);

import { useEventBus } from '@naap/plugin-sdk';

function MyComponent() {
  const eventBus = useEventBus();

  // Publish: tell every other plugin an orchestrator went unhealthy
  function alertUnhealthy(ethAddress: string) {
    eventBus.publish('orchestrator.unhealthy', { ethAddress, ts: Date.now() });
  }

  // Subscribe: react to events from other plugins
  useEffect(() => {
    const unsub = eventBus.subscribe('plugin.installed', (payload) => {
      console.log('Another plugin installed:', payload);
    });
    return unsub;
  }, [eventBus]);
}

Build the "Build a NaaP Plugin" tutorial using the current livepeer/NaaP repository. Clone https://github.com/livepeer/NaaP.git, run ./bin/start.sh, scaffold an orchestrator-health plugin with npx naap-plugin create orchestrator-health, and implement a plugin that displays orchestrator status, recent checks, and a backend health endpoint. Use the monorepo packages and local plugin SDK from the NaaP workspace; do not install @naap/plugin-sdk from npm. Add or update plugin.json, frontend components, backend routes, migrations if needed, and validation commands. Finish with run steps that start the NaaP shell, open the local plugin route, and run the repository's plugin validation command.