@back23/promptly-sdk 2.14.2 → 2.18.1

package/README.md

@@ -1,290 +1,495 @@
 # @back23/promptly-sdk
 
-Official SDK for Promptly AI CMS - A headless CMS with built-in AI capabilities.
+Promptly AI CMS 공식 SDK - 헤드리스 CMS + 이커머스 + AI 기능을 제공합니다.
 
-## Installation
+**버전: 2.18.0**
+
+## 설치
 
 ```bash
 npm install @back23/promptly-sdk
 ```
 
-## Quick Start
+## 빠른 시작
 
 ```typescript
 import { Promptly } from '@back23/promptly-sdk';
 
 const client = new Promptly({
   tenantId: 'your-tenant-id',
-  apiKey: 'pky_xxxxxxxxxxxxxxxx', // Required - Get from Dashboard > Settings > API Tokens
-  baseUrl: 'https://promptly.webbyon.com', // Optional
+  apiKey: 'pky_xxxxxxxxxxxxxxxx',  // 필수 - Dashboard > Settings > API Tokens
+  baseUrl: 'https://promptly.webbyon.com',  // 선택
+
+  // 토큰 자동 저장 (로그인 유지)
+  persistToken: true,
+  storageType: 'localStorage',  // 또는 'sessionStorage'
+  onAuthStateChange: (token, user) => {
+    console.log('Auth changed:', user);
+  },
 });
 
-// Fetch blog posts
-const { data: posts, meta } = await client.blog.list();
+// 블로그 조회
+const { data: posts } = await client.blog.list();
 
-// Fetch products
+// 상품 조회
 const { data: products } = await client.shop.listProducts();
 ```
 
-## Authentication
+---
+
+## 인증 (Auth)
 
-All API requests require an API key. Get yours from **Dashboard > Settings > API Tokens**.
+### 기본 설정
 
 ```typescript
 const client = new Promptly({
   tenantId: 'demo',
-  apiKey: 'pky_xxxxxxxxxxxxxxxx', // Required
+  apiKey: 'pky_xxxxxxxxxxxxxxxx',  // 필수
+  persistToken: true,  // 토큰 자동 저장
 });
 ```
 
-For member-specific operations (orders, profile, etc.), authenticate first:
+### 토큰 자동 저장
+
+`persistToken: true` 설정 시:
+- **로그인**: `localStorage`에 자동 저장
+- **새로고침**: 토큰 자동 복원
+- **로그아웃**: 토큰 자동 삭제
+- **저장 키**: `promptly_auth_token_{tenantId}`
 
 ```typescript
-// Login
-await client.auth.login({ email: 'user@example.com', password: 'password' });
+const client = new Promptly({
+  tenantId: 'demo',
+  apiKey: 'pky_xxx',
+  persistToken: true,
+  storageType: 'localStorage',  // 기본값, 또는 'sessionStorage'
+  onAuthStateChange: (token, user) => {
+    // 로그인/로그아웃 시 호출
+    if (token) {
+      console.log('Logged in:', user);
+    } else {
+      console.log('Logged out');
+    }
+  },
+});
+```
 
-// Now member-only APIs work
-const profile = await client.members.getProfile();
-const orders = await client.orders.list();
+### 로그인/회원가입
 
-// Check auth status
-client.isAuthenticated(); // true
+```typescript
+// 회원가입
+await client.auth.register({
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'password',
+  password_confirmation: 'password',
+});
+
+// 로그인 (토큰 자동 저장됨)
+const { member, token } = await client.auth.login({
+  email: 'john@example.com',
+  password: 'password',
+});
 
-// Logout
+// 로그아웃 (토큰 자동 삭제됨)
 await client.auth.logout();
+
+// 인증 상태 확인
+client.auth.isAuthenticated();  // true/false
+
+// 현재 사용자
+const me = await client.auth.me();
+
+// 프로필 수정
+await client.auth.updateProfile({ name: 'New Name' });
+```
+
+### 소셜 로그인
+
+```typescript
+// 사용 가능한 프로바이더
+const providers = await client.auth.getSocialProviders();
+// ['google', 'kakao', 'naver']
+
+// 로그인 URL 획득
+const { url } = await client.auth.getSocialAuthUrl('google');
+window.location.href = url;
+
+// 콜백 처리 (리다이렉트 후)
+const { member, token } = await client.auth.socialCallback('google', code);
+```
+
+### 비밀번호 재설정
+
+```typescript
+// 재설정 이메일 발송
+await client.auth.forgotPassword({ email: 'john@example.com' });
+
+// 비밀번호 재설정
+await client.auth.resetPassword({
+  token: 'reset-token',
+  email: 'john@example.com',
+  password: 'newpassword',
+  password_confirmation: 'newpassword',
+});
 ```
 
