@withwiz/toolkit 0.1.0

package/dist/constants/security.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 보안 관련 상수
+ * 프레임워크 독립적인 보안 설정
+ */
+export declare const JWT_DEFAULTS: {
+    /** 알고리즘 */
+    readonly ALGORITHM: "HS256";
+    /** 기본 액세스 토큰 만료 기간 */
+    readonly DEFAULT_ACCESS_TOKEN_EXPIRES: "7d";
+    /** 기본 리프레시 토큰 만료 기간 */
+    readonly DEFAULT_REFRESH_TOKEN_EXPIRES: "30d";
+    /** 토큰 타입 */
+    readonly TOKEN_TYPE: "Bearer";
+};
+export declare const EMAIL_VERIFICATION: {
+    /** 토큰 만료 시간 (시간 단위) */
+    readonly TOKEN_EXPIRES_HOURS: 24;
+    /** 토큰 길이 (바이트) */
+    readonly TOKEN_LENGTH: 32;
+};
+export declare const PASSWORD_RESET: {
+    /** 토큰 만료 시간 (시간 단위) */
+    readonly TOKEN_EXPIRES_HOURS: 1;
+    /** 토큰 길이 (바이트) */
+    readonly TOKEN_LENGTH: 32;
+};
+export declare const MAGIC_LINK: {
+    /** 토큰 만료 시간 (분 단위) */
+    readonly TOKEN_EXPIRES_MINUTES: 15;
+    /** 토큰 길이 (바이트) */
+    readonly TOKEN_LENGTH: 32;
+};
+export declare const API_KEY: {
+    /** 키 길이 (문자) */
+    readonly LENGTH: 32;
+    /** 키 접두사 */
+    readonly PREFIX: "tlog_";
+};
+export declare const SESSION: {
+    /** 세션 쿠키 이름 */
+    readonly COOKIE_NAME: "session";
+    /** 세션 만료 시간 (일 단위) */
+    readonly EXPIRES_DAYS: 30;
+};
+export declare const OAUTH: {
+    /** 상태 토큰 길이 */
+    readonly STATE_LENGTH: 32;
+    /** 상태 토큰 만료 시간 (분) */
+    readonly STATE_EXPIRES_MINUTES: 10;
+};
+export declare const CSRF: {
+    /** 토큰 길이 */
+    readonly TOKEN_LENGTH: 32;
+    /** 헤더 이름 */
+    readonly HEADER_NAME: "X-CSRF-Token";
+};
+export declare const SECURITY_HEADERS: {
+    /** Content Security Policy */
+    readonly CSP: "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';";
+    /** X-Frame-Options */
+    readonly X_FRAME_OPTIONS: "DENY";
+    /** X-Content-Type-Options */
+    readonly X_CONTENT_TYPE_OPTIONS: "nosniff";
+    /** Referrer-Policy */
+    readonly REFERRER_POLICY: "strict-origin-when-cross-origin";
+};

package/dist/constants/security.js

@@ -0,0 +1,23 @@
+import {
+  API_KEY,
+  CSRF,
+  EMAIL_VERIFICATION,
+  JWT_DEFAULTS,
+  MAGIC_LINK,
+  OAUTH,
+  PASSWORD_RESET,
+  SECURITY_HEADERS,
+  SESSION
+} from "../chunk-JLLMTTQ4.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  API_KEY,
+  CSRF,
+  EMAIL_VERIFICATION,
+  JWT_DEFAULTS,
+  MAGIC_LINK,
+  OAUTH,
+  PASSWORD_RESET,
+  SECURITY_HEADERS,
+  SESSION
+};

