@pillar-ai/sdk 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # @pillar-ai/sdk
 
-Pillar Embedded Help SDK - Add contextual help, tooltips, and AI chat to your application.
+Pillar Embedded Help SDK - Add contextual help and AI chat to your application.
 
 ## Installation
 
@@ -10,36 +10,11 @@ npm install @pillar-ai/sdk
 
 ## Quick Start
 
-### Script Tag (CDN)
-
-```html
-<script src="https://cdn.trypillar.com/sdk/pillar.min.js"></script>
-<script>
-  Pillar.init({
-    helpCenter: 'your-help-center',
-    publicKey: 'pk_live_xxx',
-  });
-</script>
-```
-
-Or with auto-initialization via data attributes:
-
-```html
-<script
-  src="https://cdn.trypillar.com/sdk/pillar.min.js"
-  data-help-center="your-help-center"
-  data-public-key="pk_live_xxx"
-></script>
-```
-
-### ES Modules
-
 ```javascript
-import { Pillar } from '@pillar-ai/sdk';
+import { Pillar } from "@pillar-ai/sdk";
 
 await Pillar.init({
-  helpCenter: 'your-help-center',
-  publicKey: 'pk_live_xxx',
+  helpCenter: "your-help-center",
 });
 ```
 
@@ -48,45 +23,50 @@ await Pillar.init({
 ```javascript
 Pillar.init({
   // Required
-  helpCenter: 'your-help-center',
-  publicKey: 'pk_live_xxx',
+  helpCenter: "your-help-center",
 
   // Optional configuration
-  config: {
-    // Panel configuration
-    panel: {
-      position: 'right', // 'left' | 'right'
-      mode: 'overlay', // 'overlay' | 'push'
-    },
-
-    // Floating button
-    floatingButton: {
-      enabled: true,
-      position: 'bottom-right',
-    },
+  panel: {
+    position: "right", // 'left' | 'right'
+    mode: "push", // 'overlay' | 'push'
+  },
 
-    // Tooltips
-    tooltips: {
-      enabled: true,
-      trigger: 'hover', // 'hover' | 'click'
-    },
+  // Edge trigger (sidebar tab that opens the panel)
+  edgeTrigger: {
+    enabled: true, // Set to false to use your own custom button
+  },
 
-    // Theme
-    theme: {
-      mode: 'system', // 'light' | 'dark' | 'system'
-      colors: {
-        primary: '#6366f1',
-      },
+  // Theme
+  theme: {
+    mode: "auto", // 'light' | 'dark' | 'auto'
+    colors: {
+      primary: "#6366f1",
     },
   },
 });
 ```
 
+## 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
-- **Tooltips**: Attach interactive tooltips to any element
 - **Text Selection**: Allow users to ask questions about selected text
 - **Customizable UI**: Full control over positioning, theming, and behavior
 

package/dist/actions/types.d.ts

@@ -35,6 +35,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 +59,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';
@@ -52,17 +52,6 @@ export interface ServerEmbedConfig {
         position?: string;
         label?: string;
     };
-    features?: {
-        aiChatEnabled?: boolean;
-        searchEnabled?: boolean;
-        tooltipsEnabled?: boolean;
-    };
-    sidebarTabs?: Array<{
-        id: string;
-        label: string;
-        enabled: boolean;
-        order: number;
-    }>;
     theme?: {
         colors?: {
             primary?: string;
@@ -146,13 +135,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/cli/sync.d.ts

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

package/dist/cli/sync.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/cli/sync.ts
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { pathToFileURL } from "url";
+var DEFAULT_API_URL = "https://help-api.trypillar.com";
+var LOCAL_API_URL = "http://localhost:8003";
+function parseArgs(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        result[key] = nextArg;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    }
+  }
+  return result;
+}
+function printUsage() {
+  console.log(`
+Pillar Action Sync CLI
+
+Usage:
+  npx pillar-sync --actions <path> [--local]
+
+Arguments:
+  --actions <path>   Path to your actions definition file (required)
+                     Supports .ts, .js, .mjs files
+  --local            Use localhost:8003 as the API URL (for local development)
+  --help             Show this help message
+
+Environment Variables:
+  PILLAR_SLUG        Your help center slug (required)
+  PILLAR_SECRET      Secret token for authentication (required)
+  PILLAR_API_URL     API URL (default: https://help-api.trypillar.com)
+  PILLAR_PLATFORM    Platform: web, ios, android, desktop (default: web)
+  PILLAR_VERSION     App version (default: from package.json)
+  GIT_SHA            Git commit SHA for traceability
+
+Examples:
+  # Production
+  PILLAR_SLUG=my-app PILLAR_SECRET=xxx npx pillar-sync --actions ./lib/actions.ts
+
+  # Local development
+  PILLAR_SLUG=my-app PILLAR_SECRET=xxx npx pillar-sync --actions ./lib/actions.ts --local
+`);
+}
+async function loadActions(actionsPath) {
+  const absolutePath = path.resolve(process.cwd(), actionsPath);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Actions file not found: ${absolutePath}`);
+  }
+  const fileUrl = pathToFileURL(absolutePath).href;
+  try {
+    const module = await import(fileUrl);
+    const actions = module.default || module.actions;
+    if (!actions || typeof actions !== "object") {
+      throw new Error(
+        'Actions file must export an actions object as default or named export "actions"'
+      );
+    }
+    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;
+  }
+}
+function buildManifest(actions, platform, version, gitSha) {
+  const entries = [];
+  for (const [name, definition] of Object.entries(actions)) {
+    const entry = {
+      name,
+      description: definition.description,
+      type: definition.type
+    };
+    if (definition.examples?.length)
+      entry.examples = definition.examples;
+    if (definition.path)
+      entry.path = definition.path;
+    if (definition.externalUrl)
+      entry.external_url = definition.externalUrl;
+    if (definition.autoRun)
+      entry.auto_run = definition.autoRun;
+    if (definition.autoComplete)
+      entry.auto_complete = definition.autoComplete;
+    if (definition.returns)
+      entry.returns_data = definition.returns;
+    if (definition.dataSchema)
+      entry.data_schema = definition.dataSchema;
+    if (definition.defaultData)
+      entry.default_data = definition.defaultData;
+    if (definition.requiredContext)
+      entry.required_context = definition.requiredContext;
+    entries.push(entry);
+  }
+  return {
+    platform,
+    version,
+    gitSha,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    actions: entries
+  };
+}
+async function pollStatus(statusUrl, secret, maxWaitSeconds = 300) {
+  const startTime = Date.now();
+  let lastProgress = { processed: 0, total: 0 };
+  while (true) {
+    try {
+      const response = await fetch(statusUrl, {
+        headers: {
+          "X-Pillar-Secret": secret
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Status check failed: ${response.status} ${response.statusText}`);
+      }
+      const status = await response.json();
+      if (status.progress && (status.progress.processed !== lastProgress.processed || status.progress.total !== lastProgress.total)) {
+        const { processed, total, created, updated, deleted } = status.progress;
+        const percent = total > 0 ? Math.round(processed / total * 100) : 0;
+        console.log(
+          `[pillar-sync] Progress: ${processed}/${total} (${percent}%) - Created: ${created}, Updated: ${updated}, Deleted: ${deleted}`
+        );
+        lastProgress = { processed, total };
+      }
+      if (status.status === "completed" && status.is_complete) {
+        console.log(`[pillar-sync] \u2713 Sync completed successfully`);
+        if (status.deployment_id) {
+          console.log(`[pillar-sync]   Deployment: ${status.deployment_id}`);
+        }
+        return;
+      }
+      if (status.status === "failed") {
+        throw new Error(status.error || "Sync job failed");
+      }
+      const elapsed = (Date.now() - startTime) / 1e3;
+      if (elapsed > maxWaitSeconds) {
+        throw new Error(`Timeout after ${maxWaitSeconds} seconds`);
+      }
+      await sleep(2e3);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Timeout")) {
+        throw error;
+      }
+      console.error(`[pillar-sync] Poll error: ${error}`);
+      await sleep(2e3);
+    }
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function getPackageVersion() {
+  try {
+    const pkgPath = path.join(process.cwd(), "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function getGitSha() {
+  try {
+    return execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim().slice(0, 7);
+  } catch {
+    return void 0;
+  }
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+  const actionsPath = args.actions;
+  if (!actionsPath) {
+    console.error("[pillar-sync] Missing required --actions argument");
+    console.error("");
+    printUsage();
+    process.exit(1);
+  }
+  const isLocal = args.local === true;
+  const apiUrl = isLocal ? LOCAL_API_URL : process.env.PILLAR_API_URL || DEFAULT_API_URL;
+  const slug = process.env.PILLAR_SLUG;
+  const secret = process.env.PILLAR_SECRET;
+  if (isLocal) {
+    console.log(`[pillar-sync] Using local API: ${LOCAL_API_URL}`);
+  }
+  if (!slug || !secret) {
+    console.error("[pillar-sync] Missing required environment variables:");
+    if (!slug)
+      console.error("  - PILLAR_SLUG");
+    if (!secret)
+      console.error("  - PILLAR_SECRET");
+    console.error("");
+    console.error("Get these from the Pillar admin: Actions \u2192 Configure Sync");
+    process.exit(1);
+  }
+  console.log(`[pillar-sync] Loading actions from: ${actionsPath}`);
+  let actions;
+  try {
+    actions = await loadActions(actionsPath);
+  } catch (error) {
+    console.error(`[pillar-sync] Failed to load actions:`, error);
+    process.exit(1);
+  }
+  const actionCount = Object.keys(actions).length;
+  console.log(`[pillar-sync] Found ${actionCount} actions`);
+  if (actionCount === 0) {
+    console.warn("[pillar-sync] No actions found. Nothing to sync.");
+    process.exit(0);
+  }
+  const platform = process.env.PILLAR_PLATFORM || "web";
+  const version = process.env.PILLAR_VERSION || getPackageVersion();
+  const gitSha = process.env.GIT_SHA || getGitSha();
+  console.log(`[pillar-sync] Platform: ${platform}`);
+  console.log(`[pillar-sync] Version: ${version}`);
+  console.log(`[pillar-sync] Git SHA: ${gitSha || "not available"}`);
+  const manifest = buildManifest(actions, platform, version, gitSha);
+  if (process.env.PILLAR_DEBUG) {
+    const manifestPath = path.join(process.cwd(), "actions-manifest.json");
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`[pillar-sync] Wrote manifest to ${manifestPath}`);
+  }
+  console.log(`[pillar-sync] Help Center: ${slug}`);
+  const requestBody = {
+    platform: manifest.platform,
+    version: manifest.version,
+    git_sha: gitSha,
+    actions: manifest.actions
+  };
+  const syncUrl = `${apiUrl}/api/admin/configs/${slug}/actions/sync/?async=true`;
+  console.log(`[pillar-sync] POST ${syncUrl}`);
+  try {
+    const response = await fetch(syncUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Pillar-Secret": secret
+      },
+      body: JSON.stringify(requestBody)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error(`[pillar-sync] Sync failed: ${response.status} ${response.statusText}`);
+      console.error(`[pillar-sync] Response: ${errorText}`);
+      process.exit(1);
+    }
+    const result = await response.json();
+    if (result.status === "unchanged") {
+      console.log(`[pillar-sync] \u2713 Manifest unchanged (deployment ${result.deployment_id})`);
+      return;
+    }
+    if (result.status === "accepted" && result.job_id && result.status_url) {
+      console.log(`[pillar-sync] \u2713 Job accepted (job ${result.job_id})`);
+      console.log(`[pillar-sync] Polling for completion...`);
+      const statusUrl = result.status_url.startsWith("http") ? result.status_url : `${apiUrl}${result.status_url}`;
+      await pollStatus(statusUrl, secret);
+      return;
+    }
+    if (result.status === "created") {
+      console.log(`[pillar-sync] \u2713 Created deployment ${result.deployment_id}`);
+      console.log(`[pillar-sync]   Actions: ${result.actions_count}`);
+      console.log(
+        `[pillar-sync]   Created: ${result.created}, Updated: ${result.updated}, Deleted: ${result.deleted || 0}`
+      );
+    }
+  } catch (error) {
+    console.error("[pillar-sync] Sync failed:", error);
+    process.exit(1);
+  }
+}
+main();

