@hachther/akilio-widget 0.7.0 → 1.1.0

package/README.md

@@ -63,10 +63,7 @@ placed at the bottom-left or displayed as a vertical tab in the middle of the
 right viewport edge:
 
 ```tsx
-<AkilioWidget
-  projectKey='your-project-key'
-  launcherPosition='right-middle'
-/>
+<AkilioWidget projectKey='your-project-key' launcherPosition='right-middle' />
 ```
 
 Supported values are `bottom-right`, `bottom-left`, and `right-middle`. The
@@ -76,6 +73,22 @@ the compact bottom-right launcher and the normal mobile presentation.
 
 The standalone equivalent is `data-launcher-position="right-middle"`.
 
+## Adaptive launcher
+
+The built-in launcher defaults to Akilio’s compact adaptive experience: it
+appears as an icon, expands once with a page-aware invitation, then stays quiet.
+It can show a single answer-ready signal when a response completes while chat is
+closed. Discovery and dismissal are remembered per project, and motion is
+automatically reduced for visitors who request it.
+
+Use the original persistent label while validating the new experience:
+
+```tsx
+<AkilioWidget launcherExperience='static' />
+```
+
+Standalone scripts use `data-launcher-experience="static"`.
+
 ## Page-end contextual prompt
 
 Documentation pages can show a compact “Ask about this page” input when the
@@ -181,11 +194,7 @@ and is dismissed when the visitor closes it, opens the widget, or presses
 Escape. Dismissal is stored per project and tour version.
 
 ```tsx
-<AkilioWidget
-  enableTour
-  tourDelayMs={3000}
-  tourVersion="v1"
-/>
+<AkilioWidget enableTour tourDelayMs={3000} tourVersion='v1' />
 ```
 
 Standalone attributes are `data-enable-tour`, `data-tour-delay-ms`, and
@@ -203,12 +212,14 @@ preferences.
 ## Capability-driven chat actions
 
 The widget reads `capabilities.chat` from the public project configuration. An
-enabled `summarize_page` intent that supports the `widget` surface is shown as
-an explicit “Summarize this page” action when its `page.url` requirement is
-available. Selecting it sends `intent: "summarize_page"` and the current page
-context to the chat endpoint. Unsupported, disabled, wrong-surface, or
-unmet-requirement actions are not displayed. Older API responses without the
-capability catalog retain the previous suggestion behavior.
+enabled `summarize_page` intent that supports the `widget` surface is shown in
+an action tray immediately above the composer when its `page.url` requirement
+is available. Selecting it sends `intent: "summarize_page"` and the current
+page context to the chat endpoint. Unsupported, disabled, wrong-surface, or
+unmet-requirement actions are not displayed. The action tray remains available
+throughout the conversation and is temporarily hidden while a response streams.
+Older API responses without the capability catalog retain the previous
+suggestion behavior.
 
 An enabled `contact` intent adds a “Contact the team” action. Contact responses
 can display validated `email`, `phone`, and `form` links from `contact_options`.
@@ -245,7 +256,11 @@ dist/index.min.js
 dist/index.umd.min.cjs
 dist/index.d.ts
 dist/style.css
+dist/loader.js
+dist/widget-manifest.json
+dist/releases/0.7.0/akilio-widget.min.js
 dist/akilio-widget.min.js
+dist/_headers
 ```
 
 ## React
@@ -315,10 +330,13 @@ The token resolver is evaluated for every request, so a host application can rot
 
 ## Standalone script
 
+For production websites, use the stable loader URL:
+
 ```html
 <script
   data-akilio-widget
-  src="/assets/akilio-widget.min.js"
+  data-cfasync="false"
+  src="https://cdn.example.com/widget/loader.js"
   data-api-base-url="https://api.akilio-ai.com"
   data-project-key="ask_pk_xxx"
   data-mode="floating"
