@ph-cms/client-sdk 0.1.5 → 0.1.6

package/README.md

@@ -10,6 +10,7 @@ This package provides:
 - **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
 
@@ -462,6 +463,130 @@ await client.auth.logout();
 | `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

package/dist/hooks/useFirebaseAuthSync.d.ts

@@ -0,0 +1,108 @@
+import type { Auth } from 'firebase/auth';
+import React from 'react';
+export interface UseFirebaseAuthSyncOptions {
+    /**
+     * Firebase Auth instance.
+     * Must be provided so the hook can subscribe to `onAuthStateChanged`.
+     */
+    firebaseAuth: Auth;
+    /**
+     * If true, automatically call `logout()` on the PH-CMS side
+     * when the Firebase user signs out.
+     * @default true
+     */
+    logoutOnFirebaseSignOut?: boolean;
+    /**
+     * Called when the sync exchange succeeds.
+     */
+    onSyncSuccess?: () => void;
+    /**
+     * Called when the sync exchange fails.
+     */
+    onSyncError?: (error: unknown) => void;
+}
+export interface UseFirebaseAuthSyncReturn {
+    /** Whether a token-exchange request is currently in flight. */
+    isSyncing: boolean;
+}
+/**
+ * `useFirebaseAuthSync`
+ *
+ * Subscribes to Firebase `onAuthStateChanged` and automatically synchronizes
+ * the Firebase authentication state with the PH-CMS backend:
+ *
+ * - **Firebase user signs in** and PH-CMS is not yet authenticated →
+ *   obtains a Firebase ID token and calls `loginWithFirebase({ idToken })`
+ *   which exchanges the token for PH-CMS access/refresh tokens and then
+ *   fetches the user profile via `/auth/me`.
+ *
+ * - **Firebase user signs out** and PH-CMS is still authenticated →
+ *   calls `logout()` on PH-CMS (configurable via `logoutOnFirebaseSignOut`).
+ *
+ * The hook must be rendered **inside** `<PHCMSProvider>` because it relies
+ * on context values (`isAuthenticated`, `isLoading`) and the `loginWithFirebase`
+ * / `logout` actions exposed by the auth module.
+ *
+ * ### Example
+ *
+ * ```tsx
+ * import { useFirebaseAuthSync } from '@ph-cms/client-sdk';
+ * import { getAuth } from 'firebase/auth';
+ *
+ * const firebaseAuth = getAuth(firebaseApp);
+ *
+ * function App() {
+ *   useFirebaseAuthSync({ firebaseAuth });
+ *   return <MainContent />;
+ * }
+ * ```
+ */
+export declare const useFirebaseAuthSync: (options: UseFirebaseAuthSyncOptions) => UseFirebaseAuthSyncReturn;
+export interface FirebaseAuthSyncProps {
+    /**
+     * Firebase Auth instance.
+     */
+    firebaseAuth: Auth;
+    /**
+     * If true, automatically call `logout()` on the PH-CMS side
+     * when the Firebase user signs out.
+     * @default true
+     */
+    logoutOnFirebaseSignOut?: boolean;
+    /**
+     * Called when the sync exchange succeeds.
+     */
+    onSyncSuccess?: () => void;
+    /**
+     * Called when the sync exchange fails.
+     */
+    onSyncError?: (error: unknown) => void;
+    children: React.ReactNode;
+}
+/**
+ * `<FirebaseAuthSync>`
+ *
+ * A convenience wrapper component that calls `useFirebaseAuthSync` internally.
+ * Place it **inside** `<PHCMSProvider>` and wrap the part of the tree that
+ * should wait for or react to Firebase↔PH-CMS auth synchronization.
+ *
+ * ### Example
+ *
+ * ```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>
+ *   );
+ * }
+ * ```
+ */
+export declare const FirebaseAuthSync: React.FC<FirebaseAuthSyncProps>;

package/dist/hooks/useFirebaseAuthSync.js

@@ -0,0 +1,221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebaseAuthSync = exports.useFirebaseAuthSync = void 0;
+const react_1 = __importStar(require("react"));
+const context_1 = require("../context");
+/**
+ * `useFirebaseAuthSync`
+ *
+ * Subscribes to Firebase `onAuthStateChanged` and automatically synchronizes
+ * the Firebase authentication state with the PH-CMS backend:
+ *
+ * - **Firebase user signs in** and PH-CMS is not yet authenticated →
+ *   obtains a Firebase ID token and calls `loginWithFirebase({ idToken })`
+ *   which exchanges the token for PH-CMS access/refresh tokens and then
+ *   fetches the user profile via `/auth/me`.
+ *
+ * - **Firebase user signs out** and PH-CMS is still authenticated →
+ *   calls `logout()` on PH-CMS (configurable via `logoutOnFirebaseSignOut`).
+ *
+ * The hook must be rendered **inside** `<PHCMSProvider>` because it relies
+ * on context values (`isAuthenticated`, `isLoading`) and the `loginWithFirebase`
+ * / `logout` actions exposed by the auth module.
+ *
+ * ### Example
+ *
+ * ```tsx
+ * import { useFirebaseAuthSync } from '@ph-cms/client-sdk';
+ * import { getAuth } from 'firebase/auth';
+ *
+ * const firebaseAuth = getAuth(firebaseApp);
+ *
+ * function App() {
+ *   useFirebaseAuthSync({ firebaseAuth });
+ *   return <MainContent />;
+ * }
+ * ```
+ */
+const useFirebaseAuthSync = (options) => {
+    const { firebaseAuth, logoutOnFirebaseSignOut = true, onSyncSuccess, onSyncError, } = options;
+    const { client, isAuthenticated, isLoading, refreshUser } = (0, context_1.usePHCMSContext)();
+    // Use refs for values that change frequently but should not re-trigger
+    // the effect (which would tear down and re-create the Firebase listener).
+    const isAuthenticatedRef = (0, react_1.useRef)(isAuthenticated);
+    const isLoadingRef = (0, react_1.useRef)(isLoading);
+    const syncInProgressRef = (0, react_1.useRef)(false);
+    const isSyncingStateRef = (0, react_1.useRef)(false);
+    const [isSyncing, setIsSyncing] = react_1.default.useState(false);
+    // Keep refs up to date.
+    (0, react_1.useEffect)(() => {
+        isAuthenticatedRef.current = isAuthenticated;
+    }, [isAuthenticated]);
+    (0, react_1.useEffect)(() => {
+        isLoadingRef.current = isLoading;
+    }, [isLoading]);
+    // Stable callback refs so the effect closure doesn't go stale.
+    const onSyncSuccessRef = (0, react_1.useRef)(onSyncSuccess);
+    const onSyncErrorRef = (0, react_1.useRef)(onSyncError);
+    (0, react_1.useEffect)(() => {
+        onSyncSuccessRef.current = onSyncSuccess;
+    }, [onSyncSuccess]);
+    (0, react_1.useEffect)(() => {
+        onSyncErrorRef.current = onSyncError;
+    }, [onSyncError]);
+    const handleFirebaseUser = (0, react_1.useCallback)(async (fbUser) => {
+        if (fbUser) {
+            // Firebase user is signed in.
+            // Only exchange if PH-CMS is not already authenticated and not loading.
+            if (!isAuthenticatedRef.current &&
+                !isLoadingRef.current &&
+                !syncInProgressRef.current) {
+                syncInProgressRef.current = true;
+                isSyncingStateRef.current = true;
+                setIsSyncing(true);
+                try {
+                    const idToken = await fbUser.getIdToken();
+                    await client.auth.loginWithFirebase({ idToken });
+                    // loginWithFirebase stores the tokens in the provider.
+                    // Now refresh the context so `isAuthenticated` and `user` update.
+                    await refreshUser();
+                    onSyncSuccessRef.current?.();
+                }
+                catch (error) {
+                    console.error('[useFirebaseAuthSync] Token exchange failed:', error);
+                    onSyncErrorRef.current?.(error);
+                }
+                finally {
+                    syncInProgressRef.current = false;
+                    isSyncingStateRef.current = false;
+                    setIsSyncing(false);
+                }
+            }
+        }
+        else {
+            // Firebase user signed out.
+            if (logoutOnFirebaseSignOut && isAuthenticatedRef.current) {
+                try {
+                    await client.auth.logout();
+                    await refreshUser();
+                }
+                catch (error) {
+                    console.error('[useFirebaseAuthSync] Logout failed:', error);
+                }
+            }
+        }
+    }, 
+    // `client`, `refreshUser`, and `logoutOnFirebaseSignOut` are stable
+    // across renders (client is a singleton, refreshUser is memoized,
+    // logoutOnFirebaseSignOut is typically a constant).
+    [client, refreshUser, logoutOnFirebaseSignOut]);
+    (0, react_1.useEffect)(() => {
+        // Dynamically import the listener so that this file has zero runtime
+        // dependency on firebase/auth at the module level. The `Auth` object
+        // passed in already carries the implementation; we just need the
+        // `onAuthStateChanged` function reference from it.
+        //
+        // Firebase Auth's `onAuthStateChanged` is available on the Auth object
+        // via the modular API through the standalone function, but we can also
+        // call it as `firebaseAuth.onAuthStateChanged(...)` which works on the
+        // Auth instance directly (compat style). However, the recommended
+        // modular approach is to use the standalone function.
+        //
+        // To avoid directly importing from 'firebase/auth' at the top level
+        // (since it's an optional peer dep), we use a dynamic import wrapped
+        // in a try-catch. If the import fails, we fall back to a noop.
+        let unsubscribe = null;
+        let cancelled = false;
+        const setup = async () => {
+            try {
+                // Dynamic import so builds without firebase don't break.
+                const firebaseAuthModule = await Promise.resolve().then(() => __importStar(require('firebase/auth')));
+                if (cancelled)
+                    return;
+                unsubscribe = firebaseAuthModule.onAuthStateChanged(firebaseAuth, (fbUser) => {
+                    // Fire and forget; errors are caught inside handleFirebaseUser.
+                    void handleFirebaseUser(fbUser);
+                });
+            }
+            catch {
+                // firebase/auth is not installed — this is fine, it's optional.
+                console.warn('[useFirebaseAuthSync] firebase/auth could not be imported. ' +
+                    'Make sure it is installed if you intend to use Firebase auth sync.');
+            }
+        };
+        void setup();
+        return () => {
+            cancelled = true;
+            unsubscribe?.();
+        };
+    }, [firebaseAuth, handleFirebaseUser]);
+    return { isSyncing };
+};
+exports.useFirebaseAuthSync = useFirebaseAuthSync;
+/**
+ * `<FirebaseAuthSync>`
+ *
+ * A convenience wrapper component that calls `useFirebaseAuthSync` internally.
+ * Place it **inside** `<PHCMSProvider>` and wrap the part of the tree that
+ * should wait for or react to Firebase↔PH-CMS auth synchronization.
+ *
+ * ### Example
+ *
+ * ```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>
+ *   );
+ * }
+ * ```
+ */
+const FirebaseAuthSync = ({ firebaseAuth, logoutOnFirebaseSignOut, onSyncSuccess, onSyncError, children, }) => {
+    (0, exports.useFirebaseAuthSync)({
+        firebaseAuth,
+        logoutOnFirebaseSignOut,
+        onSyncSuccess,
+        onSyncError,
+    });
+    return react_1.default.createElement(react_1.default.Fragment, null, children);
+};
+exports.FirebaseAuthSync = FirebaseAuthSync;

package/dist/index.d.ts

@@ -1,17 +1,18 @@
+export * from './auth/firebase-provider';
 export * from './auth/interfaces';
 export * from './auth/local-provider';
-export * from './auth/firebase-provider';
-export * from './errors';
 export * from './client';
+export * from './errors';
 export * from './modules/auth';
-export * from './modules/content';
 export * from './modules/channel';
-export * from './modules/terms';
+export * from './modules/content';
 export * from './modules/media';
+export * from './modules/terms';
 export * from './context';
 export * from './hooks/useAuth';
-export * from './hooks/useContent';
 export * from './hooks/useChannel';
-export * from './hooks/useTerms';
+export * from './hooks/useContent';
+export * from './hooks/useFirebaseAuthSync';
 export * from './hooks/useMedia';
+export * from './hooks/useTerms';
 export * from './types';

package/dist/index.js

@@ -14,20 +14,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auth/firebase-provider"), exports);
 __exportStar(require("./auth/interfaces"), exports);
 __exportStar(require("./auth/local-provider"), exports);
-__exportStar(require("./auth/firebase-provider"), exports);
-__exportStar(require("./errors"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./errors"), exports);
 __exportStar(require("./modules/auth"), exports);
-__exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/channel"), exports);
-__exportStar(require("./modules/terms"), exports);
+__exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/media"), exports);
+__exportStar(require("./modules/terms"), exports);
 __exportStar(require("./context"), exports);
 __exportStar(require("./hooks/useAuth"), exports);
-__exportStar(require("./hooks/useContent"), exports);
 __exportStar(require("./hooks/useChannel"), exports);
-__exportStar(require("./hooks/useTerms"), exports);
+__exportStar(require("./hooks/useContent"), exports);
+__exportStar(require("./hooks/useFirebaseAuthSync"), exports);
 __exportStar(require("./hooks/useMedia"), exports);
+__exportStar(require("./hooks/useTerms"), exports);
 __exportStar(require("./types"), exports);

package/package.json

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