@k-msg/webhook 0.1.0 → 0.1.2

package/dist/registry/delivery.store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Delivery Store
+ * 웹훅 전달 기록 저장 및 관리
+ */
+import { EventEmitter } from "events";
+import type { WebhookDelivery } from "../types/webhook.types";
+import type { DeliveryFilter, PaginationOptions, SearchResult, StorageConfig } from "./types";
+export declare class DeliveryStore extends EventEmitter {
+    private config;
+    private deliveries;
+    private indexByEndpoint;
+    private indexByStatus;
+    private indexByDate;
+    private cleanupInterval;
+    private defaultConfig;
+    constructor(config?: Partial<StorageConfig>);
+    /**
+     * 전달 기록 저장
+     */
+    saveDelivery(delivery: WebhookDelivery): Promise<void>;
+    /**
+     * 전달 기록 조회
+     */
+    getDelivery(deliveryId: string): Promise<WebhookDelivery | null>;
+    /**
+     * 필터 조건에 맞는 전달 기록 검색
+     */
+    searchDeliveries(filter?: DeliveryFilter, pagination?: PaginationOptions): Promise<SearchResult<WebhookDelivery>>;
+    /**
+     * 엔드포인트별 전달 기록 조회
+     */
+    getDeliveriesByEndpoint(endpointId: string, limit?: number): Promise<WebhookDelivery[]>;
+    /**
+     * 실패한 전달 기록 조회
+     */
+    getFailedDeliveries(endpointId?: string, limit?: number): Promise<WebhookDelivery[]>;
+    /**
+     * 전달 통계 조회
+     */
+    getDeliveryStats(endpointId?: string, timeRange?: {
+        start: Date;
+        end: Date;
+    }): Promise<{
+        totalDeliveries: number;
+        successfulDeliveries: number;
+        failedDeliveries: number;
+        pendingDeliveries: number;
+        exhaustedDeliveries: number;
+        averageLatency: number;
+        successRate: number;
+        errorBreakdown: Record<string, number>;
+    }>;
+    /**
+     * 오래된 전달 기록 정리
+     */
+    cleanupOldDeliveries(): Promise<number>;
+    /**
+     * 저장소 통계 조회
+     */
+    getStorageStats(): {
+        totalDeliveries: number;
+        memoryUsage: number;
+        indexSizes: {
+            byEndpoint: number;
+            byStatus: number;
+            byDate: number;
+        };
+    };
+    /**
+     * 인덱스 초기화
+     */
+    private initializeIndexes;
+    /**
+     * 인덱스에 전달 기록 추가
+     */
+    private addToIndexes;
+    /**
+     * 인덱스에서 전달 기록 제거
+     */
+    private removeFromIndexes;
+    /**
+     * 날짜 범위로 전달 기록 ID 조회
+     */
+    private getDeliveryIdsByDateRange;
+    /**
+     * 필터 조건 매칭 확인
+     */
+    private matchesFilter;
+    /**
+     * 객체 필드 값 가져오기
+     */
+    private getFieldValue;
+    /**
+     * 메모리 사용량 추정
+     */
+    private estimateMemoryUsage;
+    /**
+     * 메모리 사용량 확인 및 정리
+     */
+    private checkMemoryUsage;
+    /**
+     * 정리 작업 시작
+     */
+    private startCleanupTask;
+    /**
+     * 파일에 전달 기록 추가
+     */
+    private appendToFile;
+    /**
+     * 파일에서 데이터 로드
+     */
+    private loadFromFile;
+    /**
+     * 파일에 데이터 저장
+     */
+    private saveToFile;
+    /**
+     * 전달 저장소 종료
+     */
+    shutdown(): Promise<void>;
+}

