@ph-cms/client-sdk 0.1.9-beta.1 → 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`를 직접 사용할 수 있습니다.
@@ -746,54 +772,69 @@ console.log(status?.liked); // true or false
 
 스탬프 투어 기능을 사용하여 특정 지점(Marker) 방문을 인증하고 진행 현황을 조회할 수 있습니다.
 
-### 스탬프 획득 (인증)
+#### 스탬프 획득 (인증)
 
 사용자의 현재 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>;
 }
 ```
 
-### 투어 진행 현황 조회
+#### 투어 진행 현황 조회
 
 특정 투어에 대해 내가 획득한 스탬프 목록과 완주 여부를 확인합니다.
 
-```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 +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/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/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.9-beta.1",
+  "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.2-beta.1",
+    "@ph-cms/api-contract": "0.1.2",
     "@tanstack/react-query": "^5.0.0",
     "axios": "^1.6.0",
     "zod": "^3.22.4"