@ph-cms/client-sdk 0.1.8 → 0.1.9

package/README.md

@@ -516,6 +516,32 @@ function MyComponent() {
 }
 ```
 
+### Profile Update (`useUpdateProfile`)
+
+사용자가 자신의 프로필을 수정할 수 있는 훅입니다. 업데이트가 성공하면 내부적으로 `refreshUser()`가 호출되어 컨텍스트와 UI가 즉각적으로 갱신됩니다.
+
+```tsx
+import { useUpdateProfile } from '@ph-cms/client-sdk';
+
+function ProfileEditor({ userUid }) {
+  const { mutateAsync: updateProfile, isPending } = useUpdateProfile();
+
+  const handleSave = async () => {
+    await updateProfile({
+      uid: userUid,
+      data: {
+        display_name: 'New Name',
+        avatar_url: 'https://example.com/new-avatar.png',
+        profile_data: { bio: 'Hello World' },
+      }
+    });
+    alert('프로필이 업데이트되었습니다.');
+  };
+
+  return <button onClick={handleSave} disabled={isPending}>저장</button>;
+}
+```
+
 ### Standalone (Non-React) Usage
 
 React 없이 `PHCMSClient`를 직접 사용할 수 있습니다.
@@ -714,6 +740,105 @@ function ChannelList() {
 
 ---
 
+## Like (좋아요)
+
+콘텐츠에 좋아요를 남기고, 좋아요 상태를 확인할 수 있습니다.
+
+### 좋아요 토글 (인증 필수)
+
+```ts
+// 모듈 직접 사용
+const result = await client.content.toggleLike('content-uid');
+// => { liked: true, likeCount: 42 }
+
+// React Hook 사용 (Optimistic update 포함)
+const { mutate: toggleLike } = useToggleLike();
+toggleLike('content-uid');
+```
+
+### 좋아요 상태 확인 (인증 선택)
+
+```ts
+// 모듈 직접 사용
+const status = await client.content.getLikeStatus('content-uid');
+// => { liked: true }
+
+// React Hook 사용
+const { data: status } = useLikeStatus('content-uid');
+console.log(status?.liked); // true or false
+```
+
+## Stamp Tour
+
+스탬프 투어 기능을 사용하여 특정 지점(Marker) 방문을 인증하고 진행 현황을 조회할 수 있습니다.
+
+#### 스탬프 획득 (인증)
+
+사용자의 현재 GPS 좌표를 전송하여 특정 투어 내의 마커 방문을 인증합니다.
+
+```tsx
+import { useStamp } from '@ph-cms/client-sdk';
+
+function StampButton({ tourUid, markerUid }) {
+  const { mutateAsync: collectStamp, isPending } = useStamp();
+
+  const handleStamp = async () => {
+    try {
+      const result = await collectStamp({
+        tourUid,
+        markerUid,
+        data: { lat: 37.5511, lng: 126.9882 }
+      });
+      
+      console.log(`거리: ${result.distance}m`);
+      if (result.isCompletion) {
+        alert('축하합니다! 투어를 완주하셨습니다.');
+      }
+    } catch (error) {
+      alert('스탬프를 획득할 수 없습니다. (너무 멀거나 이미 획득함)');
+    }
+  };
+
+  return <button onClick={handleStamp} disabled={isPending}>스탬프 찍기</button>;
+}
+```
+
+#### 투어 진행 현황 조회
+
+특정 투어에 대해 내가 획득한 스탬프 목록과 완주 여부를 확인합니다.
+
+```tsx
+import { useStampStatus } from '@ph-cms/client-sdk';
+
+function TourProgress({ tourUid }) {
+  const { data: status, isLoading } = useStampStatus(tourUid);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>진행도: {status?.collected_markers} / {status?.total_markers}</p>
+      {status?.is_completed && <p>🏆 완주 완료!</p>}
+    </div>
+  );
+}
+```
+
+#### 투어 전체 통계 (관리자용)
+
+투어의 총 참여자 수, 완주율 등 관리용 데이터를 조회합니다. (적절한 권한 필요)
+
+```tsx
+import { useTourStats } from '@ph-cms/client-sdk';
+
+function AdminStats({ tourUid }) {
+  const { data: stats, isLoading } = useTourStats(tourUid);
+  // ...
+}
+```
+
+---
+
 ## Media & File Upload
 
 미디어 업로드는 3단계로 진행됩니다: Ticket 발급 → S3 업로드 → Content 생성/수정.
@@ -797,12 +922,19 @@ const client = new PHCMSClient({
 client.authProvider   // AuthProvider | undefined
 client.axiosInstance  // AxiosInstance — 내부 axios 인스턴스 직접 접근
 client.auth           // AuthModule
+client.user           // UserModule
 client.content        // ContentModule
 client.channel        // ChannelModule
 client.terms          // TermsModule
 client.media          // MediaModule
 ```
 
