@akropolys/kiku 2.2.34 → 2.2.42

package/EMBED.md

@@ -1,103 +1,106 @@
-# JavaScript embed
-
-Add Kiku to any website with the published CDN script before your closing
-`</body>` tag. The same embed works with JavaScript frameworks, plain HTML, and
-HTMX. The loader fetches its stylesheet and embed module automatically.
-
-```html
-<script src="https://cdn.akropolys.cloud/kiku/2.2.33/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. Normal ingestion sends one record and works on every plan. An unsigned array uses the batch endpoint and requires Growth, Pro or Business. Signing is optional unless the site requires it in Shell; it is independent of normal versus batch ingestion.
-
-For a useful minimal record, send `{ id: 'chair-123', title: 'Linen lounge chair' }`.
-Add facts in `fields`. Use `image` for a cover and `images` for an ordered gallery
-of URLs or `{ url, alt?, caption? }` objects. Each record owns its own photos.
-Prefer absolute HTTPS image URLs; without a record webpage, use absolute URLs.
-The first gallery image is the cover unless `image` overrides it. Re-ingest the
-same ID to update the record or use `images: []` to clear its gallery.
-
-Reuse loaded data instead of fetching it again just for ingestion. Await
-`Kiku.ready` after automatic setup and catch errors from `Kiku.ingest`. An await
-inside an async callback does not block browser rendering. If the embed is
-loaded dynamically, wait for its script load before accessing `window.Kiku`.
-The embed does not accept the ingestion client's `batchSize` parameter.
-
-Update a record using the same ID and the full attributes/gallery to retain.
-Avoid per-view timestamps or counters in catalogue fields; repeated changes can
-use re-index allowance. Use live data for rapidly changing values when appropriate.
-Listing pages can publish loaded arrays with batch access. Call ingestion from
-your existing data-loading or refresh callback whenever fresh records arrive;
-the embed does not watch API requests automatically. Once indexed, updates are
-shared by every visitor using the same site ID, regardless of who triggered them.
-A browser can publish a complete catalogue array, including items not rendered
-on the page, without visits to each item's page. A paginated result covers only
-its supplied records. Ingestion does not fetch other API pages or refresh stale
-cached source data; full coverage does not require a server-side import.
-
-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.
-
-## CDN files and self-hosting
-
-- [Loader](https://cdn.akropolys.cloud/kiku/2.2.33/kiku.js)
-- [Stylesheet](https://cdn.akropolys.cloud/kiku/2.2.33/styles.css)
-- [Embed module](https://cdn.akropolys.cloud/kiku/2.2.33/embed/embed.js)
-
-To self-host, install `@akropolys/kiku@2.2.33` and copy `dist/kiku.js`,
-`dist/styles.css`, and the entire `dist/embed` directory to your server. Preserve
-their relative paths and use your hosted loader URL in the script tag. Serve
-JavaScript with the correct MIME type and allow CORS across origins.
-
-When building from this repository, run `pnpm --filter @akropolys/kiku build`
-to generate those files.
-
-## Site actions
-
-Register your API endpoints and JSON Schemas in Shell. Cookie-based APIs need no extra authentication configuration. Relative paths such as `/api/cart/items` resolve against the host website, including on localhost.
-
-For an API using Clerk, Auth0 or Supabase bearer tokens, manually mount with the website's existing login client:
-
-```js
-await Kiku.mount({
-  siteId,
-  apiToken,
-  actionAuth: { provider: "supabase", client: supabase },
-});
-```
-
-For Clerk use `{ provider: "clerk", client: clerk }`; for Auth0 use `{ provider: "auth0", client: auth0 }`. Remove `data-site-id` and `data-api-token` from the loader script when calling `Kiku.mount(options)`; pass them in the options instead. See [manual mounting](https://akropolys.cloud/docs/javascript/#manual-mounting). No application wrapper or React installation is needed. This configuration does not affect standalone batch ingestion.
-
-The SDK reads the current token through the existing auth client before every action in text and voice, and adds Authorization internally. The auth client owns renewal. Tokens go directly to the site's API. Adapters default to the page's origin; for a separate API, add `origins: ["https://api.your-site.com"]` and configure browser CORS. `actionHeaders` remains available for custom auth/CSRF headers.
-
-The API must validate the session/token and permissions. A `shopperId` or `userProof` does not authorize it. Return HTTP 401 JSON when sign-in is needed, rather than redirecting to a login screen. Shell's server tester does not share shopper cookies. After a timeout, check the actual site state before retrying a mutation. Read the [site actions guide](https://akropolys.cloud/docs/actions/) for both JavaScript and React examples and troubleshooting.
+# JavaScript embed
+
+Add Kiku to any website with the published CDN script before your closing
+`</body>` tag. The same embed works with JavaScript frameworks, plain HTML, and
+HTMX. The loader fetches its stylesheet and embed module automatically.
+
+```html
+<script src="https://cdn.akropolys.cloud/kiku/2.2.42/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. Normal ingestion sends one record and works on every plan. An unsigned array uses the batch endpoint and requires Growth, Pro or Business. Signing is optional unless the site requires it in Shell; it is independent of normal versus batch ingestion.
+
+For a useful minimal record, send `{ id: 'chair-123', title: 'Linen lounge chair' }`.
+Add facts in `fields`. Use `image` for a cover and `images` for an ordered gallery
+of URLs or `{ url, alt?, caption? }` objects. Each record owns its own photos.
+Prefer absolute HTTPS image URLs; without a record webpage, use absolute URLs.
+The first gallery image is the cover unless `image` overrides it. Re-ingest the
+same ID to update the record or use `images: []` to clear its gallery.
+
+Reuse loaded data instead of fetching it again just for ingestion. Await
+`Kiku.ready` after automatic setup and catch errors from `Kiku.ingest`. An await
+inside an async callback does not block browser rendering. If the embed is
+loaded dynamically, wait for its script load before accessing `window.Kiku`.
+The embed does not accept the ingestion client's `batchSize` parameter.
+
+Update a record using the same ID and the full attributes/gallery to retain.
+Avoid per-view timestamps or counters in catalogue fields; repeated changes can
+use re-index allowance. Use live data for rapidly changing values when appropriate.
+Listing pages can publish loaded arrays with batch access. Call ingestion from
+your existing data-loading or refresh callback whenever fresh records arrive;
+the embed does not watch API requests automatically. Once indexed, updates are
+shared by every visitor using the same site ID, regardless of who triggered them.
+A browser can publish a complete catalogue array, including items not rendered
+on the page, without visits to each item's page. A paginated result covers only
+its supplied records. Ingestion does not fetch other API pages or refresh stale
+cached source data; full coverage does not require a server-side import.
+
+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. Kiku loads its audio processor as a version-matched JavaScript file; allow its origin in `script-src` when using a restrictive CSP.
+
+## CDN files and self-hosting
+
+- [Loader](https://cdn.akropolys.cloud/kiku/2.2.42/kiku.js)
+- [Stylesheet](https://cdn.akropolys.cloud/kiku/2.2.42/styles.css)
+- [Embed module](https://cdn.akropolys.cloud/kiku/2.2.42/embed/embed.js)
+- [Voice audio processor](https://cdn.akropolys.cloud/kiku/2.2.42/voice-worklet.js)
+
+To self-host this release, copy `dist/kiku.js`, `dist/styles.css`,
+`dist/voice-worklet.js`, and the entire `dist/embed` directory to your server. Preserve
+their relative paths and use your hosted loader URL in the script tag. Serve
+JavaScript with the correct MIME type and allow CORS across origins.
+
+When building from this repository, run `pnpm --filter @akropolys/kiku build`
+to generate those files.
+
+## Site actions
+
+Register your API endpoints and JSON Schemas in Shell. Cookie-based APIs need no extra authentication configuration. Relative paths such as `/api/cart/items` resolve against the host website, including on localhost.
+
+For an API using Clerk, Auth0 or Supabase bearer tokens, manually mount with the website's existing login client:
+
+```js
+await Kiku.mount({
+  siteId,
+  apiToken,
+  actionAuth: { provider: "supabase", client: supabase },
+});
+```
+
+For Clerk use `{ provider: "clerk", client: clerk }`; for Auth0 use `{ provider: "auth0", client: auth0 }`. Remove `data-site-id` and `data-api-token` from the loader script when calling `Kiku.mount(options)`; pass them in the options instead. See [manual mounting](https://akropolys.cloud/docs/javascript/#manual-mounting). No application wrapper or React installation is needed. This configuration does not affect standalone batch ingestion.
+
+The SDK reads the current token through the existing auth client before every action in text and voice, and adds Authorization internally. The auth client owns renewal. Tokens go directly to the site's API. Adapters default to the page's origin; for a separate API, add `origins: ["https://api.your-site.com"]` and configure browser CORS. `actionHeaders` remains available for custom auth/CSRF headers.
+
+The API must validate the session/token and permissions. A `shopperId` or `userProof` does not authorize it. Return HTTP 401 JSON when sign-in is needed, rather than redirecting to a login screen. Shell's server tester does not share shopper cookies. After a timeout, check the actual site state before retrying a mutation. Read the [site actions guide](https://akropolys.cloud/docs/actions/) for both JavaScript and React examples and troubleshooting.
+
+For a self-hosted React package, copy `dist/voice-worklet.js` to your site and set `voiceWorkletUrl` on `KikuButton` to its URL. Without an override, React uses the version-matched CDN file.

package/README.md

@@ -1,107 +1,107 @@
-# @akropolys/kiku
-
-Chat, search, voice, and photo input for your website. Kiku connects visitors to your content and the API actions you configure in Akropolys. For React and Next.js, use the React package below. For other websites, use the CDN embed; it also works in React when you prefer a script integration.
-
-[![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/)
-
-## JavaScript embed
-
-Add Kiku to any website with the published CDN script:
-
-```html
-<script
-  src="https://cdn.akropolys.cloud/kiku/2.2.33/kiku.js"
-  data-site-id="YOUR_SITE_ID"
-  data-api-token="YOUR_PUBLIC_BROWSER_TOKEN"
-  data-label="Ask Kiku"
-  defer
-></script>
-```
-
-The embed includes its own React runtime, styles, and mounting. Your website needs no React installation or provider, including when it uses React or Next.js. See the [embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md) for configuration, ingestion, and self-hosting.
-
-## Install
-
-Recommended for React and Next.js apps:
-
-```bash
-npm install @akropolys/kiku@2.2.33 @akropolys/sdk@2.0.5
-```
-
-This package integration requires React and React DOM 17 or later.
-
-## React and Next.js
-
-```tsx
-'use client';
-
-import { AkropolysProvider } from '@akropolys/sdk';
-import { KikuButton } from '@akropolys/kiku';
-import '@akropolys/kiku/styles.css';
-
-export default function WebsiteAssistant() {
-  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_TOKEN!}
-    >
-      <KikuButton label="Ask us" enableVoice enableVision />
-    </AkropolysProvider>
-  );
-}
-```
-
-Mount the component once in your app or layout. In Next.js App Router, import the stylesheet in your root layout if that is where your project keeps global CSS.
-
-Use your site's public browser token. Keep private keys and server credentials on your server. Enable the corresponding voice and vision features for your site in Shell.
-
-## What visitors can do
-
-- Ask about your content and compare records in tables.
-- Talk using live voice or include photos in a conversation.
-- Open source records and save items for later.
-- Long-press or right-click a message to access its actions.
-- Use translated controls, right-to-left layouts, and chat themes.
-
-## Components
-
-| Component | Purpose |
-| --- | --- |
-| `KikuButton` | A launcher that opens the chat window. |
-| `SearchBar` | Inline search with streamed results. |
-
-Both components use `AkropolysProvider` from `@akropolys/sdk`.
-
-## Customize the launcher
-
-```tsx
-<KikuButton
-  label="Ask about this property"
-  title="Your assistant"
-  placeholder="What would you like to know?"
-  chips={['Show available properties', 'Compare my options']}
-  theme="dark"
-  enableVoice
-  enableVision
-/>
-```
-
-`theme` accepts `light`, `dark`, or an `AkropolysTheme` object from `@akropolys/sdk`. Use `onSelectSource` to handle a visitor selecting a source record.
-
-## Your content and actions
-
-Give each catalogue record a stable top-level `id`. A webpage link in `fields.url` is optional; Kiku can show and save records without one. See the [SDK ingestion guide](https://github.com/akropolys/sdk/blob/HEAD/packages/sdk/README.md#batch-ingestion-client).
-
-Configure action endpoints, methods and request fields in Shell. The widget calls your API from the visitor's browser in chat and voice. Cookie authentication works automatically. For Clerk, Auth0 or Supabase bearer APIs, add one option such as `actionAuth: { provider: "supabase", client: supabase }` to `Kiku.mount(...)`, or use the `actionAuth` prop on your existing React provider. The existing auth client handles token renewal; Kiku adds the header internally. The CDN embed needs no application wrapper. Your API validates permissions and performs the operation. See the [site actions guide](https://akropolys.cloud/docs/actions/).
-
-## Links
-
-- [Akropolys](https://akropolys.cloud)
-- [Source code](https://github.com/akropolys/sdk)
-- [JavaScript embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md)
-- [Headless SDK](https://www.npmjs.com/package/@akropolys/sdk)
-
-## License
-
-MIT © [Akropolys](https://akropolys.cloud)
+# @akropolys/kiku
+
+Chat, search, voice, and photo input for your website. Kiku connects visitors to your content and the API actions you configure in Akropolys. For React and Next.js, use the React package below. For other websites, use the CDN embed; it also works in React when you prefer a script integration.
+
+[![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/)
+
+## JavaScript embed
+
+Add Kiku to any website with the published CDN script:
+
+```html
+<script
+  src="https://cdn.akropolys.cloud/kiku/2.2.42/kiku.js"
+  data-site-id="YOUR_SITE_ID"
+  data-api-token="YOUR_PUBLIC_BROWSER_TOKEN"
+  data-label="Ask Kiku"
+  defer
+></script>
+```
+
+The embed includes its own React runtime, styles, and mounting. Your website needs no React installation or provider, including when it uses React or Next.js. See the [embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md) for configuration, ingestion, and self-hosting.
+
+## Install
+
+Recommended for React and Next.js apps:
+
+```bash
+npm install @akropolys/kiku@2.2.42 @akropolys/sdk@2.0.7
+```
+
+This package integration requires React and React DOM 17 or later.
+
+## React and Next.js
+
+```tsx
+'use client';
+
+import { AkropolysProvider } from '@akropolys/sdk';
+import { KikuButton } from '@akropolys/kiku';
+import '@akropolys/kiku/styles.css';
+
+export default function WebsiteAssistant() {
+  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_TOKEN!}
+    >
+      <KikuButton label="Ask us" enableVoice enableVision />
+    </AkropolysProvider>
+  );
+}
+```
+
+Mount the component once in your app or layout. In Next.js App Router, import the stylesheet in your root layout if that is where your project keeps global CSS.
+
+Use your site's public browser token. Keep private keys and server credentials on your server. Enable the corresponding voice and vision features for your site in Shell.
+
+## What visitors can do
+
+- Ask about your content and compare records in tables.
+- Talk using live voice or include photos in a conversation.
+- Open source records and save items for later.
+- Long-press or right-click a message to access its actions.
+- Use translated controls, right-to-left layouts, and chat themes.
+
+## Components
+
+| Component | Purpose |
+| --- | --- |
+| `KikuButton` | A launcher that opens the chat window. |
+| `SearchBar` | Inline search with streamed results. |
+
+Both components use `AkropolysProvider` from `@akropolys/sdk`.
+
+## Customize the launcher
+
+```tsx
+<KikuButton
+  label="Ask about this property"
+  title="Your assistant"
+  placeholder="What would you like to know?"
+  chips={['Show available properties', 'Compare my options']}
+  theme="dark"
+  enableVoice
+  enableVision
+/>
+```
+
+`theme` accepts `light`, `dark`, or an `AkropolysTheme` object from `@akropolys/sdk`. Use `onSelectSource` to handle a visitor selecting a source record.
+
+## Your content and actions
+
+Give each catalogue record a stable top-level `id`. A webpage link in `fields.url` is optional; Kiku can show and save records without one. See the [SDK ingestion guide](https://github.com/akropolys/sdk/blob/HEAD/packages/sdk/README.md#batch-ingestion-client).
+
+Configure action endpoints, methods and request fields in Shell. The widget calls your API from the visitor's browser in chat and voice. Cookie authentication works automatically. For Clerk, Auth0 or Supabase bearer APIs, add one option such as `actionAuth: { provider: "supabase", client: supabase }` to `Kiku.mount(...)`, or use the `actionAuth` prop on your existing React provider. The existing auth client handles token renewal; Kiku adds the header internally. The CDN embed needs no application wrapper. Your API validates permissions and performs the operation. See the [site actions guide](https://akropolys.cloud/docs/actions/).
+
+## Links
+
+- [Akropolys](https://akropolys.cloud)
+- [Source code](https://github.com/akropolys/sdk)
+- [JavaScript embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md)
+- [Headless SDK](https://www.npmjs.com/package/@akropolys/sdk)
+
+## License
+
+MIT © [Akropolys](https://akropolys.cloud)