@touchcastllc/napster-companion-api 1.0.0-alpha.3 → 1.0.0-alpha.31

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@touchcastllc/napster-companion-api.svg)](https://www.npmjs.com/package/@touchcastllc/napster-companion-api)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-> A powerful, flexible JavaScript SDK for integrating AI-powered avatar experiences into your web application. Build with **Napster** and deliver engaging, interactive content across all major frameworks and deployment scenarios.
+> Real-time conversational video AI for web applications. Embed AI companions that users can talk to face-to-face via WebRTC. Attaches to any DOM element, handles video streaming and avatar rendering, connects to Azure OpenAI for conversation.
 
 **Supported Environments:**
 
@@ -15,47 +15,37 @@
 
 **Key Capabilities:**
 
-- 🎯 **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**: 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
+- **WebRTC Video Streaming:** Real-time video with AI avatars
+- **Framework Agnostic:** React, Vue, Angular, or vanilla JS
+- **Zero External Dependencies:** Drop in a script tag and go
+- **TypeScript Support:** Fully typed APIs
+- **Tree-Shakeable:** Import only what you need
+- **Production Ready:** Minified builds with type definitions
 
 ---
 
-## 2. Quick Start
+## 1. Quick Start
 
 Get up and running in minutes. Follow these four steps to integrate the SDK into your project.
 
-### 2.1 Choose Your Setup
+### 1.1 Choose Your Setup
 
 Pick the integration method that matches your project:
 
-| 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              |
+| 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          |
 
-**Quick Links:**
+---
 
-- [React 18+ Example](#react-18-hooks)
-- [React 16/17 Example](#react-1617-class-component)
-- [Vue 3 Example](#vue-3)
-- [Vue 2 Example](#vue-2)
-- [Angular Example](#angular)
-- [Vanilla JS Example](#vanilla-js--core-no-build-tools)
+### 1.2 Installation & Setup
 
-### 2.2 Installation & Import
+#### 1.2.1 For ESM Build Type (Recommended)
 
-#### For Bundler-Based Projects
+**Step 1: Install the SDK**
 
-**Install the package:**
+Install the package:
 
 ```bash
 npm install @touchcastllc/napster-companion-api
@@ -63,117 +53,150 @@ npm install @touchcastllc/napster-companion-api
 yarn add @touchcastllc/napster-companion-api
 ```
 
-**Install peer dependencies:**
+Install 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
+npm install @reduxjs/toolkit
 ```
 
-**Import the SDK:**
+**Step 2: Import the SDK**
 
 ```typescript
-// React 18+
 import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
-
-// React 16/17
-import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api/legacy";
 ```
 
-**Import CSS (required):**
+**Also, import CSS Stylesheet (required):**
+
+The SDK comes with a complete stylesheet for all components. Import it in your application:
+
+**ESM/TypeScript:**
 
 ```typescript
-import "@touchcastllc/napster-companion-api/lib/index.css";
+import "@touchcastllc/napster-companion-api/styles";
 ```
 
-#### For Browser Script Tags
+**CommonJS:**
+
+```js
+require("@touchcastllc/napster-companion-api/styles");
+```
 
-**Option A: Standalone (Easiest - React Included)**
+**HTML `<link>` Tag:**
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.min.js"></script>
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
+/>
 ```
 
-**Option B: UMD (Smaller - Bring Your Own React)**
+**CSS `@import`:**
+
+```css
+@import url("https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css");
+```
+
+The CSS file (`index.css`) is minified and contains all styles needed for the avatar widget, controls, tooltips, and more.
+
+#### 1.2.2 For Standalone Build Type
+
+**Step 1: Import the SDK**
 
 ```html
-<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>
+<!-- All dependencies bundled (easier, larger file) -->
+<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
 ```
 
-### 2.3 Initialization
+---
+
+### 1.3 Initialization
+
+#### 1.3.1 For ESM Build Type
 
 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 },
-  },
 });
-
-// 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
 ```
 
-**What `init()` Returns:**
+#### 1.3.2 For Standalone Build Type
+
+Initialize the SDK by calling `window.napsterCompanionApiSDK.init()` with your auth token and configuration options.
 
-The `init()` method returns a widget instance with the following methods:
+See the [1.4 Authentication](#14-authentication) section for details on generating auth tokens.
 
-| 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                |
+**Step 1: Add container to your HTML**
+
+```html
+<div id="sdk-container"></div>
+```
+
+**Step 2: Initialize globally**
+
+```html
+<script>
+  window.napsterCompanionApiSDK.init("AUTH_TOKEN", {
+    mountContainer: "#sdk-container",
+  });
+</script>
+```
 
 ---
 
-### 2.4 Authentication
+### 1.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 API Key
+#### Step 1: Generate Napster Companion API Key
 
-1. Visit the [Napster API Keys page](https://app.cogcache.com/organization/keys)
+1. Visit the [Napster Companion API Keys page](https://companion-api.napster.com/admin/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 API to generate auth tokens:
+Create a backend API call to the Napster Companion API to generate auth tokens:
+
+**Request URL:**
 
-```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' \
+```
+POST https://companion-api.napster.com/public/connections
+```
+
+**Request Headers:**
+
+| Header         | Value               |
+| -------------- | ------------------- |
+| `content-type` | `application/json`  |
+| `x-api-key`    | `YOUR_API_KEY_HERE` |
+
+**Request Body:**
+
+| 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.com/public/connections' \
   -H 'content-type: application/json' \
   -H 'x-api-key: YOUR_API_KEY_HERE' \
   --data-raw '{
@@ -191,7 +214,8 @@ curl 'https://management-api.cogcache.com/public/connections' \
         "temperature": 0
       },
       "useGreenVideo": true
-    }
+    },
+    "disableIdleTimeout": false
   }'
 ```
 
@@ -200,835 +224,607 @@ curl 'https://management-api.cogcache.com/public/connections' \
 Fetch the token from your backend and pass it to the SDK:
 
 ```typescript
-// Client-side code
+// Possible client-side code for token retrieval
 async function initializeAvatar() {
   // Fetch token from your backend
-  const response = await fetch("/api/get-napster-token", { method: "POST" });
+  const response = await fetch("/your-backend-endpoint", { method: "POST" });
   const { token } = await response.json();
-
-  // Initialize SDK with the token
-  const widget = await NapsterCompanionApiSdk.init(token, {
-    mountContainer: "#avatar-container",
-    position: "bottom-right",
-  });
 }
 ```
 
 ---
 
-## 3. Feature Configuration
+## 2. Examples
 
-The SDK supports several configurable features. You can enable/disable them during initialization or update them dynamically at runtime.
+We provide example implementations for popular frameworks and vanilla JavaScript:
 
-### Available Features
+### 2.1 React
 
-| 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: "" }`               |
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
 
-### Configuration During Initialization
+export function CompanionWidget() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [instance, setInstance] = useState<NapsterCompanionApiInstance | null>(
+    null
+  );
 
-```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
-    },
-  },
-});
-```
+  useEffect(() => {
+    const initSDK = async () => {
+      if (!containerRef.current) return;
 
-### Dynamic Feature Updates
+      const result = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+        mountContainer: containerRef.current,
+        position: "bottom-right",
+      });
+      setInstance(result);
+    };
 
-Update feature configuration after initialization:
+    initSDK();
 
-```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
-  },
-});
+    return () => {
+      instance?.destroy();
+    };
+  }, []);
+
+  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
+}
 ```
 
----
+### 2.2 Vue 3
 
-## 4. API Reference
+```html
+<template>
+  <div ref="containerRef"></div>
+</template>
 
