@withwiz/toolkit 0.1.0

package/dist/utils/api-helpers.d.ts

@@ -0,0 +1,147 @@
+/**
+ * API Helper Functions
+ *
+ * 범용 API 헬퍼 유틸리티
+ * 프로젝트 독립적인 재사용 가능한 함수들
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { ZodSchema } from 'zod';
+/**
+ * Zod 스키마로 데이터 검증
+ *
+ * @example
+ * ```typescript
+ * const validation = validateAndParse(linkSchema, await req.json());
+ * if (!validation.success) return validation.response;
+ * const { data } = validation;
+ * ```
+ */
+export declare function validateAndParse<T>(schema: ZodSchema<T>, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    response: NextResponse;
+};
+/**
+ * 페이지네이션 파라미터 파싱
+ *
+ * @example
+ * ```typescript
+ * const pagination = parsePagination(req);
+ * const { page, limit, skip } = pagination;
+ * ```
+ */
+export declare function parsePagination(req: NextRequest, defaultLimit?: number, maxLimit?: number): {
+    page: number;
+    limit: number;
+    skip: number;
+};
+/**
+ * 정렬 파라미터 파싱
+ *
+ * @example
+ * ```typescript
+ * const sort = parseSort(req, 'createdAt', 'desc');
+ * const { sortBy, sortOrder } = sort;
+ * ```
+ */
+export declare function parseSort(req: NextRequest, defaultSortBy?: string, defaultOrder?: 'asc' | 'desc'): {
+    sortBy: string;
+    sortOrder: 'asc' | 'desc';
+};
+/**
+ * 필터 파라미터 파싱
+ *
+ * @example
+ * ```typescript
+ * const filters = parseFilters(req, ['isActive', 'userId', 'search']);
+ * ```
+ */
+export declare function parseFilters(req: NextRequest, allowedKeys: string[]): Record<string, string>;
+/**
+ * 페이지네이션 응답 생성
+ *
+ * @example
+ * ```typescript
+ * return createPaginatedResponse(users, total, page, limit);
+ * ```
+ */
+export declare function createPaginatedResponse<T>(data: T[], total: number, page: number, limit: number): NextResponse;
+/**
+ * Admin 권한 확인
+ *
+ * @example
+ * ```typescript
+ * const adminCheck = requireAdmin(user.role);
+ * if (!adminCheck.isAdmin) return adminCheck.response;
+ * ```
+ */
+export declare function requireAdmin(userRole: string): {
+    isAdmin: true;
+} | {
+    isAdmin: false;
+    response: NextResponse;
+};
+/**
+ * Request body 파싱 (에러 핸들링 포함)
+ *
+ * @example
+ * ```typescript
+ * const bodyResult = await parseRequestBody(req);
+ * if (!bodyResult.success) return bodyResult.response;
+ * const body = bodyResult.data;
+ * ```
+ */
+export declare function parseRequestBody<T = any>(req: NextRequest): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    response: NextResponse;
+}>;
+/**
+ * User Agent 추출
+ *
+ * @example
+ * ```typescript
+ * const userAgent = getUserAgent(req);
+ * ```
+ */
+export declare function getUserAgent(req: NextRequest): string;
+/**
+ * Referer 추출
+ *
+ * @example
+ * ```typescript
+ * const referer = getReferer(req);
+ * ```
+ */
+export declare function getReferer(req: NextRequest): string | null;
+/**
+ * 검색 파라미터 가져오기 (타입 안전)
+ *
+ * @example
+ * ```typescript
+ * const userId = getSearchParam(req, 'userId');
+ * ```
+ */
+export declare function getSearchParam(req: NextRequest, key: string, defaultValue?: string): string | undefined;
+/**
+ * Boolean 검색 파라미터 파싱
+ *
+ * @example
+ * ```typescript
+ * const isActive = parseBooleanParam(req, 'isActive');
+ * ```
+ */
+export declare function parseBooleanParam(req: NextRequest, key: string, defaultValue?: boolean): boolean | undefined;
+/**
+ * Number 검색 파라미터 파싱
+ *
+ * @example
+ * ```typescript
+ * const maxCount = parseNumberParam(req, 'maxCount', 100);
+ * ```
+ */
+export declare function parseNumberParam(req: NextRequest, key: string, defaultValue?: number): number | undefined;

