@pillar-ai/sdk 0.1.0

package/dist/core/config.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Pillar SDK Configuration Types
+ */
+import type { Platform } from '../actions/types';
+export type PanelPosition = 'left' | 'right';
+export type PanelMode = 'overlay' | 'push';
+export type FloatingButtonPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+export type FloatingButtonStyle = 'floating' | 'edge';
+export type TooltipTrigger = 'hover' | 'click' | 'focus' | 'icon';
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+export type ThemeMode = 'light' | 'dark' | 'auto';
+/**
+ * Sidebar tab configuration
+ */
+export interface SidebarTabConfig {
+    id: string;
+    label: string;
+    enabled: boolean;
+    order: number;
+}
+export declare const DEFAULT_SIDEBAR_TABS: SidebarTabConfig[];
+/**
+ * Theme color configuration
+ * All colors should be valid CSS color values (hex, rgb, hsl, etc.)
+ */
+export interface ThemeColors {
+    /** Primary brand color (buttons, links, accents) */
+    primary?: string;
+    /** Primary color on hover state */
+    primaryHover?: string;
+    /** Main background color */
+    background?: string;
+    /** Secondary/subtle background (inputs, cards) */
+    backgroundSecondary?: string;
+    /** Primary text color */
+    text?: string;
+    /** Muted/secondary text color */
+    textMuted?: string;
+    /** Border color */
+    border?: string;
+    /** Border color for subtle/light borders */
+    borderLight?: string;
+}
+/**
+ * Theme configuration for customizing panel appearance
+ */
+export interface ThemeConfig {
+    /**
+     * Color mode: 'light', 'dark', or 'auto' (follows system preference)
+     * @default 'auto'
+     */
+    mode?: ThemeMode;
+    /** Custom color overrides for light mode */
+    colors?: ThemeColors;
+    /** Custom color overrides for dark mode (when mode is 'auto' or 'dark') */
+    darkColors?: ThemeColors;
+}
+export interface PanelConfig {
+    enabled?: boolean;
+    position?: PanelPosition;
+    /** Panel mode: 'overlay' slides over content, 'push' shifts content aside */
+    mode?: PanelMode;
+    width?: number;
+    /**
+     * Custom mount point for the panel.
+     * - CSS selector string (e.g., '#pillar-panel')
+     * - HTMLElement reference
+     * - 'manual' for React component-based mounting
+     * - undefined (default) mounts to document.body
+     */
+    container?: string | HTMLElement | 'manual';
+    /**
+     * Whether to use Shadow DOM for style isolation.
+     * - false (default): Panel renders in regular DOM, inherits host app CSS.
+     *   Custom cards can use the host app's design system (Tailwind, etc.)
+     * - true: Panel renders in Shadow DOM, fully isolated from host CSS.
+     *   Use this if you need style isolation on third-party sites.
+     * @default false
+     */
+    useShadowDOM?: boolean;
+    /**
+     * Viewport width below which the panel switches from 'push' mode to 'hover' mode.
+     * In hover mode, the panel floats over content instead of pushing it aside.
+     * - number: The breakpoint in pixels (default: 1200)
+     * - false: Disable responsive behavior, always use push mode
+     * @default 1200
+     */
+    hoverBreakpoint?: number | false;
+    /**
+     * Whether to show a backdrop overlay when the panel is in hover mode.
+     * Only applies when viewport is below hoverBreakpoint.
+     * @default true
+     */
+    hoverBackdrop?: boolean;
+}
+export interface FloatingButtonConfig {
+    enabled?: boolean;
+    position?: FloatingButtonPosition;
+    label?: string;
+    /**
+     * Button style:
+     * - 'edge': Slim vertical tab on screen edge, expands on hover (default)
+     * - 'floating': Traditional floating pill button
+     * @default 'edge'
+     */
+    style?: FloatingButtonStyle;
+}
+export interface TooltipsConfig {
+    enabled?: boolean;
+    defaultTrigger?: TooltipTrigger;
+}
+export interface UrlParamsConfig {
+    /** Whether to check URL params for auto-opening the panel (default: true) */
+    enabled?: boolean;
+    /** Prefix for URL params (default: 'pillar-') */
+    prefix?: string;
+    /** Whether to clear URL params after opening (default: true) */
+    clearAfterOpen?: boolean;
+}
+export interface TextSelectionConfig {
+    /** Whether to show "Ask AI" popover on text selection (default: true) */
+    enabled?: boolean;
+    /** Label for the popover button (default: 'Ask AI') */
+    label?: string;
+}
+export interface UserContext {
+    id?: string;
+    persona?: string;
+    [key: string]: unknown;
+}
+export interface PillarConfig {
+    helpCenter: string;
+    publicKey: string;
+    /**
+     * Platform identifier for code-first actions.
+     * Used to filter actions by deployment platform.
+     * @default 'web'
+     */
+    platform?: Platform;
+    /**
+     * App version for code-first actions.
+     * Used to match actions to the correct deployment version.
+     * @example '1.2.3' or git commit SHA
+     */
+    version?: string;
+    panel?: PanelConfig;
+    floatingButton?: FloatingButtonConfig;
+    tooltips?: TooltipsConfig;
+    urlParams?: UrlParamsConfig;
+    textSelection?: TextSelectionConfig;
+    sidebarTabs?: SidebarTabConfig[];
+    context?: {
+        page?: string;
+        user?: UserContext;
+    };
+    apiBaseUrl?: string;
+    theme?: ThemeConfig;
+    /**
+     * Custom CSS to inject into the panel's Shadow DOM.
+     * Use public class names (pillar-*) to override default styles.
+     * @example
+     * ```css
+     * .pillar-header { padding: 24px; }
+     * .pillar-message-user { border-radius: 8px; }
+     * ```
+     */
+    customCSS?: string;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface ResolvedPanelConfig {
+    enabled: boolean;
+    position: PanelPosition;
+    mode: PanelMode;
+    width: number;
+    /** Custom mount point - undefined means document.body */
+    container?: string | HTMLElement | 'manual';
+    /** Whether to use Shadow DOM for style isolation */
+    useShadowDOM: boolean;
+    /** Viewport width below which panel hovers instead of pushes. false = always push. */
+    hoverBreakpoint: number | false;
+    /** Whether to show backdrop when in hover mode */
+    hoverBackdrop: boolean;
+}
+export interface ResolvedThemeConfig {
+    mode: ThemeMode;
+    colors: ThemeColors;
+    darkColors: ThemeColors;
+}
+export interface ResolvedConfig {
+    helpCenter: string;
+    publicKey: string;
+    apiBaseUrl: string;
+    /** Platform for code-first actions (default: 'web') */
+    platform: Platform;
+    /** App version for code-first actions (optional) */
+    version?: string;
+    panel: ResolvedPanelConfig;
+    floatingButton: Required<FloatingButtonConfig>;
+    tooltips: Required<TooltipsConfig>;
+    urlParams: Required<UrlParamsConfig>;
+    textSelection: Required<TextSelectionConfig>;
+    sidebarTabs: SidebarTabConfig[];
+    theme: ResolvedThemeConfig;
+    customCSS?: string;
+    context: {
+        page?: string;
+        user?: UserContext;
+    };
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'helpCenter' | 'publicKey'>;
+export declare function resolveConfig(config: PillarConfig): ResolvedConfig;
+/**
+ * Server embed config type (matches backend response)
+ */
+export interface ServerEmbedConfig {
+    panel?: {
+        enabled?: boolean;
+        position?: 'left' | 'right';
+        width?: number;
+    };
+    floatingButton?: {
+        enabled?: boolean;
+        position?: string;
+        label?: string;
+    };
+    features?: {
+        aiChatEnabled?: boolean;
+        searchEnabled?: boolean;
+        tooltipsEnabled?: boolean;
+    };
+    sidebarTabs?: SidebarTabConfig[];
+    theme?: {
+        colors?: {
+            primary?: string;
+        };
+    };
+}
+/**
+ * Merge server config with local config.
+ *
+ * Priority: DEFAULT_CONFIG < serverConfig < localConfig
+ *
+ * Server values fill in gaps (admin-configured defaults),
+ * but local config (passed to Pillar.init()) always wins.
+ *
+ * @param localConfig - Config passed to Pillar.init()
+ * @param serverConfig - Config fetched from /api/public/products/{subdomain}/embed-config/
+ * @returns Merged config with server values filling in gaps
+ */
+export declare function mergeServerConfig(localConfig: PillarConfig, serverConfig: ServerEmbedConfig | null): PillarConfig;

package/dist/core/context.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Product Context Types for Pillar SDK
+ *
+ * These types enable context-aware assistance by providing
+ * information about what the user is doing in the product.
+ */
+/**
+ * Product context for the assistant.
+ * Pass this to help the assistant understand what the user is doing.
+ */
+export interface ProductContext {
+    /** Current page path (e.g., "/settings/billing") */
+    currentPage?: string;
+    /** Current feature or section (e.g., "Billing Settings") */
+    currentFeature?: string;
+    /** User's role in the product (e.g., "admin", "member") */
+    userRole?: string;
+    /** Current user state or mode (e.g., "onboarding", "trial") */
+    userState?: string;
+    /** Recent user actions for context */
+    recentActions?: string[];
+    /** Any error state the user is experiencing */
+    errorState?: {
+        code: string;
+        message: string;
+    };
+    /** Custom context data */
+    custom?: Record<string, unknown>;
+}
+/**
+ * User profile for personalization.
+ */
+export interface UserProfile {
+    /** User identifier (for conversation continuity) */
+    userId?: string;
+    /** User's name for personalized responses */
+    name?: string;
+    /** User's role/permissions */
+    role?: string;
+    /** Account/organization info */
+    accountType?: string;
+    /** User's experience level */
+    experienceLevel?: 'beginner' | 'intermediate' | 'advanced';
+}
+/**
+ * Suggestion returned from the suggestions API.
+ */
+export interface Suggestion {
+    type: 'article' | 'video' | 'tutorial' | 'action';
+    id: string;
+    title: string;
+    description: string;
+    relevanceScore: number;
+    url?: string;
+}
+/**
+ * Combined context sent to the backend.
+ */
+export interface AssistantContext {
+    product: ProductContext;
+    user: UserProfile;
+}
+/**
+ * Default empty context.
+ */
+export declare const DEFAULT_PRODUCT_CONTEXT: ProductContext;
+export declare const DEFAULT_USER_PROFILE: UserProfile;
+/**
+ * Maximum number of recent actions to track.
+ */
+export declare const MAX_RECENT_ACTIONS = 10;

package/dist/core/events.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Simple EventEmitter for SDK events
+ */
+import type { ResolvedThemeConfig } from './config';
+import type { ProductContext, UserProfile } from './context';
+import type { ExecutionPlan, ExecutionStep } from './plan';
+import type { Workflow, WorkflowStep } from './workflow';
+export type EventCallback<T = unknown> = (data: T) => void;
+/**
+ * Task execution payload - sent when a task button is clicked.
+ */
+export interface TaskExecutePayload {
+    /** Database UUID for the task (used for confirmation) */
+    id?: string;
+    /** Task unique identifier (e.g., 'invite_team_member') */
+    name: string;
+    /** Task data payload */
+    data: Record<string, unknown>;
+    /** Task type hint */
+    taskType?: 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+    /** Path template for navigate type (already resolved with params) */
+    path?: string;
+    /** External URL for external_link type */
+    externalUrl?: string;
+}
+/**
+ * Callbacks provided to custom card renderers.
+ */
+export interface CardCallbacks {
+    /** Called when user confirms the action. Pass modified data if needed. */
+    onConfirm: (modifiedData?: Record<string, unknown>) => void;
+    /** Called when user cancels the action */
+    onCancel: () => void;
+    /** Called to report card state changes (for analytics/confirmation) */
+    onStateChange?: (state: 'loading' | 'success' | 'error', message?: string) => void;
+}
+/**
+ * Card field schema definition for declarative card configuration.
+ */
+export interface CardFieldSchema {
+    /** Field name/key */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Field type */
+    type: 'text' | 'number' | 'email' | 'select' | 'multiselect' | 'checkbox' | 'textarea' | 'date' | 'hidden';
+    /** Whether field is required */
+    required?: boolean;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text shown below field */
+    helpText?: string;
+    /** Options for select/multiselect types */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Validation rules */
+    validation?: {
+        min?: number;
+        max?: number;
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        patternMessage?: string;
+    };
+}
+/**
+ * Enhanced card registration options.
+ */
+export interface CardRegistrationOptions {
+    /** Card type identifier (e.g., 'add_to_deal', 'invite_member') */
+    cardType: string;
+    /** Human-readable card title */
+    title?: string;
+    /** Card description */
+    description?: string;
+    /** Schema defining form fields (for auto-generated forms) */
+    schema?: CardFieldSchema[];
+    /** Custom renderer function (overrides schema-based rendering) */
+    renderer?: CardRenderer;
+    /** Theme/styling options */
+    theme?: {
+        variant?: 'default' | 'compact' | 'wide';
+        confirmLabel?: string;
+        cancelLabel?: string;
+    };
+}
+/**
+ * Registered card with metadata.
+ */
+export interface RegisteredCard {
+    cardType: string;
+    options: CardRegistrationOptions;
+    renderer?: CardRenderer;
+}
+/**
+ * Card renderer function signature.
+ * Customers register these to render custom confirmation cards.
+ *
+ * @param container - DOM element to render the card into
+ * @param data - Action data including extracted values from AI
+ * @param callbacks - Callbacks for confirm/cancel actions
+ * @returns Optional cleanup function called when card is unmounted
+ */
+export type CardRenderer = (container: HTMLElement, data: Record<string, unknown>, callbacks: CardCallbacks) => (() => void) | void;
+export interface PillarEvents {
+    'ready': void;
+    'error': Error;
+    'panel:open': void;
+    'panel:close': void;
+    'panel:navigate': {
+        view: string;
+        params?: Record<string, string>;
+    };
+    'tooltip:shown': {
+        tooltipId: string;
+    };
+    'tooltip:hidden': {
+        tooltipId: string;
+    };
+    'tooltip:click': {
+        tooltipId: string;
+    };
+    'article:view': {
+        articleSlug: string;
+    };
+    'search:query': {
+        query: string;
+    };
+    'chat:message': {
+        message: string;
+    };
+    'textSelection:shown': {
+        text: string;
+    };
+    'textSelection:click': {
+        text: string;
+    };
+    'context:change': {
+        context: ProductContext;
+    };
+    'profile:change': {
+        profile: UserProfile;
+    };
+    'action:report': {
+        action: string;
+        metadata?: Record<string, unknown>;
+    };
+    'action:result': {
+        actionName: string;
+        result: unknown;
+    };
+    'task:execute': TaskExecutePayload;
+    'task:complete': {
+        id?: string;
+        name: string;
+        success: boolean;
+        data?: Record<string, unknown>;
+    };
+    'workflow:start': Workflow;
+    'workflow:step:active': {
+        workflow: Workflow;
+        step: WorkflowStep;
+    };
+    'workflow:step:complete': {
+        workflow: Workflow;
+        step: WorkflowStep;
+        success: boolean;
+    };
+    'workflow:step:skip': {
+        workflow: Workflow;
+        step: WorkflowStep;
+    };
+    'workflow:complete': Workflow;
+    'workflow:cancel': Workflow;
+    'plan:start': ExecutionPlan;
+    'plan:step:active': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+    };
+    'plan:step:confirm': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+    };
+    'plan:step:complete': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+        success: boolean;
+    };
+    'plan:step:skip': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+    };
+    'plan:step:retry': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+        retryCount: number;
+    };
+    'plan:step:failed': {
+        plan: ExecutionPlan;
+        step: ExecutionStep;
+        error: Error;
+        canRetry?: boolean;
+    };
+    'plan:updated': ExecutionPlan;
+    'plan:complete': ExecutionPlan;
+    'plan:cancel': ExecutionPlan;
+    'plan:error': {
+        plan: ExecutionPlan;
+        error: Error;
+    };
+    'theme:change': {
+        theme: ResolvedThemeConfig;
+    };
+    'textSelection:change': {
+        enabled: boolean;
+    };
+}
+export declare class EventEmitter {
+    private listeners;
+    on<K extends keyof PillarEvents>(event: K, callback: EventCallback<PillarEvents[K]>): () => void;
+    off<K extends keyof PillarEvents>(event: K, callback: EventCallback<PillarEvents[K]>): void;
+    emit<K extends keyof PillarEvents>(event: K, data?: PillarEvents[K]): void;
+    removeAllListeners(event?: keyof PillarEvents): void;
+}

