@owncast/plugin-sdk 0.4.2 → 0.5.0

package/bin/owncast-plugin.js

@@ -202,7 +202,17 @@ function on_http_request() {
   Host.outputString(JSON.stringify(response));
   return 0;
 }
-module.exports = { register, on_event, on_filter, on_http_request };
+function on_tab_content() {
+  const req = JSON.parse(Host.inputString());
+  Host.outputString(sdk.dispatchTabContent(req));
+  return 0;
+}
+function on_page_content() {
+  const req = JSON.parse(Host.inputString());
+  Host.outputString(sdk.dispatchPageContent(req));
+  return 0;
+}
+module.exports = { register, on_event, on_filter, on_http_request, on_tab_content, on_page_content };
 `;
   fs.writeFileSync(synthEntry, entrySrc);
 
@@ -362,6 +372,8 @@ function generateInterface(manifest) {
     "on_event(): I32",
     "on_filter(): I32",
     "on_http_request(): I32",
+    "on_tab_content(): I32",
+    "on_page_content(): I32",
   ];
 
   const perms = new Set(manifest.permissions || []);
@@ -373,6 +385,8 @@ function generateInterface(manifest) {
   // Config is ambient too: a plugin reading its own manifest-declared config
   // (admin override falling back to the declared default) needs no permission.
   imports.push("owncast_config_get(keyPtr: PTR): PTR");
+  // Asset reading is ambient: a plugin reads only files it shipped itself.
+  imports.push("owncast_asset_read(pathPtr: PTR): PTR");
   if (perms.has("chat.send")) {
     imports.push("owncast_send_chat(textPtr: PTR): void");
     imports.push("owncast_send_chat_action(textPtr: PTR): void");

package/index.d.ts

@@ -284,6 +284,15 @@ export interface OutgoingHttpResponse {
   body?: string;
 }
 
+/** Request context passed to `onTabContent` and `onPageContent` handlers. */
+export interface ContentRequest {
+  /** The tab or page-content slot's slug, as declared in the manifest. */
+  slug: string;
+  /** The viewing user's chat identity, when available. Undefined for
+   *  anonymous viewers or when the host cannot resolve an identity. */
+  user?: ChatUser;
+}
+
 /** Payload for the sse.connect / sse.disconnect events. Fired when a browser
  *  opens or closes one of the plugin's `/plugins/<name>/_sse/<channel>`
  *  streams, so the plugin can track who is connected. `connectionId` is unique
@@ -353,6 +362,18 @@ export interface PluginDef {
    *  on `req.authenticated` yourself. Requires `http.serve` permission. */
   onHttpRequest?(req: IncomingHttpRequest): OutgoingHttpResponse;
 
+  /** Render HTML for a dynamic tab. Called by the host when the tab was
+   *  declared in the manifest without a static `content` file. Return the
+   *  full HTML string to inline as the tab body. `req.user` is the viewer's
+   *  chat identity when available, undefined for anonymous viewers. */
+  onTabContent?(req: ContentRequest): string;
+
+  /** Render HTML for the plugin's dynamic extraPageContent slot. Called by
+   *  the host when extraPageContent was declared without a static `content`
+   *  file. Return the full HTML string to inline into the viewer page.
+   *  `req.user` is the viewer's chat identity when available. */
+  onPageContent?(req: ContentRequest): string;
+
   /** Handlers for plugin-emitted custom events. The key is the event type
    *  string (e.g. "announcement.broadcast"). Notifications only, to filter
    *  custom events, additional API will be needed. */
@@ -523,6 +544,16 @@ export const owncast: {
      *  value. */
     get<T = unknown>(key: string, fallback?: T): T;
   };
+  /** Read files the plugin bundled in its own `assets/` directory — templates,
+   *  data files, and other bundled resources loaded at request time. Path is
+   *  relative to `assets/` and must not contain `..`. Ambient — no permission
+   *  required. */
+  assets: {
+    /** Raw bytes of the file, or `null` if not found. */
+    read(path: string): Uint8Array | null;
+    /** File contents as a UTF-8 string, or `null` if not found. */
+    readText(path: string): string | null;
+  };
   events: {
     emit(eventType: string, payload: unknown): void;
   };

package/index.js

@@ -770,6 +770,26 @@ const owncast = {
       return JSON.parse(Memory.find(offset).readString());
     },
   },
+  // Read files the plugin shipped in its own assets/ directory. Useful for
+  // templates, data files, and other bundled resources that need to be read
+  // at request time. Path is relative to assets/ and must not contain "..".
+  // Ambient — no permission required.
+  assets: {
+    // Returns a Uint8Array of the file's raw bytes, or null if not found.
+    read(path) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_asset_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return new Uint8Array(Memory.find(offset).readBytes());
+    },
+    // Returns the file contents as a UTF-8 string, or null if not found.
+    readText(path) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_asset_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return Memory.find(offset).readString();
+    },
+  },
   events: {
     emit(eventType, payload) {
       const fns = Host.getFunctions();
@@ -870,6 +890,16 @@ const owncast = {
   },
 };
 
+function dispatchTabContent(req) {
+  if (!registered || !isFn(registered.onTabContent)) return "";
+  return registered.onTabContent(req) || "";
+}
+
+function dispatchPageContent(req) {
+  if (!registered || !isFn(registered.onPageContent)) return "";
+  return registered.onPageContent(req) || "";
+}
+
 module.exports = {
   definePlugin,
   defineCommands,
@@ -882,4 +912,6 @@ module.exports = {
   dispatchEvent,
   dispatchFilter,
   dispatchHttp,
+  dispatchTabContent,
+  dispatchPageContent,
 };

package/package.json

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

package/scripts/postinstall.js

@@ -21,21 +21,71 @@ const EXTISM_JS_VERSION = "v1.6.0";
 const BINARYEN_VERSION = "version_119";
 const HOST_BINARIES_REPO = "owncast/plugin-sdk";
 
-// The host binaries (owncast-plugin-test/serve) are cut once per MINOR release
-// (a vX.Y.0 git tag); patch releases are JS-only fixes that ride on the same
-// runtime. Deriving the download tag straight from the npm version therefore
-// 404s on every patch (e.g. 0.4.1 has no v0.4.1 binaries), which silently
-// broke `npm test`. Zero the patch component so a patch release fetches its
-// minor's binaries. Override with OWNCAST_PLUGIN_HOST_BINARIES_VERSION (with or
-// without a leading "v") if you ever need a specific tag.
-function hostBinariesVersion() {
+// The host binaries (owncast-plugin-test/serve) implement the host-function
+// contract that the bundled JS runtime imports. That contract is additive
+// within a major version — host functions are only ever added, never removed or
+// renamed (a removal is a breaking change that requires a major bump) — so the
+// NEWEST published binary is compatible with every plugin runtime. We therefore
+// fetch the latest release tag rather than deriving one from the npm version.
+//
+// This keeps the binary in lockstep with `@owncast/plugin-sdk@^x` (which npm
+// already floats to the newest compatible runtime) and fixes the old "zero the
+// patch" guess: that fetched v<major>.<minor>.0, which 404'd on JS-only patches
+// and — when a host change shipped in a patch (e.g. timer support in 0.4.2) —
+// fetched a binary too old to satisfy the runtime's imports, breaking
+// `npm test`.
+//
+// Override with OWNCAST_PLUGIN_HOST_BINARIES_VERSION (with or without a leading
+// "v") to pin a specific tag, e.g. in CI or when bisecting.
+function latestReleaseTag() {
+  return new Promise((resolve, reject) => {
+    https
+      .get(
+        `https://api.github.com/repos/${HOST_BINARIES_REPO}/releases/latest`,
+        {
+          headers: {
+            "User-Agent": "owncast-plugin-sdk-postinstall",
+            Accept: "application/vnd.github+json",
+          },
+        },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(new Error(`HTTP ${res.statusCode}`));
+          }
+          let body = "";
+          res.on("data", (c) => (body += c));
+          res.on("end", () => {
+            try {
+              const tag = JSON.parse(body).tag_name;
+              if (!tag) return reject(new Error("no tag_name in response"));
+              resolve(tag);
+            } catch (err) {
+              reject(err);
+            }
+          });
+        },
+      )
+      .on("error", reject);
+  });
+}
+
+async function resolveHostBinariesVersion() {
   const override = process.env.OWNCAST_PLUGIN_HOST_BINARIES_VERSION;
-  if (override) return override.replace(/^v/, "");
-  const pkg = require("../package.json").version; // e.g. "0.4.1"
-  const [major, minor] = pkg.split(".");
-  return `${major}.${minor}.0`;
+  if (override) return override.replace(/^v/i, "");
+  try {
+    return (await latestReleaseTag()).replace(/^v/i, "");
+  } catch (e) {
+    // Offline or API error: best-effort fall back to this package's own
+    // version. The download below 404-skips gracefully if no such release.
+    const pkg = require("../package.json").version;
+    console.warn(
+      `[plugin-sdk] could not resolve latest host-binary release ` +
+        `(${e.message}); falling back to v${pkg}`,
+    );
+    return pkg;
+  }
 }
