@withwiz/toolkit 0.1.0

package/dist/error/logging/transports/slack.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Slack Transport
+ *
+ * Slack Webhook으로 알림 전송
+ */
+import { BaseTransport } from './base';
+import type { ILogEntry, ELogLevel } from '@withwiz/error/logging/types';
+/**
+ * SlackTransport 옵션
+ */
+export interface ISlackTransportOptions {
+    enabled?: boolean;
+    webhookUrl?: string;
+    minLevel?: ELogLevel;
+    channel?: string;
+    username?: string;
+    iconEmoji?: string;
+}
+/**
+ * SlackTransport 클래스
+ *
+ * @example
+ * ```typescript
+ * const transport = new SlackTransport({
+ *   webhookUrl: process.env.SLACK_WEBHOOK_URL,
+ *   minLevel: ELogLevel.CRITICAL,
+ *   channel: '#errors',
+ * });
+ * ```
+ */
+export declare class SlackTransport extends BaseTransport {
+    private webhookUrl;
+    private minLevel;
+    private channel?;
+    private username;
+    private iconEmoji;
+    constructor(options?: ISlackTransportOptions);
+    log(entry: ILogEntry): Promise<void>;
+    /**
+     * Slack 메시지 페이로드 생성
+     */
+    private buildPayload;
+    /**
+     * 문자열 자르기
+     */
+    private truncate;
+    /**
+     * 로그 레벨 체크
+     */
+    private shouldLog;
+}

package/dist/error/logging/transports/slack.js

@@ -0,0 +1,9 @@
+import {
+  SlackTransport
+} from "../../../chunk-EQYTE7WD.js";
+import "../../../chunk-HGC4CCKB.js";
+import "../../../chunk-6C7HQIX4.js";
+import "../../../chunk-ORMEWXMH.js";
+export {
+  SlackTransport
+};

package/dist/error/logging/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 로깅 시스템 타입 정의
+ */
+import type { AppError } from '@withwiz/error/app-error';
+/**
+ * 로그 레벨
+ */
+export declare enum ELogLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error",
+    CRITICAL = "critical"
+}
+/**
+ * 에러 로그 컨텍스트
+ */
+export interface IErrorLogContext {
+    requestId?: string;
+    method?: string;
+    path?: string;
+    userAgent?: string;
+    ip?: string;
+    userId?: string;
+    userEmail?: string;
+    userRole?: string;
+    errorCode?: number;
+    errorMessage?: string;
+    errorStack?: string;
+    environment?: string;
+    version?: string;
+    timestamp?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 로그 엔트리
+ */
+export interface ILogEntry {
+    level: ELogLevel;
+    message: string;
+    context: IErrorLogContext;
+    error?: AppError | Error;
+    timestamp: Date;
+}
+/**
+ * Transport 인터페이스
+ */
+export interface ITransport {
+    /**
+     * Transport 이름
+     */
+    name: string;
+    /**
+     * 로그 전송
+     */
+    log(entry: ILogEntry): Promise<void>;
+    /**
+     * Transport 활성화 여부
+     */
+    isEnabled(): boolean;
+}
+/**
+ * ErrorLogger 옵션
+ */
+export interface IErrorLoggerOptions {
+    /**
+     * 최소 로그 레벨
+     * 이 레벨 이상의 로그만 기록
+     */
+    minLevel?: ELogLevel;
+    /**
+     * 환경 정보
+     */
+    environment?: string;
+    /**
+     * 앱 버전
+     */
+    version?: string;
+    /**
+     * Transport 목록
+     */
+    transports?: ITransport[];
+}

package/dist/error/logging/types.js

@@ -0,0 +1,7 @@
+import {
+  ELogLevel
+} from "../../chunk-6C7HQIX4.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  ELogLevel
+};

package/dist/error/messages/en.d.ts

@@ -0,0 +1,5 @@
+/**
+ * English Error Messages
+ */
+import type { TErrorMessages } from './types';
+export declare const enMessages: TErrorMessages;

package/dist/error/messages/en.js

@@ -0,0 +1,7 @@
+import {
+  enMessages
+} from "../../chunk-N4YGR5WH.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  enMessages
+};

