@ateam-ai-mobile/plugin-runtime 0.1.0

package/src/sdk/types.ts

@@ -0,0 +1,315 @@
+/**
+ * @adas/plugin-sdk — Type definitions
+ *
+ * This is the developer contract for native mobile plugins.
+ * Both UI and service plugins use these interfaces.
+ */
+
+// ── Plugin Context ──────────────────────────────────────────
+
+export interface PluginContext {
+  tenant: string;
+  pluginId: string;
+  connectorId?: string;
+  user?: { id: string; name: string; roles: string[] };
+}
+
+// ── Bridge (shared across web and native) ───────────────────
+
+export interface PluginBridge {
+  /** Wait for host initialization */
+  onInit(cb: (ctx: PluginContext) => void): void;
+
+  /** Call an MCP tool on any connector */
+  mcpCall(tool: string, args: any, connectorId?: string): Promise<any>;
+
+  /** Raw JSON-RPC to /mcp endpoint */
+  mcpFetch(body: any): Promise<any>;
+
+  /** Send a command to the host */
+  sendCommand(type: string, payload: any): void;
+
+  /** Listen for commands from the host */
+  onCommand(cb: (type: string, payload: any) => void): () => void;
+
+  /** Close this plugin and return to chat */
+  close(): void;
+
+  /** Post a message into the user's chat thread, exactly as if the user
+   *  typed it. Use for confirmed user actions (e.g. "Connect Gmail" with
+   *  an approval modal) that should kick off a flow the orchestrator
+   *  already knows how to handle. Pair with `close()` to land the user on
+   *  the chat screen so they see Ada working on it. */
+  sendMessage(text: string): void;
+
+  /** Pre-fill the chat composer with `text` without sending. The user lands
+   *  on chat with the text already typed and the input focused, so they can
+   *  edit/review before tapping send. Use for "draft a message about X"
+   *  flows where you want the user to review before committing. Pair with
+   *  `close()` to dismiss the plugin surface. */
+  prepareMessage(text: string): void;
+}
+
+// ── Native capabilities (only available in RN plugins) ──────
+
+export interface CameraAPI {
+  takePhoto(opts?: { quality?: number; facing?: 'front' | 'back' }): Promise<{ uri: string; width: number; height: number }>;
+  scanBarcode(opts?: { formats?: string[] }): Promise<{ data: string; format: string }>;
+  pickImage(opts?: { multiple?: boolean }): Promise<{ uri: string }[]>;
+}
+
+export interface LocationAPI {
+  getCurrent(opts?: { accuracy?: 'low' | 'high' }): Promise<{ latitude: number; longitude: number; altitude?: number }>;
+  watchPosition(cb: (pos: { latitude: number; longitude: number }) => void): () => void;
+}
+
+export interface StorageAPI {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  db: {
+    execute(sql: string, params?: any[]): Promise<{ rows: any[]; changes: number }>;
+  };
+}
+
+export interface BiometricsAPI {
+  isAvailable(): Promise<boolean>;
+  authenticate(opts: { reason: string }): Promise<{ success: boolean }>;
+}
+
+export interface NotificationsAPI {
+  schedule(opts: { title: string; body: string; trigger: { seconds?: number; date?: string } }): Promise<string>;
+  cancel(id: string): Promise<void>;
+  onReceived(cb: (notification: { id: string; title: string; body: string; data?: any }) => void): () => void;
+}
+
+export interface HapticsAPI {
+  impact(style: 'light' | 'medium' | 'heavy'): void;
+  notification(type: 'success' | 'warning' | 'error'): void;
+  selection(): void;
+}
+
+export interface ConnectivityAPI {
+  isOnline(): boolean;
+  onChange(cb: (online: boolean) => void): () => void;
+}
+
+export interface FileSystemAPI {
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  pickDocument(opts?: { types?: string[] }): Promise<{ uri: string; name: string; size: number }>;
+}
+
+// ── Cookies API ────────────────────────────────────────────
+// Reads the platform's shared cookie jar (NSHTTPCookieStorage on iOS,
+// CookieManager on Android) after a WebView session has populated it.
+// This is how plugins extract HttpOnly cookies from a user's login —
+// `document.cookie` only sees non-HttpOnly. Plugin must declare
+// `cookies: true` in its manifest's native capabilities.
+
+export interface WebViewCookie {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;       // unix seconds
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Lax' | 'Strict' | 'None';
+}
+
+export interface CookiesAPI {
+  /** Get all cookies attached to a URL's effective domain. */
+  get(url: string): Promise<WebViewCookie[]>;
+  /** Clear cookies for a domain (e.g. to force re-login). */
+  clear(url: string): Promise<{ ok: boolean }>;
+}
+
+// ── Sharing API (native share sheet) ──────────────────────
+export interface SharingAPI {
+  /** Is the share sheet available on this device? */
+  isAvailable(): Promise<boolean>;
+  /** Share a local file URI via the OS share sheet. */
+  shareFile(fileUri: string, opts?: { mimeType?: string; UTI?: string; dialogTitle?: string }): Promise<{ ok: boolean; error?: string }>;
+}
+
+// ── Scanner API (QR / barcode) ────────────────────────────
+export interface ScannerAPI {
+  /** Prompt the user for camera permission. */
+  requestPermissions(): Promise<{ granted: boolean; status: string }>;
+  /**
+   * Scanner is camera-based; the plugin mounts the scanner component
+   * directly from device-bridge. This API exposes only the permission
+   * wrapper at the plugin-sdk level — the actual scan is a React
+   * component lifecycle.
+   */
+}
+
+// ── NFC API (tag read) ────────────────────────────────────
+export interface NfcNdefRecord {
+  type: string;
+  payload: string;
+}
+export interface NfcAPI {
+  /** Is NFC hardware present? */
+  isSupported(): Promise<boolean>;
+  /** Is NFC turned on? (Android has a toggle; iOS always enabled when supported.) */
+  isEnabled(): Promise<boolean>;
+  /** Read the next NFC tag presented to the device within the timeout. */
+  readOnce(timeoutMs?: number): Promise<{ ok: boolean; tagId?: string; records?: NfcNdefRecord[]; error?: string }>;
+}
+
+// ── Biometrics API (Face ID / Touch ID / fingerprint) ─────
+// NOTE: supersedes the original BiometricsAPI stub above. Same name,
+// richer implementation.
+export interface BiometricsAPIv2 {
+  /** What can this device do right now? */
+  capabilities(): Promise<{ hasHardware: boolean; isEnrolled: boolean; supportedTypes: Array<'fingerprint' | 'face' | 'iris'> }>;
+  /** Prompt the user. Resolves { success } or { success:false, error }. */
+  authenticate(opts: { reason: string; cancelLabel?: string; fallbackToPasscode?: boolean }): Promise<{ success: boolean; error?: string }>;
+}
+
+
+export interface PluginNative {
+  camera: CameraAPI;
+  location: LocationAPI;
+  storage: StorageAPI;
+  /** @deprecated use `biometricsV2` for the native-backed API. This stub
+   *  remains for backwards compatibility. */
+  biometrics: BiometricsAPI;
+  biometricsV2: BiometricsAPIv2;
+  notifications: NotificationsAPI;
+  haptics: HapticsAPI;
+  connectivity: ConnectivityAPI;
+  fileSystem: FileSystemAPI;
+  cookies: CookiesAPI;
+  sharing: SharingAPI;
+  scanner: ScannerAPI;
+  nfc: NfcAPI;
+}
+
+// ── Native capability flags (manifest declaration) ──────────
+
+export interface NativeCapabilities {
+  camera?: boolean;
+  location?: boolean;
+  biometrics?: boolean;
+  offline?: boolean;
+  backgroundTasks?: boolean;
+  fileSystem?: boolean;
+  notifications?: boolean;
+  bluetooth?: boolean;
+  haptics?: boolean;
+  /** Read the platform cookie jar after a WebView login flow. */
+  cookies?: boolean;
+  /** Render a native WebView (the plugin uses react-native-webview directly). */
+  webview?: boolean;
+  /** Native share sheet. */
+  sharing?: boolean;
+  /** Camera-based QR / barcode scanning. */
+  scanner?: boolean;
+  /** NFC tag reading (iOS entitlement + Android permission required). */
+  nfc?: boolean;
+  /** Real biometric auth (Face ID / Touch ID / fingerprint). */
+  biometricsV2?: boolean;
+}
+
+// ── Lifecycle hooks ─────────────────────────────────────────
+
+export interface PluginHooks {
+  onAppStart?: boolean;
+  onPushReceived?: boolean;
+  onConnectivity?: boolean;
+  onForeground?: boolean;
+  onBackground?: boolean;
+}
+
+// ── Theme tokens (matches host app theme) ───────────────────
+
+export interface ThemeTokens {
+  colors: {
+    bg: string;
+    surface: string;
+    surfaceAlt: string;
+    input: string;
+    border: string;
+    text: string;
+    textSecondary: string;
+    textMuted: string;
+    accent: string;
+    accentSoft: string;
+    success: string;
+    successSoft: string;
+    warning: string;
+    warningSoft: string;
+    error: string;
+    errorSoft: string;
+    purple: string;
+    purpleSoft: string;
+  };
+  spacing: { xs: number; sm: number; md: number; lg: number; xl: number; xxl: number };
+  fontSize: { xs: number; sm: number; md: number; lg: number; xl: number };
+  borderRadius: { sm: number; md: number; lg: number; full: number };
+  isDark: boolean;
+}
+
+// ── What every plugin receives ──────────────────────────────
+
+export interface PluginProps {
+  bridge: PluginBridge;
+  native: PluginNative;
+  theme: ThemeTokens;
+  context: PluginContext;
+  /** Engine-supplied props from `sys.focusUiPlugin(pluginId, props)`.
+   *  Plugins read these on first mount to support flows like "open with the
+   *  add modal pre-shown" or "prefill text X". Undefined when the plugin was
+   *  opened by the user (no props from engine). */
+  props?: any;
+}
+
+// ── Plugin Manifest (extended) ──────────────────────────────
+
+export type RenderMode =
+  | { mode: 'iframe'; iframeUrl: string; external?: boolean }
+  | { mode: 'react-native'; component: string; bundleId?: string; bundleUrl?: string }
+  | {
+      mode: 'adaptive';
+      iframe: { iframeUrl: string; external?: boolean };
+      reactNative: { component: string; bundleId?: string; bundleUrl?: string };
+    };
+
+export interface PluginManifest {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  type?: 'ui' | 'service' | 'hybrid';
+  render?: RenderMode;
+  native?: NativeCapabilities;
+  hooks?: PluginHooks;
+  channels?: string[] | { events: string[]; actions: string[] };
+  capabilities?: Record<string, unknown>;
+  _source?: string;
+  _connectorId?: string;
+  _mcpEndpoint?: string;
+}
+
+// ── Registration types ──────────────────────────────────────
+
+export interface RegisteredUIPlugin {
+  id: string;
+  type: 'ui' | 'hybrid';
+  capabilities?: NativeCapabilities;
+  Component: React.FC<PluginProps>;
+}
+
+export interface RegisteredServicePlugin {
+  id: string;
+  type: 'service';
+  capabilities?: NativeCapabilities;
+  hooks?: PluginHooks;
+  onStart: (props: Omit<PluginProps, 'theme'>) => Promise<void> | void;
+  onStop?: () => Promise<void> | void;
+}
+
+export type RegisteredPlugin = RegisteredUIPlugin | RegisteredServicePlugin;

