@kodeme-io/next-core-analytics/dist/index.d.ts

Analytics, charts, dashboards, and reporting for Next.js applications

import React$1, { Component, ReactNode } from 'react';
import * as react_jsx_runtime from 'react/jsx-runtime';
import { z } from 'zod';

/**
 * Analytics Package Types
 * @module @kodeme-io/next-core-analytics/types
 */
interface ChartDataPoint {
    name: string;
    value: number;
    [key: string]: any;
}
interface MultiSeriesDataPoint {
    name: string;
    [key: string]: string | number;
}
type ChartType = 'line' | 'bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'radar';
interface ChartConfig {
    type: ChartType;
    data: ChartDataPoint[] | MultiSeriesDataPoint[];
    xKey?: string;
    yKey?: string | string[];
    colors?: string[];
    legend?: boolean;
    grid?: boolean;
    tooltip?: boolean;
    title?: string;
    subtitle?: string;
}
interface KPIMetric {
    id: string;
    label: string;
    value: number | string;
    previousValue?: number;
    format?: 'number' | 'currency' | 'percentage' | 'duration';
    trend?: 'up' | 'down' | 'neutral';
    trendValue?: number;
    icon?: React.ComponentType<any> | React.ReactNode;
    color?: string;
    prefix?: string;
    suffix?: string;
    locale?: string;
    currency?: string;
    numberFormatOptions?: Intl.NumberFormatOptions;
}
interface KPICardConfig {
    metrics: KPIMetric[];
    variant?: 'default' | 'compact' | 'detailed';
    showTrend?: boolean;
    showComparison?: boolean;
}
interface DashboardWidget {
    id: string;
    type: 'chart' | 'kpi' | 'table' | 'custom';
    title: string;
    description?: string;
    config: ChartConfig | KPICardConfig | any;
    span?: {
        cols?: number;
        rows?: number;
    };
}
interface DashboardLayout {
    id: string;
    name: string;
    widgets: DashboardWidget[];
    refreshInterval?: number;
    filters?: DashboardFilter[];
}
interface DashboardFilter {
    id: string;
    type: 'date' | 'select' | 'multiselect' | 'range';
    label: string;
    value: any;
    options?: {
        label: string;
        value: any;
    }[];
}
type ExportFormat = 'pdf' | 'excel' | 'csv' | 'json';
interface ExportConfig {
    format: ExportFormat;
    filename?: string;
    data: any[];
    columns?: string[];
    title?: string;
    includeCharts?: boolean;
}
type AggregationType = 'sum' | 'avg' | 'min' | 'max' | 'count';
interface AggregationConfig {
    field: string;
    type: AggregationType;
    groupBy?: string;
}
type TimeGranularity = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
interface TimeSeriesConfig {
    dateField: string;
    valueField: string;
    granularity: TimeGranularity;
    fillGaps?: boolean;
}
interface ComparisonData {
    current: number;
    previous: number;
    percentChange: number;
    trend: 'up' | 'down' | 'neutral';
}
interface ComparisonConfig<T extends Record<string, any> = any> {
    currentPeriod: {
        start: Date;
        end: Date;
    };
    previousPeriod: {
        start: Date;
        end: Date;
    };
    metric: string;
    data: T[];
}

interface KPICardProps {
    metric: KPIMetric;
    variant?: 'default' | 'compact' | 'detailed';
    className?: string;
}
declare const KPICard: React$1.FC<KPICardProps>;

/**
 * Chart Container Component
 * Renders different types of charts using Recharts
 */

interface ChartContainerProps {
    config: ChartConfig;
    loading?: boolean;
    error?: string;
    className?: string;
}
declare const ChartContainer: React$1.FC<ChartContainerProps>;

/**
 * Dashboard Component
 * Renders a complete analytics dashboard with widgets
 */

interface DashboardProps {
    layout: DashboardLayout;
    onRefresh?: () => void;
    className?: string;
}
declare const Dashboard: React$1.FC<DashboardProps>;

/**
 * Export Button Component
 * Handles data export to various formats
 */

declare module 'jspdf' {
    interface jsPDF {
        autoTable: (options: any) => jsPDF;
    }
}
interface ExportButtonProps {
    config: ExportConfig;
    className?: string;
}
declare const ExportButton: React$1.FC<ExportButtonProps>;