package/dist/error/messages/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 메시지 레지스트리
+ * 에러 코드에 대한 다중 언어 메시지 제공
+ */
+import type { IErrorMessage, TLocale, TErrorMessages } from './types';
+/**
+ * 에러 코드에 해당하는 메시지 가져오기
+ *
+ * @param code - 에러 코드 (5자리)
+ * @param locale - 언어 (기본값: 'ko')
+ * @returns 에러 메시지
+ */
+export declare function getErrorMessage(code: number, locale?: TLocale): IErrorMessage;
+/**
+ * 특정 언어의 모든 메시지 가져오기
+ *
+ * @param locale - 언어
+ * @returns 모든 에러 메시지
+ */
+export declare function getAllMessages(locale?: TLocale): TErrorMessages;
+/**
+ * 에러 코드가 메시지를 가지고 있는지 확인
+ *
+ * @param code - 에러 코드
+ * @param locale - 언어
+ * @returns 메시지 존재 여부
+ */
+export declare function hasMessage(code: number, locale?: TLocale): boolean;
+/**
+ * 지원하는 언어 목록
+ */
+export declare const supportedLocales: TLocale[];
+/**
+ * 언어가 지원되는지 확인
+ *
+ * @param locale - 언어
+ * @returns 지원 여부
+ */
+export declare function isLocaleSupported(locale: string): locale is TLocale;
+export type { IErrorMessage, TLocale, TErrorMessages, IDefaultMessages } from './types';

package/dist/error/messages/index.js

@@ -0,0 +1,17 @@
+import {
+  getAllMessages,
+  getErrorMessage,
+  hasMessage,
+  isLocaleSupported,
+  supportedLocales
+} from "../../chunk-EEUBKZV4.js";
+import "../../chunk-N4YGR5WH.js";
+import "../../chunk-KXAWBFJN.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  getAllMessages,
+  getErrorMessage,
+  hasMessage,
+  isLocaleSupported,
+  supportedLocales
+};

package/dist/error/messages/ko.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 한국어 에러 메시지
+ */
+import type { TErrorMessages } from './types';
+export declare const koMessages: TErrorMessages;

package/dist/error/messages/ko.js

@@ -0,0 +1,7 @@
+import {
+  koMessages
+} from "../../chunk-KXAWBFJN.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  koMessages
+};

package/dist/error/messages/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 에러 메시지 타입 정의
+ */
+/**
+ * 에러 메시지 인터페이스
+ */
+export interface IErrorMessage {
+    /** 에러 제목 (짧고 명확하게) */
+    title: string;
+    /** 에러 설명 (상세 내용) */
+    description: string;
+    /** 사용자 행동 유도 (선택적) */
+    action?: string;
+}
+/**
+ * 지원 언어 타입
+ */
+export type TLocale = 'ko' | 'en' | 'ja';
+/**
+ * 에러 코드별 메시지 맵
+ */
+export type TErrorMessages = Record<number, IErrorMessage>;
+/**
+ * 기본 메시지 (Fallback용)
+ */
+export interface IDefaultMessages {
+    ko: IErrorMessage;
+    en: IErrorMessage;
+    ja: IErrorMessage;
+}

package/dist/error/recovery/circuit-breaker.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Circuit Breaker 패턴
+ *
+ * 연속된 실패 시 일시적으로 요청 차단
+ */
+/**
+ * Circuit Breaker 상태
+ */
+export declare enum ECircuitState {
+    CLOSED = "closed",// 정상 동작
+    OPEN = "open",// 요청 차단
+    HALF_OPEN = "half-open"
+}
+/**
+ * CircuitBreaker 옵션
+ */
+export interface ICircuitBreakerOptions {
+    /** 실패 임계값 (기본값: 5) */
+    failureThreshold?: number;
+    /** 성공 임계값 (Half-Open 상태에서, 기본값: 2) */
+    successThreshold?: number;
+    /** 타임아웃 (밀리초, 기본값: 60000) */
+    timeout?: number;
+    /** 상태 변경 콜백 */
+    onStateChange?: (oldState: ECircuitState, newState: ECircuitState) => void;
+    /** 에러 콜백 */
+    onError?: (error: unknown) => void;
+}
+/**
+ * CircuitBreaker 클래스
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   timeout: 60000,
+ * });
+ *
+ * const data = await breaker.execute(async () => {
+ *   const res = await fetch('/api/data');
+ *   return res.json();
+ * });
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private nextAttemptTime;
+    private options;
+    constructor(options?: ICircuitBreakerOptions);
+    /**
+     * 함수 실행
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 성공 처리
+     */
+    private onSuccess;
+    /**
+     * 실패 처리
+     */
+    private onFailure;
+    /**
+     * 상태 변경
+     */
+    private setState;
+    /**
+     * 현재 상태 조회
+     */
+    getState(): ECircuitState;
+    /**
+     * 상태 초기화
+     */
+    reset(): void;
+    /**
+     * 메트릭 조회
+     */
+    getMetrics(): {
+        state: ECircuitState;
+        failureCount: number;
+        successCount: number;
+        nextAttemptTime: number;
+    };
+}

package/dist/error/recovery/circuit-breaker.js

@@ -0,0 +1,9 @@
+import {
+  CircuitBreaker,
+  ECircuitState
+} from "../../chunk-7VJNLGAS.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  CircuitBreaker,
+  ECircuitState
+};

