@tinytapanalytics/sdk/src/types/index.ts

Behavioral psychology platform that detects visitor frustration, predicts abandonment, and helps you save at-risk conversions in real-time

/**
 * Type definitions for TinyTapAnalytics SDK
 */

export interface TinyTapAnalyticsConfig {
  /** API key for authentication */
  apiKey?: string;

  /** Website ID for tracking */
  websiteId?: string;

  /** API endpoint URL */
  endpoint?: string;

  /** Number of events to batch before sending */
  batchSize?: number;

  /** Interval in milliseconds to flush events */
  flushInterval?: number;

  /** Request timeout in milliseconds */
  timeout?: number;

  /** Enable automatic event tracking */
  enableAutoTracking?: boolean;

  /** Enable privacy-compliant mode */
  enablePrivacyMode?: boolean;

  /** Enable debug logging */
  debug?: boolean;

  /** User context data */
  userContext?: Partial<UserContext>;

  /** Custom endpoints for different event types */
  endpoints?: {
    events?: string;
    batch?: string;
  };

  /** Retry configuration */
  retry?: {
    maxAttempts?: number;
    baseDelay?: number;
    maxDelay?: number;
  };

  /** Enable performance monitoring */
  enablePerformanceMonitoring?: boolean;

  /** Enable micro-interaction tracking (behavioral psychology features) */
  enableMicroInteractions?: boolean;

  /** Alias for enableMicroInteractions */
  enableMicroInteractionTracking?: boolean;

  /** Micro-interaction tracking profile (minimal, balanced, detailed, performance) */
  microInteractionProfile?: 'minimal' | 'balanced' | 'detailed' | 'performance';

  /** Enable adaptive sampling for micro-interactions (default: true) */
  adaptiveSampling?: boolean;

  /** Enable heatmap tracking (click, move, scroll visualization) */
  enableHeatmap?: boolean;

  /** Heatmap sampling rate (0-1, default: 0.1 = 10% of sessions) */
  heatmapSamplingRate?: number;

  /** Batch interval in milliseconds (alias for flushInterval) */
  batchInterval?: number;

  /** Enable offline event queue */
  enableOfflineQueue?: boolean;

  /** Maximum number of offline events to store */
  maxOfflineEvents?: number;

  /** Sync interval for offline events (ms) */
  syncInterval?: number;

  /** Use fallback strategy for CORS issues (XHR → sendBeacon → image beacon) */
  useFallbackStrategy?: boolean;

  /** Enable credentials for cross-origin requests */
  withCredentials?: boolean;
}

export interface UserContext {
  /** User ID */
  userId?: string;

  /** User email */
  email?: string;

  /** User segment */
  segment?: string;

  /** User type (e.g., 'premium', 'free', 'enterprise') */
  userType?: string;

  /** Geographic location */
  location?: {
    country?: string;
    region?: string;
    city?: string;
    timezone?: string;
  };

  /** Device information */
  device?: {
    type?: 'desktop' | 'mobile' | 'tablet';
    os?: string;
    browser?: string;
    screenSize?: string;
  };

  /** Custom attributes */
  customAttributes?: Record<string, any>;
}

export interface EventData {
  /** Element selector for UI events */
  element?: string;

  /** Event value (for conversions) */
  value?: number;

  /** Currency code */
  currency?: string;

  /** Page URL */
  url?: string;

  /** Page title */
  title?: string;

  /** Referrer URL */
  referrer?: string;

  /** Form data */
  formData?: Record<string, any>;

  /** Click coordinates */
  coordinates?: {
    x: number;
    y: number;
  };

  /** Scroll depth percentage */
  scrollDepth?: number;

  /** Time spent on page */
  timeOnPage?: number;

  /** Custom metadata */
  metadata?: Record<string, any>;

  /** Additional event-specific data */
  [key: string]: any;
}

export interface TrackingOptions {
  /** Override timestamp */
  timestamp?: string | Date;

  /** Send immediately instead of batching */
  immediate?: boolean;

  /** Custom metadata for this event */
  metadata?: Record<string, any>;

  /** Priority level */
  priority?: 'low' | 'normal' | 'high';

  /** Retry configuration override */
  retry?: boolean;
}

export interface ConversionData {
  /** Conversion value */
  value: number;

  /** Currency code (defaults to USD) */
  currency?: string;

  /** Transaction ID */
  transactionId?: string;

  /** Order items */
  items?: ConversionItem[];

  /** Additional conversion metadata */
  metadata?: Record<string, any>;
}

export interface ConversionItem {
  /** Item ID */
  id: string;

  /** Item name */
  name: string;

