@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/dist/device-bridge/index.d.ts

@@ -0,0 +1,483 @@
+import { C as Capability, D as DeviceDataBundle, R as RelayResponse, P as PendingAction, A as ActionResult, L as LocationData, a as DeviceBridgeConfig, b as CapabilityStatus, c as PermissionState, B as BridgeStatus } from '../types-BRanJYTn.js';
+export { d as BridgeError, e as DomainSyncStatus } from '../types-BRanJYTn.js';
+import { BarcodeScanningResult, CameraView, useCameraPermissions } from 'expo-camera';
+
+/**
+ * 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.
+ */
+
+declare function calendarCapability(): Capability;
+declare function contactsCapability(): Capability;
+declare function locationCapability(): Capability;
+declare function batteryCapability(): Capability;
+declare function connectivityCapability(): Capability;
+declare function healthCapability(): Capability;
+declare function moodCapability(): Capability;
+declare function cameraCapability(): Capability;
+declare function notificationsCapability(): Capability;
+declare function allBuiltIn(): Capability[];
+
+declare const capabilities$1_allBuiltIn: typeof allBuiltIn;
+declare const capabilities$1_batteryCapability: typeof batteryCapability;
+declare const capabilities$1_calendarCapability: typeof calendarCapability;
+declare const capabilities$1_cameraCapability: typeof cameraCapability;
+declare const capabilities$1_connectivityCapability: typeof connectivityCapability;
+declare const capabilities$1_contactsCapability: typeof contactsCapability;
+declare const capabilities$1_healthCapability: typeof healthCapability;
+declare const capabilities$1_locationCapability: typeof locationCapability;
+declare const capabilities$1_moodCapability: typeof moodCapability;
+declare const capabilities$1_notificationsCapability: typeof notificationsCapability;
+declare namespace capabilities$1 {
+  export { capabilities$1_allBuiltIn as allBuiltIn, capabilities$1_batteryCapability as batteryCapability, capabilities$1_calendarCapability as calendarCapability, capabilities$1_cameraCapability as cameraCapability, capabilities$1_connectivityCapability as connectivityCapability, capabilities$1_contactsCapability as contactsCapability, capabilities$1_healthCapability as healthCapability, capabilities$1_locationCapability as locationCapability, capabilities$1_moodCapability as moodCapability, capabilities$1_notificationsCapability as notificationsCapability };
+}
+
+/**
+ * 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']);
+ */
+declare const BACKGROUND_TASK_NAME = "DEVICE_BRIDGE_BACKGROUND_SYNC";
+interface BackgroundSyncConfig {
+    relayUrl: string;
+    deviceId: string;
+    tenant: string;
+    actorId?: string;
+    apiKey: string;
+}
+/**
+ * Register the periodic background-fetch task.
+ * Call once at app startup, outside any React component.
+ */
+declare function registerBackgroundSync(config: BackgroundSyncConfig): Promise<void>;
+/**
+ * Unregister the background sync task.
+ */
+declare function unregisterBackgroundSync(): Promise<void>;
+/**
+ * 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.
+ */
+declare function syncDomains(config: BackgroundSyncConfig, domains: string[]): Promise<boolean>;
+
+/**
+ * Relay Client — REST client for the cloud relay service.
+ * Handles data push, action polling, and offline buffering.
+ *
+ * Endpoints:
+ *   POST   /api/device/{deviceId}/sync           ← push data bundle
+ *   GET    /api/device/{deviceId}/data/{domain}   ← read latest (used by connector, not phone)
+ *   POST   /api/device/{deviceId}/actions         ← queue action (used by connector)
+ *   GET    /api/device/{deviceId}/actions          ← poll pending actions
+ *   DELETE /api/device/{deviceId}/actions/{id}     ← confirm action executed
+ */
+
+interface RelayClientConfig {
+    relayUrl: string;
+    deviceId: string;
+    tenant: string;
+    actorId?: string;
+    apiKey?: string;
+    timeout?: number;
+}
+declare class RelayClient {
+    private baseUrl;
+    private deviceId;
+    private tenant;
+    private actorId;
+    private apiKey;
+    private timeout;
+    private offlineQueue;
+    constructor(config: RelayClientConfig);
+    /**
+     * Push a full device data bundle to the relay.
+     * If offline, buffers the bundle and retries on next sync.
+     */
+    pushData(bundle: DeviceDataBundle): Promise<RelayResponse<void>>;
+    /**
+     * Push a single domain update (partial sync).
+     */
+    pushDomain(domain: string, data: unknown): Promise<RelayResponse<void>>;
+    /**
+     * Poll for pending actions the phone needs to execute.
+     */
+    pollActions(): Promise<RelayResponse<PendingAction[]>>;
+    /**
+     * Report action execution result and remove from queue.
+     */
+    completeAction(result: ActionResult): Promise<RelayResponse<void>>;
+    /**
+     * Ping the relay to check connectivity.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get count of buffered offline bundles.
+     */
+    getOfflineQueueSize(): number;
+    private fetch;
+    private flushOfflineQueue;
+}
+
+/**
+ * Action Queue Poller — polls the relay for pending actions and executes them.
+ * Routes each action to the appropriate executor based on action type.
+ */
+
+interface QueuePollerConfig {
+    /** Polling interval in ms (default: 5000) */
+    pollInterval?: number;
+    /** Relay client instance */
+    relayClient: RelayClient;
+    /** Callback when an action is executed */
+    onActionExecuted?: (result: ActionResult) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+}
+declare class QueuePoller {
+    private relayClient;
+    private pollInterval;
+    private timer;
+    private running;
+    private onActionExecuted?;
+    private onError?;
+    constructor(config: QueuePollerConfig);
+    /**
+     * Start polling for actions.
+     */
+    start(): void;
+    /**
+     * Stop polling.
+     */
+    stop(): void;
+    /**
+     * Check if poller is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Execute a single poll cycle.
+     */
+    private poll;
+    /**
+     * Route an action to the appropriate executor.
+     */
+    private executeAction;
+}
+
+/**
+ * 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.
+ */
+type BiometricType = 'fingerprint' | 'face' | 'iris' | 'none';
+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? */
+declare function capabilities(): Promise<BiometricCapabilities>;
+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 }. */
+declare function authenticate(opts: AuthenticateOptions): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+
+type biometrics_AuthenticateOptions = AuthenticateOptions;
+type biometrics_BiometricCapabilities = BiometricCapabilities;
+type biometrics_BiometricType = BiometricType;
+declare const biometrics_authenticate: typeof authenticate;
+declare const biometrics_capabilities: typeof capabilities;
+declare namespace biometrics {
+  export { type biometrics_AuthenticateOptions as AuthenticateOptions, type biometrics_BiometricCapabilities as BiometricCapabilities, type biometrics_BiometricType as BiometricType, biometrics_authenticate as authenticate, biometrics_capabilities as capabilities };
+}
+
+/**
+ * Device-bridge: Sharing (native share sheet)
+ *
+ * Wraps expo-sharing. Lets solutions hand content off to the OS share sheet
+ * — any installed app can receive it (Messages, WhatsApp, Mail, Files, etc.).
+ *
+ * Typical use: "Share this article / calendar invite / photo with a contact."
+ */
+interface ShareOptions {
+    /** MIME type, e.g. 'application/pdf'. Optional. */
+    mimeType?: string;
+    /** iOS UTI, e.g. 'public.image'. Optional. */
+    UTI?: string;
+    /** Dialog title (Android only). */
+    dialogTitle?: string;
+}
+/** Share a local file URI. */
+declare function shareFile(fileUri: string, opts?: ShareOptions): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+declare function isAvailable(): Promise<boolean>;
+
+type sharing_ShareOptions = ShareOptions;
+declare const sharing_isAvailable: typeof isAvailable;
+declare const sharing_shareFile: typeof shareFile;
+declare namespace sharing {
+  export { type sharing_ShareOptions as ShareOptions, sharing_isAvailable as isAvailable, sharing_shareFile as shareFile };
+}
+
+/**
+ * Device-bridge: Scanner (QR / barcode)
+ *
+ * Wraps expo-camera (which replaced the deprecated expo-barcode-scanner
+ * in Expo SDK 50+). The CameraView component has built-in barcode scanning.
+ *
+ * Use cases:
+ *   - Wi-Fi QR handoff
+ *   - OAuth / pairing codes
+ *   - Payment QR codes
+ *   - Product lookup
+ *
+ * Plugins mount <CameraView onBarcodeScanned={...} /> directly. This module
+ * exposes the permission helper + a result normalizer so plugins don't need
+ * to import expo-camera directly.
+ */
+
+interface ScanResult {
+    type: string;
+    data: string;
+}
+/** Request camera permission if not already granted. */
+declare function requestPermissions(): Promise<{
+    granted: boolean;
+    status: string;
+}>;
+/** Normalize a CameraView barcode result to a stable shape. */
+declare function normalizeResult(r: BarcodeScanningResult): ScanResult;
+
+declare const scanner_CameraView: typeof CameraView;
+type scanner_ScanResult = ScanResult;
+declare const scanner_normalizeResult: typeof normalizeResult;
+declare const scanner_requestPermissions: typeof requestPermissions;
+declare const scanner_useCameraPermissions: typeof useCameraPermissions;
+declare namespace scanner {
+  export { scanner_CameraView as CameraView, type scanner_ScanResult as ScanResult, scanner_normalizeResult as normalizeResult, scanner_requestPermissions as requestPermissions, scanner_useCameraPermissions as useCameraPermissions };
+}
+
+/**
+ * Location Collector — reads device location via expo-location.
+ * Output format matches device-mock-mcp's location.current schema.
+ */
+
+/**
+ * Request location permissions (foreground + background).
+ */
+declare function requestPermission(): Promise<boolean>;
+/**
+ * Check if location permission is granted.
+ */
+declare function hasPermission(): Promise<boolean>;
+/**
+ * Collect current location.
+ * Matches the device.location.current tool output schema.
+ */
+declare function collectCurrent(): Promise<LocationData>;
+interface Position {
+    latitude: number;
+    longitude: number;
+    altitude?: number;
+    accuracy?: number;
+    timestamp: number;
+    /**
+     * Metres per second. `undefined` = the OS gave no estimate.
+     *
+     * iOS reports -1 rather than omitting it, and -1 m/s passed through as a
+     * speed would read as "moving backwards"; it is normalised away here so no
+     * caller has to know the platform's sentinel.
+     */
+    speed?: number;
+    /**
+     * COURSE OVER GROUND in degrees — the direction the user is TRAVELLING.
+     *
+     * Deliberately not called `heading`: this and the compass answer different
+     * questions and disagree constantly. Walking backwards down a corridor gives
+     * a course of south and a compass heading of north; a phone held sideways
+     * while walking forward gives the same course and a heading 90° off.
+     * "Turn right" needs the compass. "You are heading north on Main Street"
+     * needs this. The old code assigned one to the other, which is only ever
+     * right by accident.
+     *
+     * `undefined` when not moving or not estimated — iOS reports -1 for both.
+     */
+    course?: number;
+}
+/** One position fix. `accuracy: "high"` costs battery and time — default low. */
+declare function getPosition(opts?: {
+    accuracy?: 'low' | 'high';
+}): Promise<Position>;
+/**
+ * Stream position updates. Returns an unsubscribe function — call it, or the
+ * GPS keeps running and drains the battery.
+ */
+declare function watchPosition(cb: (pos: Position) => void): () => void;
+
+type location_Position = Position;
+declare const location_collectCurrent: typeof collectCurrent;
+declare const location_getPosition: typeof getPosition;
+declare const location_hasPermission: typeof hasPermission;
+declare const location_requestPermission: typeof requestPermission;
+declare const location_watchPosition: typeof watchPosition;
+declare namespace location {
+  export { type location_Position as Position, location_collectCurrent as collectCurrent, location_getPosition as getPosition, location_hasPermission as hasPermission, location_requestPermission as requestPermission, location_watchPosition as watchPosition };
+}
+
+/**
+ * @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
+ */
+
+declare class DeviceBridge {
+    private config;
+    private relay;
+    private queuePoller;
+    private caps;
+    private syncTimers;
+    private subscriptions;
+    private domainStatus;
+    private running;
+    constructor(config: DeviceBridgeConfig);
+    /**
+     * Register a capability. Does NOT request permission — just makes it known.
+     * Can be called before or after startSync().
+     */
+    register(cap: Capability): void;
+    /**
+     * Register multiple capabilities at once.
+     */
+    registerAll(caps: Capability[]): void;
+    /**
+     * Get a registered capability by ID.
+     * Use this to read name/description/reason for your permission UI.
+     */
+    getCapability(id: string): Capability | undefined;
+    /**
+     * Get all registered capabilities with their current status.
+     */
+    listCapabilities(): CapabilityStatus[];
+    /**
+     * Request permission for ONE capability.
+     * Call after showing your own explanation screen.
+     * If bridge is already running and granted, syncing starts automatically.
+     */
+    requestPermission(capId: string): Promise<boolean>;
+    /**
+     * Check permission WITHOUT prompting.
+     */
+    checkPermission(capId: string): Promise<PermissionState>;
+    /**
+     * Request ALL permissions sequentially (one at a time, not bombarded).
+     */
+    requestAllPermissions(): Promise<Map<string, boolean>>;
+    /**
+     * Get capabilities that still need permission.
+     * Use this to drive a "next permission" onboarding flow.
+     */
+    getPendingPermissions(): Capability[];
+    /**
+     * Start syncing all permitted capabilities + action queue poller.
+     */
+    startSync(): Promise<void>;
+    /**
+     * Stop all syncing.
+     */
+    stopSync(): void;
+    /**
+     * Force immediate sync of all permitted capabilities.
+     */
+    syncNow(): Promise<void>;
+    /**
+     * 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.
+     */
+    syncCapabilityNow(capId: string): Promise<void>;
+    /**
+     * Get current bridge status.
+     */
+    getStatus(): BridgeStatus;
+    /**
+     * Check if the relay is reachable.
+     */
+    checkConnectivity(): Promise<boolean>;
+    private startCapabilitySync;
+    private syncCapability;
+    private updateDomainStatus;
+    private getLastFullSync;
+    private notifyStatusChange;
+}
+
+export { ActionResult, type AuthenticateOptions, BACKGROUND_TASK_NAME, type BackgroundSyncConfig, type BiometricCapabilities, type BiometricType, BridgeStatus, Capability, CapabilityStatus, DeviceBridge, DeviceBridgeConfig, PermissionState, type Position, QueuePoller, RelayClient, type ScanResult, type ShareOptions, biometrics, capabilities$1 as capabilities, location, registerBackgroundSync, scanner, sharing, syncDomains, unregisterBackgroundSync };