Platform Stream Debuggers

CLI tools for inspecting live platform event streams in real time. Each debugger connects directly to a platform's streaming API, subscribes to all event types, and prints every incoming event with its type, timestamp, and payload.

Both tools read credentials from the database using the same config as the API server.

Shared Prerequisites

• The API database must be accessible (PostgreSQL)
• A valid channel_connection must exist for the account on the target platform
• The token_encryption_key in the config must match the key used to encrypt stored tokens
• The API's Token Refresh Worker should be running (just dev-api) to keep tokens fresh

Shared Options

Flag	Description
--account <uuid>	Required. Account UUID whose credentials to use.
--config <path>	Config directory with config/default.toml and config/local.toml. Defaults to apps/api.
--raw	Print full raw output for every event.

Troubleshooting

Symptom	Cause
"configuration file not found"	Run from repo root or use --config apps/api
"Failed to get token: invalid key length"	token_encryption_key is empty or missing in config
"Failed to get token: decryption failed"	token_encryption_key does not match the key used to encrypt stored tokens
"invalid authentication credentials"	Token is expired — ensure the Token Refresh Worker is running

---

YouTube gRPC Debugger

Connects to YouTube's liveChatMessages.streamList gRPC API and prints every incoming chat message and event.

Usage

cargo run -p lumio-api --bin grpc-debug -- --account <uuid>

# Explicit live chat ID (skip broadcast discovery)
cargo run -p lumio-api --bin grpc-debug -- --account <uuid> --live-chat-id <id>

Additional Options

Flag	Description
--live-chat-id <id>	Skip broadcast discovery and connect directly to this chat.

How It Works

1. Looks up the YouTube channel_connection for the account
2. Decrypts the OAuth access token from the database
3. Discovers active broadcasts via the YouTube Data API (or uses --live-chat-id)
4. Opens a gRPC streamList connection and prints every incoming item
5. On disconnect, fetches a fresh token and reconnects automatically

Output

[resp #1] items=42 next_page=true offline=false
  [0] TextMessageEvent | id=abc123 | 2026-05-05T12:00:00Z | Username (UC...)
       text: Hello world
       detail: text: Some("Hello world")
  [1] SuperChatEvent | id=def456 | 2026-05-05T12:01:00Z | Supporter (UC...)
       text: Great stream!
       detail: amount: Some(5000000) Some("EUR")

Unknown event types show their numeric value with automatic raw output:

  [0] UNKNOWN(25) | id=xyz789 | 2026-05-05T12:02:00Z | ? (?)
       raw: LiveChatMessage { ... }

YouTube Event Types

Type	Description
TextMessageEvent	Regular chat message
SuperChatEvent	Paid Super Chat
SuperStickerEvent	Paid Super Sticker
NewSponsorEvent	New channel member
MemberMilestoneChatEvent	Membership anniversary message
MembershipGiftingEvent	Gift memberships sent
GiftMembershipReceivedEvent	Gift membership received
MessageDeletedEvent	Message deleted by moderator
MessageRetractedEvent	Message retracted by author
UserBannedEvent	User banned (permanent or temporary)
PollEvent	Chat poll
ChatEndedEvent	Stream ended
SponsorOnlyModeStartedEvent	Members-only mode enabled
SponsorOnlyModeEndedEvent	Members-only mode disabled
Tombstone	Deleted message placeholder
FanFundingEvent	Legacy fan funding

---

Twitch EventSub Debugger

Connects to Twitch's EventSub WebSocket, subscribes to all event types for the account's channel, and prints every incoming notification.

Usage

cargo run -p lumio-api --bin eventsub-debug -- --account <uuid>

How It Works

1. Looks up the Twitch channel_connection and app_credentials for the account
2. Decrypts the OAuth access token and client ID from the database
3. Connects to the EventSub WebSocket and receives a session ID
4. Subscribes to all event types via the Helix API
5. Prints every incoming event with type, user, and a human-readable summary
6. On disconnect, fetches a fresh token and reconnects automatically
7. Handles Twitch session reconnects (30-second handover)

Output

[eventsub] Connected (session: abc123)
[eventsub] Subscribed to 25 event types
[#1] 14:32:05 | channel.chat.message | Username
       chat: Hello everyone!
[#2] 14:32:08 | channel.follow | NewFollower
       new follower
[#3] 14:32:15 | channel.subscribe | Subscriber
       tier 1000 sub
[#4] 14:33:01 | channel.raid | OtherStreamer
       raid with 150 viewers
[#5] 14:33:45 | channel.ban | ModName
       timeout: spam
[#6] 14:34:00 | stream.offline |
       stream went OFFLINE

Twitch Event Types

Type	Description
channel.chat.message	Chat message
channel.chat.notification	Sub, resub, gift sub, raid notice in chat
channel.follow	New follower
channel.subscribe	New subscription
channel.subscription.gift	Gift subscriptions
channel.subscription.message	Resub message
channel.cheer	Bits cheer
channel.raid	Incoming raid
channel.ban	User banned or timed out
channel.unban	User unbanned
channel.moderate	Moderator action
channel.channel_points_custom_reward_redemption.add	Channel point redemption
channel.poll.begin/progress/end	Poll lifecycle
channel.prediction.begin/progress/lock/end	Prediction lifecycle
channel.hype_train.begin/progress/end	Hype train lifecycle
channel.goal.begin/progress/end	Goal lifecycle
channel.update	Stream title/category change
channel.ad_break.begin	Ad break started
channel.suspicious_user.message	Suspicious user message
channel.suspicious_user.update	Suspicious user status change
stream.online	Stream went live
stream.offline	Stream ended