package/dist/registry/endpoint.manager.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Endpoint Manager
+ * 웹훅 엔드포인트 관리를 위한 고급 기능 제공
+ */
+import { EventEmitter } from "events";
+import type { WebhookEndpoint } from "../types/webhook.types";
+import { WebhookEventType } from "../types/webhook.types";
+import type { EndpointFilter, PaginationOptions, SearchResult, StorageConfig } from "./types";
+export declare class EndpointManager extends EventEmitter {
+    private config;
+    private endpoints;
+    private indexByUrl;
+    private indexByEvent;
+    private indexByStatus;
+    private defaultConfig;
+    constructor(config?: Partial<StorageConfig>);
+    /**
+     * 엔드포인트 추가
+     */
+    addEndpoint(endpoint: WebhookEndpoint): Promise<void>;
+    /**
+     * 엔드포인트 업데이트
+     */
+    updateEndpoint(endpointId: string, updates: Partial<WebhookEndpoint>): Promise<WebhookEndpoint>;
+    /**
+     * 엔드포인트 제거
+     */
+    removeEndpoint(endpointId: string): Promise<boolean>;
+    /**
+     * 엔드포인트 조회
+     */
+    getEndpoint(endpointId: string): Promise<WebhookEndpoint | null>;
+    /**
+     * URL로 엔드포인트 조회
+     */
+    getEndpointByUrl(url: string): Promise<WebhookEndpoint | null>;
+    /**
+     * 필터 조건에 맞는 엔드포인트 검색
+     */
+    searchEndpoints(filter?: EndpointFilter, pagination?: PaginationOptions): Promise<SearchResult<WebhookEndpoint>>;
+    /**
+     * 특정 이벤트 타입을 구독하는 활성 엔드포인트 조회
+     */
+    getActiveEndpointsForEvent(eventType: WebhookEventType): Promise<WebhookEndpoint[]>;
+    /**
+     * 엔드포인트 통계 조회
+     */
+    getStats(): {
+        totalEndpoints: number;
+        activeEndpoints: number;
+        inactiveEndpoints: number;
+        errorEndpoints: number;
+        suspendedEndpoints: number;
+        eventSubscriptions: Record<WebhookEventType, number>;
+    };
+    /**
+     * 만료된 엔드포인트 정리
+     */
+    cleanupExpiredEndpoints(): Promise<number>;
+    /**
+     * 인덱스 초기화
+     */
+    private initializeIndexes;
+    /**
+     * 인덱스에 엔드포인트 추가
+     */
+    private addToIndexes;
+    /**
+     * 인덱스에서 엔드포인트 제거
+     */
+    private removeFromIndexes;
+    /**
+     * 필터 조건 매칭 확인
+     */
+    private matchesFilter;
+    /**
+     * 객체 필드 값 가져오기 (정렬용)
+     */
+    private getFieldValue;
+    /**
+     * 파일에서 데이터 로드
+     */
+    private loadFromFile;
+    /**
+     * 파일에 데이터 저장
+     */
+    private saveToFile;
+    /**
+     * 엔드포인트 관리자 종료
+     */
+    shutdown(): Promise<void>;
+}

