@yeongseoksong/framework 1.6.2 → 1.7.0

package/README.md

@@ -144,7 +144,8 @@ import { appTheme } from './theme'
 | -------------------------------- | --------------------------------------------- |
 | `@yeongseoksong/framework/ui`    | UI 컴포넌트 전체 + `theme` (`"use client"`)   |
 | `@yeongseoksong/framework/store` | Zustand 스토어 — `useAuthStore` · `useUiStore` · `useNavStore` · `useSdForm` (`"use client"`) |
-| `@yeongseoksong/framework/util`  | `t()`, 한글 조사(`josa` · `withJosa` · `fixJosa`), `runFinalizers`, `filterAndSort`, `COMPANY_NAME`, `LOGO_SRC`, `LOGO_ALT` |
+| `@yeongseoksong/framework/util`  | `t()`, 한글 조사(`josa` · `withJosa` · `fixJosa`), `runFinalizers`, `filterAndSort`, `apiClient`, `COMPANY_NAME`, `LOGO_SRC`, `LOGO_ALT` |
+| `@yeongseoksong/framework/platform` | `apiClient`를 `useAuthStore`와 엮은 `Pl*` API — `PlAxios` 등 (`"use client"`) |
 | `@yeongseoksong/framework/types` | 공유 인터페이스                               |
 
 ---
@@ -862,6 +863,67 @@ fixJosa('서울(으)로 이전했습니다') // → '서울로 이전했습니
 
 ---
 
