@pillar-ai/sdk 0.1.8 → 0.1.14

package/dist/core/Pillar.d.ts

@@ -2,12 +2,12 @@
  * Main Pillar SDK Class
  * Entry point for all SDK functionality
  */
-import { type PillarConfig, type ResolvedConfig, type ThemeConfig } from './config';
-import { type Context, type Suggestion, type UserProfile } from './context';
-import { type CardRenderer, type PillarEvents, type TaskExecutePayload } from './events';
-import type { ExecutionPlan } from './plan';
-import type { Workflow } from './workflow';
-export type PillarState = 'uninitialized' | 'initializing' | 'ready' | 'error';
+import { APIClient } from "../api/client";
+import { type PillarConfig, type ResolvedConfig, type ThemeConfig } from "./config";
+import { type Context, type Suggestion, type UserProfile } from "./context";
+import { type CardRenderer, type PillarEvents, type TaskExecutePayload } from "./events";
+import type { Workflow } from "./workflow";
+export type PillarState = "uninitialized" | "initializing" | "ready" | "error";
 /**
  * Chat context for escalation to human support.
  */
@@ -16,7 +16,7 @@ export interface ChatContext {
     conversationId: string | null;
     /** Messages in the conversation */
     messages: Array<{
-        role: 'user' | 'assistant';
+        role: "user" | "assistant";
         content: string;
     }>;
 }
