@appilots/sdk 0.2.0 → 0.3.0

package/dist/index-BYVRBzjJ.d.ts

@@ -0,0 +1,619 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as _appilots_client_core from '@appilots/client-core';
+import { AgentPermissions, AppilotsUser, AppilotsClient, AppilotsEventHandler, AppilotsEvent, RemotePersonalization, ChatMessage, AgentAction, EscalationState } from '@appilots/client-core';
+
+interface AppilotsConfig {
+    /** Project ID from the Appilots dashboard */
+    projectId: string;
+    /** API base URL (defaults to Appilots cloud) */
+    apiBaseUrl?: string;
+    /** SDK API key (ak_...) for authenticating with the backend */
+    apiKey?: string;
+    /** Agent permissions for this app instance */
+    permissions?: AgentPermissions;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Host app version (e.g. package.json version). Forwarded to the API
+     * as `X-App-Version` so the server can serve the MCP document matching
+     * this app build (OTA fleets run several versions at once).
+     */
+    appVersion?: string;
+    /** Version of the MCP doc bundled with this build (stale-doc telemetry). */
+    mcpVersion?: string;
+    /**
+     * Who the app's current user is. Sessions carry `user.id` as
+     * externalUserId, and name/identifiers are upserted into the
+     * end-users registry so the support queue shows a person instead of
+     * "Usuário anônimo". Identifiers never reach the LLM.
+     */
+    user?: AppilotsUser;
+    /**
+     * Fetch the dashboard-configured personalization (theme, branding,
+     * FAB color, locale...) once on provider mount and apply it as a
+     * fallback for AppilotsChat props not set explicitly in code.
+     *
+     * Set to `false` to opt out — this is the SDK's only automatic
+     * network call before the user interacts, so apps with strict
+     * network/privacy posture can keep today's 100%-manual behavior.
+     * @default true
+     */
+    fetchPersonalization?: boolean;
+}
+interface AppilotsProviderProps {
+    /**
+     * SDK config. If omitted, auto-loads from `.appilotsrc` via the Metro
+     * resolver (requires `withAppilots()` in metro.config.js).
+     */
+    config?: AppilotsConfig;
+    children: React__default.ReactNode;
+    /** Optional custom client instance (if not provided, one is auto-created from config) */
+    client?: AppilotsClient;
+}
+interface AppilotsContextValue {
+    config: AppilotsConfig;
+    client: AppilotsClient;
+    subscribe: (handler: AppilotsEventHandler) => () => void;
+    emit: (event: AppilotsEvent) => void;
+    /**
+     * Dashboard-configured personalization fetched on mount. `null` until
+     * the fetch resolves — and forever, if it fails or is opted out
+     * (`fetchPersonalization: false`). Consumers must treat `null` as
+     * "use props/defaults"; the chat renders immediately with defaults
+     * and re-renders once this lands (accepted cold-start flash).
+     */
+    remotePersonalization: RemotePersonalization | null;
+}
+declare function AppilotsProvider({ config: configProp, children, client: externalClient }: AppilotsProviderProps): React__default.JSX.Element;
+declare function useAppilotsContext(): AppilotsContextValue;
+
+/**
+ * Convenience hook that combines all Appilots hooks into a single return value.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, currentScreen, pendingActions } = useAppilots();
+ * ```
+ */
+declare function useAppilots(): {
+    config: AppilotsConfig;
+    client: _appilots_client_core.AppilotsClient;
+    messages: _appilots_client_core.ChatMessage[];
+    isLoading: boolean;
+    error: string | null;
+    sendMessage: (content: string) => Promise<void>;
+    clearMessages: () => void;
+    clearError: () => void;
+    currentScreen: string | null;
+    navigationHistory: string[];
+    setCurrentScreen: (screenName: string) => void;
+    navigationRef: React$1.MutableRefObject<any>;
+    pendingActions: _appilots_client_core.AgentAction[];
+    executingActions: _appilots_client_core.AgentAction[];
+    completedActions: _appilots_client_core.AgentAction[];
+    approveAction: (actionId: string) => Promise<boolean>;
+    rejectAction: (actionId: string) => Promise<void>;
+};
+
+interface UseAppilotsNavigationReturn {
+    currentScreen: string | null;
+    navigationHistory: string[];
+    setCurrentScreen: (screenName: string) => void;
+    /** Navigation ref setter — attach to your NavigationContainer */
+    navigationRef: React.MutableRefObject<any>;
+}
+/**
+ * Hook for tracking navigation state and enabling agent-driven navigation.
+ *
+ * @example
+ * ```tsx
+ * const { currentScreen, navigationRef } = useAppilotsNavigation();
+ *
+ * return (
+ *   <NavigationContainer ref={navigationRef}>
+ *     <Stack.Navigator />
+ *   </NavigationContainer>
+ * );
+ * ```
+ */
+declare function useAppilotsNavigation(): UseAppilotsNavigationReturn;
+
+/**
+ * Localized copy for escalation system messages, injected by the chat
+ * surface (the hook has no i18n access — same pattern as errorPrefix).
+ * When omitted, no system messages are appended but the state machine
+ * still works.
+ */
+interface EscalationStrings {
+    /** Appended right after the escalation is created. */
+    requested: string;
+    /** Appended when an operator claims the conversation. */
+    connected: string;
+    /** Appended when the operator resolves — AI takes over again. */
+    resolved: string;
+    /** Content of the offer chip message appended when the agent gives up. */
+    offer: string;
+}
+interface UseAppilotsChatReturn {
+    messages: ChatMessage[];
+    isLoading: boolean;
+    loadingStatusKey: 'thinking' | 'statusAnalyzing' | 'statusWaitingApp' | 'statusAdjusting';
+    error: string | null;
+    pendingActions: AgentAction[];
+    /**
+     * Open escalation, or null. While set, `sendMessage` routes to the
+     * human channel — the agent session itself is never interrupted.
+     */
+    escalation: EscalationState | null;
+    /**
+     * Hand the conversation to a human operator (docs/human-escalation.md).
+     * Idempotent while an escalation is open. `agent_gave_up` is used by
+     * the auto-offer chip; the header button sends `user_requested`.
+     */
+    requestHuman: (reason?: 'user_requested' | 'agent_gave_up') => Promise<void>;
+    sendMessage: (content: string) => Promise<void>;
+    /**
+     * Cancels the in-flight generation (OKR-008 KR4). Streamed partial
+     * text is kept in the transcript; a no-op when nothing is in flight.
+     * Cancellation only covers the generation phase — once actions start
+     * executing on-device they run to completion (interrupting a half-done
+     * form fill would leave the app in a worse state than finishing it).
+     */
+    cancelMessage: () => void;
+    clearMessages: () => void;
+    clearError: () => void;
+}
+interface UseAppilotsChatOptions {
+    /** User-facing prefix for client-side failures before the relay can answer. */
+    errorPrefix?: string;
+    /**
+     * Stream assistant replies token-by-token via SSE (default true).
+     * When the streaming transport fails before any output, the hook
+     * falls back to the non-streaming endpoint transparently.
+     */
+    streaming?: boolean;
+    /** Localized escalation copy — see EscalationStrings. */
+    escalationStrings?: EscalationStrings;
+}
+/**
+ * Hook for managing chat state and sending messages to the Appilots agent.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, isLoading } = useAppilotsChat();
+ *
+ * const handleSend = () => {
+ *   sendMessage('Navigate to settings');
+ * };
+ * ```
+ */
+declare function useAppilotsChat(options?: UseAppilotsChatOptions): UseAppilotsChatReturn;
+
+interface UseAppilotsActionsOptions {
+    /**
+     * Navigation ref from useAppilotsNavigation().
+     * Required for navigate actions to work.
+     */
+    navigationRef?: React.MutableRefObject<any>;
+    /**
+     * If true, actions are executed automatically without user approval.
+     * Confirm actions always require approval regardless of this setting.
+     * @default false
+     */
+    autoExecute?: boolean;
+}
+interface UseAppilotsActionsReturn {
+    pendingActions: AgentAction[];
+    executingActions: AgentAction[];
+    completedActions: AgentAction[];
+    approveAction: (actionId: string) => Promise<boolean>;
+    rejectAction: (actionId: string) => Promise<void>;
+}
+/**
+ * Hook for monitoring and controlling agent actions.
+ *
+ * Now integrates with the ActionExecutor to actually execute actions
+ * against live UI components via the ComponentRegistry.
+ *
+ * @example
+ * ```tsx
+ * const { navigationRef } = useAppilotsNavigation();
+ * const { pendingActions, approveAction, rejectAction } = useAppilotsActions({
+ *   navigationRef,
+ *   autoExecute: false,
+ * });
+ * ```
+ */
+declare function useAppilotsActions(options?: UseAppilotsActionsOptions): UseAppilotsActionsReturn;
+
+/**
+ * ComponentRegistry — Central registry mapping component IDs to their
+ * refs, callbacks, and metadata so the ActionExecutor can find and
+ * interact with live UI elements.
+ *
+ * Screens register their interactive components via hooks
+ * (useAppilotsField, useAppilotsTarget, useAppilotsToggle).
+ * When the AI agent returns an action (e.g. form_fill with fieldId "plate"),
+ * the executor looks up "plate" here and calls the associated setter.
+ */
+type ComponentKind = 'field' | 'target' | 'toggle' | 'slider';
+interface FieldEntry {
+    kind: 'field';
+    /** Current value of the field */
+    getValue: () => string;
+    /** Set the field value programmatically */
+    setValue: (value: string) => void;
+    /** Optional: focus the input */
+    focus?: () => void;
+    /** Field type hint for the executor */
+    fieldType?: 'text' | 'select' | 'toggle' | 'date' | 'number' | 'custom';
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this field is registered */
+    screen?: string;
+}
+interface TargetEntry {
+    kind: 'target';
+    /** Execute the primary action (press) */
+    press: () => void;
+    /** Optional: long press */
+    longPress?: () => void;
+    /** Optional: scroll to this element */
+    scrollTo?: () => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this target is registered */
+    screen?: string;
+}
+interface ToggleEntry {
+    kind: 'toggle';
+    /** Current value */
+    getValue: () => boolean;
+    /** Set the toggle value */
+    setValue: (value: boolean) => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this toggle is registered */
+    screen?: string;
+}
+interface SliderEntry {
+    kind: 'slider';
+    /** Current numeric value */
+    getValue: () => number;
+    /**
+     * Set the slider value. The executor clamps to [min, max] and snaps
+     * to `step` BEFORE calling this, so implementations can trust the
+     * value — but re-validating is harmless.
+     */
+    setValue: (value: number) => void;
+    /** Lower bound (inclusive) */
+    min: number;
+    /** Upper bound (inclusive) */
+    max: number;
+    /** Step to snap to (omitted = continuous) */
+    step?: number;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this slider is registered */
+    screen?: string;
+}
+type ComponentEntry = FieldEntry | TargetEntry | ToggleEntry | SliderEntry;
+type Listener = (id: string, entry: ComponentEntry | null) => void;
+/**
+ * Public type for a registry instance. Both the singleton and any
+ * instance returned by `createComponentRegistry()` satisfy this.
+ *
+ * The class itself stays internal — devs construct via the factory
+ * to keep the surface minimal and future-proof.
+ */
+type ComponentRegistry = ComponentRegistryImpl;
+declare class ComponentRegistryImpl {
+    private components;
+    private listeners;
+    /**
+     * Register a component. If an entry with the same ID already exists,
+     * it is replaced (this handles re-renders / hot-reload).
+     */
+    register(id: string, entry: ComponentEntry): void;
+    /**
+     * Unregister a component (typically on unmount).
+     */
+    unregister(id: string): void;
+    /**
+     * Look up a component by its ID.
+     */
+    get(id: string): ComponentEntry | undefined;
+    /**
+     * Get a typed entry or undefined.
+     */
+    getField(id: string): FieldEntry | undefined;
+    getTarget(id: string): TargetEntry | undefined;
+    getToggle(id: string): ToggleEntry | undefined;
+    getSlider(id: string): SliderEntry | undefined;
+    /**
+     * Get all components on a given screen.
+     */
+    getByScreen(screen: string): Map<string, ComponentEntry>;
+    /**
+     * Get all components of a given kind.
+     */
+    getByKind(kind: ComponentKind): Map<string, ComponentEntry>;
+    /**
+     * List all registered component IDs with their kind and screen.
+     * Useful for debugging and for the AI to know what's available.
+     */
+    snapshot(): Array<{
+        id: string;
+        kind: ComponentKind;
+        screen?: string;
+        label?: string;
+    }>;
+    /**
+     * Subscribe to registry changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: Listener): () => void;
+    /**
+     * Clear all entries (useful for testing or full reset).
+     */
+    clear(): void;
+    /** Number of registered components */
+    get size(): number;
+    private notify;
+}
+/**
+ * Singleton registry instance shared across the entire SDK by default.
+ *
+ * Apps with a single Appilots session (the overwhelmingly common case)
+ * never need anything else — hooks, handlers, and auto-tracking all
+ * read from this singleton.
+ *
+ * For multi-tenant or micro-front-end setups where two Appilots
+ * sessions might coexist in the same JS process, use
+ * `createComponentRegistry()` to obtain a fresh instance and pass it
+ * via `<AppilotsRegistryProvider value={...}>`. Hooks resolve via
+ * context first, falling back to this singleton.
+ *
+ * The singleton stays in place to keep the existing public API stable
+ * — pré-mortem 2.8 is "future risk", not "current bug".
+ */
+declare const componentRegistry: ComponentRegistry;
+/**
+ * Create a fresh, isolated ComponentRegistry instance. Pair with
+ * `<AppilotsRegistryProvider value={...}>` to scope auto-tracking and
+ * hooks to that registry instead of the global singleton.
+ *
+ * @example
+ * ```tsx
+ * const tenantRegistry = createComponentRegistry();
+ * <AppilotsRegistryProvider value={tenantRegistry}>
+ *   <TenantApp />
+ * </AppilotsRegistryProvider>
+ * ```
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+
+/**
+ * useAppilotsField — Register a text input (or similar field) with the
+ * ComponentRegistry so the AI agent can fill it via form_fill actions.
+ *
+ * Usage:
+ * ```tsx
+ * const [plate, setPlate] = useState('');
+ * const plateRef = useRef<TextInput>(null);
+ *
+ * useAppilotsField('plate', {
+ *   value: plate,
+ *   onChangeText: setPlate,
+ *   ref: plateRef,           // optional — enables focus()
+ *   fieldType: 'text',       // optional — hint for executor
+ *   label: 'License Plate',  // optional — human-readable name
+ *   screen: 'VehicleForm',   // optional — scoped to screen
+ * });
+ *
+ * return <TextInput ref={plateRef} value={plate} onChangeText={setPlate} />;
+ * ```
+ */
+
+interface UseAppilotsFieldOptions {
+    /** Current value of the field */
+    value: string;
+    /** Callback to update the value (same signature as TextInput.onChangeText) */
+    onChangeText: (text: string) => void;
+    /** Optional ref to the TextInput for focus support */
+    ref?: React.RefObject<any>;
+    /** Field type hint */
+    fieldType?: FieldEntry['fieldType'];
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this field belongs to */
+    screen?: string;
+}
+/**
+ * Register a field with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier for this field (e.g. "plate", "customerName")
+ * @param options - Field configuration
+ */
+declare function useAppilotsField(id: string, options: UseAppilotsFieldOptions): void;
+
+/**
+ * useAppilotsTarget — Register a pressable UI element (button, card, link)
+ * with the ComponentRegistry so the AI agent can interact with it.
+ *
+ * Usage:
+ * ```tsx
+ * const handleSubmit = () => { ... };
+ *
+ * useAppilotsTarget('submitVehicle', {
+ *   onPress: handleSubmit,
+ *   label: 'Submit Vehicle',
+ *   screen: 'VehicleForm',
+ * });
+ *
+ * return <Button title="Submit" onPress={handleSubmit} />;
+ * ```
+ */
+interface UseAppilotsTargetOptions {
+    /** Primary press handler */
+    onPress: () => void;
+    /** Optional long-press handler */
+    onLongPress?: () => void;
+    /** Optional scroll-to handler (scroll this element into view) */
+    onScrollTo?: () => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this target belongs to */
+    screen?: string;
+}
+/**
+ * Register a pressable target with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "submitVehicle", "openSettings")
+ * @param options - Target configuration
+ */
+declare function useAppilotsTarget(id: string, options: UseAppilotsTargetOptions): void;
+
+/**
+ * useAppilotsToggle — Register a toggle/switch with the ComponentRegistry
+ * so the AI agent can flip it via ui_interaction actions.
+ *
+ * Usage:
+ * ```tsx
+ * const [pushEnabled, setPushEnabled] = useState(false);
+ *
+ * useAppilotsToggle('pushNotifications', {
+ *   value: pushEnabled,
+ *   onValueChange: setPushEnabled,
+ *   label: 'Push Notifications',
+ *   screen: 'Settings',
+ * });
+ *
+ * return <Switch value={pushEnabled} onValueChange={setPushEnabled} />;
+ * ```
+ */
+interface UseAppilotsToggleOptions {
+    /** Current toggle value */
+    value: boolean;
+    /** Callback when value changes */
+    onValueChange: (value: boolean) => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this toggle belongs to */
+    screen?: string;
+}
+/**
+ * Register a toggle with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "pushNotifications", "darkMode")
+ * @param options - Toggle configuration
+ */
+declare function useAppilotsToggle(id: string, options: UseAppilotsToggleOptions): void;
+
+/**
+ * useAppilotsSlider — Register a slider / adjustable numeric control with
+ * the ComponentRegistry so the AI agent can set it via
+ * `ui_interaction action="set_value"` actions.
+ *
+ * Registration is what makes a slider agent-operable end to end:
+ * captureSnapshot() reads this entry to advertise the slider (with
+ * min/max/step) in the observation, and the executor dispatches
+ * set_value through the same entry — clamping to [min, max] and
+ * snapping to `step` before calling onValueChange.
+ *
+ * Usage:
+ * ```tsx
+ * const [mileage, setMileage] = useState(0);
+ *
+ * useAppilotsSlider('quilometragem', {
+ *   value: mileage,
+ *   onValueChange: setMileage,
+ *   min: 0,
+ *   max: 300000,
+ *   step: 500,
+ *   label: 'Quilometragem',
+ *   screen: 'VehicleCreate',
+ * });
+ *
+ * return <MySlider value={mileage} onChange={setMileage} min={0} max={300000} />;
+ * ```
+ */
+interface UseAppilotsSliderOptions {
+    /** Current slider value */
+    value: number;
+    /** Callback when value changes */
+    onValueChange: (value: number) => void;
+    /** Lower bound (inclusive) — advertised in the observation and enforced by the executor */
+    min: number;
+    /** Upper bound (inclusive) — advertised in the observation and enforced by the executor */
+    max: number;
+    /** Step the executor snaps to (omit for a continuous slider) */
+    step?: number;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this slider belongs to */
+    screen?: string;
+}
+/**
+ * Register a slider with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "quilometragem", "volume")
+ * @param options - Slider configuration
+ */
+declare function useAppilotsSlider(id: string, options: UseAppilotsSliderOptions): void;
+
+interface SuggestedPrompt {
+    /** Display label shown on the chip and inserted into the input on tap. */
+    text: string;
+    /** Where this prompt came from. Useful for analytics or theming. */
+    source: 'dev-defined' | 'screen-popular' | 'global-popular';
+}
+interface UseSuggestedPromptsOptions {
+    /**
+     * Whether the chat is currently open. Hook only fetches while open, so
+     * suggestions don't waste a roundtrip when the chat is minimised.
+     */
+    enabled: boolean;
+    /** Max chips to return. Default 4. */
+    limit?: number;
+}
+interface UseSuggestedPromptsReturn {
+    prompts: SuggestedPrompt[];
+    isLoading: boolean;
+    /** Re-runs the fetch — call after navigation so chips refresh. */
+    refetch: () => void;
+}
+/**
+ * Returns ranked suggested prompts to render as chips in the chat
+ * empty-state. Three sources are merged in priority order:
+ *
+ *   1. **Dev-defined** — from `registerScreen({ suggestedPrompts })` in the
+ *      current app, read synchronously from the local screen registry.
+ *      First-class signal, always wins.
+ *
+ *   2. **Screen-popular** — historical user prompts sent FROM this screen,
+ *      mined server-side from agentMessages history.
+ *
+ *   3. **Global-popular** — historical user prompts across the project.
+ *      Fallback for screens with no history yet.
+ *
+ * The hook re-fetches whenever the active screen changes so chips always
+ * match where the user is right now. Server response is cached 1h, so
+ * fetches are cheap.
+ *
+ * @example
+ * ```tsx
+ * const { prompts } = useSuggestedPrompts({ enabled: chatVisible });
+ * return prompts.map((p) => (
+ *   <Chip key={p.text} onPress={() => setInput(p.text)}>{p.text}</Chip>
+ * ));
+ * ```
+ */
+declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
+
+export { type AppilotsConfig as A, type ComponentRegistry as C, type FieldEntry as F, type SliderEntry as S, type TargetEntry as T, type UseAppilotsFieldOptions as U, AppilotsProvider as a, type AppilotsProviderProps as b, type ComponentEntry as c, type ComponentKind as d, type SuggestedPrompt as e, type ToggleEntry as f, type UseAppilotsSliderOptions as g, type UseAppilotsTargetOptions as h, type UseAppilotsToggleOptions as i, type UseSuggestedPromptsOptions as j, type UseSuggestedPromptsReturn as k, componentRegistry as l, createComponentRegistry as m, useAppilotsActions as n, useAppilotsChat as o, useAppilotsContext as p, useAppilotsField as q, useAppilotsNavigation as r, useAppilotsSlider as s, useAppilotsTarget as t, useAppilots as u, useAppilotsToggle as v, useSuggestedPrompts as w };