@pillar-ai/sdk 0.1.23 → 0.1.25

package/dist/ui/types.d.ts

@@ -0,0 +1,293 @@
+/**
+ * UI Interaction Types
+ *
+ * Type definitions for the UI scanning and interaction system.
+ * This enables AI agents to understand and interact with page elements.
+ */
+/**
+ * Supported UI interaction types.
+ *
+ * - click: Click/tap on an element
+ * - type: Enter text into an input field
+ * - select: Select an option from a dropdown/select
+ * - scroll: Scroll element into view
+ * - hover: Hover over an element
+ * - focus: Focus an element
+ * - clear: Clear an input field's value
+ */
+export type UIInteractionType = 'click' | 'type' | 'select' | 'scroll' | 'hover' | 'focus' | 'clear';
+/**
+ * Element types detected by the scanner.
+ */
+export type UIElementType = 'button' | 'link' | 'input' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'switch' | 'slider' | 'menu' | 'menuitem' | 'tab' | 'dialog' | 'custom' | 'unknown';
+/**
+ * Bounding rectangle for an element.
+ */
+export interface UIElementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Represents a scanned UI element.
+ *
+ * Contains all information needed for the AI to understand
+ * and interact with a page element.
+ */
+export interface UIElement {
+    /**
+     * Unique identifier for this element.
+     * Generated during scanning (e.g., "pillar-el-0").
+     * Used to target the element for interactions.
+     */
+    id: string;
+    /**
+     * HTML tag name (lowercase).
+     * @example "button", "input", "div"
+     */
+    tag: string;
+    /**
+     * Semantic element type.
+     * Derived from tag, role, or type attribute.
+     */
+    type: UIElementType;
+    /**
+     * Human-readable label for the AI.
+     * Extracted from aria-label, text content, title, etc.
+     */
+    label: string;
+    /**
+     * Whether the element can be interacted with.
+     * False if disabled or not interactive.
+     */
+    interactable: boolean;
+    /**
+     * List of interactions this element supports.
+     * Determined by element type and attributes.
+     */
+    interactions: UIInteractionType[];
+    /**
+     * Current value for inputs, textareas, selects.
+     */
+    value?: string;
+    /**
+     * Available options for select elements.
+     */
+    options?: string[];
+    /**
+     * Placeholder text for inputs/textareas.
+     */
+    placeholder?: string;
+    /**
+     * Whether checkbox/radio/switch is checked.
+     */
+    checked?: boolean;
+    /**
+     * Whether the element is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Element's bounding rectangle.
+     * Useful for understanding layout context.
+     */
+    rect: UIElementRect;
+    /**
+     * Relevant attributes from the element.
+     * Includes data-pillar-* attributes and key attributes.
+     */
+    attributes: Record<string, string>;
+    /**
+     * XPath for precise element targeting.
+     * Used as a fallback if ID-based lookup fails.
+     */
+    xpath: string;
+    /**
+     * Nearby text or labels for additional context.
+     * Helps AI understand the element's purpose.
+     */
+    context?: string;
+    /**
+     * Reference to the actual DOM element.
+     * Only available client-side, not serialized.
+     * @internal
+     */
+    _element?: HTMLElement;
+}
+/**
+ * Scroll position on the page.
+ */
+export interface UIScrollPosition {
+    x: number;
+    y: number;
+}
+/**
+ * Page-level UI state.
+ *
+ * Represents a snapshot of the page's interactable elements
+ * at a specific point in time.
+ */
+export interface UIPageState {
+    /**
+     * Current page URL.
+     */
+    url: string;
+    /**
+     * Page title.
+     */
+    title: string;
+    /**
+     * Timestamp when the scan was performed.
+     */
+    timestamp: number;
+    /**
+     * List of interactable elements on the page.
+     */
+    elements: UIElement[];
+    /**
+     * ID of the currently focused element, if any.
+     */
+    focusedElementId?: string;
+    /**
+     * Current scroll position.
+     */
+    scrollPosition: UIScrollPosition;
+}
+/**
+ * Represents a UI interaction request from the AI.
+ */
+export interface UIInteraction {
+    /**
+     * ID of the element to interact with.
+     * Must match an element from UIPageState.elements.
+     */
+    elementId: string;
+    /**
+     * Type of interaction to perform.
+     */
+    action: UIInteractionType;
+    /**
+     * Value for type/select interactions.
+     */
+    value?: string;
+    /**
+     * Additional options for the interaction.
+     */
+    options?: UIInteractionOptions;
+}
+/**
+ * Options for UI interactions.
+ */
+export interface UIInteractionOptions {
+    /**
+     * Whether to clear existing value before typing.
+     * Only applies to 'type' action.
+     * @default true
+     */
+    clearBeforeType?: boolean;
+    /**
+     * Delay in ms between keystrokes for type action.
+     * Use 0 for instant typing.
+     * @default 0
+     */
+    typeDelay?: number;
+    /**
+     * Whether to scroll element into view before interaction.
+     * @default true
+     */
+    scrollIntoView?: boolean;
+    /**
+     * Whether to wait for element to be visible.
+     * @default true
+     */
+    waitForVisible?: boolean;
+    /**
+     * Timeout in ms for waiting operations.
+     * @default 5000
+     */
+    timeout?: number;
+}
+/**
+ * Result of a UI interaction.
+ */
+export interface UIInteractionResult {
+    /**
+     * Whether the interaction succeeded.
+     */
+    success: boolean;
+    /**
+     * Error message if the interaction failed.
+     */
+    error?: string;
+    /**
+     * The element ID that was interacted with.
+     */
+    elementId: string;
+    /**
+     * The action that was performed.
+     */
+    action: UIInteractionType;
+    /**
+     * New value after the interaction (for inputs).
+     */
+    newValue?: string;
+    /**
+     * Whether the element is still present after interaction.
+     * May be false if clicking caused navigation or element removal.
+     */
+    elementStillPresent?: boolean;
+    /**
+     * Any data extracted from the interaction.
+     * For example, selected option text.
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * Simplified element representation for AI context.
+ *
+ * Contains only essential information to reduce token usage
+ * while still providing enough context for the AI.
+ */
+export interface UIElementSummary {
+    /**
+     * Element ID for targeting.
+     */
+    id: string;
+    /**
+     * Human-readable label.
+     */
+    label: string;
+    /**
+     * Element type (button, input, etc.).
+     */
+    type: string;
+    /**
+     * Available interactions.
+     */
+    interactions: string[];
+    /**
+     * Current value (if applicable).
+     */
+    value?: string;
+    /**
+     * Available options (for selects).
+     */
+    options?: string[];
+    /**
+     * Additional context about the element.
+     */
+    context?: string;
+}
+/**
+ * Convert a full UIElement to a summary for AI context.
+ */
+export declare function toElementSummary(element: UIElement): UIElementSummary;
+/**
+ * Convert UIPageState to a minimal representation for AI context.
+ */
+export declare function toPageStateSummary(state: UIPageState): {
+    url: string;
+    title: string;
+    elements: UIElementSummary[];
+    focusedElementId?: string;
+};

package/dist/utils/tracing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenTelemetry browser tracing for Pillar SDK.
+ *
+ * Initialises a WebTracerProvider that exports spans via OTLP/JSON to the
+ * backend proxy endpoint (`/mcp/telemetry/v1/traces`).  The backend forwards
+ * them to Google Cloud Trace so browser and server spans share the same
+ * project and can be correlated by trace ID.
+ *
+ * Tracing is opt-in via `Pillar.init({ tracing: true })` or automatically
+ * when `debug: true`.
+ */
+import { trace, context, type Tracer, type Span, SpanStatusCode } from '@opentelemetry/api';
+/**
+ * Initialise the browser tracing provider.
+ *
+ * @param apiBaseUrl  The SDK's API base URL (e.g. `https://help-api.trypillar.com`)
+ * @param attrs       Extra resource attributes (product key, visitor id, …)
+ */
+export declare function initTracing(apiBaseUrl: string, attrs?: Record<string, string>): Tracer;
+/** Return the active tracer (or a no-op tracer if tracing is not initialised). */
+export declare function getTracer(): Tracer;
+/** Whether tracing has been initialised. */
+export declare function isTracingEnabled(): boolean;
+/**
+ * Build a W3C `traceparent` header value from the current active span.
+ * Returns `undefined` if there is no active span.
+ */
+export declare function getTraceparentHeader(): string | undefined;
+/**
+ * Inject `traceparent` (and optionally `tracestate`) into a headers object.
+ * Mutates and returns the headers dict.
+ */
+export declare function injectTraceHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Force-flush any pending spans. Call on page unload or when needed.
+ */
+export declare function flushTracing(): Promise<void>;
+/**
+ * Shut down the provider (call on SDK destroy).
+ */
+export declare function shutdownTracing(): Promise<void>;
+export { trace, context, SpanStatusCode };
+export type { Span };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
@@ -65,6 +65,13 @@
     }
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-zone": "^2.5.1",
+    "@opentelemetry/core": "^2.5.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.212.0",
+    "@opentelemetry/resources": "^2.5.1",
+    "@opentelemetry/sdk-trace-base": "^2.5.1",
+    "@opentelemetry/sdk-trace-web": "^2.5.1",
     "@preact/signals": "^1.3.1",
     "marked": "^17.0.1",
     "preact": "^10.25.4",

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

