@floe-ai/sdk 0.1.0-dev.3 → 0.1.0-dev.30

package/dist-sdk/index.d.ts

@@ -1,26 +1,8 @@
-declare interface ContextData {
-    screenshot?: string;
-    url: string;
-    structure: PageStructure;
-    timestamp: number;
-    userProfile?: any;
-}
-
-declare interface ElementInfo {
-    selector: string;
-    type: string;
-    text?: string;
-    visible: boolean;
-    position: DOMRect;
-    attributes: Record<string, string>;
-}
-
-declare class EventEmitter {
-    private events;
-    on(event: string, listener: (...args: any[]) => void): this;
-    off(event: string, listener: (...args: any[]) => void): this;
-    emit(event: string, ...args: any[]): boolean;
-}
+import { ContextData } from './types';
+import { EventEmitter } from './types';
+import { ScreenshotOptions } from './types';
+import { SDKConfig } from './types';
+import { UIAction } from './types';
 
 /**
  * Initialize Floe SDK
@@ -72,6 +54,20 @@ export declare interface FloeConfig {
     userInfo?: FloeUserInfo;
     /** Skip the welcome modal for returning users */
     skipOnboardingModal?: boolean;
+    /** Nudge configuration - Intercom Fin-style sliding notification */
+    nudge?: FloeNudgeConfig;
+}
+
+/**
+ * Nudge configuration for Intercom Fin-style sliding notification
+ */
+export declare interface FloeNudgeConfig {
+    /** Main nudge message (default: "Hi 👋 How can I help you today?") */
+    text?: string;
+    /** Auto-show nudge when minimized (default: true) */
+    autoShow?: boolean;
+    /** Auto-hide after ms, 0 = never (default: 0) */
+    autoHideDelay?: number;
 }
 
 /**
@@ -126,6 +122,7 @@ declare class OnboardingSDK extends EventEmitter {
     private botAudioAnalyzer;
     private userAudioAnalyzer;
     private userMicStream;
+    private userMicStreamRequestId;
     private audioElements;
     private pageTracker;
     private screenShareEnabled;
@@ -138,12 +135,20 @@ declare class OnboardingSDK extends EventEmitter {
     private endUserStatus;
     private connectionProgress;
     private isReturningUser;
+    private hasSkippedOnboarding;
     private _isMinimized;
+    private textModeEnabled;
+    private planProgress;
     constructor(config: SDKConfig);
     /**
      * Generate unique session ID
      */
     private generateSessionId;
+    /**
+     * Validate client key and check if bot is enabled for this site.
+     * This is called before showing any UI to ensure the bot should be displayed.
+     */
+    private validateClientKeyAndBotStatus;
     /**
      * Start screen sharing: sends the tab/window as a WebRTC video track to Pipecat.
      */