package/dist/constants/validation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 데이터 검증 관련 상수 (범용 유틸리티)
+ *
+ * 이 파일은 프로젝트 독립적인 범용 검증 상수들만 포함합니다.
+ * URL shortener 비즈니스 로직 관련 상수는 <your-project>/constants/ 에 위치합니다.
+ *
+ * @see <your-project>/constants/alias.ts - Alias, Link, ShortCode 관련 상수
+ */
+export declare const PASSWORD: {
+    /** 최소 길이 */
+    readonly MIN_LENGTH: 8;
+    /** 최대 길이 */
+    readonly MAX_LENGTH: 128;
+};
+export declare const USER_INPUT: {
+    /** 이메일 최대 길이 */
+    readonly EMAIL_MAX_LENGTH: 255;
+    /** 이름 최대 길이 */
+    readonly NAME_MAX_LENGTH: 100;
+    /** 사용자명 최대 길이 */
+    readonly USERNAME_MAX_LENGTH: 30;
+    /** 검색어 최대 길이 */
+    readonly SEARCH_MAX_LENGTH: 100;
+};
+export declare const URL: {
+    /** URL 최대 길이 */
+    readonly MAX_LENGTH: 2048;
+    /** URL 최소 길이 */
+    readonly MIN_LENGTH: 3;
+};
+export declare const TEXT: {
+    /** 제목 최대 길이 */
+    readonly TITLE_MAX_LENGTH: 200;
+    /** 설명 최대 길이 */
+    readonly DESCRIPTION_MAX_LENGTH: 1000;
+    /** 메모 최대 길이 */
+    readonly NOTE_MAX_LENGTH: 500;
+};
+export declare const NUMERIC: {
+    /** 양수만 허용 (최소값) */
+    readonly POSITIVE_MIN: 1;
+    /** 백분율 최대값 */
+    readonly PERCENTAGE_MAX: 100;
+    /** 정수 최대값 */
+    readonly MAX_INT: 2147483647;
+};
+export declare const DATE: {
+    /** 최대 미래 날짜 (년 단위) */
+    readonly MAX_FUTURE_YEARS: 10;
+    /** 최대 과거 날짜 (년 단위) */
+    readonly MAX_PAST_YEARS: 100;
+};
+export declare const FILE_UPLOAD: {
+    /** 최대 파일 크기 (바이트) - 5MB */
+    readonly MAX_SIZE: number;
+    /** 허용되는 이미지 확장자 */
+    readonly ALLOWED_IMAGE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp"];
+    /** 허용되는 문서 확장자 */
+    readonly ALLOWED_DOC_EXTENSIONS: readonly ["pdf", "doc", "docx", "txt"];
+};

package/dist/constants/validation.js

@@ -0,0 +1,19 @@
+import {
+  DATE,
+  FILE_UPLOAD,
+  NUMERIC,
+  PASSWORD,
+  TEXT,
+  URL,
+  USER_INPUT
+} from "../chunk-LNV2E4I6.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  DATE,
+  FILE_UPLOAD,
+  NUMERIC,
+  PASSWORD,
+  TEXT,
+  URL,
+  USER_INPUT
+};

package/dist/error/ErrorBoundary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 통합 에러 바운더리 컴포넌트
+ * React 에러 바운더리로 전역 에러를 캐치하고 친화적 UI 표시
+ */
+import React, { Component, type ReactNode } from 'react';
+interface IProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    showDetails?: boolean;
+    locale?: 'ko' | 'en';
+}
+interface IState {
+    hasError: boolean;
+    error: Error | null;
+    errorCode: number;
+}
+/**
+ * 전역 에러 바운더리
+ */
+export declare class ErrorBoundary extends Component<IProps, IState> {
+    constructor(props: IProps);
+    static getDerivedStateFromError(error: Error): IState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    handleReset: () => void;
+    handleRefresh: () => void;
+    render(): ReactNode;
+}
+/**
+ * 에러 카드 컴포넌트 (개별 섹션용)
+ */
+export declare function ErrorCard({ code, message, locale, onRetry, className, }: {
+    code?: number;
+    message?: string;
+    locale?: 'ko' | 'en';
+    onRetry?: () => void;
+    className?: string;
+}): React.ReactElement;
+/**
+ * 인라인 에러 메시지 컴포넌트 (폼 필드용)
+ */
+export declare function InlineError({ code, message, locale, }: {
+    code?: number;
+    message?: string;
+    locale?: 'ko' | 'en';
+}): React.ReactElement | null;
+export default ErrorBoundary;

package/dist/error/app-error.d.ts

