guideai-app 0.4.3-9 → 0.5.0

package/dist/utils/positionUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Position and layout utilities for GuideAI components.
+ * Handles mic position, popup position, transcript position, and z-index config.
+ */
+import type { GuideAIPosition, PopupPosition, TranscriptPosition } from '../types/GuideAI.types';
+export declare const DEFAULT_POSITION: {
+    readonly bottom: "20px";
+    readonly left: "50%";
+    readonly transform: "translateX(-50%)";
+};
+export interface ZIndexConfig {
+    main: number;
+    transcript: number;
+    microphone: number;
+    onboarding: number;
+}
+/**
+ * Get default mic position (bottom center).
+ */
+export declare function getDefaultPosition(): typeof DEFAULT_POSITION;
+/**
+ * Calculate popup position based on mic position prop.
+ * Used for onboarding and welcome bubble placement.
+ */
+export declare function calculatePositionFromProp(position?: GuideAIPosition | null): PopupPosition;
+/**
+ * Get transcript box position (left or right) based on mic position.
+ */
+export declare function getTranscriptPosition(transcriptOptions?: {
+    position?: TranscriptPosition;
+} | null, position?: GuideAIPosition | null): TranscriptPosition;
+/**
+ * Get z-index configuration from position prop.
+ */
+export declare function getZIndexConfig(position?: GuideAIPosition | null): ZIndexConfig;
+/**
+ * Get position styles for mic/base component (position only, no z-index).
+ */
+export declare function getPositionStyles(position?: GuideAIPosition | null): Record<string, string>;

package/dist/utils/webrtcConnection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * WebRTC connection manager for OpenAI Realtime API.
+ * Uses unified initialize endpoint (conversation + WebRTC SDP exchange).
+ * See: https://developers.openai.com/api/docs/guides/realtime-webrtc
+ */
+import { DataChannelManager, DataChannelConfig } from './dataChannel';
+/** Ref-like holder for mutable references (avoids React dependency in utils) */
+export interface RefLike<T> {
+    current: T | null;
+}
+export interface InitializeSessionData {
+    id: string;
+}
+export interface WebRTCConnectionConfig {
+    /** Microphone stream, or null for text-only mode */
+    audioStream: MediaStream | null;
+    /** Initialize endpoint URL (e.g. /api/initialize) - returns { id, answerSdp } */
+    initializeEndpoint: string;
+    /** Payload for initialize (organizationKey, user, conversationId */
+    initializePayload: {
+        organizationKey: string;
+        user?: string;
+        conversationId?: string | null;
+    };
+    /** Called when session data is received (id) */
+    onSessionData?: (data: InitializeSessionData) => void;
+    /** Whether running in Chrome extension content script (affects audio setup) */
+    isContentScript?: boolean;
+    /** Config for the data channel manager */
+    dataChannelConfig: DataChannelConfig;
+    /** Optional refs to populate with created objects */
+    refs?: {
+        peerConnection?: RefLike<RTCPeerConnection>;
+        dataChannelManager?: RefLike<DataChannelManager>;
+        audioElement?: RefLike<HTMLAudioElement>;
+    };
+    /** Optional existing audio element to reuse (avoids duplicate elements on reconnect) */
+    existingAudioElement?: HTMLAudioElement | null;
+}
+/**
+ * Manages WebRTC connection via unified initialize endpoint.
+ * Handles peer connection setup, SDP exchange (via initialize), and data channel creation.
+ */
+export declare class WebRTCConnection {
+    private config;
+    private peerConnection;
+    private dataChannelManager;
+    private audioElement;
+    constructor(config: WebRTCConnectionConfig);
+    /**
+     * Establish WebRTC connection via initialize endpoint.
+     */
+    connect(): Promise<boolean>;
+    private createAudioElement;
+    close(): void;
+}

package/dist/visualContext/VisualContextScheduler.d.ts

