@ph-cms/client-sdk 0.1.4 → 0.1.6

package/README.md

@@ -9,6 +9,8 @@ This package provides:
 - 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)
+- **Firebase Auth State Sync** — automatic Firebase↔PH-CMS session synchronization (from v0.1.6)
 
 ## Installation
 
@@ -18,17 +20,223 @@ 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.
 
-## React Usage
+---
+
+## Authentication Architecture
+
+### Overview
+
+The SDK's authentication system is composed of three layers:
+
+| Layer | Component | Role |
+|---|---|---|
+| **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)     │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Authentication Lifecycle
+
+#### 1. 초기 마운트 (비인증 상태)
+
+```
+App Mount
+  → PHCMSProvider mount
+    → authProvider.hasToken()  ← false (localStorage에 토큰 없음)
+    → useQuery enabled: false  ← me() 호출하지 않음
+    → user: null, isAuthenticated: false
+```
+
+서버에 불필요한 401 요청을 보내지 않습니다.
+
+#### 2. 초기 마운트 (기존 세션 복원)
+
+```
+App Mount
+  → PHCMSProvider mount
+    → authProvider.hasToken()  ← true (localStorage에 토큰 존재)
+    → useQuery enabled: true   ← me() 자동 호출
+    → GET /api/auth/me
+    → user: { ... }, isAuthenticated: true
+```
+
+페이지 새로고침이나 재방문 시 기존 세션이 자동으로 복원됩니다.
+
+#### 3. 로그인 (이메일/비밀번호)
+
+```
+user calls login({ email, password })
+  → POST /api/auth/login
+  → 서버 응답: { accessToken, refreshToken }
+  → provider.setTokens(accessToken, refreshToken)  ← localStorage 저장
+  → refetchQueries(['auth', 'me'])
+    → GET /api/auth/me
+    → user: { ... }, isAuthenticated: true
+```
+
+#### 4. 로그인 (Firebase)
+
+```
+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
+```
+
+Firebase ID 토큰을 PH-CMS 자체 토큰으로 교환한 뒤, 동일한 프로필 조회 흐름을 따릅니다.
+
+#### 5. 로그아웃
+
+```
+user calls logout()
+  → provider.logout()           ← localStorage 토큰 삭제
+  → POST /api/auth/logout       ← 서버 세션 무효화 (실패해도 무시)
+  → setQueryData(['auth','me'], null)
+  → user: null, isAuthenticated: false
+```
+
+### `refetchQueries` vs `invalidateQueries`
+
+로그인 성공 후 프로필 조회에는 `invalidateQueries` 대신 `refetchQueries`를 사용합니다.
+
+- `invalidateQueries`는 쿼리를 stale로 표시만 하고, `enabled: true`인 쿼리만 자동 refetch합니다.
+- 로그인 직후에는 `provider.setTokens()`로 토큰이 저장되지만, React 리렌더가 아직 발생하지 않아 `hasToken()`의 반환값이 context에 반영되지 않은 상태입니다.
+- 따라서 `enabled`가 여전히 `false`일 수 있고, `invalidateQueries`만으로는 `me()` 호출이 보장되지 않습니다.
+- `refetchQueries`는 `enabled` 상태와 무관하게 즉시 네트워크 요청을 강제하므로, 토큰 저장 직후 프로필 조회를 확실히 보장합니다.
+
+---
+
+## Auth Providers
+
+### `LocalAuthProvider`
+
+이메일/비밀번호 기반 인증에 사용합니다. 토큰을 `localStorage`에 저장합니다.
+
+```ts
+import { LocalAuthProvider, PHCMSClient } from '@ph-cms/client-sdk';
+
+const authProvider = new LocalAuthProvider('my_app_');
+
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
+});
+```
+
+| 생성자 인자 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `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()` | 토큰 삭제 |
+
+### `FirebaseAuthProvider`
+
+Firebase Authentication과 연동하여 사용합니다. Firebase ID 토큰을 PH-CMS 서버 토큰으로 교환하는 방식입니다.
+
+```ts
+import { FirebaseAuthProvider, PHCMSClient } from '@ph-cms/client-sdk';
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+
+const firebaseApp = initializeApp({ /* Firebase config */ });
+const firebaseAuth = getAuth(firebaseApp);
+
+const authProvider = new FirebaseAuthProvider(firebaseAuth, 'my_app_fb_');
 
-`PHCMSProvider` automatically includes a `QueryClientProvider` and manages the global authentication state.
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
+});
+```
+
+| 생성자 인자 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `auth` | `firebase/auth.Auth` | (필수) | Firebase Auth 인스턴스 |
+| `storageKeyPrefix` | `string` | `'ph_cms_fb_'` | `localStorage` 키 접두사 |
+
+#### 주요 메서드
+
+| 메서드 | 설명 |
+|---|---|
+| `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()` 호출 |
+
+### `AuthProvider` Interface
+
+커스텀 인증 프로바이더를 구현하려면 아래 인터페이스를 구현합니다:
+
+```ts
+interface AuthProvider {
+  type: 'FIREBASE' | 'LOCAL';
+  getToken(): Promise<string | null>;
+  hasToken(): boolean;
+  onTokenExpired(callback: () => Promise<void>): void;
+  logout(): Promise<void>;
+}
+```
+
+`hasToken()`은 **동기** 메서드여야 합니다. React 렌더 사이클에서 `useQuery`의 `enabled` 조건으로 사용되므로, 비동기 호출은 허용되지 않습니다.
+
+---
+
+## React Usage
 
 ### Basic Setup
 
 ```tsx
-import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
+import { PHCMSClient, LocalAuthProvider, PHCMSProvider } from '@ph-cms/client-sdk';
+
+const authProvider = new LocalAuthProvider('my_app_');
 
 const client = new PHCMSClient({
   baseURL: 'https://api.example.com',
+  auth: authProvider,
 });
 
 export function App() {
@@ -40,38 +248,350 @@ export function App() {
 }
 ```
 