package/dist/components/Button/EdgeTrigger.d.ts

@@ -3,13 +3,16 @@
  * A sidebar-style trigger that reserves space in the layout and slides out with the panel.
  * The trigger stays visible when panel opens, positioned at the panel's outer edge.
  */
-import type { FloatingButtonPosition, ResolvedConfig } from "../../core/config";
+import type { ResolvedConfig } from "../../core/config";
+import type { EventEmitter } from "../../core/events";
+export type EdgeTriggerPosition = "left" | "right";
 /**
  * EdgeTrigger class that manages the edge trigger lifecycle
  * The trigger stays visible when panel opens, sliding out with it
  */
 export declare class EdgeTrigger {
     private config;
+    private events;
     private onClick;
     private rootContainer;
     private container;
@@ -19,16 +22,18 @@ export declare class EdgeTrigger {
     private unsubscribeOpen;
     private unsubscribeWidth;
     private unsubscribeHoverMode;
+    private unsubscribeMobileMode;
     private unsubscribeActiveTab;
     private themeObserver;
     private currentTheme;
-    constructor(config: ResolvedConfig, onClick: () => void, rootContainer?: HTMLElement | null);
+    constructor(config: ResolvedConfig, events: EventEmitter, onClick: () => void, rootContainer?: HTMLElement | null);
     /**
      * Handle tab click - sets active tab and opens panel
+     * For non-assistant tabs, emits event for customer's code to handle (e.g., Intercom, Zendesk)
      */
     private handleTabClick;
     /**
-     * Get position as 'left' or 'right' from the floating button position config
+     * Get position as 'left' or 'right' from the panel position config
      */
     private getEdgePosition;
     /**
@@ -65,11 +70,7 @@ export declare class EdgeTrigger {
     /**
      * Update trigger position
      */
-    setPosition(position: FloatingButtonPosition): void;
-    /**
-     * Update trigger label
-     */
-    setLabel(label: string): void;
+    setPosition(position: EdgeTriggerPosition): void;
     /**
      * Destroy the trigger
      */

package/dist/components/Button/MobileTrigger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mobile Trigger Component
+ * A floating action button (FAB) that appears on small screens when the edge trigger is hidden.
+ * Provides a way to open the help panel on mobile devices.
+ */
+import type { ResolvedConfig } from "../../core/config";
+import type { EventEmitter } from "../../core/events";
+/**
+ * MobileTrigger class that manages the mobile floating button lifecycle
+ * The trigger appears on small screens when the viewport is below mobileBreakpoint
+ */
+export declare class MobileTrigger {
+    private config;
+    private events;
+    private onClick;
+    private rootContainer;
+    private container;
+    private stylesInjected;
+    private _isEnabled;
+    private unsubscribeMobileMode;
+    private unsubscribeOpen;
+    constructor(config: ResolvedConfig, events: EventEmitter, onClick: () => void, rootContainer?: HTMLElement | null);
+    /**
+     * Get the resolved size in pixels
+     */
+    private getSize;
+    /**
+     * Get the icon SVG string
+     */
+    private getIcon;
+    /**
+     * Get the background color (use theme primary as default)
+     */
+    private getBackgroundColor;
+    /**
+     * Initialize the mobile trigger
+     */
+    init(): void;
+    /**
+     * Show the trigger (enable it)
+     */
+    show(): void;
+    /**
+     * Hide the trigger (disable it)
+     */
+    hide(): void;
+    /**
+     * Check if the trigger is currently visible
+     */
+    get isVisible(): boolean;
+    /**
+     * Destroy the trigger
+     */
+    destroy(): void;
+    private render;
+}

package/dist/components/Button/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Button Components Index
  */
-export { FloatingButton } from './FloatingButton';
-export { EdgeTrigger } from './EdgeTrigger';
+export { EdgeTrigger, type EdgeTriggerPosition } from './EdgeTrigger';
+export { MobileTrigger } from './MobileTrigger';