package/dist/core/plan-executor.d.ts

@@ -0,0 +1,101 @@
+/**
+ * PlanExecutor - Orchestrates execution of multi-step plans.
+ *
+ * Manages the execution lifecycle of server-generated execution plans:
+ * - Receives plans from streaming events
+ * - Executes steps using registered action handlers
+ * - Sends results back to server when needed
+ * - Handles user confirmations and cancellations
+ * - Emits events for UI updates
+ */
+import type { ExecutionPlan } from './plan';
+import type { EventEmitter } from './events';
+import type { MCPClient } from '../api/mcp-client';
+export declare class PlanExecutor {
+    private mcpClient;
+    private events;
+    private siteId;
+    constructor(mcpClient: MCPClient, events: EventEmitter, siteId: string);
+    /**
+     * Receive a new plan and start execution if auto_execute.
+     *
+     * Called when the ReAct agent creates a plan via the create_plan tool.
+     */
+    handlePlanReceived(plan: ExecutionPlan): Promise<void>;
+    /**
+     * Attempt to recover an active plan from localStorage.
+     *
+     * Called during SDK initialization to resume plans after page refresh.
+     * Fetches latest state from server to ensure consistency.
+     *
+     * @returns The recovered plan or null if none found/invalid
+     */
+    recoverPlan(): Promise<ExecutionPlan | null>;
+    /**
+     * Persist the current plan to localStorage.
+     */
+    private persistPlan;
+    /**
+     * User clicks "Start Plan" for plans with auto_execute=false.
+     */
+    startPlan(): Promise<void>;
+    /**
+     * Execute the next ready step.
+     */
+    private executeNextStep;
+    /**
+     * User confirms a step requiring confirmation.
+     *
+     * @param stepId - UUID of the step to confirm
+     * @param modifiedData - Optional modified data from user input
+     */
+    confirmStep(stepId: string, modifiedData?: Record<string, unknown>): Promise<void>;
+    /**
+     * User skips a step.
+     *
+     * @param stepId - UUID of the step to skip
+     */
+    skipStep(stepId: string): Promise<void>;
+    /**
+     * Retry a failed step.
+     *
+     * @param stepId - UUID of the step to retry
+     */
+    retryStep(stepId: string): Promise<void>;
+    /**
+     * Cancel the active plan.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Complete a plan step by action name.
+     *
+     * Used by host apps when a wizard/flow completes (e.g., after user finishes
+     * adding a knowledge source). The step must be in 'awaiting_result' status.
+     *
+     * @param actionName - The action name (e.g., 'add_new_source')
+     * @param success - Whether the action completed successfully
+     * @param data - Optional result data
+     */
+    completeStepByAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Mark a step as done by step ID.
+     *
+     * Called by UI when user clicks "Done" button for a wizard step.
+     * The step must be in 'awaiting_result' status.
+     *
+     * @param stepId - UUID of the step to mark done
+     */
+    markStepDone(stepId: string): Promise<void>;
+    /**
+     * Internal helper to mark a step complete and advance to next.
+     */
+    private markStepComplete;
+    /**
+     * Execute a single step.
+     */
+    private executeStep;
+    /**
+     * Get the current active plan.
+     */
+    getActivePlan(): ExecutionPlan | null;
+}