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

package/lib/types/index.d.ts

@@ -0,0 +1,354 @@
+import type { AnalyticsConfig } from "./analytics";
+import { DataChannelMessageType } from "../constants/events";
+export * from "./errors";
+export * from "./analytics";
+export * from "./abstract-typing";
+/**
+ * Placement positions used to anchor the UI on screen.
+ * Use these values when passing `position` in the top-level config
+ * or when calling `setPosition` on the instance.
+ */
+export declare enum Position {
+    BOTTOM_RIGHT = "bottom-right",
+    BOTTOM_CENTER = "bottom-center",
+    BOTTOM_LEFT = "bottom-left",
+    TOP_RIGHT = "top-right",
+    TOP_CENTER = "top-center",
+    TOP_LEFT = "top-left",
+    CENTER = "center"
+}
+/**
+ * Function definition for AI companion function calling.
+ * Functions allow the AI companion to invoke external tools or actions
+ * during a conversation.
+ */
+export interface CompanionFunction {
+    /** Unique function name the AI can invoke. */
+    name: string;
+    /** Human-readable description of what the function does. */
+    description?: string;
+    /** JSON-Schema style parameter definitions. */
+    parameters?: Record<string, unknown>;
+}
+export interface SendMessageData {
+    /** The text message to send */
+    text: string;
+    /** The role of the message sender */
+    role: "user" | "system";
+    /** Whether to trigger an avatar response */
+    trigger_response: boolean;
+    /** Optional ID of the previous message in the conversation thread */
+    previous_item_id?: string;
+    /** Whether to delay the response (reserved for future use) */
+    delay?: boolean;
+}
+/**
+ * Data channel command types
+ */
+export type SendMessageCommand = {
+    type: DataChannelMessageType.SEND_MESSAGE;
+    data: SendMessageData;
+};
+export type CancelCommand = {
+    type: DataChannelMessageType.CANCEL;
+};
+export type SetSettingsCommand = {
+    type: DataChannelMessageType.SET_SETTINGS;
+    data: {
+        functions: CompanionFunction[];
+    };
+};
+export type StartVideoCommand = {
+    type: DataChannelMessageType.START_VIDEO;
+    data: null;
+};
+export type StopVideoCommand = {
+    type: DataChannelMessageType.STOP_VIDEO;
+    data: null;
+};
+export type DataChannelCommand = SendMessageCommand | CancelCommand | SetSettingsCommand | StartVideoCommand | StopVideoCommand;
+export declare const maxInactiveTimeoutDuration = 180000;
+export declare const defaultCountdownDuration = 30;
+export interface EventMessage {
+    event: string;
+    data?: {
+        state?: string;
+        message?: {
+            action?: string;
+            content?: string;
+            role?: string;
+        };
+        [key: string]: unknown;
+    };
+}
+/**
+ * Feature-specific configuration flags and optional parameters.
+ * Each feature contains its own small config object; toggle `enabled`
+ * to turn the feature on/off and provide small optional tuning values
+ * (for example `inactiveTimeout.duration`).
+ */
+export interface FeatureConfig {
+    /** Background removal feature. When enabled, the avatar background should be removed. */
+    backgroundRemoval?: {
+        enabled: boolean;
+    };
+    /** Waveform display settings shown during audio playback/recording. */
+    waveform?: {
+        enabled: boolean;
+        /** Optional CSS color value for the waveform. Defaults are applied by the SDK if omitted. */
+        color?: string;
+    };
+    /** Automatically hide or perform actions after a period of inactivity. */
+    inactiveTimeout?: {
+        enabled: boolean;
+        /** Duration in milliseconds used by the SDK when `enabled` is true
+         *
+         * Max: 180000ms
+         *
+         * Default: 180000ms
+         */
+        duration?: number;
+        /** Countdown duration before close connection in seconds, shown to users when inactive timeout is triggered
+         *
+         * Max: 60 seconds
+         *
+         * Default: 30 seconds
+         */
+        countdown?: number;
+    };
+    /** Small disclaimer shown to users, often used for legal text or usage hints. */
+    disclaimer?: {
+        enabled: boolean;
+        /** Optional text shown when the disclaimer is enabled. */
+        text?: string;
+        color?: string;
+    };
+    /** Loader overlay shown while the SDK/Avatar is loading. */
+    showSDKLoader?: {
+        enabled: boolean;
+        /** Optional background color for the loader overlay. */
+        bgColor?: string;
+        /** Optional color for the loader animation. */
+        color?: string;
+        /** Optional loader animation type. */
+        type?: "spinner" | "pulse";
+    };
+    /** Screen sharing feature. When enabled, users can share their screen during a session. */
+    screenShare?: {
+        enabled: boolean;
+    };
+    /** Face tracking feature. When enabled, opens the user's camera and runs
+     *  real-time face mesh detection via TensorFlow.js + MediaPipe. */
+    faceTracking?: {
+        enabled: boolean;
+        /** Detection rate in FPS. Default 15, max 30. */
+        fps?: number;
+        /** Mouth opening ratio threshold. Default 0.015. */
+        talkingThreshold?: number;
+    };
+}
+/**
+ * Configuration for the face tracking service.
+ */
+export interface FaceTrackingConfig {
+    /** Detection rate in frames per second. Default 15, max 30. */
+    fps?: number;
+    /** Mouth opening ratio threshold to determine talking state. Default 0.015. */
+    talkingThreshold?: number;
+    /** Number of frames for rolling average smoothing. Default 5. */
+    smoothingFrames?: number;
+    /** Camera video width. Default 640. */
+    videoWidth?: number;
+    /** Camera video height. Default 480. */
+    videoHeight?: number;
+}
+/**
+ * Normalized mouth landmark positions (0–1 range).
+ */
+export interface MouthLandmarks {
+    topLip: {
+        x: number;
+        y: number;
+    };
+    bottomLip: {
+        x: number;
+        y: number;
+    };
+    leftCorner: {
+        x: number;
+        y: number;
+    };
+    rightCorner: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Face tracking data emitted on each detection frame.
+ */
+export interface FaceTrackingData {
+    /** 468 normalized face landmarks (x, y, z in 0–1 range). */
+    landmarks: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /** Normalized mouth landmark positions, or null if not detected. */
+    mouthLandmarks: MouthLandmarks | null;
+    /** Whether the user is currently talking based on smoothed mouth-opening ratio. */
+    isTalking: boolean;
+}
+/**
+ * Controller returned by createFaceTrackingService for managing the detection lifecycle.
+ */
+export interface FaceTrackingController {
+    /** Initialize camera + model and start the detection loop. */
+    start(): Promise<void>;
+    /** Pause detection and stop camera, but keep the model loaded for fast restart. */
+    stop(): void;
+    /** Whether the detection loop is currently running. */
+    isActive(): boolean;
+    /** Full teardown: stop + dispose model + null all refs. */
+    destroy(): void;
+}
+export interface avatarStyleConfig {
+    /** Avatar visual style: "round" | "rectangle" | "silhouette" (Default: "round").
+     *
+     * Use "rectangle" when applying custom styling that requires a rectangular container.
+     */
+    view: "round" | "rectangle" | "silhouette";
+    /** Border width in pixels. */
+    borderWidth?: CSSStyleDeclaration["borderWidth"];
+    /** Border color as a CSS color string. */
+    borderColor?: CSSStyleDeclaration["borderColor"];
+    /** Border style as a CSS border-style string (e.g., "solid", "dashed"). */
+    borderStyle?: CSSStyleDeclaration["borderStyle"];
+}
+/**
+ * CSS style object that works with vanilla JS.
+ * Compatible with CSSStyleDeclaration.
+ * Allows both string and number values for CSS properties.
+ */
+export type StyleObject = Partial<CSSStyleDeclaration>;
+/**
+ * Main configuration object passed to `init(token, config)`.
+ * All fields are optional; sensible defaults are used by the SDK.
+ */
+export interface NapsterCompanionApiConfig {
+    /** Position of the avatar on screen. See `Position` enum. */
+    position?: Position;
+    /** CSS class name(s) to add to the SDK root container. Useful for theming. */
+    className?: string;
+    /** Inline style object applied to the SDK root container. It supports only vanilla JS style objects. */
+    style?: StyleObject;
+    /** Avatar visual style configuration. */
+    avatarStyle?: avatarStyleConfig;
+    /** Per-feature configuration object to toggle features and set options. */
+    features?: FeatureConfig;
+    /**
+     * Mount target for the SDK. Provide an actual HTMLElement or a selector
+     * string; defaults to `document.body` when omitted.
+     */
+    mountContainer?: HTMLElement | string | null;
+    /**
+     * AI companion function definitions for function calling support.
+     * These functions are sent to the server when the connection is established,
+     * allowing the AI to invoke them during conversation.
+     */
+    functions?: CompanionFunction[];
+    /** Enable debug logging throughout the SDK. When enabled, detailed logs will be output to the console. */
+    debug?: boolean;
+    /** Analytics configuration controls analytics delivery and tracking. */
+    analytics?: AnalyticsConfig;
+    /** Lifecycle callbacks. All are optional. */
+    /** Called when the SDK has finished initialization and is ready to render. */
+    onReady?: () => void;
+    /** Called when a runtime or network error occurs; receives the Error. */
+    onError?: (error: Error) => void;
+    /** Called when arbitrary data arrives over the SDK's socket/connection. */
+    onData?: (data: EventMessage) => void;
+    /** Called when the visual avatar is fully prepared and rendered. */
+    onAvatarReady?: (isReady?: boolean) => void;
+    /** Called when the avatar inactivity status changes; receives the new status. */
+    onInactivityStatusChange?: (isInactive: boolean) => void;
+    /** Called when the SDK is destroyed via the public API. */
+    onDestroy?: () => void;
+    /** Called whenever feature configuration is changed at runtime. */
+    onFeaturesUpdate?: (features: FeatureConfig) => void;
+    /** Called on each face tracking detection frame with face data (or null if no face detected). */
+    onFaceTrackingData?: (data: FaceTrackingData | null) => void;
+    /** Called when the screen share state changes (started or stopped). */
+    onScreenShareStateChange?: (isSharing: boolean) => void;
+    /** Called when a face tracking error occurs (camera denied, model load failure, etc.). */
+    onFaceTrackingError?: (error: Error) => void;
+}
+/**
+ * Public instance returned by `init`. Use these methods to control the
+ * running SDK after initialization.
+ */
+export interface NapsterCompanionApiInstance {
+    /** Show the Avatar in screen (if hidden). */
+    showAvatar: () => void;
+    /** Hide the Avatar from screen. */
+    hideAvatar: () => void;
+    /** Check whether the Avatar is currently visible on screen. */
+    avatarIsVisible: () => boolean;
+    /** Tear down the SDK, remove DOM nodes and clean up resources. */
+    destroy: () => void;
+    /** Update the inline style object applied to the SDK root container. */
+    updateStyles: (styles: NapsterCompanionApiConfig["style"]) => void;
+    /** Set the position of the SDK on screen (see `Position`). */
+    setPosition: (position: Position) => void;
+    /** Clear any programmatic position and revert to the configured/default position. */
+    clearPosition: () => void;
+    /** Update avatar style configuration (e.g., view: round/silhouette/rectangle). */
+    updateAvatarStyle: (newAvatarStyle: Partial<NonNullable<NapsterCompanionApiConfig["avatarStyle"]>>) => void;
+    /** Enable a named feature (one of the keys from `FeatureConfig`).
+     *
+     * e.g. `enableFeature("disclaimer")`
+     */
+    enableFeature: (feature: keyof FeatureConfig) => void;
+    /** Disable a named feature (one of the keys from `FeatureConfig`).
+     *
+     * e.g. `disableFeature("disclaimer")`
+     */
+    disableFeature: (feature: keyof FeatureConfig) => void;
+    /**
+     * Update a single feature's configuration. `config` may be partial; only the
+     * supplied keys will be changed.
+     *
+     * e.g. to change only the disclaimer text:
+     *
+     * `updateFeatureConfig("disclaimer", { text: "New disclaimer text" })`
+     */
+    updateFeatureConfig: (feature: keyof FeatureConfig, config: NonNullable<FeatureConfig[keyof FeatureConfig]>) => void;
+    /** Send a command to the avatar via the data channel. */
+    sendCommand: (command: DataChannelCommand) => void;
+    /** Start screen sharing. Captures the user's screen and sends frames to the avatar. */
+    startScreenShare: () => Promise<void>;
+    /** Stop screen sharing. */
+    stopScreenShare: () => void;
+    /** Toggle screen sharing on/off. */
+    toggleScreenShare: () => Promise<void>;
+    /** Whether screen sharing is currently active. */
+    readonly isScreenSharing: boolean;
+    /** Whether screen sharing is supported by the browser and enabled in config. */
+    readonly isScreenShareSupported: boolean;
+    /** Start face tracking (opens camera, loads model, begins detection loop). */
+    startFaceTracking: () => Promise<void>;
+    /** Stop face tracking (pauses detection, stops camera; model stays loaded for fast restart). */
+    stopFaceTracking: () => void;
+}
+/**
+ * Top-level SDK object exposed by the package. Call `init(token, config)` to
+ * bootstrap the SDK and receive a `NapsterCompanionApiInstance` for runtime control.
+ */
+export interface NapsterCompanionApiSDK {
+    /**
+     * Initialize the SDK using the provided connection token and optional config.
+     * Returns a Promise that resolves to a controllable `NapsterCompanionApiInstance`.
+     */
+    init(token: string, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
+    /** The SDK version string (useful for diagnostics). */
+    version: string;
+}

package/lib/umd.d.ts

@@ -0,0 +1 @@
+export { default } from "./index";

package/lib/utils/InactiveOverlayManager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Types of triggers that can show the inactive overlay
+ */
+export declare enum InactiveOverlayTriggerType {
+    /** Local SDK timeout based on user inactivity */
+    LOCAL_TIMEOUT = "local_timeout",
+    /** Server-side warning about avatar disconnection */
+    SERVER_WARNING = "server_warning"
+}
+/**
+ * Configuration for showing the inactive overlay
+ */
+export interface InactiveOverlayTrigger {
+    /** Type of trigger that initiated the overlay */
+    type: InactiveOverlayTriggerType;
+    /** Duration in seconds for the countdown */
+    duration: number;
+    /** Optional custom message to display */
+    message?: string;
+    /** Whether user interaction is needed to continue */
+    isInteractionNeeded: boolean;
+}
+/**
+ * Callbacks for overlay lifecycle events
+ */
+export interface InactiveOverlayCallbacks {
+    /** Called when user clicks "Continue" */
+    onContinue?: () => void;
+    /** Called when countdown ends */
+    onEnd?: () => void;
+    /** Called when overlay is shown */
+    onShow?: (trigger: InactiveOverlayTrigger) => void;
+    /** Called when overlay is hidden */
+    onHide?: () => void;
+}
+/**
+ * Manager class that handles all inactive overlay logic
+ * Follows Single Responsibility Principle - only manages overlay state and lifecycle
+ */
+export declare class InactiveOverlayManager {
+    private overlayController;
+    private currentTrigger;
+    private isVisible;
+    private readonly mountElement;
+    private readonly callbacks;
+    constructor(mountElement: HTMLElement, callbacks?: InactiveOverlayCallbacks);
+    /**
+     * Show the inactive overlay with the given trigger configuration
+     * This is the single entry point for showing the overlay
+     */
+    show(trigger: InactiveOverlayTrigger): void;
+    /**
+     * Hide the inactive overlay
+     * This is the single entry point for hiding the overlay
+     */
+    hide(): void;
+    /**
+     * Check if overlay is currently visible
+     */
+    isShowing(): boolean;
+    /**
+     * Get the current trigger type if overlay is visible
+     */
+    getCurrentTrigger(): InactiveOverlayTrigger | null;
+    /**
+     * Handle continue button click
+     */
+    private handleContinue;
+    /**
+     * Handle countdown end
+     */
+    private handleEnd;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}

package/lib/utils/MediaCapture.d.ts

@@ -0,0 +1,13 @@
+export declare class MediaCapture {
+    private video;
+    private canvas;
+    private ctx;
+    private worker;
+    private interval;
+    constructor(interval?: number);
+    private initWorker;
+    private drawFrame;
+    getCanvas(): HTMLCanvasElement;
+    setStream(stream: MediaStream | null): void;
+    terminate(): void;
+}

package/lib/utils/classnames.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Utility for building CSS class names programmatically
+ */
+type ClassValue = string | number | boolean | undefined | null;
+type ClassArray = ClassValue[];
+type ClassObject = Record<string, boolean | undefined | null>;
+type ClassInput = ClassValue | ClassArray | ClassObject;
+/**
+ * Combines multiple class names into a single string
+ * Supports: strings, arrays, objects with boolean values
+ *
+ * @example
+ * cn('foo', 'bar') // 'foo bar'
+ * cn(['foo', 'bar']) // 'foo bar'
+ * cn({ foo: true, bar: false }) // 'foo'
+ * cn('foo', ['bar', 'baz'], { qux: true }) // 'foo bar baz qux'
+ */
+export declare function cn(...inputs: ClassInput[]): string;
+/**
+ * Common CSS class name constants for the WaveForm component
+ */
+export declare const WaveFormClasses: {
+    readonly icon: "np_companion-action-btn-container-icon";
+    readonly persistFillColor: "np_companion-persist-fill-color";
+    readonly alignMiddle: "np_companion-align-middle";
+    readonly alignBetween: "np_companion-align-between";
+    readonly darkGreyBg: "np_companion-dark-grey-bg";
+    readonly callEnd: "np_companion-action-btn-container-call-end";
+    readonly container: "np_companion-action-btn-container-container";
+    readonly wrapper: "np_companion-action-btn-container-wrapper";
+    readonly canvas: "np_companion-action-btn-container-canvas";
+    readonly controls: "np_companion-action-btn-container-controls";
+    readonly left: "np_companion-action-btn-container-left";
+    readonly middle: "np_companion-action-btn-container-middle";
+    readonly right: "np_companion-action-btn-container-right";
+    readonly wave: "np_companion-action-btn-container-wave";
+    readonly stop: "np_companion-action-btn-container-stop";
+    readonly questionBar: "np_companion-chat-question-bar-container";
+    readonly talking: "np_companion-talking";
+    readonly muted: "muted";
+    readonly hidden: "np_companion-hidden";
+    readonly expanded: "np_companion-action-btn-container-expanded";
+    readonly collapse: "np_companion-action-btn-container-collapse";
+    readonly mobileMode: "np_companion-mobile-mode";
+    readonly displayNone: "np_companion__d-none";
+    readonly iconButton: () => string;
+    readonly iconButtonEnd: () => string;
+    readonly iconButtonWithState: (isMuted: boolean) => string;
+};
+export {};

package/lib/utils/debug.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Log levels for different types of debug output
+ */
+export declare enum LogLevel {
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error",
+    DEBUG = "debug"
+}
+/**
+ * Debug logger class that checks the Redux store for debug mode
+ */
+declare class DebugLogger {
+    private prefix;
+    /**
+     * Check if debug mode is currently enabled
+     */
+    private isDebugEnabled;
+    /**
+     * Generic log method that checks debug mode
+     */
+    private log;
+    /**
+     * Log general information
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log debug information
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log warning information
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log error information
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Log warnings - these are shown regardless of debug mode
+     */
+    critical_warn(...args: unknown[]): void;
+    /**
+     * Log errors - these are shown regardless of debug mode
+     */
+    critical_error(...args: unknown[]): void;
+    /**
+     * Log WebRTC-related debug information
+     */
+    webrtc(...args: unknown[]): void;
+    /**
+     * Log Avatar-related debug information
+     */
+    avatar(...args: unknown[]): void;
+    /**
+     * Log connection-related debug information
+     */
+    connection(...args: unknown[]): void;
+    /**
+     * Log features-related debug information
+     */
+    features(...args: unknown[]): void;
+    /**
+     * Log data/messaging-related debug information
+     */
+    data(...args: unknown[]): void;
+    /**
+     * Log timeout/timer-related debug information
+     */
+    timer(...args: unknown[]): void;
+    /**
+     * Log cleanup-related debug information
+     */
+    cleanup(...args: unknown[]): void;
+}
+/**
+ * Global debug logger instance
+ */
+export declare const debugLogger: DebugLogger;
+/**
+ * Convenience export for common usage
+ */
+export declare const debug: DebugLogger;
+export {};

package/lib/utils/domFactory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Factory for creating DOM elements with consistent configuration
+ */
+export declare class DOMFactory {
+    /**
+     * Create a generic HTML element with optional configuration
+     */
+    static createElement<K extends keyof HTMLElementTagNameMap>(tag: K, options?: {
+        className?: string;
+        id?: string;
+        attributes?: Record<string, string>;
+        styles?: Partial<CSSStyleDeclaration>;
+    }): HTMLElementTagNameMap[K];
+    /**
+     * Create a video element with common configuration
+     */
+    static createVideo(options: {
+        className?: string;
+        autoplay?: boolean;
+        muted?: boolean;
+        loop?: boolean;
+        playsInline?: boolean;
+        crossOrigin?: string;
+        poster?: string;
+        src?: string;
+    }): HTMLVideoElement;
+    /**
+     * Create an audio element with common configuration
+     */
+    static createAudio(options: {
+        className?: string;
+        autoplay?: boolean;
+    }): HTMLAudioElement;
+    /**
+     * Create a canvas element with dimensions
+     */
+    static createCanvas(options: {
+        className?: string;
+        width?: number;
+        height?: number;
+        styles?: Partial<CSSStyleDeclaration>;
+    }): HTMLCanvasElement;
+    /**
+     * Create a button element with content
+     */
+    static createButton(options: {
+        className?: string;
+        textContent?: string;
+        attributes?: Record<string, string>;
+        onClick?: () => void;
+    }): HTMLButtonElement;
+    /**
+     * Create a div element (most common case)
+     */
+    static createDiv(className?: string): HTMLDivElement;
+}

package/lib/utils/greenscreen/GreenScreenProcessor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Processor for removing green screen background from video frames
+ */
+export declare class GreenScreenProcessor {
+    /**
+     * Process image data to remove green screen and reduce green spill
+     */
+    static process(imageData: ImageData): ImageData;
+    /**
+     * Check if the image contains any green screen pixels
+     */
+    private static hasGreenScreen;
+    /**
+     * Check if a pixel matches green screen color range
+     */
+    private static isGreenPixel;
+    /**
+     * Remove green screen and reduce green spill from image data
+     */
+    private static removeGreenScreen;
+    /**
+     * Reduce green color spill on edges of foreground objects
+     */
+    private static reduceGreenSpill;
+}

package/lib/utils/greenscreen/index.d.ts

@@ -0,0 +1 @@
+export * from "./GreenScreenProcessor";