@pillar-ai/sdk 0.1.28 → 0.1.30

package/dist/store/suggestions.d.ts

@@ -23,7 +23,7 @@ export declare const hasSuggestions: import("@preact/signals-core").ReadonlySign
 export declare const hasPool: import("@preact/signals-core").ReadonlySignal<boolean>;
 /**
  * Sort suggestions by relevance to the current page.
- * Uses keyword matching between page context and suggestion text.
+ * First filters by path pattern, then scores by keyword matching.
  *
  * @param pool - Full pool of suggestions from backend
  * @param pathname - Current page pathname (e.g., '/dashboards/new')

package/dist/store/tooltips.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tooltips Store
+ * Signal-based state for tooltip visibility and data
+ */
+import type { TooltipData } from '../api/client';
+export interface TooltipInstance {
+    id: string;
+    data: TooltipData;
+    anchor: HTMLElement;
+    isVisible: boolean;
+}
+export declare const tooltips: import("@preact/signals-core").Signal<Map<string, TooltipInstance>>;
+export declare const visibleTooltipId: import("@preact/signals-core").Signal<string | null>;
+export declare const visibleTooltip: import("@preact/signals-core").ReadonlySignal<TooltipInstance | null>;
+export declare const tooltipCount: import("@preact/signals-core").ReadonlySignal<number>;
+export declare const registerTooltip: (id: string, data: TooltipData, anchor: HTMLElement) => void;
+export declare const unregisterTooltip: (id: string) => void;
+export declare const showTooltip: (id: string) => void;
+export declare const hideTooltip: (id: string) => void;
+export declare const hideAllTooltips: () => void;
+export declare const resetTooltips: () => void;

package/dist/tools/types.d.ts

@@ -491,19 +491,18 @@ export interface ToolExecuteResult {
  * @example
  * ```ts
  * pillar.defineTool({
- *   name: 'add_to_cart',
- *   description: 'Add a product to the shopping cart',
- *   inputSchema: {
+ *   name: 'get_signing_secret',
+ *   description: 'Retrieve the webhook signing secret',
+ *   outputSchema: {
  *     type: 'object',
  *     properties: {
- *       productId: { type: 'string', description: 'Product ID' },
- *       quantity: { type: 'number', description: 'Quantity to add' },
+ *       signing_secret: { type: 'string', sensitive: true },
+ *       algorithm: { type: 'string' },
  *     },
- *     required: ['productId', 'quantity'],
  *   },
- *   execute: async ({ productId, quantity }) => {
- *     await cartApi.add(productId, quantity);
- *     return { content: [{ type: 'text', text: 'Added to cart' }] };
+ *   execute: async () => {
+ *     const secret = await api.getSigningSecret();
+ *     return { signing_secret: secret.value, algorithm: 'HMAC-SHA256' };
  *   },
  * });
  * ```
@@ -563,15 +562,31 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * @default true
      */
     autoComplete?: boolean;
+    /**
+     * Context required for this tool to be available.
+     *
+     * When set, the tool is only offered to users whose current context
+     * (set via `pillar.setContext()`) matches every key/value pair.
+     *
+     * @example { userRole: 'admin' }
+     * @example { plan: 'enterprise', betaAccess: true }
+     */
+    requiredContext?: Record<string, unknown>;
     /**
      * Handler function executed when the AI invokes this tool.
      *
-     * Can return:
-     * - A `ToolExecuteResult` with MCP-style content blocks
-     * - A plain object (SDK normalizes it for the agent)
-     * - `void` if the tool has no return value
+     * Return a plain object matching the `outputSchema`. The SDK sends
+     * it directly to the backend with no wrapping — what you return is
+     * what the agent sees.
+     *
+     * To signal failure, throw an error. The SDK catches it and sends
+     * `{ success: false, error: message }` to the agent automatically.
+     *
+     * For backward compatibility the SDK also accepts the legacy
+     * `{ success, data }` envelope and unwraps it, but new tools should
+     * return flat data.
      */
-    execute: (input: TInput) => Promise<ToolExecuteResult | unknown | void> | ToolExecuteResult | unknown | void;
+    execute: (input: TInput) => Promise<ToolExecuteResult | Record<string, unknown> | void> | ToolExecuteResult | Record<string, unknown> | void;
     /**
      * Whether to also register this tool with WebMCP (navigator.modelContext).
      *

package/dist/utils/helpdesk.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Help Desk Utilities
+ * Functions to trigger external help desk widgets (Intercom, Pylon, Zendesk, Freshdesk)
+ */
+import type { HelpDeskProvider } from '../core/config';
+declare global {
+    interface Window {
+        Intercom?: (command: string, ...args: unknown[]) => void;
+        Pylon?: (command: string, ...args: unknown[]) => void;
+        zE?: (widget: string, command: string, ...args: unknown[]) => void;
+        FreshworksWidget?: (command: string, ...args: unknown[]) => void;
+    }
+}
+/**
+ * Context to pass to help desk when escalating
+ */
+export interface HelpDeskContext {
+    conversationSummary?: string;
+    currentPage?: string;
+    userId?: string;
+}
+/**
+ * Trigger the appropriate help desk widget based on provider
+ */
+export declare function triggerHelpDesk(provider: HelpDeskProvider, context?: HelpDeskContext): boolean;
+/**
+ * Open email client with optional subject and body
+ */
+export declare function openEmail(emailAddress: string, subject?: string, body?: string): void;
+/**
+ * Open a URL in a new tab
+ */
+export declare function openUrl(url: string): void;

package/dist/utils/markdown.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Markdown Renderer
+ * Uses marked library for parsing markdown to HTML
+ */
+/**
+ * Render markdown content to HTML
+ * Used for AI chat responses
+ */
+export declare function renderMarkdown(content: string): string;

package/dist/utils/normalize-tool-result.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize a tool handler's return value into the payload sent to the backend.
+ *
+ * Accepted handler return shapes:
+ *   { success: true,  data: { ... } }  → returns the data object
+ *   { success: false, error: "..." }   → forwarded as-is (backend reads error)
+ *   { key: "val", ... }                → passed through unchanged
+ *   "string" / number / array          → passed through unchanged
+ */
+export declare function normalizeToolResult(raw: unknown): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Product copilot SDK for SaaS and web apps — AI assistant that executes tasks, not just answers questions",
   "type": "module",
   "main": "./dist/pillar.esm.js",