  /** Item category */
  category?: string;

  /** Item quantity */
  quantity: number;

  /** Item price */
  price: number;

  /** Item SKU */
  sku?: string;

  /** Item brand */
  brand?: string;

  /** Additional item data */
  metadata?: Record<string, any>;
}

export interface PrivacySettings {
  /** Essential cookies (always allowed) */
  essential: boolean;

  /** Functional cookies */
  functional: boolean;

  /** Analytics cookies */
  analytics: boolean;

  /** Marketing cookies */
  marketing: boolean;
}

export interface NetworkRequest {
  /** Request URL */
  url: string;

  /** Request method */
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';

  /** Request headers */
  headers?: Record<string, string>;

  /** Request body */
  body?: any;

  /** Request timeout */
  timeout?: number;

  /** Retry configuration */
  retry?: {
    maxAttempts: number;
    baseDelay: number;
    maxDelay: number;
  };
}

export interface NetworkResponse<T = any> {
  /** Response status code */
  status: number;

  /** Response status text */
  statusText: string;

  /** Response data */
  data: T;

  /** Response headers */
  headers: Record<string, string>;

  /** Request that generated this response */
  request: NetworkRequest;
}

export interface QueuedEvent {
  /** Unique event ID */
  id: string;

  /** Event payload */
  payload: any;

  /** Timestamp when event was queued */
  queuedAt: number;

  /** Number of retry attempts */
  attempts: number;

  /** Next retry timestamp */
  nextRetry?: number;

  /** Event priority */
  priority: 'low' | 'normal' | 'high';
}

export interface SDKError {
  /** Error code */
  code: string;

  /** Error message */
  message: string;

  /** Error context */
  context?: string;

  /** Original error */
  originalError?: Error;

  /** Timestamp */
  timestamp: number;

  /** Stack trace */
  stack?: string;

  /** Additional error data */
  data?: any;
}

export interface EnvironmentInfo {
  /** Framework detection */
  framework?: 'react' | 'vue' | 'angular' | 'vanilla';

  /** SPA detection */
  isSPA: boolean;

  /** SSR detection */
  isSSR: boolean;

  /** Platform type */
  platform: 'web' | 'mobile-web' | 'amp' | 'unknown';

  /** Browser information */
  browser: {
    name: string;
    version: string;
    engine: string;
  };

  /** Device information */
  device: {
    type: 'desktop' | 'mobile' | 'tablet';
    os: string;
    screenSize: {
      width: number;
      height: number;
    };
  };

  /** Network information */
  network?: {
    effectiveType?: string;
    downlink?: number;
    rtt?: number;
  };
}

export interface BatchRequest {
  /** Batch ID */
  batchId: string;

  /** Events in this batch */
  events: any[];

  /** Batch timestamp */
  timestamp: string;

  /** Batch metadata */
  metadata: {
    sdkVersion: string;
    websiteId: string;
    sessionId: string;
    userAgent: string;
  };
}

export interface BatchResponse {
  /** Batch ID */
  batchId: string;

  /** Processing status */
  status: 'success' | 'partial' | 'failed';

  /** Number of successfully processed events */
  processed: number;

  /** Number of failed events */
  failed: number;

  /** Error details for failed events */
  errors?: Array<{
    index: number;
    error: string;
  }>;
}

// Event type constants
export const EVENT_TYPES = {
  PAGE_VIEW: 'page_view',
  CLICK: 'click',
  SCROLL: 'scroll',
  FORM_SUBMIT: 'form_submit',
  CONVERSION: 'conversion',
  IDENTIFY: 'identify',
  ERROR: 'error',
  CUSTOM: 'custom'
} as const;

export type EventType = typeof EVENT_TYPES[keyof typeof EVENT_TYPES];

// Privacy data types
export const DATA_TYPES = {
  ESSENTIAL: 'essential',
  FUNCTIONAL: 'functional',
  ANALYTICS: 'analytics',
  MARKETING: 'marketing'
} as const;

export type DataType = typeof DATA_TYPES[keyof typeof DATA_TYPES];

// Shopify-specific types for e-commerce tracking
export interface ShopifyCheckout {
  order_id?: string | number;
  total_price?: string | number;
  currency?: string;
  order_number?: string | number;
  line_items?: unknown[];
  customer?: unknown;
}

export interface ShopifyGlobal {
  checkout?: ShopifyCheckout;
  [key: string]: unknown;
}

// Window interface extensions
declare global {
  interface Window {
    __tinytapanalytics_queue?: Array<[string, ...unknown[]]>;
    Shopify?: ShopifyGlobal;
  }
}