package/dist/utils/api-helpers.js

@@ -0,0 +1,30 @@
+import {
+  createPaginatedResponse,
+  getReferer,
+  getSearchParam,
+  getUserAgent,
+  parseBooleanParam,
+  parseFilters,
+  parseNumberParam,
+  parsePagination,
+  parseRequestBody,
+  parseSort,
+  requireAdmin,
+  validateAndParse
+} from "../chunk-2KAPUVIS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  createPaginatedResponse,
+  getReferer,
+  getSearchParam,
+  getUserAgent,
+  parseBooleanParam,
+  parseFilters,
+  parseNumberParam,
+  parsePagination,
+  parseRequestBody,
+  parseSort,
+  requireAdmin,
+  validateAndParse
+};

package/dist/utils/client/client-utils.d.ts

@@ -0,0 +1,3 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;
+export declare function copyToClipboard(text: string): Promise<boolean>;

package/dist/utils/client/client-utils.js

@@ -0,0 +1,9 @@
+import {
+  cn,
+  copyToClipboard
+} from "../../chunk-62FLBG6B.js";
+import "../../chunk-ORMEWXMH.js";
+export {
+  cn,
+  copyToClipboard
+};

package/dist/utils/client/qr-code.d.ts

@@ -0,0 +1,16 @@
+import type { IQRCodeSettings, IQRCodeDownloadOptions } from '@withwiz/types/qr-code';
+export declare const DEFAULT_QR_SETTINGS: IQRCodeSettings;
+export declare const applyUserBrandToQRSettings: (settings: IQRCodeSettings, userBrand?: {
+    brandColor?: string;
+    brandLogoUrl?: string;
+}) => IQRCodeSettings;
+export declare const QR_CODE_TEMPLATES: Array<{
+    id: string;
+    name: string;
+    settings: IQRCodeSettings;
+}>;
+export declare const downloadQRCode: (svgElement: SVGElement, options: IQRCodeDownloadOptions) => Promise<void>;
+export declare const generateQRCodeUrl: (shortCode: string, baseUrl: string) => string;
+export declare const downloadQRCodeWithLogo: (svgElement: SVGElement, logoDataUrl: string, options: IQRCodeDownloadOptions) => Promise<void>;
+export declare const loadQRSettings: () => IQRCodeSettings;
+export declare const saveQRSettings: (settings: IQRCodeSettings) => void;

package/dist/utils/client/qr-code.js

