@pillar-ai/sdk 0.1.0

package/dist/components/shared/QuestionChip.d.ts

@@ -0,0 +1,14 @@
+/**
+ * QuestionChip Component
+ * Clickable chip for suggested questions
+ */
+import { h } from 'preact';
+export interface QuestionChipProps {
+    text: string;
+    onClick: () => void;
+}
+export declare function QuestionChip({ text, onClick }: QuestionChipProps): h.JSX.Element;
+/**
+ * Skeleton placeholder for loading state
+ */
+export declare function QuestionChipSkeleton(): h.JSX.Element;

package/dist/components/shared/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Components Index
+ */
+export { Loading } from './Loading';
+export { Empty } from './Empty';
+export { QuestionChip, QuestionChipSkeleton } from './QuestionChip';
+export { MessageInputArea } from './MessageInputArea';

package/dist/content/extensions/AccordionNode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Accordion Node Extension for TipTap (vanilla - HTML rendering only)
+ * Used to render collapsible accordion blocks in article content
+ */
+import { Node } from '@tiptap/core';
+/**
+ * TipTap Accordion Node Extension (vanilla, no React)
+ * Renders accordion blocks using HTML details/summary elements
+ */
+export declare const AccordionNode: Node<any, any>;

package/dist/content/extensions/CalloutNode.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Callout Node Extension for TipTap (vanilla - HTML rendering only)
+ * Used to render callout blocks in article content
+ */
+import { Node } from '@tiptap/core';
+export type CalloutType = 'info' | 'warning' | 'tip' | 'error' | 'success';
+/**
+ * TipTap Callout Node Extension (vanilla, no React)
+ * Renders callout blocks with type-specific styling classes
+ */
+export declare const CalloutNode: Node<any, any>;

package/dist/content/extensions/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TipTap Extensions for SDK content rendering
+ */
+export { CalloutNode, type CalloutType } from './CalloutNode';
+export { AccordionNode } from './AccordionNode';

package/dist/content/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Content rendering utilities for the SDK
+ */
+export { renderArticleContent, renderTipTapContent, isJSONContent, } from './renderer';
+export type { CalloutType } from './extensions';

package/dist/content/renderer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TipTap Content Renderer
+ * Converts TipTap JSON content to HTML for display in the SDK panel
+ */
+import type { JSONContent } from '@tiptap/core';
+/**
+ * Check if content is TipTap JSON format (has a 'type' property)
+ */
+export declare function isJSONContent(content: unknown): content is JSONContent;
+/**
+ * Render TipTap JSON content to HTML
+ *
+ * @param content - TipTap JSON content object
+ * @returns HTML string
+ */
+export declare function renderTipTapContent(content: JSONContent): string;
+/**
+ * Render article content to HTML
+ * Handles both TipTap JSON and legacy HTML string content
+ *
+ * @param content - TipTap JSON content or HTML string
+ * @returns HTML string
+ */
+export declare function renderArticleContent(content: JSONContent | string | null | undefined): string;

package/dist/core/Pillar.d.ts