-## API Reference
+---
 
-### Blog
+## Blog API
 
 ```typescript
-// List posts
+// 목록 조회
 const { data, meta } = await client.blog.list({
   page: 1,
   per_page: 10,
-  category: 'tech',    // Optional filter
-  tag: 'laravel',      // Optional filter
-  search: 'keyword',   // Optional search
+  category: 'tech',
+  tag: 'laravel',
+  search: 'keyword',
 });
 
-// Get single post
+// 상세 조회
 const post = await client.blog.get('post-slug');
 
-// Get featured posts
+// 추천 글
 const featured = await client.blog.featured(5);
 
-// Filter by category/tag
+// 카테고리/태그별 필터
 const { data } = await client.blog.byCategory('news');
 const { data } = await client.blog.byTag('featured');
 
-// Get all categories and tags
-const categories = await client.blog.categories(); // string[]
-const tags = await client.blog.tags();             // string[]
+// 카테고리/태그 목록
+const categories = await client.blog.categories();  // string[]
+const tags = await client.blog.tags();  // string[]
 ```
 
-**BlogPost Type:**
-```typescript
-interface BlogPost {
-  id: number;
-  title: string;
-  slug: string;
-  excerpt: string;
-  featured_image: string | null;
-  category: string | null;
-  tags: string[];
-  author: string;
-  views: number;
-  status: string;
-  published_at: string | null;
-  created_at: string;
-  content?: string;      // Detail view only
-  updated_at?: string;   // Detail view only
-}
-```
+---
 
-### Boards
+## Boards API
 
 ```typescript
-// List boards
+// 게시판 목록
 const { data: boards } = await client.boards.list();
 
-// Get board
+// 게시판 조회
 const board = await client.boards.get('board-slug');
 
-// List posts
+// 게시글 목록
 const { data: posts } = await client.boards.listPosts('board-slug', {
   page: 1,
   per_page: 10,
   search: 'keyword',
 });
 
-// Get post
+// 게시글 상세
 const post = await client.boards.getPost(postId);
 
-// Create post (auth required)
+// 게시글 작성 (인증 필요)
 await client.boards.createPost({
   board_id: 1,
   title: 'Title',
   content: 'Content',
+  is_secret: false,
 });
 
-// Update/Delete post (auth required)
+// 게시글 수정/삭제
 await client.boards.updatePost(postId, { title: 'New Title' });
 await client.boards.deletePost(postId);
 ```
 
-### Comments
+---
+
+## Comments API
 
-Supports three comment types: board posts, blog posts, and standalone pages (guestbook).
+게시판, 블로그, 독립 댓글(방명록) 지원
 
 ```typescript
-// Board post comments
+// 게시판 댓글
 const { data } = await client.comments.boardPost(postId);
 await client.comments.createBoardPost(postId, {
   author_name: 'John',
-  content: 'Great post!',
-  password: '1234',  // For guest comments
+  content: 'Great!',
+  password: '1234',  // 비회원 댓글
 });
 
-// Blog post comments
+// 블로그 댓글
 const { data } = await client.comments.blogPost('post-slug');
 await client.comments.createBlogPost('post-slug', {
-  author_name: 'Jane',
   content: 'Nice article!',
 });
 
-// Standalone comments (guestbook)
+// 독립 댓글 (방명록)
 const { data } = await client.comments.standalone('guestbook');
 await client.comments.createStandalone('guestbook', {
   author_name: 'Visitor',
   content: 'Hello!',
 });
 
-// Common operations
+// 공통
 await client.comments.update(commentId, { content: 'Updated' });
 await client.comments.delete(commentId, { password: '1234' });
 await client.comments.like(commentId);
 ```
 
