@pillar-ai/sdk 0.1.8 → 0.1.13

package/README.md

@@ -1,20 +1,115 @@
 # @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",
+  productKey: "your-product-key", // From Pillar app
+});
+```
+
+## Defining Actions
+
+Define what your co-pilot can do. When users make requests, Pillar matches intent to actions and executes them:
+
+```javascript
+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",
+    },
+
+    // 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);
+    }
+  },
 });
 ```
 
@@ -22,21 +117,17 @@ await Pillar.init({
 
 ```javascript
 Pillar.init({
-  // Required
-  helpCenter: "your-help-center",
+  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 +137,28 @@ 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()
-
-Close the help panel.
-
-### Pillar.toggle()
+| 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 |
 
-Toggle the help panel open/closed.
+For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference/core).
 
-### Pillar.setContext(context)
+## Framework Integrations
 
-Update the user/product context.
+For idiomatic integration with your framework, use our framework-specific packages:
 
-### 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'));
  * ```
  */
 /**

package/dist/api/client.d.ts

@@ -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.

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 node
 export {};

package/dist/cli/sync.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 
 // src/cli/sync.ts
 import * as fs from "fs";
@@ -59,6 +58,43 @@ async function loadActions(actionsPath) {
   if (!fs.existsSync(absolutePath)) {
     throw new Error(`Actions file not found: ${absolutePath}`);
   }
+  const isTypeScript = absolutePath.endsWith(".ts") || absolutePath.endsWith(".tsx");
+  if (isTypeScript) {
+    try {
+      const tempDir = path.dirname(absolutePath);
+      const tempFile = path.join(tempDir, `.pillar-sync-temp-${Date.now()}.mjs`);
+      const importPath = absolutePath.replace(/\\/g, "/");
+      const extractScript = `import actions from '${importPath}';
+const result = actions.default || actions;
+console.log(JSON.stringify(result));`;
+      fs.writeFileSync(tempFile, extractScript, "utf-8");
+      try {
+        const result = execSync(`npx tsx "${tempFile}"`, {
+          encoding: "utf-8",
+          cwd: process.cwd(),
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        const actions = JSON.parse(result.trim());
+        if (!actions || typeof actions !== "object") {
+          throw new Error(
+            'Actions file must export an actions object as default or named export "actions"'
+          );
+        }
+        return actions;
+      } finally {
+        if (fs.existsSync(tempFile)) {
+          fs.unlinkSync(tempFile);
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("tsx")) {
+        console.error("[pillar-sync] TypeScript files require tsx.");
+        console.error("[pillar-sync] Make sure tsx is installed: npm install -D tsx");
+        console.error("[pillar-sync] Then run: npx pillar-sync --actions ./actions.ts");
+      }
+      throw error;
+    }
+  }
   const fileUrl = pathToFileURL(absolutePath).href;
   try {
     const module = await import(fileUrl);
@@ -70,11 +106,6 @@ async function loadActions(actionsPath) {
     }
     return actions;
   } catch (error) {
-    if (error instanceof Error && error.message.includes("Unknown file extension")) {
-      console.error("[pillar-sync] TypeScript files require tsx.");
-      console.error("[pillar-sync] Make sure tsx is installed: npm install -D tsx");
-      console.error("[pillar-sync] Then run: npx pillar-sync --actions ./actions.ts");
-    }
     throw error;
   }
 }

package/dist/components/Panel/Panel.d.ts

@@ -38,6 +38,7 @@ export declare class Panel {
      */
     open(options?: {
         view?: string;
+        search?: string;
         focusInput?: boolean;
     }): void;
     /**