@touchcastllc/napster-companion-api 1.0.0-alpha.8 → 1.0.0

package/README.md

@@ -15,38 +15,47 @@
 
 **Key Capabilities:**
 
-- 🎯 **Multiple Build Targets**: Support for ES modules and standalone bundles
+- 🎯 **Multiple Build Targets**: Support for ES modules, CommonJS, UMD, and standalone bundles
+- 🔄 **React 16-19 Compatible**: Full support from React 16.0 through React 19.x
+- 🚪 **Dual Entry Points**: Modern (React 18+) and Legacy (React 16+) versions
 - 📦 **Tree-Shakeable**: Only import what you need for optimal bundle sizes
 - ⚡ **Zero External Dependencies** (Standalone): Drop in a script tag and go
-- ✨ **Advanced Features**: Waveform visualization, background removal, inactive timeouts, disclaimers, and SDK loader
-- 🔧 **TypeScript Support**: Fully typed APIs for an enhanced developer experience
-- 🛠️ **Debug Mode**: Comprehensive logging for development and troubleshooting
-- 🚀 **Production Ready**: Minified builds with type definitions
+- ✨ **Advanced Features**: Auto-play, waveform visualization, background removal, inactive timeouts, and more
+- 🔧 **TypeScript Support**: Full type definitions for a great developer experience
+- 🚀 **Production Ready**: Minified builds with source maps for debugging
 
 ---
 
-## 1. Quick Start
+## 2. Quick Start
 
 Get up and running in minutes. Follow these four steps to integrate the SDK into your project.
 
-### 1.1 Choose Your Setup
+### 2.1 Choose Your Setup
 
 Pick the integration method that matches your project:
 
-| Build Type     | Best For                                                                                                                                                                                                                                       | Import Path                           | Dependencies         |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------------- |
-| **ESM**        | ✅ **Recommended for most projects**<br>✅ You use a bundler (Vite, Webpack, Rollup, etc.)<br>✅ You want optimal bundle size (dependencies not bundled)<br>✅ You're using TypeScript or modern JavaScript                                    | `@touchcastllc/napster-companion-api` | Redux Toolkit (peer) |
-| **Standalone** | ✅ You want a `<script>` tag (no bundler, no external dependencies)<br>✅ You want zero external dependencies<br>✅ You don't want to manage dependencies separately<br>✅ You're okay with a slightly larger file (all dependencies included) | `lib/index.standalone.js`             | All bundled          |
+| Build Type                  | Best For                            | Import Path                                  | React Included? |
+| --------------------------- | ----------------------------------- | -------------------------------------------- | --------------- |
+| **React 18+** (Bundler)     | Modern React apps with Vite/Webpack | `@touchcastllc/napster-companion-api`        | No (peer dep)   |
+| **React 16/17** (Legacy)    | React 16/17 apps with bundlers      | `@touchcastllc/napster-companion-api/legacy` | No (peer dep)   |
+| **UMD** (Script Tag)        | Browser, bring your own React 18+   | `lib/index.umd.min.js`                       | No              |
+| **Standalone** (Script Tag) | Browser, zero dependencies          | `lib/index.standalone.min.js`                | Yes             |
+| **Core** (Headless)         | Custom UI, framework-agnostic       | `@touchcastllc/napster-companion-api/core`   | No              |
 
----
+**Quick Links:**
 