package/dist/registry/event.store.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Event Store
+ * 웹훅 이벤트 저장 및 관리
+ */
+import { EventEmitter } from "events";
+import type { WebhookEvent } from "../types/webhook.types";
+import { WebhookEventType } from "../types/webhook.types";
+import type { EventFilter, PaginationOptions, SearchResult, StorageConfig } from "./types";
+export declare class EventStore extends EventEmitter {
+    private config;
+    private events;
+    private indexByType;
+    private indexByDate;
+    private indexByProvider;
+    private indexByChannel;
+    private cleanupInterval;
+    private defaultConfig;
+    constructor(config?: Partial<StorageConfig>);
+    /**
+     * 이벤트 저장
+     */
+    saveEvent(event: WebhookEvent): Promise<void>;
+    /**
+     * 이벤트 조회
+     */
+    getEvent(eventId: string): Promise<WebhookEvent | null>;
+    /**
+     * 필터 조건에 맞는 이벤트 검색
+     */
+    searchEvents(filter?: EventFilter, pagination?: PaginationOptions): Promise<SearchResult<WebhookEvent>>;
+    /**
+     * 이벤트 타입별 조회
+     */
+    getEventsByType(eventType: WebhookEventType, limit?: number): Promise<WebhookEvent[]>;
+    /**
+     * 이벤트 통계 조회
+     */
+    getEventStats(timeRange?: {
+        start: Date;
+        end: Date;
+    }): Promise<{
+        totalEvents: number;
+        eventsByType: Record<WebhookEventType, number>;
+        eventsByProvider: Record<string, number>;
+        eventsByChannel: Record<string, number>;
+        eventsPerHour: Record<string, number>;
+    }>;
+    /**
+     * 오래된 이벤트 정리
+     */
+    cleanupOldEvents(): Promise<number>;
+    /**
+     * 중복 이벤트 정리
+     */
+    cleanupDuplicateEvents(): Promise<number>;
+    /**
+     * 저장소 통계 조회
+     */
+    getStorageStats(): {
+        totalEvents: number;
+        memoryUsage: number;
+        indexSizes: {
+            byType: number;
+            byDate: number;
+            byProvider: number;
+            byChannel: number;
+        };
+    };
+    /**
+     * 인덱스 초기화
+     */
+    private initializeIndexes;
+    /**
+     * 인덱스에 이벤트 추가
+     */
+    private addToIndexes;
+    /**
+     * 인덱스에서 이벤트 제거
+     */
+    private removeFromIndexes;
+    /**
+     * 날짜 범위로 이벤트 ID 조회
+     */
+    private getEventIdsByDateRange;
+    /**
+     * 필터 조건 매칭 확인
+     */
+    private matchesFilter;
+    /**
+     * 객체 필드 값 가져오기
+     */
+    private getFieldValue;
+    /**
+     * 메모리 사용량 추정
+     */
+    private estimateMemoryUsage;
+    /**
+     * 메모리 사용량 확인 및 정리
+     */
+    private checkMemoryUsage;
+    /**
+     * 이벤트 내용 키 생성 (중복 검사용)
+     */
+    private generateContentKey;
+    /**
+     * 정리 작업 시작
+     */
+    private startCleanupTask;
+    /**
+     * 파일에 이벤트 추가
+     */
+    private appendToFile;
+    /**
+     * 파일에서 데이터 로드
+     */
+    private loadFromFile;
+    /**
+     * 파일에 데이터 저장
+     */
+    private saveToFile;
+    /**
+     * 이벤트 저장소 종료
+     */
+    shutdown(): Promise<void>;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Webhook Registry Components
+ * 웹훅 엔드포인트 및 전달 기록 관리 관련 컴포넌트들
+ */
+export { WebhookRegistry } from "../services/webhook.registry";
+export { DeliveryStore } from "./delivery.store";
+export { EndpointManager } from "./endpoint.manager";
+export { EventStore } from "./event.store";
+export type { DeliveryFilter, EndpointFilter, EventFilter, PaginationOptions, SearchResult, StorageConfig, } from "./types";

package/dist/registry/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Registry Type Definitions
+ */
+import type { WebhookEventType } from "../types/webhook.types";
+export interface EndpointFilter {
+    status?: "active" | "inactive" | "error" | "suspended";
+    events?: WebhookEventType[];
+    providerId?: string[];
+    channelId?: string[];
+    createdAfter?: Date;
+    createdBefore?: Date;
+    lastTriggeredAfter?: Date;
+    lastTriggeredBefore?: Date;
+}
+export interface DeliveryFilter {
+    endpointId?: string;
+    eventId?: string;
+    status?: "pending" | "success" | "failed" | "exhausted";
+    createdAfter?: Date;
+    createdBefore?: Date;
+    completedAfter?: Date;
+    completedBefore?: Date;
+    httpStatusCode?: number[];
+    hasError?: boolean;
+}
+export interface EventFilter {
+    type?: WebhookEventType[];
+    providerId?: string[];
+    channelId?: string[];
+    templateId?: string[];
+    messageId?: string[];
+    userId?: string[];
+    organizationId?: string[];
+    createdAfter?: Date;
+    createdBefore?: Date;
+}
+export interface StorageConfig {
+    type: "memory" | "file" | "database";
+    filePath?: string;
+    enableCompression?: boolean;
+    maxFileSize?: number;
+    connectionString?: string;
+    tableName?: string;
+    maxMemoryUsage?: number;
+    retentionDays?: number;
+    enableEncryption?: boolean;
+    encryptionKey?: string;
+}
+export interface PaginationOptions {
+    page: number;
+    limit: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+}
+export interface SearchResult<T> {
+    items: T[];
+    totalCount: number;
+    page: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}

package/dist/retry/retry.manager.d.ts

@@ -0,0 +1,61 @@
+import type { WebhookConfig } from "../types/webhook.types";
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    jitter: boolean;
+}
+export interface RetryAttempt {
+    attemptNumber: number;
+    timestamp: Date;
+    success: boolean;
+    error?: string;
+    nextRetryAt?: Date;
+}
+/**
+ * Webhook 재시도 관리자
+ * 지수 백오프와 지터를 사용한 스마트 재시도 로직
+ */
+export declare class RetryManager {
+    private config;
+    constructor(webhookConfig: WebhookConfig);
+    /**
+     * 다음 재시도 시간 계산
+     */
+    calculateNextRetry(attemptNumber: number): Date;
+    /**
+     * 재시도 가능 여부 확인
+     */
+    shouldRetry(attemptNumber: number, error?: Error): boolean;
+    /**
+     * 재시도 가능한 에러인지 판단
+     */
+    private isRetryableError;
+    /**
+     * HTTP 상태 코드별 재시도 정책
+     */
+    shouldRetryStatus(statusCode: number): boolean;
+    /**
+     * 재시도 통계 계산
+     */
+    calculateRetryStats(attempts: RetryAttempt[]): {
+        totalAttempts: number;
+        successfulAttempts: number;
+        failedAttempts: number;
+        averageDelayMs: number;
+        totalTimeMs: number;
+    };
+    /**
+     * 재시도 설정 업데이트
+     */
+    updateConfig(config: Partial<RetryConfig>): void;
+    /**
+     * 현재 재시도 설정 반환
+     */
+    getConfig(): RetryConfig;
+    /**
+     * 백오프 지연 시간 계산 (테스트용)
+     */
+    getBackoffDelay(attemptNumber: number): number;
+}

