@back23/promptly-sdk 2.5.0 → 2.7.0

package/README.md

@@ -26,16 +26,16 @@ const products = await client.shop.listProducts();
 
 ## v2.5.0 Changes
 
-### BoardPost 타입 확장
+### BoardPost Type Extension
 
-게시글에 `is_secret`, `is_mine` 필드가 추가되었습니다.
+Added `is_secret` and `is_mine` fields to posts.
 
 ```typescript
 interface BoardPost {
-  // ... 기존 필드
-  is_notice: boolean;  // 공지 여부
-  is_secret: boolean;  // 비밀글 여부
-  is_mine: boolean;    // 현재 로그인 사용자의 글 여부
+  // ... existing fields
+  is_notice: boolean;  // Whether it's a notice
+  is_secret: boolean;  // Whether it's a secret post
+  is_mine: boolean;    // Whether current logged-in user is the author
 }
 ```
 
@@ -45,19 +45,19 @@ interface BoardPost {
 
 ### Dual Authentication Support Fixed
 
-API Key와 Bearer Token이 동시에 전송되도록 수정되었습니다. 이전 버전에서는 API Key가 설정되어 있으면 Authorization 헤더가 무시되어 로그인 후 멤버 전용 API 호출이 실패하는 문제가 있었습니다.
+Fixed issue where API Key and Bearer Token are now sent simultaneously. In previous versions, when API Key was set, the Authorization header was ignored, causing member-only API calls to fail after login.
 
 ```typescript
-// 이제 API Key + Bearer Token 동시 사용 가능
+// API Key + Bearer Token now work together
 const client = new Promptly({
   tenantId: 'demo',
-  apiKey: 'pky_xxx',  // X-API-Key 헤더
+  apiKey: 'pky_xxx',  // X-API-Key header
 });
 
-// 로그인 후 토큰 설정
+// Set token after login
 await client.auth.login({ email, password });
 
-// 멤버 전용 API 정상 동작 (Authorization: Bearer xxx 헤더 포함)
+// Member-only APIs work correctly (Authorization: Bearer xxx header included)
 const profile = await client.members.getProfile();
 const orders = await client.orders.list();
 ```
@@ -68,33 +68,33 @@ const orders = await client.orders.list();
 
 ### Polymorphic Comments API
 
-댓글 시스템이 재설계되어 게시판, 블로그, 방명록(독립 페이지) 등 다양한 곳에서 사용할 수 있습니다.
+The comment system has been redesigned to support various use cases including boards, blogs, and guestbooks (standalone pages).
 
 ```typescript
-// 게시판 글 댓글
+// Board post comments
 const boardComments = await client.comments.boardPost(postId);
 await client.comments.createBoardPost(postId, {
-  author_name: '홍길동',
-  content: '댓글 내용',
-  password: '1234', // 비회원 댓글용
+  author_name: 'John Doe',
+  content: 'Comment content',
+  password: '1234', // For guest comments
 });
 
-// 블로그 글 댓글
+// Blog post comments
 const blogComments = await client.comments.blogPost('post-slug');
 await client.comments.createBlogPost('post-slug', {
   author_name: 'Jane',
   content: 'Great post!',
 });
 
-// 방명록 (독립 페이지)
+// Guestbook (standalone page)
 const guestbook = await client.comments.standalone('guestbook');
 await client.comments.createStandalone('guestbook', {
-  author_name: '방문자',
-  content: '안녕하세요!',
+  author_name: 'Visitor',
+  content: 'Hello!',
 });
 
-// 공통 기능
-await client.comments.update(commentId, { content: '수정된 댓글' });
+// Common features
+await client.comments.update(commentId, { content: 'Updated comment' });
 await client.comments.delete(commentId, { password: '1234' });
 await client.comments.like(commentId);
 ```
@@ -105,46 +105,46 @@ await client.comments.like(commentId);
 
 ### Entity Definition CRUD
 
-이제 API/SDK에서 직접 커스텀 엔티티 정의를 생성/수정/삭제할 수 있습니다.
+You can now create/update/delete custom entity definitions directly from the API/SDK.
 
 ```typescript
-// 엔티티 정의 생성
+// Create entity definition
 const entity = await client.entities.create({
-  name: '고객',
+  name: 'Customer',
   slug: 'customers',  // optional, auto-generated from name
-  description: '고객 관리',
+  description: 'Customer management',
   schema: {
     fields: [
-      { name: 'company', label: '회사명', type: 'text', required: true },
-      { name: 'email', label: '이메일', type: 'email', required: true },
-      { name: 'status', label: '상태', type: 'select', options: [
-        { value: 'active', label: '활성' },
-        { value: 'inactive', label: '비활성' }
+      { name: 'company', label: 'Company Name', type: 'text', required: true },
+      { name: 'email', label: 'Email', type: 'email', required: true },
+      { name: 'status', label: 'Status', type: 'select', options: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' }
       ]}
     ]
   },
   icon: 'users'
 });
 
-// 엔티티 정의 조회
+// Get entity definition
 const entity = await client.entities.get('customers');
 
-// 엔티티 정의 수정
-await client.entities.update('customers', { name: '고객사' });
+// Update entity definition
+await client.entities.update('customers', { name: 'Clients' });
 
-// 엔티티 정의 삭제 (레코드 있으면 force 필요)
+// Delete entity definition (requires force if records exist)
 await client.entities.delete('customers', true);
 ```
 
 ### Record API Path Change
 
-레코드 API 경로가 변경되었습니다:
+The record API path has changed:
 
 ```typescript
-// v2.1.0 이전
+// Before v2.1.0
 await client.entities.createRecord('customers', { data: { company: 'ACME' } });
 
-// v2.2.0 이후 - data wrapper 불필요
+// v2.2.0 and later - no data wrapper needed
 await client.entities.createRecord('customers', { company: 'ACME' });
 ```
 
@@ -225,275 +225,275 @@ data.map(post => ...);  // data is always an array
 
 ## API Reference
 
-### Boards (게시판)
+### Boards
 
 ```typescript
-// 게시판 목록
+// List boards
 const { data: boards, meta } = await client.boards.list();
 // Returns: ListResponse<Board>
 
-// 게시판 상세
+// Get board details
 const board = await client.boards.get('first'); // slug or id
 // Returns: Board
 
-// 게시판 글 목록
+// List board posts
 const { data: posts, meta } = await client.boards.listPosts('first', {
   page: 1,
   per_page: 10,
-  search: '검색어', // optional
+  search: 'keyword', // optional
 });
 // Returns: ListResponse<BoardPost>
 
-// 글 상세
+// Get post details
 const post = await client.boards.getPost(1);
 // Returns: BoardPost
 
-// 댓글 목록
+// List comments
 const comments = await client.boards.listComments(1);
 // Returns: BoardComment[] (always an array)
 ```
 
-### Posts & Comments - Protected (로그인 필요)
+### Posts & Comments - Protected (Login Required)
 
 ```typescript
-// 먼저 로그인
+// Login first
 await client.auth.login({ email: 'user@example.com', password: 'password' });
 
-// 글 작성
+// Create post
 const newPost = await client.boards.createPost({
   board_id: 1,
-  title: '제목',
-  content: '내용',
+  title: 'Title',
+  content: 'Content',
   is_notice: false,
 });
 
-// 글 수정
+// Update post
 await client.boards.updatePost(postId, {
-  title: '수정된 제목',
-  content: '수정된 내용',
+  title: 'Updated title',
+  content: 'Updated content',
 });
 
-// 글 삭제
+// Delete post
 await client.boards.deletePost(postId);
 
-// 댓글 작성
+// Create comment
 await client.boards.createComment(postId, {
-  content: '댓글 내용',
-  parent_id: null, // 대댓글이면 부모 댓글 ID
+  content: 'Comment content',
+  parent_id: null, // Parent comment ID for replies
 });
 
-// 댓글 수정
+// Update comment
 await client.boards.updateComment(commentId, {
-  content: '수정된 댓글',
+  content: 'Updated comment',
 });
 
-// 댓글 삭제
+// Delete comment
 await client.boards.deleteComment(commentId);
 ```
 
-### Blog (블로그)
+### Blog
 
 ```typescript
-// 블로그 글 목록
+// List blog posts
 const { data: posts, meta } = await client.blog.list({
   page: 1,
   per_page: 10,
   category: 'news', // optional
   tag: 'featured',  // optional
-  search: '검색어', // optional
+  search: 'keyword', // optional
 });
 // Returns: ListResponse<BlogPost>
 
-// 블로그 글 상세
+// Get blog post details
 const post = await client.blog.get('post-slug');
 // Returns: BlogPost
 
-// 추천 글
+// Featured posts
 const featured = await client.blog.featured(5);
 // Returns: BlogPost[] (always an array)
 
-// 카테고리별 조회
+// Get posts by category
 const { data: newsPosts } = await client.blog.byCategory('news');
 
-// 태그별 조회
+// Get posts by tag
 const { data: taggedPosts } = await client.blog.byTag('featured');
 
-// 카테고리 목록
+// List categories
 const categories = await client.blog.categories();
 // Returns: string[] (always an array)
 
-// 태그 목록
+// List tags
 const tags = await client.blog.tags();
 // Returns: string[] (always an array)
 ```
 
-### Comments (댓글)
+### Comments
 
-3가지 댓글 유형을 지원합니다:
-- **게시판 댓글** (`board_post`)
-- **블로그 댓글** (`blog_post`)
-- **방명록/독립 댓글** (`page`)
+Three comment types are supported:
+- **Board comments** (`board_post`)
+- **Blog comments** (`blog_post`)
+- **Guestbook/Standalone comments** (`page`)
 
 ```typescript
-// 게시판 글 댓글 조회
+// Get board post comments
 const { data: comments, meta } = await client.comments.boardPost(postId, {
   page: 1,
   per_page: 20,
 });
 // Returns: ListResponse<Comment>
 
-// 게시판 글 댓글 작성
+// Create board post comment
 await client.comments.createBoardPost(postId, {
-  author_name: '홍길동',
+  author_name: 'John Doe',
   author_email: 'user@example.com',
-  content: '댓글 내용',
-  password: '1234',     // 비회원용
-  parent_id: null,      // 대댓글이면 부모 댓글 ID
-  is_secret: false,     // 비밀 댓글 여부
+  content: 'Comment content',
+  password: '1234',     // For guest comments
+  parent_id: null,      // Parent comment ID for replies
+  is_secret: false,     // Secret comment flag
 });
 
-// 블로그 글 댓글 조회
+// Get blog post comments
 const { data: blogComments } = await client.comments.blogPost('post-slug');
 // Returns: ListResponse<Comment>
 
-// 블로그 글 댓글 작성
+// Create blog post comment
 await client.comments.createBlogPost('post-slug', {
   author_name: 'Jane',
   content: 'Great post!',
 });
 
-// 방명록 댓글 조회 (page_slug로 구분)
+// Get guestbook comments (identified by page_slug)
 const { data: guestbook } = await client.comments.standalone('guestbook');
 // Returns: ListResponse<Comment>
 
-// 방명록 댓글 작성
+// Create guestbook comment
 await client.comments.createStandalone('guestbook', {
-  author_name: '방문자',
-  content: '안녕하세요!',
+  author_name: 'Visitor',
+  content: 'Hello!',
 });
 
-// 댓글 수정
+// Update comment
 await client.comments.update(commentId, {
-  content: '수정된 댓글',
-  password: '1234', // 비회원이 작성한 댓글인 경우
+  content: 'Updated comment',
+  password: '1234', // Required for guest comments
 });
 
-// 댓글 삭제
+// Delete comment
 await client.comments.delete(commentId, {
-  password: '1234', // 비회원이 작성한 댓글인 경우
+  password: '1234', // Required for guest comments
 });
 
-// 댓글 좋아요
+// Like comment
 const result = await client.comments.like(commentId);
 // Returns: { data: { likes: number } }
 ```
 
-### Shop (쇼핑)
+### Shop
 
-#### Public (로그인 불필요)
+#### Public (No Login Required)
 
 ```typescript
-// 상품 목록
+// List products
 const { data: products, meta } = await client.shop.listProducts({
   page: 1,
   per_page: 10,
   category: 'electronics', // optional
   is_featured: true,       // optional
-  search: '검색어',        // optional
+  search: 'keyword',       // optional
 });
 // Returns: ListResponse<Product>
 
-// 상품 상세
+// Get product details
 const product = await client.shop.getProduct('product-slug');
 // Returns: Product
 
-// 추천 상품
+// Featured products
 const featured = await client.shop.featuredProducts(8);
 // Returns: Product[] (always an array)
 
-// 카테고리 목록
+// List categories
 const categories = await client.shop.listCategories();
 // Returns: ProductCategory[] (always an array)
 ```
 
-#### Protected (로그인 필요)
+#### Protected (Login Required)
 
 ```typescript
-// 장바구니 조회
+// Get cart
 const cart = await client.shop.getCart();
 // Returns: Cart
 
-// 장바구니 추가
+// Add to cart
 await client.shop.addToCart({
   product_id: 1,
   quantity: 2,
-  variant_id: 10, // optional - 옵션상품인 경우
+  variant_id: 10, // optional - for variant products
 });
 
-// 장바구니 수량 변경
+// Update cart item quantity
 await client.shop.updateCartItem(itemId, { quantity: 3 });
 
-// 장바구니 삭제
+// Remove from cart
 await client.shop.removeFromCart(itemId);
 
-// 장바구니 비우기
+// Clear cart
 await client.shop.clearCart();
 
-// 주문 생성
+// Create order
 const order = await client.shop.createOrder({
-  orderer_name: '홍길동',
-  orderer_email: 'hong@example.com',
-  orderer_phone: '010-1234-5678',
-  shipping_name: '홍길동',
-  shipping_phone: '010-1234-5678',
+  orderer_name: 'John Doe',
+  orderer_email: 'john@example.com',
+  orderer_phone: '555-123-4567',
+  shipping_name: 'John Doe',
+  shipping_phone: '555-123-4567',
   shipping_zipcode: '12345',
-  shipping_address: '서울시 강남구',
-  shipping_address_detail: '101호',
-  shipping_memo: '문 앞에 놓아주세요',
+  shipping_address: '123 Main St',
+  shipping_address_detail: 'Apt 101',
+  shipping_memo: 'Leave at door',
   coupon_code: 'SAVE10', // optional
 });
 
-// 주문 목록
+// List orders
 const { data: orders, meta } = await client.shop.listOrders();
 // Returns: ListResponse<Order>
 
-// 주문 상세
+// Get order details
 const order = await client.shop.getOrder(orderId);
 // Returns: Order
 
-// 주문 취소
+// Cancel order
 await client.shop.cancelOrder(orderId);
 
-// 쿠폰 검증
+// Validate coupon
 const validation = await client.shop.validateCoupon('SAVE10', 50000);
 // Returns: { valid: boolean, discount_amount: number, coupon: Coupon }
 
-// 내 쿠폰 목록
+// My coupons
 const coupons = await client.shop.myCoupons();
 // Returns: Coupon[] (always an array)
 ```
 
-### Reservation (예약) - NEW in v1.3.0
+### Reservation - NEW in v1.3.0
 
-#### Public (로그인 불필요)
+#### Public (No Login Required)
 
 ```typescript
-// 예약 설정 조회
+// Get reservation settings
 const settings = await client.reservation.getSettings();
 // Returns: ReservationSettings
 
-// 서비스 목록
+// List services
 const services = await client.reservation.listServices();
 // Returns: ReservationService[] (always an array)
 
-// 담당자 목록
+// List staff
 const staffs = await client.reservation.listStaff();
 // Returns: ReservationStaff[] (always an array)
 
-// 특정 서비스의 담당자만 조회
+// Get staff for specific service
 const serviceStaffs = await client.reservation.listStaff(serviceId);
 
-// 예약 가능 날짜 조회
+// Get available dates
 const dates = await client.reservation.getAvailableDates({
   service_id: 1,
   staff_id: 2,        // optional
@@ -502,7 +502,7 @@ const dates = await client.reservation.getAvailableDates({
 });
 // Returns: string[] (YYYY-MM-DD format)
 
-// 예약 가능 시간 슬롯 조회
+// Get available time slots
 const slots = await client.reservation.getAvailableSlots({
   service_id: 1,
   date: '2026-01-15',
@@ -511,23 +511,23 @@ const slots = await client.reservation.getAvailableSlots({
 // Returns: ReservationSlot[]
 ```
 
-#### Protected (로그인 필요)
+#### Protected (Login Required)
 
 ```typescript
-// 예약 생성
+// Create reservation
 const result = await client.reservation.create({
   service_id: 1,
   staff_id: 2, // optional
   reservation_date: '2026-01-15',
   start_time: '14:00',
-  customer_name: '홍길동',
-  customer_phone: '010-1234-5678', // optional
-  customer_email: 'hong@example.com', // optional
-  customer_memo: '요청사항', // optional
+  customer_name: 'John Doe',
+  customer_phone: '555-123-4567', // optional
+  customer_email: 'john@example.com', // optional
+  customer_memo: 'Special requests', // optional
 });
 // Returns: { reservation: Reservation, requires_payment: boolean, deposit: number }
 
-// 내 예약 목록
+// List my reservations
 const { data: reservations, meta } = await client.reservation.list({
   status: 'confirmed', // optional
   upcoming: true,      // optional
@@ -535,124 +535,124 @@ const { data: reservations, meta } = await client.reservation.list({
 });
 // Returns: ListResponse<Reservation>
 
-// 다가오는 예약
+// Upcoming reservations
 const upcoming = await client.reservation.upcoming(5);
 // Returns: Reservation[] (always an array)
 
-// 지난 예약
+// Past reservations
 const past = await client.reservation.past(10);
 // Returns: Reservation[] (always an array)
 
-// 예약 상세
+// Get reservation details
 const reservation = await client.reservation.get('RES-20260115-001');
 // Returns: Reservation
 
-// 예약 취소
-const cancelled = await client.reservation.cancel('RES-20260115-001', '일정 변경');
+// Cancel reservation
+const cancelled = await client.reservation.cancel('RES-20260115-001', 'Schedule change');
 // Returns: Reservation
 ```
 
-### Auth (인증)
+### Auth (Authentication)
 
 ```typescript
-// 로그인
+// Login
 const response = await client.auth.login({
   email: 'user@example.com',
   password: 'password',
 });
 // Returns: { member: Member, token: string }
-// 토큰은 자동으로 저장됨
+// Token is automatically stored
 
-// 회원가입
+// Register
 await client.auth.register({
-  name: '홍길동',
+  name: 'John Doe',
   email: 'user@example.com',
   password: 'password',
   password_confirmation: 'password',
-  phone: '010-1234-5678', // optional
+  phone: '555-123-4567', // optional
 });
 
-// 로그아웃
+// Logout
 await client.auth.logout();
 
-// 내 정보 조회
+// Get current user
 const me = await client.auth.me();
 // Returns: Member
 
-// 프로필 수정
+// Update profile
 await client.auth.updateProfile({
-  name: '새이름',
-  phone: '010-9999-8888',
+  name: 'New Name',
+  phone: '555-999-8888',
 });
 
-// 비밀번호 변경
+// Change password
 await client.auth.updateProfile({
-  current_password: '현재비밀번호',
-  password: '새비밀번호',
-  password_confirmation: '새비밀번호',
+  current_password: 'current_password',
+  password: 'new_password',
+  password_confirmation: 'new_password',
 });
 
-// 인증 여부 확인
+// Check authentication status
 client.isAuthenticated(); // true or false
 
-// 토큰 직접 설정 (localStorage에서 복원시)
+// Set token directly (e.g., from localStorage)
 client.setToken('saved-token');
 
-// 토큰 가져오기
+// Get token
 const token = client.getToken();
 ```
 
-#### 소셜 로그인
+#### Social Login
 
 ```typescript
-// 소셜 로그인 제공자 목록
+// Get social login providers
 const providers = await client.auth.getSocialProviders();
 // Returns: SocialProvider[]
 
-// 소셜 로그인 URL 가져오기
+// Get social auth URL
 const { url } = await client.auth.getSocialAuthUrl('google');
-// 해당 URL로 리다이렉트
+// Redirect to this URL
 
-// 콜백 처리 (리다이렉트 후)
+// Handle callback (after redirect)
 const response = await client.auth.socialCallback('google', code);
 // Returns: { member: Member, token: string }
 ```
 
-### Forms (폼)
+### Forms
 
 ```typescript
-// 폼 목록
+// List forms
 const { data: forms } = await client.forms.list();
 // Returns: ListResponse<Form>
 
-// 폼 상세
+// Get form details
 const form = await client.forms.get('contact');
-// Returns: Form (필드 정보 포함)
+// Returns: Form (includes field definitions)
 
-// 폼 제출 (로그인 불필요)
+// Submit form (no login required)
 await client.forms.submit('contact', {
-  name: '홍길동',
+  name: 'John Doe',
   email: 'user@example.com',
-  message: '문의 내용',
+  message: 'Inquiry content',
 });
 
-// 내 제출 목록 (로그인 필요)
+// My submissions (login required)
 const { data: submissions } = await client.forms.mySubmissions();
 // Returns: ListResponse<FormSubmission>
 ```
 
-### Media (미디어) - Protected
+### Media - Protected
 
 ```typescript
-// 파일 업로드
+// Upload file
 const media = await client.media.upload(file); // File or Blob
 // Returns: Media
 
-// 여러 파일 업로드
+// Upload multiple files
 const mediaList = await client.media.uploadMultiple([file1, file2]);
 // Returns: Media[]
 
-// 내 미디어 목록
+// List my media
 const { data: mediaList, meta } = await client.media.list({
   page: 1,
   per_page: 20,
@@ -660,94 +660,94 @@ const { data: mediaList, meta } = await client.media.list({
 });
 // Returns: ListResponse<Media>
 
-// 미디어 삭제
+// Delete media
 await client.media.delete(mediaId);
 ```
 
-### Entities (커스텀 엔티티) - 동적 데이터 구조
+### Entities (Custom Entities) - Dynamic Data Structures
 
-API/SDK에서 직접 엔티티 정의를 생성하고 데이터를 관리할 수 있습니다.
+Create entity definitions and manage data directly from the API/SDK.
 
 #### Entity Definition CRUD
 
 ```typescript
-// 엔티티 목록 조회
+// List entities
 const entities = await client.entities.list();
 // Returns: CustomEntity[] (always an array)
 
-// 엔티티 정의 생성
+// Create entity definition
 const entity = await client.entities.create({
-  name: '고객',
+  name: 'Customer',
   slug: 'customers',
-  description: '고객 관리',
+  description: 'Customer management',
   schema: {
     fields: [
-      { name: 'company', label: '회사명', type: 'text', required: true },
-      { name: 'email', label: '이메일', type: 'email', required: true },
-      { name: 'status', label: '상태', type: 'select', options: [
-        { value: 'active', label: '활성' },
-        { value: 'inactive', label: '비활성' }
+      { name: 'company', label: 'Company Name', type: 'text', required: true },
+      { name: 'email', label: 'Email', type: 'email', required: true },
+      { name: 'status', label: 'Status', type: 'select', options: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' }
       ]}
     ]
   },
   icon: 'users'
 });
 
-// 엔티티 정의 조회 (스키마 포함)
+// Get entity definition (includes schema)
 const entity = await client.entities.get('customers');
 // Returns: CustomEntity (includes schema)
 
-// 엔티티 정의 수정
+// Update entity definition
 await client.entities.update('customers', {
-  name: '고객사',
-  description: '고객사 관리'
+  name: 'Clients',
+  description: 'Client management'
 });
 
-// 엔티티 정의 삭제 (레코드가 있으면 force 필요)
-await client.entities.delete('customers');        // 레코드 없을 때
-await client.entities.delete('customers', true);  // 레코드 있어도 강제 삭제
+// Delete entity definition (requires force if records exist)
+await client.entities.delete('customers');        // When no records exist
+await client.entities.delete('customers', true);  // Force delete with records
 ```
 
 #### Record CRUD
 
 ```typescript
-// 레코드 목록 조회
+// List records
 const { data: customers, meta } = await client.entities.listRecords('customers', {
   page: 1,
   per_page: 20,
-  search: 'ACME',              // 검색
-  sort: 'company',             // 정렬 필드
-  dir: 'asc',                  // 정렬 방향
-  filters: JSON.stringify({ status: 'active' })  // JSON 필터
+  search: 'ACME',              // Search
+  sort: 'company',             // Sort field
+  dir: 'asc',                  // Sort direction
+  filters: JSON.stringify({ status: 'active' })  // JSON filter
 });
 // Returns: ListResponse<EntityRecord>
 
-// 단일 레코드 조회
+// Get single record
 const customer = await client.entities.getRecord('customers', 1);
 // Returns: EntityRecord
 console.log(customer.data.company); // 'ABC Corp'
 
-// 레코드 생성 (스키마 필드 직접 전달)
+// Create record (pass schema fields directly)
 const newCustomer = await client.entities.createRecord('customers', {
   company: 'ABC Corp',
   email: 'contact@abc.com',
   status: 'active',
 });
 
-// 레코드 수정 (부분 업데이트 - 기존 데이터와 병합)
+// Update record (partial update - merges with existing data)
 await client.entities.updateRecord('customers', 1, {
   status: 'inactive',
   email: 'new@abc.com'
 });
 
-// 레코드 삭제
+// Delete record
 await client.entities.deleteRecord('customers', 1);
 ```
 
-#### TypeScript 타입 지원
+#### TypeScript Type Support
 
 ```typescript
-// 타입이 지정된 엔티티 접근자
+// Typed entity accessor
 interface Customer {
   company: string;
   email: string;
@@ -756,14 +756,14 @@ interface Customer {
 
 const customers = client.entities.typed<Customer>('customer');
 
-// 타입이 추론됨
+// Type inference
 const list = await customers.list();
 list.data[0].data.company; // string
 
 const record = await customers.get(1);
 record.data.tier; // 'standard' | 'vip'
 
-// 생성/수정도 타입 체크
+// Type checking on create/update
 await customers.create({
   company: 'New Corp',
   email: 'new@corp.com',
@@ -774,11 +774,11 @@ await customers.create({
 ### Site Settings
 
 ```typescript
-// 테마 설정
+// Get theme settings
 const theme = await client.getTheme();
 // Returns: { name, colors, fonts }
 
-// 사이트 설정
+// Get site settings
 const settings = await client.getSettings();
 // Returns: Record<string, any>
 ```
@@ -998,7 +998,7 @@ const client = new Promptly({
   baseUrl: 'https://promptly.webbyon.com',
 });
 
-// 블로그 글 목록 (with pagination)
+// Blog post list (with pagination)
 function BlogList() {
   const [posts, setPosts] = useState([]);
   const [meta, setMeta] = useState(null);
@@ -1042,7 +1042,7 @@ function BlogList() {
   );
 }
 
-// 예약 폼
+// Reservation form
 function ReservationForm() {
   const [services, setServices] = useState([]);
   const [selectedService, setSelectedService] = useState(null);
@@ -1072,7 +1072,7 @@ function ReservationForm() {
   return (
     <div>
       <select onChange={e => setSelectedService(Number(e.target.value))}>
-        <option>서비스 선택</option>
+        <option>Select a service</option>
         {services.map(s => (
           <option key={s.id} value={s.id}>{s.name}</option>
         ))}

package/dist/index.d.mts

@@ -393,6 +393,7 @@ interface Product {
     options?: ProductOption[];
     variants?: ProductVariant[];
     weight?: number;
+    shipping_fee?: number;
     meta?: Record<string, any>;
     sort_order: number;
     discount_percent?: number;
@@ -419,22 +420,38 @@ interface CartItem {
     variant_id?: number;
     product?: Product;
     variant?: ProductVariant;
+    product_name?: string;
+    variant_name?: string;
+    thumbnail?: string;
     quantity: number;
     price: number;
+    subtotal?: number;
+    shipping_fee?: number;
+    in_stock?: boolean;
     options?: Record<string, string>;
-    created_at: string;
-    updated_at: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface CartShippingInfo {
+    is_free: boolean;
+    free_shipping_applied?: boolean;
+    remaining_for_free?: number | null;
+    message?: string | null;
+    notice?: string | null;
 }
 interface Cart {
     id: number;
     member_id?: number;
     session_id?: string;
     items: CartItem[];
+    subtotal: number;
+    shipping_fee: number;
     total: number;
     total_quantity: number;
     item_count: number;
-    created_at: string;
-    updated_at: string;
+    shipping_info?: CartShippingInfo;
+    created_at?: string;
+    updated_at?: string;
 }
 interface AddToCartData {
     product_id: number;
@@ -794,6 +811,7 @@ declare class HttpClient {
     private timeout;
     private token;
     private apiKey;
+    private cartSessionId;
     constructor(config: PromptlyConfig);
     /**
      * Set authentication token
@@ -815,6 +833,14 @@ declare class HttpClient {
      * Get current API key
      */
     getApiKey(): string | null;
+    /**
+     * Set cart session ID (for guest cart persistence)
+     */
+    setCartSessionId(sessionId: string | null): void;
+    /**
+     * Get cart session ID
+     */
+    getCartSessionId(): string | null;
     /**
      * Build full URL with query params
      */
@@ -1146,6 +1172,10 @@ declare class ShopResource {
      * @returns ListResponse with data array and pagination meta
      */
     categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<ListResponse<Product>>;
+    /**
+     * Save cart session ID from response (for guest cart persistence)
+     */
+    private saveCartSession;
     /**
      * Get current cart
      */
@@ -1595,4 +1625,4 @@ declare class Promptly {
     getApiKey(): string | null;
 }
 
-export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type AvailableDatesParams, type AvailableSlotsParams, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type Cart, type CartItem, type Comment, type CommentCreateData, type CommentDeleteData, type CommentListParams, type CommentListResponse, type CommentUpdateData, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CreateReservationData, type CreateReservationResult, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type Reservation, type ReservationListParams, type ReservationService, type ReservationSettings, type ReservationSlot, type ReservationStaff, type ReservationStaffSummary, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };
+export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type AvailableDatesParams, type AvailableSlotsParams, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type Cart, type CartItem, type CartShippingInfo, type Comment, type CommentCreateData, type CommentDeleteData, type CommentListParams, type CommentListResponse, type CommentUpdateData, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CreateReservationData, type CreateReservationResult, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type Reservation, type ReservationListParams, type ReservationService, type ReservationSettings, type ReservationSlot, type ReservationStaff, type ReservationStaffSummary, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };

package/dist/index.d.ts

@@ -393,6 +393,7 @@ interface Product {
     options?: ProductOption[];
     variants?: ProductVariant[];
     weight?: number;
+    shipping_fee?: number;
     meta?: Record<string, any>;
     sort_order: number;
     discount_percent?: number;
@@ -419,22 +420,38 @@ interface CartItem {
     variant_id?: number;
     product?: Product;
     variant?: ProductVariant;
+    product_name?: string;
+    variant_name?: string;
+    thumbnail?: string;
     quantity: number;
     price: number;
+    subtotal?: number;
+    shipping_fee?: number;
+    in_stock?: boolean;
     options?: Record<string, string>;
-    created_at: string;
-    updated_at: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface CartShippingInfo {
+    is_free: boolean;
+    free_shipping_applied?: boolean;
+    remaining_for_free?: number | null;
+    message?: string | null;
+    notice?: string | null;
 }
 interface Cart {
     id: number;
     member_id?: number;
     session_id?: string;
     items: CartItem[];
+    subtotal: number;
+    shipping_fee: number;
     total: number;
     total_quantity: number;
     item_count: number;
-    created_at: string;
-    updated_at: string;
+    shipping_info?: CartShippingInfo;
+    created_at?: string;
+    updated_at?: string;
 }
 interface AddToCartData {
     product_id: number;
@@ -794,6 +811,7 @@ declare class HttpClient {
     private timeout;
     private token;
     private apiKey;
+    private cartSessionId;
     constructor(config: PromptlyConfig);
     /**
      * Set authentication token
@@ -815,6 +833,14 @@ declare class HttpClient {
      * Get current API key
      */
     getApiKey(): string | null;
+    /**
+     * Set cart session ID (for guest cart persistence)
+     */
+    setCartSessionId(sessionId: string | null): void;
+    /**
+     * Get cart session ID
+     */
+    getCartSessionId(): string | null;
     /**
      * Build full URL with query params
      */
@@ -1146,6 +1172,10 @@ declare class ShopResource {
      * @returns ListResponse with data array and pagination meta
      */
     categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<ListResponse<Product>>;
+    /**
+     * Save cart session ID from response (for guest cart persistence)
+     */
+    private saveCartSession;
     /**
      * Get current cart
      */
@@ -1595,4 +1625,4 @@ declare class Promptly {
     getApiKey(): string | null;
 }
 
-export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type AvailableDatesParams, type AvailableSlotsParams, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type Cart, type CartItem, type Comment, type CommentCreateData, type CommentDeleteData, type CommentListParams, type CommentListResponse, type CommentUpdateData, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CreateReservationData, type CreateReservationResult, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type Reservation, type ReservationListParams, type ReservationService, type ReservationSettings, type ReservationSlot, type ReservationStaff, type ReservationStaffSummary, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };
+export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type AvailableDatesParams, type AvailableSlotsParams, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type Cart, type CartItem, type CartShippingInfo, type Comment, type CommentCreateData, type CommentDeleteData, type CommentListParams, type CommentListResponse, type CommentUpdateData, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CreateReservationData, type CreateReservationResult, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type Reservation, type ReservationListParams, type ReservationService, type ReservationSettings, type ReservationSlot, type ReservationStaff, type ReservationStaffSummary, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };

package/dist/index.js

@@ -71,10 +71,14 @@ var HttpClient = class {
   constructor(config) {
     this.token = null;
     this.apiKey = null;
+    this.cartSessionId = null;
     this.tenantId = config.tenantId;
     this.baseUrl = (config.baseUrl || "https://promptly.webbyon.com").replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.apiKey = config.apiKey || null;
+    if (typeof window !== "undefined" && window.localStorage) {
+      this.cartSessionId = localStorage.getItem(`promptly_cart_session_${this.tenantId}`);
+    }
   }
   /**
    * Set authentication token
@@ -106,6 +110,25 @@ var HttpClient = class {
   getApiKey() {
     return this.apiKey;
   }
+  /**
+   * Set cart session ID (for guest cart persistence)
+   */
+  setCartSessionId(sessionId) {
+    this.cartSessionId = sessionId;
+    if (typeof window !== "undefined" && window.localStorage) {
+      if (sessionId) {
+        localStorage.setItem(`promptly_cart_session_${this.tenantId}`, sessionId);
+      } else {
+        localStorage.removeItem(`promptly_cart_session_${this.tenantId}`);
+      }
+    }
+  }
+  /**
+   * Get cart session ID
+   */
+  getCartSessionId() {
+    return this.cartSessionId;
+  }
   /**
    * Build full URL with query params
    */
@@ -136,6 +159,9 @@ var HttpClient = class {
     if (this.token) {
       headers["Authorization"] = `Bearer ${this.token}`;
     }
+    if (this.cartSessionId) {
+      headers["X-Cart-Session"] = this.cartSessionId;
+    }
     return headers;
   }
   /**
@@ -712,35 +738,49 @@ var ShopResource = class {
   // ============================================
   // Cart
   // ============================================
+  /**
+   * Save cart session ID from response (for guest cart persistence)
+   */
+  saveCartSession(cart) {
+    if (cart.session_id) {
+      this.http.setCartSessionId(cart.session_id);
+    }
+    return cart;
+  }
   /**
    * Get current cart
    */
   async getCart() {
-    return this.http.get("/cart");
+    const cart = await this.http.get("/cart");
+    return this.saveCartSession(cart);
   }
   /**
    * Add item to cart
    */
   async addToCart(data) {
-    return this.http.post("/cart/items", data);
+    const cart = await this.http.post("/cart/items", data);
+    return this.saveCartSession(cart);
   }
   /**
    * Update cart item quantity
    */
   async updateCartItem(itemId, data) {
-    return this.http.put(`/cart/items/${itemId}`, data);
+    const cart = await this.http.put(`/cart/items/${itemId}`, data);
+    return this.saveCartSession(cart);
   }
   /**
    * Remove item from cart
    */
   async removeFromCart(itemId) {
-    return this.http.delete(`/cart/items/${itemId}`);
+    const cart = await this.http.delete(`/cart/items/${itemId}`);
+    return this.saveCartSession(cart);
   }
   /**
    * Clear entire cart
    */
   async clearCart() {
-    return this.http.delete("/cart");
+    await this.http.delete("/cart");
+    this.http.setCartSessionId(null);
   }
   // ============================================
   // Orders (Protected)

package/dist/index.mjs

@@ -43,10 +43,14 @@ var HttpClient = class {
   constructor(config) {
     this.token = null;
     this.apiKey = null;
+    this.cartSessionId = null;
     this.tenantId = config.tenantId;
     this.baseUrl = (config.baseUrl || "https://promptly.webbyon.com").replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.apiKey = config.apiKey || null;
+    if (typeof window !== "undefined" && window.localStorage) {
+      this.cartSessionId = localStorage.getItem(`promptly_cart_session_${this.tenantId}`);
+    }
   }
   /**
    * Set authentication token
@@ -78,6 +82,25 @@ var HttpClient = class {
   getApiKey() {
     return this.apiKey;
   }
+  /**
+   * Set cart session ID (for guest cart persistence)
+   */
+  setCartSessionId(sessionId) {
+    this.cartSessionId = sessionId;
+    if (typeof window !== "undefined" && window.localStorage) {
+      if (sessionId) {
+        localStorage.setItem(`promptly_cart_session_${this.tenantId}`, sessionId);
+      } else {
+        localStorage.removeItem(`promptly_cart_session_${this.tenantId}`);
+      }
+    }
+  }
+  /**
+   * Get cart session ID
+   */
+  getCartSessionId() {
+    return this.cartSessionId;
+  }
   /**
    * Build full URL with query params
    */
@@ -108,6 +131,9 @@ var HttpClient = class {
     if (this.token) {
       headers["Authorization"] = `Bearer ${this.token}`;
     }
+    if (this.cartSessionId) {
+      headers["X-Cart-Session"] = this.cartSessionId;
+    }
     return headers;
   }
   /**
@@ -684,35 +710,49 @@ var ShopResource = class {
   // ============================================
   // Cart
   // ============================================
+  /**
+   * Save cart session ID from response (for guest cart persistence)
+   */
+  saveCartSession(cart) {
+    if (cart.session_id) {
+      this.http.setCartSessionId(cart.session_id);
+    }
+    return cart;
+  }
   /**
    * Get current cart
    */
   async getCart() {
-    return this.http.get("/cart");
+    const cart = await this.http.get("/cart");
+    return this.saveCartSession(cart);
   }
   /**
    * Add item to cart
    */
   async addToCart(data) {
-    return this.http.post("/cart/items", data);
+    const cart = await this.http.post("/cart/items", data);
+    return this.saveCartSession(cart);
   }
   /**
    * Update cart item quantity
    */
   async updateCartItem(itemId, data) {
-    return this.http.put(`/cart/items/${itemId}`, data);
+    const cart = await this.http.put(`/cart/items/${itemId}`, data);
+    return this.saveCartSession(cart);
   }
   /**
    * Remove item from cart
    */
   async removeFromCart(itemId) {
-    return this.http.delete(`/cart/items/${itemId}`);
+    const cart = await this.http.delete(`/cart/items/${itemId}`);
+    return this.saveCartSession(cart);
   }
   /**
    * Clear entire cart
    */
   async clearCart() {
-    return this.http.delete("/cart");
+    await this.http.delete("/cart");
+    this.http.setCartSessionId(null);
   }
   // ============================================
   // Orders (Protected)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@back23/promptly-sdk",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Promptly AI CMS SDK for JavaScript/TypeScript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",