-### 1.2 Installation & Setup
+- [React 18+ Example](#react-18-hooks--cleanup)
+- [React 16/17 Example](#react-1617-class-component--cleanup)
+- [Vue 3 Example](#vue-3-beforeunmount)
+- [Vue 2 Example](#vue-2-beforedestroy)
+- [Angular Example](#angular-ngondestroy)
+- [Vanilla JS Example](#vanilla-js--core-no-build-tools)
 
-#### 1.2.1 For ESM Build Type (Recommended)
+### 2.2 Installation & Import
 
-**Step 1: Install the SDK**
+#### For Bundler-Based Projects
 
-Install the package:
+**Install the package:**
 
 ```bash
 npm install @touchcastllc/napster-companion-api
@@ -54,150 +63,117 @@ npm install @touchcastllc/napster-companion-api
 yarn add @touchcastllc/napster-companion-api
 ```
 
-Install peer dependencies:
+**Install peer dependencies:**
 
 ```bash
-npm install @reduxjs/toolkit
+# For React 18+
+npm install react@^18 react-dom@^18 @reduxjs/toolkit@^2 react-redux@^9
+
+# For React 16/17
+npm install react@^16 react-dom@^16 @reduxjs/toolkit@^2 react-redux@^8
 ```
 
-**Step 2: Import the SDK**
+**Import the SDK:**
 
 ```typescript
+// React 18+
 import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
-```
-
-**Also, import CSS Stylesheet (required):**
 
-The SDK comes with a complete stylesheet for all components. Import it in your application:
+// React 16/17
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api/legacy";
+```
 
-**ESM/TypeScript:**
+**Import CSS (required):**
 
 ```typescript
-import "@touchcastllc/napster-companion-api/styles";
+import "@touchcastllc/napster-companion-api/lib/index.css";
 ```
 
-**CommonJS:**
-
-```js
-require("@touchcastllc/napster-companion-api/styles");
-```
+#### For Browser Script Tags
 
-**HTML `<link>` Tag:**
+**Option A: Standalone (Easiest - React Included)**
 
 ```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
-/>
-```
-
-**CSS `@import`:**
-
-```css
-@import url("https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css");
+<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.min.js"></script>
 ```
 
-The CSS file (`index.css`) is minified and contains all styles needed for the avatar widget, controls, tooltips, waveform visualization, and more.
-
-#### 1.2.2 For Standalone Build Type
-
-**Step 1: Import the SDK**
+**Option B: UMD (Smaller - Bring Your Own React)**
 
 ```html
-<!-- All dependencies bundled (easier, larger file) -->
-<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.umd.min.js"></script>
 ```
 
----
-
-### 1.3 Initialization
-
-#### 1.3.1 For ESM Build Type
+### 2.3 Initialization
 
 Initialize the SDK by calling `NapsterCompanionApiSdk.init()` with your auth token and configuration options.
 
-See the [1.4 Authentication](#14-authentication) section for details on generating auth tokens.
-
 **Basic Example:**
 
 ```typescript
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+
 const widget = await NapsterCompanionApiSdk.init("YOUR_AUTH_TOKEN", {
   mountContainer: "#avatar-container",
+  position: "bottom-right",
+  features: {
+    waveform: { enabled: true },
+    backgroundRemoval: { enabled: false },
+    inactiveTimeout: { enabled: true, timeoutDuration: 60000 },
+  },
 });
-```
-
-#### 1.3.2 For Standalone Build Type
 
-Initialize the SDK by calling `window.napsterCompanionApiSDK.init()` with your auth token and configuration options.
-
-See the [1.4 Authentication](#14-authentication) section for details on generating auth tokens.
-
-**Step 1: Add container to your HTML**
-
-```html
-<div id="sdk-container"></div>
+// The returned widget object exposes control methods:
+// widget.showAvatar()      - Show the avatar
+// widget.hideAvatar()      - Hide the avatar
+// widget.destroy()         - Destroy and unmount the widget
+// widget.updateStyles({...}) - Update widget styles dynamically
+// widget.enableFeature("waveform")   - Enable a specific feature
+// widget.disableFeature("waveform")  - Disable a specific feature
+// widget.updateFeatureConfig("waveform", { enabled: false }) - Update feature configuration
+// widget.setPosition("top-left") - Update widget position dynamically
+// widget.sendQuestion("Your question here") - Send a question to the avatar
 ```
 
-**Step 2: Initialize globally**
+**What `init()` Returns:**
 
-```html
-<script>
-  window.napsterCompanionApiSDK.init("AUTH_TOKEN", {
-    mountContainer: "#sdk-container",
-  });
-</script>
-```
+The `init()` method returns a widget instance with the following methods:
+
+| Method                  | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `showAvatar()`          | Shows the avatar                              |
+| `hideAvatar()`          | Hides the avatar                              |
+| `destroy()`             | Destroys and unmounts the widget from the DOM |
+| `updateStyles()`        | Updates widget styles dynamically             |
+| `enableFeature()`       | Enables a specific feature                    |
+| `disableFeature()`      | Disables a specific feature                   |
+| `updateFeatureConfig()` | Updates feature configuration                 |
+| `setPosition()`         | Updates widget position dynamically           |
+| `sendQuestion()`        | Sends a question to the avatar                |
 
 ---
 
-### 1.4 Authentication
+### 2.4 Authentication
 
 The SDK requires an **auth token** to connect to the Napster Companion API.
 
 **Important:** **Do not generate tokens in client-side code** — use a backend service to keep your API key secure.
 
-#### Step 1: Generate Napster Companion API Key
+#### Step 1: Generate Napster API Key
 
-1. Visit the [Napster Companion API Keys page](https://companion-api.napster.ai/admin/organization/keys)
+1. Visit the [Napster API Keys page](https://app.cogcache.com/organization/keys)
 2. Click **Generate API key** and enter your details
 3. Store your API key securely on your backend server
 
 #### Step 2: Create Connection & Get Token (Backend)
 
-Create a backend API call to the Napster Companion API to generate auth tokens:
-
-**Request URL:**
-
-```
-POST https://companion-api.napster.ai/public/connections
-```
-
-**Request Headers:**
-
-| Header         | Value               |
-| -------------- | ------------------- |
-| `content-type` | `application/json`  |
-| `x-api-key`    | `YOUR_API_KEY_HERE` |
-
-**Request Body:**
+Create a backend API call to the Napster API to generate auth tokens:
 
-| Field                                                       | Type    | Description                          |
-| ----------------------------------------------------------- | ------- | ------------------------------------ |
-| `companionId`                                               | string  | Your Napster Companion ID            |
-| `providerConfig.type`                                       | string  | Provider type (e.g., `azureOpenAI`)  |
-| `providerConfig.voiceId`                                    | string  | Voice identifier (e.g., `alloy`)     |
-| `providerConfig.settings.instructions`                      | string  | Custom instructions for the avatar   |
-| `providerConfig.settings.turnDetection.threshold`           | number  | Voice detection threshold            |
-| `providerConfig.settings.turnDetection.prefix_padding_ms`   | number  | Padding before speech detection (ms) |
-| `providerConfig.settings.turnDetection.silence_duration_ms` | number  | Silence duration threshold (ms)      |
-| `providerConfig.settings.temperature`                       | number  | Response temperature (0-1)           |
-| `providerConfig.useGreenVideo`                              | boolean | Enable green screen background       |
-| `disableIdleTimeout`                                        | boolean | Disable idle timeout                 |
-
-**Example Request:**
-
-```bash
-curl 'https://companion-api.napster.ai/public/connections' \
+```sh
+curl 'https://management-api.cogcache.com/public/connections' \
+  -H 'accept: */*' \
+  -H 'accept-language: en-GB,en-US;q=0.9,en;q=0.8' \
   -H 'content-type: application/json' \
   -H 'x-api-key: YOUR_API_KEY_HERE' \
   --data-raw '{
@@ -215,8 +191,7 @@ curl 'https://companion-api.napster.ai/public/connections' \
         "temperature": 0
       },
       "useGreenVideo": true
-    },
-    "disableIdleTimeout": false
+    }
   }'
 ```
 
@@ -225,608 +200,835 @@ curl 'https://companion-api.napster.ai/public/connections' \
 Fetch the token from your backend and pass it to the SDK:
 
 ```typescript
-// Possible client-side code for token retrieval
+// Client-side code
 async function initializeAvatar() {
   // Fetch token from your backend
-  const response = await fetch("/your-backend-endpoint", { method: "POST" });
+  const response = await fetch("/api/get-napster-token", { method: "POST" });
   const { token } = await response.json();
+
+  // Initialize SDK with the token
+  const widget = await NapsterCompanionApiSdk.init(token, {
+    mountContainer: "#avatar-container",
+    position: "bottom-right",
+  });
 }
 ```
 
 ---
 
-## 2. Examples
+## 3. Feature Configuration
 
-We provide example implementations for popular frameworks and vanilla JavaScript:
+The SDK supports several configurable features. You can enable/disable them during initialization or update them dynamically at runtime.
 
-### 2.1 React
+### Available Features
 
-```tsx
-import React, { useEffect, useRef, useState } from "react";
-import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
-import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
+| Feature             | Description                                 | Default Value                                |
+| ------------------- | ------------------------------------------- | -------------------------------------------- |
+| `waveform`          | Display audio waveform visualization        | `{ enabled: false }`                         |
+| `backgroundRemoval` | Remove avatar background for transparency   | `{ enabled: false }`                         |
+| `inactiveTimeout`   | Auto-hide avatar after period of inactivity | `{ enabled: false, timeoutDuration: 60000 }` |
+| `disclaimer`        | Show disclaimer text above the avatar       | `{ enabled: false, text: "" }`               |
 
-export function CompanionWidget() {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [instance, setInstance] = useState<NapsterCompanionApiInstance | null>(
-    null
-  );
-
-  useEffect(() => {
-    const initSDK = async () => {
-      if (!containerRef.current) return;
+### Configuration During Initialization
 
-      const result = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-        mountContainer: containerRef.current,
-        position: "bottom-right",
-        features: {
-          waveform: { enabled: true },
-          backgroundRemoval: { enabled: true },
-        },
-      });
-      setInstance(result);
-    };
+```typescript
+const widget = await NapsterCompanionApiSdk.init("YOUR_AUTH_TOKEN", {
+  mountContainer: "#avatar-container",
+  position: "bottom-right",
+  features: {
+    autoplay: { enabled: true },
+    waveform: { enabled: true },
+    backgroundRemoval: { enabled: false },
+    inactiveTimeout: {
+      enabled: true,
+      timeoutDuration: 60000, // 60 seconds
+    },
+  },
+});
+```
 
-    initSDK();
+### Dynamic Feature Updates
 
-    return () => {
-      instance?.destroy();
-    };
-  }, []);
+Update feature configuration after initialization:
 
-  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
-}
+```typescript
+// Enable/disable a single feature
+widget.enableFeature("waveform");
+widget.disableFeature("waveform");
+
+// Update feature configuration
+widget.updateFeatureConfig({
+  autoplay: { enabled: true },
+  inactiveTimeout: {
+    enabled: true,
+    timeoutDuration: 30000, // 30 seconds
+  },
+});
 ```
 
-### 2.2 Vue 3
+---
 
-```html
-<template>
-  <div ref="containerRef"></div>
-</template>
+## 4. API Reference
 
-<script setup lang="ts">
-  import { onMounted, onUnmounted, ref } from "vue";
-  import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
-  import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
+### Initialization
 
-  const containerRef = ref<HTMLElement>();
-  let instance: NapsterCompanionApiInstance | null = null;
+#### `NapsterCompanionApiSdk.init(token, options)`
 
-  onMounted(async () => {
-    if (!containerRef.value) return;
-
-    instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-      mountContainer: containerRef.value,
-      position: "bottom-right",
-      features: {
-        waveform: { enabled: true },
-        backgroundRemoval: { enabled: true },
-      },
-    });
-  });
+Initialize and mount the avatar widget.
 
-  onUnmounted(() => {
-    instance?.destroy();
-  });
-</script>
-```
+**Parameters:**
 
-### 2.3 Angular
+| Parameter | Type                        | Required | Description                  |
+| --------- | --------------------------- | -------- | ---------------------------- |
+| `token`   | `string`                    | Yes      | Auth token from your backend |
+| `options` | `NapsterCompanionApiConfig` | Yes      | Configuration object         |
+
+**`NapsterCompanionApiConfig` Interface:**
 
 ```typescript
-import {
-  Component,
-  OnInit,
-  OnDestroy,
-  ElementRef,
-  ViewChild,
-} from "@angular/core";
-import {
-  NapsterCompanionApiSdk,
-  NapsterCompanionApiInstance,
-} from "@touchcastllc/napster-companion-api";
+interface NapsterCompanionApiConfig {
+  mountContainer: string | HTMLElement; // CSS selector or DOM element
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  features?: {
+    autoplay?: { enabled: boolean };
+    waveform?: { enabled: boolean };
+    backgroundRemoval?: { enabled: boolean };
+    inactiveTimeout?: { enabled: boolean; timeoutDuration?: number };
+  };
+  styles?: {
+    width?: string;
+    height?: string;
+    zIndex?: number;
+  };
+  onReady?: () => void;
+  onError?: (error: Error) => void;
+  onData?: (data: EventMessage) => void;
+  onAvatarReady?: () => void;
+  onDestroy?: () => void;
+}
+```
 
-@Component({
-  selector: "app-companion",
-  template: "<div #containerRef></div>",
-})
-export class CompanionComponent implements OnInit, OnDestroy {
-  @ViewChild("containerRef") containerRef!: ElementRef<HTMLDivElement>;
-  private instance: NapsterCompanionApiInstance | null = null;
+**Returns:** `Promise<NapsterCompanionApiInstance>`
 
-  async ngOnInit() {
-    this.instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-      mountContainer: this.containerRef.nativeElement,
-      position: "bottom-right",
-      features: {
-        waveform: { enabled: true },
-        backgroundRemoval: { enabled: true },
-      },
-    });
-  }
+**Example:**
 
-  ngOnDestroy() {
-    this.instance?.destroy();
-  }
-}
+```typescript
+const widget = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+  mountContainer: "#avatar-container",
+  position: "bottom-right",
+});
 ```
 
-### 2.4 Vanilla JavaScript/TypeScript
+---
 
-```html
-<div id="sdk-container"></div>
-<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
-<script>
-  const sdk = window.napsterCompanionApiSDK;
-
-  sdk
-    .init("YOUR_TOKEN", {
-      mountContainer: "#sdk-container",
-      position: "bottom-right",
-      features: {
-        waveform: { enabled: true },
-        backgroundRemoval: { enabled: true },
-      },
-    })
-    .then(instance => {
-      // Control the avatar
-      instance.showAvatar();
+### Widget Instance Methods
 
-      // Hide after 10 seconds
-      setTimeout(() => instance.hideAvatar(), 10000);
-    });
-</script>
-```
+#### `widget.showAvatar()`
 
-### 2.5 Advanced Configuration
+Shows the avatar widget.
 
 ```typescript
-async function initAdvancedAvatar() {
-  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-    mountContainer: "#avatar-container",
-    position: "bottom-right",
+widget.showAvatar();
+```
 
-    features: {
-      backgroundRemoval: { enabled: true },
-      waveform: { enabled: true, color: "#00ff88" },
-      inactiveTimeout: { enabled: true, duration: 120000, countdown: 15 },
-      showSDKLoader: { enabled: true, bgColor: "#f0f0f0" },
-    },
+---
 
-    style: {
-      borderRadius: "12px",
-      boxShadow: "0 4px 20px rgba(0,0,0,0.3)",
-    },
+#### `widget.hideAvatar()`
 
-    onReady: () => console.log("Avatar ready!"),
-    onError: error => console.error("Error:", error),
-    onAvatarReady: ready => console.log("Avatar loaded:", ready),
-  });
+Hides the avatar widget.
 
-  return instance;
-}
+```typescript
+widget.hideAvatar();
 ```
 
-### 2.6 Dynamic Feature Control
+---
 
-```typescript
-async function controlFeatures() {
-  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-    mountContainer: "#avatar-container",
-  });
+#### `widget.destroy()`
 
-  // Toggle features dynamically
-  document.getElementById("toggle-waveform")?.addEventListener("click", () => {
-    if (instance.isFeatureEnabled("waveform")) {
-      instance.disableFeature("waveform");
-    } else {
-      instance.enableFeature("waveform");
-    }
-  });
+Destroys and unmounts the widget from the DOM. Call this during cleanup.
 
-  // Change position dynamically
-  document.getElementById("move-avatar")?.addEventListener("click", () => {
-    instance.setPosition("top-left");
-  });
-
-  return instance;
-}
+```typescript
+widget.destroy();
 ```
 
-### 2.7 Custom Styling
+---
 
-#### Inline Styles
+#### `widget.updateStyles(styles)`
 
-```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  style: {
-    border: "2px solid #00ff00",
-    borderRadius: "8px",
-    boxShadow: "0 2px 10px rgba(0,0,0,0.2)",
-    background: "rgba(255,255,255,0.95)",
-  },
-});
-```
+Update widget styling dynamically.
 
-#### CSS Classes
+**Parameters:**
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  className: "my-custom-avatar",
-});
-```
-
-```css
-.my-custom-avatar {
-  border: 2px solid #007acc;
-  border-radius: 12px;
-  backdrop-filter: blur(10px);
+interface React.CSSProperties {
+  width?: string;
+  height?: string;
+  zIndex?: number;
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
 }
 ```
 
-#### Dynamic Style Updates
+**Example:**
 
 ```typescript
-// Update styles after initialization
-instance.updateStyles({
-  opacity: "0.9",
-  transform: "scale(1.1)",
-  transition: "all 0.3s ease",
+widget.updateStyles({
+  width: "400px",
+  height: "600px",
+  zIndex: 1000,
+  position: "top-right",
 });
 ```
 
 ---
 
-## 3. Feature Configuration
+#### `widget.enableFeature(featureName)`
 
-### 3.1 Core Features
+Enable a specific feature.
 
-#### Background Removal (Green Screen)
+**Parameters:**
 
-Enable automatic green screen background removal for a clean, professional appearance. The avatar's background is removed in real-time, seamlessly blending with your application's design.
+- `featureName`: `"autoplay" | "waveform" | "backgroundRemoval" | "inactiveTimeout"`
 
-**Requirement:** Set `useGreenVideo: true` in the [Create Connection](#step-2-create-connection--get-token-backend) API request.
+**Example:**
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  features: {
-    backgroundRemoval: { enabled: true },
-  },
-});
+widget.enableFeature("waveform");
 ```
 
-#### Waveform Visualization
+---
+
+#### `widget.disableFeature(featureName)`
+
+Disable a specific feature.
+
+**Parameters:**
 
-Display a dynamic audio waveform visualization inside the avatar control area to visualize real-time speech activity. Customize the waveform color to match your application's theme.
+- `featureName`: `"autoplay" | "waveform" | "backgroundRemoval" | "inactiveTimeout"`
+
+**Example:**
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  features: {
-    waveform: {
-      enabled: true,
-      color: "#00ff00", // Optional custom color
-    },
-  },
-});
+widget.disableFeature("autoplay");
 ```
 
-#### Inactivity Timeout
+---
+
+#### `widget.updateFeatureConfig(config)`
 
-Automatically disconnect the avatar after a period of user inactivity. Users receive a countdown notification before disconnection.
+Update multiple feature configurations at once.
+
+**Parameters:**
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  features: {
-    inactiveTimeout: {
-      enabled: true,
-      duration: 60000, // 60 seconds (max: 180000ms)
-      countdown: 10, // 10 second countdown (max: 60s)
-    },
-  },
-});
+interface FeatureConfig {
+  autoplay?: { enabled: boolean };
+  waveform?: { enabled: boolean };
+  backgroundRemoval?: { enabled: boolean };
+  inactiveTimeout?: { enabled: boolean; timeoutDuration?: number };
+}
 ```
 
-#### SDK Loading Screen
-
-Display a loading screen while the avatar assets are being loaded. Customize the background color to match your application's design.
+**Example:**
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  features: {
-    showSDKLoader: {
-      enabled: true,
-      bgColor: "#ffffff", // Optional background color
-    },
-  },
+widget.updateFeatureConfig({
+  autoplay: { enabled: true },
+  inactiveTimeout: { enabled: true, timeoutDuration: 45000 },
 });
 ```
 
-### 3.2 Position & Layout
+---
 
-Customize the avatar's position on the screen using predefined positions or custom styles. Also you can override the position using style properties.
+### Type Definitions
 
 ```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  mountContainer: "#my-container", // CSS selector or HTMLElement
-  position: "bottom-right", // Predefined positions
-  // Apply custom inline styles to override default SDK styles, will be added to root container
-  style: {
-    top: "20px",
-    left: "20px",
-    zIndex: "1000",
-  },
-  // Apply CSS class name to override default SDK styles, will be added to root container
-  className: "my-custom-class",
-});
+// Main initialization options
+interface NapsterCompanionApiConfig {
+  mountContainer: string | HTMLElement;
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  features?: FeatureConfig;
+  styles?: React.CSSProperties;
+  onReady?: () => void;
+  onError?: (error: Error) => void;
+  onData?: (data: EventMessage) => void;
+  onAvatarReady?: () => void;
+  onDestroy?: () => void;
+}
+
+// Feature configuration
+interface FeatureConfig {
+  autoplay?: { enabled: boolean };
+  waveform?: { enabled: boolean };
+  backgroundRemoval?: { enabled: boolean };
+  inactiveTimeout?: { enabled: boolean; timeoutDuration?: number };
+}
+
+// Widget instance returned by init()
+interface NapsterCompanionApiInstance {
+  showAvatar(): void;
+  hideAvatar(): void;
+  destroy(): void;
+  updateStyles(styles: React.CSSProperties): void;
+  enableFeature(feature: string): void;
+  disableFeature(feature: string): void;
+  updateFeatureConfig(config: FeatureConfig): void;
+}
 ```
 
-**Available Positions:**
+---
 
-- `"bottom-right"` (default)
-- `"bottom-left"`
-- `"bottom-center"`
-- `"top-right"`
-- `"top-left"`
-- `"top-center"`
-- `"center"`
+## 5. Usage Examples
 
-## 4. Event Handling
+Framework-specific, copy-paste-ready snippets demonstrating proper lifecycle management.
 
-The SDK provides several event callbacks for monitoring status and handling errors.
+### React 18+ (Hooks)
 
-```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  // Fires when the SDK is initialized and ready to use
-  onReady: () => console.log("SDK ready!"),
-  // Fires on any SDK error
-  onError: error => console.error("SDK error:", error),
-  // Fires when the avatar is fully loaded and ready
-  onAvatarReady: isReady => console.log("Avatar ready:", isReady),
-  // Fires when user inactivity status changes
-  onInactivityStatusChange: isInactive => console.log("Inactive:", isInactive),
-  // Fires when the SDK is destroyed
-  onDestroy: () => console.log("SDK destroyed"),
-  // Fires when data is received from the WEBRTC data channel
-  onData: data => console.log("Data received:", data),
-});
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+
+export function AvatarWidget() {
+  const containerRef = useRef(null);
+  const [widget, setWidget] = useState(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function initialize() {
+      try {
+        // Fetch token from your backend
+        const response = await fetch("/api/get-napster-token", {
+          method: "POST",
+        });
+        const { token } = await response.json();
+
+        // Initialize widget
+        const instance = await NapsterCompanionApiSdk.init(token, {
+          mountContainer: containerRef.current,
+          position: "bottom-right",
+          features: {
+            autoplay: { enabled: true },
+            waveform: { enabled: true },
+          },
+        });
+
+        if (mounted) {
+          setWidget(instance);
+        }
+      } catch (error) {
+        console.error("Failed to initialize avatar:", error);
+      }
+    }
+
+    initialize();
+
+    // Cleanup on unmount
+    return () => {
+      mounted = false;
+      widget?.destroy();
+    };
+  }, []);
+
+  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
+}
 ```
 
 ---
 
-## 5. API Reference
+### React 16/17 (Class Component)
 
-### 5.1 Core Methods
+```tsx
+import React from "react";
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api/legacy";
+
+export class AvatarWidget extends React.Component {
+  containerRef = React.createRef();
+  widget = null;
+
+  async componentDidMount() {
+    try {
+      // Fetch token from your backend
+      const response = await fetch("/api/get-napster-token", {
+        method: "POST",
+      });
+      const { token } = await response.json();
 
-#### `init(token: string, config?: NapsterCompanionApiConfig): Promise<NapsterCompanionApiInstance>`
+      // Initialize widget
+      this.widget = await NapsterCompanionApiSdk.init(token, {
+        mountContainer: this.containerRef.current,
+        position: "bottom-right",
+        features: {
+          autoplay: { enabled: true },
+        },
+      });
+    } catch (error) {
+      console.error("Failed to initialize avatar:", error);
+    }
+  }
 
-Initialize the SDK with authentication token and configuration.
+  componentWillUnmount() {
+    // Cleanup on unmount
+    this.widget?.destroy();
+  }
 
-```typescript
-const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-  mountContainer: "#avatar-container",
-  position: "bottom-right",
-});
+  render() {
+    return (
+      <div ref={this.containerRef} style={{ width: "100%", height: "100%" }} />
+    );
+  }
+}
 ```
 
-#### `showAvatar(): void`
+---
 
-Make the avatar visible on screen.
+### Vue 3
 
-```typescript
-instance.showAvatar();
+```html
+<template>
+  <div ref="containerRef" style="width: 100%; height: 100%;"></div>
+</template>
+
+<script setup>
+  import { ref, onMounted, onBeforeUnmount } from "vue";
+  import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+  import "@touchcastllc/napster-companion-api/lib/index.css";
+
+  const containerRef = ref(null);
+  let widget = null;
+
+  onMounted(async () => {
+    try {
+      // Fetch token from your backend
+      const response = await fetch("/api/get-napster-token", {
+        method: "POST",
+      });
+      const { token } = await response.json();
+
+      // Initialize widget
+      widget = await NapsterCompanionApiSdk.init(token, {
+        mountContainer: containerRef.value,
+        position: "bottom-right",
+        features: {
+          autoplay: { enabled: true },
+          waveform: { enabled: true },
+        },
+      });
+    } catch (error) {
+      console.error("Failed to initialize avatar:", error);
+    }
+  });
+
+  onBeforeUnmount(() => {
+    // Cleanup on unmount
+    widget?.destroy();
+  });
+</script>
 ```
 
-#### `hideAvatar(): void`
+---
 
-Hide the avatar from screen.
+### Vue 2
 
-```typescript
-instance.hideAvatar();
+```html
+<template>
+  <div ref="container" style="width: 100%; height: 100%;"></div>
+</template>
+
+<script>
+  import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+  import "@touchcastllc/napster-companion-api/lib/index.css";
+
+  export default {
+    name: "AvatarWidget",
+    data() {
+      return {
+        widget: null,
+      };
+    },
+    async mounted() {
+      try {
+        // Fetch token from your backend
+        const response = await fetch("/api/get-napster-token", {
+          method: "POST",
+        });
+        const { token } = await response.json();
+
+        // Initialize widget
+        this.widget = await NapsterCompanionApiSdk.init(token, {
+          mountContainer: this.$refs.container,
+          position: "bottom-right",
+          features: {
+            autoplay: { enabled: true },
+          },
+        });
+      } catch (error) {
+        console.error("Failed to initialize avatar:", error);
+      }
+    },
+    beforeDestroy() {
+      // Cleanup on unmount
+      this.widget?.destroy();
+    },
+  };
+</script>
 ```
 
-#### `avatarIsVisible(): boolean`
+---
 
-Check if the avatar is currently visible.
+### Angular
 
 ```typescript
-if (instance.avatarIsVisible()) {
-  console.log("Avatar is visible");
+import {
+  Component,
+  OnInit,
+  OnDestroy,
+  ElementRef,
+  ViewChild,
+} from "@angular/core";
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+
+@Component({
+  selector: "app-avatar-widget",
+  template: ` <div #container style="width: 100%; height: 100%;"></div> `,
+  styles: [
+    `
+      @import "@touchcastllc/napster-companion-api/lib/index.css";
+    `,
+  ],
+})
+export class AvatarWidgetComponent implements OnInit, OnDestroy {
+  @ViewChild("container", { static: true }) container!: ElementRef;
+  private widget: any = null;
+
+  async ngOnInit() {
+    try {
+      // Fetch token from your backend
+      const response = await fetch("/api/get-napster-token", {
+        method: "POST",
+      });
+      const { token } = await response.json();
+
+      // Initialize widget
+      this.widget = await NapsterCompanionApiSdk.init(token, {
+        mountContainer: this.container.nativeElement,
+        position: "bottom-right",
+        features: {
+          autoplay: { enabled: true },
+          waveform: { enabled: true },
+        },
+      });
+    } catch (error) {
+      console.error("Failed to initialize avatar:", error);
+    }
+  }
+
+  ngOnDestroy() {
+    // Cleanup on unmount
+    this.widget?.destroy();
+  }
 }
 ```
 
-#### `destroy(): void`
+---
 
-Cleanup and remove the SDK completely.
+### Vanilla JS / Core (No Build Tools)
 
-```typescript
-instance.destroy();
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Napster Avatar SDK</title>
+  </head>
+  <body>
+    <div id="avatar-container"></div>
+
+    <script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.min.js"></script>
+    <script>
+      (async function () {
+        try {
+          // Fetch token from your backend
+          const response = await fetch("/api/get-napster-token", {
+            method: "POST",
+          });
+          const { token } = await response.json();
+
+          // Initialize widget
+          const widget = await window.CompanionApiSDK.init(token, {
+            mountContainer: "#avatar-container",
+            position: "bottom-right",
+            features: {
+              autoplay: { enabled: true },
+              waveform: { enabled: true },
+            },
+          });
+
+          // Widget controls
+          // widget.showAvatar();
+          // widget.hideAvatar();
+          // widget.destroy();
+        } catch (error) {
+          console.error("Failed to initialize avatar:", error);
+        }
+      })();
+    </script>
+  </body>
+</html>
 ```
 
-### 5.2 Styling & Position Methods
+---
+
+## 6. Styling & Customization
 
-#### `updateStyles(styles: StyleObject): void`
+### CSS Import Path
 
-Update container styles dynamically.
+Always import the SDK's CSS file to ensure proper styling:
+
+**For Bundler Projects:**
 
 ```typescript