+## API 클라이언트
+
+axios 인스턴스는 `NEXT_PUBLIC_API_BASE_URL`을 baseURL로 쓰고, `withCredentials: true`로 **httpOnly 쿠키 인증**을 전제합니다(`useAuthStore`가 토큰을 담지 않는 이유와 같습니다 — localStorage에 토큰을 두면 XSS 한 번에 털립니다).
+
+경로가 두 개인데, **인스턴스는 하나**입니다. `/platform`은 `/util`의 같은 객체에 `Pl` 이름과 스토어 연동을 얹은 얇은 층입니다.
+
+| 경로                                | 쓰는 경우                                                    |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `@yeongseoksong/framework/util`     | 스토어를 쓰지 않거나 인증 처리를 직접 하겠다 — 서버 코드에서도 됩니다 |
+| `@yeongseoksong/framework/platform` | `useAuthStore`를 쓴다 — 401이면 자동 로그아웃 (`"use client"`) |
+
+### `/platform` — 스토어 연동
+
+```ts
+import { PlAxios, PlApiError, PlSetUnauthorizedHandler } from '@yeongseoksong/framework/platform'
+
+// 401이 최종 확정되면 세션은 이미 정리된 뒤입니다 — 여기엔 앱 고유의 후처리만 씁니다.
+PlSetUnauthorizedHandler(() => router.replace('/login'))
+
+try {
+  const { data } = await PlAxios.get('/me')
+} catch (e) {
+  if (e instanceof PlApiError) console.error(e.status, e.code, e.message)
+}
+```
+
+이 모듈을 import하는 것만으로 401 인터셉터가 `useAuthStore.getState().logout()`을 부르도록 등록됩니다. 슬롯이 하나뿐이므로 **`setUnauthorizedHandler`를 직접 부르지 마세요** — 부르면 로그아웃이 통째로 밀려납니다. `PlSetUnauthorizedHandler`가 그 뒤에 이어 붙는 자리입니다.
+
+`PlApiError`는 `/util`의 `ApiError`와 **같은 클래스 객체**라 어느 이름으로 `instanceof`를 해도 통합니다.
+
+### `/util` — 스토어 없이
+
+```ts
+import { apiClient, ApiError, setUnauthorizedHandler } from '@yeongseoksong/framework/util'
+
+setUnauthorizedHandler(() => myOwnLogout())
+```
+
+### 토큰·재발급
+
+```ts
+// 쿠키 대신 Authorization 헤더를 쓴다면 (토큰 보관은 앱 몫입니다)
+PlSetAccessTokenGetter(() => myTokenStore.accessToken)
+
+// 401 시 재발급. true를 반환하면 실패했던 요청을 1회만 재시도합니다.
+PlSetRefreshHandler(async () => {
+  try {
+    await PlAxios.post('/auth/refresh')
+    return true
+  } catch {
+    return false
+  }
+})
+```
+
+재시도는 `_retry` 플래그로 1회에 묶여 무한 루프가 나지 않고, 동시에 여러 요청이 401을 받아도 진행 중인 재발급 promise를 공유해 refresh 엔드포인트는 **한 번만** 호출됩니다.
+
+> `/platform`은 스토어를 가져오므로 클라이언트 전용입니다. 서버 컴포넌트·서버 액션에서는 `/util`의 `apiClient`를 쓰세요.
+
+---
+
 ## 타입
 
 ```ts

package/dist/platform/index.d.mts

@@ -0,0 +1,40 @@
+import * as axios from 'axios';
+import { ApiError, ApiErrorBody, setAccessTokenGetter, setRefreshHandler } from '@yeongseoksong/framework/util';
+
+/**
+ * 스토어와 연동된 API 클라이언트 진입점.
+ *
+ * 인스턴스 자체는 `util/axios.util.ts`가 소유한다 — axios에만 의존하는 순수 유틸이라
+ * `/util`로도 그대로 나간다. 여기서는 **재수출**만 하므로 사본이 늘지 않는다:
+ * import specifier가 상대 경로가 아니라 자기참조(`@yeongseoksong/framework/util`)이고
+ * `tsup.config.ts`의 platform 패스에서 external로 잡혀 있어, esbuild가 인라인 복사하지
+ * 않고 import 문으로 남긴다. 상대 경로(`'../util'`)로 바꾸는 순간 `axios.create()`가
+ * `dist/util`과 `dist/platform`에서 각각 돌아 인터셉터·토큰 getter 등록이 서로 다른
+ * 인스턴스에 걸리는 조용한 버그가 된다.
+ */
+declare const PlAxios: axios.AxiosInstance;
+/** {@link ApiError}의 platform 이름. 같은 클래스 객체라 `instanceof`가 양쪽 이름 모두에서 통한다. */
+declare const PlApiError: typeof ApiError;
+type PlApiError = ApiError;
+/** 서버가 내려주는 표준 에러 바디. */
+type PlApiErrorBody = ApiErrorBody;
+/**
+ * 매 요청에 `Authorization: Bearer <token>` 헤더를 붙일 getter를 등록한다.
+ * `useAuthStore`는 토큰을 담지 않으므로(`partialize`가 프로필만 저장) 이 경로만은
+ * 스토어와 무관하게 소비자가 자신의 저장소를 연결한다.
+ */
+declare const PlSetAccessTokenGetter: typeof setAccessTokenGetter;
+/** 401 시 토큰 재발급을 시도할 핸들러를 등록한다. `true`를 반환하면 실패했던 요청을 1회 재시도한다. */
+declare const PlSetRefreshHandler: typeof setRefreshHandler;
+type PlUnauthorizedHandler = () => void;
+/**
+ * 최종 인증 실패(재발급이 없거나 실패한 401) 시 실행할 **추가** 핸들러를 등록한다.
+ * `null`을 넘기면 해제된다.
+ *
+ * 세션 정리(`useAuthStore.logout()`)는 위 인터셉터가 이미 하므로 여기서 또 할 필요가
+ * 없다. 이 콜백은 프레임워크가 대신할 수 없는 앱 고유의 후처리 — 로그인 페이지로
+ * 라우팅, 토스트, 로깅 — 를 위한 자리다.
+ */
+declare function PlSetUnauthorizedHandler(handler: PlUnauthorizedHandler | null): void;
+
+export { PlApiError, type PlApiErrorBody, PlAxios, PlSetAccessTokenGetter, PlSetRefreshHandler, PlSetUnauthorizedHandler };

package/dist/platform/index.mjs

@@ -0,0 +1,30 @@
+"use client";
+
+// platform/axios.ts
+import {
+  apiClient,
+  ApiError,
+  setAccessTokenGetter,
+  setRefreshHandler,
+  setUnauthorizedHandler
+} from "@yeongseoksong/framework/util";
+import { useAuthStore } from "@yeongseoksong/framework/store";
+var PlAxios = apiClient;
+var PlApiError = ApiError;
+var PlSetAccessTokenGetter = setAccessTokenGetter;
+var PlSetRefreshHandler = setRefreshHandler;
+var appUnauthorizedHandler = null;
+setUnauthorizedHandler(() => {
+  useAuthStore.getState().logout();
+  appUnauthorizedHandler == null ? void 0 : appUnauthorizedHandler();
+});
+function PlSetUnauthorizedHandler(handler) {
+  appUnauthorizedHandler = handler;
+}
+export {
+  PlApiError,
+  PlAxios,
+  PlSetAccessTokenGetter,
+  PlSetRefreshHandler,
+  PlSetUnauthorizedHandler
+};