Building Plugins

Overview

A Pomavo plugin is a small, self-hosted web service that the host application talks to over a well-defined contract. Plugins extend Pomavo without touching the core: they add widgets, which are UI panels embedded in the app, themes, and integrations, and they run completely isolated from the host.

Everything a plugin needs is provided by the @pomavo/sdk package, which ships two halves:

Anatomy of a Plugin

A typical plugin is an Express or another Node HTTP server that exposes a handful of endpoints and serves one or more widget bundles:

1
2
3
4
5
6
7
8
9
10
11

my-plugin/
├── manifest.json         # id, widgets, params, lifecycle
├── src/
│   ├── index.ts          # HTTP server entry
│   ├── routes/
│   │   ├── lifecycle.ts  # install / uninstall / update
│   │   ├── api.ts        # data endpoints (token-guarded)
│   │   └── widgets.ts    # serves widget bundles
│   └── widgets/
│       └── MyWidget.tsx  # React UI for the iframe
└── package.json

The host never runs your code directly. Instead:

Install the SDK

1

npm install @pomavo/sdk

The package exposes two entry points so the browser bundle never pulls in server-only code:

1
2
3
4
5
6
7
8
9
10

// In your widget (browser)
import { PomavoBridge } from '@pomavo/sdk/client';
 
// In your backend (Node)
import {
  PomavoClient,
  createLifecycleHandler,
  createTokenVerifier,
  verifyPluginToken,
} from '@pomavo/sdk/server';

The Security Model

Plugins are designed so that installing one can never compromise the rest of Pomavo:

• Sandboxed UI - widget code runs in an isolated iframe (allow-scripts allow-same-origin allow-popups). It cannot read the host DOM, cookies, or session.
• Explicit context - a widget only receives what the host chooses to pass through the bridge: a token, its saved settings, and the current ticket.
• Signed tokens - the host token is an HS256 JWT signed with your per-installation sharedSecret, so your backend can trust the org/user it names.
• Scoped integrations - Pomavo API access is granted through integration API keys tied to the installing organization and the permissions your manifest requests.
• Per-organization installs - a plugin is only active for organizations that install it, and uninstalling fully revokes its widgets and keys.

Next Steps