@akropolys/kiku 2.2.24 → 2.2.26

package/EMBED.md

@@ -1,44 +1,44 @@
-# Plain HTML embed
-
-Build with `pnpm --filter @akropolys/kiku build`. Host `dist/kiku.js`, `dist/styles.css`, and the entire
-`dist/embed` directory together, preserving their relative paths. Serve JavaScript
-with the correct MIME type and allow CORS when hosting assets on another origin.
-
-```html
-<script src="/kiku/kiku.js" data-site-id="YOUR_SITE_ID"
-  data-api-token="YOUR_PUBLIC_BROWSER_TOKEN" defer></script>
-```
-
-Use the same public browser token as your existing frontend integration. Never
-put secret keys or signing keys in HTML. The embed uses the same domain and
-authentication checks as the React integration. React is bundled privately;
-the host website does not install it. One widget is supported per page.
-
-For configuration in JavaScript, omit the data attributes and call this after
-the script loads:
-
-```js
-await Kiku.mount({
-  siteId: 'YOUR_SITE_ID',
-  apiToken: 'YOUR_PUBLIC_BROWSER_TOKEN',
-  button: { label: 'Ask us', enableVoice: true },
-});
-await Kiku.open();
-await Kiku.ingest({
-  id: 'example', title: 'Example', url: location.href,
-  fields: { description: 'Your page data' },
-});
-```
-
-`Kiku.ingest()` accepts one entity, an array, or signed ingestion records and
-returns the API response. Supply data explicitly; the embed does not guess a
-website's schema. Existing server ingestion works unchanged.
-
-After login, call `Kiku.updateIdentity({ shopperId, userProof })` with a proof
-issued by your server. On logout pass `{}`. `Kiku.destroy()` removes the widget
-and cleans up its client; call `mount()` again to restart. Automatic mounting
-exposes `Kiku.ready`. Repeated script tags or mount calls reuse the same widget.
-
-For a restrictive CSP, permit the script origin, existing API/voice endpoints,
-and the styles/fonts already needed by Kiku. Voice still requires HTTPS and
-microphone permission. No production embed URL has been published yet.
+# Plain HTML embed
+
+Build with `pnpm --filter @akropolys/kiku build`. Host `dist/kiku.js`, `dist/styles.css`, and the entire
+`dist/embed` directory together, preserving their relative paths. Serve JavaScript
+with the correct MIME type and allow CORS when hosting assets on another origin.
+
+```html
+<script src="/kiku/kiku.js" data-site-id="YOUR_SITE_ID"
+  data-api-token="YOUR_PUBLIC_BROWSER_TOKEN" defer></script>
+```
+
+Use the same public browser token as your existing frontend integration. Never
+put secret keys or signing keys in HTML. The embed uses the same domain and
+authentication checks as the React integration. React is bundled privately;
+the host website does not install it. One widget is supported per page.
+
+For configuration in JavaScript, omit the data attributes and call this after
+the script loads:
+
+```js
+await Kiku.mount({
+  siteId: 'YOUR_SITE_ID',
+  apiToken: 'YOUR_PUBLIC_BROWSER_TOKEN',
+  button: { label: 'Ask us', enableVoice: true },
+});
+await Kiku.open();
+await Kiku.ingest({
+  id: 'example', title: 'Example',
+  fields: { description: 'Your page data', url: location.href },
+});
+```
+
+`Kiku.ingest()` accepts one entity, an array, or signed ingestion records and
+returns the API response. Supply data explicitly; the embed does not guess a
+website's schema. Every catalogue record requires its source record's stable top-level `id`. `fields.url` is optional but recommended when a webpage is available; Kiku can show and save records without one. A supplied URL is kept in saved history. URLs, names and signatures do not replace IDs. Existing server records must also include an ID.
+
+After login, call `Kiku.updateIdentity({ shopperId, userProof })` with a proof
+issued by your server. On logout pass `{}`. `Kiku.destroy()` removes the widget
+and cleans up its client; call `mount()` again to restart. Automatic mounting
+exposes `Kiku.ready`. Repeated script tags or mount calls reuse the same widget.
+
+For a restrictive CSP, permit the script origin, existing API/voice endpoints,
+and the styles/fonts already needed by Kiku. Voice still requires HTTPS and
+microphone permission. No production embed URL has been published yet.

package/README.md

