@k-msg/analytics 0.1.1 → 0.1.3

package/dist/aggregators/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Aggregators - 데이터 집계 컴포넌트들
+ */
+export { type AggregationRule, type AggregatorConfig, MetricAggregator, } from "./metric.aggregator";
+export { type AggregationOptions, TimeSeriesAggregator, type TimeWindow, } from "./time-series.aggregator";

package/dist/aggregators/metric.aggregator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Metric Aggregator
+ * 메트릭별 특화 집계 로직
+ */
+import type { AggregatedMetric, MetricData } from "../types/analytics.types";
+import { MetricType } from "../types/analytics.types";
+export interface AggregationRule {
+    metricType: MetricType;
+    aggregationType: "sum" | "avg" | "min" | "max" | "count" | "rate" | "percentile";
+    dimensions: string[];
+    conditions?: Array<{
+        field: string;
+        operator: "equals" | "not_equals" | "gt" | "lt" | "contains";
+        value: any;
+    }>;
+    percentile?: number;
+}
+export interface AggregatorConfig {
+    rules: AggregationRule[];
+    batchSize: number;
+    flushInterval: number;
+}
+export declare class MetricAggregator {
+    private config;
+    private buffer;
+    private aggregationCache;
+    constructor(config: AggregatorConfig);
+    /**
+     * 메트릭 추가 및 실시간 집계
+     */
+    addMetric(metric: MetricData): Promise<void>;
+    /**
+     * 배치 메트릭 처리
+     */
+    addMetrics(metrics: MetricData[]): Promise<void>;
+    /**
+     * 규칙 기반 집계 실행
+     */
+    aggregateByRules(metrics: MetricData[]): Promise<AggregatedMetric[]>;
+    /**
+     * 커스텀 집계 (동적 규칙)
+     */
+    aggregateCustom(metrics: MetricData[], groupBy: string[], aggregationType: "sum" | "avg" | "min" | "max" | "count" | "rate", filters?: Record<string, any>): Promise<AggregatedMetric[]>;
+    /**
+     * 비율 계산 (예: 전환율, 오류율)
+     */
+    calculateRates(numeratorMetrics: MetricData[], denominatorMetrics: MetricData[], groupBy?: string[]): Promise<AggregatedMetric[]>;
+    /**
+     * 백분위수 계산
+     */
+    calculatePercentiles(metrics: MetricData[], percentiles: number[], groupBy?: string[]): Promise<AggregatedMetric[]>;
+    /**
+     * 슬라이딩 윈도우 집계
+     */
+    aggregateSlidingWindow(metrics: MetricData[], windowSizeMs: number, stepMs: number, aggregationType: "sum" | "avg" | "min" | "max" | "count"): Promise<AggregatedMetric[]>;
+    /**
+     * 메트릭 정규화
+     */
+    normalizeMetrics(metrics: AggregatedMetric[], method: "minmax" | "zscore" | "robust"): Promise<AggregatedMetric[]>;
+    private getBufferKey;
+    private flushBuffer;
+    private filterMetricsByRule;
+    private applyAggregationRule;
+    private groupMetrics;
+    private createGroupKey;
+    private getFieldValue;
+    private evaluateCondition;
+    private performAggregation;
+    private applyFilters;
+    private calculatePercentile;
+    private minMaxNormalize;
+    private zScoreNormalize;
+    private robustNormalize;
+    private calculateMAD;
+    private startPeriodicFlush;
+}

package/dist/aggregators/time-series.aggregator.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Time Series Data Aggregator
+ * 시계열 데이터 집계 및 다운샘플링
+ */
+import type { AggregatedMetric, MetricData } from "../types/analytics.types";
+export interface TimeWindow {
+    start: Date;
+    end: Date;
+    interval: "minute" | "hour" | "day" | "week" | "month";
+}
+export interface AggregationOptions {
+    fillGaps: boolean;
+    fillValue: number;
+    timezone?: string;
+}
+export declare class TimeSeriesAggregator {
+    private timezone;
+    constructor(timezone?: string);
+    /**
+     * 시계열 데이터를 지정된 간격으로 집계
+     */
+    aggregate(metrics: MetricData[], interval: "minute" | "hour" | "day" | "week" | "month", options?: AggregationOptions): Promise<AggregatedMetric[]>;
+    /**
+     * 롤링 윈도우 집계
+     */
+    aggregateRolling(metrics: MetricData[], windowSize: number, // 분 단위
+    step?: number): Promise<AggregatedMetric[]>;
+    /**
+     * 계절성 분해 (간단한 이동평균 기반)
+     */
+    decomposeSeasonality(metrics: AggregatedMetric[], seasonLength?: number): Promise<{
+        trend: AggregatedMetric[];
+        seasonal: AggregatedMetric[];
+        residual: AggregatedMetric[];
+    }>;
+    /**
+     * 다운샘플링 (고해상도 → 저해상도)
+     */
+    downsample(metrics: AggregatedMetric[], targetInterval: "minute" | "hour" | "day" | "week" | "month"): Promise<AggregatedMetric[]>;
+    private groupByType;
+    private groupByDimensions;
+    private aggregateByInterval;
+    private groupByTimeInterval;
+    private getTimeIntervalKey;
+    private fillTimeGaps;
+    private calculateAggregations;
+    private aggregateWindow;
+    private calculateMovingAverage;
+    private calculateSeasonalComponent;
+    private calculateResidual;
+}

