@wheeparam/library 0.0.4 → 0.0.6

package/dist/client/index.d.cts

@@ -1,144 +1,173 @@
-import { AxiosInstance } from 'axios';
+import { AxiosInstance, AxiosError } from 'axios';
 
 /**
  * @packageDocumentation
- * Axios Client (Client-only)
- *
- * 공통 요구사항:
- * - accessToken이 있으면 Authorization 헤더에 첨부
- * - 401 발생 시 refreshToken으로 토큰 재발급을 시도하고, 원래 요청을 재시도
- * - refresh 중복 호출 방지(큐 방식)
- *
- * 단순화 정책:
- * - refresh URL만 옵션으로 받아 내부에서 fetch로 토큰 재발급을 수행한다.
- * - 토큰 저장은 "localStorage" 또는 "cookie" 2가지 모드만 지원한다.
- *
- * ⚠️ 이 모듈은 브라우저 전용이다(window/localStorage 사용 가능).
- * Next.js에서는 반드시 Client Component 또는 클라이언트 전용 모듈에서 import 해야 한다.
+ * Axios client type definitions.
  */
 
 /**
- * 토큰 저장 방식
- * - localStorage: accessToken/refreshToken을 localStorage에 저장
- * - cookie: 토큰을 쿠키 기반으로 운용(클라 저장 최소화)
+ * AccessToken 저장 방식
+ *
+ * - localStorage: 브라우저 localStorage에 저장
+ * - memory: 현재 탭 메모리에만 저장
+ * - none: 저장하지 않음
  */
-type TokenStorageMode = "localStorage" | "cookie";
+type AccessTokenStorageMode = "localStorage" | "memory" | "none";
 /**
- * refresh 요청/응답 타입
+ * Refresh 요청 전략
+ *
+ * - body:
+ *   refreshToken을 클라이언트가 보관하고 있다가 body에 포함해 전송
+ *
+ * - cookieOnly:
+ *   refreshToken을 클라이언트 JS가 보관하지 않고,
+ *   HttpOnly Cookie 등 서버가 읽을 수 있는 방식만 사용
+ */
+type RefreshStrategy = "body" | "cookieOnly";
+/**
+ * Refresh 요청 body
  */
 type RefreshRequestBody = {
     refreshToken: string;
 };
+/**
+ * Refresh 응답 body
+ */
 type RefreshResponseBody = {
     accessToken: string;
-    refreshToken: string;
+    refreshToken?: string;
 };
 /**
- * createAxiosClient 옵션
+ * 로그인 상태
+ */
+type AuthState = "authenticated" | "unauthenticated";
+/**
+ * localStorage key 설정
+ */
+type TokenStorageKeys = {
+    accessTokenKey?: string;
+    refreshTokenKey?: string;
+};
+/**
+ * refresh 여부 판별 함수
+ */
+type ShouldRefreshFn = (error: AxiosError<unknown>) => boolean;
+/**
+ * refresh 응답 파싱 함수
+ */
+type ParseRefreshResponseFn = (data: unknown) => RefreshResponseBody;
+/**
+ * axios client 생성 옵션
  */
 type CreateAxiosClientOptions = {
     /**
-     * axios baseURL (선택)
+     * axios baseURL
      */
     baseURL?: string;
     /**
-     * 요청 타임아웃(ms)
+     * 요청 timeout(ms)
      * @default 10000
      */
     timeout?: number;
     /**
      * 쿠키 전송 여부
-     * - cookie 모드에서는 거의 필수
      * @default true
      */
     withCredentials?: boolean;
     /**
-     * 토큰 재발급(Refresh) API URL
+     * refresh API URL
      * @example "/api/authorize/token"
      */
     refreshUrl: string;
     /**
-     * 토큰 저장 방식
+     * accessToken 저장 방식
      * @default "localStorage"
      */
-    storage?: TokenStorageMode;
+    accessTokenStorage?: AccessTokenStorageMode;
     /**
-     * localStorage 키 이름(선택)
-     * @default { accessTokenKey: "accessToken", refreshTokenKey: "refreshToken" }
+     * refresh 전략
+     * @default "body"
      */
-    storageKeys?: {
-        accessTokenKey?: string;
-        refreshTokenKey?: string;
-    };
+    refreshStrategy?: RefreshStrategy;
+    /**
+     * 저장 key 이름
+     */
+    storageKeys?: TokenStorageKeys;
     /**
-     * 로그인 상태 변화 콜백(선택)
-     * - 프로젝트의 auth context/ref/store 업데이트에 사용
+     * 인증 상태 변경 콜백
      */
-    onAuthStateChange?: (status: "authenticated" | "unauthenticated") => void;
+    onAuthStateChange?: (status: AuthState) => void;
     /**
-     * 일반 에러 표시 콜백(선택)
-     * - Swal/toast 등 프로젝트 스타일로 구현
+     * 일반 에러 출력 콜백
      */
     onError?: (message: string, error: unknown) => void;
     /**
-     * API 에러 메시지 추출 커스터마이즈(선택)
-     * - null 반환 시 내부 기본 로직 사용
+     * 에러 메시지 추출 커스터마이즈
      */
     getErrorMessage?: (error: unknown) => string | null;
+    /**
+     * refresh 여부 판별 커스터마이즈
+     */
+    shouldRefresh?: ShouldRefreshFn;
+    /**
+     * refresh 응답 파싱 커스터마이즈
+     */
+    parseRefreshResponse?: ParseRefreshResponseFn;
 };
 /**
- * createAxiosClient 반환값
+ * createAxiosClient 반환 타입
  */
 type AxiosClient = {
     /**
-     * 구성 완료된 axios instance
+     * 구성된 axios instance
      */
     axios: AxiosInstance;
     /**
-     * 토큰 설정(로그인 성공 등)
-     * - localStorage 모드: localStorage에 저장
-     * - cookie 모드: 기본 구현은 refreshToken만 저장(필요 시)
+     * 토큰 저장
      */
     setToken: (data: Partial<RefreshResponseBody>) => void;
     /**
-     * 토큰 조회
+     * 현재 토큰 조회
      */
     getToken: () => {
         accessToken: string | null;
         refreshToken: string | null;
     };
     /**
-     * 토큰 제거(로그아웃)
+     * 토큰 제거
      */
     clearToken: () => void;
 };
