@ph-cms/client-sdk 0.1.5 → 0.1.7

package/README.md

@@ -1,15 +1,16 @@
 # @ph-cms/client-sdk
 
-Unified PH-CMS client SDK for browser and React applications.
+PH-CMS 클라이언트 SDK — 브라우저 및 React 애플리케이션을 위한 통합 클라이언트.
 
-This package provides:
+**주요 기능:**
 
-- A typed API client
-- Auth provider interfaces and implementations
-- React context and hooks for consuming the client in UI code
-- **Integrated React Query support** (from v0.1.1)
-- **Automatic Auth State Management** (from v0.1.3)
-- **Conditional profile fetching & guaranteed post-login profile load** (from v0.1.4)
+- 타입이 지정된 API 클라이언트
+- Auth Provider 인터페이스 및 구현체 (`LocalAuthProvider`, `FirebaseAuthProvider`)
+- React Context 및 Hooks
+- React Query 통합
+- 자동 토큰 갱신 (Proactive + Reactive)
+- Firebase ↔ PH-CMS 인증 동기화
+- 세분화된 인증 상태 관리 (`authStatus`)
 
 ## Installation
 
@@ -17,7 +18,82 @@ This package provides:
 npm install @ph-cms/client-sdk
 ```
 
-> **Note:** `@tanstack/react-query` is a direct dependency. You no longer need to install it manually unless you use it in your own application code.
+> `@tanstack/react-query`는 직접 의존성으로 포함되어 있어 별도 설치가 필요 없습니다.
+> Firebase를 사용하는 경우 `firebase`를 별도로 설치하세요 (선택적 peer dependency).
+
+---
+
+## Type Imports
+
+SDK에서 사용하는 모든 타입은 `@ph-cms/client-sdk`에서 직접 import할 수 있습니다.
+`@ph-cms/api-contract`를 직접 참조할 필요 없이 SDK 하나로 모든 타입을 가져올 수 있습니다.
+
+```ts
+// SDK 내부 타입
+import type {
+  AuthProvider,
+  AuthStatus,
+  JwtPayload,
+  PHCMSClientConfig,
+  PHCMSContextType,
+  PHCMSProviderProps,
+  UseFirebaseAuthSyncOptions,
+  UseFirebaseAuthSyncReturn,
+  FirebaseAuthSyncProps,
+} from '@ph-cms/client-sdk';
+
+// API 도메인 타입 (api-contract에서 re-export)
+import type {
+  // Auth
+  LoginRequest,
+  RegisterRequest,
+  RefreshTokenRequest,
+  FirebaseExchangeRequest,
+  AuthResponse,
+
+  // User
+  UserDto,
+
+  // Channel
+  ChannelDto,
+  CreateChannelDto,
+  ListChannelQuery,
+  CheckHierarchyQuery,
+  PagedChannelListResponse,
+
+  // Content
+  ContentDto,
+  ContentMediaDto,
+  CreateContentRequest,
+  UpdateContentRequest,
+  ListContentQuery,
+  PagedContentListResponse,
+
+  // Hierarchy / Policy
+  HierarchySetDto,
+  PermissionPolicySetDto,
+
+  // Terms
+  TermDto,
+  ListTermsQuery,
+  PagedTermListResponse,
+
+  // Geo
+  GeoJSON,
+  BoundsQuery,
+
+  // Media
+  MediaUploadTicketRequest,
+  MediaUploadTicketResponse,
+  MediaUploadTicketBatchRequest,
+  MediaUploadTicketBatchResponse,
+
+  // Common
+  PagedResponse,
+} from '@ph-cms/client-sdk';
+```
+
+타입들은 `src/types.ts`에 도메인별로 정리되어 있으므로, IDE의 자동완성에서 바로 확인할 수 있습니다.
 
 ---
 
@@ -25,46 +101,24 @@ npm install @ph-cms/client-sdk
 
 ### Overview
 
-The SDK's authentication system is composed of three layers:
+SDK의 인증 시스템은 세 개의 레이어로 구성됩니다:
 
 | Layer | Component | Role |
 |---|---|---|
-| **Provider** | `LocalAuthProvider` / `FirebaseAuthProvider` | 토큰 저장·조회·삭제를 담당하는 저수준 어댑터 |
+| **Provider** | `LocalAuthProvider` / `FirebaseAuthProvider` | 토큰 저장·조회·갱신·삭제를 담당하는 저수준 어댑터 |
 | **Module** | `AuthModule` (`client.auth`) | 서버 API 호출 (`login`, `loginWithFirebase`, `me`, `refresh`, `logout`) |
-| **Hook / Context** | `PHCMSProvider`, `useAuth` | React 상태 관리 — 토큰 유무에 따른 조건부 프로필 조회, 로그인·로그아웃 액션 |
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  React Component Tree                                   │
-│                                                         │
-│  PHCMSProvider                                          │
-│   └─ PHCMSInternalProvider                              │
-│       ├─ useQuery(['auth','me'])                        │
-│       │    enabled: authProvider.hasToken()              │
-│       │    → 토큰 없으면 호출하지 않음 (401 방지)       │
-│       │    → 토큰 있으면 자동으로 me() 호출             │
-│       └─ context value: { user, isAuthenticated, ... }  │
-│                                                         │
-│  useAuth()                                              │
-│   ├─ login()  ──→ AuthModule.login()                    │
-│   │               ├─ POST /api/auth/login               │
-│   │               └─ provider.setTokens()               │
-│   │            ──→ refetchQueries(['auth','me'])         │
-│   │               └─ GET /api/auth/me  ← 프로필 보장    │
-│   │                                                     │
-│   ├─ loginWithFirebase()  ──→ AuthModule.loginWithFirebase() │
-│   │               ├─ POST /api/auth/firebase/exchange   │
-│   │               └─ provider.setTokens()               │
-│   │            ──→ refetchQueries(['auth','me'])         │
-│   │               └─ GET /api/auth/me  ← 프로필 보장    │
-│   │                                                     │
-│   ├─ register()  ──→ AuthModule.register()              │
-│   │            ──→ refetchQueries(['auth','me'])         │
-│   │                                                     │
-│   └─ logout()  ──→ AuthModule.logout()                  │
-│                ──→ setQueryData(['auth','me'], null)     │
-└─────────────────────────────────────────────────────────┘
-```
+| **Hook / Context** | `PHCMSProvider`, `useAuth` | React 상태 관리 — `authStatus`, 로그인·로그아웃 액션 |
+
+**PHCMSProvider** — `useQuery(['auth','me'])`를 `authProvider.hasToken()`이 `true`일 때만 실행하여 불필요한 401을 방지하고, context로 `{ user, authStatus, hasToken, ... }`을 제공합니다.
+
+**useAuth()** — 각 액션은 서버 호출 → `provider.setTokens()` → `refreshUser()`(= `me()` 재조회) 순서로 동작합니다:
+
+| 액션 | 서버 호출 | 후속 동작 |
+|---|---|---|
+| `login()` | `POST /api/auth/login` | `setTokens()` → `refreshUser()` |
+| `loginWithFirebase()` | `POST /api/auth/firebase/exchange` | `setTokens()` → `refreshUser()` |
+| `register()` | `POST /api/auth/register` | `setTokens()` → `refreshUser()` |
+| `logout()` | `POST /api/auth/logout` | `provider.logout()` → `refreshUser()` (상태 초기화) |
 
 ### Authentication Lifecycle
 
