@owncast/plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 SDK for authoring [Owncast](https://owncast.online) plugins in JavaScript or TypeScript. Plugins compile to WebAssembly and run sandboxed inside the Owncast server.
 
-Most authors don't install this directly — instead, scaffold a new project with `npm create owncast-plugin <name>` and the generated `package.json` already lists it as a dependency.
+Most authors don't install this directly, instead, scaffold a new project with `npm create owncast-plugin <name>` and the generated `package.json` already lists it as a dependency.
 
 ## Quick start
 
@@ -38,10 +38,11 @@ Declare the permissions your plugin uses (`chat.send` for the example above) in
 
 ## What's in the package
 
-- `index.js` — runtime: `definePlugin`, the `owncast.*` host wrappers, the `filter` constructor.
-- `index.d.ts` — TypeScript declarations for editor autocomplete on every event payload and host API.
-- `bin/owncast-plugin` — CLI: `build`, `test`, `serve`, `package` subcommands.
-- `scripts/postinstall.js` — downloads the per-platform wasm toolchain (`extism-js`, `wasm-merge`, `wasm-opt`) and the Go test/serve runner on install.
+- `index.js`, runtime: `definePlugin`, the `owncast.*` host wrappers, the `filter` constructor.
+- `index.d.ts`, TypeScript declarations for editor autocomplete on every event payload and host API.
+- `testing.js`, JS test API (`runScenarios`) for writing `__tests__/*.test.js` with the full ergonomics of JavaScript instead of static JSON.
+- `bin/owncast-plugin`, CLI: `build`, `test`, `serve`, `package` subcommands.
+- `scripts/postinstall.js`, downloads the per-platform wasm toolchain (`extism-js`, `wasm-merge`, `wasm-opt`) and the Go test/serve runner on install.
 
 ## License
 

package/bin/owncast-plugin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// `owncast-plugin build`   — bundle src/plugin.{js,ts} into <name>.wasm
-// `owncast-plugin test`    — run scenarios in __tests__/ against the wasm
-// `owncast-plugin serve`   — run a localhost dev HTTP server
-// `owncast-plugin package` — produce a single-file <name>.ocpkg suitable
+// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <name>.wasm
+// `owncast-plugin test`   , run scenarios in __tests__/ against the wasm
+// `owncast-plugin serve`  , run a localhost dev HTTP server
+// `owncast-plugin package`, produce a single-file <name>.ocpkg suitable
 //                            for distribution / installation
 
 const fs = require("fs");
@@ -23,7 +23,9 @@ if (cmd === "build") {
 } else if (cmd === "package") {
   packageMain().catch(fail);
 } else {
-  console.error(`unknown command: ${cmd}\nusage: owncast-plugin <build|test|serve|package>`);
+  console.error(
+    `unknown command: ${cmd}\nusage: owncast-plugin <build|test|serve|package>`,
+  );
   process.exit(1);
 }
 
@@ -46,17 +48,20 @@ function runBinary(name, args) {
   if (!fs.existsSync(bin)) {
     console.error(
       `${name} not found at ${bin}\n` +
-      `In production this is fetched by the SDK postinstall. For the PoC, ` +
-      `build it via: cd owncast && go build -o tools/${name} ./cmd/${name}`
+        `In production this is fetched by the SDK postinstall. For the PoC, ` +
+        `build it via: cd owncast && go build -o tools/${name} ./cmd/${name}`,
     );
     process.exit(1);
   }
   const env = {
     ...process.env,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`
+    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
   };
   try {
-    execFileSync(bin, args.length > 0 ? args : [process.cwd()], { stdio: "inherit", env });
+    execFileSync(bin, args.length > 0 ? args : [process.cwd()], {
+      stdio: "inherit",
+      env,
+    });
   } catch (e) {
     process.exit(typeof e.status === "number" ? e.status : 1);
   }
@@ -74,14 +79,22 @@ async function buildMain() {
 
   // Detect entry point.
   let entry = null;
-  for (const candidate of ["src/plugin.ts", "src/plugin.js", "plugin.ts", "plugin.js"]) {
+  for (const candidate of [
+    "src/plugin.ts",
+    "src/plugin.js",
+    "plugin.ts",
+    "plugin.js",
+  ]) {
     const p = path.join(cwd, candidate);
     if (fs.existsSync(p)) {
       entry = p;
       break;
     }
   }
-  if (!entry) throw new Error("no plugin source found (expected src/plugin.ts or plugin.js)");
+  if (!entry)
+    throw new Error(
+      "no plugin source found (expected src/plugin.ts or plugin.js)",
+    );
 
   // Synthesize an entry that injects the manifest, requires user code,
   // then re-exports the SDK runtime exports as wasm-visible exports.
@@ -132,7 +145,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
     platform: "neutral",
     target: "es2020",
     outfile: bundledJS,
-    logLevel: "warning"
+    logLevel: "warning",
   });
 
   // Generate index.d.ts declaring exports + host imports based on permissions.
@@ -143,16 +156,21 @@ module.exports = { register, on_event, on_filter, on_http_request };
   const cache = findCacheDir();
   const extismJs = path.join(cache, "extism-js");
   if (!fs.existsSync(extismJs)) {
-    throw new Error(`extism-js not found at ${extismJs} — run \`npm install\` to fetch the toolchain`);
+    throw new Error(
+      `extism-js not found at ${extismJs}, run \`npm install\` to fetch the toolchain`,
+    );
   }
   const env = {
     ...process.env,
     PATH: `${cache}:${process.env.PATH}`,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`
+    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
   };
 
   const wasmOut = path.join(cwd, `${name}.wasm`);
-  execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], { stdio: "inherit", env });
+  execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], {
+    stdio: "inherit",
+    env,
+  });
 
   // If the project ships static assets in ./assets/, mirror them to the
   // canonical deployment layout (<name>-assets/) so plugin.Server finds them
@@ -162,15 +180,28 @@ module.exports = { register, on_event, on_filter, on_http_request };
   if (fs.existsSync(assetsSrc) && fs.statSync(assetsSrc).isDirectory()) {
     const assetsDest = path.join(cwd, `${name}-assets`);
     let needsLink = true;
-    if (fs.existsSync(assetsDest)) {
-      try {
-        const st = fs.lstatSync(assetsDest);
-        if (st.isSymbolicLink() && fs.realpathSync(assetsDest) === fs.realpathSync(assetsSrc)) {
-          needsLink = false;
-        } else {
-          fs.rmSync(assetsDest, { recursive: true, force: true });
-        }
-      } catch {
+    // Use lstatSync (not existsSync), existsSync follows symlinks and
+    // returns false for a dangling link, but the link's inode is still
+    // there and would make symlinkSync below fail with EEXIST. lstatSync
+    // sees the link itself regardless of whether its target resolves.
+    let st;
+    try {
+      st = fs.lstatSync(assetsDest);
+    } catch {
+      // path doesn't exist at all, fall through to create it.
+    }
+    if (st) {
+      let target;
+      if (st.isSymbolicLink()) {
+        // realpathSync throws on dangling links; treat that as "doesn't
+        // match, replace it" rather than letting it abort the build.
+        try {
+          target = fs.realpathSync(assetsDest);
+        } catch {}
+      }
+      if (target && target === fs.realpathSync(assetsSrc)) {
+        needsLink = false;
+      } else {
         fs.rmSync(assetsDest, { recursive: true, force: true });
       }
     }
@@ -182,7 +213,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
   console.log(`built ${path.relative(cwd, wasmOut)}`);
 }
 
-// `owncast-plugin package` — bundle the project into a single .ocpkg file
+// `owncast-plugin package`, bundle the project into a single .ocpkg file
 // (zip archive with plugin.manifest.json, plugin.wasm, and optional assets/).
 // Builds the wasm first if it doesn't exist.
 async function packageMain() {
@@ -217,11 +248,13 @@ async function packageMain() {
   const buf = await zip.generateAsync({
     type: "nodebuffer",
     compression: "DEFLATE",
-    compressionOptions: { level: 6 }
+    compressionOptions: { level: 6 },
   });
   fs.writeFileSync(outPath, buf);
   const sizeKb = Math.round(fs.statSync(outPath).size / 1024);
-  console.log(`packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`);
+  console.log(
+    `packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`,
+  );
 }
 
 function* walkFiles(dir) {
@@ -248,7 +281,7 @@ function generateInterface(manifest) {
     "register(): I32",
     "on_event(): I32",
     "on_filter(): I32",
-    "on_http_request(): I32"
+    "on_http_request(): I32",
   ];
 
   const perms = new Set(manifest.permissions || []);
@@ -277,7 +310,9 @@ function generateInterface(manifest) {
     imports.push("owncast_user_get(idPtr: PTR): PTR");
   }
   if (perms.has("users.moderate")) {
-    imports.push("owncast_user_set_enabled(idPtr: PTR, enabled: I32, reasonPtr: PTR): void");
+    imports.push(
+      "owncast_user_set_enabled(idPtr: PTR, enabled: I32, reasonPtr: PTR): void",
+    );
     imports.push("owncast_ban_ip(ipPtr: PTR): void");
   }
   if (perms.has("storage.upload")) {
@@ -290,8 +325,14 @@ function generateInterface(manifest) {
     imports.push("owncast_kv_get(keyPtr: PTR): PTR");
     imports.push("owncast_kv_set(keyPtr: PTR, valPtr: PTR): void");
   }
-  if (perms.has("events.emit")) imports.push("owncast_emit_event(eventTypePtr: PTR, payloadPtr: PTR): void");
-  if (perms.has("http.sse")) imports.push("owncast_sse_send(channelPtr: PTR, eventPtr: PTR, dataPtr: PTR): void");
+  if (perms.has("events.emit"))
+    imports.push(
+      "owncast_emit_event(eventTypePtr: PTR, payloadPtr: PTR): void",
+    );
+  if (perms.has("http.sse"))
+    imports.push(
+      "owncast_sse_send(channelPtr: PTR, eventPtr: PTR, dataPtr: PTR): void",
+    );
   if (perms.has("server.read")) {
     imports.push("owncast_stream_current(): PTR");
     imports.push("owncast_server_info(): PTR");
@@ -306,6 +347,10 @@ function generateInterface(manifest) {
   if (perms.has("videoconfig.write")) {
     imports.push("owncast_video_config_write(configPtr: PTR): PTR");
   }
+  if (perms.has("ui.modify")) {
+    imports.push("owncast_add_actions(actionsPtr: PTR): void");
+    imports.push("owncast_clear_actions(): void");
+  }
 
   let out = `declare module 'main' {\n`;
   for (const e of exports) out += `  export function ${e};\n`;
@@ -326,9 +371,9 @@ function findCacheDir() {
   const candidates = [
     path.join(__dirname, ".cache"),
     path.join(__dirname, "..", "bin", ".cache"),
-    path.join(__dirname, "..", "..", "..", "tools")
+    path.join(__dirname, "..", "..", "..", "tools"),
   ];
-  // Pick the first candidate that has any of the expected tools — different
+  // Pick the first candidate that has any of the expected tools, different
   // commands need different binaries (build needs extism-js, test needs
   // owncast-plugin-test) but they share a cache.
   for (const c of candidates) {
@@ -342,4 +387,3 @@ function findCacheDir() {
   }
   return candidates[0];
 }
-

package/index.d.ts

@@ -6,7 +6,7 @@ export interface ChatMessage {
   timestamp: string;
 }
 
-/** A chat user — payload of join/part/rename events. */
+/** A chat user, payload of join/part/rename events. */
 export interface ChatUser {
   id: string;
   displayName: string;
@@ -15,13 +15,13 @@ export interface ChatUser {
   scopes?: string[];
 }
 
-/** Payload of `chat.user.renamed` — the same user changing their name. */
+/** Payload of `chat.user.renamed`, the same user changing their name. */
 export interface ChatUserRename {
   user: ChatUser;
   previousName: string;
 }
 
-/** Payload of `chat.message.moderated` — a message hidden/restored by a mod. */
+/** Payload of `chat.message.moderated`, a message hidden/restored by a mod. */
 export interface ChatMessageModeration {
   messageId: string;
   visible: boolean;
@@ -30,8 +30,8 @@ export interface ChatMessageModeration {
 
 /** Stream-lifecycle payloads. */
 export interface StreamLifecycleEvent {
-  startedAt?: string;     // ISO-8601, set for stream.started
-  stoppedAt?: string;     // ISO-8601, set for stream.stopped
+  startedAt?: string; // ISO-8601, set for stream.started
+  stoppedAt?: string; // ISO-8601, set for stream.stopped
   title?: string;
   summary?: string;
 }
@@ -125,7 +125,7 @@ export const Events: {
 /** Payload shape for fediverse engagement events. */
 export interface FediverseActor {
   name: string;
-  handle: string;      // e.g. "@alice@fediverse.example"
+  handle: string; // e.g. "@alice@fediverse.example"
   url?: string;
   image?: string;
 }
@@ -136,16 +136,16 @@ export interface FediverseEngagement {
   target?: { url: string };
 }
 
-/** Inbound fediverse post — a mention or reply that contains content the
+/** Inbound fediverse post, a mention or reply that contains content the
  *  plugin can act on. Carries both the rendered content (which has the
  *  source instance's HTML) and a plain-text version (HTML stripped). */
 export interface FediverseInboundPost {
   actor: FediverseActor;
-  content: string;                 // HTML from the source instance
-  contentText: string;             // HTML stripped to plain text
-  url: string;                     // permalink to the post on its source
-  postedAt: string;                // ISO-8601
-  inReplyTo?: string;              // parent post URL, when this is a reply
+  content: string; // HTML from the source instance
+  contentText: string; // HTML stripped to plain text
+  url: string; // permalink to the post on its source
+  postedAt: string; // ISO-8601
+  inReplyTo?: string; // parent post URL, when this is a reply
   attachments?: {
     url: string;
     mediaType: string;
@@ -171,6 +171,7 @@ export const Permissions: {
   readonly HttpSSE: "http.sse";
   readonly VideoConfigRead: "videoconfig.read";
   readonly VideoConfigWrite: "videoconfig.write";
+  readonly UIModify: "ui.modify";
 };
 
 export interface BrowserPushPayload {
@@ -204,7 +205,7 @@ export interface User {
   displayName: string;
   previousNames?: string[];
   createdAt?: string;
-  disabledAt?: string;        // ISO-8601 if banned, omitted otherwise
+  disabledAt?: string; // ISO-8601 if banned, omitted otherwise
   scopes?: string[];
   isBot?: boolean;
   isAuthenticated?: boolean;
@@ -290,12 +291,12 @@ export interface PluginDef {
   onFediverseReply?(post: FediverseInboundPost): void | Promise<void>;
 
   /** HTTP request handler. Called for any path under /plugins/<name>/ that
-   *  isn't served as a static asset. Default-public — gate admin features
+   *  isn't served as a static asset. Default-public, gate admin features
    *  on `req.authenticated` yourself. Requires `http.serve` permission. */
   onHttpRequest?(req: IncomingHttpRequest): OutgoingHttpResponse;
 
   /** Handlers for plugin-emitted custom events. The key is the event type
-   *  string (e.g. "announcement.broadcast"). Notifications only — to filter
+   *  string (e.g. "announcement.broadcast"). Notifications only, to filter
    *  custom events, additional API will be needed. */
   on?: { [eventType: string]: (payload: any) => void | Promise<void> };
 
@@ -314,7 +315,7 @@ export const owncast: {
     send(text: string): void;
     /** Same identity, but in action style (italic, like IRC "/me"). */
     sendAction(text: string): void;
-    /** Post a system message — no user identity, rendered as a server
+    /** Post a system message, no user identity, rendered as a server
      *  announcement. The body is rendered as HTML, so the plugin is
      *  responsible for escaping any untrusted content. Same `chat.send`
      *  permission as the other send variants. */
@@ -348,7 +349,7 @@ export const owncast: {
     upload(name: string, data: Uint8Array | string): UploadResult | null;
   };
   /** Post to the fediverse on the streamer's behalf. Requires `fediverse.post`,
-   *  which is high-trust — admins should grant it sparingly. The host
+   *  which is high-trust, admins should grant it sparingly. The host
    *  rate-limits at ~5 posts/hour per plugin. */
   fediverse: {
     /** Publish a public, text-only post. Returns { url } on success or null
@@ -372,6 +373,22 @@ export const owncast: {
   events: {
     emit(eventType: string, payload: unknown): void;
   };
+  /** Control over the viewer action buttons this plugin contributes.
+   *  The effective list shown to viewers is `manifest.actions` ++
+   *  whatever has been added at runtime via `add`. Requires
+   *  `ui.modify`. */
+  actions: {
+    /** Append one or more buttons to the plugin's runtime list. Each
+     *  entry is validated with the same rules as `manifest.actions`
+     *  (title required; exactly one of `url` or `html`; relative URLs
+     *  rewritten into this plugin's namespace; cross-plugin URLs
+     *  rejected). The next viewer `/api/config` request returns
+     *  `manifest.actions` ++ the runtime list. */
+    add(actions: ActionButton | ActionButton[]): void;
+    /** Drop the runtime additions; only `manifest.actions` remain on
+     *  the next viewer `/api/config` request. */
+    clear(): void;
+  };
   sse: {
     /** Push one Server-Sent-Event to every browser connected to this
      *  plugin's `/plugins/<name>/_sse/<channel>` stream. `event` is the SSE
@@ -416,7 +433,7 @@ export interface HttpResponse {
   body: string;
 }
 
-/** An entry in `manifest.actions` — declares an action button the Owncast
+/** An entry in `manifest.actions`, declares an action button the Owncast
  *  UI surfaces while this plugin is enabled. Mirrors Owncast's existing
  *  ExternalAction shape; the host merges enabled-plugin buttons with the
  *  admin-configured list.
@@ -429,7 +446,7 @@ export interface HttpResponse {
  *  explicit `/plugins/<your-name>/...` paths are accepted unchanged.
  *
  *  When the resolved URL points back into this plugin, the manifest must
- *  declare `http.serve` — the host rejects the load otherwise. */
+ *  declare `http.serve`, the host rejects the load otherwise. */
 export interface ActionButton {
   /** Button label. Required. */
   title: string;
@@ -437,7 +454,7 @@ export interface ActionButton {
   url?: string;
   /** Render this raw HTML when the button is pressed. Mutually exclusive with `url`. */
   html?: string;
-  /** Icon image URL — same path conventions as `url`. */
+  /** Icon image URL, same path conventions as `url`. */
   icon?: string;
   /** Accent color, e.g. "#3b82f6". */
   color?: string;
@@ -447,7 +464,7 @@ export interface ActionButton {
   openExternally?: boolean;
 }
 
-/** `manifest.network` — narrows outbound HTTP scope for plugins that
+/** `manifest.network`, narrows outbound HTTP scope for plugins that
  *  declare the `network.fetch` permission. Required when that permission
  *  is granted; the host rejects loads otherwise. */
 export interface NetworkConfig {

package/index.js

@@ -10,45 +10,46 @@ let registered = null;
 const FilterAction = Object.freeze({
   Pass: "pass",
   Modify: "modify",
-  Drop: "drop"
+  Drop: "drop",
 });
 
 const Events = Object.freeze({
   // Chat events
-  ChatMessageReceived:  "chat.message.received",
-  ChatUserJoined:       "chat.user.joined",
-  ChatUserParted:       "chat.user.parted",
-  ChatUserRenamed:      "chat.user.renamed",
+  ChatMessageReceived: "chat.message.received",
+  ChatUserJoined: "chat.user.joined",
+  ChatUserParted: "chat.user.parted",
+  ChatUserRenamed: "chat.user.renamed",
   ChatMessageModerated: "chat.message.moderated",
   // Stream lifecycle
-  StreamStarted:        "stream.started",
-  StreamStopped:        "stream.stopped",
-  StreamTitleChanged:   "stream.title.changed",
-  // Fediverse — engagement (metadata only) + inbound posts (with content)
-  FediverseFollow:      "fediverse.follow",
-  FediverseLike:        "fediverse.like",
-  FediverseRepost:      "fediverse.repost",
-  FediverseMention:     "fediverse.mention",
-  FediverseReply:       "fediverse.reply"
+  StreamStarted: "stream.started",
+  StreamStopped: "stream.stopped",
+  StreamTitleChanged: "stream.title.changed",
+  // Fediverse, engagement (metadata only) + inbound posts (with content)
+  FediverseFollow: "fediverse.follow",
+  FediverseLike: "fediverse.like",
+  FediverseRepost: "fediverse.repost",
+  FediverseMention: "fediverse.mention",
+  FediverseReply: "fediverse.reply",
 });
 
 const Permissions = Object.freeze({
-  ChatSend:          "chat.send",
-  ChatHistory:       "chat.history",
-  ChatModerate:      "chat.moderate",
-  StorageKV:         "storage.kv",
-  StorageUpload:     "storage.upload",
-  EventsEmit:        "events.emit",
-  NetworkFetch:      "network.fetch",
-  HttpServe:         "http.serve",
-  ServerRead:        "server.read",
+  ChatSend: "chat.send",
+  ChatHistory: "chat.history",
+  ChatModerate: "chat.moderate",
+  StorageKV: "storage.kv",
+  StorageUpload: "storage.upload",
+  EventsEmit: "events.emit",
+  NetworkFetch: "network.fetch",
+  HttpServe: "http.serve",
+  ServerRead: "server.read",
   NotificationsSend: "notifications.send",
-  UsersRead:         "users.read",
-  UsersModerate:     "users.moderate",
-  FediversePost:     "fediverse.post",
-  HttpSSE:           "http.sse",
-  VideoConfigRead:   "videoconfig.read",
-  VideoConfigWrite:  "videoconfig.write"
+  UsersRead: "users.read",
+  UsersModerate: "users.moderate",
+  FediversePost: "fediverse.post",
+  HttpSSE: "http.sse",
+  VideoConfigRead: "videoconfig.read",
+  VideoConfigWrite: "videoconfig.write",
+  UIModify: "ui.modify",
 });
 
 const filter = Object.freeze({
@@ -60,14 +61,14 @@ const filter = Object.freeze({
   },
   drop(reason) {
     return { action: FilterAction.Drop, reason: reason || "" };
-  }
+  },
 });
 
 // Distinguishes notification handlers from filter handlers in the HANDLERS
-// map below. Internal — not part of the public API.
+// map below. Internal, not part of the public API.
 const HandlerKind = Object.freeze({
   Notify: "notify",
-  Filter: "filter"
+  Filter: "filter",
 });
 
 // Maps a built-in handler method name to the event type it subscribes to and
@@ -75,30 +76,54 @@ const HandlerKind = Object.freeze({
 // new built-in Owncast events.
 const HANDLERS = Object.freeze({
   // Chat
-  onChatMessage:        { event: Events.ChatMessageReceived,  kind: HandlerKind.Notify },
-  filterChatMessage:    { event: Events.ChatMessageReceived,  kind: HandlerKind.Filter },
-  onChatUserJoined:     { event: Events.ChatUserJoined,       kind: HandlerKind.Notify },
-  onChatUserParted:     { event: Events.ChatUserParted,       kind: HandlerKind.Notify },
-  onChatUserRenamed:    { event: Events.ChatUserRenamed,      kind: HandlerKind.Notify },
-  onMessageModerated:   { event: Events.ChatMessageModerated, kind: HandlerKind.Notify },
+  onChatMessage: {
+    event: Events.ChatMessageReceived,
+    kind: HandlerKind.Notify,
+  },
+  filterChatMessage: {
+    event: Events.ChatMessageReceived,
+    kind: HandlerKind.Filter,
+  },
+  onChatUserJoined: { event: Events.ChatUserJoined, kind: HandlerKind.Notify },
+  onChatUserParted: { event: Events.ChatUserParted, kind: HandlerKind.Notify },
+  onChatUserRenamed: {
+    event: Events.ChatUserRenamed,
+    kind: HandlerKind.Notify,
+  },
+  onMessageModerated: {
+    event: Events.ChatMessageModerated,
+    kind: HandlerKind.Notify,
+  },
   // Stream lifecycle
-  onStreamStarted:      { event: Events.StreamStarted,        kind: HandlerKind.Notify },
-  onStreamStopped:      { event: Events.StreamStopped,        kind: HandlerKind.Notify },
-  onStreamTitleChanged: { event: Events.StreamTitleChanged,   kind: HandlerKind.Notify },
+  onStreamStarted: { event: Events.StreamStarted, kind: HandlerKind.Notify },
+  onStreamStopped: { event: Events.StreamStopped, kind: HandlerKind.Notify },
+  onStreamTitleChanged: {
+    event: Events.StreamTitleChanged,
+    kind: HandlerKind.Notify,
+  },
   // Fediverse engagement (actor + target metadata)
-  onFediverseFollow:    { event: Events.FediverseFollow,      kind: HandlerKind.Notify },
-  onFediverseLike:      { event: Events.FediverseLike,        kind: HandlerKind.Notify },
-  onFediverseRepost:    { event: Events.FediverseRepost,      kind: HandlerKind.Notify },
+  onFediverseFollow: {
+    event: Events.FediverseFollow,
+    kind: HandlerKind.Notify,
+  },
+  onFediverseLike: { event: Events.FediverseLike, kind: HandlerKind.Notify },
+  onFediverseRepost: {
+    event: Events.FediverseRepost,
+    kind: HandlerKind.Notify,
+  },
   // Fediverse inbound posts (with content)
-  onFediverseMention:   { event: Events.FediverseMention,     kind: HandlerKind.Notify },
-  onFediverseReply:     { event: Events.FediverseReply,       kind: HandlerKind.Notify }
+  onFediverseMention: {
+    event: Events.FediverseMention,
+    kind: HandlerKind.Notify,
+  },
+  onFediverseReply: { event: Events.FediverseReply, kind: HandlerKind.Notify },
 });
 
 // typeof comparisons in well-known categories. JS guarantees these strings,
 // but we go through named constants so a stray typo can't pass silently.
 const JsType = Object.freeze({
   Function: "function",
-  Object: "object"
+  Object: "object",
 });
 const isFn = (x) => typeof x === JsType.Function;
 const isObj = (x) => x !== null && typeof x === JsType.Object;
@@ -115,7 +140,10 @@ function describeSubscriptions() {
   const notify = [];
   const filterSubs = [];
   if (registered) {
-    const priority = typeof registered.filterPriority === "number" ? registered.filterPriority : 100;
+    const priority =
+      typeof registered.filterPriority === "number"
+        ? registered.filterPriority
+        : 100;
     for (const [method, info] of Object.entries(HANDLERS)) {
       if (!isFn(registered[method])) continue;
       if (info.kind === HandlerKind.Notify) {
@@ -137,7 +165,11 @@ function dispatchEvent(envelope) {
   if (!registered) return;
   const { eventType, payload } = envelope;
   for (const [method, info] of Object.entries(HANDLERS)) {
-    if (info.kind === HandlerKind.Notify && info.event === eventType && isFn(registered[method])) {
+    if (
+      info.kind === HandlerKind.Notify &&
+      info.event === eventType &&
+      isFn(registered[method])
+    ) {
       registered[method](payload);
       return;
     }
@@ -151,7 +183,11 @@ function dispatchFilter(envelope) {
   if (!registered) return filter.pass();
   const { eventType, payload } = envelope;
   for (const [method, info] of Object.entries(HANDLERS)) {
-    if (info.kind === HandlerKind.Filter && info.event === eventType && isFn(registered[method])) {
+    if (
+      info.kind === HandlerKind.Filter &&
+      info.event === eventType &&
+      isFn(registered[method])
+    ) {
       return registered[method](payload) || filter.pass();
     }
   }
@@ -169,101 +205,140 @@ function dispatchHttp(request) {
   return {
     status: out.status || 200,
     headers: out.headers || {},
-    body: out.body == null ? "" : String(out.body)
+    body: out.body == null ? "" : String(out.body),
   };
 }
 
+// permError builds an actionable Error and logs it to stderr (which the
+// host runtime captures), so a plugin author running `owncast-plugin
+// serve` or hitting the host's logs sees exactly which permission to
+// add to their manifest. apiName is the SDK call the author wrote
+// (e.g. "owncast.actions.set"); perm is the manifest permission string.
+function permError(apiName, perm) {
+  const msg = `${apiName} requires the '${perm}' permission. Add it to your plugin.manifest.json's "permissions" array.`;
+  console.error(`[owncast-plugin] ${msg}`);
+  return new Error(msg);
+}
+
 const owncast = {
   chat: {
     send(text) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat) throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      if (!fns.owncast_send_chat)
+        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
       fns.owncast_send_chat(Memory.fromString(text).offset);
     },
     sendAction(text) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_action) throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      if (!fns.owncast_send_chat_action)
+        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
       fns.owncast_send_chat_action(Memory.fromString(text).offset);
     },
     system(body) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_system) throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      if (!fns.owncast_send_chat_system)