package/dist/error/recovery/degradation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Feature Degradation 패턴
+ *
+ * 선택적 기능 실패 시 우아한 저하 (graceful degradation)
+ */
+/**
+ * FeatureDegradation - 기능 저하 패턴
+ *
+ * 선택적 기능 실패 시 기본 작업은 계속 진행
+ *
+ * @example
+ * ```typescript
+ * const result = await FeatureDegradation.execute(
+ *   'analytics',
+ *   async () => {
+ *     await trackAnalytics(event);
+ *   }
+ * );
+ *
+ * if (!result.success) {
+ *   console.log('Analytics failed but app continues');
+ * }
+ * ```
+ */
+export declare class FeatureDegradation {
+    /**
+     * 기능 실행 (실패해도 앱은 계속)
+     */
+    static execute<T>(featureName: string, fn: () => Promise<T>, fallbackValue?: T): Promise<{
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    }>;
+    /**
+     * 여러 기능을 병렬로 실행 (일부 실패해도 계속)
+     */
+    static executeAll<T>(features: Array<{
+        name: string;
+        fn: () => Promise<T>;
+        fallbackValue?: T;
+    }>): Promise<Array<{
+        name: string;
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    }>>;
+    /**
+     * 타임아웃 포함 실행
+     */
+    static executeWithTimeout<T>(featureName: string, fn: () => Promise<T>, timeoutMs: number, fallbackValue?: T): Promise<{
+        success: boolean;
+        data?: T;
+        error?: unknown;
+        timedOut?: boolean;
+    }>;
+}

package/dist/error/recovery/degradation.js

@@ -0,0 +1,7 @@
+import {
+  FeatureDegradation
+} from "../../chunk-TEIYA7U4.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  FeatureDegradation
+};

package/dist/error/recovery/fallback.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Fallback 패턴
+ *
+ * 실패 시 대체 값 또는 대체 함수 사용
+ */
+/**
+ * Fallback 옵션
+ */
+export interface IFallbackOptions<T> {
+    /** 에러 발생 시 콜백 */
+    onError?: (error: unknown) => void;
+    /** 에러 로깅 여부 (기본값: true) */
+    logError?: boolean;
+}
+/**
+ * withFallback - Fallback 패턴 (값)
+ *
+ * @example
+ * ```typescript
+ * const data = await withFallback(
+ *   async () => {
+ *     const res = await fetch('/api/data');
+ *     return res.json();
+ *   },
+ *   { default: 'fallback data' }
+ * );
+ * ```
+ */
+export declare function withFallback<T>(fn: () => Promise<T>, fallbackValue: T, options?: IFallbackOptions<T>): Promise<T>;
+/**
+ * withFallbackFn - Fallback 패턴 (함수)
+ *
+ * @example
+ * ```typescript
+ * const data = await withFallbackFn(
+ *   async () => await fetchFromPrimary(),
+ *   async () => await fetchFromSecondary()
+ * );
+ * ```
+ */
+export declare function withFallbackFn<T>(primaryFn: () => Promise<T>, fallbackFn: () => Promise<T>, options?: IFallbackOptions<T>): Promise<T>;
+/**
+ * withFallbackChain - 여러 fallback을 순서대로 시도
+ *
+ * @example
+ * ```typescript
+ * const data = await withFallbackChain([
+ *   async () => await fetchFromPrimary(),
+ *   async () => await fetchFromSecondary(),
+ *   async () => await fetchFromCache(),
+ *   async () => ({ default: true })
+ * ]);
+ * ```
+ */
+export declare function withFallbackChain<T>(fns: Array<() => Promise<T>>, options?: IFallbackOptions<T>): Promise<T>;

package/dist/error/recovery/fallback.js

@@ -0,0 +1,11 @@
+import {
+  withFallback,
+  withFallbackChain,
+  withFallbackFn
+} from "../../chunk-MYLGYX4K.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  withFallback,
+  withFallbackChain,
+  withFallbackFn
+};

package/dist/error/recovery/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 에러 복구 전략
+ *
+ * 통합 에러 처리 시스템의 복구 패턴
+ */
+export { withRetry } from './retry';
+export type { IRetryOptions } from './retry';
+export { withFallback, withFallbackFn, withFallbackChain } from './fallback';
+export type { IFallbackOptions } from './fallback';
+export { CircuitBreaker, ECircuitState } from './circuit-breaker';
+export type { ICircuitBreakerOptions } from './circuit-breaker';
+export { FeatureDegradation } from './degradation';

package/dist/error/recovery/index.js

@@ -0,0 +1,26 @@
+import "../../chunk-ULF5RDDX.js";
+import {
+  withFallback,
+  withFallbackChain,
+  withFallbackFn
+} from "../../chunk-MYLGYX4K.js";
+import {
+  withRetry
+} from "../../chunk-A6EAAWMK.js";
+import {
+  CircuitBreaker,
+  ECircuitState
+} from "../../chunk-7VJNLGAS.js";
+import {
+  FeatureDegradation
+} from "../../chunk-TEIYA7U4.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  CircuitBreaker,
+  ECircuitState,
+  FeatureDegradation,
+  withFallback,
+  withFallbackChain,
+  withFallbackFn,
+  withRetry
+};