package/dist/security/security.manager.d.ts

@@ -0,0 +1,50 @@
+import type { WebhookConfig } from "../types/webhook.types";
+export interface SecurityConfig {
+    algorithm: "sha256" | "sha1";
+    header: string;
+    prefix?: string;
+}
+/**
+ * Webhook 보안 관리자
+ * 서명 생성 및 검증을 담당
+ */
+export declare class SecurityManager {
+    private config;
+    constructor(webhookConfig: WebhookConfig);
+    /**
+     * Webhook 페이로드에 대한 서명 생성
+     */
+    generateSignature(payload: string, secret: string): string;
+    /**
+     * Webhook 서명 검증
+     */
+    verifySignature(payload: string, signature: string, secret: string): boolean;
+    /**
+     * HTTP 헤더에서 서명 추출
+     */
+    extractSignature(headers: Record<string, string>): string | null;
+    /**
+     * Webhook 전송을 위한 보안 헤더 생성
+     */
+    createSecurityHeaders(payload: string, secret: string): Record<string, string>;
+    /**
+     * 타임스탬프 기반 재생 공격 방지 검증
+     */
+    verifyTimestamp(timestamp: string, toleranceSeconds?: number): boolean;
+    /**
+     * Webhook ID 생성 (추적용)
+     */
+    private generateWebhookId;
+    /**
+     * Constant-time 문자열 비교 (타이밍 공격 방지)
+     */
+    private constantTimeCompare;
+    /**
+     * 보안 설정 업데이트
+     */
+    updateConfig(config: Partial<SecurityConfig>): void;
+    /**
+     * 현재 보안 설정 반환
+     */
+    getConfig(): SecurityConfig;
+}

package/dist/services/webhook.dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { WebhookConfig, WebhookDelivery, WebhookEndpoint, WebhookEvent } from "../types/webhook.types";
+export interface HttpClient {
+    fetch(url: string, options: RequestInit): Promise<Response>;
+}
+export declare class DefaultHttpClient implements HttpClient {
+    fetch(url: string, options: RequestInit): Promise<Response>;
+}
+export declare class MockHttpClient implements HttpClient {
+    private responses;
+    setMockResponse(url: string, response: Response): void;
+    fetch(url: string, options: RequestInit): Promise<Response>;
+}
+export declare class WebhookDispatcher {
+    private config;
+    private httpClient;
+    constructor(config: WebhookConfig, httpClient?: HttpClient);
+    dispatch(event: WebhookEvent, endpoint: WebhookEndpoint): Promise<WebhookDelivery>;
+    private executeDelivery;
+    private makeHttpRequest;
+    private buildHeaders;
+    private generateSignature;
+    private calculateRetryDelay;
+    private sleep;
+    private generateDeliveryId;
+    shutdown(): Promise<void>;
+}