+        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
       fns.owncast_send_chat_system(Memory.fromString(body).offset);
     },
     history(limit) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_chat_history) throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
+      if (!fns.owncast_chat_history)
+        throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
       const offset = fns.owncast_chat_history(limit || 0);
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     deleteMessage(messageId) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_delete_message) throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
+      if (!fns.owncast_delete_message)
+        throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
       fns.owncast_delete_message(Memory.fromString(String(messageId)).offset);
     },
     kick(clientId) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_kick_client) throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
+      if (!fns.owncast_kick_client)
+        throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
       fns.owncast_kick_client(BigInt(clientId));
     },
     sendTo(clientId, text) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_to) throw new Error(`permission '${Permissions.ChatSend}' not granted`);
-      fns.owncast_send_chat_to(BigInt(clientId), Memory.fromString(text).offset);
+      if (!fns.owncast_send_chat_to)
+        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      fns.owncast_send_chat_to(
+        BigInt(clientId),
+        Memory.fromString(text).offset,
+      );
     },
     clients() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_chat_clients) throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
+      if (!fns.owncast_chat_clients)
+        throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
       const offset = fns.owncast_chat_clients();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
-    }
+    },
   },
   users: {
     list() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_users_list) throw new Error(`permission '${Permissions.UsersRead}' not granted`);