+### `UserModule` (`client.user`)
+
+| 메서드 | 설명 |
+|---|---|
+| `updateProfile(uid: string, data: UpdateUserProfileRequest)` | 유저의 프로필 정보 업데이트 (일반 유저는 `UpdateUserProfileRequest` 필드만 허용) → `UserDto` |
+
 ### `AuthModule` (`client.auth`)
 
 | 메서드 | 설명 |

package/dist/client.d.ts

@@ -5,6 +5,7 @@ import { ChannelModule } from './modules/channel';
 import { ContentModule } from './modules/content';
 import { MediaModule } from './modules/media';
 import { TermsModule } from './modules/terms';
+import { UserModule } from './modules/user';
 export interface PHCMSClientConfig {
     baseURL: string;
     apiPrefix?: string;
@@ -19,6 +20,7 @@ export declare class PHCMSClient {
     readonly channel: ChannelModule;
     readonly terms: TermsModule;
     readonly media: MediaModule;
+    readonly user: UserModule;
     /**
      * Whether a token refresh is currently in flight (used by the 401
      * interceptor to de-duplicate concurrent refresh attempts).

package/dist/client.js

@@ -11,6 +11,7 @@ const channel_1 = require("./modules/channel");
 const content_1 = require("./modules/content");
 const media_1 = require("./modules/media");
 const terms_1 = require("./modules/terms");
+const user_1 = require("./modules/user");
 class PHCMSClient {
     /** Exposes the auth provider so UI layers can check token state synchronously. */
     get authProvider() {
@@ -44,6 +45,7 @@ class PHCMSClient {
         this.channel = new channel_1.ChannelModule(this.axiosInstance);
         this.terms = new terms_1.TermsModule(this.axiosInstance);
         this.media = new media_1.MediaModule(this.axiosInstance);
+        this.user = new user_1.UserModule(this.axiosInstance);
         // 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/hooks/useContent.d.ts

@@ -27,6 +27,8 @@ export declare const contentKeys: {
     }];
     details: () => readonly ["contents", "detail"];
     detail: (uid: string) => readonly ["contents", "detail", string];
+    likes: () => readonly ["contents", "like"];
+    like: (uid: string) => readonly ["contents", "like", string];
 };
 export declare const useContentList: (params: ListContentQuery, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
     number: number;
@@ -64,6 +66,19 @@ export declare const useCreateContent: () => import("@tanstack/react-query").Use
     sortOrder?: number | undefined;
     mediaAttachments?: string[] | undefined;
 }, unknown>;
+export declare const useLikeStatus: (uid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+    liked: boolean;
+}, Error>;
+export declare const useToggleLike: () => import("@tanstack/react-query").UseMutationResult<{
+    liked: boolean;
+    likeCount: number;
+}, Error, string, {
+    previousLikeStatus: {
+        liked: boolean;
+    } | undefined;
+    previousDetail: ContentDto | undefined;
+    uid: string;
+}>;
 export declare const useUpdateContent: () => import("@tanstack/react-query").UseMutationResult<ContentDto, Error, {
     uid: string;
     data: UpdateContentRequest;

package/dist/hooks/useContent.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDeleteContent = exports.useUpdateContent = exports.useCreateContent = exports.useContentDetail = exports.useContentGeoList = exports.useContentList = exports.contentKeys = void 0;
+exports.useDeleteContent = exports.useUpdateContent = exports.useToggleLike = exports.useLikeStatus = exports.useCreateContent = exports.useContentDetail = exports.useContentGeoList = exports.useContentList = exports.contentKeys = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
 exports.contentKeys = {
@@ -11,6 +11,8 @@ exports.contentKeys = {
     geoList: (bounds) => [...exports.contentKeys.geoLists(), bounds],
     details: () => [...exports.contentKeys.all, 'detail'],
     detail: (uid) => [...exports.contentKeys.details(), uid],
+    likes: () => [...exports.contentKeys.all, 'like'],
+    like: (uid) => [...exports.contentKeys.likes(), uid],
 };
 const useContentList = (params, enabled = true) => {
     const client = (0, context_1.usePHCMS)();
@@ -51,6 +53,79 @@ const useCreateContent = () => {
     });
 };
 exports.useCreateContent = useCreateContent;
+const useLikeStatus = (uid, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.contentKeys.like(uid),
+        queryFn: () => client.content.getLikeStatus(uid),
+        enabled: !!uid && enabled,
+    });
+};
+exports.useLikeStatus = useLikeStatus;
+const useToggleLike = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (uid) => client.content.toggleLike(uid),
+        onMutate: async (uid) => {
+            // Cancel any outgoing refetches so they don't overwrite our optimistic update
+            await queryClient.cancelQueries({ queryKey: exports.contentKeys.like(uid) });
+            await queryClient.cancelQueries({ queryKey: exports.contentKeys.detail(uid) });
+            // Snapshot the previous values
+            const previousLikeStatus = queryClient.getQueryData(exports.contentKeys.like(uid));
+            const previousDetail = queryClient.getQueryData(exports.contentKeys.detail(uid));
+            // Optimistically update to the new value
+            const isCurrentlyLiked = previousLikeStatus?.liked ?? previousDetail?.liked ?? false;
+            const newLikedState = !isCurrentlyLiked;
+            // Update like status
+            queryClient.setQueryData(exports.contentKeys.like(uid), {
+                liked: newLikedState,
+            });
+            // Update detail if it exists
+            if (previousDetail) {
+                queryClient.setQueryData(exports.contentKeys.detail(uid), {
+                    ...previousDetail,
+                    liked: newLikedState,
+                    stat: {
+                        ...previousDetail.stat,
+                        like_count: previousDetail.stat.like_count + (newLikedState ? 1 : -1),
+                    },
+                });
+            }
+            // We could also optimistically update items in lists, but for simplicity we'll just invalidate on success/settled
+            // Return a context object with the snapshotted values
+            return { previousLikeStatus, previousDetail, uid };
+        },
+        onError: (err, uid, context) => {
+            // If the mutation fails, use the context returned from onMutate to roll back
+            if (context?.previousLikeStatus !== undefined) {
+                queryClient.setQueryData(exports.contentKeys.like(uid), context.previousLikeStatus);
+            }
+            if (context?.previousDetail !== undefined) {
+                queryClient.setQueryData(exports.contentKeys.detail(uid), context.previousDetail);
+            }
+        },
+        onSuccess: (data, uid) => {
+            // In case the optimistic update got the count wrong or anything, set exact values from server
+            queryClient.setQueryData(exports.contentKeys.like(uid), { liked: data.liked });
+            queryClient.setQueryData(exports.contentKeys.detail(uid), (old) => {
+                if (!old)
+                    return old;
+                return {
+                    ...old,
+                    liked: data.liked,
+                    stat: { ...old.stat, like_count: data.likeCount },
+                };
+            });
+        },
+        onSettled: (data, error, uid) => {
+            // Invalidate the lists so they fetch the latest liked status and like counts
+            queryClient.invalidateQueries({ queryKey: exports.contentKeys.lists() });
+            queryClient.invalidateQueries({ queryKey: exports.contentKeys.geoLists() });
+        },
+    });
+};
+exports.useToggleLike = useToggleLike;
 const useUpdateContent = () => {
     const client = (0, context_1.usePHCMS)();
     const queryClient = (0, react_query_1.useQueryClient)();

package/dist/hooks/useStampTour.d.ts

@@ -0,0 +1,37 @@
+import { CollectStampRequest } from '@ph-cms/api-contract';
+export declare const stampTourKeys: {
+    all: readonly ["stamp-tours"];
+    status: (tourUid: string) => readonly ["stamp-tours", "status", string];
+    stats: (tourUid: string) => readonly ["stamp-tours", "stats", string];
+};
+export declare const useStamp: () => import("@tanstack/react-query").UseMutationResult<{
+    isCompletion: boolean;
+    distance: number;
+}, Error, {
+    tourUid: string;
+    markerUid: string;
+    data: CollectStampRequest;
+}, unknown>;
+export declare const useStampStatus: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+    total_markers: number;
+    collected_markers: number;
+    is_completed: boolean;
+    stamps: {
+        marker_uid: string;
+        collected_at: string;
+    }[];
+}, Error>;
+export declare const useTourStats: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
+    total_markers: number;
+    tour_uid: string;
+    tour_title: string;
+    total_participants: number;
+    total_completions: number;
+    completion_rate: number;
+    avg_distance_meter: number;
+    stamps_by_marker: {
+        marker_uid: string;
+        marker_title: string;
+        stamp_count: number;
+    }[];
+}, Error>;

