npm.io
1.0.0 • Published 4h ago

vox-cart

Licence
MIT
Version
1.0.0
Deps
0
Size
137 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

vox-cart

The open source voice commerce widget. Browser-native speech recognition, on-device AI voice responses, works on any storefront.

No cloud ASR. No backend required for basic use. Drop in two script tags.

What it does

  • Voice search — customer taps a mic button and speaks naturally ("I want honey", "something for Diwali", "ingredients for biryani")
  • Smart search pipeline — exact match → category graph → Fuse.js fuzzy → phonetic → context-aware fallback
  • On-device TTS — responses spoken back using Supertonic TTS (ONNX, runs via WebGPU or WASM — no cloud), falls back to window.speechSynthesis
  • Cart integration — built-in adapters for Shopify, WooCommerce, Odoo, or any custom cart
  • Works on any storefront — Shopify, WooCommerce, Odoo, React, plain HTML

Quick start

Paste before </body> on any page:

<script>
  window.VA_CONFIG = {
    productsUrl: 'https://your-server.com/customer/va_xxx.../products',
    cartMode:    'shopify',  // 'shopify' | 'woo' | 'odoo' | 'custom'
  };
</script>
<script src="https://cdn.vox-cart.com/va-search.js" defer></script>
<script src="https://cdn.vox-cart.com/voice-agent.js" defer></script>

The mic button appears bottom-right. That's it.

Search

Search runs client-side via Fuse.js by default — no backend needed. Set useTypesense: false (or omit it) to keep everything local.

To enable server-side Typesense search, set useTypesense: true. The widget will automatically derive the search endpoint from productsUrl (replaces /products with /search) and proxy requests through voice-agent-server:

window.VA_CONFIG = {
  productsUrl:  'https://your-server.com/customer/va_xxx.../products',
  useTypesense: true,
  cartMode:     'shopify',
};
Managed backend (voice-agent-server)

voice-agent-server handles product ingestion, Typesense collection management, and search proxying. It supports Excel, Shopify, and WooCommerce catalogues.

  • Admin UI: http://your-server:8002/ui
  • Ingest via Excel upload, Shopify API sync, or WooCommerce API sync
  • One licence key per customer — passed in the productsUrl path

Product data format

productsUrl must return a JSON array. Each product:

{
  "variant_id":      "123",
  "title":           "Organic Toor Dal 1kg",
  "price":           "₹120",
  "image_url":       "https://...",
  "tag2":            "Pulses & Lentils",
  "tag3":            ["Toor Dal", "Arhar Dal"],
  "tag6":            "Organic",
  "tag7":            "Vegan",
  "tag8":            "Dal / Curry Cooking",
  "tag9":            "1.0 KG",
  "search_keywords": ["arhar", "yellow lentil"],
  "search_tags":     ["dal", "protein"]
}

Important: tag3 must be an array of clean separate strings — not a single pipe-joined string. voice-agent-server's Excel loader splits on |, ,, and ; automatically.

Field Required Description
variant_id Yes Unique identifier
title Yes Product name
price No Display price (e.g. ₹120, $5.99)
image_url No Full URL to product image
tag2 No Category
tag3 No Subcategory array (clean separate strings)
tag6–tag9 No Variety, dietary flag, pack size, weight
search_keywords No Extra search terms (defaults to tag3 if omitted)
search_tags No Extra keywords for Typesense indexing

Cart modes

cartMode What it calls
odoo /shop/cart/update_json (Odoo JSON-RPC)
shopify /cart/add.js
woo /?wc-ajax=add_to_cart
custom VA_CONFIG.cartHandler(items) — your own function 
// Custom cart example
window.VA_CONFIG = {
  cartMode:    'custom',
  cartHandler: async function(items) {
    await fetch('/api/cart', {
      method: 'POST',
      body:   JSON.stringify({ items }),
    });
  },
};

VA_CONFIG reference

Field Default Description
productsUrl /voice-agent/products Product list JSON endpoint
useTypesense false Set true to enable server-side Typesense search via proxy
logUrl /voice-agent/log Client error beacon (optional)
cartMode 'odoo' Cart adapter to use
cartUrl platform default Override default cart endpoint
cartHandler — async (items) => void — required when cartMode='custom'

TTS models

The on-device TTS uses Supertonic ONNX models (~250MB). Not included in this repo due to size. Download from HuggingFace (onnx-community/Supertonic-TTS-ONNX) and serve from your own CDN or server at /voice-agent/models/onnx-community/Supertonic-TTS-ONNX/.

Falls back to window.speechSynthesis (browser built-in) if models are unavailable — the widget still works fully without them.

Browser support

Requires SpeechRecognition API — supported in Chrome, Edge, and Safari 14.1+. Firefox not supported (no SpeechRecognition implementation).

WebGPU TTS requires Chrome 113+ or Edge 113+. Falls back to WASM on older browsers, falls back to speechSynthesis if WASM fails.

License

MIT

Keywords

voiceshoppingcartwidget