@k-msg/core 0.1.1 → 0.1.2

package/dist/logger.d.ts

@@ -0,0 +1,62 @@
+export declare enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+export interface LogContext {
+    component?: string;
+    operation?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    traceId?: string;
+    [key: string]: any;
+}
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    context: LogContext;
+    error?: Error;
+    duration?: number;
+}
+export interface LoggerConfig {
+    level: LogLevel;
+    enableConsole: boolean;
+    enableFile?: boolean;
+    filePath?: string;
+    maxFileSize?: number;
+    maxFiles?: number;
+    enableJson?: boolean;
+    enableColors?: boolean;
+}
+export declare class Logger {
+    private config;
+    private context;
+    constructor(context?: LogContext, config?: Partial<LoggerConfig>);
+    private shouldLog;
+    private formatMessage;
+    private colorizeLevel;
+    private writeLog;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext, error?: Error): void;
+    error(message: string, context?: LogContext, error?: Error): void;
+    child(context: LogContext): Logger;
+    time(label: string): () => void;
+    measure<T>(operation: string, fn: () => Promise<T>, context?: LogContext): Promise<T>;
+}
+export declare function createLogger(context?: LogContext, config?: Partial<LoggerConfig>): Logger;
+export declare function getLogger(): Logger;
+export declare function setGlobalLogger(logger: Logger): void;
+export declare const logger: {
+    debug: (message: string, context?: LogContext) => void;
+    info: (message: string, context?: LogContext) => void;
+    warn: (message: string, context?: LogContext, error?: Error) => void;
+    error: (message: string, context?: LogContext, error?: Error) => void;
+    child: (context: LogContext) => Logger;
+    time: (label: string) => () => void;
+    measure: <T>(operation: string, fn: () => Promise<T>, context?: LogContext) => Promise<T>;
+};
+export declare function loggerMiddleware(config?: Partial<LoggerConfig>): (c: any, next: any) => Promise<void>;

package/dist/platform.d.ts

@@ -0,0 +1,63 @@
+import type { BaseProvider, Config, KMsg, MessageSendOptions, MessageSendResult, PlatformHealthStatus, PlatformInfo } from "./types/index";
+/**
+ * Core AlimTalk Platform implementation
+ */
+export declare class AlimTalkPlatform implements KMsg {
+    private static readonly channelTemplateFallbacks;
+    private static readonly directTemplateCodes;
+    private providers;
+    private config;
+    private defaultProvider?;
+    constructor(config: Config);
+    getInfo(): PlatformInfo;
+    registerProvider(provider: BaseProvider): void;
+    getProvider(providerId: string): BaseProvider | null;
+    listProviders(): string[];
+    getDefaultProvider(): BaseProvider | null;
+    private isLegacySendOptions;
+    private getProviderOrThrow;
+    private resolveProviderForSend;
+    private normalizeUnifiedRecipients;
+    private resolveTemplateCode;
+    private toErrorMessage;
+    private extractErrorMessage;
+    private hasResultFailureShape;
+    private hasResultSuccessShape;
+    private isFailedDeliveryStatus;
+    private normalizeSendResult;
+    private hasTextContent;
+    private validateUnifiedSendOptions;
+    private toProviderChannel;
+    private sendLegacyMessages;
+    private sendUnifiedMessages;
+    healthCheck(): Promise<PlatformHealthStatus>;
+    get messages(): {
+        send: (options: MessageSendOptions) => Promise<MessageSendResult>;
+        getStatus: (messageId: string) => Promise<string>;
+    };
+    /**
+     * @deprecated Template operations are not yet migrated to the new provider interface.
+     * Use the provider's adapter directly for template management.
+     */
+    templates(providerId?: string): Promise<{
+        /** @deprecated Not yet implemented */
+        list: (_page?: number, _size?: number, _filters?: any) => Promise<never>;
+        /** @deprecated Not yet implemented */
+        create: (_name: string, _content: string, _category?: string, _variables?: any[], _buttons?: any[]) => Promise<never>;
+        /** @deprecated Not yet implemented */
+        modify: (_templateCode: string, _name: string, _content: string, _buttons?: any[]) => Promise<never>;
+        /** @deprecated Not yet implemented */
+        delete: (_templateCode: string) => Promise<never>;
+    }>;
+    /**
+     * @deprecated History operations are not yet migrated to the new provider interface.
+     * Use the provider's adapter directly for history queries.
+     */
+    history(providerId?: string): Promise<{
+        /** @deprecated Not yet implemented */
+        list: (_page?: number, _size?: number, _filters?: any) => Promise<never>;
+        /** @deprecated Not yet implemented */
+        cancelReservation: (_messageId: string) => Promise<never>;
+    }>;
+    providerHealth(providerId: string): Promise<import(".").ProviderHealthStatus>;
+}