-### Authentication State (`useAuth`)
+`PHCMSProvider`는 내부적으로 `QueryClientProvider`를 포함하므로, 별도로 추가할 필요가 없습니다.
+외부에서 직접 관리하는 `QueryClient`를 사용하려면 `queryClient` prop으로 전달합니다:
 
-From v0.1.3, the `useAuth` hook provides a unified interface for both authentication state and actions.
+```tsx
+import { QueryClient } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+<PHCMSProvider client={client} queryClient={queryClient}>
+  ...
+</PHCMSProvider>
+```
+
+### Authentication with `useAuth`
+
+`useAuth`는 인증 상태와 액션을 통합 제공하는 메인 훅입니다.
 
 ```tsx
 import { useAuth } from '@ph-cms/client-sdk';
 
-function ProfileComponent() {
-  const { 
-    user, 
-    isAuthenticated, 
-    isLoading, 
-    login, 
-    logout 
+function AuthComponent() {
+  const {
+    // 상태
+    user,              // UserDto | null — 현재 로그인한 사용자 프로필
+    isAuthenticated,   // boolean
+    isLoading,         // boolean — 프로필 로딩 중 여부
+
+    // 액션 (모두 Promise 반환)
+    login,             // (data: LoginRequest) => Promise<AuthResponse>
+    loginWithFirebase, // (data: FirebaseExchangeRequest) => Promise<AuthResponse>
+    register,          // (data: RegisterRequest) => Promise<AuthResponse>
+    logout,            // () => Promise<void>
+
+    // 뮤테이션 상태 (isPending, error 등)
+    loginStatus,
+    loginWithFirebaseStatus,
+    registerStatus,
+    logoutStatus,
   } = useAuth();
 
-  if (isLoading) return <div>Checking auth...</div>;
+  // ...
+}
+```
+
+#### 이메일/비밀번호 로그인
+
+```tsx
+function LoginForm() {
+  const { login, loginStatus, isAuthenticated, user } = useAuth();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
 
-  if (!isAuthenticated) {
-    return <button onClick={() => login({ email: '...', password: '...' })}>Login</button>;
+  if (isAuthenticated) {
+    return <p>Welcome, {user?.displayName}</p>;
   }
 
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    try {
+      await login({ email, password });
+      // 성공 시 자동으로 me() 호출 → user, isAuthenticated 갱신
+    } catch (error) {
+      console.error('Login failed:', error);
+    }
+  };
+
   return (
-    <div>
-      <h1>Welcome, {user?.display_name}</h1>
-      <button onClick={() => logout()}>Logout</button>
-    </div>
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={e => setEmail(e.target.value)} />
+      <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
+      <button type="submit" disabled={loginStatus.isPending}>
+        {loginStatus.isPending ? '로그인 중...' : '로그인'}
+      </button>
+      {loginStatus.error && <p>{(loginStatus.error as Error).message}</p>}
+    </form>
   );
 }
 ```
 