+      if (!fns.owncast_users_list)
+        throw new Error(`permission '${Permissions.UsersRead}' not granted`);
       const offset = fns.owncast_users_list();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     get(id) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_user_get) throw new Error(`permission '${Permissions.UsersRead}' not granted`);
+      if (!fns.owncast_user_get)
+        throw new Error(`permission '${Permissions.UsersRead}' not granted`);
       const offset = fns.owncast_user_get(Memory.fromString(id).offset);
       if (offset == 0) return null;
       return JSON.parse(Memory.find(offset).readString());
     },
     setEnabled(id, enabled, reason) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_user_set_enabled) throw new Error(`permission '${Permissions.UsersModerate}' not granted`);
+      if (!fns.owncast_user_set_enabled)
+        throw new Error(
+          `permission '${Permissions.UsersModerate}' not granted`,
+        );
       fns.owncast_user_set_enabled(
         Memory.fromString(id).offset,
         enabled ? 1 : 0,
-        Memory.fromString(reason || "").offset
+        Memory.fromString(reason || "").offset,
       );
     },
     banIP(ip) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_ban_ip) throw new Error(`permission '${Permissions.UsersModerate}' not granted`);
+      if (!fns.owncast_ban_ip)
+        throw new Error(
+          `permission '${Permissions.UsersModerate}' not granted`,
+        );
       fns.owncast_ban_ip(Memory.fromString(ip).offset);
