@ph-cms/client-sdk 0.1.3 → 0.1.5

package/README.md

@@ -8,6 +8,8 @@ This package provides:
 - 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)
 
 ## Installation
 
@@ -15,45 +17,226 @@ This package provides:
 npm install @ph-cms/client-sdk
 ```
 
-> **Note:** `@tanstack/react-query` is a direct dependency from v0.1.1. You no longer need to install it manually unless you use it in your own application code.
+> **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.
 
-If you use the React bindings, ensure you have `react` installed:
+---
+
+## 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 상태 관리 — 토큰 유무에 따른 조건부 프로필 조회, 로그인·로그아웃 액션 |
 
-```bash
-npm install react react-dom
+```
+┌─────────────────────────────────────────────────────────┐
+│  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)     │
+└─────────────────────────────────────────────────────────┘
 ```
 
-If you use Firebase auth integration:
+### 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. 로그인 (이메일/비밀번호)
 
-```bash
-npm install firebase
+```
+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
 ```
 
-## Usage (Core SDK)
+#### 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 { PHCMSClient } from '@ph-cms/client-sdk';
+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()` | 토큰 삭제 |
 
-// Use the modules directly
-const contents = await client.content.list({
-  page: 1,
-  limit: 20,
+### `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_');
+
+const client = new PHCMSClient({
+  baseURL: 'https://api.example.com',
+  auth: authProvider,
 });
 ```
 
-## React Usage (v0.1.1+)
+| 생성자 인자 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `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` 조건으로 사용되므로, 비동기 호출은 허용되지 않습니다.
+
+---
 
-From version 0.1.1, `PHCMSProvider` automatically includes a `QueryClientProvider`. You don't need to wrap your app with `QueryClientProvider` manually to use PH-CMS hooks.
+## React Usage
 
 ### Basic Setup
 
 ```tsx
-import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
-import { client } from './lib/sdk'; // Your pre-configured client
+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() {
   return (
@@ -64,73 +247,263 @@ export function App() {
 }
 ```
 
-### Using Hooks
+`PHCMSProvider`는 내부적으로 `QueryClientProvider`를 포함하므로, 별도로 추가할 필요가 없습니다.
+외부에서 직접 관리하는 `QueryClient`를 사용하려면 `queryClient` prop으로 전달합니다:
 
 ```tsx
-import { useContent, useUser } from '@ph-cms/client-sdk';
+import { QueryClient } from '@tanstack/react-query';
 
-function MyComponent() {
-  const { data: user, isLoading: userLoading } = useUser();
-  const { data: contents, isLoading: contentLoading } = useContent();
+const queryClient = new QueryClient();
+
+<PHCMSProvider client={client} queryClient={queryClient}>
+  ...
+</PHCMSProvider>
+```
 
-  if (userLoading || contentLoading) return <div>Loading...</div>;
+### Authentication with `useAuth`
+
+`useAuth`는 인증 상태와 액션을 통합 제공하는 메인 훅입니다.
+
+```tsx
+import { useAuth } from '@ph-cms/client-sdk';
+
+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();
+
+  // ...
+}
+```
+
+#### 이메일/비밀번호 로그인
+
+```tsx
+function LoginForm() {
+  const { login, loginStatus, isAuthenticated, user } = useAuth();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  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>Hello, {user?.email}</h1>
-      <ul>
-        {contents?.items.map(item => (
-          <li key={item.uid}>{item.title}</li>
-        ))}
-      </ul>
-    </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>
   );
 }
 ```
 
-### Custom QueryClient (Optional)
+#### Firebase 로그인
 
-If your application already uses React Query and you want to share the cache/settings:
+Firebase 로그인은 두 단계로 이루어집니다:
+1. Firebase SDK로 인증하여 ID 토큰을 획득
+2. `loginWithFirebase()`로 PH-CMS 서버에 토큰 교환 요청
 
 ```tsx
-import { QueryClient } from '@tanstack/react-query';
-import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
+import { FirebaseAuthProvider } from '@ph-cms/client-sdk';
+import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';
 
-const queryClient = new QueryClient();
-const client = new PHCMSClient({ baseURL: '...' });
+// 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 });
+  };
 
-export function App() {
   return (
-    <PHCMSProvider client={client} queryClient={queryClient}>
-      {/* Both your app and PH-CMS hooks will use the same queryClient */}
-      <YourComponents />
-    </PHCMSProvider>
+    <button onClick={handleFirebaseLogin} disabled={loginWithFirebaseStatus.isPending}>
+      {loginWithFirebaseStatus.isPending ? 'Firebase 로그인 중...' : 'Google 로그인'}
+    </button>
   );
 }
 ```
 
-## Admin SDK (@ph-cms/client-sdk-admin)
+#### 회원가입
+
+```tsx
+function RegisterForm() {
+  const { register, registerStatus } = useAuth();
+
+  const handleRegister = async (formData: {
+    email: string;
+    password: string;
+    display_name: string;
+    username?: string;
+  }) => {
+    await register(formData);
+    // 성공 시 자동으로 me() 호출 → 즉시 인증 상태로 전환
+  };
+
+  // ...
+}
+```
 
-For administrative tasks, use `@ph-cms/client-sdk-admin`. It follows the same provider pattern:
+#### 로그아웃
 
 ```tsx
-import { PHCMSAdminProvider } from '@ph-cms/client-sdk-admin';
-import { adminClient } from './lib/sdk';
+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 }` |
+
+---
+
+## Using Data Hooks
+
+### Content
+
+```tsx
+import { useContentList, useContentDetail } from '@ph-cms/client-sdk';
+
+function ContentList() {
+  const { data, isLoading } = useContentList({ limit: 10 });
+
+  if (isLoading) return <div>Loading...</div>;
 
-export function App() {
   return (
-    <PHCMSAdminProvider client={adminClient}>
-      <AdminComponents />
-    </PHCMSAdminProvider>
+    <ul>
+      {data?.content.map(item => (
+        <li key={item.uid}>{item.title}</li>
+      ))}
+    </ul>
   );
 }
 ```
 
-## Media & File Upload (v0.1.2+)
+### 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.
 
-### 1. Simple Workflow Example
+### Simple Workflow Example
 
 ```tsx
 import { useMediaUploadTickets, useUploadToS3, useCreateContent } from '@ph-cms/client-sdk';
@@ -149,8 +522,6 @@ function MediaUploader() {
       filename: file.name,
       contentType: file.type,
       fileSize: file.size,
-      // width: 1024, (optional)
-      // height: 768   (optional)
     }]);
 
     const { mediaUid, uploadUrl } = tickets[0];
