@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/src/device-bridge/background.ts

@@ -0,0 +1,137 @@
+/**
+ * Background Sync — registers an expo-task-manager task for periodic
+ * data sync when the app is in the background, and exposes a one-shot
+ * `syncDomains()` for silent-push triggered syncs.
+ *
+ * iOS minimum background fetch interval is ~15 minutes.
+ * Android allows more frequent background execution via WorkManager.
+ *
+ * Usage:
+ *   import { registerBackgroundSync, syncDomains } from '@mobile-pa/device-bridge';
+ *
+ *   // Periodic background fetch — call once at app startup, outside any component
+ *   registerBackgroundSync({
+ *     relayUrl: 'https://relay.example.com',
+ *     deviceId: 'device-123',
+ *     tenant: 'mobile-pa',
+ *     actorId: 'user-abc',
+ *     apiKey: 'key-xxx',
+ *   });
+ *
+ *   // Silent-push triggered sync — from FCM background message handler
+ *   await syncDomains(config, ['location', 'calendar']);
+ */
+
+import * as TaskManager from 'expo-task-manager';
+import * as BackgroundFetch from 'expo-background-fetch';
+import { RelayClient } from './relay-client';
+import * as caps from './capabilities';
+import type { Capability } from './types';
+
+export const BACKGROUND_TASK_NAME = 'DEVICE_BRIDGE_BACKGROUND_SYNC';
+
+export interface BackgroundSyncConfig {
+  relayUrl: string;
+  deviceId: string;
+  tenant: string;
+  actorId?: string;
+  apiKey: string;
+}
+
+const CAPABILITY_FACTORIES: Record<string, () => Capability> = {
+  calendar: caps.calendarCapability,
+  contacts: caps.contactsCapability,
+  location: caps.locationCapability,
+  battery: caps.batteryCapability,
+  connectivity: caps.connectivityCapability,
+  notifications: caps.notificationsCapability,
+  health: caps.healthCapability,
+};
+
+/**
+ * Register the periodic background-fetch task.
+ * Call once at app startup, outside any React component.
+ */
+export async function registerBackgroundSync(
+  config: BackgroundSyncConfig
+): Promise<void> {
+  TaskManager.defineTask(BACKGROUND_TASK_NAME, async () => {
+    try {
+      const hasNew = await syncDomains(config, ['location', 'battery', 'calendar']);
+      return hasNew
+        ? BackgroundFetch.BackgroundFetchResult.NewData
+        : BackgroundFetch.BackgroundFetchResult.NoData;
+    } catch (error) {
+      console.error('[DeviceBridge] Background sync failed:', error);
+      return BackgroundFetch.BackgroundFetchResult.Failed;
+    }
+  });
+
+  await BackgroundFetch.registerTaskAsync(BACKGROUND_TASK_NAME, {
+    minimumInterval: 300, // 5 minutes (iOS will clamp to ~15 min)
+    stopOnTerminate: false,
+    startOnBoot: true,
+  });
+}
+
+/**
+ * Unregister the background sync task.
+ */
+export async function unregisterBackgroundSync(): Promise<void> {
+  const isRegistered = await TaskManager.isTaskRegisteredAsync(
+    BACKGROUND_TASK_NAME
+  );
+  if (isRegistered) {
+    await BackgroundFetch.unregisterTaskAsync(BACKGROUND_TASK_NAME);
+  }
+}
+
+/**
+ * Collect and push the listed domains once. Used by both the periodic
+ * background-fetch task and the silent-push handler.
+ *
+ * Returns true if at least one domain pushed new data.
+ */
+export async function syncDomains(
+  config: BackgroundSyncConfig,
+  domains: string[]
+): Promise<boolean> {
+  const relay = new RelayClient({
+    relayUrl: config.relayUrl,
+    deviceId: config.deviceId,
+    tenant: config.tenant,
+    actorId: config.actorId,
+    apiKey: config.apiKey,
+    timeout: 15_000, // longer than foreground — background tasks are budget-limited but not latency-sensitive
+  });
+
+  const results = await Promise.allSettled(
+    domains.map(d => collectAndPush(relay, d))
+  );
+
+  return results.some(r => r.status === 'fulfilled' && r.value);
+}
+
+// ─── Internal ───
+
+async function collectAndPush(
+  relay: RelayClient,
+  domain: string
+): Promise<boolean> {
+  const factory = CAPABILITY_FACTORIES[domain];
+  if (!factory) {
+    console.warn(`[DeviceBridge] Unknown sync domain: ${domain}`);
+    return false;
+  }
+
+  const cap = factory();
+
+  if (cap.requiresPermission) {
+    const granted = await cap.checkPermission();
+    if (!granted) return false;
+  }
+
+  const data = await cap.collect();
+  const result = await relay.pushDomain(domain, data);
+  return result.ok;
+}

