352 lines
9.2 KiB
Markdown
352 lines
9.2 KiB
Markdown
# PR Preparation: GramJS Phase 1 - Telegram User Account Adapter
|
|
|
|
**Status:** ✅ Ready for PR submission
|
|
**Branch:** `fix/cron-systemevents-autonomous-execution`
|
|
**Commit:** `84c1ab4d5`
|
|
**Target:** `openclaw/openclaw` main branch
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Implements **Telegram user account support** via GramJS/MTProto, allowing openclaw agents to access personal Telegram accounts (DMs, groups, channels) without requiring a bot.
|
|
|
|
**Closes:** #937 (Phase 1)
|
|
|
|
---
|
|
|
|
## What's Included
|
|
|
|
### ✅ Complete Implementation
|
|
- **18 files** added/modified
|
|
- **3,825 lines** of new code
|
|
- **2 test files** with comprehensive coverage
|
|
- **14KB documentation** with setup guide, examples, troubleshooting
|
|
|
|
### Core Features
|
|
- ✅ Interactive auth flow (phone → SMS → 2FA)
|
|
- ✅ Session persistence via encrypted StringSession
|
|
- ✅ DM message send/receive
|
|
- ✅ Group message send/receive
|
|
- ✅ Reply context preservation
|
|
- ✅ Multi-account configuration
|
|
- ✅ Security policies (pairing, allowlist, dmPolicy, groupPolicy)
|
|
- ✅ Command detection (`/start`, `/help`, etc.)
|
|
|
|
### Test Coverage
|
|
- ✅ Auth flow tests (mocked readline and client)
|
|
- ✅ Message conversion tests (DM, group, reply)
|
|
- ✅ Phone validation tests
|
|
- ✅ Session verification tests
|
|
- ✅ Edge case handling (empty messages, special chars, long text)
|
|
|
|
### Documentation
|
|
- ✅ Complete setup guide (`docs/channels/telegram-gramjs.md`)
|
|
- ✅ Getting API credentials walkthrough
|
|
- ✅ Configuration examples (single/multi-account)
|
|
- ✅ Security best practices
|
|
- ✅ Troubleshooting guide
|
|
- ✅ Migration from Bot API guide
|
|
|
|
---
|
|
|
|
## Files Changed
|
|
|
|
### Core Implementation (`src/telegram-gramjs/`)
|
|
```
|
|
auth.ts - Interactive auth flow (142 lines)
|
|
auth.test.ts - Auth tests with mocks (245 lines)
|
|
client.ts - GramJS client wrapper (244 lines)
|
|
config.ts - Config adapter (218 lines)
|
|
gateway.ts - Gateway adapter (240 lines)
|
|
handlers.ts - Message handlers (206 lines)
|
|
handlers.test.ts - Handler tests (367 lines)
|
|
setup.ts - CLI setup wizard (199 lines)
|
|
types.ts - Type definitions (47 lines)
|
|
index.ts - Module exports (33 lines)
|
|
```
|
|
|
|
### Configuration
|
|
```
|
|
src/config/types.telegram-gramjs.ts - Config schema (237 lines)
|
|
```
|
|
|
|
### Plugin Extension
|
|
```
|
|
extensions/telegram-gramjs/index.ts - Plugin registration (20 lines)
|
|
extensions/telegram-gramjs/src/channel.ts - Channel plugin (275 lines)
|
|
extensions/telegram-gramjs/openclaw.plugin.json - Manifest (8 lines)
|
|
extensions/telegram-gramjs/package.json - Dependencies (9 lines)
|
|
```
|
|
|
|
### Documentation
|
|
```
|
|
docs/channels/telegram-gramjs.md - Complete setup guide (14KB, 535 lines)
|
|
GRAMJS-PHASE1-SUMMARY.md - Implementation summary (1.8KB)
|
|
```
|
|
|
|
### Registry
|
|
```
|
|
src/channels/registry.ts - Added telegram-gramjs to CHAT_CHANNEL_ORDER
|
|
```
|
|
|
|
---
|
|
|
|
## Breaking Changes
|
|
|
|
**None.** This is a new feature that runs alongside existing channels.
|
|
|
|
- Existing `telegram` (Bot API) adapter **unchanged**
|
|
- Can run both `telegram` and `telegram-gramjs` simultaneously
|
|
- No config migration required
|
|
- Opt-in feature (disabled by default)
|
|
|
|
---
|
|
|
|
## Testing Checklist
|
|
|
|
### Unit Tests ✅
|
|
- [x] Auth flow with phone/SMS/2FA (mocked)
|
|
- [x] Phone number validation
|
|
- [x] Session verification
|
|
- [x] Message conversion (DM, group, reply)
|
|
- [x] Session key routing
|
|
- [x] Command extraction
|
|
- [x] Edge cases (empty messages, special chars, long text)
|
|
|
|
### Integration Tests ⏳
|
|
- [ ] End-to-end auth flow (requires real Telegram account)
|
|
- [ ] Message send/receive (requires real Telegram account)
|
|
- [ ] Multi-account setup (requires multiple accounts)
|
|
- [ ] Gateway daemon integration (needs openclaw built)
|
|
|
|
**Note:** Integration tests require real Telegram credentials and are best done by maintainers.
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
### New Dependencies
|
|
- `telegram@^2.24.15` - GramJS library (MTProto client)
|
|
|
|
### Peer Dependencies (already in openclaw)
|
|
- Node.js 18+
|
|
- TypeScript 5+
|
|
- vitest (for tests)
|
|
|
|
---
|
|
|
|
## Documentation Quality
|
|
|
|
### Setup Guide (`docs/channels/telegram-gramjs.md`)
|
|
- 📋 Quick setup (4 steps)
|
|
- 📊 Feature comparison (GramJS vs Bot API)
|
|
- ⚙️ Configuration examples (single/multi-account)
|
|
- 🔐 Security best practices
|
|
- 🛠️ Troubleshooting (8 common issues)
|
|
- 📖 API reference (all config options)
|
|
- 💡 Real-world examples (personal/team/family setups)
|
|
|
|
### Code Documentation
|
|
- All public functions have JSDoc comments
|
|
- Type definitions for all interfaces
|
|
- Inline comments for complex logic
|
|
- Error messages are clear and actionable
|
|
|
|
---
|
|
|
|
## Known Limitations (Phase 1)
|
|
|
|
### Not Yet Implemented
|
|
- ⏳ Media support (photos, videos, files) - Phase 2
|
|
- ⏳ Voice messages - Phase 2
|
|
- ⏳ Stickers and GIFs - Phase 2
|
|
- ⏳ Reactions - Phase 2
|
|
- ⏳ Message editing/deletion - Phase 2
|
|
- ⏳ Channel messages - Phase 3
|
|
- ⏳ Secret chats - Phase 3
|
|
- ⏳ Mention detection in groups (placeholder exists)
|
|
|
|
### Workarounds
|
|
- Groups: `requireMention: true` is in config but not enforced (all messages processed)
|
|
- Media: Skipped for now (text-only)
|
|
- Channels: Explicitly filtered out
|
|
|
|
---
|
|
|
|
## Migration Path
|
|
|
|
### For New Users
|
|
1. Go to https://my.telegram.org/apps
|
|
2. Get `api_id` and `api_hash`
|
|
3. Run `openclaw setup telegram-gramjs`
|
|
4. Follow prompts (phone → SMS → 2FA)
|
|
5. Done!
|
|
|
|
### For Existing Bot API Users
|
|
Can run both simultaneously:
|
|
```json5
|
|
{
|
|
channels: {
|
|
telegram: { // Existing Bot API
|
|
enabled: true,
|
|
botToken: "..."
|
|
},
|
|
telegramGramjs: { // New user account
|
|
enabled: true,
|
|
apiId: 123456,
|
|
apiHash: "..."
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
No conflicts - separate accounts, separate sessions.
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
### ✅ Implemented
|
|
- Session string encryption (via gateway encryption key)
|
|
- DM pairing (default policy)
|
|
- Allowlist support
|
|
- Group policy enforcement
|
|
- Security checks before queueing messages
|
|
|
|
### ⚠️ User Responsibilities
|
|
- Keep session strings private (like passwords)
|
|
- Use strong 2FA on Telegram account
|
|
- Regularly review active sessions
|
|
- Use `allowFrom` in sensitive contexts
|
|
- Don't share API credentials publicly
|
|
|
|
### 📝 Documented
|
|
- Security best practices section in docs
|
|
- Session management guide
|
|
- Credential handling instructions
|
|
- Compromise recovery steps
|
|
|
|
---
|
|
|
|
## Rate Limits
|
|
|
|
### Telegram Limits (Documented)
|
|
- ~20 messages/minute per chat
|
|
- ~40-50 messages/minute globally
|
|
- Flood wait errors trigger cooldown
|
|
|
|
### GramJS Handling
|
|
- Auto-retry on `FLOOD_WAIT` errors
|
|
- Exponential backoff
|
|
- Configurable `floodSleepThreshold`
|
|
|
|
### Documentation
|
|
- Rate limit table in docs
|
|
- Best practices section
|
|
- Comparison with Bot API limits
|
|
|
|
---
|
|
|
|
## PR Checklist
|
|
|
|
- [x] Code follows openclaw patterns (studied existing telegram/whatsapp adapters)
|
|
- [x] TypeScript types complete and strict
|
|
- [x] JSDoc comments on public APIs
|
|
- [x] Unit tests with good coverage
|
|
- [x] Documentation comprehensive
|
|
- [x] No breaking changes
|
|
- [x] Git commit message follows convention
|
|
- [x] Files organized logically
|
|
- [x] Error handling robust
|
|
- [x] Logging via subsystem logger
|
|
- [x] Config validation in place
|
|
- [ ] Integration tests (requires real credentials - maintainer task)
|
|
- [ ] Performance testing (requires production scale - maintainer task)
|
|
|
|
---
|
|
|
|
## Commit Message
|
|
|
|
```
|
|
feat(telegram-gramjs): Phase 1 - User account adapter with tests and docs
|
|
|
|
Implements Telegram user account support via GramJS/MTProto (#937).
|
|
|
|
[Full commit message in git log]
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps (After Merge)
|
|
|
|
### Phase 2 (Media Support)
|
|
- Image/video upload and download
|
|
- Voice messages
|
|
- Stickers and GIFs
|
|
- File attachments
|
|
- Reactions
|
|
|
|
### Phase 3 (Advanced Features)
|
|
- Channel messages
|
|
- Secret chats
|
|
- Poll creation
|
|
- Inline queries
|
|
- Custom entity parsing (mentions, hashtags, URLs)
|
|
|
|
### Future Improvements
|
|
- Webhook support (like Bot API)
|
|
- Better mention detection
|
|
- Flood limit auto-throttling
|
|
- Session file encryption options
|
|
- Multi-device session sync
|
|
|
|
---
|
|
|
|
## Maintainer Notes
|
|
|
|
### Review Focus Areas
|
|
1. **Security:** Session string handling, encryption, allowlists
|
|
2. **Architecture:** Plugin structure, gateway integration, session routing
|
|
3. **Config Schema:** Backward compatibility, validation
|
|
4. **Error Handling:** User-facing messages, retry logic
|
|
5. **Documentation:** Clarity, completeness, examples
|
|
|
|
### Testing Recommendations
|
|
1. Test auth flow with real Telegram account
|
|
2. Test DM send/receive
|
|
3. Test group message handling
|
|
4. Test multi-account setup
|
|
5. Test session persistence across restarts
|
|
6. Test flood limit handling
|
|
7. Test error recovery
|
|
|
|
### Integration Points
|
|
- Gateway daemon (message polling)
|
|
- Config system (multi-account)
|
|
- Session storage (encryption)
|
|
- Logging (subsystem logger)
|
|
- Registry (channel discovery)
|
|
|
|
---
|
|
|
|
## Questions for Reviewers
|
|
|
|
1. **Session encryption:** Should we add option for separate encryption passphrase (vs using gateway key)?
|
|
2. **Mention detection:** Implement now or defer to Phase 2?
|
|
3. **Channel messages:** Support in Phase 1 or keep for Phase 3?
|
|
4. **Integration tests:** Add to CI or keep manual-only (requires Telegram credentials)?
|
|
|
|
---
|
|
|
|
## Contact
|
|
|
|
**Implementer:** Spotter (subagent of Clawd)
|
|
**Human:** Jakub (@oogway_defi)
|
|
**Issue:** https://github.com/openclaw/openclaw/issues/937
|
|
**Repo:** https://github.com/openclaw/openclaw
|
|
|
|
---
|
|
|
|
**Ready for PR submission! 🚀**
|