-### Initialization
+<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";
 
-#### `NapsterCompanionApiSdk.init(token, options)`
+  const containerRef = ref<HTMLElement>();
+  let instance: NapsterCompanionApiInstance | null = null;
 
-Initialize and mount the avatar widget.
+  onMounted(async () => {
+    if (!containerRef.value) return;
 
-**Parameters:**
+    instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+      mountContainer: containerRef.value,
+      position: "bottom-right",
+    });
+  });
 
-| Parameter | Type                        | Required | Description                  |
-| --------- | --------------------------- | -------- | ---------------------------- |
-| `token`   | `string`                    | Yes      | Auth token from your backend |
-| `options` | `NapsterCompanionApiConfig` | Yes      | Configuration object         |
+  onUnmounted(() => {
+    instance?.destroy();
+  });
+</script>
+```
 
-**`NapsterCompanionApiConfig` Interface:**
+### 2.3 Angular
 
 ```typescript
-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;
-}
-```
+import {
+  Component,
+  OnInit,
+  OnDestroy,
+  ElementRef,
+  ViewChild,
+} from "@angular/core";
+import {
+  NapsterCompanionApiSdk,
+  NapsterCompanionApiInstance,
+} from "@touchcastllc/napster-companion-api";
 
-**Returns:** `Promise<NapsterCompanionApiInstance>`
+@Component({
+  selector: "app-companion",
+  template: "<div #containerRef></div>",
+})
+export class CompanionComponent implements OnInit, OnDestroy {
+  @ViewChild("containerRef") containerRef!: ElementRef<HTMLDivElement>;
+  private instance: NapsterCompanionApiInstance | null = null;
 
-**Example:**
+  async ngOnInit() {
+    this.instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+      mountContainer: this.containerRef.nativeElement,
+      position: "bottom-right",
+    });
+  }
 
-```typescript
-const widget = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
-  mountContainer: "#avatar-container",
-  position: "bottom-right",
-});
+  ngOnDestroy() {
+    this.instance?.destroy();
+  }
+}
 ```
 
----
-
-### Widget Instance Methods
+### 2.4 Vanilla JavaScript/TypeScript
 
-#### `widget.showAvatar()`
+```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",
+    })
+    .then(instance => {
+      // Control the avatar
+      instance.showAvatar();
+
+      // Hide after 10 seconds
+      setTimeout(() => instance.hideAvatar(), 10000);
+    });
+</script>
+```
 
-Shows the avatar widget.
+### 2.5 Advanced Configuration
 
 ```typescript