-instance.updateStyles({
-  top: "50px",
-  left: "50px",
-  opacity: "0.8",
-});
+import "@touchcastllc/napster-companion-api/lib/index.css";
 ```
 
-#### `setPosition(position: Position): void`
-
-Change avatar position on screen.
+**For Browser Script Tags:**
 
-```typescript
-instance.setPosition("top-left");
-// or using enum
-import { Position } from "@touchcastllc/napster-companion-api";
-instance.setPosition(Position.TOP_LEFT);
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
+/>
 ```
 
-#### `clearPosition(): void`
+### Custom Container Styling
 
-Reset position to default/configured value.
+You can customize the avatar container's size, position, and z-index:
 
 ```typescript
-instance.clearPosition();
+const widget = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+  mountContainer: "#avatar-container",
+  position: "bottom-right",
+  styles: {
+    width: "400px",
+    height: "600px",
+    zIndex: 9999,
+  },
+});
+
+// Update styles dynamically
+widget.updateStyles({
+  width: "500px",
+  height: "700px",
+  position: "top-right",
+});
 ```
 
-### 5.3 Feature Control Methods
+---
 
-#### `enableFeature(feature: string): void`
+## 7. Troubleshooting
 
-Enable a specific feature.
+Common integration errors and their quick resolutions.
 
-```typescript
-instance.enableFeature("waveform");
-instance.enableFeature("backgroundRemoval");
-```
+### React Version Mismatch
 
-#### `disableFeature(feature: string): void`
+**Error:** `Error: Invalid hook call` or `React version mismatch`
 
-Disable a specific feature.
+**Cause:** Using the wrong SDK entry point for your React version.
 
-```typescript
-instance.disableFeature("waveform");
-instance.disableFeature("backgroundRemoval");
+**Solution:**
+
+- For React 18+, use: `import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";`
+- For React 16/17, use: `import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api/legacy";`
+
+```bash
+# Check your React version
+npm list react
 ```
 