package/dist/provider-registry.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Provider Registry System
+ * 프로바이더 등록, 관리, 팩토리 시스템
+ */
+import { type AdapterFactory, type BaseProvider, type ProviderConfig, type ProviderFactoryConfig, type ProviderMetadata, type StandardRequest, type StandardResult } from "./types/index";
+/**
+ * 프로바이더 레지스트리
+ * 모든 등록된 프로바이더와 어댑터 팩토리를 관리
+ */
+export declare class ProviderRegistry {
+    private factories;
+    private providers;
+    private metadata;
+    private debug;
+    /**
+     * 어댑터 팩토리 등록
+     */
+    registerFactory(factory: AdapterFactory): void;
+    /**
+     * 프로바이더 인스턴스 생성
+     */
+    createProvider(providerId: string, config: ProviderConfig): BaseProvider<StandardRequest, StandardResult>;
+    /**
+     * 등록된 프로바이더 인스턴스 반환
+     */
+    getProvider(providerId: string): BaseProvider<StandardRequest, StandardResult> | null;
+    /**
+     * 사용 가능한 프로바이더 목록
+     */
+    getAvailableProviders(): string[];
+    /**
+     * 프로바이더 메타데이터 조회
+     */
+    getProviderMetadata(providerId: string): ProviderMetadata | null;
+    /**
+     * 모든 프로바이더 메타데이터 조회
+     */
+    getAllMetadata(): ProviderMetadata[];
+    /**
+     * 특정 기능을 지원하는 프로바이더 검색
+     */
+    findProvidersByFeature(feature: string): ProviderMetadata[];
+    /**
+     * 프로바이더 등록 해제
+     */
+    unregisterProvider(providerId: string): boolean;
+    /**
+     * 모든 프로바이더 등록 해제
+     */
+    clear(): void;
+    /**
+     * 레지스트리 상태 조회
+     */
+    getStatus(): {
+        registeredFactories: number;
+        activeProviders: number;
+        availableProviders: string[];
+        metadata: ProviderMetadata[];
+    };
+    /**
+     * 프로바이더 헬스체크 실행
+     */
+    healthCheck(): Promise<Record<string, any>>;
+    /**
+     * 디버그 모드 설정
+     */
+    setDebug(enabled: boolean): void;
+}
+/**
+ * 글로벌 프로바이더 레지스트리 인스턴스
+ */
+export declare const globalProviderRegistry: ProviderRegistry;
+/**
+ * 설정 기반 프로바이더 팩토리
+ */
+export declare class ConfigBasedProviderFactory {
+    private registry;
+    private config;
+    constructor(registry: ProviderRegistry, config: ProviderFactoryConfig);
+    /**
+     * 설정에서 프로바이더 생성
+     */
+    createFromConfig(providerId: string): BaseProvider<StandardRequest, StandardResult>;
+    /**
+     * 모든 설정된 프로바이더 생성
+     */
+    createAllFromConfig(): Record<string, BaseProvider<StandardRequest, StandardResult>>;
+}
+/**
+ * 플러그인 기반 프로바이더 로더
+ */
+export declare class ProviderPluginLoader {
+    private registry;
+    constructor(registry: ProviderRegistry);
+    /**
+     * 플러그인 모듈 동적 로딩
+     */
+    loadPlugin(pluginPath: string): Promise<void>;
+    /**
+     * 여러 플러그인 배치 로딩
+     */
+    loadPlugins(pluginPaths: string[]): Promise<void>;
+    /**
+     * 팩토리 인터페이스 검증
+     */
+    private isValidFactory;
+}
+/**
+ * 프로바이더 헬스 모니터
+ * HealthChecker를 활용하여 프로바이더들의 헬스 상태를 모니터링
+ */
+export declare class ProviderHealthMonitor {
+    private registry;
+    private interval;
+    private checker;
+    private intervalId?;
+    private registeredServices;
+    constructor(registry: ProviderRegistry, interval?: number);
+    /**
+     * 헬스 모니터링 시작
+     */
+    start(): void;
+    /**
+     * 헬스 모니터링 중지
+     */
+    stop(): void;
+    /**
+     * 레지스트리의 프로바이더를 HealthChecker에 동기화
+     */
+    private syncProviders;
+    /**
+     * 현재 헬스 상태 조회
+     */
+    checkNow(): Promise<import("./health").HealthStatus>;
+}

