@wheeparam/library 0.0.5 → 0.0.6

package/dist/client/index.cjs

@@ -34,169 +34,306 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 
-// src/client/axios.ts
+// src/client/createAxiosClient.ts
 var import_axios = __toESM(require("axios"), 1);
-function createLocalStorageTokenAccess(keys) {
-  const accessTokenKey = keys?.accessTokenKey ?? "accessToken";
-  const refreshTokenKey = keys?.refreshTokenKey ?? "refreshToken";
+
+// src/client/error.ts
+var defaultShouldRefresh = (error) => {
+  return error.response?.status === 401;
+};
+function defaultParseRefreshResponse(data) {
+  const source = typeof data === "object" && data !== null ? data : {};
+  const accessToken = typeof source.result?.accessToken === "string" && source.result.accessToken || typeof source.accessToken === "string" && source.accessToken || typeof source.result?.token === "string" && source.result.token || typeof source.token === "string" && source.token || "";
+  const refreshToken = typeof source.result?.refreshToken === "string" && source.result.refreshToken || typeof source.refreshToken === "string" && source.refreshToken || void 0;
+  if (!accessToken) {
+    throw new Error("Refresh response does not contain accessToken");
+  }
   return {
-    get() {
-      return {
-        accessToken: window.localStorage.getItem(accessTokenKey),
-        refreshToken: window.localStorage.getItem(refreshTokenKey)
-      };
+    accessToken,
+    refreshToken
+  };
+}
+function getDefaultErrorMessage(error) {
+  const axiosError = error;
+  const status = axiosError.response?.status;
+  const serverMessage = axiosError.response?.data?.error;
+  if (serverMessage && serverMessage.trim().length > 0) {
+    return serverMessage;
+  }
+  switch (status) {
+    case 0:
+      return "REST API \uC11C\uBC84\uC5D0 \uC811\uADFC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.\n\uC11C\uBC84 \uAD00\uB9AC\uC790\uC5D0\uAC8C \uBB38\uC758\uD558\uC138\uC694.";
+    case 400:
+      return "\uC798\uBABB\uB41C \uC694\uCCAD\uC785\uB2C8\uB2E4.";
+    case 401:
+      return "\uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.";
+    case 403:
+      return "\uC811\uADFC \uAD8C\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.";
+    case 404:
+      return "[404] REST API \uC694\uCCAD\uC5D0 \uC2E4\uD328\uD558\uC600\uC2B5\uB2C8\uB2E4.";
+    case 500:
+      return "\uC11C\uBC84\uC5D0\uC11C \uCC98\uB9AC \uC911 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD558\uC600\uC2B5\uB2C8\uB2E4.";
+    default:
+      return "";
+  }
+}
+
+// src/client/refreshManager.ts
+var RefreshManager = class {
+  constructor() {
+    this.isRefreshing = false;
+    this.subscribers = [];
+  }
+  /**
+   * 현재 refresh 진행 중인지 반환합니다.
+   */
+  get refreshing() {
+    return this.isRefreshing;
+  }
+  /**
+   * refresh 시작 상태로 전환합니다.
+   */
+  begin() {
+    this.isRefreshing = true;
+  }
+  /**
+   * refresh 종료 상태로 전환합니다.
+   */
+  end() {
+    this.isRefreshing = false;
+  }
+  /**
+   * refresh 완료를 기다리는 subscriber를 등록합니다.
+   *
+   * @param callback refresh 완료 후 호출될 함수
+   */
+  subscribe(callback) {
+    this.subscribers.push(callback);
+  }
+  /**
+   * 대기 중인 subscriber들에게 결과를 알리고 큐를 초기화합니다.
+   *
+   * @param token 새 access token
+   */
+  notify(token) {
+    this.subscribers.forEach((callback) => callback(token));
+    this.subscribers = [];
+  }
+};
+async function requestRefresh(params) {
+  const {
+    refreshUrl,
+    withCredentials,
+    refreshStrategy,
+    refreshToken,
+    parseRefreshResponse
+  } = params;
+  const requestInit = {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
     },
-    set(data) {
-      if (data.accessToken !== void 0) {
-        window.localStorage.setItem(accessTokenKey, data.accessToken ?? "");
+    credentials: withCredentials ? "include" : "same-origin"
+  };
+  if (refreshStrategy === "body") {
+    if (!refreshToken) {
+      throw new Error("Refresh token not found");
+    }
+    requestInit.body = JSON.stringify({ refreshToken });
+  }
+  const response = await fetch(refreshUrl, requestInit);
+  if (!response.ok) {
+    throw new Error("Token refresh failed");
+  }
+  const json = await response.json();
+  return parseRefreshResponse(json);
+}
+
+// src/client/tokenStorage.ts
+function createAccessTokenAccess(mode, key = "accessToken") {
+  let memoryToken = null;
+  if (mode === "localStorage") {
+    return {
+      get: () => window.localStorage.getItem(key),
+      set: (token) => {
+        if (!token) {
+          window.localStorage.removeItem(key);
+        } else {
+          window.localStorage.setItem(key, token);
+        }
+      },
+      clear: () => {
+        window.localStorage.removeItem(key);
       }
-      if (data.refreshToken !== void 0) {
-        window.localStorage.setItem(refreshTokenKey, data.refreshToken ?? "");
+    };
+  }
+  if (mode === "memory") {
+    return {
+      get: () => memoryToken,
+      set: (token) => {
+        memoryToken = token;
+      },
+      clear: () => {
+        memoryToken = null;
       }
+    };
+  }
+  return {
+    get: () => null,
+    set: () => {
     },
-    clear() {
-      window.localStorage.removeItem(accessTokenKey);
-      window.localStorage.removeItem(refreshTokenKey);
+    clear: () => {
     }
   };
 }
-function createCookieModeTokenAccess(keys) {
-  const refreshTokenKey = keys?.refreshTokenKey ?? "refreshToken";
+function createRefreshTokenAccess(key = "refreshToken") {
   return {
-    get() {
-      return {
-        accessToken: null,
-        // 쿠키 기반이면 JS에서 accessToken을 직접 읽지 않는 전제를 둔다.
-        refreshToken: window.localStorage.getItem(refreshTokenKey)
-      };
-    },
-    set(data) {
-      if (data.refreshToken !== void 0) {
-        window.localStorage.setItem(refreshTokenKey, data.refreshToken ?? "");
+    get: () => window.localStorage.getItem(key),
+    set: (token) => {
+      if (!token) {
+        window.localStorage.removeItem(key);
+      } else {
+        window.localStorage.setItem(key, token);
       }
     },
-    clear() {
-      window.localStorage.removeItem(refreshTokenKey);
+    clear: () => {
+      window.localStorage.removeItem(key);
     }
   };
 }
+
+// src/client/createAxiosClient.ts
+function setAuthorizationHeader(config, accessToken) {
+  const headers = new import_axios.AxiosHeaders();
+  if (config.headers) {
+    const current = config.headers instanceof import_axios.AxiosHeaders ? config.headers.toJSON() : config.headers;
+    for (const [key, value] of Object.entries(current)) {
+      if (value !== void 0) {
+        headers.set(key, String(value));
+      }
+    }
+  }
+  headers.set("Authorization", `Bearer ${accessToken}`);
+  config.headers = headers;
+  return config;
+}
 function createAxiosClient(options) {
   const {
     baseURL,
     timeout = 1e4,
     withCredentials = true,
     refreshUrl,
-    storage = "localStorage",
+    accessTokenStorage = "localStorage",
+    refreshStrategy = "body",
     storageKeys,
     onAuthStateChange,
     onError,
-    getErrorMessage
+    getErrorMessage,
+    shouldRefresh = defaultShouldRefresh,
+    parseRefreshResponse = defaultParseRefreshResponse
   } = options;
-  const instance = import_axios.default.create({ baseURL, timeout, withCredentials });
-  const tokenAccess = storage === "localStorage" ? createLocalStorageTokenAccess(storageKeys) : createCookieModeTokenAccess({ refreshTokenKey: storageKeys?.refreshTokenKey });
-  let isRefreshing = false;
-  let subscribers = [];
-  const notifySubscribers = (token) => {
-    subscribers.forEach((cb) => cb(token));
-    subscribers = [];
-  };
+  const accessTokenKey = storageKeys?.accessTokenKey ?? "accessToken";
+  const refreshTokenKey = storageKeys?.refreshTokenKey ?? "refreshToken";
+  const instance = import_axios.default.create({
+    baseURL,
+    timeout,
+    withCredentials
+  });
+  const accessTokenAccess = createAccessTokenAccess(accessTokenStorage, accessTokenKey);
+  const refreshTokenAccess = createRefreshTokenAccess(refreshTokenKey);
+  const refreshManager = new RefreshManager();
   const clearAuth = () => {
-    tokenAccess.clear();
+    accessTokenAccess.clear();
+    if (refreshStrategy === "body") {
+      refreshTokenAccess.clear();
+    }
     onAuthStateChange?.("unauthenticated");
   };
-  const requestRefresh = async (refreshToken) => {
-    const res = await fetch(refreshUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refreshToken }),
-      credentials: withCredentials ? "include" : "same-origin"
-    });
-    if (!res.ok) {
-      throw new Error("Token refresh failed");
+  const getToken = () => {
+    return {
+      accessToken: accessTokenAccess.get(),
+      refreshToken: refreshStrategy === "body" ? refreshTokenAccess.get() : null
+    };
+  };
+  const setToken = (data) => {
+    if (data.accessToken !== void 0) {
+      accessTokenAccess.set(data.accessToken ?? null);
+    }
+    if (refreshStrategy === "body" && data.refreshToken !== void 0) {
+      refreshTokenAccess.set(data.refreshToken ?? null);
     }
-    return await res.json();
   };
   instance.interceptors.request.use(
     (config) => {
-      const { accessToken } = tokenAccess.get();
+      const accessToken = accessTokenAccess.get();
       if (accessToken) {
-        config.headers = config.headers ?? {};
-        config.headers.Authorization = `Bearer ${accessToken}`;
+        setAuthorizationHeader(config, accessToken);
       }
       return config;
     },
-    (e) => Promise.reject(e)
+    (error) => Promise.reject(error)
   );
   instance.interceptors.response.use(
-    (res) => res,
+    (response) => response,
     async (error) => {
-      const response = error.response;
-      const status = response?.status;
       const originalRequest = error.config ?? {};
-      if (status !== 401) {
-        let message = getErrorMessage?.(error) ?? response?.data?.error ?? "";
-        if (!message && typeof status === "number") {
-          switch (status) {
-            case 0:
-              message = "REST API \uC11C\uBC84\uC5D0 \uC811\uADFC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4\n\uC11C\uBC84 \uAD00\uB9AC\uC790\uC5D0\uAC8C \uBB38\uC758\uD558\uC138\uC694";
-              break;
-            case 400:
-              message = "\uC798\uBABB\uB41C \uC694\uCCAD\uC785\uB2C8\uB2E4.";
-              break;
-            case 404:
-              message = "[404] REST API \uC694\uCCAD\uC5D0 \uC2E4\uD328\uD558\uC600\uC2B5\uB2C8\uB2E4";
-              break;
-            case 500:
-              message = "\uC11C\uBC84\uC5D0\uC11C \uCC98\uB9AC \uC911 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD558\uC600\uC2B5\uB2C8\uB2E4.";
-              break;
-          }
+      if (!shouldRefresh(error)) {
+        const message = getErrorMessage?.(error) ?? getDefaultErrorMessage(error);
+        if (message) {
+          onError?.(message, error);
         }
-        if (message) onError?.(message, error);
         return Promise.reject(error);
       }
-      if (originalRequest._retry) {
+      const requestUrl = originalRequest.url ?? "";
+      if (typeof requestUrl === "string" && requestUrl.includes(refreshUrl)) {
         clearAuth();
         return Promise.reject(error);
       }
-      originalRequest._retry = true;
-      const { refreshToken } = tokenAccess.get();
-      if (!refreshToken) {
+      if (originalRequest._retry) {
         clearAuth();
         return Promise.reject(error);
       }
-      if (isRefreshing) {
+      originalRequest._retry = true;
+      if (refreshManager.refreshing) {
         return new Promise((resolve, reject) => {
-          subscribers.push((newToken) => {
-            if (!newToken) return reject(error);
-            originalRequest.headers = originalRequest.headers ?? {};
-            originalRequest.headers.Authorization = `Bearer ${newToken}`;
-            resolve(instance(originalRequest));
+          refreshManager.subscribe((newAccessToken) => {
+            if (!newAccessToken) {
+              reject(error);
+              return;
+            }
+            const retryRequest = setAuthorizationHeader(originalRequest, newAccessToken);
+            resolve(instance(retryRequest));
           });
         });
       }
-      isRefreshing = true;
+      refreshManager.begin();
       try {
-        const newTokens = await requestRefresh(refreshToken);
-        tokenAccess.set(newTokens);
+        const newTokens = await requestRefresh({
+          refreshUrl,
+          withCredentials,
+          refreshStrategy,
+          refreshToken: refreshStrategy === "body" ? refreshTokenAccess.get() : null,
+          parseRefreshResponse
+        });
+        setToken(newTokens);
         onAuthStateChange?.("authenticated");
-        isRefreshing = false;
-        notifySubscribers(newTokens.accessToken);
-        originalRequest.headers = originalRequest.headers ?? {};
-        originalRequest.headers.Authorization = `Bearer ${newTokens.accessToken}`;
-        return instance(originalRequest);
-      } catch (e) {
-        isRefreshing = false;
-        notifySubscribers(null);
+        refreshManager.end();
+        refreshManager.notify(newTokens.accessToken);
+        const retryRequest = setAuthorizationHeader(originalRequest, newTokens.accessToken);
+        return instance(retryRequest);
+      } catch (refreshError) {
+        refreshManager.end();
+        refreshManager.notify(null);
         clearAuth();
-        return Promise.reject(error);
+        return Promise.reject(refreshError);
       }
     }
   );
   return {
     axios: instance,
-    setToken: (data) => tokenAccess.set(data),
-    getToken: () => tokenAccess.get(),
-    clearToken: () => clearAuth()
+    setToken,
+    getToken,
+    clearToken: clearAuth
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

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 };