interface Props {
    children: ReactNode;
    fallback?: ReactNode;
    onError?: (error: Error, errorInfo: React$1.ErrorInfo) => void;
    showDetails?: boolean;
}
interface State {
    hasError: boolean;
    error?: Error;
    errorInfo?: React$1.ErrorInfo;
}
declare class AnalyticsErrorBoundary extends Component<Props, State> {
    constructor(props: Props);
    static getDerivedStateFromError(error: Error): State;
    componentDidCatch(error: Error, errorInfo: React$1.ErrorInfo): void;
    handleReset: () => void;
    render(): string | number | boolean | Iterable<React$1.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
}
declare function KPIErrorBoundary({ children }: {
    children: ReactNode;
}): react_jsx_runtime.JSX.Element;
declare function ChartErrorBoundary({ children }: {
    children: ReactNode;
}): react_jsx_runtime.JSX.Element;
declare function DashboardErrorBoundary({ children }: {
    children: ReactNode;
}): react_jsx_runtime.JSX.Element;
declare function useErrorHandler(): {
    error: Error | null;
    captureError: (error: Error) => void;
    resetError: () => void;
};

/**
 * useAnalytics Hook
 * Provides analytics data fetching and management
 */
interface UseAnalyticsOptions {
    endpoint: string;
    params?: Record<string, any>;
    realtime?: boolean;
    refreshInterval?: number;
    headers?: Record<string, string>;
    method?: 'GET' | 'POST';
    cache?: RequestCache;
    revalidate?: number;
}
interface UseAnalyticsReturn {
    data: any[] | null;
    loading: boolean;
    error: Error | null;
    refresh: () => Promise<void>;
    subscribe: (event: string, callback: (data: any) => void) => void;
    unsubscribe: (event: string) => void;
}
declare const useAnalytics: (options: UseAnalyticsOptions) => UseAnalyticsReturn;

/**
 * Data Aggregation Utilities
 * Functions for aggregating and processing analytics data
 */

declare function aggregateData<T extends Record<string, any>>(data: T[], config: AggregationConfig): Array<Record<string, any>>;
declare function processTimeSeries<T extends Record<string, any>>(data: T[], config: TimeSeriesConfig): Array<{
    date: string;
    value: number;
}>;
declare function calculateComparison<T extends Record<string, any>>(options: ComparisonConfig<T>): {
    current: number;
    previous: number;
    percentChange: number;
    trend: 'up' | 'down' | 'neutral';
};

/**
 * Formatting Utilities
 * Handles number, currency, percentage, and duration formatting with internationalization
 */

interface FormatValueOptions {
    format?: KPIMetric['format'];
    locale?: string;
    currency?: string;
    prefix?: string;
    suffix?: string;
    numberFormatOptions?: Intl.NumberFormatOptions;
}
declare function formatValue(value: number | string, options?: FormatValueOptions): string;
/**
 * Formats duration in seconds to human-readable format
 */
declare function formatDuration(seconds: number): string;
/**
 * Formats trend value with sign
 */
declare function formatTrendValue(value: number, format?: 'percentage' | 'number'): string;
/**
 * Creates a formatter function with preset options
 */
