@akropolys/kiku 2.2.28 → 2.2.30

package/EMBED.md

@@ -1,11 +1,11 @@
-# Plain HTML embed
+# JavaScript 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.
+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="/kiku/kiku.js" data-site-id="YOUR_SITE_ID"
+<script src="https://cdn.akropolys.cloud/kiku/2.2.29/kiku.js" data-site-id="YOUR_SITE_ID"
   data-api-token="YOUR_PUBLIC_BROWSER_TOKEN" defer></script>
 ```
 
@@ -32,7 +32,32 @@ await Kiku.ingest({
 
 `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.
+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
@@ -41,4 +66,18 @@ 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.
+microphone permission.
+
+## CDN files and self-hosting
+
+- [Loader](https://cdn.akropolys.cloud/kiku/2.2.29/kiku.js)
+- [Stylesheet](https://cdn.akropolys.cloud/kiku/2.2.29/styles.css)
+- [Embed module](https://cdn.akropolys.cloud/kiku/2.2.29/embed/embed.js)
+
+To self-host, install `@akropolys/kiku@2.2.29` 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.

package/README.md

@@ -1,16 +1,34 @@
 # @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.
+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.29/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 @akropolys/sdk
+npm install @akropolys/kiku@2.2.29 @akropolys/sdk@2.0.2
 ```
 
-Requires React and React DOM 17 or later. For websites without React, use the [script embed](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md).
+This package integration requires React and React DOM 17 or later.
 
 ## React and Next.js
 
@@ -73,7 +91,7 @@ Both components use `AkropolysProvider` from `@akropolys/sdk`.
 
 ## 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-on-your-server).
+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, HTTP methods, and request fields in Shell. Kiku collects the required values and presents the result returned by your backend. Your endpoint validates the request and performs the operation. See the [site actions guide](https://github.com/akropolys/sdk/blob/HEAD/packages/sdk/README.md#site-actions).
 
@@ -81,7 +99,7 @@ Configure action endpoints, HTTP methods, and request fields in Shell. Kiku coll
 
 - [Akropolys](https://akropolys.cloud)
 - [Source code](https://github.com/akropolys/sdk)
-- [Plain HTML embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md)
+- [JavaScript embed guide](https://github.com/akropolys/sdk/blob/HEAD/packages/kiku/EMBED.md)
 - [Headless SDK](https://www.npmjs.com/package/@akropolys/sdk)
 
 ## License