@k-msg/provider 0.1.0 → 0.1.2

package/dist/iwinv/types/iwinv.d.ts

@@ -0,0 +1,153 @@
+/**
+ * IWINV API TypeScript 타입 정의
+ * IWINV 알림톡 REST API 규격서 기반
+ */
+export interface IWINVBaseResponse {
+    code: number;
+    message: string;
+}
+export interface SendMessageRequest {
+    templateCode: string;
+    reserve?: "Y" | "N";
+    sendDate?: string;
+    reSend?: "Y" | "N";
+    resendCallback?: string;
+    resendType?: "Y" | "N";
+    resendTitle?: string;
+    resendContent?: string;
+    list: SendRecipient[];
+}
+export interface SendRecipient {
+    phone: string;
+    templateParam?: string[];
+}
+export interface SendMessageResponse extends IWINVBaseResponse {
+    success: number;
+    fail: number;
+}
+export interface CreateTemplateRequest {
+    templateName: string;
+    templateContent: string;
+    buttons?: CreateTemplateButton[];
+}
+export interface CreateTemplateButton {
+    type: "WL" | "AL" | "DB" | "BK" | "MD";
+    name: string;
+    linkMo?: string;
+    linkPc?: string;
+    linkIos?: string;
+    linkAnd?: string;
+}
+export interface Template {
+    templateCode: string;
+    templateName: string;
+    templateContent: string;
+    status: "Y" | "I" | "R";
+    templateStatusMsg?: string;
+    templateStatusComments?: string;
+    createDate: string;
+    buttons: any[];
+}
+export interface TemplateListRequest {
+    pageNum?: string;
+    pageSize?: string;
+    templateCode?: string;
+    templateName?: string;
+    templateStatus?: "Y" | "I" | "R";
+}
+export interface TemplateListResponse extends IWINVBaseResponse {
+    totalCount: number;
+    list: Template[];
+}
+export interface ModifyTemplateRequest {
+    templateCode: string;
+    templateName: string;
+    templateContent: string;
+    buttons?: CreateTemplateButton[];
+}
+export interface DeleteTemplateRequest {
+    templateCode: string;
+}
+export type CreateTemplateResponse = IWINVBaseResponse;
+export type ModifyTemplateResponse = IWINVBaseResponse;
+export type DeleteTemplateResponse = IWINVBaseResponse;
+export interface HistoryRequest {
+    pageNum?: number;
+    pageSize?: number;
+    reserve?: "Y" | "N";
+    startDate?: string;
+    endDate?: string;
+    seqNo?: number;
+    phone?: string;
+}
+export interface MessageHistory {
+    seqNo: number;
+    phone: string;
+    callback: string;
+    templateCode: string;
+    sendMessage: string;
+    reserve: "Y" | "N";
+    requestDate: string;
+    sendDate: string;
+    receiveDate: string;
+    statusCode: string;
+    statusCodeName: string;
+    resendStatus: string | null;
+    resendStatusName: string | null;
+    buttons: {
+        link1: string | null;
+        link2: string | null;
+        link3: string | null;
+        link4: string | null;
+        link5: string | null;
+    };
+}
+export interface HistoryResponse extends IWINVBaseResponse {
+    totalCount: number;
+    list: MessageHistory[];
+}
+export interface CancelReservationRequest {
+    seqNo: number;
+}
+export type CancelReservationResponse = IWINVBaseResponse;
+export interface BalanceResponse extends IWINVBaseResponse {
+    charge: number;
+}
+export interface IWINVConfig {
+    apiKey: string;
+    baseUrl: string;
+    smsApiKey?: string;
+    smsAuthKey?: string;
+    smsBaseUrl?: string;
+    senderNumber?: string;
+    smsSenderNumber?: string;
+    sendEndpoint?: string;
+    ipRetryCount?: number;
+    ipRetryDelayMs?: number;
+    ipAlertWebhookUrl?: string;
+    onIpRestrictionAlert?: (payload: IWINVIPRestrictionAlert) => void | Promise<void>;
+    debug?: boolean;
+    [key: string]: unknown;
+}
+export interface IWINVIPRestrictionAlert {
+    provider: "iwinv";
+    channel: string;
+    endpoint: string;
+    phoneNumber: string;
+    templateCode?: string;
+    code: string;
+    message: string;
+    attempt: number;
+    maxAttempts: number;
+    timestamp: string;
+}
+export declare const IWINV_STATUS_CODES: {
+    readonly SUCCESS: 200;
+    readonly AUTH_FAILED: 201;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+};

