@ph-cms/client-sdk 0.1.22 → 0.1.24

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
@@ -1334,7 +1398,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

@@ -8,12 +8,19 @@ const command = process.argv[2];
 if (command === 'init-skill') {
   initSkill();
 } else {
-  console.log('Usage: npx @ph-cms/client-sdk init-skill');
+  console.log('Usage: npx @ph-cms/client-sdk init-skill [--dir <path>]');
+  console.log('  --dir <path>  스킬 파일을 생성할 루트 디렉토리 (기본값: .agents)');
   process.exit(1);
 }
 
 function initSkill() {
-  const skillDir = path.join(process.cwd(), '.gemini/skills/ph-cms-client');
+  // --dir 옵션 파싱
+  const dirFlagIndex = process.argv.indexOf('--dir');
+  const baseDir = dirFlagIndex !== -1 && process.argv[dirFlagIndex + 1]
+    ? process.argv[dirFlagIndex + 1]
+    : '.agents';
+
+  const skillDir = path.join(process.cwd(), baseDir, 'skills/ph-cms-client');
   const skillMdPath = path.join(skillDir, 'SKILL.md');
 
   const skillContent = `# PH-CMS Client SDK Skill
@@ -75,5 +82,5 @@ If you need specific details about a module (e.g., \`ContentModule\`, \`AuthModu
   }
 
   fs.writeFileSync(skillMdPath, skillContent);
-  console.log('✅ PH-CMS Client SDK Skill has been successfully initialized at .gemini/skills/ph-cms-client/SKILL.md');
+  console.log(`✅ PH-CMS Client SDK Skill has been successfully initialized at ${path.join(baseDir, 'skills/ph-cms-client/SKILL.md')}`);
 }

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 });
     }
@@ -74,7 +94,9 @@ class AuthModule {
         }
         // Call the server endpoint to invalidate the session if applicable.
         // JWT-based auth is stateless, but the server may implement a blacklist.
-        await this.client.post(`${this.prefix}/auth/logout`).catch(() => { }); // Ignore error on logout
+        await this.client.post(`${this.prefix}/auth/logout`, null, {
+            headers: { 'Content-Type': 'application/json' },
+        }).catch(() => { }); // Ignore error on logout
     }
 }
 exports.AuthModule = AuthModule;

package/dist/modules/content.js

@@ -23,7 +23,9 @@ class ContentModule {
     async incrementView(uid) {
         if (!uid)
             throw new errors_1.ValidationError("UID is required", []);
-        await this.client.patch(`${this.prefix}/contents/${uid}/view`);
+        await this.client.patch(`${this.prefix}/contents/${uid}/view`, null, {
+            headers: { 'Content-Type': 'application/json' },
+        });
     }
     async create(data) {
         const validation = api_contract_1.CreateContentSchema.safeParse(data);
@@ -84,7 +86,9 @@ class ContentModule {
     async toggleLike(uid) {
         if (!uid)
             throw new errors_1.ValidationError("UID is required", []);
-        return this.client.post(`${this.prefix}/contents/${uid}/like`, {});
+        return this.client.post(`${this.prefix}/contents/${uid}/like`, null, {
+            headers: { 'Content-Type': 'application/json' },
+        });
     }
     async getLikeStatus(uid) {
         if (!uid)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ph-cms/client-sdk",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "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"