@@ -160,7 +531,6 @@ function MediaUploader() {
 
     // Step 3: Use the mediaUid to create content
     await createContent({
-      channelSlug: 'my-channel',
       type: 'post',
       title: 'Post with image',
       mediaAttachments: [mediaUid]
@@ -171,14 +541,68 @@ function MediaUploader() {
 }
 ```
 
-### 2. Supported Media Types
-The system automatically classifies media based on the `contentType`:
-- `image/*` -> `image`
-- `video/*` -> `video`
-- `audio/*` -> `audio`
-- `application/pdf`, `.docx`, etc. -> `document`
-- Others -> `file`
+---
+
+## 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;

package/dist/auth/firebase-provider.js

@@ -14,6 +14,9 @@ class FirebaseAuthProvider {
             this.refreshToken = localStorage.getItem(`${this.storageKeyPrefix}refresh_token`);
         }
     }
+    hasToken() {
+        return this.accessToken !== null || this.refreshToken !== null;
+    }
     setTokens(accessToken, refreshToken) {
         this.accessToken = accessToken;
         this.refreshToken = refreshToken;

package/dist/auth/interfaces.d.ts

@@ -5,6 +5,12 @@ export interface AuthProvider {
      * Should handle refreshing if necessary (or return null/throw if expired and can't refresh).
      */
     getToken(): Promise<string | null>;
+    /**
+     * Returns true if the provider currently holds a token (access or refresh).
+     * This is a synchronous check used to decide whether to attempt API calls
+     * that require authentication (e.g. /auth/me).
+     */
+    hasToken(): boolean;
     /**
      * Sets a callback to be called when the token is known to be expired by the external world (e.g. 401 response).
      */

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

@@ -11,6 +11,7 @@ export declare class LocalAuthProvider implements AuthProvider {
         refreshToken: string;
     }>) | undefined);
     setTokens(accessToken: string, refreshToken: string): void;
+    hasToken(): boolean;
     getToken(): Promise<string | null>;
     onTokenExpired(callback: () => Promise<void>): void;
     logout(): Promise<void>;

package/dist/auth/local-provider.js

@@ -22,6 +22,9 @@ class LocalAuthProvider {
             localStorage.setItem(`${this.storageKeyPrefix}refresh_token`, refreshToken);
         }
     }
