@owncast/plugin-sdk 0.10.1 → 0.11.0

package/bin/owncast-plugin.js

@@ -31,6 +31,14 @@ function fail(e) {
 // Same shape the host + SDK + registry all validate against.
 const slugPattern = /^[a-z][a-z0-9-]{0,63}$/;
 
+// Canonical registry browse categories for the optional manifest
+// `category` field. Shared taxonomy with the registry and the admin UI.
+const categories = new Set([
+  "chat-bots", "chat-filters", "moderation", "authentication", "themes",
+  "overlays", "notifications", "integrations", "video", "analytics",
+  "games", "admin-utilities", "examples", "other",
+]);
+
 // 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
@@ -59,6 +67,13 @@ function readAndResolveManifest(manifestPath) {
       `manifest.slug ${JSON.stringify(slug)} must match ${slugPattern} (lowercase letters/digits/hyphens, starting with a letter, max 64 chars)`,
     );
   }
+  if (manifest.category !== undefined && !categories.has(manifest.category)) {
+    // Warn only: the host and registry tolerate unknown categories, they
+    // just won't match any browse filter.
+    console.warn(
+      `warning: manifest.category ${JSON.stringify(manifest.category)} is not a known category (${[...categories].join(", ")})`,
+    );
+  }
   manifest.slug = slug;
   return manifest;
 }

package/index.d.ts

@@ -71,20 +71,36 @@ export interface StreamBroadcaster {
   bitrates?: number[];
 }
 
+/** Viewer autoplay behavior. */
+export type AutoplayMode = "off" | "always" | "sound-only";
+
+/** H.264 encoder names accepted by Owncast video config writes.
+ *  Hardware encoders must also be available in ffmpeg. */
+export type VideoCodec =
+  | "libx264"
+  | "h264_omx"
+  | "h264_vaapi"
+  | "h264_qsv"
+  | "h264_nvenc"
+  | "h264_v4l2m2m"
+  | "h264_videotoolbox";
+
 /** One configured output rendition, part of VideoConfig (owncast.videoConfig). */
 export interface StreamVariant {
   width: number;
   height: number;
   framerate: number;
   videoBitrate: number;
-  audioBitrate: number;
+  cpuUsageLevel: number;
   isPassthrough: boolean;
 }
 
 /** The current video/transcoding config returned by owncast.videoConfig.read(). */
 export interface VideoConfig {
   latencyLevel: number;
+  /** The configured encoder. Reads may report a legacy or newer host value. */
   codec: string;
+  autoplay: AutoplayMode;
   variants: StreamVariant[];
 }
 