+
 /**
- * 공용 axios 클라이언트를 생성한다.
+ * 공용 axios client를 생성합니다.
  *
- * 토큰 자동 첨부 + 401 발생 시 refresh 후 재요청을 처리한다.
+ * 이 클라이언트는 다음 기능을 제공합니다.
+ * - accessToken 자동 첨부
+ * - 401 발생 시 refresh 후 원래 요청 재시도
+ * - refresh 중복 호출 방지
  *
- * @example 기본 사용법 (Next.js Client Component)
+ * @example
  * ```ts
  * "use client";
  *
  * import Swal from "sweetalert2";
- * import nl2br from "@/utils/common";
- * import { authContextRef } from "@/components/providers/auth-provider";
- * import { createAxiosClient } from "@your-scope/toolkit/client";
+ * import { createAxiosClient } from "@your-scope/your-package/client";
  *
- * export const { axios, setToken, clearToken, getToken } = createAxiosClient({
+ * export const { axios, setToken, getToken, clearToken } = createAxiosClient({
  *   refreshUrl: "/api/authorize/token",
- *   storage: "localStorage",
+ *   accessTokenStorage: "localStorage",
+ *   refreshStrategy: "cookieOnly",
+ *   withCredentials: true,
  *
  *   onAuthStateChange: (status) => {
- *     authContextRef.setLoginStatus?.(status);
+ *     console.log("auth state:", status);
  *   },
  *
  *   onError: (message) => {
  *     Swal.fire({
  *       title: "오류 발생",
- *       html: nl2br(message),
- *       backdrop: false,
+ *       html: message.replace(/\\n/g, "<br />"),
  *       confirmButtonText: "확인",
  *     });
  *   },
@@ -147,33 +176,17 @@ type AxiosClient = {
  * export default axios;
  * ```
  *
- * @example 로그인 성공 후 토큰 저장
+ * @example
  * ```ts
- * import { setToken } from "@/lib/axios";
- *
- * async function login(id: string, pw: string) {
- *   const res = await fetch("/api/login", {
- *     method: "POST",
- *     body: JSON.stringify({ id, pw })
- *   }).then(r => r.json());
- *
- *   setToken({
- *     accessToken: res.accessToken,
- *     refreshToken: res.refreshToken
- *   });
- * }
+ * const { axios } = createAxiosClient({
+ *   refreshUrl: "/api/authorize/token",
+ *   accessTokenStorage: "localStorage",
+ *   refreshStrategy: "body",
+ * });
  * ```
  *
- * @example 로그아웃 처리
- * ```ts
- * import { clearToken } from "@/lib/axios";
- *
- * function logout() {
- *   clearToken();
- *   location.href = "/login";
- * }
- * ```
+ * @param options 생성 옵션
  */
 declare function createAxiosClient(options: CreateAxiosClientOptions): AxiosClient;
 
-export { type AxiosClient, type CreateAxiosClientOptions, type RefreshRequestBody, type RefreshResponseBody, type TokenStorageMode, createAxiosClient };
+export { type AccessTokenStorageMode, type AuthState, type AxiosClient, type CreateAxiosClientOptions, type ParseRefreshResponseFn, type RefreshRequestBody, type RefreshResponseBody, type RefreshStrategy, type ShouldRefreshFn, type TokenStorageKeys, createAxiosClient };