package/dist/error/recovery/retry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Retry 패턴
+ *
+ * 실패한 작업을 자동으로 재시도
+ */
+/**
+ * Retry 옵션
+ */
+export interface IRetryOptions {
+    /** 최대 재시도 횟수 (기본값: 3) */
+    maxAttempts?: number;
+    /** 재시도 간격 (밀리초, 기본값: 1000) */
+    delay?: number;
+    /** 지수 백오프 사용 여부 (기본값: true) */
+    exponentialBackoff?: boolean;
+    /** 백오프 배수 (기본값: 2) */
+    backoffMultiplier?: number;
+    /** 최대 지연 시간 (밀리초, 기본값: 30000) */
+    maxDelay?: number;
+    /** 재시도 가능 여부를 판단하는 함수 */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** 재시도 전 콜백 */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * withRetry - 재시도 패턴
+ *
+ * @example
+ * ```typescript
+ * const data = await withRetry(
+ *   async () => {
+ *     const res = await fetch('/api/data');
+ *     if (!res.ok) throw new Error('Fetch failed');
+ *     return res.json();
+ *   },
+ *   {
+ *     maxAttempts: 3,
+ *     delay: 1000,
+ *     exponentialBackoff: true,
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: IRetryOptions): Promise<T>;

package/dist/error/recovery/retry.js

@@ -0,0 +1,7 @@
+import {
+  withRetry
+} from "../../chunk-A6EAAWMK.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  withRetry
+};

package/dist/geolocation/batch-processor.d.ts

@@ -0,0 +1,33 @@
+import type { IBatchProcessorConfig, IBatchProcessResult } from '@withwiz/types/geoip';
+/**
+ * 범용 배치 처리기
+ * 다양한 배치 작업에 재사용 가능한 공통 로직
+ */
+export declare class BatchProcessor<T, R> {
+    private config;
+    constructor(config?: Partial<IBatchProcessorConfig>);
+    /**
+     * 배치 처리 실행
+     */
+    processBatch(items: T[], processor: (batch: T[]) => Promise<R[]>, onProgress?: (processed: number, total: number) => void): Promise<IBatchProcessResult>;
+    /**
+     * 재시도 로직이 포함된 배치 처리
+     */
+    processBatchWithRetry(items: T[], processor: (batch: T[]) => Promise<R[]>, onProgress?: (processed: number, total: number) => void): Promise<IBatchProcessResult>;
+    /**
+     * 동시 배치 처리 (병렬 처리)
+     */
+    processBatchConcurrent(items: T[], processor: (batch: T[]) => Promise<R[]>, onProgress?: (processed: number, total: number) => void): Promise<IBatchProcessResult>;
+    /**
+     * 설정 업데이트
+     */
+    updateConfig(newConfig: Partial<IBatchProcessorConfig>): void;
+    /**
+     * 현재 설정 조회
+     */
+    getConfig(): IBatchProcessorConfig;
+}
+/**
+ * 배치 처리기 팩토리 함수
+ */
+export declare function createBatchProcessor<T, R>(config?: Partial<IBatchProcessorConfig>): BatchProcessor<T, R>;

package/dist/geolocation/batch-processor.js

@@ -0,0 +1,10 @@
+import {
+  BatchProcessor,
+  createBatchProcessor
+} from "../chunk-TZAP5T4N.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  BatchProcessor,
+  createBatchProcessor
+};

package/dist/geolocation/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GeoIP Shared Module
+ *
+ * 프로젝트 독립적인 GeoIP 유틸리티
+ * - 순수 Provider 구현
+ * - 범용 배치 처리기
+ * - IP 유틸리티는 @withwiz/utils/ip-utils 에서 import
+ *
+ * 프로젝트 종속적인 서비스는 <your-project>/services/geoip 를 사용하세요.
+ */
+export { BaseGeoIPProvider, truncateString, IPApiProvider, IPApiCoProvider, IPGeolocationProvider, MaxMindProvider, GeoIPProviderFactory, } from './providers';
+export { BatchProcessor, createBatchProcessor } from './batch-processor';
+export type { IGeoIPConfig, IGeoIPService, IGeoIPProvider, IGeoIPApiResponse, IBatchProcessorConfig, IBatchProcessResult, IGeographyAnalytics, IGeoIPStats, IGeoIPError, IGeoIPCacheEntry, IGeoIPPreset, } from '@withwiz/types/geoip';
+export type { IGeoLocationData, IGeoIPResponse, IDatabaseService, ICacheService, } from '@withwiz/types/database';