-#### `isFeatureEnabled(feature: string): boolean`
+---
 
-Check if a feature is currently enabled.
+### Missing CSS Styles
 
-```typescript
-if (instance.isFeatureEnabled("waveform")) {
-  console.log("Waveform is enabled");
-}
-```
+**Error:** Widget appears unstyled or invisible
 
-## 6. Configuration Interface
+**Cause:** CSS file not imported.
+
+**Solution:**
+
+Add the CSS import:
 
 ```typescript
-interface NapsterCompanionApiConfig {
-  // Container mounting
-  mountContainer?: HTMLElement | string | null;
-
-  // Positioning
-  position?:
-    | "bottom-right"
-    | "bottom-left"
-    | "bottom-center"
-    | "top-right"
-    | "top-left"
-    | "top-center"
-    | "center";
-
-  // Styling
-  style?: StyleObject;
-  className?: string;
-
-  // Features
-  features?: {
-    backgroundRemoval?: { enabled: boolean };
-    waveform?: { enabled: boolean; color?: string };
-    inactiveTimeout?: {
-      enabled: boolean;
-      duration?: number; // max: 180000ms
-      countdown?: number; // max: 60s
-    };
-    disclaimer?: { enabled: boolean; text?: string };
-    showSDKLoader?: { enabled: boolean; bgColor?: string };
-  };
+import "@touchcastllc/napster-companion-api/lib/index.css";
+```
 
