@owncast/plugin-sdk 0.2.0 → 0.3.0

package/README.md

@@ -2,19 +2,20 @@
 
 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 `npx create-owncast-plugin@latest <slug>` and the generated `package.json` already lists it as a dependency.
 
 ## Quick start
 
 ```sh
-npm create owncast-plugin my-plugin
+npx create-owncast-plugin@latest 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__/
+npm install     # postinstall fetches the per-platform wasm toolchain
+npm run build   # compiles src/plugin.js into an intermediate build artifact
+npm run package # zips manifest + wasm + assets + icon.png into 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.
+Then install `my-plugin.ocpkg` in Owncast. From the admin's **Plugins** page click **Upload plugin** and pick the file, or copy it directly to the server's `data/plugins/` directory. Toggle **Enabled** on the plugin's row to load it.
 
 ## Writing a plugin
 

package/bin/owncast-plugin.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <name>.wasm
+// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <slug>.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 package`, produce a single-file <slug>.ocpkg suitable
 //                            for distribution / installation
+//
+// "Slug" is the plugin's identifier: lowercase, hyphenated, used in
+// filenames, URL segments, and as the registry's primary key. Plugin
+// authors set the human-readable display name via `name` in their
+// manifest; if they don't set `slug`, the CLI auto-derives it from
+// `name`.
 
 const fs = require("fs");
 const path = require("path");
@@ -14,26 +20,73 @@ 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);
 }
 
