@pillar-ai/sdk 0.1.8 → 0.1.14

package/dist/core/events.d.ts

@@ -1,10 +1,10 @@
 /**
  * Simple EventEmitter for SDK events
  */
-import type { ResolvedThemeConfig } from './config';
-import type { Context, UserProfile } from './context';
-import type { ExecutionPlan, ExecutionStep } from './plan';
-import type { Workflow, WorkflowStep } from './workflow';
+import type { CompactScanResult } from "../types/dom-scanner";
+import type { ResolvedThemeConfig } from "./config";
+import type { Context, UserProfile } from "./context";
+import type { Workflow, WorkflowStep } from "./workflow";
 export type EventCallback<T = unknown> = (data: T) => void;
 /**
  * Task execution payload - sent when a task button is clicked.
@@ -17,7 +17,7 @@ export interface TaskExecutePayload {
     /** 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';
+    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 */
@@ -32,7 +32,7 @@ export interface CardCallbacks {
     /** 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;
+    onStateChange?: (state: "loading" | "success" | "error", message?: string) => void;
 }
 /**
  * Card field schema definition for declarative card configuration.
@@ -43,7 +43,7 @@ export interface CardFieldSchema {
     /** Display label */
     label: string;
     /** Field type */
-    type: 'text' | 'number' | 'email' | 'select' | 'multiselect' | 'checkbox' | 'textarea' | 'date' | 'hidden';
+    type: "text" | "number" | "email" | "select" | "multiselect" | "checkbox" | "textarea" | "date" | "hidden";
     /** Whether field is required */
     required?: boolean;
     /** Default value */
@@ -83,7 +83,7 @@ export interface CardRegistrationOptions {
     renderer?: CardRenderer;
     /** Theme/styling options */
     theme?: {
-        variant?: 'default' | 'compact' | 'wide';
+        variant?: "default" | "compact" | "wide";
         confirmLabel?: string;
         cancelLabel?: string;
     };
@@ -107,114 +107,99 @@ export interface RegisteredCard {
  */
 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': {
+    ready: void;
+    error: Error;
+    "panel:open": void;
+    "panel:close": void;
+    "panel:navigate": {
         view: string;
         params?: Record<string, string>;
     };
-    'article:view': {
+    "article:view": {
         articleSlug: string;
     };
-    'search:query': {
+    "search:query": {
         query: string;
     };
-    'chat:message': {
+    "chat:message": {
         message: string;
     };
-    'textSelection:shown': {
+    "textSelection:shown": {
         text: string;
     };
-    'textSelection:click': {
+    "textSelection:click": {
         text: string;
     };
-    'context:change': {
+    "context:change": {
         context: Context;
     };
-    'profile:change': {
+    "profile:change": {
         profile: UserProfile;
     };
-    'action:report': {
+    "action:report": {
         action: string;
         metadata?: Record<string, unknown>;
     };
-    'action:result': {
+    "user:identified": {
+        userId: string;
+        profile?: {
+            name?: string;
+            email?: string;
+            metadata?: Record<string, unknown>;
+        };
+    };
+    "user:logout": Record<string, never>;
+    "action:result": {
         actionName: string;
         result: unknown;
+        toolCallId?: string;
     };
-    'task:execute': TaskExecutePayload;
-    'task:complete': {
+    "task:execute": TaskExecutePayload;
+    "task:complete": {
         id?: string;
         name: string;
         success: boolean;
         data?: Record<string, unknown>;
     };
-    'workflow:start': Workflow;
-    'workflow:step:active': {
+    "workflow:start": Workflow;
+    "workflow:step:active": {
         workflow: Workflow;
         step: WorkflowStep;
     };
-    'workflow:step:complete': {
+    "workflow:step:complete": {
         workflow: Workflow;
         step: WorkflowStep;
         success: boolean;
     };
-    'workflow:step:skip': {
+    "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': {
+    "workflow:complete": Workflow;
+    "workflow:cancel": Workflow;
+    "theme:change": {
         theme: ResolvedThemeConfig;
     };
-    'textSelection:change': {
+    "textSelection:change": {
+        enabled: boolean;
+    };
+    "dom:scanned": CompactScanResult;
+    "domScanning:change": {
         enabled: boolean;
     };
-    'sidebar:click': {
+    "suggestions:updated": {
+        suggestions: Array<{
+            id: string;
+            text: string;
+        }>;
+        route: string;
+    };
+    "sidebar:click": {
         tabId: string;
         label: string;
     };
     /** @deprecated Use 'sidebar:click' instead. Will be removed in next major version. */
-    'support:request': {
+    "support:request": {
         tabId: string;
     };
 }

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

@@ -39,6 +39,14 @@ export declare class PlanExecutor {
      * User clicks "Start Plan" for plans with auto_execute=false.
      */
     startPlan(): Promise<void>;
+    /**
+     * Resume execution of a stuck plan.
+     *
+     * This is a fallback method for when auto-execution fails or
+     * the plan gets into an inconsistent state. It manually triggers
+     * execution of the next ready step without requiring server confirmation.
+     */
+    resumeExecution(): Promise<void>;
     /**
      * Execute the next ready step.
      */
@@ -106,12 +114,33 @@ export declare class PlanExecutor {
     markStepDone(stepId: string): Promise<void>;
     /**
      * Internal helper to mark a step complete and advance to next.
+     *
+     * This is called when:
+     * - An inline step completes (via completeInlineStep)
+     * - A task:complete event fires for a step awaiting result (via completeStepByAction)
+     * - User clicks "Done" on a wizard step (via markStepDone)
+     *
+     * It reports the result to the server for step-by-step verification,
+     * then advances to the next step based on the server's decision.
      */
     private markStepComplete;
     /**
      * Execute a single step.
      */
     private executeStep;
+    /**
+     * Report step completion to server and handle the decision.
+     *
+     * This is the core of step-by-step verification:
+     * - Every step reports its result (success or failure)
+     * - Server decides what to do next
+     * - SDK executes the decision
+     */
+    private reportStepComplete;
+    /**
+     * Handle the server's decision after step completion.
+     */
+    private handleServerDecision;
     /**
      * Get the current active plan.
      */

package/dist/core/plan.d.ts

@@ -67,6 +67,12 @@ export interface ExecutionPlan {
     created_at: string | null;
     /** When the plan completed (ISO timestamp) */
     completed_at: string | null;
+    /**
+     * Free-form document explaining the plan's approach, reasoning,
+     * dependencies between steps, and success criteria.
+     * Generated by the LLM when creating the plan.
+     */
+    document?: string;
 }
 /**
  * A single step in an execution plan.

package/dist/hooks/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * React/Preact hooks for the Pillar SDK
+ */
+export { useDebouncedValue } from './useDebouncedValue';
+export { usePillarInstance } from './usePillarInstance';

package/dist/hooks/useDebouncedValue.d.ts

@@ -0,0 +1,22 @@
+/**
+ * useDebouncedValue Hook
+ *
+ * Debounces a value by a specified delay. Useful for preventing
+ * rapid UI updates during streaming text or frequent state changes.
+ */
+/**
+ * Returns a debounced version of the provided value.
+ * The returned value only updates after the specified delay has passed
+ * without the input value changing.
+ *
+ * @param value - The value to debounce
+ * @param delay - Delay in milliseconds before updating (default: 50ms)
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * const debouncedText = useDebouncedValue(rapidlyChangingText, 50);
+ * // debouncedText only updates every 50ms at most
+ * ```
+ */
+export declare function useDebouncedValue<T>(value: T, delay?: number): T;

package/dist/hooks/useInlineCard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * useInlineCard Hook
+ *
+ * Shared hook for rendering inline_ui cards in plan steps.
+ * Consolidates duplicated logic from InlinePlanView and PlanStepItem.
+ */
+import type { RefObject } from 'preact';
+import type { ExecutionStep } from '../core/plan';
+export interface UseInlineCardOptions {
+    /** The execution step to render a card for */
+    step: ExecutionStep;
+    /** Ref to the container element for the card */
+    containerRef: RefObject<HTMLDivElement>;
+    /** Called when the inline card is confirmed with optional data */
+    onConfirm?: (stepId: string, data?: Record<string, unknown>) => void;
+    /** Called when the inline card is cancelled/skipped */
+    onSkip: (stepId: string) => void;
+    /** Component name for debug logging */
+    componentName?: string;
+}
+export interface UseInlineCardResult {
+    /** Whether the inline card should be shown */
+    shouldShow: boolean;
+    /** Whether this step is an inline_ui type */
+    isInlineUI: boolean;
+}
+/**
+ * Hook to manage inline_ui card rendering for plan steps.
+ *
+ * Handles:
+ * - Determining when to show the inline card
+ * - Rendering custom or default confirm cards
+ * - Wiring up confirm/cancel/stateChange callbacks
+ */
+export declare function useInlineCard({ step, containerRef, onConfirm, onSkip, componentName, }: UseInlineCardOptions): UseInlineCardResult;

package/dist/hooks/usePillarInstance.d.ts

@@ -0,0 +1,30 @@
+/**
+ * usePillarInstance Hook
+ *
+ * Provides access to the Pillar singleton instance.
+ * This is a convenience hook for components that need to interact
+ * with the Pillar SDK (e.g., calling plan/workflow methods).
+ *
+ * Note: This returns a stable reference since Pillar is a singleton.
+ * The value may be null if the SDK is not initialized.
+ */
+import Pillar from '../core/Pillar';
+/**
+ * Hook to get the Pillar SDK instance.
+ *
+ * @returns The Pillar instance or null if not initialized
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const pillar = usePillarInstance();
+ *
+ *   const handleClick = () => {
+ *     pillar?.startPlan();
+ *   };
+ *
+ *   return <button onClick={handleClick}>Start</button>;
+ * }
+ * ```
+ */
+export declare function usePillarInstance(): Pillar | null;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * Pillar SDK - Embedded Help for Your Application
+ * Pillar SDK - Cursor for your product
  *
  * @example
  * // Script tag usage
  * <script src="https://cdn.trypillar.com/sdk/pillar.min.js"></script>
  * <script>
  *   Pillar.init({
- *     helpCenter: 'your-help-center',
+ *     productKey: 'your-product-key',
  *   });
  * </script>
  *
@@ -15,16 +15,18 @@
  * import { Pillar } from '@pillar-ai/sdk';
  *
  * await Pillar.init({
- *   helpCenter: 'your-help-center',
+ *   productKey: 'your-product-key',
  * });
  */
-export { Pillar, type PillarState, type ChatContext } from './core/Pillar';
-export { EventEmitter, type PillarEvents, type TaskExecutePayload, type CardRenderer, type CardCallbacks } from './core/events';
-export { type PillarConfig, type ResolvedConfig, type ResolvedPanelConfig, type ResolvedMobileTriggerConfig, type PanelConfig, type EdgeTriggerConfig, type MobileTriggerConfig, type MobileTriggerPosition, type MobileTriggerIcon, type MobileTriggerSize, type UrlParamsConfig, type TextSelectionConfig, type PanelPosition, type PanelMode, type ThemeMode, type ThemeColors, type ThemeConfig, type ResolvedThemeConfig, type SidebarTabConfig, DEFAULT_SIDEBAR_TABS, } from './core/config';
-export { type Context, type UserProfile, type Suggestion, type AssistantContext, } from './core/context';
-export { type PlanStatus, type StepStatus, type ExecutionLocation, type ExecutionPlan, type ExecutionStep, type PlanEvents, } from './core/plan';
-export { defineActions, setClientInfo, getClientInfo, getHandler, getActionDefinition, hasAction, getActionNames, getManifest, clearRegistry, getActionCount, type ActionType, type ActionDataSchema, type ActionDefinition, type ActionDefinitions, type ActionManifest, type ActionManifestEntry, type ClientInfo, type Platform, type SyncActionDefinition, type SyncActionDefinitions, type ActionTypeDataMap, type NavigateActionData, type TriggerActionData, type InlineUIData, type ExternalLinkData, type CopyTextData, type ActionDataType, type ActionNames, type TypedTaskHandler, type TypedOnTask, type TypedPillarMethods, } from './actions';
-export { APIClient, type ArticleSummary, type ChatMessage, type ChatResponse, type ProgressEvent, } from './api/client';
-export { type ChatImage, type ImageUploadResponse, } from './api/mcp-client';
-import { Pillar } from './core/Pillar';
+export { EventEmitter, type CardCallbacks, type CardRenderer, type PillarEvents, type TaskExecutePayload, } from "./core/events";
+export { Pillar, type ChatContext, type PillarState } from "./core/Pillar";
+export { DEFAULT_SIDEBAR_TABS, type DOMScanningConfig, type EdgeTriggerConfig, type InteractionHighlightConfig, type MobileTriggerConfig, type MobileTriggerIcon, type MobileTriggerPosition, type MobileTriggerSize, type PanelConfig, type PanelMode, type PanelPosition, type PillarConfig, type ResolvedConfig, type ResolvedDOMScanningConfig, type ResolvedInteractionHighlightConfig, type ResolvedMobileTriggerConfig, type ResolvedPanelConfig, type ResolvedThemeConfig, type SidebarTabConfig, type TextSelectionConfig, type ThemeColors, type ThemeConfig, type ThemeMode, type UrlParamsConfig, } from "./core/config";
+export { type AssistantContext, type Context, type Suggestion, type UserProfile, } from "./core/context";
+export { clearRegistry, getActionCount, getActionDefinition, getActionNames, getClientInfo, getHandler, getManifest, hasAction, setClientInfo, type ActionDataSchema, type ActionDataType, type ActionDefinition, type ActionDefinitions, type ActionManifest, type ActionManifestEntry, type ActionNames, type ActionType, type ActionTypeDataMap, type ClientInfo, type CopyTextData, type ExternalLinkData, type InlineUIData, type NavigateActionData, type Platform, type SyncActionDefinition, type SyncActionDefinitions, type TriggerActionData, type TypedOnTask, type TypedPillarMethods, type TypedTaskHandler, } from "./actions";
+export { APIClient, type ArticleSummary, type ChatMessage, type ChatResponse, type ProgressEvent, } from "./api/client";
+export { type ActionRequest, type ChatImage, type ImageUploadResponse, } from "./api/mcp-client";
+export { DEFAULT_SCAN_OPTIONS, INTERACTABLE_ROLES, INTERACTABLE_TAGS, SKIP_TAGS, type CompactScanResult, type InteractionType, type ScanOptions, } from "./types/dom-scanner";
+export { buildSelectorFromRef, clearPillarRefs, isInteractable, scanPageDirect, } from "./utils/dom-scanner";
+export { generateContextId, getContextDisplayLabel, isDOMSnapshotContext, isHighlightedTextContext, type DOMSnapshotContext, type GenericContext, type HighlightedTextContext, type ProductContext, type UserContextItem, type UserProfileContext, } from "./types/user-context";
+import { Pillar } from "./core/Pillar";
 export default Pillar;