@@ -1,16 +0,0 @@
-/**
- * Tab Navigation Component
- * Vertical tabs on the right edge of the panel for switching between Assistant and Support
- */
-import { h } from 'preact';
-import type { ResolvedSupportConfig } from '../../core/config';
-interface TabNavigationProps {
-    supportConfig: ResolvedSupportConfig;
-}
-export declare function TabNavigation({ supportConfig }: TabNavigationProps): h.JSX.Element;
-/**
- * CSS Styles for Tab Navigation
- * Should be appended to PANEL_STYLES
- */
-export declare const TAB_NAVIGATION_STYLES = "\n/* ============================================================================\n   Panel Wrapper (for tab layout)\n   Horizontal flex container with main content + tab nav\n   ============================================================================ */\n\n._pillar-panel-wrapper {\n  display: flex;\n  flex-direction: row;\n  height: 100%;\n  overflow: hidden;\n}\n\n._pillar-panel-wrapper > ._pillar-panel-ui {\n  flex: 1;\n  min-width: 0;\n}\n\n.pillar-panel-wrapper {}\n\n/* ============================================================================\n   Tab Navigation\n   Vertical tabs on the right edge of the panel\n   ============================================================================ */\n\n._pillar-tab-nav {\n  display: flex;\n  flex-direction: column;\n  width: 48px;\n  min-width: 48px;\n  background: var(--pillar-bg-secondary);\n  border-left: 1px solid var(--pillar-border);\n  padding: var(--pillar-spacing-sm) 0;\n  gap: var(--pillar-spacing-xs);\n}\n\n._pillar-tab {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n  gap: 2px;\n  padding: var(--pillar-spacing-sm) var(--pillar-spacing-xs);\n  margin: 0 var(--pillar-spacing-xs);\n  border: none;\n  border-radius: var(--pillar-radius-md);\n  background: transparent;\n  color: var(--pillar-text-muted);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n  position: relative;\n}\n\n._pillar-tab:hover {\n  background: var(--pillar-bg-tertiary);\n  color: var(--pillar-text);\n}\n\n._pillar-tab--active {\n  background: var(--pillar-primary-light);\n  color: var(--pillar-primary);\n}\n\n._pillar-tab--active:hover {\n  background: var(--pillar-primary-light-hover);\n  color: var(--pillar-primary);\n}\n\n._pillar-tab-icon {\n  width: 20px;\n  height: 20px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n._pillar-tab-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n._pillar-tab-label {\n  font-size: 9px;\n  font-weight: 500;\n  text-align: center;\n  line-height: 1.2;\n  max-width: 40px;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n/* Public override classes */\n.pillar-tab-nav {}\n.pillar-tab {}\n.pillar-tab-icon {}\n.pillar-tab-label {}\n";
-export {};