package/dist/client/index.d.ts

@@ -1,144 +1,173 @@
-import { AxiosInstance } from 'axios';
+import { AxiosInstance, AxiosError } from 'axios';
 
 /**
  * @packageDocumentation
- * Axios Client (Client-only)
- *
- * 공통 요구사항:
- * - accessToken이 있으면 Authorization 헤더에 첨부
- * - 401 발생 시 refreshToken으로 토큰 재발급을 시도하고, 원래 요청을 재시도
- * - refresh 중복 호출 방지(큐 방식)
- *
- * 단순화 정책:
- * - refresh URL만 옵션으로 받아 내부에서 fetch로 토큰 재발급을 수행한다.
- * - 토큰 저장은 "localStorage" 또는 "cookie" 2가지 모드만 지원한다.
- *
- * ⚠️ 이 모듈은 브라우저 전용이다(window/localStorage 사용 가능).
- * Next.js에서는 반드시 Client Component 또는 클라이언트 전용 모듈에서 import 해야 한다.
+ * Axios client type definitions.
  */
 
 /**
- * 토큰 저장 방식
- * - localStorage: accessToken/refreshToken을 localStorage에 저장
- * - cookie: 토큰을 쿠키 기반으로 운용(클라 저장 최소화)
+ * AccessToken 저장 방식
+ *
+ * - localStorage: 브라우저 localStorage에 저장
+ * - memory: 현재 탭 메모리에만 저장
+ * - none: 저장하지 않음
  */
-type TokenStorageMode = "localStorage" | "cookie";
+type AccessTokenStorageMode = "localStorage" | "memory" | "none";
 /**
- * refresh 요청/응답 타입
+ * Refresh 요청 전략
+ *
+ * - body:
+ *   refreshToken을 클라이언트가 보관하고 있다가 body에 포함해 전송
+ *
+ * - cookieOnly:
+ *   refreshToken을 클라이언트 JS가 보관하지 않고,
+ *   HttpOnly Cookie 등 서버가 읽을 수 있는 방식만 사용
+ */
+type RefreshStrategy = "body" | "cookieOnly";
+/**
+ * Refresh 요청 body
  */
 type RefreshRequestBody = {
     refreshToken: string;
 };
+/**
+ * Refresh 응답 body
+ */
 type RefreshResponseBody = {
     accessToken: string;
-    refreshToken: string;
+    refreshToken?: string;
 };
 /**
- * createAxiosClient 옵션
+ * 로그인 상태
+ */
+type AuthState = "authenticated" | "unauthenticated";
+/**
+ * localStorage key 설정
+ */
+type TokenStorageKeys = {
+    accessTokenKey?: string;
+    refreshTokenKey?: string;
+};
+/**
+ * refresh 여부 판별 함수
+ */
+type ShouldRefreshFn = (error: AxiosError<unknown>) => boolean;
+/**
+ * refresh 응답 파싱 함수
+ */
+type ParseRefreshResponseFn = (data: unknown) => RefreshResponseBody;
+/**
+ * axios client 생성 옵션
  */
 type CreateAxiosClientOptions = {
     /**
-     * axios baseURL (선택)
+     * axios baseURL
      */
     baseURL?: string;
     /**
-     * 요청 타임아웃(ms)
+     * 요청 timeout(ms)
      * @default 10000
      */
     timeout?: number;
     /**
      * 쿠키 전송 여부
-     * - cookie 모드에서는 거의 필수
      * @default true
      */
     withCredentials?: boolean;
     /**
-     * 토큰 재발급(Refresh) API URL
+     * refresh API URL
      * @example "/api/authorize/token"
      */
     refreshUrl: string;
     /**
-     * 토큰 저장 방식
+     * accessToken 저장 방식
      * @default "localStorage"
      */
-    storage?: TokenStorageMode;
+    accessTokenStorage?: AccessTokenStorageMode;
     /**
-     * localStorage 키 이름(선택)
-     * @default { accessTokenKey: "accessToken", refreshTokenKey: "refreshToken" }
+     * refresh 전략
+     * @default "body"
      */
-    storageKeys?: {
-        accessTokenKey?: string;
-        refreshTokenKey?: string;
-    };
+    refreshStrategy?: RefreshStrategy;
+    /**
+     * 저장 key 이름
+     */
+    storageKeys?: TokenStorageKeys;
     /**
-     * 로그인 상태 변화 콜백(선택)
-     * - 프로젝트의 auth context/ref/store 업데이트에 사용
+     * 인증 상태 변경 콜백
      */
-    onAuthStateChange?: (status: "authenticated" | "unauthenticated") => void;
+    onAuthStateChange?: (status: AuthState) => void;
     /**
-     * 일반 에러 표시 콜백(선택)
-     * - Swal/toast 등 프로젝트 스타일로 구현
+     * 일반 에러 출력 콜백
      */
     onError?: (message: string, error: unknown) => void;
     /**
-     * API 에러 메시지 추출 커스터마이즈(선택)
-     * - null 반환 시 내부 기본 로직 사용
+     * 에러 메시지 추출 커스터마이즈
      */
     getErrorMessage?: (error: unknown) => string | null;
+    /**
+     * refresh 여부 판별 커스터마이즈
+     */
+    shouldRefresh?: ShouldRefreshFn;
+    /**
+     * refresh 응답 파싱 커스터마이즈
+     */
+    parseRefreshResponse?: ParseRefreshResponseFn;
 };
 /**
- * createAxiosClient 반환값
+ * createAxiosClient 반환 타입
  */
 type AxiosClient = {
     /**
-     * 구성 완료된 axios instance
+     * 구성된 axios instance
      */
     axios: AxiosInstance;
     /**
-     * 토큰 설정(로그인 성공 등)
-     * - localStorage 모드: localStorage에 저장
-     * - cookie 모드: 기본 구현은 refreshToken만 저장(필요 시)
+     * 토큰 저장
      */
     setToken: (data: Partial<RefreshResponseBody>) => void;
     /**
-     * 토큰 조회
+     * 현재 토큰 조회
      */
     getToken: () => {
         accessToken: string | null;
         refreshToken: string | null;
     };
     /**
-     * 토큰 제거(로그아웃)
+     * 토큰 제거
      */
     clearToken: () => void;
 };
