feat(phase6): native responder app — Capacitor, telemetry, field workflows, roster ops

.gitignore

@@ -57,3 +57,5 @@ Thumbs.db
 # Worktrees
 .worktrees/
 worktrees/
+!apps/responder-app/ios/
+!apps/responder-app/android/

apps/admin-desktop/src/hooks/useAgencyAssistanceQueue.ts

@@ -0,0 +1,125 @@
+import { useEffect, useState } from 'react'
+import { collection, onSnapshot, query, where } from 'firebase/firestore'
+import { db } from '../app/firebase'
+import {
+  agencyAssistanceRequestDocSchema,
+  logDimension,
+  type AgencyAssistanceRequestDoc,
+} from '@bantayog/shared-validators'
+
+const log = logDimension('useAgencyAssistanceQueue')
+
+export interface BackupRequest {
+  id: string
+  reportId: string
+  municipalityId: string
+  reason: string
+  status: 'pending' | 'accepted' | 'declined' | 'fulfilled' | 'expired'
+  agencyId: string
+  createdAt: number
+}
+
+function parseBackupRequest(id: string, raw: Record<string, unknown>): BackupRequest | null {
+  if (
+    typeof raw.reportId !== 'string' ||
+    typeof raw.reason !== 'string' ||
+    typeof raw.agencyId !== 'string' ||
+    typeof raw.createdAt !== 'number'
+  ) {
+    log({
+      severity: 'WARNING',
+      code: 'backup_request.invalid',
+      message: `Invalid backup_request ${id}`,
+      data: {},
+    })
+    return null
+  }
+  return {
+    id,
+    reportId: raw.reportId,
+    municipalityId: typeof raw.municipalityId === 'string' ? raw.municipalityId : '',
+    reason: raw.reason,
+    status: typeof raw.status === 'string' ? (raw.status as BackupRequest['status']) : 'pending',
+    agencyId: raw.agencyId,
+    createdAt: raw.createdAt,
+  }
+}
+
+export function useAgencyAssistanceQueue(agencyId: string | undefined) {
+  const [requests, setRequests] = useState<(AgencyAssistanceRequestDoc & { id: string })[]>([])
+  const [backupRequests, setBackupRequests] = useState<BackupRequest[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    queueMicrotask(() => {
+      setError(null)
+      setRequests([])
+      setBackupRequests([])
+    })
+
+    if (!agencyId) {
+      queueMicrotask(() => {
+        setLoading(false)
+      })
+      return
+    }
+
+    queueMicrotask(() => {
+      setLoading(true)
+    })
+
+    const q = query(
+      collection(db, 'agency_assistance_requests'),
+      where('targetAgencyId', '==', agencyId),
+    )
+
+    const unsubscribe = onSnapshot(
+      q,
+      (snapshot) => {
+        const parsed = snapshot.docs.flatMap((doc) => {
+          const result = agencyAssistanceRequestDocSchema.safeParse(doc.data())
+          if (!result.success) {
+            log({
+              severity: 'WARNING',
+              code: 'agency_assistance.invalid',
+              message: `Doc ${doc.id} failed schema`,
+              data: {},
+            })
+            return []
+          }
+          return [{ ...result.data, id: doc.id }]
+        })
+        setRequests(parsed)
+        setLoading(false)
+      },
+      (err) => {
+        setError(err.message)
+        setLoading(false)
+      },
+    )
+
+    const backupQ = query(collection(db, 'backup_requests'), where('agencyId', '==', agencyId))
+
+    const unsubscribeBackup = onSnapshot(
+      backupQ,
+      (snapshot) => {
+        const parsed = snapshot.docs.flatMap((doc) => {
+          const req = parseBackupRequest(doc.id, doc.data() as Record<string, unknown>)
+          return req ? [req] : []
+        })
+        setBackupRequests(parsed)
+      },
+      () => {
+        // Backup request errors are non-fatal
+      },
+    )
+
+    return () => {
+      unsubscribe()
+      unsubscribeBackup()
+    }
+  }, [agencyId])
+
+  return { requests, backupRequests, loading, error }
+}

apps/admin-desktop/src/hooks/useEligibleResponders.ts

@@ -1,23 +1,41 @@
 import { useEffect, useState } from 'react'
 import { collection, onSnapshot, query, where } from 'firebase/firestore'
 import { db } from '../app/firebase'
