@akropolys/kiku 1.7.16 → 1.7.20

package/README.md

@@ -1,16 +1,22 @@
 # @akropolys/kiku
 
-[![npm](https://img.shields.io/npm/v/@akropolys/kiku?color=orange)](https://www.npmjs.com/package/@akropolys/kiku) [![License](https://img.shields.io/npm/l/@akropolys/kiku)](https://github.com/akropolys/sdk/blob/main/LICENSE) [![TypeScript](https://img.shields.io/badge/types-included-blue)](https://www.typescriptlang.org/)
+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.
 
-**[Docs](https://akropolys.io/docs)**  •  **[GitHub](https://github.com/akropolys/sdk)**
+[![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/)
 
 ---
 
-## The pre-built UI for a smarter search bar.
+## Install
 
-`@akropolys/kiku` is the ready-made front end for [`@akropolys/sdk`](https://www.npmjs.com/package/@akropolys/sdk) — a chat button, a search bar, a per-product "ask about this" prompt — so you don't have to design a search experience from scratch. Drop one in and it's already wired up to plain-language search.
+```bash
+npm install @akropolys/kiku @akropolys/sdk
+# or
+pnpm add @akropolys/kiku @akropolys/sdk
+```
 
-Want to build your own UI instead? Use `@akropolys/sdk` directly and skip this package.
+---
+
+## Usage (React / Next.js)
 
 ```tsx
 import { AkropolysProvider } from '@akropolys/sdk';
@@ -20,41 +26,39 @@ import '@akropolys/kiku/styles.css';
 export default function App() {
   return (
     <AkropolysProvider
-      siteId={process.env.NEXT_PUBLIC_AKROPOLYS_SITE_ID}
-      apiToken={process.env.NEXT_PUBLIC_AKROPOLYS_API_TOKEN}
+      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 />
+      <KikuButton
+        label="Ask me anything"
+        enableVoice={true}
+        enableVision={true}
+        theme={{
+          borderRadius: "24px",
+        }}
+      />
     </AkropolysProvider>
   );
 }
 ```
 
-## Components
-
-| Component | What it does |
-|---|---|
-| `<KikuButton />` | Floating chat assistant |
-| `<KikuChat />` | Chat widget embedded inline on the page |
-| `<SearchBar />` | Search box with a live results dropdown |
-| `<Sparkle />` | Small "ask about this" button next to a product |
-| `<ComparisonMatrix />` | Side-by-side product comparison |
-| `<VoiceButton />` | Speak a query instead of typing it |
-| `<VisualSearch />` | Search by uploading a photo |
+> **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)).
 
-## Install
+---
 
-```bash
-npm install @akropolys/kiku @akropolys/sdk
-```
+## Components
 
-```ts
-import '@akropolys/kiku/styles.css';
-```
+| Component | Description |
+|---|---|
+| `<KikuButton />` | Floating trigger button and full-screen modal with multi-modal voice & vision. |
+| `<KikuChat />` | Embedded inline conversational chat container. |
+| `<VoiceOverlay />` | Duplex live spoken voice assistant with Apple Siri chromatic animation and real-time audio visualization. |
+| `<LiveTable />` | High-precision comparative financial and sports odds table. |
 
-[Read the full docs →](https://akropolys.io/docs)
 
 ---
 
 ## License
 
-MIT © Akropolys
+MIT © [Akropolys](https://akropolys.cloud)

package/dist/index.d.mts

@@ -4,7 +4,6 @@ import { SearchResult, AkropolysTheme, ChatSource, Product, VisualSearchResponse
 interface SearchBarProps {
     placeholder?: string;
     limit?: number;
-    /** Debounce in ms — default 150 for instant type-ahead */
     debounceMs?: number;
     onSelect?: (result: SearchResult) => void;
     className?: string;
@@ -36,17 +35,22 @@ interface ChatWidgetProps {
         input?: string;
     };
     onSelectSource?: (source: ChatSource) => void;
-    /** Enable 🎙️ voice input via browser Web Speech API (free) */
     enableVoice?: boolean;
-    /** Enable 📷 visual style-match search via Gemini (requires backend GEMINI_API_KEY) */
+    /** Enable 📷 visual style-match search */
     enableVision?: boolean;
-    /** Optional category hint for visual search (e.g. 'dress', 'curtains') */
     visionCategoryHint?: string;
+    /** Enable 🔊 TTS voice audio responses from AI */
+    enableAudioResponse?: boolean;
+    /** Optional AI voice preset */
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
 }
-declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource, enableVoice, enableVision, visionCategoryHint }: ChatWidgetProps): React.JSX.Element;
+declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource, enableVoice, enableVision, visionCategoryHint, enableAudioResponse, ttsVoice, autoSpeakResponses }: ChatWidgetProps): React.JSX.Element;
 
 interface KikuButtonProps {
-    label?: string;
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+    icon?: React.ReactNode;
     title?: string;
     placeholder?: string;
     backdropColor?: string;
@@ -63,29 +67,24 @@ interface KikuButtonProps {
         input?: string;
         sendButton?: string;
     };
-    /** Enable 🎙️ voice input via browser Web Speech API (free) */
     enableVoice?: boolean;
-    /** BCP-47 tag for voice transcription (e.g. 'sw-KE', 'fr-FR'). Defaults to
-        the page's <html lang>, then the browser language. */
     voiceLang?: string;
-    /** Enable 📷 visual style-match search via Gemini (requires backend GEMINI_API_KEY) */
     enableVision?: boolean;
-    /** Optional category hint for visual search (e.g. 'dress', 'curtains') */
     visionCategoryHint?: string;
+    /** Enable 🔊 TTS voice audio responses from AI */
+    enableAudioResponse?: boolean;
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
 }
-declare function KikuButton({ label, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, enableVoice, voiceLang, enableVision, visionCategoryHint, }: KikuButtonProps): React.JSX.Element;
+declare function KikuButton({ label, children, icon, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, enableVoice, voiceLang, enableVision, visionCategoryHint, enableAudioResponse, ttsVoice, autoSpeakResponses, }: KikuButtonProps): React.JSX.Element;
 
 interface SparkleProps {
     productName: string;
     limit?: number;
     onResult?: (results: SearchResult[]) => void;
-    /** Override the backdrop colour (any CSS colour/gradient) */
     backdropColor?: string;
-    /** Override backdrop blur — e.g. "8px" or 8 */
     backdropBlur?: string | number;
-    /** Extra classes on the trigger button */
     className?: string;
-    /** Called when user clicks a result — return false to prevent default navigation */
     onNavigate?: (result: SearchResult) => boolean | void;
     theme?: AkropolysTheme;
     classNames?: {
@@ -99,29 +98,20 @@ interface SparkleProps {
 }
 declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, children, }: SparkleProps): React.JSX.Element;
 
-interface ComparisonMatrixProps {
-    sources: ChatSource[];
-    defaultCurrency?: string;
-    displayConfig?: Record<string, string>;
-}
-declare function ComparisonMatrix({ sources, defaultCurrency, displayConfig }: ComparisonMatrixProps): React.JSX.Element | null;
-
 interface VoiceButtonProps {
     onTranscript: (text: string) => void;
     onInterim?: (text: string) => void;
-    /** BCP-47 language tag. Defaults to 'en-US'. */
+    /** BCP-47 tag. Defaults to the page's <html lang>, then the browser language. */
     lang?: string;
     className?: string;
     disabled?: boolean;
+    /** Raw SpeechRecognition error code — 'not-allowed', 'audio-capture', etc. */
+    onError?: (code: string) => void;
 }
 /**
- * VoiceButton — converts speech to text using the browser's free Web Speech API.
- * No API key, no backend call, no cost.
- *
- * @example
- * <VoiceButton onTranscript={(text) => setQuery(text)} />
+ * VoiceButton — speech to text input with pause-based utterance detection.
  */
-declare function VoiceButton({ onTranscript, onInterim, lang, className, disabled, }: VoiceButtonProps): React.JSX.Element | null;
+declare function VoiceButton({ onTranscript, onInterim, lang, className, disabled, onError, }: VoiceButtonProps): React.JSX.Element | null;
 
 interface VisualSearchProps {
     /** Called with search results + the base64 preview when Gemini responds. */
@@ -136,17 +126,97 @@ interface VisualSearchProps {
     disabled?: boolean;
 }
 /**
- * VisualSearch — camera/image-upload button that powers style-match search.
- *
- * User picks a photo → it's base64-encoded in-browser → sent to POST /search/visual
- * → Gemini Flash extracts Style DNA → results returned via onResults().
- *
- * @example
- * <VisualSearch
- *   categoryHint="dress"
- *   onResults={(res, preview) => setVisualResults(res)}
- * />
+ * VisualSearch — camera/image-upload button for style-match search.
  */
 declare function VisualSearch({ onResults, onError, categoryHint, className, disabled, }: VisualSearchProps): React.JSX.Element;
 
-export { ChatWidget, type ChatWidgetProps, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };
+interface ShopifyProduct {
+    id?: number | string;
+    title?: string;
+    name?: string;
+    handle?: string;
+    url?: string;
+    price?: number | string;
+    compare_at_price?: number | string;
+    price_min?: number | string;
+    featured_image?: string;
+    images?: string[] | {
+        src: string;
+    }[];
+    image?: string;
+    type?: string;
+    product_type?: string;
+    category?: string;
+    vendor?: string;
+    brand?: string;
+    tags?: string[] | string;
+    description?: string;
+    body_html?: string;
+    variants?: Array<{
+        id: number | string;
+        title?: string;
+        price?: number | string;
+        sku?: string;
+        available?: boolean;
+    }>;
+    available?: boolean;
+    [key: string]: any;
+}
+interface StandaloneConfig {
+    siteId?: string;
+    apiToken?: string;
+    apiUrl?: string;
+    vertical?: string;
+    shopperId?: string;
+    theme?: 'dark' | 'light' | any;
+    buttonLabel?: string;
+    title?: string;
+    placeholder?: string;
+    defaultCurrency?: string;
+    chips?: string[];
+    enableVoice?: boolean;
+    voiceLang?: string;
+    enableVision?: boolean;
+    visionCategoryHint?: string;
+    enableAudioResponse?: boolean;
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline' | 'hidden' | 'custom';
+    containerId?: string;
+    containerSelector?: string;
+    dockable?: boolean;
+    product?: ShopifyProduct;
+    onAddToCart?: (items: ChatSource[]) => void;
+    onAction?: (action: any) => void;
+    [key: string]: any;
+}
+declare global {
+    interface Window {
+        AkropolysConfig?: StandaloneConfig;
+        Kiku?: {
+            version: string;
+            open: () => void;
+            close: () => void;
+            toggle: () => void;
+            ingest: (product: ShopifyProduct) => Promise<void>;
+            resetPosition: () => void;
+            getClient: () => any;
+            config: StandaloneConfig;
+        };
+    }
+}
+/**
+ * Normalizes a Shopify product object into Akropolys entity format.
+ */
+declare function normalizeShopifyProduct(p: ShopifyProduct): Record<string, any>;
+/**
+ * Native Shopify Cart Integration.
+ */
+declare function shopifyAddToCart(items: ChatSource[]): Promise<any>;
+/**
+ * Native Shopify Get Cart.
+ */
+declare function shopifyGetCart(): Promise<any>;
+declare function initKiku(customConfig?: StandaloneConfig): void;
+
+export { ChatWidget, type ChatWidgetProps, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, type ShopifyProduct, Sparkle, type StandaloneConfig, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps, initKiku, normalizeShopifyProduct, shopifyAddToCart, shopifyGetCart };

package/dist/index.d.ts

@@ -4,7 +4,6 @@ import { SearchResult, AkropolysTheme, ChatSource, Product, VisualSearchResponse
 interface SearchBarProps {
     placeholder?: string;
     limit?: number;
-    /** Debounce in ms — default 150 for instant type-ahead */
     debounceMs?: number;
     onSelect?: (result: SearchResult) => void;
     className?: string;
@@ -36,17 +35,22 @@ interface ChatWidgetProps {
         input?: string;
     };
     onSelectSource?: (source: ChatSource) => void;
-    /** Enable 🎙️ voice input via browser Web Speech API (free) */
     enableVoice?: boolean;
-    /** Enable 📷 visual style-match search via Gemini (requires backend GEMINI_API_KEY) */
+    /** Enable 📷 visual style-match search */
     enableVision?: boolean;
-    /** Optional category hint for visual search (e.g. 'dress', 'curtains') */
     visionCategoryHint?: string;
+    /** Enable 🔊 TTS voice audio responses from AI */
+    enableAudioResponse?: boolean;
+    /** Optional AI voice preset */
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
 }
-declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource, enableVoice, enableVision, visionCategoryHint }: ChatWidgetProps): React.JSX.Element;
+declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource, enableVoice, enableVision, visionCategoryHint, enableAudioResponse, ttsVoice, autoSpeakResponses }: ChatWidgetProps): React.JSX.Element;
 
 interface KikuButtonProps {
-    label?: string;
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+    icon?: React.ReactNode;
     title?: string;
     placeholder?: string;
     backdropColor?: string;
@@ -63,29 +67,24 @@ interface KikuButtonProps {
         input?: string;
         sendButton?: string;
     };
-    /** Enable 🎙️ voice input via browser Web Speech API (free) */
     enableVoice?: boolean;
-    /** BCP-47 tag for voice transcription (e.g. 'sw-KE', 'fr-FR'). Defaults to
-        the page's <html lang>, then the browser language. */
     voiceLang?: string;
-    /** Enable 📷 visual style-match search via Gemini (requires backend GEMINI_API_KEY) */
     enableVision?: boolean;
-    /** Optional category hint for visual search (e.g. 'dress', 'curtains') */
     visionCategoryHint?: string;
+    /** Enable 🔊 TTS voice audio responses from AI */
+    enableAudioResponse?: boolean;
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
 }