package/dist/hooks/useStampTour.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTourStats = exports.useStampStatus = exports.useStamp = exports.stampTourKeys = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("../context");
+exports.stampTourKeys = {
+    all: ['stamp-tours'],
+    status: (tourUid) => [...exports.stampTourKeys.all, 'status', tourUid],
+    stats: (tourUid) => [...exports.stampTourKeys.all, 'stats', tourUid],
+};
+const useStamp = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ tourUid, markerUid, data }) => client.content.stamp(tourUid, markerUid, data),
+        onSuccess: (data, variables) => {
+            queryClient.invalidateQueries({ queryKey: exports.stampTourKeys.status(variables.tourUid) });
+        },
+    });
+};
+exports.useStamp = useStamp;
+const useStampStatus = (tourUid, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.stampTourKeys.status(tourUid),
+        queryFn: () => client.content.getStampStatus(tourUid),
+        enabled: !!tourUid && enabled,
+    });
+};
+exports.useStampStatus = useStampStatus;
+const useTourStats = (tourUid, enabled = true) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.stampTourKeys.stats(tourUid),
+        queryFn: () => client.content.getTourStats(tourUid),
+        enabled: !!tourUid && enabled,
+    });
+};
+exports.useTourStats = useTourStats;

package/dist/hooks/useUser.d.ts

