@newheap/platform-ai-chat 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+NewHeap AI Chat for Angular
+Copyright 2026 NewHeap B.V.
+
+This product includes software developed by NewHeap B.V. and contributors.

package/README.md

@@ -0,0 +1,294 @@
+# @newheap/platform-ai-chat
+
+Angular assistant panel for NewHeap AI chat endpoints with streaming, tool-call and approval cards.
+
+The package talks to the assistant HTTP API of `NewHeap.Platform.AI.Chat.AspNet`
+(`MapNewHeapAssistant("/api/assistant")`): it lists agents and conversations,
+streams turns as server-sent events, shows tool calls, and pauses mutations on an
+approval card until the user approves or rejects them. It has no dependency on
+ng-bootstrap or on a specific authentication library; the host supplies the token
+and the access decision.
+
+## Installation
+
+The package is public on npmjs.org and installs without a registry token. An optional project `.npmrc` can make the public source explicit:
+
+```text
+registry=https://registry.npmjs.org/
+@newheap:registry=https://registry.npmjs.org/
+```
+
+Install the package with its peer dependencies:
+
+```bash
+npm install @newheap/platform-ai-chat @angular/cdk @angular/router marked dompurify
+```
+
+View available versions on [npmjs.org](https://www.npmjs.com/package/@newheap/platform-ai-chat). For NuGet, npm and AI-plugin installation, see [Consume public packages](../../../../docs/how-to/consume-public-packages.md).
+
+Peer dependencies: Angular `^20.3.28` (`@angular/core`, `@angular/common`),
+`@angular/cdk` `^20.2.14`, `@angular/router` `^20.3.28`, `@ngx-translate/core` `^17.0.0`, `marked` `^18.0.0`,
+`dompurify` `^3.4.0` and `rxjs` `~7.8.0`.
+
+The panel is a CDK overlay. Load the CDK overlay styles once, for example in
+`angular.json`:
+
+```json
+"styles": [
+  "node_modules/@angular/cdk/overlay-prebuilt.css",
+  "src/styles.scss"
+]
+```
+
+## Providers
+
+Register the assistant once in the root providers:
+
+```typescript
+import { ApplicationConfig, Injectable, inject } from '@angular/core';
+import { NhAssistantAccessPolicy, provideNhAssistant } from '@newheap/platform-ai-chat';
+import { map } from 'rxjs';
+
+@Injectable()
+export class AssistantAccessPolicy implements NhAssistantAccessPolicy {
+  private readonly auth = inject(AppAuthService);
+
+  canUse() {
+    return this.auth.authSubject.pipe(map(() => this.auth.isOnePermissionGranted(['app.assistant.access'])));
+  }
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideNhAssistant({
+      apiBaseUrl: environment.api.baseUrl + '/assistant',
+      getAccessToken: () => inject(AppAuthService).getAuthorization()?.token ?? null,
+      accessPolicy: AssistantAccessPolicy,
+      defaultAgentId: 'order-assistant',
+      adminRoute: '/admin/assistant'
+    })
+  ]
+};
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `apiBaseUrl` | required | Base URL of the assistant endpoints. |
+| `getAccessToken` | required | Returns the bearer token or `null`. Runs in the assistant's injection context before every request, so it may use `inject(...)`. |
+| `accessPolicy` | always allowed | Injectable class whose `canUse()` returns a boolean or an observable. |
+| `defaultAgentId` | first agent | Agent selected for new conversations. |
+| `translations` | `'bundled'` | `'bundled'` merges the library's `en` and `nl` texts into `TranslateService`; `'host'` leaves all texts to the host. |
+| `getPageContext` | none | Returns what the user has open (`{ route, title?, entities? }`). Runs in the assistant's injection context when the panel opens and before every message; see [Page context](#page-context). |
+| `adminRoute` | none | Router link of the host's administration page. The panel links to it only when the server reports `canAdminister`. |
+| `markdown` | `{ enabled: true }` | Renders assistant text as sanitized Markdown; `false` shows plain text. |
+
+Requests use `fetch` instead of the host's `HttpClient`, because `EventSource`
+cannot send an `Authorization` header and streamed responses must bypass response
+interceptors. Every request carries `Authorization: Bearer <token>` when a token
+exists and `Accept-Language` from `TranslateService`.
+
+## Host integration
+
+Place the launcher in the header and one panel in the layout:
+
+```html
+<header>
+  <nh-assistant-launcher />
+</header>
+<router-outlet />
+<nh-assistant-panel />
+```
+
+The launcher renders nothing while `GET status` reports `enabled: false`, the
+endpoint is unavailable, or the access policy denies the user. It shows a badge
+when a conversation waits for approval. Projected content replaces its default
+icon. Other components open the panel through `NhAssistantPanelService`:
+
+```typescript
+inject(NhAssistantPanelService).open(conversationId);
+```
+
+The drawer is 420 px wide on the right and fills the screen below 600 px. Escape
+closes it and focus returns to the element that opened it.
+
+`NhAssistantStore` exposes the state as signals (`enabled`, `agents`,
+`conversations`, `activeConversation`, `streaming`, `pendingApproval`, `error` and
+more) and the actions `send`, `decide`, `cancel`, `openConversation`,
+`startNewConversation` and `selectAgent`. The building blocks
+`nh-assistant-thread`, `nh-assistant-composer`, `nh-assistant-conversation-list`,
+`nh-assistant-tool-call-card`, `nh-assistant-approval-card` and
+`nh-assistant-agent-picker` are exported for custom layouts. All components are
+standalone and use `OnPush`.
+
+Assistant text is rendered as Markdown with `marked` and sanitized with DOMPurify
+against a small allow-list. Inline HTML in model text is shown as text, images
+render as their alt text, `javascript:` and `data:` links lose their target, and
+links open in a new tab with `rel="noopener noreferrer"`.
+
+## Page context
+
+With `getPageContext` every message carries what the user has open, so the model can
+answer "this project" without asking:
+
+```typescript
+getPageContext: () => inject(CurrentPage).value() ?? { route: inject(Router).url, title: inject(Title).getTitle() }
+```
+
+```typescript
+// On a project page
+this.currentPage.set({
+  route: `/projects/${project.key}`,
+  title: project.name,
+  entities: [{ type: 'project', id: project.key, label: `Project ${project.key}` }]
+});
+```
+
+The library validates and truncates the result: route at most 200 characters, title
+and labels at most 120, at most five entities with a dash-case `type` and an `id` of
+at most 64 characters. Entities with an invalid type or id are dropped rather than
+truncated. An invalid shape, an exception or a rejected promise leaves the context out
+of that message; sending continues. A chip above the message box shows what is sent;
+its close button leaves the context out of the next message, which then sends
+`clientContext: null`. Page context is untrusted data: the server treats entity ids as
+search hints and still authorizes every tool call.
+
+## Preferences
+
+The panel header opens `nh-assistant-preferences`. Users choose a style (standard,
+straight to the point, personal or detailed), the form of address, the answer length
+and optional own instructions of at most 1,000 characters. The component loads and
+saves through `NhAssistantApiService.getPreferences()` and `updatePreferences()`.
+Preferences steer the style only; the server keeps them below the application
+context and the agent instructions and never lets them change approvals or tool
+access.
+
+## Administration
+
+The administration page is a separate entry point, so it stays out of the initial
+bundle. Route to it lazily behind the host's admin permission and pass the route as
+`adminRoute`:
+
+```typescript
+{
+  path: 'admin/assistant',
+  canActivate: [IsAssistantAdministratorGuard],
+  loadComponent: () => import('@newheap/platform-ai-chat/admin').then(module => module.NhAssistantAdminComponent)
+}
+```
+
+`nh-assistant-admin` shows a no-access state unless the server reports
+`canAdminister`, and has three tabs:
+
+- **Context**: the application context with its version and hash, the version
+  history and a conflict message instead of overwriting a newer version.
+- **Agents**: code agents (override, disable, reset) and agents created by
+  administrators (edit, disable, delete). The editor chooses tool selectors from the
+  tool catalog or as patterns and assigns MCP servers.
+- **MCP servers**: server editor, connection test, tool sync and the tool table.
+  The secret is write-only: the page shows only whether one is set and offers to
+  replace or clear it. Synced tools start disabled and are treated as changes until
+  an administrator enables them and chooses the effect; remote annotations such as
+  `readOnlyHint` appear as hints only, and a changed remote input schema disables the
+  tool and shows a warning.
+
+`NhAssistantAdminApiService` (main entry) is the typed client of the `admin/*`
+endpoints. A `409` becomes the code `assistant-version-conflict`.
+
+## Theme
+
+The components define light and dark defaults and follow `prefers-color-scheme`.
+Map them onto the host's design tokens with custom properties:
+
+```scss
+:root {
+  --nh-assistant-font: var(--font-sans);
+  --nh-assistant-background: var(--surface);
+  --nh-assistant-surface: var(--surface-subtle);
+  --nh-assistant-text: var(--ink);
+  --nh-assistant-text-muted: var(--muted);
+  --nh-assistant-border: var(--line);
+  --nh-assistant-accent: var(--primary);
+  --nh-assistant-highlight: var(--brand);
+  --nh-assistant-focus: var(--accent);
+}
+```
+
+Further properties: `--nh-assistant-surface-strong`, `-accent-contrast`,
+`-user-bubble`, `-user-text`, `-success`, `-success-soft`, `-warning`,
+`-warning-soft`, `-danger`, `-danger-soft`, `-shadow`, `-radius`,
+`-radius-control`, `-font-mono`, and `--nh-assistant-launcher-size`, `-color`,
+`-background`, `-border` and `-badge-ring` for the launcher.
+
+Use the host's icon library through `NH_ASSISTANT_ICONS`; icons without a class
+use small built-in outline glyphs:
+
+```typescript
+{ provide: NH_ASSISTANT_ICONS, useValue: { assistant: 'ph ph-sparkle', close: 'ph ph-x', send: 'ph ph-paper-plane-right' } }
+```
+
+## Translations
+
+All keys live under `nh-assistant.`. With `translations: 'bundled'` the library
+merges its `en` and `nl` texts whenever the host loads a language; other
+languages receive English. Keys the host defines under `nh-assistant.` win, so a
+host adds only what the server decides:
+
+```json
+{
+  "nh-assistant": {
+    "agents": {
+      "order-assistant": { "name": "Order assistant", "description": "Answers questions about orders." }
+    },
+    "errors": { "assistant-budget-exceeded": "The daily assistant budget is used up." }
+  }
+}
+```
+
+Error events are shown through their `messageKey`, then `nh-assistant.errors.<code>`,
+then a generic text. Tool result codes use `nh-assistant.result-codes.<code>` and
+fall back to the code. With `translations: 'host'`, copy the bundles from
+`NH_ASSISTANT_TRANSLATIONS` or from `@newheap/platform-ai-chat/i18n/en.json` and
+`nl.json`.
+
+## Mock API
+
+`@newheap/platform-ai-chat/testing` plays a scripted assistant without a back-end,
+for tests, demos and front-end work before the API exists:
+
+```typescript
+import { provideNhAssistantMockApi } from '@newheap/platform-ai-chat/testing';
+
+providers: [
+  provideNhAssistant({ apiBaseUrl: '/api/assistant', getAccessToken: () => null }),
+  provideNhAssistantMockApi({
+    agents: [{ id: 'demo', version: 1, displayNameKey: 'nh-assistant.agents.demo.name', descriptionKey: 'nh-assistant.agents.demo.description', canMutate: true }],
+    turns: [
+      {
+        match: /hold/i,
+        steps: [{
+          approval: {
+            toolId: 'orders.update-status', displayName: 'Update status', summary: 'Put order 42 on hold',
+            argumentsPreview: '{"id":42}', targets: ['Order 42'],
+            approved: [{ text: 'Order 42 is on hold.' }], rejected: [{ text: 'Nothing changed.' }]
+          }
+        }]
+      },
+      { steps: [{ tool: { toolId: 'orders.list', displayName: 'List orders' } }, { text: 'There are **3** open orders.' }] }
+    ]
+  })
+]
+```
+
+Steps are `text`, `tool`, `approval`, `error` and `fail`. The optional `preferences`
+and `admin` parts of the scenario seed the preference and administration endpoints:
+context, tool catalog, agents, MCP servers with simulated remote tools, known
+policies and hosts that may receive the user's token. The mock answers every
+endpoint in memory and sends each turn as contract events over a chunked
+`text/event-stream` response, so the real client, parser and store run unchanged.
+Inject `NhAssistantMockBackend` to switch the simulated feature flag with
+`setEnabled(false)`, the admin permission with `setCanAdminister(false)`, to change
+the remote tools of a server with `setRemoteTools(...)` or to assert the received
+`requests`.
+
+The SampleProjectManagement management portal shows the complete integration
+(sample cases SPM-248 and SPM-253).