feat(analytics): add privacy-first analytics tracking

Implement comprehensive analytics to track key user interactions
and system events while preserving user privacy.

- Introduce client-side `trackEvent` for page views and general events.
- Implement server-side tracking for seal creation, pulsing, and unlocking.
- Add `AnalyticsService` for managing and storing analytics data.
- Create new API routes (`/api/analytics`, `/api/stats`) and `SealCounter` component.
- Include database migration for analytics tables.
- Update documentation and `container` for D1 integration.

Author: teycir

ANALYTICS-COMPLETE.md

@@ -0,0 +1,70 @@
+# Analytics Implementation Complete ✅
+
+## What Was Done
+
+### 1. Database Migration ✅
+- Created `migrations/003_analytics.sql`
+- Added `analytics_events` table
+- Added `analytics_summary` table
+- Fixed SQL syntax (separate INDEX statements)
+- **Executed successfully on local D1**
+
+### 2. Service Layer ✅
+- Created `lib/analytics.ts`
+- `AnalyticsService` class with methods:
+  - `trackEvent()` - Track events
+  - `getSummary()` - Get daily summaries
+  - `getTotalSealsCreated()` - Get total count
+
+### 3. API Endpoints ✅
+- `POST /api/analytics` - Client-side event tracking
+- `GET /api/stats` - Public stats endpoint
+
+### 4. Server-Side Tracking ✅
+- `app/api/create-seal/route.ts` - Tracks `seal_created`
+- `app/api/seal/[id]/route.ts` - Tracks `seal_unlocked`
+- `app/api/pulse/route.ts` - Tracks `pulse_received`
+
+### 5. Client-Side Tracking ✅
+- `app/layout.tsx` - Inline script tracks `page_view`
+- `window.trackEvent()` function available globally
+
+### 6. UI Component ✅
+- `app/components/SealCounter.tsx` - Displays total seals
+- Added to homepage below tagline
+
+### 7. Documentation ✅
+- `docs/ANALYTICS.md` - Setup guide
+- `docs/README.md` - Added analytics link
+- `docs/TODO.md` - Updated checklist
+
+## Next Steps
+
+### For Production Deployment:
+```bash
+# Run migration on remote database
+npx wrangler d1 execute DB --file=migrations/003_analytics.sql --remote
+
+# Deploy updated code
+npm run deploy
+```
+
+### Verify It Works:
+```bash
+# Check stats endpoint
+curl https://your-domain.workers.dev/api/stats
+
+# Should return: {"totalSeals": 0}
+```
+
+## Features
+
+✅ Privacy-first (no cookies, no IPs, no personal data)
+✅ GDPR compliant by design
+✅ Zero cost (uses existing D1)
+✅ Zero external dependencies
+✅ Silent failures (never breaks app)
+✅ Social proof (seal counter on homepage)
+✅ Tracks: page views, seal creation, unlocks, pulses
+
+## Status: READY FOR PRODUCTION 🚀

app/api/analytics/route.ts

@@ -0,0 +1,40 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createAPIRoute } from '@/lib/routeHelper';
+import { AnalyticsService } from '@/lib/analytics';
+
+export const runtime = 'edge';
+
+const VALID_EVENT_TYPES = ['page_view', 'seal_created', 'seal_unlocked', 'pulse_received'];
+
+export async function POST(request: NextRequest) {
+  return createAPIRoute(async ({ container }) => {
+    try {
+      const body = await request.json();
+      const { eventType, path, referrer } = body;
+
+      // Validate event type
+      if (!eventType || !VALID_EVENT_TYPES.includes(eventType)) {
+        return NextResponse.json({ success: false, error: 'Invalid event type' }, { status: 400 });
+      }
+
+      // Validate path length
+      if (path && path.length > 500) {
+        return NextResponse.json({ success: false, error: 'Path too long' }, { status: 400 });
+      }
+
+      // Validate referrer length
+      if (referrer && referrer.length > 500) {
+        return NextResponse.json({ success: false, error: 'Referrer too long' }, { status: 400 });
+      }
+
+      const analytics = new AnalyticsService(container.db);
+      const country = request.headers.get('cf-ipcountry') || undefined;
+
+      await analytics.trackEvent({ eventType, path, referrer, country });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      console.error('[Analytics API] Error:', error);
+      return NextResponse.json({ success: false }, { status: 200 });
+    }
+  }, { rateLimit: { limit: 100, window: 60000 } })(request);
+}

