@visma-swno/gaia-chat-ui

Web component library for the GAiA Assistant Chat UI, built with Lit for Visma Software Nordic products.

Installation

npm install @visma-swno/gaia-chat-ui

lit is an external dependency and must be available in your bundle:

npm install lit@^3.3.0

Quick Start

import '@visma-swno/gaia-chat-ui';

Visitor Mode (Anonymous)

<gaia-chat
  profile-id="YOUR_PROFILE_ID"
  base-url="https://api.assistant.vsn.dev"
  auth-strategy="visitor"
></gaia-chat>

Visma Connect Mode (Authenticated)

Provide a tokenProvider that returns a valid OAuth access token. Implement caching and refresh: reuse a valid token until shortly before its exp claim, then silently refresh.

<gaia-chat
  id="assistant"
  profile-id="YOUR_PROFILE_ID"
  base-url="https://api.assistant.vsn.dev"
  auth-strategy="visma"
></gaia-chat>

<script type="module">
  const assistant = document.getElementById('assistant');

  assistant.tokenProvider = async () => {
    const res = await fetch('/api/auth/assistant-token');
    const { token } = await res.json();
    return token;
  };
</script>

Properties

| Property / Attribute | Type | Default | Description | | ----------------------- | ----------------------- | ------------------------------------------ | ------------------------------------------------------------ | | base-url | string | 'https://api.assistant.stag.vsn.dev' | Backend API base URL. | | profile-id | string | 'default' | Assistant profile identifier. | | auth-strategy | 'visitor' \| 'visma' | 'visitor' | Authentication strategy. | | closeable | boolean | true | Show a close button in the header. | | selected-model | string | '' | Override the default AI model. Must be in the profile's allowed overrides. | | tokenProvider | () => Promise<string> | — | Async function returning an OAuth access token (Visma mode). Set via JS. | | hostContextProvider | HostContextProvider | — | Async function returning application context per message. Set via JS. | | tools | FrontendTool[] | [] | Frontend tool definitions sent to the agent. Set via JS. |

Events

All events bubble and are composed (cross shadow DOM).

| Event | Detail Type | Description | | ---------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- | | conversation-cleared | void | User cleared the conversation. | | message-sent | { message: string; channel: 'assistant' \| 'support' } | User sent a message. | | tool-call-approved | { messageId: string } | User approved a tool call. | | tool-call-declined | { messageId: string } | User declined a tool call. | | feedback-submitted | { rating: number; comment: string \| null } | User submitted feedback. | | close-requested | void | User clicked the close button. | | tool-call | { toolCallId: string; toolCallName: string; arguments: Record<string, unknown> \| string \| null; result: unknown } | A frontend tool call was executed. |

document.querySelector('gaia-chat').addEventListener('message-sent', (e) => {
  console.log('User sent:', e.detail.message);
});

Methods

| Method | Description | | -------------------- | ------------------------------------------------- | | clearConversation()| Clear the current conversation and reset the chat.| | stopSupport() | Stop any active support session. |

Host Context Provider

Provide dynamic application context with each message. The agent and its plugins can use this context for personalized responses.

const chat = document.querySelector('gaia-chat');

chat.hostContextProvider = async () => ({
  customerId: getCurrentCustomerId(),
  companyId: getCurrentCompanyId(),
  partnerId: getPartnerId(),
  data: {
    environment: 'production',
    userRole: getUserRole(),
  },
});

HostContext

interface HostContext {
  customerId?: string;
  companyId?: string;
  partnerId?: string;
  data?: Record<string, unknown>;
}

type HostContextProvider = () => HostContext | Promise<HostContext | null> | null;

Frontend Tools

Register custom tools that the agent can invoke. Tool results are returned to the agent and a tool-call event is dispatched to the host.

const chat = document.querySelector('gaia-chat');

chat.tools = [
  {
    name: 'getInvoice',
    description: 'Retrieve an invoice by ID',
    parameters: {
      type: 'object',
      properties: {
        invoiceId: { type: 'string', description: 'The invoice ID' },
      },
      required: ['invoiceId'],
    },
  },
];

chat.addEventListener('tool-call', (e) => {
  const { toolCallName, arguments: args } = e.detail;
  // Handle the tool call and return data to the agent
});

FrontendTool

interface FrontendTool {
  name: string;
  description: string;
  parameters: JSONSchema7; // JSON Schema draft-07, must be type: 'object'
}

Icon Registry

Register custom SVG icons for use in the component:

import { registerIcons } from '@visma-swno/gaia-chat-ui';

registerIcons({ 'my-icon': '<svg>...</svg>' });

Styling

The component exposes CSS custom properties prefixed with --gaia- for theming. Set these on the <gaia-chat> element or any ancestor.

Typography

| Property | Description | | -------------------------------- | ------------------ | | --gaia-font-family | Font family | | --gaia-font-size-xs … 3xl | Font sizes | | --gaia-line-height-xs … 3xl | Line heights | | --gaia-font-weight-regular | Regular weight | | --gaia-font-weight-medium | Medium weight | | --gaia-font-weight-semibold | Semibold weight | | --gaia-font-weight-bold | Bold weight |

Colors

| Property group | Examples | | ------------------------------- | ------------------------------------------------------------ | | --gaia-color-surface-* | page, primary, action, action-hover, error, success, information, warning, disabled, selected | | --gaia-color-text-* | headings, body, body-secondary, action, action-hover, disabled, error, success, link-visited | | --gaia-color-border-* | primary, secondary, tertiary, action, action-hover, focus, error, success | | --gaia-color-icon-* | primary, action, action-hover, disabled, error, success, on-action, on-primary | | --gaia-color-message-* | user, system, operator | | --gaia-color-neutral-* | 10 through 100 |

Example

gaia-chat {
  --gaia-font-family: 'Inter', sans-serif;
  --gaia-color-surface-page: #ffffff;
  --gaia-color-surface-action: #0066cc;
  --gaia-color-text-body: #1a1a1a;
  --gaia-color-message-user: #e6f0ff;
}

Localization

The component reads the lang attribute (on itself or <html>) and responds to changes at runtime. Supported locales are bundled with the component.

<gaia-chat lang="nb"></gaia-chat>

Exports

import { ChatApp, ToolCallEvent, registerIcons } from '@visma-swno/gaia-chat-ui';
import type { FrontendTool, HostContext, HostContextProvider } from '@visma-swno/gaia-chat-ui';

Documentation

For development instructions and architecture details, see the main repository.