-import { getDatabase, ref, onValue } from 'firebase/database'
-import { firebaseApp } from '../app/firebase'
+
+export type Freshness = 'fresh' | 'degraded' | 'stale' | 'offline'
+
+function computeFreshness(lastTelemetryAt: number | null): Freshness {
+  if (lastTelemetryAt == null) return 'offline'
+  const ageMs = Date.now() - lastTelemetryAt
+  if (ageMs < 30_000) return 'fresh'
+  if (ageMs < 90_000) return 'degraded'
+  if (ageMs < 300_000) return 'stale'
+  return 'offline'
+}
+
+const FRESHNESS_ORDER: Record<Freshness, number> = {
+  fresh: 0,
+  degraded: 1,
+  stale: 2,
+  offline: 3,
+}
 
 export interface EligibleResponder {
   uid: string
   displayName: string
   agencyId: string
+  availabilityStatus: string
+  lastTelemetryAt: number | null
+  freshness: Freshness
 }
 
 export function useEligibleResponders(municipalityId: string | undefined) {
-  const [responders, setResponders] = useState<Record<string, EligibleResponder>>({})
-  const [shift, setShift] = useState<Record<string, { isOnShift: boolean }>>({})
+  const [responders, setResponders] = useState<EligibleResponder[]>([])
 
   useEffect(() => {
     if (!municipalityId) {
       queueMicrotask(() => {
-        setResponders({})
+        setResponders([])
       })
       return
     }
@@ -27,37 +45,33 @@ export function useEligibleResponders(municipalityId: string | undefined) {
       where('isActive', '==', true),
     )
     return onSnapshot(q, (snap) => {
-      const out: Record<string, EligibleResponder> = {}
-      snap.docs.forEach((d) => {
-        const data = d.data()
-        out[d.id] = {
-          uid: d.id,
-          displayName: String(data.displayName ?? d.id),
-          agencyId: String(data.agencyId ?? 'unknown'),
-        }
-      })
-      setResponders(out)
-    })
-  }, [municipalityId])
-
-  useEffect(() => {
-    if (!municipalityId) {
-      queueMicrotask(() => {
-        setShift({})
-      })
-      return
-    }
-    const rtdb = getDatabase(firebaseApp)
-    const node = ref(rtdb, `/responder_index/${municipalityId}`)
-    const unsub = onValue(node, (s) => {
-      const snapVal = s.val()
-      setShift(snapVal !== null ? (snapVal as Record<string, { isOnShift: boolean }>) : {})
+      const eligible = snap.docs
+        .map((d) => {
+          const data = d.data()
+          const lastTelemetryAt =
+            typeof data.lastTelemetryAt === 'number' ? data.lastTelemetryAt : null
+          return {
+            uid: d.id,
+            displayName: String(data.displayName ?? d.id),
+            agencyId: String(data.agencyId ?? 'unknown'),
+            availabilityStatus: String(data.availabilityStatus ?? 'unknown'),
+            lastTelemetryAt,
+            freshness: computeFreshness(lastTelemetryAt),
+          }
+        })
+        .filter((r) => r.availabilityStatus !== 'off_duty')
+        .sort((a, b) => {
+          const aAvailable = a.availabilityStatus === 'available' ? 0 : 1
+          const bAvailable = b.availabilityStatus === 'available' ? 0 : 1
+          if (aAvailable !== bAvailable) return aAvailable - bAvailable
+          const aFresh = FRESHNESS_ORDER[a.freshness]
+          const bFresh = FRESHNESS_ORDER[b.freshness]
+          if (aFresh !== bFresh) return aFresh - bFresh
+          return a.displayName.localeCompare(b.displayName)
+        })
+      setResponders(eligible)
     })
-    return unsub
   }, [municipalityId])
 
-  const eligible = Object.values(responders)
-    .filter((r) => shift[r.uid]?.isOnShift === true)
-    .sort((a, b) => a.displayName.localeCompare(b.displayName))
-  return eligible
+  return responders
 }

apps/admin-desktop/src/hooks/useRosterManagement.ts