-widget.showAvatar();
-```
-
----
+async function initAdvancedAvatar() {
+  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+    mountContainer: "#avatar-container",
+    position: "bottom-right",
 
-#### `widget.hideAvatar()`
+    avatarStyle: {
+      view: "round", // Options: "round" | "rectangle" | "silhouette"
+    },
 
-Hides the avatar widget.
+    features: {
+      inactiveTimeout: { enabled: true, duration: 120000, countdown: 15 },
+      showSDKLoader: { enabled: true, bgColor: "#f0f0f0" },
+    },
 
-```typescript
-widget.hideAvatar();
-```
+    style: {
+      borderRadius: "12px",
+      boxShadow: "0 4px 20px rgba(0,0,0,0.3)",
+    },
 
----
+    onReady: () => console.log("Avatar ready!"),
+    onError: error => console.error("Error:", error),
+    onAvatarReady: ready => console.log("Avatar loaded:", ready),
+  });
 
-#### `widget.destroy()`
+  return instance;
+}
+```
 
-Destroys and unmounts the widget from the DOM. Call this during cleanup.
+### 2.6 Dynamic Feature Control
 
 ```typescript
-widget.destroy();
-```
+async function controlFeatures() {
+  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+    mountContainer: "#avatar-container",
+  });
 
----
+  // Change position dynamically
+  document.getElementById("move-avatar")?.addEventListener("click", () => {
+    instance.setPosition("top-left");
+  });
 
-#### `widget.updateStyles(styles)`
+  return instance;
+}
+```
 
-Update widget styling dynamically.
+### 2.7 Custom Styling
 
-**Parameters:**
+#### Inline Styles
 
 ```typescript
-interface React.CSSProperties {
-  width?: string;
-  height?: string;
-  zIndex?: number;
-  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-}
+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)",
+  },
+});
 ```
 
-**Example:**
+#### CSS Classes
 
 ```typescript
-widget.updateStyles({
-  width: "400px",
-  height: "600px",
-  zIndex: 1000,
-  position: "top-right",
+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);
+}
+```
 
-#### `widget.enableFeature(featureName)`
+#### Dynamic Style Updates
 
-Enable a specific feature.
+```typescript
+// Update styles after initialization
+instance.updateStyles({
+  opacity: "0.9",
+  transform: "scale(1.1)",
+  transition: "all 0.3s ease",
+});
+```
 
-**Parameters:**
+### 2.8 Avatar Style Configuration
 
-- `featureName`: `"autoplay" | "waveform" | "backgroundRemoval" | "inactiveTimeout"`
+Customize the avatar's visual appearance using the `avatarStyle` configuration. Control the avatar's view mode, and other visual properties.
 
-**Example:**
+#### Avatar View Modes
 
 ```typescript