package/src/sdk/useApi.ts

@@ -0,0 +1,78 @@
+/**
+ * Simple plugin API — call any connector tool.
+ *
+ * Supports THREE usage patterns:
+ *
+ *   // Pattern 1: Direct function call
+ *   const api = useApi(bridge);
+ *   const tasks = await api('task-board-mcp', 'tasks.list', {});
+ *
+ *   // Pattern 2: .call(connector, tool, args) — connector first
+ *   const api = useApi(bridge);
+ *   const tasks = await api.call('memory-mcp', 'rules.list', {});
+ *
+ *   // Pattern 3: .call(tool, args, connector) — connector last (rn-src plugins use this!)
+ *   const api = useApi(bridge);
+ *   const tasks = await api.call('memory.list', { type: 'rule' }, 'memory-mcp');
+ *
+ * All three work. The .call method auto-detects argument order.
+ */
+import { useMemo } from 'react';
+import type { PluginBridge } from './types';
+
+interface PluginApi {
+  (connectorId: string, tool: string, args?: Record<string, any>): Promise<any>;
+  call(connectorOrTool: string, toolOrArgs?: string | Record<string, any>, argsOrConnector?: Record<string, any> | string): Promise<any>;
+}
+
+/**
+ * Create a simple API function to call connector tools.
+ */
+export function useApi(bridge: PluginBridge): PluginApi {
+  return useMemo(() => {
+    // Core implementation: (connectorId, tool, args) => Promise
+    const apiFn = async (connectorId: string, tool: string, args: Record<string, any> = {}): Promise<any> => {
+      if (!bridge) {
+        throw new Error('useApi: bridge is required. Pass it from plugin props.');
+      }
+      return bridge.mcpCall(tool, args, connectorId);
+    };
+
+    // Add .call method that supports ALL THREE patterns:
+    //   api.call(connector, tool, args)  — 2nd arg is string → connector first
+    //   api.call(tool, args, connector)  — 3rd arg is string → connector last (rn-src pattern)
+    //   api.call(tool, args)             — 2 args only → use bridge default connector
+    const callMethod = async (
+      first: string,
+      second?: string | Record<string, any>,
+      third?: Record<string, any> | string,
+    ): Promise<any> => {
+      if (!bridge) {
+        throw new Error('useApi: bridge is required. Pass it from plugin props.');
+      }
+
+      if (typeof second === 'string') {
+        // api.call(connector, tool, args) — 2nd arg is tool name string
+        return bridge.mcpCall(second, (third as Record<string, any>) || {}, first);
+      }
+
+      if (typeof third === 'string') {
+        // api.call(tool, args, connector) — 3rd arg is connector ID string
+        return bridge.mcpCall(first, (second as Record<string, any>) || {}, third);
+      }
+
+      // api.call(tool, args) — no connector, use bridge default
+      return bridge.mcpCall(first, (second as Record<string, any>) || {});
+    };
+
+    // Override .call on the function to be our custom method
+    // (shadows Function.prototype.call intentionally)
+    Object.defineProperty(apiFn, 'call', {
+      value: callMethod,
+      writable: false,
+      configurable: false,
+    });
+
+    return apiFn as PluginApi;
+  }, [bridge]);
+}

