@ph-cms/client-sdk 0.1.15 → 0.1.17

package/README.md

@@ -382,12 +382,16 @@ function AuthComponent() {
     login,             // (data: LoginRequest) => Promise<AuthResponse>
     loginWithFirebase, // (data: FirebaseExchangeRequest) => Promise<AuthResponse>
     register,          // (data: RegisterRequest) => Promise<AuthResponse>
+    loginAnonymous,    // (data?: AnonymousLoginRequest) => Promise<AuthResponse>
+    upgradeAnonymous,  // (data: { email, password, display_name?, username? }) => Promise<UserDto>
     logout,            // () => Promise<void>
 
     // 뮤테이션 상태 (isPending, error 등)
     loginStatus,
     loginWithFirebaseStatus,
     registerStatus,
+    loginAnonymousStatus,
+    upgradeAnonymousStatus,
     logoutStatus,
   } = useAuth();
 }
@@ -457,6 +461,114 @@ function FirebaseLoginButton() {
 }
 ```
 
+#### 익명 회원가입
+
+이메일·비밀번호 없이 임시 계정을 생성합니다. 생성된 계정은 나중에 이메일 계정으로 전환할 수 있으며, 그 동안 쌓인 활동 히스토리(좋아요, 스탬프 등)는 그대로 유지됩니다.
+
+두 가지 방식이 있으며 **결과는 동일**합니다.
+
+---
+
+**방식 1 — 순수 익명 (Firebase 없이)**
+
+서버가 임시 계정(`provider: anonymous`)을 직접 생성합니다.
+
+```tsx
+function GuestButton() {
+  const { loginAnonymous, loginAnonymousStatus } = useAuth();
+
+  return (
+    <button
+      onClick={() => loginAnonymous()}
+      disabled={loginAnonymousStatus.isPending}
+    >
+      {loginAnonymousStatus.isPending ? '입장 중...' : '게스트로 시작하기'}
+    </button>
+  );
+}
+```
+
+`channelUid`는 `PHCMSProvider`에 설정된 값이 자동으로 사용됩니다. 직접 지정하려면 인자로 전달합니다:
+
+```ts
+await loginAnonymous({ channelUid: 'channel-uid', displayName: '손님1' });
+```
+
+---
+
+**방식 2 — Firebase 익명 (`signInAnonymously` 연동)**
+
+Firebase의 `signInAnonymously()`로 익명 인증을 먼저 수행한 뒤, 발급된 ID 토큰을 `loginAnonymous()`에 전달합니다. 서버는 이를 검증하여 `provider: firebase:anonymous` 계정을 생성합니다.
+
+이 방식은 Firebase 익명 계정을 나중에 `linkWithCredential()` 등으로 실계정에 연결하는 Firebase 네이티브 플로우와 함께 사용할 때 적합합니다.
+
+```tsx
+import { getAuth, signInAnonymously } from 'firebase/auth';
+
+function FirebaseGuestButton() {
+  const { loginAnonymous, loginAnonymousStatus } = useAuth();
+
+  const handleAnonymous = async () => {
+    const firebaseAuth = getAuth();
+    const { user } = await signInAnonymously(firebaseAuth);
+    const firebaseIdToken = await user.getIdToken();
+
+    await loginAnonymous({ firebaseIdToken });
+    // 성공 → 자동으로 me() 호출 → 인증 상태 갱신
+  };
+
+  return (
+    <button onClick={handleAnonymous} disabled={loginAnonymousStatus.isPending}>
+      {loginAnonymousStatus.isPending ? '입장 중...' : '게스트로 시작하기'}
+    </button>
+  );
+}
+```
+
+> **주의:** Firebase 익명 계정은 `POST /auth/firebase/exchange`(토큰 교환)로는 등록되지 않습니다.
+> 신규 익명 유저는 반드시 `loginAnonymous({ firebaseIdToken })`을 통해 등록해야 합니다.
+> `FirebaseAuthSync`를 사용하는 경우 이 분기가 자동으로 처리됩니다 ([Firebase Auth Sync](#firebase-auth-sync) 참고).
+
+---
+
+**익명 계정 → 이메일 계정 전환**
+
+`upgradeAnonymous()`를 호출하면 user ID를 유지한 채로 정식 이메일 계정으로 전환됩니다.
+
+```tsx
+function UpgradeForm() {
+  const { upgradeAnonymous, upgradeAnonymousStatus, user } = useAuth();
+
+  const handleUpgrade = async (email: string, password: string, displayName: string) => {
+    await upgradeAnonymous({ email, password, display_name: displayName });
+    // 성공 → role에서 'anonymous' 제거됨 → 기존 히스토리 유지
+  };
+
+  if (!user?.role.includes('anonymous')) return null;
+
+  return (
+    <form onSubmit={e => {
+      e.preventDefault();
+      const fd = new FormData(e.currentTarget);
+      handleUpgrade(
+        fd.get('email') as string,
+        fd.get('password') as string,
+        fd.get('display_name') as string,
+      );
+    }}>
+      <input name="email" type="email" placeholder="이메일" />
+      <input name="password" type="password" placeholder="비밀번호" />
+      <input name="display_name" placeholder="이름" />
+      <button type="submit" disabled={upgradeAnonymousStatus.isPending}>
+        {upgradeAnonymousStatus.isPending ? '전환 중...' : '계정 만들기'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
 #### 회원가입
 
 ```tsx
@@ -645,7 +757,15 @@ Firebase onAuthStateChanged
   │
   ├─ fbUser 존재 + PH-CMS 비인증 상태
   │   → fbUser.getIdToken()
-  │   → client.auth.loginWithFirebase({ idToken })
+  │   │
+  │   ├─ fbUser.isAnonymous === true
+  │   │   → client.auth.loginAnonymous({ channelUid, firebaseIdToken })
+  │   │       ※ POST /auth/anonymous  (등록 또는 기존 계정 토큰 재발급)
+  │   │
+  │   └─ fbUser.isAnonymous === false  (Google, 이메일 등)
+  │       → client.auth.loginWithFirebase({ idToken })
+  │           ※ POST /auth/firebase/exchange  (기존 유저 로그인 전용)
+  │
   │   → provider.setTokens(...)
   │   → refreshUser()  ← me() 호출하여 프로필 로드
   │
@@ -654,6 +774,10 @@ Firebase onAuthStateChanged
       → refreshUser()  ← 상태 초기화
 ```
 
+> `POST /auth/firebase/exchange`는 **기존 유저 로그인 전용**입니다.
+> 신규 익명 유저를 이 엔드포인트로 생성하려 하면 서버가 에러를 반환합니다.
+> `FirebaseAuthSync`를 사용하면 익명/비익명 분기가 자동으로 처리됩니다.
+
 #### `<FirebaseAuthSync>` 컴포넌트
 
 `<PHCMSProvider>` 안에서 사용합니다:

package/bin/cli.js

@@ -59,6 +59,12 @@ const { data: terms } = useChannelTerms();
 const { mutate: agree } = useAgreeTerms();
 \`\`\`
 
+## 📚 Detailed Documentation
+For the complete API reference, advanced configuration, and comprehensive examples, always refer to the full documentation:
+- **Location**: \`node_modules/@ph-cms/client-sdk/README.md\`
+
+If you need specific details about a module (e.g., \`ContentModule\`, \`AuthModule\`), read that file to ensure correct parameter usage.
+
 ## ⚠️ Common Pitfalls
 - **Manual channelUid passing**: Avoid \`useContentList({ channelUid: '...', ... })\` unless necessary. Rely on the provider.
 - **Hook-less API calls**: When using \`client.content.list()\` directly, you MUST provide \`channelUid\` in the params as there is no context available.

package/dist/hooks/useContent.d.ts

@@ -8,8 +8,8 @@ export declare const contentKeys: {
         status?: string | undefined;
         type?: string | undefined;
         channelUid?: string | undefined;
-        tags?: string[] | undefined;
         channelSlug?: string | undefined;
+        tags?: string[] | undefined;
         parentUid?: string | undefined;
         authorUid?: string | undefined;
         uids?: string[] | undefined;
@@ -45,6 +45,7 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
     title: string;
     status?: string | undefined;
     channelUid?: string | undefined;
+    channelSlug?: string | undefined;
     geometry?: {
         type: "Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon" | "GeometryCollection" | "Feature" | "FeatureCollection";
         coordinates?: any[] | undefined;
@@ -59,7 +60,6 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
     summary?: string | null | undefined;
     slug?: string | null | undefined;
     tags?: string[] | undefined;
-    channelSlug?: string | undefined;
     parentUid?: string | undefined;
     sortOrder?: number | undefined;
     mediaAttachments?: string[] | undefined;

package/dist/hooks/useFirebaseAuthSync.js

@@ -106,9 +106,15 @@ const useFirebaseAuthSync = (options) => {
                 setIsSyncing(true);
                 try {
                     const idToken = await fbUser.getIdToken();
-                    await client.auth.loginWithFirebase({ idToken, channelUid });
-                    // loginWithFirebase stores the tokens in the provider.
-                    // Now refresh the context so `isAuthenticated` and `user` update.
+                    if (fbUser.isAnonymous) {
+                        // 익명 유저는 POST /auth/anonymous 로 등록/로그인
+                        await client.auth.loginAnonymous({ channelUid, firebaseIdToken: idToken });
+                    }
+                    else {
+                        // 일반 Firebase 유저는 토큰 교환 (기존 유저 로그인)
+                        await client.auth.loginWithFirebase({ idToken, channelUid });
+                    }
+                    // Refresh the context so `isAuthenticated` and `user` update.
                     await refreshUser();
                     onSyncSuccessRef.current?.();
                 }

package/dist/hooks/useStampTour.d.ts

@@ -11,6 +11,7 @@ export declare const useCreateStampTour: () => import("@tanstack/react-query").U
     markerUids: string[];
     status?: string | undefined;
     channelUid?: string | undefined;
+    channelSlug?: string | undefined;
     geometry?: {
         type: "Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon" | "GeometryCollection" | "Feature" | "FeatureCollection";
         coordinates?: any[] | undefined;
@@ -22,7 +23,6 @@ export declare const useCreateStampTour: () => import("@tanstack/react-query").U
     image?: string | null | undefined;
     summary?: string | null | undefined;
     tags?: string[] | undefined;
-    channelSlug?: string | undefined;
     startsAt?: string | null | undefined;
     endsAt?: string | null | undefined;
 }, unknown>;

package/package.json

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