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

package/README.md

@@ -66,6 +66,8 @@ import type {
   ContentMediaDto,
   CreateContentRequest,
   UpdateContentRequest,
+  CreateStampTourRequest,
+  UpdateStampTourRequest,
   ListContentQuery,
   PagedContentListResponse,
 
@@ -516,6 +518,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`를 직접 사용할 수 있습니다.
@@ -744,56 +772,163 @@ 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>;
+}
+```
+
+#### 스탬프 획득 (인증)
 
 사용자의 현재 GPS 좌표를 전송하여 특정 투어 내의 마커 방문을 인증합니다.
 
-```ts
-// Standalone Usage
-const result = await client.content.stamp(tourUid, markerUid, {
-  lat: 37.5511,
-  lng: 126.9882
-});
+```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('스탬프를 획득할 수 없습니다. (너무 멀거나 이미 획득함)');
+    }
+  };
 
-console.log(`거리: ${result.distance}m`);
-if (result.isCompletion) {
-  alert('축하합니다! 투어를 완주하셨습니다.');
+  return <button onClick={handleStamp} disabled={isPending}>스탬프 찍기</button>;
 }
 ```
 
-### 투어 진행 현황 조회
+#### 클라이언트 위치 검증 (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>
+  );
+}
+```
+
+#### 투어 진행 현황 조회
 
 특정 투어에 대해 내가 획득한 스탬프 목록과 완주 여부를 확인합니다.
 
-```ts
-const status = await client.content.getStampStatus(tourUid);
+```tsx
+import { useStampStatus } from '@ph-cms/client-sdk';
 
-console.log(`전체 마커: ${status.total_markers}`);
-console.log(`획득 마커: ${status.collected_markers}`);
-console.log(`완주 여부: ${status.is_completed}`);
+function TourProgress({ tourUid }) {
+  const { data: status, isLoading } = useStampStatus(tourUid);
 
-status.stamps.forEach(s => {
-  console.log(`마커 ${s.marker_uid} 획득 일시: ${s.collected_at}`);
-});
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>진행도: {status?.collected_markers} / {status?.total_markers}</p>
+      {status?.is_completed && <p>🏆 완주 완료!</p>}
+    </div>
+  );
+}
 ```
 
-### 투어 전체 통계 (관리자용)
+#### 투어 전체 통계 (관리자용)
 
 투어의 총 참여자 수, 완주율 등 관리용 데이터를 조회합니다. (적절한 권한 필요)
 
-```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`);
+```tsx
+import { useTourStats } from '@ph-cms/client-sdk';
 
-stats.stamps_by_marker.forEach(m => {
-  console.log(`${m.marker_title}: ${m.stamp_count}회 방문`);
-});
+function AdminStats({ tourUid }) {
+  const { data: stats, isLoading } = useTourStats(tourUid);
+  // ...
+}
 ```
 
 ---
@@ -881,12 +1016,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`)
 
 | 메서드 | 설명 |
@@ -898,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/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

@@ -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

@@ -0,0 +1,109 @@
+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;
+}, 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>;
+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

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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: 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) });
+        },
+    });
+};
+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;
+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/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 { 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/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/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-beta.1",
+  "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-beta.1",
+    "@ph-cms/api-contract": "file:../api-contract",
     "@tanstack/react-query": "^5.0.0",
     "axios": "^1.6.0",
     "zod": "^3.22.4"