@ateam-ai-mobile/expo 0.1.5 → 0.1.8

package/src/device-bridge/index.ts

@@ -0,0 +1,467 @@
+/**
+ * @mobile-pa/device-bridge
+ *
+ * Isolated device data sync module. Zero coupling to chat, voice, or UI.
+ * Pluggable capability system — register built-in or custom capabilities.
+ *
+ * Usage (host app controls permission flow):
+ *
+ *   import { DeviceBridge, capabilities } from '@mobile-pa/device-bridge';
+ *
+ *   const bridge = new DeviceBridge({ relayUrl, deviceId, apiKey });
+ *
+ *   // 1. Register capabilities
+ *   bridge.registerAll(capabilities.allBuiltIn());
+ *
+ *   // 2. Permission flow — host app shows its own UI per capability
+ *   for (const cap of bridge.getPendingPermissions()) {
+ *     // → show explanation: cap.name, cap.description, cap.reason
+ *     // → user taps "Allow"
+ *     await bridge.requestPermission(cap.id);
+ *   }
+ *
+ *   // 3. Start syncing (only syncs permitted capabilities)
+ *   await bridge.startSync();
+ *
+ *   // 4. Add more capabilities later (even after sync started)
+ *   bridge.register(myCustomCapability);
+ *   await bridge.requestPermission(myCustomCapability.id);
+ *   // → auto-starts syncing if bridge is already running
+ */
+
+import { RelayClient } from './relay-client';
+import { QueuePoller } from './actions/queue-poller';
+import { registerBackgroundSync, unregisterBackgroundSync } from './background';
+import type {
+  DeviceBridgeConfig,
+  BridgeStatus,
+  CapabilityStatus,
+  DomainSyncStatus,
+  SyncState,
+  Capability,
+  PermissionState,
+  ActionResult,
+} from './types';
+
+// Re-export types
+export type {
+  DeviceBridgeConfig,
+  BridgeStatus,
+  CapabilityStatus,
+  DomainSyncStatus,
+  BridgeError,
+  ActionResult,
+  Capability,
+  PermissionState,
+} from './types';
+
+// Re-export capability factories
+export * as capabilities from './capabilities';
+
+export class DeviceBridge {
+  private config: DeviceBridgeConfig;
+  private relay: RelayClient;
+  private queuePoller: QueuePoller;
+
+  // Capability registry
+  private caps: Map<string, Capability> = new Map();
+  private syncTimers: Map<string, ReturnType<typeof setInterval>> = new Map();
+  private subscriptions: Map<string, () => void> = new Map();
+  private domainStatus: Map<string, DomainSyncStatus> = new Map();
+  private running = false;
+
+  constructor(config: DeviceBridgeConfig) {
+    this.config = config;
+
+    this.relay = new RelayClient({
+      relayUrl: config.relayUrl,
+      deviceId: config.deviceId,
+      tenant: config.tenant,
+      actorId: config.actorId,
+      apiKey: config.apiKey,
+    });
+
+    this.queuePoller = new QueuePoller({
+      relayClient: this.relay,
+      pollInterval: 5_000,
+      onActionExecuted: () => this.notifyStatusChange(),
+      onError: (error) => this.config.onError?.({
+        domain: 'actions',
+        message: error.message,
+        code: 'ACTION_ERROR',
+        timestamp: new Date().toISOString(),
+      }),
+    });
+  }
+
+  // ─── Capability Registration ───
+
+  /**
+   * Register a capability. Does NOT request permission — just makes it known.
+   * Can be called before or after startSync().
+   */
+  register(cap: Capability): void {
+    this.caps.set(cap.id, cap);
+    this.domainStatus.set(cap.id, {
+      domain: cap.id,
+      lastSync: null,
+      state: 'idle',
+    });
+  }
+
+  /**
+   * Register multiple capabilities at once.
+   */
+  registerAll(caps: Capability[]): void {
+    for (const cap of caps) {
+      this.register(cap);
+    }
+  }
+
+  /**
+   * Get a registered capability by ID.
+   * Use this to read name/description/reason for your permission UI.
+   */
+  getCapability(id: string): Capability | undefined {
+    return this.caps.get(id);
+  }
+
+  /**
+   * Get all registered capabilities with their current status.
+   */
+  listCapabilities(): CapabilityStatus[] {
+    return Array.from(this.caps.values()).map(cap => ({
+      id: cap.id,
+      name: cap.name,
+      permission: cap.permissionState,
+      sync: this.domainStatus.get(cap.id) || {
+        domain: cap.id,
+        lastSync: null,
+        state: 'idle' as SyncState,
+      },
+    }));
+  }
+
+  // ─── Permissions (host app controls the flow) ───
+
+  /**
+   * Request permission for ONE capability.
+   * Call after showing your own explanation screen.
+   * If bridge is already running and granted, syncing starts automatically.
+   */
+  async requestPermission(capId: string): Promise<boolean> {
+    const cap = this.caps.get(capId);
+    if (!cap) throw new Error(`Capability "${capId}" not registered`);
+
+    if (!cap.requiresPermission) {
+      cap.permissionState = 'not_needed';
+      return true;
+    }
+
+    const granted = await cap.requestPermission();
+    cap.permissionState = granted ? 'granted' : 'denied';
+
+    // Auto-start syncing if bridge is already running
+    if (granted && this.running) {
+      this.startCapabilitySync(cap);
+    }
+
+    this.notifyStatusChange();
+    return granted;
+  }
+
+  /**
+   * Check permission WITHOUT prompting.
+   */
+  async checkPermission(capId: string): Promise<PermissionState> {
+    const cap = this.caps.get(capId);
+    if (!cap) throw new Error(`Capability "${capId}" not registered`);
+    if (!cap.requiresPermission) return 'not_needed';
+
+    const granted = await cap.checkPermission();
+    cap.permissionState = granted ? 'granted' : cap.permissionState;
+    return cap.permissionState;
+  }
+
+  /**
+   * Request ALL permissions sequentially (one at a time, not bombarded).
+   */
+  async requestAllPermissions(): Promise<Map<string, boolean>> {
+    const results = new Map<string, boolean>();
+
+    for (const [id, cap] of this.caps) {
+      if (!cap.requiresPermission) {
+        cap.permissionState = 'not_needed';
+        results.set(id, true);
+        continue;
+      }
+      const granted = await cap.requestPermission();
+      cap.permissionState = granted ? 'granted' : 'denied';
+      results.set(id, granted);
+    }
+
+    this.notifyStatusChange();
+    return results;
+  }
+
+  /**
+   * Get capabilities that still need permission.
+   * Use this to drive a "next permission" onboarding flow.
+   */
+  getPendingPermissions(): Capability[] {
+    return Array.from(this.caps.values()).filter(
+      cap => cap.requiresPermission && cap.permissionState === 'not_requested'
+    );
+  }
+
+  // ─── Sync Control ───
+
+  /**
+   * Start syncing all permitted capabilities + action queue poller.
+   */
+  async startSync(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+
+    for (const [, cap] of this.caps) {
+      const permitted =
+        !cap.requiresPermission ||
+        cap.permissionState === 'granted' ||
+        cap.permissionState === 'not_needed';
+
+      if (permitted) {
+        this.startCapabilitySync(cap);
+      } else {
+        this.updateDomainStatus(cap.id, 'error', 'Permission not granted');
+      }
+    }
+
+    this.queuePoller.start();
+
+    // R7: the bridge OWNS its background-fetch lifecycle. Registering the OS task
+    // here (from this bridge's own config) — instead of the host doing it
+    // separately — is what lets stopSync() reliably UNREGISTER it: before R7 the
+    // host registered it but stopBridge never unregistered, so the OS task kept
+    // firing with the PREVIOUS user's config across logout/tenant-switch.
+    // Best-effort: a host without expo-background-fetch just skips it. Needs a
+    // tenant + apiKey (both optional on DeviceBridgeConfig) to hit the relay —
+    // without them the background task has no identity to sync as, so skip it.
+    if (this.config.tenant && this.config.apiKey) {
+      registerBackgroundSync({
+        relayUrl: this.config.relayUrl,
+        deviceId: this.config.deviceId,
+        tenant: this.config.tenant,
+        actorId: this.config.actorId,
+        apiKey: this.config.apiKey,
+      }).catch((e: any) => console.warn('[adas/bridge] registerBackgroundSync failed:', e?.message || e));
+    }
+
+    this.notifyStatusChange();
+  }
+
+  /**
+   * Stop all syncing.
+   */
+  stopSync(): void {
+    this.running = false;
+
+    for (const [id, timer] of this.syncTimers) {
+      clearInterval(timer);
+      this.updateDomainStatus(id, 'stopped');
+    }
+    this.syncTimers.clear();
+    for (const unsub of this.subscriptions.values()) {
+      try { unsub(); } catch { /* swallow — best effort cleanup */ }
+    }
+    this.subscriptions.clear();
+    this.queuePoller.stop();
+    // R7: unregister the OS background-fetch task so it can't keep firing with
+    // this (now stale) user's config after logout/tenant-switch.
+    unregisterBackgroundSync().catch((e: any) => console.warn('[adas/bridge] unregisterBackgroundSync failed:', e?.message || e));
+    this.notifyStatusChange();
+  }
+
+  /**
+   * Force immediate sync of all permitted capabilities.
+   */
+  async syncNow(): Promise<void> {
+    const promises = Array.from(this.caps.values())
+      .filter(c => c.permissionState === 'granted' || c.permissionState === 'not_needed')
+      .map(c => this.syncCapability(c));
+    await Promise.allSettled(promises);
+  }
+
+  /**
+   * Force immediate sync of a single capability by id. Used by the host to
+   * refresh fast-moving sources (battery) on app-foreground so the relay
+   * gets a fresh reading the moment the user opens the app.
+   */
+  async syncCapabilityNow(capId: string): Promise<void> {
+    const cap = this.caps.get(capId);
+    if (!cap) return;
+    const permitted =
+      !cap.requiresPermission ||
+      cap.permissionState === 'granted' ||
+      cap.permissionState === 'not_needed';
+    if (!permitted) return;
+    await this.syncCapability(cap);
+  }
+
+  /**
+   * Get current bridge status.
+   */
+  getStatus(): BridgeStatus {
+    return {
+      running: this.running,
+      capabilities: this.listCapabilities(),
+      lastFullSync: this.getLastFullSync(),
+      pendingActions: this.relay.getOfflineQueueSize(),
+    };
+  }
+
+  /**
+   * Check if the relay is reachable.
+   */
+  async checkConnectivity(): Promise<boolean> {
+    return this.relay.ping();
+  }
+
+  // ─── Internal ───
+
+  private startCapabilitySync(cap: Capability): void {
+    if (this.syncTimers.has(cap.id)) return;
+
+    const interval = this.config.syncIntervals?.[cap.id] ?? cap.defaultInterval;
+    this.syncCapability(cap);
+    const timer = setInterval(() => this.syncCapability(cap), interval);
+    this.syncTimers.set(cap.id, timer);
+
+    // Wire any OS-event subscription (e.g. battery level/state) so we push
+    // on real change rather than just on the polling cadence. iOS suspends
+    // JS timers in the background, which is exactly when these events still
+    // fire from native.
+    if (cap.subscribe && !this.subscriptions.has(cap.id)) {
+      try {
+        const unsub = cap.subscribe(() => {
+          if (this.running) this.syncCapability(cap);
+        });
+        this.subscriptions.set(cap.id, unsub);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.config.onError?.({
+          domain: cap.id,
+          message: `subscribe failed: ${message}`,
+          code: 'SUBSCRIBE_ERROR',
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  private async syncCapability(cap: Capability): Promise<void> {
+    if (!this.running) return;
+    this.updateDomainStatus(cap.id, 'syncing');
+
+    try {
+      const data = await cap.collect();
+      // Collectors that did the work and concluded "nothing to push" return
+      // null (e.g. contacts hashing detects no changes since last cycle —
+      // saves a 1MB+ payload for 6000 contacts). Stay 'idle', don't hit the
+      // network, but don't treat it as an error either.
+      if (data === null) {
+        this.updateDomainStatus(cap.id, 'idle');
+        return;
+      }
+      const result = await this.relay.pushDomain(cap.id, data);
+
+      if (result.ok) {
+        this.updateDomainStatus(cap.id, 'idle');
+      } else {
+        this.updateDomainStatus(cap.id, 'error', result.error);
+        this.config.onError?.({
+          domain: cap.id,
+          message: result.error || 'Push failed',
+          code: 'RELAY_ERROR',
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.updateDomainStatus(cap.id, 'error', message);
+      this.config.onError?.({
+        domain: cap.id,
+        message,
+        code: 'COLLECTOR_ERROR',
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  private updateDomainStatus(id: string, state: SyncState, error?: string): void {
+    const current = this.domainStatus.get(id);
+    this.domainStatus.set(id, {
+      domain: id,
+      lastSync: state === 'idle' ? new Date().toISOString() : (current?.lastSync ?? null),
+      state,
+      error,
+      itemCount: current?.itemCount,
+    });
+  }
+
+  private getLastFullSync(): string | null {
+    const syncs = Array.from(this.domainStatus.values())
+      .map(d => d.lastSync)
+      .filter((s): s is string => s !== null);
+    if (syncs.length === 0) return null;
+    return syncs.sort()[0];
+  }
+
+  private notifyStatusChange(): void {
+    this.config.onStatusChange?.(this.getStatus());
+  }
+}
+
+// ─── Background Sync Support ───
+export {
+  registerBackgroundSync,
+  unregisterBackgroundSync,
+  syncDomains,
+  BACKGROUND_TASK_NAME,
+} from './background';
+export type { BackgroundSyncConfig } from './background';
+
+// ─── Re-exports for advanced usage ───
+export { RelayClient } from './relay-client';
+export { QueuePoller } from './actions/queue-poller';
+
+// ─────────────────────────────────────────────────────────────────────
+// PLATFORM NATIVE CAPABILITIES
+// device-bridge owns every native dependency. plugin-sdk delegates to
+// these namespaces so RN plugins never import native modules directly.
+// Adding a new native capability = one file here + one plugin-sdk
+// delegation + one rebuild — THEN every future solution consumes it
+// as plain JS, no rebuild required.
+// ─────────────────────────────────────────────────────────────────────
+
+// Biometrics — Face ID / Touch ID / fingerprint (expo-local-authentication)
+export * as biometrics from './biometrics';
+export type { BiometricType, BiometricCapabilities, AuthenticateOptions } from './biometrics';
+
+// Sharing — native share sheet (expo-sharing)
+export * as sharing from './sharing';
+export type { ShareOptions } from './sharing';
+
+// Scanner — QR / barcode camera (expo-camera)
+export * as scanner from './scanner';
+export type { ScanResult } from './scanner';
+
+// Location — GPS fixes for plugin tools (expo-location, safe in Expo Go)
+export * as location from './collectors/location';
+export type { Position } from './collectors/location';
+
+// NOTE: cookies (@react-native-cookies/cookies) and nfc (react-native-nfc-manager)
+// require native modules NOT included in Expo Go. They are imported lazily
+// via require() in useNativeCapabilities.ts. Do NOT add eager exports here
+// or the app will crash in Expo Go.
+// To use: require('../../packages/device-bridge/src/cookies')
+// To use: require('../../packages/device-bridge/src/nfc')

package/src/device-bridge/nfc.ts

@@ -0,0 +1,85 @@
+/**
+ * Device-bridge: NFC
+ *
+ * Wraps react-native-nfc-manager for:
+ *   - Reading NFC tags (NDEF, Mifare)
+ *   - Writing to writable tags
+ *   - App-triggered tag discovery
+ *
+ * Use cases: physical-world triggers, inventory lookup, hardware keys,
+ * loyalty cards, transit top-up, pairing.
+ *
+ * iOS: requires "Near Field Communication Tag Reading" entitlement in the
+ * app's provisioning profile. Android: requires NFC permission in manifest.
+ */
+
+import NfcManager, { NfcTech, Ndef } from 'react-native-nfc-manager';
+
+let _initialized = false;
+
+async function ensureInit(): Promise<boolean> {
+  if (_initialized) return true;
+  try {
+    const supported = await NfcManager.isSupported();
+    if (!supported) return false;
+    await NfcManager.start();
+    _initialized = true;
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+export async function isSupported(): Promise<boolean> {
+  try { return await NfcManager.isSupported(); } catch { return false; }
+}
+
+export async function isEnabled(): Promise<boolean> {
+  try { return await NfcManager.isEnabled(); } catch { return false; }
+}
+
+export interface NdefRecord {
+  type: string;
+  payload: string;
+}
+
+export interface TagReadResult {
+  ok: boolean;
+  tagId?: string;
+  records?: NdefRecord[];
+  error?: string;
+}
+
+/** Wait for the next tag to be scanned, read NDEF records, release, and return. */
+export async function readOnce(timeoutMs: number = 30_000): Promise<TagReadResult> {
+  const ready = await ensureInit();
+  if (!ready) return { ok: false, error: 'nfc_unsupported' };
+  try {
+    const tag = await Promise.race([
+      NfcManager.requestTechnology(NfcTech.Ndef).then(() => NfcManager.getTag()),
+      new Promise<null>((resolve) => setTimeout(() => resolve(null), timeoutMs)),
+    ]);
+    if (!tag) {
+      try { await NfcManager.cancelTechnologyRequest(); } catch {}
+      return { ok: false, error: 'timeout' };
+    }
+    const records: NdefRecord[] = [];
+    if ((tag as any).ndefMessage) {
+      for (const r of (tag as any).ndefMessage) {
+        try {
+          const type = String.fromCharCode(...(r.type || []));
+          const payload = Ndef.text.decodePayload(r.payload || []);
+          records.push({ type, payload: String(payload) });
+        } catch {
+          // skip records we can't decode
+        }
+      }
+    }
+    const tagId = (tag as any).id ? Array.from((tag as any).id).map((b: any) => b.toString(16).padStart(2, '0')).join('') : undefined;
+    return { ok: true, tagId, records };
+  } catch (e: any) {
+    return { ok: false, error: String(e?.message || e) };
+  } finally {
+    try { await NfcManager.cancelTechnologyRequest(); } catch {}
+  }
+}

package/src/device-bridge/plugin.ts

@@ -0,0 +1,71 @@
+/**
+ * Service plugin wrapper for ateam-mobile.
+ *
+ * Wraps DeviceBridge as a RegisteredServicePlugin so the dynamic
+ * connector loader can start/stop it as part of the solution lifecycle.
+ *
+ * NOTE: In the current architecture, device-bridge is managed directly
+ * by capabilitiesStore (which owns the DeviceBridge instance and controls
+ * which capabilities are registered based on user preferences).
+ *
+ * This plugin wrapper is kept for potential future use where solutions
+ * might declare device-bridge as a functional connector with custom config.
+ */
+
+import { DeviceBridge, capabilities } from './index';
+
+export interface DeviceBridgePluginConfig {
+  relayUrl: string;
+  deviceId: string;
+  tenant: string;
+  apiKey?: string;
+  /** Override sync intervals per domain (ms). */
+  syncIntervals?: Record<string, number>;
+}
+
+/**
+ * Create a service plugin definition for ateam-mobile's plugin registry.
+ * Returns the shape expected by PluginSDK.registerService().
+ */
+export function createDeviceBridgePlugin(config: DeviceBridgePluginConfig) {
+  let bridge: DeviceBridge | null = null;
+
+  return {
+    type: 'service' as const,
+    capabilities: {
+      location: true,
+      notifications: true,
+    },
+    hooks: {
+      onAppStart: true,
+      onForeground: true,
+      onBackground: true,
+    },
+
+    async onStart() {
+      if (bridge) return; // already running
+
+      bridge = new DeviceBridge({
+        relayUrl: config.relayUrl,
+        deviceId: config.deviceId,
+        tenant: config.tenant,
+        apiKey: config.apiKey,
+        syncIntervals: config.syncIntervals,
+        onError: (err) => {
+          // Silence transient network errors — relay-client already buffers offline.
+          if (/Network error|Network request failed|Offline/i.test(err.message)) return;
+          console.warn(`[device-bridge] ${err.domain}: ${err.message}`);
+        },
+      });
+
+      bridge.registerAll(capabilities.allBuiltIn());
+      await bridge.requestAllPermissions();
+      await bridge.startSync();
+    },
+
+    async onStop() {
+      bridge?.stopSync();
+      bridge = null;
+    },
+  };
+}