mesauth-angular 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mesauth-angular",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Angular helper library to connect to a backend API and SignalR hub to surface the current logged-in user and incoming notifications with dark/light theme support",
   "keywords": [
     "angular",

package/types/mesauth-angular.d.ts

@@ -1,10 +1,10 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, EnvironmentProviders, OnDestroy, AfterViewInit, ElementRef } from '@angular/core';
+import { InjectionToken, EnvironmentProviders, AfterViewInit, OnDestroy, ElementRef, PipeTransform } from '@angular/core';
 import { HttpClient, HttpInterceptorFn, HttpResponse, HttpParams } from '@angular/common/http';
 import { Observable, OperatorFunction } from 'rxjs';
 import { Router } from '@angular/router';
-import { SafeHtml } from '@angular/platform-browser';
 import * as mesauth_angular from 'mesauth-angular';
+import { SafeHtml } from '@angular/platform-browser';
 
 interface MesAuthConfig {
     apiBaseUrl: string;
@@ -291,10 +291,12 @@ declare class UserProfileComponent {
     showBell: _angular_core.InputSignal<boolean>;
     showApproval: _angular_core.InputSignal<boolean>;
     showName: _angular_core.InputSignal<boolean>;
+    showAi: _angular_core.InputSignal<boolean>;
     showSignature: _angular_core.InputSignal<boolean[]>;
     signatureHeight: _angular_core.InputSignal<number>;
     notificationClick: _angular_core.OutputEmitterRef<void>;
     approvalClick: _angular_core.OutputEmitterRef<void>;
+    aiClick: _angular_core.OutputEmitterRef<void>;
     get themeClass(): string;
     readonly currentUser: _angular_core.WritableSignal<IUser>;
     readonly unreadCount: _angular_core.WritableSignal<number>;
@@ -317,6 +319,7 @@ declare class UserProfileComponent {
     loadUnreadCount(): void;
     loadPendingApprovalCount(): void;
     onApprovalClick(): void;
+    onAiClick(): void;
     getAvatarUrl(user: IUser): string;
     getLastNameInitial(user: IUser): string;
     toggleDropdown(): void;
@@ -329,7 +332,7 @@ declare class UserProfileComponent {
     onNotificationClick(): void;
     onSigErr(_ev: Event): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<UserProfileComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UserProfileComponent, "ma-user-profile", never, { "inputAvatarShape": { "alias": "inputAvatarShape"; "required": false; "isSignal": true; }; "showBell": { "alias": "showBell"; "required": false; "isSignal": true; }; "showApproval": { "alias": "showApproval"; "required": false; "isSignal": true; }; "showName": { "alias": "showName"; "required": false; "isSignal": true; }; "showSignature": { "alias": "showSignature"; "required": false; "isSignal": true; }; "signatureHeight": { "alias": "signatureHeight"; "required": false; "isSignal": true; }; }, { "notificationClick": "notificationClick"; "approvalClick": "approvalClick"; }, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UserProfileComponent, "ma-user-profile", never, { "inputAvatarShape": { "alias": "inputAvatarShape"; "required": false; "isSignal": true; }; "showBell": { "alias": "showBell"; "required": false; "isSignal": true; }; "showApproval": { "alias": "showApproval"; "required": false; "isSignal": true; }; "showName": { "alias": "showName"; "required": false; "isSignal": true; }; "showAi": { "alias": "showAi"; "required": false; "isSignal": true; }; "showSignature": { "alias": "showSignature"; "required": false; "isSignal": true; }; "signatureHeight": { "alias": "signatureHeight"; "required": false; "isSignal": true; }; }, { "notificationClick": "notificationClick"; "approvalClick": "approvalClick"; "aiClick": "aiClick"; }, never, ["*"], true, never>;
 }
 
 declare enum ApprovalStepMode {
@@ -556,6 +559,195 @@ declare class MaApprovalPanelComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaApprovalPanelComponent, "ma-approval-panel", never, {}, { "approvalActioned": "approvalActioned"; }, never, never, true, never>;
 }
 
+/**
+ * Public AI types exported from mesauth-angular.
+ *
+ * The library ships a chat panel that talks to MesAuth.Api's /ai/chat SSE endpoint.
+ * Consumer apps may register additional client-side tools that the AI can invoke
+ * to drive their UI (navigation, dialogs, etc.) via provideMesAuthAi().
+ */
+/**
+ * A tool the host app registers. The AI may call it; the handler runs in the browser
+ * with the application's DI container available via Angular's inject() in the handler.
+ *
+ * `parameters` is a JSON schema (object type). Use `readOnly: true` to skip the
+ * confirm card for safe operations like navigation. Anything that mutates server state
+ * or is hard to undo should have readOnly: false (default).
+ */
+interface ClientTool {
+    name: string;
+    description: string;
+    parameters: ClientToolSchema;
+    readOnly?: boolean;
+    /**
+     * Handler executed when the AI calls this tool.
+     * Return a string (or anything JSON-serializable) describing the outcome; this is
+     * fed back to the AI as the tool result. Throw to signal failure.
+     */
+    handler: (args: any) => Promise<unknown> | unknown;
+}
+interface ClientToolSchema {
+    type: 'object';
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [k: string]: unknown;
+}
+/** A single message in the chat panel UI (different from the on-wire format). */
+interface ChatBubble {
+    id: string;
+    role: 'user' | 'assistant' | 'tool';
+    /** Plain-text content (assistant + user). For tool: short summary. */
+    text: string;
+    /** Server tool calls that ran in this assistant turn (rendered as chips). */
+    toolEvents?: ChatToolEvent[];
+    pending?: boolean;
+}
+interface ChatToolEvent {
+    id: string;
+    name: string;
+    side: 'server' | 'client';
+    status: 'running' | 'ok' | 'error' | 'awaiting-approval' | 'declined';
+    summary?: string;
+    args?: any;
+    readOnly?: boolean;
+}
+/** Stream event types matching MesAuth.Api's AiStreamEvent JSON. */
+type AiSseEvent = {
+    type: 'session';
+    sessionId: string;
+} | {
+    type: 'token';
+    text: string;
+} | {
+    type: 'tool_call_started';
+    id: string;
+    name: string;
+    args: any;
+    side: 'server' | 'client';
+    readOnly?: boolean;
+} | {
+    type: 'tool_call_completed';
+    id: string;
+    ok: boolean;
+    summary?: string;
+} | {
+    type: 'client_tool_call';
+    id: string;
+    name: string;
+    args: any;
+    side: 'client';
+    readOnly?: boolean;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+};
+
+interface PendingApproval {
+    callId: string;
+    name: string;
+    args: any;
+    side: 'client';
+}
+/**
+ * Drives the chat panel.
+ *
+ * Uses `fetch` + `ReadableStream` (not `EventSource`, which can't POST a body) to talk to
+ * `/ai/chat` SSE. State lives in signals so the panel can re-render reactively.
+ */
+declare class MaAiService {
+    private readonly auth;
+    private readonly aiConfig;
+    private readonly tools;
+    readonly messages: _angular_core.WritableSignal<ChatBubble[]>;
+    readonly streaming: _angular_core.WritableSignal<boolean>;
+    /** When non-null, a write-class client tool is awaiting user confirmation. */
+    readonly pendingApproval: _angular_core.WritableSignal<PendingApproval>;
+    readonly lastError: _angular_core.WritableSignal<string>;
+    private sessionId;
+    /** Verbs the user already chose "always approve" for in this session. */
+    private alwaysApproved;
+    private abortController;
+    /** ID of the current assistant bubble we're streaming tokens into. */
+    private currentAssistantId;
+    get enabled(): boolean;
+    /** Start a brand-new conversation. */
+    resetSession(): void;
+    /** Cancel the in-flight stream (if any). The session id is preserved so the user can resume. */
+    cancel(): void;
+    /** User typed and submitted a message. */
+    send(text: string, currentRoute?: string): Promise<void>;
+    /**
+     * Approve (or decline) a pending client tool call. If approved (and alwaysApprove),
+     * remember the verb so we skip the prompt next time in this session.
+     */
+    resolvePendingApproval(decision: 'approve' | 'always' | 'decline'): Promise<void>;
+    private runStream;
+    private readSse;
+    private handleEvent;
+    private executeClientTool;
+    private continueWithToolResult;
+    private appendBubble;
+    private appendToken;
+    private appendToolEvent;
+    private markToolStatus;
+    private finalizeAssistant;
+    private verbOf;
+    private summarize;
+    private uid;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaAiService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MaAiService>;
+}
+
+/**
+ * Right-side, resizable chat drawer. Open/close via the public open/close/toggle methods.
+ * Uses panel-shared.css for the header/empty-state styling so it looks like the approval
+ * and notification panels.
+ */
+declare class MaAiChatPanelComponent implements AfterViewInit {
+    readonly isOpen: _angular_core.WritableSignal<boolean>;
+    readonly width: _angular_core.WritableSignal<number>;
+    readonly draft: _angular_core.WritableSignal<string>;
+    readonly ai: MaAiService;
+    private readonly router;
+    private readonly themeService;
+    private readonly uiConfig;
+    /** Suggested prompts shown in the empty state — manifest overridable. */
+    readonly quickPrompts: _angular_core.Signal<string[]>;
+    private readonly scrollContainer;
+    private readonly textArea;
+    get themeClass(): string;
+    readonly messages: _angular_core.WritableSignal<mesauth_angular.ChatBubble[]>;
+    readonly streaming: _angular_core.WritableSignal<boolean>;
+    readonly pendingApproval: _angular_core.WritableSignal<mesauth_angular.PendingApproval>;
+    readonly lastError: _angular_core.WritableSignal<string>;
+    readonly hasMessages: _angular_core.Signal<boolean>;
+    private isDragging;
+    private dragStartX;
+    private dragStartWidth;
+    constructor();
+    ngAfterViewInit(): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    newConversation(): void;
+    send(): void;
+    cancel(): void;
+    onTextareaKey(ev: KeyboardEvent): void;
+    onTextareaInput(ev: Event): void;
+    approve(): void;
+    alwaysApprove(): void;
+    decline(): void;
+    startResize(ev: PointerEvent): void;
+    onResizeMove(ev: PointerEvent): void;
+    endResize(ev: PointerEvent): void;
+    private loadWidth;
+    private scrollToBottom;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaAiChatPanelComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaAiChatPanelComponent, "ma-ai-chat-panel", never, {}, {}, never, never, true, never>;
+}
+
 type Theme = 'light' | 'dark';
 declare class ThemeService implements OnDestroy {
     private readonly _currentTheme;
@@ -580,9 +772,11 @@ declare class ThemeService implements OnDestroy {
 declare class MaUserComponent implements AfterViewInit {
     userProfile?: UserProfileComponent;
     approvalPanel: MaApprovalPanelComponent;
+    aiPanel?: MaAiChatPanelComponent;
     avatarShape: _angular_core.InputSignal<"circle" | "rounded" | "rectangle">;
     showBell: _angular_core.InputSignal<boolean>;
     showApproval: _angular_core.InputSignal<boolean>;
+    showAi: _angular_core.InputSignal<boolean>;
     showName: _angular_core.InputSignal<boolean>;
     showSignature: _angular_core.InputSignal<boolean[]>;
     theme: _angular_core.InputSignal<"light" | "dark">;
@@ -592,7 +786,7 @@ declare class MaUserComponent implements AfterViewInit {
     onNotificationRead(): void;
     onApprovalActioned(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaUserComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaUserComponent, "ma-user", never, { "avatarShape": { "alias": "avatarShape"; "required": false; "isSignal": true; }; "showBell": { "alias": "showBell"; "required": false; "isSignal": true; }; "showApproval": { "alias": "showApproval"; "required": false; "isSignal": true; }; "showName": { "alias": "showName"; "required": false; "isSignal": true; }; "showSignature": { "alias": "showSignature"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaUserComponent, "ma-user", never, { "avatarShape": { "alias": "avatarShape"; "required": false; "isSignal": true; }; "showBell": { "alias": "showBell"; "required": false; "isSignal": true; }; "showApproval": { "alias": "showApproval"; "required": false; "isSignal": true; }; "showAi": { "alias": "showAi"; "required": false; "isSignal": true; }; "showName": { "alias": "showName"; "required": false; "isSignal": true; }; "showSignature": { "alias": "showSignature"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
 declare class MaUserXComponent {
@@ -853,9 +1047,11 @@ interface MaUiManifest {
     labels?: Record<string, string>;
     /** Feature flags read by components at runtime. */
     features?: Record<string, boolean>;
+    /** Suggested prompts shown in the AI panel empty state. Overrides the library default. */
+    quickPrompts?: string[];
 }
 /** Current installed package version — keep in sync with package.json. */
-declare const PACKAGE_VERSION = "1.18.0";
+declare const PACKAGE_VERSION = "1.19.0";
 /**
  * Provides server-driven UI configuration loaded from the hosted manifest.
  * Components read `labels()` and `features()` signals instead of hardcoded strings.
@@ -867,6 +1063,7 @@ declare class MaUiConfigService {
     private _features;
     private _updateRequired;
     private _manifestVersion;
+    private _quickPrompts;
     /** Reactive map of UI string overrides from the server manifest. */
     readonly labels: _angular_core.Signal<Record<string, string>>;
     /** Reactive map of feature flags from the server manifest. */
@@ -875,6 +1072,8 @@ declare class MaUiConfigService {
     readonly updateRequired: _angular_core.Signal<boolean>;
     /** The manifest version string loaded from the server, or null if not yet loaded. */
     readonly manifestVersion: _angular_core.Signal<string>;
+    /** AI panel "quick prompts" — populated from the manifest if provided, else empty. */
+    readonly quickPrompts: _angular_core.Signal<string[]>;
     /**
      * Returns a label by key, falling back to `defaultValue` when the server
      * manifest has not provided an override.
@@ -983,5 +1182,108 @@ declare function runSsoCheckHandshake(authService: MesAuthService): Promise<void
  */
 declare function runReturnViaPostMessageIfRequested(authService: MesAuthService): Promise<boolean>;
 
-export { ALL_ACTIONS, AVATAR_FRAMES, ApprovalActionType, ApprovalDocumentStatus, ApprovalStepMode, ApprovalStepStatus, MES_AUTH_CONFIG, MaApprovalPanelComponent, MaApprovalService, MaArvContainerComponent, MaAvatarComponent, MaIconComponent, MaThemeDirective, MaUiConfigService, MaUserComponent, MaUserMenuColor, MaUserMenuComponent, MaUserXComponent, MesAuthModule, MesAuthService, NotificationBadgeComponent, NotificationPanelComponent, NotificationType, PACKAGE_VERSION, ThemeService, ToastContainerComponent, ToastService, UserProfileComponent, extractXMaPerm, mesAuthInterceptor, provideMesAuth, runReturnViaPostMessageIfRequested, runSsoCheckHandshake, withXMaPerm, xMaResource };
-export type { ApprovalDashboardDto, ApprovalDocumentDto, ApprovalDocumentSummaryDto, ApprovalHistoryDto, ApprovalReferenceDto, ApprovalStepDto, ApprovalStepRequest, ApprovalSubmitResult, ApprovalTemplateDto, ApprovalTemplateStepDto, ApprovalTemplateSummaryDto, ApproveRejectRequest, AvatarFrameDef, AvatarShape, AvatarSize, CreateApprovalRequest, CreateApprovalResponseDto, CreateApprovalTemplateRequest, DelegateRequest, FrontEndRoute, IUser, MaUiManifest, MesAuthConfig, NotificationDto, PagedList, PermissionHeader, RealTimeNotificationDto, RequestConfig, RolePreviewUserDto, StepRoleDto, Theme, Toast, UpdateApprovalTemplateRequest, UserFrontEndRoutesGrouped };
+interface MesAuthAiConfig {
+    /** Master switch — when false the Ask-AI button hides and the panel never opens. */
+    enabled?: boolean;
+    /**
+     * Extra client-side tools the AI can invoke. The handler runs in the browser.
+     * The library always exposes a set of built-in client tools (navigate, toggle theme, etc.)
+     * — these are merged in addition.
+     */
+    tools?: ClientTool[];
+    /**
+     * Optional extra paragraphs appended to the backend system prompt for this app.
+     * Use to tell the AI what domain the consumer app handles (e.g. "You are inside the SPC app").
+     */
+    systemPromptExtensions?: string[];
+    /**
+     * Optional friendly name of the host app; sent to the backend each turn.
+     */
+    appName?: string;
+}
+declare const MES_AUTH_AI_CONFIG: InjectionToken<MesAuthAiConfig>;
+/** Default configuration when the consumer doesn't call provideMesAuthAi(). */
+declare const DEFAULT_AI_CONFIG: MesAuthAiConfig;
+/**
+ * Provide AI assistant configuration to mesauth-angular.
+ *
+ * @example
+ * ```ts
+ * providers: [
+ *   provideMesAuth(...),
+ *   provideMesAuthAi({
+ *     enabled: true,
+ *     appName: 'MesExtensionSite',
+ *     tools: [
+ *       {
+ *         name: 'spc_open_chart',
+ *         description: 'Open the SPC chart for a given product line',
+ *         parameters: {
+ *           type: 'object',
+ *           properties: { lineId: { type: 'string' } },
+ *           required: ['lineId']
+ *         },
+ *         readOnly: true,
+ *         handler: (args) => inject(Router).navigateByUrl(`/spc/${args.lineId}`)
+ *       }
+ *     ]
+ *   })
+ * ]
+ * ```
+ */
+declare function provideMesAuthAi(config: MesAuthAiConfig): EnvironmentProviders;
+
+/**
+ * Resolves the full set of client tools available to the AI: built-ins + consumer-registered.
+ * Handlers are invoked through `runTool(name, args)` which automatically threads the Injector
+ * so consumer handlers can use inject() patterns.
+ */
+declare class MaAiToolsRegistry {
+    private readonly config;
+    private readonly injector;
+    /** Built-in client tools shipped by the library. */
+    private readonly builtIn;
+    /** All tools, deduplicated by name (consumer wins on conflict). */
+    list(): ClientTool[];
+    resolve(name: string): ClientTool | undefined;
+    /** Run a registered client tool and serialize its result for posting back to the agent loop. */
+    runTool(name: string, args: any): Promise<{
+        ok: boolean;
+        result: string;
+    }>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaAiToolsRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MaAiToolsRegistry>;
+}
+
+declare class MaAiButtonComponent {
+    private readonly config;
+    readonly enabled: _angular_core.Signal<boolean>;
+    clicked: _angular_core.OutputEmitterRef<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaAiButtonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaAiButtonComponent, "ma-ai-button", never, {}, { "clicked": "clicked"; }, never, never, true, never>;
+}
+
+/**
+ * Tiny hand-rolled GitHub-flavoured Markdown renderer for AI chat bubbles.
+ *
+ * Supports: headings, paragraphs (with single-newline → <br>), pipe tables,
+ * fenced + inline code, bullet/ordered lists (flat), blockquotes, bold, italic,
+ * autolinks via [text](url). All input is HTML-escaped before any markup
+ * is added, so the only HTML that reaches the DOM is what this pipe emits.
+ * Wrapped in `bypassSecurityTrustHtml` so [innerHTML] doesn't re-sanitize and
+ * strip the markup we explicitly want.
+ *
+ * Not supported (intentionally — keeps the renderer tiny and safe):
+ * nested lists, images, raw HTML, strikethrough, task lists, footnotes.
+ * If the model emits any of those, they appear as literal text.
+ */
+declare class MaAiMarkdownPipe implements PipeTransform {
+    private readonly sanitizer;
+    transform(value: string | null | undefined): SafeHtml;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaAiMarkdownPipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<MaAiMarkdownPipe, "maAiMarkdown", true>;
+}
+declare function renderMarkdown(src: string): string;
+
+export { ALL_ACTIONS, AVATAR_FRAMES, ApprovalActionType, ApprovalDocumentStatus, ApprovalStepMode, ApprovalStepStatus, DEFAULT_AI_CONFIG, MES_AUTH_AI_CONFIG, MES_AUTH_CONFIG, MaAiButtonComponent, MaAiChatPanelComponent, MaAiMarkdownPipe, MaAiService, MaAiToolsRegistry, MaApprovalPanelComponent, MaApprovalService, MaArvContainerComponent, MaAvatarComponent, MaIconComponent, MaThemeDirective, MaUiConfigService, MaUserComponent, MaUserMenuColor, MaUserMenuComponent, MaUserXComponent, MesAuthModule, MesAuthService, NotificationBadgeComponent, NotificationPanelComponent, NotificationType, PACKAGE_VERSION, ThemeService, ToastContainerComponent, ToastService, UserProfileComponent, extractXMaPerm, mesAuthInterceptor, provideMesAuth, provideMesAuthAi, renderMarkdown, runReturnViaPostMessageIfRequested, runSsoCheckHandshake, withXMaPerm, xMaResource };
+export type { AiSseEvent, ApprovalDashboardDto, ApprovalDocumentDto, ApprovalDocumentSummaryDto, ApprovalHistoryDto, ApprovalReferenceDto, ApprovalStepDto, ApprovalStepRequest, ApprovalSubmitResult, ApprovalTemplateDto, ApprovalTemplateStepDto, ApprovalTemplateSummaryDto, ApproveRejectRequest, AvatarFrameDef, AvatarShape, AvatarSize, ChatBubble, ChatToolEvent, ClientTool, ClientToolSchema, CreateApprovalRequest, CreateApprovalResponseDto, CreateApprovalTemplateRequest, DelegateRequest, FrontEndRoute, IUser, MaUiManifest, MesAuthAiConfig, MesAuthConfig, NotificationDto, PagedList, PendingApproval, PermissionHeader, RealTimeNotificationDto, RequestConfig, RolePreviewUserDto, StepRoleDto, Theme, Toast, UpdateApprovalTemplateRequest, UserFrontEndRoutesGrouped };