@ph-cms/client-sdk 0.1.49 → 0.1.51

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 애플리케이션을 위한 통합 클라이언트.
 
@@ -106,9 +106,22 @@ import type {
   // Common
   PagedResponse,
   UserProfileDto,
+  UserSearchResultDto,
   IntegratedPlace,
   PlaceSearchQuery,
   PlaceSearchResponse,
+
+  // User Group
+  UserGroupDto,
+  UserGroupMembershipDto,
+  UserGroupInviteDto,
+  UserGroupInviteStatus,
+  ListUserGroupQuery,
+  GetMyUserGroupMembershipResponse,
+  PagedMyGroupInviteListResponse,
+  JoinUserGroupResponse,
+  LeaveUserGroupResponse,
+  RespondInviteResponse,
 } from '@ph-cms/client-sdk';
 ```
 
@@ -170,8 +183,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 +403,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 +435,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 +560,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 +569,7 @@ function AuthComponent() {
     loginStatus,
     loginWithFirebaseStatus,
     registerStatus,
+    checkEmailStatus,
     loginAnonymousStatus,
     upgradeAnonymousStatus,
     logoutStatus,
@@ -1794,7 +1850,7 @@ const result = await content.list({ channelUid: 'my-channel' });
 | 카테고리 | export 항목 |
 |---|---|
 | 클라이언트 | `PHCMSClient` |
-| 모듈 | `ContentModule`, `AuthModule`, `UserModule`, `ChannelModule`, `MediaModule`, `TermsModule` |
+| 모듈 | `ContentModule`, `AuthModule`, `UserModule`, `ChannelModule`, `MediaModule`, `TermsModule`, `UserGroupModule` |
 | Auth 프로바이더 | `BaseAuthProvider`, `LocalAuthProvider`, `JwtUtils` |
 | 타입/에러 | `PHCMSClientError`, 각종 DTO/Request 타입 |
 
@@ -1805,6 +1861,7 @@ const result = await content.list({ channelUid: 'my-channel' });
 | 메서드 | 설명 |
 |---|---|
 | `getProfile(uid: string)` | 유저의 공개 프로필 정보 조회 → `UserProfileDto` |
+| `search(query, params?)` | 이름/아이디/이메일 키워드로 사용자 검색 → `UserSearchResultDto[]` |
 | `getFollowStatus(uid: string)` | 현재 로그인 사용자의 대상 유저 팔로우 상태 조회 → `FollowStatusResponse` |
 | `follow(uid: string)` | 특정 사용자 팔로우 → `FollowUserResponse` |
 | `unfollow(uid: string)` | 특정 사용자 언팔로우 → `FollowUserResponse` |
@@ -1819,6 +1876,18 @@ const result = await content.list({ channelUid: 'my-channel' });
 | `suspend(uid: string, data?: SuspendUserRequest)` | 유저 활동 정지 (글로벌 밴) → `SuspendUserResponse` |
 | `unsuspend(uid: string)` | 유저 활동 정지 해제 → `SuspendUserResponse` |
 
+예시:
+
+```ts
+const users = await client.user.search('hong', { limit: 10 });
+```
+
+React hook 예시:
+
+```ts
+const { data: users } = useUserSearch('hong', { limit: 10 });
+```
+
 ### `AuthModule` (`client.auth`)
 
 | 메서드 | 설명 |
@@ -1855,10 +1924,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`)
 
 | 메서드 | 설명 |
@@ -1878,6 +1956,46 @@ await client.content.get('cnt_123', { withParent: true, withDetail: true });
 | `agree(data: { termCodes: string[]; channelUid?: string })` | 약관 동의 제출 |
 | `listByChannel(channelUid: string)` | 채널별 약관 목록 조회 |
 