@@ -0,0 +1,215 @@
+import {
+  __spreadProps,
+  __spreadValues
+} from "../../chunk-ORMEWXMH.js";
+
+// src/utils/client/qr-code.ts
+var DEFAULT_QR_SETTINGS = {
+  size: 300,
+  // 크기 증가
+  color: "#000000",
+  bgColor: "#FFFFFF",
+  errorCorrectionLevel: "H",
+  // 높은 오류 수정 레벨 (로고 삽입 시 필요)
+  includeMargin: true,
+  marginSize: 4
+  // 여백 증가
+};
+var applyUserBrandToQRSettings = (settings, userBrand) => {
+  if (!userBrand) return settings;
+  return __spreadProps(__spreadValues({}, settings), {
+    color: userBrand.brandColor || settings.color,
+    logoUrl: userBrand.brandLogoUrl || settings.logoUrl
+  });
+};
+var QR_CODE_TEMPLATES = [
+  {
+    id: "default",
+    name: "\uAE30\uBCF8",
+    settings: DEFAULT_QR_SETTINGS
+  },
+  {
+    id: "dark",
+    name: "\uB2E4\uD06C \uD14C\uB9C8",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#FFFFFF",
+      bgColor: "#1F2937"
+    })
+  },
+  {
+    id: "blue",
+    name: "\uBE14\uB8E8 \uD14C\uB9C8",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#2563EB",
+      bgColor: "#FFFFFF"
+    })
+  },
+  {
+    id: "green",
+    name: "\uADF8\uB9B0 \uD14C\uB9C8",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      color: "#059669",
+      bgColor: "#FFFFFF"
+    })
+  },
+  {
+    id: "small",
+    name: "\uC791\uC740 \uD06C\uAE30",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      size: 200
+      // 최소 크기 증가
+    })
+  },
+  {
+    id: "large",
+    name: "\uD070 \uD06C\uAE30",
+    settings: __spreadProps(__spreadValues({}, DEFAULT_QR_SETTINGS), {
+      size: 512
+    })
+  }
+];
+var downloadQRCode = async (svgElement, options) => {
+  const { format, filename = "qrcode", quality = 1 } = options;
+  if (format === "svg") {
+    const svgData = new XMLSerializer().serializeToString(svgElement);
+    const svgBlob = new Blob([svgData], { type: "image/svg+xml;charset=utf-8" });
+    const svgUrl = URL.createObjectURL(svgBlob);
+    const link = document.createElement("a");
+    link.href = svgUrl;
+    link.download = `${filename}.svg`;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(svgUrl);
+  } else {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    const svgData = new XMLSerializer().serializeToString(svgElement);
+    const img = new Image();
+    img.onload = () => {
+      canvas.width = img.width;
+      canvas.height = img.height;
+      ctx.drawImage(img, 0, 0);
+      canvas.toBlob(
+        (blob) => {
+          if (blob) {
+            const url = URL.createObjectURL(blob);
+            const link = document.createElement("a");
+            link.href = url;
+            link.download = `${filename}.png`;
+            document.body.appendChild(link);
+            link.click();
+            document.body.removeChild(link);
+            URL.revokeObjectURL(url);
+          }
+        },
+        "image/png",
+        quality
+      );
+    };
+    img.src = "data:image/svg+xml;base64," + btoa(unescape(encodeURIComponent(svgData)));
+  }
+};
+var generateQRCodeUrl = (shortCode, baseUrl) => {
+  return `${baseUrl}/${shortCode}?src=qr`;
+};
+var downloadQRCodeWithLogo = async (svgElement, logoDataUrl, options) => {
+  const { format, filename = "qrcode", quality = 1 } = options;
+  if (format === "svg") {
+    const svgClone = svgElement.cloneNode(true);
+    const logoGroup = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    const logoImage = document.createElementNS("http://www.w3.org/2000/svg", "image");
+    logoImage.setAttributeNS("http://www.w3.org/1999/xlink", "href", logoDataUrl);
+    logoImage.setAttribute("x", "50%");
+    logoImage.setAttribute("y", "50%");
+    logoImage.setAttribute("width", "30%");
+    logoImage.setAttribute("height", "30%");
+    logoImage.setAttribute("transform", "translate(-50%, -50%)");
+    logoGroup.appendChild(logoImage);
+    svgClone.appendChild(logoGroup);
+    const svgData = new XMLSerializer().serializeToString(svgClone);
+    const svgBlob = new Blob([svgData], { type: "image/svg+xml;charset=utf-8" });
+    const svgUrl = URL.createObjectURL(svgBlob);
+    const link = document.createElement("a");
+    link.href = svgUrl;
+    link.download = `${filename}.svg`;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(svgUrl);
+  } else {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    const scale = 2;
+    const svgData = new XMLSerializer().serializeToString(svgElement);
+    const img = new Image();
+    img.onload = () => {
+      canvas.width = img.width * scale;
+      canvas.height = img.height * scale;
+      ctx.imageSmoothingEnabled = true;
+      ctx.imageSmoothingQuality = "high";
+      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+      const logoImg = new Image();
+      logoImg.onload = () => {
+        const logoSize = Math.min(canvas.width, canvas.height) * 0.3;
+        const logoX = (canvas.width - logoSize) / 2;
+        const logoY = (canvas.height - logoSize) / 2;
+        ctx.save();
+        ctx.fillStyle = "#FFFFFF";
+        ctx.beginPath();
+        ctx.arc(logoX + logoSize / 2, logoY + logoSize / 2, logoSize / 2 + 10, 0, 2 * Math.PI);
+        ctx.fill();
+        ctx.restore();
+        ctx.drawImage(logoImg, logoX, logoY, logoSize, logoSize);
+        canvas.toBlob(
+          (blob) => {
+            if (blob) {
+              const url = URL.createObjectURL(blob);
+              const link = document.createElement("a");
+              link.href = url;
+              link.download = `${filename}.png`;
+              document.body.appendChild(link);
+              link.click();
+              document.body.removeChild(link);
+              URL.revokeObjectURL(url);
+            }
+          },
+          "image/png",
+          1
+          // 최고 품질
+        );
+      };
+      logoImg.src = logoDataUrl;
+    };
+    img.src = "data:image/svg+xml;base64," + btoa(unescape(encodeURIComponent(svgData)));
+  }
+};
+var loadQRSettings = () => {
+  if (typeof window === "undefined") return DEFAULT_QR_SETTINGS;
+  try {
+    const saved = localStorage.getItem("qr-code-settings");
+    return saved ? __spreadValues(__spreadValues({}, DEFAULT_QR_SETTINGS), JSON.parse(saved)) : DEFAULT_QR_SETTINGS;
+  } catch (e) {
+    return DEFAULT_QR_SETTINGS;
+  }
+};
+var saveQRSettings = (settings) => {
+  if (typeof window === "undefined") return;
+  try {
+    localStorage.setItem("qr-code-settings", JSON.stringify(settings));
+  } catch (error) {
+    console.error("Failed to save QR code settings:", error);
+  }
+};
+export {
+  DEFAULT_QR_SETTINGS,
+  QR_CODE_TEMPLATES,
+  applyUserBrandToQRSettings,
+  downloadQRCode,
+  downloadQRCodeWithLogo,
+  generateQRCodeUrl,
+  loadQRSettings,
+  saveQRSettings
+};