+// slugPattern matches a valid plugin slug: a lowercase letter
+// followed by lowercase letters/digits/hyphens, up to 64 chars total.
+// Same shape the host + SDK + registry all validate against.
+const slugPattern = /^[a-z][a-z0-9-]{0,63}$/;
+
+// slugify mirrors the host's Go slugify: ASCII letters and digits
+// pass through lowercased; everything else collapses to a single
+// hyphen; leading and trailing hyphens are trimmed.
+// Non-ASCII names (e.g. "Café") degrade noisily (-> "caf"); plugins
+// with accented or non-Latin display names should pin `slug` in the
+// manifest instead of relying on auto-derivation.
+function slugify(input) {
+  let out = "";
+  let prevHyphen = false;
+  for (const ch of input) {
+    const code = ch.codePointAt(0);
+    let lower = ch;
+    if (code >= 65 && code <= 90) lower = String.fromCodePoint(code + 32);
+    const lc = lower.codePointAt(0);
+    if ((lc >= 97 && lc <= 122) || (lc >= 48 && lc <= 57)) {
+      out += lower;
+      prevHyphen = false;
+    } else if (!prevHyphen && out.length > 0) {
+      out += "-";
+      prevHyphen = true;
+    }
+  }
+  return out.replace(/-+$/, "");
+}
+
+// readAndResolveManifest loads plugin.manifest.json, validates the
+// required fields, and returns a manifest object with `slug` filled
+// in: either the author's explicit `slug`, or one auto-derived from
+// `name`. The returned object is what gets baked into MANIFEST_BASE
+// in the build's synthesized entry, so register() always emits both
+// name (display) and slug (identifier).
+function readAndResolveManifest(manifestPath) {
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!manifest.name || typeof manifest.name !== "string") {
+    throw new Error("manifest.name is required");
+  }
+  if (!manifest.version || typeof manifest.version !== "string") {
+    throw new Error("manifest.version is required");
+  }
+  let slug = manifest.slug;
+  if (!slug) {
+    slug = slugify(manifest.name);
+    if (!slug) {
+      throw new Error(
+        `could not derive a slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
+      );
+    }
+  }
+  if (!slugPattern.test(slug)) {
+    throw new Error(
+      `manifest.slug ${JSON.stringify(slug)} must match ${slugPattern} (lowercase letters/digits/hyphens, starting with a letter, max 64 chars)`,
+    );
+  }
+  manifest.slug = slug;
+  return manifest;
+}
+
 function testMain(args) {
   runBinary("owncast-plugin-test", args);
 }
@@ -73,9 +126,8 @@ async function buildMain() {
   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 manifest = readAndResolveManifest(manifestPath);
+  const slug = manifest.slug;
 
   // Detect entry point.
   let entry = null;
@@ -166,7 +218,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
     LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
   };
 
-  const wasmOut = path.join(cwd, `${name}.wasm`);
+  const wasmOut = path.join(cwd, `${slug}.wasm`);
   execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], {
     stdio: "inherit",
     env,
@@ -178,7 +230,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
   // 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`);
+    const assetsDest = path.join(cwd, `${slug}-assets`);
     let needsLink = true;
     // Use lstatSync (not existsSync), existsSync follows symlinks and
     // returns false for a dangling link, but the link's inode is still
@@ -222,11 +274,10 @@ async function packageMain() {
   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 manifest = readAndResolveManifest(manifestPath);
+  const slug = manifest.slug;
 
-  const wasmPath = path.join(cwd, `${name}.wasm`);
+  const wasmPath = path.join(cwd, `${slug}.wasm`);
   if (!fs.existsSync(wasmPath)) {
     await buildMain();
   }
@@ -236,6 +287,15 @@ async function packageMain() {
   zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
   zip.file("plugin.wasm", fs.readFileSync(wasmPath));
   let fileCount = 2;
+  // Bundle a top-level icon.png if the plugin source root has one.
+  // The host reads it from /api/plugins/<slug>/icon to render in the
+  // admin list and sidebar (no manifest field, no http.serve
+  // permission required).
+  const iconPath = path.join(cwd, "icon.png");
+  if (fs.existsSync(iconPath) && fs.statSync(iconPath).isFile()) {
+    zip.file("icon.png", fs.readFileSync(iconPath));
+    fileCount++;
+  }
   if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
     for (const file of walkFiles(assetsDir)) {
       const rel = path.relative(assetsDir, file).split(path.sep).join("/");
@@ -244,7 +304,7 @@ async function packageMain() {
     }
   }
 
-  const outPath = path.join(cwd, `${name}.ocpkg`);
+  const outPath = path.join(cwd, `${slug}.ocpkg`);
   const buf = await zip.generateAsync({
     type: "nodebuffer",
     compression: "DEFLATE",
@@ -387,3 +447,23 @@ function findCacheDir() {
   }
   return candidates[0];
 }
+
+// Dispatch sits at the bottom so every const + function above is
+// fully initialized before any handler runs. Calling a handler from
+// the top of the file would put the top-level `const slugPattern`
+// (and friends) in the TDZ for the first synchronous slice of
+// buildMain/packageMain.
+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);
+}

package/index.d.ts

@@ -158,6 +158,7 @@ export const Permissions: {
   readonly ChatSend: "chat.send";
   readonly ChatHistory: "chat.history";
   readonly ChatModerate: "chat.moderate";
+  readonly ChatFilter: "chat.filter";
   readonly StorageKV: "storage.kv";
   readonly StorageUpload: "storage.upload";
   readonly EventsEmit: "events.emit";
@@ -349,11 +350,13 @@ 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
-   *  rate-limits at ~5 posts/hour per plugin. */
+   *  which is high-trust (posts go out under the streamer's own handle);
+   *  admins should grant it sparingly. */
   fediverse: {
-    /** Publish a public, text-only post. Returns { url } on success or null
-     *  on rate-limit / disabled / other failure. */
+    /** Publish a public, text-only post. Returns `{ url }` (currently empty
+     *  on success: Owncast publishes the note but doesn't yet round-trip its
+     *  URL), or `null` when the host rejects the call (disabled, missing
+     *  permission, etc.). */
     post(text: string): { url: string } | null;
   };
   /** Send notifications via Owncast's configured channels.

package/index.js

@@ -36,6 +36,7 @@ const Permissions = Object.freeze({
   ChatSend: "chat.send",
   ChatHistory: "chat.history",
   ChatModerate: "chat.moderate",
+  ChatFilter: "chat.filter",
   StorageKV: "storage.kv",
   StorageUpload: "storage.upload",
   EventsEmit: "events.emit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owncast/plugin-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",

package/testing.js

@@ -33,6 +33,30 @@ const { execFileSync } = require("child_process");
 // 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).
+// slugifyForTest mirrors the slugify in the build CLI + host SDKs so
+// this entrypoint can locate the .wasm file when a manifest omits
+// `slug`. ASCII letters and digits pass through lowercased;
+// everything else collapses to a single hyphen; trailing hyphens are
+// trimmed.
+function slugifyForTest(input) {
+  let out = "";
+  let prevHyphen = false;
+  for (const ch of input) {
+    const code = ch.codePointAt(0);
+    let lower = ch;
+    if (code >= 65 && code <= 90) lower = String.fromCodePoint(code + 32);
+    const lc = lower.codePointAt(0);
+    if ((lc >= 97 && lc <= 122) || (lc >= 48 && lc <= 57)) {
+      out += lower;
+      prevHyphen = false;
+    } else if (!prevHyphen && out.length > 0) {
+      out += "-";
+      prevHyphen = true;
+    }
+  }
+  return out.replace(/-+$/, "");
+}
+
 function findCacheDir() {
   const candidates = [
     path.join(__dirname, "bin", ".cache"), // installed under node_modules
@@ -77,10 +101,20 @@ function runScenarios(scenarios, opts = {}) {
     console.error("manifest.name is required");
     process.exit(2);
   }
-  const wasmPath = path.join(cwd, `${manifest.name}.wasm`);
+  // wasm + symlink filenames key off slug (the identifier), not the
+  // display name. Derive the slug here the same way the build CLI
+  // does so this entrypoint works on manifests that omit `slug`.
+  const slug = manifest.slug || slugifyForTest(manifest.name);
+  if (!slug) {
+    console.error(
+      `could not derive slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
+    );
+    process.exit(2);
+  }
+  const wasmPath = path.join(cwd, `${slug}.wasm`);
   if (!fs.existsSync(wasmPath)) {
     console.error(
-      `${manifest.name}.wasm not found at ${wasmPath}, run \`owncast-plugin build\` first`,
+      `${slug}.wasm not found at ${wasmPath}, run \`owncast-plugin package\` first`,
     );
     process.exit(2);
   }
@@ -100,7 +134,7 @@ function runScenarios(scenarios, opts = {}) {
   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.symlinkSync(wasmPath, path.join(tmp, `${slug}.wasm`));
     fs.mkdirSync(path.join(tmp, "__tests__"));
     fs.writeFileSync(
       path.join(tmp, "__tests__", "scenarios.test.json"),