@@ -1,68 +1,78 @@
-# @akropolys/kiku
-
-Pre-built, blindly agnostic multi-modal conversational AI widget with duplex Live Voice, Computer Vision, and real-time comparative tables for any website or transactional platform.
-
-[![npm](https://img.shields.io/npm/v/@akropolys/kiku?color=orange)](https://www.npmjs.com/package/@akropolys/kiku) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/types-included-blue)](https://www.typescriptlang.org/)
-
----
-
-## Install
-
-```bash
-npm install @akropolys/kiku @akropolys/sdk
-# or
-pnpm add @akropolys/kiku @akropolys/sdk
-```
-
----
-
-## Usage (React / Next.js)
-
-```tsx
-import { AkropolysProvider } from '@akropolys/sdk';
-import { KikuButton } from '@akropolys/kiku';
-import '@akropolys/kiku/styles.css'; // required: the chat window copies its rules from this sheet (serve it same-origin, or with crossorigin="anonymous")
-
-export default function App() {
-  return (
-    <AkropolysProvider
-      siteId={process.env.NEXT_PUBLIC_AKROPOLYS_SITE_ID!}
-      apiUrl={process.env.NEXT_PUBLIC_AKROPOLYS_API_URL!}
-      apiToken={process.env.NEXT_PUBLIC_AKROPOLYS_API_KEY!}
-    >
-      <KikuButton
-        label="Ask me anything"
-        enableVoice={true}
-        enableVision={true}
-        theme={{
-          borderRadius: "24px",
-        }}
-      />
-    </AkropolysProvider>
-  );
-}
-```
-
-> **Next.js Note**: If running an experimental Next.js 15/16 canary with Tailwind CSS v4 on Windows, run `next dev --webpack` if Turbopack experiences resolver latency on Windows ([tracked upstream](https://github.com/vercel/next.js/issues)).
-
----
-
-## Components
-
-| Component | Description |
-|---|---|
-| `<KikuButton />` | Launcher pill that opens the full-screen chat, with live voice and vision. |
-| `<SearchBar />` | Inline catalogue search with streamed results. |
-| `<ScoutRail />` | Dock for the shopper's scouts: send one out, check on it, buy time. |
-| `<ScoutCharacter />` | A single animated scout avatar. |
-
-
----
-
-## License
-
-MIT © [Akropolys](https://akropolys.cloud)
-
-### Plain HTML and other frameworks
-
-Use the standalone script embed without installing React on your website. See [EMBED.md](./EMBED.md) for setup, ingestion, and identity updates.
+# @akropolys/kiku
+
+Pre-built, blindly agnostic multi-modal conversational AI widget with duplex Live Voice, Computer Vision, and real-time comparative tables for any website or transactional platform.
+
+[![npm](https://img.shields.io/npm/v/@akropolys/kiku?color=orange)](https://www.npmjs.com/package/@akropolys/kiku) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/types-included-blue)](https://www.typescriptlang.org/)
+
+---
+
+## Install
+
+```bash
+npm install @akropolys/kiku @akropolys/sdk
+# or
+pnpm add @akropolys/kiku @akropolys/sdk
+```
+
+---
+
+## Usage (React / Next.js)
+
+```tsx
+import { AkropolysProvider } from '@akropolys/sdk';
+import { KikuButton } from '@akropolys/kiku';
+import '@akropolys/kiku/styles.css'; // required: the chat window copies its rules from this sheet (serve it same-origin, or with crossorigin="anonymous")
+
+export default function App() {
+  return (
+    <AkropolysProvider
+      siteId={process.env.NEXT_PUBLIC_AKROPOLYS_SITE_ID!}
+      apiUrl={process.env.NEXT_PUBLIC_AKROPOLYS_API_URL!}
+      apiToken={process.env.NEXT_PUBLIC_AKROPOLYS_API_KEY!}
+    >
+      <KikuButton
+        label="Ask me anything"
+        enableVoice={true}
+        enableVision={true}
+        theme={{
+          borderRadius: "24px",
+        }}
+      />
+    </AkropolysProvider>
+  );
+}
+```
+
+> **Next.js Note**: If running an experimental Next.js 15/16 canary with Tailwind CSS v4 on Windows, run `next dev --webpack` if Turbopack experiences resolver latency on Windows ([tracked upstream](https://github.com/vercel/next.js/issues)).
+
+---
+
+## Records and saved history
+
+Ingest each catalogue record with a stable top-level `id`. Put its optional, recommended webpage link in `fields.url`. Kiku can show and save ID-only records and retains a supplied link in saved history. See the [SDK ingestion guide](../sdk/README.md#batch-ingestion-on-your-server) for examples.
+
+## Site actions
+
+Configure permitted actions and their request fields in Shell. Kiku collects the required values and explains the result returned by your backend. Cart updates, bookings, and other operations run through those endpoints; the widget does not maintain a separate cart or dispatch cart reducers.
+
+Remove the former action callbacks and browser action listeners when upgrading. See the [SDK action guide](../sdk/README.md#site-actions) for migration details.
+
+## Components
+
+| Component | Description |
+|---|---|
+| `<KikuButton />` | Launcher pill that opens the full-screen chat, with live voice and vision. |
+| `<SearchBar />` | Inline catalogue search with streamed results. |
+| `<ScoutRail />` | Dock for the shopper's scouts: send one out, check on it, buy time. |
+| `<ScoutCharacter />` | A single animated scout avatar. |
+
+
+---
+
+## License
+
+MIT © [Akropolys](https://akropolys.cloud)
+
+### Plain HTML and other frameworks
+
+Use the standalone script embed without installing React on your website. See [EMBED.md](./EMBED.md) for setup, ingestion, and identity updates.