package/src/device-bridge/biometrics.ts

@@ -0,0 +1,64 @@
+/**
+ * Device-bridge: Biometrics (Face ID / Touch ID / fingerprint)
+ *
+ * Used by solutions that need a biometric gate before sensitive actions
+ * (e.g. "unlock payment", "confirm financial transfer", "reveal stored
+ * credentials"). Also useful for protecting session cookies at rest.
+ *
+ * Wraps expo-local-authentication.
+ */
+
+import * as LocalAuthentication from 'expo-local-authentication';
+
+export type BiometricType = 'fingerprint' | 'face' | 'iris' | 'none';
+
+export interface BiometricCapabilities {
+  hasHardware: boolean;
+  isEnrolled: boolean;
+  /**
+   * Never contains 'none' — the mapper filters it out, since 'none' means
+   * "the OS reported an auth type we do not recognise" and is not a
+   * biometric a caller can offer. Typed as the guarantee the code makes.
+   */
+  supportedTypes: Exclude<BiometricType, 'none'>[];
+}
+
+/** What can the device do right now? */
+export async function capabilities(): Promise<BiometricCapabilities> {
+  const [hasHardware, isEnrolled, types] = await Promise.all([
+    LocalAuthentication.hasHardwareAsync(),
+    LocalAuthentication.isEnrolledAsync(),
+    LocalAuthentication.supportedAuthenticationTypesAsync(),
+  ]);
+  const supportedTypes = types.map((t) => {
+    if (t === LocalAuthentication.AuthenticationType.FINGERPRINT) return 'fingerprint';
+    if (t === LocalAuthentication.AuthenticationType.FACIAL_RECOGNITION) return 'face';
+    if (t === LocalAuthentication.AuthenticationType.IRIS) return 'iris';
+    return 'none';
+  }).filter((t) => t !== 'none') as Exclude<BiometricType, 'none'>[];
+  return { hasHardware, isEnrolled, supportedTypes };
+}
+
+export interface AuthenticateOptions {
+  /** User-visible reason shown in the system dialog. */
+  reason: string;
+  /** Label on the "cancel" button (iOS only; Android has system default). */
+  cancelLabel?: string;
+  /** If biometrics aren't enrolled, fall back to device passcode. Default true. */
+  fallbackToPasscode?: boolean;
+}
+
+/** Prompt the user for biometric auth. Resolves { success } or { success:false, error }. */
+export async function authenticate(opts: AuthenticateOptions): Promise<{ success: boolean; error?: string }> {
+  try {
+    const res = await LocalAuthentication.authenticateAsync({
+      promptMessage: opts.reason,
+      cancelLabel: opts.cancelLabel,
+      disableDeviceFallback: opts.fallbackToPasscode === false,
+    });
+    if (res.success) return { success: true };
+    return { success: false, error: (res as any).error || 'unknown' };
+  } catch (e: any) {
+    return { success: false, error: String(e?.message || e) };
+  }
+}

package/src/device-bridge/capabilities.ts

