flowgrid-sdk 1.0.0

package/dist/lib/types/analytics.d.ts

@@ -0,0 +1,365 @@
+/**
+ * @fileoverview Type definitions for product analytics tracking.
+ * @module types/analytics
+ */
+import { UserIdentity, DeviceInfo, GeoLocation, TimeSeriesData } from './common';
+/**
+ * Page view information.
+ */
+export interface PageView {
+    /** Page URL */
+    url: string;
+    /** Page path (without domain) */
+    path: string;
+    /** Page title */
+    title?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Time spent on page (seconds) */
+    timeOnPage?: number;
+    /** Scroll depth (0-100) */
+    scrollDepth?: number;
+    /** Whether user exited from this page */
+    isExit?: boolean;
+    /** Whether this was the landing page */
+    isLanding?: boolean;
+}
+/**
+ * Session information.
+ */
+export interface Session {
+    /** Session identifier */
+    sessionId: string;
+    /** User identity */
+    user?: UserIdentity;
+    /** Session start time */
+    startedAt: string;
+    /** Session end time (if ended) */
+    endedAt?: string;
+    /** Session duration in seconds */
+    duration?: number;
+    /** Number of pages viewed */
+    pageViews: number;
+    /** Number of events triggered */
+    eventCount: number;
+    /** Landing page URL */
+    landingPage?: string;
+    /** Exit page URL */
+    exitPage?: string;
+    /** Traffic source */
+    source?: string;
+    /** Traffic medium */
+    medium?: string;
+    /** Campaign */
+    campaign?: string;
+    /** Device info */
+    device?: DeviceInfo;
+    /** Location */
+    location?: GeoLocation;
+}
+/**
+ * Custom event tracking.
+ */
+export interface CustomEvent {
+    /** Event name */
+    eventName: string;
+    /** Event category */
+    category?: string;
+    /** Event action */
+    action?: string;
+    /** Event label */
+    label?: string;
+    /** Event value (numeric) */
+    value?: number;
+    /** Whether this event is non-interactive */
+    nonInteraction?: boolean;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Click/tap event.
+ */
+export interface ClickEvent {
+    /** Element ID that was clicked */
+    elementId?: string;
+    /** Element class */
+    elementClass?: string;
+    /** Element text content */
+    elementText?: string;
+    /** Element tag name */
+    elementTag?: string;
+    /** Target URL (for links) */
+    targetUrl?: string;
+    /** Click coordinates */
+    coordinates?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Form submission event.
+ */
+export interface FormEvent {
+    /** Form ID */
+    formId?: string;
+    /** Form name */
+    formName?: string;
+    /** Form action URL */
+    formAction?: string;
+    /** Whether submission was successful */
+    success: boolean;
+    /** Field names submitted (without values for privacy) */
+    fields?: string[];
+    /** Validation errors (field names only) */
+    validationErrors?: string[];
+    /** Time to complete form (seconds) */
+    completionTime?: number;
+}
+/**
+ * Search event.
+ */
+export interface SearchEvent {
+    /** Search query */
+    query: string;
+    /** Search category/scope */
+    category?: string;
+    /** Number of results */
+    resultsCount?: number;
+    /** Whether any results were clicked */
+    resultClicked?: boolean;
+    /** Position of clicked result */
+    clickedPosition?: number;
+    /** Search filters applied */
+    filters?: Record<string, string | string[]>;
+}
+/**
+ * Error/exception event.
+ */
+export interface ErrorEvent {
+    /** Error message */
+    message: string;
+    /** Error stack trace */
+    stack?: string;
+    /** Error type/name */
+    type?: string;
+    /** Whether it was fatal */
+    fatal?: boolean;
+    /** Page/component where error occurred */
+    context?: string;
+    /** User action that triggered error */
+    userAction?: string;
+}
+/**
+ * Feature usage tracking.
+ */
+export interface FeatureUsage {
+    /** Feature name */
+    featureName: string;
+    /** Feature category */
+    category?: string;
+    /** Action performed */
+    action: string;
+    /** Usage count */
+    usageCount?: number;
+    /** Time spent using feature (seconds) */
+    timeSpent?: number;
+    /** Whether feature was successfully used */
+    success?: boolean;
+}
+/**
+ * User engagement score factors.
+ */
+export interface EngagementFactors {
+    /** Days active in period */
+    daysActive: number;
+    /** Total sessions */
+    totalSessions: number;
+    /** Average session duration (seconds) */
+    avgSessionDuration: number;
+    /** Features used */
+    featuresUsed: number;
+    /** Actions taken */
+    actionsCount: number;
+    /** Content created/generated */
+    contentCreated: number;
+}
+/**
+ * Retention cohort data.
+ */
+export interface RetentionCohort {
+    /** Cohort identifier (e.g., "2026-01-W1") */
+    cohortId: string;
+    /** Cohort start date */
+    cohortDate: string;
+    /** Users in cohort */
+    cohortSize: number;
+    /** Retention by period (day/week/month index -> retained count) */
+    retention: Record<number, number>;
+    /** Retention percentages */
+    retentionPercent: Record<number, number>;
+}
+/**
+ * Funnel step definition.
+ */
+export interface FunnelStep {
+    /** Step name */
+    name: string;
+    /** Step description */
+    description?: string;
+    /** Event(s) that trigger this step */
+    events: string[];
+    /** Users who reached this step */
+    users: number;
+    /** Conversion rate from previous step */
+    conversionRate: number;
+    /** Drop-off rate from previous step */
+    dropOffRate: number;
+    /** Average time to complete (seconds) */
+    avgTimeToComplete?: number;
+}
+/**
+ * Funnel analysis results.
+ */
+export interface FunnelAnalysis {
+    /** Funnel name */
+    name: string;
+    /** Funnel steps */
+    steps: FunnelStep[];
+    /** Overall conversion rate (first to last step) */
+    overallConversionRate: number;
+    /** Total users who entered funnel */
+    totalUsers: number;
+    /** Total users who completed funnel */
+    completedUsers: number;
+    /** Analysis period */
+    period: {
+        start: string;
+        end: string;
+    };
+}
+/**
+ * Traffic metrics.
+ */
+export interface TrafficMetrics {
+    /** Total visits/sessions */
+    totalVisits: number;
+    /** Unique visitors */
+    uniqueVisitors: number;
+    /** Page views */
+    pageViews: number;
+    /** Pages per session */
+    pagesPerSession: number;
+    /** Average session duration (seconds) */
+    avgSessionDuration: number;
+    /** Bounce rate (0-1) */
+    bounceRate: number;
+    /** New visitor rate (0-1) */
+    newVisitorRate: number;
+    /** Traffic over time */
+    trafficTimeSeries: TimeSeriesData;
+}
+/**
+ * Acquisition/source metrics.
+ */
+export interface AcquisitionMetrics {
+    /** Traffic by source */
+    bySource: Array<{
+        source: string;
+        visits: number;
+        uniqueVisitors: number;
+        bounceRate: number;
+        conversionRate: number;
+    }>;
+    /** Traffic by medium */
+    byMedium: Array<{
+        medium: string;
+        visits: number;
+        uniqueVisitors: number;
+    }>;
+    /** Traffic by campaign */
+    byCampaign: Array<{
+        campaign: string;
+        visits: number;
+        conversions: number;
+        revenue?: number;
+    }>;
+}
+/**
+ * User behavior metrics.
+ */
+export interface BehaviorMetrics {
+    /** Top pages by views */
+    topPages: Array<{
+        path: string;
+        title: string;
+        views: number;
+        avgTimeOnPage: number;
+        bounceRate: number;
+    }>;
+    /** Top events */
+    topEvents: Array<{
+        eventName: string;
+        count: number;
+        uniqueUsers: number;
+    }>;
+    /** Top exit pages */
+    exitPages: Array<{
+        path: string;
+        exitRate: number;
+        exits: number;
+    }>;
+    /** Average scroll depth */
+    avgScrollDepth: number;
+}
+/**
+ * Real-time analytics.
+ */
+export interface RealTimeMetrics {
+    /** Current active users */
+    activeUsers: number;
+    /** Active users by page */
+    usersByPage: Array<{
+        path: string;
+        users: number;
+    }>;
+    /** Active users by location */
+    usersByCountry: Array<{
+        country: string;
+        users: number;
+    }>;
+    /** Active users by device */
+    usersByDevice: Array<{
+        device: string;
+        users: number;
+    }>;
+    /** Events in last minute */
+    eventsPerMinute: number;
+    /** Top events right now */
+    topEventsNow: Array<{
+        event: string;
+        count: number;
+    }>;
+}
+/**
+ * User lifecycle stage.
+ */
+export type UserLifecycleStage = 'new' | 'activated' | 'engaged' | 'retained' | 'churned' | 'resurrected';
+/**
+ * User lifecycle metrics.
+ */
+export interface LifecycleMetrics {
+    /** Users by lifecycle stage */
+    byStage: Record<UserLifecycleStage, number>;
+    /** Stage transitions this period */
+    transitions: Array<{
+        from: UserLifecycleStage;
+        to: UserLifecycleStage;
+        count: number;
+    }>;
+    /** Activation rate */
+    activationRate: number;
+    /** Churn rate */
+    churnRate: number;
+    /** Resurrection rate */
+    resurrectionRate: number;
+}

package/dist/lib/types/common.d.ts

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview Common types shared across all FlowGrid SDK modules.
+ * @module types/common
+ */
+/**
+ * Base configuration for all SDK events.
+ */
+export interface BaseConfig {
+    /** The name of the event to track */
+    eventName: string;
+    /** Additional properties to send with the event */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Standard API response from FlowGrid.
+ */
+export interface BaseResponse<T = unknown> {
+    /** The event name that was tracked */
+    eventName: string;
+    /** Properties that were sent */
+    properties: Record<string, unknown>;
+    /** API response data */
+    response: T;
+    /** Timestamp of the response */
+    timestamp: string;
+}
+/**
+ * Pagination parameters for list queries.
+ */
+export interface PaginationParams {
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Number of items per page */
+    limit?: number;
+    /** Sort field */
+    sortBy?: string;
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Date range filter for queries.
+ */
+export interface DateRangeFilter {
+    /** Start date (ISO string or Date object) */
+    startDate?: string | Date;
+    /** End date (ISO string or Date object) */
+    endDate?: string | Date;
+    /** Predefined time range */
+    range?: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'last90days' | 'thisMonth' | 'lastMonth' | 'thisYear';
+}
+/**
+ * Supported currency codes (ISO 4217).
+ */
+export type CurrencyCode = 'USD' | 'EUR' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'CHF' | 'CNY' | 'INR' | 'MXN' | 'BRL' | 'KRW' | 'SGD' | 'HKD' | 'NOK' | 'SEK' | 'DKK' | 'NZD' | 'ZAR' | 'RUB' | 'TRY' | 'PLN' | 'THB' | 'IDR' | 'MYR' | 'PHP' | 'CZK' | 'ILS' | 'CLP' | 'PKR' | 'EGP' | 'KWD' | 'AED' | 'SAR' | 'TWD' | 'VND';
+/**
+ * Money value with currency.
+ */
+export interface MoneyValue {
+    /** Amount in the smallest currency unit (e.g., cents for USD) */
+    amount: number;
+    /** Currency code (ISO 4217) */
+    currency: CurrencyCode;
+}
+/**
+ * User identification for analytics tracking.
+ */
+export interface UserIdentity {
+    /** Unique user identifier */
+    userId?: string;
+    /** Anonymous/session identifier */
+    anonymousId?: string;
+    /** User email (hashed recommended) */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** User phone (hashed recommended) */
+    phone?: string;
+}
+/**
+ * User traits for segmentation.
+ */
+export interface UserTraits {
+    /** Creation date of the user account */
+    createdAt?: string | Date;
+    /** User's plan or tier */
+    plan?: string;
+    /** Whether the user is a paying customer */
+    isPaying?: boolean;
+    /** User's lifetime value */
+    ltv?: MoneyValue;
+    /** User's company/organization */
+    company?: string;
+    /** User's role */
+    role?: string;
+    /** Custom traits */
+    [key: string]: unknown;
+}
+/**
+ * Device information for analytics.
+ */
+export interface DeviceInfo {
+    /** Device type */
+    type?: 'desktop' | 'mobile' | 'tablet' | 'tv' | 'wearable' | 'unknown';
+    /** Operating system */
+    os?: string;
+    /** OS version */
+    osVersion?: string;
+    /** Browser name */
+    browser?: string;
+    /** Browser version */
+    browserVersion?: string;
+    /** Device manufacturer */
+    manufacturer?: string;
+    /** Device model */
+    model?: string;
+    /** Screen width in pixels */
+    screenWidth?: number;
+    /** Screen height in pixels */
+    screenHeight?: number;
+}
+/**
+ * Geographic location information.
+ */
+export interface GeoLocation {
+    /** Country code (ISO 3166-1 alpha-2) */
+    country?: string;
+    /** Region/State */
+    region?: string;
+    /** City name */
+    city?: string;
+    /** Postal/ZIP code */
+    postalCode?: string;
+    /** Timezone (IANA format) */
+    timezone?: string;
+    /** Latitude */
+    latitude?: number;
+    /** Longitude */
+    longitude?: number;
+}
+/**
+ * UTM campaign parameters.
+ */
+export interface UTMParams {
+    /** Campaign source (e.g., google, newsletter) */
+    utmSource?: string;
+    /** Campaign medium (e.g., cpc, email) */
+    utmMedium?: string;
+    /** Campaign name */
+    utmCampaign?: string;
+    /** Campaign term (for paid search) */
+    utmTerm?: string;
+    /** Campaign content (for A/B testing) */
+    utmContent?: string;
+}
+/**
+ * Full context for event tracking.
+ */
+export interface TrackingContext {
+    /** User identity */
+    user?: UserIdentity;
+    /** Device information */
+    device?: DeviceInfo;
+    /** Geographic location */
+    location?: GeoLocation;
+    /** UTM parameters */
+    utm?: UTMParams;
+    /** Page URL */
+    pageUrl?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Aggregation types for metrics.
+ */
+export type AggregationType = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'median' | 'percentile';
+/**
+ * Time granularity for charts and reports.
+ */
+export type TimeGranularity = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Chart-ready data point.
+ */
+export interface ChartDataPoint {
+    /** Label for the data point (e.g., date, category) */
+    label: string;
+    /** Primary value */
+    value: number;
+    /** Secondary value (for comparison) */
+    previousValue?: number;
+    /** Percentage change from previous period */
+    changePercent?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Chart-ready time series data.
+ */
+export interface TimeSeriesData {
+    /** Time granularity */
+    granularity: TimeGranularity;
+    /** Data points */
+    data: ChartDataPoint[];
+    /** Total/summary value */
+    total?: number;
+    /** Comparison period total */
+    previousTotal?: number;
+}
+/**
+ * Metric summary for dashboards.
+ */
+export interface MetricSummary {
+    /** Metric name */
+    name: string;
+    /** Current value */
+    value: number;
+    /** Previous period value */
+    previousValue?: number;
+    /** Percentage change */
+    changePercent?: number;
+    /** Trend direction */
+    trend?: 'up' | 'down' | 'flat';
+    /** Whether higher is better */
+    higherIsBetter?: boolean;
+    /** Display format */
+    format?: 'number' | 'currency' | 'percent' | 'duration';
+    /** Currency code (if format is currency) */
+    currency?: CurrencyCode;
+}