uni-analytics-sdk/src/interfaces/index.ts

A universal SDK for analytics and logging.

// Augmenting the global Window interface to include properties
// added by third-party scripts like Google Analytics. This
// prevents TypeScript errors when accessing window.dataLayer or window.gtag.
declare global {
    interface Window {
        dataLayer: any[];
        gtag: (...args: any[]) => void;
    }
}

// This makes the gtag function available in the global scope for TypeScript.
// declare global {
//     interface Window {
//       gtag: (...args: any[]) => void;
//     }
// }

// =================================================================================================
// SECTION: Core Interfaces
// =================================================================================================

/**
 * Represents a user's traits for an `identify` call.
 */
export interface UserTraits {
    name?: string;
    email?: string;
    [key: string]: any; // Allow any other custom traits
}

/**
 * Defines the structure for a generic event that the SDK can process.
 * This is the universal format that providers will translate.
*/
export interface SDKEvent {
    type: 'track' | 'identify' | 'captureException' | 'captureMessage';
    timestamp: number;
    // For 'track' events
    eventName?: string;
    properties?: Record<string, any>;
    // For 'identify' events
    userId?: string;
    traits?: UserTraits;
    // For 'captureException' events
    error?: Error;
    // For 'captureMessage' events
    message?: string;
    // Common context for logging events
    level?: 'info' | 'warning' | 'error' | 'critical';
    context?: Record<string, any>;
}
  
/**
 * Defines the contract for any provider.
 * Providers are responsible for sending data to a specific third-party service.
*/
export interface Provider {
    /**
     * A unique identifier for the provider (e.g., 'GoogleAnalytics', 'Sentry').
     */
    name: string;
  
    /**
     * Called when the SDK is initialized. Use this to set up the provider,
     * for example, by loading an external script or initializing a client.
     * @param {Record<string, any>} config - The configuration object for this provider.
     */
    setup(config: Record<string, any>): Promise<void>;
  
    /**
     * Called by the SDK to process a batch of events.
     * @param {SDKEvent[]} events - An array of events to be processed.
     */
    processEvents(events: SDKEvent[]): Promise<void>;
  
    /**
     * A method to gracefully shut down the provider, ensuring any pending data is sent.
     */
    shutdown?(): Promise<void>;
}
  
  
/**
 * Configuration options for the UniversalSDK.
*/
export interface SDKConfig {
    /**
     * An array of provider instances to be used by the SDK.
     */
    providers: Provider[];
  
    /**
     * Configuration for each provider, keyed by the provider's name.
     */
    providerConfigs?: {
        [providerName: string]: ProviderConfig;
    };
  
    /**
     * The maximum number of events to hold in the queue before flushing.
     * @default 20
     */
    maxQueueSize?: number;
  
    /**
     * The maximum time in milliseconds to wait before flushing the queue.
     * @default 15000 (15 seconds)
     */
    flushInterval?: number;
  
    /**
     * Enable or disable debug logging for the SDK itself.
     * @default false
     */
    debug?: boolean;
}


// =================================================================================================
// SECTION: Provider Interfaces
// =================================================================================================

/**
 * A generic configuration object for any provider.
 * Using `[key: string]: any` allows for flexible provider-specific options
 * with different value types (string, boolean, etc.), fixing the type errors.
 */
export interface ProviderConfig {
    [key: string]: any;
  }
  
/**
 * Defines the contract that all providers must adhere to.
*/
export interface Provider {
    name: string;
    setup(config: ProviderConfig): Promise<void>;
    processEvents(events: SDKEvent[]): Promise<void>;
}
  
// =================================================================================================
// SECTION: Provider-Specific Configurations
// =================================================================================================

  
// Configuration specific to the Google Analytics provider.
export interface GoogleAnalyticsProviderConfig {
    /**
     * Your GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Required for both browser and server.
     */
    measurementId: string;
  
    /**
     * Your Measurement Protocol API Secret. Required for server-side (Node.js) tracking.
     */
    apiSecret?: string;
  
    /**
     * If true, sends a 'page_view' event automatically when the script loads in the browser.
     * @default true
     */
    automaticPageViews?: boolean;

    /**
     * If true, puts the provider in debug mode.
     * @default false
     */
    debug?: boolean;
    region?: 'eu' | string;
    // [key: string]: string;
}

/**
 * Defines the main configuration object for the SDK.
 */
export interface UniversalSDKConfig {
    providers: Provider[];
    providerConfigs?: {
      [providerName: string]: Record<string, any>;
    };
    queueSize?: number;
    flushInterval?: number;
    debug?: boolean;
}
  

export {};