@touchcastllc/napster-companion-api-dev 1.0.0-alpha.43

package/README.md

@@ -0,0 +1,830 @@
+# Napster Companion API SDK
+
+[![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)
+
+> 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:**
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- React 16.x through 19.x
+- Vue 2.x and 3.x
+- Angular 12+
+- Vanilla JavaScript (no build tools required)
+
+**Key Capabilities:**
+
+- **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
+
+---
+
+## 1. Quick Start
+
+Get up and running in minutes. Follow these four steps to integrate the SDK into your project.
+
+### 1.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          |
+
+---
+
+### 1.2 Installation & Setup
+
+#### 1.2.1 For ESM Build Type (Recommended)
+
+**Step 1: Install the SDK**
+
+Install the package:
+
+```bash
+npm install @touchcastllc/napster-companion-api
+# or
+yarn add @touchcastllc/napster-companion-api
+```
+
+Install peer dependencies:
+
+```bash
+npm install @reduxjs/toolkit
+```
+
+**Step 2: Import the SDK**
+
+```typescript
+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:
+
+**ESM/TypeScript:**
+
+```typescript
+import "@touchcastllc/napster-companion-api/styles";
+```
+
+**CommonJS:**
+
+```js
+require("@touchcastllc/napster-companion-api/styles");
+```
+
+**HTML `<link>` Tag:**
+
+```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");
+```
+
+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
+<!-- All dependencies bundled (easier, larger file) -->
+<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
+```
+
+---
+
+### 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
+const widget = await NapsterCompanionApiSdk.init("YOUR_AUTH_TOKEN", {
+  mountContainer: "#avatar-container",
+});
+```
+
+#### 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>
+```
+
+**Step 2: Initialize globally**
+
+```html
+<script>
+  window.napsterCompanionApiSDK.init("AUTH_TOKEN", {
+    mountContainer: "#sdk-container",
+  });
+</script>
+```
+
+---
+
+### 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 Companion API Key
+
+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 Companion API to generate auth tokens:
+
+**Request URL:**
+
+```
+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 '{
+    "companionId": "YOUR_COMPANION_ID",
+    "providerConfig": {
+      "type": "azureOpenAI",
+      "voiceId": "alloy",
+      "settings": {
+        "instructions": "Your custom instructions here...",
+        "turnDetection": {
+          "threshold": 0,
+          "prefix_padding_ms": 0,
+          "silence_duration_ms": 0
+        },
+        "temperature": 0
+      },
+      "useGreenVideo": true
+    },
+    "disableIdleTimeout": false
+  }'
+```
+
+#### Step 3: Use Token in Client
+
+Fetch the token from your backend and pass it to the SDK:
+
+```typescript
+// Possible client-side code for token retrieval
+async function initializeAvatar() {
+  // Fetch token from your backend
+  const response = await fetch("/your-backend-endpoint", { method: "POST" });
+  const { token } = await response.json();
+}
+```
+
+---
+
+## 2. Examples
+
+We provide example implementations for popular frameworks and vanilla JavaScript:
+
+### 2.1 React
+
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
+import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
+
+export function CompanionWidget() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [instance, setInstance] = useState<NapsterCompanionApiInstance | null>(
+    null
+  );
+
+  useEffect(() => {
+    const initSDK = async () => {
+      if (!containerRef.current) return;
+
+      const result = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+        mountContainer: containerRef.current,
+        position: "bottom-right",
+      });
+      setInstance(result);
+    };
+
+    initSDK();
+
+    return () => {
+      instance?.destroy();
+    };
+  }, []);
+
+  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
+}
+```
+
+### 2.2 Vue 3
+
+```html
+<template>
+  <div ref="containerRef"></div>
+</template>
+
+<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";
+
+  const containerRef = ref<HTMLElement>();
+  let instance: NapsterCompanionApiInstance | null = null;
+
+  onMounted(async () => {
+    if (!containerRef.value) return;
+
+    instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+      mountContainer: containerRef.value,
+      position: "bottom-right",
+    });
+  });
+
+  onUnmounted(() => {
+    instance?.destroy();
+  });
+</script>
+```
+
+### 2.3 Angular
+
+```typescript
+import {
+  Component,
+  OnInit,
+  OnDestroy,
+  ElementRef,
+  ViewChild,
+} from "@angular/core";
+import {
+  NapsterCompanionApiSdk,
+  NapsterCompanionApiInstance,
+} from "@touchcastllc/napster-companion-api";
+
+@Component({
+  selector: "app-companion",
+  template: "<div #containerRef></div>",
+})
+export class CompanionComponent implements OnInit, OnDestroy {
+  @ViewChild("containerRef") containerRef!: ElementRef<HTMLDivElement>;
+  private instance: NapsterCompanionApiInstance | null = null;
+
+  async ngOnInit() {
+    this.instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+      mountContainer: this.containerRef.nativeElement,
+      position: "bottom-right",
+    });
+  }
+
+  ngOnDestroy() {
+    this.instance?.destroy();
+  }
+}
+```
+
+### 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",
+    })
+    .then(instance => {
+      // Control the avatar
+      instance.showAvatar();
+
+      // Hide after 10 seconds
+      setTimeout(() => instance.hideAvatar(), 10000);
+    });
+</script>
+```
+
+### 2.5 Advanced Configuration
+
+```typescript
+async function initAdvancedAvatar() {
+  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+    mountContainer: "#avatar-container",
+    position: "bottom-right",
+
+    avatarStyle: {
+      view: "round", // Options: "round" | "rectangle" | "silhouette"
+    },
+
+    features: {
+      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)",
+    },
+
+    onReady: () => console.log("Avatar ready!"),
+    onError: error => console.error("Error:", error),
+    onAvatarReady: ready => console.log("Avatar loaded:", ready),
+  });
+
+  return instance;
+}
+```
+
+### 2.6 Dynamic Feature Control
+
+```typescript
+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");
+  });
+
+  return instance;
+}
+```
+
+### 2.7 Custom Styling
+
+#### Inline 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)",
+  },
+});
+```
+
+#### CSS Classes
+
+```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);
+}
+```
+
+#### Dynamic Style Updates
+
+```typescript
+// Update styles after initialization
+instance.updateStyles({
+  opacity: "0.9",
+  transform: "scale(1.1)",
+  transition: "all 0.3s ease",
+});
+```
+
+### 2.8 Avatar Style Configuration
+
+Customize the avatar's visual appearance using the `avatarStyle` configuration. Control the avatar's view mode, and other visual properties.
+
+#### Avatar View Modes
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init(token, {
+  avatarStyle: {
+    view: "round", // Options: "round" | "rectangle" | "silhouette"
+  },
+});
+```
+
+**Available View Modes:**
+
+- `"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**)
+
+#### Avatar Style Example
+
+```typescript
+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)",
+  },
+});
+```
+
+---
+
+## 3. Feature Configuration
+
+### 3.1 Core Features
+
+#### Inactivity Timeout
+
+Automatically disconnect the avatar after a period of user inactivity. Users receive a countdown notification before disconnection.
+
+```typescript
+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
+
+Display a loading screen while the avatar assets are being loaded. Customize the background color to match your application's design.
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    showSDKLoader: {
+      enabled: true,
+      bgColor: "#ffffff", // Optional background color
+    },
+  },
+});
+```
+
+### 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.
+
+```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",
+});
+```
+
+**Available Positions:**
+
+- `"bottom-right"` (default)
+- `"bottom-left"`
+- `"bottom-center"`
+- `"top-right"`
+- `"top-left"`
+- `"top-center"`
+- `"center"`
+
+## 4. Event Handling
+
+The SDK provides several event callbacks for monitoring status and handling errors.
+
+```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),
+});
+```
+
+---
+
+## 5. API Reference
+
+### 5.1 Core Methods
+
+#### `init(token: string, config?: NapsterCompanionApiConfig): Promise<NapsterCompanionApiInstance>`
+
+Initialize the SDK with authentication token and configuration.
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
+  mountContainer: "#avatar-container",
+  position: "bottom-right",
+});
+```
+
+#### `showAvatar(): void`
+
+Make the avatar visible on screen.
+
+```typescript
+instance.showAvatar();
+```
+
+#### `hideAvatar(): void`
+
+Hide the avatar from screen.
+
+```typescript
+instance.hideAvatar();
+```
+
+#### `avatarIsVisible(): boolean`
+
+Check if the avatar is currently visible.
+
+```typescript
+if (instance.avatarIsVisible()) {
+  console.log("Avatar is visible");
+}
+```
+
+#### `destroy(): void`
+
+Cleanup and remove the SDK completely.
+
+```typescript
+instance.destroy();
+```
+
+### 5.2 Styling & Position Methods
+
+#### `updateStyles(styles: StyleObject): void`
+
+Update container styles dynamically.
+
+```typescript
+instance.updateStyles({
+  top: "50px",
+  left: "50px",
+  opacity: "0.8",
+});
+```
+
+#### `setPosition(position: Position): void`
+
+Change avatar position on screen.
+
+```typescript
+instance.setPosition("top-left");
+// or using enum
+import { Position } from "@touchcastllc/napster-companion-api";
+instance.setPosition(Position.TOP_LEFT);
+```
+
+#### `clearPosition(): void`
+
+Reset position to default/configured value.
+
+```typescript
+instance.clearPosition();
+```
+
+### 5.3 Feature Control Methods
+
+#### `enableFeature(feature: string): void`
+
+Enable a specific feature.
+
+```typescript
+instance.enableFeature("disclaimer");
+```
+
+#### `disableFeature(feature: string): void`
+
+Disable a specific feature.
+
+```typescript
+instance.disableFeature("disclaimer");
+```
+
+#### `isFeatureEnabled(feature: string): boolean`
+
+Check if a feature is currently enabled.
+
+```typescript
+if (instance.isFeatureEnabled("disclaimer")) {
+  console.log("Disclaimer is enabled");
+}
+```
+
+### 5.4 Communication Methods
+
+#### `sendCommand(command: { type: string; data?: object }): void`
+
+Send a command to the avatar via the data channel.
+
+```typescript
+// Send a message to the avatar
+instance.sendCommand({ type: "send_message", data: { text: "Hello, how are you?" } });
+
+// Cancel the current response
+instance.sendCommand({ type: "cancel" });
+```
+
+## 6. Configuration Interface
+
+```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;
+  };
+
+  // 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 };
+  };
+
+  // Configuration
+  debug?: boolean;
+
+  // 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;
+}
+```
+
+---
+
+## 7. Troubleshooting
+
+### 7.1 Common Issues
+
+**Problem: "Module not found" Error**  
+**Solution:**
+
+```bash
+# Ensure package is installed
+npm install @touchcastllc/napster-companion-api
+
+# Install peer dependencies
+npm install @reduxjs/toolkit
+```
+
+**Problem: Invalid or expired token**  
+**Solution:**
+
+- Generate new token from backend API
+- Ensure token is passed correctly to `init()`
+
+**Problem: Avatar appears unstyled**  
+**Solution:**
+
+See the style import guide from [1.2.1 Installation & Setup](#121-for-esm-build-type-recommended)
+
+**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
+  });
+});
+```
+
+### 7.2 Debug Mode
+
+Enable debug logging:
+
+```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),
+});
+```
+
+### 7.3 Performance Issues
+
+#### Large Bundle Size
+
+- Use ESM build instead of standalone
+- Import only needed features
+- Enable tree-shaking in bundler
+
+#### Memory Leaks
+
+```typescript
+// Always cleanup when done
+useEffect(() => {
+  return () => {
+    instance?.destroy();
+  };
+}, [instance]);
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.