-const HOST_BINARIES_VERSION = hostBinariesVersion();
 
 const platform = process.platform;
 const arch = process.arch;
@@ -71,7 +121,7 @@ function binaryenURL() {
   return `https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/${file}`;
 }
 
-function hostBinaryURL(name) {
+function hostBinaryURL(name, version) {
   // Per-platform asset naming matches Go's GOOS-GOARCH convention so the
   // release CI can `go build` once per matrix entry without renaming.
   const map = {
@@ -81,7 +131,7 @@ function hostBinaryURL(name) {
     "darwin-arm64": "darwin-arm64",
   };
   const suffix = map[platformKey()];
-  return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${HOST_BINARIES_VERSION}/${name}-${suffix}`;
+  return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${version}/${name}-${suffix}`;
 }
 
 function download(url, dest) {
@@ -143,27 +193,33 @@ async function main() {
   // if the release doesn't exist yet (dev environments running against a
   // not-yet-released SDK version can substitute their own via
   // tools/bootstrap.sh).
-  for (const binary of ["owncast-plugin-test", "owncast-plugin-serve"]) {
-    const dest = path.join(cacheDir, binary);
-    if (fs.existsSync(dest)) continue;
-    const gz = dest + ".gz";
-    try {
-      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);
-      fs.unlinkSync(gz);
-    } catch (e) {
-      // 404 is expected before the first release; other errors get a soft
-      // 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.`,
-      );
-      // Make sure no partial files are left behind.
-      for (const p of [gz, dest]) if (fs.existsSync(p)) fs.unlinkSync(p);
+  const hostBinaries = ["owncast-plugin-test", "owncast-plugin-serve"];
+  const missing = hostBinaries.filter(
+    (b) => !fs.existsSync(path.join(cacheDir, b)),
+  );
+  if (missing.length) {
+    // Resolve the version only when something needs downloading, so a repeat
+    // install with a populated cache never hits the network.
+    const version = await resolveHostBinariesVersion();
+    for (const binary of missing) {
+      const dest = path.join(cacheDir, binary);
+      const gz = dest + ".gz";
+      try {
+        console.log(`[plugin-sdk] downloading ${binary} v${version}...`);
+        await download(hostBinaryURL(binary, version) + ".gz", gz);
+        fs.writeFileSync(dest, zlib.gunzipSync(fs.readFileSync(gz)));
+        fs.chmodSync(dest, 0o755);
+        fs.unlinkSync(gz);
+      } catch (e) {
+        // 404 is expected before the first release; other errors get a soft
+        // 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.`,
+        );
+        // Make sure no partial files are left behind.
+        for (const p of [gz, dest]) if (fs.existsSync(p)) fs.unlinkSync(p);
+      }
     }
   }