mesauth-angular 1.20.0 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +153 -0
  2. package/fesm2022/mesauth-angular.mjs +95 -9
  3. package/fesm2022/mesauth-angular.mjs.map +1 -1
  4. package/package.json +1 -1
  5. package/types/mesauth-angular.d.ts +22 -3
package/README.md CHANGED
@@ -4,6 +4,26 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
4
4
 
5
5
  ## Changelog
6
6
 
7
+ ### v1.22.0 (2026-05-16) — **AI panel push-layout mode**
8
+ - **AI chat panel now pushes the host layout by default.** When the panel opens, `<body>` gets `padding-inline-end: var(--ma-ai-panel-width)` so the host app reflows to make room — wide content (tables, charts) is no longer hidden under the drawer. The library self-injects the global stylesheet on first construction; **zero changes required in consumer apps**.
9
+ - New config flag `panelMode: 'static' | 'floating'` on `provideMesAuthAi()`. Default is `'static'` (push-layout). Pass `'floating'` to keep the v1.21 overlay behaviour for hosts whose layout can't reflow safely.
10
+ - CSS variable `--ma-ai-panel-width` is set live during drag-resize, so the host reflows smoothly as the user widens/narrows the panel.
11
+
12
+ ### v1.21.0 (2026-05-16) — **AI Assistant integration docs**
13
+ - 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.
14
+
15
+ ### v1.20.0 (2026-05-16) — **Ollama + Markdown + same-layer panel**
16
+ - **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.
17
+ - **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.
18
+ - **`quickPrompts` manifest field**: hosted-manifest can override the AI panel empty-state suggestions per deployment without republishing the npm package.
19
+ - **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.
20
+
21
+ ### v1.19.0 (2026-05-16) — **AI Assistant module**
22
+ - New `src/ai/` module: `MaAiButtonComponent`, `MaAiChatPanelComponent` (right-side resizable drawer, 320–800 px), `MaAiService` (SSE via `fetch` + `ReadableStream`), `MaAiToolsRegistry`, `provideMesAuthAi(config)` provider.
23
+ - Auto-wired into `ma-user` next to the bell/approval buttons. Toggle off with `[showAi]="false"` on `<ma-user>`.
24
+ - 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.
25
+ - 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`.
26
+
7
27
  ### v1.6.8 (2026-04-01) - **Permission Header Support**
8
28
  - **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.
9
29
  - **New `xMaResource()` helper**: Combines `rxResource` with automatic permission extraction for GET endpoints. Returns a signal-based resource with `.value().allowedActions`.
@@ -72,6 +92,7 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
72
92
  - 🔐 **Authentication**: User login/logout with API integration
73
93
  - 🔔 **Real-time Notifications**: SignalR integration for live notifications
74
94
  - ✅ **Approval Workflows**: `<ma-approval-panel>`, `<ma-arv-container>`, `MaApprovalService` for multi-step document approval
95
+ - 🤖 **AI Assistant**: in-browser chat panel (Ollama by default) with markdown rendering, agentic tool loop, server + client tools — see [AI Assistant](#ai-assistant)
75
96
  - 🎨 **Dark/Light Theme**: Automatic theme detection and support
76
97
  - 🖼️ **Avatar Support**: Direct API-based avatar loading
77
98
  - 🍞 **Toast Notifications**: In-app notification toasts
@@ -250,6 +271,138 @@ A standalone component for displaying a slide-out notification panel with real-t
250
271
  notificationPanel.open();
251
272
  ```
252
273
 
