@ph-cms/client-sdk 0.1.1 → 0.1.2

package/README.md

@@ -2,24 +2,25 @@
 
 Unified PH-CMS client SDK for browser and React applications.
 
-This package is intended to be published to npm and provides:
+This package provides:
 
 - A typed API client
 - Auth provider interfaces and implementations
 - React context and hooks for consuming the client in UI code
+- **Integrated React Query support** (from v0.1.1)
 
 ## Installation
 
-Install the SDK itself with its runtime dependencies:
-
 ```bash
-npm install @ph-cms/client-sdk @ph-cms/api-contract axios zod
+npm install @ph-cms/client-sdk
 ```
 
-If you use the React bindings, also install the peer dependencies:
+> **Note:** `@tanstack/react-query` is a direct dependency from v0.1.1. You no longer need to install it manually unless you use it in your own application code.
+
+If you use the React bindings, ensure you have `react` installed:
 
 ```bash
-npm install react @tanstack/react-query
+npm install react react-dom
 ```
 
 If you use Firebase auth integration:
@@ -28,7 +29,7 @@ If you use Firebase auth integration:
 npm install firebase
 ```
 
-## Usage
+## Usage (Core SDK)
 
 ```ts
 import { PHCMSClient } from '@ph-cms/client-sdk';
@@ -37,36 +38,94 @@ const client = new PHCMSClient({
   baseURL: 'https://api.example.com',
 });
 
+// Use the modules directly
 const contents = await client.content.list({
   page: 1,
   limit: 20,
 });
 ```
 
-## React Usage
+## React Usage (v0.1.1+)
+
+From version 0.1.1, `PHCMSProvider` automatically includes a `QueryClientProvider`. You don't need to wrap your app with `QueryClientProvider` manually to use PH-CMS hooks.
 
-`react` and `@tanstack/react-query` are peer dependencies, so your application must provide them.
+### Basic Setup
 
 ```tsx
-import { PHCMSClient, PHCMSProvider, usePHCMS } from '@ph-cms/client-sdk';
+import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
+import { client } from './lib/sdk'; // Your pre-configured client
 