-    }
+    },
   },
   storage: {
     upload(name, data) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_storage_upload) throw new Error(`permission '${Permissions.StorageUpload}' not granted`);
-      const dataMem = data instanceof Uint8Array
-        ? Memory.fromBuffer(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength))
-        : Memory.fromString(String(data));
+      if (!fns.owncast_storage_upload)
+        throw new Error(
+          `permission '${Permissions.StorageUpload}' not granted`,
+        );
+      const dataMem =
+        data instanceof Uint8Array
+          ? Memory.fromBuffer(
+              data.buffer.slice(
+                data.byteOffset,
+                data.byteOffset + data.byteLength,
+              ),
+            )
+          : Memory.fromString(String(data));
       const offset = fns.owncast_storage_upload(
         Memory.fromString(name).offset,
-        dataMem.offset
+        dataMem.offset,
       );
       if (offset == 0) return null;
       return JSON.parse(Memory.find(offset).readString());
-    }
+    },
   },
   fediverse: {
     /** Publish a public text-only post to the fediverse on the streamer's
@@ -271,82 +346,107 @@ const owncast = {
      *  disabled by admin, etc.). Requires `fediverse.post`. */
     post(text) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_fediverse_post) throw new Error(`permission '${Permissions.FediversePost}' not granted`);
