@ph-cms/client-sdk 0.1.49 → 0.1.50

package/README.md

@@ -1,4 +1,4 @@
-# @ph-cms/client-sdk 0.1.49
+# @ph-cms/client-sdk 0.1.51
 
 PH-CMS 클라이언트 SDK — 브라우저 및 React 애플리케이션을 위한 통합 클라이언트.
 
@@ -170,8 +170,41 @@ SDK의 인증 시스템은 세 개의 레이어로 구성됩니다:
 | `loginWithFirebase()` | `POST /api/auth/firebase/exchange` | `setTokens()` → `refreshUser()` |
 | `register()` (method: 'email') | `POST /api/auth/register` | `setTokens()` → `refreshUser()` |
 | `register()` (method: 'firebase') | `POST /api/auth/register` (provider: firebase:password) | `setTokens()` → `refreshUser()` |
+| `checkEmail()` | `GET /api/auth/check-email` | 중복 여부 확인용 |
 | `logout()` | `POST /api/auth/logout` | `provider.logout()` → `refreshUser()` (상태 초기화) |
 
+### Email Duplicate Check
+
+회원가입 전에 이메일 중복 여부와 소속 채널을 확인할 수 있습니다.
+
+`useAuth()`에서 바로 사용할 수 있습니다.
+
+```ts
+const { checkEmail, checkEmailStatus } = useAuth();
+
+const result = await checkEmail('user@example.com');
+```
+
+```ts
+{
+  email: 'user@example.com',
+  exists: true,
+  channels: [
+    {
+      channelUid: 'ch_xxx',
+      channelName: 'Seoul Channel',
+      channelSlug: 'seoul-channel',
+      relationType: 'member',
+      memberRole: 'manager'
+    }
+  ]
+}
+```
+
+- `exists: false` 이면 `channels` 는 빈 배열입니다.
+- `relationType` 은 `owner` 또는 `member` 입니다.
+- `memberRole` 은 채널 멤버인 경우에만 값이 있으며, 소유자인 경우 `null` 입니다.
+
 ### Authentication Lifecycle
 
 #### 1. 초기 마운트 (비인증 상태)