-### Shop
+---
+
+## Shop API
+
+### 상품
 
 ```typescript
-// Products
+// 상품 목록
 const { data: products } = await client.shop.listProducts({
-  category: 'electronics',
+  category: 'shoes',
   is_featured: true,
+  min_price: 10000,
+  max_price: 50000,
+  search: 'keyword',
 });
+
+// 상품 상세
 const product = await client.shop.getProduct('product-slug');
+
+// 추천 상품
 const featured = await client.shop.featuredProducts(8);
+
+// 카테고리 목록
 const categories = await client.shop.listCategories();
+```
+
+### 상품 리뷰
+
+```typescript
+// 리뷰 목록
+const { data: reviews, stats } = await client.shop.getProductReviews('product-slug', {
+  page: 1,
+  per_page: 10,
+  rating: 5,  // 별점 필터
+});
+
+// 리뷰 통계
+// stats = { average_rating: 4.5, total_count: 123, rating_counts: { 5: 80, 4: 30, ... } }
+
+// 리뷰 작성 (인증 + 구매 필요)
+await client.shop.createProductReview('product-slug', {
+  rating: 5,
+  title: 'Great product!',
+  content: 'Highly recommended.',
+  images: ['https://...'],
+});
+
+// 리뷰 수정/삭제
+await client.shop.updateProductReview(reviewId, { rating: 4 });
+await client.shop.deleteProductReview(reviewId);
+
+// 도움이 됐어요
+await client.shop.markReviewHelpful(reviewId);
+
+// 내 리뷰 목록
+const { data: myReviews } = await client.shop.getMyReviews();
+```
+
+### 장바구니 (인증 필요)
 
-// Cart (auth required)
+```typescript
+// 장바구니 조회
 const cart = await client.shop.getCart();
-await client.shop.addToCart({ product_id: 1, quantity: 2 });
+
+// 상품 추가
+await client.shop.addToCart({
+  product_id: 1,
+  quantity: 2,
+  variant_id: 3,  // 옵션 상품
+});
+
+// 수량 변경
 await client.shop.updateCartItem(itemId, { quantity: 3 });
+
+// 상품 제거
 await client.shop.removeFromCart(itemId);
+
+// 장바구니 비우기
 await client.shop.clearCart();
+```
 
-// Orders (auth required)
+### 주문 (인증 필요)
+
+```typescript
+// 주문 생성
 const order = await client.shop.createOrder({
   orderer_name: 'John Doe',
   orderer_email: 'john@example.com',
-  orderer_phone: '555-1234',
+  orderer_phone: '010-1234-5678',
   shipping_name: 'John Doe',
-  shipping_phone: '555-1234',
+  shipping_phone: '010-1234-5678',
   shipping_zipcode: '12345',
-  shipping_address: '123 Main St',
-  shipping_address_detail: 'Apt 101',
+  shipping_address: '서울시 강남구',
+  shipping_address_detail: '101동 101호',
+  shipping_memo: '부재시 경비실',
+  coupon_code: 'SAVE10',
 });
+
+// 주문 목록
 const { data: orders } = await client.shop.listOrders();
+
+// 주문 상세
 const orderDetail = await client.shop.getOrder(orderId);
+
+// 주문 취소
 await client.shop.cancelOrder(orderId);
+```
+
+### 결제 (토스페이먼츠)
 
-// Coupons
-const validation = await client.shop.validateCoupon('SAVE10', 50000);
-const myCoupons = await client.shop.myCoupons();
+```typescript
+// 결제 준비
+const payment = await client.shop.preparePayment({
+  order_number: 'ORD-123',
+  success_url: 'https://mysite.com/payment/success',
+  fail_url: 'https://mysite.com/payment/fail',
+});
+// payment = { client_key, order_id, order_name, amount, customer_name, ... }
+
+// 결제 승인 (토스 결제 완료 후)
+await client.shop.confirmPayment({
+  payment_key: 'toss_payment_key',
+  order_id: 'ORD-123',
+  amount: 50000,
+});
 ```
 
