mesauth-angular 1.20.0 → 1.21.0

package/README.md

@@ -4,6 +4,21 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
 
 ## Changelog
 
+### v1.21.0 (2026-05-16) — **AI Assistant integration docs**
+- Documentation only: full integration guide for the AI Assistant module added below ([jump](#ai-assistant)). CHANGELOG backfilled for v1.19.0 + v1.20.0 entries.
+
+### v1.20.0 (2026-05-16) — **Ollama + Markdown + same-layer panel**
+- **Ollama is the default LLM provider**. Backend `OpenAiCompatibleLlmClient` POSTs to `${BaseUrl}/chat/completions` — works against Ollama (`http://localhost:11434/v1`), OpenAI, LM Studio, vLLM, Anthropic's OpenAI-compat endpoint, OpenRouter. Tool-call `arguments` parsed in both JSON-string (spec) and parsed-object (Ollama) shapes.
+- **Markdown rendering inside assistant bubbles** via new `MaAiMarkdownPipe`. Supports GFM pipe tables, fenced + inline code, lists, blockquotes, bold/italic, sanitized links. URL allowlist blocks `javascript:` / `data:`. Pipe applies only to assistant bubbles — user input stays plain text.
+- **`quickPrompts` manifest field**: hosted-manifest can override the AI panel empty-state suggestions per deployment without republishing the npm package.
+- **AI chat panel is now same-layer with the host app** — backdrop removed; `z-index: 1040` (above page chrome, below CoreUI modals at 1055). Page stays fully interactive while the panel is open.
+
+### v1.19.0 (2026-05-16) — **AI Assistant module**
+- New `src/ai/` module: `MaAiButtonComponent`, `MaAiChatPanelComponent` (right-side resizable drawer, 320–800 px), `MaAiService` (SSE via `fetch` + `ReadableStream`), `MaAiToolsRegistry`, `provideMesAuthAi(config)` provider.
+- Auto-wired into `ma-user` next to the bell/approval buttons. Toggle off with `[showAi]="false"` on `<ma-user>`.
+- Built-in client tools shipped: `navigate`, `toggle_theme`, `show_toast`, `who_am_i_client`, `reload_page`. Consumer apps register additional tools (incl. write-class) via `provideMesAuthAi({ tools: [...] })` — write tools surface an in-panel approval card.
+- Backend: `POST /ai/chat` SSE endpoint in MesAuth.Api with 7 curated server tools + 3 universal tools (`list_apps`, `list_app_functions`, `call_app_endpoint`) that proxy to consumer apps using each `Application.HostUrl`.
+
 ### v1.6.8 (2026-04-01) - **Permission Header Support**
 - **New `withXMaPerm()` RxJS operator**: Extracts `X-MA-PERM` permission header from HTTP responses, returning `{ data, allowedActions }`. Use with `observe: 'response'` on any `HttpClient` call for zero-overhead permission-gated UI.
 - **New `xMaResource()` helper**: Combines `rxResource` with automatic permission extraction for GET endpoints. Returns a signal-based resource with `.value().allowedActions`.
@@ -72,6 +87,7 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
 - 🔐 **Authentication**: User login/logout with API integration
 - 🔔 **Real-time Notifications**: SignalR integration for live notifications
 - ✅ **Approval Workflows**: `<ma-approval-panel>`, `<ma-arv-container>`, `MaApprovalService` for multi-step document approval
+- 🤖 **AI Assistant**: in-browser chat panel (Ollama by default) with markdown rendering, agentic tool loop, server + client tools — see [AI Assistant](#ai-assistant)
 - 🎨 **Dark/Light Theme**: Automatic theme detection and support
 - 🖼️ **Avatar Support**: Direct API-based avatar loading
 - 🍞 **Toast Notifications**: In-app notification toasts
@@ -250,6 +266,138 @@ A standalone component for displaying a slide-out notification panel with real-t
     notificationPanel.open();
     ```
 
+## AI Assistant
+
+Since **v1.19.0** the library ships an in-browser AI chat panel that lives inside `<ma-user>`. It calls MesAuth.Api's `/ai/chat` SSE endpoint, which fronts an LLM (Ollama by default) and runs an agentic loop with two kinds of tools: **server tools** (data queries — `whoami`, `list_my_approvals`, etc.) and **client tools** (UI actions the model triggers in the browser — navigation, dialogs, custom logic the consumer registers).
+
+### 1. Backend prerequisite
+
+MesAuth.Api must be running v10.x with the `Ai:*` config block populated. Default points at local Ollama:
+
+```jsonc
+// appsettings.json (MesAuth.Api)
+"Ai": {
+  "Enabled": true,
+  "Provider": "ollama",
+  "BaseUrl": "http://localhost:11434/v1",   // any OpenAI-compatible base URL
+  "ApiKey": "",                             // optional; required for OpenAI / Anthropic compat
+  "Model": "qwen2.5:7b",                    // any tool-calling capable model
+  "MaxToolCallsPerTurn": 12,
+  "MaxTokensPerResponse": 4096,
+  "SessionTtlMinutes": 120
+}
+```
+
+Install Ollama (`brew install ollama` / `winget install Ollama.Ollama`) then `ollama pull qwen2.5:7b` (or `llama3.1:8b`, `mistral-nemo`, etc.).
+
+### 2. Frontend setup
+
+```ts
+// app.config.ts
+import { ApplicationConfig, inject } from '@angular/core';
+import { Router } from '@angular/router';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideMesAuth, provideMesAuthAi, mesAuthInterceptor } from 'mesauth-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([mesAuthInterceptor])),
+    provideMesAuth({
+      apiBaseUrl: 'https://mes.kefico.vn/auth',
+      userBaseUrl: 'https://mes.kefico.vn/x'
+    }),
+    provideMesAuthAi({
+      enabled: true,
+      appName: 'MesExtensionSite',                // sent to the AI as host context each turn
+      systemPromptExtensions: [
+        'You are inside the MES Extension app. Use SPC tools when the user asks about lines or charts.'
+      ],
+      tools: [
+        // example custom client tool — read-only, no approval card
+        {
+          name: 'spc_open_chart',
+          description: 'Open the SPC chart for a given product line',
+          parameters: {
+            type: 'object',
+            properties: { lineId: { type: 'string', description: 'Production line id' } },
+            required: ['lineId']
+          },
+          readOnly: true,
+          handler: (args: { lineId: string }) => {
+            inject(Router).navigateByUrl(`/spc/${args.lineId}`);
+            return `Opened SPC chart for line ${args.lineId}`;
+          }
+        }
+      ]
+    })
+  ]
+};
+```
+
+That's all that's needed — the AI button appears in the existing `<ma-user>` header and the chat panel slides in from the right when clicked. No template changes required in the consumer app.
+
+### 3. Built-in client tools
+
+| Tool | What it does |
+|---|---|
+| `navigate` | `router.navigateByUrl(path)` |
+| `toggle_theme` | Flip between light/dark via `ThemeService` |
+| `show_toast` | Surface a toast via `ToastService` |
+| `who_am_i_client` | Returns the current user from the browser (synchronous, no API call) |
+| `reload_page` | `window.location.reload()` (write-class — surfaces approval card) |
+
+Override / extend by passing your own tools in `provideMesAuthAi({ tools })`. Consumer tools always take precedence over built-ins of the same name.
+
+### 4. Server-tool catalogue (provided by MesAuth.Api)
+
+| Tool | Description |
+|---|---|
+| `whoami` | Identity, roles, department of the signed-in user |
+| `list_users` | Search users by name / department / employee code |
+| `list_my_roles` | Roles assigned to the caller |
+| `list_my_approvals` | Pending approval documents waiting on the caller |
+| `list_my_notifications` | Caller's recent notifications (unread by default) |
+| `list_health_endpoints` | Registered health endpoints + latest probe status |
+| `current_time` | Server time (UTC + Vietnam local) |
+| `list_apps` | Apps the caller has any permission in |
+| `list_app_functions` | Paginated endpoints in an app the caller can call (driven by the Authorizer-registered permission catalogue) |
+| `call_app_endpoint` | **Universal proxy** — calls any registered endpoint in any consumer app on the caller's behalf. Permission is re-checked before the call. Requires `Application.HostUrl` to be set in *Auth → Client Apps*. |
+
+### 5. Customising the empty-state suggestions
+
+Edit `wwwroot/mesauth-angular/v1/manifest.json` on the MesAuth.Api server (no npm republish needed):
+
+```json
+{
+  "version": "1.21.0",
+  "quickPrompts": [
+    "Show my pending approvals",
+    "Who is the supervisor of line A1?",
+    "How do I add a new user role?"
+  ]
+}
+```
+
+### 6. Write tools + approval cards
+
+A consumer-registered tool with `readOnly: false` (or omitted) surfaces an in-panel approval card showing the constructed `args` before the call runs. The user can choose **Approve**, **Always** (remembers the verb for this session), or **Decline**. Built-in writes (`reload_page`) follow the same flow.
+
+### 7. Disabling the AI feature
+
+Three knobs:
+
+- **Per app**: `provideMesAuthAi({ enabled: false })` hides the button and the panel.
+- **Per server**: set `Ai:Enabled = false` in MesAuth.Api appsettings — the endpoint returns 503 and the panel shows a friendly error.
+- **Per `<ma-user>`**: `<ma-user [showAi]="false">` hides the button but keeps the service available for programmatic use.
+
+### 8. Cost / safety controls
+
+- Server-side cap on tool calls per turn (`Ai:MaxToolCallsPerTurn`, default 12).
+- 8 KB truncation on every tool result fed back to the LLM (prevents context blow-up).
+- Write client tools always require user approval before executing.
+- Server tools re-check user permissions via `IFuncPermService` before running — the AI cannot bypass authorization.
+- `call_app_endpoint` forwards the caller's JWT to consumer apps, so the consumer's `MesAuth.Authorizer` middleware enforces the same permission gate it would for a normal request.
+
 ## Migration Guide
 
 ### Upgrading from v0.x to v1.1.0+

package/fesm2022/mesauth-angular.mjs

@@ -10,7 +10,7 @@ import { DomSanitizer } from '@angular/platform-browser';
 import { DatePipe, JsonPipe } from '@angular/common';
 
 /** Current installed package version — keep in sync with package.json. */
-const PACKAGE_VERSION = '1.19.0';
+const PACKAGE_VERSION = '1.21.0';
 /**
  * Provides server-driven UI configuration loaded from the hosted manifest.
  * Components read `labels()` and `features()` signals instead of hardcoded strings.