@withwiz/toolkit 0.1.0

package/dist/types/api.d.ts

@@ -0,0 +1,80 @@
+/**
+ * API 응답 타입 정의
+ *
+ * 통합 에러 시스템에서 사용하는 API 응답 형식
+ */
+/**
+ * 표준 API 응답 인터페이스
+ *
+ * @template T - 응답 데이터 타입
+ *
+ * @example
+ * ```typescript
+ * // 성공 응답
+ * const response: IApiResponse<User> = {
+ *   success: true,
+ *   data: { id: '1', email: 'user@example.com' }
+ * };
+ *
+ * // 에러 응답
+ * const errorResponse: IApiResponse = {
+ *   success: false,
+ *   error: {
+ *     code: 40401,
+ *     message: '리소스를 찾을 수 없습니다.'
+ *   }
+ * };
+ * ```
+ */
+export interface IApiResponse<T = any> {
+    /**
+     * 요청 성공 여부
+     * - true: 성공 (data 필드 포함)
+     * - false: 실패 (error 필드 포함)
+     */
+    success: boolean;
+    /**
+     * 응답 데이터 (성공 시)
+     */
+    data?: T;
+    /**
+     * 에러 정보 (실패 시)
+     */
+    error?: {
+        /**
+         * 5자리 HTTP 확장 에러 코드
+         * - XXX: HTTP 상태 코드
+         * - YY: 세부 순번
+         */
+        code: number;
+        /**
+         * 내부 개발용 상세 메시지
+         */
+        message: string;
+        /**
+         * 사용자용 다국어 메시지 (서버에서 번역되어 전달됨)
+         */
+        userMessage?: {
+            title?: string;
+            description: string;
+            action?: string;
+        };
+        /**
+         * 요청 식별을 위한 ID
+         */
+        requestId?: string;
+        /**
+         * 상세 에러 정보 (옵셔널)
+         * - 검증 에러의 경우 issues 배열 포함
+         * - 개발 환경에서만 표시되는 추가 정보
+         */
+        details?: any;
+    };
+    /**
+     * 메타데이터 (옵셔널)
+     * - 페이지네이션 정보
+     * - 캐시 정보
+     * - 기타 메타데이터
+     */
+    meta?: any;
+}

package/dist/types/database.d.ts

@@ -0,0 +1,38 @@
+export interface IGeoLocationData {
+    ipAddress: string;
+    country?: string;
+    countryName?: string;
+    region?: string;
+    regionCode?: string;
+    city?: string;
+    latitude?: number;
+    longitude?: number;
+    timezone?: string;
+    isp?: string;
+    organization?: string;
+    asn?: string;
+    isPrivate: boolean;
+    isProxy: boolean;
+    accuracy?: number;
+    lastUpdated?: Date;
+    version?: number;
+    validFrom?: Date;
+    validTo?: Date;
+    isActive?: boolean;
+}
+export interface IGeoIPResponse {
+    success: boolean;
+    data?: IGeoLocationData;
+    error?: string;
+}
+export interface IDatabaseService {
+    findGeoLocation(ipAddress: string): Promise<IGeoLocationData | null>;
+    upsertGeoLocation(data: IGeoLocationData): Promise<IGeoLocationData>;
+    findManyGeoLocations(ipAddresses: string[]): Promise<IGeoLocationData[]>;
+}
+export interface ICacheService {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePattern(pattern: string): Promise<void>;
+}