@@ -75,7 +129,7 @@ App Mount
   → PHCMSProvider mount
     → authProvider.hasToken()  ← false (localStorage에 토큰 없음)
     → useQuery enabled: false  ← me() 호출하지 않음
-    → user: null, isAuthenticated: false
+    → authStatus: 'unauthenticated'
 ```
 
 서버에 불필요한 401 요청을 보내지 않습니다.
@@ -86,62 +140,79 @@ App Mount
 App Mount
   → PHCMSProvider mount
     → authProvider.hasToken()  ← true (localStorage에 토큰 존재)
-    → useQuery enabled: true   ← me() 자동 호출
+    → useQuery enabled: true
+    → authStatus: 'loading'    ← 이 시점에 스플래시 화면 표시 가능
     → GET /api/auth/me
-    → user: { ... }, isAuthenticated: true
+    → authStatus: 'authenticated', user: { ... }
 ```
 
-페이지 새로고침이나 재방문 시 기존 세션이 자동으로 복원됩니다.
-
 #### 3. 로그인 (이메일/비밀번호)
 
 ```
 user calls login({ email, password })
   → POST /api/auth/login
-  → 서버 응답: { accessToken, refreshToken }
-  → provider.setTokens(accessToken, refreshToken)  ← localStorage 저장
-  → refetchQueries(['auth', 'me'])
+  → provider.setTokens(accessToken, refreshToken)
+  → refreshUser()
     → GET /api/auth/me
-    → user: { ... }, isAuthenticated: true
+    → authStatus: 'authenticated', user: { ... }
 ```
 