@@ -0,0 +1,218 @@
+/**
+ * Built-in Capabilities — wraps each collector as a registerable Capability.
+ *
+ * Each capability defines:
+ *   - id, name, description, reason (for UI)
+ *   - permission check/request
+ *   - collect function
+ *
+ * The host app can register these selectively, or add custom ones.
+ */
+
+import * as calendar from './collectors/calendar';
+import * as contacts from './collectors/contacts';
+import * as location from './collectors/location';
+import * as battery from './collectors/battery';
+import * as connectivity from './collectors/connectivity';
+import * as notifications from './collectors/notifications';
+import * as health from './collectors/health';
+import * as mood from './collectors/mood';
+import * as camera from './collectors/camera';
+import type { Capability } from './types';
+
+// ─── Factory functions — call these to get a Capability instance ───
+
+export function calendarCapability(): Capability {
+  return {
+    id: 'calendar',
+    name: 'Calendar',
+    description: 'Syncs your calendar events so your assistant knows your schedule.',
+    reason: 'Needed for scheduling, meeting prep, commute alerts, and daily briefings.',
+    icon: 'calendar',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: calendar.requestPermission,
+    checkPermission: calendar.hasPermission,
+    collect: async () => {
+      const [today, upcoming] = await Promise.all([
+        calendar.collectToday(),
+        calendar.collectUpcoming(7),
+      ]);
+      return { today, upcoming };
+    },
+    defaultInterval: 60_000, // 1 min
+  };
+}
+
+export function contactsCapability(): Capability {
+  return {
+    id: 'contacts',
+    name: 'Contacts',
+    description: 'Syncs your contacts so your assistant can find people and relationships.',
+    reason: 'Needed for messaging, birthday reminders, and relationship insights.',
+    icon: 'people',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: contacts.requestPermission,
+    checkPermission: contacts.hasPermission,
+    collect: async () => {
+      const list = await contacts.collectAll();
+      // null = no changes since last successful sync → bridge skips push.
+      // Critical for users with 6000+ contacts: full payload is ~1MB and
+      // would otherwise re-upload every 5 min with no actual change.
+      if (list === null) return null as any;
+      return { contacts: list };
+    },
+    defaultInterval: 300_000, // 5 min
+  };
+}
+
+export function locationCapability(): Capability {
+  return {
+    id: 'location',
+    name: 'Location',
+    description: 'Syncs your location for weather, commute, and context-aware assistance.',
+    reason: 'Needed for commute estimates, weather at your location, and situation detection.',
+    icon: 'location',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: location.requestPermission,
+    checkPermission: location.hasPermission,
+    collect: location.collectCurrent,
+    defaultInterval: 30_000, // 30 sec
+  };
+}
+
+export function batteryCapability(): Capability {
+  return {
+    id: 'battery',
+    name: 'Battery',
+    description: 'Syncs battery level and charging status.',
+    reason: 'Helps your assistant adjust behavior when battery is low.',
+    icon: 'battery',
+    requiresPermission: false,
+    permissionState: 'not_needed',
+    requestPermission: async () => true,
+    checkPermission: async () => true,
+    collect: battery.collectBattery,
+    defaultInterval: 60_000, // 1 min
+    subscribe: battery.subscribeToBattery,
+  };
+}
+
+export function connectivityCapability(): Capability {
+  return {
+    id: 'connectivity',
+    name: 'Connectivity',
+    description: 'Syncs WiFi/cellular status.',
+    reason: 'Helps your assistant know if you have internet access.',
+    icon: 'wifi',
+    requiresPermission: false,
+    permissionState: 'not_needed',
+    requestPermission: async () => true,
+    checkPermission: async () => true,
+    collect: connectivity.collectConnectivity,
+    defaultInterval: 30_000, // 30 sec
+  };
+}
+
+export function healthCapability(): Capability {
+  return {
+    id: 'health',
+    name: 'Health',
+    description: 'Reads daily steps, floors, calories, and distance from Apple Health.',
+    reason: 'Powers the personal health coach and pairs activity data with nutrition tracking.',
+    icon: 'heart',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: health.requestPermission,
+    checkPermission: health.hasPermission,
+    collect: async () => {
+      // Push today AND the last 30 days every sync. The connector slices
+      // `days` to whatever range the caller asked for. ~30 sequential
+      // HealthKit reads on iOS take <300ms total — cheap.
+      const days = await health.collectHistory(30);
+      const today = days[0] || (await health.collectToday());
+      return { today, days };
+    },
+    defaultInterval: 300_000, // 5 min
+  };
+}
+
+export function moodCapability(): Capability {
+  return {
+    id: 'mood',
+    name: 'Mood',
+    description: 'Sends a daily behavioral-signal summary (activity, routine) to infer mood — not a medical diagnosis.',
+    reason: 'Lets ada gently notice changes in energy, stress, and routine and check in.',
+    icon: 'heart',
+    // No OS permission of its own — it derives from collectors that gate
+    // themselves (e.g. health). Treated as not_needed so the bridge syncs it
+    // whenever the user has the Mood toggle on.
+    requiresPermission: false,
+    permissionState: 'not_needed',
+    requestPermission: async () => true,
+    checkPermission: async () => true,
+    collect: async () => {
+      // One compact daily summary (window/timezone/collected_at/today).
+      // Pushed as the `mood` relay domain; backend runs /api/mood/analyze.
+      return mood.collectToday();
+    },
+    defaultInterval: 3_600_000, // hourly — it's a daily summary, no need to spam
+  };
+}
+
+export function cameraCapability(): Capability {
+  return {
+    id: 'camera',
+    name: 'Camera',
+    description:
+      "Lets ada see through your camera to guide you — reading text and describing what's in " +
+      'front of you. Frames are analysed on the phone; nothing is stored or uploaded.',
+    reason: 'Powers visual guidance (Ada Guide): a live view with on-device text and scene understanding.',
+    icon: 'camera',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: camera.requestPermission,
+    checkPermission: camera.hasPermission,
+    // LIVE, not synced: the camera is used in the moment (deviceState.visual / a
+    // widget's preview) and never collected to the relay. So collect never
+    // pushes — this capability's value is the USER GRANT + OS permission, exposed
+    // to the backend like every other, not a data payload. `null` = nothing to
+    // push, which the bridge skips (same contract contacts uses when unchanged).
+    collect: async () => null as any,
+    defaultInterval: 3_600_000, // never really collects; keep the poll rare
+  };
+}
+
+export function notificationsCapability(): Capability {
+  return {
+    id: 'notifications',
+    name: 'Notifications',
+    description: 'Syncs your notifications for triage and smart grouping.',
+    reason: 'Needed for notification triage, priority filtering, and Do Not Disturb.',
+    icon: 'notifications',
+    requiresPermission: true,
+    permissionState: 'not_requested',
+    requestPermission: notifications.requestPermission,
+    checkPermission: notifications.hasPermission,
+    collect: notifications.collectNotifications,
+    defaultInterval: 15_000, // 15 sec
+  };
+}
+
+// ─── Convenience: get all built-in capabilities ───
+
+export function allBuiltIn(): Capability[] {
+  return [
+    calendarCapability(),
+    contactsCapability(),
+    locationCapability(),
+    batteryCapability(),
+    connectivityCapability(),
+    notificationsCapability(),
+    healthCapability(),
+    moodCapability(),
+    cameraCapability(),
+  ];
+}