package/dist/types/env.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared Environment Configuration Types
+ *
+ * src/shared/ 모듈에서 사용하는 환경 설정 인터페이스
+ * 외부에서 의존성 주입을 통해 제공되어야 합니다.
+ */
+/**
+ * Redis 환경 설정
+ */
+export interface IRedisEnv {
+    URL?: string;
+    TOKEN?: string;
+    IS_AVAILABLE: boolean;
+    /** Redis 캐시 사용 여부 (CACHE_REDIS_ENABLED) */
+    ENABLED: boolean;
+}
+/**
+ * 카테고리별 캐시 설정
+ */
+export interface ICacheCategoryConfig {
+    ENABLED: boolean;
+    DURATION: number;
+}
+/**
+ * 캐시 TTL 설정
+ */
+export interface ICacheTTLConfig {
+    DEFAULT: number;
+    SHORT: number;
+    LONG: number;
+    GEOIP: number;
+    SETTINGS: number;
+    ANALYTICS: number;
+    USER: number;
+    LINK: number;
+    ALIAS: number;
+    COMMUNITY: number;
+    RESERVED_WORDS: number;
+}
+/**
+ * 캐시 백엔드 타입
+ */
+export type CacheBackendType = 'redis' | 'memory' | 'hybrid';
+/**
+ * 인메모리 캐시 환경 설정
+ */
+export interface IInMemoryCacheEnv {
+    /** 인메모리 캐시 활성화 여부 */
+    ENABLED: boolean;
+    /** 최대 항목 수 */
+    MAX_SIZE: number;
+    /** 최대 메모리 (MB) */
+    MAX_MB: number;
+    /** 교체 정책: lru | fifo | ttl */
+    EVICTION: 'lru' | 'fifo' | 'ttl';
+    /** 만료 항목 정리 주기 (ms) */
+    CLEANUP_INTERVAL: number;
+}
+/**
+ * 캐시 환경 설정
+ */
+export interface ICacheEnv {
+    ENABLED: boolean;
+    /** Redis 캐시 설정 */
+    REDIS: {
+        /** Redis 캐시 사용 여부 (CACHE_REDIS_ENABLED) */
+        ENABLED: boolean;
+    };
+    /** 인메모리 캐시 설정 */
+    INMEMORY: IInMemoryCacheEnv;
+    TTL: ICacheTTLConfig;
+    ANALYTICS: ICacheCategoryConfig;
+    USER: ICacheCategoryConfig;
+    GEOIP: ICacheCategoryConfig;
+    SETTINGS: ICacheCategoryConfig;
+    RESERVED_WORDS: ICacheCategoryConfig;
+    ALIAS: ICacheCategoryConfig;
+    COMMUNITY: ICacheCategoryConfig;
+    LINK: ICacheCategoryConfig;
+    RATE_LIMIT: ICacheCategoryConfig;
+    URL_TOKEN: ICacheCategoryConfig;
+    API_KEY: ICacheCategoryConfig;
+    API_CONFIG: ICacheCategoryConfig;
+}
+/**
+ * Raw 환경 변수 인터페이스 (직접 접근용)
+ */
+export interface IRawEnv {
+    NODE_ENV: 'development' | 'production' | 'test';
+    UPSTASH_REDIS_REST_URL?: string;
+    UPSTASH_REDIS_REST_TOKEN?: string;
+    CACHE_ENABLED: boolean;
+}
+/**
+ * Shared 모듈용 환경 설정 인터페이스
+ */
+export interface ISharedEnvConfig {
+    env: IRawEnv;
+    ENV: {
+        REDIS: IRedisEnv;
+        CACHE: ICacheEnv;
+    };
+    isCacheEnabled: () => boolean;
+    isRedisAvailable: () => boolean;
+}

package/dist/types/geoip.d.ts