package/dist/services/webhook.registry.d.ts

@@ -0,0 +1,16 @@
+import type { WebhookDelivery, WebhookEndpoint, WebhookEventType } from "../types/webhook.types";
+export declare class WebhookRegistry {
+    private endpoints;
+    private deliveries;
+    addEndpoint(endpoint: WebhookEndpoint): Promise<void>;
+    updateEndpoint(endpointId: string, endpoint: WebhookEndpoint): Promise<void>;
+    removeEndpoint(endpointId: string): Promise<void>;
+    getEndpoint(endpointId: string): Promise<WebhookEndpoint | null>;
+    listEndpoints(): Promise<WebhookEndpoint[]>;
+    addDelivery(delivery: WebhookDelivery): Promise<void>;
+    getDeliveries(endpointId?: string, timeRange?: {
+        start: Date;
+        end: Date;
+    }, eventType?: WebhookEventType, status?: string, limit?: number): Promise<WebhookDelivery[]>;
+    getFailedDeliveries(endpointId?: string, eventType?: WebhookEventType): Promise<WebhookDelivery[]>;
+}

package/dist/services/webhook.service.d.ts

@@ -0,0 +1,78 @@
+import type { WebhookConfig, WebhookDelivery, WebhookEndpoint, WebhookEvent, WebhookStats, WebhookTestResult } from "../types/webhook.types";
+import { WebhookEventType } from "../types/webhook.types";
+import { type HttpClient } from "./webhook.dispatcher";
+export declare class WebhookService {
+    private config;
+    private dispatcher;
+    private registry;
+    private securityManager;
+    private retryManager;
+    private eventQueue;
+    private batchProcessor;
+    constructor(config: WebhookConfig, httpClient?: HttpClient);
+    /**
+     * 웹훅 엔드포인트 등록
+     */
+    registerEndpoint(endpoint: Omit<WebhookEndpoint, "id" | "createdAt" | "updatedAt" | "status">): Promise<WebhookEndpoint>;
+    /**
+     * 웹훅 엔드포인트 수정
+     */
+    updateEndpoint(endpointId: string, updates: Partial<WebhookEndpoint>): Promise<WebhookEndpoint>;
+    /**
+     * 웹훅 엔드포인트 삭제
+     */
+    deleteEndpoint(endpointId: string): Promise<void>;
+    /**
+     * 웹훅 엔드포인트 조회
+     */
+    getEndpoint(endpointId: string): Promise<WebhookEndpoint | null>;
+    /**
+     * 모든 웹훅 엔드포인트 조회
+     */
+    listEndpoints(): Promise<WebhookEndpoint[]>;
+    /**
+     * 이벤트 발생 (비동기 처리)
+     */
+    emit(event: WebhookEvent): Promise<void>;
+    /**
+     * 이벤트 발생 (동기 처리)
+     */
+    emitSync(event: WebhookEvent): Promise<WebhookDelivery[]>;
+    /**
+     * 웹훅 엔드포인트 테스트
+     */
+    testEndpoint(endpointId: string): Promise<WebhookTestResult>;
+    /**
+     * 웹훅 통계 조회
+     */
+    getStats(endpointId: string, timeRange: {
+        start: Date;
+        end: Date;
+    }): Promise<WebhookStats>;
+    /**
+     * 실패한 웹훅 재시도
+     */
+    retryFailed(endpointId?: string, eventType?: WebhookEventType): Promise<number>;
+    /**
+     * 웹훅 일시 중단
+     */
+    pauseEndpoint(endpointId: string): Promise<void>;
+    /**
+     * 웹훅 재개
+     */
+    resumeEndpoint(endpointId: string): Promise<void>;
+    /**
+     * 웹훅 전달 내역 조회
+     */
+    getDeliveries(endpointId?: string, eventType?: WebhookEventType, status?: string, limit?: number): Promise<WebhookDelivery[]>;
+    private processBatch;
+    private getMatchingEndpoints;
+    private validateEvent;
+    private validateEndpointUrl;
+    private generateEndpointId;
+    private startBatchProcessor;
+    /**
+     * 서비스 종료 시 정리
+     */
+    shutdown(): Promise<void>;
+}