@owncast/plugin-sdk 0.4.1 → 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,10 +372,21 @@ 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 || []);
   const imports = [];
+  // Timers are ambient (no permission): the host always provides them, since
+  // a plugin can't setTimeout in the sandbox.
+  imports.push("owncast_timer_set(id: I64, delayMs: I64, repeat: I32): I32");
+  imports.push("owncast_timer_clear(id: I64): void");
+  // 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");
@@ -424,6 +445,7 @@ function generateInterface(manifest) {
     imports.push("owncast_stream_current(): PTR");
     imports.push("owncast_server_info(): PTR");
     imports.push("owncast_server_socials(): PTR");
+    imports.push("owncast_server_emotes(): PTR");
     imports.push("owncast_server_federation(): PTR");
     imports.push("owncast_stream_broadcaster(): PTR");
     imports.push("owncast_server_tags(): PTR");

package/index.d.ts

@@ -1,7 +1,18 @@
-/** Built-in chat message payload. */
+/**
+ * Built-in chat message payload (`chat.message.received` and the chat filter).
+ *
+ * `user` carries the full sender identity — use `user.id` for stable per-user
+ * state and `user.scopes` (e.g. `"MODERATOR"`) for reliable, non-spoofable
+ * moderation gating rather than matching on the display name. `clientId`
+ * identifies the originating connection; pass it to `owncast.chat.sendTo` (or
+ * `owncast.chat.replyTo(msg, …)`) to whisper a reply back to the sender.
+ *
+ * `user` is undefined for the rare message with no associated account.
+ */
 export interface ChatMessage {
   id: string;
-  user: string;
+  user?: ChatUser;
+  clientId?: number;
   body: string;
   timestamp: string;
 }
@@ -117,6 +128,7 @@ export const Events: {
   readonly StreamTitleChanged: "stream.title.changed";
   readonly SseConnect: "sse.connect";
   readonly SseDisconnect: "sse.disconnect";
+  readonly Tick: "tick";
   readonly FediverseFollow: "fediverse.follow";
   readonly FediverseLike: "fediverse.like";
   readonly FediverseRepost: "fediverse.repost";
@@ -197,6 +209,12 @@ export interface SocialHandle {
   icon?: string;
 }
 
+/** A custom chat emote from owncast.server.emotes(). */
+export interface Emote {
+  name: string; // the `:code:` chat clients substitute
+  url: string; // image the emote renders to
+}
+
 export interface FederationInfo {
   enabled: boolean;
   username?: string;
@@ -266,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
@@ -278,6 +305,12 @@ export interface SSEConnectionEvent {
   user?: ChatUser;
 }
 
+/** Payload for the once-a-second tick event (onTick). `now` is the host
+ *  wall-clock time in unix milliseconds when the tick fired. */
+export interface TickEvent {
+  now: number;
+}
+
 export interface PluginDef {
   /** Notification handler for chat messages. Fire-and-forget. */
   onChatMessage?(msg: ChatMessage): void | Promise<void>;
@@ -309,6 +342,10 @@ export interface PluginDef {
    *  the matching onSseConnect). Requires the `http.sse` permission. */
   onSseDisconnect?(event: SSEConnectionEvent): void | Promise<void>;
 
+  /** Fires once a second for periodic work. `now` is the host wall-clock time
+   *  in unix milliseconds. Defining this opts the plugin into the tick. */
+  onTick?(event: TickEvent): void | Promise<void>;
+
   /** Someone on the fediverse followed the streamer's account. */
   onFediverseFollow?(event: FediverseEngagement): void | Promise<void>;
   /** Someone on the fediverse liked a streamer post / federated stream announcement. */
@@ -325,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. */
@@ -337,6 +386,62 @@ export interface PluginDef {
 
 export function definePlugin(def: PluginDef): PluginDef;
 
+/** What a command handler receives. */
+export interface CommandContext {
+  /** The originating chat message. */
+  msg: ChatMessage;
+  /** The sender (same as `msg.user`). */
+  user?: ChatUser;
+  /** The canonical command name that matched (not the alias used). */
+  command: string;
+  /** Whitespace-split arguments after the command word. */
+  args: string[];
+  /** The raw argument string (everything after the command word, trimmed). */
+  argString: string;
+  /** Post a public reply as the plugin's chat bot. */
+  reply(text: string): void;
+  /** Whisper a reply to the sender; falls back to a public post if their
+   *  connection is unknown. */
+  replyPrivately(text: string): void;
+}
+
+/** One command in a {@link defineCommands} table. */
+export interface CommandDefinition {
+  /** Alternate names that invoke this command. */
+  aliases?: string[];
+  /** Only allow senders whose scopes include "MODERATOR". */
+  modOnly?: boolean;
+  /** Minimum milliseconds between invocations per user (clocked off
+   *  `msg.timestamp`). */
+  cooldownMs?: number;
+  /** Invoked when the command runs. */
+  run(ctx: CommandContext): void;
+  /** Invoked instead of `run` when a non-moderator calls a `modOnly` command. */
+  onDenied?(ctx: CommandContext): void;
+  /** Invoked instead of `run` when the per-user cooldown hasn't elapsed. */
+  onCooldown?(ctx: CommandContext): void;
+}
+
+export interface CommandsConfig {
+  /** Command prefix. Default `"!"`. */
+  prefix?: string;
+  /** Match command names case-sensitively. Default false. */
+  caseSensitive?: boolean;
+  commands: Record<string, CommandDefinition>;
+  /** Fallback when a prefixed message matches no command. */
+  onUnknown?(ctx: CommandContext): void;
+  /** Default denied/cooldown handlers, used when a command omits its own. */
+  onDenied?(ctx: CommandContext): void;
+  onCooldown?(ctx: CommandContext): void;
+}
+
+/** Build a chat-command router (prefix parsing, aliases, per-user cooldowns,
+ *  moderator gating). Feed the returned function a `ChatMessage`; it returns
+ *  true when the message was a command (even if gated), false otherwise. */
+export function defineCommands(
+  config: CommandsConfig,
+): (msg: ChatMessage) => boolean;
+
 /** Typed wrappers around the Owncast host. Each method throws if the
  *  corresponding permission was not declared in plugin.manifest.json. */
 export const owncast: {
@@ -350,8 +455,14 @@ export const owncast: {
      *  responsible for escaping any untrusted content. Same `chat.send`
      *  permission as the other send variants. */
     system(body: string): void;
-    /** Private message to one chat client. */
+    /** Private message to one chat client. Requires `chat.send`. */
     sendTo(clientId: number | bigint, text: string): void;
+    /** Whisper a reply back to whoever sent a chat message. Pass the
+     *  `ChatMessage` from `onChatMessage`/`filterChatMessage` (or a bare
+     *  clientId). Returns `false` if the sender's connection is unknown (no
+     *  clientId), so callers can fall back to a public `send`. Requires
+     *  `chat.send`. */
+    replyTo(msg: ChatMessage | number | bigint, text: string): boolean;
     /** Recent chat history (most recent last). Requires `chat.history`.
      *  Default limit is 50; pass a smaller number to get fewer. */
     history(limit?: number): ChatMessage[];
@@ -418,6 +529,30 @@ export const owncast: {
   kv: {
     get(key: string): string | null;
     set(key: string, value: string | number): void;
+    /** Read a JSON value, parsed. Returns `fallback` (default `undefined`)
+     *  when the key is unset or holds invalid JSON. Requires `storage.kv`. */
+    getJSON<T = unknown>(key: string, fallback?: T): T;
+    /** Store a value as JSON. Requires `storage.kv`. */
+    setJSON(key: string, value: unknown): void;
+  };
+  /** Read this plugin's admin-configurable settings, declared under
+   *  `config` in the manifest. Ambient — no permission required. */
+  config: {
+    /** The effective value of a manifest-declared config key (admin override,
+     *  else the declared default), parsed to its declared type. Returns
+     *  `fallback` (default `undefined`) for an unknown key or one with no
+     *  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;
@@ -447,6 +582,20 @@ export const owncast: {
      *  `http.sse` permission. */
     send(channel: string, event: string, data: unknown): void;
   };
+  /** Host-driven timers. The sandbox has no setTimeout; these ask the host to
+   *  call your callback back later (in this instance). No permission required.
+   *  Timers do not survive a plugin reload or host restart. */
+  timer: {
+    /** Run `fn` once after ~`ms` milliseconds. Returns an id for `clear()`.
+     *  Very small delays are clamped up by the host; throws past the
+     *  per-plugin pending-timer cap. */
+    setTimeout(fn: () => void, ms: number): number;
+    /** Run `fn` every ~`ms` milliseconds until `clear()`. The next run is
+     *  scheduled only after the previous one returns. Returns an id. */
+    setInterval(fn: () => void, ms: number): number;
+    /** Cancel a pending timeout or interval by its id. */
+    clear(id: number): void;
+  };
   http: {
     fetch(url: string, opts?: HttpRequestOpts): HttpResponse;
   };
@@ -459,6 +608,8 @@ export const owncast: {
   server: {
     info(): ServerInfo;
     socials(): SocialHandle[];
+    /** Custom chat emotes (`:code:` → image URL) configured on this server. */
+    emotes(): Emote[];
     federation(): FederationInfo;
     tags(): string[];
   };

package/index.js

@@ -7,6 +7,14 @@
 
 let registered = null;
 
+// Host-driven timers. The sandbox has no setTimeout, so owncast.timer.* asks
+// the host to schedule a callback and call back via the internal "timer.fire"
+// event. The author's callback stays here in the long-lived instance, keyed by
+// a guest-allocated id the host echoes back. State persists across calls
+// because the plugin instance is reused; timers are dropped on reload.
+let nextTimerId = 1;
+const timerCallbacks = new Map(); // id -> { fn, repeat }
+
 const FilterAction = Object.freeze({
   Pass: "pass",
   Modify: "modify",
@@ -27,6 +35,8 @@ const Events = Object.freeze({
   // SSE connection lifecycle (who connected to / left a plugin's stream)
   SseConnect: "sse.connect",
   SseDisconnect: "sse.disconnect",
+  // Once-a-second tick for periodic work (opt in by defining onTick)
+  Tick: "tick",
   // Fediverse, engagement (metadata only) + inbound posts (with content)
   FediverseFollow: "fediverse.follow",
   FediverseLike: "fediverse.like",
@@ -109,6 +119,8 @@ const HANDLERS = Object.freeze({
   // SSE connection lifecycle
   onSseConnect: { event: Events.SseConnect, kind: HandlerKind.Notify },
   onSseDisconnect: { event: Events.SseDisconnect, kind: HandlerKind.Notify },
+  // Once-a-second tick
+  onTick: { event: Events.Tick, kind: HandlerKind.Notify },
   // Fediverse engagement (actor + target metadata)
   onFediverseFollow: {
     event: Events.FediverseFollow,
@@ -141,6 +153,111 @@ function definePlugin(def) {
   return def;
 }
 
+// defineCommands builds a chat-command router so plugins stop reimplementing
+// prefix parsing, aliases, per-user cooldowns, and moderator gating. It returns
+// a function you feed a ChatMessage (from onChatMessage or filterChatMessage);
+// it parses the command and invokes the matching handler's run(ctx). The return
+// value is true when the message was a command (even if gated), false when it
+// wasn't — so a filter can drop command messages from chat:
+//
+//   const commands = defineCommands({
+//     prefix: "!",
+//     commands: {
+//       uptime: { run: (ctx) => ctx.reply("up!") },
+//       ban: { modOnly: true, cooldownMs: 5000, run: (ctx) => ctx.reply(`bye ${ctx.args[0]}`) },
+//     },
+//   });
+//   module.exports = definePlugin({
+//     onChatMessage: commands,
+//     // or, to hide command messages from chat:
+//     // filterChatMessage: (msg) => (commands(msg) ? filter.drop("command") : filter.pass()),
+//   });
+//
+// run(ctx) receives { msg, user, command, args, argString, reply, replyPrivately }.
+// reply posts publicly; replyPrivately whispers to the sender (falling back to a
+// public post if their connection is unknown). Optional hooks: per-command or
+// top-level onCooldown(ctx) / onDenied(ctx), and a top-level onUnknown(ctx).
+function defineCommands(config) {
+  config = config || {};
+  const prefix = config.prefix || "!";
+  const caseSensitive = !!config.caseSensitive;
+  const norm = (s) => (caseSensitive ? s : s.toLowerCase());
+
+  // Resolve every name and alias to its canonical command definition.
+  const table = new Map();
+  const defs = config.commands || {};
+  for (const name of Object.keys(defs)) {
+    const def = defs[name];
+    table.set(norm(name), { name, def });
+    for (const alias of def.aliases || []) table.set(norm(alias), { name, def });
+  }
+
+  // Per-(command,user) cooldown clock, in memory for the plugin's lifetime.
+  const lastRun = new Map();
+
+  return function handle(msg) {
+    const body = (msg && msg.body) || "";
+    if (!body.startsWith(prefix)) return false;
+    const rest = body.slice(prefix.length);
+    const parts = rest.split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return false;
+    const called = parts[0];
+    const args = parts.slice(1);
+    const argString = rest.slice(called.length).trim();
+
+    const ctx = {
+      msg,
+      user: msg && msg.user,
+      command: norm(called),
+      args,
+      argString,
+      reply: (text) => owncast.chat.send(text),
+      replyPrivately: (text) => {
+        if (!owncast.chat.replyTo(msg, text)) owncast.chat.send(text);
+      },
+    };
+
+    const entry = table.get(norm(called));
+    if (!entry) {
+      if (isFn(config.onUnknown)) config.onUnknown(ctx);
+      return false;
+    }
+    const { name, def } = entry;
+    ctx.command = name;
+
+    // Moderator gating: the sender's scopes must include MODERATOR.
+    if (def.modOnly) {
+      const scopes = (msg.user && msg.user.scopes) || [];
+      if (!scopes.includes("MODERATOR")) {
+        if (isFn(def.onDenied)) def.onDenied(ctx);
+        else if (isFn(config.onDenied)) config.onDenied(ctx);
+        return true; // matched a command, but the caller wasn't allowed
+      }
+    }
+
+    // Per-user cooldown, clocked off msg.timestamp so it's deterministic in
+    // tests and independent of any sandbox clock quirks.
+    const cooldownMs = def.cooldownMs || 0;
+    if (cooldownMs > 0) {
+      const userId =
+        (msg.user && msg.user.id) ||
+        (msg.clientId != null ? `c${msg.clientId}` : "anon");
+      const key = `${name}${userId}`;
+      const now = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+      const prev = lastRun.get(key);
+      if (now && prev && now - prev < cooldownMs) {
+        if (isFn(def.onCooldown)) def.onCooldown(ctx);
+        else if (isFn(config.onCooldown)) config.onCooldown(ctx);
+        return true;
+      }
+      if (now) lastRun.set(key, now);
+    }
+
+    if (isFn(def.run)) def.run(ctx);
+    return true;
+  };
+}
+
 // Used by the build-generated entry to compute subscriptions for register().
 // Filters can optionally declare a priority via definePlugin({filterPriority}),
 // applied to every filter subscription this plugin owns. Lower = earlier.
@@ -170,8 +287,20 @@ function describeSubscriptions() {
 }
 
 function dispatchEvent(envelope) {
-  if (!registered) return;
   const { eventType, payload } = envelope;
+  // Internal: a host-scheduled timer elapsed. Run the author's callback,
+  // dropping one-shot entries first so a throw still cleans up. Not routed to
+  // user handlers or the `on` map.
+  if (eventType === "timer.fire") {
+    const id = payload && payload.id;
+    const entry = timerCallbacks.get(id);
+    if (entry) {
+      if (!entry.repeat) timerCallbacks.delete(id);
+      entry.fn();
+    }
+    return;
+  }
+  if (!registered) return;
   for (const [method, info] of Object.entries(HANDLERS)) {
     if (
       info.kind === HandlerKind.Notify &&
@@ -228,6 +357,27 @@ function permError(apiName, perm) {
   return new Error(msg);
 }
 
+// scheduleTimer registers a callback and asks the host to schedule it. The id
+// is guest-allocated and echoed back on "timer.fire". Throws if the host
+// rejects the schedule (per-plugin pending-timer cap).
+function scheduleTimer(fn, ms, repeat) {
+  if (typeof fn !== "function") {
+    throw new Error("owncast.timer: callback must be a function");
+  }
+  const id = nextTimerId++;
+  const delay = Math.max(0, Math.floor(Number(ms) || 0));
+  const fns = Host.getFunctions();
+  if (!fns.owncast_timer_set) {
+    throw new Error("owncast.timer is unavailable in this host");
+  }
+  const ok = fns.owncast_timer_set(BigInt(id), BigInt(delay), repeat ? 1 : 0);
+  if (ok !== 1) {
+    throw new Error("owncast.timer: too many pending timers");
+  }
+  timerCallbacks.set(id, { fn, repeat });
+  return id;
+}
+
 const owncast = {
   chat: {
     send(text) {
@@ -277,6 +427,20 @@ const owncast = {
         Memory.fromString(text).offset,
       );
     },
+    // replyTo whispers text back to whoever sent a chat message. Pass the
+    // ChatMessage from onChatMessage/filterChatMessage (or a bare clientId).
+    // Returns true if the sender's connection was known and the reply sent,
+    // false otherwise (e.g. the message carried no clientId) — letting callers
+    // fall back to a public post.
+    replyTo(msgOrClientId, text) {
+      const clientId =
+        msgOrClientId && typeof msgOrClientId === "object"
+          ? msgOrClientId.clientId
+          : msgOrClientId;
+      if (clientId === undefined || clientId === null) return false;
+      this.sendTo(clientId, text);
+      return true;
+    },
     clients() {
       const fns = Host.getFunctions();
       if (!fns.owncast_chat_clients)
@@ -503,6 +667,14 @@ const owncast = {
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
+    emotes() {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_server_emotes)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const offset = fns.owncast_server_emotes();
+      if (offset == 0) return [];
+      return JSON.parse(Memory.find(offset).readString());
+    },
     federation() {
       const fns = Host.getFunctions();
       if (!fns.owncast_server_federation)
@@ -569,6 +741,54 @@ const owncast = {
         Memory.fromString(String(value)).offset,
       );
     },
+    // getJSON/setJSON are convenience wrappers over the string-only store, so
+    // plugins don't reimplement JSON.parse/stringify for every stored object.
+    // getJSON returns `fallback` (default undefined) when the key is unset or
+    // holds invalid JSON.
+    getJSON(key, fallback) {
+      const raw = this.get(key);
+      if (raw == null) return fallback;
+      try {
+        return JSON.parse(raw);
+      } catch (_e) {
+        return fallback;
+      }
+    },
+    setJSON(key, value) {
+      this.set(key, JSON.stringify(value));
+    },
+  },
+  config: {
+    // get returns the effective value of a manifest-declared config key (the
+    // admin-set override, else the declared default), already parsed to its
+    // declared type. Returns `fallback` (default undefined) for an unknown key
+    // or one with no value. Ambient — no permission required.
+    get(key, fallback) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_config_get(Memory.fromString(key).offset);
+      if (offset == 0) return fallback;
+      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) {
@@ -627,6 +847,26 @@ const owncast = {
       );
     },
   },
+  timer: {
+    // setTimeout(fn, ms) runs fn once after ~ms milliseconds. setInterval
+    // repeats until clear(id). The host drives the schedule (the sandbox has
+    // no setTimeout); your callback runs in this instance when it fires.
+    // Returns an id for clear(). Very small delays are clamped up by the host,
+    // and there's a per-plugin cap on pending timers (throws past it).
+    // Note: timers are in-memory and do not survive a plugin reload or a host
+    // restart. No permission required.
+    setTimeout(fn, ms) {
+      return scheduleTimer(fn, ms, false);
+    },
+    setInterval(fn, ms) {
+      return scheduleTimer(fn, ms, true);
+    },
+    clear(id) {
+      timerCallbacks.delete(id);
+      const fns = Host.getFunctions();
+      if (fns.owncast_timer_clear) fns.owncast_timer_clear(BigInt(id));
+    },
+  },
   http: {
     // fetch(url, opts) → { status, headers, body }
     // Wraps Extism's built-in Http.request. Throws if the manifest didn't
@@ -650,8 +890,19 @@ 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,
   owncast,
   filter,
   FilterAction,
@@ -661,4 +912,6 @@ module.exports = {
   dispatchEvent,
   dispatchFilter,
   dispatchHttp,
+  dispatchTabContent,
+  dispatchPageContent,
 };

package/package.json

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

package/scripts/postinstall.js

@@ -19,11 +19,74 @@ const { execFileSync } = require("child_process");
 
 const EXTISM_JS_VERSION = "v1.6.0";
 const BINARYEN_VERSION = "version_119";
-// Tracks the SDK version that the host binaries were cut for. Usually
-// matches the SDK's own version in package.json.
-const HOST_BINARIES_VERSION = require("../package.json").version;
 const HOST_BINARIES_REPO = "owncast/plugin-sdk";
 
+// 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/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 platform = process.platform;
 const arch = process.arch;
 
@@ -58,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 = {
@@ -68,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) {
@@ -130,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);
+      }
     }
   }
 

package/testing.js

@@ -78,28 +78,40 @@ function findCacheDir() {
  * 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.
+ * Sets `process.exitCode` to non-zero if any scenario failed (never resets a
+ * previously-failed code), and returns true on success / false on failure
+ * WITHOUT exiting the process. That lets one node process run several test
+ * files in a row (see runScenarioFiles); the process ends with the right code
+ * once the event loop drains.
  *
  * @param {Array<object>} scenarios, scenario objects: { name, given?, events, expect? }
  * @param {object}        [opts]
  * @param {string}        [opts.cwd], plugin project directory (default: process.cwd())
+ * @returns {boolean} true if every scenario passed
  */
+function fail(code) {
+  // Record a non-zero exit code without clobbering an earlier failure or
+  // aborting sibling test files. Returns false for `return fail(...)`.
+  if (!process.exitCode) process.exitCode = code;
+  return false;
+}
+
 function runScenarios(scenarios, opts = {}) {
   if (!Array.isArray(scenarios) || scenarios.length === 0) {
     console.error("runScenarios: no scenarios provided");
-    process.exit(2);
+    return fail(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);
+    return fail(2);
   }
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   if (!manifest.name) {
     console.error("manifest.name is required");
-    process.exit(2);
+    return fail(2);
   }
   // wasm + symlink filenames key off slug (the identifier), not the
   // display name. Derive the slug here the same way the build CLI
@@ -109,14 +121,14 @@ function runScenarios(scenarios, opts = {}) {
     console.error(
       `could not derive slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
     );
-    process.exit(2);
+    return fail(2);
   }
   const wasmPath = path.join(cwd, `${slug}.wasm`);
   if (!fs.existsSync(wasmPath)) {
     console.error(
       `${slug}.wasm not found at ${wasmPath}, run \`owncast-plugin package\` first`,
     );
-    process.exit(2);
+    return fail(2);
   }
 
   const cache = findCacheDir();
@@ -126,7 +138,7 @@ function runScenarios(scenarios, opts = {}) {
       `owncast-plugin-test not found at ${bin}\n` +
         `Reinstall @owncast/plugin-sdk to fetch the host toolchain (postinstall handles it).`,
     );
-    process.exit(2);
+    return fail(2);
   }
 
   // Build a temp project dir that links to the wasm + manifest and contains
@@ -156,11 +168,46 @@ function runScenarios(scenarios, opts = {}) {
     try {
       execFileSync(bin, [tmp], { stdio: "inherit", env });
     } catch (e) {
-      process.exit(typeof e.status === "number" ? e.status : 1);
+      return fail(typeof e.status === "number" ? e.status : 1);
     }
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
+  return true;
+}
+
+/**
+ * Discover and run every `__tests__/*.test.js` file in one node process,
+ * aggregating their exit status. Lets you organize scenarios across multiple
+ * files (by module/feature) without a shell loop spawning a process per file.
+ * Each discovered file is expected to call runScenarios() at load time.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd], plugin project directory (default: process.cwd())
+ * @returns {boolean} true if every file's scenarios passed
+ */
+function runScenarioFiles(opts = {}) {
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+  const dir = path.join(cwd, "__tests__");
+  if (!fs.existsSync(dir)) {
+    console.error(`no __tests__ directory in ${cwd}`);
+    return fail(2);
+  }
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".test.js"))
+    .sort()
+    .map((f) => path.join(dir, f));
+  if (files.length === 0) {
+    console.error(`no *.test.js files in ${dir}`);
+    return fail(2);
+  }
+  for (const f of files) {
+    // Each file runs its own runScenarios() at require time, which records a
+    // non-zero process.exitCode on failure but no longer aborts the process.
+    require(f);
+  }
+  return !process.exitCode;
 }
 
-module.exports = { runScenarios };
+module.exports = { runScenarios, runScenarioFiles };