@k-msg/provider 0.1.0 → 0.1.2

package/dist/types/typed-templates.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Typed Template System
+ * 템플릿별 강타입 시스템
+ */
+import type { StandardRequest, StandardResult } from "@k-msg/core";
+export type MessageChannel = "alimtalk" | "sms" | "mms";
+export interface VariableType {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    phoneNumber: string;
+    url: string;
+    email: string;
+}
+export interface VariableDefinition<T extends keyof VariableType = keyof VariableType> {
+    type: T;
+    required: boolean;
+    description?: string;
+    validation?: {
+        pattern?: RegExp;
+        minLength?: number;
+        maxLength?: number;
+        min?: number;
+        max?: number;
+    };
+    defaultValue?: VariableType[T];
+}
+export interface TemplateSchema<V extends Record<string, VariableDefinition> = Record<string, VariableDefinition>> {
+    templateCode: string;
+    name: string;
+    description?: string;
+    channels: MessageChannel[];
+    variables: V;
+    metadata?: {
+        category?: string;
+        version?: string;
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+}
+export interface TemplateRegistry {
+    WELCOME_001: TemplateSchema<{
+        name: VariableDefinition<"string">;
+        service: VariableDefinition<"string">;
+        date: VariableDefinition<"date">;
+    }>;
+    OTP_AUTH_001: TemplateSchema<{
+        code: VariableDefinition<"string">;
+        expiry: VariableDefinition<"string">;
+        serviceName: VariableDefinition<"string">;
+    }>;
+    ORDER_CONFIRM_001: TemplateSchema<{
+        orderNumber: VariableDefinition<"string">;
+        productName: VariableDefinition<"string">;
+        amount: VariableDefinition<"string">;
+        deliveryDate: VariableDefinition<"date">;
+        customerName: VariableDefinition<"string">;
+    }>;
+    PAYMENT_COMPLETE_001: TemplateSchema<{
+        amount: VariableDefinition<"string">;
+        paymentMethod: VariableDefinition<"string">;
+        transactionId: VariableDefinition<"string">;
+        customerName: VariableDefinition<"string">;
+    }>;
+    SMS_DIRECT: TemplateSchema<{
+        message: VariableDefinition<"string">;
+    }>;
+    LMS_DIRECT: TemplateSchema<{
+        subject: VariableDefinition<"string">;
+        message: VariableDefinition<"string">;
+    }>;
+    EMERGENCY_NOTIFICATION: TemplateSchema<{
+        alertType: VariableDefinition<"string">;
+        message: VariableDefinition<"string">;
+        contactInfo: VariableDefinition<"string">;
+        urgencyLevel: VariableDefinition<"string">;
+    }>;
+}
+export type TemplateCode = keyof TemplateRegistry;
+export type ExtractVariables<T extends TemplateCode> = {
+    [K in keyof TemplateRegistry[T]["variables"]]: TemplateRegistry[T]["variables"][K] extends VariableDefinition<infer VT> ? VariableType[VT] : never;
+};
+export type ExtractRequiredVariables<T extends TemplateCode> = {
+    [K in keyof TemplateRegistry[T]["variables"] as TemplateRegistry[T]["variables"][K] extends {
+        required: true;
+    } ? K : never]: TemplateRegistry[T]["variables"][K] extends VariableDefinition<infer VT> ? VariableType[VT] : never;
+};
+export type ExtractOptionalVariables<T extends TemplateCode> = {
+    [K in keyof TemplateRegistry[T]["variables"] as TemplateRegistry[T]["variables"][K] extends {
+        required: false;
+    } ? K : never]?: TemplateRegistry[T]["variables"][K] extends VariableDefinition<infer VT> ? VariableType[VT] : never;
+};
+export type TemplateVariables<T extends TemplateCode> = ExtractRequiredVariables<T> & ExtractOptionalVariables<T>;
+export type ExtractChannels<T extends TemplateCode> = TemplateRegistry[T]["channels"][number];
+export interface TypedRequest<T extends TemplateCode> {
+    templateCode: T;
+    phoneNumber: string;
+    variables: TemplateVariables<T>;
+    options?: {
+        senderNumber?: string;
+        scheduledAt?: Date;
+        priority?: "high" | "normal" | "low";
+        channel?: ExtractChannels<T>;
+        subject?: string;
+    };
+}
+export interface TypedResult<T extends TemplateCode> {
+    messageId: string;
+    templateCode: T;
+    phoneNumber: string;
+    channel: ExtractChannels<T>;
+    status: "sent" | "pending" | "failed";
+    timestamp: Date;
+    variables: TemplateVariables<T>;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+/**
+ * TypedRequest를 StandardRequest로 변환하는 유틸리티 타입
+ */
+export type ToStandardRequest<T extends TemplateCode> = StandardRequest & {
+    templateCode: T;
+    variables: Record<string, string>;
+};
+/**
+ * StandardResult를 TypedResult로 변환하는 유틸리티 타입
+ */
+export type ToTypedResult<T extends TemplateCode> = Omit<TypedResult<T>, "templateCode" | "channel"> & {
+    templateCode: T;
+    channel: ExtractChannels<T>;
+};
+/**
+ * 타입 안전한 템플릿 변환 함수들
+ */
+export declare class TemplateTypeConverter {
+    /**
+     * TypedRequest를 StandardRequest로 변환
+     */
+    static toStandardRequest<T extends TemplateCode>(typedRequest: TypedRequest<T>): StandardRequest;
+    /**
+     * StandardResult를 TypedResult로 변환
+     */
+    static toTypedResult<T extends TemplateCode>(standardResult: StandardResult, templateCode: T, originalVariables: TemplateVariables<T>): TypedResult<T>;
+    /**
+     * 템플릿 코드로부터 채널 추론
+     */
+    private static inferChannel;
+    /**
+     * StandardStatus를 TypedResult 상태로 매핑
+     */
+    private static mapStandardStatus;
+}
+/**
+ * 타입 안전한 Provider 래퍼
+ * 기존 Provider를 감싸서 타입 안전성을 제공
+ */
+export declare class TypedProvider {
+    private provider;
+    constructor(provider: import("@k-msg/core").BaseProvider);
+    /**
+     * 타입 안전한 메시지 전송
+     */
+    send<T extends TemplateCode>(request: TypedRequest<T>): Promise<TypedResult<T>>;
+    /**
+     * 대량 전송 (타입 안전)
+     */
+    sendBulk<T extends TemplateCode>(requests: TypedRequest<T>[], options?: {
+        batchSize?: number;
+        concurrency?: number;
+        failFast?: boolean;
+    }): Promise<TypedResult<T>[]>;
+    /**
+     * 상태 조회 (타입 안전하지 않은 부분 - messageId만 필요)
+     */
+    getStatus(messageId: string): Promise<import("@k-msg/core").DeliveryStatus>;
+    /**
+     * 기본 Provider 접근 (고급 사용자용)
+     */
+    getUnderlyingProvider(): import("@k-msg/core").BaseProvider<StandardRequest, StandardResult>;
+}
+export declare const TEMPLATE_REGISTRY: TemplateRegistry;
+export declare class TemplateValidator {
+    static validateVariables<T extends TemplateCode>(templateCode: T, variables: Record<string, any>): ValidationResult<TemplateVariables<T>>;
+    static validateChannel<T extends TemplateCode>(templateCode: T, channel: string): boolean;
+    private static validateType;
+    private static validateValue;
+    private static applyDefaults;
+}
+export interface ValidationResult<T> {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+    validatedVariables: T;
+}

package/dist/types/unified-config.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Unified Configuration Types
+ * 통합된 설정 타입 시스템
+ */
+import type { ProviderConfig } from "@k-msg/core";
+/**
+ * 환경별 설정
+ */
+export type Environment = "development" | "staging" | "production";
+/**
+ * 로그 레벨
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * 공통 설정 인터페이스
+ */
+export interface BaseConfig {
+    environment: Environment;
+    debug?: boolean;
+    logLevel?: LogLevel;
+    timeout?: number;
+}
+/**
+ * IWINV 기본 설정 (모든 IWINV 관련 설정의 기준)
+ */
+export interface IWINVBaseConfig extends ProviderConfig, BaseConfig {
+    apiKey: string;
+    baseUrl: string;
+    userId?: string;
+    senderNumber?: string;
+}
+/**
+ * AlimTalk 특화 설정
+ */
+export interface AlimTalkConfig extends IWINVBaseConfig {
+    type: "alimtalk";
+    senderKey?: string;
+    fallbackSettings?: {
+        enableSMSFallback: boolean;
+        fallbackSenderNumber?: string;
+    };
+}
+/**
+ * SMS 특화 설정
+ */
+export interface SMSConfig extends IWINVBaseConfig {
+    type: "sms";
+    defaultMsgType?: "SMS" | "LMS" | "MMS";
+    autoDetectMessageType?: boolean;
+    maxSMSLength?: number;
+    maxLMSLength?: number;
+}
+/**
+ * MMS 특화 설정
+ */
+export interface MMSConfig extends IWINVBaseConfig {
+    type: "mms";
+    maxFileSize?: number;
+    allowedMimeTypes?: string[];
+    imageOptimization?: {
+        enabled: boolean;
+        maxWidth?: number;
+        maxHeight?: number;
+        quality?: number;
+    };
+}
+/**
+ * 채널별 설정 유니온
+ */
+export type ChannelConfig = AlimTalkConfig | SMSConfig | MMSConfig;
+/**
+ * 다중 채널 지원 설정
+ */
+export interface MultiChannelConfig {
+    channels: ChannelConfig[];
+    defaultChannel: "alimtalk" | "sms" | "mms";
+    fallbackChain?: ("alimtalk" | "sms" | "mms")[];
+}
+/**
+ * 성능 및 안정성 설정
+ */
+export interface PerformanceConfig {
+    rateLimiting?: {
+        requestsPerSecond: number;
+        burstSize: number;
+        strategy: "token_bucket" | "sliding_window";
+    };
+    circuitBreaker?: {
+        enabled: boolean;
+        failureThreshold: number;
+        timeoutMs: number;
+        retryDelayMs: number;
+    };
+    caching?: {
+        enabled: boolean;
+        ttl: number;
+        maxSize: number;
+    };
+    connectionPool?: {
+        maxConnections: number;
+        idleTimeout: number;
+        connectionTimeout: number;
+    };
+}
+/**
+ * 모니터링 설정
+ */
+export interface MonitoringConfig {
+    enableMetrics: boolean;
+    enableTracing: boolean;
+    enableHealthChecks: boolean;
+    metricsInterval?: number;
+    healthCheckInterval?: number;
+}
+/**
+ * 완전한 통합 설정
+ */
+export interface UnifiedProviderConfig extends BaseConfig {
+    provider: {
+        type: "iwinv";
+        apiKey: string;
+        baseUrl: string;
+    };
+    channels?: {
+        alimtalk?: Omit<AlimTalkConfig, "apiKey" | "baseUrl" | "type">;
+        sms?: Omit<SMSConfig, "apiKey" | "baseUrl" | "type">;
+        mms?: Omit<MMSConfig, "apiKey" | "baseUrl" | "type">;
+    };
+    performance?: PerformanceConfig;
+    monitoring?: MonitoringConfig;
+    multiChannel?: {
+        defaultChannel: "alimtalk" | "sms" | "mms";
+        fallbackChain: ("alimtalk" | "sms" | "mms")[];
+    };
+}
+/**
+ * 기본 설정 검증
+ */
+export declare function isValidBaseConfig(config: unknown): config is BaseConfig;
+/**
+ * IWINV 기본 설정 검증
+ */
+export declare function isValidIWINVBaseConfig(config: unknown): config is IWINVBaseConfig;
+/**
+ * AlimTalk 설정 검증
+ */
+export declare function isValidAlimTalkConfig(config: unknown): config is AlimTalkConfig;
+/**
+ * SMS 설정 검증
+ */
+export declare function isValidSMSConfig(config: unknown): config is SMSConfig;
+/**
+ * MMS 설정 검증
+ */
+export declare function isValidMMSConfig(config: unknown): config is MMSConfig;
+/**
+ * 통합 설정 검증
+ */
+export declare function isValidUnifiedConfig(config: unknown): config is UnifiedProviderConfig;
+/**
+ * 타입 안전한 설정 빌더
+ */
+export declare class UnifiedConfigBuilder {
+    private config;
+    static create(): UnifiedConfigBuilder;
+    environment(env: Environment): this;
+    provider(apiKey: string, baseUrl: string): this;
+    alimtalk(config: Omit<AlimTalkConfig, "apiKey" | "baseUrl" | "type">): this;
+    sms(config: Omit<SMSConfig, "apiKey" | "baseUrl" | "type">): this;
+    mms(config: Omit<MMSConfig, "apiKey" | "baseUrl" | "type">): this;
+    performance(config: PerformanceConfig): this;
+    monitoring(config: MonitoringConfig): this;
+    multiChannel(defaultChannel: "alimtalk" | "sms" | "mms", fallbackChain: ("alimtalk" | "sms" | "mms")[]): this;
+    build(): UnifiedProviderConfig;
+}
+export declare class UnifiedConfigFactory {
+    /**
+     * 개발 환경 기본 설정
+     */
+    static development(apiKey: string, baseUrl?: string): UnifiedProviderConfig;
+    /**
+     * 프로덕션 환경 기본 설정
+     */
+    static production(apiKey: string, baseUrl?: string): UnifiedProviderConfig;
+    /**
+     * 환경 변수에서 설정 생성
+     */
+    static fromEnvironment(): UnifiedProviderConfig;
+}
+/**
+ * 통합 설정을 레거시 IWINVConfig로 변환
+ */
+export declare function toLegacyIWINVConfig(config: UnifiedProviderConfig): IWINVBaseConfig;
+/**
+ * 레거시 IWINVConfig를 통합 설정으로 변환
+ */
+export declare function fromLegacyIWINVConfig(legacyConfig: IWINVBaseConfig): UnifiedProviderConfig;

package/dist/types/unified-errors.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Unified Error System
+ * 통합 에러 처리 시스템
+ */
+type StandardError = any;
+/**
+ * 에러 카테고리
+ */
+export declare enum ErrorCategory {
+    SYSTEM = "SYSTEM",
+    NETWORK = "NETWORK",
+    CONFIGURATION = "CONFIGURATION",
+    AUTHENTICATION = "AUTHENTICATION",
+    AUTHORIZATION = "AUTHORIZATION",
+    VALIDATION = "VALIDATION",
+    BUSINESS_LOGIC = "BUSINESS_LOGIC",
+    PROVIDER = "PROVIDER",
+    TEMPLATE = "TEMPLATE",
+    RATE_LIMIT = "RATE_LIMIT",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * 에러 심각도
+ */
+export declare enum ErrorSeverity {
+    LOW = "LOW",// 로깅만, 재시도 불필요
+    MEDIUM = "MEDIUM",// 경고, 재시도 가능
+    HIGH = "HIGH",// 에러, 재시도 필요
+    CRITICAL = "CRITICAL"
+}
+/**
+ * 기본 에러 정보
+ */
+export interface BaseErrorInfo {
+    code: string;
+    message: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    retryable: boolean;
+    timestamp: Date;
+    context?: Record<string, unknown>;
+}
+/**
+ * Provider 특화 에러 정보
+ */
+export interface ProviderErrorInfo extends BaseErrorInfo {
+    provider: string;
+    originalCode?: string | number;
+    originalMessage?: string;
+    endpoint?: string;
+    requestId?: string;
+}
+/**
+ * 템플릿 관련 에러 정보
+ */
+export interface TemplateErrorInfo extends BaseErrorInfo {
+    templateCode?: string;
+    templateName?: string;
+    validationErrors?: string[];
+    missingVariables?: string[];
+}
+/**
+ * 네트워크 관련 에러 정보
+ */
+export interface NetworkErrorInfo extends BaseErrorInfo {
+    url?: string;
+    method?: string;
+    statusCode?: number;
+    timeout?: boolean;
+    connectionRefused?: boolean;
+}
+/**
+ * 통합 에러 타입
+ */
+export type UnifiedErrorInfo = ProviderErrorInfo | TemplateErrorInfo | NetworkErrorInfo | BaseErrorInfo;
+/**
+ * 기본 통합 에러 클래스
+ */
+export declare class UnifiedError extends Error {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly retryable: boolean;
+    readonly timestamp: Date;
+    readonly context: Record<string, unknown>;
+    constructor(info: BaseErrorInfo);
+    /**
+     * StandardError 형식으로 변환
+     */
+    toStandardError(): StandardError;
+    /**
+     * 에러 카테고리를 StandardErrorCode로 매핑
+     */
+    private mapToStandardErrorCode;
+}
+/**
+ * Provider 에러 클래스
+ */
+export declare class ProviderError extends UnifiedError {
+    readonly provider: string;
+    readonly originalCode?: string | number;
+    readonly originalMessage?: string;
+    readonly endpoint?: string;
+    readonly requestId?: string;
+    constructor(info: ProviderErrorInfo);
+}
+/**
+ * 템플릿 에러 클래스
+ */
+export declare class TemplateError extends UnifiedError {
+    readonly templateCode?: string;
+    readonly templateName?: string;
+    readonly validationErrors?: string[];
+    readonly missingVariables?: string[];
+    constructor(info: TemplateErrorInfo);
+}
+/**
+ * 네트워크 에러 클래스
+ */
+export declare class NetworkError extends UnifiedError {
+    readonly url?: string;
+    readonly method?: string;
+    readonly statusCode?: number;
+    readonly timeout?: boolean;
+    readonly connectionRefused?: boolean;
+    constructor(info: NetworkErrorInfo);
+}
+export declare class ErrorFactory {
+    /**
+     * Provider 에러 생성
+     */
+    static createProviderError(params: {
+        provider: string;
+        message: string;
+        originalCode?: string | number;
+        originalMessage?: string;
+        endpoint?: string;
+        retryable?: boolean;
+        context?: Record<string, unknown>;
+    }): ProviderError;
+    /**
+     * 템플릿 에러 생성
+     */
+    static createTemplateError(params: {
+        templateCode?: string;
+        message: string;
+        validationErrors?: string[];
+        missingVariables?: string[];
+        retryable?: boolean;
+    }): TemplateError;
+    /**
+     * 네트워크 에러 생성
+     */
+    static createNetworkError(params: {
+        url?: string;
+        method?: string;
+        statusCode?: number;
+        message: string;
+        timeout?: boolean;
+        connectionRefused?: boolean;
+    }): NetworkError;
+    /**
+     * 인증 에러 생성
+     */
+    static createAuthenticationError(message?: string): UnifiedError;
+    /**
+     * 검증 에러 생성
+     */
+    static createValidationError(message: string, context?: Record<string, unknown>): UnifiedError;
+    /**
+     * 요율 제한 에러 생성
+     */
+    static createRateLimitError(message?: string, retryAfter?: number): UnifiedError;
+}
+export declare class ErrorConverter {
+    /**
+     * 임의의 에러를 UnifiedError로 변환
+     */
+    static toUnifiedError(error: unknown, context?: Record<string, unknown>): UnifiedError;
+    /**
+     * IWINV 에러를 ProviderError로 변환
+     */
+    static fromIWINVError(error: {
+        code: number;
+        message: string;
+        status?: number;
+        data?: unknown;
+    }): ProviderError;
+    /**
+     * HTTP 에러를 NetworkError로 변환
+     */
+    static fromHttpError(params: {
+        url: string;
+        method: string;
+        statusCode: number;
+        statusText?: string;
+        responseBody?: unknown;
+    }): NetworkError;
+}
+export declare function isUnifiedError(error: unknown): error is UnifiedError;
+export declare function isProviderError(error: unknown): error is ProviderError;
+export declare function isTemplateError(error: unknown): error is TemplateError;
+export declare function isNetworkError(error: unknown): error is NetworkError;
+export declare function isRetryableError(error: unknown): boolean;
+export interface ErrorStats {
+    total: number;
+    byCategory: Record<ErrorCategory, number>;
+    bySeverity: Record<ErrorSeverity, number>;
+    retryable: number;
+    nonRetryable: number;
+}
+export declare class ErrorAnalyzer {
+    /**
+     * 에러 목록 통계 분석
+     */
+    static analyze(errors: UnifiedError[]): ErrorStats;
+    /**
+     * 중요 에러 필터링
+     */
+    static getCriticalErrors(errors: UnifiedError[]): UnifiedError[];
+    /**
+     * 재시도 가능한 에러 필터링
+     */
+    static getRetryableErrors(errors: UnifiedError[]): UnifiedError[];
+}
+export {};

package/dist/utils/base-plugin.d.ts

@@ -0,0 +1,35 @@
+import type { PluginContext, ProviderCapabilities, ProviderImplementation, ProviderMetadata, ProviderMiddleware, ProviderPlugin } from "../interfaces";
+export declare abstract class BasePlugin implements ProviderPlugin {
+    abstract readonly metadata: ProviderMetadata;
+    abstract readonly capabilities: ProviderCapabilities;
+    protected context: PluginContext;
+    middleware: ProviderMiddleware[];
+    initialize(context: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+    abstract getImplementation(): ProviderImplementation;
+    protected executeMiddleware(phase: "pre" | "post" | "error", context: any, error?: Error): Promise<void>;
+    protected createMiddlewareContext(request: any, metadata?: Record<string, any>): {
+        request: any;
+        response: any;
+        metadata: {
+            pluginName: string;
+            pluginVersion: string;
+        };
+        startTime: number;
+    };
+    protected validateConfig(config: any, required: string[]): void;
+    protected makeRequest(url: string, options: RequestInit, metadata?: Record<string, any>): Promise<Response>;
+    /**
+     * Make HTTP request and parse JSON response
+     * Subclasses should use their specific response adapters to transform the result
+     */
+    protected makeJSONRequest<T = any>(url: string, options: RequestInit, metadata?: Record<string, any>): Promise<T>;
+    /**
+     * Helper method for logging provider-specific operations
+     */
+    protected logOperation(operation: string, data?: any): void;
+    /**
+     * Helper method for logging provider-specific errors
+     */
+    protected logError(operation: string, error: any, data?: any): void;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./base-plugin";
+export declare function normalizePhoneNumber(phone: string): string;
+export declare function validatePhoneNumber(phone: string): boolean;
+export declare function formatDateTime(date: Date): string;
+export declare function parseTemplate(template: string, variables: Record<string, string>): string;
+export declare function extractVariables(template: string): string[];
+export declare function delay(ms: number): Promise<void>;
+export declare function retry<T>(fn: () => Promise<T>, options: {
+    maxRetries: number;
+    delay: number;
+    backoff?: "linear" | "exponential";
+}): Promise<T>;