@pillar-ai/sdk 0.1.0

package/dist/actions/registry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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()`.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { defineActions } from '@pillar-ai/sdk/actions';
+ * import { router } from './router';
+ *
+ * export const actions = defineActions({
+ *   open_settings: {
+ *     description: 'Navigate to the settings page',
+ *     type: 'navigate',
+ *     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),
+ *   },
+ * });
+ * ```
+ *
+ * @param actions - Map of action name to definition
+ * @returns The same actions object (for re-export convenience)
+ */
+export declare function defineActions<T extends ActionDefinitions>(actions: T): T;
+/**
+ * Set client platform and version info.
+ *
+ * Called internally by Pillar.init() to set platform/version
+ * for API requests.
+ *
+ * @param platform - Platform identifier (web, ios, android, desktop)
+ * @param version - App version (semver or git SHA)
+ */
+export declare function setClientInfo(platform: Platform, version: string): void;
+/**
+ * Get the current client info.
+ *
+ * @returns Client info or null if not set
+ */
+export declare function getClientInfo(): ClientInfo | null;
+/**
+ * Get a registered action handler by name.
+ *
+ * @param name - Action name (e.g., "open_settings")
+ * @returns Handler function or undefined if not found
+ */
+export declare function getHandler(name: string): ActionDefinition['handler'] | undefined;
+/**
+ * Get a registered action definition by name.
+ *
+ * @param name - Action name
+ * @returns Action definition or undefined if not found
+ */
+export declare function getActionDefinition(name: string): ActionDefinition | undefined;
+/**
+ * Check if an action is registered.
+ *
+ * @param name - Action name
+ * @returns True if registered
+ */
+export declare function hasAction(name: string): boolean;
+/**
+ * Get all registered action names.
+ *
+ * @returns Array of action names
+ */
+export declare function getActionNames(): string[];
+/**
+ * Get the action manifest for syncing to the server.
+ *
+ * Extracts metadata from all registered actions (without handlers)
+ * for sending to the Pillar server during CI/CD.
+ *
+ * @param platform - Platform to include in manifest
+ * @param version - Version to include in manifest
+ * @param gitSha - Optional git commit SHA
+ * @returns Action manifest object
+ */
+export declare function getManifest(platform: Platform, version: string, gitSha?: string): ActionManifest;
+/**
+ * Clear all registered actions.
+ *
+ * Primarily for testing purposes.
+ */
+export declare function clearRegistry(): void;
+/**
+ * Get the count of registered actions.
+ *
+ * @returns Number of registered actions
+ */
+export declare function getActionCount(): number;

