@engjts/nexus 0.1.0

package/documentation/ALERTS-INDEX.md

@@ -0,0 +1,330 @@
+# 📢 Alert System Documentation Index
+
+Sistem Alert di Nexus menggunakan **Adapter Pattern** untuk mendukung multiple notification channels secara modular dan extensible.
+
+---
+
+## 📚 Documentation Files
+
+### 1. **ALERTS-COMPLETE-SUMMARY.md** ⭐ START HERE
+**Untuk:** Overview lengkap project
+- Status implementation
+- Files yang dibuat/dimodifikasi
+- Features yang diimplementasikan
+- Quick start
+- Production checklist
+
+👉 **Baca ini terlebih dahulu untuk memahami apa yang sudah selesai**
+
+---
+
+### 2. **16-alerts-system.md**
+**Untuk:** Memahami Alert System secara menyeluruh
+- Overview & fitur utama
+- Quick start (3 langkah)
+- Configuration detailed
+- Alert channels explanation
+- Alert conditions
+- Using with Observability Middleware
+- Accessing alert data
+- Best practices
+- Troubleshooting
+
+👉 **Baca ini untuk memahami cara kerja Alert System**
+
+---
+
+### 3. **17-alert-adapters.md**
+**Untuk:** Custom adapters & advanced usage
+- Adapter Pattern overview (7 built-in adapters)
+  - Telegram ✨ NEW
+  - Discord ✨ NEW
+  - Slack
+  - Webhook
+  - Email
+  - PagerDuty
+  - Console
+- Creating custom adapters
+- Registering adapters
+- Multiple channels
+- Real-world patterns
+- Adapter registry API
+- Error handling
+
+👉 **Baca ini untuk membuat custom adapter atau advanced patterns**
+
+---
+
+### 4. **18-alerts-implementation-summary.md**
+**Untuk:** Technical details & architecture
+- Status: What's implemented
+- Built-in adapters table
+- Refactored AlertManager
+- Enhanced AlertingOptions
+- Comprehensive documentation files
+- How to use (quick start & multi-channel)
+- Architecture diagram
+- Files changed
+- Design decisions (Why adapter pattern?)
+- Production checklist
+
+👉 **Baca ini untuk memahami architecture & design decisions**
+
+---
+
+### 5. **ALERTS-QUICK-REFERENCE.md**
+**Untuk:** Quick lookup & copy-paste ready code
+- Setup channels (all 7)
+- Define alerts syntax
+- Usage patterns (dev, prod, multi-channel)
+- API methods
+- Custom adapter template
+- Environment variables
+- Debugging tips
+- Common issues table
+- Cooldown behavior
+
+👉 **Baca ini saat development untuk quick reference**
+
+---
+
+## 🎯 Quick Navigation
+
+| I want to... | Read... |
+|---|---|
+| Understand the complete project | ALERTS-COMPLETE-SUMMARY.md |
+| Learn Alert System basics | 16-alerts-system.md |
+| Create custom adapter | 17-alert-adapters.md |
+| Understand architecture | 18-alerts-implementation-summary.md |
+| Quick setup code | ALERTS-QUICK-REFERENCE.md |
+| See working examples | example-alerts.ts |
+
+---
+
+## 🚀 Getting Started Path
+
+### Path 1: I just want to use it (5 mins)
+1. Read: **ALERTS-QUICK-REFERENCE.md** (quick setup)
+2. Copy: **example-alerts.ts** pattern #1 or #2
+3. Done! ✅
+
+### Path 2: I want to understand it (20 mins)
+1. Read: **ALERTS-COMPLETE-SUMMARY.md** (overview)
+2. Read: **16-alerts-system.md** (complete guide)
+3. Skim: **ALERTS-QUICK-REFERENCE.md** (reference)
+4. Done! ✅
+
+### Path 3: I need custom adapter (30 mins)
+1. Read: **ALERTS-COMPLETE-SUMMARY.md** (overview)
+2. Read: **17-alert-adapters.md** (adapter details)
+3. Read: **example-alerts.ts** (example #3)
+4. Create your adapter
+5. Done! ✅
+
+### Path 4: I need to deploy (30 mins)
+1. Read: **ALERTS-COMPLETE-SUMMARY.md** (status)
+2. Read: **18-alerts-implementation-summary.md** (architecture)
+3. Check: **Production checklist** section
+4. Setup: **.env.example.alerts** variables
+5. Deploy! 🚀
+
+---
+
+## 📝 Documentation Statistics
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| ALERTS-COMPLETE-SUMMARY.md | ~400 | Overview & summary |
+| 16-alerts-system.md | 745 | Complete guide |
+| 17-alert-adapters.md | 696 | Adapter details |
+| 18-alerts-implementation-summary.md | 385 | Architecture |
+| ALERTS-QUICK-REFERENCE.md | 286 | Quick reference |
+| **Total** | **~2,512** | Comprehensive! |
+
+---
+
+## 🔧 Code Files
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| src/advanced/observability/adapters.ts | 304 | Adapter implementations |
+| src/advanced/observability/index.ts | MODIFIED | AlertManager refactored |
+| example-alerts.ts | 381 | 6 working examples |
+| .env.example.alerts | ~20 | Environment template |
+
+---
+
+## 🎁 What You Get
+
+### ✅ Production-Ready Implementation
+- 7 built-in adapters (Telegram, Discord, Slack, Webhook, Email, PagerDuty, Console)
+- Adapter Pattern for extensibility
+- Full error handling
+- Type-safe implementation
+
+### ✅ Comprehensive Documentation
+- 5 documentation files (~2,500 lines)
+- Quick reference card
+- Real-world examples
+- Architecture documentation
+
+### ✅ Ready-to-Use Examples
+- 6 complete example patterns
+- Environment variable template
+- Copy-paste ready code
+
+### ✅ Best Practices
+- Production checklist
+- Common patterns
+- Error handling guide
+- Troubleshooting section
+
+---
+
+## 🌟 Key Features
+
+- ✨ **Telegram Support** - NEW
+- ✨ **Discord Support** - NEW
+- ✅ Slack, Webhook, Email, PagerDuty (template)
+- ✅ Multiple channels per alert
+- ✅ Adapter pattern for custom channels
+- ✅ Alert condition evaluation
+- ✅ Cooldown to prevent spam
+- ✅ Alert history tracking
+- ✅ Config validation per adapter
+- ✅ Environment-aware setup
+
+---
+
+## 📖 How Documentation is Organized
+
+```
+ALERTS-COMPLETE-SUMMARY.md ← START HERE (Overview)
+        ↓
+    Choose your path...
+        ↓
+    ├─→ 16-alerts-system.md (Learn system)
+    ├─→ 17-alert-adapters.md (Advanced)
+    ├─→ 18-alerts-implementation-summary.md (Technical)
+    └─→ ALERTS-QUICK-REFERENCE.md (Lookup)
+        ↓
+    example-alerts.ts (Copy patterns)
+        ↓
+    .env.example.alerts (Setup env vars)
+        ↓
+    Deploy! 🚀
+```
+
+---
+
+## 🎓 Learning Resources
+
+### Beginner
+- Start: ALERTS-COMPLETE-SUMMARY.md
+- Then: ALERTS-QUICK-REFERENCE.md
+- Try: example-alerts.ts pattern #1
+
+### Intermediate
+- Read: 16-alerts-system.md (complete guide)
+- Understand: 18-alerts-implementation-summary.md
+- Try: example-alerts.ts patterns #2-#4
+
+### Advanced
+- Study: 17-alert-adapters.md (adapter pattern)
+- Create: Custom adapter
+- Try: example-alerts.ts pattern #3
+
+### Production Deployment
+- Check: Production checklist in ALERTS-COMPLETE-SUMMARY.md
+- Read: 18-alerts-implementation-summary.md
+- Setup: Environment variables from .env.example.alerts
+- Deploy: Your production setup
+
+---
+
+## ✅ Verification Checklist
+
+Before using in production, verify:
+
+- [ ] Read ALERTS-COMPLETE-SUMMARY.md
+- [ ] Understood adapter pattern
+- [ ] Chose notification channels
+- [ ] Copied example from example-alerts.ts
+- [ ] Set environment variables from .env.example.alerts
+- [ ] Tested with console adapter first
+- [ ] Tested with actual channel (Telegram/Discord/etc)
+- [ ] Checked production checklist
+- [ ] Ready to deploy! 🚀
+
+---
+
+## 🆘 Need Help?
+
+### If you want to...
+- **Understand the system** → Read 16-alerts-system.md
+- **Setup quickly** → Copy from ALERTS-QUICK-REFERENCE.md
+- **Create custom adapter** → Follow 17-alert-adapters.md
+- **Troubleshoot issue** → Check troubleshooting section
+- **See working code** → Check example-alerts.ts
+
+---
+
+## 📞 Quick Reference
+
+### Setup Telegram
+```typescript
+channels: {
+  telegram: {
+    botToken: process.env.TELEGRAM_BOT_TOKEN!,
+    chatId: process.env.TELEGRAM_CHAT_ID!
+  }
+}
+```
+
+### Setup Discord
+```typescript
+channels: {
+  discord: {
+    webhookUrl: process.env.DISCORD_WEBHOOK_URL!
+  }
+}
+```
+
+### Setup Multiple Channels
+```typescript
+channels: {
+  slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
+  telegram: { botToken: '...', chatId: '...' },
+  discord: { webhookUrl: '...' }
+}
+```
+
+👉 **For more details, see ALERTS-QUICK-REFERENCE.md**
+
+---
+
+## 📊 Documentation Coverage
+
+- ✅ Overview & summary
+- ✅ Quick start guide
+- ✅ Complete usage guide
+- ✅ Adapter pattern details
+- ✅ Custom adapter creation
+- ✅ Architecture & design
+- ✅ Production deployment
+- ✅ Troubleshooting guide
+- ✅ Code examples (6 patterns)
+- ✅ Environment setup
+- ✅ API reference
+- ✅ Best practices
+
+**Status: Comprehensively Documented** ✨
+
+---
+
+**Last Updated:** December 3, 2025
+**Status:** Production Ready 🚀
+**Version:** 1.0
+
+Start with **ALERTS-COMPLETE-SUMMARY.md** 👈
+

package/documentation/ALERTS-QUICK-REFERENCE.md

@@ -0,0 +1,286 @@
+# Alert System - Quick Reference
+
+## Setup Channels
+
+### Telegram
+```typescript
+channels: {
+  telegram: {
+    botToken: process.env.TELEGRAM_BOT_TOKEN!,
+    chatId: process.env.TELEGRAM_CHAT_ID!
+  }
+}
+```
+
+### Discord
+```typescript
+channels: {
+  discord: {
+    webhookUrl: process.env.DISCORD_WEBHOOK_URL!
+  }
+}
+```
+
+### Slack
+```typescript
+channels: {
+  slack: {
+    webhookUrl: process.env.SLACK_WEBHOOK_URL!
+  }
+}
+```
+
+### Webhook (Custom)
+```typescript
+channels: {
+  webhook: {
+    url: 'https://your-service.com/alerts'
+  }
+}
+```
+
+### Multiple Channels
+```typescript
+channels: {
+  slack: { webhookUrl: '...' },
+  telegram: { botToken: '...', chatId: '...' },
+  discord: { webhookUrl: '...' }
+}
+```
+
+---
+
+## Define Alerts
+
+### Basic Alert
+```typescript
+{
+  name: 'Alert Name',
+  condition: 'metric > threshold',
+  window: '5m',
+  threshold: 0.05,
+  channels: ['slack', 'telegram']
+}
+```
+
+### Condition Operators
+- `>` - Greater than
+- `<` - Less than
+- `>=` - Greater than or equal
+- `<=` - Less than or equal
+
+### Example Conditions
+```typescript
+'error_rate > 0.05'        // 5% errors
+'response_time > 1000'     // 1000ms
+'memory > 0.8'             // 80%
+'uptime < 1'               // 100% uptime
+'db_errors >= 10'          // 10+ errors
+```
+
+---
+
+## Usage Patterns
+
+### Development
+```typescript
+alerting: {
+  enabled: true,
+  channels: { console: {} },
+  alerts: [{
+    name: 'Test',
+    condition: 'value > 1',
+    window: '5m',
+    threshold: 1,
+    channels: ['console']
+  }]
+}
+```
+
+### Production (Multi-Channel)
+```typescript
+alerting: {
+  enabled: true,
+  channels: {
+    slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
+    telegram: { 
+      botToken: process.env.TELEGRAM_BOT_TOKEN!,
+      chatId: process.env.TELEGRAM_CHAT_ID!
+    },
+    discord: { webhookUrl: process.env.DISCORD_WEBHOOK_URL! }
+  },
+  alerts: [
+    // WARNING level
+    { name: 'High Memory', condition: 'memory > 0.7', window: '5m', threshold: 0.7, channels: ['slack'] },
+    // CRITICAL level
+    { name: 'Server Down', condition: 'uptime < 1', window: '1m', threshold: 1, channels: ['slack', 'telegram'] },
+    // EMERGENCY level
+    { name: 'Critical Error', condition: 'error_rate > 0.5', window: '1m', threshold: 0.5, channels: ['slack', 'telegram', 'discord'] }
+  ]
+}
+```
+
+---
+
+## API Methods
+
+### Check & Trigger Alert
+```typescript
+await observability.alertManager?.checkAndTrigger('Alert Name', value);
+```
+
+### Get Alert History
+```typescript
+const history = observability.getAlertHistory();
+// Returns: [{ alert, timestamp, value }, ...]
+```
+
+### Get Adapter Registry
+```typescript
+const registry = observability.alertManager?.getAdapterRegistry();
+
+// Get all adapters
+registry?.getNames();
+// ['slack', 'telegram', 'discord', 'webhook', 'email', 'pagerduty', 'console']
+
+// Check if adapter exists
+registry?.has('telegram');  // true
+
+// Register custom adapter
+registry?.register('custom', customAdapter);
+
+// Unregister adapter
+registry?.unregister('console');
+```
+
+---
+
+## Custom Adapter Template
+
+```typescript
+import { AlertChannelAdapter, AlertDefinition } from './nexus/advanced/observability';
+
+class MyCustomAdapter implements AlertChannelAdapter {
+  async send(alert: AlertDefinition, value: any, config: any): Promise<void> {
+    // Your implementation
+    console.log(`Alert: ${alert.name}, Value: ${value}`);
+  }
+
+  validate(config: any): boolean {
+    // Validate config
+    return !!config.someRequiredField;
+  }
+}
+
+// Register & use
+registry?.register('my-custom', new MyCustomAdapter());
+```
+
+---
+
+## Environment Variables Template
+
+```bash
+# Telegram
+TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
+TELEGRAM_CHAT_ID=YOUR_CHAT_ID
+
+# Slack
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+
+# Discord
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
+
+# Webhook
+WEBHOOK_URL=https://your-service.com/alerts
+
+# PagerDuty
+PAGERDUTY_ROUTING_KEY=your-routing-key
+
+# Email
+EMAIL_RECIPIENTS=admin@example.com,ops@example.com
+```
+
+---
+
+## Debugging
+
+### Test Alert Trigger
+```typescript
+// Manual trigger
+await observability.alertManager?.checkAndTrigger('Test Alert', 100);
+```
+
+### View Alert History
+```typescript
+const history = observability.getAlertHistory();
+console.log(history);
+```
+
+### Check Adapter Status
+```typescript
+const registry = observability.alertManager?.getAdapterRegistry();
+console.log('Available adapters:', registry?.getNames());
+```
+
+### Validate Channel Config
+```typescript
+const adapter = registry?.get('telegram');
+const isValid = adapter?.validate({
+  botToken: 'YOUR_TOKEN',
+  chatId: 'YOUR_CHAT_ID'
+});
+console.log('Config valid:', isValid);
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Alert not triggered | Check `enabled: true`, check condition, check threshold |
+| Config invalid | Validate using `adapter.validate(config)` |
+| Adapter not found | Register adapter: `registry?.register(name, adapter)` |
+| Network error | Check webhook URL, check internet connection |
+| Rate limited | Alerts have 60s cooldown to prevent spam |
+| Wrong channel | Check `channels` array in alert definition |
+
+---
+
+## Cooldown Behavior
+
+- Alert triggered → cooldown starts (60 seconds)
+- Same alert within 60s → ignored (prevented)
+- Different alert → triggered immediately
+- After 60s → can trigger again
+
+```typescript
+// Time: 0s
+await observability.alertManager?.checkAndTrigger('Alert A', 100);  // ✅ Triggered
+
+// Time: 5s
+await observability.alertManager?.checkAndTrigger('Alert A', 100);  // ❌ Ignored (cooldown)
+
+// Time: 61s
+await observability.alertManager?.checkAndTrigger('Alert A', 100);  // ✅ Triggered
+
+// Time: 66s
+await observability.alertManager?.checkAndTrigger('Alert B', 100);  // ✅ Different alert
+```
+
+---
+
+## Resources
+
+- **Full Documentation**: `documentation/16-alerts-system.md`
+- **Adapter Guide**: `documentation/17-alert-adapters.md`
+- **Implementation Summary**: `documentation/18-alerts-implementation-summary.md`
+- **Examples**: `example-alerts.ts`
+- **Source Code**: `src/advanced/observability/adapters.ts`
+
+---
+
+**Last Updated:** 2025-12-03
+**Status:** Production Ready ✅
+