Skip to content

docs(plugins): document namespaced emitted events #240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
gabek wants to merge 2 commits into from
Closed

docs(plugins): document namespaced emitted events #240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39619cd
docs(plugins): document namespaced emitted events
gabek Aug 9, 2026
04c4af8
docs(plugins): note the reserved core-event rejection on emit
gabek Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/plugins/apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -585,6 +585,9 @@ Emit a custom event that other plugins can subscribe to. The host prefixes
Pass an event-name suffix. Dots are allowed for hierarchy. Subscribers use the
fully qualified `<plugin-slug>.<event>` name in their custom-event handler:
see the [handlers reference](/docs/plugins/events#plugin-to-plugin-events).
If the composed name would equal a built-in Owncast event (a plugin slugged
`chat` emitting `message.received`), the host drops the emit instead of
delivering a forged core event.

<Tabs groupId="plugin-lang">
<TabItem value="js" label="JavaScript" default>
Expand Down
4 changes: 2 additions & 2 deletions docs/plugins/testing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ The scenario's top-level `expect` checks what happened across the whole run:
| `bannedIPs` | List of IPs banned via `owncast.users.banIP` |
| `uploads` | List of `{ name, body?, bodyBase64? }` from `owncast.storage.upload`. `name` is always checked. Non-empty `body` values compare text. Present `bodyBase64` values compare exact decoded bytes |
| `videoConfigWrites` | List of partial configs applied via `owncast.videoConfig.write()` |
| `emits` | List of `{ eventType, payload }` for `owncast.events.emit` calls |
| `emits` | List of `{ eventType, payload }` for `owncast.events.emit` calls. `eventType` is the dispatched name, so it carries your plugin's slug prefix |
| `commands` | List of `{ name, prefix?, description?, usage?, aliases?, modOnly, caseSensitive, cooldownMs }` chat-command registrations, matched by `name` in any order (`prefix`, `description`, `usage`, and `aliases` are checked only when set) |
| `kv` | Partial map of plugin-config state after the scenario |
| `httpRequests` | List of `{ url, method?, body? }` outbound `owncast.http.fetch` calls. `url` is an exact match, an omitted `method` matches any, an omitted `body` skips the check |
Expand Down Expand Up @@ -274,7 +274,7 @@ Example exercising several:
"expect": {
"chatSends": ["alice: 1 message", "alice: 2 messages"],
"kv": { "count:u-alice": "2" },
"emits": [{ "eventType": "milestone.reached", "payload": { "user": "alice", "count": 2 } }]
"emits": [{ "eventType": "my-plugin.milestone.reached", "payload": { "user": "alice", "count": 2 } }]
}
}
```
Expand Down