@nice2dev/game-engine 1.3.12 → 1.3.14

package/dist/types/systems/NiceAnalytics.d.ts

@@ -1,493 +0,0 @@
-/**
- * NiceAnalytics - Game Analytics & Telemetry System
- *
- * Comprehensive analytics system for tracking player behavior, game performance,
- * progression metrics, and generating insights for game improvement.
- *
- * Features:
- * - Event tracking
- * - Session management
- * - Player journey tracking
- * - Funnel analysis
- * - Retention metrics
- * - Performance monitoring
- * - Custom dimensions
- * - A/B testing support
- * - Real-time dashboards
- * - Privacy compliance
- * - Offline queuing
- * - Data export
- *
- * @packageDocumentation
- */
-import { EventEmitter } from 'events';
-/** Unique event ID */
-export type AnalyticsEventId = string;
-/** Unique session ID */
-export type SessionId = string;
-/** Unique user ID */
-export type AnalyticsUserId = string;
-/** Unique experiment ID */
-export type ExperimentId = string;
-/** Event category */
-export type EventCategory = 'gameplay' | 'progression' | 'economy' | 'social' | 'ui' | 'performance' | 'error' | 'monetization' | 'engagement' | 'custom';
-/** Event priority */
-export type EventPriority = 'low' | 'normal' | 'high' | 'critical';
-/** Data type for custom dimensions */
-export type DimensionValue = string | number | boolean;
-/** Funnel stage */
-export type FunnelStage = string;
-/** Analytics event */
-export interface AnalyticsEvent {
-    id: AnalyticsEventId;
-    name: string;
-    category: EventCategory;
-    priority: EventPriority;
-    timestamp: number;
-    sessionId: SessionId;
-    userId?: AnalyticsUserId;
-    parameters: Record<string, DimensionValue>;
-    dimensions: Record<string, DimensionValue>;
-    metrics: Record<string, number>;
-    sequenceNumber: number;
-    gameVersion: string;
-    platform: string;
-    metadata?: Record<string, unknown>;
-}
-/** Session data */
-export interface AnalyticsSession {
-    id: SessionId;
-    userId?: AnalyticsUserId;
-    startTime: number;
-    endTime?: number;
-    duration: number;
-    eventCount: number;
-    isActive: boolean;
-    platform: string;
-    gameVersion: string;
-    deviceInfo: DeviceInfo;
-    entryPoint?: string;
-    exitPoint?: string;
-    dimensions: Record<string, DimensionValue>;
-}
-/** Device information */
-export interface DeviceInfo {
-    type: 'desktop' | 'mobile' | 'tablet' | 'console' | 'unknown';
-    os: string;
-    osVersion: string;
-    browser?: string;
-    browserVersion?: string;
-    screenWidth: number;
-    screenHeight: number;
-    devicePixelRatio: number;
-    language: string;
-    timezone: string;
-    memory?: number;
-    cpuCores?: number;
-    gpu?: string;
-}
-/** User properties */
-export interface UserProperties {
-    userId: AnalyticsUserId;
-    firstSeenAt: number;
-    lastSeenAt: number;
-    totalSessions: number;
-    totalPlayTime: number;
-    level: number;
-    isPaying: boolean;
-    totalSpent: number;
-    acquisitionSource?: string;
-    acquisitionCampaign?: string;
-    cohort?: string;
-    segment?: string;
-    tags: string[];
-    customProperties: Record<string, DimensionValue>;
-}
-/** Funnel definition */
-export interface FunnelDefinition {
-    id: string;
-    name: string;
-    stages: FunnelStage[];
-    timeout?: number;
-    isActive: boolean;
-}
-/** Funnel progress */
-export interface FunnelProgress {
-    funnelId: string;
-    userId: AnalyticsUserId;
-    currentStage: number;
-    completedStages: FunnelStage[];
-    startTime: number;
-    lastActivityTime: number;
-    isCompleted: boolean;
-    isAbandoned: boolean;
-    conversionTime?: number;
-}
-/** A/B Experiment */
-export interface Experiment {
-    id: ExperimentId;
-    name: string;
-    description?: string;
-    variants: ExperimentVariant[];
-    startDate: number;
-    endDate?: number;
-    targetAudience?: string;
-    isActive: boolean;
-    metrics: string[];
-}
-/** Experiment variant */
-export interface ExperimentVariant {
-    id: string;
-    name: string;
-    weight: number;
-    config: Record<string, unknown>;
-}
-/** User experiment assignment */
-export interface ExperimentAssignment {
-    experimentId: ExperimentId;
-    variantId: string;
-    assignedAt: number;
-    userId: AnalyticsUserId;
-}
-/** Performance metrics */
-export interface PerformanceMetrics {
-    fps: number;
-    frameTime: number;
-    memoryUsed: number;
-    memoryTotal: number;
-    loadTime: number;
-    drawCalls?: number;
-    triangles?: number;
-    networkLatency?: number;
-    timestamp: number;
-}
-/** Retention bucket */
-export interface RetentionBucket {
-    day: number;
-    cohort: string;
-    totalUsers: number;
-    returnedUsers: number;
-    retentionRate: number;
-}
-/** Revenue event */
-export interface RevenueEvent {
-    transactionId: string;
-    productId: string;
-    productName: string;
-    category: string;
-    price: number;
-    currency: string;
-    quantity: number;
-    isSubscription: boolean;
-    timestamp: number;
-}
-/** Error report */
-export interface ErrorReport {
-    id: string;
-    type: 'error' | 'warning' | 'crash';
-    message: string;
-    stack?: string;
-    context: Record<string, unknown>;
-    timestamp: number;
-    sessionId: SessionId;
-    count: number;
-    firstOccurrence: number;
-    lastOccurrence: number;
-}
-/** Analytics summary */
-export interface AnalyticsSummary {
-    totalEvents: number;
-    totalSessions: number;
-    totalUsers: number;
-    averageSessionDuration: number;
-    eventsPerSession: number;
-    topEvents: Array<{
-        name: string;
-        count: number;
-    }>;
-    topCategories: Array<{
-        category: EventCategory;
-        count: number;
-    }>;
-    errorRate: number;
-    performanceAvg: PerformanceMetrics;
-}
-/** Queue item */
-export interface QueuedEvent {
-    event: AnalyticsEvent;
-    retries: number;
-    queuedAt: number;
-}
-/** Privacy settings */
-export interface PrivacySettings {
-    analyticsEnabled: boolean;
-    errorReportingEnabled: boolean;
-    performanceTrackingEnabled: boolean;
-    personalDataEnabled: boolean;
-    consentTimestamp?: number;
-    consentVersion?: string;
-}
-/** Analytics event types */
-export type AnalyticsEventType = 'event_tracked' | 'session_started' | 'session_ended' | 'session_resumed' | 'user_identified' | 'user_updated' | 'funnel_progressed' | 'funnel_completed' | 'funnel_abandoned' | 'experiment_assigned' | 'revenue_tracked' | 'error_reported' | 'performance_recorded' | 'queue_flushed' | 'privacy_changed';
-/** Analytics system event */
-export interface AnalyticsSystemEvent {
-    type: AnalyticsEventType;
-    timestamp: number;
-    eventId?: AnalyticsEventId;
-    sessionId?: SessionId;
-    userId?: AnalyticsUserId;
-    data?: unknown;
-}
-/** Analytics event callback */
-export type AnalyticsEventCallback = (event: AnalyticsSystemEvent) => void;
-/** Analytics configuration */
-export interface AnalyticsConfig {
-    appId: string;
-    appVersion: string;
-    platform: string;
-    flushIntervalMs: number;
-    maxQueueSize: number;
-    maxRetries: number;
-    batchSize: number;
-    enableOfflineQueue: boolean;
-    enableAutoTracking: boolean;
-    enablePerformanceTracking: boolean;
-    enableErrorTracking: boolean;
-    performanceTrackingIntervalMs: number;
-    sessionTimeoutMs: number;
-    respectDoNotTrack: boolean;
-    anonymizeIp: boolean;
-    endpointUrl?: string;
-}
-/** Default configuration */
-export declare const DEFAULT_ANALYTICS_CONFIG: AnalyticsConfig;
-/**
- * Game analytics and telemetry system
- */
-export declare class NiceAnalytics extends EventEmitter {
-    private config;
-    private currentSession?;
-    private currentUser?;
-    private events;
-    private eventQueue;
-    private funnels;
-    private funnelProgress;
-    private experiments;
-    private assignments;
-    private errors;
-    private performanceHistory;
-    private privacySettings;
-    private deviceInfo;
-    private globalDimensions;
-    private sequenceCounter;
-    private flushInterval?;
-    private performanceInterval?;
-    private lastActivityTime;
-    private isOnline;
-    constructor(config?: Partial<AnalyticsConfig>);
-    /**
-     * Collect device information
-     */
-    private collectDeviceInfo;
-    /**
-     * Detect device type
-     */
-    private detectDeviceType;
-    /**
-     * Detect operating system
-     */
-    private detectOS;
-    /**
-     * Check Do Not Track setting
-     */
-    private checkDoNotTrack;
-    /**
-     * Generate unique ID
-     */
-    private generateId;
-    /**
-     * Emit analytics event
-     */
-    private emitEvent;
-    /**
-     * Start flush interval
-     */
-    private startFlushInterval;
-    /**
-     * Start performance tracking
-     */
-    private startPerformanceTracking;
-    /**
-     * Start new session
-     */
-    startSession(entryPoint?: string): SessionId;
-    /**
-     * End current session
-     */
-    endSession(exitPoint?: string): void;
-    /**
-     * Resume session after pause
-     */
-    resumeSession(): void;
-    /**
-     * Get current session
-     */
-    getCurrentSession(): AnalyticsSession | undefined;
-    /**
-     * Identify user
-     */
-    identify(userId: AnalyticsUserId, properties?: Partial<UserProperties>): void;
-    /**
-     * Update user properties
-     */
-    updateUser(properties: Partial<UserProperties>): void;
-    /**
-     * Set user property
-     */
-    setUserProperty(key: string, value: DimensionValue): void;
-    /**
-     * Get current user
-     */
-    getCurrentUser(): UserProperties | undefined;
-    /**
-     * Reset user (logout)
-     */
-    resetUser(): void;
-    /**
-     * Track event
-     */
-    track(name: string, category?: EventCategory, parameters?: Record<string, DimensionValue>, metrics?: Record<string, number>, priority?: EventPriority): AnalyticsEventId | undefined;
-    /**
-     * Track timed event start
-     */
-    startTimedEvent(name: string, _category?: EventCategory): string;
-    /**
-     * Track timed event end
-     */
-    endTimedEvent(timingId: string, name: string, category?: EventCategory, additionalParams?: Record<string, DimensionValue>): void;
-    /**
-     * Enqueue event for sending
-     */
-    private enqueue;
-    /**
-     * Flush event queue
-     */
-    flush(): Promise<void>;
-    /**
-     * Set global dimension
-     */
-    setDimension(key: string, value: DimensionValue): void;
-    /**
-     * Remove global dimension
-     */
-    removeDimension(key: string): void;
-    /**
-     * Get all dimensions
-     */
-    getDimensions(): Record<string, DimensionValue>;
-    /**
-     * Set multiple dimensions
-     */
-    setDimensions(dimensions: Record<string, DimensionValue>): void;
-    /**
-     * Define funnel
-     */
-    defineFunnel(funnel: FunnelDefinition): void;
-    /**
-     * Check funnel progress
-     */
-    private checkFunnels;
-    /**
-     * Get funnel progress
-     */
-    getFunnelProgress(funnelId: string): FunnelProgress | undefined;
-    /**
-     * Reset funnel progress
-     */
-    resetFunnelProgress(funnelId: string): void;
-    /**
-     * Register experiment
-     */
-    registerExperiment(experiment: Experiment): void;
-    /**
-     * Get variant for experiment
-     */
-    getVariant(experimentId: ExperimentId): ExperimentVariant | undefined;
-    /**
-     * Track experiment exposure
-     */
-    trackExposure(experimentId: ExperimentId): void;
-    /**
-     * Track experiment conversion
-     */
-    trackConversion(experimentId: ExperimentId, value?: number): void;
-    /**
-     * Track revenue
-     */
-    trackRevenue(event: Omit<RevenueEvent, 'timestamp'>): void;
-    /**
-     * Track subscription
-     */
-    trackSubscription(productId: string, action: 'start' | 'renew' | 'cancel', price?: number): void;
-    /**
-     * Track error
-     */
-    trackError(message: string, stack?: string, context?: Record<string, unknown>, type?: 'error' | 'warning' | 'crash'): void;
-    /**
-     * Get error reports
-     */
-    getErrors(): ErrorReport[];
-    /**
-     * Record performance metrics
-     */
-    recordPerformance(metrics?: Partial<PerformanceMetrics>): void;
-    /**
-     * Get performance history
-     */
-    getPerformanceHistory(): PerformanceMetrics[];
-    /**
-     * Get average performance
-     */
-    getAveragePerformance(): PerformanceMetrics;
-    /**
-     * Set privacy settings
-     */
-    setPrivacySettings(settings: Partial<PrivacySettings>): void;
-    /**
-     * Get privacy settings
-     */
-    getPrivacySettings(): PrivacySettings;
-    /**
-     * Opt out of all tracking
-     */
-    optOut(): void;
-    /**
-     * Opt in to tracking
-     */
-    optIn(): void;
-    /**
-     * Get analytics summary
-     */
-    getSummary(): AnalyticsSummary;
-    /**
-     * Export all data
-     */
-    exportData(): object;
-    /**
-     * Clear all data
-     */
-    clearData(): void;
-    /**
-     * Set online status
-     */
-    setOnlineStatus(online: boolean): void;
-    /**
-     * Destroy analytics system
-     */
-    destroy(): void;
-}
-/**
- * Create analytics system instance
- */
-export declare function createAnalyticsSystem(config?: Partial<AnalyticsConfig>): NiceAnalytics;
-export default NiceAnalytics;