app/api/create-seal/route.ts

@@ -88,6 +88,13 @@ export async function POST(request: NextRequest) {
         ip,
       );
 
+      // Track analytics
+      try {
+        const { AnalyticsService } = await import('@/lib/analytics');
+        const analytics = new AnalyticsService(container.db);
+        await analytics.trackEvent({ eventType: 'seal_created' });
+      } catch {}
+
       return jsonResponse({
         success: true,
         sealId: result.sealId,

app/api/pulse/route.ts

@@ -22,6 +22,13 @@ export async function POST(request: NextRequest) {
     const sealService = container.sealService;
     const result = await sealService.pulseSeal(pulseToken, ip, newInterval);
 
+    // Track analytics
+    try {
+      const { AnalyticsService } = await import('@/lib/analytics');
+      const analytics = new AnalyticsService(container.db);
+      await analytics.trackEvent({ eventType: 'pulse_received' });
+    } catch {}
+
     return jsonResponse({
       success: true,
       newUnlockTime: result.newUnlockTime,

app/api/seal/[id]/route.ts

@@ -68,6 +68,13 @@ export async function GET(
         const bytes = new Uint8Array(blob);
         const blobBase64 = btoa(String.fromCharCode(...bytes));
 
+        // Track analytics
+        try {
+          const { AnalyticsService } = await import('@/lib/analytics');
+          const analytics = new AnalyticsService(container.db);
+          await analytics.trackEvent({ eventType: 'seal_unlocked' });
+        } catch {}
+
         return jsonResponse({
           id: sealId,
           isLocked: false,

app/api/stats/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createAPIRoute } from '@/lib/routeHelper';
+import { AnalyticsService } from '@/lib/analytics';
+
+export const runtime = 'edge';
+
+export async function GET(request: NextRequest) {
+  return createAPIRoute(async ({ container }) => {
+    try {
+      const analytics = new AnalyticsService(container.db);
+      const totalSeals = await analytics.getTotalSealsCreated();
+      return NextResponse.json({ totalSeals });
+    } catch (error) {
+      console.error('[Stats API] Error:', error);
+      return NextResponse.json({ totalSeals: 0 }, { status: 200 });
+    }
+  }, { rateLimit: { limit: 100, window: 60000 } })(request);
+}

app/components/SealCounter.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { motion } from 'framer-motion';
+
+export function SealCounter() {
+  const [count, setCount] = useState<number | null>(null);
+
+  useEffect(() => {
+    fetch('/api/stats')
+      .then(res => res.json())
+      .then(data => setCount(data.totalSeals))
+      .catch(() => setCount(null));
+  }, []);
+
+  if (count === null || count === 0) return null;
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      className="text-center mt-4"
+    >
+      <div className="inline-flex items-center gap-2 px-4 py-2 bg-neon-green/5 border border-neon-green/20 rounded-lg">
+        <span className="text-neon-green/60 text-xs font-mono">SEALS CREATED:</span>
+        <span className="text-neon-green text-lg font-bold font-mono">{count.toLocaleString()}</span>
+      </div>
+    </motion.div>
+  );
+}

app/faq/page.tsx

@@ -35,13 +35,13 @@ export default function FAQPage() {
 
           <div>
             <h3 className="text-base sm:text-lg font-bold text-neon-green mb-2">How do I create a seal?</h3>
-            <p className="text-neon-green/60 text-sm mb-2"><strong className="text-neon-green">Timed Release:</strong> Enter message/file, select "Timed Release", choose unlock date (up to 30 days), complete security check, save vault link.</p>
-            <p className="text-neon-green/60 text-sm"><strong className="text-neon-green">Dead Man&apos;s Switch:</strong> Same as above but select "Dead Man&apos;s Switch", set pulse interval, save both vault link (public) and pulse link (private).</p>
+            <p className="text-neon-green/60 text-sm mb-2"><strong className="text-neon-green">Timed Release:</strong> Enter message/file, select &quot;Timed Release&quot;, choose unlock date (up to 30 days), complete security check, save vault link.</p>
+            <p className="text-neon-green/60 text-sm"><strong className="text-neon-green">Dead Man&apos;s Switch:</strong> Same as above but select &quot;Dead Man&apos;s Switch&quot;, set pulse interval, save both vault link (public) and pulse link (private).</p>
           </div>
 
           <div>
             <h3 className="text-base sm:text-lg font-bold text-neon-green mb-2">How does Dead Man&apos;s Switch work?</h3>
-            <p className="text-neon-green/60 text-sm">Set pulse interval (e.g., 7 days). Visit private pulse link before interval expires to reset timer. If you miss a pulse, seal auto-unlocks for recipient. Use pulse link to "burn" seal permanently.</p>
+            <p className="text-neon-green/60 text-sm">Set pulse interval (e.g., 7 days). Visit private pulse link before interval expires to reset timer. If you miss a pulse, seal auto-unlocks for recipient. Use pulse link to &quot;burn&quot; seal permanently.</p>
           </div>
 
           <div>
@@ -61,7 +61,7 @@ export default function FAQPage() {
 
           <div>
             <h3 className="text-base sm:text-lg font-bold text-neon-green mb-2">Can I cancel or delete a seal?</h3>
-            <p className="text-neon-green/60 text-sm">Dead Man&apos;s Switch seals can be burned (permanently destroyed) using the pulse token. Timed seals cannot be deleted.</p>
+            <p className="text-neon-green/60 text-sm">Dead Man&apos;s Switch seals can be &quot;burned&quot; (permanently destroyed) using the pulse token. Timed seals cannot be deleted.</p>
           </div>
 
           <div>

app/layout.tsx

@@ -103,6 +103,23 @@ export default function RootLayout({
         <StructuredData />
         <link rel="manifest" href="/manifest.json" />
         <meta name="theme-color" content="#00ff41" />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `
+              (function() {
+                if (typeof window === 'undefined') return;
+                window.trackEvent = function(type, data) {
+                  fetch('/api/analytics', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ eventType: type, ...data })
+                  }).catch(function() {});
+                };
+                window.trackEvent('page_view', { path: window.location.pathname });
+              })();
+            `,
+          }}
+        />
       </head>
       <body className={`${jetbrainsMono.className} min-h-screen bg-dark-bg text-dark-text overflow-x-hidden selection:bg-neon-green/30 selection:text-neon-green`}>
         <ScrollProgress />

app/page.tsx

@@ -25,6 +25,7 @@ import { EncryptionProgress } from './components/EncryptionProgress';
 import { FloatingIcons } from './components/FloatingIcons';
 
 import { Bitcoin, ShieldAlert, Rocket, Gift, Scale, Paperclip, FileText, Trash2, AlertTriangle, Download } from 'lucide-react';
+import { SealCounter } from './components/SealCounter';
 
 interface Template {
   name: string;
@@ -630,6 +631,7 @@ export default function HomePage() {
                 <AnimatedTagline text='"If I go silent, this speaks for me."' />
                 <p className="text-xs text-neon-green/30 max-w-md mx-auto">Encrypt messages that unlock at a future date or after inactivity</p>
                 <p className="text-xs text-yellow-500/50 max-w-md mx-auto mt-2">⚠️ Seals auto-delete 30 days after unlock</p>
+                <SealCounter />
               </motion.div>
 
               <Card className="space-y-6">