package/dist/actions/types.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Action Types - Type definitions for code-first action definitions.
+ *
+ * These types enable developers to define actions in their application code
+ * rather than in the admin UI, with full TypeScript support.
+ *
+ * @example
+ * ```ts
+ * import { defineActions } from '@pillar-ai/sdk/actions';
+ *
+ * const actions = defineActions({
+ *   open_settings: {
+ *     description: 'Navigate to the settings page',
+ *     type: 'navigate',
+ *     path: '/settings',
+ *     handler: () => router.push('/settings'),
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Supported action types.
+ *
+ * - navigate: Navigate to a page within the app
+ * - open_modal: Open a modal or dialog
+ * - fill_form: Fill form fields with data
+ * - trigger_action: Trigger a custom action
+ * - 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 ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+/**
+ * Supported platforms for action deployments.
+ */
+export type Platform = 'web' | 'ios' | 'android' | 'desktop';
+/**
+ * JSON Schema definition for action data.
+ *
+ * When provided, the AI will extract data from the user's query
+ * and populate the action's data field before execution.
+ */
+export interface ActionDataSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+        description?: string;
+        enum?: string[];
+        default?: unknown;
+    }>;
+    required?: string[];
+}
+/**
+ * Definition for a single action.
+ *
+ * Actions 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 ActionDefinition<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 action 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 action.
+     *
+     * 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 action - determines how the SDK handles it.
+     */
+    type: ActionType;
+    /**
+     * Path for navigate actions.
+     *
+     * Can include template variables like `/users/{userId}`.
+     */
+    path?: string;
+    /**
+     * External URL for external_link actions.
+     */
+    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 action.
+     */
+    dataSchema?: ActionDataSchema;
+    /**
+     * Default data to pass to the handler.
+     */
+    defaultData?: TData;
+    /**
+     * Context required for this action to be available.
+     *
+     * @example { loggedIn: true, plan: 'pro' }
+     */
+    requiredContext?: Record<string, unknown>;
+    /**
+     * Whether to auto-run this action without user confirmation.
+     *
+     * Only the highest-scoring action can auto-run.
+     * Use for simple navigations where user intent is clear.
+     *
+     * @default false
+     */
+    autoRun?: boolean;
+    /**
+     * Whether the action 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 action 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 actions that inform
+     * the agent's next decision.
+     *
+     * @default false
+     */
+    returns?: boolean;
+    /**
+     * Handler function executed when the action 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 action name to definition.
+ *
+ * Action names should be snake_case identifiers.
+ */
+export type ActionDefinitions = Record<string, ActionDefinition<any>>;
+/**
+ * Metadata for a single action in the manifest (no handler).
+ *
+ * This is what gets synced to the server.
+ */
+export interface ActionManifestEntry {
+    name: string;
+    description: string;
+    examples?: string[];
+    type: ActionType;
+    path?: string;
+    external_url?: string;
+    auto_run?: boolean;
+    auto_complete?: boolean;
+    returns_data?: boolean;
+    data_schema?: ActionDataSchema;
+    default_data?: Record<string, unknown>;
+    required_context?: Record<string, unknown>;
+}
+/**
+ * Action manifest - synced to server during CI/CD.
+ *
+ * Contains all action metadata without handlers.
+ */
+export interface ActionManifest {
+    /**
+     * 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;
+    /**
+     * Action definitions (without handlers).
+     */
+    actions: ActionManifestEntry[];
+}
+/**
+ * Client info set during SDK initialization.
+ */
+export interface ClientInfo {
+    platform: Platform;
+    version: string;
+}
+/**
+ * Action definition for syncing (without handler).
+ *
+ * Use this type when defining actions for CI/CD sync.
+ * Handlers are registered separately at runtime via pillar.onTask().
+ *
+ * @example
+ * ```ts
+ * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
+ *
+ * export const actions: SyncActionDefinitions = {
+ *   open_settings: {
+ *     description: 'Navigate to settings page',
+ *     type: 'navigate',
+ *     path: '/settings',
+ *     autoRun: true,
+ *   },
+ * };
+ * ```
+ */
+export interface SyncActionDefinition<TData = Record<string, unknown>> {
+    /** Human-readable description for AI matching */
+    description: string;
+    /** Example user queries that should trigger this action */
+    examples?: string[];
+    /** Type of action */
+    type: ActionType;
+    /** Path for navigate actions */
+    path?: string;
+    /** External URL for external_link actions */
+    externalUrl?: string;
+    /** JSON Schema for data extraction from user query */
+    dataSchema?: ActionDataSchema;
+    /** Default data to pass to the handler */
+    defaultData?: TData;
+    /** Context required for this action to be available */
+    requiredContext?: Record<string, unknown>;
+    /** Whether to auto-run this action without user confirmation */
+    autoRun?: boolean;
+    /** Whether the action completes immediately after execution */
+    autoComplete?: boolean;
+    /**
+     * Whether this action returns data for the agent.
+     * If true, the handler's return value is sent back to the agent.
+     */
+    returns?: boolean;
+}
+/**
+ * Map of action name to sync definition (no handlers).
+ *
+ * Use this type for your actions file that gets synced via CI/CD.
+ */
+export type SyncActionDefinitions = Record<string, SyncActionDefinition<any>>;
+/**
+ * Base data types for each action type.
+ * These are automatically inferred from the action's `type` field.
+ */
+export interface NavigateActionData {
+    /** CSS selector to highlight after navigation */
+    highlight_selector?: string;
+    /** Path that was navigated to (injected by SDK) */
+    path?: string;
+}
+export interface TriggerActionData {
+    /** The action being triggered */
+    action?: string;
+    /** Additional action 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;
+}
+/**
+ * Maps action types to their default data shapes.
+ * Used for automatic type inference in onTask handlers.
+ */
+export interface ActionTypeDataMap {
+    navigate: NavigateActionData;
+    trigger_action: TriggerActionData;
+    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 action from an ActionDefinitions map.
+ *
+ * Type inference priority:
+ * 1. If `defaultData` is defined, use that type (for custom fields)
+ * 2. Otherwise, infer from the action's `type` field using ActionTypeDataMap
+ * 3. Fall back to Record<string, unknown>
+ *
+ * @example
+ * ```ts
+ * const actions = {
+ *   // Inferred from type: "navigate" → NavigateActionData
+ *   open_settings: {
+ *     description: '...',
+ *     type: 'navigate',
+ *     path: '/settings',
+ *   },
+ *   // Custom data via defaultData
+ *   add_source: {
+ *     description: '...',
+ *     type: 'navigate',
+ *     defaultData: { type: '', url: '', name: '' },
+ *   },
+ * } as const satisfies SyncActionDefinitions;
+ * ```
+ */
+export type ActionDataType<TActions extends SyncActionDefinitions | ActionDefinitions, TName extends keyof TActions> = TActions[TName] extends {
+    defaultData: infer D;
+} ? D extends Record<string, unknown> ? D : Record<string, unknown> : TActions[TName] extends {
+    type: infer T;
+} ? T extends keyof ActionTypeDataMap ? ActionTypeDataMap[T] : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract all action names from an ActionDefinitions map.
+ *
+ * @example
+ * ```ts
+ * const actions = { open_settings: {...}, add_source: {...} };
+ * type Names = ActionNames<typeof actions>; // 'open_settings' | 'add_source'
+ * ```
+ */
+export type ActionNames<T extends SyncActionDefinitions | ActionDefinitions> = Extract<keyof T, string>;
+/**
+ * Typed task handler function.
+ *
+ * @template TData - The data type for this action
+ */
+export type TypedTaskHandler<TData = Record<string, unknown>> = (data: TData) => void | Promise<void>;
+/**
+ * Type-safe onTask method signature.
+ *
+ * When actions are provided to PillarProvider, this type enables
+ * TypeScript to infer the correct data type for each action handler.
+ *
+ * @template TActions - The action definitions map
+ */
+export interface TypedOnTask<TActions extends SyncActionDefinitions | ActionDefinitions> {
+    <TName extends ActionNames<TActions>>(taskName: TName, handler: TypedTaskHandler<ActionDataType<TActions, 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 action definitions.
+ *
+ * @template TActions - The action definitions map
+ *
+ * @example
+ * ```ts
+ * import type { TypedPillar } from '@pillar-ai/sdk';
+ * import type { actions } from './actions';
+ *
+ * const pillar = usePillar<typeof actions>();
+ *
+ * // TypeScript knows `data` has { type, url, name }
+ * pillar.onTask('add_source', (data) => {
+ *   console.log(data.url);
+ * });
+ * ```
+ */
+export interface TypedPillarMethods<TActions extends SyncActionDefinitions | ActionDefinitions> {
+    onTask: TypedOnTask<TActions>;
+}

package/dist/api/client.d.ts

@@ -0,0 +1,186 @@
+/**
+ * API Client for Pillar SDK
+ * Handles all communication with the Pillar backend
+ */
+import type { TaskButtonData } from '../components/Panel/TaskButton';
+import type { ResolvedConfig } from '../core/config';
+import type { ProductContext, Suggestion, UserProfile } from '../core/context';
+import type { ExecutionPlan } from '../core/plan';
+import type { Workflow } from '../core/workflow';
+import type { UserContextItem } from '../types/user-context';
+import type { ChatImage, ImageUploadResponse } from './mcp-client';
+export interface TooltipData {
+    id: string;
+    tooltip_id: string;
+    name: string;
+    content: string;
+    content_html: string;
+    article_slug?: string;
+    article_title?: string;
+    show_learn_more: boolean;
+    trigger: 'hover' | 'click' | 'focus' | 'icon';
+    position: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+}
+export interface ArticleData {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt?: string;
+    /** TipTap JSON content - preferred for rendering */
+    body_json?: Record<string, unknown>;
+    /** Legacy HTML content - fallback if body_json not available */
+    content_html?: string;
+    category_name?: string;
+    category_slug?: string;
+    reading_time?: number;
+    updated_at: string;
+    related_articles?: ArticleSummary[];
+}
+export interface ArticleSummary {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt?: string;
+    category_name?: string;
+}
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface SuggestedQuestion {
+    id: string;
+    text: string;
+}
+export interface ChatResponse {
+    message: string;
+    sources?: ArticleSummary[];
+    workflow?: Workflow;
+    conversationId?: string;
+    messageId?: string;
+    actions?: TaskButtonData[];
+}
+export interface ProgressEvent {
+    kind: 'search' | 'search_complete' | 'generating' | 'thinking';
+    message?: string;
+    progress_id?: string;
+}
+/**
+ * Server-side embed config response.
+ * These are admin-configured settings that the SDK merges with local config.
+ */
+export interface ServerEmbedConfig {
+    panel?: {
+        enabled?: boolean;
+        position?: 'left' | 'right';
+        width?: number;
+    };
+    floatingButton?: {
+        enabled?: boolean;
+        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;
+        };
+    };
+}
+export declare class APIClient {
+    private config;
+    private abortControllers;
+    private mcpClient;
+    constructor(config: ResolvedConfig);
+    private get baseUrl();
+    /**
+     * Get or create a persistent visitor ID.
+     * Stored in localStorage to persist across sessions.
+     */
+    private getVisitorId;
+    /**
+     * Get or create a session ID.
+     * Stored in sessionStorage to persist only for the current browser session.
+     */
+    private getSessionId;
+    /**
+     * Get the current page URL for analytics tracking.
+     */
+    private getPageUrl;
+    private get headers();
+    private fetch;
+    /**
+     * Fetch embed configuration from server.
+     * Called during SDK init to get admin-configured settings.
+     *
+     * @returns Server config or null if fetch fails (SDK continues with defaults)
+     */
+    fetchEmbedConfig(): Promise<ServerEmbedConfig | null>;
+    getTooltips(ids?: string[]): Promise<TooltipData[]>;
+    /**
+     * Get AI-generated suggested questions for the home view.
+     * Returns action-oriented questions based on the help center's content.
+     */
+    getSuggestedQuestions(): Promise<SuggestedQuestion[]>;
+    /**
+     * Upload an image for use in chat.
+     *
+     * @param file - The image file to upload
+     * @returns Promise with signed URL and expiration
+     */
+    uploadImage(file: File): Promise<ImageUploadResponse>;
+    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, onPlan?: (plan: ExecutionPlan) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void): Promise<ChatResponse>;
+    /**
+     * Legacy chat method using the old /ai/chat/ endpoint.
+     * @deprecated Use chat() which uses the MCP protocol.
+     */
+    chatLegacy(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null): Promise<ChatResponse>;
+    private handleStreamingChat;
+    /**
+     * Submit feedback on an AI assistant message.
+     * Fire-and-forget - errors are logged but don't throw.
+     *
+     * @param messageId - The UUID of the assistant message
+     * @param feedback - 'up' for helpful, 'down' for not helpful
+     * @param comment - Optional comment explaining the feedback
+     */
+    submitFeedback(messageId: string, feedback: 'up' | 'down', comment?: string): Promise<void>;
+    /**
+     * Confirm task execution result.
+     * Called by the SDK after a customer's task handler completes.
+     * Fire-and-forget - errors are logged but don't throw.
+     *
+     * @param taskId - The database UUID of the task
+     * @param status - 'success' or 'failure'
+     * @param details - Optional execution details
+     */
+    confirmTaskExecution(taskId: string, status: 'success' | 'failure', details?: {
+        error?: string;
+        duration_ms?: number;
+        session_id?: string;
+        conversation_id?: string;
+        [key: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Get contextual help suggestions based on product context.
+     * Returns relevant articles, videos, and actions.
+     */
+    getSuggestions(productContext: ProductContext, 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>;
+    cancelAllRequests(): void;
+}