-  // Configuration
-  debug?: boolean;
+For HTML script tags:
 
-  // Event callbacks
-  onReady?: () => void;
-  onError?: (error: Error) => void;
-  onData?: (data: EventMessage) => void;
-  onAvatarReady?: (isReady?: boolean) => void;
-  onInactivityStatusChange?: (isInactive: boolean) => void;
-  onDestroy?: () => void;
-  onFeaturesUpdate?: (features: FeatureConfig) => void;
-}
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
+/>
 ```
 
 ---
 
-## 7. Troubleshooting
+### CORS Errors
+
+**Error:** `Cross-Origin Request Blocked` when fetching token
 
-### 7.1 Common Issues
+**Cause:** Making token generation API calls from the browser.
 
-**Problem: "Module not found" Error**  
 **Solution:**
 
-```bash
-# Ensure package is installed
-npm install @touchcastllc/napster-companion-api
+**Never generate tokens in client-side code.** Create a backend endpoint:
+
+```javascript
+// Backend (Node.js/Express)
+app.post("/api/get-napster-token", async (req, res) => {
+  const response = await fetch(
+    "https://management-api.cogcache.com/public/connections",
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": process.env.NAPSTER_API_KEY,
+      },
+      body: JSON.stringify({
+        companionId: process.env.COMPANION_ID,
+        providerConfig: {
+          /* your config */
+        },
+      }),
+    }
+  );
+  const data = await response.json();
+  res.json({ token: data.token });
+});
+```
 
