@ph-cms/client-sdk 0.1.9 → 0.1.10

package/README.md

@@ -66,6 +66,8 @@ import type {
   ContentMediaDto,
   CreateContentRequest,
   UpdateContentRequest,
+  CreateStampTourRequest,
+  UpdateStampTourRequest,
   ListContentQuery,
   PagedContentListResponse,
 
@@ -770,7 +772,62 @@ console.log(status?.liked); // true or false
 
 ## Stamp Tour
 
-스탬프 투어 기능을 사용하여 특정 지점(Marker) 방문을 인증하고 진행 현황을 조회할 수 있습니다.
+스탬프 투어 기능을 사용하여 특정 지점(Marker) 방문을 인증하고 진행 현황을 조회하거나, 새로운 투어를 생성할 수 있습니다.
+
+#### 스탬프 투어 생성 (인증 필수)
+
+여러 개의 마커(Marker)를 묶어 새로운 스탬프 투어를 생성합니다.
+
+```tsx
+import { useCreateStampTour } from '@ph-cms/client-sdk';
+
+function CreateTourForm() {
+  const { mutateAsync: createTour, isPending } = useCreateStampTour();
+
+  const handleCreate = async () => {
+    await createTour({
+      channelSlug: 'my-channel',
+      parentUid: 'folder-uid',
+      title: '서울 명소 투어',
+      summary: '서울의 주요 명소를 방문하세요.',
+      markerUids: ['marker-1-uid', 'marker-2-uid'],
+      isActive: true,
+      tags: ['서울', '여행'],
+      startsAt: '2026-04-01T00:00:00Z',
+      endsAt: '2026-06-30T23:59:59Z'
+    });
+    alert('투어가 생성되었습니다.');
+  };
+
+  return <button onClick={handleCreate} disabled={isPending}>투어 만들기</button>;
+}
+```
+
+#### 스탬프 투어 수정 (인증 필수)
+
+기존 스탬프 투어의 정보나 마커 목록을 수정합니다. (참여자가 있는 경우 마커 목록 수정은 제한될 수 있습니다.)
+
+```tsx
+import { useUpdateStampTour } from '@ph-cms/client-sdk';
+
+function UpdateTourForm({ tourUid }) {
+  const { mutateAsync: updateTour, isPending } = useUpdateStampTour();
+
+  const handleUpdate = async () => {
+    await updateTour({
+      uid: tourUid,
+      data: {
+        title: '수정된 투어 제목',
+        isActive: false,
+        markerUids: ['marker-1-uid', 'marker-3-uid']
+      }
+    });
+    alert('투어가 수정되었습니다.');
+  };
+
+  return <button onClick={handleUpdate} disabled={isPending}>투어 수정</button>;
+}
+```
 
 #### 스탬프 획득 (인증)
 
@@ -803,6 +860,43 @@ function StampButton({ tourUid, markerUid }) {
 }
 ```
 
+#### 클라이언트 위치 검증 (Geo)
+
+스탬프를 획득하기 전 클라이언트 창에서 사용자의 현재 GPS 좌표와 마커 위치를 비교하여, 반경 내에 들어왔는지 선제적으로 검증할 수 있습니다. `checkStampAvailability` 함수와 지리 정보 훅 `useGeolocation`을 조합하여 다양한 검증 상태(`available`, `distance_far`, `not_stamp_location`, `checking_geo` 등)를 처리합니다.
+
+```tsx
+import { useGeolocation, checkStampAvailability } from '@ph-cms/client-sdk';
+
+function StampLocationGuard({ marker, stampStatus, isAuthenticated }) {
+  // 실시간 GPS 좌표 및 권한 상태 감지
+  const { latitude, longitude, geoError } = useGeolocation();
+
+  // 클라이언트 단에서 마커 접근 가능성 확인
+  const availability = checkStampAvailability({
+    markerUid: marker.uid,
+    markerLocation: marker.location, // { latitude, longitude }
+    stampStatus,                     // 내가 획득한 스탬프 정보 (StampStatusDto)
+    isLoggedIn: isAuthenticated,     // 권한 상태 확인
+    latitude,
+    longitude,
+    geoError,
+    distanceThreshold: 40,           // 스탬프 획득 가능 반경 (단위: 미터)
+  });
+
+  return (
+    <div>
+      <p>상태: {availability.stateMessage}</p>
+      <p>힌트: {availability.hintMessage}</p>
+      <p>거리: {availability.distance ? `${availability.distance.toFixed(1)}m` : '알 수 없음'}</p>
+      
+      {availability.state === 'available' && (
+        <button onClick={handleCollect}>스탬프 획득하기</button>
+      )}
+    </div>
+  );
+}
+```
+
 #### 투어 진행 현황 조회
 
 특정 투어에 대해 내가 획득한 스탬프 목록과 완주 여부를 확인합니다.
@@ -946,6 +1040,23 @@ client.media          // MediaModule
 | `refresh(refreshToken: string)` | 토큰 갱신 → `{ accessToken, refreshToken }` |
 | `logout()` | 로그아웃 (프로바이더 토큰 삭제 + 서버 세션 무효화) |
 
+### `ContentModule` (`client.content`)
+
+| 메서드 | 설명 |
+|---|---|
+| `list(query: ListContentQuery)` | 콘텐츠 목록 조회 → `PagedContentListResponse` |
+| `get(uid: string)` | 단일 콘텐츠 상세 조회 → `ContentDto` |
+| `create(data: CreateContentRequest)` | 일반 콘텐츠 생성 → `ContentDto` |
+| `update(uid: string, data: UpdateContentRequest)` | 콘텐츠 수정 → `ContentDto` |
+| `delete(uid: string)` | 콘텐츠 삭제 |
+| `createStampTour(data: CreateStampTourRequest)` | **스탬프 투어 생성** → `ContentDto` |
+| `updateStampTour(uid: string, data: UpdateStampTourRequest)` | **스탬프 투어 수정** → `ContentDto` |
+| `stamp(tourUid: string, markerUid: string, data: CollectStampRequest)` | 스탬프 획득 인증 → `{ isCompletion, distance }` |
+| `getStampStatus(tourUid: string)` | 내 스탬프 획득 현황 조회 → `StampStatusDto` |
+| `getTourStats(tourUid: string)` | 투어 전체 통계 조회 → `TourStatsDto` |
+| `toggleLike(uid: string)` | 좋아요 토글 → `ToggleLikeResponse` |
+| `getLikeStatus(uid: string)` | 내 좋아요 여부 확인 → `LikeStatusResponse` |
+
 ### JWT Utilities
 
 클라이언트에서 토큰 상태를 확인할 수 있는 유틸리티입니다 (서명 검증은 하지 않음).

package/dist/hooks/useContent.d.ts

@@ -9,8 +9,10 @@ export declare const contentKeys: {
         type?: string | undefined;
         tags?: string[] | undefined;
         channelUid?: string | undefined;
+        channelSlug?: string | undefined;
         parentUid?: string | undefined;
         authorUid?: string | undefined;
+        uids?: string[] | undefined;
         rootUid?: string | undefined;
         keyword?: string | undefined;
         orderBy?: "created_at" | "updated_at" | "published_at" | "title" | "view_count" | "like_count" | undefined;

package/dist/hooks/useStampTour.d.ts

@@ -1,16 +1,42 @@
-import { CollectStampRequest } from '@ph-cms/api-contract';
+import { CollectStampRequest, StampStatusDto, UpdateStampTourRequest, ContentDto } 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 useCreateStampTour: () => import("@tanstack/react-query").UseMutationResult<ContentDto, Error, {
+    title: string;
+    parentUid: string;
+    markerUids: string[];
+    isActive: boolean;
+    status?: string | undefined;
+    geometry?: {
+        type: "Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon" | "GeometryCollection" | "Feature" | "FeatureCollection";
+        coordinates?: any[] | undefined;
+        geometries?: any[] | undefined;
+        features?: any[] | undefined;
+        properties?: Record<string, any> | undefined;
+        geometry?: any;
+    } | undefined;
+    image?: string | null | undefined;
+    summary?: string | null | undefined;
+    tags?: string[] | undefined;
+    channelUid?: string | undefined;
+    channelSlug?: string | undefined;
+    startsAt?: string | null | undefined;
+    endsAt?: string | null | undefined;
+}, unknown>;
+export declare const useUpdateStampTour: () => import("@tanstack/react-query").UseMutationResult<ContentDto, Error, {
+    uid: string;
+    data: UpdateStampTourRequest;
+}, unknown>;
 export declare const useStamp: () => import("@tanstack/react-query").UseMutationResult<{
     isCompletion: boolean;
     distance: number;
 }, Error, {
     tourUid: string;
     markerUid: string;
-    data: CollectStampRequest;
+    data?: CollectStampRequest;
 }, unknown>;
 export declare const useStampStatus: (tourUid: string, enabled?: boolean) => import("@tanstack/react-query").UseQueryResult<{
     total_markers: number;
@@ -35,3 +61,49 @@ export declare const useTourStats: (tourUid: string, enabled?: boolean) => impor
         stamp_count: number;
     }[];
 }, Error>;
+export interface StampAvailability {
+    currentLocation?: {
+        latitude: number;
+        longitude: number;
+    };
+    stampLocation?: {
+        latitude: number;
+        longitude: number;
+    };
+    state: "available" | "not_logged_in" | "invalid_location" | "distance_far" | "checking_geo" | "geo_error" | "already_acquired" | "not_stamp_location";
+    stateMessage: string;
+    hintMessage: string;
+    distance: number | null;
+}
+export declare const calculateDistance: (lat1: number, lon1: number, lat2: number, lon2: number) => number;
+export declare const getStampAvailability: ({ state, currentLocation, stampLocation, distance, }: {
+    state: StampAvailability["state"];
+    currentLocation?: {
+        latitude: number;
+        longitude: number;
+    };
+    stampLocation?: {
+        latitude: number;
+        longitude: number;
+    };
+    distance?: number;
+}) => StampAvailability;
+export interface CheckStampAvailabilityParams {
+    markerUid: string;
+    markerLocation?: {
+        latitude?: number | null;
+        longitude?: number | null;
+    } | null;
+    stampStatus?: StampStatusDto | null;
+    isLoggedIn: boolean;
+    latitude: number | null;
+    longitude: number | null;
+    geoError: any;
+    distanceThreshold?: number;
+}
+export declare const checkStampAvailability: ({ markerUid, markerLocation, stampStatus, isLoggedIn, latitude, longitude, geoError, distanceThreshold, }: CheckStampAvailabilityParams) => StampAvailability;
+export declare const useGeolocation: (enabled?: boolean) => {
+    latitude: number | null;
+    longitude: number | null;
+    geoError: string | null;
+};

package/dist/hooks/useStampTour.js

@@ -1,18 +1,65 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTourStats = exports.useStampStatus = exports.useStamp = exports.stampTourKeys = void 0;
+exports.useGeolocation = exports.checkStampAvailability = exports.getStampAvailability = exports.calculateDistance = exports.useTourStats = exports.useStampStatus = exports.useStamp = exports.useUpdateStampTour = exports.useCreateStampTour = exports.stampTourKeys = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
+const useContent_1 = require("./useContent");
+const react_1 = require("react");
 exports.stampTourKeys = {
     all: ['stamp-tours'],
     status: (tourUid) => [...exports.stampTourKeys.all, 'status', tourUid],
     stats: (tourUid) => [...exports.stampTourKeys.all, 'stats', tourUid],
 };
+const useCreateStampTour = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (data) => client.content.createStampTour(data),
+        onSuccess: () => {
+            // Invalidate content lists since a new tour is a content item
+            queryClient.invalidateQueries({ queryKey: useContent_1.contentKeys.lists() });
+        },
+    });
+};
+exports.useCreateStampTour = useCreateStampTour;
+const useUpdateStampTour = () => {
+    const client = (0, context_1.usePHCMS)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ uid, data }) => client.content.updateStampTour(uid, data),
+        onSuccess: (data, variables) => {
+            queryClient.invalidateQueries({ queryKey: useContent_1.contentKeys.detail(variables.uid) });
+            queryClient.invalidateQueries({ queryKey: useContent_1.contentKeys.lists() });
+        },
+    });
+};
+exports.useUpdateStampTour = useUpdateStampTour;
 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),
+        mutationFn: async ({ tourUid, markerUid, data }) => {
+            let requestData = data;
+            if (!requestData) {
+                try {
+                    const position = await new Promise((resolve, reject) => {
+                        navigator.geolocation.getCurrentPosition(resolve, reject, {
+                            enableHighAccuracy: true,
+                            timeout: 5000,
+                            maximumAge: 0
+                        });
+                    });
+                    requestData = {
+                        lat: position.coords.latitude,
+                        lng: position.coords.longitude,
+                    };
+                }
+                catch (error) {
+                    throw new Error('위치 정보를 가져올 수 없습니다. 위치 권한을 확인해주세요.');
+                }
+            }
+            return client.content.stamp(tourUid, markerUid, requestData);
+        },
         onSuccess: (data, variables) => {
             queryClient.invalidateQueries({ queryKey: exports.stampTourKeys.status(variables.tourUid) });
         },
@@ -37,3 +84,118 @@ const useTourStats = (tourUid, enabled = true) => {
     });
 };
 exports.useTourStats = useTourStats;
+const calculateDistance = (lat1, lon1, lat2, lon2) => {
+    const R = 6371000;
+    const dLat = ((lat2 - lat1) * Math.PI) / 180;
+    const dLon = ((lon2 - lon1) * Math.PI) / 180;
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos((lat1 * Math.PI) / 180) *
+            Math.cos((lat2 * Math.PI) / 180) *
+            Math.sin(dLon / 2) *
+            Math.sin(dLon / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+};
+exports.calculateDistance = calculateDistance;
+const getStampAvailability = ({ state, currentLocation, stampLocation, distance, }) => {
+    const stateMessages = {
+        available: "스탬프 획득 가능",
+        not_logged_in: "스탬프 획득 불가 (로그인 필요)",
+        invalid_location: "장소 정보를 찾을 수 없습니다.",
+        distance_far: `스탬프 획득 불가 (${distance?.toFixed(1) || 0}m)`,
+        checking_geo: "현재 위치를 확인하고 있습니다.",
+        geo_error: "스탬프 획득 불가 (위치 권한 필요)",
+        already_acquired: "스탬프 획득 완료",
+        not_stamp_location: "스탬프 획득 불가 (스탬프 위치 아님)",
+    };
+    const hintMessages = {
+        available: "이 버튼을 눌러 스탬프를 획득해주세요.",
+        not_logged_in: "로그인 후 스탬프를 획득할 수 있습니다.",
+        invalid_location: "유효한 장소에서 시도해주세요.",
+        distance_far: "이 버튼을 눌러 위치를 업데이트 하세요.",
+        checking_geo: "잠시만 기다려주세요.",
+        geo_error: "위치 권한을 허용해주세요.",
+        already_acquired: "획득한 스탬프 목록을 확인해보세요.",
+        not_stamp_location: "스탬프 위치에서 시도해주세요.",
+    };
+    return {
+        currentLocation,
+        stampLocation,
+        state,
+        stateMessage: stateMessages[state],
+        hintMessage: hintMessages[state],
+        distance: distance ?? null,
+    };
+};
+exports.getStampAvailability = getStampAvailability;
+const checkStampAvailability = ({ markerUid, markerLocation, stampStatus, isLoggedIn, latitude, longitude, geoError, distanceThreshold = 40, }) => {
+    if (!markerLocation) {
+        return (0, exports.getStampAvailability)({ state: "not_stamp_location" });
+    }
+    if (!markerLocation.latitude || !markerLocation.longitude) {
+        return (0, exports.getStampAvailability)({ state: "invalid_location" });
+    }
+    if (geoError) {
+        return (0, exports.getStampAvailability)({ state: "geo_error" });
+    }
+    if (latitude === null || longitude === null) {
+        return (0, exports.getStampAvailability)({ state: "checking_geo" });
+    }
+    if (!isLoggedIn) {
+        return (0, exports.getStampAvailability)({ state: "not_logged_in" });
+    }
+    const acquiredUids = stampStatus?.stamps?.map((s) => s.marker_uid) || [];
+    if (acquiredUids.includes(markerUid)) {
+        return (0, exports.getStampAvailability)({ state: "already_acquired" });
+    }
+    const currentLocation = { latitude, longitude };
+    const stampLocationCoords = {
+        latitude: markerLocation.latitude,
+        longitude: markerLocation.longitude,
+    };
+    const distance = (0, exports.calculateDistance)(latitude, longitude, markerLocation.latitude, markerLocation.longitude);
+    if (distance > distanceThreshold) {
+        return (0, exports.getStampAvailability)({
+            state: "distance_far",
+            currentLocation,
+            stampLocation: stampLocationCoords,
+            distance,
+        });
+    }
+    return (0, exports.getStampAvailability)({
+        state: "available",
+        currentLocation,
+        stampLocation: stampLocationCoords,
+        distance,
+    });
+};
+exports.checkStampAvailability = checkStampAvailability;
+const useGeolocation = (enabled = true) => {
+    const [latitude, setLatitude] = (0, react_1.useState)(null);
+    const [longitude, setLongitude] = (0, react_1.useState)(null);
+    const [geoError, setGeoError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!enabled || typeof navigator === 'undefined' || !navigator.geolocation) {
+            if (enabled && typeof navigator !== 'undefined') {
+                setGeoError('Geolocation is not supported by your browser');
+            }
+            return;
+        }
+        const watchId = navigator.geolocation.watchPosition((position) => {
+            setLatitude(position.coords.latitude);
+            setLongitude(position.coords.longitude);
+            setGeoError(null);
+        }, (error) => {
+            setGeoError(error.message);
+        }, {
+            enableHighAccuracy: true,
+            maximumAge: 10000,
+            timeout: 5000,
+        });
+        return () => {
+            navigator.geolocation.clearWatch(watchId);
+        };
+    }, [enabled]);
+    return { latitude, longitude, geoError };
+};
+exports.useGeolocation = useGeolocation;

package/dist/hooks/useTerms.d.ts

@@ -5,8 +5,8 @@ export declare const termsKeys: {
     list: (params?: ListTermsQuery) => readonly ["terms", "list", {
         code?: string | undefined;
         limit?: number | undefined;
-        offset?: number | undefined;
         isActive?: boolean | undefined;
+        offset?: number | undefined;
     } | undefined];
 };
 export declare const useTermsList: (params?: ListTermsQuery) => import("@tanstack/react-query").UseQueryResult<{
@@ -14,9 +14,9 @@ export declare const useTermsList: (params?: ListTermsQuery) => import("@tanstac
         code: string;
         title: string;
         content: string;
+        isActive: boolean;
         id: number;
         version: string;
-        isActive: boolean;
         createdAt: string;
     }[];
     total: number;

package/dist/modules/content.d.ts

@@ -1,5 +1,5 @@
+import { BoundsQuery, CollectStampRequest, ContentDto, CreateContentRequest, CreateStampTourRequest, LikeStatusResponse, ListContentQuery, PagedContentListResponse, StampStatusDto, ToggleLikeResponse, TourStatsDto, UpdateContentRequest, UpdateStampTourRequest } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
-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,6 +9,8 @@ export declare class ContentModule {
     create(data: CreateContentRequest): Promise<ContentDto>;
     update(uid: string, data: UpdateContentRequest): Promise<ContentDto>;
     delete(uid: string): Promise<void>;
+    createStampTour(data: CreateStampTourRequest): Promise<ContentDto>;
+    updateStampTour(uid: string, data: UpdateStampTourRequest): Promise<ContentDto>;
     stamp(tourUid: string, markerUid: string, data: CollectStampRequest): Promise<{
         isCompletion: boolean;
         distance: number;

package/dist/modules/content.js

@@ -47,6 +47,22 @@ class ContentModule {
             throw new errors_1.ValidationError("UID is required", []);
         return this.client.delete(`/api/contents/${uid}`);
     }
+    async createStampTour(data) {
+        const validation = api_contract_1.CreateStampTourSchema.safeParse(data);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid create stamp tour data", validation.error.errors);
+        }
+        return this.client.post('/api/contents/stamp-tours', data);
+    }
+    async updateStampTour(uid, data) {
+        if (!uid)
+            throw new errors_1.ValidationError("UID is required", []);
+        const validation = api_contract_1.UpdateStampTourSchema.safeParse(data);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid update stamp tour data", validation.error.errors);
+        }
+        return this.client.put(`/api/contents/stamp-tours/${uid}`, data);
+    }
     async stamp(tourUid, markerUid, data) {
         if (!tourUid || !markerUid)
             throw new errors_1.ValidationError("Both tourUid and markerUid are required", []);

package/dist/types.d.ts

@@ -3,6 +3,7 @@ export type { JwtPayload } from './auth/jwt-utils';
 export type { PHCMSClientConfig } from './client';
 export type { AuthStatus, PHCMSContextType, PHCMSProviderProps } from './context';
 export type { FirebaseAuthSyncProps, UseFirebaseAuthSyncOptions, UseFirebaseAuthSyncReturn } from './hooks/useFirebaseAuthSync';
+export type { StampAvailability, CheckStampAvailabilityParams } from './hooks/useStampTour';
 export type { AuthResponse, FirebaseExchangeRequest, LoginRequest, RefreshTokenRequest, RegisterRequest } from '@ph-cms/api-contract';
 export type { UserDto } from '@ph-cms/api-contract';
 export type { ChannelDto, CheckHierarchyQuery, CreateChannelDto, ListChannelQuery, PagedChannelListResponse } from '@ph-cms/api-contract';

package/package.json

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