guideai-app 0.4.1 → 0.4.2

package/dist/index.d.ts

@@ -3,3 +3,6 @@ import TranscriptBox from './components/TranscriptBox';
 export default GuideAI;
 export { TranscriptBox };
 export type { GuideAIProps } from './types/GuideAI.types';
+export * from './visualContext';
+export * from './visualContext/types';
+export { getSessionId, clearSessionId, peekSessionId } from './utils/session';

package/dist/metric/index.d.ts

@@ -1,4 +1,2 @@
-export { default as EventTracker } from './event-listner';
-export type { EventData } from './event-listner';
 export { default as UserMetadataTracker } from './metadata-tracker';
 export type { UserMetadata, MetadataConfig, MetadataUpdate } from './metadata-tracker';

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

@@ -17,7 +17,7 @@ declare class UserMetadataTracker {
     init(): void;
     updateUserInfo(userInfo: Partial<UserMetadata>): void;
     trackLogin(additionalInfo?: Partial<UserMetadata>): void;
-    private trackVisitOncePerSession;
+    private trackVisitIfNewSession;
     trackVisit(): void;
     resetSessionVisitTracking(): void;
     trackVisitManually(): void;
@@ -35,7 +35,6 @@ declare class UserMetadataTracker {
     private addPendingUpdate;
     private isDataDuplicate;
     private generateDataHash;
-    private setupEventTrackerIntegration;
     private stopSyncTimer;
     private emitPendingUpdates;
     private emitPendingUpdatesImmediate;

package/dist/types/GuideAI.types.d.ts

@@ -1,4 +1,5 @@
 import { MetadataConfig, UserMetadata } from './metadata.types';
+import { VisualContextConfig } from '../visualContext/types';
 export type RecordingStatus = 'idle' | 'recording' | 'processing' | 'playing';
 export type UseStateHook = <T>(initialState: T | (() => T)) => [T, (value: T | ((prev: T) => T)) => void];
 export type UseEffectHook = (effect: () => void | (() => void), deps?: any[]) => void;
@@ -39,5 +40,6 @@ export interface GuideAIProps {
         defaultMode?: 'voice' | 'text';
         placeholder?: string;
     };
+    visualContext?: VisualContextConfig;
 }
 export type PopupPosition = 'above' | 'below';

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

@@ -1,5 +1,6 @@
 export interface UserMetadata {
     userId?: string;
+    email?: string;
     userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
     customerType?: 'individual' | 'business' | 'enterprise' | string;
     customerLicense?: string;
@@ -31,6 +32,7 @@ export interface MetadataConfig {
     customFields?: string[];
     collectBrowserInfo?: boolean;
     collectUserAgent?: boolean;
+    sessionTimeout?: number;
 }
 export interface MetadataStorageData {
     metadata: UserMetadata;

package/dist/utils/api.d.ts

@@ -14,6 +14,11 @@ interface ConversationData {
     ephemeralToken: string;
     prompt: string;
     workflows: Workflow[];
+    userMetadata?: {
+        visitCount: number;
+        loginCount?: number;
+        email?: string;
+    };
 }
 export declare const createNewConversation: (organizationKey: string, onError: (error: Error, context: string) => void, workflowKey?: string) => Promise<ConversationData | null>;
 export type { Workflow };

package/dist/utils/elementInteractions.d.ts

@@ -0,0 +1,92 @@
+export declare const HOVER_EFFECT_KEEP_ALIVE_TIME = 3000;
+export declare const createHoverEffect: (element: Element, initialRect: DOMRect, cursorElement?: HTMLElement | null, duration?: number) => Promise<void>;
+export declare const clickElement: (element: Element, rect: DOMRect, withEffects?: boolean) => Promise<void>;
+export declare const parseCustomSelector: (selector: string) => {
+    type: "text" | "css" | "xpath";
+    cssSelector?: string;
+    textContent?: string;
+    originalSelector?: string;
+};
+export declare const findElementBySelectorStrict: (selector: string) => Element | null;
+export declare const findElementBySelector: (selector: string) => Element | null;
+type ElementInteractionType = "HIGHLIGHT" | "HOVERANDCLICK";
+export declare const interactWithElement: (element: Element, cursorElement: HTMLElement | null, state: ElementInteractionType, hoverTime?: number) => Promise<HTMLElement | null>;
+export declare const processSelectorsInteraction: (selectors: string | string[], isInteracting: boolean, setIsInteracting: (interacting: boolean) => void, onEachElement: (element: Element, cursor: HTMLElement | null, index: number) => Promise<HTMLElement | null>, onComplete?: (lastElement: Element | null, cursor: HTMLElement | null) => Promise<void>) => Promise<boolean>;
+export declare const Highlight_Tool: {
+    type: string;
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            selector: {
+                oneOf: ({
+                    type: string;
+                    description: string;
+                    items?: undefined;
+                } | {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                })[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const Hover_Tool: {
+    type: string;
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            selector: {
+                oneOf: ({
+                    type: string;
+                    description: string;
+                    items?: undefined;
+                } | {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                })[];
+                description: string;
+            };
+            hoverTime: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const Go_To_A_Elm_Link_Tool: {
+    type: string;
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            linkText: {
+                type: string;
+                description: string;
+            };
+            delay: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
+export {};

package/dist/utils/gemini.d.ts

@@ -0,0 +1,3 @@
+export declare const parse_args: (prompt: string, argsToUse: any, geminiFlash: Function) => Promise<any>;
+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/goToAElmLink.d.ts

@@ -0,0 +1 @@
+export declare const goToAElmLink: (linkText: string, delay?: number) => Promise<boolean>;

package/dist/utils/highlightThenClick.d.ts

@@ -0,0 +1 @@
+export declare const highlightThenClick: (selector: string | string[], isHighlighting: boolean, setIsHighlighting: (highlighting: boolean) => void) => Promise<boolean>;

package/dist/utils/hoverThenClick.d.ts

@@ -0,0 +1 @@
+export declare const hoverThenClick: (selector: string | string[], isHovering: boolean, setIsHovering: (hovering: boolean) => void, hoverTime?: number) => Promise<boolean>;

package/dist/utils/logger.d.ts

@@ -2,7 +2,7 @@
  * Standardized logging utility for GuideAI package
  * Provides consistent formatting and development gating across all components
  */
-type Component = 'GuideAI' | 'EventTracker' | 'UserMetadata' | 'API' | 'TranscriptBox' | 'Onboarding';
+type Component = 'GuideAI' | 'UserMetadata' | 'API' | 'TranscriptBox' | 'Onboarding';
 declare class Logger {
     private static formatMessage;
     /**
@@ -29,10 +29,6 @@ declare class Logger {
      * Conversation flow tracking
      */
     static conversation(action: string, data?: any): void;
-    /**
-     * Event tracking logging
-     */
-    static event(action: string, data?: any): void;
     /**
      * Metadata tracking logging
      */

package/dist/utils/session.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gets the current session ID from sessionStorage, or generates a new one if it doesn't exist.
+ * The session ID persists across page navigations within the same browser tab,
+ * but is cleared when the tab is closed.
+ *
+ * @returns {string} The current session ID (UUID v4 format)
+ */
+export declare function getSessionId(): string;
+/**
+ * Clears the current session ID from sessionStorage.
+ * This will force a new session ID to be generated on the next call to getSessionId().
+ *
+ * Note: This is primarily for testing purposes. In normal operation,
+ * the browser automatically clears sessionStorage when the tab is closed.
+ */
+export declare function clearSessionId(): void;
+/**
+ * Gets the current session ID without generating a new one.
+ * Returns null if no session ID exists.
+ *
+ * @returns {string | null} The current session ID or null if none exists
+ */
+export declare function peekSessionId(): string | null;

package/dist/visualContext/VisualContextScheduler.d.ts

@@ -0,0 +1,43 @@
+import { ScreenshotFrame, ScreenshotProvider } from './types';
+export declare class VisualContextScheduler {
+    private getContainer;
+    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 targetWidth;
+    private rootElement;
+    private quality;
+    private minQuality;
+    private maxBytes;
+    private onFrame;
+    constructor(getContainer: () => HTMLElement | null, screenshotProvider: ScreenshotProvider, onFrame: (frame: ScreenshotFrame) => void, options?: {
+        targetWidth?: number;
+        quality?: number;
+        minQuality?: number;
+        maxBytes?: number;
+    });
+    setRootElement(root: HTMLElement | ShadowRoot | Document): void;
+    start(): void;
+    stop(): void;
+    private observeButtonState;
+    private observeDomChanges;
+    private observeScroll;
+    scheduleCapture(reason: 'preview' | 'final' | 'change'): void;
+    private performCapture;
+    private maybeRunPending;
+}

package/dist/visualContext/VisualContextStore.d.ts

@@ -0,0 +1,11 @@
+import { ScreenshotFrame } from './types';
+export declare class VisualContextStore {
+    private maxItems;
+    private frames;
+    constructor(maxItems?: number);
+    add(frame: ScreenshotFrame): void;
+    latest(): ScreenshotFrame | null;
+    all(): ScreenshotFrame[];
+    clear(): void;
+    setMaxItems(maxItems: number): void;
+}

package/dist/visualContext/debug-overlay.d.ts

@@ -0,0 +1,10 @@
+import { ScreenshotFrame } from './types';
+interface DebugOverlayProps {
+    React: typeof import('react');
+    frames: ScreenshotFrame[];
+    latencyMs: number | null;
+    onToggleGallery?: () => void;
+    showGallery?: boolean;
+}
+export declare const DebugOverlay: ({ React, frames, latencyMs, onToggleGallery, showGallery }: DebugOverlayProps) => import("react").DetailedReactHTMLElement<import("react").HTMLAttributes<HTMLElement>, HTMLElement>;
+export {};

package/dist/visualContext/defaultProvider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default screenshot provider using html2canvas
+ * Automatically detects and uses html2canvas if available
+ */
+import type { ScreenshotProvider } from './types';
+/**
+ * Creates a default screenshot provider using html2canvas
+ * Returns null if html2canvas is not available
+ */
+export declare const createDefaultScreenshotProvider: () => ScreenshotProvider | null;
+/**
+ * Get the default screenshot provider
+ * Returns null if unavailable (graceful degradation)
+ */
+export declare const getDefaultScreenshotProvider: () => ScreenshotProvider | null;

package/dist/visualContext/index.d.ts

@@ -0,0 +1,5 @@
+export { VisualContextStore } from './VisualContextStore';
+export { VisualContextScheduler } from './VisualContextScheduler';
+export { DebugOverlay } from './debug-overlay';
+export { createDefaultScreenshotProvider, getDefaultScreenshotProvider } from './defaultProvider';
+export type { ScreenshotResponse, ScreenshotFrame, ScreenshotOptions, ScreenshotProvider, VisualContextConfig } from './types';

package/dist/visualContext/types.d.ts

@@ -0,0 +1,45 @@
+export type ScreenshotResponse = {
+    ok?: boolean;
+    dataUrl?: string;
+    width?: number;
+    height?: number;
+    hash?: string;
+    isDuplicate?: boolean;
+    timestamp?: number;
+    error?: any;
+    metadata?: {
+        width?: number;
+        height?: number;
+        quality?: number;
+        [key: string]: any;
+    };
+};
+export type ScreenshotFrame = {
+    dataUrl: string;
+    width?: number;
+    height?: number;
+    hash?: string;
+    reason: 'preview' | 'final' | 'change';
+    timestamp?: number;
+    sentToLLM?: boolean;
+    llmReceivedAt?: number;
+};
+export type ScreenshotOptions = {
+    targetElement?: HTMLElement;
+    targetWidth?: number;
+    quality?: number;
+    minQuality?: number;
+    maxBytes?: number;
+};
+export type ScreenshotProvider = (options: ScreenshotOptions) => Promise<ScreenshotResponse>;
+export type VisualContextConfig = {
+    enabled: boolean;
+    screenshotProvider?: ScreenshotProvider;
+    shadowRoot?: ShadowRoot;
+    debug?: boolean;
+    maxFrames?: number;
+    targetWidth?: number;
+    quality?: number;
+    minQuality?: number;
+    maxBytes?: number;
+};

package/index.d.ts

@@ -1,3 +1,7 @@
 import GuideAI from './GuideAI';
+import TranscriptBox from './components/TranscriptBox';
 export default GuideAI;
-export type { GuideAIProps } from './GuideAI';
+export { TranscriptBox };
+export type { GuideAIProps } from './types/GuideAI.types';
+export * from './visualContext';
+export * from './visualContext/types';

package/jest.config.js

@@ -0,0 +1,26 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.ts?(x)', '**/?(*.)+(spec|test).ts?(x)'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/*.types.ts'
+  ],
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: {
+        jsx: 'react',
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true
+      }
+    }]
+  },
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1'
+  }
+};
+

package/jest.setup.js

@@ -0,0 +1,21 @@
+// Jest setup file
+require('jest-localstorage-mock');
+require('@testing-library/jest-dom');
+
+// Mock console methods to reduce noise in tests
+global.console = {
+  ...console,
+  log: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+};
+
+// Setup localStorage and sessionStorage mocks
+Object.defineProperty(window, 'localStorage', {
+  value: global.localStorage,
+});
+
+Object.defineProperty(window, 'sessionStorage', {
+  value: global.sessionStorage,
+});
+

package/metadata-tracking-example.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The GuideAI package now includes comprehensive user metadata tracking capabilities designed for integration with Overproof. This system tracks the following metadata:
+The GuideAI package now includes comprehensive user metadata tracking capabilities designed for integration with client. This system tracks the following metadata:
 
 - **User's First Visit** - Timestamp of the first time the user interacted with GuideAI
 - **User's Last Visit** - Timestamp of the most recent user interaction
@@ -181,7 +181,7 @@ interface UserMetadata {
     platform?: string;
   };
   
-  // Custom fields for Overproof-specific needs
+  // Custom fields for client-specific needs
   customFields?: Record<string, string | number | boolean>;
 }
 ```
@@ -255,14 +255,14 @@ guideAIRef.current?.trackCustomEvent('document_viewed', {
 });
 ```
 
-## Overproof Integration Example
+## client Integration Example
 
 ```typescript
-function OverproofApp() {
+function clientApp() {
   const guideAIRef = useRef();
 
-  // Track when user logs into Overproof
-  const handleOverproofLogin = (user) => {
+  // Track when user logs into client
+  const handleclientLogin = (user) => {
     guideAIRef.current?.trackLogin({
       userId: user.id,
       userType: user.role, // 'agent', 'admin', etc.
@@ -291,18 +291,18 @@ function OverproofApp() {
   return (
     <GuideAI 
       ref={guideAIRef}
-      organizationKey="overproof-org-key"
+      organizationKey="demo-org-key"
       metadata={{
         config: {
           trackVisits: true,
           trackLogins: true,
-          syncInterval: 15000, // More frequent syncing for Overproof
+          syncInterval: 15000, // More frequent syncing for client
           customFields: ['agencyId', 'territory', 'permissions'],
           collectBrowserInfo: true
         },
         onMetadataUpdate: (metadata) => {
-          // Send to Overproof analytics
-          window.OverproofAnalytics?.track('guideai_metadata_update', metadata);
+          // Send to client analytics
+          window.clientAnalytics?.track('guideai_metadata_update', metadata);
         }
       }}
     />
@@ -321,4 +321,4 @@ Metadata is automatically:
 - Synced to backend at configured intervals
 - Restored when user returns (if using persistent storage)
 
-This implementation provides a robust foundation for tracking user metadata in the Overproof environment while maintaining flexibility for other use cases.
+This implementation provides a robust foundation for tracking user metadata in the client environment while maintaining flexibility for other use cases.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "guideai-app",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "AI-powered guide component for React applications",
   "main": "dist/GuideAI.js",
-  "types": "dist/GuideAI.d.ts",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "webpack && tsc --emitDeclarationOnly && javascript-obfuscator dist/GuideAI.js --config obfuscator.json --output dist/GuideAI.js",
     "prepare": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "react",
@@ -20,6 +22,7 @@
   "dependencies": {
     "@google/generative-ai": "^0.2.1",
     "guideai-app": "^0.3.4",
+    "html2canvas": "^1.4.1",
     "openai": "^4.28.0"
   },
   "peerDependencies": {
@@ -27,10 +30,17 @@
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^30.0.0",
     "@types/react": "^18.2.0",
     "javascript-obfuscator": "^4.1.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jest-localstorage-mock": "^2.4.26",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",
+    "ts-jest": "^29.4.5",
     "ts-loader": "^9.5.2",
     "typescript": "^5.0.0",
     "util": "^0.12.5",