package/dist/utils/cors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * cors
+ *
+ * CORS 유틸리티 함수
+ * - 멀티 도메인 지원: 환경 변수 기반 동적 CORS 설정
+ */
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * CORS 설정 옵션
+ */
+export interface CorsConfig {
+    /** 기본 URL (선택적) */
+    baseUrl?: string;
+    /** 추가 허용 Origin 목록 */
+    additionalOrigins?: string[];
+    /** 개발 모드 여부 */
+    isDevelopment?: boolean;
+}
+/**
+ * CORS 설정 초기화
+ */
+export declare function initCorsConfig(config: CorsConfig): void;
+/**
+ * 현재 CORS 설정 가져오기
+ */
+export declare function getCorsConfig(): CorsConfig;
+/**
+ * 허용된 도메인 목록 (런타임 환경 변수 기반)
+ *
+ * 우선순위:
+ * 1. ALLOWED_ORIGINS 환경 변수 (쉼표로 구분)
+ * 2. BASE_URL 또는 NEXT_PUBLIC_BASE_URL에서 자동 추출
+ * 3. 개발 환경에서는 localhost 자동 추가
+ */
+export declare function getAllowedOrigins(): string[];
+export declare function isOriginAllowed(origin: string | null | undefined): boolean;
+export declare function setCorsHeaders(response: NextResponse, request?: NextRequest): NextResponse;
+export declare function withCORS(handler: (request: NextRequest) => Promise<Response>): (request: NextRequest) => Promise<NextResponse<unknown>>;
+export declare function withRestrictedCORS(handler: (request: NextRequest) => Promise<Response>, allowedOrigins?: string[]): (request: NextRequest) => Promise<NextResponse<unknown>>;
+export declare function withPublicCORS(handler: (request: NextRequest) => Promise<Response>): (request: NextRequest) => Promise<NextResponse<any>>;

package/dist/utils/cors.js

@@ -0,0 +1,21 @@
+import {
+  getAllowedOrigins,
+  getCorsConfig,
+  initCorsConfig,
+  isOriginAllowed,
+  setCorsHeaders,
+  withCORS,
+  withPublicCORS,
+  withRestrictedCORS
+} from "../chunk-GCZOXUDV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  getAllowedOrigins,
+  getCorsConfig,
+  initCorsConfig,
+  isOriginAllowed,
+  setCorsHeaders,
+  withCORS,
+  withPublicCORS,
+  withRestrictedCORS
+};

