myxelium/Toju
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 2 Releases 25 Wiki Activity

docs: improve doucmentation

Browse Source 
improve doucmentation and fix small store changes
This commit is contained in:
SocksOnHead
2026-04-30 01:16:48 +02:00
parent 3f92e74350
commit 0a714428f6
31 changed files with 4161 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs-site/docs/developer/contributing.md Normal file
View File

@@ -0,0 +1,87 @@
---
sidebar_position: 1
---
# Contributing
MetoYou is an npm-managed monorepo.
## Packages
| Path | Purpose |
| --- | --- |
| `toju-app/` | Angular renderer, chat client, voice UI, plugin runtime. |
| `electron/` | Electron main process, preload bridge, local database, local REST API, docs host. |
| `server/` | Node/TypeScript signaling server and server-directory HTTP API. |
| `website/` | Angular marketing site. |
| `docs-site/` | Docusaurus documentation site. |
| `e2e/` | Playwright browser and WebRTC tests. |
## Setup
Install root dependencies:
```bash
npm install
```
Install server dependencies when working on the signaling server:
```bash
cd server
npm install
```
## Development Commands
From the repository root:
```bash
npm run dev
```
Useful focused commands:
```bash
npm run build
npm run build:electron
npm run build:docs
npm run server:build
npm run lint
npm run test
npm run test:e2e -- tests/chat-dm-flow.spec.ts
```
Run the Docusaurus dev server:
```bash
cd docs-site
npm install
npm run start
```
Build static docs for Electron packaging:
```bash
npm run build:docs
```
## Repository Rules
- Keep changes inside the package that owns the behavior.
- Do not edit generated output in `dist/`, `dist-electron/`, `dist-server/`, `server/dist/`, `.angular/`, or `node_modules/`.
- Renderer-facing Electron capabilities must stay aligned across implementation, preload, and renderer bridge types.
- Signal-server plugin support stores metadata only. Plugin execution belongs to the client runtime.
- Update this documentation when user workflows, plugin APIs, REST routes, DOM structure, or development commands change.
## Documentation Checklist
When you change a related area, update these pages:
| Change | Docs to check |
| --- | --- |
| Voice UI or settings | User Guide: Voice Channels and Calls, Developer Guide: App Pages and DOM Structure. |
| Text channels, messages, DMs | User Guide: Text and Direct Messages, plugin message API pages. |
| Plugin manifest/API/runtime | Plugin Development pages and LLM Plugin Builder Guide. |
| Local REST API routes or schemas | Developer Guide: Local REST API and `electron/api/openapi.ts`. |
| Docusaurus hosting | Developer Guide: Docusaurus Site and Desktop and Local API. |

65
docs-site/docs/developer/docusaurus-site.md Normal file
View File

@@ -0,0 +1,65 @@
---
sidebar_position: 2
---
# Docusaurus Site
The Docusaurus documentation lives in `docs-site/` and builds to static files in `docs-site/build/`.
## Structure
```text
docs-site/
docusaurus.config.ts
sidebars.ts
docs/
intro.md
user-guide/
developer/
plugin-development/
src/css/custom.css
```
## Development
Use the Docusaurus development server while writing docs:
```bash
cd docs-site
npm run start
```
Build the static site:
```bash
npm run build
```
From the repo root, use:
```bash
npm run build:docs
```
## Electron Hosting
Electron serves the built site through the local API server when Docusaurus docs are enabled.
| Route | Purpose |
| --- | --- |
| `/docusaurus` | Docusaurus entrypoint. |
| `/docusaurus/*` | Static Docusaurus assets and generated pages. |
The endpoint is off until the user opens documentation from the desktop app or enables it through local API settings. Electron serves static files only; it does not run `docusaurus start`.
## Sidebar Rules
Navigation is controlled by `docs-site/sidebars.ts`. Add every new page there unless it is intentionally hidden. Use categories for larger sections so non-technical users can find the user guide separately from developer material.
## Content Rules
- User docs should avoid implementation jargon.
- Developer docs should name exact files, commands, routes, capabilities, and data shapes.
- Plugin API examples should use literal sample input data.
- REST docs should stay aligned with `electron/api/openapi.ts` and `electron/api/router.ts`.
- DOM docs should stay aligned with Angular routes and component selectors.

145
docs-site/docs/developer/dom-structure.md Normal file
View File