@@ -4,40 +4,37 @@ export declare class VisualContextScheduler {
     private screenshotProvider;
     private isRunning;
     private isCaptureInFlight;
-    private hasPendingCapture;
-    private pendingReason;
-    private lastHash;
     private lastCaptureAt;
-    private lastScrollAt;
-    private lastDomBurstAt;
-    private domChangeCounter;
-    private domBurstWindowMs;
-    private domBurstThreshold;
     private minIntervalMs;
-    private scrollDebounceMs;
-    private scrollTimer;
     private mode;
     private buttonObserver;
-    private domObserver;
+    private intervalId;
     private targetWidth;
     private rootElement;
     private quality;
     private minQuality;
     private maxBytes;
     private onFrame;
+    private isBufferFull;
+    private hasSignificantDomChange;
+    private markDomChangeConsumed;
+    private onError;
+    private pendingRequestResolve;
     constructor(getContainer: () => HTMLElement | null, screenshotProvider: ScreenshotProvider, onFrame: (frame: ScreenshotFrame) => void, options?: {
         targetWidth?: number;
         quality?: number;
         minQuality?: number;
         maxBytes?: number;
+        isBufferFull?: () => boolean;
+        hasSignificantDomChange?: () => boolean;
+        markDomChangeConsumed?: () => void;
+        onError?: (message: string, data?: any) => void;
     });
     setRootElement(root: HTMLElement | ShadowRoot | Document): void;
     start(): void;
     stop(): void;
     private observeButtonState;
-    private observeDomChanges;
-    private observeScroll;
     scheduleCapture(reason: 'preview' | 'final' | 'change'): void;
+    requestCapture(): Promise<ScreenshotFrame | null>;
     private performCapture;
-    private maybeRunPending;
 }

package/dist/visualContext/domChangeTracker.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DOM change tracker that detects significant host-page changes.
+ * Excludes only the GuideAI widget container (transcript, mic, etc.) - not by class name.
+ * Detects SPA navigation (route changes, visibility changes) and structural DOM changes.
+ */
+export interface DomChangeTrackerOptions {
+    /** Returns the GuideAI widget root element - mutations inside it are excluded */
+    getGuideaiRoot: () => HTMLElement | null;
+}
+export interface DomChangeTracker {
+    hasSignificantChange: () => boolean;
+    markCaptured: () => void;
+    start: () => void;
+    stop: () => void;
+}
+export declare function createDomChangeTracker(options: DomChangeTrackerOptions): DomChangeTracker;

package/dist/visualContext/index.d.ts

@@ -1,5 +1,12 @@
+/**
+ * Visual Context module for GuideAI
+ * Provides screenshot capture, storage, image sending, debug overlay,
+ * and the useVisualContext hook for integration.
+ */
 export { VisualContextStore } from './VisualContextStore';
 export { VisualContextScheduler } from './VisualContextScheduler';
 export { DebugOverlay } from './debug-overlay';
+export { useVisualContext } from './useVisualContext';
 export { createDefaultScreenshotProvider, getDefaultScreenshotProvider } from './defaultProvider';
-export type { ScreenshotResponse, ScreenshotFrame, ScreenshotOptions, ScreenshotProvider, VisualContextConfig } from './types';
+export type { ScreenshotResponse, ScreenshotFrame, ScreenshotDetail, ScreenshotOptions, ScreenshotProvider, VisualContextConfig } from './types';
+export { MAX_IMAGE_MESSAGE_BYTES } from './types';

package/dist/visualContext/types.d.ts

@@ -24,6 +24,10 @@ export type ScreenshotFrame = {
     sentToLLM?: boolean;
     llmReceivedAt?: number;
 };