@@ -334,19 +352,76 @@ For an inline widget:
 
 ```html
 <div id="support-assistant" style="height: 680px"></div>
-<script src="/assets/akilio-widget.min.js" data-auto-init="false"></script>
+<script
+  src="https://cdn.example.com/widget/loader.js"
+  data-akilio-widget
+  data-auto-init="false"
+></script>
 <script>
-  window.Akilio.mount({
-    target: '#support-assistant',
-    apiBaseUrl: 'https://api.akilio-ai.com',
-    projectKey: 'ask_pk_xxx',
-    mode: 'inline',
-    colorMode: 'system',
-    accessToken: 'short-lived-widget-token',
+  window.addEventListener('akilio:loader-ready', () => {
+    window.Akilio.mount({
+      target: '#support-assistant',
+      apiBaseUrl: 'https://api.akilio-ai.com',
+      projectKey: 'ask_pk_xxx',
+      mode: 'inline',
+      colorMode: 'system',
+      accessToken: 'short-lived-widget-token',
+    });
   });
 </script>
 ```
 
+`loader.js` is revalidated by the browser and loads the immutable release file
+for the current package version. Deploy the complete `dist` directory without
+deleting earlier `dist/releases/*` versions. Each build also keeps
+`akilio-widget.min.js` as a non-immutable compatibility file.
+
+For optional Cloudflare Pages deployments, the generated `dist/_headers` requires browser and edge
+revalidation for `loader.js` and `widget-manifest.json`. Files under
+`releases/*` receive a one-year immutable browser and edge cache. Configure
+Cloudflare Browser Cache TTL to **Respect Existing Headers** for this path so a
+cache rule does not keep the loader stale.
+
+Cloudflare R2 does not use `_headers`; the R2 deployment command writes the
+equivalent `Cache-Control` metadata on each uploaded object.
+
+Publishing a new package version updates only the loader and manifest pointers;
+existing embed snippets do not change and a manual cache purge is not normally
+required. The manifest includes the active version, release path, byte size,
+and SHA-256 digest for deployment verification.
+
+### Deploy to Cloudflare R2
+
+Set the R2 bucket name in your local `.env` or shell environment:
+
+```bash
+CLOUDFLARE_R2_BUCKET=your-r2-bucket
+# Optional folder within the bucket:
+CLOUDFLARE_R2_PREFIX=widget
+```
+
+Then validate, build, and publish the CDN assets with:
+
+```bash
+npm run deploy:r2
+```
+
+You can also provide the target without storing it in `.env`:
+
+```bash
+npm run deploy:r2 -- --bucket your-r2-bucket --prefix widget
+```
+
+Wrangler uses an existing local Cloudflare login. In CI, provide
+`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` as protected environment
+variables. Never commit a Cloudflare API token.
+
+The deploy command uploads the immutable versioned bundle first, followed by
+the compatibility bundle, manifest, and finally `loader.js`. The versioned file
+receives a one-year immutable cache policy. Stable files receive
+`max-age=0, must-revalidate`, so the CDN entry point can discover each release.
+Add `--dry-run` to build and inspect the target object paths without uploading.
+
 The standalone API can hide the launcher and control the chat imperatively:
 
 ```js
@@ -476,7 +551,10 @@ The package itself is now safe to import in an SSR module. The component must st
 
 ## Ecommerce responses
 
-When the chat API returns a `commerce` capability, the widget automatically displays its products below the assistant answer. No additional configuration is required.
+When the chat API returns a `commerce` capability, the widget renders a compact
+commerce surface inside the assistant message. Direct matches, recommendations,
+comparisons, compatible products, bundles, upsells, and cross-sells receive
+capability-aware headings and layouts.
 
 ```tsx
 <AkilioWidget