package/src/device-bridge/collectors/appEngagement.ts

@@ -0,0 +1,120 @@
+/**
+ * App Engagement Collector — our OWN usage analytics (no OS permission, fully
+ * available on every platform). Feeds the mood summary's app_sessions +
+ * app_active_min, which iOS otherwise blocks for third-party apps.
+ *
+ *   app_sessions    — count of foreground sessions today (a background→active
+ *                     transition, or a cold start, starts a session).
+ *   app_active_min  — total minutes the app was in the foreground today.
+ *
+ * Counters are kept per local day and persisted to AsyncStorage so they
+ * survive relaunches. start() must be called once at app boot to attach the
+ * AppState listener; getToday() returns the current day's tallies.
+ */
+import { AppState, type AppStateStatus } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const KEY = 'ateam.appEngagement.v1';
+
+interface DayTally {
+  date: string; // local YYYY-MM-DD
+  sessions: number;
+  activeMs: number;
+}
+
+let _tally: DayTally | null = null;
+let _foregroundSince: number | null = null;
+let _started = false;
+let _sub: { remove: () => void } | null = null;
+
+function todayKey(): string {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+function fresh(): DayTally {
+  return { date: todayKey(), sessions: 0, activeMs: 0 };
+}
+
+async function load(): Promise<void> {
+  try {
+    const raw = await AsyncStorage.getItem(KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw) as DayTally;
+      _tally = parsed?.date === todayKey() ? parsed : fresh();
+    } else {
+      _tally = fresh();
+    }
+  } catch {
+    _tally = fresh();
+  }
+}
+
+function persist(): void {
+  if (_tally) AsyncStorage.setItem(KEY, JSON.stringify(_tally)).catch(() => {});
+}
+
+function rollIfNewDay(): void {
+  if (!_tally || _tally.date !== todayKey()) {
+    _tally = fresh();
+    persist();
+  }
+}
+
+/** Fold the time spent foregrounded since the last checkpoint into activeMs. */
+function flushForeground(): void {
+  if (_foregroundSince == null || !_tally) return;
+  const now = Date.now();
+  const delta = now - _foregroundSince;
+  if (delta > 0) _tally.activeMs += delta;
+  _foregroundSince = now;
+}
+
+function onChange(state: AppStateStatus): void {
+  rollIfNewDay();
+  if (state === 'active') {
+    // New foreground session.
+    if (_tally) _tally.sessions += 1;
+    _foregroundSince = Date.now();
+    persist();
+  } else {
+    // Leaving foreground — bank the elapsed active time.
+    flushForeground();
+    _foregroundSince = null;
+    persist();
+  }
+}
+
+/** Attach the AppState listener. Idempotent; call once at app boot. */
+export async function start(): Promise<void> {
+  if (_started) return;
+  _started = true;
+  await load();
+  // Count the launch itself as the first active session.
+  rollIfNewDay();
+  if (_tally) _tally.sessions += 1;
+  _foregroundSince = Date.now();
+  persist();
+  _sub = AppState.addEventListener('change', onChange);
+}
+
+export function stop(): void {
+  flushForeground();
+  persist();
+  _sub?.remove();
+  _sub = null;
+  _started = false;
+}
+
+/** Current day's tallies for the mood summary. */
+export async function getToday(): Promise<{ app_sessions: number | null; app_active_min: number | null }> {
+  if (!_tally) await load();
+  rollIfNewDay();
+  flushForeground(); // include the in-progress foreground stretch
+  persist();
+  if (!_tally) return { app_sessions: null, app_active_min: null };
+  return {
+    app_sessions: _tally.sessions,
+    app_active_min: Math.round(_tally.activeMs / 60000),
+  };
+}