+      if (!fns.owncast_fediverse_post)
+        throw new Error(
+          `permission '${Permissions.FediversePost}' not granted`,
+        );
       const offset = fns.owncast_fediverse_post(Memory.fromString(text).offset);
       if (offset == 0) return null;
       return JSON.parse(Memory.find(offset).readString());
-    }
+    },
   },
   notifications: {
     discord(text) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_notify_discord) throw new Error(`permission '${Permissions.NotificationsSend}' not granted`);
+      if (!fns.owncast_notify_discord)
+        throw new Error(
+          `permission '${Permissions.NotificationsSend}' not granted`,
+        );
       fns.owncast_notify_discord(Memory.fromString(text).offset);
     },
     browserPush(payload) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_notify_browser_push) throw new Error(`permission '${Permissions.NotificationsSend}' not granted`);
+      if (!fns.owncast_notify_browser_push)
+        throw new Error(
+          `permission '${Permissions.NotificationsSend}' not granted`,
+        );
       const obj = typeof payload === "string" ? { title: payload } : payload;
-      fns.owncast_notify_browser_push(Memory.fromString(JSON.stringify(obj)).offset);
+      fns.owncast_notify_browser_push(
+        Memory.fromString(JSON.stringify(obj)).offset,
+      );
     },
     fediverse(payload) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_notify_fediverse) throw new Error(`permission '${Permissions.NotificationsSend}' not granted`);
