Plan: Custom Analytics events and BigQuery export

docs/plans/analytics-bigquery-export.md

@@ -0,0 +1,50 @@
+# Plan — Custom Analytics events and BigQuery export
+
+- **Status:** Proposed
+- **Effort:** Small
+- **Firebase services:** Analytics, BigQuery export
+
+## Overview
+
+Instrument key user actions and enable the Firebase Analytics → BigQuery daily export, so cohort, funnel, and retention analysis can be run in SQL.
+
+## Custom events (initial)
+
+| Event | Params | Where |
+|-------|--------|-------|
+| `claim_success` | `monarch`, `region`, `points`, `isFirstOfDay` | `claim.dart` |
+| `claim_failed_quiz` | `monarch` | `claim.dart` |
+| `nearby_viewed` | `resultsCount` | `nearby.dart` |
+| `compass_viewed` | `sectorsShown` | `fuzzy_compass.dart` |
+| `friend_added` | `method: "uid"` | `friends_screen.dart` |
+| `leaderboard_viewed` | `period`, `friendsOnly` | `leaderboard_screen.dart` |
+| `james_line_shown` | `category` | `james_strip.dart` |
+| `streak_broken` | `previousStreak` | backend mirror |
+| `signup_complete` | `provider` | `register/` |
+
+## Implementation
+
+- `lib/services/analytics_service.dart` — typed wrapper over `firebase_analytics`.
+- Replace any direct `FirebaseAnalytics.instance.logEvent` calls with the wrapper.
+- Strictly validate param types and max-length per Google's limits.
+
+## BigQuery
+
+- Enable the linked BigQuery dataset in the Firebase console (1 ds per project, daily export).
+- Create a `views/` directory in the repo with SQL for common slices (DAU, funnel, claim density by region).
+- Document each view in `docs/analytics/`.
+
+## Privacy
+
+- Do not log PII in event params (no emails, no display names, no exact coordinates — use `region` outcode).
+- Add an opt-out toggle in settings; when off, call `setAnalyticsCollectionEnabled(false)`.
+
+## Rollout
+
+- Ship event wrapper first.
+- Enable BigQuery export when there is at least one view ready to consume it.
+
+## Risks
+
+- Event count inflation costs BQ storage — trim noisy events (e.g. `james_line_shown`) if volume is excessive.
+- Privacy review before adding new params containing user input.

lib/claim.dart

@@ -125,11 +125,14 @@ class _ClaimState extends State<Claim> with TickerProviderStateMixin {
         postboxes[entry.key as String] =
             Map<String, dynamic>.from(entry.value as Map);
       }
+      // Cloud Functions serialise JS numbers as either int or double;
+      // assigning a double to a typed int field throws, so normalise via num.
+      int asInt(dynamic v) => (v as num?)?.toInt() ?? 0;
       setState(() {
-        _count = counts['total'] ?? 0;
-        _maxPoints = points['max'] ?? 0;
-        _minPoints = points['min'] ?? 0;
-        _claimedToday = counts['claimedToday'] ?? 0;
+        _count = asInt(counts['total']);
+        _maxPoints = asInt(points['max']);
+        _minPoints = asInt(points['min']);
+        _claimedToday = asInt(counts['claimedToday']);
         _postboxes = postboxes;
         currentStage = _count > 0 ? ClaimStage.results : ClaimStage.empty;
       });

lib/nearby.dart

@@ -113,23 +113,26 @@ class _NearbyState extends State<Nearby> {
       final claimedCompass = data['claimedCompass'] != null
           ? Map<String, dynamic>.from(data['claimedCompass'] as Map)
           : <String, dynamic>{};
+      // Cloud Functions serialise JS numbers as either int or double; assigning
+      // a double to a typed int field throws, so normalise every count via num.
+      int asInt(dynamic v) => (v as num?)?.toInt() ?? 0;
       setState(() {
-        _count = counts['total'] ?? 0;
-        _maxPoints = pts['max'] ?? 0;
-        _minPoints = pts['min'] ?? 0;
+        _count = asInt(counts['total']);
+        _maxPoints = asInt(pts['max']);
+        _minPoints = asInt(pts['min']);
         currentStage = NearbyStage.results;
         for (final dir in const [
           'N', 'NNE', 'NE', 'ENE', 'E', 'ESE',
           'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW',
           'W', 'WNW', 'NW', 'NNW',
         ]) {
-          _compassCounts[dir] = compass[dir] ?? 0;
-          _claimedCompassCounts[dir] = claimedCompass[dir] ?? 0;
+          _compassCounts[dir] = asInt(compass[dir]);
+          _claimedCompassCounts[dir] = asInt(claimedCompass[dir]);
         }
-        _claimedToday = counts['claimedToday'] ?? 0;
+        _claimedToday = asInt(counts['claimedToday']);
         for (final cipher in MonarchInfo.all) {
-          _cipherTotals[cipher] = counts[cipher] ?? 0;
-          _cipherClaimed[cipher] = counts['${cipher}_claimed'] ?? 0;
+          _cipherTotals[cipher] = asInt(counts[cipher]);
+          _cipherClaimed[cipher] = asInt(counts['${cipher}_claimed']);
         }
         _lastScanned = DateTime.now();
       });

lib/wear/wear_claim_page.dart

@@ -52,8 +52,10 @@ class _WearClaimPageState extends State<WearClaimPage> {
       });
       if (!mounted) return;
       final counts = result.data['counts'] ?? {};