package/dist/collectors/event.collector.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Event Collector
+ * 실시간 이벤트 수집 및 메트릭 변환
+ */
+import { EventEmitter } from "events";
+import type { MetricData } from "../types/analytics.types";
+export interface EventData {
+    id: string;
+    type: string;
+    timestamp: Date;
+    source: string;
+    payload: Record<string, any>;
+    context?: {
+        userId?: string;
+        sessionId?: string;
+        requestId?: string;
+        userAgent?: string;
+        ipAddress?: string;
+    };
+}
+export interface EventCollectorConfig {
+    bufferSize: number;
+    flushInterval: number;
+    enableDeduplication: boolean;
+    deduplicationWindow: number;
+    enableSampling: boolean;
+    samplingRate: number;
+}
+export interface EventProcessor {
+    canProcess(event: EventData): boolean;
+    process(event: EventData): Promise<MetricData[]>;
+}
+export declare class EventCollector extends EventEmitter {
+    private config;
+    private buffer;
+    private processors;
+    private recentEvents;
+    private metrics;
+    private defaultConfig;
+    constructor(config?: Partial<EventCollectorConfig>);
+    /**
+     * 이벤트 수집
+     */
+    collectEvent(event: EventData): Promise<void>;
+    /**
+     * 배치 이벤트 수집
+     */
+    collectEvents(events: EventData[]): Promise<void>;
+    /**
+     * 커스텀 이벤트 프로세서 등록
+     */
+    registerProcessor(name: string, processor: EventProcessor): void;
+    /**
+     * 이벤트 프로세서 제거
+     */
+    unregisterProcessor(name: string): boolean;
+    /**
+     * 수집된 메트릭 조회
+     */
+    getCollectedMetrics(since?: Date): MetricData[];
+    /**
+     * 실시간 메트릭 스트림
+     */
+    streamMetrics(): AsyncGenerator<MetricData[]>;
+    /**
+     * 이벤트 통계
+     */
+    getEventStats(): {
+        totalEvents: number;
+        eventsByType: Record<string, number>;
+        eventsBySource: Record<string, number>;
+        bufferSize: number;
+        metricsGenerated: number;
+    };
+    /**
+     * 버퍼 강제 플러시
+     */
+    flush(): Promise<void>;
+    private processEvent;
+    private validateEvent;
+    private isDuplicate;
+    private isHighPriorityEvent;
+    private initializeDefaultProcessors;
+    private startPeriodicFlush;
+    private startCleanup;
+}

package/dist/collectors/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Collectors - 데이터 수집 컴포넌트들
+ */
+export { EventCollector, type EventCollectorConfig, type EventData, type EventProcessor, } from "./event.collector";
+export { WebhookCollector, type WebhookCollectorConfig, type WebhookData, } from "./webhook.collector";

package/dist/collectors/webhook.collector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Webhook Collector
+ * 웹훅을 통한 외부 이벤트 수집
+ */
+import { EventEmitter } from "events";
+import type { EventData } from "./event.collector";
+export interface WebhookData {
+    id: string;
+    source: string;
+    timestamp: Date;
+    headers: Record<string, string>;
+    body: any;
+    signature?: string;
+}
+export interface WebhookCollectorConfig {
+    enableSignatureValidation: boolean;
+    signatureHeader: string;
+    secretKey?: string;
+    allowedSources: string[];
+    maxPayloadSize: number;
+    rateLimitPerMinute: number;
+}
+export interface WebhookTransformer {
+    canTransform(webhook: WebhookData): boolean;
+    transform(webhook: WebhookData): Promise<EventData[]>;
+}
+export declare class WebhookCollector extends EventEmitter {
+    private config;
+    private transformers;
+    private requestCounts;
+    private processedWebhooks;
+    private defaultConfig;
+    constructor(config?: Partial<WebhookCollectorConfig>);
+    /**
+     * 웹훅 수신 처리
+     */
+    receiveWebhook(webhook: WebhookData): Promise<EventData[]>;
+    /**
+     * 웹훅 변환기 등록
+     */
+    registerTransformer(name: string, transformer: WebhookTransformer): void;
+    /**
+     * 웹훅 변환기 제거
+     */
+    unregisterTransformer(name: string): boolean;
+    /**
+     * 처리된 웹훅 조회
+     */
+    getProcessedWebhooks(since?: Date): WebhookData[];
+    /**
+     * 웹훅 통계
+     */
+    getWebhookStats(): {
+        totalProcessed: number;
+        bySource: Record<string, number>;
+        recentCount: number;
+        transformerCount: number;
+    };
+    private validateWebhook;
+    private validateSignature;
+    private generateSignature;
+    private checkRateLimit;
+    private transformWebhook;
+    private defaultTransform;
+    private initializeDefaultTransformers;
+    private startCleanup;
+}