# @akintu/widget

Framework-independent Web Components and optional React wrappers for Akintu Embed and Inline chat
surfaces.

## Installation

```bash
npm install @akintu/widget
```

The package is ESM-only. React is an optional peer dependency and is required only when importing
`@akintu/widget/react`.

## Vanilla JavaScript

Place the surfaces where they should appear, then initialize the page once:

```html
<akintu-embed></akintu-embed>
<div data-akintu-context="pricing"></div>
```

```ts
import { initAkintu } from "@akintu/widget";

await initAkintu({ apiKey: "YOUR_CLIENT_KEY" });
```

Embed and Inline are mounted only when the matching remote feature is enabled by
`GET /api/widget-config`. The floating widget is not part of v1.

## React and Next.js

```tsx
"use client";

import { AkintuEmbed, AkintuInline } from "@akintu/widget/react";

export function AkintuSurfaces() {
  return (
    <>
      <AkintuEmbed apiKey="YOUR_CLIENT_KEY" />
      <AkintuInline apiKey="YOUR_CLIENT_KEY" context="pricing" />
    </>
  );
}
```

The React entry is safe to import during server rendering. Browser initialization happens in an
effect after hydration.

## Client key and API host

The client key is intentionally used in browser code and must be restricted to the authorized
origins configured for its tenant. Create a dedicated key for each installation. The widget keeps
the key in request memory and never writes it to element attributes, storage, logs, or errors.

Requests target `https://api.akintu.io` by default. Development and self-hosted environments can
set `apiBaseUrl`:

```ts
await initAkintu({
  apiKey: "YOUR_CLIENT_KEY",
  apiBaseUrl: "http://localhost:3003",
});
```

Only the versioned conversation `sessionId` is persisted in `localStorage`.

## Runtime behavior

- The API configuration is authoritative for Embed, Inline, STT, TTS, and theme values.
- Every surface renders inside an open Shadow DOM to isolate host and widget styles.
- Chat responses are progressively rendered from validated SSE events.
- Assistant Markdown is rendered as safe semantic DOM for headings, lists, emphasis, and inline
  code; model-provided HTML remains inert text.
- Source UUIDs stay internal until the API exposes safe public source metadata.
- Accessibility adapters are loaded only when their remote flags are enabled.

## Build outputs

- `dist/esm`: npm ESM runtime, React wrapper, declarations, and source maps.
- `dist/loader/v1/loader.js`: versioned IIFE artifact for a future CDN channel.
- `dist/loader/v1/accessibility`: optional STT and TTS ESM chunks.

The npm package is self-contained and has no dependency on private Akintu workspace packages.

## Verification

```bash
pnpm --filter @akintu/widget test
pnpm --filter @akintu/widget build
pnpm --filter @akintu/widget verify:package
pnpm --filter @akintu/widget test:e2e
```

`verify:package` installs the generated tarball into a temporary project outside the monorepo,
imports the ESM entry, and compiles a TypeScript consumer. Browser tests use a deterministic SSE
server and aggressive host CSS resets; a staging smoke test against the real API remains a
separate release check.

## License

Copyright (C) 2026 DigiWaves SAS. Released under the
[GNU General Public License v2.0 or later](./LICENSE).