@vizochok/widget

Published on npm as @vizochok/[email protected].

Embeddable AI shopping assistant chat widget for grocery retail.

Installation

npm install @vizochok/widget

Quick Start

Via npm (ESM)

import { VizochokWidget } from '@vizochok/widget';

const widget = new VizochokWidget({
  apiKey: 'pk_your_public_key',
  storeId: 'your-store-id',
  botName: 'Помічник',
  welcomeMessage: 'Привіт! Чим можу допомогти?',
  theme: {
    primaryColor: '#8B5CF6',
    borderRadius: '12px',
  },
});

widget.mount();

Via script tag (UMD)

<script src="https://unpkg.com/@vizochok/widget/dist/vizochok-widget.umd.js"></script>
<script>
  const widget = new VizochokWidget({
    apiKey: 'pk_your_public_key',
    storeId: 'your-store-id',
  });
  widget.mount();
</script>

Configuration

interface VizochokWidgetConfig {
  // Required
  apiKey: string;        // Public API key (pk_xxx)
  storeId: string;       // Store identifier

  // Optional
  userId?: string;       // User ID for personalization
  language?: 'uk' | 'en' | 'ru';  // Default: 'uk'
  apiBase?: string;      // Default: 'https://api.vizochok.com'

  // Appearance
  theme?: {
    primaryColor?: string;   // Default: '#000000'
    fontFamily?: string;     // Default: system fonts
    borderRadius?: string;   // Default: '12px'
    mode?: 'light' | 'dark' | 'auto';  // Default: 'light'
    currency?: string;       // Default: system
  };
  position?: 'bottom-right' | 'bottom-left';
  botName?: string;      // Default: 'Помічник'
  botAvatar?: string;    // Avatar image URL
  placeholder?: string;  // Input placeholder
  welcomeMessage?: string;

  // Callbacks
  onCartChanged?: (cart: CartChangedEvent) => void;
  onProductClick?: (product: ProductItem) => void;
  onSessionComplete?: (summary: SessionSummary) => void;
  onError?: (error: WidgetError) => void;
  onConnect?: () => void;
  onDisconnect?: () => void;
}

API

const widget = new VizochokWidget(config);

widget.mount();                          // Mount to document.body
widget.mount(element);                   // Mount to specific element
widget.mount(element, { inline: true }); // Mount inline (no floating bubble)
widget.open();           // Open chat panel
widget.close();          // Close chat panel
widget.toggle();         // Toggle open/close
widget.unmount();        // Remove from DOM
widget.destroy();        // Unmount + cleanup

UI Components

The widget renders these interactive blocks from the AI assistant:

| Block | Description | |-------|-------------| | text | Formatted text with markdown | | streaming_text | Real-time streaming response with cursor | | product_cards | Horizontal product card carousel | | quick_replies | Suggestion pill buttons | | confirmation | Yes/No product confirmation | | ingredient_checklist | Recipe ingredient selector | | meal_plan | Weekly meal plan cards | | session_summary | Order summary with totals | | status | Typing indicator, connection status | | error | Error message display |

Development

npm install
npm run build       # Build UMD + ESM bundles
npm run dev         # Watch mode
npm run typecheck   # Type checking

Events

The widget dispatches these custom events (bubbling through Shadow DOM):

| Event | Detail | Description | |-------|--------|-------------| | vz:send | { text } | User sends a message | | vz:product-select | { sku, quantity } | User selects a product | | vz:checklist-submit | { recipe_name, selected } | User submits checklist | | vz:cart-changed | { items, total } | Cart was updated | | vz:close | — | User closed the chat panel | | vz:new-chat | — | User started a new conversation |

Architecture

• Shadow DOM for complete style isolation
• CSS-in-JS via template literals (no external CSS files)
• Zero dependencies — pure TypeScript, no frameworks
• WebSocket with auth-via-first-message, exponential backoff reconnect, heartbeat
• Bundle size: ~50KB raw, ~11KB gzipped
• Mobile responsive: full-screen on small screens, floating bubble on desktop

License

MIT