+    hasToken() {
+        return this.accessToken !== null || this.refreshToken !== null;
+    }
     async getToken() {
         // Ideally check expiration here using jwt-decode, but for now return what we have.
         // If it's expired, the API will return 401, triggering the interceptor which calls onTokenExpired.

package/dist/client.d.ts

@@ -1,10 +1,10 @@
 import { AxiosInstance } from 'axios';
 import { AuthProvider } from './auth/interfaces';
 import { AuthModule } from './modules/auth';
-import { ContentModule } from './modules/content';
 import { ChannelModule } from './modules/channel';
-import { TermsModule } from './modules/terms';
+import { ContentModule } from './modules/content';
 import { MediaModule } from './modules/media';
+import { TermsModule } from './modules/terms';
 export interface PHCMSClientConfig {
     baseURL: string;
     apiPrefix?: string;
@@ -19,5 +19,7 @@ export declare class PHCMSClient {
     readonly channel: ChannelModule;
     readonly terms: TermsModule;
     readonly media: MediaModule;
+    /** Exposes the auth provider so UI layers can check token state synchronously. */
+    get authProvider(): AuthProvider | undefined;
     constructor(config: PHCMSClientConfig);
 }

package/dist/client.js

@@ -7,11 +7,15 @@ exports.PHCMSClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const errors_1 = require("./errors");
 const auth_1 = require("./modules/auth");
-const content_1 = require("./modules/content");
 const channel_1 = require("./modules/channel");
-const terms_1 = require("./modules/terms");
+const content_1 = require("./modules/content");
 const media_1 = require("./modules/media");
+const terms_1 = require("./modules/terms");
 class PHCMSClient {
+    /** Exposes the auth provider so UI layers can check token state synchronously. */
+    get authProvider() {
+        return this.config.auth;
+    }
     constructor(config) {
         this.config = config;
         const normalizedApiPrefix = `/${(config.apiPrefix || '/api').replace(/^\/+|\/+$/g, '')}`;

package/dist/context.d.ts

@@ -1,12 +1,14 @@
-import React, { ReactNode } from 'react';
+import { UserDto } from '@ph-cms/api-contract';
 import { QueryClient } from '@tanstack/react-query';
+import React, { ReactNode } from 'react';
 import { PHCMSClient } from './client';
-import { UserDto } from '@ph-cms/api-contract';
 export interface PHCMSContextType {
     client: PHCMSClient;
     user: UserDto | null;
     isAuthenticated: boolean;
     isLoading: boolean;
+    /** Manually trigger a refetch of the current user profile. */
+    refreshUser: () => Promise<void>;
 }
 export interface PHCMSProviderProps {
     client: PHCMSClient;

package/dist/context.js

@@ -34,40 +34,71 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.usePHCMS = exports.usePHCMSContext = exports.PHCMSProvider = void 0;
-const react_1 = __importStar(require("react"));
 const react_query_1 = require("@tanstack/react-query");
+const react_1 = __importStar(require("react"));
 const PHCMSContext = (0, react_1.createContext)(null);
+const AUTH_ME_QUERY_KEY = ['auth', 'me'];
 /**
  * Internal component to handle auth state and provide to context
  */
 const PHCMSInternalProvider = ({ client, children }) => {
-    const { data: user, isLoading, isError } = (0, react_query_1.useQuery)({
-        queryKey: ['auth', 'me'],
+    const queryClient = (0, react_query_1.useQueryClient)();
+    // Track token presence in state to trigger re-renders when it changes.
+    // Initial value from provider.
+    const [hasToken, setHasToken] = (0, react_1.useState)(() => client.authProvider?.hasToken() ?? false);
+    // The 'me' query is only enabled if we have a token.
+    const { data: user, isLoading, isError, refetch } = (0, react_query_1.useQuery)({
+        queryKey: [...AUTH_ME_QUERY_KEY],
         queryFn: () => client.auth.me(),
+        enabled: hasToken,
         retry: false,
         staleTime: 1000 * 60 * 5,
     });
+    // Function to update token state and optionally refetch
+    const refreshUser = (0, react_1.useCallback)(async () => {
+        const currentHasToken = client.authProvider?.hasToken() ?? false;
+        setHasToken(currentHasToken);
+        if (currentHasToken) {
+            await refetch();
+        }
+        else {
+            // If no token, clear the query data
+            queryClient.setQueryData([...AUTH_ME_QUERY_KEY], null);
+        }
+    }, [client.authProvider, refetch, queryClient]);
+    // Effect to sync state if provider changes externally (rare but possible)
+    (0, react_1.useEffect)(() => {
+        const interval = setInterval(() => {
+            const currentHasToken = client.authProvider?.hasToken() ?? false;
+            if (currentHasToken !== hasToken) {
+                setHasToken(currentHasToken);
+            }
+        }, 2000); // Check every 2s as a fallback
+        return () => clearInterval(interval);
+    }, [client.authProvider, hasToken]);
     const value = (0, react_1.useMemo)(() => ({
         client,
         user: user || null,
-        isAuthenticated: !!user && !isError,
-        isLoading,
-    }), [client, user, isError, isLoading]);
-    return (react_1.default.createElement(PHCMSContext.Provider, { value: value }, children));
+        isAuthenticated: !!user && !isError && hasToken,
+        isLoading: hasToken ? isLoading : false,
+        refreshUser,
+    }), [client, user, isError, isLoading, hasToken, refreshUser]);
+    return react_1.default.createElement(PHCMSContext.Provider, { value: value }, children);
 };
 /**
  * Root Provider for PH-CMS
  * Automatically includes QueryClientProvider
  */
 const PHCMSProvider = ({ client, queryClient, children }) => {
-    const internalQueryClient = (0, react_1.useMemo)(() => queryClient ?? new react_query_1.QueryClient({
-        defaultOptions: {
-            queries: {
-                refetchOnWindowFocus: false,
-                retry: false,
+    const internalQueryClient = (0, react_1.useMemo)(() => queryClient ??
+        new react_query_1.QueryClient({
+            defaultOptions: {
+                queries: {
+                    refetchOnWindowFocus: false,
+                    retry: false,
+                },
             },
-        },
-    }), [queryClient]);
+        }), [queryClient]);
     return (react_1.default.createElement(react_query_1.QueryClientProvider, { client: internalQueryClient },
         react_1.default.createElement(PHCMSInternalProvider, { client: client }, children)));
 };

package/dist/hooks/useAuth.d.ts

@@ -1,6 +1,6 @@
 /**
  * Unified Auth Hook
- * Returns both the current auth status and the actions
+ * Returns both the current auth status and the actions.
  */
 export declare const useAuth: () => {
     user: {
@@ -128,6 +128,30 @@ export declare const useAuth: () => {
         email: string;
         password: string;
     }, unknown>;
+    loginWithFirebaseStatus: import("@tanstack/react-query").UseMutationResult<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        idToken: string;
+    }, unknown>;
     registerStatus: import("@tanstack/react-query").UseMutationResult<{
         refreshToken: string;
         user: {

package/dist/hooks/useAuth.js

@@ -3,36 +3,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLogout = exports.useLogin = exports.useUser = exports.useAuth = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
+const AUTH_ME_QUERY_KEY = ['auth', 'me'];
 /**
  * Unified Auth Hook
- * Returns both the current auth status and the actions
+ * Returns both the current auth status and the actions.
  */
 const useAuth = () => {
-    const { user, isAuthenticated, isLoading } = (0, context_1.usePHCMSContext)();
+    const { user, isAuthenticated, isLoading, refreshUser } = (0, context_1.usePHCMSContext)();
     const client = (0, context_1.usePHCMS)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const loginMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.login(data),
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
+        onSuccess: async () => {
+            await refreshUser();
         },
     });
     const loginWithFirebaseMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.loginWithFirebase(data),
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
+        onSuccess: async () => {
+            await refreshUser();
         },
     });
     const registerMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.register(data),
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
+        onSuccess: async () => {
+            await refreshUser();
         },
     });
     const logoutMutation = (0, react_query_1.useMutation)({
         mutationFn: () => client.auth.logout(),
-        onSuccess: () => {
-            queryClient.setQueryData(['auth', 'me'], null);
+        onSuccess: async () => {
+            await refreshUser(); // This will clear state since hasToken will be false
             queryClient.invalidateQueries();
         },
     });
@@ -46,6 +47,7 @@ const useAuth = () => {
         logout: logoutMutation.mutateAsync,
         // Access to mutation objects for loading/error states if needed
         loginStatus: loginMutation,
+        loginWithFirebaseStatus: loginWithFirebaseMutation,
         registerStatus: registerMutation,
         logoutStatus: logoutMutation,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ph-cms/client-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Unified PH-CMS Client SDK (React + Core)",
   "keywords": [],
   "license": "MIT",