-### Using Data Hooks
+#### Firebase 로그인
+
+Firebase 로그인은 두 단계로 이루어집니다:
+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());
+
+    // 2) Firebase ID 토큰 획득
+    const idToken = await firebaseProvider.getIdToken();
+    if (!idToken) return;
+
+    // 3) PH-CMS 서버에 토큰 교환 → 자동으로 me() 호출
+    await loginWithFirebase({ idToken });
+  };
+
+  return (
+    <button onClick={handleFirebaseLogin} disabled={loginWithFirebaseStatus.isPending}>
+      {loginWithFirebaseStatus.isPending ? 'Firebase 로그인 중...' : 'Google 로그인'}
+    </button>
+  );
+}
+```
+
+#### 회원가입
+
+```tsx
+function RegisterForm() {
+  const { register, registerStatus } = useAuth();
+
+  const handleRegister = async (formData: {
+    email: string;
+    password: string;
+    display_name: string;
+    username?: string;
+  }) => {
+    await register(formData);
+    // 성공 시 자동으로 me() 호출 → 즉시 인증 상태로 전환
+  };
+
+  // ...
+}
+```
+
+#### 로그아웃
+
+```tsx
+function LogoutButton() {
+  const { logout } = useAuth();
+
+  return <button onClick={() => logout()}>로그아웃</button>;
+}
+```
+
+### Context API (`usePHCMSContext`)
+
+`useAuth` 대신 context에 직접 접근할 수도 있습니다.
+
+```tsx
+import { usePHCMSContext } from '@ph-cms/client-sdk';
+
+function MyComponent() {
+  const {
+    client,          // PHCMSClient 인스턴스
+    user,            // UserDto | null
+    isAuthenticated, // boolean
+    isLoading,       // boolean
+    refreshUser,     // () => Promise<void> — 수동으로 프로필 다시 조회
+  } = usePHCMSContext();
+
+  // 프로필 정보가 변경된 후 수동 갱신
+  const handleProfileUpdate = async () => {
+    await client.auth.me(); // or your update API
+    await refreshUser();
+  };
+}
+```
+
+### Standalone (Non-React) Usage
+
+React 없이 `PHCMSClient`와 `AuthModule`을 직접 사용할 수 있습니다.
+
+```ts
+import { PHCMSClient, LocalAuthProvider } from '@ph-cms/client-sdk';
+
+const authProvider = new LocalAuthProvider('my_app_');
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
+});
+
+// 로그인
+const authResponse = await client.auth.login({
+  email: 'user@example.com',
+  password: 'password',
+});
+// → authProvider에 토큰이 자동 저장됨
+
+// 프로필 조회
+const me = await client.auth.me();
+console.log(me.email);
+
+// 토큰 갱신
+const refreshToken = authProvider.getRefreshToken();
+if (refreshToken) {
+  const newTokens = await client.auth.refresh(refreshToken);
+  authProvider.setTokens(newTokens.accessToken, newTokens.refreshToken);
+}
+
+// 로그아웃
+await client.auth.logout();
+```
+
+### Legacy Hooks
+
+하위 호환성을 위해 개별 훅도 제공됩니다. 새 코드에서는 `useAuth`를 권장합니다.
+
+| Hook | 설명 |
+|---|---|
+| `useUser()` | `{ data: UserDto \| null, isLoading, isAuthenticated }` |
+| `useLogin()` | `{ mutateAsync: login }` |
+| `useLogout()` | `{ mutateAsync: logout }` |
+
+### Firebase Auth Sync
+
+Firebase Authentication을 사용하는 경우, Firebase의 인증 상태가 변경될 때마다 PH-CMS 백엔드와 자동으로 동기화할 수 있습니다.
+
+SDK는 두 가지 방식을 제공합니다:
+
+| 방식 | 용도 |
+|---|---|
+| `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>
+  );
+}
+```
+
+Props:
+
+| 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 />;
+}
+```
+
+반환값:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `isSyncing` | `boolean` | 토큰 교환 요청이 진행 중인지 여부 |
+
+#### 전체 구성 예시 (Firebase + LocalAuthProvider)
+
+```tsx
+import { PHCMSClient, LocalAuthProvider, FirebaseAuthProvider, PHCMSProvider, FirebaseAuthSync } from '@ph-cms/client-sdk';
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+
+// 1. Firebase 초기화
+const firebaseApp = initializeApp({ /* config */ });
+const firebaseAuth = getAuth(firebaseApp);
+
+// 2. PH-CMS 프로바이더 (Firebase 타입)
+const authProvider = new FirebaseAuthProvider(firebaseAuth, 'my_app_');
+
+// 3. PH-CMS 클라이언트
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
+});
+
+// 4. 앱 구성
+function App() {
+  return (
+    <PHCMSProvider client={client}>
+      <FirebaseAuthSync
+        firebaseAuth={firebaseAuth}
+        onSyncError={(err) => alert('인증 동기화에 실패했습니다.')}
+      >
+        <Router />
+      </FirebaseAuthSync>
+    </PHCMSProvider>
+  );
+}
+```
+
+이 구성에서는:
+- 사용자가 Firebase (예: Google 로그인)로 인증하면, `FirebaseAuthSync`가 자동으로 PH-CMS 토큰 교환 + 프로필 조회를 수행합니다.
+- 사용자가 Firebase에서 로그아웃하면, PH-CMS 세션도 자동으로 정리됩니다.
+- 앱 재방문 시 localStorage에 토큰이 남아있으면 `PHCMSProvider`가 자동으로 `me()`를 호출하여 세션을 복원합니다.
+
+---
+
+## Using Data Hooks
+
+### Content
 
 ```tsx
 import { useContentList, useContentDetail } from '@ph-cms/client-sdk';
@@ -91,9 +611,22 @@ function ContentList() {
 }
 ```
 
