@k-msg/core 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @k-msg/core
 
-Core library for the K-Message platform. Provides foundational functionality including type definitions, error handling, retry logic, and platform interfaces.
+The foundational package of the K-Message platform, providing essential types, error handling, retry mechanisms, and platform interfaces for Korean multi-channel messaging.
 
 ## Installation
 
@@ -12,12 +12,29 @@ bun add @k-msg/core
 
 ## Features
 
-- **AlimTalkPlatform**: Core messaging platform interface
-- **Error Handling**: Comprehensive error types and handling logic
-- **Retry Mechanism**: Automatic retry for network failures
-- **Health Checks**: System health monitoring and diagnostics
+### 🏗️ **Core Platform Interface**
+- **AlimTalkPlatform**: Unified messaging platform abstraction
+- **Provider Management**: Multi-provider support and switching
+- **Feature Flags**: Configurable platform capabilities
 
-## Basic Usage
+### ⚠️ **Comprehensive Error Handling**
+- **KMessageError Hierarchy**: Structured error types for different scenarios
+- **Error Context**: Rich error information with operation context
+- **Error Recovery**: Built-in fallback and recovery strategies
+
+### 🔄 **Retry & Resilience**
+- **Exponential Backoff**: Smart retry with increasing delays
+- **Circuit Breaker**: Automatic failure protection
+- **Jitter**: Randomized delays to prevent thundering herd
+
+### 💊 **Health Monitoring**
+- **System Health Checks**: Multi-component health validation
+- **Service Discovery**: Dynamic provider health monitoring
+- **Dependency Tracking**: External service availability checks
+
+## Quick Start
+
+### Basic Platform Setup
 
 ```typescript
 import { AlimTalkPlatform } from '@k-msg/core';
@@ -32,29 +49,239 @@ const platform = new AlimTalkPlatform({
   }
 });
 
-// Get platform information
+// Get platform capabilities
 const info = platform.getInfo();
-console.log(info);
+console.log(`Platform: ${info.name}, Version: ${info.version}`);
+console.log(`Supported providers: ${info.supportedProviders.join(', ')}`);
 
-// Perform health check
+// Perform comprehensive health check
 const health = await platform.healthCheck();
-console.log(health);
+console.log(`Health: ${health.status}, Services: ${Object.keys(health.services).length}`);
 ```
 
-## Error Handling
+### Error Handling Patterns
 
 ```typescript
-import { KMessageError, Result } from '@k-msg/core';
+import { KMessageError, KMessageErrorCode, Result } from '@k-msg/core';
+
+// Method 1: Result Pattern (Recommended)
+const result = await Result.fromPromise(
+  provider.sendMessage(message)
+);
 
-// Using Result pattern
-const result = await Result.fromPromise(someAsyncOperation());
 if (result.isSuccess) {
-  console.log(result.data);
+  console.log(`Message sent: ${result.data.messageId}`);
 } else {
-  console.error(result.error);
+  console.error(`Send failed: ${result.error.message}`);
+  
+  // Handle specific error types
+  if (result.error.code === KMessageErrorCode.PROVIDER_TIMEOUT) {
+    // Retry with different provider
+  } else if (result.error.code === KMessageErrorCode.TEMPLATE_NOT_FOUND) {
+    // Create template or use fallback
+  }
+}
+
+// Method 2: Try-Catch with Structured Errors
+try {
+  const response = await provider.sendMessage(message);
+  console.log('Success:', response);
+} catch (error) {
+  if (error instanceof KMessageError) {
+    console.error(`[${error.code}] ${error.message}`);
+    console.error('Context:', error.context);
+    
+    // Access original cause if available
+    if (error.cause) {
+      console.error('Root cause:', error.cause);
+    }
+  } else {
+    // Handle unexpected errors
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Retry Configuration
+
+```typescript
+import { RetryManager, RetryConfig } from '@k-msg/core';
+
+// Custom retry configuration
+const retryConfig: RetryConfig = {
+  maxAttempts: 3,
+  baseDelay: 1000,      // 1 second
+  maxDelay: 10000,      // 10 seconds
+  backoffMultiplier: 2,
+  jitterType: 'full',   // full, half, none
+  retryableErrors: [
+    KMessageErrorCode.NETWORK_ERROR,
+    KMessageErrorCode.PROVIDER_TIMEOUT,
+    KMessageErrorCode.RATE_LIMIT_EXCEEDED
+  ]
+};
+
+const retryManager = new RetryManager(retryConfig);
+
+// Execute with retry
+const result = await retryManager.execute(async () => {
+  return await provider.sendMessage(message);
+});
+```
+
+### Health Check Implementation
+
+```typescript
+import { HealthChecker, HealthStatus } from '@k-msg/core';
+
+const healthChecker = new HealthChecker();
+
+// Register custom health checks
+healthChecker.register('database', async () => {
+  const connected = await checkDatabaseConnection();
+  return {
+    status: connected ? HealthStatus.HEALTHY : HealthStatus.UNHEALTHY,
+    details: { connected, lastCheck: new Date() }
+  };
+});
+
+healthChecker.register('external-api', async () => {
+  const responseTime = await measureApiResponseTime();
+  return {
+    status: responseTime < 1000 ? HealthStatus.HEALTHY : HealthStatus.DEGRADED,
+    details: { responseTime, threshold: 1000 }
+  };
+});
+
+// Perform comprehensive health check
+const overallHealth = await healthChecker.checkAll();
+console.log(`Overall status: ${overallHealth.status}`);
+console.log(`Healthy services: ${overallHealth.healthyCount}/${overallHealth.totalCount}`);
+```
+
+## API Reference
+
+### Core Types
+
+```typescript
+// Platform configuration
+interface AlimTalkPlatformConfig {
+  providers: string[];
+  defaultProvider: string;
+  features: PlatformFeatures;
+  retryConfig?: RetryConfig;
+  healthCheckConfig?: HealthCheckConfig;
+}
+
+// Error types
+enum KMessageErrorCode {
+  UNKNOWN = 'UNKNOWN',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  PROVIDER_ERROR = 'PROVIDER_ERROR',
+  TEMPLATE_ERROR = 'TEMPLATE_ERROR',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+  // ... more error codes
 }