+/** Alias for ScreenshotFrame, used for event payload compatibility */
+export type ScreenshotDetail = ScreenshotFrame;
+/** Max size for WebRTC image message payload (bytes) */
+export declare const MAX_IMAGE_MESSAGE_BYTES = 200000;
 export type ScreenshotOptions = {
     targetElement?: HTMLElement;
     targetWidth?: number;

package/dist/visualContext/useVisualContext.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useVisualContext - React hook that encapsulates screenshot capture, storage,
+ * image sending, and debug overlay for the GuideAI visual context feature.
+ */
+import { ScreenshotFrame, VisualContextConfig } from './types';
+export type RecordingStatus = 'idle' | 'recording' | 'active' | 'processing' | 'playing';
+export interface UseVisualContextParams {
+    options: VisualContextConfig;
+    sendMessage: (msg: any) => void;
+    isDataChannelOpen: () => boolean;
+    status: RecordingStatus;
+    isConversationActive: boolean;
+    getContainer: () => HTMLElement | null;
+    onLogVisualContext: (content: string, data?: any) => void;
+    onVisualContextError?: (message: string, data?: any) => void;
+    isBufferFull?: () => boolean;
+}
+export interface UseVisualContextReturn {
+    frames: ScreenshotFrame[];
+    debugEnabled: boolean;
+    setDebugEnabled: (value: boolean | ((prev: boolean) => boolean)) => void;
+    showGallery: boolean;
+    setShowGallery: (value: boolean | ((prev: boolean) => boolean)) => void;
+    latencyMs: number | null;
+    windowAPI: Record<string, any>;
+    captureForMessage: () => Promise<{
+        type: 'input_image';
+        image_url: string;
+    } | null>;
+    cleanupOnConversationEnd: () => void;
+}
+export declare function useVisualContext(React: typeof import('react'), params: UseVisualContextParams): UseVisualContextReturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guideai-app",
-  "version": "0.4.3-9",
+  "version": "0.5.0",
   "description": "AI-powered guide component for React applications",
   "main": "dist/GuideAI.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,9 @@
   "scripts": {
     "build": "webpack --mode=production && tsc --emitDeclarationOnly && javascript-obfuscator dist/GuideAI.js --config obfuscator.json --output dist/GuideAI.js",
     "build:dev": "webpack --mode=development && tsc --emitDeclarationOnly",
+    "watch": "webpack --mode=development --watch & tsc --emitDeclarationOnly --watch",
+    "dev": "npm run watch",
+    "serve:local": "npm run build:dev && npx serve -l 8080 dist",
     "prepare": "npm run build",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -33,7 +36,6 @@
   "license": "ISC",
   "dependencies": {
     "@google/generative-ai": "^0.2.1",
-    "guideai-app": "^0.3.4",
     "html2canvas": "^1.4.1",
     "openai": "^4.28.0"
   },

package/dist/metric/event-listner.d.ts

@@ -1,143 +0,0 @@
-interface EventData {
-    type: 'click' | 'focus' | 'change' | 'submit' | 'route_change';
-    element?: Element;
-    tagName?: string;
-    className?: string;
-    id?: string;
-    textContent?: string;
-    value?: string;
-    formData?: FormData;
-    timestamp: number;
-    url: string;
-    previousUrl?: string;
-    event?: Event;
-    customerId?: string;
-    customerType?: string;
-    customerSegment?: string;
-    sessionId?: string;
-    conversationStartTime?: number;
-    timeSinceConversationStart?: number;
-    deviceType?: 'desktop' | 'mobile' | 'tablet';
-    userAgent?: string;
-    screenResolution?: string;
-    currentPage?: string;
-    userRole?: string;
-    organizationId?: string;
-    timezone?: string;
-    locale?: string;
-}
-declare class EventTracker {
-    private isTracking;
-    private eventData;
-    private batchSize;
-    private batchTimeout;
-    private batchTimer;
-    private pendingEvents;
-    private currentUrl;
-    private organizationKey?;
-    private lastEventTime;
-    private eventThrottleInterval;
-    private lastEventsByType;
-    private duplicateEventBuffer;
-    private maxDuplicateBuffer;
-    private isInitialized;
-    private sessionId;
-    private conversationStartTime;
-    private inactivityTimer;
-    private inactivityTimeout;
-    private lastActivityTime;
-    private customerMetadata;
-    constructor(options?: {
-        customerId?: string;
-        customerType?: string;
-        organizationId?: string;
-        organizationKey?: string;
-        batchSize?: number;
-        batchTimeout?: number;
-        eventThrottleInterval?: number;
-    });
-    private init;
-    private loadEventsFromStorage;
-    private saveEventsToStorage;
-    setCustomerMetadata(metadata: Partial<typeof this.customerMetadata>): void;
-    getCustomerMetadata(): typeof this.customerMetadata;
-    clearCustomerMetadata(): void;
-    initialize(): void;
-    private enrichEventData;
-    private sanitizeEventData;
-    setConversationStartTime(startTime: number): void;
-    private getConversationTiming;
-    private getDeviceType;
-    startTracking(): void;
-    stopTracking(): void;
-    private trackClickEvents;
-    private trackFocusEvents;
-    private trackChangeEvents;
-    private trackSubmitEvents;
-    private trackRouteChanges;
-    private handleClick;
-    private handleFocus;
-    private handleChange;
-    private handleSubmit;
-    private handlePopstate;
-    private handleHashChange;
-    private interceptHistoryAPI;
-    private getPreviousUrl;
-    private getSafeValue;
-    private isFocusable;
-    private isFormElement;
-    private generateEventKey;
-    private shouldThrottleEvent;
-    private isDuplicateEvent;
-    private isSignificantClickTarget;
-    private isSignificantFocusTarget;
-    private isSignificantRouteChange;
-    private logEvent;
-    private emitBatch;
-    private sendEventBatch;
-    getEventData(): EventData[];
-    clearEventData(): void;
-    getEventDataByType(type: EventData['type']): EventData[];
-    getEventDataByElement(tagName: string): EventData[];
-    getEventDataByUrl(url: string): EventData[];
-    emitPendingEvents(): void;
-    setBatchConfig(batchSize: number, batchTimeout: number): void;
-    getPendingEventsCount(): number;
-    getCustomerAnalytics(): {
-        totalEvents: number;
-        eventsByCustomer: Record<string, number>;
-        eventsByType: Record<string, number>;
-        eventsByPage: Record<string, number>;
-        eventsByDevice: Record<string, number>;
-        sessionDuration: number;
-        lastActivity: number;
-    };
-    private getSessionStartTime;
-    identifyCustomerFromContext(): void;
-    setCustomerFromAuth(authData: {
-        id?: string;
-        role?: string;
-        customerType?: 'individual' | 'business' | 'agent' | 'admin';
-        customerSegment?: string;
-    }): void;
-    private setupPageUnloadTracking;
-    private setupInactivityTracking;
-    private cleanupPageTracking;
-}
-export default EventTracker;
-export type { EventData };
-export interface CustomerMetadata {
-    customerId?: string;
-    customerType?: 'individual' | 'business' | 'agent' | 'admin';
-    customerSegment?: string;
-    userRole?: string;
-}
-export interface CustomerAnalytics {
-    totalEvents: number;
-    eventsByCustomer: Record<string, number>;
-    eventsByType: Record<string, number>;
-    eventsByPage: Record<string, number>;
-    eventsByDevice: Record<string, number>;
-    sessionDuration: number;
-    lastActivity: number;
-}

package/dist/metric/index.d.ts

@@ -1,2 +0,0 @@
-export { default as UserMetadataTracker } from './metadata-tracker';
-export type { UserMetadata, MetadataConfig, MetadataUpdate } from './metadata-tracker';

package/dist/metric/metadata-tracker.d.ts

@@ -1,50 +0,0 @@
-import { UserMetadata, MetadataConfig, MetadataUpdate } from '../types/metadata.types';
-declare class UserMetadataTracker {
-    private config;
-    private metadata;
-    private syncTimer;
-    private pendingUpdates;
-    private isInitialized;
-    private onError?;
-    private lastSyncTime;
-    private minSyncInterval;
-    private lastMetadataHash;
-    private pendingUpdateTypes;
-    private inactivityTimer;
-    private inactivityTimeout;
-    private lastActivityTime;
-    constructor(organizationKey: string, config?: MetadataConfig, onError?: (error: Error, context: string) => void);
-    init(): void;
-    updateUserInfo(userInfo: Partial<UserMetadata>): void;
-    trackLogin(additionalInfo?: Partial<UserMetadata>): void;
-    private trackVisitIfNewSession;
-    trackVisit(): void;
-    resetSessionVisitTracking(): void;
-    trackVisitManually(): void;
-    trackCustomEvent(eventType: string, customData: Record<string, any>): void;
-    getMetadata(): UserMetadata;
-    getPendingUpdates(): MetadataUpdate[];
-    clearPendingUpdates(): void;
-    syncNow(): MetadataUpdate[];
-    private loadMetadata;
-    private saveMetadata;
-    private collectBrowserInfo;
-    private parseBrowserInfo;
-    private startSyncTimer;
-    private shouldSync;
-    private addPendingUpdate;
-    private isDataDuplicate;
-    private generateDataHash;
-    private stopSyncTimer;
-    private emitPendingUpdates;
-    private emitPendingUpdatesImmediate;
-    private getFromStorage;
-    private setToStorage;
-    private clearStorage;
-    private setupPageUnloadTracking;
-    private setupInactivityTracking;
-    private cleanupPageTracking;
-    destroy(): void;
-}
-export default UserMetadataTracker;
-export type { UserMetadata, MetadataConfig, MetadataUpdate };

package/dist/types/metadata.types.d.ts

@@ -1,48 +0,0 @@
-export interface UserMetadata {
-    userId?: string;
-    email?: string;
-    userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
-    customerType?: 'individual' | 'business' | 'enterprise' | string;
-    customerLicense?: string;
-    firstVisit?: number;
-    lastVisit?: number;
-    visitCount?: number;
-    loginCount?: number;
-    lastLogin?: number;
-    organizationKey: string;
-    sessionId?: string;
-    userAgent?: string;
-    browserInfo?: {
-        name?: string;
-        version?: string;
-        platform?: string;
-    };
-    customFields?: Record<string, string | number | boolean>;
-}
-export interface MetadataUpdate {
-    type: 'visit' | 'login' | 'user_info' | 'session' | 'custom';
-    timestamp: number;
-    data: Partial<UserMetadata>;
-}
-export interface MetadataConfig {
-    trackVisits?: boolean;
-    trackLogins?: boolean;
-    syncInterval?: number;
-    storage?: 'localStorage' | 'sessionStorage' | 'memory';
-    customFields?: string[];
-    collectBrowserInfo?: boolean;
-    collectUserAgent?: boolean;
-    sessionTimeout?: number;
-}
-export interface MetadataStorageData {
-    metadata: UserMetadata;
-    lastUpdated: number;
-    version: string;
-}
-export type MetadataEventType = 'user_visit' | 'user_login' | 'user_info_update' | 'session_start' | 'session_end' | 'custom_event';
-export interface MetadataEvent {
-    type: MetadataEventType;
-    timestamp: number;
-    metadata: Partial<UserMetadata>;
-    source?: string;
-}

package/dist/utils/gemini.d.ts

@@ -1,5 +0,0 @@
-import { ElementInteractionType } from './constants';
-export declare const parse_args: (interactionType: ElementInteractionType, argsToUse: any, geminiFlash: Function, organizationKey: string) => Promise<any>;
-export declare const geminiFlash: (prompt: string, organizationKey: string) => Promise<string>;
-export declare const HIGHLIGHT_TOOL_PROMPT = "Validate the following JSON string and return ONLY a correct JSON object:\nNote: The selector(s) should be either a css selector or an xpath, so modify those if invalid.\nAlso, [url=''] is a valid css selector, so do not modify it if it's present.\nDo not add any other text or newlines to the response.\nIt should be of the following format:\n{ \"selector\": \"string\" }\nor\n{ \"selector\": [\"string\", ...] }\nDO NOT add any other text or newlines to the response, it should begin and end with curly braces.\nDO NOT add '''json to the response.\nThe JSON string is:\n";
-export declare const HOVER_TOOL_PROMPT = "Validate the following JSON string and return ONLY a correct JSON object:\nNote: The selector(s) should be either a css selector or an xpath, so modify those if invalid.\nAlso, [url=''] is a valid css selector, so do not modify it if it's present.\nDo not add any other text or newlines to the response.\nIt should be of the following format:\n{ \"selector\": \"string\" }\nor\n{ \"selector\": [\"string\", ...] }\nor\n{ \"selector\": \"string\", \"hoverTime\": number }\nor\n{ \"selector\": [\"string\", ...], \"hoverTime\": number }\nThe hoverTime parameter is optional and represents time to hover in milliseconds (500-10000).\nIf not provided, default to 3000ms.\nDO NOT add any other text or newlines to the response, it should begin and end with curly braces.\nDO NOT add '''json to the response.\nThe JSON string is:\n";

package/dist/utils/highlightAndClick.d.ts

@@ -1,3 +0,0 @@
-export declare const createHoverEffect: (element: Element, rect: DOMRect) => Promise<void>;
-export declare const createHoverEffectWithTracking: (element: Element, initialRect: DOMRect, cursorElement: HTMLElement | null, duration?: number) => Promise<void>;
-export declare const highlightThenClick: (selector: string | string[], isHovering: boolean, setIsHovering: (hovering: boolean) => void, logMessage: (content: string, sender: "GUIDEAI" | "HUMAN") => void, hoverTime?: number) => Promise<boolean>;

package/dist/utils/hoverAndClick.d.ts

@@ -1,4 +0,0 @@
-export declare const createHoverEffect: (element: Element, rect: DOMRect) => Promise<void>;
-export declare const createHoverEffectWithTracking: (element: Element, initialRect: DOMRect, cursorElement: HTMLElement | null) => Promise<void>;
-export declare const clickElement: (element: Element, rect: DOMRect) => Promise<void>;
-export declare const hoverThenClick: (selector: string | string[], isHighlighting: boolean, setIsHighlighting: (highlighting: boolean) => void, logMessage: (content: string, sender: "GUIDEAI" | "HUMAN") => void) => Promise<boolean>;