@pillar-ai/angular 0.1.11

package/dist/fesm2022/pillar-ai-angular.mjs

@@ -0,0 +1,695 @@
+import * as i0 from '@angular/core';
+import { inject, NgZone, ApplicationRef, EnvironmentInjector, signal, computed, createComponent, Injectable, input, effect, ViewChild, ChangeDetectionStrategy, Component, DestroyRef } from '@angular/core';
+import { Pillar } from '@pillar-ai/sdk';
+
+/**
+ * PillarService
+ * Angular service that initializes and manages the Pillar SDK
+ */
+class PillarService {
+    ngZone = inject(NgZone);
+    appRef = inject(ApplicationRef);
+    environmentInjector = inject(EnvironmentInjector);
+    // Internal state
+    _pillar = signal(null);
+    cleanupFns = [];
+    cardRefs = new Map();
+    onTaskCallback = null;
+    registeredCards = null;
+    // Public signals
+    state = signal('uninitialized');
+    isReady = computed(() => this.state() === 'ready');
+    isPanelOpen = signal(false);
+    /**
+     * Get the Pillar SDK instance.
+     */
+    getInstance() {
+        return this._pillar();
+    }
+    /**
+     * Initialize the Pillar SDK.
+     * Call this in your app's initialization (e.g., APP_INITIALIZER).
+     *
+     * @param initConfig - Configuration options
+     */
+    async init(initConfig) {
+        const { productKey, helpCenter, config, onTask, cards } = initConfig;
+        // Support both productKey (new) and helpCenter (deprecated)
+        const resolvedKey = productKey ?? helpCenter;
+        if (helpCenter && !productKey) {
+            console.warn('[Pillar Angular] "helpCenter" is deprecated. Use "productKey" instead.');
+        }
+        // Store callbacks for later use
+        this.onTaskCallback = onTask ?? null;
+        this.registeredCards = cards ?? null;
+        try {
+            // Pillar is a singleton - check if already initialized
+            const existingInstance = Pillar.getInstance();
+            if (existingInstance) {
+                // Reuse existing instance (preserves chat history, panel state, etc.)
+                this._pillar.set(existingInstance);
+                this.state.set(existingInstance.state);
+                this.subscribeToEvents(existingInstance);
+                this.registerCards(existingInstance);
+                return;
+            }
+            // Initialize new instance
+            const instance = await Pillar.init({
+                productKey: resolvedKey,
+                ...config,
+            });
+            this.ngZone.run(() => {
+                this._pillar.set(instance);
+                this.state.set(instance.state);
+            });
+            this.subscribeToEvents(instance);
+            this.registerCards(instance);
+        }
+        catch (error) {
+            console.error('[Pillar Angular] Failed to initialize:', error);
+            this.ngZone.run(() => {
+                this.state.set('error');
+            });
+            throw error;
+        }
+    }
+    /**
+     * Subscribe to SDK events and sync to Angular signals.
+     */
+    subscribeToEvents(instance) {
+        // Panel open/close events
+        const unsubOpen = instance.on('panel:open', () => {
+            this.ngZone.run(() => {
+                this.isPanelOpen.set(true);
+            });
+        });
+        this.cleanupFns.push(unsubOpen);
+        const unsubClose = instance.on('panel:close', () => {
+            this.ngZone.run(() => {
+                this.isPanelOpen.set(false);
+            });
+        });
+        this.cleanupFns.push(unsubClose);
+        // State change events
+        const unsubReady = instance.on('ready', () => {
+            this.ngZone.run(() => {
+                this.state.set('ready');
+            });
+        });
+        this.cleanupFns.push(unsubReady);
+        const unsubError = instance.on('error', () => {
+            this.ngZone.run(() => {
+                this.state.set('error');
+            });
+        });
+        this.cleanupFns.push(unsubError);
+        // Task execution events
+        if (this.onTaskCallback) {
+            const callback = this.onTaskCallback;
+            const unsubTask = instance.on('task:execute', (task) => {
+                this.ngZone.run(() => {
+                    callback(task);
+                });
+            });
+            this.cleanupFns.push(unsubTask);
+        }
+    }
+    /**
+     * Register custom card components.
+     */
+    registerCards(instance) {
+        if (!this.registeredCards)
+            return;
+        Object.entries(this.registeredCards).forEach(([cardType, CardComponent]) => {
+            const unsubscribe = instance.registerCard(cardType, (container, data, callbacks) => {
+                // Create an Angular component dynamically
+                const componentRef = createComponent(CardComponent, {
+                    environmentInjector: this.environmentInjector,
+                });
+                // Set inputs
+                componentRef.setInput('data', data);
+                componentRef.setInput('onConfirm', callbacks.onConfirm);
+                componentRef.setInput('onCancel', callbacks.onCancel);
+                componentRef.setInput('onStateChange', callbacks.onStateChange);
+                // Attach to the application
+                this.appRef.attachView(componentRef.hostView);
+                // Append to container
+                container.appendChild(componentRef.location.nativeElement);
+                this.cardRefs.set(container, componentRef);
+                // Return cleanup function
+                return () => {
+                    const ref = this.cardRefs.get(container);
+                    if (ref) {
+                        this.appRef.detachView(ref.hostView);
+                        ref.destroy();
+                        this.cardRefs.delete(container);
+                    }
+                };
+            });
+            this.cleanupFns.push(unsubscribe);
+        });
+    }
+    /**
+     * Open the help panel.
+     */
+    open(options) {
+        this._pillar()?.open(options);
+    }
+    /**
+     * Close the help panel.
+     */
+    close() {
+        this._pillar()?.close();
+    }
+    /**
+     * Toggle the help panel.
+     */
+    toggle() {
+        this._pillar()?.toggle();
+    }
+    /**
+     * Open a specific article.
+     */
+    openArticle(slug) {
+        this._pillar()?.open({ article: slug });
+    }
+    /**
+     * Open a specific category.
+     */
+    async openCategory(slug) {
+        this._pillar()?.navigate('category', { slug });
+    }
+    /**
+     * Perform a search.
+     */
+    search(query) {
+        this._pillar()?.open({ search: query });
+    }
+    /**
+     * Navigate to a specific view.
+     */
+    navigate(view, params) {
+        this._pillar()?.navigate(view, params);
+    }
+    /**
+     * Update the panel theme at runtime.
+     */
+    setTheme(theme) {
+        this._pillar()?.setTheme(theme);
+    }
+    /**
+     * Enable or disable the text selection "Ask AI" popover.
+     */
+    setTextSelectionEnabled(enabled) {
+        this._pillar()?.setTextSelectionEnabled(enabled);
+    }
+    /**
+     * Subscribe to SDK events.
+     */
+    on(event, callback) {
+        const pillar = this._pillar();
+        if (!pillar) {
+            return () => { };
+        }
+        // Wrap callback to run in Angular zone
+        const wrappedCallback = (data) => {
+            this.ngZone.run(() => callback(data));
+        };
+        return pillar.on(event, wrappedCallback);
+    }
+    /**
+     * Register a task handler.
+     */
+    onTask(taskName, handler) {
+        const pillar = this._pillar();
+        if (!pillar) {
+            return () => { };
+        }
+        // Wrap handler to run in Angular zone
+        const wrappedHandler = (data) => {
+            this.ngZone.run(() => handler(data));
+        };
+        return pillar.onTask(taskName, wrappedHandler);
+    }
+    /**
+     * Define a tool with metadata and handler.
+     * Returns an unsubscribe function to remove the tool.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = pillarService.defineTool({
+     *   name: 'add_to_cart',
+     *   description: 'Add a product to the shopping cart',
+     *   inputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       productId: { type: 'string' },
+     *       quantity: { type: 'number' },
+     *     },
+     *     required: ['productId', 'quantity'],
+     *   },
+     *   execute: async ({ productId, quantity }) => {
+     *     await this.cartService.add(productId, quantity);
+     *     return { content: [{ type: 'text', text: 'Added to cart' }] };
+     *   },
+     * });
+     *
+     * // Later, to unregister:
+     * unsubscribe();
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    defineTool(schema) {
+        const pillar = this._pillar();
+        if (!pillar) {
+            console.warn('[Pillar Angular] Cannot define tool - SDK not initialized');
+            return () => { };
+        }
+        // Wrap execute to run in Angular zone
+        const wrappedSchema = {
+            ...schema,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            execute: async (input) => {
+                return this.ngZone.run(() => schema.execute(input));
+            },
+        };
+        return pillar.defineTool(wrappedSchema);
+    }
+    /**
+     * Mount the panel to a specific container element.
+     * Used for manual panel placement with PillarPanelComponent.
+     */
+    mountPanelTo(container) {
+        this._pillar()?.mountPanelTo(container);
+    }
+    /**
+     * Cleanup resources.
+     * Note: We intentionally don't call Pillar.destroy() here to preserve
+     * conversation history across route changes. Call Pillar.destroy()
+     * explicitly if you need to fully reset the SDK.
+     */
+    ngOnDestroy() {
+        // Run all cleanup functions
+        this.cleanupFns.forEach((cleanup) => cleanup());
+        this.cleanupFns.length = 0;
+        // Destroy all card component refs
+        this.cardRefs.forEach((ref) => {
+            this.appRef.detachView(ref.hostView);
+            ref.destroy();
+        });
+        this.cardRefs.clear();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PillarService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PillarService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PillarService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * PillarPanelComponent
+ * Renders the Pillar help panel at a custom location in the DOM
+ */
+/**
+ * Renders the Pillar help panel at a custom location in the DOM.
+ * Use this when you want to control where the panel is rendered instead of
+ * having it automatically appended to document.body.
+ *
+ * **Important**: When using this component, set `panel.container: 'manual'` in your
+ * Pillar configuration to prevent automatic mounting.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * function initPillar() {
+ *   const pillar = inject(PillarService);
+ *   return () => pillar.init({
+ *     productKey: 'your-product-key',
+ *     config: { panel: { container: 'manual' } }
+ *   });
+ * }
+ *
+ * // layout.component.ts
+ * @Component({
+ *   selector: 'app-layout',
+ *   standalone: true,
+ *   imports: [PillarPanelComponent],
+ *   template: `
+ *     <div class="layout">
+ *       <app-sidebar />
+ *       <pillar-panel class="help-panel-container" />
+ *       <main>
+ *         <router-outlet />
+ *       </main>
+ *     </div>
+ *   `,
+ * })
+ * export class LayoutComponent {}
+ * ```
+ */
+class PillarPanelComponent {
+    containerRef;
+    pillarService = inject(PillarService);
+    hasMounted = false;
+    effectRef = null;
+    /**
+     * Optional class to add to the container element.
+     * Use host binding for styling instead if possible.
+     */
+    containerClass = input('');
+    ngAfterViewInit() {
+        // Use effect to react to isReady signal changes
+        this.effectRef = effect(() => {
+            const isReady = this.pillarService.isReady();
+            if (isReady && !this.hasMounted && this.containerRef?.nativeElement) {
+                this.pillarService.mountPanelTo(this.containerRef.nativeElement);
+                this.hasMounted = true;
+            }
+        });
+    }
+    ngOnDestroy() {
+        // Effect is automatically cleaned up when component is destroyed
+        // Panel cleanup is handled by PillarService
+        this.effectRef?.destroy();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PillarPanelComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "17.3.12", type: PillarPanelComponent, isStandalone: true, selector: "pillar-panel", inputs: { containerClass: { classPropertyName: "containerClass", publicName: "containerClass", isSignal: true, isRequired: false, transformFunction: null } }, viewQueries: [{ propertyName: "containerRef", first: true, predicate: ["container"], descendants: true, static: true }], ngImport: i0, template: '<div #container data-pillar-panel-container></div>', isInline: true, styles: [":host{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PillarPanelComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'pillar-panel', standalone: true, template: '<div #container data-pillar-panel-container></div>', changeDetection: ChangeDetectionStrategy.OnPush, styles: [":host{display:block}\n"] }]
+        }], propDecorators: { containerRef: [{
+                type: ViewChild,
+                args: ['container', { static: true }]
+            }] } });
+
+/**
+ * injectPillar Function
+ * Angular-idiomatic injection helper for accessing Pillar SDK
+ */
+/**
+ * Angular injection function to access the Pillar SDK.
+ * Use this in components, directives, or services to interact with Pillar.
+ *
+ * Must be called within an injection context (constructor, field initializer, or inject()).
+ *
+ * @example Basic usage (untyped)
+ * ```typescript
+ * @Component({
+ *   selector: 'app-help-button',
+ *   standalone: true,
+ *   template: `
+ *     <button (click)="toggle()">
+ *       {{ isPanelOpen() ? 'Close Help' : 'Get Help' }}
+ *     </button>
+ *   `,
+ * })
+ * export class HelpButtonComponent {
+ *   private pillar = injectPillar();
+ *   isPanelOpen = this.pillar.isPanelOpen;
+ *   toggle = this.pillar.toggle;
+ * }
+ * ```
+ *
+ * @example Type-safe onTask with action definitions
+ * ```typescript
+ * import { actions } from '@/lib/pillar/actions';
+ *
+ * @Component({...})
+ * export class MyComponent implements OnInit, OnDestroy {
+ *   private pillar = injectPillar<typeof actions>();
+ *   private unsubscribe?: () => void;
+ *
+ *   ngOnInit() {
+ *     // TypeScript knows data has the correct shape
+ *     this.unsubscribe = this.pillar.onTask('add_new_source', (data) => {
+ *       console.log(data.url); // ✓ Typed!
+ *     });
+ *   }
+ *
+ *   ngOnDestroy() {
+ *     this.unsubscribe?.();
+ *   }
+ * }
+ * ```
+ */
+function injectPillar() {
+    const service = inject(PillarService);
+    // Create a type-safe wrapper around pillar.onTask
+    const onTask = (taskName, handler) => {
+        // Cast handler to match the SDK's expected type
+        // The runtime behavior is the same, this is just for type narrowing
+        return service.onTask(taskName, handler);
+    };
+    return {
+        pillar: () => service.getInstance(),
+        state: service.state,
+        isReady: service.isReady,
+        isPanelOpen: service.isPanelOpen,
+        open: service.open.bind(service),
+        close: service.close.bind(service),
+        toggle: service.toggle.bind(service),
+        openArticle: service.openArticle.bind(service),
+        openCategory: service.openCategory.bind(service),
+        search: service.search.bind(service),
+        navigate: service.navigate.bind(service),
+        setTheme: service.setTheme.bind(service),
+        setTextSelectionEnabled: service.setTextSelectionEnabled.bind(service),
+        on: service.on.bind(service),
+        onTask,
+    };
+}
+
+/**
+ * injectHelpPanel Function
+ * Angular injection helper for panel-specific controls
+ */
+/**
+ * Angular injection function for panel-specific controls.
+ * Provides a simplified API focused on panel operations.
+ *
+ * Must be called within an injection context (constructor, field initializer, or inject()).
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-help-menu',
+ *   standalone: true,
+ *   template: `
+ *     <div>
+ *       <button (click)="toggle()">
+ *         {{ isOpen() ? 'Close' : 'Help' }}
+ *       </button>
+ *       <button (click)="openChat()">Ask AI</button>
+ *     </div>
+ *   `,
+ * })
+ * export class HelpMenuComponent {
+ *   private panel = injectHelpPanel();
+ *   isOpen = this.panel.isOpen;
+ *   toggle = this.panel.toggle;
+ *   openChat = this.panel.openChat;
+ * }
+ * ```
+ */
+function injectHelpPanel() {
+    const service = inject(PillarService);
+    const openSearch = (query) => {
+        if (query) {
+            service.search(query);
+        }
+        else {
+            service.open({ view: 'search' });
+        }
+    };
+    const openChat = () => {
+        service.navigate('chat');
+    };
+    return {
+        isOpen: computed(() => service.isPanelOpen()),
+        open: service.open.bind(service),
+        close: service.close.bind(service),
+        toggle: service.toggle.bind(service),
+        openArticle: service.openArticle.bind(service),
+        openCategory: service.openCategory.bind(service),
+        openSearch,
+        openChat,
+    };
+}
+
+/**
+ * injectPillarTool Function
+ * Angular-idiomatic injection helper for registering Pillar tools
+ *
+ * Register one or more tools with co-located metadata and handlers.
+ * Tools are registered when called and automatically unregistered
+ * when the component is destroyed.
+ *
+ * @example Single tool
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectPillarTool } from '@pillar-ai/angular';
+ *
+ * @Component({
+ *   selector: 'app-cart-button',
+ *   standalone: true,
+ *   template: `<button>Cart</button>`,
+ * })
+ * export class CartButtonComponent {
+ *   constructor() {
+ *     injectPillarTool({
+ *       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' }] };
+ *       },
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Multiple tools
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { injectPillarTool } from '@pillar-ai/angular';
+ *
+ * @Component({
+ *   selector: 'app-billing-page',
+ *   standalone: true,
+ *   template: `<div>Billing Content</div>`,
+ * })
+ * export class BillingPageComponent {
+ *   constructor() {
+ *     injectPillarTool([
+ *       {
+ *         name: 'get_current_plan',
+ *         description: 'Get the current billing plan',
+ *         execute: async () => ({ plan: 'pro', price: 29 }),
+ *       },
+ *       {
+ *         name: 'upgrade_plan',
+ *         description: 'Upgrade to a higher plan',
+ *         inputSchema: {
+ *           type: 'object',
+ *           properties: { planId: { type: 'string' } },
+ *           required: ['planId'],
+ *         },
+ *         execute: async ({ planId }) => {
+ *           await billingApi.upgrade(planId);
+ *           return { content: [{ type: 'text', text: 'Upgraded!' }] };
+ *         },
+ *       },
+ *     ]);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Register one or more Pillar tools with co-located metadata and handlers.
+ *
+ * The tools are registered when this function is called and automatically
+ * unregistered when the component is destroyed. Must be called within
+ * an injection context (constructor, field initializer, or inject()).
+ *
+ * @param schemaOrSchemas - Single tool schema or array of tool schemas
+ */
+function injectPillarTool(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+schemaOrSchemas) {
+    const service = inject(PillarService);
+    const destroyRef = inject(DestroyRef);
+    // Normalize to array for consistent handling
+    const schemas = Array.isArray(schemaOrSchemas)
+        ? schemaOrSchemas
+        : [schemaOrSchemas];
+    // Track unsubscribe functions
+    const unsubscribes = [];
+    // Register all tools
+    schemas.forEach((schema) => {
+        const unsub = service.defineTool(schema);
+        unsubscribes.push(unsub);
+    });
+    // Cleanup on destroy
+    destroyRef.onDestroy(() => {
+        unsubscribes.forEach((unsub) => unsub());
+    });
+}
+/** @deprecated Use injectPillarTool instead */
+const injectPillarAction = injectPillarTool;
+
+/**
+ * @pillar-ai/angular - Angular bindings for Pillar SDK
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { ApplicationConfig, APP_INITIALIZER, inject } from '@angular/core';
+ * import { PillarService } from '@pillar-ai/angular';
+ *
+ * function initPillar() {
+ *   const pillar = inject(PillarService);
+ *   return () => pillar.init({ productKey: 'your-product-key' });
+ * }
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     { provide: APP_INITIALIZER, useFactory: initPillar, multi: true },
+ *   ],
+ * };
+ *
+ * // help-button.component.ts
+ * import { Component } from '@angular/core';
+ * import { injectPillar } from '@pillar-ai/angular';
+ *
+ * @Component({
+ *   selector: 'app-help-button',
+ *   standalone: true,
+ *   template: `
+ *     <button (click)="toggle()">
+ *       {{ isPanelOpen() ? 'Close Help' : 'Get Help' }}
+ *     </button>
+ *   `,
+ * })
+ * export class HelpButtonComponent {
+ *   private pillar = injectPillar();
+ *   isPanelOpen = this.pillar.isPanelOpen;
+ *   toggle = this.pillar.toggle;
+ * }
+ *
+ * // Custom panel placement example:
+ * // layout.component.ts
+ * import { Component } from '@angular/core';
+ * import { PillarPanelComponent } from '@pillar-ai/angular';
+ *
+ * @Component({
+ *   selector: 'app-layout',
+ *   standalone: true,
+ *   imports: [PillarPanelComponent],
+ *   template: `
+ *     <div class="layout">
+ *       <pillar-panel class="custom-panel" />
+ *       <main>Your content</main>
+ *     </div>
+ *   `,
+ * })
+ * export class LayoutComponent {}
+ * ```
+ */
+// Service
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { PillarPanelComponent, PillarService, injectHelpPanel, injectPillar, injectPillarAction, injectPillarTool };
+//# sourceMappingURL=pillar-ai-angular.mjs.map