feat(telemetry): Add Sentry production monitoring and webhook alerts

.env.example

@@ -62,6 +62,14 @@ BAGS_SCORING_PRICE_IMPACT_PROBE_USDC_UNITS="10000000"
 # Keep commented out in development to use standard console log streams.
 # NEXT_PUBLIC_SENTRY_DSN="YOUR_SENTRY_DSN_URL"
 
+# TELEMETRY_ALERT_WEBHOOK_URL: Webhook URL (Discord, Slack, or webhook endpoint) for instant production alerts.
+# Never expose this variable to the client!
+# TELEMETRY_ALERT_WEBHOOK_URL="https://discord.com/api/webhooks/your-webhook-id/your-webhook-token"
+
+# NEXT_PUBLIC_RPC_LATENCY_ALERT_THRESHOLD_MS: Custom latency alert threshold in milliseconds.
+# Default: 10000 (10 seconds)
+# NEXT_PUBLIC_RPC_LATENCY_ALERT_THRESHOLD_MS="10000"
+
 # ── 5. Optional Indexers ──────────────────────────────────────────────────
 # SOLANA_INDEXER_URL: Enhanced token balance indexers (e.g. Helius API).
 # SOLANA_INDEXER_URL="https://api.helius.xyz/v0"

AGENTS.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **bagfi** (1900 symbols, 2712 relationships, 109 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **bagfi** (2413 symbols, 3637 relationships, 167 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **bagfi** (1900 symbols, 2712 relationships, 109 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **bagfi** (2413 symbols, 3637 relationships, 167 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

app/api/telemetry/alert/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server';
+import { sendAlert } from '@/lib/telemetry';
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    const { title, message, data } = body;
+
+    if (!title || !message) {
+      return NextResponse.json(
+        { error: 'Missing required parameters: title and message' },
+        { status: 400 }
+      );
+    }
+
+    // Call server-side alert dispatcher (this will trigger Webhook POST)
+    await sendAlert(title, message, data);
+
+    return NextResponse.json({ success: true });
+  } catch (error: any) {
+    return NextResponse.json(
+      { error: error.message || 'Failed to dispatch telemetry alert' },
+      { status: 500 }
+    );
+  }
+}

docs/progress.md

@@ -61,11 +61,22 @@ BagFi is a unified Web3 asset platform that consolidates fragmented crypto portf
 | **SOL7-01** | ✅ completed | Mocked Bags API and Solana transaction tests |
 | **SOL7-02** | ✅ completed | Smart Bag safety and compliance review checklist |
 | **SOL7-03** | ✅ completed | Solana/Bags launch readiness gate |
+| **P0-08** | ✅ completed | Production Sentry tracking and sliding-window webhook alerts |
 
 ---
 
 ## Log
 
+### 2026-05-25 — P0-08 completed
+- Integrated Sentry Next.js SDK for production-grade exception tracking in client, server, and edge runtimes.
+- Implemented real-time alert rules and thresholds in `lib/telemetry.ts`:
+  - Bags API Error Spikes: Triggers high-priority webhook alert on >= 3 failures (429 or 5xx) in a rolling 5-minute sliding window.
+  - Simulation Failures: Dispatches an immediate critical alert on failed Solana preflight simulations.
+  - RPC Latency Breaches: Alerts on confirmation latencies exceeding configured threshold (default 10,000ms).
+- Created secure Client-to-Server alert dispatcher `/api/telemetry/alert` preventing API webhook URL exposure to the frontend.
+- Added comprehensive testing with a 7-test Vitest suite in `test/telemetry.test.ts`.
+- Validation: Build and lint pass successfully, all 7 telemetry tests pass.
+
 ### 2026-05-19 — SOL5-02 completed
 - Finalized the "Creator Lab" with on-chain fee share configuration:
   - Added `createFeeShareConfigTransaction` to Bags API client.

docs/reports/p0-08-production-monitoring-execution.md

@@ -0,0 +1,86 @@
+# P0-08 Report: Add Production Monitoring and Alerts
+
+Date: 2026-05-25
+Task ID: P0-08
+Area: QA CI/CD Observability & Telemetry
+
+---
+
+## 1. Executive Summary
+
+This task successfully integrates production-grade telemetry, structured logging, and robust alerting thresholds to ensure the operational safety of the BagFi platform. We incorporated the Sentry Next.js SDK for comprehensive client, server, and edge exception tracking, and implemented intelligent threshold-based alert triggers inside the centralized `lib/telemetry.ts` file. 
+
+Furthermore, we established a secure server-side webhook dispatcher that sends alerts (e.g. to a Discord channel) and routes client-side events via a secure API proxy route, protecting webhook credentials from exposure to client bundles.
+
+---
+
+## 2. Technical Implementation Detail
+
+### Sentry SDK Integration
+- **SDK Dependencies**: Installed `@sentry/nextjs` to manage client, server, and edge monitoring.
+- **Runtimes Initialization**: Set up `sentry.client.config.ts`, `sentry.server.config.ts`, and `sentry.edge.config.ts` to initialize Sentry with traces sampling.
+- **Build Instrumentation**: Wrapped `nextConfig` in `next.config.ts` using `withSentryConfig` to auto-instrument routes and handle production source-map uploads.
+
+### Real-Time Alerting Rules & Thresholds
+1. **Bags.fm API Error Spikes (429/5xx)**:
+   - Tracked all Bags API requests within a sliding window of the last 10 requests.
+   - Triggers a high-priority system alert if **3 or more failures** (either `429` Rate Limited or `5xx` Server Error) occur in a rolling 5-minute window.
+   - Prevents alert spamming via an stateful active cooldown flag (`bagsSpikeAlertActive`), resetting only when errors clear.
+2. **Transaction Simulation Failures**:
+   - Triggers an **immediate critical alert** on any Solana pre-flight transaction simulation failure, attaching logs and error codes.
+3. **Solana RPC Latency Breaches**:
+   - Compares final transaction confirmation durations to a configurable limit (`NEXT_PUBLIC_RPC_LATENCY_ALERT_THRESHOLD_MS`, default `10,000ms`).
+   - Alerts and captures a Sentry warning if latency exceeds the specified limit.
+4. **Transaction Confirmation Failures**:
+   - Alerts on failed transaction statuses (`failed` or `timeout`).
+
+### Secure Client-Side Alert Proxy Route
+- Created **`app/api/telemetry/alert/route.ts`**:
+  - Securely accepts telemetry alert payloads from the frontend.
+  - Resolves environment variables and dispatches alerts directly from the server to the Discord Webhook (`TELEMETRY_ALERT_WEBHOOK_URL`).
+  - Keeps webhook integration tokens out of public client bundles.
+
+---
+
+## 3. Changes Made
+
+### Core files modified:
+- **[telemetry.ts](file:///Users/ekf/Downloads/Projects/bagfi/lib/telemetry.ts)**: Upgraded with Sentry capture bindings, sliding-window spike logic, latency checking, and webhook dispatching.
+- **[env.js](file:///Users/ekf/Downloads/Projects/bagfi/lib/env.js)**: Expanded validation schemas for recommended monitoring variables and secure server-only webhook warnings.
+- **[.env.example](file:///Users/ekf/Downloads/Projects/bagfi/.env.example)**: Added documentation for `NEXT_PUBLIC_SENTRY_DSN`, `TELEMETRY_ALERT_WEBHOOK_URL`, and `NEXT_PUBLIC_RPC_LATENCY_ALERT_THRESHOLD_MS`.
+- **[next.config.ts](file:///Users/ekf/Downloads/Projects/bagfi/next.config.ts)**: Wrapped exports using Sentry's wrapper.
+
+### New files added:
+- **[sentry.client.config.ts](file:///Users/ekf/Downloads/Projects/bagfi/sentry.client.config.ts)**: Client init.
+- **[sentry.server.config.ts](file:///Users/ekf/Downloads/Projects/bagfi/sentry.server.config.ts)**: Server init.
+- **[sentry.edge.config.ts](file:///Users/ekf/Downloads/Projects/bagfi/sentry.edge.config.ts)**: Edge init.
+- **[route.ts](file:///Users/ekf/Downloads/Projects/bagfi/app/api/telemetry/alert/route.ts)**: Client-side alert secure routing.
+- **[telemetry.test.ts](file:///Users/ekf/Downloads/Projects/bagfi/test/telemetry.test.ts)**: Comprehensive Vitest suite.
+- **[p0-08-production-monitoring.md](file:///Users/ekf/Downloads/Projects/bagfi/tasks/p0-08-production-monitoring.md)**: Local task tracker.
+
+---
+
+## 4. Verification and Test Results
+
+### Automated Test Suite
+Created `test/telemetry.test.ts` to cover all threshold alert cases. All tests passed with 100% success rate:
+```bash
+ ✓ test/telemetry.test.ts (7 tests) 9ms
+   - should dispatch alert webhook and capture exception on trackError
+   - should immediately alert and report to Sentry on Solana Simulation Failure
+   - should log normally on successful Solana simulation without alerting
+   - should trigger alert and Sentry on Solana transaction confirmation failure
+   - should trigger RPC Latency Breach alert if confirmation exceeds threshold limit
+   - should not trigger latency alert if confirmation is within threshold limits
+   - should trigger Bags API Spike alert only when error count reaches 3 in sliding window
+```
+
+Overall test run output:
+```bash
+ Test Files  7 passed (7)
+      Tests  33 passed (33)
+   Duration  1.44s
+```
+
+### Build Status
+Next.js production build (`npm run build`) and lint verification (`npm run lint`) passed successfully.

lib/env.js

@@ -20,7 +20,14 @@ const requiredBagsVars = [
 
 // Optional but recommended
 const recommendedVars = [
-  'NEXT_PUBLIC_SOLANA_WS_ENDPOINT'
+  'NEXT_PUBLIC_SOLANA_WS_ENDPOINT',
+  'NEXT_PUBLIC_SENTRY_DSN',
+  'NEXT_PUBLIC_RPC_LATENCY_ALERT_THRESHOLD_MS'
+];
+
+// Optional server-side only recommended vars
+const recommendedServerVars = [
+  'TELEMETRY_ALERT_WEBHOOK_URL'
 ];
 
 /**
@@ -117,13 +124,36 @@ export function validateEnvironment() {
     );
   }
 
-  // Security check: ensure BAGS_API_KEY is not client-side
-  if (typeof window !== 'undefined' && process.env.BAGS_API_KEY) {
-    console.error(
-      '🔒 SECURITY WARNING: BAGS_API_KEY appears to be exposed client-side!\n' +
-      '   This key must ONLY be used in server routes.\n' +
-      '   Remove it from NEXT_PUBLIC_ prefixed variables immediately.'
+  // Warn about recommended server-side vars ONLY on server
+  if (!isClient) {
+    const missingServerRec = recommendedServerVars.filter(
+      (key) => !process.env[key] || process.env[key].trim() === ''
     );
+    if (missingServerRec.length > 0) {
+      console.warn(
+        '⚠️  Missing recommended server-side environment variables:\n' +
+        missingServerRec.map(key => `  - ${key}`).join('\n') + '\n' +
+        '  Configure these for enhanced production monitoring and webhook alerts.\n'
+      );
+    }
+  }
+
+  // Security check: ensure sensitive keys are not client-side
+  if (typeof window !== 'undefined') {
+    if (process.env.BAGS_API_KEY) {
+      console.error(
+        '🔒 SECURITY WARNING: BAGS_API_KEY appears to be exposed client-side!\n' +
+        '   This key must ONLY be used in server routes.\n' +
+        '   Remove it from NEXT_PUBLIC_ prefixed variables immediately.'
+      );
+    }
+    if (process.env.TELEMETRY_ALERT_WEBHOOK_URL) {
+      console.error(
+        '🔒 SECURITY WARNING: TELEMETRY_ALERT_WEBHOOK_URL appears to be exposed client-side!\n' +
+        '   This key must ONLY be used in server environments/routes.\n' +
+        '   Remove it from client bundles immediately.'
+      );
+    }
   }
 }