@@ -26,8 +26,6 @@ export declare class Pillar {
     private _config;
     private _events;
     private _api;
-    private _mcpClient;
-    private _planExecutor;
     private _textSelectionManager;
     private _panel;
     private _edgeTrigger;
@@ -37,9 +35,14 @@ export declare class Pillar {
     private _unsubscribeHoverMode;
     private _context;
     private _userProfile;
+    private _externalUserId;
     private _taskHandlers;
     private _anyTaskHandler;
+    _registeredActions: Map<string, Record<string, unknown>>;
     private _cardRenderers;
+    private _debugPanelContainer;
+    private _routeObserver;
+    private _suggestionPool;
     constructor();
     /**
      * Create or get the shared root container for all Pillar UI elements.
@@ -79,6 +82,24 @@ export declare class Pillar {
      * Get the resolved configuration
      */
     get config(): ResolvedConfig | null;
+    /**
+     * Whether debug mode is enabled
+     */
+    get isDebugEnabled(): boolean;
+    /**
+     * Get debug log entries (for debug panel).
+     * Returns empty array if debug mode is not enabled.
+     */
+    getDebugLog(): import('../utils/debug').DebugEntry[];
+    /**
+     * Subscribe to debug log updates (for debug panel).
+     * Returns unsubscribe function.
+     */
+    onDebugLog(callback: (entries: import('../utils/debug').DebugEntry[]) => void): () => void;
+    /**
+     * Clear debug log entries.
+     */
+    clearDebugLog(): void;
     /**
      * Subscribe to SDK events
      */
@@ -167,6 +188,115 @@ export declare class Pillar {
      * pillar.setTextSelectionEnabled(true);
      */
     setTextSelectionEnabled(enabled: boolean): void;
+    /**
+     * Enable or disable DOM scanning at runtime.
+     *
+     * @param enabled - Whether to enable DOM scanning
+     *
+     * @example
+     * // Enable DOM scanning
+     * pillar.setDOMScanningEnabled(true);
+     *
+     * // Disable DOM scanning
+     * pillar.setDOMScanningEnabled(false);
+     */
+    setDOMScanningEnabled(enabled: boolean): void;
+    /**
+     * Whether DOM scanning is currently enabled.
+     */
+    get isDOMScanningEnabled(): boolean;
+    /** Currently highlighted element (for cleanup) */
+    private _highlightedElement;
+    /** Timeout for auto-removing highlight */
+    private _highlightTimeout;
+    /** Timeout for fade-out transition completion */
+    private _fadeOutTimeout;
+    /** Original styles to restore after highlight */
+    private _originalStyles;
+    /**
+     * Highlight an element to show AI interaction.
+     * Scrolls into view if not visible and adds an outline highlight with fade transition.
+     *
+     * @param el - Element to highlight
+     */
+    private highlightElement;
+    /**
+     * Clear the current element highlight with optional fade-out.
+     * @param immediate - If true, skip fade-out transition
+     */
+    private clearHighlight;
+    /**
+     * Get a DOM element by its pillar selector.
+     *
+     * @param selector - CSS selector (typically from DOMNode.selector)
+     * @returns The matching element or null
+     */
+    getElement(selector: string): Element | null;
+    /**
+     * Click an element by its selector.
+     * Uses realistic mouse event simulation (mousedown → mouseup → click)
+     * for better compatibility with UI frameworks.
+     *
+     * @param selector - CSS selector for the element to click
+     * @returns true if the element was found and clicked, false otherwise
+     */
+    clickElement(selector: string): boolean;
+    /**
+     * Type text into an input element.
+     * Uses realistic input simulation that works with React controlled inputs.
+     *
+     * @param selector - CSS selector for the input element
+     * @param text - Text to type into the element
+     * @returns true if the element was found and text was entered, false otherwise
+     */
+    typeInElement(selector: string, text: string): boolean;
+    /**
+     * Select an option in a select element.
+     * Uses realistic event simulation for React compatibility.
+     *
+     * @param selector - CSS selector for the select element
+     * @param value - Value of the option to select
+     * @returns true if the element was found and option was selected, false otherwise
+     */
+    selectOption(selector: string, value: string): boolean;
+    /**
+     * Focus an element by its selector.
+     * Fires both focus and focusin events for compatibility.
+     *
+     * @param selector - CSS selector for the element to focus
+     * @returns true if the element was found and focused, false otherwise
+     */
+    focusElement(selector: string): boolean;
+    /**
+     * Toggle a checkbox or radio element.
+     * Uses click simulation for realistic behavior and React compatibility.
+     *
+     * @param selector - CSS selector for the checkbox/radio element
+     * @returns true if the element was found and toggled, false otherwise
+     */
+    toggleElement(selector: string): boolean;
+    /**
+     * Handle the interact_with_page action from the LLM.
+     * Routes to appropriate DOM interaction method based on operation.
+     *
+     * @param params - Interaction parameters from LLM
+     * @returns Result object with success status and optional error
+     *
+     * @example
+     * // Click a button
+     * pillar.handlePageInteraction({ operation: 'click', ref: 'pr-a1' });
+     *
+     * // Type in an input
+     * pillar.handlePageInteraction({ operation: 'type', ref: 'pr-b1', value: 'hello' });
+     */
+    handlePageInteraction(params: {
+        operation: 'click' | 'type' | 'select' | 'focus' | 'toggle';
+        ref: string;
+        value?: string;
+    }): {
+        success: boolean;
+        error?: string;
+    };
     /**
      * Mount the panel to a specific container element.
      * Used for manual mounting mode (e.g., from React component).
@@ -188,6 +318,70 @@ export declare class Pillar {
      * Set the user profile for personalization.
      */
     setUserProfile(profile: UserProfile): void;
+    /**
+     * Identify the current user after login.
+     *
+     * Call this when a user logs into your application to:
+     * - Link their anonymous conversation history to their account
+     * - Enable cross-device conversation history retrieval
+     * - Associate future conversations with their user ID
+     *
+     * @param userId - Your application's user ID for this user
+     * @param profile - Optional user profile data (name, email, metadata)
+     * @param options - Optional settings for the identify call
+     * @param options.preserveConversation - If true, keeps the current conversation (default: false)
+     *
+     * @example
+     * ```typescript
+     * // When user logs in
+     * await pillar.identify('user-123', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     * });
+     *
+     * // Keep current conversation when identifying
+     * await pillar.identify('user-123', undefined, { preserveConversation: true });
+     * ```
+     */
+    identify(userId: string, profile?: {
+        name?: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    }, options?: {
+        preserveConversation?: boolean;
+    }): Promise<void>;
+    /**
+     * Clear the user's identity (logout).
+     *
+     * Call this when a user logs out of your application.
+     * Future conversations will be tracked anonymously until identify() is called again.
+     *
+     * Note: This does not delete existing conversations - they remain associated
+     * with the user's account for future retrieval.
+     *
+     * @param options - Optional settings for the logout call
+     * @param options.preserveConversation - If true, keeps the current conversation (default: false)
+     *
+     * @example
+     * ```typescript
+     * // When user logs out
+     * pillar.logout();
+     *
+     * // Keep current conversation when logging out
+     * pillar.logout({ preserveConversation: true });
+     * ```
+     */
+    logout(options?: {
+        preserveConversation?: boolean;
+    }): void;
+    /**
+     * Get the current external user ID (if identified).
+     */
+    get externalUserId(): string | null;
+    /**
+     * Whether the current user is identified (logged in).
+     */
+    get isIdentified(): boolean;
     /**
      * Report a user action for context building.
      * Recent actions are tracked and sent with chat requests for better context.
@@ -232,6 +426,57 @@ export declare class Pillar {
      * });
      */
     onTask(taskName: string, handler: (data: Record<string, unknown>) => void): () => void;
+    /**
+     * Register an action definition at runtime.
+     *
+     * This is primarily for demos and development. In production, actions
+     * should be synced via the `pillar-sync` CLI during CI/CD.
+     *
+     * The action definition is stored locally and can be used by `onTask`
+     * handlers. For actions with `returnsData: true`, the handler's return
+     * value is sent back to the agent.
+     *
+     * @param action - Action definition with name and properties
+     *
+     * @example
+     * pillar.registerAction({
+     *   name: 'list_datasets',
+     *   description: 'List available datasets',
+     *   type: 'query',
+     *   returnsData: true,
+     * });
+     */
+    registerAction(action: {
+        name: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Get a registered action definition by name.
+     *
+     * @param name - Action name
+     * @returns Action definition or undefined
+     */
+    getRegisteredAction(name: string): Record<string, unknown> | undefined;
+    /**
+     * Get handler for an action, checking all registration systems.
+     *
+     * Lookup order:
+     * 1. Code-first action registry (synced via pillar-sync CLI) - handler in definition
+     * 2. Task handlers (registered via onTask at runtime)
+     *
+     * This is the recommended pattern:
+     * - Action definitions synced to server via CLI (so AI knows what's possible)
+     * - Handlers registered at runtime via onTask (client-side execution)
+     *
+     * @param actionName - Action name to look up
+     * @returns Handler function or undefined if not found
+     *
+     * @example
+     * const handler = pillar.getHandler('list_datasources');
+     * if (handler) {
+     *   const result = await handler({ limit: 10 });
+     * }
+     */
+    getHandler(actionName: string): ((data: Record<string, unknown>) => unknown) | undefined;
     /**
      * Register a catch-all handler for any task.
      * Useful for logging, analytics, or handling unknown tasks.
@@ -268,6 +513,22 @@ export declare class Pillar {
      * @param data - Optional result data
      */
     completeTask(taskName: string, success?: boolean, data?: Record<string, unknown>): void;
+    /**
+     * Signal that an action has completed.
+     *
+     * For simple actions, this emits the completion event.
+     * For wizard actions (modals, multi-step flows), call this when the user
+     * finishes the flow.
+     *
+     * @param actionName - The action identifier
+     * @param success - Whether the action completed successfully (default: true)
+     * @param data - Optional result data
+     *
+     * @example
+     * // In your wizard completion handler:
+     * pillar.completeAction('add_source', true, { sourceId: source.id });
+     */
+    completeAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
     /**
      * Confirm task execution result.
      * Call this after your task handler completes to report success/failure
@@ -293,7 +554,7 @@ export declare class Pillar {
      *   }
      * });
      */
-    confirmTaskExecution(taskId: string, status: 'success' | 'failure', details?: {
+    confirmTaskExecution(taskId: string, status: "success" | "failure", details?: {
         error?: string;
         duration_ms?: number;
         [key: string]: unknown;
@@ -380,104 +641,81 @@ export declare class Pillar {
      */
     private _executeWorkflowStep;
     /**
-     * Get the active execution plan, if any.
-     */
-    get activePlan(): ExecutionPlan | null;
-    /**
-     * Handle a plan received from the AI streaming response.
-     * Called when the ReAct agent creates a plan via the create_plan tool.
+     * Send action result back to the agent.
      *
-     * @param plan - The execution plan from the server
-     */
-    handlePlanReceived(plan: ExecutionPlan): void;
-    /**
-     * Start a plan that was waiting for user confirmation.
-     * For plans with auto_execute=false, the user must explicitly start execution.
-     */
-    startPlan(): Promise<void>;
-    /**
-     * Confirm a plan step requiring confirmation.
+     * Called automatically for actions with `returns: true` after their
+     * handler completes. The result is sent to the agent for further reasoning.
      *
-     * @param stepId - UUID of the step to confirm
-     * @param data - Optional modified data from user input
+     * @param actionName - The name of the action that was executed
+     * @param result - The result data to send back to the agent
+     * @param toolCallId - Unique ID for this specific tool invocation (for result correlation)
+     * @returns Promise that resolves when the result is delivered
+     * @internal
      */
-    confirmPlanStep(stepId: string, data?: Record<string, unknown>): Promise<void>;
+    sendActionResult(actionName: string, result: unknown, toolCallId?: string): Promise<void>;
     /**
-     * Confirm an inline_ui step with data from the inline card.
+     * Execute a query action and send the result back to the agent.
      *
-     * This is called when the user interacts with an inline card (e.g., invite form)
-     * within a plan step and clicks confirm.
+     * This is called when the agent sends a `query_request` event.
+     * Query actions are expected to return data that the agent can use
+     * for further reasoning.
      *
-     * @param stepId - UUID of the step to confirm
-     * @param data - Data from the inline card (e.g., email, form fields)
+     * @param actionName - The name of the action to execute
+     * @param args - Arguments for the action
+     * @param schema - Optional schema for parameter validation
      */
-    confirmInlinePlanStep(stepId: string, data?: Record<string, unknown>): Promise<void>;
+    executeQueryAction(actionName: string, args?: Record<string, unknown>, schema?: {
+        properties?: Record<string, unknown>;
+        required?: string[];
+    }): Promise<void>;
     /**
-     * Skip a plan step.
-     *
-     * @param stepId - UUID of the step to skip
+     * Validate query parameters against a schema.
+     * @returns Error message if validation fails, null if valid
      */
-    skipPlanStep(stepId: string): Promise<void>;
+    private _validateQueryParams;
     /**
-     * Retry a failed step in the active plan.
-     *
-     * @param stepId - UUID of the step to retry
+     * Internal initialization
      */
-    retryPlanStep(stepId: string): Promise<void>;
+    private _init;
     /**
-     * Cancel the active plan.
+     * Actual initialization logic
      */
-    cancelPlan(): Promise<void>;
+    private _doInit;
     /**
-     * Complete a plan step by action name.
-     *
-     * Use this when the host app completes a wizard or flow that was started
-     * by a plan step. The plan will advance to the next step.
-     *
-     * @param actionName - The action name (e.g., 'add_new_source')
-     * @param success - Whether the action completed successfully (default: true)
-     * @param data - Optional result data
-     *
-     * @example
-     * // In your source creation success handler:
-     * pillar.completePlanStepByAction('add_new_source');
+     * Attempt to recover an interrupted session from localStorage.
+     * Checks if there's a saved session hint and validates with the server.
      */
-    completePlanStepByAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
+    private _recoverSession;
     /**
-     * Mark a plan step as done by step ID.
-     *
-     * Use this when the UI "Done" button is clicked for a wizard step.
-     * The step must be in 'awaiting_result' status.
-     *
-     * @param stepId - UUID of the step to mark as done
+     * Handle URL parameters for auto-opening the panel
      */
-    markPlanStepDone(stepId: string): Promise<void>;
+    private _handleUrlParams;
     /**
-     * Send action result back to the agent.
-     *
-     * Called automatically for actions with `returns: true` after their
-     * handler completes. The result is sent to the agent for further reasoning.
-     *
-     * @param actionName - The name of the action that was executed
-     * @param result - The result data to send back to the agent
-     * @internal
+     * Mount the debug panel to the document body.
      */
-    sendActionResult(actionName: string, result: unknown): void;
+    private _mountDebugPanel;
     /**
-     * Internal initialization
+     * Set up debug event capturing for all SDK events.
+     * Logs all events to the debug log store for display in the debug panel.
      */
-    private _init;
+    private _setupDebugEventCapture;
     /**
-     * Actual initialization logic
+     * Initialize page-aware suggestions.
+     * Fetches the suggestion pool from the backend and starts route observation.
      */
-    private _doInit;
+    private _initSuggestions;
     /**
-     * Handle URL parameters for auto-opening the panel
+     * Handle route change by re-sorting suggestions for the new page context.
      */
-    private _handleUrlParams;
+    private _handleRouteChange;
     /**
      * Internal cleanup
      */
     private _destroy;
 }
+/**
+ * Get the API client from the current Pillar instance.
+ * Returns null if SDK is not initialized.
+ */
+export declare function getApiClient(): APIClient | null;
 export default Pillar;

package/dist/core/config.d.ts

@@ -110,6 +110,102 @@ export interface TextSelectionConfig {
     /** Label for the popover button (default: 'Ask AI') */
     label?: string;
 }
+export interface InteractionHighlightConfig {
+    /**
+     * Whether to highlight elements when the AI interacts with them.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Outline color for highlighted elements (CSS color value).
+     * @default '#3b82f6' (blue-500)
+     */
+    outlineColor?: string;
+    /**
+     * Outline width in pixels.
+     * @default 2
+     */
+    outlineWidth?: number;
+    /**
+     * Outline offset in pixels (space between element and outline).
+     * @default 2
+     */
+    outlineOffset?: number;
+    /**
+     * Duration in milliseconds to show the highlight.
+     * Set to 0 for no auto-removal (highlight stays until next interaction).
+     * @default 2000
+     */
+    duration?: number;
+    /**
+     * Whether to scroll the element into view if not visible.
+     * @default true
+     */
+    scrollIntoView?: boolean;
+    /**
+     * Scroll behavior when scrolling element into view.
+     * @default 'smooth'
+     */
+    scrollBehavior?: ScrollBehavior;
+}
+export interface DOMScanningConfig {
+    /**
+     * Whether DOM scanning is enabled.
+     * When enabled, page structure is captured and sent with messages.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Whether to include text content in the scan.
+     * @default true
+     */
+    includeText?: boolean;
+    /**
+     * Maximum depth to traverse the DOM tree.
+     * @default 20
+     */
+    maxDepth?: number;
+    /**
+     * Whether to only include visible elements.
+     * @default true
+     */
+    visibleOnly?: boolean;
+    /**
+     * CSS selector for elements to exclude from scanning.
+     * @example '.sidebar, .footer, [data-no-scan]'
+     */
+    excludeSelector?: string;
+    /**
+     * Maximum text length before truncation.
+     * @default 500
+     */
+    maxTextLength?: number;
+    /**
+     * Configuration for highlighting elements during AI interactions.
+     */
+    interactionHighlight?: InteractionHighlightConfig;
+}
+export interface SuggestionsConfig {
+    /**
+     * Enable page-aware suggestion sorting.
+     * When enabled, suggestions are re-sorted based on the current page context
+     * whenever the user navigates to a new route.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Debounce time for route change detection (ms).
+     * Prevents excessive sorting on rapid navigation.
+     * @default 100
+     */
+    debounceMs?: number;
+    /**
+     * Maximum number of suggestions to display.
+     * The backend returns a larger pool which is sorted and trimmed to this limit.
+     * @default 6
+     */
+    displayLimit?: number;
+}
 export interface EdgeTriggerConfig {
     /**
      * Whether to show the edge trigger sidebar tab.
@@ -177,7 +273,11 @@ export interface MobileTriggerConfig {
     offset?: number;
 }
 export interface PillarConfig {
-    helpCenter: string;
+    /**
+     * Your product key from the Pillar app.
+     * Get it at app.trypillar.com
+     */
+    productKey?: string;
     /**
      * Platform identifier for code-first actions.
      * Used to filter actions by deployment platform.
@@ -190,11 +290,22 @@ export interface PillarConfig {
      * @example '1.2.3' or git commit SHA
      */
     version?: string;
+    /**
+     * Enable debug mode for verbose logging and debug panel.
+     * When enabled:
+     * - All SDK events are logged to console
+     * - A debug panel shows real-time execution flow
+     * - Network requests/responses are captured
+     * @default false
+     */
+    debug?: boolean;
     panel?: PanelConfig;
     edgeTrigger?: EdgeTriggerConfig;
     mobileTrigger?: MobileTriggerConfig;
     urlParams?: UrlParamsConfig;
     textSelection?: TextSelectionConfig;
+    domScanning?: DOMScanningConfig;
+    suggestions?: SuggestionsConfig;
     sidebarTabs?: SidebarTabConfig[];
     apiBaseUrl?: string;
     theme?: ThemeConfig;
@@ -244,25 +355,52 @@ export interface ResolvedThemeConfig {
     colors: ThemeColors;
     darkColors: ThemeColors;
 }
+export interface ResolvedInteractionHighlightConfig {
+    enabled: boolean;
+    outlineColor: string;
+    outlineWidth: number;
+    outlineOffset: number;
+    duration: number;
+    scrollIntoView: boolean;
+    scrollBehavior: ScrollBehavior;
+}
+export interface ResolvedDOMScanningConfig {
+    enabled: boolean;
+    includeText: boolean;
+    maxDepth: number;
+    visibleOnly: boolean;
+    excludeSelector?: string;
+    maxTextLength: number;
+    interactionHighlight: ResolvedInteractionHighlightConfig;
+}
+export interface ResolvedSuggestionsConfig {
+    enabled: boolean;
+    debounceMs: number;
+    displayLimit: number;
+}
 export interface ResolvedConfig {
-    helpCenter: string;
+    productKey: string;
     apiBaseUrl: string;
     /** Platform for code-first actions (default: 'web') */
     platform: Platform;
     /** App version for code-first actions (optional) */
     version?: string;
+    /** Debug mode enabled */
+    debug: boolean;
     panel: ResolvedPanelConfig;
     edgeTrigger: Required<EdgeTriggerConfig>;
     mobileTrigger: ResolvedMobileTriggerConfig;
     urlParams: Required<UrlParamsConfig>;
     textSelection: Required<TextSelectionConfig>;
+    domScanning: ResolvedDOMScanningConfig;
+    suggestions: ResolvedSuggestionsConfig;
     sidebarTabs: SidebarTabConfig[];
     theme: ResolvedThemeConfig;
     customCSS?: string;
     onReady?: () => void;
     onError?: (error: Error) => void;
 }
-export declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'helpCenter' | 'publicKey'>;
+export declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'productKey' | 'publicKey'>;
 export declare function resolveConfig(config: PillarConfig): ResolvedConfig;
 /**
  * Server embed config type (matches backend response)