-      fns.owncast_notify_fediverse(Memory.fromString(JSON.stringify(payload)).offset);
-    }
+      if (!fns.owncast_notify_fediverse)
+        throw new Error(
+          `permission '${Permissions.NotificationsSend}' not granted`,
+        );
+      fns.owncast_notify_fediverse(
+        Memory.fromString(JSON.stringify(payload)).offset,
+      );
+    },
   },
   stream: {
     current() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_stream_current) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_stream_current)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_stream_current();
       if (offset == 0) return { online: false, viewers: 0 };
       return JSON.parse(Memory.find(offset).readString());
     },
     broadcaster() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_stream_broadcaster) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_stream_broadcaster)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_stream_broadcaster();
       if (offset == 0) return {};
       return JSON.parse(Memory.find(offset).readString());
-    }
+    },
   },
   server: {
     info() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_server_info) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_server_info)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_server_info();
       if (offset == 0) return {};
       return JSON.parse(Memory.find(offset).readString());
     },
     socials() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_server_socials) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_server_socials)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_server_socials();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     federation() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_server_federation) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_server_federation)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_server_federation();
       if (offset == 0) return { enabled: false };
       return JSON.parse(Memory.find(offset).readString());
     },
     tags() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_server_tags) throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      if (!fns.owncast_server_tags)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
       const offset = fns.owncast_server_tags();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
-    }
+    },
   },
   videoConfig: {
     /** Read the current video/transcoding config: { latencyLevel, codec,
      *  variants }. Requires `videoconfig.read`. */
     read() {
       const fns = Host.getFunctions();
-      if (!fns.owncast_video_config_read) throw new Error(`permission '${Permissions.VideoConfigRead}' not granted`);
+      if (!fns.owncast_video_config_read)
+        throw new Error(
+          `permission '${Permissions.VideoConfigRead}' not granted`,
+        );
       const offset = fns.owncast_video_config_read();
       if (offset == 0) return { latencyLevel: 0, codec: "", variants: [] };
       return JSON.parse(Memory.find(offset).readString());
@@ -356,39 +456,73 @@ const owncast = {
      *  rejects the config. Requires `videoconfig.write`. */
     write(config) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_video_config_write) throw new Error(`permission '${Permissions.VideoConfigWrite}' not granted`);
-      const offset = fns.owncast_video_config_write(Memory.fromString(JSON.stringify(config || {})).offset);
-      if (offset == 0) throw new Error('videoConfig.write failed');
+      if (!fns.owncast_video_config_write)
+        throw new Error(
+          `permission '${Permissions.VideoConfigWrite}' not granted`,
+        );
+      const offset = fns.owncast_video_config_write(
+        Memory.fromString(JSON.stringify(config || {})).offset,
+      );
+      if (offset == 0) throw new Error("videoConfig.write failed");
       const result = JSON.parse(Memory.find(offset).readString());
-      if (!result.ok) throw new Error(result.error || 'videoConfig.write failed');
-    }
+      if (!result.ok)
+        throw new Error(result.error || "videoConfig.write failed");
+    },
   },
   kv: {
     get(key) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_kv_get) throw new Error(`permission '${Permissions.StorageKV}' not granted`);
+      if (!fns.owncast_kv_get)
+        throw new Error(`permission '${Permissions.StorageKV}' not granted`);
       const offset = fns.owncast_kv_get(Memory.fromString(key).offset);
       if (offset == 0) return null;
       return Memory.find(offset).readString();
     },
     set(key, value) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_kv_set) throw new Error(`permission '${Permissions.StorageKV}' not granted`);
+      if (!fns.owncast_kv_set)
+        throw new Error(`permission '${Permissions.StorageKV}' not granted`);
       fns.owncast_kv_set(
         Memory.fromString(key).offset,
-        Memory.fromString(String(value)).offset
+        Memory.fromString(String(value)).offset,
       );
-    }
+    },
   },
   events: {
     emit(eventType, payload) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_emit_event) throw new Error(`permission '${Permissions.EventsEmit}' not granted`);
+      if (!fns.owncast_emit_event)
+        throw new Error(`permission '${Permissions.EventsEmit}' not granted`);
       fns.owncast_emit_event(
         Memory.fromString(eventType).offset,
-        Memory.fromString(JSON.stringify(payload)).offset
+        Memory.fromString(JSON.stringify(payload)).offset,
       );
