Firebot Kick Integration Developer
Expert assistant for developing and maintaining the Firebot Kick.com integration - a TypeScript-based plugin that connects Firebot to the Kick live streaming platform.
What This Skill Does
Helps you work on the Firebot Kick integration codebase with deep understanding of:
Kick API integration patterns (OAuth, Pusher WebSockets, webhooks)Firebot extension architecture and IPC communicationEvent handling, effects, filters, and replacement variablesTypeScript conventions and testing strategies specific to this projectInstructions for AI Agent
Core Working Principles
1. **Concise Communication**
- Keep task summaries to 3 sentences maximum
- Do not create markdown documentation unless explicitly requested
- Focus on implementation over explanation
2. **When to Update CLAUDE.md**
Update the project's CLAUDE.md file only when:
- Implementing significant architectural changes or new features
- Discovering new patterns or learnings about the codebase
- Completing major milestones
- Establishing new testing patterns
- Finding optimizations or clarifying conventions
3. **Verification Steps**
After changes, always:
- Run `npm run build:dev` to verify compilation
- Check that `IntegrationDefinition` in `src/integration.ts` aligns with capabilities
- Test webhook handling with payloads from `test-payloads` directory
Project Architecture
**Tech Stack:** TypeScript, Jest, Webpack, AngularJS (frontend)
**Key Components:**
OAuth authentication with automatic token refreshPusher WebSocket for real-time chat integrationWebhook notifications for stream eventsChat effects, stream management effects, comprehensive event support**Integration Singleton:** `src/integration-singleton.ts` manages backend state and IPC communication
Critical IPC Communication Patterns
Firebot UI extensions use Electron IPC with strict synchronous/asynchronous patterns:
**Backend → Frontend Updates:** Use `frontendCommunicator.send()` for unsolicited updates**Frontend → Backend Sync:** Use `backendCommunicator.fireEventSync()` with backend `on()` handlers (returns values immediately)**Frontend → Backend Async:** Use `backendCommunicator.fireEvent()` with backend `onAsync()` handlers (returns Promises)**Never mix sync/async:** `fireEventSync()` with `onAsync()` hangs; `fireEvent()` with `on()` ignores return values**Serialization:** Electron cannot serialize `undefined` - use empty strings ("") or 0 for defaults**Auth URLs:** Must use synchronous `on()` + `fireEventSync()` pattern for immediate data returnWebhook Signature Verification
Two signature schemes:
**Production webhooks:** RSA-SHA256 (base64-encoded), input format: `${messageId}.${timestamp}.${JSON.stringify(payload)}`**Test webhooks:** Ed25519 (hex-encoded), input format: `JSON.stringify(payload)`Verification logic: `src/internal/webhook-handler/webhook-signature-verifier.ts`
User ID and Username Conventions
**User IDs:** Prefix Kick user IDs with 'k' (e.g., `k12345`)**Usernames:** Append '@kick' to Kick usernames (e.g., `username@kick`)Code Conventions
**Style:** camelCase for variables/functions, PascalCase for classes, follow ESLint rules**Logging:** Use `logger.debug` for observability, no emojis in logs or code comments**Kick Capitalization:** Always capitalize "Kick" (or lowercase "kick" in appropriate contexts)**Comments:** Explain "why" or act as section headers; avoid obvious comments or removal markers**Removals:** Delete completely - no backward compatibility unless instructed**Emojis:** Only in documentation using GitHub markdown syntax (`:white_check_mark:`)**No emdashes:** Not in code, comments, or documentationTesting Strategy
**Framework:** Jest
**Test Organization:** Place tests in `__tests__` subdirectory under the module being tested
**What to Test:**
Effects: Only the `onTriggerEvent` methodFilters: Only the `predicate` methodReplacement variables: Only the `evaluator` methodMust call actual implementation functions (not mocks) to be meaningfulMock data construction-only tests are insufficient**Coverage Areas:**
Isolated unit tests per componentEdge cases for state transitions and error handlingEvent parsing/validation for webhooks and WebSocket payloadsFunctional tests simulating real-world patterns (chat, event processing)API client endpoint communication and error scenariosKnown Limitations & Workarounds
Kick's public API is incomplete; some events require undocumented Pusher WebSocket serviceKick has a "private API" (not used) requiring CloudFlare protection bypassWebhook delivery can be delayed seconds or minutes`navigator.clipboard.writeText()` requires document focus - use `window.focus()` first with fallback to `document.execCommand('copy')`Use Angular's `$timeout` instead of native `setTimeout` in AngularJS controllersDocumentation
Format: Markdown in `doc/` directoryMust satisfy markdownlint rulesReference from `README.md`Reference Implementation
Consult `../firebot-mage-youtube-integration` for similar patterns and approaches.
Examples
**Adding a new event handler:**
```typescript
// 1. Define event type in kick-api-types submodule
// 2. Add event source in src/integration.ts
// 3. Implement handler in src/events/
// 4. Add tests in src/events/__tests__/
// 5. Update IntegrationDefinition
// 6. Run npm run build:dev
```
**Debugging IPC issues:**
Check if handler is sync (`on()`) or async (`onAsync()`)Verify frontend uses matching `fireEventSync()` or `fireEvent()`Ensure no `undefined` values in returned data**Testing webhook signatures:**
Use fixtures in `src/internal/webhook-handler/__fixtures__/`Test both production (RSA-SHA256) and test (Ed25519) schemesVerify signature input format matches webhook typeImportant Constraints
Do not use Kick's private API or attempt CloudFlare protection bypassBuild output must consolidate to single file via webpackAll logging must provide observability without emojisComplete removals - no deprecation shims unless explicitly required