@touchcastllc/napster-companion-api-dev 1.5.0-alpha.0 → 1.6.0-alpha.0

package/lib/stores/index.d.ts

@@ -2,5 +2,5 @@ export { store } from "./store";
 export type { RootState } from "./store";
 export { setOnFeaturesUpdateCallback } from "./middleware/featuresUpdateMiddleware";
 export * from "./selectors";
-export { setSessionId, setAvatarReady, setDataChannel, setStopInteraction, setMuted, setAutoMicActive, setVolume, setAvatarSpeaking, setScreenSharing, setUserTalking, setConnectionToken, setCloseConnectionHandler, setSessionTerminatedByServer, resetAvatar, } from "./slices/avatarSlice";
-export { setFeatures, resetFeatures, setPosition, setDebugMode, } from "./slices/appSlice";
+export { setSessionId, setDataChannel, setStopInteraction, setMuted, setAutoMicActive, setVolume, setAvatarSpeaking, setScreenSharing, setUserTalking, setConnectionToken, setCloseConnectionHandler, setSessionTerminatedByServer, resetAvatar, } from "./slices/avatarSlice";
+export { setFeatures, resetFeatures, setDebugMode } from "./slices/appSlice";

package/lib/stores/selectors.d.ts

@@ -1,10 +1,9 @@
 import { RootState } from "./index";
-import { FeatureConfig, Position } from "../types";
+import { FeatureConfig } from "../types";
 /**
  * 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 selectMuted: (state: RootState) => boolean;
 export declare const selectAutoMicActive: (state: RootState) => boolean;
@@ -18,9 +17,7 @@ export declare const selectSessionTerminatedByServer: (state: RootState) => bool
  * App state selectors
  */
 export declare const selectFeatures: (state: RootState) => FeatureConfig;
-export declare const selectPosition: (state: RootState) => Position | undefined;
 /**
  * Composite selectors
  */
 export declare const selectIsConnected: (state: RootState) => boolean;
-export declare const selectCanSendMessage: (state: RootState) => boolean;

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

@@ -1,11 +1,10 @@
-import { Position, FeatureConfig } from "../../types";
+import { FeatureConfig } from "../../types";
 export interface AppState {
     features: FeatureConfig;
-    position?: Position;
     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">, setDebugMode: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<boolean | undefined, "app/setDebugMode">;
+}, "app/setFeatures">, resetFeatures: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"app/resetFeatures">, setDebugMode: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<boolean | undefined, "app/setDebugMode">;
 export declare const appReducer: import("redux").Reducer<AppState>;

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

