@agentictrust/ui

Thin runtime loader and React SDK for the Agentic Trust chat widget.

v0.1.2+ — This package is a lightweight loader (~6 KB) that dynamically fetches widget.js from your platform URL at runtime. You always get the latest widget without updating the npm dependency. The apiUrl you pass must be reachable from the browser.

Install

npm install @agentictrust/ui

React / Next.js

"use client";

import { Widget } from "@agentictrust/ui";

export default function Page() {
  return (
    <div style={{ height: 720 }}>
      <Widget
        apiUrl="https://platform.agentictrust.com/api/v1"
        apiKey="lum_pk_your_api_key"
      />
    </div>
  );
}

On mount, the Widget component loads widget.js from your platform and renders the chat UI inside a shadow root, fully isolated from your app's styles.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiUrl | string | Yes | API base URL (e.g. https://platform.agentictrust.com/api/v1) | | apiKey | string | Yes | Public API key (lum_pk_...) | | user | UserIdentity | No | End-user identity for HMAC verification | | userTokens | Record<string, string> | No | Auth headers forwarded to action endpoints | | pageContext | PageContext | No | Page metadata sent with messages | | captureDom | boolean | No | Auto-capture headings, links, buttons, and form fields | | readOnly | boolean | No | Hide the chat input | | className | string | No | CSS class on the host element | | style | CSSProperties | No | Inline styles on the host element |

Imperative client API

For non-React apps or floating widget installs:

import { initAsync, destroy } from "@agentictrust/ui";

await initAsync({
  apiUrl: "https://platform.agentictrust.com/api/v1",
  apiKey: "lum_pk_your_api_key",
});

// later
destroy();

Full API

| Method | Description | |--------|-------------| | init(options) | Mount the widget synchronously (uses default config) | | initAsync(options) | Mount the widget after fetching config from the server | | destroy() | Unmount the widget and clean up all state | | open() | Open the chat panel | | close() | Close the chat panel | | toggle() | Toggle the chat panel open/closed | | setContext(ctx) | Update page context for the next message | | registerTools(tools) | Register browser-side tools the agent can invoke | | onToolResult(callback) | Subscribe to server-side tool results (returns unsubscribe fn) | | registerToolRenderers(renderers) | Customize how specific tools render in the chat | | identify(token) | Verify user identity with a signed JWT | | setIdentityTokenFetcher(fn) | Auto-refresh JWT identity tokens before expiry |

Example: client-side tools + identity

import { initAsync, registerTools, identify, setContext } from "@agentictrust/ui";

await initAsync({
  apiUrl: "https://platform.agentictrust.com/api/v1",
  apiKey: "lum_pk_your_api_key",
});

registerTools({
  get_cart_items: async () => {
    const items = JSON.parse(localStorage.getItem("cart") ?? "[]");
    return { items, count: items.length };
  },
});

setContext({
  title: document.title,
  url: location.href,
});

await identify("<signed-jwt-token>");

Hosted script (IIFE)

Building this package also emits dist/agentic-trust-widget.js, an IIFE bundle that exposes a global AgenticTrust object. The main app copies it to /public/widget.js for script-tag embeds:

<script src="https://platform.agentictrust.com/widget.js"></script>
<script>
  AgenticTrust.initAsync({
    apiUrl: "https://platform.agentictrust.com/api/v1",
    apiKey: "lum_pk_your_api_key"
  });
</script>

Build

cd widget
npm run build

This produces:

• dist/index.js + dist/index.d.ts — ES module thin loader for React bundlers (~6 KB)
• dist/agentic-trust-widget.js — IIFE bundle for script-tag embeds (~365 KB, served by the platform)

Exports

// React component
import { Widget, AgenticTrustWidget } from "@agentictrust/ui";

// Imperative singleton
import { AgenticTrust } from "@agentictrust/ui";

// Individual methods
import { init, initAsync, destroy, open, close, toggle } from "@agentictrust/ui";
import { setContext, registerTools, onToolResult, registerToolRenderers } from "@agentictrust/ui";
import { identify, setIdentityTokenFetcher } from "@agentictrust/ui";

// Loader client (delegates to the platform's widget.js at runtime)
import { createAgenticTrust } from "@agentictrust/ui";

// Script loader (for manual control)
import { loadWidgetScript } from "@agentictrust/ui";

// Types
import type {
  InitOptions, WidgetConfig, PageContext, UserIdentity,
  ClientToolRegistryInput, ToolRendererMap, ToolResultEvent,
  AgenticTrustClient, AgenticTrustWidgetProps,
} from "@agentictrust/ui";

Publishing

The repo includes a GitHub Actions workflow at .github/workflows/publish-widget-sdk.yml. It publishes to npm when a widget-v* tag is pushed, provided the tagged commit includes changes under widget/.

Release flow

cd widget
npm version patch --no-git-tag-version
cd ..
git add widget/package.json
git commit -m "release: @agentictrust/ui $(node -p 'require(\"./widget/package.json\").version')"
git tag "widget-v$(node -p 'require(\"./widget/package.json\").version')"
git push origin master --tags

Requirements

• GitHub repository secret NPM_TOKEN
• npm access to publish under the @agentictrust scope