Feature: Integrate Twitch Chat and Real-time Features (EventSub, Stream Metadata)

## Summary

Integrate Twitch chat and real-time features to provide a comprehensive streaming experience within the ArkavoKit app. This includes bi-directional chat, real-time event notifications, stream metadata, and viewer analytics.

## Motivation

Currently, ArkavoKit supports RTMP streaming to Twitch, but lacks integration with Twitch's interactive features. To provide a complete streaming solution, we need to:

1. **Enable chat interaction** - Allow streamers to read and respond to chat messages
2. **Monitor stream health** - Display viewer count, stream status, and health metrics
3. **Receive real-time events** - Get notifications for subscriptions, follows, raids, etc.
4. **Moderate content** - Support chat moderation capabilities

## Proposed Implementation

### Phase 1: OAuth Authentication & API Foundation

**Authentication Flow:**
- Implement Twitch OAuth 2.0 user authentication
- Request appropriate scopes:
- `chat:read` - Read chat messages
- `chat:edit` - Send chat messages
- `channel:moderate` - Moderate chat
- `moderator:read:chatters` - Read chatters list
- `moderator:manage:chat_messages` - Delete messages via API
- Securely store access tokens and refresh tokens

**References:**
- [Getting OAuth Access Tokens](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/)
- [Twitch Access Token Scopes](https://dev.twitch.tv/docs/authentication/scopes/)

### Phase 2: Chat Integration via EventSub WebSocket

**EventSub WebSocket Connection:**
- Implement WebSocket client for EventSub chat
- Subscribe to chat-related events:
- `channel.chat.message` - Receive chat messages
- `channel.chat.notification` - Subscriptions, gifted subs, raids, etc.
- `channel.chat.clear` - Chat cleared by moderator
- `channel.chat.clear_user_messages` - User messages cleared/timed out

**Chat Message Handling:**
- Parse incoming chat messages (text, emotes, badges, color)
- Display messages in a clean, native SwiftUI chat view
- Support Twitch emotes rendering
- Show user badges (subscriber, moderator, VIP, etc.)

**Sending Chat Messages:**
- Use [Send Chat Message API](https://dev.twitch.tv/docs/api/reference#send-chat-message) endpoint
- Support reply-to-message functionality
- Handle rate limits appropriately

**Note:** As of 2025, Twitch PubSub is deprecated (decommissioned April 14, 2025). EventSub is the recommended approach.

**References:**
- [Chat & Chatbots Documentation](https://dev.twitch.tv/docs/chat/)
- [EventSub Documentation](https://dev.twitch.tv/docs/eventsub)
- [Twitch Chat on EventSub Announcement](https://discuss.dev.twitch.com/t/available-today-twitch-chat-on-eventsub-an-api-for-sending-chat-and-the-conduit-transport-method-for-eventsub/54596)
- [Migrating from Twitch IRC](https://dev.twitch.tv/docs/chat/irc-migration/)

### Phase 3: Stream Metadata & Analytics

**Helix API Integration:**
- Get stream information via `/helix/streams` endpoint
- Real-time viewer count
- Stream uptime
- Stream title and category
- Stream thumbnail
- Language
- Poll for updates every 30-60 seconds
- Display metrics in stream overlay or dashboard

**Stream Management:**
- Update stream title via `/helix/channels`
- Update stream category/game
- Create and manage stream markers

**References:**
- [Twitch API Reference](https://dev.twitch.tv/docs/api/reference)

### Phase 4: Additional EventSub Subscriptions

**Channel Events:**
- `channel.update` - Stream title/category changes
- `channel.follow` - New follower notifications
- `stream.online` - Stream went live
- `stream.offline` - Stream went offline

**Subscription Events:**
- `channel.subscribe` - New subscription
- `channel.subscription.gift` - Gifted subscription
- `channel.subscription.message` - Resub with message
- `channel.raid` - Incoming raid

**Moderation Events:**
- `channel.moderator.add` - Moderator added
- `channel.moderator.remove` - Moderator removed
- `channel.ban` - User banned
- `channel.unban` - User unbanned

**References:**
- [EventSub Subscription Types](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/)

## Technical Architecture

### Proposed Module Structure

```
Sources/ArkavoTwitch/
├── Authentication/
│ ├── TwitchOAuthManager.swift
│ └── TokenStorage.swift
├── API/
│ ├── TwitchAPIClient.swift (Helix API)
│ └── Models/
│ ├── StreamInfo.swift
│ ├── UserInfo.swift
│ └── ChatMessage.swift
├── EventSub/
│ ├── EventSubWebSocket.swift
│ ├── EventSubSubscriptions.swift
│ └── EventHandlers/
│ ├── ChatEventHandler.swift
│ └── ChannelEventHandler.swift
└── Chat/
├── ChatManager.swift
├── ChatMessageSender.swift
└── EmoteRenderer.swift
```

### SwiftUI Components

```
Sources/ArkavoUI/Twitch/
├── TwitchChatView.swift
├── TwitchMetricsView.swift
├── TwitchAuthenticationView.swift
└── Components/
├── ChatMessageRow.swift
├── EmoteImage.swift
└── StreamMetricsBadge.swift
```

## Swift Library Options

Consider integrating or learning from existing Swift Twitch libraries:

1. **swift-twitch-client** - WIP library supporting Chat, API, and EventSub
- [GitHub: LosFarmosCTL/swift-twitch-client](https://github.com/LosFarmosCTL/swift-twitch-client)

2. **SwiftTwitch** - Wrapper around Twitch API for iOS
- [GitHub: Chris-Perkins/SwiftTwitch](https://github.com/Chris-Perkins/SwiftTwitch)

3. **twitch-ios-sdk** - Lightweight Swift wrapper (100% Swift, no dependencies)
- [GitHub: oyvinddd/twitch-ios-sdk](https://github.com/oyvinddd/twitch-ios-sdk)

**Note:** Given our project's needs and existing architecture, implementing a custom solution may be preferable to ensure tight integration with ArkavoKit's streaming pipeline.

## UI/UX Considerations

### Chat Interface
- Bottom-docked chat panel (similar to Twitch Studio)
- Auto-scroll with "pause" on manual scroll
- Rich text rendering for emotes
- User mention autocomplete
- Command autocomplete (/ban, /timeout, etc.)
- Color-coded usernames
- Timestamps (optional)

### Stream Metrics Dashboard
- Live viewer count with trend indicator
- Peak viewers during stream
- Chat activity graph
- Recent followers/subscribers list
- Quick stream info editor (title/category)

### Notifications
- Toast notifications for key events (raids, large subs, etc.)
- Sound effects (configurable)
- On-screen alerts overlay

## Security & Privacy

1. **OAuth Token Storage:**
- Use Keychain for secure token storage on iOS/macOS
- Implement automatic token refresh
- Clear tokens on logout

2. **Rate Limiting:**
- Implement exponential backoff for API requests
- Respect Twitch rate limits (per the API documentation)
- Queue outgoing chat messages appropriately

3. **Data Privacy:**
- Only request necessary OAuth scopes
- Follow Twitch Developer Agreement
- Handle chat data responsibly (no logging sensitive info)

## Testing Strategy

1. **Unit Tests:**
- OAuth flow mocking
- EventSub message parsing
- Chat message formatting
- Rate limit handling

2. **Integration Tests:**
- EventSub WebSocket connection handling
- API request/response validation
- Token refresh flow

3. **Manual Testing:**
- Test with actual Twitch stream
- Verify chat messages send/receive correctly
- Validate moderation commands
- Stress test with high chat volume

## Dependencies

- Native Swift URLSession for HTTP/WebSocket
- SwiftUI for UI components
- Combine for reactive state management
- Swift Concurrency (async/await) for async operations

## Migration Path

Since Twitch deprecated PubSub (decommissioned April 14, 2025), ensure we:
- Build directly on EventSub (no legacy IRC/PubSub dependencies)
- Use modern WebSocket transport (not webhooks for mobile)
- Implement according to 2025+ best practices

## Success Criteria

- [ ] Users can authenticate with Twitch OAuth
- [ ] Users can read live chat messages
- [ ] Users can send chat messages from the app
- [ ] Real-time viewer count displays during stream
- [ ] Users receive notifications for subscriptions/follows/raids
- [ ] Chat moderation commands work (timeout, ban, delete)
- [ ] Emotes render correctly
- [ ] EventSub WebSocket auto-reconnects on disconnect
- [ ] Token refresh happens automatically
- [ ] All features work on both iOS and macOS

## References

### Official Documentation
- [Twitch Developer Documentation](https://dev.twitch.tv/docs)
- [EventSub Documentation](https://dev.twitch.tv/docs/eventsub)
- [Chat & Chatbots](https://dev.twitch.tv/docs/chat/)
- [Twitch API Reference](https://dev.twitch.tv/docs/api/reference)
- [Authentication Guide](https://dev.twitch.tv/docs/authentication/)
- [OAuth Scopes](https://dev.twitch.tv/docs/authentication/scopes/)

### Community Resources
- [EventSub WebSocket Announcement](https://discuss.dev.twitch.com/t/available-today-twitch-chat-on-eventsub-an-api-for-sending-chat-and-the-conduit-transport-method-for-eventsub/54596)
- [Migrating from Twitch IRC](https://dev.twitch.tv/docs/chat/irc-migration/)

## Related Issues

- None yet - this is the foundational Twitch integration issue

## Priority

**High** - This is a key differentiator for the streaming app and provides essential interactivity for streamers.

Begin by checking whether the proposed Sources/ArkavoTwitch/ and Sources/ArkavoUI/Twitch/ directories exist and how the current RTMP streaming integration is structured. Review the Twitch OAuth, EventSub, Helix API, and SwiftUI requirements before choosing a scope. Done would require the listed authentication, chat, metadata, event, moderation, reconnection, token-refresh, and iOS/macOS success criteria to work together.

Written by the indexing model from the issue text.