-widget.enableFeature("waveform");
+const instance = await NapsterCompanionApiSdk.init(token, {
+  avatarStyle: {
+    view: "round", // Options: "round" | "rectangle" | "silhouette"
+  },
+});
 ```
 
----
-
-#### `widget.disableFeature(featureName)`
-
-Disable a specific feature.
-
-**Parameters:**
+**Available View Modes:**
 
-- `featureName`: `"autoplay" | "waveform" | "backgroundRemoval" | "inactiveTimeout"`
+- `"round"` (default) - Circular avatar with rounded appearance
+- `"rectangle"` - Rectangular container, ideal for custom styling
+- `"silhouette"` - Full view without background styling. (**Note: works only with green screen feature enabled in [Create Connection](#step-2-create-connection--get-token-backend) API**)
 
-**Example:**
+#### Avatar Style Example
 
 ```typescript
-widget.disableFeature("autoplay");
+const instance = await NapsterCompanionApiSdk.init(token, {
+  avatarStyle: {
+    view: "rectangle",
+  },
+  style: {
+    borderRadius: "16px", // Works well with rectangle
+    boxShadow: "0 8px 32px rgba(0,0,0,0.2)",
+  },
+});
 ```
 
 ---
 
-#### `widget.updateFeatureConfig(config)`
+## 3. Feature Configuration
 
-Update multiple feature configurations at once.
+### 3.1 Core Features
 
-**Parameters:**
+#### Inactivity Timeout
 
-```typescript
-interface FeatureConfig {
-  autoplay?: { enabled: boolean };
-  waveform?: { enabled: boolean };
-  backgroundRemoval?: { enabled: boolean };
-  inactiveTimeout?: { enabled: boolean; timeoutDuration?: number };
-}
-```
-
-**Example:**
+Automatically disconnect the avatar after a period of user inactivity. Users receive a countdown notification before disconnection.
 
 ```typescript
-widget.updateFeatureConfig({
-  autoplay: { enabled: true },
-  inactiveTimeout: { enabled: true, timeoutDuration: 45000 },
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    inactiveTimeout: {
+      enabled: true,
+      duration: 60000, // 60 seconds (max: 180000ms)
+      countdown: 10, // 10 second countdown (max: 60s)
+    },
+  },
 });
 ```
 
----
+#### SDK Loading Screen
 
-### Type Definitions
+Display a loading screen while the avatar assets are being loaded. Customize the background color to match your application's design.
 
 ```typescript
-// 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;
-}
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    showSDKLoader: {
+      enabled: true,
+      bgColor: "#ffffff", // Optional background color
+    },
+  },
+});
 ```
 
----
-
-## 5. Usage Examples
+### 3.2 Position & Layout
 
-Framework-specific, copy-paste-ready snippets demonstrating proper lifecycle management.
+Customize the avatar's position on the screen using predefined positions or custom styles. Also you can override the position using style properties.
 
-### React 18+ (Hooks)
-
-```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%" }} />;
-}
+```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",
+});
 ```
 
----
-
-### React 16/17 (Class Component)
+**Available Positions:**
 
-```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();
+- `"bottom-right"` (default)
+- `"bottom-left"`
+- `"bottom-center"`
+- `"top-right"`
+- `"top-left"`
+- `"top-center"`
+- `"center"`
 
-      // 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);
-    }
-  }
+## 4. Event Handling
 
-  componentWillUnmount() {
-    // Cleanup on unmount
-    this.widget?.destroy();
-  }
+The SDK provides several event callbacks for monitoring status and handling errors.
 
-  render() {
-    return (
-      <div ref={this.containerRef} style={{ width: "100%", height: "100%" }} />
-    );
-  }
-}
+```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),
+});
 ```
 
 ---
 
-### Vue 3
+## 5. API Reference
 
-```html
-<template>
-  <div ref="containerRef" style="width: 100%; height: 100%;"></div>
-</template>
+### 5.1 Core Methods
 
-<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;
+#### `init(token: string, config?: NapsterCompanionApiConfig): Promise<NapsterCompanionApiInstance>`
 