-declare function KikuButton({ label, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, enableVoice, voiceLang, enableVision, visionCategoryHint, }: KikuButtonProps): React.JSX.Element;
+declare function KikuButton({ label, children, icon, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, enableVoice, voiceLang, enableVision, visionCategoryHint, enableAudioResponse, ttsVoice, autoSpeakResponses, }: KikuButtonProps): React.JSX.Element;
 
 interface SparkleProps {
     productName: string;
     limit?: number;
     onResult?: (results: SearchResult[]) => void;
-    /** Override the backdrop colour (any CSS colour/gradient) */
     backdropColor?: string;
-    /** Override backdrop blur — e.g. "8px" or 8 */
     backdropBlur?: string | number;
-    /** Extra classes on the trigger button */
     className?: string;
-    /** Called when user clicks a result — return false to prevent default navigation */
     onNavigate?: (result: SearchResult) => boolean | void;
     theme?: AkropolysTheme;
     classNames?: {
@@ -99,29 +98,20 @@ interface SparkleProps {
 }
 declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, children, }: SparkleProps): React.JSX.Element;
 
-interface ComparisonMatrixProps {
-    sources: ChatSource[];
-    defaultCurrency?: string;
-    displayConfig?: Record<string, string>;
-}
-declare function ComparisonMatrix({ sources, defaultCurrency, displayConfig }: ComparisonMatrixProps): React.JSX.Element | null;
-
 interface VoiceButtonProps {
     onTranscript: (text: string) => void;
     onInterim?: (text: string) => void;
-    /** BCP-47 language tag. Defaults to 'en-US'. */
+    /** BCP-47 tag. Defaults to the page's <html lang>, then the browser language. */
     lang?: string;
     className?: string;
     disabled?: boolean;
+    /** Raw SpeechRecognition error code — 'not-allowed', 'audio-capture', etc. */
+    onError?: (code: string) => void;
 }
 /**
- * VoiceButton — converts speech to text using the browser's free Web Speech API.
- * No API key, no backend call, no cost.
- *
- * @example
- * <VoiceButton onTranscript={(text) => setQuery(text)} />
+ * VoiceButton — speech to text input with pause-based utterance detection.
  */