package/dist/middleware/index.d.ts

@@ -0,0 +1,27 @@
+import type { ProviderMiddleware } from "../interfaces";
+export declare function createRetryMiddleware(options: {
+    maxRetries: number;
+    retryDelay: number;
+    retryableErrors?: string[];
+    retryableStatusCodes?: number[];
+}): ProviderMiddleware;
+export declare function createRateLimitMiddleware(options: {
+    messagesPerSecond?: number;
+    messagesPerMinute?: number;
+    messagesPerHour?: number;
+    messagesPerDay?: number;
+    strategy?: "sliding-window" | "fixed-window";
+}): ProviderMiddleware;
+export declare function createLoggingMiddleware(options: {
+    logger: any;
+    logLevel?: string;
+}): ProviderMiddleware;
+export declare function createMetricsMiddleware(options: {
+    collector: any;
+    labels?: Record<string, string>;
+}): ProviderMiddleware;
+export declare function createCircuitBreakerMiddleware(options: {
+    threshold: number;
+    timeout: number;
+    resetTimeout: number;
+}): ProviderMiddleware;

package/dist/mock/index.d.ts

@@ -0,0 +1 @@
+export * from "../providers/mock";

package/dist/providers/mock/index.d.ts

@@ -0,0 +1 @@
+export * from "./mock.provider";

package/dist/providers/mock/mock.provider.d.ts