package/src/sdk/usePluginTheme.ts

@@ -0,0 +1,86 @@
+/**
+ * Theme delivered to plugins via `usePluginTheme()`.
+ *
+ * Theming flows from the HOST — plugin-side fallback hex values are a no-op
+ * by design. The default is the Ada warm-paper palette (matching the
+ * reference app); hosts with their own brand call `setPluginThemeColors()`
+ * once at startup to override.
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+import { ada, spacing, fontSize, borderRadius } from '@ateam-ai-mobile/core';
+import type { ThemeTokens } from './types';
+
+type ThemeColors = ThemeTokens['colors'];
+
+// Ada palette mapped onto the plugin theme contract — mirrors the reference
+// app's useTheme.ts. Everything renders against warm paper; dark mode is on
+// the roadmap.
+const adaColors: ThemeColors = {
+  bg: ada.paper,
+  surface: ada.paperSoft,
+  surfaceAlt: ada.paperDeep,
+  input: ada.paper,
+  border: ada.border,
+  text: ada.ink,
+  textSecondary: ada.inkSoft,
+  textMuted: ada.inkMuted,
+  accent: ada.orange,
+  accentSoft: ada.orangeSoft,
+  success: '#5A8A5C',
+  successSoft: 'rgba(90,138,92,0.14)',
+  warning: '#D49A4E',
+  warningSoft: 'rgba(212,154,78,0.16)',
+  error: '#C15545',
+  errorSoft: 'rgba(193,85,69,0.14)',
+  purple: ada.orangeDeep,
+  purpleSoft: ada.orangeSoft,
+};
+
+let _colors: ThemeColors = adaColors;
+let _isDark = false;
+const _subscribers = new Set<() => void>();
+
+/** Override the plugin theme (host brand). Call once at startup — mounted
+ *  plugins re-render with the new tokens. */
+export function setPluginThemeColors(colors: Partial<ThemeColors>, opts?: { isDark?: boolean }): void {
+  _colors = { ...adaColors, ...colors };
+  if (opts?.isDark !== undefined) _isDark = opts.isDark;
+  _subscribers.forEach(fn => fn());
+}
+
+function subscribe(fn: () => void): () => void {
+  _subscribers.add(fn);
+  return () => { _subscribers.delete(fn); };
+}
+
+export function usePluginTheme(): ThemeTokens {
+  const colors = useSyncExternalStore(subscribe, () => _colors);
+  const isDark = useSyncExternalStore(subscribe, () => _isDark);
+
+  // Memoize so plugins don't re-render on every host render.
+  return useMemo(() => ({
+    colors,
+    spacing: {
+      xs: spacing.xs,
+      sm: spacing.sm,
+      md: spacing.md,
+      lg: spacing.lg,
+      xl: spacing.xl,
+      xxl: spacing.xxl,
+    },
+    fontSize: {
+      xs: fontSize.xs,
+      sm: fontSize.sm,
+      md: fontSize.md,
+      lg: fontSize.lg,
+      xl: fontSize.xl,
+    },
+    borderRadius: {
+      sm: borderRadius.sm,
+      md: borderRadius.md,
+      lg: borderRadius.lg,
+      full: borderRadius.full,
+    },
+    isDark,
+  }), [colors, isDark]);
+}