@pillar-ai/sdk 0.1.8 → 0.1.14

package/README.md

@@ -1,42 +1,132 @@
 # @pillar-ai/sdk
 
-Pillar Embedded Help SDK - Add contextual help and AI chat to your application.
+Cursor for your product — Embed an AI co-pilot that executes tasks, not just answers questions.
+
+[![npm version](https://img.shields.io/npm/v/@pillar-ai/sdk)](https://www.npmjs.com/package/@pillar-ai/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@pillar-ai/sdk)](https://www.npmjs.com/package/@pillar-ai/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+
+## What is Pillar?
+
+Pillar is an embedded AI co-pilot that helps users complete tasks, not just answer questions. Users say what they want, and Pillar uses your UI to make it happen — navigating pages, pre-filling forms, and calling your APIs.
+
+**How it works:**
+
+1. User asks: *"Export this to CSV"* or *"Turn off email notifications"*
+2. Pillar understands intent and chains actions
+3. Your code executes with the user's session
+
+## Features
+
+- **Task Execution** — Navigate pages, pre-fill forms, call APIs on behalf of users
+- **Multi-Step Plans** — Chain actions into workflows for complex tasks
+- **Context-Aware** — Knows current page, user state, and selected text
+- **Knowledge Sync** — Trained on your docs, Zendesk, Intercom, and more
+- **Custom Action Cards** — Render interactive UI for confirmations and data input
+- **Framework Bindings** — First-class support for React, Vue, and Svelte
+
+## Why Pillar?
+
+- **Runs client-side** with the user's session — no proxy servers, no token forwarding
+- **One npm install**, define your actions, and you're live
+- **Syncs with your docs** for grounded, accurate answers
+
+## Documentation
+
+**[View Full Documentation](https://trypillar.com/docs)** | [Getting Started](https://trypillar.com/docs/getting-started/quick-start) | [API Reference](https://trypillar.com/docs/reference/core)
 
 ## Installation
 
 ```bash
 npm install @pillar-ai/sdk
+# or
+pnpm add @pillar-ai/sdk
+# or
+yarn add @pillar-ai/sdk
 ```
 
 ## Quick Start
 
+### 1. Get Your Product Key
+
+First, register your product in the [Pillar app](https://app.trypillar.com):
+
+1. Sign up or log in at [app.trypillar.com](https://app.trypillar.com)
+2. Create a new product
+3. Copy your **Product Key** from the settings page
+
+### 2. Initialize the SDK
+
 ```javascript
 import { Pillar } from "@pillar-ai/sdk";
 
-await Pillar.init({
-  helpCenter: "your-help-center",
+// Initialize and get the instance
+const pillar = await Pillar.init({
+  productKey: "your-product-key", // From Pillar app
 });
+
+// Now you can use instance methods
+pillar.setContext({ currentPage: "/dashboard" });
+pillar.open();
+```
+
+You can also get the instance later using `Pillar.getInstance()`:
+
+```javascript
+// Anywhere in your app after init
+const pillar = Pillar.getInstance();
+pillar?.setContext({ currentPage: "/settings" });
 ```
 
+## Defining Actions
+
+Define what your co-pilot can do. When users make requests, Pillar matches intent to actions and executes them.
+
+### Register Task Handlers
+
+Use `onTask` to handle actions when the AI executes them:
+
+```javascript
+const pillar = await Pillar.init({
+  productKey: "your-product-key",
+});
+
+// Handle navigation
+pillar.onTask("go_to_settings", (data) => {
+  router.push("/settings");
+});
+
+// Handle triggers
+pillar.onTask("export_to_csv", async (data) => {
+  await downloadCSV();
+});
+
+// Handle actions with data
+pillar.onTask("update_preferences", (data) => {
+  updateUserPreferences(data.emailAlerts, data.frequency);
+});
+```
+
+### Code-First Action Definitions
+
+For production, define actions in code and sync them via the `pillar-sync` CLI during CI/CD. See [Setting Up Actions](https://trypillar.com/docs/guides/actions) for details.
+
 ## Configuration
 
 ```javascript
-Pillar.init({
-  // Required
-  helpCenter: "your-help-center",
+const pillar = await Pillar.init({
+  productKey: "your-product-key",
 
-  // Optional configuration
   panel: {
     position: "right", // 'left' | 'right'
     mode: "push", // 'overlay' | 'push'
   },
 
-  // Edge trigger (sidebar tab that opens the panel)
   edgeTrigger: {
-    enabled: true, // Set to false to use your own custom button
+    enabled: true, // Set to false to use your own button
   },
 
-  // Theme
   theme: {
     mode: "auto", // 'light' | 'dark' | 'auto'
     colors: {
@@ -46,63 +136,31 @@ Pillar.init({
 });
 ```
 
-## Custom Trigger Button
-
-To use your own button instead of the built-in edge trigger:
-
-```javascript
-Pillar.init({
-  helpCenter: "your-help-center",
-  edgeTrigger: { enabled: false },
-});
-
-// Then control the panel programmatically
-document.getElementById("my-help-button").addEventListener("click", () => {
-  Pillar.toggle();
-});
-```
-
-## Features
-
-- **AI Chat**: Embedded AI assistant that understands your product
-- **Edge Trigger**: Built-in sidebar tab to open the help panel (or use your own button)
-- **Contextual Help**: Show relevant help based on user context
-- **Text Selection**: Allow users to ask questions about selected text
-- **Customizable UI**: Full control over positioning, theming, and behavior
-
 ## API Reference
 
-### Pillar.init(config)
-
-Initialize the SDK with your configuration.
-
-### Pillar.open()
-
-Open the help panel.
-
-### Pillar.close()
+| Method | Description |
+|--------|-------------|
+| `Pillar.init(config)` | Initialize the SDK, returns the instance |
+| `Pillar.getInstance()` | Get the initialized SDK instance |
+| `pillar.open()` | Open the co-pilot panel |
+| `pillar.close()` | Close the co-pilot panel |
+| `pillar.toggle()` | Toggle the co-pilot panel |
+| `pillar.setContext(context)` | Update the user/product context |
+| `pillar.on(event, callback)` | Subscribe to SDK events |
 
-Close the help panel.
+> **Note:** `Pillar.init()` and `Pillar.getInstance()` are static methods on the class. All other methods (lowercase `pillar`) are instance methods - call them on the instance returned from `init()` or `getInstance()`.
 
-### Pillar.toggle()
+For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference/core).
 
-Toggle the help panel open/closed.
+## Framework Integrations
 
-### Pillar.setContext(context)
+For idiomatic integration with your framework, use our framework-specific packages:
 
-Update the user/product context.
-
-### Pillar.on(event, callback)
-
-Subscribe to SDK events.
-
-## React Integration
-
-For React applications, use the `@pillar-ai/react` package for a more idiomatic integration with hooks and components.
-
-```bash
-npm install @pillar-ai/react
-```
+| Framework | Package | Installation |
+|-----------|---------|--------------|
+| React | [@pillar-ai/react](https://github.com/pillarhq/sdk-react) | `npm install @pillar-ai/react` |
+| Vue | [@pillar-ai/vue](https://github.com/pillarhq/sdk-vue) | `npm install @pillar-ai/vue` |
+| Svelte | [@pillar-ai/svelte](https://github.com/pillarhq/sdk-svelte) | `npm install @pillar-ai/svelte` |
 
 ## License
 

package/dist/actions/index.d.ts

@@ -30,4 +30,4 @@
  * @module actions
  */
 export type { ActionType, ActionDataSchema, ActionDefinition, ActionDefinitions, ActionManifest, ActionManifestEntry, ClientInfo, Platform, SyncActionDefinition, SyncActionDefinitions, ActionTypeDataMap, NavigateActionData, TriggerActionData, InlineUIData, ExternalLinkData, CopyTextData, ActionDataType, ActionNames, TypedTaskHandler, TypedOnTask, TypedPillarMethods, } from './types';
-export { defineActions, setClientInfo, getClientInfo, getHandler, getActionDefinition, hasAction, getActionNames, getManifest, clearRegistry, getActionCount, } from './registry';
+export { setClientInfo, getClientInfo, getHandler, getActionDefinition, hasAction, getActionNames, getManifest, clearRegistry, getActionCount, } from './registry';

package/dist/actions/registry.d.ts

@@ -2,45 +2,33 @@
  * Action Registry - Manages code-defined action handlers.
  *
  * This module provides the registration and lookup mechanism for
- * actions defined in code. Actions are registered using `defineActions()`
- * and can be looked up by name using `getHandler()`.
+ * actions defined in code. Actions are registered at runtime via
+ * `pillar.onTask()` and can be looked up by name using `getHandler()`.
  *
- * The registry also generates the manifest that gets synced to the server
- * during CI/CD builds.
- */
-import type { ActionDefinition, ActionDefinitions, ActionManifest, ClientInfo, Platform } from './types';
-/**
- * Define and register actions with the SDK.
- *
- * Call this during app initialization to register your action handlers.
- * The metadata will be synced to the server during CI/CD builds.
+ * Action metadata is synced to the server during CI/CD builds using
+ * the `pillar-sync` CLI with a barrel file export pattern:
  *
  * @example
  * ```ts
- * import { defineActions } from '@pillar-ai/sdk/actions';
- * import { router } from './router';
+ * // lib/pillar/actions/index.ts
+ * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
  *
- * export const actions = defineActions({
+ * export const actions = {
  *   open_settings: {
  *     description: 'Navigate to the settings page',
- *     type: 'navigate',
+ *     type: 'navigate' as const,
  *     path: '/settings',
- *     handler: () => router.push('/settings'),
- *   },
- *   open_billing: {
- *     description: 'Navigate to billing and subscription management',
- *     type: 'navigate',
- *     path: '/settings/billing',
  *     autoRun: true,
- *     handler: (data) => router.push('/settings/billing', data),
  *   },
- * });
- * ```
+ * } as const satisfies SyncActionDefinitions;
+ *
+ * export default actions;
  *
- * @param actions - Map of action name to definition
- * @returns The same actions object (for re-export convenience)
+ * // Sync via CI/CD:
+ * // npx pillar-sync --actions ./lib/pillar/actions/index.ts
+ * ```
  */
-export declare function defineActions<T extends ActionDefinitions>(actions: T): T;
+import type { ActionDefinition, ActionManifest, ClientInfo, Platform } from './types';
 /**
  * Set client platform and version info.
  *

package/dist/actions/types.d.ts

@@ -6,16 +6,22 @@
  *
  * @example
  * ```ts
- * import { defineActions } from '@pillar-ai/sdk/actions';
+ * // lib/pillar/actions/index.ts
+ * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
  *
- * const actions = defineActions({
+ * export const actions = {
  *   open_settings: {
  *     description: 'Navigate to the settings page',
- *     type: 'navigate',
+ *     type: 'navigate' as const,
  *     path: '/settings',
- *     handler: () => router.push('/settings'),
+ *     autoRun: true,
  *   },
- * });
+ * } as const satisfies SyncActionDefinitions;
+ *
+ * export default actions;
+ *
+ * // Sync via CI/CD: npx pillar-sync --actions ./lib/pillar/actions/index.ts
+ * // Register handlers at runtime: pillar.onTask('open_settings', () => router.push('/settings'));
  * ```
  */
 /**
@@ -25,12 +31,13 @@
  * - open_modal: Open a modal or dialog
  * - fill_form: Fill form fields with data
  * - trigger_action: Trigger a custom action
+ * - query: Fetch data from the client and return to the agent (implies returns: true)
  * - copy_text: Copy text to clipboard
  * - external_link: Open an external URL
  * - start_tutorial: Start a tutorial/walkthrough
  * - inline_ui: Display inline UI card in chat
  */
-export type ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+export type ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
 /**
  * Supported platforms for action deployments.
  */
@@ -163,7 +170,7 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
  *
  * Action names should be snake_case identifiers.
  */
-export type ActionDefinitions = Record<string, ActionDefinition<any>>;
+export type ActionDefinitions = Record<string, ActionDefinition<unknown>>;
 /**
  * Metadata for a single action in the manifest (no handler).
  *
@@ -269,7 +276,7 @@ export interface SyncActionDefinition<TData = Record<string, unknown>> {
  *
  * Use this type for your actions file that gets synced via CI/CD.
  */
-export type SyncActionDefinitions = Record<string, SyncActionDefinition<any>>;
+export type SyncActionDefinitions = Record<string, SyncActionDefinition<unknown>>;
 /**
  * Base data types for each action type.
  * These are automatically inferred from the action's `type` field.
@@ -300,6 +307,10 @@ export interface CopyTextData {
     /** Text to copy to clipboard */
     text?: string;
 }
+export interface QueryActionData {
+    /** Query parameters passed to the handler */
+    [key: string]: unknown;
+}
 /**
  * Maps action types to their default data shapes.
  * Used for automatic type inference in onTask handlers.
@@ -307,6 +318,7 @@ export interface CopyTextData {
 export interface ActionTypeDataMap {
     navigate: NavigateActionData;
     trigger_action: TriggerActionData;
+    query: QueryActionData;
     inline_ui: InlineUIData;
     external_link: ExternalLinkData;
     copy_text: CopyTextData;

package/dist/api/client.d.ts

@@ -5,10 +5,10 @@
 import type { TaskButtonData } from '../components/Panel/TaskButton';
 import type { ResolvedConfig } from '../core/config';
 import type { Context, Suggestion, UserProfile } from '../core/context';
-import type { ExecutionPlan } from '../core/plan';
 import type { Workflow } from '../core/workflow';
 import type { UserContextItem } from '../types/user-context';
-import type { ChatImage, ImageUploadResponse } from './mcp-client';
+import type { ActionRequest, ChatImage, ImageUploadResponse } from './mcp-client';
+import { MCPClient } from './mcp-client';
 export interface ArticleSummary {
     id: string;
     title: string;
@@ -23,6 +23,8 @@ export interface ChatMessage {
 export interface SuggestedQuestion {
     id: string;
     text: string;
+    /** If true, this is an admin-configured suggestion that should rank first */
+    manual?: boolean;
 }
 export interface ChatResponse {
     message: string;
@@ -32,10 +34,31 @@ export interface ChatResponse {
     messageId?: string;
     actions?: TaskButtonData[];
 }
+/**
+ * Child item within a progress event (e.g., search source, plan step).
+ */
+export interface ProgressChild {
+    id: string;
+    label: string;
+    url?: string;
+}
+/**
+ * Progress event for tracking AI response generation steps.
+ * Uses a generic design where the server controls display text via `label`.
+ *
+ * The new schema uses `id` and `status` fields. Legacy fields are kept
+ * for backwards compatibility with older backend versions.
+ */
 export interface ProgressEvent {
-    kind: 'search' | 'search_complete' | 'generating' | 'thinking';
-    message?: string;
+    kind: string;
+    id?: string;
+    label?: string;
+    status?: 'active' | 'done' | 'error';
+    text?: string;
+    children?: ProgressChild[];
+    metadata?: Record<string, unknown>;
     progress_id?: string;
+    message?: string;
 }
 /**
  * Server-side embed config response.
@@ -58,12 +81,48 @@ export interface ServerEmbedConfig {
         };
     };
 }
+/**
+ * Conversation summary in history list.
+ */
+export interface ConversationSummary {
+    id: string;
+    title: string;
+    startedAt: string | null;
+    lastMessageAt: string | null;
+    messageCount: number;
+}
+/**
+ * Full conversation with messages.
+ */
+export interface ConversationDetail extends ConversationSummary {
+    messages: Array<{
+        id: string;
+        role: 'user' | 'assistant';
+        content: string;
+        timestamp: string | null;
+    }>;
+}
 export declare class APIClient {
     private config;
     private abortControllers;
     private mcpClient;
+    private _externalUserId;
     constructor(config: ResolvedConfig);
+    /**
+     * Get the underlying MCP client.
+     * Used by Pillar for direct MCP operations like sendActionResult.
+     */
+    get mcp(): MCPClient;
     private get baseUrl();
+    /**
+     * Set the external user ID for authenticated users.
+     * This ID will be included in all subsequent requests.
+     */
+    setExternalUserId(userId: string): void;
+    /**
+     * Clear the external user ID (for logout).
+     */
+    clearExternalUserId(): void;
     /**
      * Get or create a persistent visitor ID.
      * Stored in localStorage to persist across sessions.
@@ -99,7 +158,7 @@ export declare class APIClient {
      * @returns Promise with signed URL and expiration
      */
     uploadImage(file: File): Promise<ImageUploadResponse>;
-    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, onPlan?: (plan: ExecutionPlan) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void): Promise<ChatResponse>;
+    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void, onConversationStarted?: (conversationId: string, messageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<void>): Promise<ChatResponse>;
     /**
      * Legacy chat method using the old /ai/chat/ endpoint.
      * @deprecated Use chat() which uses the MCP protocol.
@@ -143,5 +202,32 @@ export declare class APIClient {
      * Note: Context is passed to the MCP ask tool as additional arguments.
      */
     chatWithContext(message: string, history: ChatMessage[] | undefined, ctx: Context, userProfile: UserProfile, onChunk?: (chunk: string) => void, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void): Promise<ChatResponse>;
+    /**
+     * Identify the current user after login.
+     * Links the anonymous visitor to the authenticated user ID, enabling
+     * cross-device conversation history.
+     *
+     * @param userId - Client's authenticated user ID
+     * @param profile - Optional user profile data
+     */
+    identify(userId: string, profile?: {
+        name?: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * List past conversations for the current visitor.
+     *
+     * @param limit - Max number of conversations to return (default: 20, max: 50)
+     * @returns List of conversation summaries
+     */
+    listConversations(limit?: number): Promise<ConversationSummary[]>;
+    /**
+     * Get a single conversation with all messages.
+     *
+     * @param conversationId - UUID of the conversation
+     * @returns Conversation with messages
+     */
+    getConversation(conversationId: string): Promise<ConversationDetail | null>;
     cancelAllRequests(): void;
 }