+### `UserGroupModule` (`client.userGroup`)
+
+| 메서드 | 설명 |
+|---|---|
+| `listByBaseContent(baseContentUid, params?)` | 기준 콘텐츠에 연결된 공개 그룹 목록 조회 → `PagedUserGroupListResponse` |
+| `getMyMembership(baseContentUid, groupUid)` | 현재 사용자의 특정 그룹 가입 여부 조회 → `GetMyUserGroupMembershipResponse` |
+| `join(baseContentUid, groupUid)` | 그룹 self join → `JoinUserGroupResponse` |
+| `leave(baseContentUid, groupUid)` | 그룹 탈퇴 → `LeaveUserGroupResponse` |
+| `listMine(params?)` | 현재 사용자가 가입한 그룹 목록 조회 → `PagedMyUserGroupMembershipListResponse` |
+| `listMyInvites(params?)` | 현재 사용자의 그룹 초대 목록 조회 → `PagedMyGroupInviteListResponse` |
+| `acceptInvite(inviteUid)` | 그룹 초대 수락 → `RespondInviteResponse` |
+| `declineInvite(inviteUid)` | 그룹 초대 거절 → `RespondInviteResponse` |
+
+예시:
+
+```ts
+const groups = await client.userGroup.listByBaseContent(baseContentUid, {
+  limit: 20,
+  offset: 0,
+});
+
+const joined = await client.userGroup.join(baseContentUid, groupUid);
+
+const invites = await client.userGroup.listMyInvites({ limit: 20, offset: 0 });
+
+await client.userGroup.acceptInvite('invite_123');
+await client.userGroup.declineInvite('invite_123');
+```
+
+React hook 예시:
+
+```ts
+const { data: myInvites } = useMyUserGroupInvites({ limit: 20 });
+const acceptInvite = useAcceptUserGroupInvite();
+const declineInvite = useDeclineUserGroupInvite();
+
+await acceptInvite.mutateAsync({ inviteUid: 'inv_123' });
+await declineInvite.mutateAsync({ inviteUid: 'inv_123' });
+```
+
 ### JWT Utilities
 
 클라이언트에서 토큰 상태를 확인할 수 있는 유틸리티입니다 (서명 검증은 하지 않음).

package/dist/client.d.ts

@@ -6,6 +6,7 @@ import { ContentModule } from './modules/content';
 import { MediaModule } from './modules/media';
 import { PlaceModule } from './modules/place';
 import { TermsModule } from './modules/terms';