package/dist/utils/csv-export.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CSV Export Utilities
+ *
+ * CSV 내보내기 공통 유틸리티
+ * - 스트리밍 CSV 생성
+ * - 배치 처리
+ * - 타입 안전한 데이터 변환
+ *
+ * @created 2025-11-27
+ */
+import { NextResponse } from 'next/server';
+/**
+ * CSV 컬럼 정의
+ */
+export interface CsvColumn<T> {
+    header: string;
+    accessor: keyof T | ((row: T) => string | number | boolean | null | undefined);
+}
+/**
+ * CSV Export 옵션
+ */
+export interface CsvExportOptions<T> {
+    /** CSV 파일명 (확장자 제외) */
+    filename: string;
+    /** 컬럼 정의 */
+    columns: CsvColumn<T>[];
+    /** BOM 추가 여부 (Excel 호환성) */
+    includeBom?: boolean;
+    /** 로깅용 컨텍스트 */
+    logContext?: Record<string, unknown>;
+}
+/**
+ * 배치 Export 옵션
+ */
+export interface BatchExportOptions<T> extends CsvExportOptions<T> {
+    /** 배치 크기 */
+    batchSize?: number;
+    /** 데이터 페처 함수 */
+    fetcher: (cursor?: string) => Promise<{
+        data: T[];
+        nextCursor?: string;
+    }>;
+}
+/**
+ * CSV 필드 이스케이프
+ * - 쌍따옴표를 이스케이프
+ * - 필드를 쌍따옴표로 감싸기
+ */
+export declare function escapeCsvField(value: unknown): string;
+/**
+ * 데이터 행을 CSV 문자열로 변환
+ */
+export declare function rowToCsv<T>(row: T, columns: CsvColumn<T>[]): string;
+/**
+ * 헤더 행 생성
+ */
+export declare function createCsvHeader<T>(columns: CsvColumn<T>[]): string;
+/**
+ * 간단한 CSV Export (메모리에 모든 데이터 로드)
+ * - 소규모 데이터에 적합
+ * - 최대 10,000 rows 권장
+ */
+export declare function createSimpleCsvResponse<T>(data: T[], options: CsvExportOptions<T>): NextResponse;
+/**
+ * 스트리밍 CSV Export (대용량 데이터)
+ * - 배치 처리로 메모리 효율적
+ * - 대규모 데이터에 적합
+ */
+export declare function createStreamingCsvResponse<T>(options: BatchExportOptions<T>): NextResponse;
+/**
+ * 날짜 포맷팅 헬퍼
+ */
+export declare const dateFormatter: {
+    /** ISO 형식 (YYYY-MM-DD) */
+    iso: (date: Date | null | undefined) => string;
+    /** 한국어 형식 */
+    korean: (date: Date | null | undefined) => string;
+    /** 영어 형식 */
+    english: (date: Date | null | undefined) => string;
+    /** 커스텀 형식 (date-fns 사용) */
+    custom: (date: Date | null | undefined, formatStr: string) => string;
+};
+/**
+ * Boolean 포맷팅 헬퍼
+ */
+export declare const boolFormatter: {
+    /** Active/Inactive */
+    activeInactive: (value: boolean) => string;
+    /** Yes/No */
+    yesNo: (value: boolean) => string;
+    /** 1/0 */
+    numeric: (value: boolean) => string;
+    /** Verified/Not Verified */
+    verified: (value: boolean) => string;
+    /** 한국어 */
+    korean: (value: boolean) => string;
+};

package/dist/utils/csv-export.js

@@ -0,0 +1,20 @@
+import {
+  boolFormatter,
+  createCsvHeader,
+  createSimpleCsvResponse,
+  createStreamingCsvResponse,
+  dateFormatter,
+  escapeCsvField,
+  rowToCsv
+} from "../chunk-BKGVSC6S.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  boolFormatter,
+  createCsvHeader,
+  createSimpleCsvResponse,
+  createStreamingCsvResponse,
+  dateFormatter,
+  escapeCsvField,
+  rowToCsv
+};

package/dist/utils/error-message-formatter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error Message Formatter
+ *
+ * 사용자 친화적인 에러 메시지로 변환하는 유틸리티
+ */
+/**
+ * Redis 에러 메시지를 사용자 친화적으로 정제
+ */
+export declare function formatRedisError(errorMessage: string): string;
+/**
+ * 데이터베이스 에러 메시지를 사용자 친화적으로 정제
+ */
+export declare function formatDatabaseError(errorMessage: string): string;
+/**
+ * 일반적인 에러 메시지를 사용자 친화적으로 정제
+ */
+export declare function formatGenericError(errorMessage: string): string;

package/dist/utils/error-message-formatter.js

@@ -0,0 +1,11 @@
+import {
+  formatDatabaseError,
+  formatGenericError,
+  formatRedisError
+} from "../chunk-OIVXOT2X.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  formatDatabaseError,
+  formatGenericError,
+  formatRedisError
+};