@@ -152,10 +157,20 @@ declare class OnboardingSDK extends EventEmitter {
      * Initialize the SDK and connect to servers
      */
     init(): Promise<void>;
+    /**
+     * Setup navigation detection for page navigation events.
+     * Ensures navigationCompleteDetector is instantiated and started regardless
+     * of text/voice mode — navigation tracking is needed in both modes so the
+     * server always knows the current page context.
+     */
+    private setupNavigationDetection;
     /**
      * Setup audio playback for bot audio tracks with real-time level analysis.
-     * Centralizes all audio element handling, analyzer instantiation, and navigation detector setup.
-     * This is the single source of truth for audio/navigation initialization to prevent duplicates.
+     * Centralizes all audio element handling and analyzer instantiation.
+     * This is the single source of truth for audio initialization to prevent duplicates.
+     *
+     * Note: Navigation detection is handled separately by setupNavigationDetection()
+     * so it works in both voice and text modes.
      */
     private setupAudioPlayback;
     /**
@@ -269,6 +284,32 @@ declare class OnboardingSDK extends EventEmitter {
      * Actions: highlight, click, type, focus, hover, scroll
      */
     private handleHybridAction;
+    /**
+     * Wait for navigation to complete by polling the current URL.
+     * Compares normalized URL components (origin, pathname, search, hash)
+     * to avoid false positives from substring matching.
+     *
+     * @param expectedUrl - Absolute URL we're navigating to (already resolved)
+     * @param timeoutMs - Maximum time to wait in milliseconds
+     * @returns true if navigation was observed, false if timed out
+     */
+    private waitForNavigation;
+    /**
+     * Finalize any pending bot navigation that was interrupted by a full-page load.
+     *
+     * When navigate sets `window.location.href` for a cross-origin or MPA target the
+     * entire JS context is destroyed, so the optimistic sendMetadata never fires.
+     * The navigate handler persists a record to sessionStorage before triggering
+     * the navigation.  On the next page load this method reads it back, validates
+     * that we actually arrived at the expected destination, and sends the final
+     * bot_action_complete metadata so the server can auto-advance the task.
+     *
+     * Called once during init() — safe to call before the WebRTC transport is
+     * connected because sendMetadata already guards on `this.isConnected`.
+     * We retry briefly after init to cover the case where the transport
+     * connects a moment later.
+     */
+    private _finalizePendingNavigation;
     /**
      * Check a precondition and report the result to the server.
      * Used for conditional task execution (e.g., check if an option exists before selecting it).
@@ -291,8 +332,23 @@ declare class OnboardingSDK extends EventEmitter {
      */
     private handleDropdownOptionClick;
     /**
-     * Find a visible dropdown option by text
-     * Uses STRICT matching to avoid selecting wrong options
+     * Check if a dropdown/listbox is currently open on the page.
+     * Delegates to shared dropdown-helpers module.
+     */
+    private isDropdownCurrentlyOpen;
+    /**
+     * Find the search input within or associated with a dropdown.
+     * Delegates to shared dropdown-helpers module.
+     */
+    private findDropdownSearchInput;
+    /**
+     * Type text into a dropdown search input to filter options, then find the target option.
+     * Delegates to shared dropdown-helpers module.
+     */
+    private typeToFilterDropdown;
+    /**
+     * Find a visible dropdown option by text.
+     * Delegates to shared dropdown-helpers module.
      */
     private findVisibleDropdownOption;
     /**
@@ -345,6 +401,24 @@ declare class OnboardingSDK extends EventEmitter {
      * @returns true if action succeeded
      */
     private executeActionFast;
+    /**
+     * Handle direct API execution request from server
+     * Part of Capability-Based Guidance - allows bot to execute APIs directly
+     *
+     * The SDK makes the fetch() call with the user's session/cookies,
+     * then reports the result back to the bot.
+     */
+    private handleExecuteApi;
+    /**
+     * Evaluate a JSONPath-style condition (simple implementation)
+     * Supports: $.path.to.value == "expected" or just $.path.to.value (truthy check)
+     */
+    private evaluateJsonPathCondition;
+    /**
+     * Extract value from object using simple JSONPath
+     * Supports: $.path.to.value or just path.to.value
+     */
+    private extractJsonPath;
     /**
      * Handle batched navigation request from server
      * Executes multiple navigation steps quickly without LLM round-trips
@@ -387,9 +461,25 @@ declare class OnboardingSDK extends EventEmitter {
      * Public API Methods
      */
     /**
-     * Send text message
+     * Send text message (low-level)
      */
     sendText(text: string): Promise<void>;
+    /**
+     * Toggle text mode on/off
+     * When text mode is enabled, mic is muted and user types messages.
+     * When disabled, mic is re-enabled and voice mode resumes.
+     */
+    toggleTextMode(): void;
+    /**
+     * Send a text message with optimistic UI update.
+     * Uses custom 'text_message' RTVI message type (Approach B) instead of
+     * Pipecat's native send-text, so the server-side handler can run the full
+     * processing pipeline (state machine, system prompt refresh, activity
+     * recording, goal extraction, transcript recording) — not just LLM injection.
+     *
+     * In text mode, TTS is skipped (audio_response: false).
+     */
+    sendTextMessage(text: string): Promise<void>;
     /**
      * Toggle microphone mute
      */
@@ -503,59 +593,4 @@ declare class OnboardingSDK extends EventEmitter {
     disconnect(): Promise<void>;
 }
 
-declare interface PageStructure {
-    title: string;
-    url: string;
-    elements: ElementInfo[];
-    viewport: {
-        width: number;
-        height: number;
-    };
-}
-
-declare interface ScreenshotOptions {
-    redact?: boolean;
-    scale?: number;
-    quality?: number;
-    format?: 'webp' | 'jpeg' | 'png';
-}
-
-declare interface SDKConfig {
-    clientKey: string;
-    apiUrl?: string;
-    enableVideo?: boolean;
-    enableAudio?: boolean;
-    enableScreenCapture?: boolean;
-    redactionPatterns?: Record<string, RegExp>;
-    debug?: boolean;
-    industry?: string;
-    useCase?: string;
-    companyName?: string;
-    companySize?: string;
-    role?: string;
-    userInfo?: UserInfo;
-    skipOnboardingModal?: boolean;
-    enableDiscoveryPopup?: boolean;
-}
-
-declare interface UIAction {
-    type: 'click' | 'type' | 'select' | 'hover' | 'scroll';
-    selector: string;
-    value?: string;
-    description?: string;
-}
-
-/**
- * AI Onboarding Agent SDK
- * Voice-first onboarding platform with WebRTC connectivity to Pipecat server
- */
-declare interface UserInfo {
-    externalId?: string;
-    email?: string;
-    name?: string;
-    company?: string;
-    designation?: string;
-    metadata?: Record<string, any>;
-}
-
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floe-ai/sdk",
-  "version": "0.1.0-dev.3",
+  "version": "0.1.0-dev.30",
   "description": "Floe AI Onboarding SDK for React applications",
   "type": "module",
   "main": "./dist-sdk/floe-sdk.es.js",
@@ -35,7 +35,9 @@
     "serve": "node serve-dist.js",
     "serve:sdk": "vite preview --config vite.config.sdk.ts --port 5174",
     "clean": "rm -rf dist dist-sdk",
-    "prepublishOnly": "npm run build:sdk"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -52,6 +54,7 @@
     "@types/react": "^18.2.0 || ^19.0.0",
     "@types/react-dom": "^18.2.0 || ^19.0.0",
     "@vitejs/plugin-react": "^4.2.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "patch-package": "^8.0.0",
@@ -59,7 +62,8 @@
     "react-dom": "^18.2.0",
     "typescript": "^5.3.0",
     "vite": "^5.0.0",
-    "vite-plugin-dts": "^4.0.0"
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.0.18"
   },
   "keywords": [
     "floe",