-#### 4. 로그인 (Firebase)
+#### 4. 로그아웃
 
 ```
-user calls loginWithFirebase({ idToken })
-  → POST /api/auth/firebase/exchange
-  → 서버 응답: { accessToken, refreshToken }
-  → provider.setTokens(accessToken, refreshToken)  ← localStorage 저장
-  → refetchQueries(['auth', 'me'])
-    → GET /api/auth/me
-    → user: { ... }, isAuthenticated: true
+user calls logout()
+  → provider.logout()           ← localStorage 토큰 삭제
+  → POST /api/auth/logout       ← 서버 세션 무효화 (실패해도 무시)
+  → refreshUser()
+    → hasToken: false → queryData 초기화
+    → authStatus: 'unauthenticated', user: null
 ```
 
-Firebase ID 토큰을 PH-CMS 자체 토큰으로 교환한 뒤, 동일한 프로필 조회 흐름을 따릅니다.
+### Token Refresh (자동 토큰 갱신)
+
+SDK는 두 가지 방식으로 토큰을 자동 갱신합니다:
 
-#### 5. 로그아웃
+#### Proactive Refresh (사전 갱신)
+
+Provider의 `getToken()` 호출 시 JWT의 `exp` 클레임을 검사합니다.
+만료 임박 시 (`expiryBufferMs` 이내, 기본 60초) 서버에 갱신 요청을 보냅니다.
 
 ```
-user calls logout()
-  → provider.logout()           ← localStorage 토큰 삭제
-  → POST /api/auth/logout       ← 서버 세션 무효화 (실패해도 무시)
-  → setQueryData(['auth','me'], null)
-  → user: null, isAuthenticated: false
+Request Interceptor
+  → provider.getToken()
+    → JWT exp 검사: 만료 임박?
+      → Yes: tryRefresh() → POST /api/auth/refresh
+              → 새 토큰 저장 → 새 accessToken 반환
+      → No:  기존 accessToken 반환
+  → Authorization: Bearer {token}
 ```
 
-### `refetchQueries` vs `invalidateQueries`
+#### Reactive Refresh (401 대응 갱신)
 
-로그인 성공 후 프로필 조회에는 `invalidateQueries` 대신 `refetchQueries`를 사용합니다.
+서버가 401을 반환하면 interceptor가 자동으로 토큰을 갱신하고 원본 요청을 재시도합니다.
 
-- `invalidateQueries`는 쿼리를 stale로 표시만 하고, `enabled: true`인 쿼리만 자동 refetch합니다.
-- 로그인 직후에는 `provider.setTokens()`로 토큰이 저장되지만, React 리렌더가 아직 발생하지 않아 `hasToken()`의 반환값이 context에 반영되지 않은 상태입니다.
-- 따라서 `enabled`가 여전히 `false`일 수 있고, `invalidateQueries`만으로는 `me()` 호출이 보장되지 않습니다.
-- `refetchQueries`는 `enabled` 상태와 무관하게 즉시 네트워크 요청을 강제하므로, 토큰 저장 직후 프로필 조회를 확실히 보장합니다.
+```
+API Request → 401 Unauthorized
+  → coordinatedRefresh(refreshToken)
+    → POST /api/auth/refresh (with _skipAuth flag)
+    → 성공: provider.setTokens() → 원본 요청 재시도
+    → 실패: ApiError throw
+```
+
+**동시 요청 처리:** 여러 요청이 동시에 401을 받으면 하나의 refresh 요청만 실행되고,
+나머지 요청은 큐에서 대기합니다 (de-duplication).
+
+**순환 방지:** refresh 요청 자체는 `_skipAuth` 플래그가 붙어 request interceptor에서
+토큰 첨부를 건너뛰므로, `getToken()` → `tryRefresh()` 재귀 호출이 발생하지 않습니다.
 
 ---
 
 ## Auth Providers
 