declare function createFormatter(options: Partial<FormatValueOptions>): (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
declare const currencyFormatters: {
    USD: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    EUR: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    GBP: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    JPY: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    CNY: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    IDR: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
};
declare const numberFormatters: {
    default: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    european: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    asian: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
};
declare const percentageFormatters: {
    default: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
    european: (value: number | string, additionalOptions?: Partial<FormatValueOptions>) => string;
};

/**
 * Data Validation Utilities
 * Zod schemas for validating analytics data
 */

declare const ChartDataPointSchema: z.ZodObject<{
    name: z.ZodString;
    value: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    name: string;
    value: number;
}, {
    name: string;
    value: number;
}>;
declare const MultiSeriesDataPointSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
declare const KPIMetricSchema: z.ZodObject<{
    id: z.ZodString;
    label: z.ZodString;
    value: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
    previousValue: z.ZodOptional<z.ZodNumber>;
    format: z.ZodOptional<z.ZodEnum<["number", "currency", "percentage", "duration"]>>;
    trend: z.ZodOptional<z.ZodEnum<["up", "down", "neutral"]>>;
    trendValue: z.ZodOptional<z.ZodNumber>;
    color: z.ZodOptional<z.ZodString>;
    prefix: z.ZodOptional<z.ZodString>;
    suffix: z.ZodOptional<z.ZodString>;
    locale: z.ZodOptional<z.ZodString>;
    currency: z.ZodOptional<z.ZodString>;
    numberFormatOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
    icon: z.ZodOptional<z.ZodAny>;
}, "strip", z.ZodTypeAny, {
    value: string | number;
    id: string;
    label: string;
    currency?: string | undefined;
    format?: "number" | "currency" | "percentage" | "duration" | undefined;
    locale?: string | undefined;
    prefix?: string | undefined;
    suffix?: string | undefined;
    numberFormatOptions?: Record<string, any> | undefined;
    previousValue?: number | undefined;
    trend?: "up" | "down" | "neutral" | undefined;
    trendValue?: number | undefined;
    color?: string | undefined;
    icon?: any;
}, {
    value: string | number;
    id: string;
    label: string;
    currency?: string | undefined;
    format?: "number" | "currency" | "percentage" | "duration" | undefined;
    locale?: string | undefined;
    prefix?: string | undefined;
    suffix?: string | undefined;
    numberFormatOptions?: Record<string, any> | undefined;
    previousValue?: number | undefined;
    trend?: "up" | "down" | "neutral" | undefined;
    trendValue?: number | undefined;
    color?: string | undefined;
    icon?: any;
}>;
declare const ChartConfigSchema: z.ZodObject<{
    type: z.ZodEnum<["line", "bar", "area", "pie", "donut", "scatter", "radar"]>;
    data: z.ZodArray<z.ZodAny, "many">;
    xKey: z.ZodOptional<z.ZodString>;
    yKey: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
    legend: z.ZodOptional<z.ZodBoolean>;
    grid: z.ZodOptional<z.ZodBoolean>;
    tooltip: z.ZodOptional<z.ZodBoolean>;
    title: z.ZodOptional<z.ZodString>;
    subtitle: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    type: "line" | "bar" | "area" | "pie" | "donut" | "scatter" | "radar";
    data: any[];
    xKey?: string | undefined;
    yKey?: string | string[] | undefined;
    colors?: string[] | undefined;
    legend?: boolean | undefined;
    grid?: boolean | undefined;
    tooltip?: boolean | undefined;
    title?: string | undefined;
    subtitle?: string | undefined;
}, {
    type: "line" | "bar" | "area" | "pie" | "donut" | "scatter" | "radar";
    data: any[];
    xKey?: string | undefined;
    yKey?: string | string[] | undefined;
    colors?: string[] | undefined;
    legend?: boolean | undefined;
    grid?: boolean | undefined;
    tooltip?: boolean | undefined;
    title?: string | undefined;
    subtitle?: string | undefined;
}>;
declare const DashboardWidgetSchema: z.ZodObject<{
    id: z.ZodString;
    type: z.ZodEnum<["chart", "kpi", "table", "custom"]>;
    title: z.ZodString;
    description: z.ZodOptional<z.ZodString>;
    config: z.ZodAny;
    span: z.ZodOptional<z.ZodObject<{
        cols: z.ZodOptional<z.ZodNumber>;
        rows: z.ZodOptional<z.ZodNumber>;
    }, "strip", z.ZodTypeAny, {
        cols?: number | undefined;
        rows?: number | undefined;
    }, {
        cols?: number | undefined;
        rows?: number | undefined;
    }>>;
}, "strip", z.ZodTypeAny, {
    type: "chart" | "kpi" | "table" | "custom";
    id: string;
    title: string;
    description?: string | undefined;
    config?: any;
    span?: {
        cols?: number | undefined;
        rows?: number | undefined;
    } | undefined;
}, {
    type: "chart" | "kpi" | "table" | "custom";
    id: string;
    title: string;
    description?: string | undefined;
    config?: any;
    span?: {
        cols?: number | undefined;
        rows?: number | undefined;
    } | undefined;
}>;
declare const DashboardLayoutSchema: z.ZodObject<{
    id: z.ZodString;
    name: z.ZodString;
    widgets: z.ZodArray<z.ZodObject<{
        id: z.ZodString;
        type: z.ZodEnum<["chart", "kpi", "table", "custom"]>;
        title: z.ZodString;
        description: z.ZodOptional<z.ZodString>;
        config: z.ZodAny;
        span: z.ZodOptional<z.ZodObject<{
            cols: z.ZodOptional<z.ZodNumber>;
            rows: z.ZodOptional<z.ZodNumber>;
        }, "strip", z.ZodTypeAny, {
            cols?: number | undefined;
            rows?: number | undefined;
        }, {
            cols?: number | undefined;
            rows?: number | undefined;
        }>>;
    }, "strip", z.ZodTypeAny, {
        type: "chart" | "kpi" | "table" | "custom";
        id: string;
        title: string;
        description?: string | undefined;
        config?: any;
        span?: {
            cols?: number | undefined;
            rows?: number | undefined;
        } | undefined;
    }, {
        type: "chart" | "kpi" | "table" | "custom";
        id: string;
        title: string;
        description?: string | undefined;
        config?: any;
        span?: {
            cols?: number | undefined;
            rows?: number | undefined;
        } | undefined;
    }>, "many">;
    refreshInterval: z.ZodOptional<z.ZodNumber>;
    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
        id: z.ZodString;
        type: z.ZodEnum<["date", "select", "multiselect", "range"]>;
        label: z.ZodString;
        value: z.ZodAny;
        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
            label: z.ZodString;
            value: z.ZodAny;
        }, "strip", z.ZodTypeAny, {
            label: string;
            value?: any;
        }, {
            label: string;
            value?: any;
        }>, "many">>;
    }, "strip", z.ZodTypeAny, {
        type: "date" | "select" | "multiselect" | "range";
        id: string;
        label: string;
        value?: any;
        options?: {
            label: string;
            value?: any;
        }[] | undefined;
    }, {
        type: "date" | "select" | "multiselect" | "range";
        id: string;
        label: string;
        value?: any;
        options?: {
            label: string;
            value?: any;
        }[] | undefined;
    }>, "many">>;
}, "strip", z.ZodTypeAny, {
    name: string;
    id: string;
    widgets: {
        type: "chart" | "kpi" | "table" | "custom";
        id: string;
        title: string;
        description?: string | undefined;
        config?: any;
        span?: {
            cols?: number | undefined;
            rows?: number | undefined;
        } | undefined;
    }[];
    refreshInterval?: number | undefined;
    filters?: {
        type: "date" | "select" | "multiselect" | "range";
        id: string;
        label: string;
        value?: any;
        options?: {
            label: string;
            value?: any;
        }[] | undefined;
    }[] | undefined;
}, {
    name: string;
    id: string;
    widgets: {
        type: "chart" | "kpi" | "table" | "custom";
        id: string;
        title: string;
        description?: string | undefined;
        config?: any;
        span?: {
            cols?: number | undefined;
            rows?: number | undefined;
        } | undefined;
    }[];
    refreshInterval?: number | undefined;
    filters?: {
        type: "date" | "select" | "multiselect" | "range";
        id: string;
        label: string;
        value?: any;
        options?: {
            label: string;
            value?: any;
        }[] | undefined;
    }[] | undefined;
}>;
declare const ExportConfigSchema: z.ZodObject<{
    format: z.ZodEnum<["pdf", "excel", "csv", "json"]>;
    filename: z.ZodOptional<z.ZodString>;
    data: z.ZodArray<z.ZodAny, "many">;
    columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
    title: z.ZodOptional<z.ZodString>;
    includeCharts: z.ZodOptional<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    format: "pdf" | "excel" | "csv" | "json";
    data: any[];
    title?: string | undefined;
    filename?: string | undefined;
    columns?: string[] | undefined;
    includeCharts?: boolean | undefined;
}, {
    format: "pdf" | "excel" | "csv" | "json";
    data: any[];
    title?: string | undefined;
    filename?: string | undefined;
    columns?: string[] | undefined;
    includeCharts?: boolean | undefined;
}>;
declare const AnalyticsRequestSchema: z.ZodObject<{
    endpoint: z.ZodString;
    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
    method: z.ZodOptional<z.ZodEnum<["GET", "POST"]>>;
    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    cache: z.ZodOptional<z.ZodEnum<["default", "no-store", "reload", "no-cache", "force-cache", "only-if-cached"]>>;
}, "strip", z.ZodTypeAny, {
    endpoint: string;
    params?: Record<string, any> | undefined;
    method?: "GET" | "POST" | undefined;
    headers?: Record<string, string> | undefined;
    cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached" | undefined;
}, {
    endpoint: string;
    params?: Record<string, any> | undefined;
    method?: "GET" | "POST" | undefined;
    headers?: Record<string, string> | undefined;
    cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached" | undefined;
}>;
declare function validateChartData(data: unknown[]): {
    name: string;
    value: number;
}[];
declare function validateKPI(metric: unknown): {
    value: string | number;
    id: string;
    label: string;
    currency?: string | undefined;
    format?: "number" | "currency" | "percentage" | "duration" | undefined;
    locale?: string | undefined;
    prefix?: string | undefined;
    suffix?: string | undefined;
    numberFormatOptions?: Record<string, any> | undefined;
    previousValue?: number | undefined;
    trend?: "up" | "down" | "neutral" | undefined;
    trendValue?: number | undefined;
    color?: string | undefined;
    icon?: any;
};
declare function validateKPIs(metrics: unknown[]): {
    value: string | number;
    id: string;
    label: string;
    currency?: string | undefined;
    format?: "number" | "currency" | "percentage" | "duration" | undefined;
    locale?: string | undefined;
    prefix?: string | undefined;
    suffix?: string | undefined;
    numberFormatOptions?: Record<string, any> | undefined;
    previousValue?: number | undefined;
    trend?: "up" | "down" | "neutral" | undefined;
    trendValue?: number | undefined;
    color?: string | undefined;
    icon?: any;
}[];
declare function validateChartConfig(config: unknown): {
    type: "line" | "bar" | "area" | "pie" | "donut" | "scatter" | "radar";
    data: any[];
    xKey?: string | undefined;
    yKey?: string | string[] | undefined;
    colors?: string[] | undefined;
    legend?: boolean | undefined;
    grid?: boolean | undefined;
    tooltip?: boolean | undefined;
    title?: string | undefined;
    subtitle?: string | undefined;
};
declare function validateDashboardLayout(layout: unknown): {
    name: string;
    id: string;
    widgets: {
        type: "chart" | "kpi" | "table" | "custom";
        id: string;
        title: string;
        description?: string | undefined;
        config?: any;
        span?: {
            cols?: number | undefined;
            rows?: number | undefined;
        } | undefined;
    }[];
    refreshInterval?: number | undefined;
    filters?: {
        type: "date" | "select" | "multiselect" | "range";
        id: string;
        label: string;
        value?: any;
        options?: {
            label: string;
            value?: any;
        }[] | undefined;
    }[] | undefined;
};
declare function validateExportConfig(config: unknown): {
    format: "pdf" | "excel" | "csv" | "json";
    data: any[];
    title?: string | undefined;
    filename?: string | undefined;
    columns?: string[] | undefined;
    includeCharts?: boolean | undefined;
};
declare function validateAnalyticsRequest(options: unknown): {
    endpoint: string;
    params?: Record<string, any> | undefined;
    method?: "GET" | "POST" | undefined;
    headers?: Record<string, string> | undefined;
    cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached" | undefined;
};
declare function safeValidate<T>(schema: z.ZodSchema<T>, data: unknown): {
    success: boolean;
    data?: T;
    errors?: z.ZodError;
};
declare function getValidationErrors(error: z.ZodError): string[];
declare function createValidationMonitor(): {
    validate: <T>(schema: z.ZodSchema<T>, data: unknown) => T;
    getStats: () => {
        averageValidationTime: number;
        successRate: number;
        totalValidations: number;
        failedValidations: number;
        totalValidationTime: number;
    };
    reset: () => void;
};
declare const validationMonitor: {
    validate: <T>(schema: z.ZodSchema<T>, data: unknown) => T;
    getStats: () => {
        averageValidationTime: number;
        successRate: number;
        totalValidations: number;
        failedValidations: number;
        totalValidationTime: number;
    };
    reset: () => void;
};

