The web widget

#What the widget is for

@rekhu/assistant-widget is the chat in the browser. It is a web component, <rekhu-assistant>, in its own shadow DOM, so it works in Vue, React, Nuxt, Next, Svelte or plain HTML, and your CSS and its CSS never meet. It has no dependencies, is about 17 kB gzipped, and is safe to import during server rendering.

The widget talks only to the chat route of your back end, from rekhu/assistant-laravel or @rekhu/assistant-node. It holds no Rekhu key.

Note: a Blade or Livewire app does not need this package. The <x-rekhu-assistant /> tag serves the same widget, without npm. Use the package for Inertia with router navigation, or for a front end of its own.

#Add the widget in four steps

1. Install the package with npm, pnpm or yarn.
2. Find the chat route of your back end: /rekhu/assistant/chat for the Laravel package, or the path you mounted the Node.js package on, such as /api/rekhu/chat.
3. Mount it once, in the browser, for a signed-in user, with endpoint set to that route.
4. Hand it your router, with navigate, so pages open without a reload, and onAction, so your data refreshes after an action.

npm install @rekhu/assistant-widget

A client component in Next.js:

'use client';
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { mount } from '@rekhu/assistant-widget';

export function Assistant() {
    const router = useRouter();
    useEffect(() => {
        const el = mount({
            endpoint: '/api/rekhu/chat',
            navigate: (path) => router.push(path),   // pages open without a reload
            onAction: () => router.refresh(),        // an action changed data: refresh the page
        });
        return () => el?.destroy();
    }, [router]);
    return null;
}

A Nuxt plugin, plugins/rekhu-assistant.client.ts:

import { mount } from '@rekhu/assistant-widget';

export default defineNuxtPlugin(() => {
    const { loggedIn } = useUserSession();
    const router = useRouter();
    if (!loggedIn.value) return;

    mount({ endpoint: '/api/rekhu/chat', navigate: (path) => router.push(path), onAction: () => refreshNuxtData() });
});

Plain HTML, from a CDN, without a build step:

<script src="https://unpkg.com/@rekhu/assistant-widget@0.8/dist/rekhu-assistant.js"></script>
<script>
  RekhuAssistant.mount({ endpoint: '/api/rekhu/chat' });
</script>

#Signing the user in

The widget sends the user's own sign-in with every message, the way the rest of your front end does. Your back end decides who that is.

mount({
    endpoint: 'https://api.example.com/rekhu/assistant/chat',
    headers: () => ({ Authorization: `Bearer ${token.value}` }),
    credentials: 'omit',
    navigateOrigins: ['https://api.example.com'],
    navigate: (path, url) => router.push(url.pathname + url.search),
});

The token is the user's sign-in token for your back end, never your Rekhu key.

Warning: never put a secret key (agk_…) in front-end code: not in a component, not in a NEXT_PUBLIC_, NUXT_PUBLIC_ or VITE_ variable. Anyone who has it can use your Rekhu credit.

#Options

mount() returns the element, with open(), close(), configure(options) (for example a new token) and destroy(). It returns null during server rendering.

The widget sends DOM events that bubble to document: rekhu:action (an action ran), rekhu:error, rekhu:unauthorized (the sign-in ended, 401 or 419) and rekhu:report.

#Make it look like your app

Everything the widget draws can be restyled from your own CSS. Set variables on the element, and reach any part with ::part():

rekhu-assistant {
  --c: #0f766e;                 /* the accent: launcher, your messages, buttons */
  --rekhu-font: 15px/1.6 "Inter", sans-serif;
  --rekhu-bg: #ffffff;
  --rekhu-radius: 20px;
  --rekhu-width: 440px;
  --rekhu-height: 680px;
}

rekhu-assistant::part(panel) { inset-inline-end: 0; bottom: 0; height: 100vh; border-radius: 0; }
rekhu-assistant::part(message user) { background: #0f766e; }

The parts include launcher, panel, header, title, log, message (with user or bot), step, card, quick-button, input, send, chart and file-link.

#A chat screen of your own

For a chat that is entirely yours, use the connection without the widget. createClient speaks the same protocol with the same sign-in:

import { createClient, renderMessage } from '@rekhu/assistant-widget';

const chat = createClient({ endpoint: '/api/rekhu/chat' });

const { greeting, quick, messages } = await chat.history();
await chat.send('Where is my order?', (event) => {
    // start, text (append event.text), step, card (page, confirm, done, failed, file), error, done
});
await chat.confirm(card.id, onEvent);   // the user clicked Confirm on a confirm card

renderMessage(text) turns an answer into safe HTML with everything the widget draws: paragraphs, lists, tables, code, links and charts. Call it on the whole text each time a piece arrives. Everything the model writes is escaped, and links only go to http(s) addresses or your own paths.

#Next

• Conversation history: the list of earlier conversations, and the client calls behind it.
• Flutter: the same chat in a mobile app.