@pillar-ai/sdk 0.1.21 → 0.1.22

package/dist/tools/types.d.ts

@@ -0,0 +1,564 @@
+/**
+ * Tool Types - Type definitions for code-first tool definitions.
+ *
+ * These types enable developers to define tools in their application code
+ * rather than in the admin UI, with full TypeScript support.
+ *
+ * @example
+ * ```ts
+ * // lib/pillar/tools/index.ts
+ * import type { SyncToolDefinitions } from '@pillar-ai/sdk';
+ *
+ * export const tools = {
+ *   open_settings: {
+ *     description: 'Navigate to the settings page',
+ *     type: 'navigate' as const,
+ *     path: '/settings',
+ *     autoRun: true,
+ *   },
+ * } as const satisfies SyncToolDefinitions;
+ *
+ * export default tools;
+ *
+ * // Sync via CI/CD: npx pillar-sync --scan ./src
+ * // Register handlers at runtime: pillar.onTask('open_settings', () => router.push('/settings'));
+ * ```
+ */
+/**
+ * Supported tool types.
+ *
+ * - navigate: Navigate to a page within the app
+ * - open_modal: Open a modal or dialog
+ * - fill_form: Fill form fields with data
+ * - trigger_tool: Trigger a custom tool
+ * - 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 ToolType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_tool' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+/**
+ * Supported platforms for tool deployments.
+ */
+export type Platform = 'web' | 'ios' | 'android' | 'desktop';
+/**
+ * Schema property definition for a single field.
+ * Supports nested objects and arrays with items.
+ */
+export interface ToolDataSchemaProperty {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /** Items schema for array types */
+    items?: ToolDataSchemaProperty;
+    /** Nested properties for object types */
+    properties?: Record<string, ToolDataSchemaProperty>;
+    /** Required fields for nested object types */
+    required?: string[];
+}
+/**
+ * JSON Schema definition for tool data.
+ *
+ * When provided, the AI will extract data from the user's query
+ * and populate the tool's data field before execution.
+ */
+export interface ToolDataSchema {
+    type: 'object';
+    properties: Record<string, ToolDataSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Definition for a single tool.
+ *
+ * Tools are defined in code and synced to the server during CI/CD.
+ * The server stores the metadata, and the SDK executes the handler locally.
+ *
+ * @template TData - Type for the data passed to the handler
+ */
+export interface ToolDefinition<TData = Record<string, unknown>> {
+    /**
+     * Human-readable description for AI matching.
+     *
+     * The AI uses semantic similarity to match user queries to this description.
+     * Be specific about when this tool should be suggested.
+     *
+     * @example "Navigate to the billing page. Suggest when user asks about payments, invoices, or subscription."
+     */
+    description: string;
+    /**
+     * Example user queries that should trigger this tool.
+     *
+     * Provide 3-5 natural phrasings users might say:
+     * - Imperative: "open settings", "go to billing"
+     * - Questions: "where can I change my password?"
+     * - Informal: "settings", "show analytics"
+     *
+     * These are embedded and used for semantic matching alongside the description.
+     */
+    examples?: string[];
+    /**
+     * Type of tool - determines how the SDK handles it.
+     */
+    type: ToolType;
+    /**
+     * Path for navigate tools.
+     *
+     * Can include template variables like `/users/{userId}`.
+     */
+    path?: string;
+    /**
+     * External URL for external_link tools.
+     */
+    externalUrl?: string;
+    /**
+     * JSON Schema for data extraction from user query.
+     *
+     * When provided, the AI will attempt to extract structured data
+     * from the conversation before executing the tool.
+     */
+    dataSchema?: ToolDataSchema;
+    /**
+     * Default data to pass to the handler.
+     */
+    defaultData?: TData;
+    /**
+     * Context required for this tool to be available.
+     *
+     * @example { loggedIn: true, plan: 'pro' }
+     */
+    requiredContext?: Record<string, unknown>;
+    /**
+     * Whether to auto-run this tool without user confirmation.
+     *
+     * Only the highest-scoring tool can auto-run.
+     * Use for simple navigations where user intent is clear.
+     *
+     * @default false
+     */
+    autoRun?: boolean;
+    /**
+     * Whether the tool completes immediately after execution.
+     *
+     * If false, the SDK waits for host app confirmation.
+     * Use true for simple navigations and clipboard operations.
+     *
+     * @default false
+     */
+    autoComplete?: boolean;
+    /**
+     * Whether this tool returns data for the agent.
+     *
+     * If true, the handler's return value is sent back to the agent
+     * for further reasoning. Use for query/lookup tools that inform
+     * the agent's next decision.
+     *
+     * @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 tool is triggered.
+     *
+     * This runs in the client - the server only stores metadata.
+     * If `returns: true`, the return value is sent to the agent.
+     */
+    handler: (data: TData) => void | unknown | Promise<void | unknown>;
+}
+/**
+ * Map of tool name to definition.
+ *
+ * Tool names should be snake_case identifiers.
+ */
+export type ToolDefinitions = Record<string, ToolDefinition<unknown>>;
+/**
+ * Metadata for a single tool in the manifest (no handler).
+ *
+ * This is what gets synced to the server.
+ */
+export interface ToolManifestEntry {
+    name: string;
+    description: string;
+    examples?: string[];
+    type: ToolType;
+    path?: string;
+    external_url?: string;
+    auto_run?: boolean;
+    auto_complete?: boolean;
+    returns_data?: boolean;
+    data_schema?: ToolDataSchema;
+    default_data?: Record<string, unknown>;
+    required_context?: Record<string, unknown>;
+    parameter_examples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+}
+/**
+ * Tool manifest - synced to server during CI/CD.
+ *
+ * Contains all tool metadata without handlers.
+ */
+export interface ToolManifest {
+    /**
+     * Platform this manifest is for.
+     */
+    platform: Platform;
+    /**
+     * Version of the client app (semver or git SHA).
+     */
+    version: string;
+    /**
+     * Git commit SHA for traceability.
+     */
+    gitSha?: string;
+    /**
+     * When this manifest was generated.
+     */
+    generatedAt: string;
+    /**
+     * Tool definitions (without handlers).
+     */
+    tools: ToolManifestEntry[];
+    /**
+     * Custom agent guidance synced alongside tools.
+     * Injected into the AI agent's prompt as product_guidance.
+     */
+    agentGuidance?: string;
+}
+/**
+ * Client info set during SDK initialization.
+ */
+export interface ClientInfo {
+    platform: Platform;
+    version: string;
+}
+/**
+ * Tool definition for syncing (without handler).
+ *
+ * Use this type when defining tools for CI/CD sync.
+ * Handlers are registered separately at runtime via pillar.onTask().
+ *
+ * @example
+ * ```ts
+ * import type { SyncToolDefinitions } from '@pillar-ai/sdk';
+ *
+ * export const tools: SyncToolDefinitions = {
+ *   open_settings: {
+ *     description: 'Navigate to settings page',
+ *     type: 'navigate',
+ *     path: '/settings',
+ *     autoRun: true,
+ *   },
+ * };
+ * ```
+ */
+export interface SyncToolDefinition<TData = Record<string, unknown>> {
+    /** Human-readable description for AI matching */
+    description: string;
+    /** Example user queries that should trigger this tool */
+    examples?: string[];
+    /** Type of tool */
+    type: ToolType;
+    /** Path for navigate tools */
+    path?: string;
+    /** External URL for external_link tools */
+    externalUrl?: string;
+    /** JSON Schema for data extraction from user query */
+    dataSchema?: ToolDataSchema;
+    /** Default data to pass to the handler */
+    defaultData?: TData;
+    /** Context required for this tool to be available */
+    requiredContext?: Record<string, unknown>;
+    /** Whether to auto-run this tool without user confirmation */
+    autoRun?: boolean;
+    /** Whether the tool completes immediately after execution */
+    autoComplete?: boolean;
+    /**
+     * Whether this tool returns data for the agent.
+     * 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 tool name to sync definition (no handlers).
+ *
+ * Use this type for your tools file that gets synced via CI/CD.
+ */
+export type SyncToolDefinitions = Record<string, SyncToolDefinition<unknown>>;
+/**
+ * Base data types for each tool type.
+ * These are automatically inferred from the tool's `type` field.
+ */
+export interface NavigateToolData {
+    /** CSS selector to highlight after navigation */
+    highlight_selector?: string;
+    /** Path that was navigated to (injected by SDK) */
+    path?: string;
+}
+export interface TriggerToolData {
+    /** The tool being triggered */
+    tool?: string;
+    /** Additional tool parameters */
+    [key: string]: unknown;
+}
+export interface InlineUIData {
+    /** Card type for rendering */
+    card_type: string;
+    /** Additional card data */
+    [key: string]: unknown;
+}
+export interface ExternalLinkData {
+    /** The URL being opened */
+    url?: string;
+}
+export interface CopyTextData {
+    /** Text to copy to clipboard */
+    text?: string;
+}
+export interface QueryToolData {
+    /** Query parameters passed to the handler */
+    [key: string]: unknown;
+}
+/**
+ * Maps tool types to their default data shapes.
+ * Used for automatic type inference in onTask handlers.
+ */
+export interface ToolTypeDataMap {
+    navigate: NavigateToolData;
+    trigger_tool: TriggerToolData;
+    query: QueryToolData;
+    inline_ui: InlineUIData;
+    external_link: ExternalLinkData;
+    copy_text: CopyTextData;
+    open_modal: Record<string, unknown>;
+    fill_form: Record<string, unknown>;
+    start_tutorial: Record<string, unknown>;
+}
+/**
+ * Extract the data type for a specific tool from a ToolDefinitions map.
+ *
+ * Type inference priority:
+ * 1. If `defaultData` is defined, use that type (for custom fields)
+ * 2. Otherwise, infer from the tool's `type` field using ToolTypeDataMap
+ * 3. Fall back to Record<string, unknown>
+ *
+ * @example
+ * ```ts
+ * const tools = {
+ *   // Inferred from type: "navigate" → NavigateToolData
+ *   open_settings: {
+ *     description: '...',
+ *     type: 'navigate',
+ *     path: '/settings',
+ *   },
+ *   // Custom data via defaultData
+ *   add_source: {
+ *     description: '...',
+ *     type: 'navigate',
+ *     defaultData: { type: '', url: '', name: '' },
+ *   },
+ * } as const satisfies SyncToolDefinitions;
+ * ```
+ */
+export type ToolDataType<TTools extends SyncToolDefinitions | ToolDefinitions, TName extends keyof TTools> = TTools[TName] extends {
+    defaultData: infer D;
+} ? D extends Record<string, unknown> ? D : Record<string, unknown> : TTools[TName] extends {
+    type: infer T;
+} ? T extends keyof ToolTypeDataMap ? ToolTypeDataMap[T] : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract all tool names from a ToolDefinitions map.
+ *
+ * @example
+ * ```ts
+ * const tools = { open_settings: {...}, add_source: {...} };
+ * type Names = ToolNames<typeof tools>; // 'open_settings' | 'add_source'
+ * ```
+ */
+export type ToolNames<T extends SyncToolDefinitions | ToolDefinitions> = Extract<keyof T, string>;
+/**
+ * Typed task handler function.
+ *
+ * @template TData - The data type for this tool
+ */
+export type TypedTaskHandler<TData = Record<string, unknown>> = (data: TData) => void | Promise<void>;
+/**
+ * Type-safe onTask method signature.
+ *
+ * When tools are provided to PillarProvider, this type enables
+ * TypeScript to infer the correct data type for each tool handler.
+ *
+ * @template TTools - The tool definitions map
+ */
+export interface TypedOnTask<TTools extends SyncToolDefinitions | ToolDefinitions> {
+    <TName extends ToolNames<TTools>>(taskName: TName, handler: TypedTaskHandler<ToolDataType<TTools, TName>>): () => void;
+    (taskName: string, handler: TypedTaskHandler): () => void;
+}
+/**
+ * Extended Pillar interface with type-safe onTask.
+ *
+ * Use this when you want strongly typed task handlers based on
+ * your tool definitions.
+ *
+ * @template TTools - The tool definitions map
+ *
+ * @example
+ * ```ts
+ * import type { TypedPillar } from '@pillar-ai/sdk';
+ * import type { tools } from './tools';
+ *
+ * const pillar = usePillar<typeof tools>();
+ *
+ * // TypeScript knows `data` has { type, url, name }
+ * pillar.onTask('add_source', (data) => {
+ *   console.log(data.url);
+ * });
+ * ```
+ */
+export interface TypedPillarMethods<TTools extends SyncToolDefinitions | ToolDefinitions> {
+    onTask: TypedOnTask<TTools>;
+}
+/**
+ * Result returned from a tool's execute function.
+ *
+ * Follows the MCP tool result format. Plain objects are also accepted
+ * by the SDK and normalized to this shape automatically.
+ */
+export interface ToolExecuteResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Unified tool definition that co-locates metadata and handler.
+ *
+ * Use with `pillar.defineTool()` or the `usePillarTool()` React hook.
+ * The CLI scanner (`npx pillar-sync --scan ./src`) discovers these
+ * definitions automatically — no barrel file needed.
+ *
+ * @template TInput - Type of the input object passed to `execute`
+ *
+ * @example
+ * ```ts
+ * pillar.defineTool({
+ *   name: 'add_to_cart',
+ *   description: 'Add a product to the shopping cart',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       productId: { type: 'string', description: 'Product ID' },
+ *       quantity: { type: 'number', description: 'Quantity to add' },
+ *     },
+ *     required: ['productId', 'quantity'],
+ *   },
+ *   execute: async ({ productId, quantity }) => {
+ *     await cartApi.add(productId, quantity);
+ *     return { content: [{ type: 'text', text: 'Added to cart' }] };
+ *   },
+ * });
+ * ```
+ */
+export interface ToolSchema<TInput = Record<string, unknown>> {
+    /** Unique tool name (e.g., 'add_to_cart') */
+    name: string;
+    /** Human-readable description for AI matching */
+    description: string;
+    /**
+     * Type of tool - determines how the SDK handles it and organizes it in the UI.
+     */
+    type?: ToolType;
+    /**
+     * JSON Schema describing the input parameters.
+     * The AI extracts structured data from the conversation to populate these.
+     */
+    inputSchema?: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /**
+     * Example user queries that should trigger this tool.
+     * Used for semantic matching alongside the description.
+     */
+    examples?: string[];
+    /**
+     * Whether to auto-execute without user confirmation.
+     * @default false
+     */
+    autoRun?: boolean;
+    /**
+     * Whether the tool completes immediately after execution.
+     * @default true
+     */
+    autoComplete?: boolean;
+    /**
+     * 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
+     */
+    execute: (input: TInput) => Promise<ToolExecuteResult | unknown | void> | ToolExecuteResult | unknown | void;
+}
+/** @deprecated Use ToolType instead */
+export type ActionType = ToolType;
+/** @deprecated Use ToolDataSchemaProperty instead */
+export type ActionDataSchemaProperty = ToolDataSchemaProperty;
+/** @deprecated Use ToolDataSchema instead */
+export type ActionDataSchema = ToolDataSchema;
+/** @deprecated Use ToolDefinition instead */
+export type ActionDefinition<TData = Record<string, unknown>> = ToolDefinition<TData>;
+/** @deprecated Use ToolDefinitions instead */
+export type ActionDefinitions = ToolDefinitions;
+/** @deprecated Use ToolManifestEntry instead */
+export type ActionManifestEntry = ToolManifestEntry;
+/** @deprecated Use ToolManifest instead */
+export type ActionManifest = ToolManifest;
+/** @deprecated Use SyncToolDefinition instead */
+export type SyncActionDefinition<TData = Record<string, unknown>> = SyncToolDefinition<TData>;
+/** @deprecated Use SyncToolDefinitions instead */
+export type SyncActionDefinitions = SyncToolDefinitions;
+/** @deprecated Use NavigateToolData instead */
+export type NavigateActionData = NavigateToolData;
+/** @deprecated Use TriggerToolData instead */
+export type TriggerActionData = TriggerToolData;
+/** @deprecated Use QueryToolData instead */
+export type QueryActionData = QueryToolData;
+/** @deprecated Use ToolTypeDataMap instead */
+export type ActionTypeDataMap = ToolTypeDataMap;
+/** @deprecated Use ToolDataType instead */
+export type ActionDataType<TTools extends SyncToolDefinitions | ToolDefinitions, TName extends keyof TTools> = ToolDataType<TTools, TName>;
+/** @deprecated Use ToolNames instead */
+export type ActionNames<T extends SyncToolDefinitions | ToolDefinitions> = ToolNames<T>;
+/** @deprecated Use ToolExecuteResult instead */
+export type ActionResult = ToolExecuteResult;
+/** @deprecated Use ToolSchema instead */
+export type ActionSchema<TInput = Record<string, unknown>> = ToolSchema<TInput>;

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/resilient-fetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resilient fetch wrapper with configurable exponential backoff.
+ *
+ * Retries on network errors (TypeError / Failed to fetch) and 5xx responses.
+ * Does NOT retry on 4xx (client errors) since those won't resolve by retrying.
+ *
+ * Base delay default (100ms) matches the `exponential-backoff` library.
+ * Backoff schedule: baseDelayMs * 2^(attempt-1)  -->  100, 200, 400, 800, 1600, 3200 ...
+ */
+export interface ResilientFetchOptions extends RequestInit {
+    /** Max retry attempts after the initial request (0 = no retries). Default: 0 */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 100 */
+    baseDelayMs?: number;
+    /**
+     * Custom predicate to decide whether a failed attempt should be retried.
+     * Called with the caught error (for network failures) or the Response (for HTTP errors).
+     * Return `true` to retry, `false` to fail immediately.
+     * Default: retry on network errors + 5xx status codes.
+     */
+    retryOn?: (error: unknown, response?: Response) => boolean;
+    /** Called before each retry. Useful for per-call-site logging. */
+    onRetry?: (attempt: number, delay: number, error: unknown) => void;
+}
+export declare function resilientFetch(url: string, options?: ResilientFetchOptions): Promise<Response>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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",
@@ -68,7 +68,8 @@
     "@preact/signals": "^1.3.1",
     "marked": "^17.0.1",
     "preact": "^10.25.4",
-    "preact-iso": "^2.9.0"
+    "preact-iso": "^2.9.0",
+    "user": "^0.0.0"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",