@k-msg/provider 0.1.1 → 0.1.2

package/README.md

@@ -24,7 +24,9 @@ bun add @k-msg/provider @k-msg/core
 ## Built-in Providers
 
 ### IWINV Provider
+
 Production-ready AlimTalk provider with full feature support:
+
 - ✅ AlimTalk message sending with variable substitution
 - ✅ SMS/LMS fallback for failed AlimTalk messages
 - ✅ Template management (create, update, delete, list)
@@ -137,4 +139,4 @@ class CustomMessagingService implements MessagingService {
 
 ## License
 
-MIT
+MIT

package/dist/abstract/provider.base.d.ts

@@ -0,0 +1,108 @@
+import type { ConfigurationSchema, DeliveryStatus } from "@k-msg/core";
+import type { AccountContract, AlimTalkProvider, AlimTalkRequest, AlimTalkResult, AnalyticsContract, ChannelContract, MessagingContract, ProviderCapabilities, ProviderConfiguration, TemplateContract } from "../contracts/provider.contract";
+export declare abstract class BaseAlimTalkProvider implements AlimTalkProvider {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    readonly type: "messaging";
+    abstract readonly version: string;
+    abstract readonly capabilities: ProviderCapabilities;
+    protected config: Record<string, unknown>;
+    protected isConfigured: boolean;
+    abstract templates: TemplateContract;
+    abstract channels: ChannelContract;
+    abstract messaging: MessagingContract;
+    abstract analytics: AnalyticsContract;
+    abstract account: AccountContract;
+    constructor(config?: Record<string, unknown>);
+    /**
+     * Configure the provider with necessary credentials and settings
+     */
+    configure(config: Record<string, unknown>): void;
+    abstract send<T extends AlimTalkRequest = AlimTalkRequest, R extends AlimTalkResult = AlimTalkResult>(request: T): Promise<R>;
+    abstract getStatus(requestId: string): Promise<DeliveryStatus>;
+    abstract cancel?(requestId: string): Promise<boolean>;
+    abstract getSupportedFeatures(): string[];
+    abstract getConfigurationSchema(): ConfigurationSchema;
+    abstract getProviderConfiguration(): ProviderConfiguration;
+    /**
+     * Validate the provided configuration
+     */
+    protected validateConfiguration(config: Record<string, unknown>): void;
+    private validateFieldValue;
+    /**
+     * Called after configuration is set
+     */
+    protected onConfigured(): void;
+    /**
+     * Check if the provider is properly configured
+     */
+    isReady(): boolean;
+    /**
+     * Get configuration value
+     */
+    protected getConfig<T = unknown>(key: string): T;
+    /**
+     * Check if a configuration key exists
+     */
+    protected hasConfig(key: string): boolean;
+    getCapabilities(): ProviderCapabilities;
+    /**
+     * Perform health check on the provider
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        issues: string[];
+        latency?: number;
+    }>;
+    /**
+     * Test basic connectivity to the provider
+     */
+    protected abstract testConnectivity(): Promise<void>;
+    /**
+     * Test authentication with the provider
+     */
+    protected abstract testAuthentication(): Promise<void>;
+    /**
+     * Get provider information
+     */
+    getInfo(): {
+        id: string;
+        name: string;
+        version: string;
+        capabilities: ProviderCapabilities;
+        configured: boolean;
+    };
+    /**
+     * Get provider version
+     */
+    protected abstract getVersion(): string;
+    /**
+     * Cleanup resources when provider is destroyed
+     */
+    destroy(): void;
+    /**
+     * Called when provider is being destroyed
+     */
+    protected onDestroy(): void;
+    /**
+     * Create standardized error
+     */
+    protected createError(code: string, message: string, details?: Record<string, unknown>): Error;
+    /**
+     * Log provider activity
+     */
+    protected log(level: "info" | "warn" | "error", message: string, data?: unknown): void;
+    /**
+     * Handle rate limiting
+     */
+    protected handleRateLimit(operation: string): Promise<void>;
+    /**
+     * Retry mechanism for failed operations
+     */
+    protected withRetry<T>(operation: () => Promise<T>, options?: {
+        maxRetries?: number;
+        initialDelay?: number;
+        maxDelay?: number;
+        backoffFactor?: number;
+    }): Promise<T>;
+}

package/dist/adapters/aligo.adapter.d.ts

@@ -0,0 +1,50 @@
+import { BaseProviderAdapter, KMsgError, type Provider, type Result, type SendOptions, type SendResult, type StandardError, type StandardRequest, type StandardResult, type Template, type TemplateProvider } from "@k-msg/core";
+import type { AligoConfig, AligoResponse } from "../types/aligo";
+export declare class AligoAdapter extends BaseProviderAdapter implements Provider, TemplateProvider {
+    protected readonly aligoConfig: AligoConfig;
+    private static readonly directTemplates;
+    readonly id = "aligo";
+    readonly name = "Aligo Smart SMS";
+    private readonly SMS_HOST;
+    private readonly ALIMTALK_HOST;
+    constructor(aligoConfig: AligoConfig);
+    send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
+    sendStandard(request: StandardRequest): Promise<StandardResult>;
+    adaptRequest(request: StandardRequest): any;
+    adaptResponse(response: AligoResponse): StandardResult;
+    mapError(error: any): StandardError;
+    private mapAligoError;
+    getAuthHeaders(): Record<string, string>;
+    getBaseUrl(): string;
+    getEndpoint(operation: string): string;
+    /**
+     * Aligo 특화 기능: 잔액 조회
+     */
+    getBalance(): Promise<number>;
+    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>>;
+    private sendSMS;
+    private sendAlimTalk;
+    private sendFriendTalk;
+    private formatAligoDate;
+    private request;
+    private handleError;
+    private toProviderChannel;
+    private normalizeChannelLike;
+    private resolveStandardChannel;
+    private extractStandardMessage;
+    private buildSmsBodyFromStandard;
+    private isKakaoChannel;
+    private buildFriendTalkBody;
+    private buildAlimTalkBodyFromStandard;
+    private buildFriendTalkBodyFromStandard;
+    private interpolateMessage;
+    private mapTemplateStatus;
+}

package/dist/adapters/iwinv.adapter.d.ts

@@ -0,0 +1,111 @@
+/**
+ * IWINV Provider Adapter
+ * IWINV API를 표준 인터페이스로 변환하는 어댑터
+ */
+import { type AdapterFactory, BaseProviderAdapter, KMsgError, type ProviderConfig, type ProviderMetadata, type Result, type StandardError, type StandardRequest, type StandardResult, type Template, type TemplateProvider } from "@k-msg/core";
+export interface IWINVError {
+    code: number;
+    message: string;
+    status?: number;
+    data?: unknown;
+}
+export interface IWINVRequest {
+    templateCode: string;
+    reserve?: "Y" | "N";
+    sendDate?: string;
+    reSend?: "Y" | "N";
+    resendCallback?: string;
+    resendType?: "Y" | "N";
+    resendTitle?: string;
+    resendContent?: string;
+    list: IWINVRecipient[];
+}
+export interface IWINVRecipient {
+    phone: string;
+    templateParam?: string[];
+}
+export interface IWINVResponse {
+    code: number;
+    message: string;
+    success?: number;
+    fail?: number;
+    seqNo?: number;
+}
+export interface IWINVBalanceResponse {
+    code: number;
+    charge: number;
+}
+export interface IWINVTemplate {
+    templateCode: string;
+    templateName: string;
+    templateContent: string;
+    status: "Y" | "I" | "R";
+    templateStatusMsg?: string;
+    templateStatusComments?: string;
+    createDate: string;
+    buttons: any[];
+}
+export interface IWINVTemplateListResponse extends IWINVResponse {
+    totalCount: number;
+    list: IWINVTemplate[];
+}
+export declare function isIWINVError(error: unknown): error is IWINVError;
+export declare function isIWINVResponse(response: unknown): response is IWINVResponse;
+export declare function isIWINVBalanceResponse(response: unknown): response is IWINVBalanceResponse;
+export interface IWINVConfig extends ProviderConfig {
+    userId?: string;
+    senderNumber?: string;
+    sendEndpoint?: string;
+}
+/**
+ * IWINV API 어댑터 구현
+ */
+export declare class IWINVAdapter extends BaseProviderAdapter implements TemplateProvider {
+    private static readonly directTemplates;
+    private readonly endpoints;
+    constructor(config: IWINVConfig);
+    adaptRequest(request: StandardRequest): IWINVRequest;
+    adaptResponse(response: IWINVResponse): StandardResult;
+    mapError(error: IWINVError | Error | unknown): StandardError;
+    getAuthHeaders(): Record<string, string>;
+    getBaseUrl(): string;
+    getEndpoint(operation: string): string;
+    getRequestConfig(): RequestInit;
+    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>>;
+    private mapIWINVTemplate;
+    private mapIWINVTemplateStatus;
+    isRetryableError(error: IWINVError | Error | unknown): boolean;
+    /**
+     * IWINV 날짜 형식으로 변환 (yyyy-MM-dd HH:mm:ss)
+     */
+    private formatIWINVDate;
+    /**
+     * IWINV 상태 코드를 표준 상태로 매핑
+     */
+    private mapIWINVStatus;
+    /**
+     * IWINV 특화 기능: 예약 발송 취소
+     */
+    cancelScheduledMessage(messageId: string): Promise<boolean>;
+    /**
+     * IWINV 특화 기능: 잔액 조회
+     */
+    getBalance(): Promise<number>;
+}
+/**
+ * IWINV 어댑터 팩토리
+ */
+export declare class IWINVAdapterFactory implements AdapterFactory {
+    create(config: ProviderConfig): BaseProviderAdapter;
+    private isValidIWINVConfig;
+    supports(providerId: string): boolean;
+    getMetadata(): ProviderMetadata;
+}

package/dist/aligo/provider.d.ts

@@ -0,0 +1,18 @@
+import { type SendOptions, type StandardRequest, UniversalProvider } from "@k-msg/core";
+import type { AligoConfig } from "../types/aligo";
+export declare class AligoProvider extends UniversalProvider {
+    constructor(config: AligoConfig);
+    send(params: SendOptions | StandardRequest | any): Promise<any>;
+    getBalance(): Promise<number>;
+}
+export declare const createAligoProvider: (config: AligoConfig) => AligoProvider;
+export declare const createDefaultAligoProvider: () => AligoProvider;
+export declare class AligoProviderFactory {
+    static create(config: AligoConfig): AligoProvider;
+    static createDefault(): AligoProvider;
+    static getInstance(): {
+        createProvider: (config: AligoConfig) => AligoProvider;
+        initialize: () => void;
+    };
+}
+export declare function initializeAligo(): void;

package/dist/config/provider-config-v2.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Enhanced Provider Configuration System
+ * 개선된 프로바이더 설정 시스템
+ */
+export interface ProviderConfigBase {
+    apiKey: string;
+    baseUrl: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+}
+export interface AlimTalkConfig extends ProviderConfigBase {
+    type: "alimtalk";
+    senderKey?: string;
+    fallbackSettings?: {
+        enableSMSFallback: boolean;
+        smsConfig?: SMSConfig;
+    };
+    templateValidation?: {
+        enableStrictMode: boolean;
+        allowDynamicTemplates: boolean;
+    };
+}
+export interface SMSConfig extends ProviderConfigBase {
+    type: "sms";
+    senderNumber: string;
+    defaultMsgType: "SMS" | "LMS" | "MMS";
+    autoDetectMessageType?: boolean;
+    lengthLimits?: {
+        sms: number;
+        lms: number;
+    };
+}
+export interface MMSConfig extends ProviderConfigBase {
+    type: "mms";
+    senderNumber: string;
+    mediaSettings?: {
+        maxFileSize: number;
+        allowedTypes: string[];
+        compressionQuality: number;
+    };
+}
+export interface ConnectionPoolConfig {
+    maxConnections: number;
+    idleTimeout: number;
+    connectionTimeout: number;
+    keepAlive: boolean;
+}
+export interface CacheConfig {
+    enabled: boolean;
+    ttl: number;
+    maxSize: number;
+    strategy: "LRU" | "FIFO" | "TTL";
+}
+export interface CircuitBreakerConfig {
+    enabled: boolean;
+    failureThreshold: number;
+    timeoutMs: number;
+    retryDelayMs: number;
+    maxRetries: number;
+}
+export interface RateLimitConfig {
+    requestsPerSecond: number;
+    burstSize: number;
+    strategy: "token_bucket" | "sliding_window";
+}
+export interface EnvironmentConfig {
+    environment: "development" | "staging" | "production";
+    rateLimits: RateLimitConfig;
+    monitoring: {
+        enableMetrics: boolean;
+        enableTracing: boolean;
+        enableHealthChecks: boolean;
+        metricsInterval: number;
+    };
+    logging: {
+        level: "debug" | "info" | "warn" | "error";
+        structured: boolean;
+        sensitiveDataMasking: boolean;
+    };
+}
+export interface IWINVConfigV2 {
+    environment: EnvironmentConfig;
+    alimtalk?: AlimTalkConfig;
+    sms?: SMSConfig;
+    mms?: MMSConfig;
+    shared: {
+        connectionPool: ConnectionPoolConfig;
+        cache: CacheConfig;
+        circuitBreaker: CircuitBreakerConfig;
+    };
+    security?: {
+        enableApiKeyValidation: boolean;
+        enableRequestSigning: boolean;
+        allowedDomains?: string[];
+    };
+}
+export declare class IWINVConfigBuilder {
+    private config;
+    static create(): IWINVConfigBuilder;
+    environment(env: EnvironmentConfig): this;
+    alimtalk(config: AlimTalkConfig): this;
+    sms(config: SMSConfig): this;
+    mms(config: MMSConfig): this;
+    shared(config: IWINVConfigV2["shared"]): this;
+    security(config: IWINVConfigV2["security"]): this;
+    build(): IWINVConfigV2;
+}
+export declare class ConfigFactory {
+    static development(): IWINVConfigV2;
+    static production(): IWINVConfigV2;
+    static fromEnvironment(): IWINVConfigV2;
+}
+export declare class ConfigValidator {
+    static validate(config: IWINVConfigV2): ConfigValidationResult;
+    private static isValidUrl;
+}
+export interface ConfigValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}