274
+ ## AI Assistant
275
+
276
+ 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).
277
+
278
+ ### 1. Backend prerequisite
279
+
280
+ MesAuth.Api must be running v10.x with the `Ai:*` config block populated. Default points at local Ollama:
281
+
282
+ ```jsonc
283
+ // appsettings.json (MesAuth.Api)
284
+ "Ai": {
285
+ "Enabled": true,
286
+ "Provider": "ollama",
287
+ "BaseUrl": "http://localhost:11434/v1", // any OpenAI-compatible base URL
288
+ "ApiKey": "", // optional; required for OpenAI / Anthropic compat
289
+ "Model": "qwen2.5:7b", // any tool-calling capable model
290
+ "MaxToolCallsPerTurn": 12,
291
+ "MaxTokensPerResponse": 4096,
292
+ "SessionTtlMinutes": 120
293
+ }
294
+ ```
295
+
296
+ Install Ollama (`brew install ollama` / `winget install Ollama.Ollama`) then `ollama pull qwen2.5:7b` (or `llama3.1:8b`, `mistral-nemo`, etc.).
297
+
298
+ ### 2. Frontend setup
299
+
300
+ ```ts
301
+ // app.config.ts
302
+ import { ApplicationConfig, inject } from '@angular/core';
303
+ import { Router } from '@angular/router';
304
+ import { provideHttpClient, withInterceptors } from '@angular/common/http';
305
+ import { provideMesAuth, provideMesAuthAi, mesAuthInterceptor } from 'mesauth-angular';
306
+
307
+ export const appConfig: ApplicationConfig = {
308
+ providers: [
309
+ provideHttpClient(withInterceptors([mesAuthInterceptor])),
310
+ provideMesAuth({
311
+ apiBaseUrl: 'https://mes.kefico.vn/auth',
312
+ userBaseUrl: 'https://mes.kefico.vn/x'
313
+ }),
314
+ provideMesAuthAi({
315
+ enabled: true,
316
+ appName: 'MesExtensionSite', // sent to the AI as host context each turn
317
+ systemPromptExtensions: [
318
+ 'You are inside the MES Extension app. Use SPC tools when the user asks about lines or charts.'
319
+ ],
320
+ tools: [
321
+ // example custom client tool — read-only, no approval card
322
+ {
323
+ name: 'spc_open_chart',
324
+ description: 'Open the SPC chart for a given product line',
325
+ parameters: {
326
+ type: 'object',
327
+ properties: { lineId: { type: 'string', description: 'Production line id' } },
328
+ required: ['lineId']
329
+ },
330
+ readOnly: true,
331
+ handler: (args: { lineId: string }) => {
332
+ inject(Router).navigateByUrl(`/spc/${args.lineId}`);
333
+ return `Opened SPC chart for line ${args.lineId}`;
334
+ }
335
+ }
336
+ ]
337
+ })
338
+ ]
339
+ };
340
+ ```
341
+
342
+ 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.
343
+
344
+ ### 3. Built-in client tools
345
+
346
+ | Tool | What it does |
347
+ |---|---|
348
+ | `navigate` | `router.navigateByUrl(path)` |
349
+ | `toggle_theme` | Flip between light/dark via `ThemeService` |
350
+ | `show_toast` | Surface a toast via `ToastService` |
351
+ | `who_am_i_client` | Returns the current user from the browser (synchronous, no API call) |
352
+ | `reload_page` | `window.location.reload()` (write-class — surfaces approval card) |
353
+
354
+ Override / extend by passing your own tools in `provideMesAuthAi({ tools })`. Consumer tools always take precedence over built-ins of the same name.
355
+
356
+ ### 4. Server-tool catalogue (provided by MesAuth.Api)
357
+
358
+ | Tool | Description |
359
+ |---|---|
360
+ | `whoami` | Identity, roles, department of the signed-in user |
361
+ | `list_users` | Search users by name / department / employee code |
362
+ | `list_my_roles` | Roles assigned to the caller |
363
+ | `list_my_approvals` | Pending approval documents waiting on the caller |
364
+ | `list_my_notifications` | Caller's recent notifications (unread by default) |
365
+ | `list_health_endpoints` | Registered health endpoints + latest probe status |
366
+ | `current_time` | Server time (UTC + Vietnam local) |
367
+ | `list_apps` | Apps the caller has any permission in |
368
+ | `list_app_functions` | Paginated endpoints in an app the caller can call (driven by the Authorizer-registered permission catalogue) |
369
+ | `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*. |
370
+
371
+ ### 5. Customising the empty-state suggestions
372
+
373
+ Edit `wwwroot/mesauth-angular/v1/manifest.json` on the MesAuth.Api server (no npm republish needed):
374
+
375
+ ```json
376
+ {
377
+ "version": "1.21.0",
378
+ "quickPrompts": [
379
+ "Show my pending approvals",
380
+ "Who is the supervisor of line A1?",
381
+ "How do I add a new user role?"
382
+ ]
383
+ }
384
+ ```
385
+
386
+ ### 6. Write tools + approval cards
387
+
388
+ 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.
389
+
390
+ ### 7. Disabling the AI feature
391
+
392
+ Three knobs:
393
+
394
+ - **Per app**: `provideMesAuthAi({ enabled: false })` hides the button and the panel.
395
+ - **Per server**: set `Ai:Enabled = false` in MesAuth.Api appsettings — the endpoint returns 503 and the panel shows a friendly error.
396
+ - **Per `<ma-user>`**: `<ma-user [showAi]="false">` hides the button but keeps the service available for programmatic use.
397
+
398
+ ### 8. Cost / safety controls
399
+
400
+ - Server-side cap on tool calls per turn (`Ai:MaxToolCallsPerTurn`, default 12).
401
+ - 8 KB truncation on every tool result fed back to the LLM (prevents context blow-up).
402
+ - Write client tools always require user approval before executing.
403
+ - Server tools re-check user permissions via `IFuncPermService` before running — the AI cannot bypass authorization.
404
+ - `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.
405
+
253
406
  ## Migration Guide
254
407
 
255
408
  ### Upgrading from v0.x to v1.1.0+