@@ -488,7 +566,42 @@ When the chat API returns a `commerce` capability, the widget automatically disp
 />
 ```
 
-Product links open in a new tab. The widget also sends an authenticated commerce event to `/api/v1/commerce/events/` using the response capability (`search` or `recommendation`).
+Product links open through the existing product callback. Trusted
+`commerce.actions` are matched only to products returned in the same response.
+`add_to_cart` proposals require a second explicit confirmation, then use the
+backend's one-time capability-confirmation flow and an idempotency key before a
+cart tool is executed. The provider cart ID is retained in `sessionStorage` for
+subsequent additions during the same browser session. The widget also records
+authenticated commerce events.
+
+The widget refreshes `GET /commerce/cart/current/` whenever its chat panel is
+opened. The header cart control shows the returned line items and only exposes a
+checkout link supplied by the backend. A chat response with `cart_state` causes
+an immediate refresh, ensuring the local cart display follows server-side cart
+changes without treating the compact summary as the source of truth.
+
+### `/chat/` response contract
+
+`AkilioChatResponse` follows the public OpenAPI `ChatResponse` schema. It
+supports documented conversation context, answer content, citations, commerce,
+suggestions, warnings, market resolution, grounding/refusal flags, escalation,
+contact options, customer actions, agent tools, and intent decisions. Commerce
+products and actions are runtime-validated before they are rendered because the
+OpenAPI schema deliberately leaves those objects extensible.
+
+The documented response does not include top-level `images`, `rich_actions`,
+`forms`, or `cart` fields. The widget does not treat those fields as part of its
+public chat contract. Add them to the backend OpenAPI schema before introducing
+matching widget rendering.
+
+## Human handoff
+
+When a configured contact action is submitted, the widget sends its consented
+request to `POST /chat/contact-requests/` with the conversation and assistant
+message that offered the action. `POST /chat/handoffs/` is an equivalent backend
+alias. The backend derives the conversation summary, intent, customer context,
+and action context from the validated conversation. The widget renders the
+browser-safe handoff delivery status returned by the API.
 
 ## Assistant mode
 
@@ -519,3 +632,195 @@ For the standalone build:
 ## Follow-up suggestions
 
 When `/api/v1/chat/` returns a `suggestions` array, the widget displays accessible suggestion chips under that assistant response. Selecting a chip sends it as the next user message. Suggestions are retained in local history and restored from server conversation message metadata or structured content when supplied by the API.
+
+## Widget Core (AKI-WIDGET-001)
+
+Built-in interface translations cover English and French (including regional
+locales such as `fr-CA`). Supply `locale` and `copy` for other languages; missing
+translations fall back to English. The widget sets its language and direction
+for common right-to-left locales. The standalone script reads the page language.
+The backend receives the requested locale for generated responses.
+
+White-label policy hides Akilio marks in the launcher, discovery tip, header,
+messages, and confirmation cards. Default text becomes neutral; explicitly
+configured project titles and copy remain under the integrator's control.
+
+History, preferences, configuration, and anonymous continuation credentials use
+browser storage with an in-memory fallback when storage is blocked or full.
+Persistent storage is required to resume after a full page reload; memory-only
+sessions remain usable during the current visit. History is scoped by project
+and locale and retains the latest 60 messages.
+
+Mobile forms use 16px inputs and main controls have 44px touch targets, alongside
+viewport sizing and safe-area padding. Physical-device keyboard testing and live
+backend acceptance testing are still required before production sign-off.
+
+## Adding languages
+
+Translations live in `src/locales/en.ts` and `src/locales/fr.ts`. To ship a new
+built-in language:
+
+1. Copy `en.ts` to a new file such as `es.ts` and rename the export to `es`.
+2. Translate every message, the starter questions, and the `whiteLabel` wording.
+   Preserve placeholders such as `{seconds}`. Set `direction` to `ltr` or `rtl`.
+3. Import the pack in `src/locales/index.ts` and add it to `builtInLanguages`.
+4. Run `npm run typecheck`, `npm test`, and `npm run build`.
+
+Each complete pack uses `satisfies AkilioLanguagePack`, so missing translation
+keys are reported by TypeScript when the interface grows.
+
+You can also add languages without rebuilding the widget using the `translations`
+option. Partial packs are supported; untranslated text falls back to English:
+
+```tsx
+import type { AkilioTranslations } from '@hachther/akilio-widget';
+
+const translations = {
+  es: {
+    direction: 'ltr',
+    messages: {
+      title: 'Asistente',
+      launcher: 'Hacer una pregunta',
+      submit: 'Enviar',
+      placeholder: 'Escribe tu pregunta...',
+      suggestions: ['¿Cómo puedo contactar con el equipo?'],
+    },
+    whiteLabel: {
+      title: 'Asistente',
+      launcher: 'Hacer una pregunta',
+      configFailed: 'No se puede cargar la configuración.',
+    },
+  },
+} satisfies AkilioTranslations;
+
+<AkilioWidget
+  projectKey='your-project-key'
+  locale='es-MX'
+  translations={translations}
+/>;
+```
+
+The same dictionary works with `window.Akilio.mount({ projectKey: 'your-project-key',
+locale: 'es-MX', translations })`. For script integrations, use programmatic mounting
+with auto-init disabled when supplying dictionaries.
+
+Locale matching ignores case and accepts underscores. The fallback order is the
+most specific locale, then its parent language/script, then English. For example,
+`zh-Hant-TW` inherits from `zh-Hant`, `zh`, and `en`. Custom dictionaries override
+built-ins at the same locale. Existing project title, placeholder, and starter
+questions still take precedence; the `copy` prop remains the final text override.
+White-label wording is stored separately from branded defaults. Dictionaries are
+scoped to each widget, so one integration cannot change another's translations.
+
+Changing `locale` or `translations` props updates React UI copy. The requested
+locale is still sent to the backend; adding UI translations does not configure
+backend response languages. This framework uses plain text messages and existing
+named placeholders, not ICU plural rules.
+
+## Business branding (AKI-WIDGET-002)
+
+```tsx
+<AkilioWidget
+  projectKey='your-project-key'
+  agentName='Alex'
+  welcomeMessage='Welcome to Acme. How can I help?'
+  starterPrompts={['Explore our services', 'Contact the team']}
+  launcherPosition='bottom-left'
+  theme={{
+    logo_url: 'https://example.com/logo.png',
+    brand_name: 'Acme',
+    primary_color: '#123456',
+    primary_dark_color: '#102030',
+    primary_foreground_color: '#ffffff',
+  }}
+/>
+```
+
+Business logos appear in the launcher, discovery tip, header, empty state,
+assistant answers, and human-help confirmation cards. HTTP(S) and relative image
+URLs are accepted. Failed or invalid images fall back to the Akilio mark when
+branding is enabled, or a neutral icon when branding is hidden. Required
+“Powered by Akilio” attribution remains visible with a business logo.
+
+Name priority: `copy.title`, `agentName`, host `theme.brand_name`, server
+`theme_config.brand_name`, server `title`, then language defaults. Welcome text
+uses `copy.emptyState`, `welcomeMessage`, server `welcome_message`, then language
+defaults. The welcome message appears before the first conversation message.
+
+Before configuration arrives, starter prompts use `starterPrompts` and then
+language suggestions. Once available, `starter_questions` from the public
+configuration endpoint is authoritative, including an explicit empty array that
+hides prompts. Up to four are shown; server-advertised capability actions remain
+independent of starter prompts.
+
+Standalone embeds accept the same options via `Akilio.mount()` or these attributes:
+
+```html
+<script
+  src="https://your-cdn.example/widget/loader.js"
+  data-akilio-widget
+  data-project-key="your-project-key"
+  data-agent-name="Alex"
+  data-brand-name="Acme"
+  data-logo-url="https://example.com/logo.png"
+  data-welcome-message="Welcome to Acme. How can I help?"
+  data-starter-prompts='["Explore our services", "Contact the team"]'
+  data-theme='{"primary_color":"#123456"}'
+  data-launcher-position="bottom-left"
+></script>
+```
+
+Use `data-starter-prompts='[]'` to hide prompts. Dedicated logo/name attributes
+override corresponding values in `data-theme`. Malformed prompt JSON falls back
+to configuration defaults. Custom React launchers and external HTML buttons using
+`launcher: 'hidden'` with `open()`, `close()`, or `toggle()` remain supported.
+### Direct product-card cart actions
+
+Product cards and product details expose Add to cart automatically when backend
+capability discovery includes executable `commerce.add_to_cart`. Available
+variants receive direct actions independent of the LLM response. Clicking the
+button supplies consent; backend capability confirmation is still executed.
+Shopify products on their own storefront use the Shopify adapter. The selected variant is added through
+the Shopify Ajax Cart API, sharing the website's browser cart, without a chat or
+LLM round trip. Cards retain their variant selector, display update feedback,
+and link to the storefront cart after success. Themes can listen for the
+`akilio:cart-updated` window event to refresh their cart counter or drawer.
+
+The backend product payload supplies `cart_provider: "shopify"` to select the
+native adapter when applicable. Other products execute the advertised backend
+cart capability. Actions are hidden for unavailable products and blocked
+business-rule decisions. A backend-managed cart does not necessarily share the
+website browser cart; direct website-cart adapters beyond Shopify are not implemented.
+
+### Voice messages
+
+The composer now supports recording, playback preview, send, and cancel on browsers
+with MediaRecorder and microphone permission. HTTPS (or supported localhost access)
+is required. Recording is capped at five minutes and 10 MiB. EN/FR copy can be
+overridden through the existing translation/copy configuration.
+
+Sending uploads to the authenticated public chat voice endpoint, polls private
+transcription status, then submits the transcript through normal chat. The backend
+must include the shared voice migrations and a transcription worker (or the existing
+explicit development synchronous-processing mode). Voice input produces text replies;
+this does not enable synthesized voice responses.
+
+Voice uploads and polling use the existing widget bearer-token/origin mechanism.
+Microphone capture stops when the panel closes or consent becomes unavailable.
+Update your distributed bundle to make these controls available in deployed widgets.
+
+### Email verification
+
+Once a conversation exists, the widget offers **Verify your email** above the composer. The inline form requests an email code, displays the server's masked email, confirms the code, and restores the verified badge from the conversation's server session. It supports resend cooldowns, expiry, cancellation, retry limits, unavailable providers, and English/French copy overrides (`identity*` keys).
+
+Verification uses the dedicated `/customer-identity/verifications/`, `/{id}/confirm/`, `/{id}/resend/`, and `/customer-identity/session/` routes under `apiBaseUrl`, with the existing widget authentication. Codes are submitted directly as strings and cleared from the input; they are never chat messages or widget analytics events. Challenge IDs and pending questions are held only in memory. The server determines verification and authorization.
+
+A chat response (including a streaming final response) may include `identity_verification_required: { methods: ['email'], purpose: 'identity' }` (`step_up` is also supported). This opens the form. On successful confirmation and an authoritative session lookup, the widget submits the paused question once in the same conversation without duplicating the user's chat bubble. Cancel or a new question discards that continuation. This is a new optional response contract; the backend must emit it when protected actions require verification. It does not itself enforce access to protected actions.
+
+The actual verification provider remains a backend integration. Until that provider is configured, delivery returns an unavailable message. No eSauti calls or credentials are implemented in the widget.
+
+### Multiple widget installations
+
+Create installations in Portal → Widget. Each has its own public key, assigned Agent, appearance and allowed domains. Use `widgetKey` with the React component or `data-widget-key` on the script tag. The existing `projectKey` / `data-project-key` spelling remains supported. Keys identify installations; the workspace remains the tenant boundary. New conversations use the assigned Agent, while existing conversations retain their original Agent.
+
+Managed installations: omit host text/theme and presentation props to follow published Agent text and widget appearance. Public configuration supplies layout, launcher, tour, sound and contextual-prompt options; explicit host props still take precedence. Existing embeds with inline overrides must remove those overrides or replace their snippet once to follow portal publications.

package/dist/_headers

@@ -0,0 +1,16 @@
+# Cloudflare Pages response headers
+/loader.js
+  Cache-Control: public, max-age=0, must-revalidate
+  Cloudflare-CDN-Cache-Control: no-cache
+
+/widget-manifest.json
+  Cache-Control: public, max-age=0, must-revalidate
+  Cloudflare-CDN-Cache-Control: no-cache
+
+/akilio-widget.min.js
+  Cache-Control: public, max-age=0, must-revalidate
+  Cloudflare-CDN-Cache-Control: no-cache
+
+/releases/*
+  Cache-Control: public, max-age=31536000, immutable
+  Cloudflare-CDN-Cache-Control: public, max-age=31536000, immutable