handhold-sdk 1.0.0

package/types/index.d.ts

@@ -0,0 +1,538 @@
+/**
+ * Hand Hold SDK - TypeScript Definitions
+ * @version 1.0.0
+ */
+
+declare module 'handhold-sdk' {
+  // ==================== Configuration ====================
+
+  export interface HandHoldConfig {
+    /** API key for authentication (required) */
+    apiKey: string;
+    /** Backend API base URL (required) */
+    baseUrl: string;
+    /** UI theme */
+    theme?: 'light' | 'dark';
+    /** Widget position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Primary accent color (hex) */
+    primaryColor?: string;
+    /** Z-index for overlays */
+    zIndex?: number;
+    /** Minimum confidence to highlight elements (0-1) */
+    minHighlightConfidence?: number;
+    /** Session timeout in milliseconds */
+    sessionInactivityTimeout?: number;
+    /** Enable cross-page session tracking */
+    enableMultiPageTracking?: boolean;
+    /** Show floating help button */
+    showHelpButton?: boolean;
+    /** Maximum intents to display */
+    maxIntents?: number;
+    /** API request timeout in milliseconds */
+    apiTimeout?: number;
+    /** Number of retry attempts for API calls */
+    retryAttempts?: number;
+    /** Base retry delay in milliseconds */
+    retryDelay?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Log level */
+    logLevel?: 'error' | 'warn' | 'info' | 'debug';
+    /** Widget title */
+    widgetTitle?: string;
+    /** Search placeholder text */
+    widgetPlaceholder?: string;
+    /** Help button text */
+    helpButtonText?: string;
+    /** Enable client-side caching */
+    enableCache?: boolean;
+    /** Cache TTL in milliseconds */
+    cacheTTL?: number;
+  }
+
+  // ==================== Intent ====================
+
+  export interface Intent {
+    /** Intent key (e.g., 'approve_payroll') */
+    key: string;
+    /** Human-readable label */
+    label: string;
+    /** Canonical verb */
+    verb?: string;
+    /** Object/target of the action */
+    object?: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Original text from UI element */
+    original_text?: string;
+    /** CSS selector of source element */
+    source_element?: string;
+    /** Element position on page */
+    element_position?: ElementPosition;
+    /** Element type (button, link, etc.) */
+    element_type?: string;
+  }
+
+  export interface ElementPosition {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+  }
+
+  // ==================== Guidance ====================
+
+  export interface GuidanceStep {
+    /** Step order (1-based) */
+    order: number;
+    /** Step instruction text */
+    text: string;
+    /** CSS selector for target element */
+    selector?: string;
+    /** Match confidence (0-1) */
+    confidence: number;
+    /** How the element was matched */
+    match_type?: 'exact' | 'fuzzy' | 'semantic';
+    /** Route where this step applies */
+    page_route?: string;
+    /** Additional UI hint */
+    ui_hint?: string;
+  }
+
+  export interface Guidance {
+    /** Intent key */
+    intent: string;
+    /** Brief summary */
+    summary: string;
+    /** Array of steps */
+    steps: GuidanceStep[];
+    /** Current step index (0-based) */
+    current_step: number;
+    /** Total number of steps */
+    total_steps: number;
+    /** Related KB articles */
+    related_articles?: RelatedArticle[];
+    /** Whether result was cached */
+    cached?: boolean;
+    /** Session ID */
+    session_id?: string;
+  }
+
+  export interface RelatedArticle {
+    title: string;
+    url: string;
+  }
+
+  // ==================== Session ====================
+
+  export interface Session {
+    /** Unique session ID */
+    session_id: string;
+    /** Intent key */
+    intent: string;
+    /** Intent label */
+    intent_label?: string;
+    /** Summary of the guidance */
+    summary?: string;
+    /** Array of steps */
+    steps: GuidanceStep[];
+    /** Current step index (0-based) */
+    current_step: number;
+    /** Number of steps completed */
+    steps_completed: number;
+    /** Total number of steps */
+    total_steps: number;
+    /** Route where session started */
+    original_route: string;
+    /** Current route */
+    current_route: string;
+    /** Timestamp when session started */
+    started_at: number;
+    /** Timestamp of last activity */
+    last_activity: number;
+    /** Session status */
+    status: 'active' | 'completed' | 'abandoned' | 'expired';
+    /** Navigation history */
+    navigation_history: string[];
+  }
+
+  // ==================== UI Elements ====================
+
+  export interface UIElement {
+    /** Element text content */
+    text: string;
+    /** ARIA label */
+    aria_label?: string;
+    /** Title attribute */
+    title?: string;
+    /** ARIA role or inferred role */
+    role: string;
+    /** CSS selector */
+    selector: string;
+    /** HTML tag name */
+    tag: string;
+    /** Input type (for inputs) */
+    type?: string;
+    /** Whether element is disabled */
+    disabled?: boolean;
+    /** Element position */
+    position: ElementPosition;
+    /** data-testid attribute */
+    data_testid?: string;
+  }
+
+  export interface PageContext {
+    /** Current route/URL */
+    route: string;
+    /** Page title */
+    title: string;
+    /** Page headings */
+    headings: string[];
+    /** Forms on page */
+    forms: FormInfo[];
+    /** All interactive UI elements */
+    ui_elements: UIElement[];
+    /** Primary action buttons */
+    primaryActions: string[];
+  }
+
+  export interface FormInfo {
+    id?: string;
+    name?: string;
+    inputs: string[];
+  }
+
+  // ==================== Events ====================
+
+  export type EventCallback<T = any> = (data: T) => void;
+
+  export interface NavigationEventData {
+    route: string;
+    previousRoute: string;
+    pathname: string;
+    search: string;
+    hash: string;
+  }
+
+  export interface CompletedEventData {
+    intent: string;
+  }
+
+  export interface ClosedEventData {
+    intent?: string;
+  }
+
+  // ==================== API Responses ====================
+
+  export interface IntentExtractionResult {
+    intent: string | null;
+    confidence: number;
+    reasoning?: string;
+    clarifying_question?: string;
+    suggested_intents?: string[];
+  }
+
+  export interface ElementMatchResult {
+    selector: string | null;
+    confidence: number;
+    match_type: 'exact' | 'fuzzy' | 'semantic' | null;
+    found: boolean;
+    fallback_message?: string;
+  }
+
+  export interface KBSearchResult {
+    query: string;
+    results: KBArticle[];
+    total: number;
+  }
+
+  export interface KBArticle {
+    id: string;
+    title: string;
+    excerpt?: string;
+    content?: string;
+    score: number;
+    intent_tags?: string[];
+    route_pattern?: string;
+  }
+
+  // ==================== Main SDK Class ====================
+
+  export interface HandHoldInstance {
+    /**
+     * Initialize the SDK
+     */
+    init(options: HandHoldConfig): Promise<void>;
+
+    /**
+     * Open the help widget
+     */
+    open(): void;
+
+    /**
+     * Close the help widget
+     */
+    close(): void;
+
+    /**
+     * Toggle the help widget
+     */
+    toggle(): void;
+
+    /**
+     * Start guidance for a specific intent
+     */
+    startGuidance(intentKey: string): Promise<void>;
+
+    /**
+     * Get available intents for current page
+     */
+    getIntents(): Intent[];
+
+    /**
+     * Check if there's an active session
+     */
+    hasActiveSession(): boolean;
+
+    /**
+     * Get the active session
+     */
+    getActiveSession(): Session | null;
+
+    /**
+     * Get session progress (0-100)
+     */
+    getProgress(): number;
+
+    /**
+     * Subscribe to events
+     */
+    on<T = any>(event: string, callback: EventCallback<T>): () => void;
+
+    /**
+     * Unsubscribe from events
+     */
+    off(event: string, callback: EventCallback): void;
+
+    /**
+     * Destroy the SDK instance
+     */
+    destroy(): void;
+
+    /**
+     * Get SDK version
+     */
+    getVersion(): string;
+
+    /**
+     * Check if SDK is initialized
+     */
+    isInitialized(): boolean;
+  }
+
+  // ==================== Component Classes ====================
+
+  export class Config {
+    constructor(options: HandHoldConfig);
+    get<K extends keyof HandHoldConfig>(key: K): HandHoldConfig[K];
+    getAll(): Readonly<HandHoldConfig>;
+    getCSSVariables(): Record<string, string>;
+  }
+
+  export class Logger {
+    constructor(options?: { prefix?: string; level?: string; enabled?: boolean });
+    error(...args: any[]): void;
+    warn(...args: any[]): void;
+    info(...args: any[]): void;
+    debug(...args: any[]): void;
+    group(label: string): void;
+    groupEnd(): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+  }
+
+  export class EventBus {
+    static on<T = any>(event: string, callback: EventCallback<T>): () => void;
+    static once<T = any>(event: string, callback: EventCallback<T>): () => void;
+    static off(event: string, callback: EventCallback): void;
+    static emit<T = any>(event: string, data?: T): void;
+    static clear(): void;
+    static listenerCount(event: string): number;
+  }
+
+  export class APIClient {
+    constructor(config: Config);
+    inferIntents(data: { route: string; page_title?: string; ui_elements: UIElement[] }): Promise<{ intents: Intent[]; cached: boolean }>;
+    extractIntent(data: { user_query: string; route: string; available_intents: string[] }): Promise<IntentExtractionResult>;
+    getGuidance(data: { intent: string; route: string; page_context?: any; ui_elements: UIElement[]; session_id?: string }): Promise<Guidance>;
+    matchElement(data: { step_description: string; original_selector?: string; route: string; ui_elements: UIElement[]; session_id?: string }): Promise<ElementMatchResult>;
+    updateSession(data: { session_id: string; status: string; current_step: number; total_steps: number }): Promise<any>;
+    searchKB(query: string, options?: { limit?: number; intent?: string; route?: string }): Promise<KBSearchResult>;
+    healthCheck(): Promise<{ status: string; timestamp: string }>;
+  }
+
+  export class PageObserver {
+    constructor(config: Config);
+    observe(): void;
+    disconnect(): void;
+    scanPage(): PageContext;
+    getRoute(): string;
+    elementExists(selector: string): boolean;
+    findElement(selector: string): Element | null;
+    waitForElement(selector: string, timeout?: number): Promise<Element>;
+  }
+
+  export class NavigationObserver {
+    constructor(config: Config);
+    observe(): void;
+    disconnect(): void;
+    getRoute(): string;
+    getPathname(): string;
+    forceCheck(): void;
+  }
+
+  export class ElementScanner {
+    constructor(config: Config);
+    scan(): UIElement[];
+    getPageContext(): PageContext;
+    findElement(selector: string): Element | null;
+    elementExists(selector: string): boolean;
+  }
+
+  export class IntentExtractor {
+    static extract(uiElements: UIElement[], route: string, options?: { maxIntents?: number }): Intent[];
+    static matchQueryToIntent(query: string, intents: Intent[]): Intent | null;
+    static getClarification(query: string, candidates: Intent[]): { question: string; options: Intent[] };
+  }
+
+  export class ActionVerbMap {
+    static get(word: string): string | undefined;
+    static getLabel(verb: string): string;
+    static isActionVerb(word: string): boolean;
+    static findInText(text: string): { verb: string; position: number } | null;
+  }
+
+  export class SessionManager {
+    constructor(config: Config);
+    getSessionId(): string;
+    startSession(data: { intent: string; intent_label?: string; steps: GuidanceStep[]; original_route: string; summary?: string }): Session;
+    getActiveSession(): Session | null;
+    hasActiveSession(): boolean;
+    updateSession(session: Session): void;
+    endSession(): void;
+    advanceStep(): boolean;
+    getCurrentStep(): GuidanceStep | null;
+    getStep(index: number): GuidanceStep | null;
+    updateStep(index: number, updates: Partial<GuidanceStep>): void;
+    getProgress(): number;
+    recordNavigation(route: string): void;
+    isInSameFlow(newRoute: string): boolean;
+  }
+
+  export class SessionStorage {
+    constructor(prefix?: string);
+    set<T>(key: string, value: T): boolean;
+    get<T>(key: string): T | null;
+    remove(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    keys(): string[];
+  }
+
+  export class HelpWidget {
+    constructor(config: Config);
+    render(): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    destroy(): void;
+    showIntentMenu(intents: Intent[]): void;
+    showLoading(): void;
+    showGuidanceTooltip(guidance: Guidance): void;
+    updateTooltip(session: Session): void;
+    showError(message: string): void;
+    showClarification(question: string, options: Intent[]): void;
+    showSuccess(message: string): void;
+    showTextOnlyGuidance(text: string, fallback?: string): void;
+    showNavigationSuggestion(article: { title: string; route?: string; excerpt?: string }): void;
+    confirmContinueSession(message: string): Promise<boolean>;
+  }
+
+  export class UICoach {
+    constructor(config: Config);
+    highlightElement(selector: string, options?: HighlightOptions): boolean;
+    clearHighlight(): void;
+    updateTooltipMessage(message: string): void;
+    isActive(): boolean;
+    destroy(): void;
+  }
+
+  export interface HighlightOptions {
+    message?: string;
+    showArrow?: boolean;
+    showTooltip?: boolean;
+    arrowPosition?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    showDoneButton?: boolean;
+    showSkipButton?: boolean;
+  }
+
+  // ==================== Utility Functions ====================
+
+  export namespace domUtils {
+    export function generateSelector(element: Element): string;
+    export function getElementText(element: Element): string;
+    export function getElementRole(element: Element): string;
+    export function getElementPosition(element: Element): ElementPosition;
+    export function isElementVisible(element: Element): boolean;
+    export function isInteractiveElement(element: Element): boolean;
+    export function getInteractiveElements(root?: Element): Element[];
+    export function createElement(html: string): Element;
+    export function waitForElement(selector: string, timeout?: number): Promise<Element>;
+  }
+
+  export namespace stringUtils {
+    export function toSnakeCase(str: string): string;
+    export function toTitleCase(str: string): string;
+    export function toCamelCase(str: string): string;
+    export function truncate(str: string, maxLength: number): string;
+    export function capitalize(str: string): string;
+    export function hashString(str: string): string;
+    export function extractKeywords(text: string): string[];
+    export function similarity(str1: string, str2: string): number;
+    export function containsAllKeywords(str: string, keywords: string[]): boolean;
+    export function pluralize(word: string, count: number): string;
+    export function generateId(prefix?: string): string;
+  }
+
+  // ==================== Default Export ====================
+
+  const HandHold: HandHoldInstance;
+  export default HandHold;
+
+  // Also export the class for custom instantiation
+  export class HandHold implements HandHoldInstance {
+    constructor();
+    init(options: HandHoldConfig): Promise<void>;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    startGuidance(intentKey: string): Promise<void>;
+    getIntents(): Intent[];
+    hasActiveSession(): boolean;
+    getActiveSession(): Session | null;
+    getProgress(): number;
+    on<T = any>(event: string, callback: EventCallback<T>): () => void;
+    off(event: string, callback: EventCallback): void;
+    destroy(): void;
+    getVersion(): string;
+    isInitialized(): boolean;
+  }
+}
+
+// Global declaration for script tag usage
+declare global {
+  interface Window {
+    HandHold: import('handhold-sdk').HandHoldInstance;
+  }
+}