+
 /**
- * 공용 axios 클라이언트를 생성한다.
+ * 공용 axios client를 생성합니다.
  *
- * 토큰 자동 첨부 + 401 발생 시 refresh 후 재요청을 처리한다.
+ * 이 클라이언트는 다음 기능을 제공합니다.
+ * - accessToken 자동 첨부
+ * - 401 발생 시 refresh 후 원래 요청 재시도
+ * - refresh 중복 호출 방지
  *
- * @example 기본 사용법 (Next.js Client Component)
+ * @example
  * ```ts
  * "use client";
  *
  * import Swal from "sweetalert2";
- * import nl2br from "@/utils/common";
- * import { authContextRef } from "@/components/providers/auth-provider";
- * import { createAxiosClient } from "@your-scope/toolkit/client";
+ * import { createAxiosClient } from "@your-scope/your-package/client";
  *
- * export const { axios, setToken, clearToken, getToken } = createAxiosClient({
+ * export const { axios, setToken, getToken, clearToken } = createAxiosClient({
  *   refreshUrl: "/api/authorize/token",
- *   storage: "localStorage",
+ *   accessTokenStorage: "localStorage",
+ *   refreshStrategy: "cookieOnly",
+ *   withCredentials: true,
  *
  *   onAuthStateChange: (status) => {
- *     authContextRef.setLoginStatus?.(status);
+ *     console.log("auth state:", status);
  *   },
  *
  *   onError: (message) => {
  *     Swal.fire({
  *       title: "오류 발생",
- *       html: nl2br(message),
- *       backdrop: false,
+ *       html: message.replace(/\\n/g, "<br />"),
  *       confirmButtonText: "확인",
  *     });
  *   },
@@ -147,33 +176,17 @@ type AxiosClient = {
  * export default axios;
  * ```
  *
- * @example 로그인 성공 후 토큰 저장
+ * @example
  * ```ts
- * import { setToken } from "@/lib/axios";
- *
- * async function login(id: string, pw: string) {
- *   const res = await fetch("/api/login", {
- *     method: "POST",
- *     body: JSON.stringify({ id, pw })
- *   }).then(r => r.json());
- *
- *   setToken({
- *     accessToken: res.accessToken,
- *     refreshToken: res.refreshToken
- *   });
- * }
+ * const { axios } = createAxiosClient({
+ *   refreshUrl: "/api/authorize/token",
+ *   accessTokenStorage: "localStorage",
+ *   refreshStrategy: "body",
+ * });
  * ```
  *
- * @example 로그아웃 처리
- * ```ts
- * import { clearToken } from "@/lib/axios";
- *
- * function logout() {
- *   clearToken();
- *   location.href = "/login";
- * }
- * ```
+ * @param options 생성 옵션
  */
 declare function createAxiosClient(options: CreateAxiosClientOptions): AxiosClient;
 
-export { type AxiosClient, type CreateAxiosClientOptions, type RefreshRequestBody, type RefreshResponseBody, type TokenStorageMode, createAxiosClient };
+export { type AccessTokenStorageMode, type AuthState, type AxiosClient, type CreateAxiosClientOptions, type ParseRefreshResponseFn, type RefreshRequestBody, type RefreshResponseBody, type RefreshStrategy, type ShouldRefreshFn, type TokenStorageKeys, createAxiosClient };