@@ -1,11 +1,5 @@
-export interface WebRTCStatus {
-    blocked: boolean;
-    reason: string;
-    message: string;
-}
 export interface AvatarState {
     sessionId?: string;
-    avatarReady: boolean;
     dataChannel: RTCDataChannel | null;
     stopInteraction: boolean;
     muted: boolean;
@@ -18,5 +12,5 @@ export interface AvatarState {
     closeConnectionHandler?: () => void;
     sessionTerminatedByServer: boolean;
 }
-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">, setStopInteraction: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setStopInteraction">, setMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMuted">, setAutoMicActive: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAutoMicActive">, setVolume: import("@reduxjs/toolkit").ActionCreatorWithPayload<number, "avatar/setVolume">, setAvatarSpeaking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAvatarSpeaking">, setScreenSharing: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setScreenSharing">, setUserTalking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setUserTalking">, setConnectionToken: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setConnectionToken">, setCloseConnectionHandler: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<(() => void) | undefined, "avatar/setCloseConnectionHandler">, setSessionTerminatedByServer: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setSessionTerminatedByServer">, resetAvatar: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"avatar/resetAvatar">;
+export declare const setSessionId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setSessionId">, setDataChannel: import("@reduxjs/toolkit").ActionCreatorWithPayload<RTCDataChannel | null, "avatar/setDataChannel">, setStopInteraction: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setStopInteraction">, setMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMuted">, setAutoMicActive: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAutoMicActive">, setVolume: import("@reduxjs/toolkit").ActionCreatorWithPayload<number, "avatar/setVolume">, setAvatarSpeaking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAvatarSpeaking">, setScreenSharing: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setScreenSharing">, setUserTalking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setUserTalking">, setConnectionToken: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setConnectionToken">, setCloseConnectionHandler: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<(() => void) | undefined, "avatar/setCloseConnectionHandler">, setSessionTerminatedByServer: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setSessionTerminatedByServer">, resetAvatar: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"avatar/resetAvatar">;
 export declare const avatarReducer: import("redux").Reducer<AvatarState>;

package/lib/stores/store.d.ts

@@ -8,4 +8,3 @@ export declare const store: import("@reduxjs/toolkit").EnhancedStore<{
     }, 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

@@ -11,25 +11,3 @@ export interface BaseController<TOptions = unknown> {
      */
     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/errors.d.ts

@@ -30,12 +30,6 @@ export declare class InitializationError extends SDKError {
 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
  */
@@ -48,30 +42,6 @@ export declare class ConnectionError extends SDKError {
 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
  */
@@ -123,10 +93,6 @@ export declare enum ErrorCodes {
  * 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
  */

package/lib/types/index.d.ts

@@ -1,7 +1,5 @@
-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.
@@ -326,17 +324,42 @@ export interface PersistenceOptions {
      */
     iframeOnNavigate?: boolean;
     /**
-     * URLs/domains excluded from persistence: instead of loading inside the iframe they
-     * open as a normal top-level navigation (which ends the session). Use for pages that
-     * can't be framed (auth / SSO) or shouldn't be (checkout, signout). Cross-origin
-     * links always open top-level by default, so this only matters for same-origin.
+     * Pages of YOUR OWN site that must not be framed: they open as a normal top-level
+     * navigation, which ends the session. Use for anything that breaks inside an iframe
+     * or shouldn't be wrapped — auth / SSO, checkout, sign-out.
+     *
+     * Same-origin only, and that is not a limitation: anything cross-origin already opens
+     * top-level unless you list it under {@link include}.
      */
     exclude?: {
-        /** Hostnames to exclude (exact host or a parent domain, e.g. `"napster.com"`). */
-        domains?: string[];
-        /** URLs to exclude: an absolute `"https://…"` (exact/prefix) or a same-origin path prefix. */
+        /** An absolute `"https://…"` (exact or prefix) or a same-origin path prefix (`"/checkout"`). */
         urls?: string[];
     };
+    /**
+     * Other people's domains that ARE allowed to load inside the site frame, so following
+     * a link to them keeps the session alive instead of ending it. Everything cross-origin
+     * breaks out by default; this is the exception list.
+     *
+     * ```ts
+     * include: { domains: ["docs.example.com", "partner.io"] }
+     * ```
+     *
+     * Matches the exact host or any subdomain of it. Only add a domain you control or have
+     * agreed with, and know what you give up — inside a cross-origin page the engine can
+     * see nothing:
+     *
+     * - the site must permit framing at all; one that sends `X-Frame-Options: DENY` or a
+     *   restrictive `frame-ancestors` shows a blank frame, and that cannot be detected;
+     * - links clicked in there are not intercepted, so the user can wander anywhere and
+     *   nothing brings them back;
+     * - the address bar stops following the frame, and back/forward stop syncing with it;
+     * - ending the session there cannot reload the page the user is on, so it unwraps to
+     *   the last page of your own site instead.
+     */
+    include?: {
+        /** Hostnames allowed inside the frame (exact host or a parent domain, e.g. `"example.com"`). */
+        domains?: string[];
+    };
     /** Value for the site iframe's `allow` attribute (Permissions Policy). Default: `"autoplay; clipboard-write"`. */
     iframeAllowAttribute?: string;
     /**
@@ -452,8 +475,6 @@ export interface NapsterCompanionApiConfig {
         /** Optional companion picture shown on the button. */
         avatarUrl?: string;
     };
-    /** 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;

package/lib/utils/debug.d.ts

@@ -96,9 +96,5 @@ declare class DebugLogger {
 /**
  * Global debug logger instance
  */
-export declare const debugLogger: DebugLogger;
-/**
- * Convenience export for common usage
- */
 export declare const debug: DebugLogger;
 export {};

package/lib/utils/mediaError.d.ts

@@ -5,10 +5,3 @@
  * level down in `context.error`.
  */
 export declare function rootCauseName(error: unknown): string | undefined;
-/**
- * Whether a media failure leaves the user with a recoverable permission
- * problem. Both flavors land on the same "access blocked" screen: a denied
- * prompt is fixable in site settings, and a missing device is equally fatal to
- * a voice session, so neither may negotiate a session the agent cannot hear.
- */
-export declare function isMicUnavailable(error: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "1.5.0-alpha.0",
+  "version": "1.6.0-alpha.0",
   "keywords": [
     "napster",
     "companion-api",

package/lib/services/analytics.d.ts

@@ -1,148 +0,0 @@
-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/types/analytics.d.ts

@@ -1,95 +0,0 @@
-/**
- * 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;
-}