vocalia-widget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 VocalIA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# vocalia-widget
+
+AI-powered voice assistant widget for websites. 40 industry personas, 5 languages (FR/EN/ES/AR/Darija), BANT lead qualification, RTL support.
+
+## Installation
+
+```bash
+npm install vocalia-widget
+```
+
+## Usage
+
+### General purpose
+
+```js
+import { initVocalia } from 'vocalia-widget';
+
+initVocalia({
+  tenantId: 'your_tenant_id',
+  apiKey: 'voc_xxxxxxxxxxxx',
+  position: 'bottom-right',
+  primaryColor: '#5E6AD2',
+  language: 'auto',
+  persona: 'AGENCY'
+});
+```
+
+### B2B (lead qualification)
+
+```js
+import { initVocaliaB2B } from 'vocalia-widget';
+
+initVocaliaB2B({
+  tenantId: 'your_tenant_id',
+  persona: 'SAAS'
+});
+```
+
+### E-commerce (product catalog)
+
+```js
+import { initVocaliaEcommerce } from 'vocalia-widget';
+
+initVocaliaEcommerce({
+  tenantId: 'your_tenant_id',
+  persona: 'ECOMMERCE'
+});
+```
+
+## CDN Alternative
+
+```html
+<script>
+  window.VOCALIA_CONFIG = {
+    tenantId: 'your_tenant_id',
+    position: 'bottom-right',
+    primaryColor: '#5E6AD2'
+  };
+</script>
+<script src="https://cdn.jsdelivr.net/npm/vocalia-widget/src/voice-widget.js" defer></script>
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `tenantId` | string | *required* | Your VocalIA tenant identifier. |
+| `apiKey` | string | — | API key for authenticated operations (BANT/CRM). |
+| `position` | string | `'bottom-right'` | Widget position: `bottom-right`, `bottom-left`, `top-right`, `top-left`. |
+| `primaryColor` | hex | `'#5E6AD2'` | Button and accent color. |
+| `buttonSize` | number | `60` | Button diameter in pixels. |
+| `language` | string | `'auto'` | Force language: `fr`, `en`, `es`, `ar`, `ary`. |
+| `persona` | string | `'AGENCY'` | Initial AI personality (see Personas list). |
+| `ecommerceMode` | boolean | `true` | Enable catalog search & cart intent detection. |
+| `autoStart` | boolean | `false` | Start voice synthesis immediately on open. |
+| `debug` | boolean | `false` | Enable console logging for voice events. |
+
+## Programmatic Control
+
+The widget can be controlled programmatically via the `window.VocalIA` object:
+
+```js
+// Open the widget
+VocalIA.open();
+
+// Close the widget
+VocalIA.close();
+
+// Toggle state
+VocalIA.toggle();
+
+// Switch persona on the fly
+VocalIA.setPersona('RESTAURANT');
+
+// Send data to the AI (e.g., current product context)
+VocalIA.sendContext({
+  productId: '123',
+  price: '99.99',
+  currency: 'EUR'
+});
+```
+
+## Event Hooks
+
+Listen to widget lifecycle events to trigger custom site logic:
+
+```js
+window.addEventListener('vocalia:ready', (e) => {
+  console.log('VocalIA is loaded and ready.');
+});
+
+window.addEventListener('vocalia:message', (e) => {
+  const { role, text } = e.detail;
+  console.log(`New ${role} message: ${text}`);
+});
+
+window.addEventListener('vocalia:qualify', (e) => {
+  const { score, bant } = e.detail;
+  // Trigger your own CRM conversion pixels here
+  console.log('Lead qualified:', bant);
+});
+
+window.addEventListener('vocalia:error', (e) => {
+  console.error('VocalIA Error:', e.detail.message);
+});
+```
+
+## Advanced Customization (CSS)
+
+The widget uses CSS Variables for style overrides. You can define these in your main stylesheet:
+
+```css
+:root {
+  --vocalia-primary: #FF5733;
+  --vocalia-font: 'Inter', sans-serif;
+  --vocalia-z-index: 9999;
+}
+```
+
+## Data Attributes
+
+Control widget behavior without writing JavaScript using HTML data attributes:
+
+```html
+<!-- Trigger widget open from any button -->
+<button data-vocalia-action="open">Speak with AI</button>
+
+<!-- Switch persona based on page section -->
+<section data-vocalia-persona="DENTAL"> ... </section>
+```
+
+## Personas
+
+VocalIA includes 40 fine-tuned personas, categorized by industry:
+
+* **Real Estate:** `PROPERTY`, `LISTINGS`, `CLIENT_RELATIONS`
+* **Healthcare:** `DENTAL`, `HEALTHCARE`, `WELLNESS`
+* **Professional Services:** `LAWYER`, `INSURANCE`, `FINANCE`, `AGENCY`
+* **Home Services:** `CONTRACTOR`, `PLUMBING`, `ROOFING`
+* **E-commerce & Retail:** `ECOMMERCE`, `RESTAURANT`, `HOTEL`, `TRAVEL`
+* **Tech & Education:** `SAAS`, `EDUCATION`, `CUSTOMER_SUPPORT`
+
+## Languages & Localization
+
+VocalIA is a global-first platform with deep regional intelligence:
+
+* **RTL Support:** Automatically adjusts UI layout for Arabic and Darija.
+* **Auto-Detection:** Uses sophisticated visitor logic:
+  * Geo: Morocco -> French (Primary) / Darija (Secondary)
+  * Geo: MENA -> Arabic
+  * Geo: Europe/Americas -> English / Local
+* **Manual Override:** Set `language: 'ary'` to force Moroccan Darija specifically.
+
+## Requirements
+
+* **HTTPS:** Browsers block microphone access on insecure connections.
+* **Supported Browsers:** Chrome (v33+), Safari (v14.1+), Edge (v79+).
+* **Network:** Access to `api.vocalia.ma` (Port 443).
+
+## Enterprise Support
+
+For white-label solutions, custom personas training, or on-premise deployments, contact [enterprise@vocalia.ma](mailto:enterprise@vocalia.ma).
+
+## License
+
+MIT © [Jouiet/VocalIA](https://github.com/Jouiet/VocalIA)

package/index.d.ts

@@ -0,0 +1,15 @@
+export interface VocaliaConfig {
+  tenantId: string;
+  apiKey?: string;
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  primaryColor?: string;
+  buttonSize?: number;
+  language?: 'auto' | 'fr' | 'en' | 'es' | 'ar' | 'ary';
+  persona?: string;
+  ecommerceMode?: boolean;
+  showOnMobile?: boolean;
+}
+
+export function initVocalia(config: VocaliaConfig): void;
+export function initVocaliaB2B(config: VocaliaConfig): void;
+export function initVocaliaEcommerce(config: VocaliaConfig): void;

package/index.js

@@ -0,0 +1,51 @@
+// VocalIA Widget NPM Entry Point
+// Usage: import { initVocalia, initVocaliaB2B, initVocaliaEcommerce } from 'vocalia-widget';
+
+/**
+ * Initialize VocalIA Widget
+ * @param {object} config - Configuration object
+ */
+export function initVocalia(config) {
+    if (typeof window === 'undefined') return;
+
+    // Map NPM config keys to widget SAFE_CONFIG_KEYS format
+    const safeConfig = {};
+    if (config.ecommerceMode !== undefined) safeConfig.ECOMMERCE_MODE = config.ecommerceMode;
+    if (config.position) safeConfig.widgetPosition = config.position;
+    if (config.language) safeConfig.DEFAULT_LANG = config.language === 'auto' ? undefined : config.language;
+    if (config.exitIntent !== undefined) safeConfig.EXIT_INTENT_ENABLED = config.exitIntent;
+    if (config.socialProof !== undefined) safeConfig.SOCIAL_PROOF_ENABLED = config.socialProof;
+    if (config.aiMode !== undefined) safeConfig.AI_MODE = config.aiMode;
+    if (config.apiTimeout) safeConfig.API_TIMEOUT = config.apiTimeout;
+
+    // Set safe config keys (these pass through widget H8 filter)
+    window.VOCALIA_CONFIG = safeConfig;
+
+    // Load Script dynamically from CDN/API (Unified V3 Kernel)
+    // tenantId is passed via data-vocalia-tenant attribute (widget reads this natively)
+    // primaryColor is applied server-side via /config endpoint based on tenant
+    if (!document.getElementById('vocalia-script')) {
+        const script = document.createElement('script');
+        script.id = 'vocalia-script';
+        script.src = `https://api.vocalia.ma/voice-assistant/voice-widget-v3.js`;
+        script.defer = true;
+        // Pass tenantId via data attribute — widget detectTenantId() reads this (line 3704)
+        if (config.tenantId) script.dataset.vocaliaTenant = config.tenantId;
+        if (config.apiKey) script.dataset.vocaliaApiKey = config.apiKey;
+        document.body.appendChild(script);
+    }
+}
+
+/**
+ * Initialize B2B-specialized Widget
+ */
+export function initVocaliaB2B(config) {
+    initVocalia({ ...config, ecommerceMode: false });
+}
+
+/**
+ * Initialize E-commerce-specialized Widget
+ */
+export function initVocaliaEcommerce(config) {
+    initVocalia({ ...config, ecommerceMode: true });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "vocalia-widget",
+    "version": "1.0.0",
+    "description": "AI-powered voice assistant widget for websites. 40 industry personas, 5 languages (FR/EN/ES/AR/Darija), BANT lead qualification, RTL support. Zero API cost via Web Speech API.",
+    "type": "module",
+    "main": "index.js",
+    "module": "index.js",
+    "types": "index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./index.js",
+            "types": "./index.d.ts"
+        }
+    },
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "voice-ai",
+        "vocalia",
+        "widget",
+        "voice-assistant",
+        "voice-commerce",
+        "chatbot",
+        "lead-qualification",
+        "multilingual",
+        "rtl",
+        "darija",
+        "morocco",
+        "web-speech-api"
+    ],
+    "author": "VocalIA <dev@vocalia.ma>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Jouiet/VocalIA.git",
+        "directory": "distribution/npm/vocalia-widget"
+    },
+    "homepage": "https://vocalia.ma",
+    "bugs": {
+        "url": "https://github.com/Jouiet/VocalIA/issues"
+    },
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "files": [
+        "src",
+        "index.js",
+        "index.d.ts",
+        "README.md",
+        "LICENSE"
+    ]
+}