-declare function VoiceButton({ onTranscript, onInterim, lang, className, disabled, }: VoiceButtonProps): React.JSX.Element | null;
+declare function VoiceButton({ onTranscript, onInterim, lang, className, disabled, onError, }: VoiceButtonProps): React.JSX.Element | null;
 
 interface VisualSearchProps {
     /** Called with search results + the base64 preview when Gemini responds. */
@@ -136,17 +126,97 @@ interface VisualSearchProps {
     disabled?: boolean;
 }
 /**
- * VisualSearch — camera/image-upload button that powers style-match search.
- *
- * User picks a photo → it's base64-encoded in-browser → sent to POST /search/visual
- * → Gemini Flash extracts Style DNA → results returned via onResults().
- *
- * @example
- * <VisualSearch
- *   categoryHint="dress"
- *   onResults={(res, preview) => setVisualResults(res)}
- * />
+ * VisualSearch — camera/image-upload button for style-match search.
  */
 declare function VisualSearch({ onResults, onError, categoryHint, className, disabled, }: VisualSearchProps): React.JSX.Element;
 
-export { ChatWidget, type ChatWidgetProps, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };
+interface ShopifyProduct {
+    id?: number | string;
+    title?: string;
+    name?: string;
+    handle?: string;
+    url?: string;
+    price?: number | string;
+    compare_at_price?: number | string;
+    price_min?: number | string;
+    featured_image?: string;
+    images?: string[] | {
+        src: string;
+    }[];
+    image?: string;
+    type?: string;
+    product_type?: string;
+    category?: string;
+    vendor?: string;
+    brand?: string;
+    tags?: string[] | string;
+    description?: string;
+    body_html?: string;
+    variants?: Array<{
+        id: number | string;
+        title?: string;
+        price?: number | string;
+        sku?: string;
+        available?: boolean;
+    }>;
+    available?: boolean;
+    [key: string]: any;
+}
+interface StandaloneConfig {
+    siteId?: string;
+    apiToken?: string;
+    apiUrl?: string;
+    vertical?: string;
+    shopperId?: string;
+    theme?: 'dark' | 'light' | any;
+    buttonLabel?: string;
+    title?: string;
+    placeholder?: string;
+    defaultCurrency?: string;
+    chips?: string[];
+    enableVoice?: boolean;
+    voiceLang?: string;
+    enableVision?: boolean;
+    visionCategoryHint?: string;
+    enableAudioResponse?: boolean;
+    ttsVoice?: string;
+    autoSpeakResponses?: boolean;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline' | 'hidden' | 'custom';
+    containerId?: string;
+    containerSelector?: string;
+    dockable?: boolean;
+    product?: ShopifyProduct;
+    onAddToCart?: (items: ChatSource[]) => void;
+    onAction?: (action: any) => void;
+    [key: string]: any;
+}
+declare global {
+    interface Window {
+        AkropolysConfig?: StandaloneConfig;
+        Kiku?: {
+            version: string;
+            open: () => void;
+            close: () => void;
+            toggle: () => void;
+            ingest: (product: ShopifyProduct) => Promise<void>;
+            resetPosition: () => void;
+            getClient: () => any;
+            config: StandaloneConfig;
+        };
+    }
+}
+/**
+ * Normalizes a Shopify product object into Akropolys entity format.
+ */
+declare function normalizeShopifyProduct(p: ShopifyProduct): Record<string, any>;
+/**
+ * Native Shopify Cart Integration.
+ */
+declare function shopifyAddToCart(items: ChatSource[]): Promise<any>;
+/**
+ * Native Shopify Get Cart.
+ */
+declare function shopifyGetCart(): Promise<any>;
+declare function initKiku(customConfig?: StandaloneConfig): void;
+
+export { ChatWidget, type ChatWidgetProps, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, type ShopifyProduct, Sparkle, type StandaloneConfig, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps, initKiku, normalizeShopifyProduct, shopifyAddToCart, shopifyGetCart };