-  onMounted(async () => {
-    try {
-      // Fetch token from your backend
-      const response = await fetch("/api/get-napster-token", {
-        method: "POST",
-      });
-      const { token } = await response.json();
+Initialize the SDK with authentication token and configuration.
 
-      // 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>
+```typescript
+const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+  mountContainer: "#avatar-container",
+  position: "bottom-right",
+});
 ```
 
----
-
-### Vue 2
+#### `showAvatar(): void`
 
-```html
-<template>
-  <div ref="container" style="width: 100%; height: 100%;"></div>
-</template>
+Make the avatar visible on screen.
 
-<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>
+```typescript
+instance.showAvatar();
 ```
 
----
+#### `hideAvatar(): void`
 
-### Angular
+Hide the avatar from screen.
 
 ```typescript
-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();
-  }
-}
+instance.hideAvatar();
 ```
 
----
+#### `avatarIsVisible(): boolean`
 
-### Vanilla JS / Core (No Build Tools)
+Check if the avatar is currently visible.
 
-```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>
+```typescript
+if (instance.avatarIsVisible()) {
+  console.log("Avatar is visible");
+}
 ```
 
----
-
-## 6. Styling & Customization
-
-### CSS Import Path
+#### `destroy(): void`
 
-Always import the SDK's CSS file to ensure proper styling:
-
-**For Bundler Projects:**
+Cleanup and remove the SDK completely.
 
 ```typescript
-import "@touchcastllc/napster-companion-api/lib/index.css";
+instance.destroy();
 ```
 
-**For Browser Script Tags:**
-
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
-/>
-```
+### 5.2 Styling & Position Methods
 
-### Custom Container Styling
+#### `updateStyles(styles: StyleObject): void`
 
-You can customize the avatar container's size, position, and z-index:
+Update container styles dynamically.
 
 ```typescript
-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",
+instance.updateStyles({
+  top: "50px",
+  left: "50px",
+  opacity: "0.8",
 });
 ```
 
----
-
-## 7. Troubleshooting
-
-Common integration errors and their quick resolutions.
-
-### React Version Mismatch
-
-**Error:** `Error: Invalid hook call` or `React version mismatch`
-
-**Cause:** Using the wrong SDK entry point for your React version.
-
-**Solution:**
+#### `setPosition(position: Position): void`
 
-- For React 18+, use: `import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";`
-- For React 16/17, use: `import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api/legacy";`
+Change avatar position on screen.
 
-```bash
-# Check your React version
-npm list react
+```typescript
+instance.setPosition("top-left");
+// or using enum
+import { Position } from "@touchcastllc/napster-companion-api";
+instance.setPosition(Position.TOP_LEFT);
 ```
 
----
-
-### Missing CSS Styles
-
-**Error:** Widget appears unstyled or invisible
-
-**Cause:** CSS file not imported.
+#### `clearPosition(): void`
 
-**Solution:**
-
-Add the CSS import:
+Reset position to default/configured value.
 
 ```typescript
-import "@touchcastllc/napster-companion-api/lib/index.css";
-```
-
-For HTML script tags:
-
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
-/>
+instance.clearPosition();
 ```
 
----
-
-### CORS Errors
-
-**Error:** `Cross-Origin Request Blocked` when fetching token
+### 5.3 Feature Control Methods
 
-**Cause:** Making token generation API calls from the browser.
+#### `enableFeature(feature: string): void`
 
-**Solution:**
+Enable a specific feature.
 
-**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 });
-});
+```typescript
+instance.enableFeature("disclaimer");
 ```
 
-Then fetch from your backend in the client:
+#### `disableFeature(feature: string): void`
+
+Disable a specific feature.
 
 ```typescript
-const response = await fetch("/api/get-napster-token", { method: "POST" });
-const { token } = await response.json();
+instance.disableFeature("disclaimer");
 ```
 
----
-
-### Authentication / Token Issues
-
-**Error:** `401 Unauthorized` or `Invalid token`
+#### `isFeatureEnabled(feature: string): boolean`
 
-**Possible Causes:**
+Check if a feature is currently enabled.
 
-1. Token expired
-2. Invalid API key
-3. Incorrect companion ID
+```typescript
+if (instance.isFeatureEnabled("disclaimer")) {
+  console.log("Disclaimer is enabled");
+}
+```
 
-**Solution:**
+### 5.4 Communication Methods
 
-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:
+#### `sendCommand(command: { type: string; data?: object }): void`
 