/**
 * @kodeme-io/next-core-analytics
 * Analytics, charts, dashboards, and reporting for Next.js applications
 * @version 0.5.0
 */

declare const version = "0.8.0";

export { type AggregationConfig, type AggregationType, AnalyticsErrorBoundary, AnalyticsRequestSchema, type ChartConfig, ChartConfigSchema, ChartContainer, type ChartDataPoint, ChartDataPointSchema, ChartErrorBoundary, type ChartType, type ComparisonConfig, type ComparisonData, Dashboard, DashboardErrorBoundary, type DashboardFilter, type DashboardLayout, DashboardLayoutSchema, type DashboardWidget, DashboardWidgetSchema, ExportButton, type ExportConfig, ExportConfigSchema, type ExportFormat, type FormatValueOptions, KPICard, type KPICardConfig, KPIErrorBoundary, type KPIMetric, KPIMetricSchema, type MultiSeriesDataPoint, MultiSeriesDataPointSchema, type TimeGranularity, type TimeSeriesConfig, aggregateData, calculateComparison, createFormatter, createValidationMonitor, currencyFormatters, formatDuration, formatTrendValue, formatValue, getValidationErrors, numberFormatters, percentageFormatters, processTimeSeries, safeValidate, useAnalytics, useErrorHandler, validateAnalyticsRequest, validateChartConfig, validateChartData, validateDashboardLayout, validateExportConfig, validateKPI, validateKPIs, validationMonitor, version };