@@ -0,0 +1,26 @@
+import { UpdateUserProfileRequest } from '@ph-cms/api-contract';
+/**
+ * Hook to update a user's profile.
+ * Typically used by a user to update their own profile.
+ */
+export declare const useUpdateProfile: () => import("@tanstack/react-query").UseMutationResult<{
+    uid: string;
+    email: string;
+    username: string | null;
+    display_name: string;
+    avatar_url: string | null;
+    phone_number: string | null;
+    email_verified_at: string | null;
+    phone_verified_at: string | null;
+    locale: string;
+    timezone: string;
+    status: string;
+    role: string[];
+    profile_data: Record<string, any>;
+    last_login_at: string | null;
+    created_at: string;
+    updated_at: string;
+}, Error, {
+    uid: string;
+    data: UpdateUserProfileRequest | Record<string, any>;
+}, unknown>;

package/dist/hooks/useUser.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdateProfile = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("../context");
+/**
+ * Hook to update a user's profile.
+ * Typically used by a user to update their own profile.
+ */
+const useUpdateProfile = () => {
+    const client = (0, context_1.usePHCMS)();
+    const { refreshUser } = (0, context_1.usePHCMSContext)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (params) => client.user.updateProfile(params.uid, params.data),
+        onSuccess: async () => {
+            // Refresh user in context after a successful update so the UI gets the new data
+            await refreshUser();
+        },
+    });
+};
+exports.useUpdateProfile = useUpdateProfile;

package/dist/index.d.ts

@@ -10,11 +10,14 @@ export * from './modules/channel';
 export * from './modules/content';
 export * from './modules/media';
 export * from './modules/terms';
+export * from './modules/user';
 export * from './context';
 export * from './hooks/useAuth';
 export * from './hooks/useChannel';
 export * from './hooks/useContent';
+export * from './hooks/useStampTour';
 export * from './hooks/useFirebaseAuthSync';
 export * from './hooks/useMedia';
 export * from './hooks/useTerms';
+export * from './hooks/useUser';
 export * from './types';

package/dist/index.js

@@ -26,11 +26,14 @@ __exportStar(require("./modules/channel"), exports);
 __exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/media"), exports);
 __exportStar(require("./modules/terms"), exports);
+__exportStar(require("./modules/user"), exports);
 __exportStar(require("./context"), exports);
 __exportStar(require("./hooks/useAuth"), exports);
 __exportStar(require("./hooks/useChannel"), exports);
 __exportStar(require("./hooks/useContent"), exports);