-const client = new PHCMSClient({ baseURL: 'https://api.example.com' });
+export function App() {
+  return (
+    <PHCMSProvider client={client}>
+      <YourComponents />
+    </PHCMSProvider>
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import { useContent, useUser } from '@ph-cms/client-sdk';
 
-function ContentCount() {
-  const sdk = usePHCMS();
-  // Use sdk.content / sdk.auth / sdk.channel / sdk.terms here.
-  return null;
+function MyComponent() {
+  const { data: user, isLoading: userLoading } = useUser();
+  const { data: contents, isLoading: contentLoading } = useContent();
+
+  if (userLoading || contentLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>Hello, {user?.email}</h1>
+      <ul>
+        {contents?.items.map(item => (
+          <li key={item.uid}>{item.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
 }
+```
+
+### Custom QueryClient (Optional)
+
+If your application already uses React Query and you want to share the cache/settings:
+
+```tsx
+import { QueryClient } from '@tanstack/react-query';
+import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
+
+const queryClient = new QueryClient();
+const client = new PHCMSClient({ baseURL: '...' });
 
 export function App() {
   return (
-    <PHCMSProvider client={client}>
-      <ContentCount />
+    <PHCMSProvider client={client} queryClient={queryClient}>
+      {/* Both your app and PH-CMS hooks will use the same queryClient */}
+      <YourComponents />
     </PHCMSProvider>
   );
 }
 ```
 
+## Admin SDK (@ph-cms/client-sdk-admin)
+
+For administrative tasks, use `@ph-cms/client-sdk-admin`. It follows the same provider pattern:
+
+```tsx
+import { PHCMSAdminProvider } from '@ph-cms/client-sdk-admin';
+import { adminClient } from './lib/sdk';
+
+export function App() {
+  return (
+    <PHCMSAdminProvider client={adminClient}>
+      <AdminComponents />
+    </PHCMSAdminProvider>
+  );
+}
+```
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -4,6 +4,7 @@ import { AuthModule } from './modules/auth';
 import { ContentModule } from './modules/content';
 import { ChannelModule } from './modules/channel';
 import { TermsModule } from './modules/terms';
+import { MediaModule } from './modules/media';
 export interface PHCMSClientConfig {
     baseURL: string;
     apiPrefix?: string;
@@ -17,5 +18,6 @@ export declare class PHCMSClient {
     readonly content: ContentModule;
     readonly channel: ChannelModule;
     readonly terms: TermsModule;
+    readonly media: MediaModule;
     constructor(config: PHCMSClientConfig);
 }

package/dist/client.js

@@ -10,6 +10,7 @@ const auth_1 = require("./modules/auth");
 const content_1 = require("./modules/content");
 const channel_1 = require("./modules/channel");
 const terms_1 = require("./modules/terms");
+const media_1 = require("./modules/media");
 class PHCMSClient {
     constructor(config) {
         this.config = config;
@@ -69,6 +70,7 @@ class PHCMSClient {
         this.content = new content_1.ContentModule(this.axiosInstance);
         this.channel = new channel_1.ChannelModule(this.axiosInstance);
         this.terms = new terms_1.TermsModule(this.axiosInstance);
+        this.media = new media_1.MediaModule(this.axiosInstance);
     }
 }
 exports.PHCMSClient = PHCMSClient;

package/dist/hooks/useMedia.d.ts

@@ -0,0 +1,32 @@
+export declare const mediaKeys: {
+    all: readonly ["media"];
+    details: () => readonly ["media", "detail"];
+    detail: (uid: string) => readonly ["media", "detail", string];
+};
+export declare const useMediaUploadTickets: () => import("@tanstack/react-query").UseMutationResult<{
+    mediaUid: string;
+    uploadUrl: string;
+    expiresAt: number;
+}[], Error, {
+    filename: string;
+    contentType: string;
+    fileSize: number;
+    width?: number | undefined;
+    height?: number | undefined;
+}[], unknown>;
+export declare const useUploadToS3: () => import("@tanstack/react-query").UseMutationResult<void, Error, {
+    url: string;
+    file: File | Blob;
+}, unknown>;
+export declare const useMediaDetail: (uid: string) => import("@tanstack/react-query").UseQueryResult<{
+    uid: string;
+    type: "image" | "video" | "audio" | "document" | "file";
+    url: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    order: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    description?: string | null | undefined;
+}, Error>;

package/dist/hooks/useMedia.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMediaDetail = exports.useUploadToS3 = exports.useMediaUploadTickets = exports.mediaKeys = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("../context");
+exports.mediaKeys = {
+    all: ['media'],
+    details: () => [...exports.mediaKeys.all, 'detail'],
+    detail: (uid) => [...exports.mediaKeys.details(), uid],
+};
+const useMediaUploadTickets = () => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (data) => client.media.getUploadTickets(data),
+    });
+};
+exports.useMediaUploadTickets = useMediaUploadTickets;
+const useUploadToS3 = () => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ url, file }) => client.media.uploadToS3(url, file),
+    });
+};
+exports.useUploadToS3 = useUploadToS3;
+const useMediaDetail = (uid) => {
+    const client = (0, context_1.usePHCMS)();
+    return (0, react_query_1.useQuery)({
+        queryKey: exports.mediaKeys.detail(uid),
+        queryFn: () => client.media.getMedia(uid),
+        enabled: !!uid,
+    });
+};
+exports.useMediaDetail = useMediaDetail;

package/dist/index.d.ts

@@ -7,9 +7,11 @@ export * from './modules/auth';
 export * from './modules/content';
 export * from './modules/channel';
 export * from './modules/terms';
+export * from './modules/media';
 export * from './context';
 export * from './hooks/useAuth';
 export * from './hooks/useContent';
 export * from './hooks/useChannel';
 export * from './hooks/useTerms';
+export * from './hooks/useMedia';
 export * from './types';

package/dist/index.js

@@ -23,9 +23,11 @@ __exportStar(require("./modules/auth"), exports);
 __exportStar(require("./modules/content"), exports);
 __exportStar(require("./modules/channel"), exports);
 __exportStar(require("./modules/terms"), exports);
+__exportStar(require("./modules/media"), exports);
 __exportStar(require("./context"), exports);
 __exportStar(require("./hooks/useAuth"), exports);
 __exportStar(require("./hooks/useContent"), exports);
 __exportStar(require("./hooks/useChannel"), exports);
 __exportStar(require("./hooks/useTerms"), exports);
+__exportStar(require("./hooks/useMedia"), exports);
 __exportStar(require("./types"), exports);

package/dist/modules/media.d.ts

@@ -0,0 +1,20 @@
+import { AxiosInstance } from "axios";
+import { MediaUploadTicketBatchRequest, MediaUploadTicketBatchResponse, ContentMediaDto } from "@ph-cms/api-contract";
+export declare class MediaModule {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * 미디어 업로드 티켓(Presigned URL) 발급 요청
+     */
+    getUploadTickets(data: MediaUploadTicketBatchRequest): Promise<MediaUploadTicketBatchResponse>;
+    /**
+     * 미디어 상세 정보 조회
+     */
+    getMedia(uid: string): Promise<ContentMediaDto>;
+    /**
+     * S3 Presigned URL을 사용하여 파일 직접 업로드
+     * @param url getUploadTickets를 통해 발급받은 uploadUrl
+     * @param file 업로드할 파일 객체 (File 또는 Blob)
+     */
+    uploadToS3(url: string, file: File | Blob): Promise<void>;
+}

package/dist/modules/media.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaModule = void 0;
+const axios_1 = __importDefault(require("axios"));
+const api_contract_1 = require("@ph-cms/api-contract");
+const errors_1 = require("../errors");
+class MediaModule {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 미디어 업로드 티켓(Presigned URL) 발급 요청
+     */
+    async getUploadTickets(data) {
+        const validation = api_contract_1.MediaUploadTicketBatchRequestSchema.safeParse(data);
+        if (!validation.success) {
+            throw new errors_1.ValidationError("Invalid upload ticket request", validation.error.errors);
+        }
+        return this.client.post('/api/media/upload-tickets', data);
+    }
+    /**
+     * 미디어 상세 정보 조회
+     */
+    async getMedia(uid) {
+        if (!uid)
+            throw new errors_1.ValidationError("Media UID is required", []);
+        return this.client.get(`/api/media/${uid}`);
+    }
+    /**
+     * S3 Presigned URL을 사용하여 파일 직접 업로드
+     * @param url getUploadTickets를 통해 발급받은 uploadUrl
+     * @param file 업로드할 파일 객체 (File 또는 Blob)
+     */
+    async uploadToS3(url, file) {
+        if (!url)
+            throw new errors_1.ValidationError("Upload URL is required", []);
+        // CMS API 전용 interceptor가 없는 순수 axios 인스턴스로 요청
+        // S3는 PUT 메서드를 사용하며, 티켓 발급 시 지정한 Content-Type과 일치해야 함
+        await axios_1.default.put(url, file, {
+            headers: {
+                'Content-Type': file.type,
+            },
+        });
+    }
+}
+exports.MediaModule = MediaModule;

package/package.json

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