+### Channel
+
+```tsx
+import { useChannelList } from '@ph-cms/client-sdk';
+
+function ChannelList() {
+  const { data, isLoading } = useChannelList({ limit: 20 });
+  // ...
+}
+```
+
+---
+
 ## Media & File Upload
 
-Uploading media files follows a 3-step process: Request a Ticket -> Upload to S3 -> Create/Update Content.
+Uploading media files follows a 3-step process: Request a Ticket → Upload to S3 → Create/Update Content.
 
 ### Simple Workflow Example
 
@@ -133,6 +666,68 @@ function MediaUploader() {
 }
 ```
 
+---
+
+## Error Handling
+
+SDK는 세 종류의 에러를 throw합니다:
+
+| Error Class | 상황 | 주요 필드 |
+|---|---|---|
+| `ValidationError` | Zod 스키마 검증 실패 (클라이언트 측) | `errors: ZodIssue[]` |
+| `ApiError` | 서버가 2xx 이외의 응답을 반환 | `statusCode: number`, `originalError: any` |
+| `PHCMSError` | 네트워크 오류 등 기타 에러 | `message: string` |
+
+```tsx
+import { ApiError } from '@ph-cms/client-sdk';
+
+try {
+  await login({ email, password });
+} catch (error) {
+  if (error instanceof ApiError) {
+    if (error.statusCode === 401) {
+      console.error('잘못된 인증 정보입니다.');
+    }
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `PHCMSClient`
+
+```ts
+const client = new PHCMSClient({
+  baseURL: string;       // 서버 URL (필수)
+  apiPrefix?: string;    // API 경로 접두사 (기본값: '/api')
+  auth?: AuthProvider;   // 인증 프로바이더
+  timeout?: number;      // 요청 타임아웃 ms (기본값: 10000)
+});
+
+client.authProvider   // AuthProvider | undefined — 인증 프로바이더 접근
+client.axiosInstance  // AxiosInstance — 내부 axios 인스턴스 직접 접근
+client.auth           // AuthModule
+client.content        // ContentModule
+client.channel        // ChannelModule
+client.terms          // TermsModule
+client.media          // MediaModule
+```
+
+### `AuthModule` (`client.auth`)
+
+| 메서드 | 설명 |
+|---|---|
+| `login(data: LoginRequest)` | 이메일/비밀번호 로그인 → `AuthResponse` |
+| `loginWithFirebase(data: FirebaseExchangeRequest)` | Firebase ID 토큰 교환 → `AuthResponse` |
+| `register(data: RegisterRequest)` | 회원가입 → `AuthResponse` |
+| `me()` | 현재 사용자 프로필 조회 → `UserDto` |
+| `refresh(refreshToken: string)` | 토큰 갱신 → `{ accessToken, refreshToken }` |
+| `logout()` | 로그아웃 (프로바이더 토큰 삭제 + 서버 세션 무효화) |
+
+---
+
 ## License
 
-MIT
+MIT

package/dist/auth/firebase-provider.d.ts

@@ -1,5 +1,5 @@
-import { AuthProvider } from "./interfaces";
 import type { Auth } from "firebase/auth";
+import { AuthProvider } from "./interfaces";
 export declare class FirebaseAuthProvider implements AuthProvider {
     private readonly auth;
     private readonly storageKeyPrefix;
@@ -8,6 +8,7 @@ export declare class FirebaseAuthProvider implements AuthProvider {
     private refreshToken;
     private onExpiredCallback;
     constructor(auth: Auth, storageKeyPrefix?: string);
+    hasToken(): boolean;
     setTokens(accessToken: string, refreshToken: string): void;
     getToken(): Promise<string | null>;
     onTokenExpired(callback: () => Promise<void>): void;