@docgenlab.com/chat-widget

Embeddable AI knowledge-base chat widget for DocGenLab. Drop into any site to give your end-users a grounded, citation-backed assistant.

Features

• Floating launcher + chat panel (bottom-right or bottom-left)
• Streaming responses over Server-Sent Events
• Citation chips for every answer (sources linked to your KB documents)
• Optional image attachment (PNG/JPEG/WebP/GIF, max 10 MB)
• Mobile bottom-sheet layout under 480px
• Theme override (primary color, font, radius)
• Conversation persistence across page reloads (per-browser via localStorage)
• No external CSS framework — scoped class names, no global pollution

Security model

The agentKey you embed is a publishable key (pk_live_...). It will appear in the network tab. Like Stripe's publishable key, this is by design — security comes from:

1. Domain allowlist — register the customer's site domains against the key in your DocGenLab dashboard. Requests from other Origins are rejected.
2. Rate limit — per-key and per-IP, enforced server-side.
3. Org-level monthly quota — hard cap on total queries.

Never put a secret key (sk_live_...) in client code.

Install

npm install @docgenlab.com/chat-widget

Usage (React / Next.js / Vue / Svelte etc.)

import { DocGenLabChat } from '@docgenlab.com/chat-widget';
import '@docgenlab.com/chat-widget/style.css';

export function MyApp() {
    return (
        <DocGenLabChat
            agentKey="pk_live_..."
            position="bottom-right"
            theme={{ primary: '#7C3AED' }}
            greeting="Hi! Ask me anything about our product."
        />
    );
}

Usage (vanilla HTML — WordPress, marketing pages, anything without a build)

<link rel="stylesheet" href="https://unpkg.com/@docgenlab.com/chat-widget/dist/widget.css" />
<script src="https://unpkg.com/@docgenlab.com/chat-widget"></script>
<script>
    DocGenLab.init({
        agentKey: 'pk_live_...',
        position: 'bottom-right',
        theme: { primary: '#7C3AED' },
    });
</script>

To remove the widget later (e.g. on a sign-out page):

DocGenLab.destroy();

Configuration

| Prop | Type | Default | Description | |---|---|---|---| | agentKey | string | required | The pk_live_... key from your dashboard | | apiBaseUrl | string | https://api.docgenlab.com | Override for self-hosted / staging | | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Launcher corner | | theme.primary | string | #4F46E5 | Accent color (header, send button, user msg) | | theme.primaryText | string | #FFFFFF | Text on top of the primary color | | theme.radius | string | 14px | Border radius for panel/bubble | | theme.fontFamily | string | system stack | Font family | | greeting | string | "Hi — how can I help?" | Empty-state message | | agentName | string | from /agent API | Override the displayed name | | agentAvatarUrl | string | none | Optional avatar shown next to assistant msgs | | enableImageUpload | boolean | true | Allow end-users to attach screenshots | | hideBranding | boolean | false | Hide "Powered by DocGenLab" — paid tier | | openOnLoad | boolean | false | Auto-open the panel on first load | | endUserId | string | — | Customer's authenticated user id. Conversations follow this user across browsers + devices (vs the default anonymous-per-browser cookie). Without endUserHash, the id is unverified. | | endUserHash | string | — | HMAC-SHA256 of endUserId signed with your identity-verification secret. Required only when the agent enforces identity verification. | | onReady | (agent) => void | — | Fired when the agent resolves | | onError | (err) => void | — | Fired on unrecoverable errors |

Identity verification (optional)

For unauthenticated visitors, the widget assigns an anonymous UUID per browser via localStorage. Conversations are scoped to that UUID.

If your site has authenticated users and you want chat history to follow each user across devices:

<DocGenLabChat
    agentKey="pk_live_..."
    endUserId={currentUser.id}
    endUserHash={currentUser.docgenlabHash}
/>

Generate endUserHash on YOUR backend (never on the client) using HMAC-SHA256:

import { createHmac } from 'crypto';
const hash = createHmac('sha256', process.env.DOCGENLAB_IDENTITY_SECRET)
    .update(user.id)
    .digest('hex');

Without endUserHash, the user id is unverified (any browser can claim any id). Standard Intercom-style trust model.

Responsive behaviour

The widget adapts automatically across breakpoints:

• Phone portrait (≤480 wide): full-width bottom sheet, 90dvh tall (respects iOS Safari's collapsible bottom bar)
• Phone landscape / short screens (≤600 high): side panel anchored to the launcher corner, doesn't fight the on-screen keyboard
• Tablet (481–768 wide): slimmer 340px panel with reduced inset
• Tiny phones (≤360 wide): smaller launcher (48px), tightened padding
• Touch devices: larger tap-targets via @media (hover: none) and (pointer: coarse)

Browser support

ES2018+ targets. Edge, Chrome, Firefox, Safari (last 2 versions). IE11 not supported.

Bundle size

~50 KB gzipped (ESM, with React externalised). UMD bundle (React included) is ~95 KB gzipped.

Development

npm install
npm run dev      # Vite dev server
npm run build    # produces dist/index.js (ESM), dist/index.umd.cjs (UMD), dist/widget.css
npm run typecheck

License

UNLICENSED — internal DocGenLab project. Distribution to customers under separate commercial terms.