-# Install peer dependencies
-npm install @reduxjs/toolkit
+Then fetch from your backend in the client:
+
+```typescript
+const response = await fetch("/api/get-napster-token", { method: "POST" });
+const { token } = await response.json();
 ```
 
-**Problem: Invalid or expired token**  
-**Solution:**
+---
+
+### Authentication / Token Issues
+
+**Error:** `401 Unauthorized` or `Invalid token`
+
+**Possible Causes:**
 
-- Generate new token from backend API
-- Ensure token is passed correctly to `init()`
+1. Token expired
+2. Invalid API key
+3. Incorrect companion ID
 
-**Problem: Avatar appears unstyled**  
 **Solution:**
 
-See the style import guide from [1.2.1 Installation & Setup](#121-for-esm-build-type-recommended)
+1. **Verify your API key** at [Napster API Keys page](https://app.cogcache.com/organization/keys)
+2. **Check token expiration** - generate a fresh token
+3. **Verify companion ID** matches your configuration
+4. **Ensure backend endpoint** is working:
+
+---
+
+### Widget Not Mounting
+
+**Error:** Container element not found or widget doesn't appear
+
+**Possible Causes:**
+
+1. Container element doesn't exist
+2. Invalid CSS selector
+3. Container rendered after initialization
 
-**Problem:** `mountContainer` element doesn't exist  
 **Solution:**
 
 ```typescript
-// Wait for DOM to load
-document.addEventListener("DOMContentLoaded", async () => {
-  const instance = await NapsterCompanionApiSdk.init(token, {
-    mountContainer: "#avatar-container", // Ensure element exists
-  });
+// ✅ Good: Wait for DOM element
+useEffect(() => {
+  const container = document.querySelector("#avatar-container");
+  if (container) {
+    NapsterCompanionApiSdk.init(token, {
+      mountContainer: container, // Use DOM element directly
+    });
+  }
+}, []);
+
+// ❌ Bad: Container may not exist yet
+const widget = NapsterCompanionApiSdk.init(token, {
+  mountContainer: "#avatar-container",
 });
 ```
 
-### 7.2 Debug Mode
+---
 
-Enable debug logging:
+### Module Not Found
 
-```typescript
-const instance = await NapsterCompanionApiSdk.init(token, {
-  debug: true, // Enable debug logs
-  onError: error => console.error("SDK Error:", error),
-  onData: data => console.log("SDK Data:", data),
-});
+**Error:** `Cannot find module '@touchcastllc/napster-companion-api'`
+
+**Cause:** Package not installed.
+
+**Solution:**
+
+```bash
+npm install @touchcastllc/napster-companion-api
+# or
+yarn add @touchcastllc/napster-companion-api
 ```
 
-### 7.3 Performance Issues
+---
 
-#### Large Bundle Size
+### Peer Dependency Warnings
 
-- Use ESM build instead of standalone
-- Import only needed features
-- Enable tree-shaking in bundler
+**Warning:** `ERESOLVE unable to resolve dependency tree`
 
-#### Memory Leaks
+**Cause:** Missing or incompatible peer dependencies.
 
-```typescript
-// Always cleanup when done
-useEffect(() => {
-  return () => {
-    instance?.destroy();
-  };
-}, [instance]);
+**Solution:**
+
+Install all required peer dependencies:
+
+```bash
+# For React 18+
+npm install react@^18 react-dom@^18 @reduxjs/toolkit@^2 react-redux@^9
+
+# For React 16/17
+npm install react@^16 react-dom@^16 @reduxjs/toolkit@^2 react-redux@^8
+```
+
+---
+
+### TypeScript Errors
+
+**Error:** `Cannot find type definitions`
+
+**Cause:** TypeScript can't locate type definitions.
+
+**Solution:**
+
+The SDK includes TypeScript definitions. Ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
 ```
 
 ---
 
-## License
+## 📚 Additional Resources
+
+- **API Keys**: [Generate API Keys](https://app.cogcache.com/organization/keys)
+- **npm**: [@touchcastllc/napster-companion-api](https://www.npmjs.com/package/@touchcastllc/napster-companion-api)
+
+---
+
+## 📝 License
 
-This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE) file for details.