@@ -0,0 +1,145 @@
---
sidebar_position: 3
---
# App Pages and DOM Structure
This page maps the app routes and important DOM areas. It is useful for plugin authors, testers, and contributors who need stable mental models of where UI mounts.
## Angular Routes
| Route | Component | Purpose |
| --- | --- | --- |
| `/` | Redirect | Redirects to `/search`. |
| `/login` | `LoginComponent` | User login. |
| `/register` | `RegisterComponent` | User registration. |
| `/invite/:inviteId` | `InviteComponent` | Resolve and accept invite links. |
| `/search` | `ServerSearchComponent` | Search and join servers. |
| `/room/:roomId` | `ChatRoomComponent` | Main server page with text, voice, members, and plugin panels. |
| `/dm` | `DmWorkspaceComponent` | Direct-message workspace. |
| `/dm/:conversationId` | `DmWorkspaceComponent` | A selected direct-message conversation. |
| `/settings` | `SettingsComponent` | App, voice, server, plugin, desktop, theme, local API settings. |
| `/plugin-store` | `PluginStoreComponent` | Browse plugin sources and install/update plugins. |
| `/plugins/:pluginId/:pageId` | `PluginPageHostComponent` | Host for plugin app pages registered with `api.ui.registerAppPage()`. |
## Page Shell
The renderer is an Angular app. The common shell contains router outlet content plus persistent app surfaces such as the server rail, title bar integrations, settings modals, and floating voice controls.
High-level structure:
```html
<app-root>
<router-outlet></router-outlet>
<!-- global dialogs, overlays, floating voice controls, and desktop integrations -->
</app-root>
```
## Server Page DOM
The server page is the most important page for plugins.
```html
<app-chat-room>
<app-servers-rail></app-servers-rail>
<app-rooms-side-panel>
<section>Text Channels</section>
<section>Voice Channels</section>
<section data-testid="plugin-room-side-panel">
<app-plugin-render-host></app-plugin-render-host>
</section>
<section>Members</section>
</app-rooms-side-panel>
<main>
<app-voice-workspace></app-voice-workspace>
<app-chat-messages>
<app-message-list></app-message-list>
<app-typing-indicator></app-typing-indicator>
<app-message-composer></app-message-composer>
<app-klipy-gif-picker></app-klipy-gif-picker>
</app-chat-messages>
</main>
</app-chat-room>
```
## Text Channel Area
Text channel UI is owned by the chat domain.
```html
<app-chat-messages>
<app-message-list>
<app-message-item></app-message-item>
</app-message-list>
<app-message-overlays></app-message-overlays>
<app-typing-indicator></app-typing-indicator>
<app-message-composer></app-message-composer>
</app-chat-messages>
```
Plugin touchpoints:
- `api.ui.registerComposerAction()` adds composer actions.
- `api.ui.registerEmbedRenderer()` renders declared custom embed payloads.
- `api.ui.mountElement()` can mount into a selector such as `app-chat-messages` when the plugin has `ui.dom`.
## Voice Area
Voice UI is split between channel membership, controls, and media workspace.
```html
<app-rooms-side-panel>
<section>Voice Channels</section>
</app-rooms-side-panel>
<app-voice-controls></app-voice-controls>
<app-floating-voice-controls></app-floating-voice-controls>
<app-voice-workspace>
<app-voice-workspace-stream-tile></app-voice-workspace-stream-tile>
</app-voice-workspace>
```
Plugin touchpoints:
- `api.media.playAudioClip()` plays local audio.
- `api.media.addCustomAudioStream()` contributes audio to voice handling.
- `api.media.addCustomVideoStream()` contributes a video stream.
- `api.channels.addAudioChannel()` creates a voice channel entry when the plugin has channel management rights.
## Plugin Store and Manager DOM
```html
<app-plugin-store>
<!-- source management, search, plugin cards, install/update/uninstall actions -->
</app-plugin-store>
<app-plugin-manager>
<!-- installed plugins, capability grants, activate/reload/unload, logs, docs -->
</app-plugin-manager>
```
Plugin pages registered through `api.ui.registerAppPage()` render at `/plugins/:pluginId/:pageId`:
```html
<app-plugin-page-host>
<app-plugin-render-host></app-plugin-render-host>
</app-plugin-page-host>
```
## Plugin Render Host
`PluginRenderHostComponent` accepts plugin render functions that return either an `HTMLElement` or a string. Returning an `HTMLElement` is preferred for interactive UI. Returned strings are rendered as simple text content.
## Stable Selectors for Tests and Plugins
Prefer plugin APIs over DOM selectors. When direct DOM mounting is necessary, use stable app selectors and keep cleanup through the returned disposable.
Common targets:
| Selector | Area |
| --- | --- |
| `body` | Global overlays or modals. |
| `app-chat-messages` | Main text channel surface. |
| `app-rooms-side-panel` | Server side panel. |
| `[data-testid="plugin-room-side-panel"]` | Plugin side-panel area in the server sidebar. |
Avoid depending on Tailwind utility classes; they are layout details and may change.

1432
docs-site/docs/developer/llm-plugin-builder-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

300
docs-site/docs/developer/rest-api.md Normal file
View File