@@ -0,0 +1,144 @@
+/**
+ * AppError - 애플리케이션 통합 에러 클래스
+ *
+ * HTTP 상태 코드를 확장한 5자리 에러 코드 체계 (XXXYY)
+ * - XXX: HTTP 상태 코드
+ * - YY: 세부 순번
+ *
+ * 사용자 친화적 메시지 제공 (에러 코드는 별도 필드로 제공)
+ */
+import { getErrorCategory } from "@withwiz/constants/error-codes";
+import type { ErrorCodeKey, IErrorCodeInfo } from "@withwiz/constants/error-codes";
+/**
+ * 에러 상세 정보 인터페이스
+ */
+export interface IErrorDetails {
+    field?: string;
+    value?: unknown;
+    constraint?: string;
+    [key: string]: unknown;
+}
+/**
+ * 직렬화된 에러 형식
+ */
+export interface ISerializedError {
+    code: number;
+    message: string;
+    status: number;
+    key: string;
+    category: ReturnType<typeof getErrorCategory>;
+    details?: IErrorDetails;
+    timestamp: string;
+    requestId?: string;
+}
+/**
+ * AppError - 통합 애플리케이션 에러
+ *
+ * @example
+ * // 에러 코드 키로 생성
+ * throw AppError.fromKey('NOT_FOUND', '링크를 찾을 수 없습니다');
+ *
+ * // 직접 생성
+ * throw new AppError(40403, '링크를 찾을 수 없습니다');
+ *
+ * // 팩토리 메서드 사용
+ * throw AppError.notFound('링크를 찾을 수 없습니다');
+ */
+export declare class AppError extends Error {
+    readonly code: number;
+    readonly status: number;
+    readonly key: string;
+    readonly category: ReturnType<typeof getErrorCategory>;
+    readonly details?: IErrorDetails;
+    readonly timestamp: Date;
+    requestId?: string;
+    constructor(code: number, message?: string, details?: IErrorDetails, requestId?: string);
+    /**
+     * 에러 코드로 에러 키 찾기
+     */
+    private findErrorKey;
+    /**
+     * JSON 직렬화
+     */
+    toJSON(): ISerializedError;
+    /**
+     * 사용자 친화적 메시지 반환
+     */
+    toFriendlyMessage(): string;
+    /**
+     * 에러가 특정 카테고리인지 확인
+     */
+    isCategory(category: ReturnType<typeof getErrorCategory>): boolean;
+    /**
+     * 로깅용 문자열 반환
+     */
+    toLogString(): string;
+    /**
+     * 에러 코드 키로 에러 생성
+     */
+    static fromKey(key: ErrorCodeKey, customMessage?: string, details?: IErrorDetails): AppError;
+    /**
+     * 에러 정보로 에러 생성
+     */
+    static fromErrorInfo(errorInfo: IErrorCodeInfo, customMessage?: string, details?: IErrorDetails): AppError;
+    /**
+     * 알 수 없는 에러를 AppError로 변환
+     */
+    static from(error: unknown, fallbackMessage?: string): AppError;
+    static validation(message?: string, details?: IErrorDetails): AppError;
+    static badRequest(message?: string, details?: IErrorDetails): AppError;
+    static invalidInput(message?: string, details?: IErrorDetails): AppError;
+    static missingField(fieldName: string): AppError;
+    static invalidUrl(url?: string): AppError;
+    static invalidEmail(email?: string): AppError;
+    static weakPassword(): AppError;
+    static invalidAlias(alias?: string): AppError;
+    static unauthorized(message?: string): AppError;
+    static invalidToken(): AppError;
+    static tokenExpired(): AppError;
+    static invalidCredentials(): AppError;
+    static sessionExpired(): AppError;
+    static forbidden(message?: string): AppError;
+    static emailNotVerified(): AppError;
+    static accountDisabled(): AppError;
+    static accountLocked(): AppError;
+    static notFound(message?: string): AppError;
+    static userNotFound(): AppError;
+    static linkNotFound(): AppError;
+    static tagNotFound(): AppError;
+    static favoriteNotFound(): AppError;
+    static groupNotFound(): AppError;
+    static conflict(message?: string): AppError;
+    static duplicate(resourceName?: string): AppError;
+    static emailExists(email?: string): AppError;
+    static aliasExists(alias?: string): AppError;
+    static businessRule(message?: string, details?: IErrorDetails): AppError;
+    static invalidOperation(message?: string): AppError;
+    static quotaExceeded(quotaType?: string): AppError;
+    static linkExpired(): AppError;
+    static linkInactive(): AppError;
+    static linkPasswordRequired(): AppError;
+    static linkPasswordIncorrect(): AppError;
+    static reservedWord(word?: string): AppError;
+    static alreadyFavorited(): AppError;
+    static cannotDeleteOwnAccount(): AppError;
+    static fileTooLarge(maxSize?: string): AppError;
+    static unsupportedFileType(fileType?: string): AppError;
+    static rateLimit(retryAfter?: number): AppError;
+    static dailyLimit(): AppError;
+    static apiQuotaExceeded(): AppError;
+    static serverError(message?: string): AppError;
+    static internalError(message?: string): AppError;
+    static databaseError(message?: string): AppError;
+    static emailSendFailed(): AppError;
+    static cacheError(): AppError;
+    static fileUploadFailed(): AppError;
+    static externalServiceError(serviceName?: string): AppError;
+    static serviceUnavailable(message?: string): AppError;
+    static accessBlocked(reason?: string): AppError;
+    static securityValidationFailed(): AppError;
+    static blockedUrl(url?: string): AppError;
+    static suspiciousActivity(): AppError;
+    static ipBlocked(ip?: string): AppError;
+}
+export default AppError;

