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

package/lib/services/analytics.d.ts

@@ -0,0 +1,148 @@
+import type { AnalyticsConfig } from "../types/analytics";
+/**
+ * Analytics service class
+ */
+export declare class AnalyticsService {
+    private config;
+    private eventQueue;
+    private performanceQueue;
+    private errorQueue;
+    private flushTimer?;
+    private sessionId;
+    private providers;
+    constructor(config?: Partial<AnalyticsConfig>);
+    /**
+     * Setup analytics providers from configuration
+     */
+    private setupProviders;
+    /**
+     * Generate a unique session ID
+     */
+    private generateSessionId;
+    /**
+     * Start the flush timer for batched sending
+     */
+    private startFlushTimer;
+    /**
+     * Setup automatic error tracking
+     */
+    private setupErrorTracking;
+    /**
+     * Setup performance tracking
+     */
+    private setupPerformanceTracking;
+    /**
+     * Track an analytics event
+     */
+    trackEvent(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a performance metric
+     */
+    trackPerformance(name: string, value: number, unit: "ms" | "bytes" | "count" | "percentage", context?: Record<string, unknown>): void;
+    /**
+     * Track an error
+     */
+    trackError(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Track user interaction
+     */
+    trackInteraction(action: string, target?: string, properties?: Record<string, unknown>): void;
+    /**
+     * Flush all queued data
+     */
+    flush(): void;
+    /**
+     * Flush events queue
+     */
+    private flushEvents;
+    /**
+     * Flush performance queue
+     */
+    private flushPerformance;
+    /**
+     * Flush errors queue
+     */
+    private flushErrors;
+    /**
+     * Send data to analytics endpoint
+     */
+    private sendData;
+    /**
+     * Send data to a specific analytics provider
+     */
+    private sendToProvider;
+    /**
+     * Send to custom endpoint (backward compatible)
+     */
+    private sendToCustomEndpoint;
+    /**
+     * Provider-specific send methods
+     */
+    private sendToGA4;
+    private sendToMixpanel;
+    private sendToSegment;
+    private sendToAmplitude;
+    private sendToPostHog;
+    private sendToAzureInsights;
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: Partial<AnalyticsConfig>): void;
+    /**
+     * Destroy the analytics service
+     */
+    destroy(): void;
+}
+/**
+ * Initialize analytics service
+ *
+ * @example
+ * // Single provider configuration
+ * const analytics = initializeAnalytics({
+ *   enabled: true,
+ *   provider: {
+ *     type: 'google-analytics-4',
+ *     measurementId: 'G-XXXXXXXXXX',
+ *     apiKey: 'your-api-secret'
+ *   }
+ * });
+ *
+ * @example
+ * // Multiple providers configuration
+ * const analytics = initializeAnalytics({
+ *   enabled: true,
+ *   providers: [
+ *     {
+ *       type: 'google-analytics-4',
+ *       measurementId: 'G-XXXXXXXXXX',
+ *       apiKey: 'your-api-secret'
+ *     },
+ *     {
+ *       type: 'mixpanel',
+ *       projectToken: 'your-mixpanel-token'
+ *     }
+ *   ]
+ * });
+ *
+ * @example
+ * // Backward compatible legacy configuration
+ * const analytics = initializeAnalytics({
+ *   enabled: true,
+ *   endpoint: 'https://your-api.com/analytics',
+ *   apiKey: 'your-api-key'
+ * });
+ */
+export declare function initializeAnalytics(config: Partial<AnalyticsConfig>): AnalyticsService;
+/**
+ * Get the global analytics instance
+ */
+export declare function getAnalytics(): AnalyticsService | null;
+/**
+ * Convenience functions for common tracking
+ */
+export declare const analytics: {
+    track: (name: string, properties?: Record<string, unknown>) => void;
+    performance: (name: string, value: number, unit: "ms" | "bytes" | "count" | "percentage", context?: Record<string, unknown>) => void;
+    error: (error: Error, context?: Record<string, unknown>) => void;
+    interaction: (action: string, target?: string, properties?: Record<string, unknown>) => void;
+};

package/lib/services/faceTracking.d.ts

@@ -0,0 +1,13 @@
+import type { FaceTrackingConfig, FaceTrackingData, FaceTrackingController } from "../types";
+interface FaceTrackingCallbacks {
+    onData?: (data: FaceTrackingData | null) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Creates a vanilla-JS face tracking service using TensorFlow.js + MediaPipe Face Mesh.
+ *
+ * Lazy-loads @tensorflow/tfjs and @tensorflow-models/face-landmarks-detection
+ * only when start() is called, keeping the main bundle small (~2MB deferred).
+ */
+export declare function createFaceTrackingService(config?: FaceTrackingConfig, callbacks?: FaceTrackingCallbacks): FaceTrackingController;
+export {};

package/lib/services/screenShare.d.ts

@@ -0,0 +1,15 @@
+import { MediaCapture } from "../utils/MediaCapture";
+export interface ScreenShareController {
+    start: () => Promise<void>;
+    stop: () => void;
+    toggle: () => Promise<void>;
+    isSharing: () => boolean;
+    isSupported: () => boolean;
+    getCapture: () => MediaCapture;
+    destroy: () => void;
+}
+export declare function checkScreenShareSupport(): boolean;
+export interface ScreenShareControllerOptions {
+    onStateChange?: (isSharing: boolean) => void;
+}
+export declare function createScreenShareController(options?: ScreenShareControllerOptions): ScreenShareController;

package/lib/services/webrtc.d.ts

@@ -0,0 +1,29 @@
+import { type EventMessage, type CompanionFunction } from "../types";
+import type { MediaCapture } from "../utils/MediaCapture";
+export interface WebRTCController {
+    startWithToken: (token: string) => Promise<void>;
+    close: () => void;
+    forceReconnect: () => Promise<void>;
+    getConnectionStatus: () => string;
+    getReconnectAttempts: () => number;
+    getError: () => Error | null;
+    updateAudioDevice: (deviceId: string) => Promise<void>;
+}
+interface WebRTCParams {
+    currentAudioDeviceId?: string;
+    functions?: CompanionFunction[];
+    screenShareCapture?: MediaCapture | null;
+    onChatMessage?: (data: EventMessage) => void;
+    onConnectionSuccess?: () => void;
+    onConnectionError?: (error: Error) => void;
+    onStreams?: (streams: {
+        videoStream?: MediaStream | null;
+        audioStream?: MediaStream | null;
+        userMicrophoneStream?: MediaStream | null;
+    }) => void;
+    onDataChannel?: (dc: RTCDataChannel) => void;
+    maxReconnectAttempts?: number;
+    reconnectInterval?: number;
+}
+export declare function createWebRTCController(params?: WebRTCParams): WebRTCController;
+export {};

package/lib/setupTests.d.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom";

package/lib/stores/index.d.ts

@@ -0,0 +1,8 @@
+export { store } from "./store";
+export type { RootState, AppDispatch } from "./store";
+export { setOnFeaturesUpdateCallback } from "./middleware/featuresUpdateMiddleware";
+export * from "./selectors";
+export { setSessionId, setAvatarReady, setDataChannel, setAvatarId, setVideoId, setStopInteraction, setMuted, addTranscript, setCustomVoiceId, setDefaultVoiceId, setConnectionToken, setCloseConnectionHandler, avatarReducer, } from "./slices/avatarSlice";
+export type { WebRTCStatus, AvatarState, Transcript, } from "./slices/avatarSlice";
+export { appReducer, setFeatures, resetFeatures, setPosition, setShowExperience, setDebugMode, } from "./slices/appSlice";
+export type { AppState } from "./slices/appSlice";

package/lib/stores/middleware/featuresUpdateMiddleware.d.ts

@@ -0,0 +1,4 @@
+import type { Middleware } from "@reduxjs/toolkit";
+import type { FeatureConfig } from "../../types";
+export declare const setOnFeaturesUpdateCallback: (callback: ((features: FeatureConfig) => void) | null) => void;
+export declare const featuresUpdateMiddleware: Middleware;

package/lib/stores/selectors.d.ts

@@ -0,0 +1,30 @@
+import { RootState } from "./index";
+import { FeatureConfig, Position } from "../types";
+import { Transcript } from "./slices/avatarSlice";
+/**
+ * Avatar state selectors
+ */
+export declare const selectSessionId: (state: RootState) => string | undefined;
+export declare const selectAvatarReady: (state: RootState) => boolean;
+export declare const selectDataChannel: (state: RootState) => RTCDataChannel | null;
+export declare const selectAvatarId: (state: RootState) => string | undefined;
+export declare const selectVideoId: (state: RootState) => string | undefined;
+export declare const selectMuted: (state: RootState) => boolean;
+export declare const selectTranscript: (state: RootState) => Transcript | undefined;
+export declare const selectCustomVoiceId: (state: RootState) => string | undefined;
+export declare const selectDefaultVoiceId: (state: RootState) => string | undefined;
+export declare const selectConnectionToken: (state: RootState) => string | undefined;
+export declare const selectCompanionId: (state: RootState) => string | undefined;
+export declare const selectStopInteraction: (state: RootState) => boolean;
+export declare const selectCloseConnectionHandler: (state: RootState) => (() => void) | undefined;
+/**
+ * App state selectors
+ */
+export declare const selectFeatures: (state: RootState) => FeatureConfig;
+export declare const selectPosition: (state: RootState) => Position | undefined;
+export declare const selectShowExperience: (state: RootState) => boolean;
+/**
+ * Composite selectors
+ */
+export declare const selectIsConnected: (state: RootState) => boolean;
+export declare const selectCanSendMessage: (state: RootState) => boolean;

package/lib/stores/slices/appSlice.d.ts

@@ -0,0 +1,12 @@
+import { Position, FeatureConfig } from "../../types";
+export interface AppState {
+    features: FeatureConfig;
+    position?: Position;
+    showExperience: boolean;
+    debugMode?: boolean;
+}
+export declare const setFeatures: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    feature: keyof FeatureConfig;
+    config: FeatureConfig[keyof FeatureConfig];
+}, "app/setFeatures">, resetFeatures: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"app/resetFeatures">, setPosition: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<Position | undefined, "app/setPosition">, setShowExperience: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "app/setShowExperience">, setDebugMode: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<boolean | undefined, "app/setDebugMode">;
+export declare const appReducer: import("redux").Reducer<AppState>;

package/lib/stores/slices/avatarSlice.d.ts

@@ -0,0 +1,26 @@
+export interface WebRTCStatus {
+    blocked: boolean;
+    reason: string;
+    message: string;
+}
+export interface Transcript {
+    role: string;
+    content: string;
+}
+export interface AvatarState {
+    sessionId?: string;
+    avatarReady: boolean;
+    dataChannel: RTCDataChannel | null;
+    avatarId?: string;
+    videoId?: string;
+    stopInteraction: boolean;
+    muted: boolean;
+    transcript?: Transcript;
+    customVoiceId: string | undefined;
+    defaultVoiceId: string | undefined;
+    connectionToken?: string;
+    companionId?: string;
+    closeConnectionHandler?: () => void;
+}
+export declare const setSessionId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setSessionId">, setAvatarReady: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAvatarReady">, setDataChannel: import("@reduxjs/toolkit").ActionCreatorWithPayload<RTCDataChannel | null, "avatar/setDataChannel">, setAvatarId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setAvatarId">, setVideoId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setVideoId">, setStopInteraction: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setStopInteraction">, setMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMuted">, addTranscript: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<Transcript | undefined, "avatar/addTranscript">, setCustomVoiceId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setCustomVoiceId">, setDefaultVoiceId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setDefaultVoiceId">, setConnectionToken: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setConnectionToken">, setCloseConnectionHandler: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<(() => void) | undefined, "avatar/setCloseConnectionHandler">;
+export declare const avatarReducer: import("redux").Reducer<AvatarState>;

package/lib/stores/store.d.ts

@@ -0,0 +1,11 @@
+export declare const store: import("@reduxjs/toolkit").EnhancedStore<{
+    avatar: import(".").AvatarState;
+    app: import(".").AppState;
+}, import("redux").UnknownAction, import("@reduxjs/toolkit").Tuple<[import("redux").StoreEnhancer<{
+    dispatch: import("redux-thunk").ThunkDispatch<{
+        avatar: import(".").AvatarState;
+        app: import(".").AppState;
+    }, undefined, import("redux").UnknownAction>;
+}>, import("redux").StoreEnhancer]>>;
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;

package/lib/types/abstract-typing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Base controller interface for all component controllers
+ */
+export interface BaseController<TOptions = unknown> {
+    /**
+     * Update controller with new options
+     */
+    update(options: Partial<TOptions>): void;
+    /**
+     * Destroy controller and clean up resources
+     */
+    destroy(silent?: boolean): void;
+}
+/**
+ * Extended controller interface with lifecycle hooks
+ */
+export interface LifecycleController<TOptions = unknown> extends BaseController<TOptions> {
+    /**
+     * Initialize controller (called after construction)
+     */
+    initialize?(): void;
+    /**
+     * Hook called before destroy
+     */
+    beforeDestroy?(): void;
+}
+/**
+ * Controller with render capabilities
+ */
+export interface RenderController<TOptions = unknown> extends LifecycleController<TOptions> {
+    /**
+     * Render or re-render the component
+     */
+    render(): void;
+}

package/lib/types/analytics.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Analytics and monitoring service for SDK usage tracking
+ */
+export interface AnalyticsEvent {
+    /** Name of the analytics event */
+    name: string;
+    /** Properties associated with the event */
+    properties?: Record<string, unknown>;
+    /** Timestamp of the event */
+    timestamp?: number;
+    /** User identifier */
+    userId?: string;
+    /** Session identifier */
+    sessionId?: string;
+}
+/**
+ * Supported analytics providers
+ */
+export type AnalyticsProvider = "custom" | "google-analytics-4" | "mixpanel" | "segment" | "amplitude" | "posthog" | "azure-insights";
+/**
+ * Analytics provider configuration
+ */
+export interface ProviderConfig {
+    /** Type of analytics provider */
+    type: AnalyticsProvider;
+    /** Measurement ID for Google Analytics 4 */
+    measurementId?: string;
+    /** Project token for Mixpanel */
+    projectToken?: string;
+    /** Write key for Segment */
+    writeKey?: string;
+    /** Generic API key */
+    apiKey?: string;
+    /** Custom endpoint */
+    endpoint?: string;
+    /** Regional endpoint */
+    region?: string;
+}
+/**
+ * Performance metric data structure
+ */
+export interface PerformanceMetric {
+    /** Name of the performance metric */
+    name: string;
+    /** Value of the metric */
+    value: number;
+    /** Unit of the metric value */
+    unit: "ms" | "bytes" | "count" | "percentage";
+    /** Timestamp of the metric */
+    timestamp?: number;
+    /** Additional context for the metric */
+    context?: Record<string, unknown>;
+}
+/**
+ * Error event data structure
+ */
+export interface ErrorEvent {
+    /** Error object */
+    error: Error;
+    /** Additional context for the error */
+    context?: Record<string, unknown>;
+    /** Timestamp of the error event */
+    timestamp?: number;
+    /** User identifier */
+    userId?: string;
+    /** Session identifier */
+    sessionId?: string;
+    /** Stack trace of the error */
+    stack?: string;
+}
+/**
+ * Analytics configuration options
+ */
+export interface AnalyticsConfig {
+    /** Enable or disable analytics tracking */
+    enabled: boolean;
+    /** Analytics service provider configuration */
+    provider?: ProviderConfig;
+    /** Support multiple analytics service providers */
+    providers?: ProviderConfig[];
+    /** Unique user identifier for tracking purposes */
+    userId?: string;
+    /** Unique session identifier for tracking purposes */
+    sessionId?: string;
+    /** Batch size for sending analytics events */
+    batchSize?: number;
+    /** Interval in milliseconds for flushing analytics data */
+    flushInterval?: number;
+    /** Enable or disable performance tracking */
+    enablePerformanceTracking?: boolean;
+    /** Enable or disable error tracking */
+    enableErrorTracking?: boolean;
+    /** Enable or disable user interaction tracking */
+    enableUserInteractionTracking?: boolean;
+}

package/lib/types/errors.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Base error class for all SDK errors
+ */
+export declare class SDKError extends Error {
+    readonly code: string;
+    readonly timestamp: Date;
+    context?: Record<string, unknown>;
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+    /**
+     * Serializes the error for logging or transmission
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        timestamp: string;
+        context: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Initialization related errors
+ */
+export declare class InitializationError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Token related errors
+ */
+export declare class TokenError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * React version compatibility errors
+ */
+export declare class ReactVersionError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Connection related errors
+ */
+export declare class ConnectionError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * WebRTC related errors
+ */
+export declare class WebRTCError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * API related errors
+ */
+export declare class APIError extends SDKError {
+    readonly status?: number;
+    readonly response?: unknown;
+    constructor(message: string, status?: number, response?: unknown, context?: Record<string, unknown>);
+    toJSON(): {
+        status: number | undefined;
+        response: unknown;
+        name: string;
+        message: string;
+        code: string;
+        timestamp: string;
+        context: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Configuration related errors
+ */
+export declare class ConfigurationError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Feature related errors
+ */
+export declare class FeatureError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Media related errors (video, audio)
+ */
+export declare class MediaError extends SDKError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Face tracking related errors
+ */
+export declare class FaceTrackingError extends SDKError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Error codes enum for consistent error identification
+ */
+export declare enum ErrorCodes {
+    ALREADY_INITIALIZED = "ALREADY_INITIALIZED",
+    INVALID_TOKEN = "INVALID_TOKEN",
+    REACT_VERSION_UNSUPPORTED = "REACT_VERSION_UNSUPPORTED",
+    CONTAINER_NOT_FOUND = "CONTAINER_NOT_FOUND",
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    TOKEN_GENERATION_FAILED = "TOKEN_GENERATION_FAILED",
+    MISSING_CREDENTIALS = "MISSING_CREDENTIALS",
+    WEBRTC_NOT_SUPPORTED = "WEBRTC_NOT_SUPPORTED",
+    PEER_CONNECTION_FAILED = "PEER_CONNECTION_FAILED",
+    DATA_CHANNEL_ERROR = "DATA_CHANNEL_ERROR",
+    API_REQUEST_FAILED = "API_REQUEST_FAILED",
+    INVALID_RESPONSE = "INVALID_RESPONSE",
+    RATE_LIMITED = "RATE_LIMITED",
+    INVALID_CONFIGURATION = "INVALID_CONFIGURATION",
+    MISSING_REQUIRED_CONFIG = "MISSING_REQUIRED_CONFIG",
+    FEATURE_NOT_SUPPORTED = "FEATURE_NOT_SUPPORTED",
+    FEATURE_DISABLED = "FEATURE_DISABLED",
+    MEDIA_ACCESS_DENIED = "MEDIA_ACCESS_DENIED",
+    MEDIA_DEVICE_ERROR = "MEDIA_DEVICE_ERROR",
+    VIDEO_LOAD_ERROR = "VIDEO_LOAD_ERROR",
+    CAMERA_PERMISSION_DENIED = "CAMERA_PERMISSION_DENIED",
+    CAMERA_NOT_FOUND = "CAMERA_NOT_FOUND",
+    MODEL_LOAD_FAILED = "MODEL_LOAD_FAILED",
+    DETECTION_FAILED = "DETECTION_FAILED"
+}
+/**
+ * Type guard to check if an error is an SDK error
+ */
+export declare function isSDKError(error: unknown): error is SDKError;
+/**
+ * Helper function to create appropriate error based on context
+ */
+export declare function createError(type: "initialization" | "token" | "react" | "connection" | "webrtc" | "api" | "config" | "feature" | "media" | "faceTracking", message: string, context?: Record<string, unknown>): SDKError;
+/**
+ * Error handler utility for consistent error processing
+ */
+export declare class ErrorHandler {
+    private static onError?;
+    /**
+     * Set global error handler
+     */
+    static setErrorHandler(handler: (error: SDKError) => void): void;
+    /**
+     * Handle an error with optional context
+     */
+    static handle(error: unknown, context?: Record<string, unknown>): SDKError;
+}