@withwiz/toolkit 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @withwiz/toolkit
+
+Shared utility library for [withwiz](https://github.com/greeun) projects — a collection of production-ready modules for authentication, caching, error handling, middleware, geolocation, logging, and more.
+
+## Features
+
+- **Auth** — JWT, password hashing, OAuth helpers, Prisma adapter
+- **Cache** — Redis-backed caching with factory, invalidation, and defaults
+- **Constants** — Error codes, messages, pagination, security constants
+- **Error** — Typed `AppError`, centralized error handler and display
+- **Geolocation** — GeoIP lookup, batch processing, provider factory
+- **Hooks** — `useDataTable`, `useDebounce`, `useExitIntent`, `useTimezone`
+- **Logger** — Winston-based structured logger with daily rotation
+- **Middleware** — Auth, rate-limiting, CORS, security middleware wrappers
+- **Storage** — Cloudflare R2 (AWS S3-compatible) storage
+- **System** — Health check endpoint
+- **Types** — Shared TypeScript types (API, DB, env, GeoIP, user, i18n, QR)
+- **Utils** — Sanitizer, validators, CSV export, URL normalizer, timezone, IP utils, and more
+- **Validators** — Password strength validator
+
+## Installation
+
+```bash
+npm install @withwiz/toolkit
+# or
+pnpm add @withwiz/toolkit
+# or
+yarn add @withwiz/toolkit
+```
+
+### Peer dependencies
+
+```bash
+npm install next react react-dom
+```
+
+## Quick start
+
+```ts
+// Auth — JWT
+import { signToken, verifyToken } from '@withwiz/toolkit/auth/core/jwt'
+
+const token = await signToken({ userId: 'u_123' })
+const payload = await verifyToken(token)
+```
+
+```ts
+// Cache — Redis wrapper
+import { withCache } from '@withwiz/toolkit/cache'
+
+const data = await withCache('my-key', async () => fetchData(), 3600)
+```
+
+```ts
+// Error — typed error class
+import { AppError } from '@withwiz/toolkit/error'
+
+throw new AppError('NOT_FOUND', 'Resource not found', 404)
+```
+
+```ts
+// Logger
+import { logInfo, logError } from '@withwiz/toolkit/logger/logger'
+
+logInfo('Server started', { port: 3000 })
+logError('Something went wrong', { error })
+```
+
+```ts
+// Geolocation
+import { getGeoLocation } from '@withwiz/toolkit/geolocation'
+
+const geo = await getGeoLocation('8.8.8.8')
+// { country: 'US', city: 'Mountain View', ... }
+```
+
+```tsx
+// Hooks (React)
+import { useDebounce } from '@withwiz/toolkit/hooks/useDebounce'
+
+const debouncedQuery = useDebounce(query, 300)
+```
+
+```ts
+// Utils
+import { sanitizeInput } from '@withwiz/toolkit/utils/sanitizer'
+import { formatNumber }  from '@withwiz/toolkit/utils/format-number'
+import { normalizeUrl }  from '@withwiz/toolkit/utils/url-normalizer'
+```
+
+## Module reference
+
+| Subpath | Description |
+|---|---|
+| `/auth` | Full auth module (JWT + password + OAuth + Prisma adapter) |
+| `/auth/core/jwt` | JWT sign / verify |
+| `/auth/core/password` | bcrypt helpers |
+| `/auth/core/oauth` | OAuth utilities |
+| `/auth/adapters/prisma` | Prisma-based session adapter |
+| `/cache` | Redis cache (get / set / delete / withCache) |
+| `/cache/cache-factory` | Cache factory for multiple backends |
+| `/cache/cache-invalidation` | Pattern-based cache invalidation |
+| `/constants` | All shared constants |
+| `/constants/error-codes` | Application error codes |
+| `/constants/messages` | Shared user-facing messages |
+| `/constants/pagination` | Default pagination settings |
+| `/constants/security` | Security-related constants |
+| `/error` | AppError, error handler, error display |
+| `/geolocation` | GeoIP lookup & batch processor |
+| `/hooks/useDataTable` | Table state management hook |
+| `/hooks/useDebounce` | Debounce hook |
+| `/hooks/useExitIntent` | Exit intent detection hook |
+| `/hooks/useTimezone` | Timezone detection hook |
+| `/logger/logger` | Structured Winston logger |
+| `/middleware` | Next.js middleware helpers |
+| `/middleware/auth` | Auth middleware |
+| `/middleware/rate-limit` | Rate limiting middleware |
+| `/middleware/cors` | CORS middleware |
+| `/middleware/security` | Security headers middleware |
+| `/storage` | Cloudflare R2 / S3 storage client |
+| `/system/health-check` | Health check handler |
+| `/types/api` | API response types |
+| `/types/database` | Database entity types |
+| `/types/env` | Environment variable types |
+| `/types/user` | User types |
+| `/types/geoip` | GeoIP types |
+| `/utils` | All utility functions |
+| `/utils/sanitizer` | Input sanitization |
+| `/utils/url-normalizer` | URL normalization |
+| `/utils/timezone` | Timezone formatting helpers |
+| `/utils/csv-export` | CSV export helper |
+| `/validators/password-validator` | Password strength validator |
+
+## Requirements
+
+- Node.js >= 18
+- Next.js >= 14
+- React >= 18
+- TypeScript >= 5
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## License
+
+MIT © [withwiz](https://github.com/greeun)

package/dist/auth/adapters/prisma/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @shared/auth/adapters/prisma
+ *
+ * Prisma ORM 어댑터 (데이터베이스 추상화 구현)
+ * 타 프로젝트에서 재사용 가능
+ *
+ * Prisma 7부터 Generated Client가 프로젝트별 경로에 생성되므로,
+ * 패키지 독립성을 위해 덕 타이핑(Duck Typing) 방식으로 PrismaClient를 받습니다.
+ */
+type PrismaClientLike = Record<string, any>;
+import type { UserRepository, OAuthAccountRepository, EmailTokenRepository, BaseUser, CreateUserData, UpdateUserData, OAuthAccount, CreateOAuthAccountData, UpdateOAuthAccountData, EmailToken, TokenType, OAuthProvider } from '@withwiz/auth/types';
+export declare class PrismaUserRepository implements UserRepository {
+    private prisma;
+    constructor(prisma: PrismaClientLike);
+    findById(id: string): Promise<BaseUser | null>;
+    findByEmail(email: string): Promise<BaseUser | null>;
+    create(data: CreateUserData): Promise<BaseUser>;
+    update(id: string, data: UpdateUserData): Promise<BaseUser>;
+    delete(id: string): Promise<void>;
+    updateLastLoginAt(id: string): Promise<void>;
+    verifyEmail(email: string): Promise<void>;
+    private mapToBaseUser;
+}
+export declare class PrismaOAuthAccountRepository implements OAuthAccountRepository {
+    private prisma;
+    constructor(prisma: PrismaClientLike);
+    findByProvider(provider: OAuthProvider, providerAccountId: string): Promise<OAuthAccount | null>;
+    findByUserId(userId: string): Promise<OAuthAccount[]>;
+    create(data: CreateOAuthAccountData): Promise<OAuthAccount>;
+    update(id: string, data: UpdateOAuthAccountData): Promise<OAuthAccount>;
+    delete(id: string): Promise<void>;
+    private mapToOAuthAccount;
+}
+export declare class PrismaEmailTokenRepository implements EmailTokenRepository {
+    private prisma;
+    constructor(prisma: PrismaClientLike);
+    create(email: string, token: string, type: TokenType, expiresAt: Date): Promise<EmailToken>;
+    findByEmailAndToken(email: string, token: string, type: TokenType): Promise<EmailToken | null>;
+    delete(email: string, token: string, type: TokenType): Promise<void>;
+    deleteExpired(): Promise<void>;
+    markAsUsed(id: string): Promise<void>;
+}
+export {};

package/dist/auth/adapters/prisma/index.js

@@ -0,0 +1,284 @@
+import "../../../chunk-ORMEWXMH.js";
+
+// src/auth/adapters/prisma/index.ts
+var PrismaUserRepository = class {
+  constructor(prisma) {
+    this.prisma = prisma;
+  }
+  async findById(id) {
+    const user = await this.prisma.user.findUnique({ where: { id } });
+    return user ? this.mapToBaseUser(user) : null;
+  }
+  async findByEmail(email) {
+    const user = await this.prisma.user.findUnique({ where: { email } });
+    return user ? this.mapToBaseUser(user) : null;
+  }
+  async create(data) {
+    const user = await this.prisma.user.create({
+      data: {
+        email: data.email,
+        password: data.password || null,
+        name: data.name || null,
+        role: data.role || "USER",
+        emailVerified: data.emailVerified || null,
+        image: data.image || null
+      }
+    });
+    return this.mapToBaseUser(user);
+  }
+  async update(id, data) {
+    const user = await this.prisma.user.update({
+      where: { id },
+      data: {
+        email: data.email,
+        password: data.password,
+        name: data.name,
+        role: data.role,
+        emailVerified: data.emailVerified,
+        isActive: data.isActive,
+        image: data.image
+      }
+    });
+    return this.mapToBaseUser(user);
+  }
+  async delete(id) {
+    await this.prisma.user.delete({ where: { id } });
+  }
+  async updateLastLoginAt(id) {
+    await this.prisma.user.update({
+      where: { id },
+      data: { lastLoginAt: /* @__PURE__ */ new Date() }
+    });
+  }
+  async verifyEmail(email) {
+    await this.prisma.user.update({
+      where: { email },
+      data: { emailVerified: /* @__PURE__ */ new Date() }
+    });
+  }
+  mapToBaseUser(user) {
+    return {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      role: user.role,
+      emailVerified: user.emailVerified,
+      isActive: user.isActive,
+      image: user.image,
+      createdAt: user.createdAt,
+      updatedAt: user.updatedAt
+    };
+  }
+};
+var PrismaOAuthAccountRepository = class {
+  constructor(prisma) {
+    this.prisma = prisma;
+  }
+  async findByProvider(provider, providerAccountId) {
+    const account = await this.prisma.account.findUnique({
+      where: {
+        provider_providerAccountId: {
+          provider,
+          providerAccountId
+        }
+      },
+      include: {
+        token: true
+      }
+    });
+    return account ? this.mapToOAuthAccount(account) : null;
+  }
+  async findByUserId(userId) {
+    const accounts = await this.prisma.account.findMany({
+      where: { userId },
+      include: {
+        token: true
+      }
+    });
+    return accounts.map((a) => this.mapToOAuthAccount(a));
+  }
+  async create(data) {
+    const account = await this.prisma.account.create({
+      data: {
+        userId: data.userId,
+        type: "oauth",
+        // Account 모델의 type 필드
+        provider: data.provider,
+        providerAccountId: data.providerAccountId,
+        token: data.accessToken || data.refreshToken ? {
+          create: {
+            accessToken: data.accessToken || null,
+            refreshToken: data.refreshToken || null,
+            expiresAt: data.expiresAt ? Math.floor(data.expiresAt.getTime() / 1e3) : null,
+            tokenType: data.tokenType || null,
+            scope: data.scope || null
+          }
+        } : void 0
+      },
+      include: {
+        token: true
+      }
+    });
+    return this.mapToOAuthAccount(account);
+  }
+  async update(id, data) {
+    const account = await this.prisma.account.update({
+      where: { id },
+      data: {
+        token: {
+          upsert: {
+            create: {
+              accessToken: data.accessToken || null,
+              refreshToken: data.refreshToken || null,
+              expiresAt: data.expiresAt ? Math.floor(data.expiresAt.getTime() / 1e3) : null,
+              tokenType: data.tokenType || null,
+              scope: data.scope || null
+            },
+            update: {
+              accessToken: data.accessToken || null,
+              refreshToken: data.refreshToken || null,
+              expiresAt: data.expiresAt ? Math.floor(data.expiresAt.getTime() / 1e3) : null,
+              tokenType: data.tokenType || null,
+              scope: data.scope || null
+            }
+          }
+        }
+      },
+      include: {
+        token: true
+      }
+    });
+    return this.mapToOAuthAccount(account);
+  }
+  async delete(id) {
+    await this.prisma.account.delete({ where: { id } });
+  }
+  mapToOAuthAccount(account) {
+    var _a, _b, _c, _d, _e;
+    return {
+      id: account.id,
+      userId: account.userId,
+      provider: account.provider,
+      providerAccountId: account.providerAccountId,
+      accessToken: ((_a = account.token) == null ? void 0 : _a.accessToken) || null,
+      refreshToken: ((_b = account.token) == null ? void 0 : _b.refreshToken) || null,
+      expiresAt: ((_c = account.token) == null ? void 0 : _c.expiresAt) ? new Date(account.token.expiresAt * 1e3) : null,
+      tokenType: ((_d = account.token) == null ? void 0 : _d.tokenType) || null,
+      scope: ((_e = account.token) == null ? void 0 : _e.scope) || null,
+      createdAt: account.createdAt,
+      updatedAt: account.updatedAt || account.createdAt
+    };
+  }
+};
+var PrismaEmailTokenRepository = class {
+  constructor(prisma) {
+    this.prisma = prisma;
+  }
+  async create(email, token, type, expiresAt) {
+    let result;
+    switch (type) {
+      case "EMAIL_VERIFICATION":
+        result = await this.prisma.emailVerificationToken.create({
+          data: { email, token, expires: expiresAt }
+        });
+        break;
+      case "PASSWORD_RESET":
+        result = await this.prisma.passwordResetToken.create({
+          data: { email, token, expires: expiresAt }
+        });
+        break;
+      case "MAGIC_LINK":
+        result = await this.prisma.magicLinkToken.create({
+          data: { email, token, expires: expiresAt, used: false }
+        });
+        break;
+      default:
+        throw new Error(`Unsupported token type: ${type}`);
+    }
+    return {
+      id: result.id,
+      email: result.email,
+      token: result.token,
+      type,
+      expires: result.expires,
+      used: result.used,
+      createdAt: result.createdAt
+    };
+  }
+  async findByEmailAndToken(email, token, type) {
+    let result;
+    switch (type) {
+      case "EMAIL_VERIFICATION":
+        result = await this.prisma.emailVerificationToken.findFirst({
+          where: { email, token }
+        });
+        break;
+      case "PASSWORD_RESET":
+        result = await this.prisma.passwordResetToken.findFirst({
+          where: { email, token }
+        });
+        break;
+      case "MAGIC_LINK":
+        result = await this.prisma.magicLinkToken.findFirst({
+          where: { email, token }
+        });
+        break;
+      default:
+        throw new Error(`Unsupported token type: ${type}`);
+    }
+    if (!result) return null;
+    return {
+      id: result.id,
+      email: result.email,
+      token: result.token,
+      type,
+      expires: result.expires,
+      used: result.used,
+      createdAt: result.createdAt
+    };
+  }
+  async delete(email, token, type) {
+    switch (type) {
+      case "EMAIL_VERIFICATION":
+        await this.prisma.emailVerificationToken.deleteMany({
+          where: { email, token }
+        });
+        break;
+      case "PASSWORD_RESET":
+        await this.prisma.passwordResetToken.deleteMany({
+          where: { email, token }
+        });
+        break;
+      case "MAGIC_LINK":
+        await this.prisma.magicLinkToken.deleteMany({
+          where: { email, token }
+        });
+        break;
+    }
+  }
+  async deleteExpired() {
+    const now = /* @__PURE__ */ new Date();
+    await Promise.all([
+      this.prisma.emailVerificationToken.deleteMany({
+        where: { expires: { lt: now } }
+      }),
+      this.prisma.passwordResetToken.deleteMany({
+        where: { expires: { lt: now } }
+      }),
+      this.prisma.magicLinkToken.deleteMany({
+        where: { expires: { lt: now } }
+      })
+    ]);
+  }
+  async markAsUsed(id) {
+    await this.prisma.magicLinkToken.update({
+      where: { id },
+      data: { used: true }
+    });
+  }
+};
+export {
+  PrismaEmailTokenRepository,
+  PrismaOAuthAccountRepository,
+  PrismaUserRepository
+};

package/dist/auth/core/email/token-generator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Auth - Email Token Generator
+ *
+ * 이메일 인증용 토큰 생성 유틸리티 (프레임워크 독립적)
+ * crypto 모듈 기반
+ */
+export declare class TokenGenerator {
+    /**
+     * 안전한 랜덤 토큰 생성
+     *
+     * @param bytes - 바이트 수 (기본: 32)
+     * @returns 16진수 문자열 토큰
+     */
+    static generate(bytes?: number): string;
+    /**
+     * URL-safe 토큰 생성 (Base64URL)
+     *
+     * @param bytes - 바이트 수 (기본: 32)
+     * @returns URL-safe 토큰
+     */
+    static generateUrlSafe(bytes?: number): string;
+    /**
+     * 숫자 PIN 코드 생성
+     *
+     * @param length - PIN 길이 (기본: 6)
+     * @returns 숫자 PIN 코드
+     */
+    static generatePIN(length?: number): string;
+    /**
+     * 만료 시간 계산
+     *
+     * @param milliseconds - 만료까지의 밀리초
+     * @returns 만료 Date 객체
+     */
+    static calculateExpiry(milliseconds: number): Date;
+    /**
+     * 토큰이 만료되었는지 확인
+     *
+     * @param expiryDate - 만료 Date
+     * @returns 만료 여부
+     */
+    static isExpired(expiryDate: Date): boolean;
+}

package/dist/auth/core/email/token-generator.js

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

package/dist/auth/core/jwt/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared Auth - JWT Client Module
+ *
+ * 클라이언트 측 JWT 유틸리티 (브라우저 전용, 완전히 독립적)
+ * 프레임워크 독립적 - React, Vue, Angular 등 어디서나 사용 가능
+ */
+interface TokenStorage {
+    accessToken: string | null;
+    refreshToken: string | null;
+    expiresAt: number | null;
+}
+interface UserInfo {
+    userId: string;
+    email: string;
+    role: string;
+}
+export declare class JWTClientManager {
+    private storageKey;
+    constructor(storageKey?: string);
+    /**
+     * 로컬 스토리지에서 토큰 가져오기
+     */
+    getStoredTokens(): TokenStorage | null;
+    /**
+     * 토큰을 로컬 스토리지에 저장
+     */
+    storeTokens(accessToken: string, refreshToken: string, expiresIn?: number): void;
+    /**
+     * 로컬 스토리지에서 토큰 제거
+     */
+    clearStoredTokens(): void;
+    /**
+     * JWT 토큰에서 페이로드 디코딩 (검증 없음)
+     */
+    decodeJWTPayload(token: string): any | null;
+    /**
+     * 토큰 만료 여부 확인
+     */
+    isTokenExpired(token: string): boolean;
+    /**
+     * 토큰 남은 시간 (초)
+     */
+    getTokenRemainingTime(token: string): number;
+    /**
+     * 토큰에서 사용자 정보 추출
+     */
+    extractUserFromToken(token: string): UserInfo | null;
+    /**
+     * 토큰에서 사용자 role 추출
+     */
+    getUserRole(token: string | null): string;
+    /**
+     * Authorization 헤더 생성
+     */
+    createAuthHeader(token: string): string;
+    /**
+     * API 요청용 헤더 생성
+     */
+    createApiHeaders(token: string): Record<string, string>;
+    /**
+     * 토큰이 곧 만료되는지 확인 (5분 이내)
+     */
+    isTokenExpiringSoon(token: string, thresholdSeconds?: number): boolean;
+    /**
+     * 토큰 만료 시간 포맷팅
+     */
+    getTokenExpirationString(token: string): string | null;
+    /**
+     * 토큰 발급 시간 포맷팅
+     */
+    getTokenIssuedAtString(token: string): string | null;
+}
+export declare const getStoredTokens: () => TokenStorage | null;
+export declare const storeTokens: (accessToken: string, refreshToken: string, expiresIn?: number) => void;
+export declare const clearStoredTokens: () => void;
+export declare const clearTokens: () => void;
+export declare const decodeJWTPayload: (token: string) => any;
+export declare const isTokenExpired: (token: string) => boolean;
+export declare const getTokenRemainingTime: (token: string) => number;
+export declare const extractUserFromToken: (token: string) => UserInfo | null;
+export declare const getUserRole: (token: string | null) => string;
+export declare const createAuthHeader: (token: string) => string;
+export declare const createApiHeaders: (token: string) => Record<string, string>;
+export declare const isTokenExpiringSoon: (token: string) => boolean;
+export declare const getTokenExpirationString: (token: string) => string | null;
+export declare const getTokenIssuedAtString: (token: string) => string | null;
+export {};

package/dist/auth/core/jwt/client.js

@@ -0,0 +1,36 @@
+"use client";
+import {
+  JWTClientManager,
+  clearStoredTokens,
+  clearTokens,
+  createApiHeaders,
+  createAuthHeader,
+  decodeJWTPayload,
+  extractUserFromToken,
+  getStoredTokens,
+  getTokenExpirationString,
+  getTokenIssuedAtString,
+  getTokenRemainingTime,
+  getUserRole,
+  isTokenExpired,
+  isTokenExpiringSoon,
+  storeTokens
+} from "../../../chunk-XRRPEBKB.js";
+import "../../../chunk-ORMEWXMH.js";
+export {
+  JWTClientManager,
+  clearStoredTokens,
+  clearTokens,
+  createApiHeaders,
+  createAuthHeader,
+  decodeJWTPayload,
+  extractUserFromToken,
+  getStoredTokens,
+  getTokenExpirationString,
+  getTokenIssuedAtString,
+  getTokenRemainingTime,
+  getUserRole,
+  isTokenExpired,
+  isTokenExpiringSoon,
+  storeTokens
+};