@@ -92,7 +108,8 @@ export interface VideoConfig {
  *  are left unchanged. */
 export interface VideoConfigUpdate {
   latencyLevel?: number;
-  codec?: string;
+  codec?: VideoCodec;
+  autoplay?: AutoplayMode;
   variants?: StreamVariant[];
 }
 
@@ -147,6 +164,23 @@ export interface FediverseTargetedEngagement extends FediverseEngagement {
   target: { url: string };
 }
 
+/** An accepted quote request. `target` identifies the local post being quoted,
+ *  while `url` identifies the remote quote post. Content metadata is present
+ *  when the requesting server embeds the quote Note in its request. */
+export interface FediverseQuote extends FediverseTargetedEngagement {
+  content?: string; // HTML from the source instance
+  contentText?: string; // HTML stripped to plain text
+  url: string; // permalink to the remote quote post
+  postedAt?: string; // ISO-8601
+  inReplyTo?: string;
+  attachments?: {
+    url: string;
+    mediaType: string;
+    alt?: string;
+  }[];
+  language?: string;
+}
+
 /** 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). */
@@ -173,6 +207,7 @@ export const Permissions: {
   readonly StorageKV: "storage.kv";
   readonly StorageUpload: "storage.upload";
   readonly StorageFS: "storage.fs";
+  readonly StorageSQL: "storage.sql";
   readonly EventsEmit: "events.emit";
   readonly NetworkFetch: "network.fetch";
   readonly HttpServe: "http.serve";
@@ -192,13 +227,18 @@ export const Permissions: {
 
 /** Request for `owncast.users.register`. */
 export interface UserRegisterRequest {
-  /** Stable, provider-scoped external identity (e.g. `"github:583231"`). The
-   *  host namespaces it by the calling plugin's slug. */
+  /** Stable external identity within this plugin's provider namespace. */
   authId: string;
-  /** Optional display name to seed on the user. */
-  displayName?: string;
+  /** Optional display name to seed on the user. Omit or pass `null` to generate one. */
+  displayName?: string | null;
   /** Optional scopes to grant the user (e.g. `["MODERATOR"]`). */
   scopes?: string[];
+  /** Verified public profile URL. The host accepts only absolute HTTP(S) URLs. */
+  profileUrl?: string;
+  /** Label for the verified identity, such as a GitHub login or fediverse handle. */
+  handle?: string;
+  /** Surface the verified identity publicly only when the viewer opted in. */
+  public?: boolean;
 }
 
 /** Result of `owncast.users.register`: the resolved Owncast user ID. */
@@ -277,13 +317,38 @@ export interface UploadResult {
   url: string;
 }
 
-/** Result of a mutating owncast.fs call (write/delete). `ok` is false and
- *  `error` is set when the host rejected the operation. */
+/** Result of a mutating owncast.fs call (write/delete). An empty object means
+ *  success. `error` is set when the host rejected the operation. */
 export interface FsResult {
-  ok: boolean;
   error?: string;
 }
 
+/** A value a plugin can bind to a statement parameter, or read back out of a
+ *  column. Blobs arrive base64-encoded as strings. */
+export type SQLValue = null | boolean | number | string;
+
+/** Result of `owncast.sql.exec`. Absence of `error` means success. Both
+ *  counters are SQLite 64-bit integers, so they lose precision in JavaScript
+ *  above `Number.MAX_SAFE_INTEGER`. */
+export interface SQLExecResult {
+  error?: string;
+  rowsAffected: number;
+  lastInsertId: number;
+}
+
+/** One row as `owncast.sql.query` hands it back: column name to value. */
+export type SQLRow = Record<string, SQLValue>;
+
+/** The host's raw query response, before the SDK keys rows by column name.
+ *  Absence of `error` means success. `rows` holds values in `columns` order,
+ *  and `truncated` is set when more rows matched than the caller's row limit. */
+export interface SQLQueryResult {
+  error?: string;
+  columns: string[];
+  rows: SQLValue[][];
+  truncated?: boolean;
+}
+
 export const filter: {
   pass(): FilterResult;
   modify(payload: any): FilterResult;
@@ -415,8 +480,8 @@ export interface PluginDef {
   onFediverseLike?(event: FediverseTargetedEngagement): void | Promise<void>;
   /** Someone on the fediverse boosted (reposted) a streamer post. Requires `fediverse.inbound`. */
   onFediverseRepost?(event: FediverseTargetedEngagement): void | Promise<void>;
-  /** Someone on the fediverse quoted a locally authored post. `target.url` identifies that quoted post. Requires `fediverse.inbound`. */
-  onFediverseQuote?(event: FediverseTargetedEngagement): void | Promise<void>;
+  /** Someone on the fediverse quoted a locally authored post. `target.url` identifies the local post and `url` identifies the remote quote post. Requires `fediverse.inbound`. */
+  onFediverseQuote?(event: FediverseQuote): void | Promise<void>;
   /** Someone @-mentioned the streamer in a public post. Requires `fediverse.inbound`. */
   onFediverseMention?(post: FediverseInboundPost): void | Promise<void>;
   /** Someone replied to one of the streamer's federated posts. Requires `fediverse.inbound`. */
@@ -470,9 +535,10 @@ export interface PluginDef {
    *  Requires `ui.modify`. */
   onPageScripts?(): string | null | void;
 
-  /** 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. */
+  /** Handlers for custom events owned by this plugin. Keys are local hook names
+   *  such as "announcement.broadcast". The host registers each hook as
+   *  `<your-slug>.<hook>`, which emitters use as the target event type.
+   *  Notifications only. Filtering custom events requires additional API. */
   on?: { [eventType: string]: (payload: any) => void | Promise<void> };
 
   /** Filter chain priority (lower = earlier). Applies to every filter*
@@ -528,9 +594,16 @@ export interface CommandEvent {
   argString: string;
 }
 
-/** Typed wrappers around the Owncast host. Each method throws if the
- *  corresponding permission was not declared in plugin.manifest.json. */
+/** Typed wrappers around the Owncast host. Methods that require a permission
+ *  say so in their documentation and throw when it was not declared. */
 export const owncast: {
+  /** Write a plugin-attributed entry to Owncast's server log. No permission
+   *  is required. */
+  log: {
+    info(message: string): void;
+    warning(message: string): void;
+    error(message: string): void;
+  };
   chat: {
     /** Post as the plugin's own chat bot (display name = the plugin's name). */
     send(text: string): void;
@@ -552,9 +625,11 @@ export const owncast: {
     /** Recent chat history (most recent last). Requires `chat.history`.
      *  Default limit is 50. Pass a smaller number to get fewer. */
     history(limit?: number): ChatMessage[];
-    /** Hide a chat message by ID. Requires `chat.moderate`. */
+    /** Hide a chat message by ID. Throws when the host rejects the operation.
+     *  Requires `chat.moderate`. */
     deleteMessage(messageId: string): void;
-    /** Disconnect a chat client by its numeric ID. Requires `chat.moderate`. */
+    /** Disconnect a chat client by its numeric ID. Throws when the host rejects
+     *  the operation. Requires `chat.moderate`. */
     kick(clientId: number | bigint): void;
     /** List currently-connected chat clients. Requires `chat.history`. */
     clients(): ChatClient[];
@@ -565,20 +640,24 @@ export const owncast: {
     list(): User[];
     /** Fetch one user by ID. Requires `users.read`. */
     get(id: string): User | null;
-    /** Enable/disable a user, with an optional reason. Requires `users.moderate`. */
+    /** Enable or disable a user, with an optional reason. Throws when the host
+     *  rejects the operation. Requires `users.moderate`. */
     setEnabled(id: string, enabled: boolean, reason?: string): void;
-    /** Ban an IP address. Requires `users.moderate`. */
+    /** Ban an IP address. Throws when the host rejects the operation. Requires
+     *  `users.moderate`. */
     banIP(ip: string): void;
-    /** Find-or-create an authenticated user for an external identity. `authId`
-     *  is the stable provider-scoped id (e.g. `"github:583231"`). The host
-     *  namespaces it by this plugin's slug so plugins can't collide on or spoof
-     *  each other's users. Returns `{ userId }`. Throws on host error.
+    /** Find or create an authenticated user for an external identity. The host
+     *  scopes `authId` to this plugin's slug. `profileUrl` and `handle`
+     *  describe a verified external profile, and `public` opts that identity
+     *  into public display. Returns `{ userId }`. Throws on host error.
      *  Requires `users.register`. */
     register(opts: UserRegisterRequest | string): UserRegisterResult;
   };
   /** Viewer-authentication gate. Only a plugin holding `auth.gate` (and enabled
    *  by an admin) can issue sessions, and only inside `onHttpRequest`, where the
-   *  host attaches or clears the signed session cookie on the response. */
+   *  host attaches or clears the signed session cookie on the response. The
+   *  admin selects the cumulative, host-owned access mode. Plugins cannot read
+   *  or change it. */
   auth: {
     /** Issue a gate session for an already-registered user (see
      *  `users.register`). `ttl` is optional seconds (0/omitted = host default).
@@ -593,7 +672,7 @@ export const owncast: {
   storage: {
     upload(name: string, data: Uint8Array | string): UploadResult | null;
   };
-  /** Private, sandboxed filesystem under data/plugin-data/<slug>/. The bytes
+  /** Private, sandboxed filesystem under data/plugin-storage/<slug>/files/. The bytes
    *  stay server-side (never served over HTTP) and the host confines every
    *  path to this plugin's own directory. All methods require `storage.fs`. */
   fs: {
@@ -610,6 +689,29 @@ export const owncast: {
     /** Report whether a path exists inside the sandbox. */
     exists(path: string): boolean;
   };
+  /** Private SQLite database, one per plugin, stored in `db/` next to the
+   *  `storage.fs` sandbox in `files/`, outside anything `owncast.fs.*` can name,
+   *  and quota'd separately. Every call runs with a 2 second timeout. Absence
+   *  of `error` means success. An error, missing response, or non-object
+   *  response throws. JavaScript loses unsafe integers before `JSON.stringify`
+   *  on writes and during `JSON.parse` on reads, so store values above
+   *  `Number.MAX_SAFE_INTEGER` (2^53 - 1) as TEXT when they must remain exact.
+   *  Requires `storage.sql`. */
+  sql: {
+    /** Execute one statement batch as a single transaction: it commits whole
+     *  or leaves the database untouched. A transaction cannot stay open
+     *  across calls. */
+    exec(sql: string, params?: SQLValue[]): SQLExecResult;
+    /** Query rows as objects keyed by column name. Alias duplicate columns.
+     *  The result is never silently shortened: a query returning more than
+     *  10000 rows, or more than 1 MiB of encoded data, throws asking for a
+     *  LIMIT. */
+    query(sql: string, params?: SQLValue[]): SQLRow[];
+    /** Return the first matching row, or null. Only that row is read back, so
+     *  this stays under the result budget on a table `query` is too big
+     *  for. */
+    queryRow(sql: string, params?: SQLValue[]): SQLRow | null;
+  };
   /** Post to the fediverse on the streamer's behalf. Requires `fediverse.post`,
    *  which is high-trust (posts go out under the streamer's own handle), so
    *  admins should grant it sparingly. */
@@ -632,6 +734,7 @@ export const owncast: {
   };
   kv: {
     get(key: string): string | null;
+    /** Store a value. Throws when the host rejects the operation. */
     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`. */
@@ -659,6 +762,8 @@ export const owncast: {
     readText(path: string): string | null;
   };
   events: {
+    /** Emit to a custom hook using its fully qualified
+     *  `<recipient-plugin-slug>.<hook>` name. Requires `events.emit`. */
     emit(eventType: string, payload: unknown): void;
   };
   /** Control over the viewer action buttons this plugin contributes.
@@ -670,11 +775,11 @@ export const owncast: {
      *  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. */
+     *  rejected). Throws when the host rejects the action list. */
     add(actions: ActionButton | ActionButton[]): void;
     /** Drop the runtime additions, so only `manifest.actions` remain on
-     *  the next viewer `/api/config` request. */
+     *  the next viewer `/api/config` request. Throws when the host rejects the
+     *  operation. */
     clear(): void;
   };
   sse: {
@@ -718,7 +823,8 @@ export const owncast: {
     tags(): string[];
   };
   /** Read/change video/transcoding configuration. read() requires
-   *  `videoconfig.read`, and write() requires `videoconfig.write`. */
+   *  `videoconfig.read`. write() requires `videoconfig.write` and throws when
+   *  the host rejects the update or does not return an operation result. */
   videoConfig: {
     read(): VideoConfig;
     write(config: VideoConfigUpdate): void;
@@ -778,3 +884,38 @@ export interface NetworkConfig {
    *  host but must be written explicitly. */
   allowedHosts: string[];
 }
+
+/** `manifest.category` (optional), the plugin's registry browse category.
+ *  One of the canonical slugs below. The plugin registry uses it to filter
+ *  the browse listing; unknown values are tolerated but won't match any
+ *  filter.
+ *
+ *  - `chat-bots`: Chat bots
+ *  - `chat-filters`: Chat filters
+ *  - `moderation`: Moderation
+ *  - `authentication`: Authentication
+ *  - `themes`: Themes
+ *  - `overlays`: Overlays & widgets
+ *  - `notifications`: Notifications
+ *  - `integrations`: Integrations
+ *  - `video`: Video & streaming
+ *  - `analytics`: Analytics & stats
+ *  - `games`: Games & fun
+ *  - `admin-utilities`: Admin utilities
+ *  - `examples`: Examples
+ *  - `other`: Other */
+export type PluginCategory =
+  | "chat-bots"
+  | "chat-filters"
+  | "moderation"
+  | "authentication"
+  | "themes"
+  | "overlays"
+  | "notifications"
+  | "integrations"
+  | "video"
+  | "analytics"
+  | "games"
+  | "admin-utilities"
+  | "examples"
+  | "other";

package/index.js

@@ -1,9 +1,10 @@
 // @owncast/plugin-sdk runtime, bundled into every plugin.
 //
 // Authors define typed handlers (onChatMessage, filterChatMessage, ...) plus
-// an `on: { [customEvent]: handler }` object for plugin-emitted events. The
+// an `on: { [localCustomHook]: handler }` object for plugin-owned events. The
 // SDK derives the manifest's subscriptions from which handlers are present
-// and returns them via register(). Authors don't maintain a duplicate list.
+// and returns them via register(). The host qualifies custom hooks with the
+// declaring plugin's slug.
 
 let registered = null;
 
@@ -65,6 +66,7 @@ const Permissions = Object.freeze({
   StorageKV: "storage.kv",
   StorageUpload: "storage.upload",
   StorageFS: "storage.fs",
+  StorageSQL: "storage.sql",
   EventsEmit: "events.emit",
   NetworkFetch: "network.fetch",
   HttpServe: "http.serve",
@@ -351,16 +353,6 @@ function dispatchHttp(request) {
   };
 }
 
-// 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);
-}
 
 // 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
@@ -383,16 +375,77 @@ function scheduleTimer(fn, ms, repeat) {
   return id;
 }
 
-// hostFns returns the host import table, throwing an actionable error if the
-// named function wasn't granted (the plugin's manifest is missing its
-// permission). This is the per-call guard every owncast.* method used to inline.
+// hostFns returns the complete host import table. Missing imports indicate an
+// incompatible host. Permission denials are reported by result-returning calls.
 function hostFns(name, perm) {
   const fns = Host.getFunctions();
   if (!fns[name]) throw new Error(`permission '${perm}' not granted`);
   return fns;
 }
 
+function operationResult(offset, failureMessage) {
+  if (offset == 0) return { error: failureMessage };
+  try {
+    const result = JSON.parse(Memory.find(offset).readString());
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return { error: failureMessage };
+    }
+    return result;
+  } catch {
+    return { error: failureMessage };
+  }
+}
+
+function requireOperationResult(offset, failureMessage) {
+  const result = operationResult(offset, failureMessage);
+  if (Object.prototype.hasOwnProperty.call(result, "error")) {
+    throw new Error(result.error || failureMessage);
+  }
+  return result;
+}
+
+function sqlResult(offset) {
+  return requireOperationResult(offset, "SQL host call failed");
+}
+
+function sqlRows(result) {
+  if (!Array.isArray(result.columns) || !Array.isArray(result.rows)) {
+    throw new Error("SQL host returned an invalid result");
+  }
+  return result.rows.map((values) => {
+    if (!Array.isArray(values)) {
+      throw new Error("SQL host returned an invalid result");
+    }
+    return Object.fromEntries(result.columns.map((column, i) => [column, values[i]]));
+  });
+}
+
+function sqlQuery(sql, params, maxRows) {
+  const fns = hostFns("owncast_sql_query", Permissions.StorageSQL);
+  const payload = { sql: String(sql), params: Array.from(params || []) };
+  if (maxRows) payload.maxRows = maxRows;
+  const request = Memory.fromString(JSON.stringify(payload));
+  return sqlResult(fns.owncast_sql_query(request.offset));
+}
+
+function logToHost(name, message) {
+  const fn = Host.getFunctions()[name];
+  if (!fn) throw new Error("owncast.log is unavailable in this host");
+  fn(Memory.fromString(String(message)).offset);
+}
+
 const owncast = {
+  log: {
+    info(message) {
+      logToHost("owncast_log_info", message);
+    },
+    warning(message) {
+      logToHost("owncast_log_warning", message);
+    },
+    error(message) {
+      logToHost("owncast_log_error", message);
+    },
+  },
   chat: {
     send(text) {
       const fns = hostFns("owncast_send_chat", Permissions.ChatSend);
@@ -414,11 +467,15 @@ const owncast = {
     },
     deleteMessage(messageId) {
       const fns = hostFns("owncast_delete_message", Permissions.ChatModerate);
-      fns.owncast_delete_message(Memory.fromString(String(messageId)).offset);
+      const offset = fns.owncast_delete_message(
+        Memory.fromString(String(messageId)).offset,
+      );
+      requireOperationResult(offset, "chat.deleteMessage failed");
     },
     kick(clientId) {
       const fns = hostFns("owncast_kick_client", Permissions.ChatModerate);
-      fns.owncast_kick_client(BigInt(clientId));
+      const offset = fns.owncast_kick_client(BigInt(clientId));
+      requireOperationResult(offset, "chat.kick failed");
     },
     sendTo(clientId, text) {
       const fns = hostFns("owncast_send_chat_to", Permissions.ChatSend);
@@ -463,37 +520,44 @@ const owncast = {
     },
     setEnabled(id, enabled, reason) {
       const fns = hostFns("owncast_user_set_enabled", Permissions.UsersModerate);
-      fns.owncast_user_set_enabled(
+      const offset = fns.owncast_user_set_enabled(
         Memory.fromString(id).offset,
         enabled ? 1 : 0,
         Memory.fromString(reason || "").offset,
       );
+      requireOperationResult(offset, "users.setEnabled failed");
     },
     banIP(ip) {
       const fns = hostFns("owncast_ban_ip", Permissions.UsersModerate);
-      fns.owncast_ban_ip(Memory.fromString(ip).offset);
+      const offset = fns.owncast_ban_ip(Memory.fromString(ip).offset);
+      requireOperationResult(offset, "users.banIP failed");
     },
-    // Find-or-create an authenticated Owncast user for an external identity
-    // (e.g. a provider account). `authId` is the stable provider-scoped id. The
-    // host namespaces it by this plugin's slug so it can't collide with or spoof
-    // another plugin's users. Optionally seeds displayName and scopes. Returns
-    // { userId }. Throws on host error. Requires `users.register`.
+    // Find or create an authenticated Owncast user for an external identity.
+    // profileUrl and handle describe a verified profile. public opts that
+    // identity into public display. Returns { userId }. Throws on host error.
+    // Requires `users.register`.
     register(opts) {
       const fns = hostFns("owncast_users_register", Permissions.UsersRegister);
-      const req =
-        typeof opts === "string" ? { authId: opts } : opts || {};
+      const source = typeof opts === "string" ? { authId: opts } : opts || {};
+      const req = {
+        authId: source.authId,
+        displayName: source.displayName,
+        scopes: source.scopes,
+        profileUrl: source.profileUrl,
+        handle: source.handle,
+        public: source.public,
+      };
       const offset = fns.owncast_users_register(
         Memory.fromString(JSON.stringify(req)).offset,
       );
-      if (offset == 0) throw new Error("users.register failed");
-      const result = JSON.parse(Memory.find(offset).readString());
-      if (result.error) throw new Error(result.error);
-      return result; // { userId }
+      return requireOperationResult(offset, "users.register failed"); // { userId }
     },
   },
   // Viewer-authentication gate. Only a plugin holding `auth.gate` (and enabled by
   // an admin) can issue sessions, and these are valid only inside onHttpRequest,
   // where the host attaches/clears the signed session cookie on the response.
+  // The admin selects the cumulative, host-owned access mode. Plugins cannot
+  // read or change it.
   auth: {
     // Issue a gate session for an already-registered user (see users.register).
     // `ttl` is optional seconds, and 0/omitted uses the host default. Throws on
@@ -504,9 +568,7 @@ const owncast = {
       const offset = fns.owncast_auth_grant_session(
         Memory.fromString(JSON.stringify(req)).offset,
       );
-      if (offset == 0) throw new Error("auth.grantSession failed");
-      const result = JSON.parse(Memory.find(offset).readString());
-      if (result.error) throw new Error(result.error);
+      requireOperationResult(offset, "auth.grantSession failed");
     },
     // Clear the current viewer's gate session (logout). The plugin still owns the
     // response/redirect. Requires `auth.gate`.
@@ -535,7 +597,7 @@ const owncast = {
       return JSON.parse(Memory.find(offset).readString());
     },
   },
-  // Private, sandboxed filesystem under data/plugin-data/<slug>/. Unlike
+  // Private, sandboxed filesystem under data/plugin-storage/<slug>/files/. Unlike
   // storage.upload (which publishes browser-accessible files), these bytes
   // stay server-side. The host confines every path to this plugin's own
   // directory. All methods require the 'storage.fs' permission.
@@ -557,7 +619,7 @@ const owncast = {
       return Memory.find(offset).readString();
     },
     // Write bytes (Uint8Array) or a string to a file, creating parent
-    // directories as needed. Returns { ok, error? }.
+    // directories as needed. Returns { error? }.
     write(path, data) {
       const fns = hostFns("owncast_fs_write", Permissions.StorageFS);
       const dataMem =
@@ -573,8 +635,7 @@ const owncast = {
         Memory.fromString(path).offset,
         dataMem.offset,
       );
-      if (offset == 0) return { ok: false, error: "write failed" };
-      return JSON.parse(Memory.find(offset).readString());
+      return operationResult(offset, "write failed");
     },
     // List the entry names (files and subdirectories) directly inside dir.
     // A missing directory lists as empty. Returns string[].
@@ -584,12 +645,11 @@ const owncast = {
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
-    // Remove a single file or empty directory. Returns { ok, error? }.
+    // Remove a single file or empty directory. Returns { error? }.
     delete(path) {
       const fns = hostFns("owncast_fs_delete", Permissions.StorageFS);
       const offset = fns.owncast_fs_delete(Memory.fromString(path).offset);
-      if (offset == 0) return { ok: false, error: "delete failed" };
-      return JSON.parse(Memory.find(offset).readString());
+      return operationResult(offset, "delete failed");
     },
     // Report whether a path exists inside the sandbox. Returns boolean.
     exists(path) {
@@ -597,6 +657,23 @@ const owncast = {
       return fns.owncast_fs_exists(Memory.fromString(path).offset) === 1;
     },
   },
+  sql: {
+    exec(sql, params = []) {
+      const fns = hostFns("owncast_sql_exec", Permissions.StorageSQL);
+      const request = Memory.fromString(
+        JSON.stringify({ sql: String(sql), params: Array.from(params || []) }),
+      );
+      return sqlResult(fns.owncast_sql_exec(request.offset));
+    },
+    query(sql, params = []) {
+      return sqlRows(sqlQuery(sql, params));
+    },
+    queryRow(sql, params = []) {
+      // Asking the host for one row keeps a first-row read off the result
+      // budget, so this works against a table `query` would be too big for.
+      return sqlRows(sqlQuery(sql, params, 1))[0] || null;
+    },
+  },
   fediverse: {
     /** Publish a public text-only post to the fediverse on the streamer's
      *  behalf. Returns { url } on success, null on failure (rate-limited,
@@ -690,10 +767,7 @@ const owncast = {
       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");
+      requireOperationResult(offset, "videoConfig.write failed");
     },
   },
   kv: {
@@ -705,10 +779,11 @@ const owncast = {
     },
     set(key, value) {
       const fns = hostFns("owncast_kv_set", Permissions.StorageKV);
-      fns.owncast_kv_set(
+      const offset = fns.owncast_kv_set(
         Memory.fromString(key).offset,
         Memory.fromString(String(value)).offset,
       );
+      requireOperationResult(offset, "kv.set failed");
     },
     // getJSON/setJSON are convenience wrappers over the string-only store, so
     // plugins don't reimplement JSON.parse/stringify for every stored object.
@@ -769,28 +844,27 @@ const owncast = {
     },
   },
   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'.
+    // Append one or more action buttons to the plugin's effective list.
+    // The host validates and persists the list, returning { error? }.
     add(actions) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_add_actions)
-        throw permError("owncast.actions.add", Permissions.UIModify);
+      const fns = hostFns("owncast_add_actions", Permissions.UIModify);
       const list = Array.isArray(actions) ? actions : [actions];
-      fns.owncast_add_actions(Memory.fromString(JSON.stringify(list)).offset);
+      requireOperationResult(
+        fns.owncast_add_actions(
+          Memory.fromString(JSON.stringify(list)).offset,
+        ),
+        "owncast.actions.add failed",
+      );
     },
     // 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();
+      const fns = hostFns("owncast_clear_actions", Permissions.UIModify);
+      requireOperationResult(
+        fns.owncast_clear_actions(),
+        "owncast.actions.clear failed",
+      );
     },
   },
   sse: {

package/package.json

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