@ph-cms/client-sdk 0.1.27 → 0.1.30

package/README.md

@@ -1,14 +1,15 @@
-# @ph-cms/client-sdk 0.1.27
+# @ph-cms/client-sdk 0.1.28
 
 PH-CMS 클라이언트 SDK — 브라우저 및 React 애플리케이션을 위한 통합 클라이언트.
 
 **주요 기능:**
 
 - 타입이 지정된 API 클라이언트
-- Auth Provider 인터페이스 및 구현체 (`LocalAuthProvider`, `FirebaseAuthProvider`)
+- Auth Provider 인터페이스 및 구현체 (`LocalAuthProvider`, `FirebaseAuthProvider`, `StaticAuthProvider`)
 - React Context 및 Hooks
 - React Query 통합
 - 자동 토큰 갱신 (Proactive + Reactive)
+- SSR (Server-Side Rendering) 지원 및 Cookie 연동 가능
 - Firebase ↔ PH-CMS 인증 동기화
 - 세분화된 인증 상태 관리 (`authStatus`)
 
@@ -206,6 +207,74 @@ API Request → 401 Unauthorized
 
 ---
 
+## Server-Side Rendering (SSR)
+
+SDK는 SSR 환경(Next.js, Remix 등)에서 인증된 상태로 API를 호출할 수 있는 기능을 제공합니다. 
+브라우저의 쿠키를 서버가 읽어 SDK에 직접 주입하는 방식으로 작동합니다.
+
+### 1. `StaticAuthProvider`
+
+SSR 환경에서는 `localStorage`가 없으므로, 메모리에만 토큰을 들고 있는 `StaticAuthProvider`를 사용하거나 `PHCMSClient` 설정에 직접 토큰을 주입합니다.
+
+```ts
+import { PHCMSClient } from '@ph-cms/client-sdk/core';
+
+// Next.js Server Component 또는 API Route 예시
+export async function getServerSideProps({ req }) {
+  // .env 등에 설정된 프리픽스를 가져옵니다 (기본값 phcms_)
+  const prefix = process.env.NEXT_PUBLIC_PH_CMS_AUTH_STORAGE_PREFIX || "phcms_";
+  
+  const accessToken = req.cookies[`${prefix}access_token`];
+  const refreshToken = req.cookies[`${prefix}refresh_token`];
+
+  const client = new PHCMSClient({
+    baseURL: process.env.API_URL,
+    accessToken,   // 쿠키에서 뽑은 토큰 주입
+    refreshToken,
+  });
+
+  // 이제 이 호출은 인증된 상태(Bearer 헤더 포함)로 서버에서 실행됩니다.
+  const content = await client.content.get(uid);
+  
+  return { props: { content } };
+}
+```
+
+### 2. Next.js Middleware 연동 (추천)
+
+`httpOnly` 쿠키를 사용할 경우, 브라우저의 SDK가 리프레시 토큰에 접근할 수 없습니다. 이때 Next.js 미들웨어를 통해 토큰 갱신을 처리하면 매끄러운 UX를 제공할 수 있습니다.
+
+```ts
+// middleware.ts (Next.js)
+import { NextResponse, NextRequest } from 'next/server';
+
+export async function middleware(req: NextRequest) {
+  const accessToken = req.cookies.get('access_token')?.value;
+  const refreshToken = req.cookies.get('refresh_token')?.value;
+
+  // 액세스 토큰은 만료되었으나 리프레시 토큰이 있는 경우
+  if (!accessToken && refreshToken) {
+    const res = await fetch(`${process.env.API_URL}/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    });
+
+    if (res.ok) {
+      const tokens = await res.json();
+      const response = NextResponse.next();
+      response.cookies.set('access_token', tokens.accessToken, { httpOnly: true, path: '/' });
+      response.cookies.set('refresh_token', tokens.refreshToken, { httpOnly: true, path: '/' });
+      return response;
+    }
+  }
+
+  return NextResponse.next();
+}
+```
+
+---
+
 ## Auth Providers
 
 모든 Provider는 `BaseAuthProvider` 추상 클래스를 상속합니다.

package/dist/auth/static-provider.d.ts

@@ -0,0 +1,22 @@
+import { AuthProvider } from './interfaces';
+/**
+ * A read-only AuthProvider for SSR or static environments.
+ * It holds tokens in memory and does not attempt automatic refresh
+ * or storage persistence.
+ */
+export declare class StaticAuthProvider implements AuthProvider {
+    private accessToken;
+    private refreshToken;
+    readonly type: "LOCAL";
+    constructor(accessToken: string | null, refreshToken?: string | null);
+    getToken(): Promise<string | null>;
+    hasToken(): boolean;
+    getRefreshToken(): string | null;
+    setRefreshFn(_fn: (refreshToken: string) => Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>): void;
+    setTokens(accessToken: string, refreshToken: string): void;
+    onTokenExpired(_callback: () => Promise<void>): void;
+    logout(): Promise<void>;
+}

package/dist/auth/static-provider.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaticAuthProvider = void 0;
+/**
+ * A read-only AuthProvider for SSR or static environments.
+ * It holds tokens in memory and does not attempt automatic refresh
+ * or storage persistence.
+ */
+class StaticAuthProvider {
+    constructor(accessToken, refreshToken = null) {
+        this.accessToken = accessToken;
+        this.refreshToken = refreshToken;
+        this.type = 'LOCAL';
+    }
+    async getToken() {
+        return this.accessToken;
+    }
+    hasToken() {
+        return !!this.accessToken || !!this.refreshToken;
+    }
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    setRefreshFn(_fn) {
+        // No-op: Static provider doesn't refresh automatically
+    }
+    setTokens(accessToken, refreshToken) {
+        this.accessToken = accessToken;
+        this.refreshToken = refreshToken;
+    }
+    onTokenExpired(_callback) {
+        // No-op
+    }
+    async logout() {
+        this.accessToken = null;
+        this.refreshToken = null;
+    }
+}
+exports.StaticAuthProvider = StaticAuthProvider;

package/dist/client.d.ts

@@ -10,6 +10,10 @@ export interface PHCMSClientConfig {
     baseURL: string;
     apiPrefix?: string;
     auth?: AuthProvider;
+    /** SSR 전용: 쿠키 등에서 뽑아낸 액세스 토큰을 직접 주입할 때 사용 */
+    accessToken?: string;
+    /** SSR 전용: 쿠키 등에서 뽑아낸 리프레시 토큰을 직접 주입할 때 사용 */
+    refreshToken?: string;
     timeout?: number;
     axiosInstance?: AxiosInstance;
 }

package/dist/client.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PHCMSClient = void 0;
 const axios_1 = __importDefault(require("axios"));
+const static_provider_1 = require("./auth/static-provider");
 const errors_1 = require("./errors");
 const auth_1 = require("./modules/auth");
 const channel_1 = require("./modules/channel");
@@ -43,9 +44,15 @@ class PHCMSClient {
         this.refreshQueue = [];
         this.normalizedApiPrefix = `/${(config.apiPrefix || '/api').replace(/^\/+|\/+$/g, '')}`;
         const normalizedApiPrefix = this.normalizedApiPrefix;
+        // If tokens are provided directly (SSR use case), and no auth provider is set,
+        // wrap them in a StaticAuthProvider to ensure interceptors work.
+        if ((config.accessToken || config.refreshToken) && !config.auth) {
+            this.config.auth = new static_provider_1.StaticAuthProvider(config.accessToken || null, config.refreshToken || null);
+        }
         this.axiosInstance = config.axiosInstance || axios_1.default.create({
             baseURL: config.baseURL,
             timeout: config.timeout || 10000,
+            withCredentials: true,
             headers: {
                 'Content-Type': 'application/json',
             },

package/dist/hooks/useUser.d.ts

@@ -43,6 +43,16 @@ export declare const useUser: () => {
     isAuthenticated: boolean;
     error: boolean;
 };
+/**
+ * Hook to fetch a user's public profile.
+ */
+export declare const useUserProfile: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
+    uid: string;
+    username: string | null;
+    display_name: string;
+    avatar_url: string | null;
+    profile_data: Record<string, any>;
+}, Error>;
 /**
  * Hook to update a user's profile.
  * Typically used by a user to update their own profile.

package/dist/hooks/useUser.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useAgreeTerms = exports.useChannelTerms = exports.useUpdateProfile = exports.useUser = exports.termsKeys = void 0;
+exports.useAgreeTerms = exports.useChannelTerms = exports.useUpdateProfile = exports.useUserProfile = exports.useUser = exports.termsKeys = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
 exports.termsKeys = {
@@ -15,6 +15,18 @@ const useUser = () => {
     return { data: user, isLoading, isAuthenticated, error: isError };
 };
 exports.useUser = useUser;
+/**
+ * Hook to fetch a user's public profile.
+ */
+const useUserProfile = (uid) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: ['user-profile', uid],
+        queryFn: () => client.user.getProfile(uid),
+        enabled: !!uid,
+    });
+};
+exports.useUserProfile = useUserProfile;
 /**
  * Hook to update a user's profile.
  * Typically used by a user to update their own profile.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './auth/firebase-provider';
 export * from './auth/interfaces';
 export * from './auth/jwt-utils';
 export * from './auth/local-provider';
+export * from './auth/static-provider';
 export * from './client';
 export * from './errors';
 export * from './modules/auth';

package/dist/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./auth/firebase-provider"), exports);
 __exportStar(require("./auth/interfaces"), exports);
 __exportStar(require("./auth/jwt-utils"), exports);
 __exportStar(require("./auth/local-provider"), exports);
+__exportStar(require("./auth/static-provider"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./modules/auth"), exports);

package/dist/modules/user.d.ts

@@ -1,9 +1,15 @@
-import { UpdateUserProfileRequest, UserDto } from "@ph-cms/api-contract";
+import { UpdateUserProfileRequest, UserDto, UserProfileDto } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
 export declare class UserModule {
     private client;
     private prefix;
     constructor(client: AxiosInstance, prefix?: string);
+    /**
+     * Retrieves a user's public profile.
+     *
+     * @param uid - The UID of the user.
+     */
+    getProfile(uid: string): Promise<UserProfileDto>;
     /**
      * Updates a user's profile.
      *

package/dist/modules/user.js

@@ -6,6 +6,14 @@ class UserModule {
         this.client = client;
         this.prefix = prefix;
     }
+    /**
+     * Retrieves a user's public profile.
+     *
+     * @param uid - The UID of the user.
+     */
+    async getProfile(uid) {
+        return this.client.get(`${this.prefix}/users/${uid}/profile`);
+    }
     /**
      * Updates a user's profile.
      *

package/dist/types.d.ts

@@ -5,7 +5,7 @@ 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 { UserDto, UserProfileDto } from '@ph-cms/api-contract';
 export type { ChannelDto, CheckHierarchyQuery } from '@ph-cms/api-contract';
 export type { ContentDto, ContentStatDto, ContentMediaDto, CreateContentRequest, ListContentQuery, PagedContentListResponse, UpdateContentRequest } from '@ph-cms/api-contract';
 export type { HierarchySetDto } from '@ph-cms/api-contract';

package/package.json

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