chore: Fix app

2026-07-14 00:41:05 +02:00
parent 3e090933fd
commit edc4d935d8
98 changed files with 2878 additions and 155 deletions
@@ -0,0 +1,65 @@
+# Invites & Join Requests
+
+> **Status:** Active
+> **Last updated:** 2026-07-05
+
+## Overview
+
+Invite links and join-request approval let users join private or moderated chat-servers without public listing. Spans signaling **server** REST + HTML invite pages and the product **client** `server-directory` invite feature.
+
+## Responsibilities
+
+- Server: create time-limited invites, resolve invite metadata, record join requests, notify requesters on moderation decisions.
+- Client: create/copy invite links, render invite landing UX, call join API with invite codes/passwords.
+- It does NOT own: WebSocket room membership (`join_server` after REST join succeeds).
+
+## Key concepts
+
+- **Invite:** opaque id mapping to a server; may expire.
+- **Join request:** pending membership when server requires approval.
+- **request_update:** server-pushed WebSocket notification when a moderator approves/denies.
+
+## REST API
+
+### Invites
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| POST | `/api/servers/:id/invites` | Bearer | Create invite (moderator) |
+| GET | `/api/invites/:id` | Public | Resolve invite metadata + server card |
+| GET | `/invite/:id` | Public | HTML invite landing page (browser) |
+
+### Join
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| POST | `/api/servers/:id/join` | Bearer | Join with password, invite id, or public access; may create join request |
+
+### Join requests (moderation)
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| GET | `/api/servers/:id/requests` | Bearer (`manageServer`) | List pending requests |
+| PUT | `/api/requests/:id` | Bearer (`manageServer`) | Approve or deny; body `{ status }` |
+
+`PUT /api/requests/:id` validates optional `ownerId` matches authenticated user, checks `manageServer` permission, updates status, and sends `notifyUser(request.userId, { type: 'request_update', request })`.
+
+## Client flow
+
+1. Moderator creates invite via `ServerDirectoryFacade.createInvite()`.
+2. Recipient opens `/invite/:id` or deep link; client resolves `GET /api/invites/:id`.
+3. Authenticated user calls `POST /api/servers/:id/join` with invite payload.
+4. On approval-required servers, user waits for `request_update` or polls requests list (moderator UI).
+
+## Related
+
+- [server-directory.md](server-directory.md) — join/leave REST
+- [authentication.md](authentication.md) — bearer on mutations
+- [signaling.md](signaling.md) — `join_server` after join
+- Domain README: [`toju-app/src/app/domains/server-directory/README.md`](../../toju-app/src/app/domains/server-directory/README.md)
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-07-05 | Initial cross-context invite/join-request contract |