package/dist/components/Views/HelpCenterArticles.d.ts

@@ -1,17 +0,0 @@
-/**
- * Help Center Articles Component
- * Shows contextual articles based on current page + browse option
- */
-import { h } from 'preact';
-interface HelpCenterArticlesProps {
-    /** Current page path/URL for contextual search */
-    currentPage?: string;
-    /** Maximum number of articles to show */
-    maxArticles?: number;
-}
-export declare function HelpCenterArticles({ currentPage, maxArticles }: HelpCenterArticlesProps): h.JSX.Element;
-/**
- * CSS Styles for Help Center Articles
- */
-export declare const HELP_CENTER_ARTICLES_STYLES = "\n/* ============================================================================\n   Help Center Articles\n   ============================================================================ */\n\n._pillar-hc-articles {\n  display: flex;\n  flex-direction: column;\n  gap: var(--pillar-spacing-md);\n}\n\n._pillar-hc-articles-header {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--pillar-spacing-md);\n}\n\n._pillar-hc-articles-title {\n  font-size: var(--pillar-font-size-sm);\n  font-weight: 600;\n  color: var(--pillar-text-muted);\n  text-transform: uppercase;\n  letter-spacing: 0.05em;\n}\n\n._pillar-hc-articles-browse {\n  display: flex;\n  align-items: center;\n  gap: var(--pillar-spacing-xs);\n  padding: var(--pillar-spacing-xs) var(--pillar-spacing-sm);\n  background: transparent;\n  border: 1px solid var(--pillar-border);\n  border-radius: var(--pillar-radius-md);\n  font-size: var(--pillar-font-size-sm);\n  color: var(--pillar-text-muted);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-hc-articles-browse:hover {\n  background: var(--pillar-bg-secondary);\n  color: var(--pillar-text);\n  border-color: var(--pillar-primary);\n}\n\n._pillar-hc-articles-browse svg {\n  width: 14px;\n  height: 14px;\n}\n\n._pillar-hc-articles-list {\n  display: flex;\n  flex-direction: column;\n  gap: var(--pillar-spacing-sm);\n}\n\n._pillar-hc-articles-empty {\n  padding: var(--pillar-spacing-lg);\n  text-align: center;\n  color: var(--pillar-text-muted);\n  font-size: var(--pillar-font-size-sm);\n}\n\n._pillar-hc-articles-browse-btn {\n  margin-top: var(--pillar-spacing-md);\n  padding: var(--pillar-spacing-sm) var(--pillar-spacing-lg);\n  background: var(--pillar-primary);\n  color: white;\n  border: none;\n  border-radius: var(--pillar-radius-md);\n  font-size: var(--pillar-font-size-sm);\n  font-weight: 500;\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-hc-articles-browse-btn:hover {\n  background: var(--pillar-primary-hover);\n}\n\n/* Public override classes */\n.pillar-hc-articles {}\n.pillar-hc-articles-header {}\n.pillar-hc-articles-title {}\n.pillar-hc-articles-browse {}\n.pillar-hc-articles-list {}\n.pillar-hc-articles-empty {}\n.pillar-hc-articles-browse-btn {}\n";
-export {};