@@ -357,7 +390,9 @@ const client = new PHCMSClient({
 
 ### `FirebaseAuthProvider`
 
-Firebase Authentication과 연동합니다. PH-CMS 토큰이 없으면 Firebase ID 토큰으로 fallback합니다.
+Firebase Authentication과 연동합니다. PH-CMS access/refresh 토큰을 관리하며,
+`getToken()`은 PH-CMS access token만 반환합니다. PH-CMS 토큰이 없거나 만료되어 갱신에 실패하면 `null`을 반환합니다.
+Firebase ID 토큰이 필요하면 별도로 `getIdToken()`을 호출합니다.
 
 ```ts
 import { FirebaseAuthProvider, PHCMSClient } from '@ph-cms/client-sdk';
@@ -387,7 +422,13 @@ const client = new PHCMSClient({
 
 1. PH-CMS access token이 유효하면 → 그대로 반환
 2. 만료 임박이면 → `tryRefresh()` 시도 → 성공하면 새 토큰 반환
-3. PH-CMS 토큰이 없거나 갱신 실패 → Firebase ID 토큰으로 fallback
+3. PH-CMS access token이 없거나 갱신 실패 → `null` 반환
+
+Firebase ID token이 필요한 경우:
+
+```ts
+const firebaseIdToken = await authProvider.getIdToken();
+```
 
 ### `AuthProvider` Interface
 
@@ -506,6 +547,7 @@ function AuthComponent() {
     login,             // (data: LoginRequest) => Promise<AuthResponse>
     loginWithFirebase, // (data: FirebaseExchangeRequest) => Promise<AuthResponse>
     register,          // (data: RegisterInput) => Promise<AuthResponse>  ← method: 'email' | 'firebase'
+    checkEmail,        // (email: string) => Promise<CheckEmailResponse>
     loginAnonymous,    // (data?: AnonymousLoginRequest) => Promise<AuthResponse>
     upgradeAnonymous,  // (data: { email, password, display_name?, username?, phone_number? }) => Promise<UserDto>
     logout,            // () => Promise<void>
@@ -514,6 +556,7 @@ function AuthComponent() {
     loginStatus,
     loginWithFirebaseStatus,
     registerStatus,
+    checkEmailStatus,
     loginAnonymousStatus,
     upgradeAnonymousStatus,
     logoutStatus,
@@ -1855,10 +1898,19 @@ const result = await content.list({ channelUid: 'my-channel' });
 예시:
 
 ```ts
-await client.content.list({ withParent: true, withDetail: true, page: 1, limit: 20 });
+await client.content.list({
+  withParent: true,
+  withDetail: true,
+  page: 1,
+  limit: 20,
+  periodAt: '2026-06-10T00:00:00Z',
+});
 await client.content.get('cnt_123', { withParent: true, withDetail: true });
 ```
 
+`periodAt`은 `startAt` / `endAt`로 저장된 콘텐츠 기간을 기준으로 목록을 필터링할 때 사용합니다.
+예를 들어 `periodAt: '2026-06-10T00:00:00Z'`를 전달하면 해당 시점에 유효한 콘텐츠만 조회됩니다.
+
 ### `ChannelModule` (`client.channel`)
 
 | 메서드 | 설명 |

package/dist/hooks/useAuth.d.ts

@@ -168,6 +168,17 @@ export declare const useAuth: () => {
         };
         accessToken: string;
     }, Error, RegisterInput, unknown>;
+    checkEmail: import("@tanstack/react-query").UseMutateAsyncFunction<{
+        email: string;
+        exists: boolean;
+        channels: {
+            channelUid: string;
+            channelName: string;
+            channelSlug: string;
+            relationType: "owner" | "member";
+            memberRole: string | null;
+        }[];
+    }, Error, string, unknown>;
     loginAnonymous: import("@tanstack/react-query").UseMutateAsyncFunction<{
         refreshToken: string;
         user: {
@@ -365,6 +376,17 @@ export declare const useAuth: () => {
         };
         accessToken: string;
     }, Error, RegisterInput, unknown>;
+    checkEmailStatus: import("@tanstack/react-query").UseMutationResult<{
+        email: string;
+        exists: boolean;
+        channels: {
+            channelUid: string;
+            channelName: string;
+            channelSlug: string;
+            relationType: "owner" | "member";
+            memberRole: string | null;
+        }[];
+    }, Error, string, unknown>;
     loginAnonymousStatus: import("@tanstack/react-query").UseMutationResult<{
         refreshToken: string;
         user: {

package/dist/hooks/useAuth.js

@@ -46,6 +46,9 @@ const useAuth = () => {
             await refreshUser();
         },
     });
+    const checkEmailMutation = (0, react_query_1.useMutation)({
+        mutationFn: (email) => client.auth.checkEmail(email),
+    });
     const loginAnonymousMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.loginAnonymous({
             channelUid: data?.channelUid || channelUid,
@@ -75,6 +78,7 @@ const useAuth = () => {
         login: loginMutation.mutateAsync,
         loginWithFirebase: loginWithFirebaseMutation.mutateAsync,
         register: registerMutation.mutateAsync,
+        checkEmail: checkEmailMutation.mutateAsync,
         loginAnonymous: loginAnonymousMutation.mutateAsync,
         upgradeAnonymous: upgradeAnonymousMutation.mutateAsync,
         logout: logoutMutation.mutateAsync,
@@ -83,6 +87,7 @@ const useAuth = () => {
         loginStatus: loginMutation,
         loginWithFirebaseStatus: loginWithFirebaseMutation,
         registerStatus: registerMutation,
+        checkEmailStatus: checkEmailMutation,
         loginAnonymousStatus: loginAnonymousMutation,
         upgradeAnonymousStatus: upgradeAnonymousMutation,
         logoutStatus: logoutMutation,

package/dist/hooks/useContent.d.ts

@@ -17,6 +17,7 @@ export declare const contentKeys: {
         uids?: string[] | undefined;
         rootUid?: string | undefined;
         keyword?: string | undefined;
+        periodAt?: string | undefined;
         orderBy?: "title" | "created_at" | "updated_at" | "published_at" | "view_count" | "like_count" | undefined;
         orderDir?: "asc" | "desc" | undefined;
         includeDeleted?: boolean | undefined;
@@ -33,7 +34,7 @@ export declare const contentKeys: {
     likes: () => readonly ["contents", "like"];
     like: (uid: string) => readonly ["contents", "like", string];
 };
-export declare const useContentList: (params: ListContentQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useContentList: (params: ListContentQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     number: number;
     totalPages: number;
     content: ContentDto[];
@@ -42,11 +43,11 @@ export declare const useContentList: (params: ListContentQuery, enabled?: boolea
     first: boolean;
     last: boolean;
     empty: boolean;
-}, Error>;
+}>, Error>;
 export declare const useContentDetail: (uid: string, params?: {
     withParent?: boolean;
     withDetail?: boolean;
-}) => import("@tanstack/react-query").UseQueryResult<ContentDto, Error>;
+}) => import("@tanstack/react-query").UseQueryResult<NoInfer<ContentDto>, Error>;
 export declare const useIncrementView: () => import("@tanstack/react-query").UseMutationResult<void, Error, string, {
     previousDetail: ContentDto | undefined;
     uid: string;
@@ -74,10 +75,12 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
     parentUid?: string | undefined;
     sortOrder?: number | undefined;
     mediaAttachments?: string[] | undefined;
+    startAt?: string | null | undefined;
+    endAt?: string | null | undefined;
 }, unknown>;
-export declare const useLikeStatus: (uid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useLikeStatus: (uid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     liked: boolean;
-}, Error>;
+}>, Error>;
 export declare const useToggleLike: () => import("@tanstack/react-query").UseMutationResult<{
     liked: boolean;
     likeCount: number;

package/dist/hooks/useMedia.d.ts

@@ -18,7 +18,7 @@ export declare const useUploadToS3: () => import("@tanstack/react-query").UseMut
     url: string;
     file: File | Blob;
 }, unknown>;
-export declare const useMediaDetail: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useMediaDetail: (uid: string) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     type: "image" | "video" | "audio" | "document" | "file";
     url: string;
     uid: string;
@@ -29,4 +29,4 @@ export declare const useMediaDetail: (uid: string) => import("@tanstack/react-qu
     width?: number | undefined;
     height?: number | undefined;
     description?: string | null | undefined;
-}, Error>;
+}>, Error>;

package/dist/hooks/usePlace.d.ts

@@ -7,7 +7,7 @@ export declare const placeKeys: {
         lng?: number | undefined;
     }];
 };
-export declare const usePlaceSearch: (params: PlaceSearchQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const usePlaceSearch: (params: PlaceSearchQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     items: {
         id: string;
         provider: "google" | "naver";
@@ -35,4 +35,4 @@ export declare const usePlaceSearch: (params: PlaceSearchQuery, enabled?: boolea
         }[];
     }[];
     keyword: string;
-}, Error>;
+}>, Error>;

package/dist/hooks/useStampTour.d.ts

@@ -38,7 +38,7 @@ export declare const useStamp: () => import("@tanstack/react-query").UseMutation
     markerUid: string;
     data?: CollectStampRequest;
 }, unknown>;
-export declare const useStampStatus: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useStampStatus: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     total_markers: number;
     collected_markers: number;
     is_completed: boolean;
@@ -46,8 +46,8 @@ export declare const useStampStatus: (tourUid: string, enabled?: boolean) => imp
         marker_uid: string;
         collected_at: string;
     }[];
-}, Error>;
-export declare const useTourStats: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+}>, Error>;
+export declare const useTourStats: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     total_markers: number;
     tour_uid: string;
     tour_title: string;
@@ -60,7 +60,7 @@ export declare const useTourStats: (tourUid: string, enabled?: boolean) => impor
         marker_title: string;
         stamp_count: number;
     }[];
-}, Error>;
+}>, Error>;
 export interface StampAvailability {
     currentLocation?: {
         latitude: number;

package/dist/hooks/useUser.d.ts

@@ -60,24 +60,24 @@ export declare const useUser: () => {
 /**
  * Hook to fetch a user's public profile.
  */
-export declare const useUserProfile: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useUserProfile: (uid: string) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     uid: string;
     username: string | null;
     display_name: string;
     avatar_url: string | null;
     follower_count: number;
     profile_data: Record<string, any>;
-}, Error>;
+}>, Error>;
 /**
  * Hook to fetch follow status for a target user.
  */
-export declare const useFollowStatus: (uid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useFollowStatus: (uid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     is_following: boolean;
-}, Error>;
+}>, Error>;
 /**
  * Hook to fetch followers of a target user.
  */
-export declare const useFollowers: (uid: string, params?: Partial<ListUserFollowQuery>, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useFollowers: (uid: string, params?: Partial<ListUserFollowQuery>, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     items: {
         uid: string;
         username: string | null;
@@ -90,11 +90,11 @@ export declare const useFollowers: (uid: string, params?: Partial<ListUserFollow
     page: number;
     limit: number;
     totalPages: number;
-}, Error>;
+}>, Error>;
 /**
  * Hook to fetch followings of a target user.
  */
-export declare const useFollowings: (uid: string, params?: Partial<ListUserFollowQuery>, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useFollowings: (uid: string, params?: Partial<ListUserFollowQuery>, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     items: {
         uid: string;
         username: string | null;
@@ -107,7 +107,7 @@ export declare const useFollowings: (uid: string, params?: Partial<ListUserFollo
     page: number;
     limit: number;
     totalPages: number;
-}, Error>;
+}>, Error>;
 /**
  * Hook to update a user's profile.
  * Typically used by a user to update their own profile.
@@ -167,7 +167,7 @@ export declare const useUnfollowUser: () => import("@tanstack/react-query").UseM
 /**
  * Hook to fetch contents liked by a specific user.
  */
-export declare const useLikedContents: (uid: string, params?: Partial<ListLikedContentQuery>) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useLikedContents: (uid: string, params?: Partial<ListLikedContentQuery>) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     number: number;
     totalPages: number;
     content: import("@ph-cms/api-contract").ContentDto[];
@@ -176,18 +176,18 @@ export declare const useLikedContents: (uid: string, params?: Partial<ListLikedC
     first: boolean;
     last: boolean;
     empty: boolean;
-}, Error>;
+}>, Error>;
 /**
  * Hook to fetch statistics of liked contents by type for a specific user.
  */
-export declare const useLikedStats: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
+export declare const useLikedStats: (uid: string) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     type: string;
     count: number;
-}[], Error>;
+}[]>, Error>;
 /**
  * List terms required/available for the current channel.
  */
-export declare const useChannelTerms: () => import("@tanstack/react-query").UseQueryResult<{
+export declare const useChannelTerms: () => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     code: string;
     type: "text" | "url";
     id: number;
@@ -197,7 +197,7 @@ export declare const useChannelTerms: () => import("@tanstack/react-query").UseQ
     isActive: boolean;
     createdAt: string;
     isRequired?: boolean | undefined;
-}[], Error>;
+}[]>, Error>;
 /**
  * Submit term agreements for the current user.
  */
@@ -228,7 +228,7 @@ export declare const useUnblockUser: () => import("@tanstack/react-query").UseMu
 export declare const useBlockedUsers: (uid: string, params?: {
     page?: number;
     limit?: number;
-}) => import("@tanstack/react-query").UseQueryResult<{
+}) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
     items: {
         uid: string;
         username: string | null;
@@ -241,7 +241,7 @@ export declare const useBlockedUsers: (uid: string, params?: {
     page: number;
     limit: number;
     totalPages: number;
-}, Error>;
+}>, Error>;
 /**
  * Hook to suspend a user (Global Ban).
  * Admin only.

package/dist/modules/auth.d.ts

@@ -1,6 +1,52 @@
 import { AnonymousLoginRequest, AuthResponse, FirebaseExchangeRequest, FirebaseRegisterRequest, LoginRequest, RegisterRequest, UserDto } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
 import { AuthProvider } from "../auth/interfaces";
+import { z } from "zod";
+declare const CheckEmailResponseSchema: z.ZodObject<{
+    email: z.ZodString;
+    exists: z.ZodBoolean;
+    channels: z.ZodArray<z.ZodObject<{
+        channelUid: z.ZodString;
+        channelName: z.ZodString;
+        channelSlug: z.ZodString;
+        relationType: z.ZodEnum<["owner", "member"]>;
+        memberRole: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        channelUid: string;
+        channelName: string;
+        channelSlug: string;
+        relationType: "owner" | "member";
+        memberRole: string | null;
+    }, {
+        channelUid: string;
+        channelName: string;
+        channelSlug: string;
+        relationType: "owner" | "member";
+        memberRole: string | null;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+    exists: boolean;
+    channels: {
+        channelUid: string;
+        channelName: string;
+        channelSlug: string;
+        relationType: "owner" | "member";
+        memberRole: string | null;
+    }[];
+}, {
+    email: string;
+    exists: boolean;
+    channels: {
+        channelUid: string;
+        channelName: string;
+        channelSlug: string;
+        relationType: "owner" | "member";
+        memberRole: string | null;
+    }[];
+}>;
+type CheckEmailResponse = z.infer<typeof CheckEmailResponseSchema>;
+export type { CheckEmailResponse };
 export declare class AuthModule {
     private client;
     private provider?;
@@ -15,6 +61,7 @@ export declare class AuthModule {
      */
     loginWithFirebase(data: FirebaseExchangeRequest): Promise<AuthResponse>;
     register(data: RegisterRequest): Promise<AuthResponse>;
+    checkEmail(email: string): Promise<CheckEmailResponse>;
     /**
      * 서버 사이드 Firebase 회원가입.
      * 클라이언트는 idToken 없이 이메일/비밀번호를 전송하고,

package/dist/modules/auth.js

@@ -3,6 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthModule = void 0;
 const api_contract_1 = require("@ph-cms/api-contract");
 const errors_1 = require("../errors");
+const zod_1 = require("zod");
+const CheckEmailQuerySchema = zod_1.z.object({
+    email: zod_1.z.string().email(),
+});
+const EmailChannelAssociationSchema = zod_1.z.object({
+    channelUid: zod_1.z.string(),
+    channelName: zod_1.z.string(),
+    channelSlug: zod_1.z.string(),
+    relationType: zod_1.z.enum(["owner", "member"]),
+    memberRole: zod_1.z.string().nullable(),
+});
+const CheckEmailResponseSchema = zod_1.z.object({
+    email: zod_1.z.string().email(),
+    exists: zod_1.z.boolean(),
+    channels: zod_1.z.array(EmailChannelAssociationSchema),
+});
 class AuthModule {
     constructor(client, provider, prefix = '/api') {
         this.client = client;
@@ -48,6 +64,15 @@ class AuthModule {
         }
         return response;
     }
+    async checkEmail(email) {
+        const validation = CheckEmailQuerySchema.safeParse({ email });
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid email", validation.error.errors);
+        }
+        return this.client.get(`${this.prefix}/auth/check-email`, {
+            params: validation.data,
+        });
+    }
     /**
      * 서버 사이드 Firebase 회원가입.
      * 클라이언트는 idToken 없이 이메일/비밀번호를 전송하고,

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type { UserDto, UserProfileDto, FollowStatusResponse, FollowUserResponse,
 export type { ChannelContentCountDto, ChannelContentCountsQuery, ChannelContentCountsResponse, ChannelDto, ChannelPublicContentSummaryResponse, CheckHierarchyQuery, } from '@ph-cms/api-contract';
 export type { ContentDto, ContentStatDto, ContentMediaDto, ContentStatus, CreateContentRequest, ListContentQuery, PagedContentListResponse, UpdateContentRequest, } from '@ph-cms/api-contract';
 export type { HierarchySetDto } from '@ph-cms/api-contract';
-export type { PermissionPolicySetDto } from '@ph-cms/api-contract';
+export type { ChannelContentRolePolicy, PermissionAction, PermissionPolicyDocument, PermissionPolicySetDto, PermissionRule, } from '@ph-cms/api-contract';
 export type { TermDto } from '@ph-cms/api-contract';
 export type { GeoJSON } from '@ph-cms/api-contract';
 export type { MediaUploadTicketBatchRequest, MediaUploadTicketBatchResponse, MediaUploadTicketRequest, MediaUploadTicketResponse } from '@ph-cms/api-contract';

package/package.json

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