@engjts/nexus 0.1.8 → 0.1.10

package/documentation/ALERTS-INDEX.md

@@ -1,330 +0,0 @@
-# 📢 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

@@ -1,286 +0,0 @@
-# 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 ✅
-