package/dist/components/Views/SupportView.d.ts

@@ -1,15 +0,0 @@
-/**
- * Support View Component
- * Displays configurable support channels and help center articles
- */
-import { h } from 'preact';
-import type { ResolvedSupportConfig } from '../../core/config';
-interface SupportViewProps {
-    supportConfig: ResolvedSupportConfig;
-}
-export declare function SupportView({ supportConfig }: SupportViewProps): h.JSX.Element;
-/**
- * CSS Styles for Support View
- */
-export declare const SUPPORT_VIEW_STYLES = "\n/* ============================================================================\n   Support View\n   ============================================================================ */\n\n._pillar-support-view {\n  display: flex;\n  flex-direction: column;\n  gap: var(--pillar-spacing-md);\n  padding: var(--pillar-spacing-lg);\n  overflow-y: auto;\n}\n\n._pillar-support-card {\n  display: flex;\n  align-items: center;\n  gap: var(--pillar-spacing-md);\n  padding: var(--pillar-spacing-md) var(--pillar-spacing-lg);\n  background: var(--pillar-bg-secondary);\n  border: 1px solid var(--pillar-border);\n  border-radius: var(--pillar-radius-lg);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n  text-align: left;\n  width: 100%;\n}\n\n._pillar-support-card:hover {\n  background: var(--pillar-bg-tertiary);\n  border-color: var(--pillar-primary);\n}\n\n._pillar-support-card-icon {\n  width: 24px;\n  height: 24px;\n  color: var(--pillar-primary);\n  flex-shrink: 0;\n}\n\n._pillar-support-card-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n._pillar-support-card-content {\n  display: flex;\n  flex-direction: column;\n  flex: 1;\n  min-width: 0;\n}\n\n._pillar-support-card-title {\n  font-size: var(--pillar-font-size-base);\n  font-weight: 500;\n  color: var(--pillar-text);\n}\n\n._pillar-support-card-desc {\n  font-size: var(--pillar-font-size-sm);\n  color: var(--pillar-text-muted);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n._pillar-support-card-external {\n  width: 16px;\n  height: 16px;\n  color: var(--pillar-text-muted);\n  flex-shrink: 0;\n}\n\n._pillar-support-card-external svg {\n  width: 100%;\n  height: 100%;\n}\n\n._pillar-support-articles {\n  margin-top: var(--pillar-spacing-lg);\n  padding-top: var(--pillar-spacing-lg);\n  border-top: 1px solid var(--pillar-border);\n}\n\n._pillar-support-section-title {\n  font-size: var(--pillar-font-size-sm);\n  font-weight: 600;\n  color: var(--pillar-text-muted);\n  text-transform: uppercase;\n  letter-spacing: 0.05em;\n  margin-bottom: var(--pillar-spacing-md);\n}\n\n/* Public override classes */\n.pillar-support-view {}\n.pillar-support-card {}\n.pillar-support-card-icon {}\n.pillar-support-card-content {}\n.pillar-support-card-title {}\n.pillar-support-card-desc {}\n.pillar-support-card-external {}\n.pillar-support-articles {}\n.pillar-support-section-title {}\n";
-export {};

package/dist/utils/helpdesk.d.ts

@@ -1,33 +0,0 @@
-/**
- * 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;