package/dist/provider.d.ts

@@ -0,0 +1,36 @@
+import type { KMsgError } from "./errors";
+import type { Result } from "./result";
+import type { SendOptions, SendResult } from "./types/index";
+export interface Template {
+    id: string;
+    code: string;
+    name: string;
+    content: string;
+    category?: string;
+    status: "APPROVED" | "REJECTED" | "PENDING" | "INSPECTION";
+    buttons?: any[];
+    variables?: string[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface TemplateProvider {
+    createTemplate(template: Omit<Template, "id" | "status" | "createdAt" | "updatedAt">): Promise<Result<Template, KMsgError>>;
+    updateTemplate(code: string, template: Partial<Omit<Template, "id" | "code" | "status" | "createdAt" | "updatedAt">>): Promise<Result<Template, KMsgError>>;
+    deleteTemplate(code: string): Promise<Result<void, KMsgError>>;
+    getTemplate(code: string): Promise<Result<Template, KMsgError>>;
+    listTemplates(params?: {
+        status?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<Result<Template[], KMsgError>>;
+}
+/**
+ * @deprecated Use `BaseProvider` from `@k-msg/core` instead.
+ * Legacy provider interface that uses the Result<T, E> pattern for send().
+ * New providers should implement `BaseProvider` which uses adapter-based patterns.
+ */
+export interface Provider {
+    readonly id: string;
+    readonly name: string;
+    send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
+}

package/dist/resilience/bulk-operation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Bulk operation handler with error recovery
+ */
+import { type RetryOptions } from "./retry-handler";
+export interface BulkOperationOptions {
+    concurrency: number;
+    retryOptions: RetryOptions;
+    failFast: boolean;
+    onProgress?: (completed: number, total: number, failed: number) => void;
+}
+export declare class BulkOperationHandler {
+    static execute<T, R>(items: T[], operation: (item: T) => Promise<R>, options?: Partial<BulkOperationOptions>): Promise<{
+        successful: {
+            item: T;
+            result: R;
+        }[];
+        failed: {
+            item: T;
+            error: Error;
+        }[];
+        summary: {
+            total: number;
+            successful: number;
+            failed: number;
+            duration: number;
+        };
+    }>;
+    private static createBatches;
+}

package/dist/resilience/circuit-breaker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Circuit breaker pattern implementation
+ */
+export interface CircuitBreakerOptions {
+    failureThreshold: number;
+    timeout: number;
+    resetTimeout: number;
+    onOpen?: () => void;
+    onHalfOpen?: () => void;
+    onClose?: () => void;
+}
+export declare class CircuitBreaker {
+    private options;
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private nextAttemptTime;
+    constructor(options: CircuitBreakerOptions);
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private recordFailure;
+    getState(): string;
+    getFailureCount(): number;
+    reset(): void;
+}

package/dist/resilience/error-recovery.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Error recovery utilities - combines multiple recovery patterns
+ */
+import { type CircuitBreakerOptions } from "./circuit-breaker";
+import { type RetryOptions } from "./retry-handler";
+export declare const ErrorRecovery: {
+    /**
+     * Create a resilient function that combines multiple recovery patterns
+     */
+    createResilientFunction<T extends any[], R>(func: (...args: T) => Promise<R>, options?: {
+        retryOptions?: Partial<RetryOptions>;
+        circuitBreaker?: CircuitBreakerOptions;
+        rateLimiter?: {
+            maxRequests: number;
+            windowMs: number;
+        };
+        timeout?: number;
+        fallback?: (...args: T) => Promise<R>;
+    }): (...args: T) => Promise<R>;
+};

package/dist/resilience/graceful-degradation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Graceful degradation handler
+ */
+import { type RetryOptions } from "./retry-handler";
+export declare class GracefulDegradation {
+    private fallbackStrategies;
+    registerFallback<T>(operationName: string, fallbackFunction: () => Promise<T>): void;
+    executeWithFallback<T>(operationName: string, primaryOperation: () => Promise<T>, options?: {
+        timeout?: number;
+        retryOptions?: Partial<RetryOptions>;
+    }): Promise<T>;
+}

package/dist/resilience/health-monitor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Health check monitor with automatic recovery
+ * Note: This is the resilience-layer health monitor.
+ * For the main health check system, see ../health.ts
+ */
+export declare class HealthMonitor {
+    private services;
+    private healthStatus;
+    private lastCheck;
+    private checkInterval;
+    private intervalId?;
+    constructor(services: Map<string, () => Promise<boolean>>, checkIntervalMs?: number);
+    start(): void;
+    stop(): void;
+    private checkAllServices;
+    getServiceHealth(serviceName: string): boolean | undefined;
+    getAllHealth(): Record<string, boolean>;
+    isServiceHealthy(serviceName: string): boolean;
+    getLastCheckTime(serviceName: string): number | undefined;
+}

package/dist/resilience/index.d.ts

@@ -0,0 +1,7 @@
+export { BulkOperationHandler, type BulkOperationOptions, } from "./bulk-operation";
+export { CircuitBreaker, type CircuitBreakerOptions } from "./circuit-breaker";
+export { ErrorRecovery } from "./error-recovery";
+export { GracefulDegradation } from "./graceful-degradation";
+export { HealthMonitor } from "./health-monitor";
+export { RateLimiter } from "./rate-limiter";
+export { RetryHandler, type RetryOptions } from "./retry-handler";

package/dist/resilience/rate-limiter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rate limiter for API calls
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private windowMs;
+    private requests;
+    constructor(maxRequests: number, windowMs: number);
+    acquire(): Promise<void>;
+    canMakeRequest(): boolean;
+    getRemainingRequests(): number;
+}

package/dist/resilience/retry-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Retry options and handler for K-Message Platform
+ */
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    jitter?: boolean;
+    retryCondition?: (error: Error, attempt: number) => boolean;
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Exponential backoff retry mechanism
+ */
+export declare class RetryHandler {
+    private static defaultOptions;
+    static execute<T>(operation: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+    static createRetryableFunction<T extends any[], R>(func: (...args: T) => Promise<R>, options?: Partial<RetryOptions>): (...args: T) => Promise<R>;
+}

package/dist/result.d.ts

@@ -0,0 +1,61 @@
+export type Ok<T> = {
+    readonly isSuccess: true;
+    readonly isFailure: false;
+    readonly value: T;
+};
+export type Fail<E> = {
+    readonly isSuccess: false;
+    readonly isFailure: true;
+    readonly error: E;
+};
+export type Result<T, E = Error> = Ok<T> | Fail<E>;
+export declare const ok: <T>(value: T) => Ok<T>;
+export declare const fail: <E>(error: E) => Fail<E>;
+/**
+ * Result utility functions for chaining and transformation
+ */
+export declare const Result: {
+    /**
+     * Transform the success value of a Result
+     */
+    map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+    /**
+     * Chain Result-returning operations
+     */
+    flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+    /**
+     * Transform the error of a Result
+     */
+    mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+    /**
+     * Extract the value or throw the error
+     */
+    unwrap<T, E>(result: Result<T, E>): T;
+    /**
+     * Extract the value or return a default
+     */
+    unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+    /**
+     * Extract the value or compute a default from the error
+     */
+    unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+    /**
+     * Pattern match on a Result
+     */
+    match<T, E, U>(result: Result<T, E>, handlers: {
+        ok: (value: T) => U;
+        fail: (error: E) => U;
+    }): U;
+    /**
+     * Convert a Promise to a Result
+     */
+    fromPromise<T, E = Error>(promise: Promise<T>): Promise<Result<T, E>>;
+    /**
+     * Check if a Result is Ok
+     */
+    isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+    /**
+     * Check if a Result is Fail
+     */
+    isFail<T, E>(result: Result<T, E>): result is Fail<E>;
+};

package/dist/test-utils.d.ts

@@ -0,0 +1,12 @@
+import { KMsgError, KMsgErrorCode, type Provider, type Result, type SendOptions, type SendResult } from "./index";
+export declare class MockProvider implements Provider {
+    readonly id: string;
+    readonly name: string;
+    constructor(id?: string, name?: string);
+    send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
+}
+export declare const TestAssertions: {
+    assertKMsgError: (error: any, expectedCode: KMsgErrorCode) => void;
+    assertSuccess: <T, E>(result: Result<T, E>) => T;
+    assertFailure: <T, E>(result: Result<T, E>) => E;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./message";
+export * from "./platform";
+export * from "./provider";
+export * from "./standard";

package/dist/types/message.d.ts

@@ -0,0 +1,34 @@
+export type MessageType = "ALIMTALK" | "FRIENDTALK" | "SMS" | "LMS" | "MMS";
+export interface BaseOptions {
+    to: string;
+    from: string;
+    messageId?: string;
+}
+export interface AlimTalkOptions extends BaseOptions {
+    type: "ALIMTALK";
+    templateId: string;
+    variables: Record<string, string>;
+}
+export interface Button {
+    name: string;
+    type: string;
+    urlPc?: string;
+    urlMobile?: string;
+}
+export interface FriendTalkOptions extends BaseOptions {
+    type: "FRIENDTALK";
+    text: string;
+    imageUrl?: string;
+    buttons?: Button[];
+}
+export interface SmsOptions extends BaseOptions {
+    type: "SMS" | "LMS" | "MMS";
+    text: string;
+    subject?: string;
+}
+export type SendOptions = AlimTalkOptions | FriendTalkOptions | SmsOptions;
+export interface SendResult {
+    messageId: string;
+    status: "PENDING" | "SENT" | "FAILED";
+    provider: string;
+}

package/dist/types/platform.d.ts

@@ -0,0 +1,88 @@
+import type { Button, MessageType } from "./message";
+export interface PlatformHealthStatus {
+    healthy: boolean;
+    providers: Record<string, boolean>;
+    issues: string[];
+}
+export interface PlatformInfo {
+    version: string;
+    providers: string[];
+    features: string[];
+}
+export interface LegacyMessageSendOptions {
+    templateId: string;
+    recipients: {
+        phoneNumber: string;
+        variables?: Record<string, any>;
+    }[];
+    variables: Record<string, any>;
+}
+export interface UnifiedMessageRecipient {
+    phoneNumber: string;
+    variables?: Record<string, any>;
+}
+export interface UnifiedMessageSendOptions {
+    channel: MessageType;
+    recipients: Array<string | UnifiedMessageRecipient>;
+    providerId?: string;
+    templateCode?: string;
+    variables?: Record<string, any>;
+    text?: string;
+    subject?: string;
+    imageUrl?: string;
+    buttons?: Button[];
+    options?: {
+        scheduledAt?: Date;
+        senderNumber?: string;
+        subject?: string;
+        [key: string]: any;
+    };
+}
+export type MessageSendOptions = LegacyMessageSendOptions | UnifiedMessageSendOptions;
+export interface MessageSendResult {
+    results: Array<{
+        messageId?: string;
+        status: string;
+        phoneNumber: string;
+        error?: {
+            message: string;
+        };
+    }>;
+    summary: {
+        total: number;
+        sent: number;
+        failed: number;
+    };
+}
+export interface KMsg {
+    getInfo(): PlatformInfo;
+    registerProvider(provider: any): void;
+    getProvider(providerId: string): any | null;
+    listProviders(): string[];
+    healthCheck(): Promise<PlatformHealthStatus>;
+    messages: {
+        send(options: MessageSendOptions): Promise<MessageSendResult>;
+        getStatus(messageId: string): Promise<string>;
+    };
+}
+export interface Config {
+    defaultProvider?: string;
+    providers: string[];
+    features: {
+        enableBulkSending?: boolean;
+        enableScheduling?: boolean;
+        enableAnalytics?: boolean;
+    };
+    messageDefaults?: {
+        providerId?: string;
+        senderNumber?: string;
+        subject?: string;
+        templateCodes?: Partial<Record<MessageType, string>>;
+        channels?: Partial<Record<MessageType, {
+            providerId?: string;
+            senderNumber?: string;
+            subject?: string;
+            templateCode?: string;
+        }>>;
+    };
+}