@pillar-ai/sdk 0.1.13 → 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pillar, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -61,62 +61,61 @@ First, register your product in the [Pillar app](https://app.trypillar.com):
 ```javascript
 import { Pillar } from "@pillar-ai/sdk";
 
-await Pillar.init({
+// 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:
+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
-Pillar.init({
+const pillar = await Pillar.init({
   productKey: "your-product-key",
-  actions: {
-    // Navigation actions
-    go_to_settings: {
-      type: "navigate",
-      label: "Open Settings",
-      description: "Navigate to the settings page",
-      path: "/settings",
-    },
+});
 
-    // Trigger actions that execute code
-    export_to_csv: {
-      type: "trigger",
-      label: "Export to CSV",
-      description: "Export current data to a CSV file",
-    },
+// Handle navigation
+pillar.onTask("go_to_settings", (data) => {
+  router.push("/settings");
+});
 
-    // Actions with data schemas
-    update_preferences: {
-      type: "trigger",
-      label: "Update Preferences",
-      description: "Update notification preferences",
-      dataSchema: {
-        emailAlerts: { type: "boolean" },
-        frequency: { type: "string", enum: ["daily", "weekly", "monthly"] },
-      },
-    },
-  },
+// Handle triggers
+pillar.onTask("export_to_csv", async (data) => {
+  await downloadCSV();
+});
 
-  onTask: (actionName, data) => {
-    // Your code executes here
-    if (actionName === "export_to_csv") {
-      downloadCSV();
-    }
-    if (actionName === "update_preferences") {
-      updateUserPreferences(data.emailAlerts, data.frequency);
-    }
-  },
+// 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({
+const pillar = await Pillar.init({
   productKey: "your-product-key",
 
   panel: {
@@ -141,12 +140,15 @@ Pillar.init({
 
 | Method | Description |
 |--------|-------------|
-| `Pillar.init(config)` | Initialize the SDK with your configuration |
-| `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 |
+| `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 |
+
+> **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()`.
 
 For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference/core).
 

package/dist/actions/types.d.ts

@@ -31,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.
  */
@@ -156,6 +157,18 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
      * @default false
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     *
+     * Each example should have a `description` explaining the scenario
+     * and a `parameters` object matching the `dataSchema`.
+     * Useful for complex schemas where the AI benefits from seeing
+     * what a correct call looks like.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
     /**
      * Handler function executed when the action is triggered.
      *
@@ -169,7 +182,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).
  *
@@ -188,6 +201,10 @@ export interface ActionManifestEntry {
     data_schema?: ActionDataSchema;
     default_data?: Record<string, unknown>;
     required_context?: Record<string, unknown>;
+    parameter_examples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Action manifest - synced to server during CI/CD.
@@ -215,6 +232,11 @@ export interface ActionManifest {
      * Action definitions (without handlers).
      */
     actions: ActionManifestEntry[];
+    /**
+     * Custom agent guidance synced alongside actions.
+     * Injected into the AI agent's prompt as product_guidance.
+     */
+    agentGuidance?: string;
 }
 /**
  * Client info set during SDK initialization.
@@ -269,13 +291,22 @@ export interface SyncActionDefinition<TData = Record<string, unknown>> {
      * If true, the handler's return value is sent back to the agent.
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     * Each example should have a `description` and a `parameters` object
+     * matching the `dataSchema`.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Map of action name to sync definition (no handlers).
  *
  * 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.
@@ -306,6 +337,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.
@@ -313,6 +348,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,21 +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: 'processing' | 'search' | 'search_complete' | 'query' | 'query_complete' | 'query_failed' | 'generating';
-    message?: string;
+    kind: string;
+    id?: string;
+    label?: string;
+    status?: 'active' | 'done' | 'error';
+    text?: string;
+    children?: ProgressChild[];
+    metadata?: Record<string, unknown>;
     progress_id?: string;
-    metadata?: {
-        sources?: Array<{
-            title: string;
-            url: string;
-            score?: number;
-        }>;
-        result_count?: number;
-        query?: string;
-        action_name?: string;
-        no_sources_used?: boolean;
-    };
+    message?: string;
 }
 /**
  * Server-side embed config response.
@@ -69,12 +81,76 @@ export interface ServerEmbedConfig {
         };
     };
 }
+/**
+ * Conversation summary in history list.
+ */
+export interface ConversationSummary {
+    id: string;
+    title: string;
+    startedAt: string | null;
+    lastMessageAt: string | null;
+    messageCount: number;
+}
+/**
+ * Display step in the agent's timeline.
+ * This is a human-readable timeline that includes thinking, tool decisions, and tool results.
+ * Used for UI display of the agent's reasoning process.
+ */
+export interface DisplayStep {
+    step_type: 'thinking' | 'tool_decision' | 'parallel_tool_decision' | 'tool_result' | 'token_summary' | 'step_start' | 'generating' | 'narration';
+    iteration?: number;
+    timestamp_ms?: number;
+    content?: string;
+    tool?: string;
+    tools?: Array<{
+        tool: string;
+        arguments: Record<string, unknown>;
+    }>;
+    arguments?: Record<string, unknown>;
+    success?: boolean;
+    reasoning?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+/**
+ * Message in conversation history.
+ * Contains display-oriented fields for UI rendering.
+ * LLM-native fields (llm_message) are kept server-side for conversation replay.
+ */
+export interface HistoryMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: string | null;
+    display_trace?: DisplayStep[];
+}
+/**
+ * Full conversation with messages.
+ */
+export interface ConversationDetail extends ConversationSummary {
+    messages: HistoryMessage[];
+}
 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.
@@ -110,7 +186,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, assistantMessageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<void>, signal?: AbortSignal, onRequestId?: (requestId: number) => void): Promise<ChatResponse>;
     /**
      * Legacy chat method using the old /ai/chat/ endpoint.
      * @deprecated Use chat() which uses the MCP protocol.
@@ -154,5 +230,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;
 }