@@ -0,0 +1,152 @@
+import type { IGeoLocationData, IDatabaseService, ICacheService } from './database';
+export interface IGeoIPConfig {
+    cacheEnabled: boolean;
+    cacheTTL: number;
+    batchSize: number;
+    rateLimitDelay: number;
+    maxRetries: number;
+    timeout: number;
+    enablePrivateIPDetection: boolean;
+    enableProxyDetection: boolean;
+    fallbackProviders: string[];
+}
+export interface IGeoIPService {
+    getGeoLocation(ip: string): Promise<IGeoLocationData | null>;
+    getGeoLocationBatch(ips: string[]): Promise<Map<string, IGeoLocationData>>;
+    updateClickHistoryGeoLocation(linkId: string, ip: string): Promise<void>;
+    getGeographyAnalytics(linkId: string, days?: number): Promise<IGeographyAnalytics>;
+    getUserGeographyAnalytics(userId: string, days?: number): Promise<IGeographyAnalytics>;
+    findOrCreateGeoLocation(ip: string): Promise<string | null>;
+    isGeoLocationOutdated(validFrom: Date): boolean;
+}
+export interface IBatchProcessorConfig {
+    batchSize: number;
+    delayBetweenBatches: number;
+    maxConcurrentBatches: number;
+    retryAttempts: number;
+    timeout: number;
+}
+export interface IBatchProcessResult {
+    totalProcessed: number;
+    successful: number;
+    failed: number;
+    skipped: number;
+    errors: string[];
+    processingTime: number;
+    averageTimePerItem: number;
+}
+export interface IGeoIPServiceFactory {
+    getInstance(databaseService?: IDatabaseService, cacheService?: ICacheService, config?: Partial<IGeoIPConfig>): IGeoIPService;
+}
+export interface IGeoIPBatchProcessor {
+    processMissingGeoIPData(): Promise<IBatchProcessResult>;
+    processLinkGeoIPData(linkId: string): Promise<IBatchProcessResult>;
+    cleanupOldGeoIPData(daysOld?: number): Promise<number>;
+    getGeoIPStats(): Promise<IGeoIPStats>;
+    processUserGeoIPData(userId: string): Promise<IBatchProcessResult>;
+}
+export interface IGeoIPApiResponse {
+    status?: string;
+    message?: string;
+    country?: string;
+    countryCode?: string;
+    region?: string;
+    regionName?: string;
+    city?: string;
+    lat?: number;
+    lon?: number;
+    timezone?: string;
+    isp?: string;
+    org?: string;
+    as?: string;
+    proxy?: boolean;
+    hosting?: boolean;
+    country_code?: string;
+    country_name?: string;
+    region_code?: string;
+    latitude?: number;
+    longitude?: number;
+    organization?: string;
+    asn?: string;
+}
+export interface IGeoIPProvider {
+    name: string;
+    url(ip: string): string;
+    parseResponse(data: IGeoIPApiResponse): IGeoLocationData | null;
+    isAvailable(): boolean;
+    getRateLimit(): number;
+    getTimeout(): number;
+}
+export interface IGeographyAnalytics {
+    totalClicks: number;
+    countries: Array<{
+        country: string;
+        countryName: string;
+        count: number;
+        percentage: number;
+    }>;
+    cities: Array<{
+        country: string | null;
+        city: string;
+        count: number;
+        percentage: number;
+    }>;
+    regions: Array<{
+        country: string | null;
+        region: string;
+        count: number;
+        percentage: number;
+    }>;
+    timezones: Array<{
+        timezone: string;
+        count: number;
+        percentage: number;
+    }>;
+    isps: Array<{
+        isp: string;
+        count: number;
+        percentage: number;
+    }>;
+    privateIPs: number;
+    proxyConnections: number;
+    lastUpdated: Date;
+}
+export interface IGeoIPStats {
+    totalRecords: number;
+    privateIPs: number;
+    publicIPs: number;
+    recentUpdates: number;
+    oldestRecord?: Date;
+    newestRecord?: Date;
+    providerStats: Array<{
+        provider: string;
+        requests: number;
+        successRate: number;
+        averageResponseTime: number;
+    }>;
+    cacheStats: {
+        hitRate: number;
+        missRate: number;
+        totalRequests: number;
+    };
+}
+export interface IGeoIPError {
+    code: 'PROVIDER_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'INVALID_IP' | 'NETWORK_ERROR' | 'PARSING_ERROR' | 'DATABASE_ERROR';
+    message: string;
+    provider?: string;
+    ip?: string;
+    timestamp: Date;
+    retryable: boolean;
+}
+export interface IGeoIPCacheEntry {
+    data: IGeoLocationData;
+    timestamp: Date;
+    ttl: number;
+    hits: number;
+}
+export interface IGeoIPPreset {
+    name: string;
+    description: string;
+    config: IGeoIPConfig;
+    useCase: 'development' | 'production' | 'testing' | 'high-volume' | 'low-latency';
+}

package/dist/types/i18n.d.ts

