@owncast/plugin-sdk 0.6.0 → 0.10.1

package/index.d.ts

@@ -1,34 +1,25 @@
 /**
  * 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
+ * `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
+ * 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?: ChatUser;
+  user?: User;
   clientId?: number;
   body: string;
   timestamp: string;
 }
 
-/** A chat user, payload of join/part/rename events. */
-export interface ChatUser {
-  id: string;
-  displayName: string;
-  isBot?: boolean;
-  isAuthenticated?: boolean;
-  scopes?: string[];
-}
-
 /** Payload of `chat.user.renamed`, the same user changing their name. */
 export interface ChatUserRename {
-  user: ChatUser;
+  user: User;
   previousName: string;
 }
 
@@ -36,7 +27,7 @@ export interface ChatUserRename {
 export interface ChatMessageModeration {
   messageId: string;
   visible: boolean;
-  moderator?: ChatUser;
+  moderator?: User;
 }
 
 /** Stream-lifecycle payloads. */
@@ -129,9 +120,11 @@ export const Events: {
   readonly SseConnect: "sse.connect";
   readonly SseDisconnect: "sse.disconnect";
   readonly Tick: "tick";
+  readonly FediverseActivity: "fediverse.activity";
   readonly FediverseFollow: "fediverse.follow";
   readonly FediverseLike: "fediverse.like";
   readonly FediverseRepost: "fediverse.repost";
+  readonly FediverseQuote: "fediverse.quote";
   readonly FediverseMention: "fediverse.mention";
   readonly FediverseReply: "fediverse.reply";
 };
@@ -146,10 +139,14 @@ export interface FediverseActor {
 
 export interface FediverseEngagement {
   actor: FediverseActor;
-  /** For likes and reposts: the target object URL. Not set for follows. */
+  /** For likes, reposts, and quotes: the target object URL. Not set for follows. */
   target?: { url: string };
 }
 
+export interface FediverseTargetedEngagement extends FediverseEngagement {
+  target: { url: 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). */
@@ -183,13 +180,40 @@ export const Permissions: {
   readonly NotificationsSend: "notifications.send";
   readonly UsersRead: "users.read";
   readonly UsersModerate: "users.moderate";
+  readonly UsersRegister: "users.register";
+  readonly AuthGate: "auth.gate";
   readonly FediversePost: "fediverse.post";
+  readonly FediverseInbound: "fediverse.inbound";
   readonly HttpSSE: "http.sse";
   readonly VideoConfigRead: "videoconfig.read";
   readonly VideoConfigWrite: "videoconfig.write";
   readonly UIModify: "ui.modify";
 };
 
+/** 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. */
+  authId: string;
+  /** Optional display name to seed on the user. */
+  displayName?: string;
+  /** Optional scopes to grant the user (e.g. `["MODERATOR"]`). */
+  scopes?: string[];
+}
+
+/** Result of `owncast.users.register`: the resolved Owncast user ID. */
+export interface UserRegisterResult {
+  userId: string;
+}
+
+/** Request for `owncast.auth.grantSession`. */
+export interface GrantSessionRequest {
+  /** The Owncast user ID returned by `owncast.users.register`. */
+  userId: string;
+  /** Optional session lifetime in seconds. 0/omitted uses the host default. */
+  ttl?: number;
+}
+
 export interface BrowserPushPayload {
   title: string;
   body?: string;
@@ -221,10 +245,14 @@ export interface FederationInfo {
   isPrivate?: boolean;
 }
 
-/** A user record from owncast.users.list() / .get(). */
+/** A user. The sender identity carried by every chat payload
+ *  (chat.message.received, join/part/rename, moderation) and the record
+ *  returned by owncast.users.list() / .get(). `displayColor` is an index into
+ *  the instance's configured user-color palette, not a literal color. */
 export interface User {
   id: string;
   displayName: string;
+  displayColor: number;
   previousNames?: string[];
   createdAt?: string;
   disabledAt?: string; // ISO-8601 if banned, omitted otherwise
@@ -262,6 +290,30 @@ export const filter: {
   drop(reason?: string): FilterResult;
 };
 
+/** Request passed to `onAuthCheck`: the host-resolved identity of the viewer
+ *  whose session is being re-validated (same `user` shape `onHttpRequest`
+ *  receives, and the plugin never re-resolves it). */
+export interface AuthCheckRequest {
+  user: User;
+}
+
+/** Verdict returned from `onAuthCheck`:
+ *  - `ok`      keep the session as-is
+ *  - `refresh` keep it and re-issue the cookie (optionally with a new `ttl`
+ *              in seconds) for sliding-expiry
+ *  - `deny`    end the session and bounce the viewer back to the login screen */
+export type AuthCheckResult =
+  | { action: "ok" }
+  | { action: "refresh"; ttl?: number }
+  | { action: "deny"; reason?: string };
+
+/** Verdict helpers for `onAuthCheck`. */
+export const authCheck: {
+  ok(): AuthCheckResult;
+  refresh(opts?: { ttl?: number }): AuthCheckResult;
+  deny(reason?: string): AuthCheckResult;
+};
+
 /** Incoming HTTP request, paths are relative to the plugin's namespace
  *  (i.e. the leading /plugins/<name>/ has been stripped). */
 export interface IncomingHttpRequest {
@@ -275,7 +327,7 @@ export interface IncomingHttpRequest {
   authenticated: boolean;
   /** Identity of the user that made the request, when it came with a
    *  user-token. Undefined for anonymous or admin-only requests. */
-  user?: ChatUser;
+  user?: User;
 }
 
 export interface OutgoingHttpResponse {
@@ -290,7 +342,7 @@ export interface ContentRequest {
   slug: string;
   /** The viewing user's chat identity, when available. Undefined for
    *  anonymous viewers or when the host cannot resolve an identity. */
-  user?: ChatUser;
+  user?: User;
 }
 
 /** Payload for the sse.connect / sse.disconnect events. Fired when a browser
@@ -302,7 +354,7 @@ export interface ContentRequest {
 export interface SSEConnectionEvent {
   channel: string;
   connectionId: number;
-  user?: ChatUser;
+  user?: User;
 }
 
 /** Payload for the once-a-second tick event (onTick). `now` is the host
@@ -312,21 +364,13 @@ export interface TickEvent {
 }
 
 export interface PluginDef {
-  /** Declarative chat-command table. When set, the SDK wires the chat
-   *  subscription and prefix parsing for you — no onChatMessage needed. Maps
-   *  canonical command name → definition (run/description/usage/aliases/
-   *  modOnly/cooldownMs/...); see {@link CommandDefinition}. For advanced
-   *  composition (e.g. dropping command messages via a filter) use the
-   *  lower-level {@link defineCommands} router instead. If you also provide
-   *  onChatMessage, the router runs first and then onChatMessage runs for every
-   *  message. */
+  /** Declarative chat commands with aliases, moderator gates, and per-user
+   *  cooldowns. Command messages also remain available to onChatMessage. */
   commands?: Record<string, CommandDefinition>;
   /** Command prefix for the `commands` table. Default "!". */
   commandPrefix?: string;
   /** Match command names case-sensitively. Default false. */
   commandsCaseSensitive?: boolean;
-  /** Called when a prefixed message matched no command in `commands`. */
-  onUnknownCommand?(ctx: CommandContext): void;
 
   /** Notification handler for chat messages. Fire-and-forget. */
   onChatMessage?(msg: ChatMessage): void | Promise<void>;
@@ -336,9 +380,9 @@ export interface PluginDef {
   filterChatMessage?(msg: ChatMessage): FilterResult;
 
   /** User connected to chat. */
-  onChatUserJoined?(user: ChatUser): void | Promise<void>;
+  onChatUserJoined?(user: User): void | Promise<void>;
   /** User disconnected from chat. */
-  onChatUserParted?(user: ChatUser): void | Promise<void>;
+  onChatUserParted?(user: User): void | Promise<void>;
   /** User changed their display name. */
   onChatUserRenamed?(change: ChatUserRename): void | Promise<void>;
   /** A chat message was hidden or restored by a moderator. */
@@ -362,15 +406,20 @@ export interface PluginDef {
    *  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. */
+  /** A verified inbound ActivityPub activity as its raw JSON object. Requires `fediverse.inbound`. */
+  onFediverse?(activity: Record<string, unknown>): void | Promise<void>;
+
+  /** Someone on the fediverse followed the streamer's account. Requires `fediverse.inbound`. */
   onFediverseFollow?(event: FediverseEngagement): void | Promise<void>;
-  /** Someone on the fediverse liked a streamer post / federated stream announcement. */
-  onFediverseLike?(event: FediverseEngagement): void | Promise<void>;
-  /** Someone on the fediverse boosted (reposted) a streamer post. */
-  onFediverseRepost?(event: FediverseEngagement): void | Promise<void>;
-  /** Someone @-mentioned the streamer in a public post. */
+  /** Someone on the fediverse liked a streamer post / federated stream announcement. Requires `fediverse.inbound`. */
+  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 @-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. */
+  /** Someone replied to one of the streamer's federated posts. Requires `fediverse.inbound`. */
   onFediverseReply?(post: FediverseInboundPost): void | Promise<void>;
 
   /** HTTP request handler. Called for any path under /plugins/<name>/ that
@@ -378,6 +427,15 @@ export interface PluginDef {
    *  on `req.authenticated` yourself. Requires `http.serve` permission. */
   onHttpRequest?(req: IncomingHttpRequest): OutgoingHttpResponse;
 
+  /** Re-validate a viewer's gate session on page load. Only meaningful for the
+   *  active `auth.gate` plugin: the host calls it on the viewer's `/` request
+   *  with the resolved `req.user`, and acts on the verdict: `ok` to continue,
+   *  `refresh` to extend the session, `deny` to revoke it and force re-login.
+   *  Optional. Without it a granted session lasts until its cookie
+   *  expires (no mid-session revocation). This is the revocation hook: return
+   *  `deny` for users your provider has banned/deleted. Requires `auth.gate`. */
+  onAuthCheck?(req: AuthCheckRequest): AuthCheckResult;
+
   /** 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
@@ -390,6 +448,28 @@ export interface PluginDef {
    *  `req.user` is the viewer's chat identity when available. */
   onPageContent?(req: ContentRequest): string;
 
+  /** Return CSS to inline into the viewer page at request time, the dynamic
+   *  counterpart to `manifest.styles`, applied to the whole UI. Called once
+   *  per `/api/config` for any plugin holding `ui.modify`. No manifest field
+   *  is needed, just export this handler. Return nothing (a bare `return`, or
+   *  `""`) to contribute nothing. The output is appended after any static
+   *  `manifest.styles` files, so returning only the active override wins
+   *  within your plugin's own styles. Plugin styles sit below the admin's
+   *  appearance settings, so an admin's explicit colors override yours.
+   *  Global (no per-viewer argument) so `/api/config` stays cacheable.
+   *  Requires `ui.modify`. */
+  onPageStyles?(): string | null | void;
+
+  /** Return JavaScript to append to the viewer page at request time, the
+   *  dynamic counterpart to `manifest.scripts`. Called once per `/api/config`
+   *  for any plugin holding `ui.modify`. The host wraps each plugin's script
+   *  (static and dynamic) in a try/catch so a runtime error can't break other
+   *  plugins, but it runs in the shared viewer `window`: wrap your code in an
+   *  IIFE to avoid global collisions, and escape any untrusted strings you
+   *  embed. Return nothing (a bare `return`, or `""`) to contribute nothing.
+   *  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. */
@@ -407,61 +487,46 @@ export interface CommandContext {
   /** The originating chat message. */
   msg: ChatMessage;
   /** The sender (same as `msg.user`). */
-  user?: ChatUser;
+  user?: User;
   /** The canonical command name that matched (not the alias used). */
   command: string;
+  /** The command name or alias exactly as the sender typed it. */
+  invokedAs: 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
+  /** Whisper a reply to the sender, falling back to a public post if their
    *  connection is unknown. */
   replyPrivately(text: string): void;
 }
 
-/** One command in a {@link defineCommands} table. */
+/** One command in a declarative command table. */
 export interface CommandDefinition {
-  /** Short, human-readable summary of what the command does. Surfaced in
-   *  command listings (e.g. a future `!help`); ignored by the router itself. */
+  /** Short, human-readable summary shown in command listings. */
   description?: string;
   /** Optional usage/example string, e.g. "!latency <0-4>". */
   usage?: string;
   /** Alternate names that invoke this command. */
   aliases?: string[];
-  /** Only allow senders whose scopes include "MODERATOR". */
+  /** Dispatch only for senders whose scopes include "MODERATOR". */
   modOnly?: boolean;
-  /** Minimum milliseconds between invocations per user (clocked off
-   *  `msg.timestamp`). */
+  /** Non-negative integer milliseconds between invocations per user. */
   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;
+/** Internal payload for a matched command declaration. */
+export interface CommandEvent {
+  message: ChatMessage;
+  command: string;
+  invokedAs: string;
+  args: string[];
+  argString: string;
+}
 
 /** Typed wrappers around the Owncast host. Each method throws if the
  *  corresponding permission was not declared in plugin.manifest.json. */
@@ -485,7 +550,7 @@ export const owncast: {
      *  `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. */
+     *  Default limit is 50. Pass a smaller number to get fewer. */
     history(limit?: number): ChatMessage[];
     /** Hide a chat message by ID. Requires `chat.moderate`. */
     deleteMessage(messageId: string): void;
@@ -500,12 +565,30 @@ export const owncast: {
     list(): User[];
     /** Fetch one user by ID. Requires `users.read`. */
     get(id: string): User | null;
-    /** Enable/disable a user; reason is optional. Requires `users.moderate`. */
+    /** Enable/disable a user, with an optional reason. Requires `users.moderate`. */
     setEnabled(id: string, enabled: boolean, reason?: string): void;
     /** Ban an IP address. 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.
+     *  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. */
+  auth: {
+    /** Issue a gate session for an already-registered user (see
+     *  `users.register`). `ttl` is optional seconds (0/omitted = host default).
+     *  Throws on host error. Requires `auth.gate`. */
+    grantSession(opts: GrantSessionRequest | string): void;
+    /** Clear the current viewer's gate session (logout). The plugin still owns
+     *  the response/redirect. Requires `auth.gate`. */
+    endSession(): void;
   };
-  /** Upload bytes to Owncast's storage backend (local or S3); returns a
+  /** Upload bytes to Owncast's storage backend (local or S3). Returns a
    *  public URL. Requires `storage.upload`. */
   storage: {
     upload(name: string, data: Uint8Array | string): UploadResult | null;
@@ -520,7 +603,7 @@ export const owncast: {
     readText(path: string): string | null;
     /** Write bytes or a string, creating parent directories as needed. */
     write(path: string, data: Uint8Array | string): FsResult;
-    /** List entry names directly inside dir; missing dir lists as empty. */
+    /** List entry names directly inside dir. A missing dir lists as empty. */
     list(dir: string): string[];
     /** Remove a single file or empty directory. */
     delete(path: string): FsResult;
@@ -528,7 +611,7 @@ export const owncast: {
     exists(path: string): boolean;
   };
   /** 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);
+   *  which is high-trust (posts go out under the streamer's own handle), so
    *  admins should grant it sparingly. */
   fediverse: {
     /** Publish a public, text-only post. Returns `{ url }` (currently empty
@@ -557,7 +640,7 @@ export const owncast: {
     setJSON(key: string, value: unknown): void;
   };
   /** Read this plugin's admin-configurable settings, declared under
-   *  `config` in the manifest. Ambient — no permission required. */
+   *  `config` in the manifest. Ambient, so no permission is required. */
   config: {
     /** The effective value of a manifest-declared config key (admin override,
      *  else the declared default), parsed to its declared type. Returns
@@ -565,10 +648,10 @@ export const owncast: {
      *  value. */
     get<T = unknown>(key: string, fallback?: T): T;
   };
-  /** Read files the plugin bundled in its own `assets/` directory — templates,
+  /** 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. */
+   *  relative to `assets/` and must not contain `..`. Ambient, so no permission
+   *  is required. */
   assets: {
     /** Raw bytes of the file, or `null` if not found. */
     read(path: string): Uint8Array | null;
@@ -585,30 +668,30 @@ export const owncast: {
   actions: {
     /** Append one or more buttons to the plugin's runtime list. Each
      *  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
+     *  (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. */
     add(actions: ActionButton | ActionButton[]): void;
-    /** Drop the runtime additions; only `manifest.actions` remain on
+    /** Drop the runtime additions, so only `manifest.actions` remain on
      *  the next viewer `/api/config` request. */
     clear(): void;
   };
   sse: {
     /** Push one Server-Sent-Event to every browser connected to this
      *  plugin's `/plugins/<name>/_sse/<channel>` stream. `event` is the SSE
-     *  event name (`""` → the default "message" event); `data` is sent as-is
-     *  if a string, otherwise JSON-stringified. Fire-and-forget; frames to a
+     *  event name (`""` → the default "message" event). `data` is sent as-is
+     *  if a string, otherwise JSON-stringified. Fire-and-forget, and frames to a
      *  slow client are dropped rather than blocking the plugin. Requires the
      *  `http.sse` permission. */
     send(channel: string, event: string, data: unknown): void;
   };
-  /** Host-driven timers. The sandbox has no setTimeout; these ask the host to
+  /** Host-driven timers. The sandbox has no setTimeout, so 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
+     *  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
@@ -635,7 +718,7 @@ export const owncast: {
     tags(): string[];
   };
   /** Read/change video/transcoding configuration. read() requires
-   *  `videoconfig.read`; write() requires `videoconfig.write`. */
+   *  `videoconfig.read`, and write() requires `videoconfig.write`. */
   videoConfig: {
     read(): VideoConfig;
     write(config: VideoConfigUpdate): void;
@@ -656,7 +739,7 @@ export interface HttpResponse {
 
 /** An entry in `manifest.actions`, declares an action button the Owncast
  *  UI surfaces while this plugin is enabled. Mirrors Owncast's existing
- *  ExternalAction shape; the host merges enabled-plugin buttons with the
+ *  ExternalAction shape. The host merges enabled-plugin buttons with the
  *  admin-configured list.
  *
  *  Exactly one of `url` or `html` is required.
@@ -687,10 +770,10 @@ export interface ActionButton {
 
 /** `manifest.network`, narrows outbound HTTP scope for plugins that
  *  declare the `network.fetch` permission. Required when that permission
- *  is granted; the host rejects loads otherwise. */
+ *  is granted. The host rejects loads otherwise. */
 export interface NetworkConfig {
   /** Hostname globs the plugin can reach via `owncast.http.fetch`.
-   *  Bare names match exactly (`"api.discord.com"`); `*` is a wildcard
+   *  Bare names match exactly (`"api.discord.com"`), and `*` is a wildcard
    *  segment (`"*.weather.com"`). The bare wildcard `"*"` matches any
    *  host but must be written explicitly. */
   allowedHosts: string[];