@@ -0,0 +1,300 @@
---
sidebar_position: 4
---
# Local REST API
The MetoYou desktop app exposes an optional local HTTP API for scripts and tools. It is implemented in Electron and reads local desktop data.
## Enable the API
1. Open Settings.
2. Open Local API settings.
3. Enable the local server.
4. Choose a port. The default is `17878`.
5. Add trusted signaling server URLs for authentication.
6. Enable Scalar docs if you want `/docs`.
7. Enable Docusaurus docs if you want `/docusaurus`.
By default the server binds to `127.0.0.1`. Only enable LAN exposure when you understand the risk.
## Authentication
Protected routes require a bearer token. Get one by posting username, password, and an allowed signaling server URL.
```bash
curl -s http://127.0.0.1:17878/api/auth/login \
-H 'Content-Type: application/json' \
-d '{
"username": "alice",
"password": "correct horse battery staple",
"serverUrl": "https://tojusignal.example.com"
}'
```
Example response:
```json
{
"token": "local_4cddf95c5b8c4b6f9e0c",
"expiresAt": 1777477200000,
"user": {
"id": "user-alice-01",
"username": "alice",
"displayName": "Alice"
}
}
```
Use the token:
```bash
curl -s http://127.0.0.1:17878/api/profile \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
Logout revokes the current token:
```bash
curl -i -X POST http://127.0.0.1:17878/api/auth/logout \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
## OpenAPI and Scalar
| Route | Auth | Purpose |
| --- | --- | --- |
| `GET /api/openapi.json` | No | OpenAPI 3.1 document. |
| `GET /docs` | No | Scalar API reference when enabled. |
## Public Routes
### GET /api/health
Checks whether the local API server is running.
```bash
curl -s http://127.0.0.1:17878/api/health
```
Example response:
```json
{
"status": "ok",
"version": "1.0.0",
"timestamp": 1777473600000,
"exposeOnLan": false
}
```
### GET /api/openapi.json
Returns the machine-readable API document.
```bash
curl -s http://127.0.0.1:17878/api/openapi.json
```
### POST /api/auth/login
Issues a local bearer token after credentials are validated by an allowed signaling server.
Request body:
```json
{
"username": "alice",
"password": "correct horse battery staple",
"serverUrl": "https://tojusignal.example.com"
}
```
Common errors:
| Status | Error code | Meaning |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | Missing username, password, or server URL. |
| 403 | `NO_ALLOWED_SERVERS` | No allowed signaling servers are configured. |
| 403 | `SERVER_NOT_ALLOWED` | The server URL is not in the allowed list. |
| 401 | `INVALID_CREDENTIALS` | Signaling server rejected the login. |
| 502 | `UPSTREAM_UNREACHABLE` | The signaling server could not be reached. |
## Protected Routes
All routes below require:
```http
Authorization: Bearer local_4cddf95c5b8c4b6f9e0c
```
### GET /api/profile
Reads the current local user profile.
```bash
curl -s http://127.0.0.1:17878/api/profile \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET /api/rooms
Lists rooms known to this device.
```bash
curl -s http://127.0.0.1:17878/api/rooms \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}`
Reads one room by id.
```bash
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75 \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}/users`
Lists users known for a room.
```bash
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/users \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}/messages`
Lists local messages for a room. `limit` defaults to `100` and is clamped from `1` to `500`. `offset` defaults to `0`.
```bash
curl -s 'http://127.0.0.1:17878/api/rooms/room-7ebdde75/messages?limit=50&offset=0' \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}/messages/since`
Lists local messages after a required timestamp.
```bash
curl -s 'http://127.0.0.1:17878/api/rooms/room-7ebdde75/messages/since?sinceTimestamp=1777470000000' \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}/bans`
Lists active bans for a room.
```bash
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/bans \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/rooms/{roomId}/bans/{userId}`
Checks whether a user is banned in a room.
```bash
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/bans/user-muse-01 \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
Example response:
```json
{ "isBanned": false }
```
### GET `/api/messages/{messageId}`
Reads one local message by id.
```bash
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001 \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/messages/{messageId}/reactions`
Lists reactions for a message.
```bash
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001/reactions \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/messages/{messageId}/attachments`
Lists attachments for a message.
```bash
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001/attachments \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET `/api/users/{userId}`
Reads one user by id.
```bash
curl -s http://127.0.0.1:17878/api/users/user-muse-01 \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET /api/attachments
Lists all attachments stored on this device.
```bash
curl -s http://127.0.0.1:17878/api/attachments \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
### GET /api/plugin-data
Reads a plugin data value from the local desktop database. `scope` must be `local` or `server`. Provide `serverId` when reading server-scoped data.
```bash
curl -s 'http://127.0.0.1:17878/api/plugin-data?pluginId=example.soundboard&key=favorites&scope=server&serverId=room-7ebdde75' \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
Example response:
```json
{
"value": [
{ "label": "Chime", "url": "https://cdn.example.com/chime.wav" }
]
}
```
### GET `/api/meta/{key}`
Reads a desktop metadata value by key.
```bash
curl -s http://127.0.0.1:17878/api/meta/metoyou_currentUserId \
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
```
Example response:
```json
{
"key": "metoyou_currentUserId",
"value": "user-alice-01"
}
```
## Data Model Notes
Rooms, users, messages, reactions, attachments, and bans are returned from local desktop persistence. Many schemas allow additional properties because the local database can carry richer app state than the REST docs need to guarantee.
## Security Notes
- Keep the API bound to `127.0.0.1` unless LAN access is required.
- Only add signaling servers you trust to the allowed list.
- Bearer tokens are local to the running desktop app.
- Stop the local API server to clear issued tokens.