@iota-big3/sdk-gateway

/** * Analytics & Metrics Type Definitions * * @module analytics-metrics-types * @description Comprehensive types for analytics and metrics including: * - Time-series data management * - Key Performance Indicators (KPIs) * - Business metrics and dashboards * - Reporting and visualization * - Real-time analytics * - Data aggregation and roll-ups * - Custom metrics and dimensions * - Alerting and anomaly detection * * Designed for scalable analytics and business intelligence */ import type { Brand } from './index'; /** Metric identifier */ export type MetricId = Brand<string, 'MetricId'>; /** Dashboard identifier */ export type DashboardId = Brand<string, 'DashboardId'>; /** Report identifier */ export type ReportId = Brand<string, 'ReportId'>; /** Time series identifier */ export type TimeSeriesId = Brand<string, 'TimeSeriesId'>; /** Alert identifier */ export type AlertId = Brand<string, 'AlertId'>; /** Dimension identifier */ export type DimensionId = Brand<string, 'DimensionId'>; /** Segment identifier */ export type SegmentId = Brand<string, 'SegmentId'>; /** * Time series data point */ export interface TimeSeriesPoint<T = number> { readonly timestamp: string; readonly value: T; readonly metadata?: Record<string, unknown>; readonly quality?: DataQuality; } /** * Data quality indicator */ export declare enum DataQuality { Good = "GOOD", Estimated = "ESTIMATED", Interpolated = "INTERPOLATED", Missing = "MISSING", Anomalous = "ANOMALOUS" } /** * Time series dataset */ export interface TimeSeries<T = number> { readonly seriesId: TimeSeriesId; readonly name: string; readonly description?: string; readonly metric: MetricDefinition; readonly points: TimeSeriesPoint<T>[]; readonly granularity: TimeGranularity; readonly dimensions?: Record<string, string>; readonly tags?: string[]; readonly metadata: TimeSeriesMetadata; } /** * Time granularity levels */ export declare enum TimeGranularity { Second = "SECOND", Minute = "MINUTE", FiveMinutes = "FIVE_MINUTES", FifteenMinutes = "FIFTEEN_MINUTES", Hour = "HOUR", Day = "DAY", Week = "WEEK", Month = "MONTH", Quarter = "QUARTER", Year = "YEAR" } /** * Time series metadata */ export interface TimeSeriesMetadata { readonly startTime: string; readonly endTime: string; readonly pointCount: number; readonly missingCount: number; readonly aggregationType?: AggregationType; readonly unit?: string; readonly timezone?: string; } /** * Aggregation types */ export declare enum AggregationType { Sum = "SUM", Average = "AVERAGE", Minimum = "MINIMUM", Maximum = "MAXIMUM", Count = "COUNT", CountDistinct = "COUNT_DISTINCT", Median = "MEDIAN", Percentile = "PERCENTILE", StandardDeviation = "STANDARD_DEVIATION", First = "FIRST", Last = "LAST" } /** * Metric definition */ export interface MetricDefinition { readonly metricId: MetricId; readonly name: string; readonly displayName: string; readonly description?: string; readonly type: MetricType; readonly category: MetricCategory; readonly unit?: MetricUnit; readonly formula?: MetricFormula; readonly dimensions?: DimensionDefinition[]; readonly metadata: MetricMetadata; } /** * Metric types */ export declare enum MetricType { Counter = "COUNTER",// Monotonically increasing Gauge = "GAUGE",// Can go up or down Histogram = "HISTOGRAM",// Distribution of values Summary = "SUMMARY",// Statistical summary Rate = "RATE",// Change over time Percentage = "PERCENTAGE",// 0-100 Currency = "CURRENCY",// Monetary values Duration = "DURATION" } /** * Metric categories */ export declare enum MetricCategory { Business = "BUSINESS", Technical = "TECHNICAL", Financial = "FINANCIAL", Customer = "CUSTOMER", Operational = "OPERATIONAL", Marketing = "MARKETING", Sales = "SALES", Support = "SUPPORT", Custom = "CUSTOM" } /** * Metric units */ export interface MetricUnit { readonly symbol: string; readonly name: string; readonly type: UnitType; readonly conversionFactor?: number; } /** * Unit types */ export declare enum UnitType { Count = "COUNT", Percentage = "PERCENTAGE", Currency = "CURRENCY", Bytes = "BYTES", Time = "TIME", Rate = "RATE", Custom = "CUSTOM" } /** * Metric formula for calculated metrics */ export interface MetricFormula { readonly expression: string; readonly variables: FormulaVariable[]; readonly aggregation?: AggregationType; } /** * Formula variable */ export interface FormulaVariable { readonly name: string; readonly metricId: MetricId; readonly aggregation?: AggregationType; readonly filters?: MetricFilter[]; } /** * Metric filter */ export interface MetricFilter { readonly dimension: string; readonly operator: FilterOperator; readonly value: unknown; } /** * Filter operators */ export declare enum FilterOperator { Equals = "EQUALS", NotEquals = "NOT_EQUALS", GreaterThan = "GREATER_THAN", LessThan = "LESS_THAN", GreaterThanOrEqual = "GREATER_THAN_OR_EQUAL", LessThanOrEqual = "LESS_THAN_OR_EQUAL", Contains = "CONTAINS", NotContains = "NOT_CONTAINS", StartsWith = "STARTS_WITH", EndsWith = "ENDS_WITH", In = "IN", NotIn = "NOT_IN", Between = "BETWEEN", IsNull = "IS_NULL", IsNotNull = "IS_NOT_NULL" } /** * Metric metadata */ export interface MetricMetadata { readonly createdAt: string; readonly updatedAt: string; readonly owner?: string; readonly dataSource?: string; readonly refreshInterval?: number; readonly retentionPeriod?: number; readonly visibility?: 'public' | 'private' | 'restricted'; readonly tags?: string[]; } /** * Dimension definition */ export interface DimensionDefinition { readonly dimensionId: DimensionId; readonly name: string; readonly displayName: string; readonly type: DimensionType; readonly cardinality?: number; readonly values?: DimensionValue[]; } /** * Dimension types */ export declare enum DimensionType { String = "STRING", Number = "NUMBER", Date = "DATE", Boolean = "BOOLEAN", Geography = "GEOGRAPHY", Category = "CATEGORY", Hierarchy = "HIERARCHY" } /** * Dimension value */ export interface DimensionValue { readonly value: unknown; readonly label: string; readonly order?: number; readonly parent?: unknown; readonly metadata?: Record<string, unknown>; } /** * Key Performance Indicator */ export interface KPI { readonly kpiId: string; readonly name: string; readonly description?: string; readonly metric: MetricDefinition; readonly target: KPITarget; readonly actual: KPIValue; readonly trend?: KPITrend; readonly status: KPIStatus; readonly period: TimePeriod; readonly segments?: KPISegment[]; readonly metadata: KPIMetadata; } /** * KPI target */ export interface KPITarget { readonly value: number; readonly type: TargetType; readonly tolerance?: number; readonly stretchGoal?: number; } /** * Target types */ export declare enum TargetType { Fixed = "FIXED", Percentage = "PERCENTAGE", Growth = "GROWTH", Reduction = "REDUCTION", Range = "RANGE" } /** * KPI value */ export interface KPIValue { readonly value: number; readonly timestamp: string; readonly confidence?: number; readonly isProjected?: boolean; } /** * KPI trend */ export interface KPITrend { readonly direction: TrendDirection; readonly change: number; readonly changeAbsolute: number; readonly timePeriod: string; readonly sparkline?: number[]; } /** * Trend directions */ export declare enum TrendDirection { Up = "UP", Down = "DOWN", Flat = "FLAT" } /** * KPI status */ export declare enum KPIStatus { OnTrack = "ON_TRACK", AtRisk = "AT_RISK", OffTrack = "OFF_TRACK", Exceeded = "EXCEEDED", NoData = "NO_DATA" } /** * Time period */ export interface TimePeriod { readonly start: string; readonly end: string; readonly type: PeriodType; readonly comparison?: TimePeriod; } /** * Period types */ export declare enum PeriodType { Custom = "CUSTOM", Today = "TODAY", Yesterday = "YESTERDAY", ThisWeek = "THIS_WEEK", LastWeek = "LAST_WEEK", ThisMonth = "THIS_MONTH", LastMonth = "LAST_MONTH", ThisQuarter = "THIS_QUARTER", LastQuarter = "LAST_QUARTER", ThisYear = "THIS_YEAR", LastYear = "LAST_YEAR", Last7Days = "LAST_7_DAYS", Last30Days = "LAST_30_DAYS", Last90Days = "LAST_90_DAYS" } /** * KPI segment */ export interface KPISegment { readonly segmentId: SegmentId; readonly name: string; readonly filters: MetricFilter[]; readonly value: KPIValue; readonly contribution?: number; } /** * KPI metadata */ export interface KPIMetadata { readonly owner: string; readonly department?: string; readonly priority: 'low' | 'medium' | 'high' | 'critical'; readonly reviewFrequency?: string; readonly lastReviewed?: string; readonly notes?: string; readonly relatedKPIs?: string[]; } /** * Analytics dashboard */ export interface Dashboard { readonly dashboardId: DashboardId; readonly name: string; readonly description?: string; readonly layout: DashboardLayout; readonly widgets: Widget[]; readonly filters?: DashboardFilter[]; readonly refreshInterval?: number; readonly metadata: DashboardMetadata; } /** * Dashboard layout */ export interface DashboardLayout { readonly type: LayoutType; readonly columns?: number; readonly rows?: number; readonly responsive?: boolean; readonly breakpoints?: LayoutBreakpoint[]; } /** * Layout types */ export declare enum LayoutType { Grid = "GRID", Flex = "FLEX", Fixed = "FIXED", Masonry = "MASONRY" } /** * Layout breakpoint */ export interface LayoutBreakpoint { readonly width: number; readonly columns: number; } /** * Dashboard widget */ export interface Widget { readonly widgetId: string; readonly type: WidgetType; readonly title: string; readonly subtitle?: string; readonly config: WidgetConfig; readonly position: WidgetPosition; readonly size: WidgetSize; readonly interactions?: WidgetInteraction[]; } /** * Widget types */ export declare enum WidgetType { LineChart = "LINE_CHART", BarChart = "BAR_CHART", PieChart = "PIE_CHART", AreaChart = "AREA_CHART", ScatterPlot = "SCATTER_PLOT", Heatmap = "HEATMAP", Gauge = "GAUGE", Metric = "METRIC", KPICard = "KPI_CARD", Sparkline = "SPARKLINE", Table = "TABLE", PivotTable = "PIVOT_TABLE", GeoMap = "GEO_MAP", HeatMap = "HEAT_MAP", Text = "TEXT", Image = "IMAGE", Filter = "FILTER" } /** * Widget configuration */ export interface WidgetConfig { readonly data: WidgetDataSource; readonly visualization?: VisualizationConfig; readonly filters?: MetricFilter[]; readonly thresholds?: Threshold[]; readonly actions?: WidgetAction[]; } /** * Widget data source */ export type WidgetDataSource = { type: 'metric'; metricId: MetricId; } | { type: 'kpi'; kpiId: string; } | { type: 'query'; query: AnalyticsQuery; } | { type: 'static'; data: unknown; }; /** * Visualization configuration */ export interface VisualizationConfig { readonly colors?: string[]; readonly legend?: LegendConfig; readonly axes?: AxesConfig; readonly animation?: boolean; readonly tooltips?: boolean; readonly style?: Record<string, unknown>; } /** * Legend configuration */ export interface LegendConfig { readonly show: boolean; readonly position: 'top' | 'bottom' | 'left' | 'right'; readonly alignment?: 'start' | 'center' | 'end'; } /** * Axes configuration */ export interface AxesConfig { readonly x?: AxisConfig; readonly y?: AxisConfig; } /** * Axis configuration */ export interface AxisConfig { readonly label?: string; readonly type?: 'linear' | 'logarithmic' | 'category' | 'time'; readonly min?: number; readonly max?: number; readonly format?: string; } /** * Threshold definition */ export interface Threshold { readonly value: number; readonly color?: string; readonly label?: string; readonly comparison: ComparisonOperator; } /** * Comparison operators */ export declare enum ComparisonOperator { GreaterThan = ">", LessThan = "<", GreaterThanOrEqual = ">=", LessThanOrEqual = "<=", Equal = "=", NotEqual = "!=" } /** * Widget position */ export interface WidgetPosition { readonly x: number; readonly y: number; readonly z?: number; } /** * Widget size */ export interface WidgetSize { readonly width: number; readonly height: number; readonly minWidth?: number; readonly minHeight?: number; readonly maxWidth?: number; readonly maxHeight?: number; } /** * Widget interaction */ export interface WidgetInteraction { readonly type: InteractionType; readonly target?: string; readonly config?: Record<string, unknown>; } /** * Interaction types */ export declare enum InteractionType { Click = "CLICK", Hover = "HOVER", Drill = "DRILL", Filter = "FILTER", Export = "EXPORT", Share = "SHARE" } /** * Widget action */ export interface WidgetAction { readonly type: 'navigate' | 'filter' | 'export' | 'custom'; readonly label: string; readonly config: Record<string, unknown>; } /** * Dashboard filter */ export interface DashboardFilter { readonly filterId: string; readonly dimension: string; readonly displayName: string; readonly type: FilterType; readonly config: FilterConfig; readonly defaultValue?: unknown; readonly required?: boolean; } /** * Filter types */ export declare enum FilterType { Dropdown = "DROPDOWN", MultiSelect = "MULTI_SELECT", DateRange = "DATE_RANGE", NumberRange = "NUMBER_RANGE", Search = "SEARCH", Toggle = "TOGGLE" } /** * Filter configuration */ export interface FilterConfig { readonly options?: FilterOption[]; readonly dataSource?: string; readonly cascading?: boolean; readonly placeholder?: string; } /** * Filter option */ export interface FilterOption { readonly value: unknown; readonly label: string; readonly selected?: boolean; } /** * Dashboard metadata */ export interface DashboardMetadata { readonly createdAt: string; readonly updatedAt: string; readonly createdBy: string; readonly updatedBy?: string; readonly version: number; readonly tags?: string[]; readonly category?: string; readonly audience?: string[]; readonly favorite?: boolean; readonly shared?: boolean; readonly permissions?: DashboardPermission[]; } /** * Dashboard permission */ export interface DashboardPermission { readonly principal: string; readonly role: 'viewer' | 'editor' | 'owner'; readonly grantedAt: string; readonly grantedBy: string; } /** * Analytics report */ export interface Report { readonly reportId: ReportId; readonly name: string; readonly description?: string; readonly type: ReportType; readonly sections: ReportSection[]; readonly parameters?: ReportParameter[]; readonly schedule?: ReportSchedule; readonly distribution?: ReportDistribution; readonly metadata: ReportMetadata; } /** * Report types */ export declare enum ReportType { Executive = "EXECUTIVE", Operational = "OPERATIONAL", Financial = "FINANCIAL", Compliance = "COMPLIANCE", Performance = "PERFORMANCE", Custom = "CUSTOM" } /** * Report section */ export interface ReportSection { readonly sectionId: string; readonly title: string; readonly type: SectionType; readonly content: SectionContent; readonly order: number; readonly pageBreak?: boolean; } /** * Section types */ export declare enum SectionType { Header = "HEADER", Summary = "SUMMARY", Chart = "CHART", Table = "TABLE", Text = "TEXT", PageBreak = "PAGE_BREAK", Footer = "FOOTER" } /** * Section content */ export type SectionContent = { type: 'text'; content: string; format?: 'plain' | 'markdown' | 'html'; } | { type: 'metric'; metricId: MetricId; visualization?: WidgetType; } | { type: 'dashboard'; dashboardId: DashboardId; } | { type: 'query'; query: AnalyticsQuery; visualization?: WidgetType; }; /** * Report parameter */ export interface ReportParameter { readonly name: string; readonly type: ParameterType; readonly displayName: string; readonly required: boolean; readonly defaultValue?: unknown; readonly options?: ParameterOption[]; } /** * Parameter types */ export declare enum ParameterType { String = "STRING", Number = "NUMBER", Date = "DATE", DateRange = "DATE_RANGE", Boolean = "BOOLEAN", Select = "SELECT", MultiSelect = "MULTI_SELECT" } /** * Parameter option */ export interface ParameterOption { readonly value: unknown; readonly label: string; } /** * Report schedule */ export interface ReportSchedule { readonly frequency: ScheduleFrequency; readonly time?: string; readonly dayOfWeek?: number; readonly dayOfMonth?: number; readonly timezone?: string; readonly active: boolean; readonly nextRun?: string; } /** * Schedule frequencies */ export declare enum ScheduleFrequency { Once = "ONCE", Hourly = "HOURLY", Daily = "DAILY", Weekly = "WEEKLY", BiWeekly = "BI_WEEKLY", Monthly = "MONTHLY", Quarterly = "QUARTERLY", Yearly = "YEARLY" } /** * Report distribution */ export interface ReportDistribution { readonly recipients: Recipient[]; readonly format: ReportFormat[]; readonly channel: DistributionChannel; readonly includeData?: boolean; readonly password?: boolean; } /** * Recipient */ export interface Recipient { readonly type: 'user' | 'group' | 'email'; readonly id: string; readonly role?: 'to' | 'cc' | 'bcc'; } /** * Report formats */ export declare enum ReportFormat { PDF = "PDF", Excel = "EXCEL", CSV = "CSV", PowerPoint = "POWERPOINT", HTML = "HTML", JSON = "JSON" } /** * Distribution channels */ export declare enum DistributionChannel { Email = "EMAIL", Slack = "SLACK", Teams = "TEAMS", Webhook = "WEBHOOK", FileShare = "FILE_SHARE", API = "API" } /** * Report metadata */ export interface ReportMetadata { readonly createdAt: string; readonly updatedAt: string; readonly createdBy: string; readonly lastGenerated?: string; readonly generationCount: number; readonly averageGenerationTime?: number; readonly tags?: string[]; readonly category?: string; readonly confidentiality?: 'public' | 'internal' | 'confidential' | 'restricted'; } /** * Analytics query */ export interface AnalyticsQuery { readonly queryId?: string; readonly name?: string; readonly metrics: MetricDefinition[]; readonly dimensions?: string[]; readonly filters?: QueryFilter[]; readonly groupBy?: string[]; readonly orderBy?: OrderBy[]; readonly limit?: number; readonly timeRange?: TimeRange; } /** * Query filter */ export interface QueryFilter { readonly field: string; readonly operator: FilterOperator; readonly value: unknown; readonly combinator?: 'AND' | 'OR'; } /** * Order by clause */ export interface OrderBy { readonly field: string; readonly direction: 'ASC' | 'DESC'; } /** * Time range */ export interface TimeRange { readonly type: 'absolute' | 'relative'; readonly start?: string; readonly end?: string; readonly duration?: string; readonly offset?: string; } /** * Analytics alert */ export interface Alert { readonly alertId: AlertId; readonly name: string; readonly description?: string; readonly condition: AlertCondition; readonly actions: AlertAction[]; readonly schedule: AlertSchedule; readonly status: AlertStatus; readonly metadata: AlertMetadata; } /** * Alert condition */ export interface AlertCondition { readonly metric: MetricDefinition; readonly threshold: Threshold; readonly duration?: string; readonly aggregation?: AggregationType; readonly filters?: MetricFilter[]; } /** * Alert action */ export interface AlertAction { readonly type: AlertActionType; readonly config: Record<string, unknown>; readonly cooldown?: number; } /** * Alert action types */ export declare enum AlertActionType { Email = "EMAIL", SMS = "SMS", Slack = "SLACK", Webhook = "WEBHOOK", PagerDuty = "PAGER_DUTY", Custom = "CUSTOM" } /** * Alert schedule */ export interface AlertSchedule { readonly checkInterval: number; readonly activeHours?: { readonly start: string; readonly end: string; readonly timezone: string; readonly days?: number[]; }; } /** * Alert status */ export declare enum AlertStatus { Active = "ACTIVE", Triggered = "TRIGGERED", Resolved = "RESOLVED", Disabled = "DISABLED", Error = "ERROR" } /** * Alert metadata */ export interface AlertMetadata { readonly createdAt: string; readonly updatedAt: string; readonly createdBy: string; readonly lastTriggered?: string; readonly triggerCount: number; readonly falsePositiveCount?: number; readonly tags?: string[]; readonly severity: 'low' | 'medium' | 'high' | 'critical'; } /** * Calculate time series statistics */ export declare function calculateTimeSeriesStats<T extends number>(series: TimeSeriesPoint<T>[]): TimeSeriesStatistics; /** * Time series statistics */ export interface TimeSeriesStatistics { readonly count: number; readonly min: number; readonly max: number; readonly mean: number; readonly median: number; readonly stdDev: number; readonly sum: number; } /** * Check if KPI is meeting target */ export declare function isKPIMeetingTarget(kpi: KPI): boolean; /** * Calculate metric aggregation */ export declare function aggregateMetricValues(values: number[], type: AggregationType): number; export declare const analyticsMetricsTypes: { DataQuality: typeof DataQuality; TimeGranularity: typeof TimeGranularity; AggregationType: typeof AggregationType; MetricType: typeof MetricType; MetricCategory: typeof MetricCategory; UnitType: typeof UnitType; FilterOperator: typeof FilterOperator; DimensionType: typeof DimensionType; TargetType: typeof TargetType; TrendDirection: typeof TrendDirection; KPIStatus: typeof KPIStatus; PeriodType: typeof PeriodType; LayoutType: typeof LayoutType; WidgetType: typeof WidgetType; ComparisonOperator: typeof ComparisonOperator; InteractionType: typeof InteractionType; FilterType: typeof FilterType; ReportType: typeof ReportType; SectionType: typeof SectionType; ParameterType: typeof ParameterType; ScheduleFrequency: typeof ScheduleFrequency; ReportFormat: typeof ReportFormat; DistributionChannel: typeof DistributionChannel; AlertActionType: typeof AlertActionType; AlertStatus: typeof AlertStatus; calculateTimeSeriesStats: typeof calculateTimeSeriesStats; isKPIMeetingTarget: typeof isKPIMeetingTarget; aggregateMetricValues: typeof aggregateMetricValues; }; //# sourceMappingURL=analytics-metrics-types.d.ts.map