----
+Send a command to the avatar via the data channel.
 
-### Widget Not Mounting
+```typescript
+// Send a message to the avatar
+instance.sendCommand({ type: "send_message", data: { text: "Hello, how are you?" } });
 
-**Error:** Container element not found or widget doesn't appear
+// Cancel the current response
+instance.sendCommand({ type: "cancel" });
+```
 
-**Possible Causes:**
+## 6. Configuration Interface
 
-1. Container element doesn't exist
-2. Invalid CSS selector
-3. Container rendered after initialization
+```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;
+  avatarStyle?: {
+    view: "round" | "rectangle" | "silhouette";
+    borderWidth?: string;
+    borderColor?: string;
+    borderStyle?: string;
+  };
 
-**Solution:**
+  // Features
+  features?: {
+    backgroundRemoval?: { enabled: boolean };
+    inactiveTimeout?: {
+      enabled: boolean;
+      duration?: number; // max: 180000ms
+      countdown?: number; // max: 60s
+    };
+    disclaimer?: { enabled: boolean; text?: string };
+    showSDKLoader?: { enabled: boolean; bgColor?: string };
+  };
 
-```typescript
-// ✅ Good: Wait for DOM element
-useEffect(() => {
-  const container = document.querySelector("#avatar-container");
-  if (container) {
-    NapsterCompanionApiSdk.init(token, {
-      mountContainer: container, // Use DOM element directly
-    });
-  }
-}, []);
+  // Configuration
+  debug?: boolean;
 
-// ❌ Bad: Container may not exist yet
-const widget = NapsterCompanionApiSdk.init(token, {
-  mountContainer: "#avatar-container",
-});
+  // 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;
+}
 ```
 
 ---
 
-### Module Not Found
-
-**Error:** `Cannot find module '@touchcastllc/napster-companion-api'`
+## 7. Troubleshooting
 
-**Cause:** Package not installed.
+### 7.1 Common Issues
 
+**Problem: "Module not found" Error**  
 **Solution:**
 
 ```bash
+# Ensure package is installed
 npm install @touchcastllc/napster-companion-api
-# or
-yarn add @touchcastllc/napster-companion-api
-```
 
----
-
-### Peer Dependency Warnings
+# Install peer dependencies
+npm install @reduxjs/toolkit
+```
 
-**Warning:** `ERESOLVE unable to resolve dependency tree`
+**Problem: Invalid or expired token**  
+**Solution:**
 
-**Cause:** Missing or incompatible peer dependencies.
+- Generate new token from backend API
+- Ensure token is passed correctly to `init()`
 
+**Problem: Avatar appears unstyled**  
 **Solution:**
 
-Install all required peer dependencies:
+See the style import guide from [1.2.1 Installation & Setup](#121-for-esm-build-type-recommended)
 
-```bash
-# For React 18+
-npm install react@^18 react-dom@^18 @reduxjs/toolkit@^2 react-redux@^9
+**Problem:** `mountContainer` element doesn't exist  
+**Solution:**
 
-# For React 16/17
-npm install react@^16 react-dom@^16 @reduxjs/toolkit@^2 react-redux@^8
+```typescript
+// Wait for DOM to load
+document.addEventListener("DOMContentLoaded", async () => {
+  const instance = await NapsterCompanionApiSdk.init(token, {
+    mountContainer: "#avatar-container", // Ensure element exists
+  });
+});
 ```
 
----
-
-### TypeScript Errors
-
-**Error:** `Cannot find type definitions`
+### 7.2 Debug Mode
 
-**Cause:** TypeScript can't locate type definitions.
+Enable debug logging:
 
-**Solution:**
+```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),
+});
+```
 
-The SDK includes TypeScript definitions. Ensure your `tsconfig.json` includes:
+### 7.3 Performance Issues
 
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  }
-}
-```
+#### Large Bundle Size
 
----
+- Use ESM build instead of standalone
+- Import only needed features
+- Enable tree-shaking in bundler
 
-## 📚 Additional Resources
+#### Memory Leaks
 
-- **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)
+```typescript
+// Always cleanup when done
+useEffect(() => {
+  return () => {
+    instance?.destroy();
+  };
+}, [instance]);
+```
 
 ---
 
-## 📝 License
+## License
 
-MIT License. See [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.