package/src/device-bridge/collectors/battery.ts

@@ -0,0 +1,83 @@
+/**
+ * Battery Collector — reads battery status via expo-battery.
+ * Output format matches device-mock-mcp's device.battery schema.
+ */
+
+import * as ExpoBattery from 'expo-battery';
+// Type-only alias: the value namespace above cannot be used in type
+// position, so `ExpoBattery.Calendar`-style annotations need this.
+// BatteryState is not re-exported from the package entry — derive it from
+// the API that returns it so we never hand-maintain a copy of the enum.
+type BatteryState = Awaited<ReturnType<typeof ExpoBattery.getBatteryStateAsync>>;
+import type { BatteryData } from '../types';
+
+// No permission needed for battery
+
+/**
+ * Collect current battery status.
+ * Matches the device.battery tool output schema.
+ */
+export async function collectBattery(): Promise<BatteryData> {
+  const level = await ExpoBattery.getBatteryLevelAsync();
+  const state = await ExpoBattery.getBatteryStateAsync();
+  const lowPower = await ExpoBattery.isLowPowerModeEnabledAsync();
+
+  return {
+    ok: true,
+    timestamp: new Date().toISOString(),
+    battery: {
+      level: Math.round(level * 100), // expo-battery returns 0-1
+      state: mapBatteryState(state),
+      low_power_mode: lowPower,
+    },
+  };
+}
+
+/**
+ * Subscribe to OS-level battery changes (level + charging state).
+ *
+ * iOS suspends JS timers when the app is backgrounded, so a pure setInterval
+ * sync drifts: the relay ends up stuck on whatever level we last sampled
+ * before the app went to sleep (commonly 100% from an overnight charge).
+ * expo-battery's listeners fire from the native side and survive that gap,
+ * so we get a fresh push as soon as the OS notices a change.
+ *
+ * Level changes are throttled to >=5pp deltas — without that, iOS emits a
+ * level event for every 1% tick which would spam the relay.
+ */
+export function subscribeToBattery(callback: () => void): () => void {
+  let lastLevel: number | null = null;
+
+  const levelSub = ExpoBattery.addBatteryLevelListener(({ batteryLevel }) => {
+    const pct = Math.round(batteryLevel * 100);
+    if (lastLevel === null || Math.abs(pct - lastLevel) >= 5) {
+      lastLevel = pct;
+      callback();
+    }
+  });
+
+  const stateSub = ExpoBattery.addBatteryStateListener(() => {
+    callback();
+  });
+
+  return () => {
+    levelSub?.remove?.();
+    stateSub?.remove?.();
+  };
+}
+
+// ─── Helpers ───
+
+function mapBatteryState(
+  state: BatteryState
+): 'charging' | 'unplugged' | 'full' {
+  switch (state) {
+    case ExpoBattery.BatteryState.CHARGING:
+      return 'charging';
+    case ExpoBattery.BatteryState.FULL:
+      return 'full';
+    case ExpoBattery.BatteryState.UNPLUGGED:
+    default:
+      return 'unplugged';
+  }
+}