@@ -0,0 +1,11 @@
+export type Locale = 'en' | 'ko' | 'ja';
+export interface II18nConfig {
+    defaultLocale: Locale;
+    locales: Locale[];
+    localeNames: Record<Locale, string>;
+}
+declare global {
+    interface Window {
+        __NEXT_LOCALE__: Locale;
+    }
+}

package/dist/types/qr-code.d.ts

@@ -0,0 +1,139 @@
+export interface IQRCodeSettings {
+    size: number;
+    color: string;
+    bgColor: string;
+    errorCorrectionLevel: 'L' | 'M' | 'Q' | 'H';
+    includeMargin: boolean;
+    marginSize: number;
+    logoUrl?: string;
+    brandColor?: string;
+}
+export interface IQRCodeConfig {
+    id: string;
+    linkId: string;
+    settings: IQRCodeSettings;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface IQRTemplate {
+    id: string;
+    userId: string;
+    name: string;
+    description?: string;
+    settings: IQRCodeSettings;
+    isDefault: boolean;
+    isPublic: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface IQRCodeStats {
+    totalClicks: number;
+    qrClicks: number;
+    normalClicks: number;
+    aliasClicks: number;
+    apiClicks: number;
+    qrUsageRate: number;
+}
+export interface IQRCodeAnalytics {
+    dailyStats: Array<{
+        date: string;
+        totalClicks: number;
+        qrClicks: number;
+        qrUsageRate: number;
+    }>;
+    deviceStats: Array<{
+        deviceType: string;
+        totalClicks: number;
+        qrClicks: number;
+        qrUsageRate: number;
+    }>;
+    browserStats: Array<{
+        browser: string;
+        totalClicks: number;
+        qrClicks: number;
+        qrUsageRate: number;
+    }>;
+}
+export interface IQRCodeDownloadOptions {
+    format: 'png' | 'svg';
+    filename: string;
+    quality?: number;
+}
+export declare const DEFAULT_QR_SETTINGS: IQRCodeSettings;
+export declare const QR_CODE_TEMPLATES: readonly [{
+    readonly id: "default";
+    readonly name: "기본";
+    readonly description: "표준 QR 코드 스타일";
+    readonly settings: IQRCodeSettings;
+}, {
+    readonly id: "minimal";
+    readonly name: "미니멀";
+    readonly description: "깔끔한 미니멀 스타일";
+    readonly settings: {
+        readonly color: "#333333";
+        readonly bgColor: "#FFFFFF";
+        readonly marginSize: 2;
+        readonly size: number;
+        readonly errorCorrectionLevel: "L" | "M" | "Q" | "H";
+        readonly includeMargin: boolean;
+        readonly logoUrl?: string;
+        readonly brandColor?: string;
+    };
+}, {
+    readonly id: "branded";
+    readonly name: "브랜드";
+    readonly description: "브랜드 컬러 적용";
+    readonly settings: {
+        readonly color: "#3B82F6";
+        readonly bgColor: "#F8FAFC";
+        readonly errorCorrectionLevel: "H";
+        readonly size: number;
+        readonly includeMargin: boolean;
+        readonly marginSize: number;
+        readonly logoUrl?: string;
+        readonly brandColor?: string;
+    };
+}, {
+    readonly id: "dark";
+    readonly name: "다크";
+    readonly description: "다크 테마 스타일";
+    readonly settings: {
+        readonly color: "#FFFFFF";
+        readonly bgColor: "#1F2937";
+        readonly errorCorrectionLevel: "Q";
+        readonly size: number;
+        readonly includeMargin: boolean;
+        readonly marginSize: number;
+        readonly logoUrl?: string;
+        readonly brandColor?: string;
+    };
+}, {
+    readonly id: "colorful";
+    readonly name: "컬러풀";
+    readonly description: "화려한 컬러 스타일";
+    readonly settings: {
+        readonly color: "#EF4444";
+        readonly bgColor: "#FEF3C7";
+        readonly errorCorrectionLevel: "H";
+        readonly size: number;
+        readonly includeMargin: boolean;
+        readonly marginSize: number;
+        readonly logoUrl?: string;
+        readonly brandColor?: string;
+    };
+}, {
+    readonly id: "large";
+    readonly name: "라지";
+    readonly description: "큰 크기 QR 코드";
+    readonly settings: {
+        readonly size: 500;
+        readonly errorCorrectionLevel: "H";
+        readonly color: string;
+        readonly bgColor: string;
+        readonly includeMargin: boolean;
+        readonly marginSize: number;
+        readonly logoUrl?: string;
+        readonly brandColor?: string;
+    };
+}];

package/dist/types/qr-code.js

@@ -0,0 +1,75 @@
+import {
+  __spreadProps,
+  __spreadValues
+} from "../chunk-ORMEWXMH.js";
+
+// src/types/qr-code.ts
+var DEFAULT_QR_SETTINGS = {
+  size: 300,
+  color: "#000000",
+  bgColor: "#FFFFFF",
+  errorCorrectionLevel: "M",
+  includeMargin: true,
+  marginSize: 4
+};
+var QR_CODE_TEMPLATES = [
+  {
+    id: "default",
+    name: "\uAE30\uBCF8",
+    description: "\uD45C\uC900 QR \uCF54\uB4DC \uC2A4\uD0C0\uC77C",
+    settings: DEFAULT_QR_SETTINGS
+  },
+  {
+    id: "minimal",
+    name: "\uBBF8\uB2C8\uBA40",
+    description: "\uAE54\uB054\uD55C \uBBF8\uB2C8\uBA40 \uC2A4\uD0C0\uC77C",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#333333",
+      bgColor: "#FFFFFF",
+      marginSize: 2
+    })
+  },
+  {
+    id: "branded",
+    name: "\uBE0C\uB79C\uB4DC",
+    description: "\uBE0C\uB79C\uB4DC \uCEEC\uB7EC \uC801\uC6A9",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#3B82F6",
+      bgColor: "#F8FAFC",
+      errorCorrectionLevel: "H"
+    })
+  },
+  {
+    id: "dark",
+    name: "\uB2E4\uD06C",
+    description: "\uB2E4\uD06C \uD14C\uB9C8 \uC2A4\uD0C0\uC77C",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#FFFFFF",
+      bgColor: "#1F2937",
+      errorCorrectionLevel: "Q"
+    })
+  },
+  {
+    id: "colorful",
+    name: "\uCEEC\uB7EC\uD480",
+    description: "\uD654\uB824\uD55C \uCEEC\uB7EC \uC2A4\uD0C0\uC77C",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#EF4444",
+      bgColor: "#FEF3C7",
+      errorCorrectionLevel: "H"
+    })
+  },
+  {
+    id: "large",
+    name: "\uB77C\uC9C0",
+    description: "\uD070 \uD06C\uAE30 QR \uCF54\uB4DC",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      size: 500,
+      errorCorrectionLevel: "H"
+    })
+  }
+];
+export {
+  DEFAULT_QR_SETTINGS,
+  QR_CODE_TEMPLATES
+};

package/dist/types/user.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 범용 사용자 인터페이스
+ * 프로젝트별 특화 필드는 상속받아 확장
+ */
+export interface IUser {
+    id: string;
+    email: string;
+    name?: string | null;
+    createdAt: string;
+    updatedAt?: string;
+    isActive?: boolean;
+    emailVerified?: Date | null;
+    lastLoginAt?: string | null;
+}
+/**
+ * 범용 사용자 생성 데이터
+ */
+export interface IUserCreateData {
+    email: string;
+    name?: string;
+    password?: string;
+}
+/**
+ * 범용 사용자 업데이트 데이터
+ */
+export interface IUserUpdateData {
+    name?: string;
+    email?: string;
+    isActive?: boolean;
+}
+/**
+ * 범용 사용자 필터
+ */
+export interface IUserFilters {
+    search?: string;
+    isActive?: string;
+}
+/**
+ * 범용 사용자 정렬 옵션
+ */
+export interface IUserSortOptions {
+    sort: string;
+    order: 'asc' | 'desc';
+}
+/**
+ * 범용 사용자 목록 결과
+ */
+export interface IUserListResult<T = IUser> {
+    users: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}