+모든 Provider는 `BaseAuthProvider` 추상 클래스를 상속합니다.
+공통 로직(토큰 저장, 갱신, de-duplication, localStorage 관리)은 `BaseAuthProvider`에 구현되어 있고,
+각 Provider는 `getToken()`과 `logout()` 등 고유 로직만 오버라이드합니다.
+
 ### `LocalAuthProvider`
 
 이메일/비밀번호 기반 인증에 사용합니다. 토큰을 `localStorage`에 저장합니다.
@@ -149,7 +220,9 @@ user calls logout()
 ```ts
 import { LocalAuthProvider, PHCMSClient } from '@ph-cms/client-sdk';
 
-const authProvider = new LocalAuthProvider('my_app_');
+const authProvider = new LocalAuthProvider('my_app_', {
+  expiryBufferMs: 60_000, // 선택 — 만료 60초 전부터 갱신 시도 (기본값)
+});
 
 const client = new PHCMSClient({
   baseURL: 'https://api.example.com',
@@ -159,21 +232,12 @@ const client = new PHCMSClient({
 
 | 생성자 인자 | 타입 | 기본값 | 설명 |
 |---|---|---|---|
-| `storageKeyPrefix` | `string` | `'ph_cms_'` | `localStorage` 키 접두사. `{prefix}access_token`, `{prefix}refresh_token` 형태로 저장됩니다. |
-
-#### 주요 메서드
-
-| 메서드 | 설명 |
-|---|---|
-| `hasToken()` | `accessToken` 또는 `refreshToken`이 존재하면 `true` 반환 |
-| `getToken()` | 현재 `accessToken` 반환 (`Promise<string \| null>`) |
-| `setTokens(access, refresh)` | 토큰 저장 (login 성공 시 SDK가 자동 호출) |
-| `getRefreshToken()` | 현재 `refreshToken` 반환 |
-| `logout()` | 토큰 삭제 |
+| `storageKeyPrefix` | `string` | `'ph_cms_'` | `localStorage` 키 접두사 (`{prefix}access_token`, `{prefix}refresh_token`) |
+| `options.expiryBufferMs` | `number` | `60_000` | 만료 몇 ms 전부터 토큰을 갱신할지 |
 
 ### `FirebaseAuthProvider`
 
-Firebase Authentication과 연동하여 사용합니다. Firebase ID 토큰을 PH-CMS 서버 토큰으로 교환하는 방식입니다.
+Firebase Authentication과 연동합니다. PH-CMS 토큰이 없으면 Firebase ID 토큰으로 fallback합니다.
 
 ```ts
 import { FirebaseAuthProvider, PHCMSClient } from '@ph-cms/client-sdk';
@@ -183,7 +247,9 @@ import { getAuth } from 'firebase/auth';
 const firebaseApp = initializeApp({ /* Firebase config */ });
 const firebaseAuth = getAuth(firebaseApp);
 
