@pillar-ai/sdk 0.1.7 → 0.1.13

package/README.md

@@ -1,114 +1,164 @@
 # @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",
-  publicKey: "pk_live_xxx",
+  productKey: "your-product-key", // From Pillar app
 });
 ```
 
-## Configuration
+## Defining Actions
+
+Define what your co-pilot can do. When users make requests, Pillar matches intent to actions and executes them:
 
 ```javascript
 Pillar.init({
-  // Required
-  helpCenter: "your-help-center",
-  publicKey: "pk_live_xxx",
-
-  // Optional configuration
-  config: {
-    // Panel configuration
-    panel: {
-      position: "right", // 'left' | 'right'
-      mode: "push", // 'overlay' | 'push'
+  productKey: "your-product-key",
+  actions: {
+    // Navigation actions
+    go_to_settings: {
+      type: "navigate",
+      label: "Open Settings",
+      description: "Navigate to the settings page",
+      path: "/settings",
     },
 
-    // Edge trigger (sidebar tab that opens the panel)
-    edgeTrigger: {
-      enabled: true, // Set to false to use your own custom button
+    // Trigger actions that execute code
+    export_to_csv: {
+      type: "trigger",
+      label: "Export to CSV",
+      description: "Export current data to a CSV file",
     },
 
-    // Theme
-    theme: {
-      mode: "auto", // 'light' | 'dark' | 'auto'
-      colors: {
-        primary: "#6366f1",
+    // 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"] },
       },
     },
   },
+
+  onTask: (actionName, data) => {
+    // Your code executes here
+    if (actionName === "export_to_csv") {
+      downloadCSV();
+    }
+    if (actionName === "update_preferences") {
+      updateUserPreferences(data.emailAlerts, data.frequency);
+    }
+  },
 });
 ```
 
-## Custom Trigger Button
-
-To use your own button instead of the built-in edge trigger:
+## Configuration
 
 ```javascript
 Pillar.init({
-  helpCenter: "your-help-center",
-  publicKey: "pk_live_xxx",
-  edgeTrigger: { enabled: false },
-});
+  productKey: "your-product-key",
 
-// Then control the panel programmatically
-document.getElementById("my-help-button").addEventListener("click", () => {
-  Pillar.toggle();
-});
-```
+  panel: {
+    position: "right", // 'left' | 'right'
+    mode: "push", // 'overlay' | 'push'
+  },
 
-## Features
+  edgeTrigger: {
+    enabled: true, // Set to false to use your own button
+  },
 
-- **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
+  theme: {
+    mode: "auto", // 'light' | 'dark' | 'auto'
+    colors: {
+      primary: "#6366f1",
+    },
+  },
+});
+```
 
 ## API Reference
 
-### Pillar.init(config)
-
-Initialize the SDK with your configuration.
+| 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.open()
+For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference/core).
 
-Open the help panel.
+## Framework Integrations
 
-### Pillar.close()
+For idiomatic integration with your framework, use our framework-specific packages:
 
-Close the help panel.
-
-### Pillar.toggle()
-
-Toggle the help panel open/closed.
-
-### Pillar.setContext(context)
-
-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'));
  * ```
  */
 /**
@@ -35,6 +41,22 @@ export type ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_acti
  * Supported platforms for action deployments.
  */
 export type Platform = 'web' | 'ios' | 'android' | 'desktop';
+/**
+ * Schema property definition for a single field.
+ * Supports nested objects and arrays with items.
+ */
+export interface ActionDataSchemaProperty {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /** Items schema for array types */
+    items?: ActionDataSchemaProperty;
+    /** Nested properties for object types */
+    properties?: Record<string, ActionDataSchemaProperty>;
+    /** Required fields for nested object types */
+    required?: string[];
+}
 /**
  * JSON Schema definition for action data.
  *
@@ -43,12 +65,7 @@ export type Platform = 'web' | 'ios' | 'android' | 'desktop';
  */
 export interface ActionDataSchema {
     type: 'object';
-    properties: Record<string, {
-        type: 'string' | 'number' | 'boolean' | 'array' | 'object';
-        description?: string;
-        enum?: string[];
-        default?: unknown;
-    }>;
+    properties: Record<string, ActionDataSchemaProperty>;
     required?: string[];
 }
 /**

package/dist/api/client.d.ts

@@ -4,7 +4,7 @@
  */
 import type { TaskButtonData } from '../components/Panel/TaskButton';
 import type { ResolvedConfig } from '../core/config';
-import type { ProductContext, Suggestion, UserProfile } from '../core/context';
+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';
@@ -33,9 +33,20 @@ export interface ChatResponse {
     actions?: TaskButtonData[];
 }
 export interface ProgressEvent {
-    kind: 'search' | 'search_complete' | 'generating' | 'thinking';
+    kind: 'processing' | 'search' | 'search_complete' | 'query' | 'query_complete' | 'query_failed' | 'generating';
     message?: string;
     progress_id?: string;
+    metadata?: {
+        sources?: Array<{
+            title: string;
+            url: string;
+            score?: number;
+        }>;
+        result_count?: number;
+        query?: string;
+        action_name?: string;
+        no_sources_used?: boolean;
+    };
 }
 /**
  * Server-side embed config response.
@@ -135,13 +146,13 @@ export declare class APIClient {
      * Get contextual help suggestions based on product context.
      * Returns relevant articles, videos, and actions.
      */
-    getSuggestions(productContext: ProductContext, userProfile: UserProfile): Promise<Suggestion[]>;
+    getSuggestions(ctx: Context, userProfile: UserProfile): Promise<Suggestion[]>;
     /**
      * Chat with enhanced context.
      * Includes product context and user profile for better responses.
      *
      * Note: Context is passed to the MCP ask tool as additional arguments.
      */
-    chatWithContext(message: string, history: ChatMessage[] | undefined, productContext: ProductContext, userProfile: UserProfile, onChunk?: (chunk: string) => void, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void): Promise<ChatResponse>;
+    chatWithContext(message: string, history: ChatMessage[] | undefined, ctx: Context, userProfile: UserProfile, onChunk?: (chunk: string) => void, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void): Promise<ChatResponse>;
     cancelAllRequests(): void;
 }

package/dist/api/mcp-client.d.ts

@@ -59,10 +59,22 @@ export interface StreamCallbacks {
     onError?: (error: string) => void;
     /** Called when stream is complete */
     onComplete?: (conversationId?: string, queryLogId?: string) => void;
-    /** Called for progress updates */
+    /** Called for progress updates (search, query, generating, etc.) */
     onProgress?: (progress: {
         kind: string;
         message?: string;
+        progress_id?: string;
+        metadata?: {
+            sources?: Array<{
+                title: string;
+                url: string;
+                score?: number;
+            }>;
+            result_count?: number;
+            query?: string;
+            action_name?: string;
+            no_sources_used?: boolean;
+        };
     }) => void;
 }
 /** Image for chat requests (from upload-image endpoint) */

package/dist/cli/sync.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env npx tsx
 export {};