+__exportStar(require("./hooks/useStampTour"), exports);
 __exportStar(require("./hooks/useFirebaseAuthSync"), exports);
 __exportStar(require("./hooks/useMedia"), exports);
 __exportStar(require("./hooks/useTerms"), exports);
+__exportStar(require("./hooks/useUser"), exports);
 __exportStar(require("./types"), exports);

package/dist/modules/content.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { CreateContentRequest, UpdateContentRequest, ListContentQuery, ContentDto, PagedContentListResponse, BoundsQuery } from "@ph-cms/api-contract";
+import { CreateContentRequest, UpdateContentRequest, ListContentQuery, ContentDto, PagedContentListResponse, BoundsQuery, CollectStampRequest, StampStatusDto, TourStatsDto, ToggleLikeResponse, LikeStatusResponse } from "@ph-cms/api-contract";
 export declare class ContentModule {
     private client;
     constructor(client: AxiosInstance);
@@ -9,4 +9,12 @@ export declare class ContentModule {
     create(data: CreateContentRequest): Promise<ContentDto>;
     update(uid: string, data: UpdateContentRequest): Promise<ContentDto>;
     delete(uid: string): Promise<void>;
+    stamp(tourUid: string, markerUid: string, data: CollectStampRequest): Promise<{
+        isCompletion: boolean;
+        distance: number;
+    }>;
+    getStampStatus(tourUid: string): Promise<StampStatusDto>;
+    getTourStats(tourUid: string): Promise<TourStatsDto>;
+    toggleLike(uid: string): Promise<ToggleLikeResponse>;
+    getLikeStatus(uid: string): Promise<LikeStatusResponse>;
 }

package/dist/modules/content.js

@@ -47,5 +47,34 @@ class ContentModule {
             throw new errors_1.ValidationError("UID is required", []);
         return this.client.delete(`/api/contents/${uid}`);
     }
+    async stamp(tourUid, markerUid, data) {
+        if (!tourUid || !markerUid)
+            throw new errors_1.ValidationError("Both tourUid and markerUid are required", []);
+        const validation = api_contract_1.CollectStampSchema.safeParse(data);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid stamp data", validation.error.errors);
+        }
+        return this.client.post(`/api/contents/${tourUid}/stamp/${markerUid}`, data);
+    }
+    async getStampStatus(tourUid) {
+        if (!tourUid)
+            throw new errors_1.ValidationError("tourUid is required", []);
+        return this.client.get(`/api/contents/${tourUid}/stamp-status`);
+    }
+    async getTourStats(tourUid) {
+        if (!tourUid)
+            throw new errors_1.ValidationError("tourUid is required", []);
+        return this.client.get(`/api/contents/${tourUid}/stamp-stats`);
+    }
+    async toggleLike(uid) {
+        if (!uid)
+            throw new errors_1.ValidationError("UID is required", []);
+        return this.client.post(`/api/contents/${uid}/like`);
+    }
+    async getLikeStatus(uid) {
+        if (!uid)
+            throw new errors_1.ValidationError("UID is required", []);
+        return this.client.get(`/api/contents/${uid}/like`);
+    }
 }
 exports.ContentModule = ContentModule;

package/dist/modules/user.d.ts

@@ -0,0 +1,17 @@
+import { UpdateUserProfileRequest, UserDto } from "@ph-cms/api-contract";
+import { AxiosInstance } from "axios";
+export declare class UserModule {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Updates a user's profile.
+     *
+     * Normal users can only update specific fields defined in `UpdateUserProfileRequest`
+     * (e.g., `display_name`, `avatar_url`, `profile_data`).
+     * Admin users can pass any updatable fields.
+     *
+     * @param uid - The UID of the user to update.
+     * @param data - The update payload.
+     */
+    updateProfile(uid: string, data: UpdateUserProfileRequest | Record<string, any>): Promise<UserDto>;
+}

package/dist/modules/user.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserModule = void 0;
+class UserModule {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Updates a user's profile.
+     *
+     * Normal users can only update specific fields defined in `UpdateUserProfileRequest`
+     * (e.g., `display_name`, `avatar_url`, `profile_data`).
+     * Admin users can pass any updatable fields.
+     *
+     * @param uid - The UID of the user to update.
+     * @param data - The update payload.
+     */
+    async updateProfile(uid, data) {
+        return this.client.patch(`/api/users/${uid}`, data);
+    }
+}
+exports.UserModule = UserModule;

package/package.json

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