@@ -0,0 +1,22 @@
+import { KMsgError, type Provider, type Result, type SendOptions, type SendResult, type Template, type TemplateProvider } from "@k-msg/core";
+export declare class MockProvider implements Provider, TemplateProvider {
+    readonly id = "mock";
+    readonly name = "Mock Provider";
+    calls: SendOptions[];
+    private failureCount;
+    private templates;
+    send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
+    mockSuccess(): void;
+    mockFailure(count: number): void;
+    getHistory(): SendOptions[];
+    clearHistory(): void;
+    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>>;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1 @@
+export * from "./plugin-registry";

package/dist/registry/plugin-registry.d.ts

@@ -0,0 +1,15 @@
+import type { Logger, MetricsCollector, PluginStorage, ProviderConfig, ProviderPlugin } from "../interfaces";
+export declare class PluginRegistry {
+    private plugins;
+    private instances;
+    register(plugin: ProviderPlugin): void;
+    create(pluginId: string, config: ProviderConfig, options?: {
+        logger?: Logger;
+        metrics?: MetricsCollector;
+        storage?: PluginStorage;
+    }): Promise<ProviderPlugin>;
+    loadAndCreate(pluginId: string, config: ProviderConfig, options?: any): Promise<ProviderPlugin>;
+    getSupportedTypes(): string[];
+    validateProviderConfig(type: string, config: ProviderConfig): boolean;
+    destroyAll(): Promise<void>;
+}

package/dist/services/provider.manager.d.ts

@@ -0,0 +1,24 @@
+import type { BaseProvider, ProviderType, StandardRequest, StandardResult } from "@k-msg/core";
+import type { AlimTalkProvider, AlimTalkRequest, AlimTalkResult } from "../contracts/provider.contract";
+import type { SMSProvider, SMSRequest, SMSResult } from "../contracts/sms.contract";
+export declare class ProviderManager {
+    private providers;
+    private defaultProvider?;
+    registerProvider(provider: BaseProvider<StandardRequest, StandardResult>): void;
+    unregisterProvider(providerId: string): void;
+    getProvider(providerId?: string): BaseProvider<StandardRequest, StandardResult> | null;
+    getAlimTalkProvider(providerId?: string): AlimTalkProvider | null;
+    listProviders(): BaseProvider<StandardRequest, StandardResult>[];
+    listAlimTalkProviders(): AlimTalkProvider[];
+    setDefaultProvider(providerId: string): void;
+    healthCheckAll(): Promise<Record<string, boolean>>;
+    getProvidersForChannel(channel: string): BaseProvider<StandardRequest, StandardResult>[];
+    getProvidersByType(type: ProviderType): BaseProvider<StandardRequest, StandardResult>[];
+    getSMSProvider(providerId?: string): SMSProvider | null;
+    listSMSProviders(): SMSProvider[];
+    send<TRequest extends StandardRequest, TResult extends StandardResult>(providerId: string, request: TRequest): Promise<TResult>;
+    sendAlimTalk(providerId: string | undefined, request: AlimTalkRequest): Promise<AlimTalkResult>;
+    sendSMS(providerId: string | undefined, request: SMSRequest): Promise<SMSResult>;
+    private isAlimTalkProvider;
+    private isSMSProvider;
+}

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

@@ -0,0 +1,49 @@
+import type { BaseProvider, StandardRequest, StandardResult } from "@k-msg/core";
+import type { AlimTalkProvider, AlimTalkRequest, AlimTalkResult } from "../contracts/provider.contract";
+/**
+ * Manages the lifecycle and access to different messaging providers.
+ */
+export declare class ProviderService {
+    private providers;
+    private defaultProviderId?;
+    /**
+     * @param defaultProviderId The ID of the provider to use when none is specified.
+     */
+    constructor(defaultProviderId?: string);
+    /**
+     * Registers a new provider instance.
+     * If no default provider is set, the first registered provider becomes the default.
+     * @param provider The provider instance to register.
+     */
+    register(provider: BaseProvider<StandardRequest, StandardResult>): void;
+    /**
+     * Retrieves a provider by its unique ID.
+     * @param providerId The ID of the provider.
+     * @returns The provider instance or undefined if not found.
+     */
+    get(providerId: string): BaseProvider<StandardRequest, StandardResult> | undefined;
+    /**
+     * Retrieves a typed AlimTalk provider by its unique ID.
+     * @param providerId The ID of the provider.
+     * @returns The AlimTalk provider instance or undefined if not found or not an AlimTalk provider.
+     */
+    getAlimTalk(providerId: string): AlimTalkProvider | undefined;
+    /**
+     * Retrieves the default provider.
+     * @returns The default provider instance or undefined if not set.
+     */
+    getDefault(): BaseProvider<StandardRequest, StandardResult> | undefined;
+    /**
+     * Lists all registered providers.
+     * @returns An array of all provider instances.
+     */
+    list(): BaseProvider<StandardRequest, StandardResult>[];
+    /**
+     * Lists all AlimTalk providers.
+     * @returns An array of AlimTalk provider instances.
+     */
+    listAlimTalk(): AlimTalkProvider[];
+    send<TRequest extends StandardRequest, TResult extends StandardResult>(providerId: string, request: TRequest): Promise<TResult>;
+    sendAlimTalk(providerId: string, request: AlimTalkRequest): Promise<AlimTalkResult>;
+    private isAlimTalkProvider;
+}

package/dist/test-helpers.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Test Helpers and Utilities
+ * 테스트 헬퍼 및 유틸리티 함수들
+ */
+import type { StandardRequest } from "@k-msg/core";
+import type { IWINVConfig } from "./iwinv/types/iwinv";
+export declare const TEST_CONFIGS: {
+    development: IWINVConfig;
+    production: IWINVConfig;
+    invalid: IWINVConfig;
+};
+export declare const createTestRequests: () => {
+    alimtalk: {
+        welcome: StandardRequest;
+        otp: StandardRequest;
+        order: StandardRequest;
+    };
+    sms: {
+        short: StandardRequest;
+        long: StandardRequest;
+    };
+    invalid: {
+        emptyPhone: StandardRequest;
+        invalidPhone: StandardRequest;
+        emptyTemplate: StandardRequest;
+    };
+};
+export declare const createBulkTestData: (count?: number) => {
+    templateCode: string;
+    phoneNumber: string;
+    variables: {
+        index: string;
+        name: string;
+        message: string;
+    };
+    channel: "alimtalk" | "sms" | "auto";
+}[];
+export declare const createPerformanceTracker: () => {
+    start: () => void;
+    end: () => void;
+    record: (success: boolean) => void;
+    getMetrics: () => {
+        startTime: number;
+        endTime: number;
+        duration: number;
+        memoryUsage: {
+            start: number;
+            end: number;
+            peak: number;
+        };
+        requestCount: number;
+        successCount: number;
+        errorCount: number;
+    };
+    reset: () => void;
+};
+export declare const createMockHttpResponse: (options?: {
+    success?: boolean;
+    delay?: number;
+    statusCode?: number;
+    data?: any;
+}) => Promise<unknown>;
+export declare const createConcurrencyTester: () => {
+    runConcurrent: <T>(operations: (() => Promise<T>)[], maxConcurrency?: number) => Promise<Array<{
+        result: T | null;
+        error: Error | null;
+        duration: number;
+    }>>;
+    testRateLimit: <T>(operation: () => Promise<T>, requestsPerSecond: number, duration: number) => Promise<{
+        attempted: number;
+        successful: number;
+        failed: number;
+        actualRate: number;
+    }>;
+};
+export declare const createValidationHelpers: () => {
+    isValidPhoneNumber: (phone: string) => boolean;
+    isValidTemplateCode: (code: string) => boolean;
+    containsSensitiveData: (variables: Record<string, string>) => boolean;
+    getMessageType: (message: string) => "sms" | "lms" | "mms";
+};
+export declare const createTestStateTracker: () => {
+    recordTest: (name: string, passed: boolean, duration: number, error?: string) => void;
+    skip: (name: string) => void;
+    getStats: () => {
+        totalTests: number;
+        passedTests: number;
+        failedTests: number;
+        skippedTests: number;
+        duration: number;
+        errors: Array<{
+            test: string;
+            error: string;
+        }>;
+    };
+    getSummary: () => {
+        successRate: number;
+        averageDuration: number;
+        totalTests: number;
+        passedTests: number;
+        failedTests: number;
+        skippedTests: number;
+        duration: number;
+        errors: Array<{
+            test: string;
+            error: string;
+        }>;
+    };
+    reset: () => void;
+};

package/dist/types/aligo.d.ts

@@ -0,0 +1,69 @@
+export interface AligoConfig {
+    apiKey: string;
+    userId: string;
+    senderKey?: string;
+    sender?: string;
+    testMode?: boolean;
+    debug?: boolean;
+    smsBaseUrl?: string;
+    alimtalkBaseUrl?: string;
+    friendtalkEndpoint?: string;
+}
+export interface AligoSMSRequest {
+    key: string;
+    user_id: string;
+    sender: string;
+    receiver: string;
+    msg: string;
+    msg_type?: "SMS" | "LMS" | "MMS";
+    title?: string;
+    testmode_yn?: "Y" | "N";
+    destination?: string;
+    rdate?: string;
+    rtime?: string;
+    image?: string;
+}
+export interface AligoAlimTalkRequest {
+    apikey: string;
+    userid: string;
+    senderkey: string;
+    tpl_code: string;
+    sender: string;
+    [key: string]: any;
+    testMode?: "Y" | "N";
+}
+export interface AligoResponse {
+    result_code: string;
+    message: string;
+    msg_id?: string;
+    success_cnt?: number;
+    error_cnt?: number;
+    msg_type?: string;
+}
+export interface AligoTemplateListRequest {
+    apikey: string;
+    userid: string;
+    senderkey: string;
+    tpl_code?: string;
+}
+export interface AligoTemplateCreateRequest {
+    apikey: string;
+    userid: string;
+    senderkey: string;
+    tpl_name: string;
+    tpl_content: string;
+    tpl_button?: string;
+}
+export interface AligoTemplateDeleteRequest {
+    apikey: string;
+    userid: string;
+    senderkey: string;
+    tpl_code: string;
+}
+export interface AligoRemainResponse {
+    result_code: string;
+    message: string;
+    SMS_CNT: number;
+    LMS_CNT: number;
+    MMS_CNT: number;
+}

package/dist/types/base.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 공통 프로바이더 인터페이스와 타입 정의
+ * 모든 K-Message 프로바이더가 구현해야 하는 기본 인터페이스
+ * 알림톡, 친구톡, SMS, LMS 등 다양한 메시징 채널 지원
+ */
+export declare enum MessageChannel {
+    ALIMTALK = "alimtalk",// 카카오 알림톡
+    FRIENDTALK = "friendtalk",// 카카오 친구톡
+    SMS = "sms",// 단문 메시지
+    LMS = "lms",// 장문 메시지
+    MMS = "mms",// 멀티미디어 메시지
+    PUSH = "push",// 푸시 알림
+    EMAIL = "email"
+}
+export declare enum MessageType {
+    TEXT = "text",// 텍스트만
+    RICH = "rich",// 리치 메시지 (버튼, 이미지 등)
+    TEMPLATE = "template",// 템플릿 기반
+    CUSTOM = "custom"
+}
+export interface SendOptions {
+    channel?: MessageChannel;
+    messageType?: MessageType;
+    reserve?: boolean;
+    sendDate?: Date | string;
+    timezone?: string;
+    senderKey?: string;
+    senderNumber?: string;
+    senderName?: string;
+    enableFallback?: boolean;
+    fallbackChannel?: MessageChannel;
+    fallbackContent?: string;
+    fallbackTitle?: string;
+    title?: string;
+    subject?: string;
+    priority?: "high" | "normal" | "low";
+    trackingId?: string;
+    campaignId?: string;
+    tags?: string[];
+    attachments?: MediaAttachment[];
+    metadata?: Record<string, any>;
+}
+export interface MediaAttachment {
+    type: "image" | "video" | "audio" | "document";
+    url: string;
+    filename?: string;
+    size?: number;
+    mimeType?: string;
+}
+export interface TemplateFilters {
+    templateCode?: string;
+    templateName?: string;
+    templateStatus?: string;
+    [key: string]: any;
+}
+export interface HistoryFilters {
+    reserve?: "Y" | "N" | boolean;
+    startDate?: string | Date;
+    endDate?: string | Date;
+    messageId?: number | string;
+    phone?: string;
+    [key: string]: any;
+}
+export interface HealthCheckResult {
+    healthy: boolean;
+    issues: string[];
+    data?: {
+        balance?: number;
+        status: string;
+        code?: number;
+        message?: string;
+    } | null;
+}
+export interface SendResult {
+    success: boolean;
+    messageId: string | null;
+    status: string;
+    error: string | null;
+}
+export interface TemplateResult {
+    success: boolean;
+    templateCode: string | null;
+    status: string;
+    error: string | null;
+}
+export interface BaseProvider<TConfig = any> {
+    readonly id: string;
+    readonly name: string;
+    readonly supportedChannels: MessageChannel[];
+    readonly supportedTypes: MessageType[];
+    healthCheck(): Promise<HealthCheckResult>;
+    sendMessage?(recipient: string, // 수신자 (전화번호 또는 이메일)
+    content: MessageContent, options?: SendOptions): Promise<SendResult>;
+    sendTemplateMessage?(templateCode: string, phoneNumber: string, variables: Record<string, any>, options?: SendOptions): Promise<SendResult>;
+    createTemplate?(template: TemplateCreateRequest): Promise<TemplateResult>;
+    getTemplates?(pageNum?: number, pageSize?: number, filters?: TemplateFilters): Promise<any>;
+    modifyTemplate?(templateCode: string, template: TemplateUpdateRequest): Promise<TemplateResult>;
+    deleteTemplate?(templateCode: string): Promise<any>;
+    getHistory?(pageNum?: number, pageSize?: number, filters?: HistoryFilters): Promise<any>;
+    cancelReservation?(messageId: number | string): Promise<any>;
+    getSenderNumbers?(): Promise<SenderNumber[]>;
+    verifySenderNumber?(phoneNumber: string): Promise<SenderVerificationResult>;
+    getChannelInfo?(channel: MessageChannel): Promise<ChannelInfo>;
+}
+export interface MessageContent {
+    channel?: MessageChannel;
+    type?: MessageType;
+    text: string;
+    title?: string;
+    templateId?: string;
+    variables?: Record<string, any>;
+    buttons?: MessageButton[];
+    attachments?: MediaAttachment[];
+}
+export interface MessageButton {
+    type: "web" | "app" | "phone" | "delivery";
+    text: string;
+    url?: string;
+    scheme?: string;
+    phoneNumber?: string;
+}
+export interface TemplateCreateRequest {
+    name: string;
+    content: string;
+    channel: MessageChannel;
+    category?: string;
+    buttons?: MessageButton[];
+    variables?: string[];
+    description?: string;
+}
+export interface TemplateUpdateRequest {
+    name?: string;
+    content?: string;
+    buttons?: MessageButton[];
+    description?: string;
+}
+export interface SenderNumber {
+    phoneNumber: string;
+    name?: string;
+    verified: boolean;
+    verifiedAt?: Date;
+    status: "active" | "pending" | "rejected" | "blocked";
+}
+export interface SenderVerificationResult {
+    success: boolean;
+    phoneNumber: string;
+    status: string;
+    verificationCode?: string;
+    error?: string;
+}
+export interface ChannelInfo {
+    channel: MessageChannel;
+    available: boolean;
+    limits: {
+        maxLength?: number;
+        maxAttachments?: number;
+        maxAttachmentSize?: number;
+    };
+    features: {
+        supportsButtons: boolean;
+        supportsAttachments: boolean;
+        supportsTemplates: boolean;
+        supportsScheduling: boolean;
+    };
+}
+export interface BaseProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    debug?: boolean;
+    timeout?: number;
+    retries?: number;
+}