Add Types to Untyped Code

Add TypeScript types to this file. Rules: 1. Start with function signatures — parameters and return types 2. Add interface/type definitions for data structures 3. Use specific types, not 'any' — if you're unsure, use 'unknown' and add a TODO 4. Don't change any runtime behavior 5. Prefer interfaces over type aliases for objects [paste code]