+import { UserGroupModule } from './modules/user-group';
 import { UserModule } from './modules/user';
 export interface PHCMSClientConfig {
     baseURL: string;
@@ -28,6 +29,7 @@ export declare class PHCMSClient {
     readonly media: MediaModule;
     readonly place: PlaceModule;
     readonly user: UserModule;
+    readonly userGroup: UserGroupModule;
     /**
      * Whether a token refresh is currently in flight (used by the 401
      * interceptor to de-duplicate concurrent refresh attempts).

package/dist/client.js

@@ -13,6 +13,7 @@ const content_1 = require("./modules/content");
 const media_1 = require("./modules/media");
 const place_1 = require("./modules/place");
 const terms_1 = require("./modules/terms");
+const user_group_1 = require("./modules/user-group");
 const user_1 = require("./modules/user");
 class PHCMSClient {
     /** Exposes the auth provider so UI layers can check token state synchronously. */
@@ -71,6 +72,7 @@ class PHCMSClient {
         this.media = new media_1.MediaModule(this.axiosInstance, normalizedApiPrefix);
         this.place = new place_1.PlaceModule(this.axiosInstance, normalizedApiPrefix);
         this.user = new user_1.UserModule(this.axiosInstance, normalizedApiPrefix);
+        this.userGroup = new user_group_1.UserGroupModule(this.axiosInstance, normalizedApiPrefix);
         // Wire the refresh function into the auth provider so it can
         // proactively refresh tokens inside `getToken()` without needing
         // a direct reference to the AuthModule / axios instance.

package/dist/core.d.ts

@@ -10,5 +10,6 @@ export * from './modules/content';
 export * from './modules/media';
 export * from './modules/place';
 export * from './modules/terms';
+export * from './modules/user-group';
 export * from './modules/user';
 export * from './types';

package/dist/core.js

@@ -29,5 +29,6 @@ __exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/media"), exports);
 __exportStar(require("./modules/place"), exports);
 __exportStar(require("./modules/terms"), exports);
+__exportStar(require("./modules/user-group"), exports);
 __exportStar(require("./modules/user"), exports);
 __exportStar(require("./types"), exports);

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

@@ -1,4 +1,5 @@
 import { ListLikedContentQuery, ListUserFollowQuery, UpdateUserProfileRequest, BlockUserRequest, SuspendUserRequest } from '@ph-cms/api-contract';
+import { UserSearchResultDto } from '../types';
 export declare const termsKeys: {
     all: readonly ["terms"];
     lists: () => readonly ["terms", "list"];
@@ -15,6 +16,11 @@ export declare const userKeys: {
         page: number;
         limit: number;
     }>];
+    search: (query: string, params: {
+        limit?: number;
+    }) => readonly ["users", "search", string, {
+        limit?: number;
+    }];
 };
 /**
  * Access the current user profile and status.
@@ -60,24 +66,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 +96,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 +113,13 @@ export declare const useFollowings: (uid: string, params?: Partial<ListUserFollo
     page: number;
     limit: number;
     totalPages: number;
-}, Error>;
+}>, Error>;
+/**
+ * Hook to search users by keyword.
+ */
+export declare const useUserSearch: (query: string, params?: {
+    limit?: number;
+}, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<UserSearchResultDto[]>, Error>;
 /**
  * Hook to update a user's profile.
  * Typically used by a user to update their own profile.
@@ -167,7 +179,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 +188,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 +209,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 +240,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 +253,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/hooks/useUser.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useUnsuspendUser = exports.useSuspendUser = exports.useBlockedUsers = exports.useUnblockUser = exports.useBlockUser = exports.useAgreeTerms = exports.useChannelTerms = exports.useLikedStats = exports.useLikedContents = exports.useUnfollowUser = exports.useFollowUser = exports.useUpdateProfile = exports.useFollowings = exports.useFollowers = exports.useFollowStatus = exports.useUserProfile = exports.useUser = exports.userKeys = exports.termsKeys = void 0;
+exports.useUnsuspendUser = exports.useSuspendUser = exports.useBlockedUsers = exports.useUnblockUser = exports.useBlockUser = exports.useAgreeTerms = exports.useChannelTerms = exports.useLikedStats = exports.useLikedContents = exports.useUnfollowUser = exports.useFollowUser = exports.useUpdateProfile = exports.useUserSearch = exports.useFollowings = exports.useFollowers = exports.useFollowStatus = exports.useUserProfile = exports.useUser = exports.userKeys = exports.termsKeys = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
 exports.termsKeys = {
@@ -13,6 +13,7 @@ exports.userKeys = {
     followStatus: (uid) => [...exports.userKeys.all, 'follow-status', uid],
     followers: (uid, params) => [...exports.userKeys.all, 'followers', uid, params],
     followings: (uid, params) => [...exports.userKeys.all, 'followings', uid, params],
+    search: (query, params) => [...exports.userKeys.all, 'search', query, params],
 };
 /**
  * Access the current user profile and status.
@@ -70,6 +71,19 @@ const useFollowings = (uid, params = {}, enabled = true) => {
     });
 };
 exports.useFollowings = useFollowings;
+/**
+ * Hook to search users by keyword.
+ */
+const useUserSearch = (query, params = {}, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    const normalizedQuery = query.trim();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.userKeys.search(normalizedQuery, params),
+        queryFn: () => client.user.search(normalizedQuery, params),
+        enabled: !!normalizedQuery && enabled,
+    });
+};
+exports.useUserSearch = useUserSearch;
 /**
  * Hook to update a user's profile.
  * Typically used by a user to update their own profile.

package/dist/hooks/useUserGroup.d.ts

@@ -0,0 +1,122 @@
+import { ListUserGroupQuery } from "@ph-cms/api-contract";
+export declare const userGroupKeys: {
+    all: readonly ["user-groups"];
+    publicLists: () => readonly ["user-groups", "public", "list"];
+    publicListPrefix: (baseContentUid: string) => readonly ["user-groups", "public", "list", string];
+    publicList: (baseContentUid: string, params?: ListUserGroupQuery) => readonly ["user-groups", "public", "list", string, {
+        limit?: number | undefined;
+        offset?: number | undefined;
+    }];
+    myMembership: (baseContentUid: string, groupUid: string) => readonly ["user-groups", "me", string, string];
+    myGroups: (params?: ListUserGroupQuery) => readonly ["user-groups", "my-groups", {
+        limit?: number | undefined;
+        offset?: number | undefined;
+    }];
+    myInvites: (params?: ListUserGroupQuery) => readonly ["user-groups", "my-invites", {
+        limit?: number | undefined;
+        offset?: number | undefined;
+    }];
+};
+export declare const useBaseContentUserGroups: (baseContentUid: string, params?: ListUserGroupQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    items: {
+        isActive: boolean;
+        createdAt: string;
+        uid: string;
+        channelUid: string;
+        name: string;
+        description: string | null;
+        baseContentUid: string;
+        groupCode: string;
+        joinMode: "open" | "invite_only" | "approval";
+        updatedAt: string;
+        joined?: boolean | undefined;
+    }[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}>, Error>;
+export declare const useMyUserGroupMembership: (baseContentUid: string, groupUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    isJoined: boolean;
+    membership: {
+        baseContentUid: string;
+        groupCode: string;
+        membershipUid: string;
+        groupUid: string;
+        groupName: string;
+        baseContentType: string;
+        baseContentTitle: string;
+        baseContentImage: string | null;
+        baseContentSlug: string | null;
+        joinedAt: string;
+    } | null;
+}>, Error>;
+export declare const useMyUserGroups: (params?: ListUserGroupQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    items: {
+        baseContentUid: string;
+        groupCode: string;
+        membershipUid: string;
+        groupUid: string;
+        groupName: string;
+        baseContentType: string;
+        baseContentTitle: string;
+        baseContentImage: string | null;
+        baseContentSlug: string | null;
+        joinedAt: string;
+    }[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}>, Error>;
+export declare const useMyUserGroupInvites: (params?: ListUserGroupQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    items: {
+        status: "pending" | "accepted" | "declined";
+        createdAt: string;
+        uid: string;
+        baseContentUid: string;
+        groupCode: string;
+        updatedAt: string;
+        groupUid: string;
+        groupName: string;
+        inviterUid: string;
+    }[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}>, Error>;
+export declare const useJoinUserGroup: () => import("@tanstack/react-query").UseMutationResult<{
+    joined: boolean;
+    membership: {
+        baseContentUid: string;
+        groupCode: string;
+        membershipUid: string;
+        groupUid: string;
+        groupName: string;
+        baseContentType: string;
+        baseContentTitle: string;
+        baseContentImage: string | null;
+        baseContentSlug: string | null;
+        joinedAt: string;
+    };
+}, Error, {
+    baseContentUid: string;
+    groupUid: string;
+}, unknown>;
+export declare const useLeaveUserGroup: () => import("@tanstack/react-query").UseMutationResult<{
+    left: boolean;
+}, Error, {
+    baseContentUid: string;
+    groupUid: string;
+}, unknown>;
+export declare const useAcceptUserGroupInvite: () => import("@tanstack/react-query").UseMutationResult<{
+    success: boolean;
+}, Error, {
+    inviteUid: string;
+}, unknown>;
+export declare const useDeclineUserGroupInvite: () => import("@tanstack/react-query").UseMutationResult<{
+    success: boolean;
+}, Error, {
+    inviteUid: string;
+}, unknown>;

package/dist/hooks/useUserGroup.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDeclineUserGroupInvite = exports.useAcceptUserGroupInvite = exports.useLeaveUserGroup = exports.useJoinUserGroup = exports.useMyUserGroupInvites = exports.useMyUserGroups = exports.useMyUserGroupMembership = exports.useBaseContentUserGroups = exports.userGroupKeys = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("../context");
+exports.userGroupKeys = {
+    all: ["user-groups"],
+    publicLists: () => [...exports.userGroupKeys.all, "public", "list"],
+    publicListPrefix: (baseContentUid) => [...exports.userGroupKeys.publicLists(), baseContentUid],
+    publicList: (baseContentUid, params = {}) => [...exports.userGroupKeys.publicLists(), baseContentUid, params],
+    myMembership: (baseContentUid, groupUid) => [...exports.userGroupKeys.all, "me", baseContentUid, groupUid],
+    myGroups: (params = {}) => [...exports.userGroupKeys.all, "my-groups", params],
+    myInvites: (params = {}) => [...exports.userGroupKeys.all, "my-invites", params],
+};
+const useBaseContentUserGroups = (baseContentUid, params = {}, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.userGroupKeys.publicList(baseContentUid, params),
+        queryFn: () => client.userGroup.listByBaseContent(baseContentUid, params),
+        enabled: !!baseContentUid && enabled,
+    });
+};
+exports.useBaseContentUserGroups = useBaseContentUserGroups;
+const useMyUserGroupMembership = (baseContentUid, groupUid, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.userGroupKeys.myMembership(baseContentUid, groupUid),
+        queryFn: () => client.userGroup.getMyMembership(baseContentUid, groupUid),
+        enabled: !!baseContentUid && !!groupUid && enabled,
+    });
+};
+exports.useMyUserGroupMembership = useMyUserGroupMembership;
+const useMyUserGroups = (params = {}, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.userGroupKeys.myGroups(params),
+        queryFn: () => client.userGroup.listMine(params),
+        enabled,
+    });
+};
+exports.useMyUserGroups = useMyUserGroups;
+const useMyUserGroupInvites = (params = {}, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.userGroupKeys.myInvites(params),
+        queryFn: () => client.userGroup.listMyInvites(params),
+        enabled,
+    });
+};
+exports.useMyUserGroupInvites = useMyUserGroupInvites;
+const useJoinUserGroup = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ baseContentUid, groupUid }) => client.userGroup.join(baseContentUid, groupUid),
+        onSuccess: (_data, variables) => {
+            queryClient.invalidateQueries({
+                queryKey: exports.userGroupKeys.publicListPrefix(variables.baseContentUid),
+            });
+            queryClient.invalidateQueries({
+                queryKey: exports.userGroupKeys.myMembership(variables.baseContentUid, variables.groupUid),
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "my-groups"],
+            });
+        },
+    });
+};
+exports.useJoinUserGroup = useJoinUserGroup;
+const useLeaveUserGroup = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ baseContentUid, groupUid }) => client.userGroup.leave(baseContentUid, groupUid),
+        onSuccess: (_data, variables) => {
+            queryClient.invalidateQueries({
+                queryKey: exports.userGroupKeys.publicListPrefix(variables.baseContentUid),
+            });
+            queryClient.invalidateQueries({
+                queryKey: exports.userGroupKeys.myMembership(variables.baseContentUid, variables.groupUid),
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "my-groups"],
+            });
+        },
+    });
+};
+exports.useLeaveUserGroup = useLeaveUserGroup;
+const useAcceptUserGroupInvite = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ inviteUid }) => client.userGroup.acceptInvite(inviteUid),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "my-invites"],
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "my-groups"],
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "public", "list"],
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "me"],
+            });
+        },
+    });
+};
+exports.useAcceptUserGroupInvite = useAcceptUserGroupInvite;
+const useDeclineUserGroupInvite = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ inviteUid }) => client.userGroup.declineInvite(inviteUid),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "my-invites"],
+            });
+            queryClient.invalidateQueries({
+                queryKey: [...exports.userGroupKeys.all, "me"],
+            });
+        },
+    });
+};
+exports.useDeclineUserGroupInvite = useDeclineUserGroupInvite;

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from './modules/content';
 export * from './modules/media';
 export * from './modules/place';
 export * from './modules/terms';
+export * from './modules/user-group';
 export * from './modules/user';
 export * from './context';
 export * from './hooks/useAuth';
@@ -20,5 +21,6 @@ export * from './hooks/useStampTour';
 export * from './hooks/useFirebaseAuthSync';
 export * from './hooks/useMedia';
 export * from './hooks/usePlace';
+export * from './hooks/useUserGroup';
 export * from './hooks/useUser';
 export * from './types';

package/dist/index.js

@@ -28,6 +28,7 @@ __exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/media"), exports);
 __exportStar(require("./modules/place"), exports);
 __exportStar(require("./modules/terms"), exports);
+__exportStar(require("./modules/user-group"), exports);
 __exportStar(require("./modules/user"), exports);
 __exportStar(require("./context"), exports);
 __exportStar(require("./hooks/useAuth"), exports);
@@ -36,5 +37,6 @@ __exportStar(require("./hooks/useStampTour"), exports);
 __exportStar(require("./hooks/useFirebaseAuthSync"), exports);
 __exportStar(require("./hooks/useMedia"), exports);
 __exportStar(require("./hooks/usePlace"), exports);
+__exportStar(require("./hooks/useUserGroup"), exports);
 __exportStar(require("./hooks/useUser"), exports);
 __exportStar(require("./types"), exports);

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/modules/user-group.d.ts

@@ -0,0 +1,15 @@
+import { GetMyUserGroupMembershipResponse, JoinUserGroupResponse, LeaveUserGroupResponse, ListUserGroupQuery, PagedMyGroupInviteListResponse, PagedMyUserGroupMembershipListResponse, PagedUserGroupListResponse, RespondInviteResponse } from "@ph-cms/api-contract";
+import { AxiosInstance } from "axios";
+export declare class UserGroupModule {
+    private client;
+    private prefix;
+    constructor(client: AxiosInstance, prefix?: string);
+    listByBaseContent(baseContentUid: string, params?: ListUserGroupQuery): Promise<PagedUserGroupListResponse>;
+    getMyMembership(baseContentUid: string, groupUid: string): Promise<GetMyUserGroupMembershipResponse>;
+    join(baseContentUid: string, groupUid: string): Promise<JoinUserGroupResponse>;
+    leave(baseContentUid: string, groupUid: string): Promise<LeaveUserGroupResponse>;
+    listMine(params?: ListUserGroupQuery): Promise<PagedMyUserGroupMembershipListResponse>;
+    listMyInvites(params?: ListUserGroupQuery): Promise<PagedMyGroupInviteListResponse>;
+    acceptInvite(inviteUid: string): Promise<RespondInviteResponse>;
+    declineInvite(inviteUid: string): Promise<RespondInviteResponse>;
+}

package/dist/modules/user-group.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserGroupModule = void 0;
+const api_contract_1 = require("@ph-cms/api-contract");
+const errors_1 = require("../errors");
+class UserGroupModule {
+    constructor(client, prefix = "/api") {
+        this.client = client;
+        this.prefix = prefix;
+    }
+    async listByBaseContent(baseContentUid, params = {}) {
+        if (!baseContentUid)
+            throw new errors_1.ValidationError("Base content UID is required", []);
+        const validation = api_contract_1.ListUserGroupQuerySchema.safeParse(params);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid user group list params", validation.error.errors);
+        }
+        return this.client.get(`${this.prefix}/contents/${baseContentUid}/user-groups`, { params: validation.data });
+    }
+    async getMyMembership(baseContentUid, groupUid) {
+        if (!baseContentUid)
+            throw new errors_1.ValidationError("Base content UID is required", []);
+        if (!groupUid)
+            throw new errors_1.ValidationError("Group UID is required", []);
+        return this.client.get(`${this.prefix}/contents/${baseContentUid}/user-groups/${groupUid}/me`);
+    }
+    async join(baseContentUid, groupUid) {
+        if (!baseContentUid)
+            throw new errors_1.ValidationError("Base content UID is required", []);
+        if (!groupUid)
+            throw new errors_1.ValidationError("Group UID is required", []);
+        return this.client.post(`${this.prefix}/contents/${baseContentUid}/user-groups/${groupUid}/join`);
+    }
+    async leave(baseContentUid, groupUid) {
+        if (!baseContentUid)
+            throw new errors_1.ValidationError("Base content UID is required", []);
+        if (!groupUid)
+            throw new errors_1.ValidationError("Group UID is required", []);
+        return this.client.delete(`${this.prefix}/contents/${baseContentUid}/user-groups/${groupUid}/join`);
+    }
+    async listMine(params = {}) {
+        const validation = api_contract_1.ListUserGroupQuerySchema.safeParse(params);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid my user group list params", validation.error.errors);
+        }
+        return this.client.get(`${this.prefix}/me/user-groups`, { params: validation.data });
+    }
+    async listMyInvites(params = {}) {
+        const validation = api_contract_1.ListUserGroupQuerySchema.safeParse(params);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid my user group invite list params", validation.error.errors);
+        }
+        return this.client.get(`${this.prefix}/me/group-invites`, { params: validation.data });
+    }
+    async acceptInvite(inviteUid) {
+        if (!inviteUid)
+            throw new errors_1.ValidationError("Invite UID is required", []);
+        return this.client.post(`${this.prefix}/me/group-invites/${inviteUid}/accept`);
+    }
+    async declineInvite(inviteUid) {
+        if (!inviteUid)
+            throw new errors_1.ValidationError("Invite UID is required", []);
+        return this.client.post(`${this.prefix}/me/group-invites/${inviteUid}/decline`);
+    }
+}
+exports.UserGroupModule = UserGroupModule;

package/dist/modules/user.d.ts

@@ -1,5 +1,6 @@
 import { LikedStatsByTypeResponse, ListLikedContentQuery, ListUserFollowQuery, PagedContentListResponse, PagedUserProfileListResponse, UpdateUserProfileRequest, UserDto, UserProfileDto, FollowStatusResponse, FollowUserResponse, BlockUserRequest, BlockUserResponse, PagedBlockedUserListResponse, SuspendUserRequest, SuspendUserResponse } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
+import { UserSearchResultDto } from "../types";
 export declare class UserModule {
     private client;
     private prefix;
@@ -42,6 +43,15 @@ export declare class UserModule {
      * @param params - Paging parameters.
      */
     getFollowings(uid: string, params?: Partial<ListUserFollowQuery>): Promise<PagedUserProfileListResponse>;
+    /**
+     * Searches users by name, username, or email keyword.
+     *
+     * @param query - Search keyword.
+     * @param params - Optional search limits.
+     */
+    search(query: string, params?: {
+        limit?: number;
+    }): Promise<UserSearchResultDto[]>;
     /**
      * Updates a user's profile.
      *

package/dist/modules/user.js

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserModule = void 0;
 const api_contract_1 = require("@ph-cms/api-contract");
+const zod_1 = require("zod");
 const errors_1 = require("../errors");
+const UserSearchQuerySchema = zod_1.z.object({
+    limit: zod_1.z.coerce.number().int().min(1).max(10).optional(),
+});
 class UserModule {
     constructor(client, prefix = '/api') {
         this.client = client;
@@ -76,6 +80,27 @@ class UserModule {
         }
         return this.client.get(`${this.prefix}/users/${uid}/followings`, { params: validation.data });
     }
+    /**
+     * Searches users by name, username, or email keyword.
+     *
+     * @param query - Search keyword.
+     * @param params - Optional search limits.
+     */
+    async search(query, params = {}) {
+        const keyword = query.trim();
+        if (!keyword)
+            throw new errors_1.ValidationError("Query is required", []);
+        const validation = UserSearchQuerySchema.safeParse(params);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid user search params", validation.error.errors);
+        }
+        return this.client.get(`${this.prefix}/users/search`, {
+            params: {
+                q: keyword,
+                ...validation.data,
+            },
+        });
+    }
     /**
      * Updates a user's profile.
      *

package/dist/types.d.ts

@@ -2,6 +2,12 @@ export type { AuthProvider } from './auth/interfaces';
 export type { JwtPayload } from './auth/jwt-utils';
 export type { PHCMSClientConfig } from './client';
 export type { AuthStatus, PHCMSContextType, PHCMSProviderProps } from './context';
+export type UserSearchResultDto = {
+    uid: string;
+    username: string | null;
+    display_name: string;
+    avatar_url: string | null;
+};
 export type { FirebaseAuthSyncProps, UseFirebaseAuthSyncOptions, UseFirebaseAuthSyncReturn } from './hooks/useFirebaseAuthSync';
 export type { StampAvailability, CheckStampAvailabilityParams } from './hooks/useStampTour';
 export type { AnonymousLoginRequest, AuthResponse, FirebaseExchangeRequest, FirebaseRegisterRequest, LoginRequest, RefreshTokenRequest, RegisterRequest, } from '@ph-cms/api-contract';
@@ -9,9 +15,10 @@ 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';
 export type { IntegratedPlace, PlaceSearchQuery, PlaceSearchResponse, } from '@ph-cms/api-contract';
+export type { GetMyUserGroupMembershipResponse, JoinUserGroupResponse, LeaveUserGroupResponse, ListUserGroupQuery, PagedMyGroupInviteListResponse, PagedMyUserGroupMembershipListResponse, PagedUserGroupListResponse, RespondInviteResponse, UserGroupDto, UserGroupJoinMode, UserGroupInviteDto, UserGroupInviteStatus, UserGroupMembershipDto, } from '@ph-cms/api-contract';
 export type { PagedResponse } from '@ph-cms/api-contract';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ph-cms/client-sdk",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "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.29",
     "@tanstack/react-query": "^5.0.0",
     "axios": "^1.6.0",
     "zod": "^3.22.4"