@@ -0,0 +1,454 @@
+/**
+ * Main Pillar SDK Class
+ * Entry point for all SDK functionality
+ */
+import { type PillarConfig, type ResolvedConfig, type ThemeConfig } from './config';
+import { type ProductContext, 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';
+export declare class Pillar {
+    private static instance;
+    private _state;
+    private _config;
+    private _events;
+    private _api;
+    private _mcpClient;
+    private _planExecutor;
+    private _tooltipManager;
+    private _textSelectionManager;
+    private _panel;
+    private _floatingButton;
+    private _initPromise;
+    private _rootContainer;
+    private _unsubscribeHoverMode;
+    private _productContext;
+    private _userProfile;
+    private _taskHandlers;
+    private _anyTaskHandler;
+    private _cardRenderers;
+    constructor();
+    /**
+     * Create or get the shared root container for all Pillar UI elements.
+     * Uses isolation: isolate to create a new stacking context.
+     * Z-index changes based on hover mode (999 in hover mode, -1 in push mode).
+     */
+    private _createRootContainer;
+    /**
+     * Subscribe to hover mode changes and update root container z-index.
+     */
+    private _subscribeToHoverModeForRoot;
+    /**
+     * Initialize the Pillar SDK
+     */
+    static init(config: PillarConfig): Promise<Pillar>;
+    /**
+     * Get the current Pillar instance
+     */
+    static getInstance(): Pillar | null;
+    /**
+     * Destroy the Pillar instance
+     */
+    static destroy(): void;
+    /**
+     * Current SDK state
+     */
+    get state(): PillarState;
+    /**
+     * Whether SDK is ready
+     */
+    get isReady(): boolean;
+    /**
+     * Whether the panel is currently open
+     */
+    get isPanelOpen(): boolean;
+    /**
+     * Get the resolved configuration
+     */
+    get config(): ResolvedConfig | null;
+    /**
+     * Subscribe to SDK events
+     */
+    on<K extends keyof PillarEvents>(event: K, callback: (data: PillarEvents[K]) => void): () => void;
+    /**
+     * Open the help panel
+     */
+    open(options?: {
+        view?: string;
+        article?: string;
+        search?: string;
+        focusInput?: boolean;
+    }): void;
+    /**
+     * Close the help panel
+     */
+    close(): void;
+    /**
+     * Toggle the help panel
+     */
+    toggle(): void;
+    /**
+     * Navigate to a specific view in the panel
+     */
+    navigate(view: string, params?: Record<string, string>): void;
+    /**
+     * Update the user context
+     */
+    setContext(context: ResolvedConfig['context']): void;
+    /**
+     * Update the theme at runtime.
+     * Use this to sync with your app's theme (e.g., dark mode toggle).
+     *
+     * @param theme - Partial theme config to merge with current theme
+     *
+     * @example
+     * // Switch to dark mode
+     * pillar.setTheme({ mode: 'dark' });
+     *
+     * // Switch to light mode with custom primary color
+     * pillar.setTheme({ mode: 'light', colors: { primary: '#ff0000' } });
+     *
+     * // Let system preference decide
+     * pillar.setTheme({ mode: 'auto' });
+     */
+    setTheme(theme: Partial<ThemeConfig>): void;
+    /**
+     * Enable or disable the text selection "Ask AI" popover at runtime.
+     *
+     * @param enabled - Whether to show the popover when text is selected
+     *
+     * @example
+     * // Disable text selection popover
+     * pillar.setTextSelectionEnabled(false);
+     *
+     * // Re-enable it
+     * pillar.setTextSelectionEnabled(true);
+     */
+    setTextSelectionEnabled(enabled: boolean): void;
+    /**
+     * Manually trigger tooltip scan
+     */
+    scanTooltips(): void;
+    /**
+     * Show a specific tooltip
+     */
+    showTooltip(tooltipId: string): void;
+    /**
+     * Hide a specific tooltip
+     */
+    hideTooltip(tooltipId: string): void;
+    /**
+     * Mount the panel to a specific container element.
+     * Used for manual mounting mode (e.g., from React component).
+     */
+    mountPanelTo(container: HTMLElement): void;
+    /**
+     * Get the panel host element for external mounting
+     */
+    getPanelHostElement(): HTMLElement | null;
+    /**
+     * Get the current product context
+     */
+    get productContext(): ProductContext;
+    /**
+     * Get the current user profile
+     */
+    get userProfile(): UserProfile;
+    /**
+     * Set the complete product context.
+     * Use this when navigating to a new page or starting a new session.
+     */
+    setProductContext(context: ProductContext): void;
+    /**
+     * Update specific product context fields without replacing the entire context.
+     * Use this for incremental updates like tracking actions.
+     */
+    updateContext(updates: Partial<ProductContext>): void;
+    /**
+     * Set the user profile for personalization.
+     */
+    setUserProfile(profile: UserProfile): void;
+    /**
+     * Report a user action for context building.
+     * Recent actions are tracked and sent with chat requests for better context.
+     *
+     * @param action - Description of the action (e.g., "clicked_upgrade", "viewed_invoice")
+     * @param metadata - Optional metadata about the action
+     */
+    reportAction(action: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Clear any error state from the context.
+     */
+    clearErrorState(): void;
+    /**
+     * Set an error state in the context.
+     * The assistant will use this to provide relevant troubleshooting help.
+     */
+    setErrorState(code: string, message: string): void;
+    /**
+     * Get contextual help suggestions based on current product context.
+     * Returns relevant articles, videos, and actions.
+     */
+    getSuggestions(): Promise<Suggestion[]>;
+    /**
+     * Get the full context object to send to the backend.
+     * Used internally by the API client.
+     */
+    getAssistantContext(): {
+        product: ProductContext;
+        user: UserProfile;
+    };
+    /**
+     * Register a handler for a specific task.
+     * Called when the AI suggests a task and the user clicks it.
+     *
+     * @param taskName - The task identifier (e.g., 'invite_team_member')
+     * @param handler - Function to handle the task execution
+     * @returns Unsubscribe function
+     *
+     * @example
+     * pillar.onTask('invite_team_member', (data) => {
+     *   openInviteModal(data);
+     * });
+     */
+    onTask(taskName: string, handler: (data: Record<string, unknown>) => void): () => void;
+    /**
+     * Register a catch-all handler for any task.
+     * Useful for logging, analytics, or handling unknown tasks.
+     *
+     * @param handler - Function called with task name and data
+     * @returns Unsubscribe function
+     *
+     * @example
+     * pillar.onAnyTask((name, data) => {
+     *   analytics.track('task_executed', { name, data });
+     * });
+     */
+    onAnyTask(handler: (name: string, data: Record<string, unknown>) => void): () => void;
+    /**
+     * Remove a task handler.
+     *
+     * @param taskName - The task identifier to stop handling
+     */
+    offTask(taskName: string): void;
+    /**
+     * Execute a task programmatically.
+     * This is called internally by the widget when a user clicks a task button.
+     * Can also be called directly if you want to trigger a task.
+     *
+     * @param payload - Task execution payload
+     */
+    executeTask(payload: TaskExecutePayload): void;
+    /**
+     * Mark a task as complete.
+     * Call this after your task handler finishes successfully.
+     *
+     * @param taskName - The task identifier
+     * @param success - Whether the task completed successfully
+     * @param data - Optional result data
+     */
+    completeTask(taskName: string, success?: boolean, data?: Record<string, unknown>): void;
+    /**
+     * Confirm task execution result.
+     * Call this after your task handler completes to report success/failure
+     * back to Pillar for implementation status tracking.
+     *
+     * @param taskId - The database UUID of the task (from task:execute event)
+     * @param status - 'success' or 'failure'
+     * @param details - Optional execution details
+     *
+     * @example
+     * pillar.on('task:execute', async (task) => {
+     *   const startTime = Date.now();
+     *   try {
+     *     await performAction(task);
+     *     pillar.confirmTaskExecution(task.id, 'success', {
+     *       duration_ms: Date.now() - startTime,
+     *     });
+     *   } catch (error) {
+     *     pillar.confirmTaskExecution(task.id, 'failure', {
+     *       error: error.message,
+     *       duration_ms: Date.now() - startTime,
+     *     });
+     *   }
+     * });
+     */
+    confirmTaskExecution(taskId: string, status: 'success' | 'failure', details?: {
+        error?: string;
+        duration_ms?: number;
+        [key: string]: unknown;
+    }): void;
+    /**
+     * Register a custom card renderer for inline_ui type actions.
+     *
+     * When the AI returns an action with action_type: 'inline_ui' and
+     * a card_type in its data, the SDK will look for a registered renderer
+     * and call it to render the inline UI card.
+     *
+     * @param cardType - The card type identifier (e.g., 'invite_members')
+     * @param renderer - Function that renders the card into a container
+     * @returns Unsubscribe function
+     *
+     * @example
+     * // Vanilla JS
+     * pillar.registerCard('invite_members', (container, data, callbacks) => {
+     *   container.innerHTML = `
+     *     <div class="invite-card">
+     *       <h3>Invite Team Members</h3>
+     *       ${data.emails.map(e => `<div>${e}</div>`).join('')}
+     *       <button id="confirm">Send Invites</button>
+     *     </div>
+     *   `;
+     *   container.querySelector('#confirm').onclick = callbacks.onConfirm;
+     *   return () => container.innerHTML = ''; // cleanup
+     * });
+     */
+    registerCard(cardType: string, renderer: CardRenderer): () => void;
+    /**
+     * Get a registered card renderer by type.
+     * Returns undefined if no renderer is registered for the given type.
+     *
+     * @param cardType - The card type identifier
+     */
+    getCardRenderer(cardType: string): CardRenderer | undefined;
+    /**
+     * Check if a card renderer is registered for a given type.
+     *
+     * @param cardType - The card type identifier
+     */
+    hasCardRenderer(cardType: string): boolean;
+    /**
+     * Get the active workflow, if any.
+     */
+    get workflow(): Workflow | null;
+    /**
+     * Start a workflow.
+     * Called when the AI returns a workflow in its response.
+     *
+     * @param workflow - The workflow to start
+     */
+    startWorkflow(workflow: Workflow): void;
+    /**
+     * Initiate a workflow step that requires user confirmation.
+     * Called when user clicks "Start" on a step with auto_run=false.
+     *
+     * @param stepIndex - Optional step index (defaults to current)
+     */
+    initiateWorkflowStep(stepIndex?: number): void;
+    /**
+     * Confirm a workflow step as complete.
+     * Called by the host app after the action is done.
+     * Automatically advances to the next step.
+     *
+     * @param success - Whether the step completed successfully
+     * @param stepIndex - Optional step index (defaults to current)
+     */
+    confirmWorkflowStep(success: boolean, stepIndex?: number): void;
+    /**
+     * Skip a workflow step.
+     *
+     * @param stepIndex - Optional step index (defaults to current)
+     */
+    skipWorkflowStep(stepIndex?: number): void;
+    /**
+     * Cancel the active workflow.
+     */
+    cancelWorkflow(): void;
+    /**
+     * Execute a workflow step.
+     * Internal method that runs the task and handles auto_complete.
+     */
+    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.
+     *
+     * @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.
+     *
+     * @param stepId - UUID of the step to confirm
+     * @param data - Optional modified data from user input
+     */
+    confirmPlanStep(stepId: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Skip a plan step.
+     *
+     * @param stepId - UUID of the step to skip
+     */
+    skipPlanStep(stepId: string): Promise<void>;
+    /**
+     * Retry a failed step in the active plan.
+     *
+     * @param stepId - UUID of the step to retry
+     */
+    retryPlanStep(stepId: string): Promise<void>;
+    /**
+     * Cancel the active plan.
+     */
+    cancelPlan(): Promise<void>;
+    /**
+     * 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');
+     */
+    completePlanStepByAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * 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
+     */
+    markPlanStepDone(stepId: string): Promise<void>;
+    /**
+     * 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
+     */
+    sendActionResult(actionName: string, result: unknown): void;
+    /**
+     * Internal initialization
+     */
+    private _init;
+    /**
+     * Actual initialization logic
+     */
+    private _doInit;
+    /**
+     * Handle URL parameters for auto-opening the panel
+     */
+    private _handleUrlParams;
+    /**
+     * Internal cleanup
+     */
+    private _destroy;
+}
+export default Pillar;