@@ -0,0 +1,85 @@
+import { useEffect, useState } from 'react'
+import { collection, onSnapshot, query, where } from 'firebase/firestore'
+import { db } from '../app/firebase'
+import { callables } from '../services/callables'
+
+export interface RosterResponder {
+  uid: string
+  displayName: string
+  availabilityStatus: string
+  lastTelemetryAt: number | null
+  municipalityId: string
+}
+
+export function useRosterManagement(agencyId: string | undefined) {
+  const [responders, setResponders] = useState<RosterResponder[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    queueMicrotask(() => {
+      setResponders([])
+      setError(null)
+    })
+
+    if (!agencyId) {
+      queueMicrotask(() => {
+        setLoading(false)
+      })
+      return
+    }
+
+    queueMicrotask(() => {
+      setLoading(true)
+    })
+
+    const q = query(collection(db, 'responders'), where('agencyId', '==', agencyId))
+
+    const unsubscribe = onSnapshot(
+      q,
+      (snapshot) => {
+        const docs: RosterResponder[] = snapshot.docs.map((d) => {
+          const data = d.data()
+          return {
+            uid: d.id,
+            displayName: String(data.displayName ?? d.id),
+            availabilityStatus: String(data.availabilityStatus ?? 'unknown'),
+            lastTelemetryAt: typeof data.lastTelemetryAt === 'number' ? data.lastTelemetryAt : null,
+            municipalityId: String(data.municipalityId ?? ''),
+          }
+        })
+        setResponders(docs)
+        setLoading(false)
+      },
+      (err) => {
+        setError(err.message)
+        setLoading(false)
+      },
+    )
+
+    return () => {
+      unsubscribe()
+    }
+  }, [agencyId])
+
+  const suspendResponder = async (uid: string) => {
+    await callables.suspendResponder({ uid, idempotencyKey: crypto.randomUUID() })
+  }
+
+  const revokeResponder = async (uid: string) => {
+    await callables.revokeResponder({ uid, idempotencyKey: crypto.randomUUID() })
+  }
+
+  const bulkAvailabilityOverride = async (
+    uids: string[],
+    status: 'available' | 'unavailable' | 'off_duty',
+  ) => {
+    await callables.bulkAvailabilityOverride({
+      uids,
+      status,
+      idempotencyKey: crypto.randomUUID(),
+    })
+  }
+
+  return { responders, loading, error, suspendResponder, revokeResponder, bulkAvailabilityOverride }
+}

apps/admin-desktop/src/pages/AgencyAssistanceQueuePage.test.tsx

@@ -3,20 +3,17 @@ import '@testing-library/jest-dom'
 import { render, screen, fireEvent, waitFor } from '@testing-library/react'
 import { AgencyAssistanceQueuePage } from './AgencyAssistanceQueuePage.js'
 
-const { mockOnSnapshot, mockCallable, mockHttpsCallable } = vi.hoisted(() => {
+const { mockUseAgencyAssistanceQueue, mockCallable, mockHttpsCallable } = vi.hoisted(() => {
   return {
-    mockOnSnapshot: vi.fn(),
+    mockUseAgencyAssistanceQueue: vi.fn(),
     mockCallable: vi.fn(),
     mockHttpsCallable: vi.fn(() => mockCallable),
   }
 })
 
-vi.mock('firebase/firestore', () => ({
-  collection: vi.fn(),
-  query: vi.fn(),
-  where: vi.fn(),
-  onSnapshot: mockOnSnapshot,
-  getFirestore: vi.fn(),
+vi.mock('../hooks/useAgencyAssistanceQueue', () => ({
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  useAgencyAssistanceQueue: (...args: unknown[]) => mockUseAgencyAssistanceQueue(...args),
 }))
 
 vi.mock('firebase/functions', () => ({
@@ -39,21 +36,21 @@ vi.mock('../app/firebase', () => ({
 
 const pendingRequest = {
   id: 'ar1',
-  data: () => ({
-    reportId: 'r1',
-    requestedByMunicipality: 'Daet',
-    message: 'Need BFP assistance',
-    priority: 'urgent',
-    status: 'pending',
-    targetAgencyId: 'bfp',
-    createdAt: 1713350400000,
-  }),
+  reportId: 'r1',
+  requestedByMunicipality: 'Daet',
+  message: 'Need BFP assistance',
+  priority: 'urgent' as const,
+  status: 'pending' as const,
+  targetAgencyId: 'bfp',
+  createdAt: 1713350400000,
 }
 
 beforeEach(() => {
-  mockOnSnapshot.mockImplementation((_q, cb) => {
-    cb({ docs: [pendingRequest] })
-    return vi.fn() // unsubscribe
+  mockUseAgencyAssistanceQueue.mockReturnValue({
+    requests: [pendingRequest],
+    backupRequests: [],
+    loading: false,
+    error: null,
   })
   mockCallable.mockResolvedValue({ data: { status: 'accepted' } })
 })
@@ -66,7 +63,6 @@ describe('AgencyAssistanceQueuePage', () => {
 
   it('shows Accept and Decline buttons on pending requests', () => {
     render(<AgencyAssistanceQueuePage />)
-    // Use getAllByRole and pick the ones with exact text (action buttons)
     const acceptButtons = screen.getAllByRole('button', { name: /^Accept$/ })
     const declineButtons = screen.getAllByRole('button', { name: /^Decline$/ })
     expect(acceptButtons).toHaveLength(1)