package/dist/error/app-error.js

@@ -0,0 +1,10 @@
+import {
+  AppError,
+  app_error_default
+} from "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  AppError,
+  app_error_default as default
+};

package/dist/error/components/EmptyState.d.ts

@@ -0,0 +1,50 @@
+/**
+ * EmptyState 컴포넌트
+ *
+ * 데이터가 없는 상태 표시
+ */
+import React from 'react';
+import type { TLocale } from '@withwiz/error/messages';
+export interface IEmptyStateProps {
+    /** 제목 */
+    title?: string;
+    /** 설명 */
+    description?: string;
+    /** 로케일 (기본값: 'ko') */
+    locale?: TLocale;
+    /** 아이콘 (이모지 또는 SVG) */
+    icon?: string | React.ReactNode;
+    /** 액션 버튼 텍스트 */
+    actionText?: string;
+    /** 액션 핸들러 */
+    onAction?: () => void;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * EmptyState 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * // 기본 빈 상태
+ * <EmptyState
+ *   title="데이터가 없습니다"
+ *   description="아직 등록된 항목이 없습니다."
+ * />
+ *
+ * // 액션 버튼 포함
+ * <EmptyState
+ *   title="링크가 없습니다"
+ *   description="첫 번째 링크를 생성해보세요."
+ *   actionText="링크 생성"
+ *   onAction={() => router.push('/create')}
+ * />
+ *
+ * // 커스텀 아이콘
+ * <EmptyState
+ *   icon="📭"
+ *   title="받은 메일함이 비어있습니다"
+ * />
+ * ```
+ */
+export declare function EmptyState({ title, description, locale, icon, actionText, onAction, size, }: IEmptyStateProps): import("react/jsx-runtime").JSX.Element;

package/dist/error/components/ErrorAlert.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ErrorAlert 컴포넌트
+ *
+ * 배너형 에러 알림 (섹션별 에러 표시)
+ */
+import type { TLocale } from '@withwiz/error/messages';
+export interface IErrorAlertProps {
+    /** 에러 코드 (예: 40907, 50001) */
+    code: number;
+    /** 로케일 (기본값: 'ko') */
+    locale?: TLocale;
+    /** 닫기 버튼 표시 여부 */
+    dismissible?: boolean;
+    /** 닫기 핸들러 */
+    onDismiss?: () => void;
+    /** 액션 버튼 텍스트 */
+    actionText?: string;
+    /** 액션 핸들러 */
+    onAction?: () => void;
+    /** 추가 메시지 */
+    additionalMessage?: string;
+    /** 커스텀 아이콘 */
+    icon?: string;
+    /** 스타일 변형 */
+    variant?: 'filled' | 'outlined';
+}
+/**
+ * ErrorAlert 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * // 기본 사용
+ * <ErrorAlert code={40907} />
+ *
+ * // 닫기 가능
+ * <ErrorAlert
+ *   code={50001}
+ *   dismissible
+ *   onDismiss={() => console.log('dismissed')}
+ * />
+ *
+ * // 액션 버튼 포함
+ * <ErrorAlert
+ *   code={42203}
+ *   actionText="플랜 업그레이드"
+ *   onAction={() => router.push('/pricing')}
+ * />
+ * ```
+ */
+export declare function ErrorAlert({ code, locale, dismissible, onDismiss, actionText, onAction, additionalMessage, icon: customIcon, variant, }: IErrorAlertProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/error/components/ErrorPage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ErrorPage 컴포넌트
+ *
+ * 전체 페이지 에러 표시 (404, 500 등)
+ */
+import type { TLocale } from '@withwiz/error/messages';
+export interface IErrorPageProps {
+    /** 에러 코드 (예: 40401, 50001) */
+    code: number;
+    /** 로케일 (기본값: 'ko') */
+    locale?: TLocale;
+    /** 홈으로 돌아가기 버튼 표시 여부 */
+    showHomeButton?: boolean;
+    /** 홈 URL (기본값: '/') */
+    homeUrl?: string;
+    /** 재시도 버튼 표시 여부 */
+    showRetryButton?: boolean;
+    /** 재시도 핸들러 */
+    onRetry?: () => void;
+    /** 추가 메시지 */
+    additionalMessage?: string;
+}
+/**
+ * ErrorPage 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * // 404 페이지
+ * <ErrorPage code={40401} showHomeButton />
+ *
+ * // 500 페이지 (재시도 가능)
+ * <ErrorPage
+ *   code={50001}
+ *   showRetryButton
+ *   onRetry={() => window.location.reload()}
+ * />
+ * ```
+ */
+export declare function ErrorPage({ code, locale, showHomeButton, homeUrl, showRetryButton, onRetry, additionalMessage, }: IErrorPageProps): import("react/jsx-runtime").JSX.Element;

package/dist/error/components/LoadingState.d.ts

@@ -0,0 +1,37 @@
+/**
+ * LoadingState 컴포넌트
+ *
+ * 로딩 상태 표시
+ */
+import type { TLocale } from '@withwiz/error/messages';
+export interface ILoadingStateProps {
+    /** 로딩 메시지 */
+    message?: string;
+    /** 로케일 (기본값: 'ko') */
+    locale?: TLocale;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 전체 화면 로딩 여부 */
+    fullScreen?: boolean;
+    /** 스피너 타입 */
+    variant?: 'spinner' | 'dots' | 'pulse';
+}
+/**
+ * LoadingState 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * // 기본 로딩
+ * <LoadingState />
+ *
+ * // 커스텀 메시지
+ * <LoadingState message="데이터를 불러오는 중..." />
+ *
+ * // 전체 화면 로딩
+ * <LoadingState fullScreen message="처리 중..." />
+ *
+ * // Dots 애니메이션
+ * <LoadingState variant="dots" />
+ * ```
+ */
+export declare function LoadingState({ message, locale, size, fullScreen, variant, }: ILoadingStateProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,13 @@
+/**
+ * UI 컴포넌트
+ *
+ * 통합 에러 처리 시스템의 UI 컴포넌트
+ */
+export { ErrorPage } from './ErrorPage';
+export type { IErrorPageProps } from './ErrorPage';
+export { ErrorAlert } from './ErrorAlert';
+export type { IErrorAlertProps } from './ErrorAlert';
+export { LoadingState } from './LoadingState';
+export type { ILoadingStateProps } from './LoadingState';
+export { EmptyState } from './EmptyState';
+export type { IEmptyStateProps } from './EmptyState';

package/dist/error/components/index.js

@@ -0,0 +1,18 @@
+import {
+  EmptyState,
+  ErrorAlert,
+  ErrorPage,
+  LoadingState
+} from "../../chunk-ZHVUK5OY.js";
+import "../../chunk-POKGHK3L.js";
+import "../../chunk-EEUBKZV4.js";
+import "../../chunk-N4YGR5WH.js";
+import "../../chunk-KXAWBFJN.js";
+import "../../chunk-Y3OTJH2S.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  EmptyState,
+  ErrorAlert,
+  ErrorPage,
+  LoadingState
+};

package/dist/error/core/locale-detector.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 로케일 감지 유틸리티
+ * 클라이언트와 서버에서 사용자 언어를 감지
+ */
+import { NextRequest } from 'next/server';
+import type { TLocale } from '@withwiz/error/messages/types';
+/**
+ * 로케일 감지기
+ */
+export declare class LocaleDetector {
+    /**
+     * 클라이언트 측 로케일 감지
+     * 우선순위: localStorage > cookie > navigator.language > 기본값
+     *
+     * @returns 감지된 로케일
+     */
+    static detectClient(): TLocale;
+    /**
+     * 서버 측 로케일 감지
+     * 우선순위: Cookie > Accept-Language 헤더 > 기본값
+     *
+     * @param request - NextRequest 객체
+     * @returns 감지된 로케일
+     */
+    static detectServer(request: NextRequest): TLocale;
+    /**
+     * 유효한 로케일인지 확인
+     *
+     * @param locale - 확인할 로케일
+     * @returns 유효 여부
+     */
+    private static isValidLocale;
+    /**
+     * 클라이언트에서 로케일 설정 (localStorage + cookie)
+     *
+     * @param locale - 설정할 로케일
+     */
+    static setClientLocale(locale: TLocale): void;
+    /**
+     * 클라이언트에서 로케일 제거
+     */
+    static clearClientLocale(): void;
+}
+export default LocaleDetector;

package/dist/error/core/locale-detector.js

@@ -0,0 +1,9 @@
+import {
+  LocaleDetector,
+  locale_detector_default
+} from "../../chunk-XHZ5L4FO.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  LocaleDetector,
+  locale_detector_default as default
+};