-### Reservation
+### 쿠폰
+
+```typescript
+// 쿠폰 검증
+const result = await client.shop.validateCoupon('SAVE10', 50000);
+// { valid: true, discount_amount: 5000, coupon: { ... } }
+
+// 내 쿠폰 목록
+const coupons = await client.shop.myCoupons();
+```
+
+### 배송 설정
+
+```typescript
+const settings = await client.shop.getShippingSettings();
+// { base_fee, free_shipping_threshold, ... }
+```
+
+---
+
+## Reservation API
+
+### 공개 API
 
 ```typescript
-// Public APIs
+// 예약 설정
 const settings = await client.reservation.getSettings();
+
+// 서비스 목록
 const services = await client.reservation.listServices();
+
+// 담당자 목록
 const staff = await client.reservation.listStaff(serviceId);
 
-// Get available dates/slots
+// 예약 가능 날짜
 const dates = await client.reservation.getAvailableDates({
   service_id: 1,
   staff_id: 2,
   start_date: '2026-01-01',
   end_date: '2026-01-31',
 });
+
+// 예약 가능 시간
 const slots = await client.reservation.getAvailableSlots({
   service_id: 1,
   date: '2026-01-15',
   staff_id: 2,
 });
+```
 
-// Create reservation (auth required)
-const result = await client.reservation.create({
+### 예약 관리 (인증 필요)
+
+```typescript
+// 예약 생성
+await client.reservation.create({
   service_id: 1,
   staff_id: 2,
   reservation_date: '2026-01-15',
   start_time: '14:00',
   customer_name: 'John Doe',
-  customer_phone: '555-1234',
+  customer_phone: '010-1234-5678',
+  customer_email: 'john@example.com',
+  notes: '요청사항',
 });
 
-// My reservations (auth required)
+// 내 예약 목록
 const { data } = await client.reservation.list({ status: 'confirmed' });
+
+// 다가오는/지난 예약
 const upcoming = await client.reservation.upcoming(5);
 const past = await client.reservation.past(10);
-await client.reservation.cancel('RES-20260115-001', 'Schedule change');
+
+// 예약 취소
+await client.reservation.cancel('RES-20260115-001', '일정 변경');
 ```
 
-### Forms
+---
+
+## Forms API
 
 ```typescript
-// List forms
+// 폼 목록
 const { data: forms } = await client.forms.list();
 
-// Get form with fields
+// 폼 상세 (필드 정보 포함)
 const form = await client.forms.get('contact');
 
-// Submit form
+// 폼 제출
 await client.forms.submit('contact', {
   name: 'John Doe',
   email: 'john@example.com',
   message: 'Hello!',
 });
 
-// My submissions (auth required)
+// 내 제출 목록 (인증 필요)
 const { data: submissions } = await client.forms.mySubmissions();
 ```
 
-### Media (Auth Required)
+---
+
+## Media API (인증 필요)
 
 ```typescript
-// Upload
+// 파일 업로드
 const media = await client.media.upload(file);
+
+// 여러 파일 업로드
 const mediaList = await client.media.uploadMultiple([file1, file2]);
 
-// List & Delete
+// 내 미디어 목록
 const { data: myMedia } = await client.media.list({ type: 'image/jpeg' });
+
+// 미디어 삭제
 await client.media.delete(mediaId);
 ```
 
-### Custom Entities
+---
+
+## Custom Entities API
+
+동적 데이터 구조 생성/관리
 
-Dynamic data structures for custom use cases.
+### 엔티티 정의
 
 ```typescript
-// Entity definitions
+// 엔티티 목록
 const entities = await client.entities.list();
+
+// 엔티티 조회
 const entity = await client.entities.get('customers');
 
+// 엔티티 생성
 await client.entities.create({
   name: 'Customer',
   slug: 'customers',
@@ -300,74 +505,57 @@ await client.entities.create({
   },
 });
 
+// 엔티티 수정/삭제
 await client.entities.update('customers', { name: 'Clients' });
-await client.entities.delete('customers', true); // force delete
+await client.entities.delete('customers', true);  // force
+```
 
-// Records
+### 레코드
+
+```typescript
+// 레코드 목록
 const { data: records } = await client.entities.listRecords('customers', {
   search: 'ACME',
   filters: JSON.stringify({ status: 'active' }),
 });
+
+// 레코드 조회
 const record = await client.entities.getRecord('customers', 1);
 
+// 레코드 생성
 await client.entities.createRecord('customers', {
   company: 'ACME Corp',
   email: 'contact@acme.com',
   status: 'active',
 });
+
+// 레코드 수정/삭제
 await client.entities.updateRecord('customers', 1, { status: 'inactive' });
 await client.entities.deleteRecord('customers', 1);
+```
 
-// TypeScript support
+### TypeScript 지원
+
+```typescript
 interface Customer {
   company: string;
   email: string;
   status: 'active' | 'inactive';
 }
+
 const customers = client.entities.typed<Customer>('customers');
-const { data } = await customers.list();
+const { data } = await customers.list();  // data: Customer[]
 ```
 
-### Auth
+---
 
-```typescript
-// Register
-await client.auth.register({
-  name: 'John Doe',
-  email: 'john@example.com',
-  password: 'password',
-  password_confirmation: 'password',
-});
+## 응답 타입
 
-// Login/Logout
-const { member, token } = await client.auth.login({
-  email: 'john@example.com',
-  password: 'password',
-});
-await client.auth.logout();
-
-// Profile
-const me = await client.auth.me();
-await client.auth.updateProfile({ name: 'New Name' });
-
-// Token management
-client.setToken('saved-token');
-const token = client.getToken();
-client.isAuthenticated();
-
-// Social login
-const providers = await client.auth.getSocialProviders();
-const { url } = await client.auth.getSocialAuthUrl('google');
-const response = await client.auth.socialCallback('google', code);
-```
-
-## Response Types
-
-All list APIs return a consistent format:
+모든 목록 API는 일관된 형식 반환:
 
 ```typescript
 interface ListResponse<T> {
-  data: T[];  // Always an array, never null
+  data: T[];  // 항상 배열, null 아님
   meta: {
     current_page: number;
     last_page: number;
@@ -379,7 +567,9 @@ interface ListResponse<T> {
 }
 ```
 
-## Error Handling
+---
+
+## 에러 처리
 
 ```typescript
 import { Promptly, PromptlyError } from '@back23/promptly-sdk';
@@ -395,15 +585,21 @@ try {
 }
 ```
 
-## React Example
+---
+
+## React 예시
 
 ```tsx
+'use client';
+
 import { useState, useEffect } from 'react';
 import { Promptly } from '@back23/promptly-sdk';
 
+// 싱글톤 클라이언트
 const client = new Promptly({
-  tenantId: 'demo',
+  tenantId: process.env.NEXT_PUBLIC_PROMPTLY_TENANT_ID!,
   apiKey: process.env.NEXT_PUBLIC_PROMPTLY_API_KEY!,
+  persistToken: true,
 });
 
 function BlogList() {
@@ -424,8 +620,6 @@ function BlogList() {
         <article key={post.id}>
           <h2>{post.title}</h2>
           <p>{post.excerpt}</p>
-          <span>{post.category}</span>
-          {post.tags.map(tag => <span key={tag}>{tag}</span>)}
         </article>
       ))}
     </div>
@@ -433,25 +627,41 @@ function BlogList() {
 }
 ```
 
+---
+
 ## Changelog
 
+### v2.18.0
+- 상품 리뷰 API 추가
+- 배송 설정 API 추가
+
+### v2.15.0
+- 토스페이먼츠 결제 API 추가
+
 ### v2.12.0
-- Added `category`, `tags`, `views`, `published_at` fields to BlogPost response
-- Added `GET /blog/categories` and `GET /blog/tags` endpoints
+- 블로그 카테고리/태그 필터 추가
+- `category`, `tags`, `views`, `published_at` 필드 추가
+
+### v2.10.0
+- `persistToken` 옵션 추가 (토큰 자동 저장)
+- `onAuthStateChange` 콜백 추가
+- `storageType` 옵션 추가
 
 ### v2.5.0
-- Added `is_secret` and `is_mine` fields to BoardPost
+- 게시판 비밀글 지원 (`is_secret`, `is_mine`)
 
 ### v2.3.0
-- Polymorphic comments API (board, blog, standalone)
+- 다형성 댓글 API (board, blog, standalone)
 
 ### v2.0.0
-- **Breaking:** API key required for all requests
+- **Breaking:** API key 필수
 
 ### v1.3.0
-- Unified `ListResponse<T>` format for all list APIs
-- Reservation system support
+- `ListResponse<T>` 통일
+- 예약 시스템 지원
+
+---
 
-## License
+## 라이선스
 
 MIT