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,92 @@
+import { useEffect, useState } from 'react'
+import { collection, onSnapshot, query, where } from 'firebase/firestore'
+import { db } from '../app/firebase'
+
+export interface AgencyAssistanceRequest {
+  id: string
+  reportId: string
+  requestedByMunicipality: string
+  message: string
+  priority: 'urgent' | 'normal'
+  status: 'pending' | 'accepted' | 'declined' | 'fulfilled' | 'expired'
+  targetAgencyId: string
+  createdAt: number
+}
+
+export interface BackupRequest {
+  id: string
+  reportId: string
+  municipalityId: string
+  reason: string
+  status: 'pending' | 'accepted' | 'declined' | 'fulfilled' | 'expired'
+  agencyId: string
+  createdAt: number
+}
+
+export function useAgencyAssistanceQueue(agencyId: string | undefined) {
+  const [requests, setRequests] = useState<AgencyAssistanceRequest[]>([])
+  const [backupRequests, setBackupRequests] = useState<BackupRequest[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    queueMicrotask(() => {
+      setError(null)
+    })
+
+    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 docs: AgencyAssistanceRequest[] = snapshot.docs.map((doc) => ({
+          id: doc.id,
+          ...doc.data(),
+        })) as AgencyAssistanceRequest[]
+        setRequests(docs)
+        setLoading(false)
+      },
+      (err) => {
+        setError(err.message)
+        setLoading(false)
+      },
+    )
+
+    const backupQ = query(collection(db, 'backup_requests'), where('agencyId', '==', agencyId))
+
+    const unsubscribeBackup = onSnapshot(
+      backupQ,
+      (snapshot) => {
+        const docs: BackupRequest[] = snapshot.docs.map((doc) => ({
+          id: doc.id,
+          ...doc.data(),
+        })) as BackupRequest[]
+        setBackupRequests(docs)
+      },
+      () => {
+        // Backup request errors are non-fatal; don't overwrite main error state
+      },
+    )
+
+    return () => {
+      unsubscribe()
+      unsubscribeBackup()
+    }
+  }, [agencyId])
+
+  return { requests, backupRequests, loading, error }
+}

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

@@ -4,10 +4,31 @@ 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) {
@@ -30,10 +51,15 @@ export function useEligibleResponders(municipalityId: string | undefined) {
       const out: Record<string, EligibleResponder> = {}
       snap.docs.forEach((d) => {
         const data = d.data()
+        const lastTelemetryAt =
+          typeof data.lastTelemetryAt === 'number' ? data.lastTelemetryAt : null
         out[d.id] = {
           uid: d.id,
           displayName: String(data.displayName ?? d.id),
           agencyId: String(data.agencyId ?? 'unknown'),
+          availabilityStatus: String(data.availabilityStatus ?? 'unknown'),
+          lastTelemetryAt,
+          freshness: computeFreshness(lastTelemetryAt),
         }
       })
       setResponders(out)
@@ -58,6 +84,17 @@ export function useEligibleResponders(municipalityId: string | undefined) {
 
   const eligible = Object.values(responders)
     .filter((r) => shift[r.uid]?.isOnShift === true)
-    .sort((a, b) => a.displayName.localeCompare(b.displayName))
+    .sort((a, b) => {
+      // Available first
+      const aAvailable = a.availabilityStatus === 'available' ? 0 : 1
+      const bAvailable = b.availabilityStatus === 'available' ? 0 : 1
+      if (aAvailable !== bAvailable) return aAvailable - bAvailable
+      // Then by freshness
+      const aFresh = FRESHNESS_ORDER[a.freshness]
+      const bFresh = FRESHNESS_ORDER[b.freshness]
+      if (aFresh !== bFresh) return aFresh - bFresh
+      // Then by name
+      return a.displayName.localeCompare(b.displayName)
+    })
   return eligible
 }

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

@@ -0,0 +1,82 @@
+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: string) => {
+    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)