-    }
+    },
+  },
+  actions: {
+    // Append one or more action buttons to the plugin's effective list
+    // (manifest.actions ++ runtime additions). Accepts a single button
+    // object or an array. The host validates each entry (title
+    // required, exactly one of url/html, relative URLs rewritten into
+    // this plugin's namespace, cross-plugin URLs rejected) and persists
+    // the result, so the next /api/config request returns the longer
+    // list. Requires 'ui.modify'.
+    add(actions) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_add_actions)
+        throw permError("owncast.actions.add", Permissions.UIModify);
+      const list = Array.isArray(actions) ? actions : [actions];
+      fns.owncast_add_actions(Memory.fromString(JSON.stringify(list)).offset);
+    },
+    // Drop the runtime additions so only manifest.actions remain in
+    // the effective list on the next /api/config request. Requires
+    // 'ui.modify'.
+    clear() {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_clear_actions)
+        throw permError("owncast.actions.clear", Permissions.UIModify);
+      fns.owncast_clear_actions();
+    },
   },
   sse: {
     // send(channel, event, data) pushes one Server-Sent-Event to every
@@ -401,14 +535,15 @@ const owncast = {
     // the 'http.sse' permission.
     send(channel, event, data) {
       const fns = Host.getFunctions();
-      if (!fns.owncast_sse_send) throw new Error(`permission '${Permissions.HttpSSE}' not granted`);
+      if (!fns.owncast_sse_send)
+        throw new Error(`permission '${Permissions.HttpSSE}' not granted`);
       const payload = typeof data === "string" ? data : JSON.stringify(data);
       fns.owncast_sse_send(
         Memory.fromString(channel || "").offset,
         Memory.fromString(event || "").offset,
-        Memory.fromString(payload).offset
+        Memory.fromString(payload).offset,
       );
-    }
+    },
   },
   http: {
     // fetch(url, opts) → { status, headers, body }
@@ -420,13 +555,17 @@ const owncast = {
       const req = {
         url,
         method: opts.method || "GET",
-        headers: opts.headers || {}
+        headers: opts.headers || {},
       };
       const body = opts.body != null ? String(opts.body) : null;
       const res = body != null ? Http.request(req, body) : Http.request(req);
-      return { status: res.status, headers: res.headers || {}, body: res.body || "" };
-    }
-  }
+      return {
+        status: res.status,
+        headers: res.headers || {},
+        body: res.body || "",
+      };
+    },
+  },
 };
 
 module.exports = {
@@ -439,5 +578,5 @@ module.exports = {
   describeSubscriptions,
   dispatchEvent,
   dispatchFilter,
-  dispatchHttp
+  dispatchHttp,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owncast/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",
@@ -28,6 +28,7 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "testing.js",
     "bin/owncast-plugin.js",
     "scripts/postinstall.js"
   ],
@@ -44,4 +45,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/scripts/postinstall.js

@@ -2,13 +2,13 @@
 // Downloads per-platform tooling into <sdk>/bin/.cache so the build CLI
 // finds it without polluting the user's system:
 //
-//   - extism-js                  — JS → wasm compiler (extism/js-pdk releases)
-//   - wasm-merge, wasm-opt, lib  — binaryen post-processing (WebAssembly/binaryen releases)
-//   - owncast-plugin-test/serve  — scenario runner + dev server (this repo's releases)
+//   - extism-js                 , JS → wasm compiler (extism/js-pdk releases)
+//   - wasm-merge, wasm-opt, lib , binaryen post-processing (WebAssembly/binaryen releases)
+//   - owncast-plugin-test/serve , scenario runner + dev server (this repo's releases)
 //
 // PoC scope: linux-x86_64 + darwin-arm64 + darwin-x86_64 covered.
 // owncast-plugin-test/serve downloads gracefully skip if the matching
-// release asset isn't published yet — dev builds can substitute their own
+// release asset isn't published yet, dev builds can substitute their own
 // via tools/bootstrap.sh.
 
 const fs = require("fs");
@@ -41,7 +41,7 @@ function extismJsURL() {
     "linux-x86_64": `extism-js-x86_64-linux-${EXTISM_JS_VERSION}.gz`,
     "linux-aarch64": `extism-js-aarch64-linux-${EXTISM_JS_VERSION}.gz`,
     "darwin-x86_64": `extism-js-x86_64-macos-${EXTISM_JS_VERSION}.gz`,
-    "darwin-arm64": `extism-js-aarch64-macos-${EXTISM_JS_VERSION}.gz`
+    "darwin-arm64": `extism-js-aarch64-macos-${EXTISM_JS_VERSION}.gz`,
   };
   const file = map[platformKey()];
   return `https://github.com/extism/js-pdk/releases/download/${EXTISM_JS_VERSION}/${file}`;
@@ -52,7 +52,7 @@ function binaryenURL() {
     "linux-x86_64": `binaryen-${BINARYEN_VERSION}-x86_64-linux.tar.gz`,
     "linux-aarch64": `binaryen-${BINARYEN_VERSION}-aarch64-linux.tar.gz`,
     "darwin-x86_64": `binaryen-${BINARYEN_VERSION}-x86_64-macos.tar.gz`,
-    "darwin-arm64": `binaryen-${BINARYEN_VERSION}-arm64-macos.tar.gz`
+    "darwin-arm64": `binaryen-${BINARYEN_VERSION}-arm64-macos.tar.gz`,
   };
   const file = map[platformKey()];
   return `https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/${file}`;
@@ -65,7 +65,7 @@ function hostBinaryURL(name) {
     "linux-x86_64": "linux-amd64",
     "linux-aarch64": "linux-arm64",
     "darwin-x86_64": "darwin-amd64",
-    "darwin-arm64": "darwin-arm64"
+    "darwin-arm64": "darwin-arm64",
   };
   const suffix = map[platformKey()];
   return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${HOST_BINARIES_VERSION}/${name}-${suffix}`;
@@ -75,8 +75,10 @@ function download(url, dest) {
   return new Promise((resolve, reject) => {
     const req = (u) =>
       https.get(u, (res) => {
-        if (res.statusCode === 302 || res.statusCode === 301) return req(res.headers.location);
-        if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+        if (res.statusCode === 302 || res.statusCode === 301)
+          return req(res.headers.location);
+        if (res.statusCode !== 200)
+          return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
         const out = fs.createWriteStream(dest);
         res.pipe(out);
         out.on("finish", () => out.close(resolve));
@@ -113,7 +115,7 @@ async function main() {
     fs.copyFileSync(path.join(extracted, "bin", "wasm-opt"), wasmOptDest);
     fs.chmodSync(wasmMergeDest, 0o755);
     fs.chmodSync(wasmOptDest, 0o755);
-    // copy lib too — wasm-opt links against libbinaryen.so on linux
+    // copy lib too, wasm-opt links against libbinaryen.so on linux
     const libSrc = path.join(extracted, "lib");
     if (fs.existsSync(libSrc)) {
       fs.cpSync(libSrc, path.join(cacheDir, "lib"), { recursive: true });
@@ -122,7 +124,7 @@ async function main() {
     fs.unlinkSync(tar);
   }
 
-  // owncast-plugin-test + owncast-plugin-serve — built from this repo's
+  // owncast-plugin-test + owncast-plugin-serve, built from this repo's
   // host-runtime/ Go sources, published as gzipped release assets on
   // github.com/owncast/plugin-sdk (roughly halves the download). Skip silently
   // if the release doesn't exist yet (dev environments running against a
@@ -133,7 +135,9 @@ async function main() {
     if (fs.existsSync(dest)) continue;
     const gz = dest + ".gz";
     try {
-      console.log(`[plugin-sdk] downloading ${binary} ${HOST_BINARIES_VERSION}...`);
+      console.log(
+        `[plugin-sdk] downloading ${binary} ${HOST_BINARIES_VERSION}...`,
+      );
       await download(hostBinaryURL(binary) + ".gz", gz);
       fs.writeFileSync(dest, zlib.gunzipSync(fs.readFileSync(gz)));
       fs.chmodSync(dest, 0o755);
@@ -143,7 +147,7 @@ async function main() {
       // warning so the user sees them but the install still succeeds.
       console.warn(
         `[plugin-sdk] could not fetch ${binary}: ${e.message}\n` +
-        `  Build locally via tools/bootstrap.sh, or use the latest GitHub release.`
+          `  Build locally via tools/bootstrap.sh, or use the latest GitHub release.`,
       );
       // Make sure no partial files are left behind.
       for (const p of [gz, dest]) if (fs.existsSync(p)) fs.unlinkSync(p);

package/testing.js

@@ -0,0 +1,124 @@
+// JavaScript test API for Owncast plugins.
+//
+// Lets authors write their __tests__/*.test.js with the full ergonomics of JS
+//, loops, helpers, fixtures, computed payloads, shared setup, instead of
+// hand-authoring static JSON. Each call to `runScenarios([...])` invokes the
+// same `owncast-plugin-test` host binary the JSON scenarios use, so this is
+// purely a more pleasant authoring layer over the same execution.
+//
+// Quick start:
+//
+//   const { runScenarios } = require("@owncast/plugin-sdk/testing");
+//
+//   const chat = (user, body) => ({
+//     event: "chat.message.received",
+//     payload: { id: "1", user, body, timestamp: "2024-01-01T00:00:00Z" },
+//   });
+//
+//   runScenarios([
+//     { name: "greets users",   events: [chat("alice", "hi")],   expect: { chatSends: ["hello, alice!"] } },
+//     { name: "ignores others", events: [chat("bob", "morning")], expect: { chatSends: [] } },
+//   ]);
+//
+// Each scenario object has the same shape as a JSON scenario file:
+//   { name, given?, events: [...], expect?: {...} }
+// See the Plugin Author Guide for every assertion field.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+// Find the directory holding the owncast-plugin-test binary. Check for that
+// binary specifically (not just any toolchain file) so we correctly fall
+// through to the dev tools/ dir when postinstall has only fetched part of the
+// toolchain (e.g., on a not-yet-released SDK version).
+function findCacheDir() {
+  const candidates = [
+    path.join(__dirname, "bin", ".cache"), // installed under node_modules
+    path.join(__dirname, "..", "..", "tools"), // dev fallback (repo root tools/)
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "owncast-plugin-test"))) return c;
+  }
+  return candidates[0];
+}
+
+/**
+ * Run an array of scenarios against the loaded plugin via the
+ * `owncast-plugin-test` host binary.
+ *
+ * The binary takes a project directory and auto-discovers
+ * `__tests__/*.test.json`. To avoid colliding with any JSON scenarios you
+ * might also have in the project, this function sets up a temporary project
+ * dir that links to your manifest + wasm and contains only the generated
+ * scenarios it's running.
+ *
+ * Exits the process with status 0 if every scenario passed, non-zero otherwise.
+ *
+ * @param {Array<object>} scenarios, scenario objects: { name, given?, events, expect? }
+ * @param {object}        [opts]
+ * @param {string}        [opts.cwd], plugin project directory (default: process.cwd())
+ */
+function runScenarios(scenarios, opts = {}) {
+  if (!Array.isArray(scenarios) || scenarios.length === 0) {
+    console.error("runScenarios: no scenarios provided");
+    process.exit(2);
+  }
+
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+  const manifestPath = path.join(cwd, "plugin.manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`plugin.manifest.json not found in ${cwd}`);
+    process.exit(2);
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!manifest.name) {
+    console.error("manifest.name is required");
+    process.exit(2);
+  }
+  const wasmPath = path.join(cwd, `${manifest.name}.wasm`);
+  if (!fs.existsSync(wasmPath)) {
+    console.error(
+      `${manifest.name}.wasm not found at ${wasmPath}, run \`owncast-plugin build\` first`,
+    );
+    process.exit(2);
+  }
+
+  const cache = findCacheDir();
+  const bin = path.join(cache, "owncast-plugin-test");
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `owncast-plugin-test not found at ${bin}\n` +
+        `Reinstall @owncast/plugin-sdk to fetch the host toolchain (postinstall handles it).`,
+    );
+    process.exit(2);
+  }
+
+  // Build a temp project dir that links to the wasm + manifest and contains
+  // only the scenarios we're running. The binary will auto-discover them.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "owncast-plugin-test-"));
+  try {
+    fs.symlinkSync(manifestPath, path.join(tmp, "plugin.manifest.json"));
+    fs.symlinkSync(wasmPath, path.join(tmp, `${manifest.name}.wasm`));
+    fs.mkdirSync(path.join(tmp, "__tests__"));
+    fs.writeFileSync(
+      path.join(tmp, "__tests__", "scenarios.test.json"),
+      JSON.stringify(scenarios, null, 2),
+    );
+
+    const env = {
+      ...process.env,
+      LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
+    };
+    try {
+      execFileSync(bin, [tmp], { stdio: "inherit", env });
+    } catch (e) {
+      process.exit(typeof e.status === "number" ? e.status : 1);
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+module.exports = { runScenarios };