@k-msg/core 0.4.0 → 0.5.0

package/dist/provider.d.ts

@@ -1,6 +1,6 @@
 import type { KMsgError } from "./errors";
 import type { Result } from "./result";
-import type { SendOptions, SendResult } from "./types/index";
+import type { MessageType, SendOptions, SendResult } from "./types/index";
 export interface Template {
     id: string;
     code: string;
@@ -24,13 +24,16 @@ export interface TemplateProvider {
         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 ProviderHealthStatus {
+    healthy: boolean;
+    issues: string[];
+    latencyMs?: number;
+    data?: Record<string, unknown>;
+}
 export interface Provider {
     readonly id: string;
     readonly name: string;
+    readonly supportedTypes: readonly MessageType[];
+    healthCheck(): Promise<ProviderHealthStatus>;
     send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
 }

package/dist/test-utils.d.ts

@@ -1,8 +1,13 @@
-import { KMsgError, KMsgErrorCode, type Provider, type Result, type SendOptions, type SendResult } from "./index";
+import { KMsgError, KMsgErrorCode, type MessageType, type Provider, type Result, type SendOptions, type SendResult } from "./index";
 export declare class MockProvider implements Provider {
     readonly id: string;
     readonly name: string;
+    readonly supportedTypes: readonly MessageType[];
     constructor(id?: string, name?: string);
+    healthCheck(): Promise<{
+        healthy: boolean;
+        issues: never[];
+    }>;
     send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
 }
 export declare const TestAssertions: {

package/dist/types/index.d.ts

@@ -1,6 +1,3 @@
 export * from "./balance";
 export * from "./history";
 export * from "./message";
-export * from "./platform";
-export * from "./provider";
-export * from "./standard";

package/dist/types/message.d.ts

@@ -1,34 +1,188 @@
 export type MessageType = "ALIMTALK" | "FRIENDTALK" | "SMS" | "LMS" | "MMS" | "NSA" | "VOICE" | "FAX" | "RCS_SMS" | "RCS_LMS" | "RCS_MMS" | "RCS_TPL" | "RCS_ITPL" | "RCS_LTPL";
-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 {
+export type MessageStatus = "PENDING" | "SENT" | "FAILED";
+export type MessageVariables = Record<string, string | number | boolean | Date | null | undefined>;
+export interface MessageButton {
     name: string;
+    /**
+     * Provider-dependent. Common values: "WL" (web link), "AL" (app link), ...
+     */
     type: string;
     urlPc?: string;
     urlMobile?: string;
 }
-export interface FriendTalkOptions extends BaseOptions {
+export interface CommonSendOptions {
+    /**
+     * Correlation id generated by KMsg (or provided by the caller).
+     * Providers must echo this value back in SendResult.messageId.
+     */
+    messageId?: string;
+    /**
+     * Optional routing hint to force a specific provider by id.
+     */
+    providerId?: string;
+    to: string;
+    /**
+     * Sender number / sender id. Optional at KMsg layer; providers may require it.
+     */
+    from?: string;
+    /**
+     * Common delivery options understood by multiple providers.
+     */
+    options?: {
+        scheduledAt?: Date;
+        /**
+         * Country code for providers that support it (e.g. SOLAPI).
+         * Examples: "82", "+82".
+         */
+        country?: string;
+        customFields?: Record<string, string>;
+    };
+    /**
+     * Provider-specific escape hatch (use sparingly).
+     */
+    providerOptions?: Record<string, unknown>;
+}
+export interface KakaoSendOptions {
+    profileId?: string;
+    disableSms?: boolean;
+    adFlag?: boolean;
+    buttons?: unknown[];
+    imageId?: string;
+    /**
+     * FriendTalk image upload link hint (SOLAPI).
+     */
+    imageLink?: string;
+    [key: string]: any;
+}
+export interface NaverSendOptions {
+    talkId?: string;
+    /**
+     * Override the template identifier for NSA (provider-specific).
+     */
+    templateCode?: string;
+    disableSms?: boolean;
+    variables?: MessageVariables;
+    buttons?: unknown[];
+    [key: string]: any;
+}
+export interface VoiceSendOptions {
+    voiceType?: "FEMALE" | "MALE";
+    headerMessage?: string;
+    tailMessage?: string;
+    replyRange?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    counselorNumber?: string;
+    [key: string]: any;
+}
+export interface FaxSendOptions {
+    fileIds?: string[];
+    fileUrls?: string[];
+    [key: string]: any;
+}
+export interface RcsSendOptions {
+    brandId?: string;
+    /**
+     * Override template identifier for RCS_*TPL types.
+     */
+    templateCode?: string;
+    copyAllowed?: boolean;
+    variables?: MessageVariables;
+    mmsType?: "M3" | "S3" | "M4" | "S4" | "M5" | "S5" | "M6" | "S6";
+    commercialType?: boolean;
+    disableSms?: boolean;
+    buttons?: unknown[];
+    additionalBody?: {
+        title?: string;
+        description?: string;
+        imageId?: string;
+        buttons?: unknown[];
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+export interface SmsSendOptions extends CommonSendOptions {
+    type: "SMS" | "LMS" | "MMS";
+    text: string;
+    /**
+     * LMS/MMS subject.
+     */
+    subject?: string;
+    /**
+     * Optional image URL for MMS (provider-specific).
+     */
+    imageUrl?: string;
+    variables?: MessageVariables;
+}
+export interface AlimTalkSendOptions extends CommonSendOptions {
+    type: "ALIMTALK";
+    templateCode: string;
+    variables: MessageVariables;
+    kakao?: KakaoSendOptions;
+}
+export interface FriendTalkSendOptions extends CommonSendOptions {
     type: "FRIENDTALK";
     text: string;
     imageUrl?: string;
-    buttons?: Button[];
+    buttons?: MessageButton[];
+    variables?: MessageVariables;
+    kakao?: KakaoSendOptions;
 }
-export interface SmsOptions extends BaseOptions {
-    type: "SMS" | "LMS" | "MMS";
+export interface NsaSendOptions extends CommonSendOptions {
+    type: "NSA";
+    templateCode: string;
+    variables: MessageVariables;
+    naver?: NaverSendOptions;
+}
+export interface VoiceMessageSendOptions extends CommonSendOptions {
+    type: "VOICE";
+    text: string;
+    variables?: MessageVariables;
+    voice?: VoiceSendOptions;
+}
+export interface FaxMessageSendOptions extends CommonSendOptions {
+    type: "FAX";
+    fax: FaxSendOptions;
+}
+export interface RcsTextSendOptions extends CommonSendOptions {
+    type: "RCS_SMS" | "RCS_LMS" | "RCS_MMS";
     text: string;
     subject?: string;
+    imageUrl?: string;
+    variables?: MessageVariables;
+    rcs?: RcsSendOptions;
+}
+export interface RcsTemplateSendOptions extends CommonSendOptions {
+    type: "RCS_TPL" | "RCS_ITPL" | "RCS_LTPL";
+    templateCode: string;
+    variables: MessageVariables;
+    rcs?: RcsSendOptions;
 }
-export type SendOptions = AlimTalkOptions | FriendTalkOptions | SmsOptions;
+export type SendOptions = SmsSendOptions | AlimTalkSendOptions | FriendTalkSendOptions | NsaSendOptions | VoiceMessageSendOptions | FaxMessageSendOptions | RcsTextSendOptions | RcsTemplateSendOptions;
+export type SmsDefaultSendInput = Omit<SmsSendOptions, "type" | "text"> & {
+    type?: undefined;
+    /**
+     * SMS text. If omitted, `content` is used.
+     */
+    text?: string;
+    /**
+     * Alias for `text`.
+     */
+    content?: string;
+};
+/**
+ * Developer-facing input type.
+ * - SMS defaults allow omitting `type` and using `content`.
+ * - Other channels are modeled as discriminated unions on `type`.
+ */
+export type SendInput = SendOptions | SmsDefaultSendInput;
 export interface SendResult {
+    /**
+     * Correlation id (equals the request `messageId`).
+     */
     messageId: string;
-    status: "PENDING" | "SENT" | "FAILED";
-    provider: string;
+    providerId: string;
+    providerMessageId?: string;
+    status: MessageStatus;
+    type: MessageType;
+    to: string;
+    raw?: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-msg/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packageManager": "bun@1.3.8",
   "description": "Core types and interfaces for K-Message platform",
   "type": "module",

package/dist/platform.d.ts

@@ -1,73 +0,0 @@
-import type { BalanceQuery, BalanceResult, BaseProvider, Config, HistoryQuery, HistoryResult, 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>;
-    };
-    balance(providerId?: string): Promise<{
-        get: (query?: BalanceQuery) => Promise<BalanceResult>;
-    }>;
-    /**
-     * @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?: Record<string, unknown>) => Promise<never>;
-        /** @deprecated Not yet implemented */
-        create: (_name: string, _content: string, _category?: string, _variables?: unknown[], _buttons?: unknown[]) => Promise<never>;
-        /** @deprecated Not yet implemented */
-        modify: (_templateCode: string, _name: string, _content: string, _buttons?: unknown[]) => Promise<never>;
-        /** @deprecated Not yet implemented */
-        delete: (_templateCode: string) => Promise<never>;
-    }>;
-    /**
-     * History operations (common API surface).
-     *
-     * Notes:
-     * - Not all providers implement history. This method will throw when unsupported.
-     * - For provider-specific, advanced fields, use provider adapter directly.
-     */
-    history(providerId?: string): Promise<{
-        list: (queryOrPage?: HistoryQuery | number, pageSize?: number, filters?: Partial<Omit<HistoryQuery, "page" | "pageSize">> & {
-            channel?: HistoryQuery["channel"];
-        }) => Promise<HistoryResult>;
-        cancelReservation: (_messageId: string) => Promise<never>;
-    }>;
-    providerHealth(providerId: string): Promise<import(".").ProviderHealthStatus>;
-    private getProviderAdapter;
-    private isSmsChannel;
-    private normalizeHistoryQuery;
-    private getFunction;
-}

package/dist/provider-registry.d.ts

@@ -1,135 +0,0 @@
-/**
- * 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/router/round-robin-router-provider.d.ts

@@ -1,20 +0,0 @@
-import type { BaseProvider, ProviderHealthStatus, StandardRequest, StandardResult } from "../types/index";
-/**
- * Round-robin router provider that forwards requests to upstream providers.
- * Useful for simple load distribution or provider rotation strategies.
- */
-export declare class RoundRobinRouterProvider implements BaseProvider<StandardRequest, StandardResult> {
-    readonly id: string;
-    readonly name: string;
-    readonly type: "messaging";
-    readonly version = "1.0.0";
-    private readonly providers;
-    private idx;
-    constructor(params: {
-        id: string;
-        name?: string;
-        providers: BaseProvider<StandardRequest, StandardResult>[];
-    });
-    healthCheck(): Promise<ProviderHealthStatus>;
-    send<T extends StandardRequest = StandardRequest, R extends StandardResult = StandardResult>(request: T): Promise<R>;
-}

package/dist/types/platform.d.ts

@@ -1,151 +0,0 @@
-import type { BalanceQuery, BalanceResult } from "./balance";
-import type { HistoryQuery, HistoryResult } from "./history";
-import type { Button, MessageType } from "./message";
-import type { BaseProvider } from "./provider";
-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, unknown>;
-    }[];
-    variables: Record<string, unknown>;
-}
-export interface UnifiedMessageRecipient {
-    phoneNumber: string;
-    variables?: Record<string, unknown>;
-}
-export interface UnifiedMessageSendOptions {
-    channel: MessageType;
-    recipients: Array<string | UnifiedMessageRecipient>;
-    providerId?: string;
-    templateCode?: string;
-    variables?: Record<string, unknown>;
-    text?: string;
-    subject?: string;
-    imageUrl?: string;
-    buttons?: Button[];
-    options?: {
-        scheduledAt?: Date;
-        senderNumber?: string;
-        subject?: string;
-        country?: string;
-        customFields?: Record<string, string>;
-        kakaoOptions?: {
-            pfId?: string;
-            templateId?: string;
-            variables?: Record<string, string>;
-            disableSms?: boolean;
-            adFlag?: boolean;
-            buttons?: unknown[];
-            imageId?: string;
-            [key: string]: unknown;
-        };
-        naverOptions?: {
-            talkId?: string;
-            templateId?: string;
-            disableSms?: boolean;
-            variables?: Record<string, string>;
-            buttons?: unknown[];
-            [key: string]: unknown;
-        };
-        voiceOptions?: {
-            voiceType: "FEMALE" | "MALE";
-            headerMessage?: string;
-            tailMessage?: string;
-            replyRange?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-            counselorNumber?: string;
-            [key: string]: unknown;
-        };
-        faxOptions?: {
-            fileIds?: string[];
-            fileUrls?: string[];
-            [key: string]: unknown;
-        };
-        rcsOptions?: {
-            brandId?: string;
-            templateId?: string;
-            copyAllowed?: boolean;
-            variables?: Record<string, string>;
-            mmsType?: "M3" | "S3" | "M4" | "S4" | "M5" | "S5" | "M6" | "S6";
-            commercialType?: boolean;
-            disableSms?: boolean;
-            buttons?: unknown[];
-            additionalBody?: {
-                title?: string;
-                description?: string;
-                imageId?: string;
-                buttons?: unknown[];
-                [key: string]: unknown;
-            };
-            [key: string]: unknown;
-        };
-        [key: string]: unknown;
-    };
-}
-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: BaseProvider): void;
-    getProvider(providerId: string): BaseProvider | null;
-    listProviders(): string[];
-    healthCheck(): Promise<PlatformHealthStatus>;
-    balance(providerId?: string): Promise<{
-        get(query?: BalanceQuery): Promise<BalanceResult>;
-    }>;
-    history(providerId?: string): Promise<{
-        list(query: HistoryQuery): Promise<HistoryResult>;
-        list(page?: number, pageSize?: number, filters?: Partial<Omit<HistoryQuery, "page" | "pageSize">> & {
-            channel?: HistoryQuery["channel"];
-        }): Promise<HistoryResult>;
-    }>;
-    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;
-        }>>;
-    };
-}