-      final total = (counts['total'] as int?) ?? 0;
-      final claimed = (counts['claimedToday'] as int?) ?? 0;
+      // Cloud Functions serialise JS numbers as either int or double; `as int?`
+      // would throw on a double, so normalise via num.
+      final total = (counts['total'] as num?)?.toInt() ?? 0;
+      final claimed = (counts['claimedToday'] as num?)?.toInt() ?? 0;
       _postboxes = Map<String, dynamic>.from(result.data['postboxes'] ?? {});
       setState(() {
         _count = total;

lib/wear/wear_compass_page.dart

@@ -75,8 +75,13 @@ class _WearCompassPageState extends State<WearCompassPage> {
       final counts = result.data['counts'] ?? {};
       final compassRaw = result.data['compass'] ?? {};
       setState(() {
-        _totalCount = (counts['total'] as int?) ?? 0;
-        _compassCounts = Map<String, int>.from(compassRaw);
+        // Cloud Functions serialise JS numbers as either int or double;
+        // `as int?` would throw on a double, so normalise via num.
+        _totalCount = (counts['total'] as num?)?.toInt() ?? 0;
+        _compassCounts = {
+          for (final e in (compassRaw as Map).entries)
+            e.key as String: (e.value as num).toInt(),
+        };
         _stage = _CompassStage.results;
       });
       // Haptic pulse to signal scan complete.
@@ -206,7 +211,13 @@ class _WearCompassPageState extends State<WearCompassPage> {
               angle: -rotation,
               child: CustomPaint(
                 size: Size(size, size),
-                painter: FuzzyCompassPainter(sectors: sectorValues),
+                // Pass rotation so the painter counter-rotates the 'N' label;
+                // otherwise it spins with the canvas and is unreadable whenever
+                // the watch is not pointing north.
+                painter: FuzzyCompassPainter(
+                  sectors: sectorValues,
+                  rotation: rotation,
+                ),
               ),
             ),
             // Centre count overlay (doesn't rotate)

lib/wear/wear_status_page.dart

@@ -18,10 +18,14 @@ class WearStatusPage extends StatefulWidget {
 class _WearStatusPageState extends State<WearStatusPage> {
   final StreakService _streakService = StreakService();
   late final Stream<int?> _streakStream = _streakService.streakStream();
+  // Cache so the StreamBuilder doesn't re-subscribe (and briefly show empty
+  // stats) on every rebuild. Computed once in initState from the uid at mount.
+  late final Stream<DocumentSnapshot<Map<String, dynamic>>>? _userDocStream =
+      _buildUserDocStream();
 
   String? get _displayName => FirebaseAuth.instance.currentUser?.displayName;
 
-  Stream<DocumentSnapshot<Map<String, dynamic>>>? _userDocStream() {
+  Stream<DocumentSnapshot<Map<String, dynamic>>>? _buildUserDocStream() {
     final uid = FirebaseAuth.instance.currentUser?.uid;
     if (uid == null) return null;
     return FirebaseFirestore.instance.collection('users').doc(uid).snapshots();
@@ -71,7 +75,7 @@ class _WearStatusPageState extends State<WearStatusPage> {
 
               // Lifetime points
               StreamBuilder<DocumentSnapshot<Map<String, dynamic>>>(
-                stream: _userDocStream(),
+                stream: _userDocStream,
                 builder: (context, snap) {
                   final data = snap.data?.data();
                   final lifetimePoints =