+
+// Health check results
+interface HealthCheckResult {
+  status: HealthStatus;
+  services: Record<string, ServiceHealthInfo>;
+  timestamp: Date;
+  totalChecks: number;
+  passedChecks: number;
+}
+```
+
+### Test Utilities
+
+```typescript
+import { TestData, TestAssertions } from '@k-msg/core/test-utils';
+
+// Generate test data
+const testMessage = TestData.createMessage({
+  provider: 'iwinv',
+  templateCode: 'AUTH_OTP',
+  phoneNumber: '01012345678'
+});
+
+// Test assertions
+await TestAssertions.assertMessageSent(result);
+TestAssertions.assertErrorType(error, KMessageErrorCode.TEMPLATE_NOT_FOUND);
 ```
 
+## Advanced Usage
+
+### Custom Error Types
+
+```typescript
+import { KMessageError, KMessageErrorCode } from '@k-msg/core';
+
+class CustomProviderError extends KMessageError {
+  constructor(
+    message: string,
+    public readonly providerId: string,
+    cause?: Error
+  ) {
+    super(
+      message,
+      KMessageErrorCode.PROVIDER_ERROR,
+      { operation: 'send_message', provider: providerId },
+      cause
+    );
+  }
+}
+```
+
+### Plugin Integration
+
+```typescript
+import { AlimTalkPlatform, PlatformPlugin } from '@k-msg/core';
+
+class LoggingPlugin implements PlatformPlugin {
+  name = 'logging';
+  
+  async initialize(platform: AlimTalkPlatform) {
+    platform.on('message_sent', (event) => {
+      console.log(`Message sent: ${event.messageId}`);
+    });
+    
+    platform.on('error', (event) => {
+      console.error(`Error: ${event.error.message}`);
+    });
+  }
+}
+
+const platform = new AlimTalkPlatform(config);
+await platform.use(new LoggingPlugin());
+```
+
+## Best Practices
+
+1. **Always use Result pattern** for error handling in production code
+2. **Configure retries** appropriately for your use case
+3. **Implement health checks** for all external dependencies
+4. **Use structured logging** with error context information
+5. **Monitor error rates** and adjust retry policies accordingly
+
+## Testing
+
+```bash
+# Run unit tests
+bun test
+
+# Run with coverage
+bun test --coverage
+
+# Run specific test files
+bun test retry.test.ts
+```
+
+## Contributing
+
+See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
 ## License
 
-MIT
+MIT License - see [LICENSE](../../LICENSE) for details.

package/dist/config.d.ts

@@ -0,0 +1,206 @@
+import { z } from "zod";
+import { LogLevel } from "./logger";
+export declare const DatabaseConfigSchema: z.ZodObject<{
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    database: z.ZodString;
+    username: z.ZodString;
+    password: z.ZodString;
+    ssl: z.ZodDefault<z.ZodBoolean>;
+    maxConnections: z.ZodDefault<z.ZodNumber>;
+    connectionTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const RedisConfigSchema: z.ZodObject<{
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    password: z.ZodOptional<z.ZodString>;
+    db: z.ZodDefault<z.ZodNumber>;
+    keyPrefix: z.ZodDefault<z.ZodString>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const LoggerConfigSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<typeof LogLevel>>;
+    enableConsole: z.ZodDefault<z.ZodBoolean>;
+    enableFile: z.ZodDefault<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
+    maxFileSize: z.ZodDefault<z.ZodNumber>;
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+    enableJson: z.ZodDefault<z.ZodBoolean>;
+    enableColors: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const HealthConfigSchema: z.ZodObject<{
+    timeout: z.ZodDefault<z.ZodNumber>;
+    interval: z.ZodDefault<z.ZodNumber>;
+    retries: z.ZodDefault<z.ZodNumber>;
+    includeMetrics: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const IWINVConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodDefault<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    retryAttempts: z.ZodDefault<z.ZodNumber>;
+    retryDelay: z.ZodDefault<z.ZodNumber>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+    rateLimit: z.ZodDefault<z.ZodObject<{
+        requests: z.ZodDefault<z.ZodNumber>;
+        perSecond: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SMSConfigSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        iwinv: "iwinv";
+        aligo: "aligo";
+        coolsms: "coolsms";
+    }>;
+    apiKey: z.ZodString;
+    apiSecret: z.ZodOptional<z.ZodString>;
+    senderId: z.ZodString;
+    defaultCountryCode: z.ZodDefault<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ServerConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+    cors: z.ZodDefault<z.ZodObject<{
+        origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        credentials: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    maxRequestSize: z.ZodDefault<z.ZodNumber>;
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    enableMetrics: z.ZodDefault<z.ZodBoolean>;
+    enableDocs: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const QueueConfigSchema: z.ZodObject<{
+    maxConcurrency: z.ZodDefault<z.ZodNumber>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+    retryDelay: z.ZodDefault<z.ZodNumber>;
+    maxAge: z.ZodDefault<z.ZodNumber>;
+    batchSize: z.ZodDefault<z.ZodNumber>;
+    processingInterval: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const KMessageConfigSchema: z.ZodObject<{
+    environment: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        staging: "staging";
+        production: "production";
+    }>>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        cors: z.ZodDefault<z.ZodObject<{
+            origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            credentials: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        maxRequestSize: z.ZodDefault<z.ZodNumber>;
+        requestTimeout: z.ZodDefault<z.ZodNumber>;
+        enableMetrics: z.ZodDefault<z.ZodBoolean>;
+        enableDocs: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    database: z.ZodOptional<z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        port: z.ZodDefault<z.ZodNumber>;
+        database: z.ZodString;
+        username: z.ZodString;
+        password: z.ZodString;
+        ssl: z.ZodDefault<z.ZodBoolean>;
+        maxConnections: z.ZodDefault<z.ZodNumber>;
+        connectionTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    redis: z.ZodOptional<z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        port: z.ZodDefault<z.ZodNumber>;
+        password: z.ZodOptional<z.ZodString>;
+        db: z.ZodDefault<z.ZodNumber>;
+        keyPrefix: z.ZodDefault<z.ZodString>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    logger: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<typeof LogLevel>>;
+        enableConsole: z.ZodDefault<z.ZodBoolean>;
+        enableFile: z.ZodDefault<z.ZodBoolean>;
+        filePath: z.ZodOptional<z.ZodString>;
+        maxFileSize: z.ZodDefault<z.ZodNumber>;
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+        enableJson: z.ZodDefault<z.ZodBoolean>;
+        enableColors: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    health: z.ZodDefault<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodNumber>;
+        interval: z.ZodDefault<z.ZodNumber>;
+        retries: z.ZodDefault<z.ZodNumber>;
+        includeMetrics: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    queue: z.ZodDefault<z.ZodObject<{
+        maxConcurrency: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        retryDelay: z.ZodDefault<z.ZodNumber>;
+        maxAge: z.ZodDefault<z.ZodNumber>;
+        batchSize: z.ZodDefault<z.ZodNumber>;
+        processingInterval: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    providers: z.ZodDefault<z.ZodObject<{
+        iwinv: z.ZodOptional<z.ZodObject<{
+            apiKey: z.ZodString;
+            baseUrl: z.ZodDefault<z.ZodString>;
+            timeout: z.ZodDefault<z.ZodNumber>;
+            retryAttempts: z.ZodDefault<z.ZodNumber>;
+            retryDelay: z.ZodDefault<z.ZodNumber>;
+            debug: z.ZodDefault<z.ZodBoolean>;
+            rateLimit: z.ZodDefault<z.ZodObject<{
+                requests: z.ZodDefault<z.ZodNumber>;
+                perSecond: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        sms: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodEnum<{
+                iwinv: "iwinv";
+                aligo: "aligo";
+                coolsms: "coolsms";
+            }>;
+            apiKey: z.ZodString;
+            apiSecret: z.ZodOptional<z.ZodString>;
+            senderId: z.ZodString;
+            defaultCountryCode: z.ZodDefault<z.ZodString>;
+            timeout: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    features: z.ZodDefault<z.ZodObject<{
+        enableBulkSending: z.ZodDefault<z.ZodBoolean>;
+        enableScheduling: z.ZodDefault<z.ZodBoolean>;
+        enableAnalytics: z.ZodDefault<z.ZodBoolean>;
+        enableWebhooks: z.ZodDefault<z.ZodBoolean>;
+        enableTemplateCache: z.ZodDefault<z.ZodBoolean>;
+        maxTemplatesPerProvider: z.ZodDefault<z.ZodNumber>;
+        maxRecipientsPerBatch: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    security: z.ZodDefault<z.ZodObject<{
+        apiKeyRequired: z.ZodDefault<z.ZodBoolean>;
+        rateLimitEnabled: z.ZodDefault<z.ZodBoolean>;
+        maxRequestsPerMinute: z.ZodDefault<z.ZodNumber>;
+        enableCors: z.ZodDefault<z.ZodBoolean>;
+        trustedProxies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DatabaseConfig = z.infer<typeof DatabaseConfigSchema>;
+export type RedisConfig = z.infer<typeof RedisConfigSchema>;
+export type ConfigLoggerConfig = z.infer<typeof LoggerConfigSchema>;
+export type HealthConfig = z.infer<typeof HealthConfigSchema>;
+export type IWINVConfig = z.infer<typeof IWINVConfigSchema>;
+export type SMSConfig = z.infer<typeof SMSConfigSchema>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export type QueueConfig = z.infer<typeof QueueConfigSchema>;
+export type KMessageConfig = z.infer<typeof KMessageConfigSchema>;
+export declare class ConfigLoader {
+    static loadFromEnv(): KMessageConfig;
+    static loadFromFile(filePath: string): Promise<KMessageConfig>;
+    static validate(config: any): KMessageConfig;
+    static getDefaults(): KMessageConfig;
+}
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+export declare const developmentConfig: DeepPartial<KMessageConfig>;
+export declare const productionConfig: DeepPartial<KMessageConfig>;
+export declare function mergeConfigs(base: KMessageConfig, override: Partial<KMessageConfig>): KMessageConfig;
+export declare function validateProviderConfig(provider: "iwinv" | "sms", config: any): any;
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+export declare enum KMsgErrorCode {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    TEMPLATE_NOT_FOUND = "TEMPLATE_NOT_FOUND",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    NETWORK_TIMEOUT = "NETWORK_TIMEOUT",
+    NETWORK_SERVICE_UNAVAILABLE = "NETWORK_SERVICE_UNAVAILABLE",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    MESSAGE_SEND_FAILED = "MESSAGE_SEND_FAILED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+export declare class KMsgError extends Error {
+    readonly code: KMsgErrorCode;
+    readonly details?: Record<string, any>;
+    constructor(code: KMsgErrorCode, message: string, details?: Record<string, any>);
+    toJSON(): {
+        name: string;
+        code: KMsgErrorCode;
+        message: string;
+        details: Record<string, any> | undefined;
+    };
+}
+export declare const ErrorUtils: {
+    isRetryable: (error: any) => boolean;
+};

package/dist/health.d.ts

@@ -0,0 +1,39 @@
+export interface HealthStatus {
+    healthy: boolean;
+    timestamp: Date;
+    uptime: number;
+    version?: string;
+    services?: Record<string, ServiceHealth>;
+    metrics?: Record<string, any>;
+}
+export interface ServiceHealth {
+    healthy: boolean;
+    latency?: number;
+    error?: string;
+    lastCheck?: Date;
+}
+export interface HealthCheckConfig {
+    timeout?: number;
+    interval?: number;
+    retries?: number;
+    includeMetrics?: boolean;
+}
+export declare class HealthChecker {
+    private config;
+    private startTime;
+    private services;
+    private lastCheck;
+    constructor(config?: HealthCheckConfig);
+    registerService(name: string, checkFn: () => Promise<ServiceHealth>): void;
+    unregisterService(name: string): boolean;
+    clearServices(): void;
+    checkHealth(): Promise<HealthStatus>;
+    getLastKnownStatus(): HealthStatus;
+    private timeoutPromise;
+    private calculateAverageLatency;
+}
+export declare class SimpleHealthChecker {
+    static database(): () => Promise<ServiceHealth>;
+    static external(url: string, timeout?: number): () => Promise<ServiceHealth>;
+    static memory(maxUsageMB?: number): () => Promise<ServiceHealth>;
+}