@aginies/webuikit 0.2.0

package/README.md

@@ -0,0 +1,75 @@
+# @aginies/webuikit
+
+React components and widgets that embed Aginies agents into any site: the hosted chat as a
+bubble, an inline panel or a full page, plus the core primitives of the Aginies design
+system. The package is public; rendering requires an activation token issued for your
+deployment, and the platform only answers origins listed in its configuration.
+
+```bash
+npm install @aginies/webuikit react react-dom
+```
+
+## Quick start
+
+```tsx
+import { init, AginiesProvider, ChatWidget } from '@aginies/webuikit'
+import '@aginies/webuikit/styles.css'
+
+init({ baseUrl: 'https://app.your-aginies.example', token: 'agn_…', locale: 'tr' })
+
+export function App() {
+  return (
+    <AginiesProvider>
+      <ChatWidget identifier='support' mode='bubble' />
+    </AginiesProvider>
+  )
+}
+```
+
+`init()` runs the activation handshake (`POST /api/ui/activate`) once. Until it succeeds
+the provider renders its `fallback`; if the platform refuses the token or the origin,
+nothing renders and one warning is logged.
+
+## Activation keys
+
+Two kinds of token work with `init()`:
+
+- **Tenant keys** (`agn_pk_…`) are created per tenant in the platform's admin console
+  (tenant page, "UI package keys"), each with its own list of allowed origins
+  (`https://www.example.com`, `https://*.example.com` or `*` for development), an
+  optional module list and an optional expiry. The key is publishable: it identifies the
+  tenant and unlocks nothing on its own. A successful activation returns a one-hour
+  session that the client sends as `Authorization: Bearer …` on every platform call and
+  renews on its own when it expires. Only the tenant's own chats can be reached through
+  it, and only the modules the key enables render; the rest render nothing and log one
+  warning. `client.getSession()` and `client.hasModule('chat')` expose both, and
+  `useModule('run')` does the same inside components.
+- **The static key** from the platform's `UI_PACKAGE_ACTIVATION_KEY` works for origins
+  listed in `UI_PACKAGE_ALLOWED_ORIGINS`. No session is involved: those origins are
+  trusted by configuration. Meant for the platform's own sites and local development.
+
+## Platform configuration
+
+| Variable | Purpose |
+|---|---|
+| `UI_PACKAGE_ACTIVATION_KEY` | The static activation token (optional when tenant keys are used). |
+| `UI_PACKAGE_ALLOWED_ORIGINS` | Comma-separated origins trusted without a tenant key (CORS, cookies, frame-ancestors). `*` for local development. |
+| `INTERNAL_API_SECRET` | Signs tenant sessions (already required by the platform). |
+
+## Components
+
+- `ChatWidget` — `identifier`, `mode` (`bubble` | `inline` | `full`), `position`, `launcherLabel`, `theme` (`dark` | `light` | `auto`). Streams replies, renders them as Markdown (headings, emphasis, code, links, lists, quotes, tables; never raw HTML), renders structured replies (text, buttons, table, cards, pie, image), lets visitors attach up to five files of 10 MB, and handles password and e-mail protected chats. E-mail protection follows the platform's two-step flow: the address receives a six-digit code, which the widget verifies.
+- `Markdown` — the same renderer on its own: `<Markdown text={reply} />`.
+- `AgentRunner` — `workflowId`, `apiKey` (an `execute`-scoped key for that agent only; it is visible to the page), `fields` (form spec) and `onResult`. Posts the form as the agent's input, streams text and steps, shows the final output. `useAgentRun(workflowId, apiKey)` for a custom UI.
+- `useChat(identifier)` — the same state for a custom UI: `messages`, `send`, `stop`, `busy`, `authNeed`, `authenticate`.
+- `ApprovalPanel` — `workflowId`, `executionId` (from the resume link a "Human in the Loop" block sends), optional `contextId`, `onResumed`. Shows what the agent proposes, renders the approver's form the block author configured (string, number, boolean, JSON, select), validates it and resumes the run; queued resumes are reported as such. `useApproval(workflowId, executionId)` for a custom UI; the `approval` module must be enabled on the key.
+- Observability (data-driven): `StatTiles`, `SuccessHeatmap` (per-agent success by day or hour, threshold-coloured), `RunTimeline` (steps on the run scale with tokens and cost), `CostBars` (cost by scenario, unit or channel).
+- Core: `Button`, `Tag`, `Chip`, `Panel`, `Eyebrow`, `Stat`, `Field`, `Input`, `Textarea`, `Spinner`.
+- `useChat(identifier)` — the widget's state for a custom UI: `messages`, `send(text, files)`, `stop`, `authenticate({ password })`, `requestCode(email)`, `verifyCode(email, code)`.
+- `AginiesClient` — the underlying client (`activate`, `getChat`, `sendMessage` as an async generator, `getSession`, `hasModule`, `fetchRaw` with the session attached).
+
+## Theming
+
+Styles come from `@aginies/tokens`: dark by default, `.light` / `[data-theme="light"]` on an
+ancestor (or the widget's `theme` prop) for the light palette. Override `--signal`,
+`--bg`, `--panel` and friends on a wrapper to whitelabel.