@owncast/plugin-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Gabe Kangas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @owncast/plugin-sdk
+
+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.
+
+## Quick start
+
+```sh
+npm create owncast-plugin my-plugin
+cd my-plugin
+npm install   # postinstall fetches the per-platform wasm toolchain
+npm run build # bundles src/plugin.js → my-plugin.wasm + my-plugin.ocpkg
+npm test      # runs scenarios from __tests__/
+```
+
+Then drop `my-plugin.ocpkg` into your Owncast server's `plugins/` directory and enable it from the admin.
+
+## Writing a plugin
+
+```js
+const { definePlugin, owncast, filter } = require("@owncast/plugin-sdk");
+
+module.exports = definePlugin({
+  onChatMessage(msg) {
+    owncast.chat.send(`echo: ${msg.body}`);
+  },
+
+  filterChatMessage(msg) {
+    return msg.body.includes("spam") ? filter.drop("spam") : filter.pass();
+  },
+});
+```
+
+Declare the permissions your plugin uses (`chat.send` for the example above) in `plugin.manifest.json`. The full author guide covers every event handler, host API, and the testing harness:
+
+**[→ Owncast Plugin Author Guide](https://github.com/owncast/plugin-sdk/blob/main/docs/PLUGIN_AUTHOR_GUIDE.md)**
+
+## 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.
+
+## License
+
+MIT

package/bin/owncast-plugin.js

@@ -0,0 +1,345 @@
+#!/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
+//                            for distribution / installation
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const esbuild = require("esbuild");
+const JSZip = require("jszip");
+
+const cmd = process.argv[2] || "build";
+const restArgs = process.argv.slice(3);
+
+if (cmd === "build") {
+  buildMain().catch(fail);
+} else if (cmd === "test") {
+  testMain(restArgs);
+} else if (cmd === "serve") {
+  serveMain(restArgs);
+} else if (cmd === "package") {
+  packageMain().catch(fail);
+} else {
+  console.error(`unknown command: ${cmd}\nusage: owncast-plugin <build|test|serve|package>`);
+  process.exit(1);
+}
+
+function fail(e) {
+  console.error(`${cmd} failed: ${e.message}`);
+  process.exit(1);
+}
+
+function testMain(args) {
+  runBinary("owncast-plugin-test", args);
+}
+
+function serveMain(args) {
+  runBinary("owncast-plugin-serve", args);
+}
+
+function runBinary(name, args) {
+  const cache = findCacheDir();
+  const bin = path.join(cache, name);
+  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}`
+    );
+    process.exit(1);
+  }
+  const env = {
+    ...process.env,
+    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`
+  };
+  try {
+    execFileSync(bin, args.length > 0 ? args : [process.cwd()], { stdio: "inherit", env });
+  } catch (e) {
+    process.exit(typeof e.status === "number" ? e.status : 1);
+  }
+}
+
+async function buildMain() {
+  const cwd = process.cwd();
+  const manifestPath = path.join(cwd, "plugin.manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("plugin.manifest.json not found in current directory");
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const name = manifest.name;
+  if (!name) throw new Error("manifest.name is required");
+
+  // Detect entry point.
+  let entry = null;
+  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)");
+
+  // Synthesize an entry that injects the manifest, requires user code,
+  // then re-exports the SDK runtime exports as wasm-visible exports.
+  const buildDir = path.join(cwd, ".owncast-build");
+  fs.mkdirSync(buildDir, { recursive: true });
+  const synthEntry = path.join(buildDir, "entry.js");
+  const manifestJSON = JSON.stringify(manifest);
+  // Always emit register/on_event/on_filter as wasm exports. The SDK derives
+  // subscriptions at runtime from the plugin's handler methods and merges
+  // them into the manifest returned by register(). The host then only calls
+  // on_event/on_filter for plugins actually subscribed to that event, so
+  // unused exports are harmless.
+  const entrySrc = `const sdk = require("@owncast/plugin-sdk");
+const MANIFEST_BASE = ${manifestJSON};
+require(${JSON.stringify(entry)});
+function register() {
+  const manifest = Object.assign({}, MANIFEST_BASE, { subscriptions: sdk.describeSubscriptions() });
+  Host.outputString(JSON.stringify(manifest));
+  return 0;
+}
+function on_event() {
+  const envelope = JSON.parse(Host.inputString());
+  sdk.dispatchEvent(envelope);
+  return 0;
+}
+function on_filter() {
+  const envelope = JSON.parse(Host.inputString());
+  const result = sdk.dispatchFilter(envelope);
+  Host.outputString(JSON.stringify(result));
+  return 0;
+}
+function on_http_request() {
+  const request = JSON.parse(Host.inputString());
+  const response = sdk.dispatchHttp(request);
+  Host.outputString(JSON.stringify(response));
+  return 0;
+}
+module.exports = { register, on_event, on_filter, on_http_request };
+`;
+  fs.writeFileSync(synthEntry, entrySrc);
+
+  // Bundle to a single CJS file targeting the QuickJS runtime extism-js uses.
+  const bundledJS = path.join(buildDir, "bundle.js");
+  await esbuild.build({
+    entryPoints: [synthEntry],
+    bundle: true,
+    format: "cjs",
+    platform: "neutral",
+    target: "es2020",
+    outfile: bundledJS,
+    logLevel: "warning"
+  });
+
+  // Generate index.d.ts declaring exports + host imports based on permissions.
+  const dts = path.join(buildDir, "index.d.ts");
+  fs.writeFileSync(dts, generateInterface(manifest));
+
+  // Find toolchain.
+  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`);
+  }
+  const env = {
+    ...process.env,
+    PATH: `${cache}:${process.env.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 });
+
+  // If the project ships static assets in ./assets/, mirror them to the
+  // canonical deployment layout (<name>-assets/) so plugin.Server finds them
+  // without per-deployment renames. We use a symlink so edits to assets/
+  // show up live during dev (no rebuild needed for HTML/CSS changes).
+  const assetsSrc = path.join(cwd, "assets");
+  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 {
+        fs.rmSync(assetsDest, { recursive: true, force: true });
+      }
+    }
+    if (needsLink) {
+      fs.symlinkSync(path.resolve(assetsSrc), assetsDest, "dir");
+    }
+  }
+
+  console.log(`built ${path.relative(cwd, wasmOut)}`);
+}
+
+// `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() {
+  const cwd = process.cwd();
+  const manifestPath = path.join(cwd, "plugin.manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("plugin.manifest.json not found in current directory");
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const name = manifest.name;
+  if (!name) throw new Error("manifest.name is required");
+
+  const wasmPath = path.join(cwd, `${name}.wasm`);
+  if (!fs.existsSync(wasmPath)) {
+    await buildMain();
+  }
+
+  const assetsDir = path.join(cwd, "assets");
+  const zip = new JSZip();
+  zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
+  zip.file("plugin.wasm", fs.readFileSync(wasmPath));
+  let fileCount = 2;
+  if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
+    for (const file of walkFiles(assetsDir)) {
+      const rel = path.relative(assetsDir, file).split(path.sep).join("/");
+      zip.file(`assets/${rel}`, fs.readFileSync(file));
+      fileCount++;
+    }
+  }
+
+  const outPath = path.join(cwd, `${name}.ocpkg`);
+  const buf = await zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE",
+    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)`);
+}
+
+function* walkFiles(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // Resolve symlinks so the assets/ → <name>-assets/ link the build CLI
+    // makes doesn't cause us to skip files. statSync follows.
+    const full = path.join(dir, entry.name);
+    let info;
+    try {
+      info = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (info.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (info.isFile()) {
+      yield full;
+    }
+  }
+}
+
+function generateInterface(manifest) {
+  const exports = [
+    "register(): I32",
+    "on_event(): I32",
+    "on_filter(): I32",
+    "on_http_request(): I32"
+  ];
+
+  const perms = new Set(manifest.permissions || []);
+  const imports = [];
+  if (perms.has("chat.send")) {
+    imports.push("owncast_send_chat(textPtr: PTR): void");
+    imports.push("owncast_send_chat_action(textPtr: PTR): void");
+    imports.push("owncast_send_chat_system(bodyPtr: PTR): void");
+    imports.push("owncast_send_chat_to(clientId: I64, textPtr: PTR): void");
+  }
+  if (perms.has("chat.history")) {
+    imports.push("owncast_chat_history(limit: I32): PTR");
+    imports.push("owncast_chat_clients(): PTR");
+  }
+  if (perms.has("chat.moderate")) {
+    imports.push("owncast_delete_message(idPtr: PTR): void");
+    imports.push("owncast_kick_client(clientId: I64): void");
+  }
+  if (perms.has("notifications.send")) {
+    imports.push("owncast_notify_discord(textPtr: PTR): void");
+    imports.push("owncast_notify_browser_push(payloadPtr: PTR): void");
+    imports.push("owncast_notify_fediverse(payloadPtr: PTR): void");
+  }
+  if (perms.has("users.read")) {
+    imports.push("owncast_users_list(): PTR");
+    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_ban_ip(ipPtr: PTR): void");
+  }
+  if (perms.has("storage.upload")) {
+    imports.push("owncast_storage_upload(namePtr: PTR, dataPtr: PTR): PTR");
+  }
+  if (perms.has("fediverse.post")) {
+    imports.push("owncast_fediverse_post(textPtr: PTR): PTR");
+  }
+  if (perms.has("storage.kv")) {
+    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("server.read")) {
+    imports.push("owncast_stream_current(): PTR");
+    imports.push("owncast_server_info(): PTR");
+    imports.push("owncast_server_socials(): PTR");
+    imports.push("owncast_server_federation(): PTR");
+    imports.push("owncast_stream_broadcaster(): PTR");
+    imports.push("owncast_server_tags(): PTR");
+  }
+  if (perms.has("videoconfig.read")) {
+    imports.push("owncast_video_config_read(): PTR");
+  }
+  if (perms.has("videoconfig.write")) {
+    imports.push("owncast_video_config_write(configPtr: PTR): PTR");
+  }
+
+  let out = `declare module 'main' {\n`;
+  for (const e of exports) out += `  export function ${e};\n`;
+  out += `}\n`;
+  if (imports.length > 0) {
+    out += `\ndeclare module 'extism:host' {\n  interface user {\n`;
+    for (const i of imports) out += `    ${i};\n`;
+    out += `  }\n}\n`;
+  }
+  return out;
+}
+
+function findCacheDir() {
+  // Look in node_modules/@owncast/plugin-sdk/bin/.cache (when used as a dep)
+  // and in the repo's tools/ dir (when developing). The dev candidate
+  // assumes Node resolved __dirname through any symlink to the real SDK
+  // path (sdks/js/bin/), then walks up to the repo root.
+  const candidates = [
+    path.join(__dirname, ".cache"),
+    path.join(__dirname, "..", "bin", ".cache"),
+    path.join(__dirname, "..", "..", "..", "tools")
+  ];
+  // 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) {
+    if (
+      fs.existsSync(path.join(c, "extism-js")) ||
+      fs.existsSync(path.join(c, "owncast-plugin-test")) ||
+      fs.existsSync(path.join(c, "owncast-plugin-serve"))
+    ) {
+      return c;
+    }
+  }
+  return candidates[0];
+}
+