docs: Add PR preparation checklist for GramJS Phase 1
This commit is contained in:
spiceoogway
parent
84c1ab4d55
commit
bd214dc061
351
PR-PREP-GRAMJS-PHASE1.md
Normal file
351
PR-PREP-GRAMJS-PHASE1.md
Normal file
@ -0,0 +1,351 @@
|
||||
# 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! 🚀**
|
||||
Loading…
Reference in New Issue
Block a user