@ph-cms/client-sdk 0.1.23 → 0.1.25

package/README.md

@@ -47,6 +47,8 @@ import type {
   // Auth
   LoginRequest,
   RegisterRequest,
+  RegisterInput,           // register() 훅에 전달하는 유니온 타입 (method: 'email' | 'firebase')
+  FirebaseRegisterRequest, // method: 'firebase' 방식의 페이로드 타입
   RefreshTokenRequest,
   FirebaseExchangeRequest,
   AuthResponse,
@@ -113,7 +115,8 @@ SDK의 인증 시스템은 세 개의 레이어로 구성됩니다:
 |---|---|---|
 | `login()` | `POST /api/auth/login` | `setTokens()` → `refreshUser()` |
 | `loginWithFirebase()` | `POST /api/auth/firebase/exchange` | `setTokens()` → `refreshUser()` |
-| `register()` | `POST /api/auth/register` | `setTokens()` → `refreshUser()` |
+| `register()` (method: 'email') | `POST /api/auth/register` | `setTokens()` → `refreshUser()` |
+| `register()` (method: 'firebase') | `POST /api/auth/register` (provider: firebase:password) | `setTokens()` → `refreshUser()` |
 | `logout()` | `POST /api/auth/logout` | `provider.logout()` → `refreshUser()` (상태 초기화) |
 
 ### Authentication Lifecycle
@@ -381,7 +384,7 @@ function AuthComponent() {
     // 액션 (모두 Promise 반환)
     login,             // (data: LoginRequest) => Promise<AuthResponse>
     loginWithFirebase, // (data: FirebaseExchangeRequest) => Promise<AuthResponse>
-    register,          // (data: RegisterRequest) => Promise<AuthResponse>
+    register,          // (data: RegisterInput) => Promise<AuthResponse>  ← method: 'email' | 'firebase'
     loginAnonymous,    // (data?: AnonymousLoginRequest) => Promise<AuthResponse>
     upgradeAnonymous,  // (data: { email, password, display_name?, username? }) => Promise<UserDto>
     logout,            // () => Promise<void>
@@ -571,24 +574,85 @@ function UpgradeForm() {
 
 #### 회원가입
 
+`register()`는 `method` 필드로 이메일 방식과 Firebase 방식을 구분합니다.
+`channelUid` 또는 `channelSlug` 중 하나는 필수입니다 (`PHCMSProvider`에 설정된 값이 자동으로 사용됩니다).
+
+```ts
+import type { RegisterInput } from '@ph-cms/client-sdk';
+```
+
+---
+
+**방식 1 — 이메일/비밀번호 (`method: 'email'` 또는 생략)**
+
 ```tsx
 function RegisterForm() {
   const { register, registerStatus } = useAuth();
 
-  const handleRegister = async (formData: {
-    email: string;
-    password: string;
-    display_name: string;
-    username?: string;
-  }) => {
-    await register(formData);
+  const handleRegister = async () => {
+    await register({
+      // method: 'email',  // 생략 가능 (기본값)
+      email: 'user@example.com',
+      password: 'password123',
+      display_name: '홍길동',
+      termCodes: ['SERVICE_TERM', 'PRIVACY_TERM'], // 동의할 약관 코드 목록
+      // channelUid는 PHCMSProvider에 설정된 값이 자동 사용됨
+      // 명시적으로 지정하려면: channelUid: 'my-channel'
+    });
     // 성공 → 자동으로 me() 호출 → 즉시 인증 상태로 전환
   };
 
-  // ...
+  return (
+    <button onClick={handleRegister} disabled={registerStatus.isPending}>
+      {registerStatus.isPending ? '가입 중...' : '회원가입'}
+    </button>
+  );
 }
 ```
 
+---
+
+**방식 2 — Firebase 회원가입 (`method: 'firebase'`)**
+
+서버가 Firebase 계정 생성과 PH-CMS 계정 생성을 하나의 트랜잭션으로 처리합니다.
+DB 트랜잭션 실패 시 서버가 Firebase 계정을 즉시 롤백하므로 고아 계정이 발생하지 않습니다.
+
+클라이언트는 Firebase ID 토큰 없이 이메일/비밀번호만 전송합니다.
+
+```tsx
+function FirebaseRegisterForm() {
+  const { register, registerStatus } = useAuth();
+
+  const handleRegister = async () => {
+    await register({
+      method: 'firebase',
+      email: 'user@example.com',
+      password: 'password123',
+      display_name: '홍길동',
+      termCodes: ['SERVICE_TERM', 'PRIVACY_TERM'],
+      // channelUid는 PHCMSProvider에 설정된 값이 자동 사용됨
+    });
+    // 성공 → Firebase 계정 + PH-CMS 계정 동시 생성
+    //       → 자동으로 me() 호출 → 즉시 인증 상태로 전환
+  };
+
+  return (
+    <button onClick={handleRegister} disabled={registerStatus.isPending}>
+      {registerStatus.isPending ? '가입 중...' : 'Firebase로 회원가입'}
+    </button>
+  );
+}
+```
+
+> **Firebase 방식과 `loginWithFirebase()`의 차이**
+>
+> | | `register({ method: 'firebase' })` | `loginWithFirebase({ idToken })` |
+> |---|---|---|
+> | **목적** | 신규 가입 | 기존 Firebase 계정으로 로그인 / 신규 가입 |
+> | **클라이언트 역할** | 이메일·비밀번호만 전송 | Firebase SDK로 직접 인증 후 ID 토큰 전달 |
+> | **Firebase 계정 생성** | 서버가 처리 (롤백 보장) | 클라이언트가 처리 |
+> | **용도** | 서버 사이드 Firebase 가입 플로우 | 소셜 로그인(Google 등) 또는 자체 Firebase 로그인 |
+
 #### 로그아웃
 
 ```tsx
@@ -1238,6 +1302,18 @@ client.content        // ContentModule
 client.channel        // ChannelModule
 client.terms          // TermsModule
 client.media          // MediaModule
+
+await client.getToken() // 현재 유효한 PH-CMS access token 반환 (만료 시 자동 갱신, 없으면 null)
+```
+
+`getToken()`은 PH-CMS SDK가 아닌 외부 서비스(예: 알림 서비스)를 클라이언트에서 직접 호출할 때 Authorization 헤더에 넣을 토큰을 가져오는 데 사용합니다.
+
+```ts
+const token = await client.getToken();
+
+const res = await fetch(`${NOTIFICATION_SERVICE_URL}/notifications`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
 ```
 
 `apiPrefix`는 생성 시 각 모듈에 직접 주입됩니다. 예를 들어 `apiPrefix: '/v2/api'`로 설정하면 모든 모듈의 요청 URL이 `/v2/api/contents/...`, `/v2/api/auth/...` 형태로 전송됩니다.
@@ -1334,7 +1410,8 @@ const result = await content.list({ channelUid: 'my-channel' });
 |---|---|
 | `login(data: LoginRequest)` | 이메일/비밀번호 로그인 → `AuthResponse` |
 | `loginWithFirebase(data: FirebaseExchangeRequest)` | Firebase ID 토큰 교환 → `AuthResponse` |
-| `register(data: RegisterRequest)` | 회원가입 → `AuthResponse` |
+| `register(data: RegisterRequest)` | 이메일 회원가입 → `AuthResponse` (`channelUid` \| `channelSlug` 필수) |
+| `registerWithFirebase(data: FirebaseRegisterRequest)` | 서버 사이드 Firebase 회원가입 → `AuthResponse` (`channelUid` \| `channelSlug` 필수) |
 | `me(params?: { channelUid?: string })` | 현재 사용자 프로필 조회 → `UserDto` |
 | `refresh(refreshToken: string)` | 토큰 갱신 → `{ accessToken, refreshToken }` |
 | `logout()` | 로그아웃 (프로바이더 토큰 삭제 + 서버 세션 무효화) |

package/bin/cli.js

@@ -13,7 +13,7 @@ if (command === 'init-skill') {
   process.exit(1);
 }
 
-function initSkill() {g
+function initSkill() {
   // --dir 옵션 파싱
   const dirFlagIndex = process.argv.indexOf('--dir');
   const baseDir = dirFlagIndex !== -1 && process.argv[dirFlagIndex + 1]

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

@@ -30,15 +30,13 @@ export declare class FirebaseAuthProvider extends BaseAuthProvider {
         expiryBufferMs?: number;
     });
     /**
-     * Returns a valid access token for PH-CMS API calls.
+     * Returns the current valid PH-CMS access token.
      *
      * 1. If a PH-CMS access token exists and is still valid, return it.
      * 2. If the PH-CMS access token is expired (or will expire within
      *    `expiryBufferMs`), attempt an automatic refresh using the stored
      *    refresh token.
-     * 3. If no PH-CMS token exists at all (or refresh failed), fall back to
-     *    the Firebase ID token (useful for the initial exchange call or if the
-     *    server supports Firebase tokens directly).
+     * 3. If no PH-CMS token exists or refresh fails, return `null`.
      */
     getToken(): Promise<string | null>;
     /**

package/dist/auth/firebase-provider.js

@@ -28,32 +28,22 @@ class FirebaseAuthProvider extends base_provider_1.BaseAuthProvider {
         this.type = 'FIREBASE';
     }
     /**
-     * Returns a valid access token for PH-CMS API calls.
+     * Returns the current valid PH-CMS access token.
      *
      * 1. If a PH-CMS access token exists and is still valid, return it.
      * 2. If the PH-CMS access token is expired (or will expire within
      *    `expiryBufferMs`), attempt an automatic refresh using the stored
      *    refresh token.
-     * 3. If no PH-CMS token exists at all (or refresh failed), fall back to
-     *    the Firebase ID token (useful for the initial exchange call or if the
-     *    server supports Firebase tokens directly).
+     * 3. If no PH-CMS token exists or refresh fails, return `null`.
      */
     async getToken() {
-        if (this.accessToken) {
-            const expired = this.isCurrentTokenExpired();
-            if (expired === true) {
-                const refreshed = await this.tryRefresh();
-                if (refreshed)
-                    return refreshed;
-                // Refresh failed — fall through to Firebase ID token fallback.
-            }
-            else {
-                // Token is valid (or unparseable — let server decide).
-                return this.accessToken;
-            }
+        if (!this.accessToken)
+            return null;
+        const expired = this.isCurrentTokenExpired();
+        if (expired === true) {
+            return this.tryRefresh();
         }
-        // Fallback to Firebase ID token if no valid PH-CMS token is available.
-        return this.getIdToken();
+        return this.accessToken;
     }
     /**
      * Clears PH-CMS tokens **and** signs the user out of Firebase.

package/dist/client.d.ts

@@ -35,6 +35,15 @@ export declare class PHCMSClient {
     private refreshQueue;
     /** Exposes the auth provider so UI layers can check token state synchronously. */
     get authProvider(): AuthProvider | undefined;
+    /**
+     * Returns the current valid PH-CMS access token.
+     *
+     * Delegates to the configured {@link AuthProvider.getToken}, which handles
+     * expiry checks and automatic refresh internally.
+     *
+     * Returns `null` when no provider is configured or no valid token exists.
+     */
+    getToken(): Promise<string | null>;
     private readonly normalizedApiPrefix;
     constructor(config: PHCMSClientConfig);
     /**

package/dist/client.js

@@ -17,6 +17,17 @@ class PHCMSClient {
     get authProvider() {
         return this.config.auth;
     }
+    /**
+     * Returns the current valid PH-CMS access token.
+     *
+     * Delegates to the configured {@link AuthProvider.getToken}, which handles
+     * expiry checks and automatic refresh internally.
+     *
+     * Returns `null` when no provider is configured or no valid token exists.
+     */
+    async getToken() {
+        return this.config.auth?.getToken() ?? null;
+    }
     constructor(config) {
         this.config = config;
         /**

package/dist/hooks/useAuth.d.ts

@@ -1,3 +1,16 @@
+import { FirebaseRegisterRequest, RegisterRequest } from '@ph-cms/api-contract';
+type FirebaseRegisterInput = {
+    method: 'firebase';
+} & FirebaseRegisterRequest;
+type EmailRegisterInput = {
+    method?: 'email';
+} & RegisterRequest;
+/**
+ * register()에 전달할 수 있는 입력 타입.
+ * - method: 'firebase' → Firebase idToken 기반 가입 (FirebaseRegisterRequest)
+ * - method: 'email' (기본값) → 이메일/비밀번호 기반 가입 (RegisterRequest)
+ */
+export type RegisterInput = FirebaseRegisterInput | EmailRegisterInput;
 /**
  * Unified Auth Hook
  * Returns both the current auth status and the actions.
@@ -150,16 +163,7 @@ export declare const useAuth: () => {
             }[] | undefined;
         };
         accessToken: string;
-    }, Error, {
-        email: string;
-        display_name: string;
-        username?: string | null | undefined;
-        password?: string | undefined;
-        provider?: string | undefined;
-        provider_subject?: string | undefined;
-        termCodes?: string[] | undefined;
-        channelUid?: string | undefined;
-    }, unknown>;
+    }, Error, RegisterInput, unknown>;
     loginAnonymous: import("@tanstack/react-query").UseMutateAsyncFunction<{
         refreshToken: string;
         user: {
@@ -349,16 +353,7 @@ export declare const useAuth: () => {
             }[] | undefined;
         };
         accessToken: string;
-    }, Error, {
-        email: string;
-        display_name: string;
-        username?: string | null | undefined;
-        password?: string | undefined;
-        provider?: string | undefined;
-        provider_subject?: string | undefined;
-        termCodes?: string[] | undefined;
-        channelUid?: string | undefined;
-    }, unknown>;
+    }, Error, RegisterInput, unknown>;
     loginAnonymousStatus: import("@tanstack/react-query").UseMutationResult<{
         refreshToken: string;
         user: {
@@ -551,3 +546,4 @@ export declare const useUpgradeAnonymous: () => import("@tanstack/react-query").
     display_name?: string;
     username?: string;
 }, unknown>;
+export {};

package/dist/hooks/useAuth.js

@@ -28,10 +28,20 @@ const useAuth = () => {
         },
     });
     const registerMutation = (0, react_query_1.useMutation)({
-        mutationFn: (data) => client.auth.register({
-            channelUid: data.channelUid || channelUid,
-            ...data
-        }),
+        mutationFn: (data) => {
+            if (data.method === 'firebase') {
+                const { method, channelUid: explicitChannelUid, ...rest } = data;
+                return client.auth.registerWithFirebase({
+                    ...rest,
+                    channelUid: explicitChannelUid || channelUid,
+                });
+            }
+            const { method, channelUid: explicitChannelUid, ...rest } = data;
+            return client.auth.register({
+                ...rest,
+                channelUid: explicitChannelUid || channelUid,
+            });
+        },
         onSuccess: async () => {
             await refreshUser();
         },

package/dist/hooks/useContent.d.ts

@@ -44,6 +44,7 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
     type: string;
     title: string;
     status?: string | undefined;
+    text?: string | null | undefined;
     channelUid?: string | undefined;
     channelSlug?: string | undefined;
     geometry?: {
@@ -55,7 +56,6 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
         geometry?: any;
     } | undefined;
     image?: string | null | undefined;
-    text?: string | null | undefined;
     attributes?: Record<string, any> | undefined;
     summary?: string | null | undefined;
     slug?: string | null | undefined;

package/dist/hooks/useMedia.d.ts

@@ -20,8 +20,8 @@ export declare const useUploadToS3: () => import("@tanstack/react-query").UseMut
 }, unknown>;
 export declare const useMediaDetail: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
     type: "image" | "video" | "audio" | "document" | "file";
-    uid: string;
     url: string;
+    uid: string;
     name: string;
     mimeType: string;
     size: number;

package/dist/hooks/useUser.d.ts

@@ -87,6 +87,7 @@ export declare const useUpdateProfile: () => import("@tanstack/react-query").Use
  */
 export declare const useChannelTerms: () => import("@tanstack/react-query").UseQueryResult<{
     code: string;
+    type: "text" | "url";
     id: number;
     version: string;
     title: string;

package/dist/modules/auth.d.ts

@@ -1,4 +1,4 @@
-import { AuthResponse, FirebaseExchangeRequest, LoginRequest, RegisterRequest, UserDto, AnonymousLoginRequest } from "@ph-cms/api-contract";
+import { AnonymousLoginRequest, AuthResponse, FirebaseExchangeRequest, FirebaseRegisterRequest, LoginRequest, RegisterRequest, UserDto } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
 import { AuthProvider } from "../auth/interfaces";
 export declare class AuthModule {
@@ -15,6 +15,13 @@ export declare class AuthModule {
      */
     loginWithFirebase(data: FirebaseExchangeRequest): Promise<AuthResponse>;
     register(data: RegisterRequest): Promise<AuthResponse>;
+    /**
+     * 서버 사이드 Firebase 회원가입.
+     * 클라이언트는 idToken 없이 이메일/비밀번호를 전송하고,
+     * 서버가 Firebase 계정 생성과 백엔드 유저 생성을 원자적으로 처리한다.
+     * DB 실패 시 서버가 Firebase 계정을 롤백하므로 고아 계정이 발생하지 않는다.
+     */
+    registerWithFirebase(data: FirebaseRegisterRequest): Promise<AuthResponse>;
     me(params?: {
         channelUid?: string;
         channelSlug?: string;

package/dist/modules/auth.js

@@ -48,6 +48,26 @@ class AuthModule {
         }
         return response;
     }
+    /**
+     * 서버 사이드 Firebase 회원가입.
+     * 클라이언트는 idToken 없이 이메일/비밀번호를 전송하고,
+     * 서버가 Firebase 계정 생성과 백엔드 유저 생성을 원자적으로 처리한다.
+     * DB 실패 시 서버가 Firebase 계정을 롤백하므로 고아 계정이 발생하지 않는다.
+     */
+    async registerWithFirebase(data) {
+        const validation = api_contract_1.FirebaseRegisterSchema.safeParse(data);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid Firebase register data", validation.error.errors);
+        }
+        const response = await this.client.post(`${this.prefix}/auth/register`, {
+            ...data,
+            provider: 'firebase:password',
+        });
+        if (this.provider) {
+            this.provider.setTokens(response.accessToken, response.refreshToken);
+        }
+        return response;
+    }
     async me(params) {
         return this.client.get(`${this.prefix}/auth/me`, { params });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ph-cms/client-sdk",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Unified PH-CMS Client SDK (React + Core)",
   "keywords": [],
   "license": "MIT",
@@ -30,7 +30,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@ph-cms/api-contract": "^0.1.8",
+    "@ph-cms/api-contract": "^0.1.9",
     "@tanstack/react-query": "^5.0.0",
     "axios": "^1.6.0",
     "zod": "^3.22.4"