158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# OpenSpec Change: enterprise-gaming-chat
|
|
|
|
- **Change ID**: enterprise-gaming-chat
|
|
- **Package**: `@suaveplan/chat`
|
|
- **Category**: gaming/multiplayer
|
|
- **Target path**: `gaming/multiplayer/chat`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/chat.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/chat` on the genesis branch from scratch at enterprise quality. The package provides in-game chat with named channels, whispers, configurable rate limiting, and a profanity filter. A `ChatManager` maintains typed `ChatChannel` objects (global, local, party, trade, custom); messages are validated against rate limit before dispatch; a `ProfanityFilter` uses a blocklist with configurable mask character; a `WhisperRouter` routes directed messages between two players. Genesis adds Zod message schemas, structured errors, OTel message-rate counter, injectable clock, and 100% coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis yet — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `ChatError`; `CHAT.*` codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `Clock` |
|
|
| `@suaveplan/events` (`workspace:^`) | `chat:message`, `chat:whisper`, `chat:muted` events |
|
|
| `zod` (`catalog:forms`) | `ChatMessage`, `ChannelConfig` schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Messages-per-second counter |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
type ChannelType = 'global' | 'local' | 'party' | 'trade' | 'system' | 'custom'
|
|
|
|
interface ChannelConfig {
|
|
id: string
|
|
type: ChannelType
|
|
displayName: string
|
|
maxHistory?: number // message ring buffer size, default 100
|
|
rateLimitPerMin?: number // default 30
|
|
}
|
|
|
|
interface ChatMessage {
|
|
id: string
|
|
channelId: string
|
|
senderId: string
|
|
senderName: string
|
|
content: string
|
|
timestamp: number
|
|
filtered?: boolean
|
|
}
|
|
|
|
function createChatManager(options?: ChatManagerOptions): ChatManager
|
|
|
|
interface ChatManagerOptions {
|
|
profanityFilter?: ProfanityFilter
|
|
clock?: Clock
|
|
}
|
|
|
|
interface ChatManager {
|
|
createChannel(config: ChannelConfig): ChatChannel
|
|
getChannel(id: string): ChatChannel | undefined
|
|
deleteChannel(id: string): void
|
|
sendMessage(channelId: string, senderId: string, senderName: string, content: string): ChatMessage
|
|
whisper(fromId: string, fromName: string, toId: string, content: string): ChatMessage
|
|
mute(playerId: string, durationMs?: number): void
|
|
unmute(playerId: string): void
|
|
isMuted(playerId: string): boolean
|
|
tick(dt: number): void // expire mutes
|
|
}
|
|
|
|
interface ChatChannel {
|
|
readonly id: string
|
|
readonly config: ChannelConfig
|
|
getHistory(): ChatMessage[]
|
|
subscribe(playerId: string): void
|
|
unsubscribe(playerId: string): void
|
|
readonly subscribers: ReadonlySet<string>
|
|
}
|
|
|
|
// Profanity filter
|
|
function createProfanityFilter(blocklist: string[], options?: FilterOptions): ProfanityFilter
|
|
|
|
interface FilterOptions {
|
|
maskChar?: string // default '*'
|
|
mode?: 'mask' | 'block' // block throws, mask replaces
|
|
}
|
|
|
|
interface ProfanityFilter {
|
|
filter(text: string): { filtered: string; triggered: boolean }
|
|
addWord(word: string): void
|
|
removeWord(word: string): void
|
|
}
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type ChatErrorCode =
|
|
| 'CHAT_CHANNEL_NOT_FOUND'
|
|
| 'CHAT_RATE_LIMIT_EXCEEDED'
|
|
| 'CHAT_SENDER_MUTED'
|
|
| 'CHAT_CONTENT_BLOCKED'
|
|
| 'CHAT_RECIPIENT_NOT_FOUND'
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
gaming/multiplayer/chat/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/common.ts
|
|
types/common.md
|
|
core/
|
|
chat-manager/
|
|
chat-manager.ts
|
|
chat-manager.md
|
|
chat-manager.types.ts
|
|
chat-manager.test.ts
|
|
index.ts
|
|
chat-channel/
|
|
chat-channel.ts
|
|
chat-channel.md
|
|
chat-channel.types.ts
|
|
chat-channel.test.ts
|
|
index.ts
|
|
utils/
|
|
profanity-filter.ts
|
|
profanity-filter.md
|
|
profanity-filter.test.ts
|
|
rate-limiter.ts
|
|
rate-limiter.md
|
|
rate-limiter.test.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/react-social-game` renders chat panel. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.
|