-const authProvider = new FirebaseAuthProvider(firebaseAuth, 'my_app_fb_');
+const authProvider = new FirebaseAuthProvider(firebaseAuth, 'my_app_fb_', {
+  expiryBufferMs: 60_000,
+});
 
 const client = new PHCMSClient({
   baseURL: 'https://api.example.com',
@@ -195,32 +261,41 @@ const client = new PHCMSClient({
 |---|---|---|---|
 | `auth` | `firebase/auth.Auth` | (필수) | Firebase Auth 인스턴스 |
 | `storageKeyPrefix` | `string` | `'ph_cms_fb_'` | `localStorage` 키 접두사 |
+| `options.expiryBufferMs` | `number` | `60_000` | 만료 몇 ms 전부터 토큰을 갱신할지 |
 
-#### 주요 메서드
+**`getToken()` 동작:**
 
-| 메서드 | 설명 |
-|---|---|
-| `hasToken()` | PH-CMS 교환 토큰이 존재하면 `true` 반환 |
-| `getToken()` | PH-CMS `accessToken` → Firebase ID 토큰 순으로 fallback 반환 |
-| `getIdToken()` | Firebase ID 토큰을 직접 반환 (토큰 교환 시 사용) |
-| `setTokens(access, refresh)` | 교환된 PH-CMS 토큰 저장 (SDK가 자동 호출) |
-| `logout()` | PH-CMS 토큰 삭제 + `firebase.auth.signOut()` 호출 |
+1. PH-CMS access token이 유효하면 → 그대로 반환
+2. 만료 임박이면 → `tryRefresh()` 시도 → 성공하면 새 토큰 반환
+3. PH-CMS 토큰이 없거나 갱신 실패 → Firebase ID 토큰으로 fallback
 
 ### `AuthProvider` Interface
 
-커스텀 인증 프로바이더를 구현하려면 아래 인터페이스를 구현합니다:
+커스텀 인증 Provider를 구현하려면 아래 인터페이스를 따릅니다.
+`BaseAuthProvider`를 상속하면 대부분의 메서드가 이미 구현되어 있으므로, `type`과 `getToken()`만 구현하면 됩니다.
 
 ```ts
 interface AuthProvider {
   type: 'FIREBASE' | 'LOCAL';
   getToken(): Promise<string | null>;
   hasToken(): boolean;
+  getRefreshToken(): string | null;
+  setRefreshFn(fn: (refreshToken: string) => Promise<{ accessToken: string; refreshToken: string }>): void;
+  setTokens(accessToken: string, refreshToken: string): void;
   onTokenExpired(callback: () => Promise<void>): void;
   logout(): Promise<void>;
 }
 ```
 
-`hasToken()`은 **동기** 메서드여야 합니다. React 렌더 사이클에서 `useQuery`의 `enabled` 조건으로 사용되므로, 비동기 호출은 허용되지 않습니다.
+| 메서드 | 설명 |
+|---|---|
+| `hasToken()` | 토큰 존재 여부 (동기). React의 `useQuery` `enabled` 조건에 사용되므로 반드시 동기여야 합니다 |
+| `getToken()` | 유효한 access token 반환. 만료 시 자동 갱신 시도 후 반환 |
+| `getRefreshToken()` | 현재 refresh token 반환 |
+| `setRefreshFn(fn)` | `PHCMSClient`가 생성 시 호출. Provider가 자체적으로 토큰을 갱신할 수 있게 함 |
+| `setTokens(access, refresh)` | 새 토큰 쌍 저장 (login/refresh 성공 시 자동 호출) |
+| `onTokenExpired(callback)` | 토큰 만료 + 갱신 실패 시 호출할 콜백 등록 |
+| `logout()` | 세션 정리 (토큰 삭제) |
 
 ---
 
@@ -247,7 +322,7 @@ export function App() {
 }
 ```
 
-`PHCMSProvider`는 내부적으로 `QueryClientProvider`를 포함하므로, 별도로 추가할 필요가 없습니다.
+`PHCMSProvider`는 내부적으로 `QueryClientProvider`를 포함합니다.
 외부에서 직접 관리하는 `QueryClient`를 사용하려면 `queryClient` prop으로 전달합니다:
 
 ```tsx
@@ -260,6 +335,39 @@ const queryClient = new QueryClient();
 </PHCMSProvider>
 ```
 
+### Authentication Status (`authStatus`)
+
+Context는 세분화된 인증 상태를 `authStatus`로 제공합니다:
+
+| `authStatus` | `hasToken` | `user` | 의미 |
+|---|---|---|---|
+| `'unauthenticated'` | `false` | `null` | 미로그인 (토큰 없음) → 로그인 화면 표시 |
+| `'loading'` | `true` | `null` | 세션 복원 중 (`me()` 호출 중) → 스플래시 화면 표시 |
+| `'authenticated'` | `true` | `UserDto` | 인증 완료 → 메인 화면 표시 |
+| `'unauthenticated'` | `true` | `null` | 토큰 있으나 `me()` 실패 → 재로그인 유도 |
+
+```tsx
+import { usePHCMSContext } from '@ph-cms/client-sdk';
+
+function AppRouter() {
+  const { authStatus, hasToken } = usePHCMSContext();
+
+  switch (authStatus) {
+    case 'loading':
+      return <SplashScreen />;
+    case 'authenticated':
+      return <MainApp />;
+    case 'unauthenticated':
+      // hasToken이 true이면 토큰은 있었으나 만료/검증 실패
+      if (hasToken) return <SessionExpiredScreen />;
+      return <LoginScreen />;
+  }
+}
+```
+
+> `isAuthenticated`와 `isLoading`은 하위 호환을 위해 유지되지만,
+> 내부적으로 `authStatus`에서 파생됩니다 (`isAuthenticated === authStatus === 'authenticated'`).
+
 ### Authentication with `useAuth`
 
 `useAuth`는 인증 상태와 액션을 통합 제공하는 메인 훅입니다.
@@ -270,9 +378,9 @@ import { useAuth } from '@ph-cms/client-sdk';
 function AuthComponent() {
   const {
     // 상태
-    user,              // UserDto | null — 현재 로그인한 사용자 프로필
+    user,              // UserDto | null
     isAuthenticated,   // boolean
-    isLoading,         // boolean — 프로필 로딩 중 여부
+    isLoading,         // boolean
 
     // 액션 (모두 Promise 반환)
     login,             // (data: LoginRequest) => Promise<AuthResponse>
@@ -286,8 +394,6 @@ function AuthComponent() {
     registerStatus,
     logoutStatus,
   } = useAuth();
-
-  // ...
 }
 ```
 
@@ -300,14 +406,14 @@ function LoginForm() {
   const [password, setPassword] = useState('');
 
   if (isAuthenticated) {
-    return <p>Welcome, {user?.displayName}</p>;
+    return <p>Welcome, {user?.display_name}</p>;
   }
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
     try {
       await login({ email, password });
-      // 성공 시 자동으로 me() 호출 → user, isAuthenticated 갱신
+      // 성공 → 자동으로 me() 호출 → user, isAuthenticated 갱신
     } catch (error) {
       console.error('Login failed:', error);
     }
@@ -329,30 +435,22 @@ function LoginForm() {
 #### Firebase 로그인
 
 Firebase 로그인은 두 단계로 이루어집니다:
-1. Firebase SDK로 인증하여 ID 토큰을 획득
-2. `loginWithFirebase()`로 PH-CMS 서버에 토큰 교환 요청
+1. Firebase SDK로 인증하여 ID 토큰 획득
+2. `loginWithFirebase()`로 PH-CMS 서버에 토큰 교환
 
 ```tsx
-import { FirebaseAuthProvider } from '@ph-cms/client-sdk';
 import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';
 
-// firebaseProvider는 앱 초기화 시 생성
-declare const firebaseProvider: FirebaseAuthProvider;
-
 function FirebaseLoginButton() {
   const { loginWithFirebase, loginWithFirebaseStatus } = useAuth();
 
   const handleFirebaseLogin = async () => {
-    // 1) Firebase 인증 (Google 팝업 예시)
     const auth = getAuth();
-    await signInWithPopup(auth, new GoogleAuthProvider());
+    const result = await signInWithPopup(auth, new GoogleAuthProvider());
+    const idToken = await result.user.getIdToken();
 
-    // 2) Firebase ID 토큰 획득
-    const idToken = await firebaseProvider.getIdToken();
-    if (!idToken) return;
-
-    // 3) PH-CMS 서버에 토큰 교환 → 자동으로 me() 호출
     await loginWithFirebase({ idToken });
+    // 성공 → 자동으로 me() 호출 → 인증 상태 갱신
   };
 
   return (
@@ -376,7 +474,7 @@ function RegisterForm() {
     username?: string;
   }) => {
     await register(formData);
-    // 성공 시 자동으로 me() 호출 → 즉시 인증 상태로 전환
+    // 성공 → 자동으로 me() 호출 → 즉시 인증 상태로 전환
   };
 
   // ...
@@ -406,20 +504,21 @@ function MyComponent() {
     user,            // UserDto | null
     isAuthenticated, // boolean
     isLoading,       // boolean
+    authStatus,      // 'loading' | 'authenticated' | 'unauthenticated'
+    hasToken,        // boolean — Provider에 토큰이 존재하는지
     refreshUser,     // () => Promise<void> — 수동으로 프로필 다시 조회
   } = usePHCMSContext();
 
-  // 프로필 정보가 변경된 후 수동 갱신
   const handleProfileUpdate = async () => {
-    await client.auth.me(); // or your update API
-    await refreshUser();
+    // 프로필 수정 API 호출 후
+    await refreshUser(); // context 갱신
   };
 }
 ```
 
 ### Standalone (Non-React) Usage
 
-React 없이 `PHCMSClient`와 `AuthModule`을 직접 사용할 수 있습니다.
+React 없이 `PHCMSClient`를 직접 사용할 수 있습니다.
 
 ```ts
 import { PHCMSClient, LocalAuthProvider } from '@ph-cms/client-sdk';
@@ -430,18 +529,18 @@ const client = new PHCMSClient({
   auth: authProvider,
 });
 
-// 로그인
+// 로그인 — provider에 토큰이 자동 저장됨
 const authResponse = await client.auth.login({
   email: 'user@example.com',
   password: 'password',
 });
-// → authProvider에 토큰이 자동 저장됨
 
 // 프로필 조회
 const me = await client.auth.me();
 console.log(me.email);
 
-// 토큰 갱신
+// 토큰 갱신 (수동)
+// 일반적으로 SDK가 자동으로 처리하지만, 필요 시 직접 호출 가능
 const refreshToken = authProvider.getRefreshToken();
 if (refreshToken) {
   const newTokens = await client.auth.refresh(refreshToken);
@@ -462,6 +561,122 @@ await client.auth.logout();
 | `useLogin()` | `{ mutateAsync: login }` |
 | `useLogout()` | `{ mutateAsync: logout }` |
 
+### Firebase Auth Sync
+
+Firebase 인증 상태가 변경될 때 PH-CMS 백엔드와 자동으로 동기화할 수 있습니다.
+
+| 방식 | 용도 |
+|---|---|
+| `useFirebaseAuthSync` 훅 | 기존 컴포넌트에 동기화 로직을 삽입할 때 |
+| `<FirebaseAuthSync>` 컴포넌트 | 컴포넌트 트리를 감싸서 선언적으로 사용할 때 |
+
+#### 동기화 동작
+
+```
+Firebase onAuthStateChanged
+  │
+  ├─ fbUser 존재 + PH-CMS 비인증 상태
+  │   → fbUser.getIdToken()
+  │   → client.auth.loginWithFirebase({ idToken })
+  │   → provider.setTokens(...)
+  │   → refreshUser()  ← me() 호출하여 프로필 로드
+  │
+  └─ fbUser null (로그아웃) + PH-CMS 인증 상태
+      → client.auth.logout()
+      → refreshUser()  ← 상태 초기화
+```
+
+#### `<FirebaseAuthSync>` 컴포넌트
+
+`<PHCMSProvider>` 안에서 사용합니다:
+
+```tsx
+import { PHCMSProvider, FirebaseAuthSync } from '@ph-cms/client-sdk';
+import { getAuth } from 'firebase/auth';
+
+const firebaseAuth = getAuth(firebaseApp);
+
+function App() {
+  return (
+    <PHCMSProvider client={client}>
+      <FirebaseAuthSync firebaseAuth={firebaseAuth}>
+        <MainContent />
+      </FirebaseAuthSync>
+    </PHCMSProvider>
+  );
+}
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `firebaseAuth` | `firebase/auth.Auth` | (필수) | Firebase Auth 인스턴스 |
+| `logoutOnFirebaseSignOut` | `boolean` | `true` | Firebase 로그아웃 시 PH-CMS도 자동 로그아웃할지 |
+| `onSyncSuccess` | `() => void` | — | 토큰 교환 성공 시 콜백 |
+| `onSyncError` | `(error: unknown) => void` | — | 토큰 교환 실패 시 콜백 |
+
+#### `useFirebaseAuthSync` 훅
+
+```tsx
+import { useFirebaseAuthSync } from '@ph-cms/client-sdk';
+import { getAuth } from 'firebase/auth';
+
+const firebaseAuth = getAuth(firebaseApp);
+
+function AppContent() {
+  const { isSyncing } = useFirebaseAuthSync({
+    firebaseAuth,
+    onSyncSuccess: () => console.log('Firebase↔PH-CMS 동기화 완료'),
+    onSyncError: (err) => console.error('동기화 실패:', err),
+  });
+
+  if (isSyncing) return <div>인증 동기화 중...</div>;
+
+  return <MainContent />;
+}
+```
+
+#### 전체 구성 예시 (Firebase)
+
+```tsx
+import {
+  PHCMSClient,
+  FirebaseAuthProvider,
+  PHCMSProvider,
+  FirebaseAuthSync,
+} from '@ph-cms/client-sdk';
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+
+const firebaseApp = initializeApp({ /* config */ });
+const firebaseAuth = getAuth(firebaseApp);
+
+const authProvider = new FirebaseAuthProvider(firebaseAuth, 'my_app_fb_');
+
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
+});
+
+function App() {
+  return (
+    <PHCMSProvider client={client}>
+      <FirebaseAuthSync
+        firebaseAuth={firebaseAuth}
+        onSyncError={(err) => alert('인증 동기화에 실패했습니다.')}
+      >
+        <Router />
+      </FirebaseAuthSync>
+    </PHCMSProvider>
+  );
+}
+```
+
+이 구성에서는:
+- Firebase 로그인 시 `FirebaseAuthSync`가 자동으로 PH-CMS 토큰 교환 + 프로필 조회를 수행
+- Firebase 로그아웃 시 PH-CMS 세션도 자동 정리
+- 앱 재방문 시 localStorage 토큰으로 세션 자동 복원
+- 토큰 만료 시 자동 갱신 (proactive + reactive)
+
 ---
 
 ## Using Data Hooks
@@ -501,9 +716,7 @@ function ChannelList() {
 
 ## Media & File Upload
 
-Uploading media files follows a 3-step process: Request a Ticket → Upload to S3 → Create/Update Content.
-
-### Simple Workflow Example
+미디어 업로드는 3단계로 진행됩니다: Ticket 발급 → S3 업로드 → Content 생성/수정.
 
 ```tsx
 import { useMediaUploadTickets, useUploadToS3, useCreateContent } from '@ph-cms/client-sdk';
@@ -517,7 +730,7 @@ function MediaUploader() {
     const file = event.target.files?.[0];
     if (!file) return;
 
-    // Step 1: Get Upload Ticket (Presigned URL)
+    // Step 1: Upload Ticket 발급 (Presigned URL)
     const tickets = await getTickets([{
       filename: file.name,
       contentType: file.type,
@@ -526,14 +739,14 @@ function MediaUploader() {
 
     const { mediaUid, uploadUrl } = tickets[0];
 
-    // Step 2: Upload File directly to S3
+    // Step 2: S3에 파일 직접 업로드
     await uploadToS3({ url: uploadUrl, file });
 
-    // Step 3: Use the mediaUid to create content
+    // Step 3: mediaUid로 Content 생성
     await createContent({
       type: 'post',
       title: 'Post with image',
-      mediaAttachments: [mediaUid]
+      mediaAttachments: [mediaUid],
     });
   };
 
@@ -581,7 +794,7 @@ const client = new PHCMSClient({
   timeout?: number;      // 요청 타임아웃 ms (기본값: 10000)
 });
 
-client.authProvider   // AuthProvider | undefined — 인증 프로바이더 접근
+client.authProvider   // AuthProvider | undefined
 client.axiosInstance  // AxiosInstance — 내부 axios 인스턴스 직접 접근
 client.auth           // AuthModule
 client.content        // ContentModule
@@ -601,6 +814,24 @@ client.media          // MediaModule
 | `refresh(refreshToken: string)` | 토큰 갱신 → `{ accessToken, refreshToken }` |
 | `logout()` | 로그아웃 (프로바이더 토큰 삭제 + 서버 세션 무효화) |
 
+### JWT Utilities
+
+클라이언트에서 토큰 상태를 확인할 수 있는 유틸리티입니다 (서명 검증은 하지 않음).
+
+```ts
+import {
+  decodeJwtPayload,
+  getTokenExpirationMs,
+  isTokenExpired,
+  getTokenTTL,
+} from '@ph-cms/client-sdk';
+
+const payload = decodeJwtPayload(token);   // JwtPayload | null
+const expiresAt = getTokenExpirationMs(token); // number (ms) | null
+const expired = isTokenExpired(token, 60_000); // boolean | null
+const ttl = getTokenTTL(token);            // number (ms) | null
+```
+
 ---
 
 ## License