@ph-cms/client-sdk 0.1.8 → 0.1.9-beta.1

package/README.md

@@ -714,6 +714,90 @@ 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 좌표를 전송하여 특정 투어 내의 마커 방문을 인증합니다.
+
+```ts
+// Standalone Usage
+const result = await client.content.stamp(tourUid, markerUid, {
+  lat: 37.5511,
+  lng: 126.9882
+});
+
+console.log(`거리: ${result.distance}m`);
+if (result.isCompletion) {
+  alert('축하합니다! 투어를 완주하셨습니다.');
+}
+```
+
+### 투어 진행 현황 조회
+
+특정 투어에 대해 내가 획득한 스탬프 목록과 완주 여부를 확인합니다.
+
+```ts
+const status = await client.content.getStampStatus(tourUid);
+
+console.log(`전체 마커: ${status.total_markers}`);
+console.log(`획득 마커: ${status.collected_markers}`);
+console.log(`완주 여부: ${status.is_completed}`);
+
+status.stamps.forEach(s => {
+  console.log(`마커 ${s.marker_uid} 획득 일시: ${s.collected_at}`);
+});
+```
+
+### 투어 전체 통계 (관리자용)
+
+투어의 총 참여자 수, 완주율 등 관리용 데이터를 조회합니다. (적절한 권한 필요)
+
+```ts
+const stats = await client.content.getTourStats(tourUid);
+
+console.log(`총 참여자: ${stats.total_participants}`);
+console.log(`총 완주자: ${stats.total_completions}`);
+console.log(`완주율: ${stats.completion_rate * 100}%`);
+console.log(`평균 오차 거리: ${stats.avg_distance_meter}m`);
+
+stats.stamps_by_marker.forEach(m => {
+  console.log(`${m.marker_title}: ${m.stamp_count}회 방문`);
+});
+```
+
+---
+
 ## Media & File Upload
 
 미디어 업로드는 3단계로 진행됩니다: Ticket 발급 → S3 업로드 → Content 생성/수정.

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/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/package.json

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